Query cookbook

A documentation tree, three levels deep (area, topic, page), where each page carries data the palette never shows: a kind, tags, the year it was last updated, and whether it is a draft. Four fields declared over those properties turn them into queries, and catsearch completes their names and values from the actions themselves. This is the shape of a docs site’s search, a settings screen, or a file tree.

  • plain words still search titles and keywords
  • only leaves, no areas or topics
  • every page below one area
  • recent GPU material
  • a range: what may be out of date
  • unfinished pages, for an editor
  • published pages in one topic
  • grouped alternatives within an area
  • pages nobody has tagged yet
  • a half-typed path: the completions show what can follow
Handlers and events report here.
query-cookbook.ts
// catsearch with fields of your own. Each doc page carries a kind, tags,
// a year and a draft flag next to the fields ninja-keys reads; declaring
// fields over them makes `kind:page tag:gpu updated:>=2026 -is:draft`
// a query, with completions for every name and value.
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';
import {function enumField<Row>(spec: Options<EnumField<Row>, "name" | "get">): EnumField<Row>enumField,
function flagField<Row>(spec: Omit<Options<FlagField<Row>, "name">, "flags"> & {
    readonly flags: ReadonlyMap<string, (row: Row) => boolean> | Readonly<Record<string, (row: Row) => boolean>>;
}): FlagField<Row>
flagField
, function numberField<Row>(spec: Options<NumberField<Row>, "name" | "get">): NumberField<Row>numberField, function textField<Row>(spec: Options<TextField<Row>, "name" | "get">): TextField<Row>textField} from 'catsearch';
type type Kind = "area" | "topic" | "page"Kind = 'area' | 'topic' | 'page'; interface Doc extends INinjaAction { readonly Doc.kind: Kindkind: type Kind = "area" | "topic" | "page"Kind; readonly Doc.tags: readonly string[]tags: readonly string[]; readonly Doc.updated: numberupdated: number; readonly Doc.draft: booleandraft: boolean; } interface Entry { readonly Entry.title: stringtitle: string; readonly Entry.tags?: readonly string[]tags?: readonly string[]; readonly Entry.updated?: numberupdated?: number; readonly Entry.draft?: booleandraft?: boolean; readonly Entry.keywords?: stringkeywords?: string; readonly Entry.children?: readonly Entry[]children?: readonly Entry[]; } const const KINDS: readonly Kind[]KINDS: readonly type Kind = "area" | "topic" | "page"Kind[] = ['area', 'topic', 'page']; /** An entry and everything below it, as one nested action. */ function function doc(entry: Entry, depth: number, section: string): Doc

An entry and everything below it, as one nested action.

