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
// 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 NinjaKeysA keyboard command palette: a modal list of actions, opened with a hotkey,
searched as you type, with nested menus and per-action hotkeys.
NinjaKeys} from '@appulsauce/ninja-keys';
import {function catsearchSearcher<A extends INinjaAction = INinjaAction>(options?: CatsearchOptions<A>): SearcherA 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 NinjaKeysA keyboard command palette: a modal list of actions, opened with a hotkey,
searched as you type, with nested menus and per-action hotkeys.
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: stringThe text shown in the list, and searched.
title}"`);
const const commands: INinjaAction[]commands: INinjaAction[] = [
{
INinjaAction.id: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Git',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Git',
INinjaAction.mdIcon?: stringA 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Commit',
INinjaAction.hotkey?: stringA 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?: stringMore 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Push', INinjaAction.keywords?: stringMore 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Pull',
INinjaAction.keywords?: stringMore 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: stringUnique 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: stringThe 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: stringUnique 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: stringThe 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Switch branch',
INinjaAction.hotkey?: stringA 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Delete branch',
INinjaAction.keywords?: stringMore 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Format document',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Editor',
INinjaAction.hotkey?: stringA 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?: stringMore 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Rename symbol',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Editor',
INinjaAction.keywords?: stringMore 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Fold all',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Editor',
INinjaAction.keywords?: stringMore 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Zen mode',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'View',
INinjaAction.keywords?: stringMore 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Toggle minimap', INinjaAction.section?: stringA 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: stringUnique 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: stringThe text shown in the list, and searched.
title: 'Connect to host',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Remote',
INinjaAction.keywords?: stringMore 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: SearcherDecides 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): SearcherA 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.