ShortcutRegistry

One keyboard-shortcut system for an app page.

tsx

import { ShortcutRegistry } from "@sdxc/ui/app";

Usage

Holds every shortcut on a page and answers keystrokes: the candidates a keystroke completes are ranked by layer (topmost open modal, then open sheets, then the page), then priority, then the latest registered, and the first that runs without declining claims the key.

Signature

typescript

new ShortcutRegistry(options?: Shortcuts.Options)

Parameters

Parameter	Type	Required	Description
`options`	`Shortcuts.Options`	No	How long a sequence waits for its next key.

Methods

Method	Description
`register(registration: Shortcuts.Registration): () => void`	Adds a shortcut until `signal` aborts or the returned function runs.
`list(document?: Document): Shortcuts.Entry[]`	Every labelled shortcut, registered or declared in `document`, in registration then document order, one row per distinct keys and label.
`listen(document: Document, signal?: AbortSignal): void`	Answers keystrokes on `document` until `signal` aborts, in the bubble phase so a handler nearer the target that claims a key keeps it.
`handle(event: KeyboardEvent): boolean`	Runs the shortcut a keystroke completes, default-preventing the keystroke when one ran or a sequence is waiting for its next key.

Examples

tsx

let registry = shortcutRegistry(document);
registry.register({ keys: "g m", label: "Go to Monitors", group: "Navigation", run: () => location.assign("/monitors"), signal });

The events, constants and types its module publishes, each imported from @sdxc/ui/app too.

Constant

SHORTCUT_ATTRIBUTE

Attribute a link, button or field declares its shortcut on, as "g m", "c" or "s, /" (comma-separated alternatives). Pressing it clicks the element, or focuses it when it is a field.

typescript

const SHORTCUT_ATTRIBUTE = "data-shortcut"

Constant

SHORTCUT_LABEL_ATTRIBUTE

Attribute naming a declared shortcut in the help sheet; an empty value keeps it unlisted.

typescript

const SHORTCUT_LABEL_ATTRIBUTE = "data-shortcut-label"

Constant

SHORTCUT_GROUP_ATTRIBUTE

Attribute naming the help-sheet group of every shortcut declared on or inside its element.

typescript

const SHORTCUT_GROUP_ATTRIBUTE = "data-shortcut-group"

Constant

SHORTCUT_SCOPE_ATTRIBUTE

Attribute marking an element as a shortcut layer, "sheet" or "modal", for a panel built from something other than <dialog> or [popover]. The layer counts as open while it and its ancestors are free of hidden and inert.

typescript

const SHORTCUT_SCOPE_ATTRIBUTE = "data-shortcut-scope"

Constant

SHORTCUT_SEQUENCE_TIMEOUT_MS

Milliseconds a sequence waits for its next key before the keys typed so far are dropped.

typescript

const SHORTCUT_SEQUENCE_TIMEOUT_MS = 1200

Constant

ESCAPE_PRIORITY

Priorities for the Escape ladder: with every handler declining when it has nothing to undo, one press clears the selection, the next clears the filters, and only then does a panel close.

typescript

const ESCAPE_PRIORITY = { selection: 30, filters: 20, close: 10 } as const

Function

shortcutAlternatives

Splits keys into its alternatives: an array as given, a string at its commas. A lone "," stays the comma key.

typescript

shortcutAlternatives(keys: string | readonly string[]): string[]

Parameter	Type	Required	Description
`keys`	`string \| readonly string[]`	Yes	The keys as registered.

Function

shortcutGlyphs

The key caps a hint prints for one alternative, sequence steps in press order, with arrows and the space bar as their symbols. A letter prints as its cap, upper-cased, and a capital letter, which only Shift types, prints with the Shift cap before it.

typescript

shortcutGlyphs(alternative: string, apple: boolean): string[]

Parameter	Type	Required	Description
`alternative`	`string`	Yes	A combo or sequence, e.g. `"g m"`, `"mod+k"`, `"arrowdown"`.
`apple`	`boolean`	Yes	Whether the reader's keyboard carries the Apple modifier glyphs.

tsx

shortcutGlyphs("g m", true) // ["G", "M"]

Function

isApplePlatform

Whether the reader's keyboard prints the Apple modifier glyphs, read from the platform the browser reports. On a server it answers true, the glyphs most readers see.

typescript

isApplePlatform(): boolean

Function