npm - @noxlovette/material - Versions diffs - 0.8.3 → 0.9.1 - Mend

@noxlovette/material 0.8.3 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (53) hide show

package/claude-skill/material-design/SKILL.md +1 -1
package/claude-skill/material-design/references/component-patterns.md +36 -1
package/dist/animation/presence.svelte.js +37 -1
package/dist/animation/sharedAxisTransition.d.ts +2 -1
package/dist/animation/sharedAxisTransition.js +19 -1
package/dist/components/buttons/FAB.svelte +4 -1
package/dist/components/buttons/theme.d.ts +6 -3
package/dist/components/buttons/theme.js +3 -2
package/dist/components/containers/context-menu/theme.js +4 -4
package/dist/components/containers/list/theme.js +1 -1
package/dist/components/containers/menu/Menu.svelte +2 -5
package/dist/components/containers/menu/theme.js +4 -2
package/dist/components/containers/pane/theme.js +1 -1
package/dist/components/date/theme.js +1 -1
package/dist/components/forms/command/Command.mdx +90 -0
package/dist/components/forms/command/Command.stories.svelte +69 -10
package/dist/components/forms/command/Command.stories.svelte.d.ts +2 -17
package/dist/components/forms/command/CommandDialog.svelte +58 -0
package/dist/components/forms/command/CommandDialog.svelte.d.ts +11 -0
package/dist/components/forms/command/CommandItem.svelte +48 -5
package/dist/components/forms/command/CommandItem.svelte.d.ts +4 -0
package/dist/components/forms/command/index.d.ts +1 -0
package/dist/components/forms/command/index.js +1 -0
package/dist/components/forms/command/theme.d.ts +371 -6
package/dist/components/forms/command/theme.js +32 -1
package/dist/components/forms/command/types.d.ts +27 -1
package/dist/components/forms/search/Search.mdx +9 -0
package/dist/components/forms/search/Search.stories.svelte +14 -2
package/dist/components/forms/search/Search.svelte +41 -9
package/dist/components/forms/search/Search.svelte.d.ts +3 -0
package/dist/components/forms/search/SearchView.svelte +57 -6
package/dist/components/forms/search/SearchView.svelte.d.ts +4 -2
package/dist/components/forms/search/theme.js +4 -2
package/dist/components/forms/search/types.d.ts +14 -1
package/dist/components/forms/slider/theme.js +1 -1
package/dist/components/nav/appbar/AppBar.stories.svelte +30 -2
package/dist/components/nav/appbar/AppBar.svelte +40 -8
package/dist/components/nav/appbar/theme.js +1 -1
package/dist/components/nav/appbar/types.d.ts +14 -0
package/dist/components/nav/navbar/theme.js +1 -1
package/dist/components/nav/rail/Rail.mdx +6 -0
package/dist/components/nav/rail/Rail.svelte +55 -1
package/dist/components/nav/rail/Rail.svelte.d.ts +3 -0
package/dist/components/nav/rail/theme.js +1 -1
package/dist/components/nav/rail/types.d.ts +7 -0
package/dist/components/toolbar/theme.js +4 -1
package/dist/styles/motion.css +26 -0
package/dist/utils/Layer.svelte +3 -1
package/dist/utils/index.d.ts +1 -0
package/dist/utils/index.js +1 -0
package/dist/utils/shortcut.d.ts +26 -0
package/dist/utils/shortcut.js +84 -0
package/package.json +1 -1

package/claude-skill/material-design/SKILL.md CHANGED Viewed

@@ -66,6 +66,6 @@ This repo is a single, already-opinionated M3 component library, not a blank can
 ## References
 - [`references/tokens-and-styles.md`](references/tokens-and-styles.md) — full token/utility inventory
-- [`references/component-patterns.md`](references/component-patterns.md) — `tv()` slots/variants/compoundVariants pattern + variant decision tree
+- [`references/component-patterns.md`](references/component-patterns.md) — `tv()` slots/variants/compoundVariants pattern + variant decision tree; search vs command palette; page-wide keyboard shortcuts
 - [`references/motion-guide.md`](references/motion-guide.md) — applying transitions (qualities of a good transition, choosing a pattern), which animation primitive and spring to reach for, reduced-motion target behavior
 - [`references/accessibility-checklist.md`](references/accessibility-checklist.md) — pre-delivery checklist

package/claude-skill/material-design/references/component-patterns.md CHANGED Viewed

@@ -26,7 +26,7 @@ Only fall back to `bare` (no color/background at all) when the component supplie
 ## Reuse before you build
