Keyboard shortcuts & navigation — design

Approved scope (user): full suite — row hotkeys, list navigation, global chords, help
overlay, Ctrl/Cmd+K command palette. ClickUp-style row targeting ("right-click or hover a
doc, press e = edit"). No new npm dependencies.

Architecture

One central registry (web/src/lib/hotkeys.ts) + a single window keydown listener
mounted inside AppShell (so the standalone routes — office editor, TipTap editor, preview
tab — never see it). Components register bindings with a useHotkeys(bindings) hook;
each binding carries scope, key, i18n label key, an enabled predicate and a run
callback. The help overlay and the palette read the same registry, so documentation and
searchable actions can never drift from the real bindings.

Scope priority (first match wins): menu (context menu open) → row (hover > selection)
→ list → global. Chords (g + letter) are handled by the listener with a 1.5s
pending-chord window.

Guards: bindings are suppressed when the event target is an input/textarea/select/
contentEditable, when any Carbon modal is open (.cds--modal.is-visible), or when a
Carbon menu/combobox owns focus — except bindings explicitly flagged inDialog (the
palette's own navigation, Escape).

Keymap

Global: g d Documents · g i Inbox · g w Workflows · g c Correspondence ·
g a Ask the Archive · g r Reports · g f Forensic verify · g t Trash ·
g m Administration (admin only) · / focus search · ? help overlay ·
Ctrl/Cmd+K palette · u upload (documents page).

List (documents page, grid + table): j/↓ next · k/↑ previous · Enter open ·
Esc clear selection. Linear order in both views (v1).

Row (target = context-menu row > hovered row > selected row):
doc — Enter/o open, v preview, d download, e edit details, m move,
c duplicate, p pin/unpin, x/Del delete (confirm);
folder — Enter/o open, e edit folder, r rename, m move, x/Del delete.
Context-menu items render key hints via Carbon MenuItem shortcut prop.

Palette (Ctrl/Cmd+K)

Hand-rolled modal (Carbon styling). One input; sections: Actions (registry bindings
currently enabled, incl. row actions when a row is targeted), Navigate (chord
destinations), Documents (≥2 chars → debounced useDocSearch, Enter jumps to
detail). ↑/↓ + Enter, Esc closes.

Help overlay (?)

Modal listing every registered binding grouped by section, generated from the registry.
en + id.

Non-goals (v1)

User-remappable keys; 2-D grid arrow navigation; shortcuts on the standalone
editor/preview routes; shortcuts inside modals.

Testing

Playwright keyboard e2e on the x056 demo: chord navigation, / focus, list j/k + Enter,
hover + e opens Edit details, palette doc-jump, help overlay lists bindings.