Grilling: how do view-local, non-command keys get expressed in the migration?

[adehad]

Part of map #1
Blocks #7

Question

The commands! macro covers the 57 palette commands, but the migration also has to absorb view-local keys that are not commands: j/k and arrow navigation, Esc/cancel per overlay, in-dialog letter keys (e.g. s = squash inside the rebase dialog), tab-cycling between panels, and column/panel resize keys.

Do these get their own per-view actions! namespaces alongside the macro (e.g. graph::SelectNext, rebase_dialog::SetSquash, menu::Cancel), or does commands! extend to cover them? Which of them should be user-rebindable at all versus hardcoded? And does every overlay get a menu::Cancel-style action, or one shared Cancel resolved by context depth?

[adehad]

Resolution

Inventory that drove this (36 handlers across 33 files)

• 15 distinct single letters, and four of them mean different things in different views: d (DiffViewer toggle display mode / Blame+FileHistory back-to-diff / rebase drop), s (stage hunk / stage file / squash), p (partial-staging toggle / pick), b+h (cross-navigation between blame and history, also global toggles).
• Only 1 of 14 overlays sets a key_context (CommandPalette). CommitPanel sets one and has no handler at all.
• stop_propagation is inconsistent: some handlers stop on every arm, DiffViewer and Sidebar stop on some arms and let others bubble into key_handler.rs, and GraphView / DetailPanel / InteractiveRebase / every dialog never stop. Hence key_handler.rs re-handles Esc per visible overlay and re-handles d/b/y/h, and its j/k fallback is gated on a hand-rolled !panel_has_focus.
• Two views hand-roll type-to-filter: DetailPanel's file search (in the same handler that owns j/k/v/[/]) and InteractiveRebase's reword mode (which swallows the very p/r/s/f/d letters that are commands in normal mode).

1. One registry, grouped by view

View-local keys live in the same commands! macro as the palette commands, grouped into per-view blocks so the context and action namespace are declared once and entries carry only what varies:

commands! {
    view Workspace in rgitui {
        CommandPalette  "secondary-shift-p";
        StageAll        "secondary-s"        if has_changes;
        Commit          "secondary-enter"    if has_staged;
    }

    view GraphView in graph {
        CopySha         "y"                  if selection;
        SquashSelected  "secondary-shift-s"  if multi_selection;
        SelectNext      "j"                  hidden;   // not in the palette
    }

    view InteractiveRebase in rebase {
        Pick "p";  Reword "r";  Squash "s";  Fixup "f";  Drop "d";
    }
}

One source of truth for actions, defaults, contexts, availability, palette membership, conflict checking, and the shortcuts view.

2. JSON format: Zed-style sections, namespace::Action names

Surveyed Zed (local checkout at the pinned rev), VS Code, lazygit, gitui, and Helix. Adopt Zed's array of {context, bindings} sections:

[
  { "context": "GraphView",
    "bindings": {
      "y": "graph::CopySha",
      "secondary-shift-s": "graph::SquashSelected",
      "d": null                      // unbind
  }}
]

Why not the alternatives:

• No translation layer. gpui's KeyBinding::load + KeyBindingContextPredicate::parse consume these strings directly (~40 lines of deserialize + a loop). Any other shape means inventing a view→predicate mapping and losing &&, !, and > (descendant) — which rgitui needs today: any_overlay_active exists purely to emulate context depth.
• Nested-by-view (lazygit) breaks on real focus trees. lazygit gets away with it because a TUI has one focused view; rgitui has sidebar > changes list > diff viewer plus modal overlays. Section-plus-predicate resolves those by specificity (deepest wins). lazygit's action→key direction also makes "unbind this keystroke here" inexpressible.
• Not VS Code's flat when array: per-entry predicates triple the file size, and gpui has no -command concept — null/NoAction already covers removal.
• Dot notation is not viable as the primary name. gpui's derive macro forces namespace::PascalCase and panics if the name contains ::; a dotted deprecated_aliases entry would work mechanically but the UI would keep showing graph::CopySha while the file said graph.copySha. Emit graph::CopySha; the view … in <namespace> block supplies the namespace.

Per-view grouping survives in the JSON: the macro generates the default keymap with one comment-headed section per view block, in macro order. Grouping is visible in the file the user reads while the loader stays gpui's. (Every surveyed format that nests uses nesting for exactly one axis — scope or chord prefix, never both.)

3. Human-readable surface

The macro emits docs/KEYBINDINGS.md (view, keystroke, action name, description), written by a test that fails with a diff if the file is stale, so it can never drift. Readable on GitHub, reviewable in PRs, and the copy-paste source for overrides.

Plus a generated JSON Schema for keymap.json: the macro already knows every action name and doc comment, so $schema gives editors autocompletion of action names and inline docs, catching typos at edit time rather than as a load-time toast.

4. Text-entry conflict: refactor, don't work around

DetailPanel's file search and InteractiveRebase's reword mode both migrate to the shared TextInput widget, which already swallows printable characters correctly and is what Sidebar/CommandPalette/GraphView search use. This deletes two hand-rolled editors and removes the problem class, rather than maintaining key_context("DetailPanel searching") flags by hand at every mode transition.

5. Cancel/Confirm: shared actions, resolved by context depth

One menu::Cancel and one menu::Confirm, bound once. Every overlay gains a key_context (14 of them currently have none) so gpui's deepest-context-wins dispatch picks the right handler — this is what dissolves the 10-branch Esc cascade and the any_overlay_active gate. Blame and FileHistory keep a distinct SwitchToDiff action, since their Esc is a navigation, not a dismissal. CommitPanel either gets a handler or loses its context.

6. Duplicates collapse; no global fallbacks

One action per behaviour, bound only in the context where it belongs. The global d/b/h/y duplicates and the !panel_has_focus hack are deleted — focus plus context depth replaces them.

Accepted behaviour change: these keys stop firing when focus is somewhere unrelated. Arguably a fix (today they fire from anywhere, including over unrelated panels), but it is user-visible and belongs in the PR description. Consequence for conflict detection: with everything context-scoped, the checker should see zero overlaps in the defaults — a test asserts exactly that.