@thomasfosterau/components 0.0.0 → 0.2.0

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

@@ -0,0 +1,66 @@
+import { createForm, type EntityFormDefinition, type WidgetEntry } from '@thomasfosterau/effect-forms-svelte';
+import type { HTMLFormAttributes } from 'svelte/elements';
+type Store = ReturnType<typeof createForm>;
+/** The props a widget entry receives: its definition's `props()` shape, owned by the form library. */
+type WidgetProps = ReturnType<WidgetEntry['props']>;
+interface Props extends Omit<HTMLFormAttributes, 'action' | 'method' | 'children'> {
+    /** The form definition from `defineEntityForm`. */
+    definition: EntityFormDefinition;
+    /** Which of the definition’s entry sets to render. */
+    mode: 'create' | 'update';
+    /** Where Cancel goes. Omitted renders no cancel link. */
+    cancelHref?: string | undefined;
+    /** A named action (`?/addItem`). Omitted posts to the page's default action. */
+    action?: string | undefined;
+    /**
+     * All-string initial values: an edit page's current values, or a create page's pre-filled FK.
+     * @defaultValue `{}`
+     */
+    initial?: Readonly<Record<string, string>> | undefined;
+    /**
+     * Initial rows per `rows` widget key (a contributor list's current credits).
+     * @defaultValue `{}`
+     */
+    initialRows?: Readonly<Record<string, readonly unknown[]>> | undefined;
+    /**
+     * Render-time extra props per widget key (a picker's load-resolved `options`).
+     * @defaultValue `{}`
+     */
+    fieldProps?: Readonly<Record<string, Readonly<WidgetProps>>> | undefined;
+    /**
+     * The spreadable `<form>` attributes for this store.
+     * @defaultValue the store's own `form.props`
+     */
+    enhance?: ((form: Store) => Store['props']) | undefined;
+    /**
+     * Text of the cancel link.
+     * @defaultValue `'Cancel'`
+     */
+    cancelLabel?: string | undefined;
+    /**
+     * Submit button text while the form is submitting.
+     * @defaultValue `'Saving…'`
+     */
+    pendingLabel?: string | undefined;
+    /**
+     * The empty option of a select entry.
+     * @defaultValue `'Choose…'`
+     */
+    selectPlaceholder?: string | undefined;
+    /**
+     * Read out after a required field’s label.
+     * @defaultValue `'(required)'` (from `FormField`)
+     */
+    requiredLabel?: string | undefined;
+    /**
+     * Form-level messages from outside the store — a server action's failure
+     * message that carries no form state (`page.form?.message`, wrapped in an
+     * array). Rendered in the same `FormErrors` block as the store's own root
+     * errors, after them, one `role="alert"` each. The text is shown as given.
+     */
+    messages?: readonly string[] | undefined;
+}
+/** Renders an `@thomasfosterau/effect-forms-svelte` `defineEntityForm` definition through this library’s field primitives. */
+declare const EntityForm: import("svelte").Component<Props, {}, "">;
+type EntityForm = ReturnType<typeof EntityForm>;
+export default EntityForm;

package/dist/forms/FormActions.svelte

