wehub-resource-sync
67 lines
2.8 KiB
Markdown
67 lines
2.8 KiB
Markdown
# Keyboard Layout Shortcut Dispatch
|
|
|
|
## Problem
|
|
|
|
Keyboard shortcuts must follow the user's active keyboard layout. A shortcut like `Cmd+W`
|
|
means "Command plus the key that produces `w`", not "Command plus the physical key labeled
|
|
W on a US keyboard." Physical-position matching breaks Dvorak, Colemak, AZERTY, JIS, and
|
|
other non-US layouts, and it also makes user keybinding overrides impossible to reason about.
|
|
|
|
## Decision
|
|
|
|
Orca app shortcuts dispatch by logical key by default.
|
|
|
|
The shared keybinding registry in `src/shared/keybindings.ts` is the source of truth for
|
|
app commands, configurable commands, shortcut recording, labels, conflict detection, browser
|
|
guest forwarding, and terminal pane commands. Code handling a user-facing app command must
|
|
call `keybindingMatchesAction`, `keybindingMatchesInput`, or a policy function built on those
|
|
helpers.
|
|
|
|
Physical `KeyboardEvent.code` may only decide a shortcut when the key is layout-invariant or
|
|
the platform cannot provide a real logical key.
|
|
|
|
Allowed physical-code uses:
|
|
|
|
- Modifier key release tracking, such as left/right Control release for held `Ctrl+Tab`.
|
|
- Layout-invariant keys, such as arrows, Tab, Enter, Escape, Backspace, Delete, Insert,
|
|
PageUp, PageDown, and explicit numpad bindings.
|
|
- Dead, unidentified, or missing logical keys where `KeyboardEvent.key` cannot describe the
|
|
produced key.
|
|
- Terminal byte encoding where the intent is a physical terminal escape sequence rather than
|
|
an Orca command.
|
|
|
|
Disallowed physical-code uses:
|
|
|
|
- Letter shortcuts for app actions.
|
|
- Punctuation shortcuts for app actions when `KeyboardEvent.key` reports the produced
|
|
punctuation.
|
|
- Clipboard shortcuts that are exposed as app or terminal UI commands.
|
|
- Hardcoded undo/redo/new/close/copy/paste handling outside the shared registry.
|
|
|
|
## Terminal Boundary
|
|
|
|
Terminal handling has two different jobs:
|
|
|
|
1. Orca commands that act on terminal UI, such as copy selection, paste, search, clear,
|
|
pane focus, split, and close. These are app shortcuts and must be layout-aware.
|
|
2. Bytes sent to the shell, such as readline escapes and Option-as-Alt sequences. These may
|
|
use physical key positions when terminal compatibility requires it.
|
|
|
|
This boundary is intentional. It lets non-US layouts use Orca commands naturally while
|
|
preserving shell behavior where users expect physical terminal-control sequences.
|
|
|
|
## Regression Requirements
|
|
|
|
Shortcut tests must cover both directions of a non-QWERTY swap:
|
|
|
|
- The key that produces the configured logical character must match, even if its physical code
|
|
differs.
|
|
- The physical US key must not match when it produces a different logical character.
|
|
|
|
Tests must also cover intentional exceptions:
|
|
|
|
- Dead or missing key fallback.
|
|
- Shifted punctuation aliases.
|
|
- Numpad-specific bindings.
|
|
- Terminal byte-encoding paths that intentionally use physical codes.
|