@thomasfosterau/components 0.0.0-stage → 0.1.0

package/dist/forms/SearchForm.svelte.d.ts

@@ -0,0 +1,36 @@
+import type { HTMLFormAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLFormAttributes, 'action' | 'method'> {
+    /** Where the search submits — an app path, resolved through the context. */
+    action: string;
+    /**
+     * The query parameter's name.
+     * @defaultValue `'q'`
+     */
+    name?: string | undefined;
+    /**
+     * The query. Bindable.
+     * @defaultValue `''`
+     */
+    value?: string | undefined;
+    /**
+     * Accessible name of the field.
+     * @defaultValue `'Search'`
+     */
+    label?: string | undefined;
+    /**
+     * Text of the submit button.
+     * @defaultValue `'Search'`
+     */
+    submitLabel?: string | undefined;
+    /** Placeholder in the field. */
+    placeholder?: string | undefined;
+    /**
+     * Refuse to submit an empty query.
+     * @defaultValue `true`
+     */
+    required?: boolean | undefined;
+}
+/** The site search box: a `<search>` landmark around a GET form that works without JavaScript. */
+declare const SearchForm: import("svelte").Component<Props, {}, "value">;
+type SearchForm = ReturnType<typeof SearchForm>;
+export default SearchForm;

package/dist/forms/entity-form.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@thomasfosterau/components/entity-form` — the renderer for
+ * `@thomasfosterau/effect-forms-svelte`'s `defineEntityForm` definitions.
+ *
+ * A separate entry point, and the only one that reaches Effect:
+ * `@thomasfosterau/effect-forms-svelte` (and, through it, `effect`) is an
+ * OPTIONAL peer of this package, needed exactly when this entry is imported.
+ * Deliberately NOT re-exported from the `forms` family or the root barrel.
+ *
+ * @module
+ */
+export { default as EntityForm } from './EntityForm.svelte';

package/dist/forms/entity-form.js

@@ -0,0 +1,12 @@
+/**
+ * `@thomasfosterau/components/entity-form` — the renderer for
+ * `@thomasfosterau/effect-forms-svelte`'s `defineEntityForm` definitions.
+ *
+ * A separate entry point, and the only one that reaches Effect:
+ * `@thomasfosterau/effect-forms-svelte` (and, through it, `effect`) is an
+ * OPTIONAL peer of this package, needed exactly when this entry is imported.
+ * Deliberately NOT re-exported from the `forms` family or the root barrel.
+ *
+ * @module
+ */
+export { default as EntityForm } from './EntityForm.svelte';

package/dist/forms/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * forms — the pieces of a form that are not one control: the whole-form error
+ * list, the submit row, a hidden command field, and the site search form.
+ *
+ * Everything field-level lives in `fields/`. The split is by who owns the
+ * message: a `FormErrors` message has no field to attach to, and a
+ * `FormActions` row belongs to the form rather than to anything in it.
+ *
+ * @module
+ */
+export { default as FormActions } from './FormActions.svelte';
+export { default as FormErrors } from './FormErrors.svelte';
+export { default as HiddenField } from './HiddenField.svelte';
+export { default as SearchForm } from './SearchForm.svelte';

package/dist/forms/index.js

@@ -0,0 +1,14 @@
+/**
+ * forms — the pieces of a form that are not one control: the whole-form error
+ * list, the submit row, a hidden command field, and the site search form.
+ *
+ * Everything field-level lives in `fields/`. The split is by who owns the
+ * message: a `FormErrors` message has no field to attach to, and a
+ * `FormActions` row belongs to the form rather than to anything in it.
+ *
+ * @module
+ */
+export { default as FormActions } from './FormActions.svelte';
+export { default as FormErrors } from './FormErrors.svelte';
+export { default as HiddenField } from './HiddenField.svelte';
+export { default as SearchForm } from './SearchForm.svelte';

package/dist/hotkeys/HotkeyBadge.svelte

@@ -0,0 +1,39 @@
+<!-- @component
+A hotkey trigger as daisyUI `kbd` chips: ⌘ K for `'$mod+k'`, G then P for `['g', 'p']`.
+-->
+<!--
+  HotkeyBadge — a hotkey trigger rendered as daisyUI `kbd` chips: ⌘ K for
+  `'$mod+k'`, G then P for `['g', 'p']`. Used by the command palette's rows
+  and by the hotkey help overlay.
+
+  `$mod` resolves to ⌘ / Ctrl only AFTER hydration. The server cannot know the
+  reader's platform, so server-rendered output always shows `controlLabel` and
+  a Mac corrects itself on mount; resolving it during render instead would be
+  a hydration mismatch on every Mac. That is why `apple` is `$state` written
+  from an `$effect` rather than a `$derived`.
+
+  ARIA contract: the chips are `<kbd>` elements, which is the element for user
+  input, and the separator between sequential keys is real text
+  (`thenLabel`) — not a bare "→" — so "G then P" is announced as an
+  instruction rather than as two loose letters. The badge contributes no name
+  of its own: it is read as part of the row it labels.
+-->
+<script lang="ts">import { isApplePlatform, triggerDisplay } from "./match.js";
+let { trigger, commandLabel = "⌘", controlLabel = "Ctrl", thenLabel = "then", class: className, ...rest } = $props();
+const display = $derived(triggerDisplay(trigger));
+// Resolved client-side to avoid an SSR/client hydration mismatch.
+let apple = $state(false);
+$effect(() => {
+	apple = isApplePlatform();
+});
+const modLabel = $derived(apple ? commandLabel : controlLabel);
+</script>
+
+<span {...rest} class={['inline-flex shrink-0 items-center gap-1', className]}>
+  {#each display.keys as key, index (index)}
+    {#if index > 0 && display.sequential}
+      <span class="text-base-content/50 text-xs">{thenLabel}</span>
+    {/if}
+    <kbd class="kbd kbd-sm">{key === '$mod' ? modLabel : key}</kbd>
+  {/each}
+</span>

package/dist/hotkeys/HotkeyBadge.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { HotkeyTrigger } from './types.ts';
+interface Props extends HTMLAttributes<HTMLSpanElement> {
+    /** The trigger to render — a chord (`'$mod+k'`) or a sequence (`['g','p']`). */
+    trigger: HotkeyTrigger;
+    /**
+     * What `$mod` reads as on Apple platforms.
+     * @defaultValue `'⌘'`
+     */
+    commandLabel?: string | undefined;
+    /**
+     * What `$mod` reads as everywhere else, and during server rendering.
+     * @defaultValue `'Ctrl'`
+     */
+    controlLabel?: string | undefined;
+    /**
+     * Read between the keys of a sequence.
+     * @defaultValue `'then'`
+     */
+    thenLabel?: string | undefined;
+}
+/** A hotkey trigger as daisyUI `kbd` chips: ⌘ K for `'$mod+k'`, G then P for `['g', 'p']`. */
+declare const HotkeyBadge: import("svelte").Component<Props, {}, "">;
+type HotkeyBadge = ReturnType<typeof HotkeyBadge>;
+export default HotkeyBadge;

package/dist/hotkeys/HotkeyHelpDialog.svelte

@@ -0,0 +1,68 @@
+<!-- @component
+The `?` overlay listing every hotkey the viewer can press right now, grouped into this page and everywhere.
+-->
+<!--
+  HotkeyHelpDialog — the `?` overlay: every hotkey the current viewer can
+  press right now, grouped into "This page" and "Everywhere", with
+  platform-aware key chips.
+
+  The list is read live from the registry rather than passed in, so it can
+  never drift from what `HotkeyProvider` would actually match: role-gated
+  actions are already absent, and a page's registrations disappear with the
+  page. Opening and closing is the registry's `helpOpen`, which is what a
+  registered action toggles.
+
+  ARIA contract: it is this library's `Dialog`, so bits-ui owns the modal —
+  `aria-modal`, the focus trap, Escape, the focus return — and `title` is the
+  dialog's accessible name. Each section is a `<section>` with a heading, and
+  each hotkey a list item pairing the action's label with its `HotkeyBadge`,
+  so the reading order is "what it does, then what to press".
+-->
+<script lang="ts">import Dialog from "../feedback/Dialog.svelte";
+import { getHotkeyRegistry } from "./context.svelte.js";
+import HotkeyBadge from "./HotkeyBadge.svelte";
+let { title = "Keyboard shortcuts", closeLabel = "Close", emptyLabel = "No keyboard shortcuts are available on this page.", groupLabels = {
+	page: "This page",
+	global: "Everywhere"
+}, commandLabel, controlLabel, thenLabel } = $props();
+const registry = getHotkeyRegistry();
+const sections = $derived([{
+	heading: groupLabels.page,
+	entries: registry.hotkeys.filter((entry) => entry.scope === "page")
+}, {
+	heading: groupLabels.global,
+	entries: registry.hotkeys.filter((entry) => entry.scope === "global")
+}].filter((section) => section.entries.length > 0));
+</script>
+
+{#snippet hotkeyRow(entry: RegisteredAction)}
+  <li class="flex items-center justify-between gap-4 py-1.5">
+    <span class="text-base-content text-sm">{entry.action.label}</span>
+    {#if entry.action.trigger !== undefined}
+      <HotkeyBadge trigger={entry.action.trigger} {commandLabel} {controlLabel} {thenLabel} />
+    {/if}
+  </li>
+{/snippet}
+
+<Dialog
+  bind:open={() => registry.helpOpen, (open) => (registry.helpOpen = open)}
+  {title}
+  {closeLabel}
+>
+  {#if registry.hotkeys.length === 0}
+    <p class="text-base-content/70 text-sm leading-6">{emptyLabel}</p>
+  {:else}
+    {#each sections as section (section.heading)}
+      <section class="mt-4 first:mt-0">
+        <h3 class="text-base-content/70 text-xs font-semibold tracking-wide uppercase">
+          {section.heading}
+        </h3>
+        <ul class="divide-base-300 mt-2 divide-y">
+          {#each section.entries as entry (entry.action.id)}
+            {@render hotkeyRow(entry)}
+          {/each}
+        </ul>
+      </section>
+    {/each}
+  {/if}
+</Dialog>

package/dist/hotkeys/HotkeyHelpDialog.svelte.d.ts

@@ -0,0 +1,35 @@
+interface Props {
+    /**
+     * The dialog's accessible name.
+     * @defaultValue `'Keyboard shortcuts'`
+     */
+    title?: string | undefined;
+    /**
+     * Accessible name of the corner close button.
+     * @defaultValue `'Close'`
+     */
+    closeLabel?: string | undefined;
+    /**
+     * Shown when nothing with a trigger is registered.
+     * @defaultValue `'No keyboard shortcuts are available on this page.'`
+     */
+    emptyLabel?: string | undefined;
+    /**
+     * Section headings, in render order.
+     * @defaultValue `{ page: 'This page', global: 'Everywhere' }`
+     */
+    groupLabels?: {
+        page: string;
+        global: string;
+    } | undefined;
+    /** What `$mod` reads as on Apple platforms. */
+    commandLabel?: string | undefined;
+    /** What `$mod` reads as everywhere else. */
+    controlLabel?: string | undefined;
+    /** Read between the keys of a sequence. */
+    thenLabel?: string | undefined;
+}
+/** The `?` overlay listing every hotkey the viewer can press right now, grouped into this page and everywhere. */
+declare const HotkeyHelpDialog: import("svelte").Component<Props, {}, "">;
+type HotkeyHelpDialog = ReturnType<typeof HotkeyHelpDialog>;
+export default HotkeyHelpDialog;

package/dist/hotkeys/HotkeyProvider.svelte

@@ -0,0 +1,92 @@
+<!-- @component
+The single global `keydown` listener that drives the hotkey registry; hotkeys never fire while the reader is typing.
+-->
+<!--
+  HotkeyProvider — the single global `keydown` listener that drives the hotkey
+  registry. Owns the sequence buffer (for `g p`-style triggers) and enforces
+  the editable-target guard, so hotkeys never fire while the reader is typing
+  in a form field or a rich-text editor.
+
+  Render once, from the root layout, inside the component that called
+  `createHotkeyRegistry()`. It renders nothing.
+
+  ARIA contract: none of its own — it has no markup. What it owes assistive
+  technology is negative: it must never steal a keystroke from a control that
+  needs it, which is what the editable-target guard and the
+  "`paletteOpen` / `helpOpen` suppress everything but `allowInEditable`" rule
+  are for. bits-ui owns keyboard interaction inside its own dialogs.
+
+  Not on a bits-ui primitive because there is no primitive for this: it is a
+  document-level key router over an app-owned registry, not a widget.
+-->
+<script lang="ts">import { getHotkeyRegistry } from "./context.svelte.js";
+import { SEQUENCE_TIMEOUT_MS, hasChordModifier, isEditableTarget, isSequenceKey, matchChord, matchSequence } from "./match.js";
+const registry = getHotkeyRegistry();
+let sequenceBuffer = [];
+let sequenceTimer;
+function clearSequence() {
+	sequenceBuffer = [];
+	if (sequenceTimer !== undefined) clearTimeout(sequenceTimer);
+	sequenceTimer = undefined;
+}
+function armSequenceTimeout() {
+	if (sequenceTimer !== undefined) clearTimeout(sequenceTimer);
+	sequenceTimer = setTimeout(clearSequence, SEQUENCE_TIMEOUT_MS);
+}
+function activate(action, event) {
+	event.preventDefault();
+	clearSequence();
+	void action.run();
+}
+// The keyboard event router. The chord / sequence / suppression branching is
+// inherently branchy; splitting it would scatter the buffer state machine
+// across helpers and hurt readability more than the branch count does.
+function onKeydown(event) {
+	// While a hotkey-owned dialog is open, or focus sits in an editable
+	// element, only `allowInEditable` actions (the palette toggle) may fire —
+	// bits-ui owns keyboard interaction inside its dialogs, and typing must
+	// never trigger actions.
+	const suppressed = registry.paletteOpen || registry.helpOpen || isEditableTarget(event.target);
+	const actions = suppressed ? registry.active.filter((entry) => entry.action.allowInEditable) : registry.active;
+	if (hasChordModifier(event)) {
+		const action = matchChord(event, actions);
+		if (action !== undefined) activate(action, event);
+		return;
+	}
+	// Plain keys: ignore non-printable keys (Escape, arrows, bare modifiers,
+	// F-keys) entirely — they neither fire nor disturb a pending sequence.
+	if (!isSequenceKey(event)) return;
+	if (suppressed) {
+		clearSequence();
+		return;
+	}
+	// Try extending the pending sequence first, then restarting from this key
+	// alone, so a stray prefix never swallows a fresh trigger.
+	let hit;
+	for (const candidate of [[...sequenceBuffer, event.key], [event.key]]) {
+		const match = matchSequence(candidate, actions);
+		if (match.exact !== undefined || match.isPrefix) {
+			hit = {
+				candidate,
+				match
+			};
+			break;
+		}
+	}
+	if (hit === undefined) {
+		clearSequence();
+		return;
+	}
+	if (hit.match.exact !== undefined) {
+		activate(hit.match.exact, event);
+		return;
+	}
+	sequenceBuffer = hit.candidate;
+	armSequenceTimeout();
+}
+$effect(() => () => {
+	if (sequenceTimer !== undefined) clearTimeout(sequenceTimer);
+});
+</script>
+
+<svelte:window onkeydown={onKeydown} />

package/dist/hotkeys/HotkeyProvider.svelte.d.ts

@@ -0,0 +1,4 @@
+/** The single global `keydown` listener that drives the hotkey registry; hotkeys never fire while the reader is typing. */
+declare const HotkeyProvider: import("svelte").Component<Record<string, never>, {}, "">;
+type HotkeyProvider = ReturnType<typeof HotkeyProvider>;
+export default HotkeyProvider;

package/dist/hotkeys/context.svelte.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Svelte context plumbing for the hotkey registry, plus the declarative
+ * `registerHotkeys` helper that pages and shared page components call to
+ * contribute page-scoped actions.
+ *
+ * @module
+ */
+import { HotkeyRegistry, type HotkeyRegistryOptions } from './registry.svelte.ts';
+import type { CommandAction, HotkeyScope } from './types.ts';
+/** Raised by {@link getHotkeyRegistry} when no registry has been created above. */
+export declare class HotkeyRegistryMissing extends Error {
+    readonly name = "HotkeyRegistryMissing";
+}
+/**
+ * Create the registry and place it in context. Call once, from the root
+ * layout, during component initialisation.
+ */
+export declare function createHotkeyRegistry(options: HotkeyRegistryOptions): HotkeyRegistry;
+/**
+ * Read the registry from context, or `undefined` when none was created.
+ *
+ * This is the seam that lets `CommandPalette` work in an app that never
+ * mounted a registry: it falls back to its `items` prop. Components that
+ * cannot work without one (`HotkeyProvider`, `HotkeyHelpDialog`) call
+ * {@link getHotkeyRegistry} instead, so the failure is loud.
+ */
+export declare function tryGetHotkeyRegistry(): HotkeyRegistry | undefined;
+/** Read the registry from context. Throws when none was created. */
+export declare function getHotkeyRegistry(): HotkeyRegistry;
+/**
+ * Declaratively register actions for the lifetime of the calling component.
+ * Registration is reactive: the `actions` thunk re-runs when its dependencies
+ * change (a resource's `canEdit` resolving, say), replacing the previous
+ * registration.
+ *
+ * ```svelte
+ * registerHotkeys(() =>
+ *   post.canEdit
+ *     ? [{ id: 'post.edit', label: 'Edit post', trigger: 'e', group: 'actions',
+ *          run: () => goto(`/posts/${post.id}/edit`) }]
+ *     : [],
+ * );
+ * ```
+ */
+export declare function registerHotkeys(actions: () => readonly CommandAction[], options?: {
+    scope?: HotkeyScope | undefined;
+}): void;

package/dist/hotkeys/context.svelte.js

@@ -0,0 +1,72 @@
+/**
+ * Svelte context plumbing for the hotkey registry, plus the declarative
+ * `registerHotkeys` helper that pages and shared page components call to
+ * contribute page-scoped actions.
+ *
+ * @module
+ */
+import { getContext, setContext, untrack } from 'svelte';
+import { HotkeyRegistry } from "./registry.svelte.js";
+const CONTEXT_KEY = Symbol('@thomasfosterau/components:hotkey-registry');
+/** Raised by {@link getHotkeyRegistry} when no registry has been created above. */
+export class HotkeyRegistryMissing extends Error {
+    name = 'HotkeyRegistryMissing';
+}
+/**
+ * Create the registry and place it in context. Call once, from the root
+ * layout, during component initialisation.
+ */
+export function createHotkeyRegistry(options) {
+    const registry = new HotkeyRegistry(options);
+    setContext(CONTEXT_KEY, registry);
+    return registry;
+}
+/**
+ * Read the registry from context, or `undefined` when none was created.
+ *
+ * This is the seam that lets `CommandPalette` work in an app that never
+ * mounted a registry: it falls back to its `items` prop. Components that
+ * cannot work without one (`HotkeyProvider`, `HotkeyHelpDialog`) call
+ * {@link getHotkeyRegistry} instead, so the failure is loud.
+ */
+export function tryGetHotkeyRegistry() {
+    return getContext(CONTEXT_KEY);
+}
+/** Read the registry from context. Throws when none was created. */
+export function getHotkeyRegistry() {
+    const registry = tryGetHotkeyRegistry();
+    if (!registry) {
+        throw new HotkeyRegistryMissing('HotkeyRegistry not found in context. ' +
+            'createHotkeyRegistry() must be called by an ancestor (the root layout).');
+    }
+    return registry;
+}
+/**
+ * Declaratively register actions for the lifetime of the calling component.
+ * Registration is reactive: the `actions` thunk re-runs when its dependencies
+ * change (a resource's `canEdit` resolving, say), replacing the previous
+ * registration.
+ *
+ * ```svelte
+ * registerHotkeys(() =>
+ *   post.canEdit
+ *     ? [{ id: 'post.edit', label: 'Edit post', trigger: 'e', group: 'actions',
+ *          run: () => goto(`/posts/${post.id}/edit`) }]
+ *     : [],
+ * );
+ * ```
+ */
+export function registerHotkeys(actions, options = {}) {
+    const registry = getHotkeyRegistry();
+    const scope = options.scope ?? 'page';
+    $effect(() => {
+        // Track only the `actions` thunk's own reactive inputs. `register()`
+        // reads *and* writes the registry's `#registrations` `$state`; left
+        // tracked, that read-then-write makes the effect re-trigger itself
+        // forever (`effect_update_depth_exceeded`, which crashed hydration on
+        // every page). `untrack` isolates the register call so the effect re-runs
+        // only when `actions()` changes, not when the array it writes does.
+        const batch = actions();
+        return untrack(() => registry.register(scope, batch));
+    });
+}

