[Bug] Kbd does not normalise the key aliases useHotkeys accepts
- Dominant language
- TypeScript
- Stars
- 13.1k
- Forks
- 1.1k
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 687
Description
### Description
`useHotkeys` and `Kbd` take the same `'+'`-separated combo string, but each keeps its own key vocabulary. `useHotkeys` resolves aliases through `KEY_ALIASES` (`esc`, `space`, `up`, `down`, `left`, `right`, `return`, `plus`) and accepts `mod`/`ctrl`/`meta`/`alt`/`shift` as modifiers. `Kbd` resolves through `KEY_DISPLAY` and `KEY_LABEL`, a different set, and falls back to `key.toUpperCase()` for anything it does not recognise. That fallback is written for single letters (`k` → `K`), so a multi-character alias comes back as an uppercased word.
Rendered on macOS:
| combo | glyphs | aria-label |
|---|---|---|
| `mod+k` | ⌘ K | Command + K |
| `shift+enter` | ⇧ ↵ | Shift + Enter |
| `meta+k` | META K | META + K |
| `esc` | ESC | ESC |
| `return` | RETURN | RETURN |
| `space` | SPACE | SPACE |
The rendered key is never the wrong key, so this is a missing normalisation rather than a wrong hint. The cost lands hardest on the accessibility side: `KEY_LABEL` exists because glyphs announce meaninglessly, and "META" or "ESC" is not much better than a glyph.
The four cases are not one problem.
`esc` and `return` look like a plain gap. `KEY_DISPLAY` already holds `escape` → `Esc` and `enter` → `↵`, and `useHotkeys` already collapses both aliases in `KEY_ALIASES`. `Kbd` does not run the same step.
`meta` and `space` need a decision I don't think a contributor should make. `meta` is ⊞ on Windows, not ⌘, so whether it branches on platform the way `mod` does is an API question. `␣` vs `Space` is a design choice.
### Reproduction
```tsx
useHotkeys([{keys: 'return', onPress: doThing}]); // fires on Enter
// renders "RETURN"
```
Same for `meta`, `esc`, and `space`.
### Astryx Version
`@astryxdesign/core@0.5.0`, and current `main`.
### Environment
Any browser and OS. Not platform dependent.
---
*Diagnosis and draft prepared with Claude Code; reviewed and verified by the contributor before filing.*
Contributor guide
Research direction
Start with Kbd's KEY_DISPLAY and KEY_LABEL handling, then compare it with useHotkeys' KEY_ALIASES; these are the relevant entry points named in the issue. Resolve the platform behavior for meta and the presentation choice for space before changing normalization. Done means the agreed aliases render intended glyphs and accessible labels without regressing single-letter combinations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- accessibility, frontend
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100