@spectral_labs/ui 1.6.1 → 1.7.0

package/dist/components/command/__tests__/CommandInlineDirectTest.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+  import CommandInput from '../components/command-input.svelte'
+  import CommandItem from '../components/command-item.svelte'
+  import CommandList from '../components/command-list.svelte'
+  import CommandRoot from '../components/command-root.svelte'
+
+  /**
+   * The same inline composition with NO `Command.Group`.
+   *
+   * The group and the item each gate rendering on their own predicate, and
+   * both read the registry. Reviewing #224 turned up two distinct failures
+   * behind one symptom, so the group must be removable from the picture for a
+   * test to say which mechanism it is exercising.
+   */
+  let open = $state(false)
+  let value = $state('')
+
+  export function setOpen(next: boolean) {
+    open = next
+  }
+</script>
+
+<CommandRoot mode="inline" bind:open bind:value>
+  <CommandInput class="probe-input" />
+  <CommandList>
+    <CommandItem value="copy" keywords={['duplicate']}>Copy</CommandItem>
+    <CommandItem value="paste">Paste</CommandItem>
+  </CommandList>
+</CommandRoot>

package/dist/components/command/__tests__/CommandInlineTest.svelte

@@ -0,0 +1,89 @@
+<script lang="ts">
+  import type { CommandMode } from '../command.svelte.js'
+  import CommandEmpty from '../components/command-empty.svelte'
+  import CommandGroup from '../components/command-group.svelte'
+  import CommandInput from '../components/command-input.svelte'
+  import CommandItem from '../components/command-item.svelte'
+  import CommandList from '../components/command-list.svelte'
+  import CommandRoot from '../components/command-root.svelte'
+
+  type Entry = { value: string; label: string; keywords?: string[] }
+
+  /**
+   * Harness for the `inline` composition: a field that outlives its results.
+   *
+   * The harness OWNS `open` and `entries` as local state and exposes accessors,
+   * rather than taking them as props a test would try to reassign — Svelte 5
+   * props are not writable through the object `mount()` returns. Owning them
+   * here is also closer to real use: `bind:open` lets the Root push a close
+   * back (Escape, outside pointer) and the test observes the same value the
+   * consumer would.
+   *
+   * `entries` is mutable so a test can change the COLLECTION between two
+   * openings — the case where a stale selection, a dead ARIA reference or a
+   * lost first arrow would actually show up.
+   */
+  const {
+    initialOpen = false,
+    initialEntries = [
+      { value: 'copy', label: 'Copy', keywords: ['duplicate'] },
+      { value: 'paste', label: 'Paste' },
+      { value: 'cut', label: 'Cut' },
+    ] as Entry[],
+    mode = 'inline' as CommandMode,
+    portalTo = undefined,
+    trapFocus = undefined,
+    onOpenChange = undefined,
+    onEscapeKeydown = undefined,
+    onSelect = undefined,
+    inputAttrs = undefined,
+  }: {
+    initialOpen?: boolean
+    initialEntries?: Entry[]
+    mode?: CommandMode
+    portalTo?: HTMLElement | string
+    trapFocus?: boolean
+    onOpenChange?: (open: boolean) => void
+    onEscapeKeydown?: (event: KeyboardEvent) => void
+    onSelect?: (value: string) => void
+    inputAttrs?: Record<string, unknown>
+  } = $props()
+
+  let open = $state(initialOpen)
+  let entries = $state(initialEntries)
+  let value = $state('')
+  let element = $state<HTMLInputElement | null>(null)
+
+  export function setOpen(next: boolean) {
+    open = next
+  }
+  export function getOpen() {
+    return open
+  }
+  export function setEntries(next: Entry[]) {
+    entries = next
+  }
+  export function getElement() {
+    return element
+  }
+</script>
+
+<CommandRoot bind:value bind:open {mode} {portalTo} {trapFocus} {onOpenChange} {onEscapeKeydown}>
+  <CommandInput
+    placeholder="Search..."
+    wrapperClass="probe-wrapper"
+    class="probe-input"
+    bind:element
+    {...inputAttrs ?? {}}
+  />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Actions">
+      {#each entries as entry (entry.value)}
+        <CommandItem value={entry.value} keywords={entry.keywords} {onSelect}>
+          {entry.label}
+        </CommandItem>
+      {/each}
+    </CommandGroup>
+  </CommandList>
+</CommandRoot>

package/dist/components/command/__tests__/command-inline.test.svelte.js

@@ -0,0 +1,392 @@
+import { flushSync, mount, unmount } from 'svelte';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { EscapeLayerState, resetEscapeLayerStack } from '../../../internal/escape-layer/index.js';
+import CommandInlineDirectTest from './CommandInlineDirectTest.svelte';
+import CommandInlineTest from './CommandInlineTest.svelte';
+/**
+ * `mode: 'inline'` — a persistent field with non-modal results.
+ *
+ * The contract these pins defend is not "the list is hidden": it is that a
+ * CLOSED palette is inert. It executes nothing, it claims no key, it holds no
+ * slot in the global layer stacks, and it names no option that is not on
+ * screen. `modal` is the default and must come through untouched.
+ */
+if (typeof globalThis.PointerEvent === 'undefined') {
+    // @ts-expect-error — minimal polyfill for testing
+    globalThis.PointerEvent = class PointerEvent extends MouseEvent {
+        constructor(type, init) {
+            super(type, init);
+        }
+    };
+}
+describe('command — inline mode', () => {
+    let target;
+    let instance;
+    function setup(props = {}) {
+        target = document.createElement('div');
+        document.body.appendChild(target);
+        instance = mount(CommandInlineTest, { target, props });
+        flushSync();
+        return target;
+    }
+    afterEach(() => {
+        if (instance)
+            unmount(instance);
+        instance = undefined;
+        target?.remove();
+        resetEscapeLayerStack();
+        document.body.innerHTML = '';
+    });
+    const input = () => target.querySelector('input.probe-input');
+    const options = () => [...target.querySelectorAll('[data-command-item]')];
+    const activeId = () => input().getAttribute('aria-activedescendant');
+    function press(key, init = {}) {
+        const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...init });
+        input().dispatchEvent(event);
+        flushSync();
+        return event;
+    }
+    function type(text) {
+        const el = input();
+        el.value = text;
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        flushSync();
+    }
+    // --- The field outlives the results ------------------------------------
+    it('closed: the field is rendered and NO option is', () => {
+        setup({ initialOpen: false });
+        expect(input()).toBeTruthy();
+        expect(options()).toHaveLength(0);
+        expect(target.querySelector('[role="listbox"]')).toBeNull();
+    });
+    it('closed: aria-expanded is false, and the relations that would dangle are absent', () => {
+        setup({ initialOpen: false });
+        expect(input().getAttribute('aria-expanded')).toBe('false');
+        expect(input().getAttribute('aria-controls')).toBeNull();
+        expect(activeId()).toBeNull();
+    });
+    it('the SAME input element survives a close and a reopen — never a second field', () => {
+        setup({ initialOpen: true });
+        const first = input();
+        instance.setOpen(false);
+        flushSync();
+        expect(options()).toHaveLength(0);
+        const whileClosed = input();
+        instance.setOpen(true);
+        flushSync();
+        // Node identity, not a lookalike: a remounted field would lose focus,
+        // selection and any consumer `bind:element` reference.
+        expect(whileClosed).toBe(first);
+        expect(input()).toBe(first);
+    });
+    it('exposes the real input element through `bind:element`, with no internal selector', () => {
+        setup({ initialOpen: false });
+        expect(instance.getElement()).toBe(input());
+        instance.getElement().focus();
+        expect(document.activeElement).toBe(input());
+    });
+    // --- A closed palette claims nothing -----------------------------------
+    it('closed: Enter executes nothing and is NOT prevented — it belongs to the page', () => {
+        const onSelect = vi.fn();
+        setup({ initialOpen: false, onSelect });
+        const event = press('Enter');
+        expect(onSelect).not.toHaveBeenCalled();
+        expect(event.defaultPrevented).toBe(false);
+    });
+    it('closed: a third-party Escape layer mounted FIRST still receives the key', () => {
+        const onEscapeKeydown = vi.fn();
+        // Mounted BEFORE the palette, so it sits at the BOTTOM of the stack. The
+        // stack offers the keystroke to the topmost 'close' layer and stops there:
+        // a palette that illicitly kept its layer while closed would be above this
+        // one and would swallow the key. Mounted after, it would win either way
+        // and the test would pass on a broken implementation.
+        const other = new EscapeLayerState({ enabled: true, onEscapeKeydown });
+        other.mount();
+        setup({ initialOpen: false });
+        const event = press('Escape');
+        expect(onEscapeKeydown).toHaveBeenCalledTimes(1);
+        expect(event.defaultPrevented).toBe(false);
+        other.unmount();
+    });
+    it('open: the palette DOES take the key from a layer mounted before it — the test above discriminates', () => {
+        const onEscapeKeydown = vi.fn();
+        const other = new EscapeLayerState({ enabled: true, onEscapeKeydown });
+        other.mount();
+        setup({ initialOpen: true });
+        press('Escape');
+        // Same order, results open: the palette is topmost and answers, so the
+        // previous test really observes the layer being absent, not the ordering.
+        expect(onEscapeKeydown).not.toHaveBeenCalled();
+        expect(instance.getOpen()).toBe(false);
+        other.unmount();
+    });
+    it('closed: Home and End stay with the caret — native editing is preserved', () => {
+        setup({ initialOpen: false });
+        expect(press('Home').defaultPrevented).toBe(false);
+        expect(press('End').defaultPrevented).toBe(false);
+    });
+    it('closed: an arrow OPENS the results instead of moving an unseen selection', () => {
+        const onOpenChange = vi.fn();
+        setup({ initialOpen: false, onOpenChange });
+        const event = press('ArrowDown');
+        expect(event.defaultPrevented).toBe(true);
+        expect(onOpenChange).toHaveBeenCalledWith(true);
+        expect(instance.getOpen()).toBe(true);
+        flushSync();
+        expect(options().length).toBeGreaterThan(0);
+    });
+    // --- Open: the engine is the one that shipped ---------------------------
+    it('open: keyword filtering still decides — a term absent from the label finds the option', () => {
+        setup({ initialOpen: true });
+        type('duplicate');
+        const values = options().map((el) => el.dataset.value);
+        expect(values).toEqual(['copy']);
+    });
+    it('open: arrow then Enter activates the option exactly ONCE', () => {
+        const onSelect = vi.fn();
+        setup({ initialOpen: true, onSelect });
+        press('ArrowDown');
+        const selected = options().find((el) => el.dataset.selected === 'true');
+        press('Enter');
+        expect(onSelect).toHaveBeenCalledTimes(1);
+        expect(onSelect).toHaveBeenCalledWith(selected.dataset.value);
+    });
+    it('open: aria-activedescendant names the rendered option’s DOM id, never its value', () => {
+        setup({ initialOpen: true });
+        const selected = options().find((el) => el.dataset.selected === 'true');
+        expect(activeId()).toBe(selected.id);
+        expect(activeId()).not.toBe(selected.dataset.value);
+        // And it resolves to a node that is really in the document.
+        expect(document.getElementById(activeId())).toBe(selected);
+        expect(input().getAttribute('aria-controls')).toBe(target.querySelector('[role="listbox"]').id);
+    });
+    // --- The reference cannot outlive what it names -------------------------
+    it('after filtering, the reference follows the surviving option', () => {
+        setup({ initialOpen: true });
+        type('duplicate');
+        const selected = options().find((el) => el.dataset.selected === 'true');
+        expect(selected.dataset.value).toBe('copy');
+        expect(activeId()).toBe(selected.id);
+    });
+    it('when nothing matches, there is no active option and no reference', () => {
+        setup({ initialOpen: true });
+        type('zzzzz');
+        expect(options()).toHaveLength(0);
+        expect(activeId()).toBeNull();
+    });
+    it('removing the active option leaves no dead reference', () => {
+        setup({
+            initialOpen: true,
+            initialEntries: [
+                { value: 'copy', label: 'Copy' },
+                { value: 'paste', label: 'Paste' },
+            ],
+        });
+        expect(options().find((el) => el.dataset.selected === 'true').dataset.value).toBe('copy');
+        // The consumer drops the option that is currently active.
+        instance.setEntries([{ value: 'paste', label: 'Paste' }]);
+        flushSync();
+        const id = activeId();
+        expect(id).not.toBeNull();
+        const named = document.getElementById(id);
+        expect(named).not.toBeNull();
+        expect(named.dataset.value).toBe('paste');
+    });
+    it('reopening after the options changed: no stale selection, no dead reference, no lost first arrow', () => {
+        const onSelect = vi.fn();
+        setup({
+            initialOpen: true,
+            onSelect,
+            initialEntries: [
+                { value: 'copy', label: 'Copy' },
+                { value: 'paste', label: 'Paste' },
+            ],
+        });
+        // Move the selection away from the first option, then close.
+        press('ArrowDown');
+        expect(options().find((el) => el.dataset.selected === 'true').dataset.value).toBe('paste');
+        instance.setOpen(false);
+        flushSync();
+        expect(activeId()).toBeNull();
+        // A completely different collection comes back.
+        instance.setEntries([
+            { value: 'rename', label: 'Rename' },
+            { value: 'delete', label: 'Delete' },
+        ]);
+        instance.setOpen(true);
+        flushSync();
+        const selected = options().find((el) => el.dataset.selected === 'true');
+        // Not the stale `paste`, which no longer exists.
+        expect(selected.dataset.value).toBe('rename');
+        expect(activeId()).toBe(selected.id);
+        // The first arrow MOVES; it is not spent recovering from a stale value.
+        press('ArrowDown');
+        expect(options().find((el) => el.dataset.selected === 'true').dataset.value).toBe('delete');
+        press('Enter');
+        expect(onSelect).toHaveBeenCalledTimes(1);
+        expect(onSelect).toHaveBeenCalledWith('delete');
+    });
+    // --- A retained query must survive a remount (review of #224, [P1]) -----
+    /**
+     * One symptom — zero options after a close and a reopen with the query still
+     * in the field — hiding TWO mechanisms, so each gets its own pin.
+     *
+     *  · `Command.Group` gated its children on `hasVisibleItems()`, a predicate
+     *    over the very registry those children fill. Empty registry + retained
+     *    query ⇒ children never mount ⇒ registry stays empty. A deadlock.
+     *  · An item's `isVisible` reads `getScore()` from a plain Map during
+     *    RENDER, while `registerItem` writes that score from an `$effect`, i.e.
+     *    afterwards. Nothing woke the derived, so a matching item stayed hidden.
+     *
+     * Both make `aria-activedescendant` name a node that is not in the document,
+     * which is why every pin here resolves the id rather than trusting it.
+     */
+    function activeElement() {
+        const id = activeId();
+        return id === null ? null : document.getElementById(id);
+    }
+    it('a query kept across a close and a reopen still renders its match, named and actionable', () => {
+        const onSelect = vi.fn();
+        setup({ initialOpen: true, onSelect });
+        type('duplicate');
+        expect(options().map((el) => el.dataset.value)).toEqual(['copy']);
+        instance.setOpen(false);
+        flushSync();
+        expect(options()).toHaveLength(0);
+        instance.setOpen(true);
+        flushSync();
+        expect(options().map((el) => el.dataset.value)).toEqual(['copy']);
+        // The reference resolves to a node that is really in the document.
+        expect(activeElement()).not.toBeNull();
+        expect(activeElement()).toBe(options()[0]);
+        press('Enter');
+        expect(onSelect).toHaveBeenCalledTimes(1);
+        expect(onSelect).toHaveBeenCalledWith('copy');
+    });
+    it('a query typed while CLOSED renders its match when an arrow opens the list', () => {
+        setup({ initialOpen: false });
+        type('duplicate');
+        expect(options()).toHaveLength(0);
+        press('ArrowDown');
+        expect(options().map((el) => el.dataset.value)).toEqual(['copy']);
+        expect(activeElement()).toBe(options()[0]);
+    });
+    it('same, with NO Command.Group: the item mechanism alone is enough to break it', () => {
+        target = document.createElement('div');
+        document.body.appendChild(target);
+        instance = mount(CommandInlineDirectTest, { target });
+        flushSync();
+        type('duplicate');
+        press('ArrowDown');
+        expect(options().map((el) => el.dataset.value)).toEqual(['copy']);
+        expect(activeElement()).not.toBeNull();
+        expect(activeElement()).toBe(options()[0]);
+    });
+    // --- Event composition --------------------------------------------------
+    it('a consumer onkeydown runs first and its preventDefault cancels the local handling', () => {
+        const onOpenChange = vi.fn();
+        setup({
+            initialOpen: false,
+            onOpenChange,
+            inputAttrs: { onkeydown: (e) => e.preventDefault() },
+        });
+        press('ArrowDown');
+        expect(onOpenChange).not.toHaveBeenCalled();
+        expect(instance.getOpen()).toBe(false);
+    });
+    it('a consumer onkeydown cannot retract a close already performed in the capture phase', () => {
+        const onEscapeKeydown = vi.fn();
+        setup({
+            initialOpen: true,
+            onEscapeKeydown,
+            inputAttrs: { onkeydown: (e) => e.preventDefault() },
+        });
+        press('Escape');
+        // The layer listens on `document` in capture — it read `defaultPrevented`
+        // before the input's handler ever ran. `onEscapeKeydown` is the hook.
+        expect(onEscapeKeydown).toHaveBeenCalledTimes(1);
+        expect(instance.getOpen()).toBe(false);
+    });
+    // --- Anchorable, and no focus trap --------------------------------------
+    it('renders IN PLACE with the inline chrome released, so results can be anchored', () => {
+        setup({ initialOpen: true });
+        const root = target.querySelector('.sp-command');
+        // In place — not portalled to document.body, which would break both the
+        // consumer's scoped CSS and any anchoring to the field.
+        expect(root.parentElement).not.toBe(document.body);
+        expect(target.contains(root)).toBe(true);
+        expect(root.dataset.mode).toBe('inline');
+        // The field and the results share one owner, which is what lets a consumer
+        // anchor the second to the first.
+        const field = root.querySelector('.sp-command-input-wrapper');
+        const list = root.querySelector('[role="listbox"]');
+        expect(field.parentElement).toBe(root);
+        expect(list.parentElement).toBe(root);
+        // Whether the released `overflow` really keeps the list unclipped is a
+        // LAYOUT fact, and this environment has no CSS at all — vite does not load
+        // the components' stylesheets into jsdom. It is proven in a real Chromium
+        // by `tests/e2e/command-inline.spec.ts`, on the docs page's live demo.
+    });
+    it('does not trap focus: an outside control keeps it', () => {
+        setup({ initialOpen: true });
+        const outside = document.createElement('button');
+        document.body.appendChild(outside);
+        outside.focus();
+        flushSync();
+        expect(document.activeElement).toBe(outside);
+        outside.remove();
+    });
+    it('the consumer names the field; the component keeps its structure', () => {
+        setup({
+            initialOpen: true,
+            inputAttrs: {
+                'aria-label': 'Site search',
+                'aria-describedby': 'hint-id',
+                title: 'Search',
+                'data-testid': 'field',
+                // Refused by the type; spread anyway to prove the markup order wins.
+                role: 'textbox',
+                id: 'consumer-id',
+                'aria-expanded': 'false',
+                'aria-activedescendant': 'nope',
+            },
+        });
+        const el = input();
+        // The consumer's naming and description reach the real combobox…
+        expect(el.getAttribute('aria-label')).toBe('Site search');
+        expect(el.getAttribute('aria-describedby')).toBe('hint-id');
+        expect(el.getAttribute('title')).toBe('Search');
+        expect(el.getAttribute('data-testid')).toBe('field');
+        // …while the structure stays the component's, whatever is spread.
+        expect(el.getAttribute('role')).toBe('combobox');
+        expect(el.id).not.toBe('consumer-id');
+        expect(el.getAttribute('aria-expanded')).toBe('true');
+        expect(el.getAttribute('aria-activedescendant')).not.toBe('nope');
+        expect(el.getAttribute('aria-activedescendant')).toBe(options().find((o) => o.dataset.selected === 'true').id);
+    });
+    it('exposes the wrapper through `wrapperClass` while `class` stays on the input', () => {
+        setup({ initialOpen: false });
+        const wrapper = target.querySelector('.sp-command-input-wrapper');
+        expect(wrapper.classList.contains('probe-wrapper')).toBe(true);
+        expect(input().classList.contains('probe-input')).toBe(true);
+        expect(input().classList.contains('probe-wrapper')).toBe(false);
+    });
+    // --- The default mode is untouched --------------------------------------
+    it('modal stays the default: closing unmounts the field itself', () => {
+        // `portalTo` keeps the modal content inside `target` for querying — the
+        // modal default is `document.body`, which is itself part of the contract.
+        target = document.createElement('div');
+        document.body.appendChild(target);
+        instance = mount(CommandInlineTest, {
+            target,
+            props: { mode: 'modal', initialOpen: true, portalTo: target },
+        });
+        flushSync();
+        expect(input()).toBeTruthy();
+        expect(input().getAttribute('aria-expanded')).toBe('true');
+        instance.setOpen(false);
+        flushSync();
+        expect(target.querySelector('input')).toBeNull();
+        expect(target.querySelector('.sp-command')).toBeNull();
+    });
+});

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

