@signal9/era-ui 1.25.0 → 1.26.1

package/dist/os/launcher.svelte.d.ts

@@ -1,7 +1,9 @@
 type $$ComponentProps = {
     open?: boolean;
-    /** Register Ctrl/Cmd+K to toggle and Escape to close (default true). */
-    hotkey?: boolean;
+    /** Global binding(s) that toggle the launcher (tinykeys grammar, e.g.
+     *  `'$mod+k'`). No default — the taskbar button is the base affordance.
+     *  Escape always closes while open. */
+    hotkey?: string | string[];
 };
 declare const Launcher: import("svelte").Component<$$ComponentProps, {}, "open">;
 type Launcher = ReturnType<typeof Launcher>;

package/dist/os/wm.svelte.d.ts

@@ -126,7 +126,9 @@ export declare class WindowManager {
      *  singleton — from any workspace; it is brought to the active one). */
     open(appId: string, overrides?: Partial<Pick<AppWindow, 'title' | 'pos' | 'size' | 'resizable' | 'workspaceId'>>): string | null;
     close(id: string): void;
-    /** Bring a window to the front (and un-minimize it if needed). */
+    /** Make a window the frontmost VISIBLE one: switch to its workspace,
+     *  un-minimize it, and bring it to the front. Focus means reveal at every
+     *  level — never a silent off-screen z bump. */
     focus(id: string): void;
     minimize(id: string): void;
     /** Taskbar behaviour: focus if not focused, else minimize; restore if minimized. */

package/dist/os/wm.svelte.js

@@ -77,7 +77,11 @@ export class WindowManager {
         if (app.singleton) {
             const existing = this.windows.find((w) => w.appId === appId);
             if (existing) {
-                existing.workspaceId = overrides?.workspaceId ?? this.activeWorkspaceId;
+                // Reveal, don't relocate: restore() → focus() switches to the
+                // workspace the window already lives on, the way every virtual
+                // desktop behaves. An explicit override still moves it.
+                if (overrides?.workspaceId)
+                    existing.workspaceId = overrides.workspaceId;
                 this.restore(existing.id);
                 return existing.id;
             }
@@ -108,11 +112,15 @@ export class WindowManager {
     close(id) {
         this.windows = this.windows.filter((w) => w.id !== id);
     }
-    /** Bring a window to the front (and un-minimize it if needed). */
+    /** Make a window the frontmost VISIBLE one: switch to its workspace,
+     *  un-minimize it, and bring it to the front. Focus means reveal at every
+     *  level — never a silent off-screen z bump. */
     focus(id) {
         const w = this.#find(id);
         if (!w)
             return;
+        if (w.workspaceId !== this.activeWorkspaceId)
+            this.switchWorkspace(w.workspaceId);
         if (w.state === 'minimized')
             w.state = 'normal';
         if (w.z <= this.#z)

package/dist/styles/themes.css

@@ -56,7 +56,7 @@
 	--color-destructive-fg: oklch(0.96 0 0);
 	--color-success: oklch(0.65 0.17 145);
 	--color-success-fg: oklch(0.96 0 0);
---color-warning: oklch(0.8 0.16 85);
+	--color-warning: oklch(0.8 0.16 85);
 	--color-warning-fg: oklch(0.162 0 0);
 }
 
@@ -95,7 +95,7 @@
 		--color-destructive-fg: oklch(0.98 0 0);
 		--color-success: oklch(0.5 0.17 145);
 		--color-success-fg: oklch(0.98 0 0);
---color-warning: oklch(0.72 0.15 85);
+		--color-warning: oklch(0.72 0.15 85);
 		--color-warning-fg: oklch(0.162 0 0);
 	}
 }
@@ -131,7 +131,7 @@
 	--color-destructive-fg: oklch(0.98 0 0);
 	--color-success: oklch(0.5 0.17 145);
 	--color-success-fg: oklch(0.98 0 0);
---color-warning: oklch(0.72 0.15 85);
+	--color-warning: oklch(0.72 0.15 85);
 	--color-warning-fg: oklch(0.162 0 0);
 }
 
@@ -175,7 +175,7 @@
 	--color-destructive-fg: oklch(0.96 0.016 90);
 	--color-success: oklch(0.7 0.125 184);
 	--color-success-fg: oklch(0.19 0.014 50);
---color-warning: oklch(0.78 0.14 82);
+	--color-warning: oklch(0.78 0.14 82);
 	--color-warning-fg: oklch(0.19 0.014 50);
 }
 
