Installation
ninja-keys is one custom element, <ninja-keys>, built with Lit. It has two runtime dependencies, lit and hotkeys-js, and works in any page or framework that can put an element in the DOM.
pnpm add @appulsauce/ninja-keys # or: npm install @appulsauce/ninja-keysImport it
Importing the package defines the element, once, for the whole page:
import '@appulsauce/ninja-keys';The same module exports the element’s class and every type, for TypeScript:
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, 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} from '@appulsauce/ninja-keys';
const const ninja: NinjaKeys | nullninja = var document: Documentwindow.document returns a reference to the document contained in the window.
document.ParentNode.querySelector<"ninja-keys">(selectors: "ninja-keys"): NinjaKeys | null (+4 overloads)Returns the first element that is a descendant of node that matches selectors.
querySelector('ninja-keys');
document.querySelector('ninja-keys') is typed as NinjaKeys | null without a cast: the package declares the tag in HTMLElementTagNameMap.
Without a build step
The package is ES modules, so a page with no bundler can load it from a CDN that resolves bare imports, such as esm.sh or unpkg’s ?module:
<script type="module" src="https://esm.sh/@appulsauce/ninja-keys@1.3.0"></script>
<ninja-keys></ninja-keys>Pin a version in the URL, as here, for anything you ship.
catsearch, for field queries
The field query searcher lives at @appulsauce/ninja-keys/catsearch and is built on the catsearch package. catsearch is an optional peer dependency: install it next to @appulsauce/ninja-keys only if you use that searcher. The main entry never loads it.
pnpm add catsearch # or: npm install catsearchUnreleased changes
To try what is on main before a release, build the repository and install the folder:
git clone https://github.com/KaiErikNiermann/ninja-keys.git
cd ninja-keys && pnpm install && pnpm run build
cd ../your-project && pnpm add ../ninja-keysIcons
Actions can show a Material Icons glyph by name (mdIcon). For that, the element adds the Material Icons stylesheet from Google Fonts to the page when it connects, unless the page already has one. Set noAutoLoadMdIcons to stop it, for example when you use your own SVG icons or must not load third-party fonts. See Actions and menus.