svelte-5-select 2.0.0 → 2.1.0

package/README.md

@@ -1,16 +1,16 @@
-<div style="text-align: center;">
+<div align="center">
   <img src="https://raw.githubusercontent.com/IDontKnowMyUsername/svelte-5-select/master/svelte-select.png" alt="Svelte 5 Select" width="150" />
   <h1>Svelte 5 Select</h1>
 </div>
-<div style="text-align: center;">
+<div align="center">
   <a href="https://npmjs.org/package/svelte-5-select">
-    <img src="https://badgen.now.sh/npm/v/svelte-5-select" alt="version" />
+    <img src="https://badgen.net/npm/v/svelte-5-select" alt="version" />
   </a>
   <a href="https://npmjs.org/package/svelte-5-select">
-    <img src="https://badgen.now.sh/npm/dm/svelte-5-select" alt="downloads" />
+    <img src="https://badgen.net/npm/dm/svelte-5-select" alt="downloads" />
   </a>
 </div>
-<div style="text-align: center;">A select/autocomplete/typeahead Svelte 5 component.</div>
+<div align="center">A select/autocomplete/typeahead Svelte 5 component.</div>
 
 ## Demos
 
@@ -54,7 +54,7 @@ List position and floating is powered by `floating-ui`, see their [package-entry
 | focused                | `boolean` | `false`         | Input focus; set `true` to focus the input, `false` to blur it and close the list |
 | listAutoWidth          | `boolean` | `true`          | If `false` will ignore width of select                         |
 | showChevron            | `boolean` | `false`         | Show chevron                                                   |
-| inputAttributes        | `object`  | `{}`            | Pass in HTML attributes to Select's input; `on*` handlers run after the component's own, not instead of them |
+| inputAttributes        | `object`  | `{}`            | Pass in HTML attributes to Select's input; `on*` handlers run after the component's own, not instead of them. `value`, `placeholder`, and `style` are ignored — use `bind:filterText`, `placeholder`, and `inputStyles` |
 | placeholderAlwaysShow  | `boolean` | `false`         | When `multiple` placeholder text will always show              |
 | loading                | `boolean` | `false`         | Shows `loading-icon`. `loadOptions` will override this         |
 | listOffset             | `number`  | `5`             | `px` space between select and list                             |
@@ -82,6 +82,7 @@ List position and floating is powered by `floating-ui`, see their [package-entry
 | ariaFocused            | `() => string` | see below  | Announcement when the input receives focus                     |
 | ariaListOpen           | `(label: string, count: number) => string` | see below | Announcement when the list opens on a focused option           |
 | ariaValues             | `(values: string) => string` | see below | Announcement naming the current selection                      |
+| ariaActiveTag          | `(label: string) => string` | see below | Announcement when the arrow-key tag cursor lands on a multi-select tag |
 
 The `aria*` text-builder defaults are shown in the [A11y](#a11y-accessibility) section. See [Function props](#function-props) for the overridable behavior functions (`loadOptions`, `filter`, `groupBy`, and friends).
 
@@ -219,7 +220,7 @@ You can also use custom collections.
 
 ### Async Items
 
-To load items asynchronously then `loadOptions` is the simplest solution. Supply a function that returns a `Promise` that resolves with a list of items. `loadOptions` fires once on mount, on typing non-empty `filterText` (debounced), and whenever `loadOptionsDeps` or `disabled` change. Emptying the filter text or closing the list cancels a pending typing-driven load instead of re-fetching. One open/close-related exception: reopening the list with retained filter text whose load was cancelled on close (e.g. with `clearFilterTextOnBlur={false}`) refetches immediately, so the list never shows results that are stale for the visible text.
+To load items asynchronously then `loadOptions` is the simplest solution. Supply a function that returns a `Promise` that resolves with a list of items. `loadOptions` fires once on mount, on typing non-empty `filterText` (debounced), and whenever `loadOptionsDeps` or `disabled` change. Closing the list cancels a pending typing-driven load instead of re-fetching. Beyond those triggers, one rule: the open list never shows results that are stale for the visible text. Reopening it refetches when the shown results don't match the retained filter text (`clearFilterTextOnBlur={false}`), when Escape wiped the text over query-narrowed results, or after a failed load; and emptying the text while the list stays open — deleting the query, or a selection wiping it with `closeListOnChange={false}` — refetches the baseline (empty-query) set in place.
 
 ```html
 <script>
@@ -340,10 +341,12 @@ Internal wiring (the shared state store, the composables, and their types) is de
 
 ## TypeScript
 
-The component is generic over your item type: values, items, snippets, and callbacks are typed from the `items` you pass in — plain interfaces work, no index signature needed (TypeScript >= 5.4). Only `items`, `value`, and `loadOptions` drive that inference: configuration callbacks like `groupBy`/`itemFilter` receive the inferred `Item` but never widen it, so a loosely-typed callback const can't silently change what `Item` means. The `multiple` prop narrows types too: with `multiple`, `bind:value` and the `onValueChange`/`onSelectionChange` payloads are `Item[]`; without it they are `Item | null`. The `null` appears only in the dispatch payloads (`onValueChange(null)` on clear) — an emptied `bind:value` is always `undefined`, so test it with falsiness, not `=== null`.
+The component is generic over your item type: values, items, snippets, and callbacks are typed from the `items` you pass in — plain interfaces work, no index signature needed (TypeScript >= 5.4). Only `items`, `value`, and `loadOptions` drive that inference: configuration callbacks and event handlers (`groupBy`, `itemFilter`, `onselect`, …) receive the inferred `Item` but never widen it, so a loosely-typed callback const can't silently change what `Item` means. The `multiple` prop narrows types too: with `multiple`, the `onValueChange`/`onSelectionChange` payloads are `Item[]`; without it they are `Item | null`. `bind:value` is looser than the payloads — it also accepts raw string ids on input, and an emptied `bind:value` is always `undefined` — so test it with falsiness, not `=== null` (the `null` appears only in the dispatch payloads, e.g. `onValueChange(null)` on clear).
 
 ```svelte
 <script lang="ts">
+  import { Select } from 'svelte-5-select';
+
   interface Country {
     code: string;
     name: string;
@@ -361,11 +364,17 @@ The component is generic over your item type: values, items, snippets, and callb
 
 `SelectProps`, `SelectItem`, `SelectValue`, and `SelectValueProp` (the bindable `value` shape, which also accepts raw string ids) are exported for annotating your own wrappers.
 
+One resolution caveat: the full generic typing requires Svelte-aware tooling (svelte-check, the Svelte VS Code extension) or `"moduleResolution": "bundler"` — which SvelteKit and Vite templates use. Plain `tsc` under `"moduleResolution": "nodenext"` cannot resolve `.svelte` type declarations, so the `Select` component import silently falls back to Svelte's untyped ambient component type there (the exported types like `SelectProps` still resolve fully).
+
+## SSR (SvelteKit)
+
+The component server-renders: no browser globals are touched at module scope or during init, and the selection — including raw string `value` entries, which are resolved against `items` before the first render — the multi-select tags, the hidden form inputs, and an open list are all in the server HTML. Floating list positioning is applied client-side after hydration. Server rendering is exercised by its own test suite (`tests/src/ssr.test.ts`).
+
 ## A11y (Accessibility)
 
 The input renders as a WAI-ARIA combobox with a listbox popup, including `aria-expanded`, `aria-activedescendant`, `aria-required`, `aria-invalid`, `aria-busy` (while loading), and `aria-multiselectable` where applicable. When `groupBy` is set, each group's options are wrapped in a `role="group"` region named by its header (via `aria-labelledby`). Set `hasError` with `ariaErrorMessage` to wire the input to an external error element via `aria-errormessage`. A `disabled` Select marks the input `aria-disabled` + `readonly` (rather than natively `disabled`) so the combobox and its value stay in the accessibility tree and remain announceable, while staying non-interactive and out of the tab order. Keyboard support covers ArrowUp/ArrowDown, PageUp/PageDown, Home/End, Enter, Tab (commits the highlighted option — but only after you've navigated or typed, so tabbing straight past an opened list never selects), Escape, `Alt`+ArrowDown/ArrowUp (open/close), Space (select in select-only mode), and Backspace/ArrowLeft/ArrowRight for multi-select items; with `multiFullItemClearable`, each tag is a focusable button that Enter/Space removes. The open listbox is named by `ariaLabel`, an `aria-labelledby` supplied via `inputAttributes`, or — on the `id` + `<label for>` path — by that label (a wrapping `<label>` contributes only its own text). The focused input shows a ring (`--focused-box-shadow`) in addition to the border colour; the option under the keyboard cursor shows a >=3:1 outline (`--item-hover-outline`) on top of the hover background; the spinner and item transitions respect `prefers-reduced-motion`; and focus/selection stay visible under Windows High Contrast Mode (`forced-colors`).
 
-The textbox itself only ever contains the typed filter text — the current selection is rendered beside it and conveyed to assistive tech through two polite `role="status"` live regions (customizable via the `ariaValues`, `ariaFocused`, `ariaListOpen`, `ariaEmpty`, `ariaLoading`, and `ariaCleared` builders): focusing a valued Select announces the selection, and selecting/clearing announces the change.
+The textbox itself only ever contains the typed filter text — the current selection is rendered beside it and conveyed to assistive tech through two polite `role="status"` live regions (customizable via the `ariaValues`, `ariaFocused`, `ariaListOpen`, `ariaEmpty`, `ariaLoading`, `ariaCleared`, and `ariaActiveTag` builders): focusing a valued Select announces the selection, and selecting/clearing announces the change.
 
 Give the input an accessible name with either `ariaLabel` or an external `<label for={id}>` (set the `id` prop). In development the component logs a `console.warn` if it finds neither `ariaLabel`, an `aria-labelledby`, nor an associated `<label>` — the placeholder is only a last-resort fallback that some screen readers ignore. The warning is stripped from production builds.
 
@@ -383,6 +392,7 @@ Selection and list state (including the empty/loading state) are announced throu
   ariaCleared={() => `Selection cleared.`}
   ariaClearSelectLabel="Clear selection"
   ariaRemoveItemLabel={(label) => `Remove ${label}`}
+  ariaActiveTag={(label) => `${label} is active. Press Backspace to remove, or left and right arrow keys to move between selected options.`}
 />
 ```
 
@@ -393,7 +403,7 @@ The public API moved to idiomatic Svelte 5:
 - **Slots → snippets.** `<div slot="item" let:item />` becomes `{#snippet itemSnippet(item, index)}...{/snippet}` declared inside `<Select>`. See the [Snippets](#snippets) table for the full mapping (`slot="chevron-icon"` → `chevronIconSnippet`, etc.).
 - **Events → callback props.** `on:change={(e) => e.detail}` becomes `onSelectionChange={(value) => ...}` and `on:input` becomes `onValueChange={(value) => ...}` — handlers receive the value directly, with no `event.detail`.
 - **`export let` overrides → regular props.** Functions like `itemFilter`, `groupBy`, and the aria text builders are passed as props.
-- **CSS variables are kebab-case.** `--borderRadius` is now `--border-radius`; see [the full list](/docs/theming_variables.md).
+- **CSS variables are kebab-case.** As in svelte-select v5 — but if you are coming from a pre-v5 version, camelCase names like `--borderRadius` are now `--border-radius`; see [the full list](/docs/theming_variables.md).
 
 ## Migrating from 1.x to 2.0
 
@@ -426,7 +436,7 @@ You can style a component by overriding [the available CSS custom properties](/d
   import { Select } from 'svelte-5-select';
 </script>
 
-<Select --border-radius= "10px" --placeholder-color="blue" />
+<Select --border-radius="10px" --placeholder-color="blue" />
 ```
 
 You can also use the `inputStyles` prop to write in any override styles needed for the input.

package/dist/ChevronIcon.svelte

@@ -1,3 +1,9 @@
+<script lang="ts">
+    // Required even though empty: script-less components make svelte2tsx emit a
+    // legacy d.ts referencing `SvelteComponent` without importing it, which breaks
+    // consumers that type-check with skipLibCheck: false.
+</script>
+
 <svg width="100%" height="100%" viewBox="0 0 20 20" focusable="false" aria-hidden="true">
     <path
         fill="currentColor"

package/dist/ChevronIcon.svelte.d.ts

@@ -1,18 +1,5 @@
-export default ChevronIcon;
-type ChevronIcon = SvelteComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {}> & {
-    $$bindings?: string | undefined;
-};
-declare const ChevronIcon: $$__sveltets_2_IsomorphicComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {}, {}, string>;
 interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
-    new (options: import("svelte").ComponentConstructorOptions<Props>): import("svelte").SvelteComponent<Props, Events, Slots> & {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
         $$bindings?: Bindings;
     } & Exports;
     (internal: unknown, props: {
@@ -24,3 +11,8 @@ interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> =
     };
     z_$$bindings?: Bindings;
 }
+declare const ChevronIcon: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type ChevronIcon = InstanceType<typeof ChevronIcon>;
+export default ChevronIcon;

package/dist/ClearIcon.svelte

@@ -1,3 +1,9 @@
+<script lang="ts">
+    // Required even though empty: script-less components make svelte2tsx emit a
+    // legacy d.ts referencing `SvelteComponent` without importing it, which breaks
+    // consumers that type-check with skipLibCheck: false.
+</script>
+
 <svg width="100%" height="100%" viewBox="-2 -2 50 50" focusable="false" aria-hidden="true" role="presentation">
     <path
         fill="currentColor"

package/dist/ClearIcon.svelte.d.ts

@@ -1,18 +1,5 @@
-export default ClearIcon;
-type ClearIcon = SvelteComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {}> & {
-    $$bindings?: string | undefined;
-};
-declare const ClearIcon: $$__sveltets_2_IsomorphicComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {}, {}, string>;
 interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
-    new (options: import("svelte").ComponentConstructorOptions<Props>): import("svelte").SvelteComponent<Props, Events, Slots> & {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
         $$bindings?: Bindings;
     } & Exports;
     (internal: unknown, props: {
@@ -24,3 +11,8 @@ interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> =
     };
     z_$$bindings?: Bindings;
 }
+declare const ClearIcon: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type ClearIcon = InstanceType<typeof ClearIcon>;
+export default ClearIcon;

package/dist/LoadingIcon.svelte

@@ -1,3 +1,9 @@
+<script lang="ts">
+    // Required even though empty: script-less components make svelte2tsx emit a
+    // legacy d.ts referencing `SvelteComponent` without importing it, which breaks
+    // consumers that type-check with skipLibCheck: false.
+</script>
+
 <svg class="loading" viewBox="25 25 50 50" aria-hidden="true" focusable="false">
     <circle
         class="circle_path"

package/dist/LoadingIcon.svelte.d.ts

@@ -1,18 +1,5 @@
-export default LoadingIcon;
-type LoadingIcon = SvelteComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {}> & {
-    $$bindings?: string | undefined;
-};
-declare const LoadingIcon: $$__sveltets_2_IsomorphicComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {}, {}, string>;
 interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
-    new (options: import("svelte").ComponentConstructorOptions<Props>): import("svelte").SvelteComponent<Props, Events, Slots> & {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
         $$bindings?: Bindings;
     } & Exports;
     (internal: unknown, props: {
@@ -24,3 +11,8 @@ interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> =
     };
     z_$$bindings?: Bindings;
 }
+declare const LoadingIcon: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type LoadingIcon = InstanceType<typeof LoadingIcon>;
+export default LoadingIcon;

package/dist/Select.svelte

@@ -20,16 +20,16 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
         SelectValue,
         SelectClearValue,
         SelectErrorEvent,
-    } from './types';
+    } from './types.js';
     import { createFloatingActions } from 'svelte-floating-ui';
     import { useAriaHandlers } from './aria-handlers.svelte';
 
-    import _filter from './filter';
+    import _filter from './filter.js';
 
     import ChevronIcon from './ChevronIcon.svelte';
     import ClearIcon from './ClearIcon.svelte';
     import LoadingIcon from './LoadingIcon.svelte';
-    import type { SelectItem } from './types';
+    import type { SelectItem } from './types.js';
     import type { HTMLInputAttributes } from 'svelte/elements';
     import { createSelectState } from './select-state.svelte';
     import { useKeyboardNavigation } from './keyboard-navigation.svelte';
@@ -43,7 +43,7 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
         isItemSelectableCheck,
         normalizeItem,
         createGroupHeaderItem as _createGroupHeaderItem,
-    } from './utils';
+    } from './utils.js';
 
     const defaultItemFilter = (label: string, filterText: string, _option: SelectItem): boolean =>
         `${label}`.toLowerCase().includes(filterText?.toLowerCase());
@@ -118,6 +118,8 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
         // ARIA props
         ariaLabel = undefined,
         ariaErrorMessage = undefined,
+        ariaActiveTag = (label: string) =>
+            `${label} is active. Press Backspace to remove, or left and right arrow keys to move between selected options.`,
         ariaClearSelectLabel = 'Clear selection',
         ariaRemoveItemLabel = (label: string) => `Remove ${label}`,
         ariaCleared = () => {
@@ -335,6 +337,15 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
                 (consumer as (e: Event) => unknown)(e);
             };
         }
+        // aria-describedby composes the same way: the attribute takes a
+        // space-separated id list, so a consumer description must extend the
+        // selection description, not silently replace it (later-spread-wins
+        // dropped the selection from browse-mode reading).
+        const consumerDescribedby = inputAttributes?.['aria-describedby'];
+        const ownDescribedby = !multiple && value ? `selected-${_id}` : undefined;
+        if (consumerDescribedby && ownDescribedby) {
+            attrs['aria-describedby'] = `${ownDescribedby} ${consumerDescribedby}`;
+        }
         return attrs;
     });
     let prefloat = $state(true);
@@ -505,7 +516,7 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
     );
     let ariaContext = $derived.by(() => {
         if (activeTagLabel !== undefined) {
-            return `${activeTagLabel} is active. Press Backspace to remove, or left and right arrow keys to move between selected options.`;
+            return ariaActiveTag(activeTagLabel);
         }
         // Tracked triggers: the list opening/closing, the result count changing
         // (filtering), and the loading flag. hoverItemIndex is deliberately read
@@ -561,6 +572,10 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
     // triggers scrolling.
     function handleKeyDown(e: KeyboardEvent): void {
         keyboardNav.handleKeyDown(e);
+        // Mirror keyboardNav's IME gate: during composition the arrows move
+        // through the IME candidate window, not the list — the keyboard cursor
+        // stays put, so the list must not scroll either.
+        if (e.isComposing || e.keyCode === 229) return;
         const isTypeAhead = !searchable && e.key.length === 1;
         if (
             e.key === 'ArrowDown' ||
@@ -740,8 +755,13 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
         const currentItemId = itemId;
         untrack(() => {
             if (warnedAboutMissingItemId || !currentItems?.length) return;
-            const missing = (currentItems as (Item | string)[]).some(
-                (item) => typeof item !== 'string' && getItemProperty(item, currentItemId) === undefined,
+            // String items are converted to `{ value, label, index }` rows, so
+            // any other `itemId` never exists on them — the same silent
+            // identity collapse the object-item check catches.
+            const missing = (currentItems as (Item | string)[]).some((item) =>
+                typeof item === 'string'
+                    ? !['value', 'label', 'index'].includes(currentItemId)
+                    : getItemProperty(item, currentItemId) === undefined,
             );
             if (!missing) return;
             warnedAboutMissingItemId = true;
@@ -754,6 +774,33 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
         });
     });
 
+    // Dev-only: the same identity collapse can enter through `value` — partial
+    // objects that lack the itemId field (e.g. seeded from a form payload) all
+    // compare equal to each other and to nothing in `items`, so selection
+    // display and dedup misbehave while `items` itself passes the check above.
+    let warnedAboutValueMissingItemId = false;
+    $effect(() => {
+        if (!DEV) return;
+        const currentValue = value;
+        const currentItemId = itemId;
+        untrack(() => {
+            if (warnedAboutValueMissingItemId || currentValue == null) return;
+            const entries = Array.isArray(currentValue) ? currentValue : [currentValue];
+            // Raw strings are their own id, so only object entries can be missing it
+            const missing = (entries as (Item | string)[]).some(
+                (entry) => typeof entry !== 'string' && getItemProperty(entry, currentItemId) === undefined,
+            );
+            if (!missing) return;
+            warnedAboutValueMissingItemId = true;
+            console.warn(
+                `[svelte-select] Some \`value\` entries have no "${currentItemId}" field (the current ` +
+                    '`itemId`). Value entries are matched against items by that field, so entries ' +
+                    'without it cannot be recognized as selected, deduplicated, or validated. Pass ' +
+                    'value entries that carry the `itemId` field.',
+            );
+        });
+    });
+
     // Dev-only: warn once the input is mounted if it has no robust accessible
     // name. The placeholder is only a last-resort fallback that some screen
     // readers ignore, so an unnamed combobox is a real gap worth surfacing.
