Field queries

An editor’s commands searched with catsearchSearcher() and no configuration. Plain words work as they always did; the fields and relations below come built in. Click a query to open the palette with it, then edit it: completions for field names and values appear under the input, and Tab takes the first.

  • plain words: titles and keywords, every level
  • one section
  • everything you can run without the palette
  • a word, but only somewhere below Git
  • exactly the contents of one menu
  • negation: the remote command outside Git
  • alternatives
  • a half-typed field: see the completion, press Tab
Handlers and events report here.
field-queries.ts
// catsearch over an editor's commands, with no configuration: the
// built-in fields (title, keyword, section, has) and the menu relations
// (parent., under.) are enough for most palettes.
import '@appulsauce/ninja-keys';
import type {INinjaAction, class NinjaKeys

A keyboard command palette: a modal list of actions, opened with a hotkey, searched as you type, with nested menus and per-action hotkeys.

@fireschange - On every change of the search text. detail is {search: string, actions: INinjaAction[]}, the actions now shown.@firesselected - When an action is chosen, or Enter is pressed with nothing to choose. detail is {search: string, action?: INinjaAction}.@firesopen - When the palette becomes visible, however it was opened.@firesclose - When the palette is hidden, however it was closed: a method, a hotkey, Escape, a click on the overlay, or an action.@slotfooter - Replaces the key-hint footer; an empty element hides it.@csspartactions-list - The scrolling list that holds every action.@csspartninja-action - One action row.@csspartninja-selected - The selected action row.@csspartninja-icon - An action's Material icon.@csspartninja-input - The search input.@csspartninja-input-wrapper - The element around the search input.@csspartninja-search-hint - The line under the input holding a searcher's completions and notice.@csspartninja-suggestion - One completion chip.@csspartninja-notice - A searcher's notice.@cssprop[--ninja-width=640px] - Width of the palette.@cssprop[--ninja-top=20%] - Distance from the top of the viewport.@cssprop[--ninja-font-size=16px] - Base size every other size scales from.@cssprop[--ninja-font-family=inherit] - Font of the palette.@cssprop[--ninja-code-font-family=ui-monospace, monospace] - Font of completion chips.@cssprop[--ninja-z-index=1] - Stacking order of the overlay.@cssprop[--ninja-backdrop-filter=none] - Filter behind the overlay, such as blur(4px).@cssprop[--ninja-overflow-background=rgba(255, 255, 255, 0.5)] - The overlay over the page.@cssprop[--ninja-modal-background=#fff] - Background of the palette.@cssprop[--ninja-modal-shadow=rgb(0 0 0 / 50%) 0px 16px 70px] - Shadow of the palette.@cssprop[--ninja-text-color=rgb(60, 65, 73)] - Text.@cssprop[--ninja-accent-color=rgb(110, 94, 210)] - Caret, selection bar and focused chips.@cssprop[--ninja-secondary-text-color=rgb(107, 111, 118)] - Hints, keys and breadcrumbs.@cssprop[--ninja-secondary-background-color=rgb(239, 241, 244)] - Key badges, breadcrumbs and chips.@cssprop[--ninja-selected-background=rgb(248, 249, 251)] - The selected row.@cssprop[--ninja-selected-text-color=inherit] - Text of the selected row.@cssprop[--ninja-placeholder-color=#8e8e8e] - Placeholder of the input.@cssprop[--ninja-group-text-color=rgb(144, 149, 157)] - Section headers.@cssprop[--ninja-icon-color=var(--ninja-secondary-text-color)] - Icons.@cssprop[--ninja-icon-size=1.2em] - Icons.@cssprop[--ninja-key-border-radius=0.25em] - Key badges, breadcrumbs and chips.@cssprop[--ninja-separate-border=1px solid var(--ninja-secondary-background-color)] - Lines between the input, the list and the footer.@cssprop[--ninja-actions-height=300px] - Maximum height of the list.@cssprop[--ninja-footer-background=rgba(242, 242, 242, 0.4)] - The footer.
NinjaKeys
} from '@appulsauce/ninja-keys';
import {function catsearchSearcher<A extends INinjaAction = INinjaAction>(options?: CatsearchOptions<A>): Searcher

A searcher that reads the search box as a catsearch query over the actions. An empty box lists the open menu as the default searcher does; a query searches every level below the open menu.

catsearchSearcher
} from '@appulsauce/ninja-keys/catsearch';
export default function function setup(ninja: NinjaKeys, report: (message: string) => void): voidsetup( ninja: NinjaKeysninja: class NinjaKeys

A keyboard command palette: a modal list of actions, opened with a hotkey, searched as you type, with nested menus and per-action hotkeys.

@fireschange - On every change of the search text. detail is {search: string, actions: INinjaAction[]}, the actions now shown.@firesselected - When an action is chosen, or Enter is pressed with nothing to choose. detail is {search: string, action?: INinjaAction}.@firesopen - When the palette becomes visible, however it was opened.@firesclose - When the palette is hidden, however it was closed: a method, a hotkey, Escape, a click on the overlay, or an action.@slotfooter - Replaces the key-hint footer; an empty element hides it.@csspartactions-list - The scrolling list that holds every action.@csspartninja-action - One action row.@csspartninja-selected - The selected action row.@csspartninja-icon - An action's Material icon.@csspartninja-input - The search input.@csspartninja-input-wrapper - The element around the search input.@csspartninja-search-hint - The line under the input holding a searcher's completions and notice.@csspartninja-suggestion - One completion chip.@csspartninja-notice - A searcher's notice.@cssprop[--ninja-width=640px] - Width of the palette.@cssprop[--ninja-top=20%] - Distance from the top of the viewport.@cssprop[--ninja-font-size=16px] - Base size every other size scales from.@cssprop[--ninja-font-family=inherit] - Font of the palette.@cssprop[--ninja-code-font-family=ui-monospace, monospace] - Font of completion chips.@cssprop[--ninja-z-index=1] - Stacking order of the overlay.@cssprop[--ninja-backdrop-filter=none] - Filter behind the overlay, such as blur(4px).@cssprop[--ninja-overflow-background=rgba(255, 255, 255, 0.5)] - The overlay over the page.@cssprop[--ninja-modal-background=#fff] - Background of the palette.@cssprop[--ninja-modal-shadow=rgb(0 0 0 / 50%) 0px 16px 70px] - Shadow of the palette.@cssprop[--ninja-text-color=rgb(60, 65, 73)] - Text.@cssprop[--ninja-accent-color=rgb(110, 94, 210)] - Caret, selection bar and focused chips.@cssprop[--ninja-secondary-text-color=rgb(107, 111, 118)] - Hints, keys and breadcrumbs.@cssprop[--ninja-secondary-background-color=rgb(239, 241, 244)] - Key badges, breadcrumbs and chips.@cssprop[--ninja-selected-background=rgb(248, 249, 251)] - The selected row.@cssprop[--ninja-selected-text-color=inherit] - Text of the selected row.@cssprop[--ninja-placeholder-color=#8e8e8e] - Placeholder of the input.@cssprop[--ninja-group-text-color=rgb(144, 149, 157)] - Section headers.@cssprop[--ninja-icon-color=var(--ninja-secondary-text-color)] - Icons.@cssprop[--ninja-icon-size=1.2em] - Icons.@cssprop[--ninja-key-border-radius=0.25em] - Key badges, breadcrumbs and chips.@cssprop[--ninja-separate-border=1px solid var(--ninja-secondary-background-color)] - Lines between the input, the list and the footer.@cssprop[--ninja-actions-height=300px] - Maximum height of the list.@cssprop[--ninja-footer-background=rgba(242, 242, 242, 0.4)] - The footer.
NinjaKeys
,
report: (message: string) => voidreport: (message: stringmessage: string) => void ): void { const const run: (action: INinjaAction) => voidrun = (action: INinjaActionaction: INinjaAction) => report: (message: string) => voidreport(`Ran "${action: INinjaActionaction.INinjaAction.title: string

The text shown in the list, and searched.

title
}"`);
const const commands: INinjaAction[]commands: INinjaAction[] = [ { INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'git',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Git',
INinjaAction.section?: string

A heading the action is grouped under, in the order sections appear.

section
: 'Git',
INinjaAction.mdIcon?: string

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'merge',
INinjaAction.children?: INinjaAction[] | string[]

The menu this action opens: the ids of its children in a flat list, or the child actions themselves in a tree. ninja-keys flattens a tree into ids, so a searcher always sees ids.

children
: [
{ INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'commit',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Commit',
INinjaAction.hotkey?: string

A shortcut that runs handler from anywhere on the page, written as hotkeys-js takes it (ctrl+n, cmd+shift+p, alt+1,alt+2 for either). Shown on the action's row.

hotkey
: 'alt+c',
INinjaAction.keywords?: string

More words to match, separated by spaces; not shown.

keywords
: 'save snapshot',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun,
}, {INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'push', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Push', INinjaAction.keywords?: string

More words to match, separated by spaces; not shown.

keywords
: 'upload remote',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun},
{ INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'pull',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Pull',
INinjaAction.keywords?: string

More words to match, separated by spaces; not shown.

keywords
: 'download remote fetch',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun,
}, { INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'branches',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Branches',
INinjaAction.children?: INinjaAction[] | string[]

The menu this action opens: the ids of its children in a flat list, or the child actions themselves in a tree. ninja-keys flattens a tree into ids, so a searcher always sees ids.

children
: [
{INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'branch-new', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'New branch',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun},
{ INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'branch-switch',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Switch branch',
INinjaAction.hotkey?: string

A shortcut that runs handler from anywhere on the page, written as hotkeys-js takes it (ctrl+n, cmd+shift+p, alt+1,alt+2 for either). Shown on the action's row.

hotkey
: 'alt+b',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun,
}, { INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'branch-delete',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Delete branch',
INinjaAction.keywords?: string

More words to match, separated by spaces; not shown.

keywords
: 'remove',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun,
}, ], }, ], }, { INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'format',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Format document',
INinjaAction.section?: string

A heading the action is grouped under, in the order sections appear.

section
: 'Editor',
INinjaAction.hotkey?: string

A shortcut that runs handler from anywhere on the page, written as hotkeys-js takes it (ctrl+n, cmd+shift+p, alt+1,alt+2 for either). Shown on the action's row.

hotkey
: 'alt+f',
INinjaAction.keywords?: string

More words to match, separated by spaces; not shown.

keywords
: 'prettier',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun,
}, { INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'rename',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Rename symbol',
INinjaAction.section?: string

A heading the action is grouped under, in the order sections appear.

section
: 'Editor',
INinjaAction.keywords?: string

More words to match, separated by spaces; not shown.

keywords
: 'refactor',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun,
}, { INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'fold',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Fold all',
INinjaAction.section?: string

A heading the action is grouped under, in the order sections appear.

section
: 'Editor',
INinjaAction.keywords?: string

More words to match, separated by spaces; not shown.

keywords
: 'collapse',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun,
}, { INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'zen',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Zen mode',
INinjaAction.section?: string

A heading the action is grouped under, in the order sections appear.

section
: 'View',
INinjaAction.keywords?: string

More words to match, separated by spaces; not shown.

keywords
: 'focus distraction',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun,
}, {INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'minimap', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Toggle minimap', INinjaAction.section?: string

A heading the action is grouped under, in the order sections appear.

section
: 'View',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun},
{ INinjaAction.id: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'remote-ssh',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Connect to host',
INinjaAction.section?: string

A heading the action is grouped under, in the order sections appear.

section
: 'Remote',
INinjaAction.keywords?: string

More words to match, separated by spaces; not shown.

keywords
: 'ssh remote',
INinjaAction.handler?: (action: INinjaAction) => {
    keepOpen?: boolean;
} | void

Runs when the action is chosen, by Enter, a click or its hotkey. The palette closes afterwards unless it returns {keepOpen: true}.

handler
: const run: (action: INinjaAction) => voidrun,
}, ]; ninja: NinjaKeysninja.NinjaKeys.data: INinjaAction[]

The actions, as a flat list (children name their menu in parent) or a tree (menus hold their children in children). Assign a new array to change it; the hotkeys are rebound each time.

data
= const commands: INinjaAction[]commands;
ninja: NinjaKeysninja.NinjaKeys.searcher: Searcher

Decides which actions a search shows, and may add a notice and completions under the search box. The default is the regular-expression match over title and keywords; @appulsauce/ninja-keys/catsearch provides a field query language (section:guides under.title:rendering).

searcher
= catsearchSearcher<INinjaAction>(options?: CatsearchOptions<INinjaAction> | undefined): Searcher

A searcher that reads the search box as a catsearch query over the actions. An empty box lists the open menu as the default searcher does; a query searches every level below the open menu.

catsearchSearcher
();
}

Which query for which question

“Run the thing I know the shortcut for.” has:hotkey lists every action with one, which doubles as a cheat sheet of the app’s shortcuts.

“The delete in Git, not the other deletes.” A word plus a place: delete under.title:git. under. follows the menu tree upwards any number of levels, so it finds Delete branch inside Git › Branches. Use parent. instead when only the direct menu counts.

“What is in that menu?” parent.title:branches lists a menu’s contents without opening it, and can be combined with anything else (parent.title:branches has:hotkey).

“Everything except…” A leading - negates any term: -section:view hides a section, and -under.title:git a whole menu’s contents, from a busy result.

“This or that.” OR (or |) between terms, or commas inside one field: section:view,editor.

Each field is listed in the catsearch guide. For fields over properties of your own actions, see the query cookbook.