PSA/docs/features/keyboard-shortcuts.md

# Keyboard Shortcuts

Alga PSA ships a system-wide keyboard shortcut engine active on all MSP pages
(`/msp`). Shortcuts are grouped by scope: **global** shortcuts fire anywhere;
**page** shortcuts fire on the current page; **panel/dialog** shortcuts fire
when a drawer or dialog is open and take priority over page shortcuts.

## Opening the Command Palette

Press **`Mod+K`** (⌘K on macOS, Ctrl+K on Windows/Linux) to open the command
palette. The palette merges navigation destinations, runnable shortcut actions,
and full record search into one keyboard-driven overlay. From here you can:

- **Navigate** to any page by typing its name (e.g. `tickets`, `schedule`).
- **Search records** across clients, tickets, contacts, projects, assets, and
  more.
- **Run an action** by prefixing `>` (e.g. `>create ticket`).
- **Open a record by ID** with `#` (e.g. `#1042`).
- **Narrow by type** using field scopes: `ticket:`, `client:`, `project:`,
  `asset:`, `contact:`, `user:` / `@name`, `nav:` / `/path`.
- **Magic keywords**: `$mine`, `$recent`, `$open` (abbreviate to first
  syllable: `$m`, `$rec`, `$op`).
- **Operators**: double-quoted phrases (`status:"in progress"`), `-` / `NOT`
  exclusion, `*` and `?` wildcards, fuzzy `term~`.

## Discovering Shortcuts

Press **`?`** on any MSP page (when not focused in a text field) to open the
**shortcut help dialog**. It lists every shortcut active in the current
context, grouped by scope, resolved for the user's operating system, and with
personalized bindings flagged.

Shortcuts are also surfaced as **visible `kbd` hints** rendered next to
instrumented controls (search field, primary action buttons, relevant menu
items). These hints use OS-native glyph notation (⌘/⌥/⇧/⌃ on macOS;
Ctrl/Alt/Shift on Windows/Linux). The `aria-keyshortcuts` attribute is set on
instrumented controls for screen readers.

## Default Shortcut Reference

### Global (fire anywhere in `/msp`)

| Action | macOS | Windows / Linux |
|--------|-------|-----------------|
| Open command palette | ⌘K | Ctrl+K |
| Open shortcut help dialog | ? | ? |
| Quick-create dialog (multi-type) | N | N |

### Navigation sequences

Press the first key, then the second key within ≈1 second. Sequences are
suppressed while any input, textarea, rich-text editor, or combobox is
focused, and reset on route change.

| Sequence | Destination |
|----------|-------------|
| G → T | Tickets |
| G → C | Clients |
| G → P | Projects |
| G → A | Assets |
| G → S | Schedule |
| G → H | Dashboard (Home) |

### Page-level (fire when the matching page is active)

| Action | Key |
|--------|-----|
| Open current page's create dialog | C |
| Save current page | ⌘S / Ctrl+S |
| Navigate to previous record | `[` |
| Navigate to next record | `]` |

`C` and `N` are suppressed while any editable target is focused and while a
dialog or drawer owns scope.

### Panel / dialog scope

When a drawer or modal dialog is open it captures `Escape` (close/cancel) and
`[`/`]` (previous/next record within the panel). Global and page shortcuts do
not fire while a panel-scope owner is active.

## Customizing Shortcuts

Navigate to **Profile → Keyboard Shortcuts** to manage personal bindings.

| Control | Effect |
|---------|--------|
| Click the binding chip for any action | Capture a new key combination |
| Toggle **Enabled** switch | Disable the shortcut without losing the binding |
| Reset icon on a row | Restore that action's default binding |
| **Reset all** button (confirmation required) | Clear all personal overrides |

Conflict detection runs before commit: if the captured key is already claimed
by another action, the UI prompts for confirmation; the previous owner is
unbound and the new binding takes effect.

