docs(keyboard): document the leader-sequence runtime in the dispatch header (RIG-2710) - #619
Merged
Merged
Conversation
This was referenced Aug 25, 2026
|
Compass engineering docs preview: https://compass-ux-rig-2710-dispatch.compass-eng-docs.pages.dev Deployed from |
rigel-mintaka
force-pushed
the
compass-ux/rig-2709-leader-runtime
branch
from
August 25, 2026 18:25
c956910 to
761ad0f
Compare
rigel-mintaka
force-pushed
the
compass-ux/rig-2710-dispatch-doc
branch
from
August 25, 2026 18:25
365ce79 to
5cce33c
Compare
rigel-mintaka
marked this pull request as ready for review
August 25, 2026 18:36
rigel-mintaka
force-pushed
the
compass-ux/rig-2709-leader-runtime
branch
from
August 26, 2026 03:32
761ad0f to
391ad7e
Compare
rigel-mintaka
force-pushed
the
compass-ux/rig-2710-dispatch-doc
branch
from
August 26, 2026 03:32
5cce33c to
480e4a9
Compare
mattwilkinsonn
force-pushed
the
compass-ux/rig-2709-leader-runtime
branch
from
August 26, 2026 04:26
391ad7e to
328d0d6
Compare
mattwilkinsonn
force-pushed
the
compass-ux/rig-2710-dispatch-doc
branch
from
August 26, 2026 04:26
480e4a9 to
2f3fa80
Compare
…(RIG-2708) Adds the four Go-to leader sequences from the frozen leader-chords design (`docs/designs/product/compass-leader-chords/design.md`, T2 / §A4-A5) to `DEFAULT_KEYMAP` and hardens the two shipped chord scanners so a sequence renders correctly everywhere and never reaches `aria-keyshortcuts`. - `DEFAULT_KEYMAP`: a new `// Go-to sequences (RIG-2484)` block with `G B → view.bridge`, `G L → view.backlog`, `G D → view.done`, `G S → view.settings`, each placed after any existing modifier row for the same command so the modifier chord stays the first match. - `shortcutForAria` now skips sequence rows (`chordSegments(entry.chord).length === 1`): a sequence-only command returns `undefined` (its writer omits the attribute) and a dual-bound command returns its modifier chord. A press-then-press sequence has no valid WAI-ARIA representation, so the skip is mandatory and makes the result row-order-independent. - `shortcutFor` now returns `formatChordForDisplay` of the first matching row and does NOT skip sequences, so `view.backlog`/`view.done` display `"G then L"`/`"G then D"` and keep their point-of-use chip and title; a dual-bound command still shows its modifier chord because that row is first. - The `?` overlay join formats via `formatChordForDisplay`, so a sequence row reads `"G then B"` instead of the misleading `"G B"`. Tests: `keymap.test.ts` moves `view.backlog` out of the `shortcutFor` miss group, adds a sequence-only-display case, a dual-bound modifier-wins case, and a `DEFAULT_KEYMAP` authoring-invariant block (every sequence is two modifier-less segments; no leader prefix is also a complete single chord); `ShortcutsOverlay.test.tsx` updates the bridge-filter row count 1→2 and asserts the formatted `"G then B"`; `Palette.test.tsx` asserts Backlog/Done carry no `aria-keyshortcuts` but a `"Backlog (G then L)"`/`"Done (G then D)"` title while Bridge keeps `aria-keyshortcuts="Control+B"`. Stacked on RIG-2707 (the sequence-grammar helpers). The dispatcher leader runtime that makes these chords fire is T3 (RIG-2709); until it lands the rows are advertised only through the discoverability net, which is why T2 and T3 ship in one stack. Ledger-impact: none. DL-248..DL-252 for this record landed with the design PR (#544). Refs RIG-2708 Co-authored-by: Matt Wilkinson <matt@rigel.build>
…-2709) Arm-and-complete "press G, then <key>" sequences inside the one `keydown` handler `installKeymap` already owns — no second listener, no module global. - Per-install `pending` leader state + a `disarm()` that clears the live timeout; leader set is `leaderPrefixes(DEFAULT_KEYMAP, platform)`, computed once at install (table-derived, never hard-coded). - Per-keydown order (§A3): normalize → editable-guard FIRST (modifier-less keys only) → completion (pure-modifier keys ignored, Escape disarms+consumes, else disarm then resolve the `"<leader> <chord>"` sequence rows; a dead sequence falls through and re-enters arming) → arming (leader prefix, no command modifier, not `event.repeat`; preventDefault+stopPropagation) → single-chord path (unchanged). - Tier resolution factored into a `resolve(matching, event)` closure so a completed sequence and a single chord run byte-identical (active group → scoped → global, scope gate intact). - `isEditableTarget` extended to `HTMLSelectElement` and `[role=combobox|listbox|menu]` so a bare leader key never steals native `<select>` typeahead or an ARIA widget's keys. - Uninstaller clears any live disarm timer (no leak against a torn-down closure on test teardown / HMR). - `LEADER_TIMEOUT_MS = 1000` (OQ1 ratified) exported for runtime + tests. Also folds the two deferred RIG-2707 review lows into `leaderPrefixes`'s unit coverage (first runtime caller): per-platform resolution of a `Mod` leader segment, and distinct-leader accumulation with same-leader dedup. Tests: dispatch.test.ts + keyboard-e2e.test.tsx (51 pass) cover arm/complete, timeout disarm, editable + `<select>` + ARIA-widget guards, dead-sequence fall-through, re-arm, Escape, lone-Shift-does-not-disarm, Mod+B-mid-sequence disarm-and-resolve, held-key no-arm, and uninstall-clears-timer; the two e2e cases drive `G S`/`G L` through real App wiring. keymap.test.ts 20 pass. Ledger-impact: none (decisions landed with the design PR #544; DL-248..252). RIG-2709
…header (RIG-2710) Extend the `dispatch.ts` module header with the leader runtime's contract now that it ships (RIG-2709): the arm → complete → disarm → fall-through model, the guard-first per-keydown ordering, the editable-target extension, and that a completed sequence and a single chord run the same three-tier resolution. Leaders are table-derived (`leaderPrefixes`), never hard-coded. Doc-only; no behavior change. `tsc --noEmit` + biome clean. Ledger-impact: none (DL-248..252 landed with the design PR #544). RIG-2710
rigel-mintaka
force-pushed
the
compass-ux/rig-2709-leader-runtime
branch
from
August 26, 2026 04:40
328d0d6 to
7477dd0
Compare
rigel-mintaka
force-pushed
the
compass-ux/rig-2710-dispatch-doc
branch
from
August 26, 2026 04:41
2f3fa80 to
5a538dd
Compare
mattwilkinsonn
approved these changes
Aug 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR is part of a stack containing 3 PRs:
mainExtend the
dispatch.tsmodule header with the leader runtime's contract nowthat it ships (RIG-2709): the arm → complete → disarm → fall-through model, the
guard-first per-keydown ordering, the editable-target extension, and that a
completed sequence and a single chord run the same three-tier resolution.
Leaders are table-derived (
leaderPrefixes), never hard-coded.Doc-only; no behavior change.
tsc --noEmit+ biome clean.Ledger-impact: none (DL-248..252 landed with the design PR #544).
RIG-2710