package/dist/hotkeys/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * hotkeys — the registry that answers "what can the viewer do right now", and
+ * the two surfaces that read it back.
+ *
+ * An app creates one registry in its root layout (`createHotkeyRegistry`),
+ * renders `HotkeyProvider` once to mount the key listener, and registers
+ * actions from anywhere below with `registerHotkeys` — global ones from the
+ * layout, page ones from the page, torn down when it unmounts. `search/`'s
+ * `CommandPalette` and `HotkeyHelpDialog` then list exactly what is live.
+ *
+ * Everything user-facing is a prop: the registry stores the labels the app
+ * registered, and the two components take their own chrome copy
+ * (`title`, `closeLabel`, `commandLabel`, …) with English defaults.
+ *
+ * @module
+ */
+export { HotkeyRegistryMissing, createHotkeyRegistry, getHotkeyRegistry, registerHotkeys, tryGetHotkeyRegistry, } from './context.svelte.ts';
+export { HotkeyRegistry, type HotkeyRegistryOptions } from './registry.svelte.ts';
+export { default as HotkeyBadge } from './HotkeyBadge.svelte';
+export { default as HotkeyHelpDialog } from './HotkeyHelpDialog.svelte';
+export { default as HotkeyProvider } from './HotkeyProvider.svelte';
+export { SEQUENCE_TIMEOUT_MS, hasChordModifier, isApplePlatform, isEditableTarget, isSequenceKey, matchChord, matchSequence, triggerDisplay, type SequenceMatch, type TriggerDisplay, } from './match.ts';
+export type { CommandAction, CommandActionGroup, HotkeyChord, HotkeyScope, HotkeySequence, HotkeyTrigger, RegisteredAction, } from './types.ts';

