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.
The default search
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
darkfinds 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) => SearchResultDecides 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) => {
return {SearchResult.actions: readonly INinjaAction[]The actions to show, in the order to show them.
actions: [], SearchResult.notice?: stringOne 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 itsparent. The array is the same object untildatais set again.context.root: the id of the open menu, orundefinedat the top level.context.cursor: where the caret is insearch, 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 calledfoo” 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 itssearchtext and puts the caret at itscursor.
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) => SearchResultDecides 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.
map((a: INinjaActiona) => [a: INinjaActiona.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, a: INinjaActiona]));
}
const const parentTitle: (a: INinjaAction) => stringparentTitle = (a: INinjaActiona: INinjaAction) =>
let byId: Map<string, INinjaAction>byId.Map<string, INinjaAction>.get(key: string): INinjaAction | undefinedReturns 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.
get(a: INinjaActiona.INinjaAction.parent?: string | undefinedThe id of the menu this action is in, for a flat list.
parent ?? '')?.INinjaAction.title: string | undefinedThe text shown in the list, and searched.
title ?? '';
const const query: stringquery = search: stringsearch.String.toLowerCase(): stringConverts 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.
filter((a: INinjaActiona) =>
`${const parentTitle: (a: INinjaAction) => stringparentTitle(a: INinjaActiona)} ${a: INinjaActiona.INinjaAction.title: stringThe text shown in the list, and searched.
title}`.String.toLowerCase(): stringConverts all the alphabetic characters in a string to lowercase.
toLowerCase().String.includes(searchString: string, position?: number): booleanReturns 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.
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) => SearchResultDecides 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): SearchResultThe 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?: stringOne 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: numberGets 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: 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 = 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 typekind:event.