fix(core): normalize Kbd esc and return aliases

[harjothkhara]

Summary

Kbd now normalizes the unambiguous esc and return aliases already accepted by useHotkeys, so their visual glyphs and accessible names match escape and enter. This is a partial fix for #5403; meta and space remain open design/API decisions.

Case

useHotkeys already maps esc and return to the corresponding KeyboardEvent.key values (useHotkeys.ts:64-74,132-133), but Kbd previously sent every token directly through its display and label fallbacks (Kbd.tsx:89-120). As a result, esc rendered and announced as ESC, while return rendered and announced as RETURN.

Fix

Kbd now normalizes the two aliases before display and accessible-label resolution (Kbd.tsx:79-82,173-190). The touched lookup tables use Map, keeping arbitrary key names on the uppercase fallback instead of accidentally resolving inherited object properties (Kbd.tsx:64-120), and occurrence-qualified React keys preserve every badge when canonical and alias spellings repeat (Kbd.tsx:173-205). Component docs and the CLI/Storybook showcases now demonstrate the aliases (Kbd.doc.mjs:12-16, KbdModifierCombos.tsx:23-31, Kbd.stories.tsx:74-87).

Scope

This intentionally handles only esc and return. It does not choose platform behavior for meta or a glyph for space; those remain tracked in #5403. Existing empty-combo-segment behavior and the separate useHotkeys lookup implementation are parser-hardening follow-ups, not part of this rendering fix.

Testing

• pnpm exec vitest run packages/core/src/Kbd/Kbd.test.tsx packages/core/src/hooks/useHotkeys.test.ts — 2 files, 36 tests passed.
• pnpm -F @astryxdesign/core typecheck — passed.
• pnpm -F @astryxdesign/core typecheck:docs — passed.
• pnpm -F @astryxdesign/core build — 581 files compiled and verified.
• pnpm check:repo — all repository integrity checks passed.
• ESLint passed for the changed TypeScript and TSX files.
• Negative control on origin/main: the alias regression cases failed because esc rendered/announced as ESC and return as RETURN. With the fix, standalone, uppercase, combo, semantic-equivalence, repeated-key, and accessible-name cases pass.
• Hardening red/green: before the source hardening, repeated/case-equivalent tokens emitted duplicate React-key warnings and constructor/__proto__ failed through prototype-backed lookup; the committed regression tests now pass.

Refs #5403

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview	Aug 28, 2026 4:56pm

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

Modified Components

Kbd _{(@astryxdesign/core)} · View in Storybook

Metric	Before	After	Delta
Bundle Size (ESM)	N/A	N/A	N/A
Lines of Code	N/A	140	-
Complexity	N/A	Medium (13)	-

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.8KB	1.2KB

Accessibility Audit

Status: No accessibility violations detected.

Visual Regression

110 added · 0 removed. View the report

To accept these exact frames: /accept-visual 33191992132/1 <reason>

Added — After

Added — After

Added — After

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

[rubyycheung]

Looks good from design. Normalizing and makes their visual output and accessible names consistent with the canonical and keys, without changing the established Kbd presentation.

[rubyycheung]

Clarification: normalizing esc and return makes their visual output and accessible names consistent with the canonical escape and enter keys.