@spectral_labs/ui 1.6.0 → 1.7.0

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":"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"}