API reference

Generated from the library at build time: the element's attributes, events, slot, parts and CSS properties from its custom elements manifest, and every type and signature from its TypeScript sources through TypeDoc. Each description is the doc comment in the source.

<ninja-keys>

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

Import ninja-keys once to define it. Properties marked with an attribute can be set from HTML as well.

Properties

placeholder attribute placeholder default 'Type a command or search...'
placeholder: string

Placeholder of the search input.

disableHotkeys attribute disableHotkeys default false
disableHotkeys: boolean

If true, the hotkeys declared by actions are not registered. The palette's own navigation keys stay bound.

hideBreadcrumbs attribute hideBreadcrumbs default false
hideBreadcrumbs: boolean

Hide the breadcrumb row above the input that shows the open menu.

openHotkey attribute openHotkey default 'cmd+k,ctrl+k'
openHotkey: string

Opens the palette, or closes it when open. Any hotkeys-js key list; an empty string binds no key, for a palette opened only by open().

navigationUpHotkey attribute navigationUpHotkey default 'up,shift+tab'
navigationUpHotkey: string

Moves the selection up, wrapping at the top.

navigationDownHotkey attribute navigationDownHotkey default 'down,tab'
navigationDownHotkey: string

Moves the selection down, wrapping at the bottom. While the searcher offers completions, Tab takes the first instead.

closeHotkey attribute closeHotkey default 'esc'
closeHotkey: string

Closes the palette.

goBackHotkey attribute goBackHotkey default 'backspace'
goBackHotkey: string

Goes up one menu level, when the search box is empty.

selectHotkey attribute selectHotkey default 'enter'
selectHotkey: string

Chooses the selected action: runs its handler, or opens its menu. With nothing selected it still fires selected, with no action.

hotKeysJoinedView attribute hotKeysJoinedView default false
hotKeysJoinedView: boolean

Show an action's hotkey as one badge (ctrl+n) rather than a badge per key.

noAutoLoadMdIcons attribute noAutoLoadMdIcons default false
noAutoLoadMdIcons: boolean

Do not add the Material Icons stylesheet from Google Fonts to the page on connect. Set it when the actions use icon rather than mdIcon, or when the page loads the font itself.

data default []
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.

searcher default defaultSearcher
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).

visible default false
visible: boolean

Whether the palette is open. Read it; use open() and close() to change it.

Methods

open
open(options?: {parent?: string; search?: string}): void

Show a modal.

search starts the search box with that text, as if typed: a host that opens the palette on a key press can pass on what the user typed while it was opening, instead of dropping it or letting it reach the page.

submit
submit(): Promise<void>

Run the selected action, as Enter does: after open({search}), the first match. Does nothing while closed or when nothing matches. Resolves once the action has run.

close
close(): void

Close modal

setParent
setParent(parent?: string): void

Navigate to group of actions

Events

selected

When an action is chosen, or Enter is pressed with nothing to choose. detail is {search: string, action?: INinjaAction}.

change

On every change of the search text. detail is {search: string, actions: INinjaAction[]}, the actions now shown.

open

When the palette becomes visible, however it was opened.

close

When the palette is hidden, however it was closed: a method, a hotkey, Escape, a click on the overlay, or an action.

Slots

Shadow parts

actions-list

The scrolling list that holds every action.

ninja-action

One action row.

ninja-selected

The selected action row.

ninja-icon

An action's Material icon.

ninja-input

The search input.

ninja-input-wrapper

The element around the search input.

ninja-search-hint

The line under the input holding a searcher's completions and notice.

ninja-suggestion

One completion chip.

ninja-notice

A searcher's notice.

CSS properties

--ninja-width default 640px

Width of the palette.

--ninja-top default 20%

Distance from the top of the viewport.

--ninja-font-size default 16px

Base size every other size scales from.

--ninja-font-family default inherit

Font of the palette.

--ninja-code-font-family default ui-monospace, monospace

Font of completion chips.

--ninja-z-index default 1

Stacking order of the overlay.

--ninja-backdrop-filter default none

Filter behind the overlay, such as blur(4px).

--ninja-overflow-background default rgba(255, 255, 255, 0.5)

The overlay over the page.

--ninja-modal-background default #fff

Background of the palette.