doc
(entry: Entryentry: Entry, depth: numberdepth: number, section: stringsection: string): Doc {
return { 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
: entry: Entryentry.Entry.title: stringtitle,
INinjaAction.title: string

The text shown in the list, and searched.

title
: entry: Entryentry.Entry.title: stringtitle,
INinjaAction.section?: string

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

section
,
Doc.kind: Kindkind: const KINDS: readonly Kind[]KINDS[var Math: Math

An intrinsic object that provides basic mathematics functionality and constants.

Math
.Math.min(...values: number[]): number

Returns the smaller of a set of supplied numeric expressions.

@paramvalues Numeric expressions to be evaluated.
min
(depth: numberdepth, const KINDS: readonly Kind[]KINDS.ReadonlyArray<Kind>.length: number

Gets the length of the array. This is a number one higher than the highest element defined in an array.

length
- 1)] ?? 'page',
Doc.tags: readonly string[]tags: entry: Entryentry.Entry.tags?: readonly string[] | undefinedtags ?? [], Doc.updated: numberupdated: entry: Entryentry.Entry.updated?: number | undefinedupdated ?? 2025, Doc.draft: booleandraft: entry: Entryentry.Entry.draft?: boolean | undefineddraft ?? false, ...(entry: Entryentry.Entry.keywords?: string | undefinedkeywords !== var undefinedundefined && {INinjaAction.keywords?: string

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

keywords
: entry: Entryentry.Entry.keywords?: stringkeywords}),
...(entry: Entryentry.Entry.children?: readonly Entry[] | undefinedchildren && { INinjaAction.children?: string[] | INinjaAction[]

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
: entry: Entryentry.Entry.children?: readonly Entry[]children.ReadonlyArray<Entry>.map<Doc>(callbackfn: (value: Entry, index: number, array: readonly Entry[]) => Doc, thisArg?: any): Doc[]

Calls a defined callback function on each element of an array, and returns an array that contains the results.

@paramcallbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
map
((child: Entrychild) => function doc(entry: Entry, depth: number, section: string): Doc

An entry and everything below it, as one nested action.

doc
(child: Entrychild, depth: numberdepth + 1, section: stringsection)),
}), }; } const const TREE: readonly Entry[]TREE: readonly Entry[] = [ { Entry.title: stringtitle: 'Rendering', Entry.tags?: readonly string[]tags: ['gpu'], Entry.children?: readonly Entry[]children: [ { Entry.title: stringtitle: 'Lighting', Entry.children?: readonly Entry[]children: [ { Entry.title: stringtitle: 'Shadow maps', Entry.tags?: readonly string[]tags: ['gpu', 'quality'], Entry.keywords?: stringkeywords: 'pcf cascades', Entry.updated?: numberupdated: 2026, }, { Entry.title: stringtitle: 'Global illumination', Entry.tags?: readonly string[]tags: ['gpu', 'baking'], Entry.updated?: numberupdated: 2024, }, {Entry.title: stringtitle: 'Bloom', Entry.tags?: readonly string[]tags: ['post'], Entry.draft?: booleandraft: true}, ], }, { Entry.title: stringtitle: 'Materials', Entry.children?: readonly Entry[]children: [ { Entry.title: stringtitle: 'PBR basics', Entry.tags?: readonly string[]tags: ['quality'], Entry.keywords?: stringkeywords: 'roughness metallic', }, {Entry.title: stringtitle: 'Texture compression', Entry.tags?: readonly string[]tags: ['memory'], Entry.updated?: numberupdated: 2026}, ], }, ], }, { Entry.title: stringtitle: 'Audio', Entry.children?: readonly Entry[]children: [ { Entry.title: stringtitle: 'Mixing', Entry.children?: readonly Entry[]children: [ {Entry.title: stringtitle: 'Buses', Entry.updated?: numberupdated: 2023}, {Entry.title: stringtitle: 'Ducking and sidechains', Entry.keywords?: stringkeywords: 'compressor'}, ], }, { Entry.title: stringtitle: 'Spatial audio', Entry.children?: readonly Entry[]children: [ {Entry.title: stringtitle: 'HRTF', Entry.tags?: readonly string[]tags: ['quality']}, { Entry.title: stringtitle: 'Occlusion', Entry.keywords?: stringkeywords: 'acoustic shadow', Entry.updated?: numberupdated: 2026, Entry.draft?: booleandraft: true, }, ], }, ], }, { Entry.title: stringtitle: 'Performance', Entry.children?: readonly Entry[]children: [ { Entry.title: stringtitle: 'Profiling', Entry.children?: readonly Entry[]children: [ {Entry.title: stringtitle: 'GPU captures', Entry.tags?: readonly string[]tags: ['gpu'], Entry.updated?: numberupdated: 2026}, {Entry.title: stringtitle: 'Frame budget', Entry.keywords?: stringkeywords: 'ms fps'}, { Entry.title: stringtitle: 'Shadow cost', Entry.tags?: readonly string[]tags: ['gpu'], Entry.keywords?: stringkeywords: 'cascades', Entry.draft?: booleandraft: true, }, ], }, ], }, ]; export const const docsSearcher: SearcherdocsSearcher = catsearchSearcher<Doc>(options?: CatsearchOptions<Doc> | 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
<Doc>({
CatsearchOptions<Doc>.fields?: readonly Field<Doc>[]

More fields over your actions, after the built-in ones. A name or alias that clashes with a built-in field makes the Schema constructor throw.

fields
: [
enumField<Doc>(spec: Options<EnumField<Doc>, "name" | "get">): EnumField<Doc>enumField<Doc>({ name: stringname: 'kind', get: (row: Doc) => Stringsget: (d: Docd) => d: Docd.Doc.kind: Kindkind, choices?: readonly string[]choices: const KINDS: readonly Kind[]KINDS, detail?: string

What completion calls this field's values; defaults to the name.

detail
: 'area, topic or page',
}), textField<Doc>(spec: Options<TextField<Doc>, "name" | "get">): TextField<Doc>textField<Doc>({name: stringname: 'tag', get: (row: Doc) => Stringsget: (d: Docd) => d: Docd.Doc.tags: readonly string[]tags}), numberField<Doc>(spec: Options<NumberField<Doc>, "name" | "get">): NumberField<Doc>numberField<Doc>({name: stringname: 'updated', get: (row: Doc) => Numbersget: (d: Docd) => d: Docd.Doc.updated: numberupdated}),
flagField<Doc>(spec: Omit<Options<FlagField<Doc>, "name">, "flags"> & {
    readonly flags: ReadonlyMap<string, (row: Doc) => boolean> | Readonly<Record<string, (row: Doc) => boolean>>;
}): FlagField<Doc>
flagField
<Doc>({
name: stringname: 'is', flags: ReadonlyMap<string, (row: Doc) => boolean> | Readonly<Record<string, (row: Doc) => boolean>>flags: {draft: (d: Doc) => booleandraft: (d: Docd) => d: Docd.Doc.draft: booleandraft, published: (d: Doc) => booleanpublished: (d: Docd) => !d: Docd.Doc.draft: booleandraft}, }), ], }); 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 open: (action: INinjaAction) => voidopen = (action: INinjaActionaction: INinjaAction) => { const const d: Docd = action: INinjaActionaction as Doc; report: (message: string) => voidreport(`${const d: Docd.INinjaAction.title: string

The text shown in the list, and searched.

title
}: ${const d: Docd.Doc.kind: Kindkind}, ${const d: Docd.Doc.updated: numberupdated}${const d: Docd.Doc.draft: booleandraft ? ', draft' : ''}`);
}; const const withHandlers: (d: Doc) => DocwithHandlers = (d: Docd: Doc): Doc => d: Docd.INinjaAction.children?: string[] | INinjaAction[] | undefined

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
?.Array<T>.length: number | undefined

Gets or sets the length of the array. This is a number one higher than the highest index in the array.

length
? { ...d: Docd, INinjaAction.children?: string[] | INinjaAction[]

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
: (d: Docd.INinjaAction.children?: string[] | INinjaAction[]

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
as Doc[]).Array<Doc>.map<Doc>(callbackfn: (value: Doc, index: number, array: Doc[]) => Doc, thisArg?: any): Doc[]

Calls a defined callback function on each element of an array, and returns an array that contains the results.

@paramcallbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
map
((child: Docchild) => const withHandlers: (d: Doc) => DocwithHandlers(child: Docchild)),
} : {...d: Docd,
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 open: (action: INinjaAction) => voidopen};
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 TREE: readonly Entry[]TREE.ReadonlyArray<Entry>.map<Doc>(callbackfn: (value: Entry, index: number, array: readonly Entry[]) => Doc, thisArg?: any): Doc[]

Calls a defined callback function on each element of an array, and returns an array that contains the results.

@paramcallbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
map
((entry: Entryentry) => const withHandlers: (d: Doc) => DocwithHandlers(function doc(entry: Entry, depth: number, section: string): Doc

An entry and everything below it, as one nested action.

doc
(entry: Entryentry, 0, entry: Entryentry.Entry.title: stringtitle)));
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
= const docsSearcher: SearcherdocsSearcher;
}

