@ruckc/truss-ui 1.2.0 → 1.4.0

package/README.md

@@ -7,7 +7,7 @@ A **Svelte 5 / SvelteKit design system** that blends Material 3's tonal surfaces
 
 **Docs and live demo: <https://truss.ruck.io>**
 
-- **69 components**: forms and pickers (no native `<select>`, date or time inputs), data tables with virtual scrolling, trees, menus, dialogs, an application shell and more.
+- **90+ components**: forms and pickers (no native `<select>`, date or time inputs), data tables with virtual scrolling, trees, menus, dialogs, an application shell and more.
 - **Zero runtime dependencies** in the core (peer: `svelte`). Fonts are bundled and served by *your* build.
 - **Accessible by construction**: names, ARIA, focus and complete keyboard maps, audited for every combination of every component's options.
 - **Themeable**: one set of `--tr-*` CSS tokens, light and dark, drives everything, including charts, graphs and maps.
@@ -71,8 +71,11 @@ npm run check        # svelte-check
 npm run package:all  # build all four packages into their dist/ folders
 npm run build        # regenerate the API docs and prerender the site (adapter-static)
 npm test             # the full browser suite (starts its own dev server)
+npm run test:coverage  # the suite with V8 coverage; the report lands in coverage/report/index.html
 ```
 
+Coverage is collected from the browser (V8, no instrumented build) and mapped back to the `.svelte`/`.ts` sources; `coverage/report/` also holds `lcov.info` and `coverage-summary.json`. To measure a subset, run `COVERAGE=1 npx playwright test tests/misc.spec.ts` and then `npm run coverage:report`. In CI the browser suite is split into 6 parallel shards; a final job merges their test reports and coverage into one HTML report and a summary on the run page (report only, no thresholds).
+
 Repository layout:
 
 ```
@@ -99,6 +102,8 @@ Every push to `main` that passes CI is released automatically: the version is wo
 
 Commits that don't follow the format (no `type:` prefix) don't trigger a release on their own. Publishing uses npm [trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC from the `ci.yml` workflow), so no npm token is stored anywhere. Each package's trusted publisher on npmjs.com must be for workflow `ci.yml` with the **`npm publish`** action allowed (the default is only `npm stage publish`, which npm rejects with `403 OIDC permission denied for this action`).
 
+A new version can take several minutes to become installable after the release job publishes it, so an install that returns 404 right after a release should be retried rather than republished.
+
 ## Licence
 
 MIT © Curtis Ruck. The bundled Inter and JetBrains Mono fonts are under the SIL Open Font License 1.1.

package/dist/commands.svelte.d.ts

@@ -0,0 +1,41 @@
+import type { IconSource } from './types.js';
+export type Command = {
+    /** Unique id. Registering the same id again replaces the earlier command. */
+    id: string;
+    label: string;
+    /** Heading the command is listed under in the palette and the shortcut sheet. */
+    group?: string;
+    icon?: IconSource;
+    /** Extra words the palette's search matches. */
+    keywords?: string[];
+    /** Bound globally while registered: `mod+shift+n`, `g h`... */
+    shortcut?: string;
+    /** Return false to hide the command from the palette and pause its shortcut. */
+    when?: () => boolean;
+    /** Let the shortcut fire while the user is typing in a field. */
+    allowInInput?: boolean;
+    run: () => void | Promise<void>;
+};
+/**
+ * Registry behind `<CommandPalette>` and `<ShortcutSheet>`. Registration is reactive, so palettes update as screens
+ * register and unregister their own commands.
+ */
+declare class CommandStore {
+    #private;
+    /** Every registered command. */
+    get all(): Command[];
+    /** The commands whose `when` currently allows them. */
+    get available(): Command[];
+    register(cmd: Command): () => void;
+    /** Run a command by id (regardless of `when`). Returns false if there is none. */
+    run(id: string): Promise<boolean>;
+}
+export declare const commands: CommandStore;
+/** Register a command; returns the function that unregisters it (call it from `onDestroy` / an effect cleanup). */
+export declare const registerCommand: (cmd: Command) => (() => void);
+/**
+ * Fuzzy subsequence score of `query` in `text`: -1 when the letters do not appear in order, otherwise higher is better
+ * (consecutive letters and word starts score more).
+ */
+export declare function fuzzyScore(query: string, text: string): number;
+export {};