package/dist/hotkeys/index.js

@@ -0,0 +1,22 @@
+/**
+ * hotkeys — the registry that answers "what can the viewer do right now", and
+ * the two surfaces that read it back.
+ *
+ * An app creates one registry in its root layout (`createHotkeyRegistry`),
+ * renders `HotkeyProvider` once to mount the key listener, and registers
+ * actions from anywhere below with `registerHotkeys` — global ones from the
+ * layout, page ones from the page, torn down when it unmounts. `search/`'s
+ * `CommandPalette` and `HotkeyHelpDialog` then list exactly what is live.
+ *
+ * Everything user-facing is a prop: the registry stores the labels the app
+ * registered, and the two components take their own chrome copy
+ * (`title`, `closeLabel`, `commandLabel`, …) with English defaults.
+ *
+ * @module
+ */
+export { HotkeyRegistryMissing, createHotkeyRegistry, getHotkeyRegistry, registerHotkeys, tryGetHotkeyRegistry, } from "./context.svelte.js";
+export { HotkeyRegistry } from "./registry.svelte.js";
+export { default as HotkeyBadge } from './HotkeyBadge.svelte';
+export { default as HotkeyHelpDialog } from './HotkeyHelpDialog.svelte';
+export { default as HotkeyProvider } from './HotkeyProvider.svelte';
+export { SEQUENCE_TIMEOUT_MS, hasChordModifier, isApplePlatform, isEditableTarget, isSequenceKey, matchChord, matchSequence, triggerDisplay, } from "./match.js";