-- **State layer / ripple** — wrap the interactive element with `Layer.svelte` (`src/lib/utils/Layer.svelte`) rather than writing hover/press opacity by hand. It listens for `.m3-layer` on its parent, already respects `prefers-reduced-motion` for the ripple, and its tint (hover 0.08, focus and pressed 0.10) matches the M3 state-layer tokens — don't retune those numbers per component.
+- **State layer / ripple** — wrap the interactive element with `Layer.svelte` (`src/lib/utils/Layer.svelte`) rather than writing hover/press opacity by hand. It listens for `.m3-layer` on its parent, already respects `prefers-reduced-motion` for the ripple, and its tint (hover 0.08, focus and pressed 0.10) matches the M3 state-layer tokens — don't retune those numbers per component. Its tint only reacts to real `:hover`/`:focus-visible`/`:active`, and no Tailwind class can drive it (its CSS is unlayered and beats `@layer utilities`). For a highlight that follows an attribute while focus stays elsewhere (a combobox's `data-selected`/`data-highlighted` option), fill the item: `data-selected:bg-md-sys-color-on-surface/10`, as menus and `commandItem` do.
 - **Icons** — always `Icon.svelte`, never a raw `<span class="material-symbols-...">` or an inline SVG for a Material Symbol.
   - `name` is typed (`MaterialSymbolName`), so a typo is a type error. A `string[]` of names needs `as const` or `satisfies MaterialSymbolName[]`.
   - Show state with `fill` (0 → 1 on the selected item; it animates), not a weight change.
@@ -71,6 +71,41 @@ See `/docs/pane` in the showcase site for the full prop reference and worked exa
 A viewport-anchored `Rail` publishes `--md-rail-inset` on `<html>`: 0 below `md`, the collapsed 96dp on medium windows (the expanded rail is modal there and overlays), and its live width from `lg` (it pushes content, in step with its spring). `App`'s shell pads by it and `AppBar` starts at it. Never add `md:ml-24` or similar to a page, a `PaneGrid` or an app bar. A custom shell uses `ps-(--md-rail-inset)`; another fixed surface spanning the window uses `left-(--md-rail-inset)`. A rail with `anchor="parent"` renders a spacer beside itself instead, so it and its content go in a flex row.
+## Search, command palette and keyboard shortcuts
+Two components take a typed query over a list. Pick by what the user is looking for, not by
+looks:
+| The user wants to…                                            | Component                                    | Why                                                                                                                                                    |
+| ------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Find **content** (records, pages, products, people)           | `Search` with `results` (or search `AppBar`) | M3 search. The app filters (you render `results`), Enter with nothing highlighted calls `onsearch(query)`, the query stays in the bar                  |
+| **Do** something or **go** somewhere (commands, destinations) | `CommandDialog` + `CommandItem`s             | Not M3; built from M3 parts. bits-ui filters and ranks, the best match is always highlighted so Enter always runs one, the query is discarded on close |
+| A central search entry point in a page body, not the top bar  | `Search` placed in the page                  | The view docks where the bar sits (medium+) or goes full-screen (compact); it doesn't need an `AppBar`                                                 |
+Don't make the palette the app's search: it can't search for exactly what was typed, and it only
+filters items already rendered. Don't fill a search view with actions. Having both is normal; a
+palette may end with a "Search for “…”" item that hands the query to search.
+Page-wide keys, all built on `src/lib/utils/shortcut.ts` (`triggersShortcut`, `matchesShortcut`,
+`ariaKeyShortcut`, `shortcutLabel`), each on by default and off with `null`:
+| Key              | Component                 | Prop                          |
+| ---------------- | ------------------------- | ----------------------------- |
+| `/`              | `Search`, search `AppBar` | `shortcut` / `searchShortcut` |
+| ⌘K / Ctrl+K      | `CommandDialog`           | `shortcut`                    |
+| ⌘1–⌘9 / Ctrl+1–9 | `Rail` (Nth destination)  | `shortcutModifier`            |
+- Write shortcuts like `aria-keyshortcuts`, with `Mod` for ⌘ on Apple and Ctrl elsewhere
+  (`'Mod+K'`). Never bind the Windows/Super key: the OS owns it.
+- A new page-wide shortcut goes through `triggersShortcut(e, shortcut, ownerEl)` on
+  `<svelte:window onkeydown>`. It already skips bare keys while typing in a field, IME
+  composition, repeats, and any open modal the owner isn't inside. Set `aria-keyshortcuts` on the
+  control it activates, resolving `Mod` on the client (`isApplePlatform()` in an `$effect`) so SSR
+  and hydration agree.
+- One owner per key per page: with two `Search` bars, pass `shortcut={null}` to all but one.
+- Show a shortcut with `shortcutLabel()` (`⌘K` / `Ctrl+K`), e.g. in a `Kbd` or `CommandItem`'s
+  `shortcut`.
 ## Before exporting a new component
 Follow CLAUDE.md's "Adding a New Component" steps as the mechanical checklist (create `.svelte` + `types.ts`, define `theme.ts` with `tv()`, export from the category `index.ts`, run `bun scripts/generate-components-index.ts`, add a showcase route and a docs page) — this skill governs the _design_ decisions (which variant/color/motion) that should be made before or while writing that `theme.ts`, not the export mechanics themselves.