@@ -218,7 +218,7 @@
 		--color-destructive-fg: oklch(0.98 0.012 78);
 		--color-success: oklch(0.5 0.13 158);
 		--color-success-fg: oklch(0.98 0.012 78);
---color-warning: oklch(0.7 0.13 80);
+		--color-warning: oklch(0.7 0.13 80);
 		--color-warning-fg: oklch(0.19 0.014 50);
 	}
 }
@@ -253,7 +253,7 @@
 	--color-destructive-fg: oklch(0.98 0.012 78);
 	--color-success: oklch(0.5 0.13 158);
 	--color-success-fg: oklch(0.98 0.012 78);
---color-warning: oklch(0.7 0.13 80);
+	--color-warning: oklch(0.7 0.13 80);
 	--color-warning-fg: oklch(0.19 0.014 50);
 }
 
@@ -291,7 +291,7 @@
 	--color-destructive-fg: var(--color-12);
 	--color-success: oklch(0.71 0.09 164);
 	--color-success-fg: var(--color-1);
---color-warning: oklch(0.78 0.1 85);
+	--color-warning: oklch(0.78 0.1 85);
 	--color-warning-fg: var(--color-1);
 }
 
@@ -329,7 +329,7 @@
 		--color-destructive-fg: oklch(0.98 0.008 80);
 		--color-success: oklch(0.54 0.11 164);
 		--color-success-fg: oklch(0.98 0.008 80);
---color-warning: oklch(0.68 0.1 82);
+		--color-warning: oklch(0.68 0.1 82);
 		--color-warning-fg: oklch(0.2 0.012 60);
 	}
 }
@@ -364,6 +364,6 @@
 	--color-destructive-fg: oklch(0.98 0.008 80);
 	--color-success: oklch(0.54 0.11 164);
 	--color-success-fg: oklch(0.98 0.008 80);
---color-warning: oklch(0.68 0.1 82);
+	--color-warning: oklch(0.68 0.1 82);
 	--color-warning-fg: oklch(0.2 0.012 60);
 }

package/dist/ui/button/index.d.ts