@@ -767,7 +814,13 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
         ariaLabel;
         untrack(() => {
             if (!input) return;
-            const named = !!ariaLabel || !!input.getAttribute('aria-labelledby') || (input.labels?.length ?? 0) > 0;
+            // getAttribute over the props: an aria-label supplied through
+            // inputAttributes names the input just as well as the ariaLabel prop
+            const named =
+                !!ariaLabel ||
+                !!input.getAttribute('aria-label') ||
+                !!input.getAttribute('aria-labelledby') ||
+                (input.labels?.length ?? 0) > 0;
             if (!named) {
                 console.warn(
                     '[svelte-select] The Select input has no accessible name. Pass `ariaLabel`, ' +
@@ -801,6 +854,14 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
                 listboxLabelledby = inputLabelledby;
                 return;
             }
+            // An aria-label supplied through inputAttributes names only the
+            // input; forward it so the listbox is named the same way the
+            // ariaLabel prop's is (accname precedence: labelledby above wins).
+            const inputAriaLabel = input.getAttribute('aria-label');
+            if (inputAriaLabel) {
+                listboxLabelText = inputAriaLabel;
+                return;
+            }
             const labelEl = input.labels?.[0];
             if (!labelEl) return;
             // An implicit wrapping <label> contains the component itself, so
@@ -867,13 +928,21 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
                 groupValues.push(groupValue);
                 groups[groupValue] = [];
                 if (groupValue) {
-                    groups[groupValue].push(
-                        Object.assign(createGroupHeaderItem(groupValue, item as Item), {
-                            id: groupValue,
-                            groupHeader: true,
-                            selectable: groupHeaderSelectable,
-                        }),
-                    );
+                    const header = Object.assign(createGroupHeaderItem(groupValue, item as Item), {
+                        id: groupValue,
+                        groupHeader: true,
+                        selectable: groupHeaderSelectable,
+                    });
+                    // Headers are compared by `itemId` like any other row
+                    // (selection, hover, dedup): one lacking that field
+                    // compares equal to every other bare header, so selecting
+                    // one marked them all selected and made the rest
+                    // unselectable. Stamp the group value when the builder
+                    // didn't provide the field.
+                    if (getItemProperty(header, itemId) === undefined) {
+                        (header as SelectItem)[itemId] = groupValue;
+                    }
+                    groups[groupValue].push(header);
                 }
             }
 
@@ -1123,7 +1192,7 @@ Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
                          The group's accessible name still resolves via aria-labelledby,
                          which follows hidden targets. Selectable headers are real options. -->
                     <div
-                        onmouseover={() => hoverManager.handleHover(i)}
+                        onmousemove={() => hoverManager.handleHover(i)}
                         onfocus={() => hoverManager.handleHover(i)}
                         onclick={(ev) => {
                             ev.stopPropagation();
@@ -1807,5 +1876,24 @@ input:focus {
         outline: 2px dashed Highlight;
         outline-offset: -2px;
     }
+
+    /* The error state is conveyed only by an author border colour, which is
+       flattened to the standard border — border width + style survive the
+       forced palette, so a double border keeps the state visible. */
+    .svelte-select.error {
+        border: 3px double CanvasText;
+    }
+
+    /* Disabled is aria-disabled + readonly, not :disabled, so the UA never
+       applies its own GrayText treatment — do it explicitly. */
+    .disabled,
+    .disabled input,
+    .disabled input::placeholder {
+        color: GrayText;
+    }
+
+    .disabled {
+        border-color: GrayText;
+    }
 }
 </style>

package/dist/Select.svelte.d.ts

@@ -1,5 +1,5 @@
-import type { ItemLike, SelectProps, SelectRow } from './types';
-import type { SelectItem } from './types';
+import type { ItemLike, SelectProps, SelectRow } from './types.js';
+import type { SelectItem } from './types.js';
 declare function $$render<Item extends ItemLike = SelectItem, Multiple extends boolean = false>(): {
     props: SelectProps<Item, Multiple>;
     exports: {

package/dist/aria-handlers.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { SelectItem } from './types';
+import type { SelectItem } from './types.js';
 interface AriaHandlersConfig {
     ariaValues: (values: string) => string;
     ariaListOpen: (label: string, count: number) => string;

package/dist/aria-handlers.svelte.js

@@ -1,3 +1,4 @@
+import { isItemSelectableCheck } from './utils.js';
 export function useAriaHandlers(config) {
     // Read the config properties at call time so live getters (see Select.svelte) stay reactive
     function handleAriaSelection(context) {
@@ -34,7 +35,17 @@ export function useAriaHandlers(config) {
             // screen-reader user can ever reach. Selectable headers
             // (groupHeaderSelectable) are real options and do count.
             const count = filteredItems.filter((item) => !(item.groupHeader && !item.selectable)).length;
-            return config.ariaListOpen(_item[label], count);
+            // This text renders before use-hover's keep-hover-selectable
+            // correction runs, so on the first open of a grouped list the cursor
+            // is still parked on a non-selectable header. Announce the option the
+            // correction is about to land on (the first selectable row — the same
+            // index checkHoverSelectable computes) instead of a row the cursor can
+            // never reach; the region won't recompute after the correction because
+            // hoverItemIndex is deliberately untracked (see Select.svelte).
+            const announced = isItemSelectableCheck(_item)
+                ? _item
+                : (filteredItems.find(isItemSelectableCheck) ?? _item);
+            return config.ariaListOpen(announced[label], count);
         }
         else {
             return config.ariaFocused();

package/dist/filter.d.ts

@@ -1,4 +1,4 @@
-import type { FilterConfig, ItemLike, SelectItem } from './types';
+import type { FilterConfig, ItemLike, SelectItem } from './types.js';
 /**
  * The built-in filtering pipeline: converts raw string items, applies
  * `itemFilter` against the filter text (skipped when `loadOptions` is set —

package/dist/filter.js

@@ -1,4 +1,4 @@
-import { areItemsEqual, isStringArray } from './utils';
+import { areItemsEqual, isStringArray } from './utils.js';
 /**
  * The built-in filtering pipeline: converts raw string items, applies
  * `itemFilter` against the filter text (skipped when `loadOptions` is set —

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { default as Select } from './Select.svelte';
 export { default as ChevronIcon } from './ChevronIcon.svelte';
 export { default as ClearIcon } from './ClearIcon.svelte';
 export { default as LoadingIcon } from './LoadingIcon.svelte';
-export { default as filter } from './filter';
-export { areItemsEqual, isGroupHeader, normalizeItem } from './utils';
-export type { ItemLike, SelectItem, SelectGroupHeader, SelectRow, SelectProps, SelectValue, SelectValueProp, SelectClearValue, JustValue, FloatingConfig, FilterConfig, SelectErrorEvent, } from './types';
+export { default as filter } from './filter.js';
+export { areItemsEqual, isGroupHeader, normalizeItem } from './utils.js';
+export type { ItemLike, SelectItem, SelectGroupHeader, SelectRow, SelectProps, SelectValue, SelectValueProp, SelectClearValue, JustValue, FloatingConfig, FilterConfig, SelectErrorEvent, } from './types.js';

package/dist/index.js

@@ -5,5 +5,5 @@ export { default as ChevronIcon } from './ChevronIcon.svelte';
 export { default as ClearIcon } from './ClearIcon.svelte';
 export { default as LoadingIcon } from './LoadingIcon.svelte';
 // Utility functions
-export { default as filter } from './filter';
-export { areItemsEqual, isGroupHeader, normalizeItem } from './utils';
+export { default as filter } from './filter.js';
+export { areItemsEqual, isGroupHeader, normalizeItem } from './utils.js';

package/dist/keyboard-navigation.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { ItemLike, KeyboardNavigationActions, KeyboardNavigationState, SelectItem } from './types';
+import type { ItemLike, KeyboardNavigationActions, KeyboardNavigationState, SelectItem } from './types.js';
 export declare function useKeyboardNavigation<Item extends ItemLike = SelectItem>(state: KeyboardNavigationState<Item>, actions: KeyboardNavigationActions): {
     handleKeyDown: (e: KeyboardEvent) => void;
     handleEscapeKey: (e: KeyboardEvent) => void;

package/dist/keyboard-navigation.svelte.js

@@ -1,4 +1,4 @@
-import { areItemsEqual, getItemProperty, isItemSelectableCheck } from './utils';
+import { areItemsEqual, getItemProperty, isItemSelectableCheck } from './utils.js';
 export function useKeyboardNavigation(state, actions) {
     // Handlers claim an event (preventDefault/stopPropagation) only on branches
     // that actually act on it. Unclaimed keys keep bubbling so ancestors still
@@ -11,6 +11,14 @@ export function useKeyboardNavigation(state, actions) {
         // disabled control must never mutate its value from the keyboard.
         if (!state.focused || state.disabled)
             return;
+        // While an IME composition is active every key belongs to the IME:
+        // Enter commits the conversion, arrows move through the candidate
+        // window, Escape cancels it. Acting on those presses would select the
+        // hovered option and wipe the half-composed filter text. keyCode 229
+        // catches the WebKit/legacy path where the composition keydown
+        // reports isComposing === false.
+        if (e.isComposing || e.keyCode === 229)
+            return;
         const handlers = {
             Escape: handleEscapeKey,
             Enter: handleEnterKey,

package/dist/no-styles/ChevronIcon.svelte

@@ -1,3 +1,9 @@
+<script lang="ts">
+    // Required even though empty: script-less components make svelte2tsx emit a
+    // legacy d.ts referencing `SvelteComponent` without importing it, which breaks
+    // consumers that type-check with skipLibCheck: false.
+</script>
+
 <svg width="100%" height="100%" viewBox="0 0 20 20" focusable="false" aria-hidden="true">
     <path
         fill="currentColor"

package/dist/no-styles/ChevronIcon.svelte.d.ts

@@ -1,18 +1,5 @@
-export default ChevronIcon;
-type ChevronIcon = SvelteComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {}> & {
-    $$bindings?: string | undefined;
-};
-declare const ChevronIcon: $$__sveltets_2_IsomorphicComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {}, {}, string>;
 interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
-    new (options: import("svelte").ComponentConstructorOptions<Props>): import("svelte").SvelteComponent<Props, Events, Slots> & {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
         $$bindings?: Bindings;
     } & Exports;
     (internal: unknown, props: {
@@ -24,3 +11,8 @@ interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> =
     };
     z_$$bindings?: Bindings;
 }
+declare const ChevronIcon: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type ChevronIcon = InstanceType<typeof ChevronIcon>;
+export default ChevronIcon;

package/dist/no-styles/ClearIcon.svelte

@@ -1,3 +1,9 @@
+<script lang="ts">
+    // Required even though empty: script-less components make svelte2tsx emit a
+    // legacy d.ts referencing `SvelteComponent` without importing it, which breaks
+    // consumers that type-check with skipLibCheck: false.
+</script>
+
 <svg width="100%" height="100%" viewBox="-2 -2 50 50" focusable="false" aria-hidden="true" role="presentation">
     <path
         fill="currentColor"

package/dist/no-styles/ClearIcon.svelte.d.ts

@@ -1,18 +1,5 @@
-export default ClearIcon;
-type ClearIcon = SvelteComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {}> & {
-    $$bindings?: string | undefined;
-};
-declare const ClearIcon: $$__sveltets_2_IsomorphicComponent<{
-    [x: string]: never;
-}, {
-    [evt: string]: CustomEvent<any>;
-}, {}, {}, string>;
 interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
-    new (options: import("svelte").ComponentConstructorOptions<Props>): import("svelte").SvelteComponent<Props, Events, Slots> & {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
         $$bindings?: Bindings;
     } & Exports;
     (internal: unknown, props: {
@@ -24,3 +11,8 @@ interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> =
     };
     z_$$bindings?: Bindings;
 }
+declare const ClearIcon: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type ClearIcon = InstanceType<typeof ClearIcon>;
+export default ClearIcon;