Actions and menus
Everything in the palette is an action: a command that runs, a link, or a menu that holds more actions. The element’s data property takes them as an array of INinjaAction.
The action
import type {INinjaAction} from '@appulsauce/ninja-keys';
const const action: INinjaActionaction: INinjaAction = {
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: 'export-pdf', // unique; menus and breadcrumbs refer to it
INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Export as PDF', // shown and searched
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'File', // grouping heading
INinjaAction.keywords?: stringMore words to match, separated by spaces; not shown.
keywords: 'print save', // searched, not shown
INinjaAction.hotkey?: stringA 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.
hotkey: 'ctrl+shift+e', // works with the palette closed too
INinjaAction.mdIcon?: stringA Material Icons ligature name (settings, dark_mode).
mdIcon: 'picture_as_pdf', // a Material Icons name
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: (self: INinjaActionself) => {
var console: Consoleconsole.Console.log(...data: any[]): voidThe console.log() static method outputs a message to the console.
log(`running ${self: INinjaActionself.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}`);
},
};Only id and title are required. Every field is described in the API reference.
Handlers and keeping the palette open
handler runs when the action is chosen, with Enter, a click, or its hotkey, and receives the action itself. The palette closes afterwards. Return {keepOpen: true} to keep it open, for actions people repeat (zoom, next page) or ones that open a menu:
const const zoomIn: INinjaActionzoomIn: INinjaAction = {
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: 'zoom-in',
INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Zoom in',
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: () => {
var document: Documentwindow.document returns a reference to the document contained in the window.
document.Document.documentElement: HTMLElementThe documentElement read-only property of the Document interface returns the Element that is the root element of the document (for example, the element for HTML documents).
documentElement.ElementCSSInlineStyle.style: CSSStyleDeclarationstyle.CSSStyleProperties.fontSize: stringThe font-size CSS property sets the size of the font. Changing the font size also updates the sizes of the font size-relative units, such as em, ex, and so forth.
fontSize = '110%';
return {keepOpen?: booleankeepOpen: true};
},
};An action with children and no handler opens its menu. One with neither fires the selected event and leaves the palette open, which is enough when the page handles selected itself (see Opening and events).
Sections
Actions with the same section are grouped under it as a heading. Sections appear in the order their first action does, so order data the way the groups should read. Actions without a section form one group with no heading, placed where the first of them is.
Menus
A menu is an action with children. Choosing it opens the menu: the list shows its children, a breadcrumb names it above the input, and Backspace on an empty search goes back up. Menus nest to any depth. They can be written two ways.
As a tree, with children holding the child actions:
const const tree: INinjaAction[]tree: INinjaAction[] = [
{
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: 'Theme',
INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Change theme…',
INinjaAction.children?: INinjaAction[] | string[]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: [
{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: 'light', INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Light'},
{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: 'dark', INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Dark'},
],
},
];Or as a flat list, where each child names its menu in parent and the menu lists the children’s ids:
const const flat: INinjaAction[]flat: INinjaAction[] = [
{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: 'Theme', INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Change theme…', INinjaAction.children?: INinjaAction[] | string[]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: ['light', 'dark']},
{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: 'light', INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Light', INinjaAction.parent?: stringThe id of the menu this action is in, for a flat list.
parent: 'Theme'},
{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: 'dark', INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Dark', INinjaAction.parent?: stringThe id of the menu this action is in, for a flat list.
parent: 'Theme'},
];The element flattens a tree into the second form itself, so pick whichever your data already is. A flat list suits data from a server or a database; a tree suits menus written by hand. A tree’s children are given their parent from where they sit.
The breadcrumbs show the menu’s id, so give menus readable ids ('Theme', not 'menu-3').
Opening a menu directly
open({parent}) opens the palette inside a menu. A menu action’s own hotkey can do it, so the hotkey jumps straight to the choices:
const const theme: INinjaActiontheme: INinjaAction = {
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: 'Theme',
INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Change theme…',
INinjaAction.hotkey?: stringA 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.
hotkey: 'alt+t',
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: ['light', 'dark'],
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 ninja: NinjaKeysninja.NinjaKeys.open(options?: {
parent?: string;
search?: string;
} | undefined): 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.
open({parent?: stringparent: 'Theme'});
return {keepOpen?: booleankeepOpen: true};
},
};Search at the top level looks through every level, so dark finds the Dark action inside the Theme menu without opening it. Inside a menu, search looks only at that menu’s own actions (the catsearch searcher searches everything below the menu instead).
Icons
mdIcon takes a Material Icons name. The element loads that font from Google Fonts when it connects, unless the page already links it or noAutoLoadMdIcons is set.
icon takes HTML instead, usually an SVG. Give it the ninja-icon class so it is sized and coloured like the built-in icons (--ninja-icon-size, --ninja-icon-color):
const const search: INinjaActionsearch: INinjaAction = {
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: 'search',
INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Search projects…',
INinjaAction.icon?: stringHTML 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.
icon: `<svg class="ninja-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor"
stroke-width="2"><circle cx="11" cy="11" r="7"/><path d="m20 20-3.5-3.5"/></svg>`,
};icon is rendered as HTML, unescaped. Build it only from markup you control, never from user input. This site’s palette uses lucide icons this way.
Changing the actions
Assign a new array to data to change the actions; the element re-flattens it and rebinds every action hotkey, releasing the old ones. Mutating the array in place does not re-render it. Assigning the same array again does, which keeps frameworks that wrap data in proxies working.