package/dist/commands.svelte.js

@@ -0,0 +1,59 @@
+import { untrack } from 'svelte';
+import { hotkeys } from './hotkeys.svelte.js';
+/**
+ * Registry behind `<CommandPalette>` and `<ShortcutSheet>`. Registration is reactive, so palettes update as screens
+ * register and unregister their own commands.
+ */
+class CommandStore {
+    #items = $state.raw([]);
+    #unbind = new Map();
+    /** Every registered command. */
+    get all() { return this.#items; }
+    /** The commands whose `when` currently allows them. */
+    get available() { return this.#items.filter((c) => !c.when || c.when()); }
+    register(cmd) {
+        return untrack(() => {
+            this.#remove(cmd.id);
+            this.#items = [...this.#items, cmd];
+            if (cmd.shortcut)
+                this.#unbind.set(cmd.id, hotkeys.register(cmd.shortcut, () => void cmd.run(), { description: cmd.label, group: cmd.group, when: cmd.when, allowInInput: cmd.allowInInput }));
+            return () => untrack(() => { if (this.#items.includes(cmd))
+                this.#remove(cmd.id); });
+        });
+    }
+    #remove(id) {
+        this.#unbind.get(id)?.();
+        this.#unbind.delete(id);
+        this.#items = this.#items.filter((c) => c.id !== id);
+    }
+    /** Run a command by id (regardless of `when`). Returns false if there is none. */
+    async run(id) {
+        const c = this.#items.find((x) => x.id === id);
+        if (!c)
+            return false;
+        await c.run();
+        return true;
+    }
+}
+export const commands = new CommandStore();
+/** Register a command; returns the function that unregisters it (call it from `onDestroy` / an effect cleanup). */
+export const registerCommand = (cmd) => commands.register(cmd);
+/**
+ * Fuzzy subsequence score of `query` in `text`: -1 when the letters do not appear in order, otherwise higher is better
+ * (consecutive letters and word starts score more).
+ */
+export function fuzzyScore(query, text) {
+    const q = query.toLowerCase().replace(/\s+/g, ''), t = text.toLowerCase();
+    if (!q)
+        return 0;
+    let ti = 0, score = 0, run = 0;
+    for (const ch of q) {
+        const at = t.indexOf(ch, ti);
+        if (at < 0)
+            return -1;
+        run = at === ti && ti > 0 ? run + 1 : 0;
+        score += 1 + run * 2 + (at === 0 || /[\s\-_/.]/.test(t[at - 1]) ? 3 : 0);
+        ti = at + 1;
+    }
+    return score - t.length * 0.01 + (t.startsWith(q) ? 5 : t.includes(q) ? 3 : 0);
+}

package/dist/components/Accordion.svelte

@@ -57,7 +57,7 @@
 	.acc { border: 1px solid var(--tr-outline-variant); border-radius: var(--tr-radius-md); overflow: hidden; background: var(--tr-surface-container-low); }
 	.item + .item { border-top: 1px solid var(--tr-outline-variant); }
 	h3 { margin: 0; font-size: inherit; }
-	.hd { display: flex; align-items: center; gap: 8px; width: 100%; height: 36px; padding: 0 12px; border: 0; background: var(--tr-surface-container); color: var(--tr-on-surface); font: 600 var(--tr-text-md) var(--tr-font-sans); text-align: left; cursor: pointer; }
+	.hd { display: flex; align-items: center; gap: 8px; width: 100%; height: calc(var(--tr-control-h) + 4px); padding: 0 var(--tr-space-3); border: 0; background: var(--tr-surface-container); color: var(--tr-on-surface); font: 600 var(--tr-text-md) var(--tr-font-sans); text-align: left; cursor: pointer; }
 	.hd:hover:not(:disabled) { background: var(--tr-surface-container-high); }
 	.hd:disabled { opacity: 0.45; cursor: not-allowed; }
 	.hd:focus-visible { outline: none; box-shadow: inset 0 0 0 2px var(--tr-primary); }

package/dist/components/Button.svelte

@@ -1,7 +1,10 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import type { HTMLAnchorAttributes, HTMLButtonAttributes } from 'svelte/elements';
+	import { mount, unmount } from 'svelte';
 	import Icon from '../icons/Icon.svelte';
+	import TooltipTip from './TooltipTip.svelte';
+	import { ariaKeyShortcuts } from '../keys.js';
 	import type { Intent, IconSource } from '../types.js';
 
 	type Common = {
@@ -12,6 +15,8 @@
 		icon?: IconSource;
 		rightIcon?: IconSource;
 		loading?: boolean;
+		/** A key combination (`mod+s`) shown in a hover/focus tooltip beside the label, never inline, and exposed as `aria-keyshortcuts`. Display only: bind the key with `registerCommand` or `hotkeys`. */
+		shortcut?: string;
 		children?: Snippet;
 	};
 	/**
@@ -30,6 +35,7 @@
 		icon,
 		rightIcon,
 		loading = false,
+		shortcut,
 		href,
 		type = 'button',
 		disabled,
@@ -38,6 +44,54 @@
 		...rest
 	}: Props = $props();
 
+	const uid = $props.id();
+	let el = $state<HTMLElement>();
+	/**
+	 * The shortcut tooltip is mounted into <body> (or the enclosing <dialog>, which sits in the top layer) instead of wrapping the
+	 * button, so `.tr-btn` stays a direct child of ButtonGroup and InputGroup.
+	 */
+	$effect(() => {
+		const node = el;
+		if (!shortcut || !node) return;
+		let timer: ReturnType<typeof setTimeout>;
+		let tip: ReturnType<typeof mount> | undefined;
+		let before: string | null = null;
+		const show = (now: boolean) => {
+			clearTimeout(timer);
+			timer = setTimeout(() => {
+				if (tip) return;
+				const text = node.getAttribute('aria-label') ?? node.textContent?.trim() ?? '';
+				before = node.getAttribute('aria-describedby');
+				node.setAttribute('aria-describedby', before ? `${before} ${uid}-tip` : `${uid}-tip`);
+				tip = mount(TooltipTip, { target: node.closest('dialog') ?? document.body, props: { anchor: node, id: `${uid}-tip`, text, shortcut } });
+			}, now ? 0 : 350);
+		};
+		const hide = () => {
+			clearTimeout(timer);
+			if (!tip) return;
+			unmount(tip);
+			tip = undefined;
+			if (before) node.setAttribute('aria-describedby', before); else node.removeAttribute('aria-describedby');
+		};
+		const esc = (e: KeyboardEvent) => e.key === 'Escape' && hide();
+		const enter = () => show(false), focus = () => show(true);
+		node.addEventListener('pointerenter', enter);
+		node.addEventListener('pointerleave', hide);
+		node.addEventListener('pointerdown', hide);
+		node.addEventListener('focusin', focus);
+		node.addEventListener('focusout', hide);
+		addEventListener('keydown', esc);
+		return () => {
+			hide();
+			node.removeEventListener('pointerenter', enter);
+			node.removeEventListener('pointerleave', hide);
+			node.removeEventListener('pointerdown', hide);
+			node.removeEventListener('focusin', focus);
+			node.removeEventListener('focusout', hide);
+			removeEventListener('keydown', esc);
+		};
+	});
+
 	const iconPx = $derived(size === 'lg' ? 20 : 16) as 16 | 20;
 	const asLink = $derived(!!href && !disabled && !loading);
 	/** Attributes that only make sense on an anchor are dropped when a disabled/loading link becomes a button. */
@@ -55,11 +109,12 @@
 {/snippet}
 
 {#if asLink}
-	<a class="tr-btn {klass}" data-variant={variant} data-intent={intent} data-size={size} data-icon-only={!children} {...anchorRest} {href} {rel}>
+	<a bind:this={el} class="tr-btn {klass}" data-variant={variant} data-intent={intent} data-size={size} data-icon-only={!children} aria-keyshortcuts={shortcut ? ariaKeyShortcuts(shortcut) : undefined} {...anchorRest} {href} {rel}>
 		{@render content()}
 	</a>
 {:else}
 	<button
+		bind:this={el}
 		class="tr-btn {klass}"
 		data-variant={variant}
 		data-intent={intent}
@@ -68,6 +123,7 @@
 		{type}
 		disabled={disabled || loading}
 		aria-busy={loading || undefined}
+		aria-keyshortcuts={shortcut ? ariaKeyShortcuts(shortcut) : undefined}
 		{...buttonRest}
 	>
 		{@render content()}
@@ -77,6 +133,7 @@
 <style>
 	.tr-btn {
 		--c: var(--tr-primary);
+		--ct: var(--tr-primary-text, var(--tr-primary));
 		--on: var(--tr-on-primary);
 		--cc: var(--tr-primary-container);
 		--on-cc: var(--tr-on-primary-container);
@@ -104,11 +161,11 @@
 	.tr-btn[data-size='lg'] { height: var(--tr-control-h-lg); min-width: var(--tr-control-h-lg); padding: 0 16px; font-size: var(--tr-text-lg); }
 	.tr-btn[data-icon-only='true'] { padding: 0; }
 
-	.tr-btn[data-intent='neutral'] { --c: var(--tr-on-surface); --on: var(--tr-surface); --cc: var(--tr-surface-container-high); --on-cc: var(--tr-on-surface); }
-	.tr-btn[data-intent='secondary'] { --c: var(--tr-secondary); --on: var(--tr-on-secondary); --cc: var(--tr-secondary-container); --on-cc: var(--tr-on-secondary-container); }
-	.tr-btn[data-intent='success'] { --c: var(--tr-success); --on: var(--tr-on-success); --cc: var(--tr-success-container); --on-cc: var(--tr-on-success-container); }
-	.tr-btn[data-intent='warning'] { --c: var(--tr-warning); --on: var(--tr-on-warning); --cc: var(--tr-warning-container); --on-cc: var(--tr-on-warning-container); }
-	.tr-btn[data-intent='danger'] { --c: var(--tr-danger); --on: var(--tr-on-danger); --cc: var(--tr-danger-container); --on-cc: var(--tr-on-danger-container); }
+	.tr-btn[data-intent='neutral'] { --c: var(--tr-on-surface); --ct: var(--tr-on-surface); --on: var(--tr-surface); --cc: var(--tr-surface-container-high); --on-cc: var(--tr-on-surface); }
+	.tr-btn[data-intent='secondary'] { --c: var(--tr-secondary); --ct: var(--tr-secondary-text, var(--tr-secondary)); --on: var(--tr-on-secondary); --cc: var(--tr-secondary-container); --on-cc: var(--tr-on-secondary-container); }
+	.tr-btn[data-intent='success'] { --c: var(--tr-success); --ct: var(--tr-success); --on: var(--tr-on-success); --cc: var(--tr-success-container); --on-cc: var(--tr-on-success-container); }
+	.tr-btn[data-intent='warning'] { --c: var(--tr-warning); --ct: var(--tr-warning); --on: var(--tr-on-warning); --cc: var(--tr-warning-container); --on-cc: var(--tr-on-warning-container); }
+	.tr-btn[data-intent='danger'] { --c: var(--tr-danger); --ct: var(--tr-danger); --on: var(--tr-on-danger); --cc: var(--tr-danger-container); --on-cc: var(--tr-on-danger-container); }
 
 	/* Primary filled: solid, high contrast */
 	.tr-btn[data-variant='filled'] { background: var(--c); color: var(--on); box-shadow: var(--tr-elevation-1); }
@@ -117,9 +174,9 @@
 	.tr-btn[data-variant='tonal'] { background: var(--cc); color: var(--on-cc); }
 	.tr-btn[data-variant='tonal']:hover:not(:disabled) { background: color-mix(in srgb, var(--on-cc) 10%, var(--cc)); }
 	/* Outlined: precise 1px border */
-	.tr-btn[data-variant='outlined'] { border-color: var(--tr-outline); color: var(--c); background: transparent; }
+	.tr-btn[data-variant='outlined'] { border-color: var(--tr-outline); color: var(--ct); background: transparent; }
 	.tr-btn[data-variant='outlined']:hover:not(:disabled) { background: color-mix(in srgb, var(--c) 8%, transparent); }
-	.tr-btn[data-variant='minimal'] { color: var(--c); background: transparent; }
+	.tr-btn[data-variant='minimal'] { color: var(--ct); background: transparent; }
 	.tr-btn[data-variant='minimal']:hover:not(:disabled) { background: color-mix(in srgb, var(--c) 10%, transparent); }
 
 	.tr-btn:active:not(:disabled) { transform: scale(0.98); }

package/dist/components/Button.svelte.d.ts

@@ -9,6 +9,8 @@ type Common = {
     icon?: IconSource;
     rightIcon?: IconSource;
     loading?: boolean;
+    /** A key combination (`mod+s`) shown in a hover/focus tooltip beside the label, never inline, and exposed as `aria-keyshortcuts`. Display only: bind the key with `registerCommand` or `hotkeys`. */
+    shortcut?: string;
     children?: Snippet;
 };
 /**

package/dist/components/Calendar.svelte

@@ -149,10 +149,10 @@
 	.title { flex: 1; text-align: center; font-weight: 600; }
 	.grid { outline: none; }
 	.row { display: grid; grid-template-columns: repeat(7, 1fr); }
-	.dow { height: 24px; display: grid; place-items: center; font-size: var(--tr-text-xs); font-weight: 700; text-transform: uppercase; color: var(--tr-on-surface-variant); }
+	.dow { height: var(--tr-control-h-sm); display: grid; place-items: center; font-size: var(--tr-text-xs); font-weight: 700; text-transform: uppercase; color: var(--tr-on-surface-variant); }
 	[role='gridcell'] { display: contents; }
 	.day {
-		height: 32px; border: 0; background: none; color: var(--tr-on-surface); font: inherit; font-variant-numeric: tabular-nums;
+		height: var(--tr-control-h); border: 0; background: none; color: var(--tr-on-surface); font: inherit; font-variant-numeric: tabular-nums;
 		border-radius: var(--tr-radius-sm); cursor: pointer; position: relative;
 	}
 	.day:hover:not(:disabled) { background: var(--tr-surface-container-highest); }

package/dist/components/Card.svelte

@@ -3,6 +3,7 @@
 	import type { HTMLAnchorAttributes, HTMLAttributes, HTMLButtonAttributes } from 'svelte/elements';
 
 	type Base = {
+		/** Padding of the body only (the `children` between header and footer): `md` (default) is 16px, `sm` is 8px 12px, `none` removes it so the content can supply its own spacing or a media-only card has none. The header, footer and actions keep their own padding. */
 		padding?: 'none' | 'sm' | 'md';
 		elevation?: 0 | 1 | 2 | 3;
 		/** Edge-to-edge content above the header and body (an image, video or map); clipped by the card's rounded corners. */

package/dist/components/Card.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAnchorAttributes, HTMLAttributes, HTMLButtonAttributes } from 'svelte/elements';
 type Base = {
+    /** Padding of the body only (the `children` between header and footer): `md` (default) is 16px, `sm` is 8px 12px, `none` removes it so the content can supply its own spacing or a media-only card has none. The header, footer and actions keep their own padding. */
     padding?: 'none' | 'sm' | 'md';
     elevation?: 0 | 1 | 2 | 3;
     /** Edge-to-edge content above the header and body (an image, video or map); clipped by the card's rounded corners. */

package/dist/components/Checkbox.svelte

@@ -25,7 +25,7 @@
 </label>
 
 <style>
-	.cb { display: inline-flex; align-items: flex-start; gap: 8px; min-height: 24px; cursor: pointer; }
+	.cb { display: inline-flex; align-items: flex-start; gap: 8px; min-height: var(--tr-control-h-sm); cursor: pointer; }
 	.cb[data-disabled='true'] { opacity: 0.5; cursor: not-allowed; }
 	.box { flex: none; display: grid; place-items: center; width: 18px; height: 18px; margin-top: 3px; border: 1px solid var(--tr-outline); border-radius: var(--tr-radius-sm); background: var(--tr-surface-container-low); color: var(--tr-on-primary); transition: background-color var(--tr-dur) var(--tr-ease), box-shadow var(--tr-dur) var(--tr-ease); }
 	.box :global(svg) { width: 14px; height: 14px; }

package/dist/components/CommandPalette.svelte

@@ -0,0 +1,207 @@
+<script lang="ts" module>
+	import type { IconSource } from '../types.js';
+
+	/** A result that is not a registered command, typically returned by a provider (search hits, recent documents...). */
+	export type PaletteItem = {
+		id: string;
+		label: string;
+		group?: string;
+		icon?: IconSource;
+		keywords?: string[];
+		/** Shown beside the label (display only). */
+		shortcut?: string;
+		run: () => void | Promise<void>;
+	};
+
+	/** An async source of extra results, queried as the user types. */
+	export type PaletteProvider = {
+		id: string;
+		/** Group heading for items that do not set their own. */
+		label: string;
+		/** Fewer typed characters than this skip the provider (default 1; use 0 to also query with an empty box). */
+		minLength?: number;
+		search: (query: string, signal: AbortSignal) => Promise<PaletteItem[]>;
+	};
+</script>
+
+<script lang="ts">
+	import { tick } from 'svelte';
+	import Dialog from './Dialog.svelte';
+	import Icon from '../icons/Icon.svelte';
+	import Kbd from './Kbd.svelte';
+	import { commands, fuzzyScore } from '../commands.svelte.js';
+	import { hotkeys } from '../hotkeys.svelte.js';
+
+	let {
+		open = $bindable(false),
+		shortcut = 'mod+k',
+		providers = [],
+		placeholder = 'Type a command or search…',
+		title = 'Command palette',
+		recents = 5,
+		storageKey = 'truss-command-recents',
+		debounce = 150
+	}: {
+		open?: boolean;
+		/** Key combination that toggles the palette; `null` disables the built-in binding. */
+		shortcut?: string | null;
+		/** Extra async result sources shown beneath the registered commands. */
+		providers?: PaletteProvider[];
+		placeholder?: string;
+		/** Accessible name of the dialog. */
+		title?: string;
+		/** How many recently run commands to list first when the box is empty (0 turns recents off). */
+		recents?: number;
+		/** localStorage key that remembers recent commands. */
+		storageKey?: string;
+		debounce?: number;
+	} = $props();
+
+	type Row = { key: string; id: string; label: string; group: string; icon?: IconSource; shortcut?: string; run: () => void | Promise<void>; command: boolean; i: number };
+
+	const uid = $props.id();
+	let query = $state('');
+	let active = $state(0);
+	let remote = $state.raw<Omit<Row, 'i'>[]>([]);
+	let searching = $state(false);
+	let input = $state<HTMLInputElement>();
+	let list = $state<HTMLDivElement>();
+	let recent = $state.raw<string[]>([]);
+
+	// ───── recents (localStorage may be unavailable or throw)
+	const loadRecent = (): string[] => {
+		try { const v = JSON.parse(localStorage.getItem(storageKey) ?? '[]'); return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []; } catch { return []; }
+	};
+	const remember = (id: string) => {
+		recent = [id, ...recent.filter((x) => x !== id)].slice(0, Math.max(recents, 0));
+		try { localStorage.setItem(storageKey, JSON.stringify(recent)); } catch { /* storage unavailable */ }
+	};
+
+	// ───── bindings: toggle on the shortcut, and own the keyboard while open
+	$effect(() => {
+		if (!shortcut) return;
+		const off = [
+			hotkeys.register(shortcut, () => (open = !open), { allowInInput: true, description: 'Open command palette', group: 'General' }),
+			hotkeys.register(shortcut, () => (open = false), { scope: 'palette', allowInInput: true })
+		];
+		return () => off.forEach((f) => f());
+	});
+	$effect(() => { if (open) return hotkeys.pushScope('palette'); });
+	$effect(() => {
+		if (!open) return;
+		query = ''; active = 0; remote = [];
+		recent = loadRecent();
+		tick().then(() => input?.focus());
+	});
+
+	// ───── results
+	const toRow = (c: { id: string; label: string; group?: string; icon?: IconSource; shortcut?: string; run: () => void | Promise<void> }, command: boolean, fallback: string): Omit<Row, 'i'> =>
+		({ key: `${command ? 'c' : 'r'}:${c.id}`, id: c.id, label: c.label, group: c.group ?? fallback, icon: c.icon, shortcut: c.shortcut, run: c.run, command });
+
+	const rows = $derived.by<Row[]>(() => {
+		if (!open) return [];
+		const q = query.trim();
+		const cmds = commands.available;
+		let out: Omit<Row, 'i'>[];
+		if (!q) {
+			const byId = new Map(cmds.map((c) => [c.id, c]));
+			const rec = recent.map((id) => byId.get(id)).filter((c): c is NonNullable<typeof c> => !!c).slice(0, recents);
+			const seen = new Set(rec.map((c) => c.id));
+			out = [...rec.map((c) => ({ ...toRow(c, true, 'Commands'), group: 'Recent', key: `recent:${c.id}` })), ...cmds.filter((c) => !seen.has(c.id)).map((c) => toRow(c, true, 'Commands'))];
+		} else {
+			out = cmds
+				.map((c) => ({ c, s: Math.max(fuzzyScore(q, c.label) * 2, fuzzyScore(q, (c.keywords ?? []).join(' ')), fuzzyScore(q, c.group ?? '') * 0.5) }))
+				.filter((x) => x.s >= 0)
+				.sort((a, b) => b.s - a.s)
+				.map((x) => toRow(x.c, true, 'Commands'));
+		}
+		out = [...out, ...remote];
+		// keep groups together, in order of first appearance
+		const order = [...new Set(out.map((r) => r.group))];
+		return order.flatMap((g) => out.filter((r) => r.group === g)).map((r, i) => ({ ...r, i }));
+	});
+	const sections = $derived.by(() => {
+		const m = new Map<string, Row[]>();
+		for (const r of rows) (m.get(r.group) ?? m.set(r.group, []).get(r.group)!).push(r);
+		return [...m].map(([name, items]) => ({ name, items }));
+	});
+	$effect(() => { if (active >= rows.length) active = 0; });
+	$effect(() => { void active; list?.querySelector('[aria-selected="true"]')?.scrollIntoView({ block: 'nearest' }); });
+
+	const status = $derived(searching ? 'Searching…' : rows.length ? `${rows.length} result${rows.length === 1 ? '' : 's'}` : 'No results');
+
+	// ───── async providers
+	$effect(() => {
+		if (!open) return;
+		const q = query.trim();
+		const live = providers.filter((p) => q.length >= (p.minLength ?? 1));
+		if (!live.length) { remote = []; searching = false; return; }
+		searching = true;
+		const ctrl = new AbortController();
+		const timer = setTimeout(async () => {
+			const results = await Promise.allSettled(live.map((p) => p.search(q, ctrl.signal)));
+			if (ctrl.signal.aborted) return;
+			remote = results.flatMap((r, n) => (r.status === 'fulfilled' ? r.value.map((it) => toRow(it, false, live[n].label)) : []));
+			searching = false;
+		}, debounce);
+		return () => { clearTimeout(timer); ctrl.abort(); };
+	});
+
+	async function choose(r: Row | undefined) {
+		if (!r) return;
+		if (r.command) remember(r.id);
+		open = false;
+		await tick(); // let the dialog close (and give focus back) before the action runs
+		await r.run();
+	}
+
+	function onKey(e: KeyboardEvent) {
+		if (e.key === 'ArrowDown') { e.preventDefault(); active = rows.length ? (active + 1) % rows.length : 0; }
+		else if (e.key === 'ArrowUp') { e.preventDefault(); active = rows.length ? (active - 1 + rows.length) % rows.length : 0; }
+		else if (e.key === 'Enter' && !e.isComposing) { e.preventDefault(); choose(rows[active]); }
+	}
+</script>
+
+<Dialog bind:open {title} size="lg">
+	{#if open}
+		<div class="pal">
+			<input
+				bind:this={input} bind:value={query} oninput={() => (active = 0)} onkeydown={onKey}
+				class="q" type="text" role="combobox" aria-label={title} aria-expanded="true" aria-controls="{uid}-list" aria-autocomplete="list"
+				aria-activedescendant={rows[active] ? `${uid}-o${active}` : undefined} {placeholder} autocomplete="off" spellcheck="false"
+			/>
+			<div class="list" id="{uid}-list" role="listbox" aria-label="Results" bind:this={list}>
+				{#each sections as sec, si (sec.name)}
+					<div role="group" aria-labelledby="{uid}-g{si}">
+						<div class="gh" id="{uid}-g{si}">{sec.name}</div>
+						{#each sec.items as r (r.key)}
+							<!-- svelte-ignore a11y_click_events_have_key_events, a11y_interactive_supports_focus -->
+							<div id="{uid}-o{r.i}" role="option" class="opt" aria-selected={r.i === active} onclick={() => choose(r)} onpointermove={() => { if (active !== r.i) active = r.i; }}>
+								<span class="lead">{#if r.icon}<Icon name={r.icon} />{/if}</span>
+								<span class="lbl">{r.label}</span>
+								{#if r.shortcut}<Kbd keys={r.shortcut} />{/if}
+							</div>
+						{/each}
+					</div>
+				{/each}
+				{#if !rows.length && !searching}<div class="empty">No matching commands</div>{/if}
+			</div>
+			<div class="tr-visually-hidden" role="status" aria-live="polite">{status}</div>
+		</div>
+	{/if}
+</Dialog>
+
+<style>
+	.pal { display: flex; flex-direction: column; gap: 8px; margin: -16px; }
+	.q { height: 44px; padding: 0 16px; border: 0; border-bottom: 1px solid var(--tr-outline-variant); background: transparent; color: var(--tr-on-surface); font: var(--tr-text-lg) var(--tr-font-sans); outline: none; }
+	.q::placeholder { color: var(--tr-on-surface-variant); }
+	.q:focus-visible { box-shadow: inset 0 -2px 0 var(--tr-primary); }
+	.list { max-height: min(50vh, 420px); overflow: auto; padding: 0 8px 8px; }
+	.gh { padding: 8px 8px 2px; font-size: var(--tr-text-xs); font-weight: 700; letter-spacing: 0.06em; text-transform: uppercase; color: var(--tr-on-surface-variant); }
+	.opt { display: flex; align-items: center; gap: 8px; height: var(--tr-control-h); padding: 0 8px; border-radius: var(--tr-radius-sm); cursor: pointer; color: var(--tr-on-surface); }
+	.opt[aria-selected='true'] { background: var(--tr-surface-container-highest); box-shadow: inset 2px 0 0 var(--tr-primary); }
+	.lead { display: inline-flex; width: 16px; flex: none; }
+	.lbl { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+	.opt :global(.tr-kbd) { color: var(--tr-on-surface-variant); }
+	.empty { padding: 16px 8px; text-align: center; color: var(--tr-on-surface-variant); }
+</style>

package/dist/components/CommandPalette.svelte.d.ts

@@ -0,0 +1,39 @@
+import type { IconSource } from '../types.js';
+/** A result that is not a registered command, typically returned by a provider (search hits, recent documents...). */
+export type PaletteItem = {
+    id: string;
+    label: string;
+    group?: string;
+    icon?: IconSource;
+    keywords?: string[];
+    /** Shown beside the label (display only). */
+    shortcut?: string;
+    run: () => void | Promise<void>;
+};
+/** An async source of extra results, queried as the user types. */
+export type PaletteProvider = {
+    id: string;
+    /** Group heading for items that do not set their own. */
+    label: string;
+    /** Fewer typed characters than this skip the provider (default 1; use 0 to also query with an empty box). */
+    minLength?: number;
+    search: (query: string, signal: AbortSignal) => Promise<PaletteItem[]>;
+};
+type $$ComponentProps = {
+    open?: boolean;
+    /** Key combination that toggles the palette; `null` disables the built-in binding. */
+    shortcut?: string | null;
+    /** Extra async result sources shown beneath the registered commands. */
+    providers?: PaletteProvider[];
+    placeholder?: string;
+    /** Accessible name of the dialog. */
+    title?: string;
+    /** How many recently run commands to list first when the box is empty (0 turns recents off). */
+    recents?: number;
+    /** localStorage key that remembers recent commands. */
+    storageKey?: string;
+    debounce?: number;
+};
+declare const CommandPalette: import("svelte").Component<$$ComponentProps, {}, "open">;
+type CommandPalette = ReturnType<typeof CommandPalette>;
+export default CommandPalette;