--ninja-modal-shadow default rgb(0 0 0 / 50%) 0px 16px 70px

Shadow of the palette.

--ninja-text-color default rgb(60, 65, 73)

Text.

--ninja-accent-color default rgb(110, 94, 210)

Caret, selection bar and focused chips.

--ninja-secondary-text-color default rgb(107, 111, 118)

Hints, keys and breadcrumbs.

--ninja-secondary-background-color default rgb(239, 241, 244)

Key badges, breadcrumbs and chips.

--ninja-selected-background default rgb(248, 249, 251)

The selected row.

--ninja-selected-text-color default inherit

Text of the selected row.

--ninja-placeholder-color default #8e8e8e

Placeholder of the input.

--ninja-group-text-color default rgb(144, 149, 157)

Section headers.

--ninja-icon-color default var(--ninja-secondary-text-color)

Icons.

--ninja-icon-size default 1.2em

Icons.

--ninja-key-border-radius default 0.25em

Key badges, breadcrumbs and chips.

--ninja-separate-border default 1px solid var(--ninja-secondary-background-color)

Lines between the input, the list and the footer.

--ninja-actions-height default 300px

Maximum height of the list.

@appulsauce/ninja-keys

Exports of import … from '@appulsauce/ninja-keys'.

INinjaAction interface source

interface INinjaAction

One entry in the palette: a command, a link, or a menu of more actions.

children
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.

handler
handler?: (action: INinjaAction) => void | {keepOpen?: boolean}

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

hotkey
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.

icon
icon?: string

HTML for a custom icon, usually an <svg>; give it the ninja-icon class to size it like the built-in ones. Rendered unescaped, so never put untrusted text in it.

id
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.

keywords
keywords?: string

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

mdIcon
mdIcon?: string

A Material Icons ligature name (settings, dark_mode).

parent
parent?: string

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

section
section?: string

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

title
title: string

The text shown in the list, and searched.

NinjaChangeDetail interface source

interface NinjaChangeDetail

detail of the change event.

actions
readonly actions: readonly INinjaAction[]

The actions now shown, in order.

NinjaKeysEventMap interface source

interface NinjaKeysEventMap

The events <ninja-keys> fires, for typed listeners.

change
change: CustomEvent<NinjaChangeDetail>
close
close: CustomEvent<null>
open
open: CustomEvent<null>
selected
selected: CustomEvent<NinjaSelectedDetail>

NinjaSelectedDetail interface source

interface NinjaSelectedDetail

detail of the selected event.

action
readonly action: INinjaAction | undefined

The chosen action, or undefined when Enter was pressed on no match.

SearchContext interface source

interface SearchContext

What a searcher knows besides the text and the actions: which menu is open and where the caret is in the search box.

cursor
readonly cursor: number

The caret's offset in the search text, in UTF-16 code units.

root
readonly root: string | undefined

The id of the open submenu, or undefined at the root.

SearchResult interface source

interface SearchResult
actions
readonly actions: readonly INinjaAction[]

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

notice
readonly notice?: string

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

suggestions
readonly suggestions?: readonly SearchSuggestion[]

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

SearchSuggestion interface source

interface SearchSuggestion

A completion for the search text. Taking it replaces the whole search with search and puts the caret at cursor (the end when omitted).

cursor
readonly cursor?: number

Where the caret goes in search; the end when omitted.

detail
readonly detail?: string

A hint shown dimmed beside the label.

label
readonly label: string

What the chip shows, such as section:.

Searcher type source

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.

defaultSearcher const source

const defaultSearcher: Searcher

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.

groupBySection function source

function groupBySection(actions: readonly INinjaAction[]): Map<string | undefined, INinjaAction[]>

Actions grouped by section, sections in the order they first appear. Pushes into the existing bucket rather than rebuilding it per action, which an earlier reduce did and which made this quadratic in the number of matches.

@appulsauce/ninja-keys/catsearch

Exports of import … from '@appulsauce/ninja-keys/catsearch'.

CatsearchOptions interface source

interface CatsearchOptions<A extends INinjaAction>
fields
readonly fields?: readonly Field<A>[]

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.

limit
readonly limit?: number

How many completions to offer at once (default 10).

relations
readonly relations?: readonly Relation<A>[]

More relations, after parent and under.

catsearchSearcher function source

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.