@@ -4,6 +4,14 @@
  * Manages search filtering, item scoring, keyboard navigation,
  * and selection for a command palette interface.
  */
+/**
+ * `'modal'` — the shipped behaviour: the Root exists only while open, and
+ * closing unmounts everything, layers included.
+ * `'inline'` — the Root and its field stay mounted; `open` then governs only
+ * whether the RESULTS are rendered, and the Escape / outside-pointer layers
+ * follow the results, never the field.
+ */
+export type CommandMode = 'modal' | 'inline';
 export interface CommandItem {
     id: string;
     value: string;
@@ -18,6 +26,25 @@ export interface CommandState {
     listId: string;
     shouldFilter: boolean;
     loop: boolean;
+    /** Composition mode of the owning Root. */
+    mode: CommandMode;
+    /** Whether the Root currently considers the palette open. */
+    open: boolean;
+    /** Whether a `Command.List` is actually rendered right now. */
+    listMounted: boolean;
+    /** Called by `Command.List` to report its own mount/unmount. */
+    setListMounted: (mounted: boolean) => void;
+    /**
+     * DOM id of the option that is BOTH active and rendered, or `null`.
+     *
+     * Resolved against the live registry — never from the stored selection
+     * alone — so it cannot outlive the option it names: filtering it out,
+     * unmounting the list, or removing the option all make it `null` on the
+     * spot. This is what `aria-activedescendant` reads.
+     */
+    getActiveOptionId: () => string | null;
+    /** Asks the Root to open. No-op when it is already open. */
+    requestOpen: () => void;
     setSearch: (query: string) => void;
     getScore: (value: string) => number;
     filter: (value: string, search: string, keywords?: string[]) => number;
@@ -47,7 +74,10 @@ export declare function createCommandState(options: {
     filter: (value: string, search: string, keywords?: string[]) => number;
     shouldFilter: boolean;
     loop: boolean;
+    mode: CommandMode;
+    open: boolean;
     onSearchChange?: (search: string) => void;
+    onRequestOpen?: () => void;
 }): CommandState;
 export declare function setCommandContext(state: CommandState): void;
 export declare function getCommandContext(): CommandState;

package/dist/components/command/command.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.svelte.d.ts","sourceRoot":"","sources":["../../../src/lib/components/command/command.svelte.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,OAAO,CAAA;IACrB,IAAI,EAAE,OAAO,CAAA;IACb,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACnC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACtE,YAAY,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAA;IACzC,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,gBAAgB,EAAE,MAAM,MAAM,CAAA;IAC9B,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,KAAK,IAAI,CAAA;IACtE,aAAa,EAAE,MAAM,IAAI,CAAA;IACzB,QAAQ,EAAE,MAAM,WAAW,EAAE,CAAA;IAC7B,eAAe,EAAE,MAAM,WAAW,EAAE,CAAA;IACpC,eAAe,EAAE,MAAM,OAAO,CAAA;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAYxF;AA0CD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACtE,YAAY,EAAE,OAAO,CAAA;IACrB,IAAI,EAAE,OAAO,CAAA;IACb,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CAC1C,GAAG,YAAY,CA+Hf;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAE3D;AAED,wBAAgB,iBAAiB,IAAI,YAAY,CAEhD"}
+{"version":3,"file":"command.svelte.d.ts","sourceRoot":"","sources":["../../../src/lib/components/command/command.svelte.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE5C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,OAAO,CAAA;IACrB,IAAI,EAAE,OAAO,CAAA;IACb,2CAA2C;IAC3C,IAAI,EAAE,WAAW,CAAA;IACjB,6DAA6D;IAC7D,IAAI,EAAE,OAAO,CAAA;IACb,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAA;IACpB,gEAAgE;IAChE,cAAc,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;IAC1C;;;;;;;OAOG;IACH,iBAAiB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACtC,4DAA4D;IAC5D,WAAW,EAAE,MAAM,IAAI,CAAA;IACvB,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACnC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACtE,YAAY,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAA;IACzC,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IACpC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAC/B,gBAAgB,EAAE,MAAM,MAAM,CAAA;IAC9B,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,KAAK,IAAI,CAAA;IACtE,aAAa,EAAE,MAAM,IAAI,CAAA;IACzB,QAAQ,EAAE,MAAM,WAAW,EAAE,CAAA;IAC7B,eAAe,EAAE,MAAM,WAAW,EAAE,CAAA;IACpC,eAAe,EAAE,MAAM,OAAO,CAAA;CAC/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAYxF;AA0CD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACtE,YAAY,EAAE,OAAO,CAAA;IACrB,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,WAAW,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;IACb,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAA;CAC3B,GAAG,YAAY,CA6Mf;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAE3D;AAED,wBAAgB,iBAAiB,IAAI,YAAY,CAEhD"}

package/dist/components/command/command.svelte.js

@@ -4,7 +4,7 @@
  * Manages search filtering, item scoring, keyboard navigation,
  * and selection for a command palette interface.
  */
-import { getContext, setContext } from 'svelte';
+import { getContext, setContext, untrack } from 'svelte';
 import { useId } from '../../internal/helpers/index.js';
 const KEY = Symbol('sp-command');
 /**
@@ -76,7 +76,45 @@ export function createCommandState(options) {
     // eslint-disable-next-line svelte/prefer-svelte-reactivity -- internal non-reactive scoring cache
     const scores = new Map();
     let selectedValue = $state('');
+    let listMounted = $state(false);
+    /**
+     * `items` and `scores` are deliberately PLAIN (a hot scoring cache). Anything
+     * derived from the COLLECTION therefore needs an explicit reactive beat, or
+     * removing an option would leave `aria-activedescendant` naming a node that
+     * no longer exists — silently, because no signal changed.
+     */
+    let collectionVersion = $state(0);
+    /**
+     * `registerItem` / `unregisterItem` run from an item's `$effect`. A plain
+     * `collectionVersion += 1` there is a read-modify-WRITE of reactive state, so
+     * the effect would take a dependency on the very signal it bumps and loop
+     * forever. The read is untracked; only the write is observable.
+     */
+    function bumpCollection() {
+        collectionVersion = untrack(() => collectionVersion) + 1;
+    }
+    /**
+     * The selection as the user actually sees it.
+     *
+     * The stored `selectedValue` survives unregistration (an option removed by
+     * the consumer, or the whole list unmounted while an inline field stays put).
+     * Reading it raw would hand out a selection that no rendered option carries —
+     * a stale highlight, a dead ARIA reference, and a first arrow press spent
+     * recovering instead of moving. Resolving against the live enabled+visible
+     * set makes all three impossible by construction, whatever order mounts and
+     * unmounts happen to interleave in during a remount.
+     */
+    function resolveSelected() {
+        void collectionVersion;
+        const enabled = getEnabledVisibleItems();
+        if (enabled.length === 0)
+            return '';
+        if (enabled.some((item) => item.value === selectedValue))
+            return selectedValue;
+        return enabled[0].value;
+    }
     function updateScores(search) {
+        bumpCollection();
         scores.clear();
         if (!options.shouldFilter || search === '') {
             for (const item of items)
@@ -89,6 +127,7 @@ export function createCommandState(options) {
         }
     }
     function getVisibleItems() {
+        void collectionVersion;
         return items.filter((item) => (scores.get(item.value) ?? 0) > 0);
     }
     function getEnabledVisibleItems() {
@@ -106,7 +145,11 @@ export function createCommandState(options) {
             selectedValue = enabled[enabled.length - 1].value;
             return;
         }
-        const currentIndex = enabled.findIndex((item) => item.value === selectedValue);
+        // Résolue, pas brute : après un remontage la valeur stockée peut ne
+        // correspondre à aucune option rendue, et la navigation repartirait alors
+        // du début au lieu de continuer depuis ce qui est mis en évidence.
+        const current = resolveSelected();
+        const currentIndex = enabled.findIndex((item) => item.value === current);
         if (direction === 'next') {
             if (currentIndex === -1 || currentIndex >= enabled.length - 1) {
                 selectedValue = options.loop ? enabled[0].value : enabled[enabled.length - 1].value;
@@ -131,10 +174,39 @@ export function createCommandState(options) {
             return options.search;
         },
         get selectedValue() {
-            return selectedValue;
+            return resolveSelected();
         },
         inputId,
         listId,
+        get mode() {
+            return options.mode;
+        },
+        get open() {
+            return options.open;
+        },
+        get listMounted() {
+            return listMounted;
+        },
+        setListMounted(mounted) {
+            listMounted = mounted;
+        },
+        getActiveOptionId() {
+            void collectionVersion;
+            // No list rendered ⇒ no option rendered ⇒ nothing to point at.
+            if (!listMounted)
+                return null;
+            const active = resolveSelected();
+            if (active === '')
+                return null;
+            const item = getEnabledVisibleItems().find((candidate) => candidate.value === active);
+            // The DOM id of the rendered option, never its business `value`.
+            return item ? item.id : null;
+        },
+        requestOpen() {
+            if (options.open)
+                return;
+            options.onRequestOpen?.();
+        },
         get shouldFilter() {
             return options.shouldFilter;
         },
@@ -151,11 +223,19 @@ export function createCommandState(options) {
             }
         },
         getScore(value) {
+            // `scores` is a plain Map, so a reader that did not touch the collection
+            // beat would never see a score written AFTER it first ran. That is the
+            // case on every mount: an item's `isVisible` derived evaluates during
+            // render, while `registerItem` runs in its `$effect`, i.e. later. With a
+            // retained query the item scored 0 at render, matched at registration,
+            // and stayed hidden forever — no signal had changed.
+            void collectionVersion;
             return scores.get(value) ?? 0;
         },
         filter: options.filter,
         registerItem(item) {
             items.push(item);
+            bumpCollection();
             const score = options.shouldFilter && options.search
                 ? options.filter(item.value, options.search, item.keywords)
                 : 1;
@@ -171,13 +251,14 @@ export function createCommandState(options) {
                 const item = items[index];
                 scores.delete(item.value);
                 items.splice(index, 1);
+                bumpCollection();
             }
         },
         select(value) {
             selectedValue = value;
         },
         getSelectedValue() {
-            return selectedValue;
+            return resolveSelected();
         },
         navigateItems,
         selectCurrent() {

package/dist/components/command/components/command-group.svelte

@@ -7,26 +7,36 @@
   const ctx = getCommandContext()
   const headingId = useId('sp-command-group')
 
-  // In filtered mode, groups are hidden if they have no visible items
-  // For simplicity, we always render and let CSS/items handle visibility
+  // In filtered mode, a group with no visible item is hidden — its heading
+  // alone would be a promise of results that are not there.
   const isHidden = $derived(
     !forceMount && ctx.shouldFilter && ctx.search !== '' && !ctx.hasVisibleItems(),
   )
 </script>
 
-{#if !isHidden}
-  <div
-    class="sp-command-group {className ?? ''}"
-    role="group"
-    aria-labelledby={heading ? headingId : undefined}
-    data-command-group
-  >
-    {#if heading}
-      <div class="sp-command-group-heading" id={headingId}>{heading}</div>
-    {/if}
-    {#if children}{@render children()}{/if}
-  </div>
-{/if}
+<!--
+  The group is HIDDEN, never unmounted. Items register from their own
+  `$effect`, so they must exist for the registry to learn about them: gating
+  the children on `hasVisibleItems()` — a predicate over that same registry —
+  deadlocked whenever the registry was empty while a query was retained. On
+  remount (an inline field whose list reopens, a list rebuilt after its options
+  changed) nothing ever registered again and the palette showed zero options,
+  permanently. Items already gate their OWN rendering on their score, so a
+  hidden group is an empty box: `hidden` takes it out of layout and out of the
+  accessibility tree, which is all the rule was ever asking for.
+-->
+<div
+  class="sp-command-group {className ?? ''}"
+  role="group"
+  aria-labelledby={heading ? headingId : undefined}
+  data-command-group
+  hidden={isHidden}
+>
+  {#if heading}
+    <div class="sp-command-group-heading" id={headingId}>{heading}</div>
+  {/if}
+  {#if children}{@render children()}{/if}
+</div>
 
 <style>
   .sp-command-group {

package/dist/components/command/components/command-group.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-group.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/command/components/command-group.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAiCpD,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"command-group.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/command/components/command-group.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAgCpD,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/components/command/components/command-input.svelte

@@ -3,12 +3,55 @@
   import { kbd } from '../../../internal/helpers/index.js'
   import { getCommandContext } from '../command.svelte.js'
 
-  const { placeholder = 'Search...', class: className }: CommandInputProps = $props()
+  let {
+    placeholder = 'Search...',
+    class: className,
+    wrapperClass,
+    element = $bindable(null),
+    // Pulled out of `rest` so the built-in behaviour can COMPOSE with it
+    // instead of being clobbered by the spread.
+    onkeydown: consumerKeydown,
+    ...rest
+  }: CommandInputProps = $props()
   const ctx = getCommandContext()
 
-  function onkeydown(e: KeyboardEvent) {
+  /**
+   * Every keyboard behaviour below is gated on the list being REALLY rendered,
+   * never on finding a node in the document. In `modal` the list is always
+   * rendered alongside the input, so this is constantly true and nothing about
+   * the shipped behaviour moves. In `inline` the field outlives the results,
+   * and that is where the distinction earns its keep.
+   */
+  const open = $derived(ctx.listMounted)
+
+  /** The rendered option's DOM id, or nothing at all. Resolved through the live
+   *  registry, so it cannot name an option that filtering, removal or a closed
+   *  list has taken away. */
+  const activeOptionId = $derived(ctx.getActiveOptionId() ?? undefined)
+
+  function onkeydown(e: KeyboardEvent & { currentTarget: EventTarget & HTMLInputElement }) {
     if (e.isComposing) return
 
+    // The consumer runs first and may cancel Spectral's local handling for this
+    // key. It cannot retract a close the Escape layer has already performed:
+    // that one runs earlier, on `document`, in the capture phase —
+    // `onEscapeKeydown` on `Command.Root` is the hook for it.
+    consumerKeydown?.(e)
+    if (e.defaultPrevented) return
+
+    if (!open) {
+      // Results closed. The field is an ordinary text input: Enter belongs to
+      // the surrounding form, Escape to whatever surface is actually listening,
+      // Home/End to the caret. Claiming them here would make a closed palette
+      // interfere with the page — and Enter, in particular, could activate an
+      // option nobody can see.
+      if (e.key === kbd.ARROW_DOWN || e.key === kbd.ARROW_UP) {
+        e.preventDefault()
+        ctx.requestOpen()
+      }
+      return
+    }
+
     switch (e.key) {
       case kbd.ARROW_DOWN: {
         e.preventDefault()
@@ -54,7 +97,7 @@
   }
 </script>
 
-<div class="sp-command-input-wrapper">
+<div class="sp-command-input-wrapper {wrapperClass ?? ''}">
   <svg
     class="sp-command-input-icon"
     xmlns="http://www.w3.org/2000/svg"
@@ -71,13 +114,19 @@
     <circle cx="11" cy="11" r="8" />
     <path d="m21 21-4.3-4.3" />
   </svg>
+  <!-- `{...rest}` FIRST: a consumer may add attributes, never override the
+       field's identity (role, id, type) or the three relations computed from
+       the palette's own state — those come after and win. -->
   <input
+    {...rest}
+    bind:this={element}
     class="sp-command-input {className ?? ''}"
     id={ctx.inputId}
     type="text"
     role="combobox"
-    aria-expanded="true"
-    aria-controls={ctx.listId}
+    aria-expanded={ctx.open}
+    aria-controls={open ? ctx.listId : undefined}
+    aria-activedescendant={activeOptionId}
     aria-autocomplete="list"
     autocomplete="off"
     {placeholder}

package/dist/components/command/components/command-input.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { CommandInputProps } from '../types.js';
-declare const CommandInput: import("svelte").Component<CommandInputProps, {}, "">;
+declare const CommandInput: import("svelte").Component<CommandInputProps, {}, "element">;
 type CommandInput = ReturnType<typeof CommandInput>;
 export default CommandInput;
 //# sourceMappingURL=command-input.svelte.d.ts.map

package/dist/components/command/components/command-input.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-input.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/command/components/command-input.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAwEpD,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"command-input.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/command/components/command-input.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAoHpD,QAAA,MAAM,YAAY,8DAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/components/command/components/command-list.svelte

@@ -4,11 +4,30 @@
 
   const { label = 'Suggestions', class: className, children }: CommandListProps = $props()
   const ctx = getCommandContext()
+
+  /**
+   * In `modal` the Root only exists while open, so this is always true and
+   * nothing changes. In `inline` the field outlives the results: the list must
+   * be ABSENT when closed, not merely hidden. Hiding it in CSS would leave
+   * every option in the document, where the Enter path could still reach one —
+   * an invisible command, executed.
+   */
+  const rendered = $derived(ctx.mode !== 'inline' || ctx.open)
+
+  // The Root gates behaviour on the list being REALLY rendered, so the list is
+  // what reports it rather than anyone inferring it.
+  $effect(() => {
+    if (!rendered) return
+    ctx.setListMounted(true)
+    return () => ctx.setListMounted(false)
+  })
 </script>
 
-<div class="sp-command-list {className ?? ''}" id={ctx.listId} role="listbox" aria-label={label}>
-  {#if children}{@render children()}{/if}
-</div>
+{#if rendered}
+  <div class="sp-command-list {className ?? ''}" id={ctx.listId} role="listbox" aria-label={label}>
+    {#if children}{@render children()}{/if}
+  </div>
+{/if}
 
 <style>
   .sp-command-list {

package/dist/components/command/components/command-list.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-list.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/command/components/command-list.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAmBnD,QAAA,MAAM,WAAW,sDAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}
+{"version":3,"file":"command-list.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/command/components/command-list.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAsCnD,QAAA,MAAM,WAAW,sDAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

package/dist/components/command/components/command-root.svelte

@@ -15,7 +15,8 @@
     shouldFilter = true,
     loop = true,
     portalTo,
-    trapFocus = true,
+    mode = 'modal',
+    trapFocus,
     closeOnEscape = true,
     closeOnOutsideClick = true,
     onEscapeKeydown,
@@ -26,10 +27,27 @@
     children,
   }: CommandProps = $props()
 
+  /** A field living in an app bar must stay in the page's natural tab order,
+   *  so `inline` flips the default — an explicit value still wins. */
+  const trapsFocus = $derived(trapFocus ?? mode !== 'inline')
+  /** Inline renders IN PLACE unless a target is given: the consumer's scoped
+   *  CSS then applies, and the results can be anchored to the field. */
+  const portalDisabled = $derived(mode === 'inline' && portalTo === undefined)
+
   const commandState = createCommandState({
     get search() {
       return value
     },
+    get mode() {
+      return mode
+    },
+    get open() {
+      return open
+    },
+    onRequestOpen() {
+      open = true
+      onOpenChange?.(true)
+    },
     get filter() {
       return filter
     },
@@ -83,11 +101,15 @@
     },
   })
 
+  // The two layers follow `open` in BOTH modes — which is exactly what makes a
+  // closed inline palette inert: no `document` listener, and no slot held in
+  // the global Escape / dismiss stacks that a surface below would have to
+  // yield to.
   $effect(() => {
     if (open && isBrowser) {
       escapeLayer.mount()
       dismissLayer.mount()
-      if (trapFocus && contentEl) {
+      if (trapsFocus && contentEl) {
         focusScope.setElement(contentEl)
         focusScope.mount()
       }
@@ -109,12 +131,14 @@
   })
 </script>
 
-{#if presence.isPresent}
-  <Portal to={portalTo}>
+<!-- Inline keeps the Root mounted whatever `open` is: the field is the point. -->
+{#if mode === 'inline' || presence.isPresent}
+  <Portal to={portalTo} disabled={portalDisabled}>
     <div
       bind:this={contentEl}
       class="sp-command {className ?? ''}"
       data-command-root
+      data-mode={mode}
       data-state={open ? 'open' : 'closed'}
     >
       {#if children}{@render children()}{/if}
@@ -132,4 +156,19 @@
     background-color: var(--sp-sys-color-surface-container);
     box-shadow: var(--sp-sys-elevation-3);
   }
+
+  /**
+   * Inline is not a panel: it is a field with results hanging off it. The
+   * panel chrome is dropped so the consumer can dress the field, and
+   * `overflow` is released so results positioned below are not clipped by the
+   * very element that owns them. `position: relative` makes the Root the
+   * containing block, which is what an anchored list needs.
+   */
+  .sp-command[data-mode='inline'] {
+    position: relative;
+    overflow: visible;
+    border-radius: 0;
+    background-color: transparent;
+    box-shadow: none;
+  }
 </style>

package/dist/components/command/components/command-root.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-root.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/command/components/command-root.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAoI/C,QAAA,MAAM,WAAW,gEAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}
+{"version":3,"file":"command-root.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/command/components/command-root.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AA2J/C,QAAA,MAAM,WAAW,gEAAwC,CAAC;AAC1D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;AAClD,eAAe,WAAW,CAAC"}

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

@@ -1,4 +1,5 @@
 export { defaultFilter } from './command.svelte.js';
+export type { CommandMode } from './command.svelte.js';
 export { default as Empty } from './components/command-empty.svelte';
 export { default as Group } from './components/command-group.svelte';
 export { default as Input } from './components/command-input.svelte';

package/dist/components/command/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/components/command/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,mCAAmC,CAAA;AACpE,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,mCAAmC,CAAA;AACpE,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,mCAAmC,CAAA;AACpE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,kCAAkC,CAAA;AAClE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,kCAAkC,CAAA;AAClE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,kCAAkC,CAAA;AAClE,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,uCAAuC,CAAA;AAC5E,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,qBAAqB,GACtB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/components/command/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,mCAAmC,CAAA;AACpE,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,mCAAmC,CAAA;AACpE,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,mCAAmC,CAAA;AACpE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,kCAAkC,CAAA;AAClE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,kCAAkC,CAAA;AAClE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,kCAAkC,CAAA;AAClE,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,uCAAuC,CAAA;AAC5E,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,qBAAqB,GACtB,MAAM,YAAY,CAAA"}

package/dist/components/command/types.d.ts

@@ -1,5 +1,6 @@
 import type { Snippet } from 'svelte';
-import type { HTMLAttributes } from 'svelte/elements';
+import type { HTMLAttributes, HTMLInputAttributes } from 'svelte/elements';
+import type { CommandMode } from './command.svelte.js';
 export interface CommandProps {
     /** Current search query (bindable). */
     value?: string;
@@ -9,13 +10,39 @@ export interface CommandProps {
     shouldFilter?: boolean;
     /** Whether keyboard navigation loops at edges. @default true */
     loop?: boolean;
+    /**
+     * Composition mode.
+     *
+     * - `'modal'` (default, unchanged behaviour): `open` controls whether the
+     *   palette is MOUNTED — closing unmounts the content, the field included,
+     *   together with the Escape and outside-pointer layers.
+     * - `'inline'`: the Root and its `Command.Input` stay mounted whatever `open`
+     *   is, so a search field can live permanently in a bar; `open` then governs
+     *   only whether `Command.List` is RENDERED, and the two layers follow the
+     *   results. A closed inline palette listens to nothing: no document
+     *   listener, no slot held in the global layer stacks.
+     *
+     * @default 'modal'
+     */
+    mode?: CommandMode;
     /**
      * Controls whether the palette is mounted. When true, render content. Default: true.
+     * In `'inline'` mode this controls the RESULTS only — see `mode`.
      */
     open?: boolean;
-    /** Portal target. Default undefined (document.body). */
+    /**
+     * Portal target. Default `document.body` in `'modal'` mode; in `'inline'`
+     * mode the content is rendered IN PLACE by default, so the consumer's scoped
+     * CSS applies and the results can be anchored to the field. Passing a target
+     * portals in either mode.
+     */
     portalTo?: HTMLElement | string;
-    /** Trap focus within the palette. Default: true. */
+    /**
+     * Trap focus within the palette.
+     * @default `true` in `'modal'` mode, `false` in `'inline'` mode — a field
+     * sitting in a bar must stay part of the page's natural tab order. An
+     * explicit value is honoured in both modes.
+     */
     trapFocus?: boolean;
     /** Close on Escape keydown. Default: true. */
     closeOnEscape?: boolean;
@@ -35,10 +62,38 @@ export interface CommandProps {
     class?: string;
     children?: Snippet;
 }
-export interface CommandInputProps {
+/**
+ * Extends the native `input` attributes. A consumer's `title`, `name`,
+ * `aria-label` / `aria-labelledby` / `aria-describedby`, `data-testid`,
+ * `style` and native event handlers reach the real `role="combobox"` node.
+ *
+ * The field's IDENTITY stays with the component: `role`, `id`, `type` and the
+ * three computed relations (`aria-expanded`, `aria-controls`,
+ * `aria-activedescendant`) are rejected by the type — they are derived from
+ * the palette's own state and a consumer value could only contradict it.
+ *
+ * Consumer handlers COMPOSE with the built-in ones: yours runs first, and
+ * calling `preventDefault()` cancels Spectral's local keyboard handling for
+ * that key. It does NOT retract a close already performed by the Escape layer,
+ * which runs earlier, on `document`, in the capture phase — `onEscapeKeydown`
+ * on `Command.Root` is the public hook for that.
+ */
+export interface CommandInputProps extends Omit<HTMLInputAttributes, 'class' | 'children' | 'value' | 'type' | 'role' | 'id' | 'autocomplete' | 'oninput' | 'aria-expanded' | 'aria-controls' | 'aria-activedescendant' | 'aria-autocomplete'> {
     /** Placeholder text for the search input. */
     placeholder?: string;
+    /** Class placed on the `<input>` itself. */
     class?: string;
+    /**
+     * Class placed on the wrapper that holds the icon and the input — the box
+     * that carries the padding and the bottom border. This is the hook for
+     * restyling the field as, say, a pill inside an app bar.
+     */
+    wrapperClass?: string;
+    /**
+     * The real input element, bindable. Lets the consumer focus the field
+     * (a `Cmd/Ctrl+K` shortcut, say) without reaching for an internal selector.
+     */
+    element?: HTMLInputElement | null;
 }
 export interface CommandListProps {
     /** Accessible label for the listbox. */

package/dist/components/command/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/components/command/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gGAAgG;IAChG,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACvE,0EAA0E;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,wDAAwD;IACxD,QAAQ,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC/B,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,mDAAmD;IACnD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IAChD,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IACjD,uFAAuF;IACvF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAC5C,cAAc,CAAC,cAAc,CAAC,EAC9B,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,UAAU,GAAG,eAAe,GAAG,eAAe,CACtF;IACC,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/components/command/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtD,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gGAAgG;IAChG,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACvE,0EAA0E;IAC1E,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC/B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,mDAAmD;IACnD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IAChD,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IACjD,uFAAuF;IACvF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAC7C,mBAAmB,EACjB,OAAO,GACP,UAAU,GACV,OAAO,GACP,MAAM,GACN,MAAM,GACN,IAAI,GACJ,cAAc,GACd,SAAS,GACT,eAAe,GACf,eAAe,GACf,uBAAuB,GACvB,mBAAmB,CACtB;IACC,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAC5C,cAAc,CAAC,cAAc,CAAC,EAC9B,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,UAAU,GAAG,eAAe,GAAG,eAAe,CACtF;IACC,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@spectral_labs/ui",
   "type": "module",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"