Skip to content
Pauta4.5.0

Command Palette

One palette per window lists every registered command, so a command that exists is a command people can find. The pure parts (FuzzyMatch, MatchText, the key helper, PickerKeys in Editora and PaletteKeys in the copies, and the caret-key helper, TextInputKeymap in Editora and TextInputKeys in the copies) are shared with Termina and Mirada. Torrenta shares MatchText and ranks with its own CommandMatcher.

Rules on this page 8
IDLevelRule
Rules
PAL-01MUST
Every app has one Command Palette per window, opened by the palette.show command. Its chords, M-x in the Emacs keymap and Ctrl+Shift+P (Cmd+Shift+P on macOS) in the others (Ctrl+Shift+A allowed in the IntelliJ keymap), are KBD-05.
PAL-02MUST
The palette lists every registered command, with its title from command.<id> and its description from command.<id>.desc.
Behavior
PAL-04SHOULD
The palette opens from the palette.show command, by its chord or a menu item, with an empty query that lists every command.
PAL-05SHOULD
Typing filters the list, and the first enabled match is selected.
PAL-06SHOULD
↑ ↓, C-n C-p and Page Up/Down move the selection; Enter, or a click on an enabled row, runs the command. The palette closes first, then the command runs.
PAL-07SHOULD
Esc, C-g or a click on the scrim cancels, and focus returns to where it was.
PAL-08SHOULD
C-h, or the first of C-h, F1, Shift+F1 the active keymap leaves free, opens the selected command’s page on the website, for the running version.
PAL-09SHOULD
A live keymap switch re-renders the key chips, the opener chip and the key legend.
  • PAL-01 MUST Every app has one Command Palette per window, opened by the palette.show command. Its chords, M-x in the Emacs keymap and Ctrl+Shift+P (Cmd+Shift+P on macOS) in the others (Ctrl+Shift+A allowed in the IntelliJ keymap), are KBD-05.
  • PAL-02 MUST The palette lists every registered command, with its title from command.<id> and its description from command.<id>.desc.
    • Check (code): the palette’s rows come from the whole registry, filtered only by the query; a command that cannot run stays listed, grayed. A catalog parity test fails on a command title with no .desc.
    • Reference: Editora CommandPalette.filter (registry.all()), MessagesTest; the Spec table below.

The palette is an in-scene overlay in the window’s root StackPane, over a faint scrim, never a javafx.stage.Popup: KBD-07.

  1. 1Opener chip. The chord that opened the palette, read from the active keymap. No chip when the user has unbound it, never a wrong one.
  2. 2Query field. The first row is the input; there is no title. Prompt "Run command…". Emacs caret keys work inside it.
  3. 3Match highlight. The characters the fuzzy matcher scored, bold in the accent color. The highlight and the ranking come from the same call, so they never disagree.
  4. 4Selected row. Tinted background plus a 2 px accent bar on its inside edge. The bar is what makes the selection readable in a long list.
  5. 5Key chip. The command's binding in the active keymap, in the keyboard color (brace periwinkle). Absent when unbound.
  6. 6Unavailable command. Listed, grayed, never selected and inert to clicks. Its tooltip says why and what to do ("Unavailable — no merge, rebase, cherry-pick or revert is in progress.").
  7. 7Description. The selected command's command.<id>.desc, one line with an ellipsis, always one line tall so the card never jumps.
  8. 8Key legend. The palette's own keys, rendered from the active keymap.
PropertyValueReference
KindIn-scene overlay in the window’s root StackPane, over a faint scrim. Not a javafx.stage.Popup: on Windows a popup does not reliably take keyboard focus.OverlayHost
Width620 pxcontent.setPrefWidth(620)
Rows36 px high, 8 visible before the list scrollsROW_HEIGHT, VISIBLE_ROWS
Card-color-bg-overlay, 1 px -color-border-default, radius 12, padding 6, one wide drop shadow.command-palette in app.css
Row text12.5 px; padding 7 × 16.command-palette .list-cell
Scrimrgba(0,0,0,0.18); a click on it closes the palette.overlay-backdrop
ContentEvery registered command: title from command.<id>, description from command.<id>.descCommandRegistry, MessagesTest
RankingFuzzy score over title, id and description; a query that names a title outranks a fuzzy hitFuzzyMatch, titlePhraseScore
  • PAL-04 SHOULD The palette opens from the palette.show command, by its chord or a menu item, with an empty query that lists every command.
    • Check (code): show clears the field and filters on the empty query before the card appears.
    • Reference: Editora CommandPalette.show.
  • PAL-05 SHOULD Typing filters the list, and the first enabled match is selected.
  • PAL-06 SHOULD ↑ ↓, C-n C-p and Page Up/Down move the selection; Enter, or a click on an enabled row, runs the command. The palette closes first, then the command runs.
  • PAL-07 SHOULD Esc, C-g or a click on the scrim cancels, and focus returns to where it was.
    • Check (code): the cancel key and a press on the backdrop both hide the overlay, and hiding focuses the node that had focus before it opened.
    • Reference: Editora PickerKeys (CANCEL), OverlayHost (previousFocus).
  • PAL-08 SHOULD C-h, or the first of C-h, F1, Shift+F1 the active keymap leaves free, opens the selected command’s page on the website, for the running version.
  • PAL-09 SHOULD A live keymap switch re-renders the key chips, the opener chip and the key legend.
KeyEnglish
palette.promptRun command…
palette.disabled.<reason>Unavailable — what is missing. What to do first.
Editora's command palette filtered to Git commands
Editora.
Torrenta's command palette listing torrent actions with shortcuts
Torrenta.
Termina's command palette over a terminal listing tab commands
Termina.

Pauta 4.5.0 · · Changelog · This page in the latest edition