Search

How the palette decides what a search shows is replaceable. Out of the box it matches text; set the searcher property to rank results your way, query fields, add a line of help under the input, or offer completions.

With no searcher set, the search text is read as a case-insensitive regular expression over each action’s title and keywords. Text that is not a valid expression (a lone ( or [) is matched as a plain substring instead, so typing never breaks the list.

  • At the top level, a search looks through every level, so dark finds an action inside a Theme menu.
  • Inside a menu, it looks only at that menu’s own actions.
  • An empty search shows the actions of the open menu (the top level when none is).

Matches keep the order of data and are grouped by section. This search is exported as defaultSearcher, for searchers that wrap it.

The searcher contract

A searcher is a function from the search text to what the palette shows:

const const searcher: Searchersearcher: type Searcher = (search: string, actions: readonly INinjaAction[], context: SearchContext) => SearchResult

Decides which actions a search shows. ninja-keys calls it on every render with the flattened action list, so it should be cheap; cache anything derived from actions by the array's identity, which only changes when data is set.

Searcher
= (
search: string
search
, actions: readonly INinjaAction[]actions, context: SearchContextcontext) => {
return {SearchResult.actions: readonly INinjaAction[]

The actions to show, in the order to show them.

actions
: [], SearchResult.notice?: string

One line about the query (a half-typed filter, an unknown field).

notice
: '', SearchResult.suggestions?: readonly SearchSuggestion[]

Completions for the text under the caret. Tab takes the first.

suggestions
: []};
};

It receives:

  • search: the text in the box.
  • actions: every action, flattened, so a tree’s children are ids and each child has its parent. The array is the same object until data is set again.
  • context.root: the id of the open menu, or undefined at the top level.
  • context.cursor: where the caret is in search, for completing the word under it.

It returns a SearchResult:

  • actions: the actions to show, in the order to show them. The palette still groups them by section, in the order sections first appear.
  • notice (optional): one line shown under the input, such as “no field called foo” or “Enter searches the web”.
  • suggestions (optional): completions, shown as chips under the input. Clicking one, or Tab for the first, replaces the search with its search text and puts the caret at its cursor.

The palette calls the searcher on every render, which is every keystroke and more. Keep it cheap: anything derived from actions alone (an index, a lookup by id) can be built once and cached on the array’s identity.

let let indexed: readonly INinjaAction[] | undefinedindexed: readonly INinjaAction[] | undefined;
let let byId: Map<string, INinjaAction>byId = new 
var Map: MapConstructor
new <string, INinjaAction>(iterable?: Iterable<readonly [string, INinjaAction]> | null | undefined) => Map<string, INinjaAction> (+3 overloads)
Map
<string, INinjaAction>();
const const searcher: Searchersearcher: type Searcher = (search: string, actions: readonly INinjaAction[], context: SearchContext) => SearchResult

Decides which actions a search shows. ninja-keys calls it on every render with the flattened action list, so it should be cheap; cache anything derived from actions by the array's identity, which only changes when data is set.

Searcher
= (search: stringsearch, actions: readonly INinjaAction[]actions) => {
if (actions: readonly INinjaAction[]actions !== let indexed: readonly INinjaAction[] | undefinedindexed) { let indexed: readonly INinjaAction[] | undefinedindexed = actions: readonly INinjaAction[]actions; let byId: Map<string, INinjaAction>byId = new
var Map: MapConstructor
new <string, INinjaAction>(iterable?: Iterable<readonly [string, INinjaAction]> | null | undefined) => Map<string, INinjaAction> (+3 overloads)
Map
(actions: readonly INinjaAction[]actions.ReadonlyArray<INinjaAction>.map<[string, INinjaAction]>(callbackfn: (value: INinjaAction, index: number, array: readonly INinjaAction[]) => [string, INinjaAction], thisArg?: any): [string, INinjaAction][]

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
((a: INinjaActiona) => [a: INinjaActiona.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
, a: INinjaActiona]));
} const const parentTitle: (a: INinjaAction) => stringparentTitle = (a: INinjaActiona: INinjaAction) => let byId: Map<string, INinjaAction>byId.Map<string, INinjaAction>.get(key: string): INinjaAction | undefined

Returns a specified element from the Map object. If the value that is associated to the provided key is an object, then you will get a reference to that object and any change made to that object will effectively modify it inside the Map.

@returnsReturns the element associated with the specified key. If no element is associated with the specified key, undefined is returned.
get
(a: INinjaActiona.INinjaAction.parent?: string | undefined

The id of the menu this action is in, for a flat list.

parent
?? '')?.INinjaAction.title: string | undefined

The text shown in the list, and searched.

title
?? '';
const const query: stringquery = search: stringsearch.String.toLowerCase(): string

Converts all the alphabetic characters in a string to lowercase.

toLowerCase
();
return { SearchResult.actions: readonly INinjaAction[]

The actions to show, in the order to show them.

actions
: actions: readonly INinjaAction[]actions.ReadonlyArray<INinjaAction>.filter(predicate: (value: INinjaAction, index: number, array: readonly INinjaAction[]) => unknown, thisArg?: any): INinjaAction[] (+1 overload)

Returns the elements of an array that meet the condition specified in a callback function.

@parampredicate A function that accepts up to three arguments. The filter method calls the predicate function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the predicate function. If thisArg is omitted, undefined is used as the this value.
filter
((a: INinjaActiona) =>
`${const parentTitle: (a: INinjaAction) => stringparentTitle(a: INinjaActiona)} ${a: INinjaActiona.INinjaAction.title: string

The text shown in the list, and searched.

title
}`.String.toLowerCase(): string

Converts all the alphabetic characters in a string to lowercase.

toLowerCase
().String.includes(searchString: string, position?: number): boolean

Returns true if searchString appears as a substring of the result of converting this object to a String, at one or more positions that are greater than or equal to position; otherwise, returns false.

@paramsearchString search string@paramposition If position is undefined, 0 is assumed, so as to search all of the String.
includes
(const query: stringquery)
), }; };

Wrapping the default

To keep the default’s matching and add to it, call defaultSearcher and change its result:

const const withHelp: SearcherwithHelp: type Searcher = (search: string, actions: readonly INinjaAction[], context: SearchContext) => SearchResult

Decides which actions a search shows. ninja-keys calls it on every render with the flattened action list, so it should be cheap; cache anything derived from actions by the array's identity, which only changes when data is set.

Searcher
= (search: stringsearch, actions: readonly INinjaAction[]actions, context: SearchContextcontext) => {
const const result: SearchResultresult = function defaultSearcher(search: string, actions: readonly INinjaAction[], context: SearchContext): SearchResult

The search ninja-keys has always done: the text as a case-insensitive regular expression over title and keywords, across every level at the root and within the open submenu otherwise.

defaultSearcher
(search: stringsearch, actions: readonly INinjaAction[]actions, context: SearchContextcontext);
return { ...const result: SearchResultresult, SearchResult.notice?: string

One line about the query (a half-typed filter, an unknown field).

notice
:
const result: SearchResultresult.SearchResult.actions: readonly INinjaAction[]

The actions to show, in the order to show them.

actions
.ReadonlyArray<INinjaAction>.length: number

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

length
=== 0
? 'Nothing here. Enter searches the API.' : '', }; }; const 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 withHelp: SearcherwithHelp;

Pair a notice like that with a selected listener, which fires with no action when Enter is pressed on an empty list (see Events).

Searchers in these docs

  • Ranked searcher: prefix matches before word matches before substrings, with a notice.
  • catsearch queries: a field query language with completions, shipped as @appulsauce/ninja-keys/catsearch. This site’s own search uses it; press Ctrl K and type kind:event.