Theming

One set of actions in three looks. Each look is a class on the element and a few lines of CSS: custom properties for colours and sizes, ::part() for the rest. Nothing reaches into the shadow root any other way.

All three run the same setup; only the class differs:

// The same actions under each look; the look is only the element's class
// (see theme-*.css). `compact` also replaces the footer through its slot.
import '@appulsauce/ninja-keys';
import type {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): 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 ): void { const const commands: readonly [readonly ["Deploy", "rocket_launch", "Releases"], readonly ["Roll back", "undo", "Releases"], readonly ["Open logs", "receipt_long", "Service"], readonly ["Scale up", "add", "Service"], readonly ["Scale down", "remove", "Service"]]commands = [ ['Deploy', 'rocket_launch', 'Releases'], ['Roll back', 'undo', 'Releases'], ['Open logs', 'receipt_long', 'Service'], ['Scale up', 'add', 'Service'], ['Scale down', 'remove', 'Service'], ] as type const = readonly [readonly ["Deploy", "rocket_launch", "Releases"], readonly ["Roll back", "undo", "Releases"], readonly ["Open logs", "receipt_long", "Service"], readonly ["Scale up", "add", "Service"], readonly ["Scale down", "remove", "Service"]]const; 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 commands: readonly [readonly ["Deploy", "rocket_launch", "Releases"], readonly ["Roll back", "undo", "Releases"], readonly ["Open logs", "receipt_long", "Service"], readonly ["Scale up", "add", "Service"], readonly ["Scale down", "remove", "Service"]]commands.
ReadonlyArray<readonly ["Deploy", "rocket_launch", "Releases"] | readonly ["Roll back", "undo", "Releases"] | readonly ["Open logs", "receipt_long", "Service"] | readonly ["Scale up", "add", "Service"] | readonly ["Scale down", "remove", "Service"]>.map<{
    id: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down";
    title: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down";
    mdIcon: "rocket_launch" | "undo" | "receipt_long" | "add" | "remove";
    section: "Releases" | "Service";
    handler: () => void;
}>(callbackfn: (value: readonly ["Deploy", "rocket_launch", "Releases"] | readonly ["Roll back", "undo", "Releases"] | readonly ["Open logs", "receipt_long", "Service"] | readonly ["Scale up", "add", "Service"] | readonly ["Scale down", "remove", "Service"], index: number, array: readonly (readonly ["Deploy", "rocket_launch", "Releases"] | readonly [...] | readonly [...] | readonly [...] | readonly [...])[]) => {
    id: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down";
    title: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down";
    mdIcon: "rocket_launch" | "undo" | "receipt_long" | "add" | "remove";
    section: "Releases" | "Service";
    handler: () => void;
}, thisArg?: any): {
    id: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down";
    title: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down";
    mdIcon: "rocket_launch" | "undo" | "receipt_long" | "add" | "remove";
    section: "Releases" | "Service";
    handler: () => void;
}[]

Calls a defined callback function on each element of an array, and returns an array that contains the results.

@paramcallbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
map
(([title: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down"title, mdIcon: "rocket_launch" | "undo" | "receipt_long" | "add" | "remove"mdIcon, section: "Releases" | "Service"section]) => ({
id: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down"id: title: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down"title, title: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down"title, mdIcon: "rocket_launch" | "undo" | "receipt_long" | "add" | "remove"mdIcon, section: "Releases" | "Service"section, handler: () => voidhandler: () => report: (message: string) => voidreport(`${title: "Deploy" | "Roll back" | "Open logs" | "Scale up" | "Scale down"title} (${ninja: NinjaKeysninja.Element.className: string

The className property of the Element interface gets and sets the value of the class attribute of the specified element.

MDN Reference

className
})`),
})); if (!ninja: NinjaKeysninja.Element.classList: DOMTokenList

The read-only classList property of the Element interface contains a live DOMTokenList collection representing the class attribute of the element. This can then be used to manipulate the class list.

MDN Reference

classList
.DOMTokenList.contains(token: string): boolean

The contains() method of the DOMTokenList interface returns a boolean value — true if the underlying list contains the given token, otherwise false.

MDN Reference

contains
('compact')) return;
// An empty element in the footer slot hides the key hints. const const footer: HTMLDivElementfooter = var document: Document

window.document returns a reference to the document contained in the window.

MDN Reference

document
.Document.createElement<"div">(tagName: "div", options?: ElementCreationOptions): HTMLDivElement (+2 overloads)

In an HTML document, the document.createElement() method creates the HTML element specified by localName, or an HTMLUnknownElement if localName isn't recognized.

MDN Reference

createElement
('div');
const footer: HTMLDivElementfooter.Element.slot: string

The slot property of the Element interface returns the name of the shadow DOM slot the element is inserted in.

MDN Reference

slot
= 'footer';
ninja: NinjaKeysninja.ParentNode.append(...nodes: (Node | string)[]): void

Inserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

MDN Reference

append
(const footer: HTMLDivElementfooter);
}

Terminal

Monospace type, green on black, square key badges. Only custom properties, plus one ::part() rule for the placeholder.

Handlers and events report here.
theme-terminal.css
/* Terminal: a monospace, green-on-black palette with square corners. */
ninja-keys.terminal {
  --ninja-font-family: 'IBM Plex Mono', ui-monospace, monospace;
  --ninja-modal-background: #0b0f0c;
  --ninja-text-color: #b7f5c4;
  --ninja-accent-color: #4ade80;
  --ninja-secondary-text-color: #6b8f75;
  --ninja-secondary-background-color: #16201a;
  --ninja-selected-background: #142b1c;
  --ninja-selected-text-color: #eafff0;
  --ninja-placeholder-color: #4d6b56;
  --ninja-group-text-color: #4ade80;
  --ninja-footer-background: #0b0f0c;
  --ninja-separate-border: 1px solid #1f3326;
  --ninja-overflow-background: rgb(0 0 0 / 60%);
  --ninja-key-border-radius: 0;
  --ninja-modal-shadow: 0 0 0 1px #1f3326, 0 24px 60px rgb(0 0 0 / 60%);
}

ninja-keys.terminal::part(ninja-input)::placeholder {
  font-style: italic;
}

Glass

A frosted panel over a blurred page: --ninja-backdrop-filter blurs what is behind the overlay, and ::part(ninja-action) rounds the rows.

Handlers and events report here.
theme-glass.css
/* Glass: a frosted panel over a blurred page, with rounded rows. */
ninja-keys.glass {
  --ninja-width: 34rem;
  --ninja-top: 15%;
  --ninja-backdrop-filter: blur(8px) saturate(140%);
  --ninja-overflow-background: rgb(120 110 200 / 18%);
  --ninja-modal-background: rgb(255 255 255 / 72%);
  --ninja-selected-background: rgb(110 94 210 / 14%);
  --ninja-footer-background: transparent;
  --ninja-modal-shadow: 0 30px 80px rgb(40 30 90 / 35%);
}

ninja-keys.glass::part(actions-list) {
  padding: 0.5rem;
}

ninja-keys.glass::part(ninja-action) {
  border-radius: 0.5rem;
  border-inline-start: none;
}

Compact

Smaller type and a shorter list from three properties, and no footer: the setup puts an empty element in the footer slot when the element has this class.

Handlers and events report here.
theme-compact.css
/* Compact: smaller type, a shorter list, and no footer (see the slot). */
ninja-keys.compact {
  --ninja-font-size: 15px; /* rows are 0.8125em of this: about 12px */
  --ninja-width: 28rem;
  --ninja-actions-height: 12rem;
  --ninja-icon-size: 1em;
}

The full list of properties and parts, with defaults, is in the API reference; Styling explains how they reach the palette.