Nested menus

Menus three levels deep, written as a tree. Choosing Settings… opens its menu; the breadcrumb above the input names where you are, and Backspace on an empty search goes back up. A search at the top level still finds every level: type cozy.

Handlers and events report here.
nested.ts
// Menus inside menus, written as a tree: `children` holds the child
// actions, and ninja-keys flattens it. An action with children opens its
// menu when chosen; Backspace on an empty search goes back up.
import '@appulsauce/ninja-keys';
import type {INinjaAction, class NinjaKeys

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

@fireschange - On every change of the search text. detail is {search: string, actions: INinjaAction[]}, the actions now shown.@firesselected - When an action is chosen, or Enter is pressed with nothing to choose. detail is {search: string, action?: INinjaAction}.@firesopen - When the palette becomes visible, however it was opened.@firesclose - When the palette is hidden, however it was closed: a method, a hotkey, Escape, a click on the overlay, or an action.@slotfooter - Replaces the key-hint footer; an empty element hides it.@csspartactions-list - The scrolling list that holds every action.@csspartninja-action - One action row.@csspartninja-selected - The selected action row.@csspartninja-icon - An action's Material icon.@csspartninja-input - The search input.@csspartninja-input-wrapper - The element around the search input.@csspartninja-search-hint - The line under the input holding a searcher's completions and notice.@csspartninja-suggestion - One completion chip.@csspartninja-notice - A searcher's notice.@cssprop[--ninja-width=640px] - Width of the palette.@cssprop[--ninja-top=20%] - Distance from the top of the viewport.@cssprop[--ninja-font-size=16px] - Base size every other size scales from.@cssprop[--ninja-font-family=inherit] - Font of the palette.@cssprop[--ninja-code-font-family=ui-monospace, monospace] - Font of completion chips.@cssprop[--ninja-z-index=1] - Stacking order of the overlay.@cssprop[--ninja-backdrop-filter=none] - Filter behind the overlay, such as blur(4px).@cssprop[--ninja-overflow-background=rgba(255, 255, 255, 0.5)] - The overlay over the page.@cssprop[--ninja-modal-background=#fff] - Background of the palette.@cssprop[--ninja-modal-shadow=rgb(0 0 0 / 50%) 0px 16px 70px] - Shadow of the palette.@cssprop[--ninja-text-color=rgb(60, 65, 73)] - Text.@cssprop[--ninja-accent-color=rgb(110, 94, 210)] - Caret, selection bar and focused chips.@cssprop[--ninja-secondary-text-color=rgb(107, 111, 118)] - Hints, keys and breadcrumbs.@cssprop[--ninja-secondary-background-color=rgb(239, 241, 244)] - Key badges, breadcrumbs and chips.@cssprop[--ninja-selected-background=rgb(248, 249, 251)] - The selected row.@cssprop[--ninja-selected-text-color=inherit] - Text of the selected row.@cssprop[--ninja-placeholder-color=#8e8e8e] - Placeholder of the input.@cssprop[--ninja-group-text-color=rgb(144, 149, 157)] - Section headers.@cssprop[--ninja-icon-color=var(--ninja-secondary-text-color)] - Icons.@cssprop[--ninja-icon-size=1.2em] - Icons.@cssprop[--ninja-key-border-radius=0.25em] - Key badges, breadcrumbs and chips.@cssprop[--ninja-separate-border=1px solid var(--ninja-secondary-background-color)] - Lines between the input, the list and the footer.@cssprop[--ninja-actions-height=300px] - Maximum height of the list.@cssprop[--ninja-footer-background=rgba(242, 242, 242, 0.4)] - The footer.
NinjaKeys
} from '@appulsauce/ninja-keys';
export default function function setup(ninja: NinjaKeys, report: (message: string) => void, page: HTMLElement): voidsetup( ninja: NinjaKeysninja: class NinjaKeys

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

@fireschange - On every change of the search text. detail is {search: string, actions: INinjaAction[]}, the actions now shown.@firesselected - When an action is chosen, or Enter is pressed with nothing to choose. detail is {search: string, action?: INinjaAction}.@firesopen - When the palette becomes visible, however it was opened.@firesclose - When the palette is hidden, however it was closed: a method, a hotkey, Escape, a click on the overlay, or an action.@slotfooter - Replaces the key-hint footer; an empty element hides it.@csspartactions-list - The scrolling list that holds every action.@csspartninja-action - One action row.@csspartninja-selected - The selected action row.@csspartninja-icon - An action's Material icon.@csspartninja-input - The search input.@csspartninja-input-wrapper - The element around the search input.@csspartninja-search-hint - The line under the input holding a searcher's completions and notice.@csspartninja-suggestion - One completion chip.@csspartninja-notice - A searcher's notice.@cssprop[--ninja-width=640px] - Width of the palette.@cssprop[--ninja-top=20%] - Distance from the top of the viewport.@cssprop[--ninja-font-size=16px] - Base size every other size scales from.@cssprop[--ninja-font-family=inherit] - Font of the palette.@cssprop[--ninja-code-font-family=ui-monospace, monospace] - Font of completion chips.@cssprop[--ninja-z-index=1] - Stacking order of the overlay.@cssprop[--ninja-backdrop-filter=none] - Filter behind the overlay, such as blur(4px).@cssprop[--ninja-overflow-background=rgba(255, 255, 255, 0.5)] - The overlay over the page.@cssprop[--ninja-modal-background=#fff] - Background of the palette.@cssprop[--ninja-modal-shadow=rgb(0 0 0 / 50%) 0px 16px 70px] - Shadow of the palette.@cssprop[--ninja-text-color=rgb(60, 65, 73)] - Text.@cssprop[--ninja-accent-color=rgb(110, 94, 210)] - Caret, selection bar and focused chips.@cssprop[--ninja-secondary-text-color=rgb(107, 111, 118)] - Hints, keys and breadcrumbs.@cssprop[--ninja-secondary-background-color=rgb(239, 241, 244)] - Key badges, breadcrumbs and chips.@cssprop[--ninja-selected-background=rgb(248, 249, 251)] - The selected row.@cssprop[--ninja-selected-text-color=inherit] - Text of the selected row.@cssprop[--ninja-placeholder-color=#8e8e8e] - Placeholder of the input.@cssprop[--ninja-group-text-color=rgb(144, 149, 157)] - Section headers.@cssprop[--ninja-icon-color=var(--ninja-secondary-text-color)] - Icons.@cssprop[--ninja-icon-size=1.2em] - Icons.@cssprop[--ninja-key-border-radius=0.25em] - Key badges, breadcrumbs and chips.@cssprop[--ninja-separate-border=1px solid var(--ninja-secondary-background-color)] - Lines between the input, the list and the footer.@cssprop[--ninja-actions-height=300px] - Maximum height of the list.@cssprop[--ninja-footer-background=rgba(242, 242, 242, 0.4)] - The footer.
NinjaKeys
,
report: (message: string) => voidreport: (message: stringmessage: string) => void, page: HTMLElementpage: HTMLElement ): void { const const pick: (choice: string) => () => voidpick = (choice: stringchoice: string) => () => report: (message: string) => voidreport(choice: stringchoice); const const tree: INinjaAction[]tree: INinjaAction[] = [ { INinjaAction.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.

id
: 'Projects',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Open project…',
INinjaAction.mdIcon?: string

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'folder_open',
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: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'atlas', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'atlas',
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 pick: (choice: string) => () => voidpick('Opened atlas')},
{INinjaAction.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.

id
: 'beacon', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'beacon',
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 pick: (choice: string) => () => voidpick('Opened beacon')},
{INinjaAction.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.

id
: 'cinder', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'cinder',
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 pick: (choice: string) => () => voidpick('Opened cinder')},
], }, { INinjaAction.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.

id
: 'Settings',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Settings…',
INinjaAction.mdIcon?: string

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'settings',
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: string

Unique 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: string

The text shown in the list, and searched.

title
: 'Theme…',
INinjaAction.mdIcon?: string

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'palette',
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: string

Unique 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: string

The text shown in the list, and searched.

title
: 'Light',
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 pick: (choice: string) => () => voidpick('Light theme')},
{INinjaAction.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.

id
: 'dark', INinjaAction.title: string

The text shown in the list, and searched.

title
: '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 pick: (choice: string) => () => voidpick('Dark theme')},
], }, { INinjaAction.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.

id
: 'Density',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Density…',
INinjaAction.mdIcon?: string

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'density_medium',
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: string

Unique across all actions. Child actions name their menu by it in parent, and the breadcrumbs show it while that menu is open.

id
: 'compact', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Compact',
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 pick: (choice: string) => () => voidpick('Compact')},
{INinjaAction.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.

id
: 'cozy', INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Cozy',
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 pick: (choice: string) => () => voidpick('Cozy')},
], }, ], }, { INinjaAction.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.

id
: 'sign-out',
INinjaAction.title: string

The text shown in the list, and searched.

title
: 'Sign out',
INinjaAction.mdIcon?: string

A Material Icons ligature name (settings, dark_mode).

mdIcon
: 'logout',
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 pick: (choice: string) => () => voidpick('Signed out'),
}, ]; 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 tree: INinjaAction[]tree;
// A button elsewhere on the page can open a menu directly. page: HTMLElementpage .ParentNode.querySelector<Element>(selectors: string): Element | null (+4 overloads)

Returns the first element that is a descendant of node that matches selectors.

MDN Reference

querySelector
('[data-open="Theme"]')
?.Element.addEventListener<K>(type: K, listener: (this: Element, ev: ElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)

The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.

MDN Reference

addEventListener
('click', () => 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'}));
}

The second button calls ninja.open({parent: 'Theme'}), opening the palette straight into a menu: the pattern for a menu’s own hotkey, or a settings link elsewhere on the page.

The same menus as a flat list, where each child names its menu in parent, behave identically; Actions and menus has both forms side by side.