Custom bindings are stored per user account and sync across devices. A binding
authored on macOS (e.g. `mod+J`) resolves automatically to Ctrl+J on
Windows/Linux; non-portable combos surface a non-blocking advisory on sign-in
from the other OS.

## Shortcut Profiles

Three preset profiles are available from the Keyboard Shortcuts panel:

| Profile | Description |
|---------|-------------|
| **Default** | Standard bindings optimized for MSP workflows |
| **Vim** | `j`/`k` list navigation and Vim-style action keys |
| **Emacs** | Emacs-inspired modifier-based bindings |

Selecting a profile applies its preset as the binding baseline. Per-action
overrides stack on top of any profile. Per-action reset returns to the active
profile's baseline (not the factory default).

## Scope and Priority Rules

The dispatcher picks the highest-priority registered action that matches the
event's active scope set:

1. **Dialog / panel** — highest priority; owns `Escape` and record-nav keys.
2. **Editor** — `editor`-scoped shortcuts (invoice designer, workflow designer,
   rich-text) override page shortcuts.
3. **Page** — page-scoped shortcuts fire when the registered page is active.
4. **Global / shell** — lowest priority; fire regardless of current page.

When the same key maps to two actions in the same scope at the same priority,
the conflict is reported in the settings panel and help dialog (it does not
silently pick one).

Single-letter shortcuts (`C`, `N`, `j`, `k`) are always suppressed inside
`<input>`, `<textarea>`, `<select>`, `contenteditable`, and ARIA text/combobox
roots unless the action explicitly sets `allowInEditable`.

## Architecture Overview

The engine lives in `packages/ui/src/keyboard-shortcuts/` and has no imports
of `@alga-psa/user-composition` or any feature package — dependency direction
is enforced by a CI boundary guard (`scripts/guard-keyboard-shortcuts-*.mjs`
and `eslint-plugin-custom-rules`).

| Path | Role |
|------|------|
| `packages/ui/src/keyboard-shortcuts/provider.tsx` | Single delegated capture-phase `keydown` listener; dispatch loop |
| `packages/ui/src/keyboard-shortcuts/catalog.ts` | Single source of truth for action metadata (ids, default bindings, scope, priority) |
| `packages/ui/src/keyboard-shortcuts/parser.ts` | `parseBinding` / `parseSequence` — dual `event.code` + `event.key` matching, `mod` resolution |
| `packages/ui/src/keyboard-shortcuts/preferences.ts` | `ShortcutStorage` adapter interface + preference resolution (`user override → profile delta → platform default`) |
| `packages/ui/src/keyboard-shortcuts/ShortcutHintHud.tsx` | `<Kbd>` / `ShortcutHint` component rendering OS-native glyphs |
| `packages/ui/src/keyboard-shortcuts/command-palette-query.ts` | Command palette query parser (TeamCity-style field scopes + operators) |
| `server/src/components/settings/general/KeyboardShortcutsPanel.tsx` | Profile → Keyboard Shortcuts settings UI |

The provider is mounted in `MspLayoutClient.tsx` (wraps `DefaultLayout` and
`AlgaDeskMspShell`). It does not mount on auth or client-portal pages.

Persistence uses the existing `user_preferences` table via `useUserPreference`
(key `keyboard_shortcuts_v1`); no new tables or API endpoints. The stored blob
is a versioned delta (`{ version, bindings, disabled, profile }`), using
platform-neutral syntax (`mod+k`), with a `v1 → v2` migration that adds the
`profile` field defaulting to `'default'`.

## Coverage and Non-Goals (v1)

The shortcut engine covers all routes under `/msp`. The following are
deliberately out of scope for the initial release:

- Auth screens and the client portal.
- Tenant-level shortcut defaults or admin lock-down.
- Export / import of personal override sets.
- Browser-owned combos (`mod+R`, `mod+F`, `mod+P`, `mod+W`, `mod+T`, `mod+N`)
  are not overridden.
- Component-local widget key handling (DatePicker, SearchableSelect, TagInput,
  Radix internals) retains its local handlers unchanged.