suaveplan/openspec/changes/enterprise-react-hotkeys/tasks.md

Tasks: enterprise-react-hotkeys

Change ID: enterprise-react-hotkeys Package: @suaveplan/react-hotkeys Target path: react/ui/react-hotkeys Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/react-translate

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree per proposal layout.
• Write package.json at 0.1.0 with "sideEffects": false, exports map.
• Dependencies: @suaveplan/error workspace:^, @suaveplan/react-translate workspace:^, zod catalog:forms, tslib catalog:build.
• Write tsconfig.json, vitest.config.ts, scripts.

---

2. Error codes and types

• Define HotkeyError extending SuaveplanError; codes: HOTKEY_CONFLICT, HOTKEY_INVALID_COMBO.
• Define all types: HotkeyCombo (single token + modifier flags), HotkeyBinding (combo string + handler + description), HotkeyOptions, HotkeyRegistryEntry, RegistryEntry.
• Write HotkeyBindingSchema Zod schema.

---

3. Combo parser (src/utils/combo-parser/)

• Implement parseCombo(raw: string): HotkeyCombo | HotkeyCombo[] — supports ctrl+shift+k, cmd+k, mod+k (platform-aware), g g (sequence as array), option+/.
• Implement matchesCombo(event: KeyboardEvent, combo: HotkeyCombo): boolean.
• Implement formatCombo(combo: HotkeyCombo): string — ⌘K on mac, Ctrl+K on other.
• Implement isModifierKey(event): boolean, isMac(): boolean.
• Write combo-parser.test.ts (≤500 lines): all modifier combos, sequence combos, platform-aware mod, edge cases (/, space). { timeout: 5000 }.
• Write combo-parser.md.

---

4. Store (src/store/hotkey-store/)

• Implement createHotkeyStore() — useSyncExternalStore-compatible external store holding Map<scope, HotkeyRegistryEntry[]>.
• register(scope, entry): () => void — adds entry, returns unsubscribe; throws HotkeyError(HOTKEY_CONFLICT) if same scope+combo already registered.
• getEntries(scope): HotkeyRegistryEntry[], subscribe(listener): () => void.
• Sequence buffer: tracks last N keydowns; matches against sequence combos.
• Write hotkey-store.test.ts, hotkey-store.md.

---

5. Hooks

useHotkey

• Registers single combo; installs keydown listener on document (SSR-safe via useEffect).
• prevent-in-input guard.
• Returns { isPressed: boolean }.
• Write test (combo fires, in-input blocked, SSR-safe), stories (playground toggle), md.

useHotkeys

• Bulk-registers HotkeyBinding[]; detects conflicts via store and emits HotkeyError(HOTKEY_CONFLICT) (non-throwing — logs via console.warn in dev, captures OTel event).
• Write test, md.

useHotkeyRegistry

• Subscribes to store via useSyncExternalStore; returns current entries for active scope.
• Write test (mount/unmount triggers re-render), md.

---

6. Components

HotkeyScope

• Provides scope name via context; routes events only when scope is active.
• Write test, stories (scoped-routing — two scopes, only active one fires), md.

HotkeyCheatSheet

• Renders grouped registry entries (scope → table of combo + description).
• Uses useTranslation for chrome strings ("Keyboard Shortcuts", "Description", "Shortcut").
• Re-renders live when entries change (via useHotkeyRegistry).
• Write test, stories (default, live-update on mount, playground), md.

---

7. E2E

• e2e/hotkeys.spec.ts — Playwright:
  • Press ctrl+k (or meta+k on mac), verify handler fires.
  • Press g g sequence, verify handler fires.
  • Focus <input>, press hotkey, verify handler does NOT fire.
  • Switch HotkeyScope, verify only active scope responds.

---

8. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/react-hotkeys — green.
• bunx turbo test:coverage --filter=@suaveplan/react-hotkeys — 100%.
• bun scripts/publish.ts --package @suaveplan/react-hotkeys.
• Archive change folder.