package/dist/animation/presence.svelte.js CHANGED Viewed

@@ -27,12 +27,14 @@ const fromTo = (from, to) => Object.fromEntries(Object.entries(to).map(([key, va
 export const presence = (isOpen, transition, onExitComplete) => (node) => {
     let controls;
     let started = false;
+    let settleTimer;
     if (transition.origin)
         node.style.transformOrigin = transition.origin;
     $effect(() => {
         const open = isOpen();
         untrack(() => {
             const { hidden, shown, exited = hidden, enter, exit } = transition;
+            clearTimeout(settleTimer);
             if (open) {
                 controls = animate(node, started ? shown : fromTo(hidden, shown), enter);
             }
@@ -42,11 +44,45 @@ export const presence = (isOpen, transition, onExitComplete) => (node) => {
                     if (controls === current)
                         onExitComplete?.();
                 });
+                settleTimer = setTimeout(() => {
+                    if (controls === current)
+                        settle(node);
+                }, exitDeadline(current));
             }
             started = true;
         });
     });
-    return () => controls?.stop();
+    return () => {
+        clearTimeout(settleTimer);
+        controls?.stop();
+    };
+};
+/*
+  bits-ui unmounts its content only once every animation on it has settled, and `Presence` once
+  Motion's exit resolves. On touch devices a closed menu was reported staying mounted, one per
+  open, stacking up (#53): some animation on the node never settled. So once the exit has had its
+  time, whatever is still running or paused there is finished (or cancelled, if it can't be),
+  which settles bits-ui's wait and the exit's promise.
+*/
+const EXIT_DEADLINE_MARGIN_MS = 150;
+const EXIT_DEADLINE_FALLBACK_MS = 1000;
+const exitDeadline = (controls) => {
+    const seconds = controls.duration;
+    return Number.isFinite(seconds) && seconds > 0
+        ? seconds * 1000 + EXIT_DEADLINE_MARGIN_MS
+        : EXIT_DEADLINE_FALLBACK_MS;
+};
+const settle = (node) => {
+    for (const animation of node.getAnimations?.() ?? []) {
+        if (animation.playState === 'finished')
+            continue;
+        try {
+            animation.finish();
+        }
+        catch {
+            animation.cancel();
+        }
+    }
 };
 /**
  * Keeps an element mounted until its exit animation finishes — the Motion replacement for a

package/dist/animation/sharedAxisTransition.d.ts CHANGED Viewed

@@ -64,7 +64,8 @@ export declare const lateral: (update: () => void | Promise<void>, { target, axi
  * instead of `lateral` there.
  *
  * Not built into `Navbar`/`Rail`: they don't own the content region that changes, so the app wraps
- * its own route change in this.
+ * its own route change in this. They, the AppBar and a docked Toolbar stay still and on top while
+ * it runs; give a fixed floating Toolbar or FAB the `md-vt-persist` class for the same (motion.css).
  *
  * The `target` region swaps its box instantly instead of sliding or resizing to the new page's:
  * that movement would be exactly the spatial connection this pattern avoids, and after a

package/dist/animation/sharedAxisTransition.js CHANGED Viewed

@@ -2,8 +2,25 @@ import { animateView } from 'motion';
 import { prefersReducedMotion } from './reducedMotion.js';
 import { springTokens, springTransition } from './spring.js';
 const SHARED_AXIS_OFFSET_PX = 30;
+/* While a navigation transition runs, `.md-vt-persist` chrome (Navbar, Rail, AppBar, …) gets
+   its own static layer above the page's (motion.css). Counted, since transitions queue. */
+const NAVIGATING = 'md-navigation-transition';
+let navigating = 0;
+const markNavigating = (builder) => {
+    const root = document.documentElement;
+    navigating++;
+    root.classList.add(NAVIGATING);
+    new Promise((resolve, reject) => builder.then ? builder.then(resolve, reject) : resolve(undefined))
+        .then((animation) => animation?.finished)
+        .catch(() => { })
+        .finally(() => {
+        if (--navigating === 0)
+            root.classList.remove(NAVIGATING);
+    });
+};
 const view = (update, target, spring) => {
     const builder = animateView(update, springTransition(spring));
+    markNavigating(builder);
     return target ? builder.add(target) : builder;
 };
 /* Outgoing content clears quickly; incoming content waits a beat so the two never overlap fully.
@@ -117,7 +134,8 @@ export const lateral = (update, { target, axis = 'x', direction = 'forward', spr
  * instead of `lateral` there.
  *
  * Not built into `Navbar`/`Rail`: they don't own the content region that changes, so the app wraps
- * its own route change in this.
+ * its own route change in this. They, the AppBar and a docked Toolbar stay still and on top while
+ * it runs; give a fixed floating Toolbar or FAB the `md-vt-persist` class for the same (motion.css).
  *
  * The `target` region swaps its box instantly instead of sliding or resizing to the new page's:
  * that movement would be exactly the spatial connection this pattern avoids, and after a

package/dist/components/buttons/FAB.svelte CHANGED Viewed

@@ -343,7 +343,10 @@ Floating action buttons (FABs) help people take primary actions.
         surfaceOpen && 'invisible',
         // In its footprint, pinned to the top trailing corner the close button shares.
         withMenu &&
-          neverExpanded && ['col-start-1 row-start-1 self-start justify-self-end', footprint[size]],
+          neverExpanded && [
+            'col-start-1 row-start-1 self-start justify-self-end',
+            !open && footprint[size]
+          ],
         className
       )
     })}

package/dist/components/buttons/theme.d.ts CHANGED Viewed

@@ -443,7 +443,8 @@ export declare const fab: import("tailwind-variants").TVReturnType<{
     };
     /**
      * The FAB menu's open state: the FAB becomes the round close button, label shut. Its size and
-     * corners spring to 56dp round in FAB.svelte.
+     * corners spring to 56dp round in FAB.svelte; the classes hold that box once the spring
+     * settles, so the button can't fall back to its content width (#49: a 24×56 pill).
      */
     menuOpen: {
         true: {
@@ -509,7 +510,8 @@ export declare const fab: import("tailwind-variants").TVReturnType<{
     };
     /**
      * The FAB menu's open state: the FAB becomes the round close button, label shut. Its size and
-     * corners spring to 56dp round in FAB.svelte.
+     * corners spring to 56dp round in FAB.svelte; the classes hold that box once the spring
+     * settles, so the button can't fall back to its content width (#49: a 24×56 pill).
      */
     menuOpen: {
         true: {
@@ -575,7 +577,8 @@ export declare const fab: import("tailwind-variants").TVReturnType<{
     };
     /**
      * The FAB menu's open state: the FAB becomes the round close button, label shut. Its size and
-     * corners spring to 56dp round in FAB.svelte.
+     * corners spring to 56dp round in FAB.svelte; the classes hold that box once the spring
+     * settles, so the button can't fall back to its content width (#49: a 24×56 pill).
      */
     menuOpen: {
         true: {

package/dist/components/buttons/theme.js CHANGED Viewed

@@ -276,11 +276,12 @@ export const fab = tv({
         },
         /**
          * The FAB menu's open state: the FAB becomes the round close button, label shut. Its size and
-         * corners spring to 56dp round in FAB.svelte.
+         * corners spring to 56dp round in FAB.svelte; the classes hold that box once the spring
+         * settles, so the button can't fall back to its content width (#49: a 24×56 pill).
          */
         menuOpen: {
             true: {
-                base: 'justify-center px-spacing-0',
+                base: 'justify-center px-spacing-0 size-spacing-700 rounded-[1.75rem]',
                 icon: 'size-spacing-250 text-[20px]',
                 labelTrack: 'grid-cols-[0fr]!'
             },

package/dist/components/containers/context-menu/theme.js CHANGED Viewed

@@ -2,7 +2,7 @@ import { tv } from '../../../utils/tv.js';
 export const contextMenu = tv({
     slots: {
         content: `
-      z-layer-popup min-w-48 max-w-sm gap-spacing-50 overflow-y-auto rounded-lg
+      z-layer-popup outline-none min-w-48 max-w-sm gap-spacing-50 overflow-y-auto rounded-lg
       bg-md-sys-color-surface-container-high px-spacing-100 py-spacing-50
       shadow-elevation-3 ring-md-sys-color-outline/10
     `,
@@ -10,14 +10,14 @@ export const contextMenu = tv({
       rounded-sm relative flex w-full cursor-pointer select-none items-center gap-spacing-100
       px-spacing-150 py-spacing-100 text-left md-sys-typescale-body-large text-md-sys-color-on-surface
       outline-none transition-colors md-sys-motion-fast-effects
-      hover:bg-md-sys-color-on-surface/8 data-[highlighted]:bg-md-sys-color-on-surface/8
+      data-[highlighted]:bg-md-sys-color-on-surface/8
       data-[disabled]:cursor-not-allowed data-[disabled]:opacity-38
     `,
         subTrigger: `
       rounded-sm relative flex w-full cursor-pointer select-none items-center gap-spacing-100
       px-spacing-150 py-spacing-100 text-left md-sys-typescale-body-large text-md-sys-color-on-surface
       outline-none transition-colors md-sys-motion-fast-effects
-      hover:bg-md-sys-color-on-surface/8 data-[state=open]:bg-md-sys-color-on-surface/8
+      data-[state=open]:bg-md-sys-color-on-surface/8
       data-[highlighted]:bg-md-sys-color-on-surface/8
       data-[disabled]:cursor-not-allowed data-[disabled]:opacity-38
     `,
@@ -36,7 +36,7 @@ export const contextMenu = tv({
         },
         color: {
             error: {
-                item: 'text-md-sys-color-error hover:bg-md-sys-color-error/8 data-[highlighted]:bg-md-sys-color-error/8',
+                item: 'text-md-sys-color-error data-[highlighted]:bg-md-sys-color-error/8',
                 icon: 'text-md-sys-color-error'
             }
         }

package/dist/components/containers/list/theme.js CHANGED Viewed

@@ -71,7 +71,7 @@ export const listItem = tv({
                     'cursor-pointer outline-none',
                     'hover:[--li-shape:0.75rem]',
                     'focus-visible:[--li-shape:1rem]',
-                    'focus-visible:outline-3 focus-visible:-outline-offset-3 focus-visible:outline-md-sys-color-secondary',
+                    'focus-visible:outline-solid focus-visible:outline-3 focus-visible:-outline-offset-3 focus-visible:outline-md-sys-color-secondary',
                     'active:[--li-shape:1rem]'
                 ]
             },

package/dist/components/containers/menu/Menu.svelte CHANGED Viewed

@@ -20,6 +20,7 @@ Contrast with `MenuItem` (a single interactive row inside the panel) and
   import { DropdownMenu } from 'bits-ui';
   import clsx from 'clsx';
   import Button from '../../buttons/Button.svelte';
+  import { menu } from './theme.js';
   import type { MenuProps } from './types.js';
   let {
@@ -49,11 +50,7 @@ Contrast with `MenuItem` (a single interactive row inside the panel) and
         <div {...wrapperProps} class={wrapperProps.class as any}>
           <div
             {...props}
-            class={clsx(
-              'bg-md-sys-color-surface-container-high shadow-elevation-3 ring-md-sys-color-outline/10 gap-spacing-50 px-spacing-100 py-spacing-50 max-w-sm min-w-48 overflow-y-auto rounded-lg',
-              props.class as any,
-              contentClass
-            )}
+            class={clsx(menu().content(), props.class as any, contentClass)}
             {@attach presence(() => isOpen, enterExit.scale)}
           >
             {@render children()}

package/dist/components/containers/menu/theme.js CHANGED Viewed

@@ -4,12 +4,14 @@ export const menu = tv({
         content: `
       bg-md-sys-color-surface-container-high shadow-elevation-3
       ring-md-sys-color-outline/10 max-w-sm min-w-48 gap-spacing-50
-      overflow-y-auto rounded-lg px-spacing-100 py-spacing-50
+      overflow-y-auto rounded-lg px-spacing-100 py-spacing-50 outline-none
     `,
+        // No `hover:` fill: bits-ui sets `data-highlighted` on mouse hover already,
+        // and a `:hover` tint sticks to the last-tapped row on touch screens (#48).
         item: `
       rounded-sm h-11 relative flex w-full cursor-pointer items-center gap-spacing-100 px-spacing-150 py-spacing-100
       md-sys-typescale-body-medium whitespace-nowrap text-md-sys-color-on-surface
-      hover:bg-md-sys-color-on-surface/8 data-[highlighted]:bg-md-sys-color-on-surface/8
+      data-[highlighted]:bg-md-sys-color-on-surface/8
       focus-visible:outline-2 focus-visible:outline-offset-2
       focus-visible:outline-md-sys-color-primary
       data-[disabled]:cursor-not-allowed data-[disabled]:opacity-38

package/dist/components/containers/pane/theme.js CHANGED Viewed

@@ -218,7 +218,7 @@ export const pane = tv({
  */
 export const paneHandle = tv({
     slots: {
-        base: 'group relative flex shrink-0 w-spacing-150 self-stretch cursor-col-resize touch-none items-center justify-center rounded-full bg-transparent outline-none hover:bg-md-sys-color-outline/20 focus-visible:outline-2 focus-visible:outline-md-sys-color-secondary',
+        base: 'group relative flex shrink-0 w-spacing-150 self-stretch cursor-col-resize touch-none items-center justify-center rounded-full bg-transparent outline-none hover:bg-md-sys-color-outline/20 focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-md-sys-color-secondary',
         // Size is sprung inline by PaneHandle.svelte; only color transitions here.
         grip: 'rounded-full transition-colors md-sys-motion-effects'
     },

package/dist/components/date/theme.js CHANGED Viewed

@@ -286,7 +286,7 @@ export const dateCalendar = tv({
       cursor-pointer outline-none
       transition-colors md-sys-motion-fast-effects
-      focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-md-sys-color-secondary
+      focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-md-sys-color-secondary
       data-today:border data-today:border-md-sys-color-primary data-today:text-md-sys-color-primary

package/dist/components/forms/command/Command.mdx ADDED Viewed

@@ -0,0 +1,90 @@
+import { Meta, Title, Subtitle, Canvas, Controls, ArgTypes } from '@storybook/addon-docs/blocks';
+import * as CommandStories from './Command.stories.svelte';
+import CommandItem from './CommandItem.svelte';
+import CommandDialog from './CommandDialog.svelte';
+<Meta of={CommandStories} />
+<Title />
+<Subtitle>
+  A command palette: type to filter a known set of actions and destinations, then run one.
+</Subtitle>
+`import { Command, CommandDialog, CommandInput, CommandList, CommandGroup, CommandItem, CommandEmpty, CommandSeparator } from '@noxlovette/material';`
+Not an M3 component. M3 has no command palette, so this one is assembled from M3 parts: the
+items are M3 list items, and `CommandDialog` takes the docked search view's width (360–720dp), a
+modal dialog's scrim, extra-large shape and enter/exit motion. Filtering, ranking and keyboard
+navigation come from bits-ui's `Command`.
+<Canvas of={CommandStories.Playground} />
+<Controls of={CommandStories.Playground} />
+## Search or command palette?
+They look alike, a field over a list, but they answer different questions. Use both in one app
+if it has both kinds of need.
+|                       | `Search` (bar + search view)                                                    | `CommandDialog` (palette)                                         |
+| --------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Answers               | "Where is the thing that matches this?"                                         | "What do I want to do, or where do I want to go?"                 |
+| Items                 | App content: open-ended, often fetched, rich rows                               | A finite, known set of actions and destinations                   |
+| Filtering             | Yours: you render the matches in `results`                                      | The component's: bits-ui scores and sorts the items               |
+| Enter, nothing picked | Searches for the query as typed (`onsearch`)                                    | Can't happen: the best match is always highlighted, Enter runs it |
+| The query             | Stays in the bar; it's part of the page's state                                 | Thrown away on close                                              |
+| Where it lives        | On the page or in the search `AppBar`, visible                                  | Nowhere until summoned; one per app                               |
+| Page-wide key         | `/`                                                                             | ⌘K (Ctrl+K off Apple platforms)                                   |
+| M3                    | [Search](https://m3.material.io/components/search/overview), spec'd with motion | None; built from M3 parts                                         |
+Rules of thumb:
+- **Content goes in search, commands go in the palette.** "Invoices from March" is a search.
+  "New invoice", "Go to settings", "Toggle dark theme" are commands.
+- **Don't use the palette as the app's search.** Its first match is always highlighted, so it
+  can't search for exactly what was typed, and its filter only sees items already rendered.
+- **Don't use search as a launcher.** A search view's suggestions are content, and a bar
+  on every page for actions is the wrong emphasis.
+- **Both at once is fine.** A palette can end with a "Search for “…”" item that hands the query
+  to search.
+## Items
+Each `CommandItem` is an M3 list item: its children are the headline, with an optional `leading`
+icon, `supporting` second line, and `trailingText`. `shortcut` shows a keyboard shortcut at the end,
+labelled for the platform (`⌘,` on a Mac, `Ctrl+,` elsewhere). It's only shown; bind the key
+yourself.
+```svelte
+<CommandItem value="settings" shortcut="Mod+," onSelect={openSettings}>
+  {#snippet leading()}<Icon name="settings" />{/snippet}
+  Settings
+</CommandItem>
+```
+The highlighted item, from the arrow keys or the pointer, takes a focused item's look: a 10%
+on-surface fill and the 12dp shape. Focus itself stays in the input.
+<ArgTypes of={CommandItem} />
+## Dialog
+`CommandDialog` wraps `Command` in a modal overlay opened with ⌘K from anywhere, including from
+inside a text field. ⌘K again, Esc or a click on the scrim closes it. Close it yourself from an
+item's `onSelect` (`bind:open`). `shortcut` changes the keys; `null` turns them off.
+<Canvas of={CommandStories.Dialog} />
+<ArgTypes of={CommandDialog} />
+## Accessibility
+- **Combobox.** The input is a `combobox` over the `listbox`, with `aria-activedescendant` on the
+  highlighted item, so screen readers follow the arrow keys while focus stays in the field.
+- **Dialog.** `CommandDialog` is a modal dialog named by `label` (default "Command palette") and
+  keeps focus inside while open.
+- **Shortcut.** ⌘K doesn't fire while another modal dialog is open, so it never opens on top of
+  a search view or a confirmation dialog.
+- **Keys.** ↑/↓ move through the items, Home/End jump to the first and last, Enter runs the
+  highlighted one.

package/dist/components/forms/command/Command.stories.svelte CHANGED Viewed

@@ -7,18 +7,27 @@
   import CommandGroup from './CommandGroup.svelte';
   import CommandItem from './CommandItem.svelte';
   import CommandSeparator from './CommandSeparator.svelte';
+  import CommandDialog from './CommandDialog.svelte';
+  import Kbd from '../../typography/kbd/Kbd.svelte';
+  import Button from '../../buttons/Button.svelte';
+  import { shortcutLabel } from '../../../utils/shortcut.js';
   import Icon from '../../../utils/icon/Icon.svelte';
-  import { command } from './theme.js';
-  const { itemIcon } = command();
   const { Story } = defineMeta({
     title: 'Forms/Command',
-    tags: ['autodocs'],
     component: Command
   });
 </script>
+<script lang="ts">
+  let paletteOpen = $state(false);
+  let ran = $state('');
+  const run = (name: string) => {
+    ran = name;
+    paletteOpen = false;
+  };
+</script>
 <Story name="Playground" asChild>
   <div class="w-96">
     <Command>
@@ -27,30 +36,30 @@
         <CommandEmpty>No results found.</CommandEmpty>
         <CommandGroup heading="Suggestions">
           <CommandItem value="calendar">
-            <Icon name="calendar_today" class={itemIcon()} />
+            {#snippet leading()}<Icon name="calendar_today" />{/snippet}
             Calendar
           </CommandItem>
           <CommandItem value="search-emoji">
-            <Icon name="mood" class={itemIcon()} />
+            {#snippet leading()}<Icon name="mood" />{/snippet}
             Search Emoji
           </CommandItem>
           <CommandItem value="calculator">
-            <Icon name="calculate" class={itemIcon()} />
+            {#snippet leading()}<Icon name="calculate" />{/snippet}
             Calculator
           </CommandItem>
         </CommandGroup>
         <CommandSeparator />
         <CommandGroup heading="Settings">
           <CommandItem value="profile">
-            <Icon name="person" class={itemIcon()} />
+            {#snippet leading()}<Icon name="person" />{/snippet}
             Profile
           </CommandItem>
           <CommandItem value="billing">
-            <Icon name="credit_card" class={itemIcon()} />
+            {#snippet leading()}<Icon name="credit_card" />{/snippet}
             Billing
           </CommandItem>
           <CommandItem value="settings">
-            <Icon name="settings" class={itemIcon()} />
+            {#snippet leading()}<Icon name="settings" />{/snippet}
             Settings
           </CommandItem>
         </CommandGroup>
@@ -59,6 +68,56 @@
   </div>
 </Story>
+<!--
+  Press ⌘K (Ctrl+K off Apple platforms) anywhere in the story, or the button. Arrow keys move the
+  highlight, Enter runs the command, Esc or ⌘K again closes it.
+-->
+<Story
+  name="Dialog"
+  asChild
+  parameters={{ layout: 'fullscreen', docs: { story: { inline: false, height: '520px' } } }}
+>
+  <div
+    class="gap-spacing-200 p-spacing-300 md-sys-typescale-body-medium text-md-sys-color-on-surface flex min-h-dvh flex-col items-start"
+  >
+    <Button variant="tonal" onclick={() => (paletteOpen = true)}>
+      Open the palette <Kbd position="relative">{shortcutLabel('Mod+K')}</Kbd>
+    </Button>
+    <p class="text-md-sys-color-on-surface-variant">{ran ? `Ran: ${ran}` : 'Nothing run yet'}</p>
+    <CommandDialog bind:open={paletteOpen}>
+      <CommandInput placeholder="Type a command or search..." />
+      <CommandList>
+        <CommandEmpty>No results found.</CommandEmpty>
+        <CommandGroup heading="Suggestions">
+          <CommandItem value="calendar" onSelect={() => run('Calendar')}>
+            {#snippet leading()}<Icon name="calendar_today" />{/snippet}
+            Calendar
+          </CommandItem>
+          <CommandItem value="calculator" onSelect={() => run('Calculator')}>
+            {#snippet leading()}<Icon name="calculate" />{/snippet}
+            Calculator
+          </CommandItem>
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="Settings">
+          <CommandItem
+            value="profile"
+            supporting="Name, photo and email"
+            onSelect={() => run('Profile')}
+          >
+            {#snippet leading()}<Icon name="person" />{/snippet}
+            Profile
+          </CommandItem>
+          <CommandItem value="settings" shortcut="Mod+," onSelect={() => run('Settings')}>
+            {#snippet leading()}<Icon name="settings" />{/snippet}
+            Settings
+          </CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </CommandDialog>
+  </div>
+</Story>
 <Story name="Empty State" asChild>
   <div class="w-96">
     <Command>

package/dist/components/forms/command/Command.stories.svelte.d.ts CHANGED Viewed

@@ -1,19 +1,4 @@
 import Command from './Command.svelte';
-interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
-    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
-        $$bindings?: Bindings;
-    } & Exports;
-    (internal: unknown, props: {
-        $$events?: Events;
-        $$slots?: Slots;
-    }): Exports & {
-        $set?: any;
-        $on?: any;
-    };
-    z_$$bindings?: Bindings;
-}
-declare const Command: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
-    [evt: string]: CustomEvent<any>;
-}, {}, {}, string>;
-type Command = InstanceType<typeof Command>;
+declare const Command: import("svelte").Component<Record<string, never>, {}, "">;
+type Command = ReturnType<typeof Command>;
 export default Command;

package/dist/components/forms/command/CommandDialog.svelte ADDED Viewed

@@ -0,0 +1,58 @@
+<!--
+@component
+A command palette: a `Command` in a modal overlay, opened from anywhere with ⌘K (Ctrl+K off Apple
+platforms). The same keys close it again, as do Esc and a click on the scrim.
+Put `CommandInput`, `CommandList` and the rest inside it, as with `Command`, and close it from an
+item's `onSelect` (`bind:open`).
+-->
+<script lang="ts">
+  import { Dialog } from 'bits-ui';
+  import clsx from 'clsx';
+  import { enterExit, presence } from '../../../animation/index.js';
+  import { triggersShortcut } from '../../../utils/index.js';
+  import Command from './Command.svelte';
+  import { commandDialog } from './theme.js';
+  import type { CommandDialogProps } from './types.js';
+  let {
+    open = $bindable(false),
+    value = $bindable(''),
+    shortcut = 'Mod+K',
+    label = 'Command palette',
+    children,
+    class: className,
+    ...restProps
+  }: CommandDialogProps = $props();
+  const s = commandDialog();
+  let content = $state<HTMLElement | null>(null);
+  function onShortcut(e: KeyboardEvent) {
+    if (!triggersShortcut(e, shortcut, open ? content : null)) return;
+    e.preventDefault();
+    open = !open;
+  }
+</script>
+<svelte:window onkeydown={onShortcut} />
+<Dialog.Root bind:open>
+  <Dialog.Portal>
+    <Dialog.Overlay>
+      {#snippet child({ props, open: isOpen })}
+        <div {...props} class={s.scrim()} {@attach presence(() => isOpen, enterExit.fade)}></div>
+      {/snippet}
+    </Dialog.Overlay>
+    <Dialog.Content bind:ref={content}>
+      {#snippet child({ props, open: isOpen })}
+        <div {...props} class={s.content()} {@attach presence(() => isOpen, enterExit.dialog)}>
+          <Dialog.Title class="sr-only">{label}</Dialog.Title>
+          <Command {...restProps} bind:value class={s.command({ class: clsx(className) })}>
+            {@render children()}
+          </Command>
+        </div>
+      {/snippet}
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog.Root>

package/dist/components/forms/command/CommandDialog.svelte.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+import type { CommandDialogProps } from './types.js';
+/**
+ * A command palette: a `Command` in a modal overlay, opened from anywhere with ⌘K (Ctrl+K off Apple
+ * platforms). The same keys close it again, as do Esc and a click on the scrim.
+ *
+ * Put `CommandInput`, `CommandList` and the rest inside it, as with `Command`, and close it from an
+ * item's `onSelect` (`bind:open`).
+ */
+declare const CommandDialog: import("svelte").Component<CommandDialogProps, {}, "value" | "open">;
+type CommandDialog = ReturnType<typeof CommandDialog>;
+export default CommandDialog;