package/dist/hotkeys/match.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure key-matching helpers for the hotkey registry. No Svelte, no DOM
+ * mutation — just functions over `KeyboardEvent`s, trigger grammars and the
+ * sequence buffer, so the matching rules stay testable and `HotkeyProvider`
+ * stays thin.
+ *
+ * Trigger model:
+ *
+ * - **Modifier chords** (`'$mod+k'`) — held together. `$mod` is ⌘ on macOS
+ *   and Ctrl elsewhere. Matched on their own; never buffered.
+ * - **Plain keys / sequences** (`'e'`, `'/'`, `['g', 'p']`) — pressed in
+ *   order with no modifier held. A plain single key is just a sequence of
+ *   length one, so matching is uniform.
+ *
+ * @module
+ */
+import type { CommandAction, HotkeyTrigger, RegisteredAction } from './types.ts';
+/** Sequence buffer entries expire after this many milliseconds. */
+export declare const SEQUENCE_TIMEOUT_MS = 1000;
+/** Whether the runtime platform treats `$mod` as ⌘ (macOS / iOS). */
+export declare function isApplePlatform(): boolean;
+/**
+ * Whether a keyboard event's target is an editable surface — a form field or
+ * a contenteditable region (which covers a rich-text editor's root). Hotkeys
+ * without `allowInEditable` stay inert there so typing never fires actions.
+ */
+export declare function isEditableTarget(target: EventTarget | null): boolean;
+/** Whether an event carries a chord modifier (⌘ / Ctrl / Alt). */
+export declare function hasChordModifier(event: KeyboardEvent): boolean;
+/**
+ * Whether an event's key can participate in a sequence: a single printable
+ * character pressed without chord modifiers.
+ */
+export declare function isSequenceKey(event: KeyboardEvent): boolean;
+/**
+ * Find the action whose modifier chord matches the event. `actions` must
+ * already be in precedence order (page before global, later registrations
+ * first).
+ */
+export declare function matchChord(event: KeyboardEvent, actions: readonly RegisteredAction[]): CommandAction | undefined;
+/** The result of `matchSequence`: the action a key buffer completes, and whether it could still grow into another. */
+export interface SequenceMatch {
+    /** The action whose sequence the buffer completes, if any. */
+    exact: CommandAction | undefined;
+    /** Whether the buffer is a strict prefix of at least one sequence. */
+    isPrefix: boolean;
+}
+/**
+ * Match a candidate key buffer against the active plain-key triggers.
+ * `actions` must already be in precedence order.
+ */
+export declare function matchSequence(buffer: readonly string[], actions: readonly RegisteredAction[]): SequenceMatch;
+/** A trigger split into the keys a `HotkeyBadge` renders, and whether they are pressed in turn or together. */
+export interface TriggerDisplay {
+    /**
+     * Keys to render as `<kbd>` chips, in order. `'$mod'` is left un-resolved
+     * so the rendering component can substitute the platform-appropriate
+     * label.
+     */
+    keys: readonly string[];
+    /** True when keys are pressed one after another rather than held together. */
+    sequential: boolean;
+}
+/** Project a trigger into its display form for help overlays and badges. */
+export declare function triggerDisplay(trigger: HotkeyTrigger): TriggerDisplay;