The fields

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';
import {function enumField<Row>(spec: Options<EnumField<Row>, "name" | "get">): EnumField<Row>enumField,
function flagField<Row>(spec: Omit<Options<FlagField<Row>, "name">, "flags"> & {
    readonly flags: ReadonlyMap<string, (row: Row) => boolean> | Readonly<Record<string, (row: Row) => boolean>>;
}): FlagField<Row>
flagField
, function numberField<Row>(spec: Options<NumberField<Row>, "name" | "get">): NumberField<Row>numberField, function textField<Row>(spec: Options<TextField<Row>, "name" | "get">): TextField<Row>textField} from 'catsearch';
const const searcher: Searchersearcher = catsearchSearcher<Doc>(options?: CatsearchOptions<Doc> | 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
<Doc>({
CatsearchOptions<Doc>.fields?: readonly Field<Doc>[]

More fields over your actions, after the built-in ones. A name or alias that clashes with a built-in field makes the Schema constructor throw.

fields
: [
enumField<Doc>(spec: Options<EnumField<Doc>, "name" | "get">): EnumField<Doc>enumField<Doc>({ name: stringname: 'kind', get: (row: Doc) => Stringsget: (d: Docd) => d: Docd.Doc.kind: "area" | "topic" | "page"kind, choices?: readonly string[]choices: ['area', 'topic', 'page'], }), textField<Doc>(spec: Options<TextField<Doc>, "name" | "get">): TextField<Doc>textField<Doc>({name: stringname: 'tag', get: (row: Doc) => Stringsget: (d: Docd) => d: Docd.Doc.tags: readonly string[]tags}), numberField<Doc>(spec: Options<NumberField<Doc>, "name" | "get">): NumberField<Doc>numberField<Doc>({name: stringname: 'updated', get: (row: Doc) => Numbersget: (d: Docd) => d: Docd.Doc.updated: numberupdated}),
flagField<Doc>(spec: Omit<Options<FlagField<Doc>, "name">, "flags"> & {
    readonly flags: ReadonlyMap<string, (row: Doc) => boolean> | Readonly<Record<string, (row: Doc) => boolean>>;
}): FlagField<Doc>
flagField
<Doc>({
name: stringname: 'is', flags: ReadonlyMap<string, (row: Doc) => boolean> | Readonly<Record<string, (row: Doc) => boolean>>flags: {draft: (d: Doc) => booleandraft: (d: Docd) => d: Docd.Doc.draft: booleandraft, published: (d: Doc) => booleanpublished: (d: Docd) => !d: Docd.Doc.draft: booleandraft}, }), ], });

Choose the field kind by the question people will ask of it:

KindUse forBecause
enumFielda fixed set of values: kind, status, typeit matches whole values, so kind:page never matches “pager”; choices completes values no action has yet
textFieldfree text and lists: tags, authors, pathsit matches substrings, and get can return an array
numberFielddates, sizes, counts, prioritiesit takes ranges: 2023..2024, >=2026, <10
flagFieldyes/no states with names: draft, pinned, readseveral named predicates under one key: is:draft, is:published

Recipes

Narrow, then search. Put the structural part first and the words last: under.title:audio kind:page occlusion. The completions keep up while you type the words.

Find stale content. updated:<2025 -is:draft lists published pages not touched since 2024: a review queue.

Find gaps. none matches an empty field: tag:none for untagged pages, section:none for actions outside any section.

Scope to the open menu. Inside a menu, a query searches only below it, so opening Rendering and typing kind:page lists Rendering’s pages without saying under..

Link to a search. A query is text, so a link can carry one: read it from the URL and pass it to open({search}) (see the page-driven example).

Every operator is in the catsearch guide.