Basic palette
Six actions in three sections, each with a Material icon; three have hotkeys. Open the palette and try:
- typing
re: the Files section narrows to Open recent, matched on its keywords too (reopen); - pressing Enter on Zoom in: the palette stays open, because its handler returns
{keepOpen: true}; - closing the palette and pressing Alt N: an action’s hotkey works without the palette.
// A flat list of actions in three sections, with Material icons, hotkeys
// and handlers. `setup` gets this demo's <ninja-keys> and a `report`
// function that writes to the line above; on your page the element is
// `document.querySelector('ninja-keys')`.
import '@appulsauce/ninja-keys';
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} from '@appulsauce/ninja-keys';
export default function function setup(ninja: NinjaKeys, report: (message: string) => void): voidsetup(
ninja: NinjaKeysninja: 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,
report: (message: string) => voidreport: (message: stringmessage: string) => void
): void {
const const actions: INinjaAction[]actions: 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: 'new-file',
INinjaAction.title: stringThe text shown in the list, and searched.
title: 'New file',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Files',
INinjaAction.mdIcon?: stringA Material Icons ligature name (settings, dark_mode).
mdIcon: 'note_add',
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+n',
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: () => report: (message: string) => voidreport('New file'),
},
{
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: 'open-recent',
INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Open recent…',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Files',
INinjaAction.mdIcon?: stringA Material Icons ligature name (settings, dark_mode).
mdIcon: 'history',
INinjaAction.keywords?: stringMore words to match, separated by spaces; not shown.
keywords: 'previous last reopen',
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: () => report: (message: string) => voidreport('Open recent'),
},
{
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: 'share',
INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Share link',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Files',
INinjaAction.mdIcon?: stringA Material Icons ligature name (settings, dark_mode).
mdIcon: 'link',
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+s',
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: (action: INinjaActionaction) => report: (message: string) => voidreport(`${action: INinjaActionaction.INinjaAction.title: stringThe text shown in the list, and searched.
title}: copied`),
},
{
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.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'View',
INinjaAction.mdIcon?: stringA Material Icons ligature name (settings, dark_mode).
mdIcon: 'zoom_in',
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+=',
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: () => {
report: (message: string) => voidreport('Zoom in (the palette stays open)');
// Keep the palette open for actions people repeat.
return {keepOpen?: booleankeepOpen: true};
},
},
{
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: 'full-screen',
INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Toggle full screen',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'View',
INinjaAction.mdIcon?: stringA Material Icons ligature name (settings, dark_mode).
mdIcon: 'fullscreen',
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: () => report: (message: string) => voidreport('Full screen'),
},
{
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: 'docs',
INinjaAction.title: stringThe text shown in the list, and searched.
title: 'Read the docs',
INinjaAction.section?: stringA heading the action is grouped under, in the order sections appear.
section: 'Help',
INinjaAction.mdIcon?: stringA Material Icons ligature name (settings, dark_mode).
mdIcon: 'menu_book',
INinjaAction.keywords?: stringMore words to match, separated by spaces; not shown.
keywords: 'manual guide',
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: () => report: (message: string) => voidreport('Docs'),
},
];
ninja: NinjaKeysninja.NinjaKeys.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.
data = const actions: INinjaAction[]actions;
}This is the whole of the Quickstart. The fields are described in Actions and menus.