@@ -2,7 +2,7 @@ import Button from './button.svelte';
 export { Button };
 export { buttonVariants } from './variants.js';
 export interface ButtonVariants {
-    tone?: 'default' | 'accent' | 'destructive' | 'success';
+    tone?: 'default' | 'accent' | 'destructive' | 'success' | 'warning';
     size?: 'default' | 'sm' | 'xs' | 'icon';
     variant?: 'filled' | 'link';
     icon?: boolean;

package/dist/ui/command-bar/command-bar.svelte

@@ -0,0 +1,254 @@
+<script lang="ts">
+	import ChevronRight from '@lucide/svelte/icons/chevron-right';
+	import { cn } from '../../utils/index.js';
+	import { keys, isTextEntryFocused, type KeyBindingMap } from '../../utils/hotkeys.js';
+	import type { CommandBarItem } from './types.js';
+
+	let {
+		items,
+		placeholder = 'Type a command…',
+		empty = 'No results found.',
+		hotkey,
+		class: className
+	}: {
+		/** The root view. */
+		items: CommandBarItem[];
+		placeholder?: string;
+		/** Empty-state message when the filter matches nothing. */
+		empty?: string;
+		/** Global binding(s) that focus the bar (tinykeys grammar, e.g.
+		 *  `['`', 'Escape']`). While another field has focus only Escape
+		 *  acts — it blurs that field instead of stealing the caret. */
+		hotkey?: string | string[];
+		class?: string;
+	} = $props();
+
+	let input = $state<HTMLInputElement | null>(null);
+	let value = $state('');
+	let focused = $state(false);
+	let selectedIndex = $state(0);
+	// Drill-in stack: each entry is a completed segment (its label renders as a
+	// locked breadcrumb before the input; Backspace on an empty input pops it).
+	let stack = $state<CommandBarItem[]>([]);
+
+	const view = $derived(stack.at(-1));
+	const viewItems = $derived(view?.items ?? items);
+	const viewPlaceholder = $derived(view?.placeholder ?? placeholder);
+
+	// Substring filter with exact-match priority (2 exact, 1 substring), the
+	// same scoring the terminal uses — exact hits sort first so completion
+	// always grabs the literal match.
+	const filtered = $derived.by(() => {
+		const q = value.trim().toLowerCase();
+		if (!q) return viewItems;
+		return viewItems
+			.map((item) => {
+				const label = item.label.toLowerCase();
+				const kw = item.keywords?.map((k) => k.toLowerCase()) ?? [];
+				let score = 0;
+				if (label === q || kw.includes(q)) score = 2;
+				else if (
+					label.includes(q) ||
+					item.value.toLowerCase().includes(q) ||
+					kw.some((k) => k.includes(q))
+				)
+					score = 1;
+				return { item, score };
+			})
+			.filter((s) => s.score > 0)
+			.sort((a, b) => b.score - a.score)
+			.map((s) => s.item);
+	});
+	const selected = $derived(filtered[selectedIndex]);
+	const open = $derived(focused || value !== '');
+
+	// zsh-style ghost completion: the selected item's remaining characters laid
+	// under the caret (or the view placeholder while empty).
+	const ghost = $derived.by(() => {
+		if (!value) return viewPlaceholder;
+		if (!selected) return '';
+		const label = selected.label;
+		return label.toLowerCase().startsWith(value.toLowerCase()) ? label.slice(value.length) : '';
+	});
+
+	// New keystrokes / view changes re-aim the selection at the top match.
+	$effect(() => {
+		void value;
+		void stack.length;
+		selectedIndex = 0;
+	});
+
+	function reset() {
+		value = '';
+		stack = [];
+		selectedIndex = 0;
+	}
+
+	function drill(item: CommandBarItem) {
+		stack.push(item);
+		value = '';
+	}
+
+	/** Enter / click: run the item, or descend if it's a view. */
+	function choose(item: CommandBarItem) {
+		if (item.onSelect) {
+			item.onSelect();
+			reset();
+			input?.blur();
+		} else if (item.items) {
+			drill(item);
+		}
+	}
+
+	/** Tab / Space: completion — descend into a view, else run. */
+	function complete(item: CommandBarItem) {
+		if (item.items) drill(item);
+		else choose(item);
+	}
+
+	function onKeydown(e: KeyboardEvent) {
+		if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+			e.preventDefault();
+			const delta = e.key === 'ArrowDown' ? 1 : -1;
+			selectedIndex = Math.min(Math.max(selectedIndex + delta, 0), filtered.length - 1);
+		} else if (e.key === 'Enter') {
+			if (selected) choose(selected);
+		} else if (e.key === 'Tab' || e.key === ' ') {
+			if (selected) {
+				e.preventDefault();
+				complete(selected);
+			}
+		} else if (e.key === 'Escape') {
+			e.stopPropagation();
+			reset();
+			input?.blur();
+		} else if (e.key === 'Backspace' && value === '' && stack.length) {
+			e.preventDefault();
+			stack.pop();
+		} else if (e.key.toLowerCase() === 'u' && (e.ctrlKey || e.metaKey)) {
+			e.preventDefault();
+			reset();
+		}
+	}
+
+	// Focus hotkeys: a central map on window (tinykeys grammar). Guarded the
+	// way the terminal guards them — while any field is focused, only Escape
+	// acts (it blurs the field); every other binding is ignored so typing a
+	// backtick in a text input never steals the caret.
+	const bindings = $derived.by((): KeyBindingMap => {
+		if (!hotkey) return {};
+		const list = Array.isArray(hotkey) ? hotkey : [hotkey];
+		return Object.fromEntries(
+			list.map((b) => [
+				b,
+				(e: KeyboardEvent) => {
+					if (isTextEntryFocused()) {
+						if (b === 'Escape') (document.activeElement as HTMLElement).blur();
+						return;
+					}
+					e.preventDefault();
+					input?.focus();
+				}
+			])
+		);
+	});
+
+	export function focusInput() {
+		input?.focus();
+	}
+</script>
+
+<svelte:window use:keys={bindings} />
+
+<!-- The terminal command bar: a bare prompt line, not a floating palette. The
+     dropdown is a flat sheet anchored under it — no border, shadow or radius,
+     just the elevated surface, exactly like the shell it mirrors. -->
+<div class={cn('relative flex h-(--era-h-md) w-full min-w-0 items-center font-mono', className)}>
+	<ChevronRight class="mx-(--era-gap) size-(--era-h-xs) shrink-0 text-muted" />
+
+	<!-- Completed segments: the locked prefix. Backspace (empty input) pops. -->
+	{#each stack as seg (seg.value)}
+		<span class="shrink-0 text-body text-muted">{seg.label}</span>
+		<ChevronRight class="mx-(--era-gap) size-(--era-h-xxs) shrink-0 text-muted opacity-60" />
+	{/each}
+
+	<div class="relative h-full min-w-0 flex-1">
+		<input
+			bind:this={input}
+			bind:value
+			type="text"
+			role="combobox"
+			aria-expanded={open}
+			aria-controls="era-command-bar-list"
+			aria-activedescendant={selected ? `era-cmdbar-${selected.value}` : undefined}
+			aria-label={viewPlaceholder}
+			autocapitalize="off"
+			autocomplete="off"
+			autocorrect="off"
+			spellcheck="false"
+			class="h-full w-full bg-transparent text-body text-bright outline-none"
+			onkeydown={onKeydown}
+			onfocus={() => (focused = true)}
+			onblur={() => (focused = false)}
+		/>
+		<!-- Ghost text rides at the end of the typed value (ch units — the bar
+		     is mono by contract, so 1ch == one typed character). -->
+		<span
+			aria-hidden="true"
+			class="pointer-events-none absolute top-1/2 -translate-y-1/2 text-body whitespace-pre text-fg opacity-40"
+			style:left="{value.length}ch">{ghost}</span
+		>
+	</div>
+
+	{#if open}
+		<div
+			id="era-command-bar-list"
+			role="listbox"
+			tabindex="-1"
+			aria-label="Commands"
+			class="absolute top-full left-0 z-50 max-h-64 w-full overflow-x-hidden overflow-y-auto bg-2"
+			onmousedown={(e) => e.preventDefault()}
+		>
+			{#if !filtered.length}
+				<div class="flex h-(--era-h-md) items-center px-(--era-inset-md) text-body text-muted">
+					{empty}
+				</div>
+			{:else}
+				{#each filtered as item, i (item.value)}
+					<!-- Selection is keyboard-driven (selectedIndex), not :hover —
+					     mousedown is cancelled so a click never blurs the input. The
+					     keyboard path is the combobox input above (WAI-ARIA combobox:
+					     options are not tab stops). -->
+					<!-- svelte-ignore a11y_click_events_have_key_events -->
+					<div
+						id="era-cmdbar-{item.value}"
+						role="option"
+						tabindex={-1}
+						aria-selected={i === selectedIndex}
+						class={cn(
+							'flex h-(--era-h-md) cursor-default items-center gap-(--era-gap) px-(--era-inset-md) text-body whitespace-nowrap',
+							i === selectedIndex ? 'bg-3 text-bright' : 'text-fg'
+						)}
+						onclick={() => choose(item)}
+					>
+						{#if typeof item.icon === 'string'}
+							<span class="shrink-0">{item.icon}</span>
+						{:else if item.icon}
+							{@const Icon = item.icon}
+							<Icon class="size-(--era-h-xs) shrink-0 text-muted" />
+						{/if}
+						<span class="shrink-0">{item.label}</span>
+						{#if item.items}
+							<ChevronRight class="size-(--era-h-xxs) shrink-0 text-muted" />
+						{/if}
+						{#if item.sublabel}
+							<span class="ml-auto truncate pl-(--era-inset-md) text-body text-muted">
+								{item.sublabel}
+							</span>
+						{/if}
+					</div>
+				{/each}
+			{/if}
+		</div>
+	{/if}
+</div>

package/dist/ui/command-bar/command-bar.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { CommandBarItem } from './types.js';
+type $$ComponentProps = {
+    /** The root view. */
+    items: CommandBarItem[];
+    placeholder?: string;
+    /** Empty-state message when the filter matches nothing. */
+    empty?: string;
+    /** Global binding(s) that focus the bar (tinykeys grammar, e.g.
+     *  `['`', 'Escape']`). While another field has focus only Escape
+     *  acts — it blurs that field instead of stealing the caret. */
+    hotkey?: string | string[];
+    class?: string;
+};
+declare const CommandBar: import("svelte").Component<$$ComponentProps, {
+    focusInput: () => void;
+}, "">;
+type CommandBar = ReturnType<typeof CommandBar>;
+export default CommandBar;

package/dist/ui/command-bar/index.d.ts

@@ -0,0 +1,2 @@
+export { default as CommandBar } from './command-bar.svelte';
+export type { CommandBarItem } from './types.js';

package/dist/ui/command-bar/index.js

@@ -0,0 +1 @@
+export { default as CommandBar } from './command-bar.svelte';

package/dist/ui/command-bar/types.d.ts

@@ -0,0 +1,20 @@
+import type { Component } from 'svelte';
+import type { IconProps } from '@lucide/svelte';
+/** One row of a CommandBar view. Selecting it runs `onSelect`; if it has
+ *  `items` it's a drill-in view instead (Tab/Space/Enter descends into it,
+ *  Backspace at an empty input pops back out). */
+export interface CommandBarItem {
+    /** Stable id, also matched by the filter. */
+    value: string;
+    label: string;
+    keywords?: string[];
+    /** Right-aligned muted description. */
+    sublabel?: string;
+    /** Emoji/text or a Lucide component. */
+    icon?: Component<IconProps> | string;
+    onSelect?: () => void;
+    /** Sub-view items — makes this a drill-in segment. */
+    items?: CommandBarItem[];
+    /** Placeholder shown while this sub-view is open. */
+    placeholder?: string;
+}

package/dist/ui/command-bar/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/index.d.ts

@@ -10,6 +10,7 @@ export * as Checkbox from './checkbox/index.js';
 export * as Combobox from './combobox/index.js';
 export * as Collapsible from './collapsible/index.js';
 export * as Command from './command/index.js';
+export * from './command-bar/index.js';
 export * as ContextMenu from './context-menu/index.js';
 export * as DateField from './date-field/index.js';
 export * as DatePicker from './date-picker/index.js';

package/dist/ui/index.js

@@ -10,6 +10,7 @@ export * as Checkbox from './checkbox/index.js';
 export * as Combobox from './combobox/index.js';
 export * as Collapsible from './collapsible/index.js';
 export * as Command from './command/index.js';
+export * from './command-bar/index.js';
 export * as ContextMenu from './context-menu/index.js';
 export * as DateField from './date-field/index.js';
 export * as DatePicker from './date-picker/index.js';

package/dist/utils/hotkeys.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Global hotkeys — a tinykeys-style engine (after Jamie Kyle's tinykeys, MIT).
+ *
+ * Bindings are declared as one central map from binding strings to handlers:
+ *
+ *   <svelte:window use:keys={{ '$mod+k': openPalette, '/': focusSearch }} />
+ *
+ * Grammar: a binding is a space-separated SEQUENCE of presses (chords like
+ * `'g d'` work, with a timeout between presses); each press is
+ * `<mod>+<mod>+<key>`; a parenthesised key `'([1-9])'` matches as a regex
+ * against event.key/code. `$mod` normalises to Meta on Apple platforms and
+ * Control everywhere else. Matching is exact on modifiers — extra held
+ * modifiers make a press NOT match, so `$mod+k` never also fires on
+ * `$mod+shift+k`.
+ */
+export type KeyBindingPress = [mods: string[], key: string | RegExp];
+export type KeyBindingMap = Record<string, (event: KeyboardEvent) => void>;
+export interface KeyBindingOptions {
+    /** Keyboard event to listen for (default `'keydown'`). */
+    event?: 'keydown' | 'keyup';
+    capture?: boolean;
+    /** ms allowed between presses of a sequence (default 1000). */
+    timeout?: number;
+}
+/** SSR-safe platform sniff — resolved lazily so importing this module never
+ *  touches `navigator` on the server. */
+export declare function isApplePlatform(): boolean;
+/** What `$mod` means here: `'Meta'` (⌘) on Apple platforms, `'Control'` else. */
+export declare function modKey(): 'Meta' | 'Control';
+export declare function parseKeybinding(binding: string): KeyBindingPress[];
+export declare function matchKeyBindingPress(event: KeyboardEvent, [mods, key]: KeyBindingPress): boolean;
+/** One listener that walks the whole map, tracking partial sequence matches. */
+export declare function createKeybindingsHandler(bindings: KeyBindingMap, options?: KeyBindingOptions): (event: Event) => void;
+/** Attach a binding map to a target; returns the unsubscriber. An empty map
+ *  attaches nothing — a consumer with no bindings costs zero per keystroke. */
+export declare function hotkeys(target: Window | HTMLElement, bindings: KeyBindingMap, options?: KeyBindingOptions): () => void;
+/** Svelte action form — `<svelte:window use:keys={{ '$mod+k': open }} />`. */
+export declare function keys(node: Window | HTMLElement, bindings: KeyBindingMap): {
+    update(next: KeyBindingMap): void;
+    destroy(): void;
+};
+/** Is the user currently typing somewhere? The standard guard for global
+ *  focus-stealing hotkeys — shared so every consumer agrees on what counts
+ *  as a text-entry context. */
+export declare function isTextEntryFocused(): boolean;
+/** Format one binding for display: `'$mod+k'` → `⌘K` on Apple, `Ctrl+K`
+ *  elsewhere. Sequences join with spaces (`'g d'` → `G D`). */
+export declare function formatKeybinding(binding: string): string;

package/dist/utils/hotkeys.js

@@ -0,0 +1,142 @@
+/**
+ * Global hotkeys — a tinykeys-style engine (after Jamie Kyle's tinykeys, MIT).
+ *
+ * Bindings are declared as one central map from binding strings to handlers:
+ *
+ *   <svelte:window use:keys={{ '$mod+k': openPalette, '/': focusSearch }} />
+ *
+ * Grammar: a binding is a space-separated SEQUENCE of presses (chords like
+ * `'g d'` work, with a timeout between presses); each press is
+ * `<mod>+<mod>+<key>`; a parenthesised key `'([1-9])'` matches as a regex
+ * against event.key/code. `$mod` normalises to Meta on Apple platforms and
+ * Control everywhere else. Matching is exact on modifiers — extra held
+ * modifiers make a press NOT match, so `$mod+k` never also fires on
+ * `$mod+shift+k`.
+ */
+const MODIFIER_KEYS = ['Shift', 'Meta', 'Alt', 'Control'];
+const DEFAULT_TIMEOUT = 1000;
+/** SSR-safe platform sniff — resolved lazily so importing this module never
+ *  touches `navigator` on the server. */
+export function isApplePlatform() {
+    if (typeof navigator === 'undefined')
+        return false;
+    const platform = navigator.userAgentData?.platform ??
+        navigator.platform;
+    return /mac|iphone|ipad|ipod/i.test(platform);
+}
+/** What `$mod` means here: `'Meta'` (⌘) on Apple platforms, `'Control'` else. */
+export function modKey() {
+    return isApplePlatform() ? 'Meta' : 'Control';
+}
+export function parseKeybinding(binding) {
+    return binding
+        .trim()
+        .split(' ')
+        .map((press) => {
+        const parts = press.split(/\b\+/);
+        const rawKey = parts.pop();
+        const key = /^\(.+\)$/.test(rawKey) ? new RegExp(`^${rawKey.slice(1, -1)}$`) : rawKey;
+        const mods = parts.map((mod) => (mod === '$mod' ? modKey() : mod));
+        return [mods, key];
+    });
+}
+function getModifierState(event, mod) {
+    return typeof event.getModifierState === 'function' ? event.getModifierState(mod) : false;
+}
+export function matchKeyBindingPress(event, [mods, key]) {
+    const keyMatches = key instanceof RegExp
+        ? key.test(event.key) || key.test(event.code)
+        : key.toUpperCase() === event.key.toUpperCase() || key === event.code;
+    if (!keyMatches)
+        return false;
+    // Every required modifier must be down…
+    if (mods.some((mod) => !getModifierState(event, mod)))
+        return false;
+    // …and no extra one may be (exact-match kills superset collisions).
+    return !MODIFIER_KEYS.some((mod) => !mods.includes(mod) && key !== mod && getModifierState(event, mod));
+}
+/** One listener that walks the whole map, tracking partial sequence matches. */
+export function createKeybindingsHandler(bindings, options = {}) {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const parsed = Object.entries(bindings).map(([binding, handler]) => [parseKeybinding(binding), handler]);
+    const possible = new Map();
+    let timer = null;
+    return (event) => {
+        if (!(event instanceof KeyboardEvent))
+            return;
+        for (const [sequence, handler] of parsed) {
+            const remaining = possible.get(sequence) ?? sequence;
+            if (matchKeyBindingPress(event, remaining[0])) {
+                if (remaining.length > 1) {
+                    possible.set(sequence, remaining.slice(1));
+                }
+                else {
+                    possible.delete(sequence);
+                    handler(event);
+                }
+            }
+            else if (!MODIFIER_KEYS.includes(event.key)) {
+                // A wrong non-modifier press breaks the sequence (a lone modifier
+                // doesn't — it may be the start of the next press's chord).
+                possible.delete(sequence);
+            }
+        }
+        if (timer)
+            clearTimeout(timer);
+        if (possible.size)
+            timer = setTimeout(() => possible.clear(), timeout);
+    };
+}
+/** Attach a binding map to a target; returns the unsubscriber. An empty map
+ *  attaches nothing — a consumer with no bindings costs zero per keystroke. */
+export function hotkeys(target, bindings, options = {}) {
+    if (Object.keys(bindings).length === 0)
+        return () => { };
+    const handler = createKeybindingsHandler(bindings, options);
+    const event = options.event ?? 'keydown';
+    target.addEventListener(event, handler, { capture: options.capture });
+    return () => target.removeEventListener(event, handler, { capture: options.capture });
+}
+/** Svelte action form — `<svelte:window use:keys={{ '$mod+k': open }} />`. */
+export function keys(node, bindings) {
+    let off = hotkeys(node, bindings);
+    return {
+        update(next) {
+            off();
+            off = hotkeys(node, next);
+        },
+        destroy() {
+            off();
+        }
+    };
+}
+/** Is the user currently typing somewhere? The standard guard for global
+ *  focus-stealing hotkeys — shared so every consumer agrees on what counts
+ *  as a text-entry context. */
+export function isTextEntryFocused() {
+    if (typeof document === 'undefined')
+        return false;
+    const el = document.activeElement;
+    return (el instanceof HTMLElement &&
+        (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.isContentEditable));
+}
+const APPLE_GLYPHS = {
+    Meta: '⌘',
+    Alt: '⌥',
+    Shift: '⇧',
+    Control: '⌃'
+};
+/** Format one binding for display: `'$mod+k'` → `⌘K` on Apple, `Ctrl+K`
+ *  elsewhere. Sequences join with spaces (`'g d'` → `G D`). */
+export function formatKeybinding(binding) {
+    return parseKeybinding(binding)
+        .map(([mods, key]) => {
+        const keyLabel = key instanceof RegExp ? String(key.source) : key.toUpperCase();
+        if (isApplePlatform()) {
+            return [...mods.map((m) => APPLE_GLYPHS[m] ?? m), keyLabel].join('');
+        }
+        const names = mods.map((m) => (m === 'Control' ? 'Ctrl' : m));
+        return [...names, keyLabel].join('+');
+    })
+        .join(' ');
+}

package/dist/utils/index.d.ts

@@ -13,3 +13,4 @@ export type { VariantProps } from 'tailwind-variants';
 export type PartProps<T> = WithoutChildrenOrChild<T> & {
     children?: Snippet;
 };
+export { hotkeys, keys, parseKeybinding, matchKeyBindingPress, createKeybindingsHandler, formatKeybinding, isApplePlatform, modKey, type KeyBindingMap, type KeyBindingPress, type KeyBindingOptions } from './hotkeys.js';

package/dist/utils/index.js

@@ -22,3 +22,4 @@ export function cn(...inputs) {
 }
 /** `tv` preconfigured with this library's tailwind-merge settings. */
 export const tv = createTV({ twMergeConfig });
+export { hotkeys, keys, parseKeybinding, matchKeyBindingPress, createKeybindingsHandler, formatKeybinding, isApplePlatform, modKey } from './hotkeys.js';