@@ -0,0 +1,29 @@
+<!-- @component
+The submit and cancel row that closes a form.
+-->
+<!--
+  FormActions — the submit / cancel row that closes a form.
+
+  ARIA contract: the submit control is a real `type="submit"` button, so
+  Enter in any field still submits the form. While `pending` it is disabled
+  AND `aria-busy="true"` (disabled alone says "you may not"; busy says "it is
+  already happening") and its label swaps to `pendingLabel` — the button
+  keeps a name throughout, which a spinner-only state would not.
+
+  Cancel is a LINK, not a button: it navigates away, and a reader should be
+  able to see where to before they commit to it.
+-->
+<script lang="ts">import Button from "../ui/Button.svelte";
+import LinkButton from "../ui/LinkButton.svelte";
+let { submitLabel = "Save", pendingLabel = "Saving…", pending = false, disabled = false, tone = "primary", cancelHref, cancelLabel = "Cancel", children, class: className, ...rest } = $props();
+</script>
+
+<div {...rest} class={['flex flex-wrap items-center gap-3 pt-2', className]}>
+  <Button type="submit" {tone} loading={pending} {disabled}>
+    {pending ? pendingLabel : submitLabel}
+  </Button>
+  {#if cancelHref !== undefined}
+    <LinkButton href={cancelHref} variant="ghost" disabled={pending}>{cancelLabel}</LinkButton>
+  {/if}
+  {@render children?.()}
+</div>

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

@@ -0,0 +1,37 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { Tone } from '../ui/tones.ts';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * Idle label of the submit button.
+     * @defaultValue `'Save'`
+     */
+    submitLabel?: string | undefined;
+    /**
+     * Label while the form is in flight.
+     * @defaultValue `'Saving…'`
+     */
+    pendingLabel?: string | undefined;
+    /** The form is being submitted. */
+    pending?: boolean | undefined;
+    /** Extra disable condition — a required picker still empty, say. */
+    disabled?: boolean | undefined;
+    /**
+     * Colour of the submit button.
+     * @defaultValue `'primary'`
+     */
+    tone?: Tone | undefined;
+    /** Where cancel goes. Omit for a form with no cancel affordance. */
+    cancelHref?: string | undefined;
+    /**
+     * Text of the cancel control.
+     * @defaultValue `'Cancel'`
+     */
+    cancelLabel?: string | undefined;
+    /** Extra controls, rendered after cancel. */
+    children?: Snippet<[]> | undefined;
+}
+/** The submit and cancel row that closes a form. */
+declare const FormActions: import("svelte").Component<Props, {}, "">;
+type FormActions = ReturnType<typeof FormActions>;
+export default FormActions;

package/dist/forms/FormErrors.svelte

@@ -0,0 +1,21 @@
+<!-- @component
+The whole-form messages that belong to the submission rather than to any one field.
+-->
+<!--
+  FormErrors — the whole-form messages: the ones that belong to the
+  submission rather than to any one field ("That name is already taken",
+  "Your session expired").
+
+  ARIA contract: one `Alert` per message, each `live="assertive"`. Assertive
+  is right here and would be wrong for page furniture: these appear in
+  response to something the reader just did, and the next thing they will do
+  is try again. Nothing is rendered while the list is empty, so the alert is
+  inserted — and therefore announced — exactly when there is something to say.
+-->
+<script lang="ts">import Alert from "../ui/Alert.svelte";
+let { messages, tone = "error", class: className } = $props();
+</script>
+
+{#each messages ?? [] as message, index (index)}
+  <Alert {tone} live="assertive" class={className}>{message}</Alert>
+{/each}

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

@@ -0,0 +1,16 @@
+import type { StatusTone } from '../ui/tones.ts';
+interface Props {
+    /** Whole-form messages. */
+    messages?: readonly string[] | undefined;
+    /**
+     * Colour of the alert.
+     * @defaultValue `'error'`
+     */
+    tone?: StatusTone | undefined;
+    /** Extra classes, merged last. */
+    class?: string | undefined;
+}
+/** The whole-form messages that belong to the submission rather than to any one field. */
+declare const FormErrors: import("svelte").Component<Props, {}, "">;
+type FormErrors = ReturnType<typeof FormErrors>;
+export default FormErrors;

package/dist/forms/HiddenField.svelte

@@ -0,0 +1,22 @@
+<!-- @component
+A fixed value posted with the form and never edited.
+-->
+<!--
+  HiddenField — a fixed value posted with the form and never edited: the
+  parent id a create form hangs its row off, a command discriminator, a
+  redirect target.
+
+  It is a component rather than a bare `<input type="hidden">` so that a form
+  described declaratively (a list of fields) can include one without dropping
+  out of that description, and so the value passes through one place that
+  stringifies it.
+
+  ARIA contract: none, deliberately — a hidden input is not in the
+  accessibility tree, and anything a reader needs to KNOW about does not
+  belong in one.
+-->
+<script lang="ts">let { name, value, ...rest } = $props();
+export {};
+</script>
+
+<input {...rest} type="hidden" {name} value={String(value)} />

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

@@ -0,0 +1,11 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLInputAttributes, 'type' | 'value'> {
+    /** The posted field name. */
+    name: string;
+    /** The posted value. */
+    value: string | number;
+}
+/** A fixed value posted with the form and never edited. */
+declare const HiddenField: import("svelte").Component<Props, {}, "">;
+type HiddenField = ReturnType<typeof HiddenField>;
+export default HiddenField;

package/dist/forms/SearchForm.svelte

@@ -0,0 +1,43 @@
+<!-- @component
+The site search box: a `<search>` landmark around a GET form that works without JavaScript.
+-->
+<!--
+  SearchForm — the site search box: a `<search>` landmark around a GET form
+  that works with no JavaScript at all.
+
+  Method GET on purpose. A search is a request for a REPRESENTATION, so its
+  result should be a URL people can bookmark, share and go back to; a POST
+  would make the results page un-linkable and re-submit on refresh.
+
+  ARIA contract: `<search>` is the landmark (so "go to search" reaches it
+  without an `aria-label` per instance), the visible label is visually hidden
+  but real — `for`/`id`, not a `placeholder`, which disappears the moment
+  someone types and is not a name at all — and the submit button carries its
+  own text rather than an icon alone.
+
+  `action` resolves through the components context, so an app with a base path
+  or a locale prefix gets the right URL without this file knowing about either.
+-->
+<script lang="ts">import { getComponentsContext } from "../context.svelte.js";
+import Button from "../ui/Button.svelte";
+let { action, name = "q", value = $bindable(""), label = "Search", submitLabel = "Search", placeholder, required = true, class: className, ...rest } = $props();
+const context = getComponentsContext();
+const resolved = $derived(context.href(action));
+const uid = $props.id();
+</script>
+
+<search class={['block', className]}>
+  <form {...rest} action={resolved} method="get" class="join w-full">
+    <label class="sr-only" for={uid}>{label}</label>
+    <input
+      id={uid}
+      class="input join-item w-full"
+      type="search"
+      {name}
+      {placeholder}
+      {required}
+      bind:value
+    />
+    <Button type="submit" tone="primary" class="join-item">{submitLabel}</Button>
+  </form>
+</search>

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;