@spaethtech/svelte-ui 0.14.0 → 0.15.0

package/.claude/skills/svelte-ui/SKILL.md

@@ -153,7 +153,8 @@ All from `@spaethtech/svelte-ui` (see the shipped `docs/components.md` + `docs/u
 examples):
 
 - **Form:** `Button` `ButtonDropdown` `Input` `Select` `Combobox` `Slider` `List` `TextArea` `Checkbox`
-  `Toggle` `Radio` `Rating` · **`Combobox`** (free-text autocomplete — arbitrary value + suggestions,
+  `Toggle` `Radio` `Rating` (display `average`/`count`, OR `interactive` + `bind:value` star picker
+  with `allowHalf`, click/hover/arrow-keys) · **`Combobox`** (free-text autocomplete — arbitrary value + suggestions,
   client `options` or async `suggest`; vs `Select` which is a closed choice. Composes Input + Popup.) ·
   **`TokenInput`** (multi-value entry — Enter/comma adds a removable `Chip` token, Backspace-on-empty
   removes; `bind:values`, `max`, `allowDuplicates`; FieldChrome.) · **`FileUpload`** (drag-drop + click
@@ -170,20 +171,22 @@ examples):
 - **Specialized inputs:** `PasswordInput` `EmailInput` `SearchInput` `NumberInput` (formatting +
   `percent`/`stepper`/`clamp`/`liveFormat`) `PhoneInput` (stores E.164; dep-free, inject
   `parse`/`format` for per-country)
-- **Date / time:** `DatePicker` `Calendar` `TimePicker` `TimeSpinner` `TimeRangeInput` `DateTimeInput`
-  · **`DateRangePicker`** (start–end range + presets rail; `bind:start`/`bind:end` ISO; composes
-  `Calendar mode="range"` + `Input` + `Popup`. `DatePicker range` is the bare, preset-less variant.)
+- **Date / time:** `DatePicker` `Calendar` `TimePicker` `TimeSpinner` `TimeRangeInput` `DateTimeInput`.
+  For a start–end range use **`DatePicker range`** (`bind:value` = `{ start, end }`) — it composes
+  `Calendar mode="range"`.
 - **Data:** `DataTable` `Query` — driven by the headless layer at **`@spaethtech/svelte-ui/data`**
   (query-language parser/AST, `createGrid`, `DataGrid<T>`, `DataSet`). · **`Pagination`** (standalone
-  pager: numbered buttons + ellipsis, prev/next/first/last, `bind:page`/`bind:perPage`, `total`,
-  `perPageOptions`, `showTotal`; built from `Button`+`Select` — the reusable DataTable footer pager).
+  pager styled like the DataTable footer: tinted band, per-page `Select`, range total, and a
+  `First·Prev·[page]/N·Next·Last` stepper whose indicator is an editable `NumberInput` quick-jump;
+  `bind:page`/`bind:perPage`, `total`, `perPageOptions`, `showEdges`/`showTotal`, `borderless`;
+  `variant` tints band+hover only; built from `Button`+`Select`+`NumberInput`).
 - **Overlays:** `Dialog` (pure modal shell — BYO content; `width`/`height` take any CSS value;
   `onShow(ctx)`/`onHide(ctx)` control focus — set `ctx.autoFocus` to a selector/element/`false`,
   `ctx.restoreFocus` likewise) · `ConfirmDialog` (title + message + Confirm/Cancel, built on Dialog)
   · **`Drawer`** (edge-anchored sliding panel / "sheet"; `side` left/right/top/bottom, `size` CSS
   length, `bind:open`, `dismissible`/`backdrop`; same modal mechanics as Dialog — a pure shell, put a
-  Card inside) · `Popup` `Menu` · `tooltip` (a Svelte `use:` action) · `anchored` (positioning engine)
-- **Navigation:** **`Breadcrumbs`** (trail of `BreadcrumbItem` {`label`,`href`,`onclick`,`icon`}; last =
+  Card inside) · `Popup` `Menu` · **`ContextMenu`** (right-click menu at the pointer; `items` MenuItem[]; on `Menu`) · **`CommandPalette`** (⌘K/Ctrl+K fuzzy command launcher; `bind:open`, `commands` Command[] {`label`,`keywords`,`group`,`icon`,`shortcut`,`disabled`,`onrun`}, global `hotkey` default `"mod+k"`; ↑/↓/Enter/Esc; on `Input`+`Kbd`) · `tooltip` (a Svelte `use:` action) · `anchored` (positioning engine)
+- **Navigation:** **`Tree`** (hierarchical expandable tree — `items` of `TreeNode`; `bind:expanded`/`selected`; roving-tabindex keyboard; ARIA `tree`) · **`Breadcrumbs`** (trail of `BreadcrumbItem` {`label`,`href`,`onclick`,`icon`}; last =
   current page; `maxItems` collapses the middle to a `⋯` Menu; `separator` slot) · `TabStrip` (tabs;
   `size`/`variant`, `gap`/`pad` bordered spacer cells, `height` for a
   fixed-height bar with bottom-aligned tabs, `activeSurface` to flow the active tab into the content
@@ -193,14 +196,14 @@ examples):
   `interactMode` `'hover'|'click'` popouts; `currentPath` active-match (per-item `activeMatch` for
   query-keyed/exact rules); `bind:open`/`bind:api`/`bind:activeMode`; `publishWidthVar` → CSS width var;
   popouts expose `data-sbm-popout`/`data-open`)
-- **Feedback:** `Alert` `Banner` `Badge` `Toaster` + `toast` · **`Spinner`** (indeterminate loading
+- **Feedback:** `Alert` `Banner` `Badge` `Toaster` + `toast` · **`Kbd`** (keyboard keycap; `text`/`keys` combo) · **`Spinner`** (indeterminate loading
   ring; `variant`/`size`, omit `variant` to inherit `currentColor`. `Button` has a `loading` prop that
   renders one in place of its icon and blocks interaction.) · **`Progress`** (horizontal bar;
   determinate `value`/`max` or `indeterminate` sweep; `variant`/`size` = 4/8/12px; `label`/`showValue`.)
   · **`Skeleton`** (neutral loading placeholder; `shape` text/rect/circle, `lines`, `width`/`height`,
   `animate` shimmer. No `variant` — it's absent-content, not a themed surface. Compose to sketch a card.)
 - **Layout:** `Card` `CardHeader` `CardBody` `CardFooter` · **`Grid`** (auto-placed equal-cell grid;
-  `columns` + `gap`) · **`Divider`** (thin `role="separator"` rule; `orientation` h/v, optional inline
+  `columns` + `gap`) · **`ScrollArea`** (themed thin-scrollbar container; `orientation`, `maxHeight`, `variant` thumb) · **`Splitter`** (two resizable panes + draggable divider; `bind:size` %, `orientation`, keyboard) · **`Carousel`** (sliding viewport; `items` + `slide` snippet, `bind:index`, `autoplay`, controls + dots) · **`Stat`** (metric/KPI card — `label`/`value`/`delta` up-down + `icon`; on `Card`) · **`Timeline`** (vertical event list — `items` of `TimelineItem` {`title`,`time`,`description`,`icon`,`variant`}) · **`Divider`** (thin `role="separator"` rule; `orientation` h/v, optional inline
   `label`+`labelAlign`; `--ui-border-color`)
 - **Flow:** **`Stepper`** (linear multi-step indicator — `steps` of `StepItem` {`label`,`description`,
   `icon`}, `bind:current`, `orientation` h/v, `onstep` clickable; done/current/upcoming markers +
@@ -208,7 +211,7 @@ examples):
 - **Disclosure:** **`Disclosure`** (one expand/collapse section; `title`/`header`, `bind:open`, panel
   stays mounted so state is preserved) · **`Accordion`** (coordinated group — `multiple` single/multi,
   `bind:value`; children are `<Disclosure value="…">`, no per-item `bind:open`)
-- **Display / theme:** **`Chip`** (interactive pill — `selected` toggle fill, `removable` ×/`onremove`,
+- **Display / theme:** **`EmptyState`** (zero-data placeholder — icon + title + description + `action`) · **`Chip`** (interactive pill — `selected` toggle fill, `removable` ×/`onremove`,
   `onclick`/`href`, `icon`; the interactive counterpart to display-only `Badge`) · **`Avatar`** (image →
   `name` initials → `icon` → glyph fallback; `size`, `variant` fill, `shape`, `status` dot) +
   **`AvatarGroup`** (overlapped stack; `items`+`max` → `+N`) ·

package/dist/components/Carousel/Carousel.svelte

@@ -0,0 +1,147 @@
+<!--
+/**
+ * Carousel — a sliding, single-item-at-a-time viewport with prev/next controls + dot indicators.
+ * Data-driven (`items` + a `slide` snippet); `bind:index`, optional `autoplay`, `loop`, keyboard.
+ * ARIA carousel roles. Composes `Button`. See Carousel.spec.md.
+ */
+-->
+<script lang="ts" module>
+  import type { Snippet } from "svelte";
+</script>
+
+<script lang="ts" generics="T">
+  import Button from "../Button.svelte";
+  import IconPrev from "~icons/mdi/chevron-left";
+  import IconNext from "~icons/mdi/chevron-right";
+  import type { Variant } from "../../types/variants.js";
+  import { variantToken } from "../../types/variants.js";
+
+  let {
+    items,
+    slide,
+    index = $bindable(0),
+    loop = true,
+    autoplay,
+    controls = true,
+    indicators = true,
+    variant = "primary",
+    ariaLabel = "Carousel",
+    class: cls = "",
+  }: {
+    items: T[];
+    slide: Snippet<[T, number]>;
+    index?: number;
+    loop?: boolean;
+    /** Auto-advance interval in ms; pauses on hover/focus. Omit to disable. */
+    autoplay?: number;
+    controls?: boolean;
+    indicators?: boolean;
+    variant?: Variant;
+    ariaLabel?: string;
+    class?: string;
+  } = $props();
+
+  const n = $derived(items.length);
+  const token = $derived(variantToken[variant]);
+  let paused = $state(false);
+
+  const go = (i: number) => {
+    index = loop ? (i + n) % n : Math.min(Math.max(i, 0), n - 1);
+  };
+  const next = () => go(index + 1);
+  const prev = () => go(index - 1);
+
+  $effect(() => {
+    index = Math.min(Math.max(index, 0), Math.max(0, n - 1));
+  });
+
+  // Autoplay — advances on an interval, paused while hovered/focused.
+  $effect(() => {
+    if (!autoplay || paused || n <= 1) return;
+    const t = setInterval(() => go(index + 1), autoplay);
+    return () => clearInterval(t);
+  });
+
+  function onKeydown(e: KeyboardEvent) {
+    if (e.key === "ArrowLeft") {
+      e.preventDefault();
+      prev();
+    } else if (e.key === "ArrowRight") {
+      e.preventDefault();
+      next();
+    }
+  }
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions a11y_no_noninteractive_tabindex (focusable carousel region for keyboard nav) -->
+<div
+  role="region"
+  aria-roledescription="carousel"
+  aria-label={ariaLabel}
+  tabindex="0"
+  class="relative overflow-hidden rounded-[var(--ui-border-radius)] focus-visible:[outline:2px_solid_color-mix(in_srgb,var(--ui-color-text)_70%,transparent)] {cls}"
+  onkeydown={onKeydown}
+  onmouseenter={() => (paused = true)}
+  onmouseleave={() => (paused = false)}
+  onfocusin={() => (paused = true)}
+  onfocusout={() => (paused = false)}
+>
+  <div
+    class="flex transition-transform duration-300 ease-out"
+    style="transform: translateX(-{index * 100}%);"
+  >
+    {#each items as item, i (i)}
+      <div
+        class="w-full shrink-0"
+        role="group"
+        aria-roledescription="slide"
+        aria-label={`${i + 1} of ${n}`}
+        aria-hidden={i !== index}
+      >
+        {@render slide(item, i)}
+      </div>
+    {/each}
+  </div>
+
+  {#if controls && n > 1}
+    <div class="absolute inset-y-0 left-2 flex items-center">
+      <Button
+        title="Previous"
+        variant="secondary"
+        onclick={prev}
+        disabled={!loop && index === 0}
+        class="!rounded-full shadow"
+      >
+        {#snippet icon()}<IconPrev />{/snippet}
+      </Button>
+    </div>
+    <div class="absolute inset-y-0 right-2 flex items-center">
+      <Button
+        title="Next"
+        variant="secondary"
+        onclick={next}
+        disabled={!loop && index === n - 1}
+        class="!rounded-full shadow"
+      >
+        {#snippet icon()}<IconNext />{/snippet}
+      </Button>
+    </div>
+  {/if}
+
+  {#if indicators && n > 1}
+    <div class="absolute inset-x-0 bottom-2 flex items-center justify-center gap-1.5">
+      {#each items as _, i (i)}
+        <button
+          type="button"
+          aria-label={`Go to slide ${i + 1}`}
+          aria-current={i === index}
+          onclick={() => go(i)}
+          class="h-2 rounded-full transition-all {i === index ? 'w-5' : 'w-2'}"
+          style="background-color: {i === index
+            ? `var(${token})`
+            : 'color-mix(in srgb, var(--ui-color-background) 70%, var(--ui-color-text))'};"
+        ></button>
+      {/each}
+    </div>
+  {/if}
+</div>

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

@@ -0,0 +1,38 @@
+import type { Snippet } from "svelte";
+import type { Variant } from "../../types/variants.js";
+declare function $$render<T>(): {
+    props: {
+        items: T[];
+        slide: Snippet<[T, number]>;
+        index?: number;
+        loop?: boolean;
+        /** Auto-advance interval in ms; pauses on hover/focus. Omit to disable. */
+        autoplay?: number;
+        controls?: boolean;
+        indicators?: boolean;
+        variant?: Variant;
+        ariaLabel?: string;
+        class?: string;
+    };
+    exports: {};
+    bindings: "index";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "index";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Carousel: $$IsomorphicComponent;
+type Carousel<T> = InstanceType<typeof Carousel<T>>;
+export default Carousel;

package/dist/components/Carousel/index.d.ts

@@ -0,0 +1 @@
+export { default as Carousel } from "./Carousel.svelte";

package/dist/components/Carousel/index.js

@@ -0,0 +1 @@
+export { default as Carousel } from "./Carousel.svelte";

package/dist/components/Combobox/Combobox.svelte

@@ -10,9 +10,10 @@
   import Input from "../Input.svelte";
   import Popup from "../Popup.svelte";
   import IconChevronDown from "~icons/mdi/chevron-down";
+  import Spinner from "../Spinner/Spinner.svelte";
   import type { Variant } from "../../types/variants.js";
   import type { Size } from "../../types/sizes.js";
-  import type { Responsive } from "../../types/responsive.js";
+  import { responsiveClasses, type Responsive } from "../../types/responsive.js";
 
   let {
     value = $bindable(""),
@@ -65,6 +66,10 @@
   let fieldEl = $state<HTMLDivElement>();
   let inputEl = $state<HTMLInputElement>();
   let asyncResults = $state<string[]>([]);
+  let loading = $state(false);
+  // Monotonic request id — a later query invalidates the results of any earlier in-flight one, so a
+  // slow response can't clobber a newer, faster one (out-of-order race).
+  let reqSeq = 0;
 
   // Suggestions: async `suggest` (debounced) or client-side substring filter of `options`.
   const filtered = $derived.by(() => {
@@ -78,23 +83,37 @@
     return maxResults != null ? out.slice(0, maxResults) : out;
   });
 
-  // Debounced async fetch — re-runs as `value` changes; gated by `minChars`.
+  // Debounced async fetch — re-runs as `value` changes; gated by `minChars`. Sets `loading` for the
+  // whole debounce→resolve window so the field shows feedback (otherwise the delay reads as "broken").
   $effect(() => {
     if (!suggest) return;
     const q = value;
     if (q.trim().length < minChars) {
       asyncResults = [];
+      loading = false;
       return;
     }
+    const seq = ++reqSeq;
+    loading = true;
     const t = setTimeout(() => {
       suggest(q)
-        .then((r) => (asyncResults = r))
-        .catch(() => (asyncResults = []));
+        .then((r) => {
+          if (seq !== reqSeq) return; // a newer query superseded this one
+          asyncResults = r;
+          loading = false;
+        })
+        .catch(() => {
+          if (seq !== reqSeq) return;
+          asyncResults = [];
+          loading = false;
+        });
     }, debounceMs);
     return () => clearTimeout(t);
   });
 
-  const canOpen = $derived(open && !disabled && filtered.length > 0);
+  // Open the popup while loading too, so the "Loading…" row can show during the async fetch.
+  const canOpen = $derived(open && !disabled && (filtered.length > 0 || loading));
+  const optionText = $derived(responsiveClasses(size, { sm: "text-xs", md: "text-sm", lg: "text-base" }));
 
   function choose(v: string) {
     value = v;
@@ -166,14 +185,20 @@
   }}
 >
   {#snippet actions()}
-    <span
-      class="inline-flex items-center justify-center opacity-60 transition-transform duration-150 {canOpen
-        ? 'rotate-180'
-        : ''} [&_svg]:w-4 [&_svg]:h-4"
-      aria-hidden="true"
-    >
-      <IconChevronDown />
-    </span>
+    {#if loading}
+      <span class="inline-flex items-center justify-center opacity-70" aria-hidden="true">
+        <Spinner size="sm" />
+      </span>
+    {:else}
+      <span
+        class="inline-flex items-center justify-center opacity-60 transition-transform duration-150 {canOpen
+          ? 'rotate-180'
+          : ''} [&_svg]:w-4 [&_svg]:h-4"
+        aria-hidden="true"
+      >
+        <IconChevronDown />
+      </span>
+    {/if}
   {/snippet}
 </Input>
 
@@ -181,25 +206,31 @@
   <ul
     id={listId}
     role="listbox"
-    class="max-h-64 overflow-y-auto rounded-md border shadow-lg [background-color:var(--ui-color-background)] [color:var(--ui-color-text)] [border-color:var(--ui-border-color)] py-1"
+    class="max-h-64 overflow-y-auto rounded-md border shadow-lg [background-color:var(--ui-color-background)] [color:var(--ui-color-text)] [border-color:var(--ui-border-color)] py-1 {optionText}"
   >
-    {#each filtered as opt, i (opt + i)}
-      <!-- svelte-ignore a11y_click_events_have_key_events -->
-      <li
-        id={optId(i)}
-        role="option"
-        aria-selected={i === highlight}
-        class="cursor-pointer px-3 py-1.5 text-sm {i === highlight
-          ? '[background-color:var(--ui-color-hover)]'
-          : ''} hover:[background-color:var(--ui-color-hover)]"
-        onpointerdown={(e) => {
-          e.preventDefault(); // keep input focused so the click lands before blur closes the list
-          choose(opt);
-        }}
-        onpointerenter={() => (highlight = i)}
-      >
-        {opt}
+    {#if filtered.length === 0 && loading}
+      <li class="flex items-center gap-2 px-3 py-1.5 [color:color-mix(in_srgb,var(--ui-color-text)_60%,transparent)]" aria-hidden="true">
+        <Spinner size="sm" /> Loading…
       </li>
-    {/each}
+    {:else}
+      {#each filtered as opt, i (opt + i)}
+        <!-- svelte-ignore a11y_click_events_have_key_events -->
+        <li
+          id={optId(i)}
+          role="option"
+          aria-selected={i === highlight}
+          class="cursor-pointer px-3 py-1.5 {i === highlight
+            ? '[background-color:var(--ui-color-hover)]'
+            : ''} hover:[background-color:var(--ui-color-hover)]"
+          onpointerdown={(e) => {
+            e.preventDefault(); // keep input focused so the click lands before blur closes the list
+            choose(opt);
+          }}
+          onpointerenter={() => (highlight = i)}
+        >
+          {opt}
+        </li>
+      {/each}
+    {/if}
   </ul>
 </Popup>

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

@@ -1,7 +1,7 @@
 import type { Snippet } from "svelte";
 import type { Variant } from "../../types/variants.js";
 import type { Size } from "../../types/sizes.js";
-import type { Responsive } from "../../types/responsive.js";
+import { type Responsive } from "../../types/responsive.js";
 type $$ComponentProps = {
     value?: string;
     options?: string[];

package/dist/components/CommandPalette/CommandPalette.svelte

@@ -0,0 +1,203 @@
+<!--
+/**
+ * CommandPalette — a ⌘K/Ctrl+K fuzzy command launcher: a top-centered overlay with a search `Input`
+ * and a filtered, grouped, keyboard-navigable command list. `bind:open`, a global `hotkey`, per-command
+ * `shortcut` (shown as `Kbd`). Portals to <body> (scroll-lock + backdrop + focus). See spec.
+ */
+-->
+<script lang="ts" module>
+  import type { Snippet } from "svelte";
+  export type Command = {
+    id?: string;
+    label: string;
+    keywords?: string[];
+    group?: string;
+    icon?: Snippet;
+    shortcut?: string[];
+    disabled?: boolean;
+    onrun: () => void;
+  };
+</script>
+
+<script lang="ts">
+  import Input from "../Input.svelte";
+  import Kbd from "../Kbd/Kbd.svelte";
+  import IconSearch from "~icons/mdi/magnify";
+
+  let {
+    open = $bindable(false),
+    commands,
+    hotkey = "mod+k",
+    placeholder = "Type a command or search…",
+    empty = "No matching commands",
+    onopen,
+  }: {
+    open?: boolean;
+    commands: Command[];
+    /** Global open hotkey — `mod` = ⌘ on macOS, Ctrl elsewhere. Set `""` to disable. */
+    hotkey?: string;
+    placeholder?: string;
+    empty?: string;
+    onopen?: () => void;
+  } = $props();
+
+  let query = $state("");
+  let highlight = $state(0);
+  let inputEl = $state<HTMLInputElement>();
+  let previouslyFocused: HTMLElement | null = null;
+
+  const isMac =
+    typeof navigator !== "undefined" && /mac|iphone|ipad/i.test(navigator.platform || navigator.userAgent);
+
+  const filtered = $derived.by(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return commands;
+    return commands.filter(
+      (c) =>
+        c.label.toLowerCase().includes(q) ||
+        (c.keywords ?? []).some((k) => k.toLowerCase().includes(q)),
+    );
+  });
+  // Group in first-seen order for rendering; `filtered` is the flat list the highlight indexes into.
+  const groups = $derived.by(() => {
+    const map = new Map<string, Command[]>();
+    for (const c of filtered) {
+      const g = c.group ?? "";
+      (map.get(g) ?? map.set(g, []).get(g)!).push(c);
+    }
+    return [...map.entries()].map(([name, items]) => ({ name, items }));
+  });
+
+  function portal(node: HTMLElement) {
+    document.body.appendChild(node);
+    return { destroy: () => node.remove() };
+  }
+
+  // Global hotkey — toggles open. `mod+k` → ⌘K (mac) / Ctrl+K.
+  function onGlobalKey(e: KeyboardEvent) {
+    if (!hotkey) return;
+    const parts = hotkey.toLowerCase().split("+");
+    const key = parts[parts.length - 1];
+    const needMod = parts.includes("mod");
+    const modOk = needMod ? (isMac ? e.metaKey : e.ctrlKey) : true;
+    if (modOk && e.key.toLowerCase() === key) {
+      e.preventDefault();
+      open = !open;
+    }
+  }
+
+  // On open: remember focus, reset query/highlight, focus the input. On close: restore focus.
+  $effect(() => {
+    if (!open) return;
+    previouslyFocused = document.activeElement as HTMLElement | null;
+    query = "";
+    highlight = 0;
+    onopen?.();
+    const sbw = window.innerWidth - document.documentElement.clientWidth;
+    const prevOverflow = document.body.style.overflow;
+    const prevPad = document.body.style.paddingRight;
+    document.body.style.overflow = "hidden";
+    if (sbw > 0) document.body.style.paddingRight = `${sbw}px`;
+    queueMicrotask(() => inputEl?.focus());
+    return () => {
+      document.body.style.overflow = prevOverflow;
+      document.body.style.paddingRight = prevPad;
+      previouslyFocused?.focus?.();
+    };
+  });
+  // Keep the highlight in range as the filter changes.
+  $effect(() => {
+    if (highlight > filtered.length - 1) highlight = Math.max(0, filtered.length - 1);
+  });
+
+  function run(c: Command | undefined) {
+    if (!c || c.disabled) return;
+    open = false;
+    c.onrun();
+  }
+  function onKeydown(e: KeyboardEvent) {
+    const len = filtered.length;
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      if (len) highlight = (highlight + 1) % len;
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      if (len) highlight = (highlight - 1 + len) % len;
+    } else if (e.key === "Enter") {
+      e.preventDefault();
+      run(filtered[highlight]);
+    } else if (e.key === "Escape") {
+      e.preventDefault();
+      open = false;
+    }
+  }
+</script>
+
+<svelte:window onkeydown={onGlobalKey} />
+
+{#if open}
+  <!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
+  <div use:portal class="fixed inset-0 z-[9999] flex justify-center bg-black/40 p-4 pt-[12vh]" role="presentation"
+    onclick={(e) => { if (e.target === e.currentTarget) open = false; }}>
+    <div
+      class="h-max w-full max-w-xl overflow-hidden rounded-[var(--ui-border-radius)] border shadow-2xl [background-color:var(--ui-color-background)] [border-color:var(--ui-border-color)]"
+      role="dialog"
+      aria-modal="true"
+      aria-label="Command palette"
+    >
+      <Input
+        bind:value={query}
+        bind:element={inputEl}
+        {placeholder}
+        borderless
+        icon={searchIcon}
+        iconPosition="left"
+        role="combobox"
+        aria-expanded="true"
+        aria-controls="cmdp-list"
+        aria-activedescendant={filtered.length ? `cmdp-opt-${highlight}` : undefined}
+        onkeydown={onKeydown}
+        class="[&_input]:h-12 border-b [border-color:var(--ui-border-color)] rounded-none"
+      />
+
+      <ul id="cmdp-list" role="listbox" class="max-h-80 overflow-y-auto p-1">
+        {#if filtered.length === 0}
+          <li class="px-3 py-8 text-center text-sm [color:color-mix(in_srgb,var(--ui-color-text)_55%,transparent)]">
+            {empty}
+          </li>
+        {:else}
+          {#each groups as g (g.name)}
+            {#if g.name}
+              <li class="px-3 pb-1 pt-3 text-xs font-medium uppercase tracking-wide [color:color-mix(in_srgb,var(--ui-color-text)_45%,transparent)]">
+                {g.name}
+              </li>
+            {/if}
+            {#each g.items as c (c.id ?? c.label)}
+              {@const idx = filtered.indexOf(c)}
+              <li>
+                <!-- svelte-ignore a11y_click_events_have_key_events -->
+                <div
+                  id={`cmdp-opt-${idx}`}
+                  role="option"
+                  aria-selected={idx === highlight}
+                  aria-disabled={c.disabled || undefined}
+                  onclick={() => run(c)}
+                  onpointermove={() => (highlight = idx)}
+                  class="flex cursor-pointer items-center gap-3 rounded-[var(--ui-border-radius)] px-3 py-2 text-sm {c.disabled
+                    ? 'opacity-40'
+                    : ''} {idx === highlight ? '[background-color:var(--ui-color-hover)]' : ''}"
+                >
+                  {#if c.icon}<span class="inline-flex shrink-0 [&_svg]:w-4 [&_svg]:h-4 [color:var(--ui-color-secondary)]">{@render c.icon()}</span>{/if}
+                  <span class="min-w-0 flex-1 truncate [color:var(--ui-color-text)]">{c.label}</span>
+                  {#if c.shortcut}<Kbd keys={c.shortcut} size="sm" />{/if}
+                </div>
+              </li>
+            {/each}
+          {/each}
+        {/if}
+      </ul>
+    </div>
+  </div>
+{/if}
+
+{#snippet searchIcon()}<IconSearch />{/snippet}

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

@@ -0,0 +1,23 @@
+import type { Snippet } from "svelte";
+export type Command = {
+    id?: string;
+    label: string;
+    keywords?: string[];
+    group?: string;
+    icon?: Snippet;
+    shortcut?: string[];
+    disabled?: boolean;
+    onrun: () => void;
+};
+type $$ComponentProps = {
+    open?: boolean;
+    commands: Command[];
+    /** Global open hotkey — `mod` = ⌘ on macOS, Ctrl elsewhere. Set `""` to disable. */
+    hotkey?: string;
+    placeholder?: string;
+    empty?: string;
+    onopen?: () => void;
+};
+declare const CommandPalette: import("svelte").Component<$$ComponentProps, {}, "open">;
+type CommandPalette = ReturnType<typeof CommandPalette>;
+export default CommandPalette;

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

@@ -0,0 +1,2 @@
+export { default as CommandPalette } from "./CommandPalette.svelte";
+export type { Command } from "./CommandPalette.svelte";

package/dist/components/CommandPalette/index.js

@@ -0,0 +1 @@
+export { default as CommandPalette } from "./CommandPalette.svelte";