@spectral_labs/ui 1.6.1 → 1.8.0-next.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spectral
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,201 @@
+# Third-party notices
+
+`@spectral_labs/ui` is released under the MIT licence (`LICENSE`). It also ships the third-party material below, which keeps its own licence: one section per item, its licence reproduced as is.
+
+## Inter (OFL-1.1)
+
+Inter 4.001, the variable font files `src/fonts/inter/InterVariable.woff2` and `src/fonts/inter/InterVariable-Italic.woff2` (https://github.com/rsms/inter). The copyright line is the one the font files carry.
+
+```text
+Copyright 2016 The Inter Project Authors
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+```
+
+## JetBrains Mono (OFL-1.1)
+
+JetBrains Mono 2.304, the font files `src/fonts/jetbrains-mono/JetBrainsMono-Regular.woff2`, `src/fonts/jetbrains-mono/JetBrainsMono-Bold.woff2` and `src/fonts/jetbrains-mono/JetBrainsMono-Italic.woff2` (https://github.com/JetBrains/JetBrainsMono). The copyright line is the one the font files carry.
+
+```text
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+```

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