svelte-5-select 1.0.2 → 2.0.0

package/dist/Select.svelte

@@ -1,9 +1,27 @@
 <svelte:options runes={true} />
-<script lang="ts">
-    import { onDestroy, onMount, untrack } from 'svelte';
+
+<!--
+@component
+A select/autocomplete/typeahead control: a WAI-ARIA combobox with a floating
+listbox popup. Generic over your item type; supports multi-select, async
+loading (`loadOptions`), grouping (`groupBy`), and snippet-based customization.
+Bind `value` (and optionally `justValue`, `filterText`, `listOpen`, `focused`).
+-->
+
+<script lang="ts" generics="Item extends ItemLike = SelectItem, Multiple extends boolean = false">
+    import { onDestroy, onMount, tick, untrack } from 'svelte';
+    import { DEV } from 'esm-env';
     import { offset, flip, shift } from 'svelte-floating-ui/dom';
+    import type {
+        FloatingConfig,
+        ItemLike,
+        SelectProps,
+        SelectRow,
+        SelectValue,
+        SelectClearValue,
+        SelectErrorEvent,
+    } from './types';
     import { createFloatingActions } from 'svelte-floating-ui';
-    import type { FloatingConfig, SelectProps, SelectValue, ErrorEvent as SelectErrorEvent } from './types';
     import { useAriaHandlers } from './aria-handlers.svelte';
 
     import _filter from './filter';
@@ -13,27 +31,33 @@
     import LoadingIcon from './LoadingIcon.svelte';
     import type { SelectItem } from './types';
     import type { HTMLInputAttributes } from 'svelte/elements';
+    import { createSelectState } from './select-state.svelte';
     import { useKeyboardNavigation } from './keyboard-navigation.svelte';
     import { useHover } from './use-hover.svelte';
     import { useValue } from './use-value.svelte';
     import { useLoadOptions } from './use-load-options.svelte';
-    import { areItemsEqual, isItemSelectableCheck, createGroupHeaderItem as _createGroupHeaderItem } from './utils';
-
-    const defaultItemFilter = (label: string, filterText: string, option: SelectItem): boolean =>
+    import {
+        areItemsEqual,
+        convertStringItemsToObjects,
+        getItemProperty,
+        isItemSelectableCheck,
+        normalizeItem,
+        createGroupHeaderItem as _createGroupHeaderItem,
+    } from './utils';
+
+    const defaultItemFilter = (label: string, filterText: string, _option: SelectItem): boolean =>
         `${label}`.toLowerCase().includes(filterText?.toLowerCase());
 
-    const defaultOnError = (error: SelectErrorEvent): void => {};
-    const defaultOnLoaded = (options: SelectItem[]): void => {};
-    const defaultHandleClear = (e?: MouseEvent): void => {};
+    const defaultOnError = (_error: SelectErrorEvent): void => {};
+    const defaultOnLoaded = (_options: SelectItem[]): void => {};
 
     let timeout = $state<ReturnType<typeof setTimeout>>();
-    let clearState = $state(false);
 
     let {
         // Core data props
         filterText = $bindable(''),
         itemId = 'value',
-        items = $bindable<SelectItem[] | string[] | null>(null),
+        items = $bindable<Item[] | string[] | null>(null),
         justValue = $bindable(),
         label = 'label',
         value = $bindable(),
@@ -57,7 +81,7 @@
         filterSelectedItems = true,
         groupHeaderSelectable = false,
         multiFullItemClearable = false,
-        multiple = false,
+        multiple = false as Multiple,
         required = false,
         searchable = true,
         useJustValue = false,
@@ -65,7 +89,7 @@
         // Styling props
         containerStyles = '',
         inputStyles = '',
-        listStyle = '',
+        listStyles = '',
         hideEmptyState = false,
 
         // Advanced props
@@ -78,17 +102,14 @@
         loadOptionsDeps = [],
 
         // Function props
-        createGroupHeaderItem = (groupValue: string, item: SelectItem) => {
-            return _createGroupHeaderItem(groupValue, item, label);
+        createGroupHeaderItem = (groupValue: string, _item: Item) => {
+            return _createGroupHeaderItem(groupValue, label);
         },
         debounce = (fn: () => void, wait = 1) => {
             clearTimeout(timeout);
             timeout = setTimeout(fn, wait);
         },
         filter = _filter,
-        getFilteredItems = () => {
-            return filteredItems;
-        },
         groupBy = undefined,
         groupFilter = (groups: string[]) => groups,
         itemFilter = defaultItemFilter,
@@ -96,30 +117,46 @@
 
         // ARIA props
         ariaLabel = undefined,
+        ariaErrorMessage = undefined,
+        ariaClearSelectLabel = 'Clear selection',
+        ariaRemoveItemLabel = (label: string) => `Remove ${label}`,
+        ariaCleared = () => {
+            return `Selection cleared.`;
+        },
+        ariaEmpty = () => {
+            return `No options`;
+        },
         ariaFocused = () => {
-            return `Select is focused, type to refine list, press down to open the menu.`;
+            // In select-only mode (searchable={false}) the input is readonly, so
+            // "type to refine" would instruct an action that does nothing
+            return searchable
+                ? `Select is focused, type to refine list, press down to open the menu.`
+                : `Select is focused, press down to open the menu.`;
         },
         ariaListOpen = (label: string, count: number) => {
             return `You are currently focused on option ${label}. There are ${count} results available.`;
         },
+        ariaLoading = () => {
+            return `Loading Data`;
+        },
         ariaValues = (values: string) => {
             return `Option ${values}, selected.`;
         },
 
         // Custom behavior
-        handleClear = defaultHandleClear,
+        handleClear = internalHandleClear,
 
         // Event handlers
         onblur = () => {},
-        onchange = () => {},
         onclear = () => {},
         onerror = defaultOnError,
         onfilter = () => {},
         onfocus = () => {},
         onhoveritem = () => {},
-        oninput = () => {},
         onloaded = defaultOnLoaded,
         onselect = () => {},
+        onSelectionChange = () => {},
+        onValueChange = () => {},
 
         // Snippet props
         chevronIconSnippet,
@@ -137,22 +174,20 @@
         selectionSnippet,
 
         // DOM references (for binding)
-        container = undefined,
-        input = undefined,
+        container = $bindable(undefined),
+        input = $bindable(undefined),
         ...rest
-    }: SelectProps = $props();
-
-    let normalizedValue = $derived<SelectItem | SelectItem[] | null>(
-        !value
-            ? null
-            : typeof value === 'string'
-                ? { value, label: value }
-                : value
-    );
+    }: SelectProps<Item, Multiple> = $props();
 
-    const _generatedId = `svelte-select-${Math.random().toString(36).slice(2, 9)}`;
+    let normalizedValue = $derived<SelectItem | SelectItem[] | null>(normalizeItem(value));
+
+    const _uid = $props.id();
+    const _generatedId = `svelte-select-${_uid}`;
     let _id = $derived(id ?? _generatedId);
 
+    // Group headers render as options only when they are selectable; otherwise they are presentational
+    const isPresentationalHeader = (item: SelectItem | undefined): boolean => !!item?.groupHeader && !item.selectable;
+
     const DEFAULT_INPUT_ATTRS = {
         autocapitalize: 'none',
         autocomplete: 'off',
@@ -164,348 +199,632 @@
     } as const;
 
     const ariaHandlers = useAriaHandlers({
-        ariaValues,
-        ariaListOpen,
-        ariaFocused,
+        get ariaValues() {
+            return ariaValues;
+        },
+        get ariaListOpen() {
+            return ariaListOpen;
+        },
+        get ariaFocused() {
+            return ariaFocused;
+        },
+        get ariaEmpty() {
+            return ariaEmpty;
+        },
+        get ariaLoading() {
+            return ariaLoading;
+        },
     });
 
-    handleClear = (e?: MouseEvent): void => {
-        clearState = true;
-        onclear(value as SelectValue);
+    function internalHandleClear(_e?: MouseEvent): void {
+        selectState.clearState = true;
+        onclear(value as unknown as SelectClearValue<Item, Multiple>);
         value = undefined;
         closeList();
         handleFocus();
-    };
+    }
 
     let list = $state<HTMLDivElement | undefined>();
-    let _inputAttributes = $derived<HTMLInputAttributes>({
-        ...DEFAULT_INPUT_ATTRS,
-        role: 'combobox',
-        'aria-controls': listOpen ? `listbox-${_id}` : undefined,
-        'aria-expanded': listOpen,
-        'aria-haspopup': 'listbox',
-        'aria-activedescendant': listOpen ? `listbox-${_id}-item-${hoverItemIndex}` : undefined,
-        'aria-label': ariaLabel,
-        tabindex: 0,
-        readonly: !searchable,
-        id: id ? id : undefined,
-        ...inputAttributes,
+    let filteredItems = $derived.by<SelectItem[]>(() =>
+        filter({
+            loadOptions,
+            filterText,
+            items,
+            multiple,
+            value: normalizedValue,
+            itemId,
+            groupBy,
+            label,
+            filterSelectedItems,
+            itemFilter,
+            convertStringItemsToObjects,
+            applyGrouping,
+        }),
+    );
+
+    // Fold the flat filteredItems (header, item, item, header, …) into real
+    // listbox groups so each group can carry role="group" named by its header.
+    // Flat indices are preserved on every entry so ids, aria-activedescendant
+    // and hover keep working. Without groupBy every row is a plain option and
+    // the list renders flat exactly as before.
+    type GroupRow =
+        | { type: 'option'; item: SelectItem; index: number }
+        | { type: 'group'; headerIndex: number; header: SelectItem; options: { item: SelectItem; index: number }[] };
+
+    let groupedRows = $derived.by<GroupRow[]>(() => {
+        const rows: GroupRow[] = [];
+        let current: Extract<GroupRow, { type: 'group' }> | null = null;
+        filteredItems.forEach((item, index) => {
+            if (item.groupHeader) {
+                current = { type: 'group', headerIndex: index, header: item, options: [] };
+                rows.push(current);
+            } else if (item.groupItem && current) {
+                current.options.push({ item, index });
+            } else {
+                current = null;
+                rows.push({ type: 'option', item, index });
+            }
+        });
+        return rows;
+    });
+    // The option the combobox currently points at. With a custom listSnippet the
+    // consumer owns option rendering, so this only resolves if they honour the
+    // documented id contract — a dev-only effect below warns when it dangles.
+    let _activeDescendantId = $derived(
+        listOpen && filteredItems[hoverItemIndex] && !isPresentationalHeader(filteredItems[hoverItemIndex])
+            ? `listbox-${_id}-item-${hoverItemIndex}`
+            : undefined,
+    );
+    let _inputAttributes = $derived.by<HTMLInputAttributes>(() => {
+        const attrs: HTMLInputAttributes = {
+            ...DEFAULT_INPUT_ATTRS,
+            // The APG select-only pattern has no autocomplete behavior: with
+            // searchable={false} the input is readonly and typing never refines
+            // the list, so advertising list-autocomplete would misinform AT
+            'aria-autocomplete': searchable ? ('list' as const) : undefined,
+            // The selection renders in a sibling div, so the combobox's own
+            // accessible value is the (empty) filter text; describe the element
+            // holding the selection so browse-mode users can read it from the
+            // input itself. Multiple mode is excluded: each chip is separately
+            // focusable and announced, and the description would also read
+            // every remove-button label.
+            'aria-describedby': !multiple && value ? `selected-${_id}` : undefined,
+            role: 'combobox',
+            'aria-controls': listOpen ? `listbox-${_id}` : undefined,
+            'aria-expanded': listOpen,
+            'aria-haspopup': 'listbox',
+            'aria-activedescendant': _activeDescendantId,
+            // Only an explicit ariaLabel: a default aria-label would override an external
+            // <label for={id}> in accessible-name computation. Without either, the
+            // placeholder still names the input as the spec's last-resort fallback.
+            'aria-label': ariaLabel,
+            'aria-required': required || undefined,
+            'aria-invalid': hasError || undefined,
+            // aria-errormessage is only meaningful alongside aria-invalid="true"
+            'aria-errormessage': hasError && ariaErrorMessage ? ariaErrorMessage : undefined,
+            readonly: !searchable,
+            id: id ? id : undefined,
+            ...inputAttributes,
+            // Disabled is expressed with aria-disabled + readonly rather than the native
+            // `disabled` attribute so the current value stays in the accessibility tree
+            // and screen readers can still announce it. Spread last (after
+            // inputAttributes) so a disabled control is never left interactive or
+            // tab-reachable; interaction is blocked by the `disabled` guards in
+            // handleClick/handleFocus/handleItemClick and the disabled effect, which
+            // also force-closes a programmatically opened list.
+            ...(disabled ? { 'aria-disabled': true, readonly: true, tabindex: -1 } : {}),
+        };
+        // A consumer handler in inputAttributes must add to the input's own
+        // oninput/onblur/onfocus/onkeydown, not replace them: these attributes
+        // are spread after the template's handlers (later-spread-wins), which
+        // would otherwise silently disable filtering, focus handling, and
+        // keyboard navigation. Composed order: the component's handler first,
+        // then the consumer's.
+        const internalHandlers = {
+            oninput: handleInput,
+            onblur: handleBlur,
+            onfocus: handleFocus,
+            onkeydown: handleKeyDown,
+        };
+        for (const key of Object.keys(internalHandlers) as (keyof typeof internalHandlers)[]) {
+            const consumer = inputAttributes?.[key];
+            if (typeof consumer !== 'function') continue;
+            const internal = internalHandlers[key] as (e: Event) => unknown;
+            (attrs as Record<string, unknown>)[key] = (e: Event) => {
+                internal(e);
+                (consumer as (e: Event) => unknown)(e);
+            };
+        }
+        return attrs;
     });
-    let activeValue = $state<number | undefined>(undefined);
-    let prev_value = $state<SelectItem | SelectItem[] | string | null | undefined>();
-    let prev_filterText: string | undefined = $state();
-    let prev_multiple = $state();
-    let isScrolling = $state(false);
     let prefloat = $state(true);
-    let hasValue = $state(false);
+    let hasValue = $derived(multiple ? Array.isArray(value) && value.length > 0 : !!value);
     let placeholderText = $derived(
         placeholderAlwaysShow && multiple
             ? placeholder
-            : multiple && value?.length === 0
-                ? placeholder
-                : value ? '' : placeholder
-    );
-    let showClear = $derived(
-        hasValue && clearable && !disabled && !loading
-    );
-    let hideSelectedItem = $derived(
-        hasValue && filterText.length > 0
-    );
-    let filteredItems = $state<SelectItem[]>([]);
-
-    let ariaContext = $derived(
-        ariaHandlers.handleAriaContent({
-            value,
-            filteredItems,
-            hoverItemIndex,
-            listOpen,
-            multiple,
-            label,
-        })
+            : multiple && Array.isArray(value) && value.length === 0
+              ? placeholder
+              : value
+                ? ''
+                : placeholder,
     );
+    let showClear = $derived(hasValue && clearable && !disabled && !loading);
+    let hideSelectedItem = $derived(hasValue && filterText.length > 0);
+
+    /**
+     * Instance export — call via a `bind:this` reference: returns the currently
+     * rendered rows. They include any group headers synthesized by `groupBy`
+     * (hence `SelectRow` rather than `Item`); narrow with `isGroupHeader`.
+     */
+    export function getFilteredItems(): SelectRow<Item>[] {
+        return filteredItems as SelectRow<Item>[];
+    }
+
+    // Announce a cleared selection explicitly: the live region uses
+    // aria-relevant="additions text", so merely emptying the selection span
+    // announces nothing.
+    let selectionCleared = $state(false);
+    let prevHadValue = false; // seeded by the first effect run below
+    $effect(() => {
+        hasValue;
+        focused;
+        untrack(() => {
+            if (!focused || hasValue) {
+                selectionCleared = false;
+            } else if (prevHadValue) {
+                selectionCleared = true;
+            }
+            prevHadValue = hasValue;
+        });
+    });
+
     let ariaSelection = $derived(
-        value ? ariaHandlers.handleAriaSelection({
-            value,
-            filteredItems,
-            hoverItemIndex,
-            listOpen,
-            multiple,
-            label,
-        }) : ''
+        hasValue
+            ? ariaHandlers.handleAriaSelection({
+                  value,
+                  filteredItems,
+                  hoverItemIndex,
+                  listOpen,
+                  multiple,
+                  label,
+              })
+            : selectionCleared
+              ? ariaCleared()
+              : '',
     );
 
+    // svelte-floating-ui keeps a reference to this object; effects below mutate it in place
     let _floatingConfig = $state<FloatingConfig>({
         strategy: 'absolute',
         placement: 'bottom-start',
-        middleware: [offset(listOffset), flip(), shift()],
         autoUpdate: false,
     });
 
-    // Initialize composables
-    const valueManager = useValue({
-        getState: () => ({
-            value,
-            prevValue: prev_value,
-            items,
-            multiple,
-            itemId,
-            label,
-            hasValue,
-            normalizedValue,
-            useJustValue,
-            justValue,
-            clearState,
-            closeListOnChange,
-        }),
-        setValue: (v) => value = v,
-        setJustValue: (v) => justValue = v,
-        setPrevValue: (v) => prev_value = v,
-        setClearState: (v) => clearState = v,
-        setActiveValue: (v) => activeValue = v,
-        setFilterText: (v) => filterText = v,
-        closeList,
-        oninput: (v) => oninput?.(v as SelectValue),
-        onchange: (v) => onchange?.(v as SelectValue),
-        onclear: (v) => onclear(v as SelectValue),
-        onselect: (s) => onselect?.(s),
+    // The shared reactive state object: live accessors over the props and derived
+    // values above, plus internal shared state owned by the factory. Composables
+    // read and write these fields directly.
+    const selectState = createSelectState<Item>({
+        get value() {
+            return value;
+        },
+        set value(v) {
+            value = v;
+        },
+        get items() {
+            return items;
+        },
+        set items(v) {
+            items = v;
+        },
+        get filterText() {
+            return filterText;
+        },
+        set filterText(v) {
+            filterText = v;
+        },
+        get justValue() {
+            return justValue;
+        },
+        set justValue(v) {
+            justValue = v;
+        },
+        get listOpen() {
+            return listOpen;
+        },
+        set listOpen(v) {
+            listOpen = v;
+        },
+        get loading() {
+            return loading;
+        },
+        set loading(v) {
+            loading = v;
+        },
+        get focused() {
+            return focused;
+        },
+        set focused(v) {
+            focused = v;
+        },
+        get hoverItemIndex() {
+            return hoverItemIndex;
+        },
+        set hoverItemIndex(v) {
+            hoverItemIndex = v;
+        },
+        get multiple() {
+            return multiple;
+        },
+        get itemId() {
+            return itemId;
+        },
+        get label() {
+            return label;
+        },
+        get searchable() {
+            return searchable;
+        },
+        get disabled() {
+            return disabled;
+        },
+        get useJustValue() {
+            return useJustValue;
+        },
+        get closeListOnChange() {
+            return closeListOnChange;
+        },
+        get debounceWait() {
+            return debounceWait;
+        },
+        get groupBy() {
+            return groupBy;
+        },
+        get loadOptions() {
+            return loadOptions;
+        },
+        get loadOptionsDeps() {
+            return loadOptionsDeps;
+        },
+        get filteredItems() {
+            return filteredItems;
+        },
+        get normalizedValue() {
+            return normalizedValue;
+        },
+        get hasValue() {
+            return hasValue;
+        },
     });
 
-    const hoverManager = useHover({
-        getState: () => ({
-            listOpen,
-            filteredItems,
-            hoverItemIndex,
-            multiple,
-            value,
-            isScrolling,
-            groupBy,
-            itemId,
-        }),
-        setHoverItemIndex: (v) => hoverItemIndex = v,
-        setIsScrolling: (v) => isScrolling = v,
-        onhoveritem: (i) => onhoveritem?.(i),
+    // The active-tag mechanism (ArrowLeft/ArrowRight + Backspace) is otherwise
+    // only visible as a CSS outline; announce it so non-sighted users can use it
+    let activeTagLabel = $derived(
+        multiple && selectState.activeValue !== undefined && Array.isArray(value)
+            ? ((value as Item[])[selectState.activeValue]?.[label] as string | undefined)
+            : undefined,
+    );
+    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.`;
+        }
+        // Tracked triggers: the list opening/closing, the result count changing
+        // (filtering), and the loading flag. hoverItemIndex is deliberately read
+        // untracked — aria-activedescendant already announces each option as the
+        // keyboard cursor lands on it, so recomputing here per keystroke made every
+        // arrow key announce the option name twice AND re-read the whole result
+        // count. Leaving the region's text unchanged means it simply stays silent
+        // while arrowing, which is what the APG pattern expects.
+        listOpen;
+        filteredItems.length;
+        loading;
+        return untrack(() =>
+            ariaHandlers.handleAriaContent({
+                value,
+                filteredItems,
+                hoverItemIndex,
+                listOpen,
+                multiple,
+                label,
+                loading,
+            }),
+        );
     });
 
-    const loadOptionsManager = useLoadOptions({
-        getState: () => ({
-            filterText,
-            prevFilterText: prev_filterText,
-            loadOptionsDeps,
-            loadOptions,
-            disabled,
-            multiple,
-            value,
-            items,
-            itemId,
-            useJustValue,
-            justValue,
-            listOpen,
-            debounceWait,
-        }),
-        setItems: (v) => items = v,
-        setValue: (v) => value = v,
-        setJustValue: (v) => justValue = v,
-        setLoading: (v) => loading = v,
-        setListOpen: (v) => listOpen = v,
-        debounce,
-        convertStringItemsToObjects: valueManager.convertStringItemsToObjects,
-        onloaded: (opts) => onloaded(opts),
+    // Initialize composables (creation order is effect order: value, hover, load options)
+    const valueManager = useValue(selectState, {
+        closeList,
+        // Deferred: loadOptionsManager is created a few lines below
+        retireStaleValidation: () => loadOptionsManager.retireValidationForFreshSelection(),
+        onValueChange: (v) => onValueChange?.(v as unknown as SelectValue<Item, Multiple>),
+        onSelectionChange: (v) => onSelectionChange?.(v as unknown as SelectValue<Item, Multiple>),
+        onclear: (v) => onclear(v as unknown as SelectClearValue<Item, Multiple>),
+        onselect: (s) => onselect?.(s as Item),
+    });
+
+    const hoverManager = useHover(selectState);
+
+    const loadOptionsManager = useLoadOptions(selectState, {
+        debounce: (fn, wait) => debounce(fn, wait),
+        onloaded: (opts) => onloaded(opts as (Item | SelectItem)[]),
         onerror: (err) => onerror(err),
     });
 
-    const keyboardNav = useKeyboardNavigation({
-        getState: () => ({
-            listOpen,
-            filteredItems,
-            hoverItemIndex,
-            multiple,
-            value,
-            filterText,
-            activeValue,
-            itemId,
-            focused,
-        }),
-        setListOpen: (v) => listOpen = v,
-        setHoverItemIndex: (v) => hoverItemIndex = v,
-        setActiveValue: (v) => activeValue = v,
+    const keyboardNav = useKeyboardNavigation(selectState, {
         closeList,
         setHoverIndex: hoverManager.setHoverIndex,
         handleSelect,
         handleMultiItemClear: valueManager.handleMultiItemClear,
     });
-    const handleKeyDown = keyboardNav.handleKeyDown;
+
+    // Keyboard navigation must keep the hovered option visible. This hooks the
+    // key handler rather than an effect on hoverItemIndex so mouse hover never
+    // triggers scrolling.
+    function handleKeyDown(e: KeyboardEvent): void {
+        keyboardNav.handleKeyDown(e);
+        const isTypeAhead = !searchable && e.key.length === 1;
+        if (
+            e.key === 'ArrowDown' ||
+            e.key === 'ArrowUp' ||
+            e.key === 'Home' ||
+            e.key === 'End' ||
+            e.key === 'PageDown' ||
+            e.key === 'PageUp' ||
+            isTypeAhead
+        ) {
+            void tick().then(scrollHoveredItemIntoView);
+        }
+    }
+
+    function scrollHoveredItemIntoView(): void {
+        if (!listOpen || !list) return;
+        const el = document.getElementById(`listbox-${_id}-item-${hoverItemIndex}`);
+        el?.scrollIntoView?.({ block: 'nearest' });
+    }
 
     const [floatingRef, floatingContent, floatingUpdate] = createFloatingActions(_floatingConfig);
 
     onMount(() => {
+        // A disabled Select never grabs focus on mount; the disabled effect
+        // below also normalizes an initial `focused: true` back to false.
+        if (disabled) return;
         if (listOpen) focused = true;
         if (focused && input) input.focus();
     });
 
-    // Filter items
+    // Keep the floating middleware in sync with listOffset. User overrides are
+    // merged INTO _floatingConfig: svelte-floating-ui re-reads that object on its
+    // own deferred/autoUpdate recomputes, so a merge into a throwaway copy would
+    // be reverted one tick later.
     $effect.pre(() => {
-        filterText;
-        value;
-        items;
-        untrack(
-            () =>
-                (filteredItems = filter({
-                    loadOptions: undefined,
-                    filterText,
-                    items,
-                    multiple,
-                    value: normalizedValue,
-                    itemId,
-                    groupBy,
-                    label,
-                    filterSelectedItems,
-                    itemFilter,
-                    convertStringItemsToObjects: valueManager.convertStringItemsToObjects,
-                    filterGroupedItems,
-                })),
-        );
-    });
-
-    // Set value on hasValue change
-    $effect(() => {
-        hasValue;
+        const middleware = [offset(listOffset), flip(), shift()];
+        floatingConfig;
         untrack(() => {
-            if (items) valueManager.setValue();
+            _floatingConfig.middleware = middleware;
+            if (floatingConfig) Object.assign(_floatingConfig, floatingConfig);
+            if (container && list) {
+                floatingUpdate(_floatingConfig);
+            }
         });
     });
 
-    // Setup multi when multiple changes
+    // Sync the focused prop with real DOM focus, and close the list on unfocus.
+    // `bind:focused` is documented as writable, so a parent write must move real
+    // DOM focus: `focused = true` alone used to leave focus elsewhere while the
+    // window keydown handler (gated only on `focused`) claimed arrow/Enter keys
+    // page-wide, with no blur ever able to reset it. Transition-guarded so the
+    // mount run doesn't closeList(), which wiped an initial filterText via
+    // clearFilterTextOnBlur while the mount loadOptions fetch used the original text.
+    let prevFocused = focused;
     $effect(() => {
-        if (multiple) {
-            untrack(() => valueManager.setupMulti());
-        }
+        focused;
+        untrack(() => {
+            if (focused === prevFocused) return;
+            prevFocused = focused;
+            if (focused) {
+                if (disabled) {
+                    // A disabled Select cannot be focused programmatically
+                    focused = false;
+                    prevFocused = false;
+                    return;
+                }
+                if (input && document.activeElement !== input) handleFocus();
+            } else {
+                closeList();
+                selectState.activeValue = undefined;
+                if (input && document.activeElement === input) input.blur();
+            }
+        });
     });
 
-    // Clear value when switching from multiple to single
+    // Setup filter text: every write after mount behaves like typing (opens the
+    // list); only the mount run stays passive — an initial filterText filters
+    // (and fetches, with loadOptions) without opening the list or moving focus.
+    // A first-run flag, not a prevFilterText compare: the effect only reruns on
+    // real changes, and the old compare against the last *typed* value silently
+    // ignored a programmatic write that happened to equal it (fetching against
+    // a closed list with loadOptions).
+    let filterTextSeeded = false;
     $effect(() => {
-        if (prev_multiple && !multiple && value) {
-            value = null;
-        }
-        prev_multiple = multiple;
+        filterText;
+        untrack(() => {
+            if (!filterTextSeeded) {
+                filterTextSeeded = true;
+                return;
+            }
+            setupFilterText();
+        });
     });
 
-    // Check for duplicates
+    // Fire onhoveritem. The callback runs untracked: reactive reads inside a
+    // consumer callback must not become dependencies of this effect, and an
+    // inline callback prop changing identity per parent render must not refire.
     $effect(() => {
-        if (multiple && value && value.length > 1) {
-            untrack(() => valueManager.checkValueForDuplicates());
-        }
+        hoverItemIndex;
+        untrack(() => onhoveritem?.(hoverItemIndex));
     });
 
-    // Dispatch selected item
+    // Fire onfilter — untracked like onhoveritem; an onfilter that writes
+    // `items` would otherwise loop through filteredItems
     $effect(() => {
-        if (value) {
-            untrack(() => valueManager.dispatchSelectedItem());
-        }
+        filteredItems;
+        listOpen;
+        untrack(() => {
+            if (filteredItems && listOpen) onfilter?.(filteredItems as SelectRow<Item>[]);
+        });
     });
 
-    // Value cleared notification
+    // Floating UI config
     $effect(() => {
-        if (prev_value && !value) {
-            oninput?.((value || []) as SelectValue);
+        if (container && floatingConfig) {
+            untrack(() => {
+                Object.assign(_floatingConfig, floatingConfig);
+                floatingUpdate(_floatingConfig);
+            });
         }
     });
 
-    // Close list on unfocus
-    $effect(() => {
-        if (!focused && input) closeList();
-    });
-
-    // Setup filter text
+    // List mounted
     $effect(() => {
-        filterText;
+        listOpen;
         untrack(() => {
-            if (filterText !== prev_filterText) setupFilterText();
+            // A closed list retires Tab's commit-intent; the next open starts
+            // from an auto-parked cursor again (see handleTabKey). Reset on
+            // close, not open: a type-ahead press that opens the list parks
+            // the cursor in the same handler, and a reset-on-open flush would
+            // clobber that intent.
+            if (!listOpen) selectState.userNavigatedSinceOpen = false;
+            listMounted(list, listOpen);
+            if (listOpen && container && list) {
+                setListWidth();
+                // Opening with a value starts hovered on that value; bring it into view
+                void tick().then(scrollHoveredItemIntoView);
+            }
         });
     });
 
-    // Set value index as hover when list opens
-    $effect(() => {
-        if (!multiple && listOpen && value && filteredItems) {
-            untrack(() => hoverManager.setValueIndexAsHoverIndex());
-        }
-    });
-
-    // Fire onhoveritem
+    // Focus when list opens
     $effect(() => {
-        onhoveritem?.(hoverItemIndex);
+        if (input && listOpen && !focused) handleFocus();
     });
 
-    // Compute hasValue
+    // Dev-only: a custom listSnippet takes over option rendering, so the combobox's
+    // aria-activedescendant only resolves if the consumer reproduces the option ids.
+    // A dangling activedescendant points assistive tech at nothing, which is worse
+    // than a plain listbox — so surface it rather than letting it fail silently.
     $effect(() => {
-        multiple;
-        value;
+        if (!DEV) return;
+        const activeId = _activeDescendantId;
+        const hasListSnippet = !!listSnippet;
         untrack(() => {
-            hasValue = multiple
-                ? !!(value && value.length > 0)
-                : !!value;
+            if (!hasListSnippet || !activeId || document.getElementById(activeId)) return;
+            console.warn(
+                `[svelte-select] listSnippet is rendering the list, but no element with id "${activeId}" ` +
+                    "exists, so the combobox's aria-activedescendant points at nothing and screen readers " +
+                    'cannot follow keyboard navigation. Give each option you render ' +
+                    `id="listbox-${_id}-item-{index}" (matching its index in the snippet argument) and ` +
+                    'role="option".',
+            );
         });
     });
 
-    // Compute justValue
+    // Dev-only: items are compared by their `itemId` field everywhere
+    // (selection, hover, dedup), and entries missing that field all compare
+    // equal — the first pick works, every later click on a different option
+    // reads "already selected" and just closes the list, and every option
+    // renders selected. The failure is completely silent, so surface the
+    // config error instead.
+    let warnedAboutMissingItemId = false;
     $effect(() => {
-        multiple;
-        itemId;
-        value;
+        if (!DEV) return;
+        const currentItems = items;
+        const currentItemId = itemId;
         untrack(() => {
-            justValue = valueManager.computeJustValue();
+            if (warnedAboutMissingItemId || !currentItems?.length) return;
+            const missing = (currentItems as (Item | string)[]).some(
+                (item) => typeof item !== 'string' && getItemProperty(item, currentItemId) === undefined,
+            );
+            if (!missing) return;
+            warnedAboutMissingItemId = true;
+            console.warn(
+                `[svelte-select] Some items have no "${currentItemId}" field (the current \`itemId\`). ` +
+                    'Items are compared by that field, so items without it all compare as the same ' +
+                    'item — selection, hover state, and deduplication will misbehave. Point `itemId` ' +
+                    'at a field your items actually have, or add the field to your items.',
+            );
         });
     });
 
-    // Check hover selectable
+    // 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.
     $effect(() => {
-        filteredItems;
-        value;
-        multiple;
-        listOpen;
+        // Gate on esm-env's DEV, never on Vite's build-time env object: that object
+        // is undefined outside a Vite bundle, so reading its DEV flag threw at mount
+        // for rollup/webpack/no-build consumers. esm-env resolves per-bundler and
+        // tree-shakes this whole effect out of production builds.
+        if (!DEV) return;
+        input;
+        ariaLabel;
         untrack(() => {
-            if (listOpen && filteredItems.length > 0) {
-                if (!isItemSelectableCheck(filteredItems[hoverItemIndex])) {
-                    hoverManager.checkHoverSelectable();
-                } else if (groupBy && hoverItemIndex === 0) {
-                    hoverManager.checkHoverSelectable();
-                }
+            if (!input) return;
+            const named = !!ariaLabel || !!input.getAttribute('aria-labelledby') || (input.labels?.length ?? 0) > 0;
+            if (!named) {
+                console.warn(
+                    '[svelte-select] The Select input has no accessible name. Pass `ariaLabel`, ' +
+                        'or set the `id` prop and add a matching `<label for={id}>`, so screen readers ' +
+                        'can announce the field. The placeholder is only a last-resort fallback and is ' +
+                        'ignored by some assistive tech.',
+                );
             }
         });
     });
 
-    // Fire onfilter
-    $effect(() => {
-        if (filteredItems && listOpen) onfilter?.(filteredItems);
-    });
-
-    // Floating UI config
-    $effect(() => {
-        if (container && floatingConfig) floatingUpdate({..._floatingConfig, ...floatingConfig});
-    });
-
-    // List mounted
+    // The listbox needs its own accessible name (ARIA 1.2): `ariaLabel` covers
+    // one recommended naming path, but the others — `id` + external `<label for>`
+    // or an `aria-labelledby` supplied through `inputAttributes` — name only the
+    // input; neither cascades to the floating list. Resolve a name when the list
+    // opens, in the same precedence the input uses: explicit ariaLabel, then the
+    // input's own aria-labelledby (forwarded), then the associated label —
+    // referenced via aria-labelledby when it is external and has an id (live
+    // text), otherwise a text snapshot. The consumer's label is never mutated.
+    let listboxLabelledby = $state<string | undefined>();
+    let listboxLabelText = $state<string | undefined>();
     $effect(() => {
         listOpen;
+        ariaLabel;
         untrack(() => {
-            listMounted(list, listOpen);
-            if (listOpen && container && list) setListWidth();
+            listboxLabelledby = undefined;
+            listboxLabelText = undefined;
+            if (!listOpen || ariaLabel || !input) return;
+            const inputLabelledby = input.getAttribute('aria-labelledby');
+            if (inputLabelledby) {
+                listboxLabelledby = inputLabelledby;
+                return;
+            }
+            const labelEl = input.labels?.[0];
+            if (!labelEl) return;
+            // An implicit wrapping <label> contains the component itself, so
+            // both aria-labelledby and a plain textContent snapshot would pull
+            // in everything rendered inside (chips, options, live regions).
+            // Snapshot only the label's own text — the nodes outside this
+            // component's subtree.
+            const wrapsComponent = container ? labelEl.contains(container) : false;
+            if (!wrapsComponent && labelEl.id) {
+                listboxLabelledby = labelEl.id;
+            } else if (!wrapsComponent) {
+                listboxLabelText = labelEl.textContent?.trim() || undefined;
+            } else {
+                let text = '';
+                for (const node of labelEl.childNodes) {
+                    if (node === container || (node instanceof Element && container && node.contains(container)))
+                        continue;
+                    text += node.textContent ?? '';
+                }
+                listboxLabelText = text.trim() || undefined;
+            }
         });
     });
 
-    // Focus when list opens
-    $effect(() => {
-        if (input && listOpen && !focused) handleFocus();
-    });
-
-    // Reset hover on filterText change
-    $effect(() => {
-        if (filterText) {
-            untrack(() => {
-                hoverItemIndex = hoverManager.getFirstSelectableIndex();
-            });
-        }
-    });
-
     // Auto update floating config
     $effect(() => {
         if (container && floatingConfig?.autoUpdate === undefined) {
@@ -515,44 +834,41 @@
 
     // Disabled state
     $effect(() => {
-        if (disabled) {
+        disabled;
+        // listOpen is a tracked trigger too: neither setupFilterText nor the list
+        // template gates on disabled, so a programmatic bind:listOpen (or
+        // filterText) write while disabled would otherwise render an operable
+        // list — this effect only reruns on `disabled` flips without it.
+        listOpen;
+        untrack(() => {
+            if (!disabled) return;
             listOpen = false;
             filterText = '';
-        }
-    });
-
-    // Load options handler
-    $effect(() => {
-        const currentFilterText = filterText;
-        const currentDeps = [...loadOptionsDeps];
-
-        if (loadOptions) {
-            untrack(() => {
-                loadOptionsManager.handleLoadOptions(currentFilterText, currentDeps);
-            });
-
-            // Keep outside untrack for proper reactivity
-            if (!disabled && currentFilterText.length > 0 && !listOpen) {
-                listOpen = true;
-            }
-        }
+            // Disabling must also release focus: every keyboard handler gates
+            // on `focused`, so a Select disabled while it held focus stayed
+            // fully keyboard-operable (list toggling, Enter selection,
+            // Backspace tag removal) despite being aria-disabled. This also
+            // normalizes an initial `focused: true, disabled: true` mount.
+            if (focused) focused = false;
+            if (input && document.activeElement === input) input.blur();
+        });
     });
 
-    function filterGroupedItems(_items: SelectItem[]): SelectItem[] {
+    function applyGrouping(_items: SelectItem[]): SelectItem[] {
         if (!groupBy) return _items;
 
         const groupValues: string[] = [];
         const groups: Record<string, SelectItem[]> = {};
 
         _items.forEach((item) => {
-            const groupValue: string = groupBy(item);
+            const groupValue: string = groupBy(item as Item);
 
             if (!groupValues.includes(groupValue)) {
                 groupValues.push(groupValue);
                 groups[groupValue] = [];
                 if (groupValue) {
                     groups[groupValue].push(
-                        Object.assign(createGroupHeaderItem(groupValue, item), {
+                        Object.assign(createGroupHeaderItem(groupValue, item as Item), {
                             id: groupValue,
                             groupHeader: true,
                             selectable: groupHeaderSelectable,
@@ -575,8 +891,13 @@
 
     function setupFilterText() {
         if (loadOptions) {
-            if (filterText.length > 0 && !listOpen) {
-                listOpen = true;
+            if (filterText.length > 0) {
+                if (!listOpen) listOpen = true;
+                // Typing dismisses an armed tag cursor here too — mirrors the
+                // non-loadOptions branch below; without this the cursor stayed
+                // highlighted and announced while the user typed (Backspace
+                // itself was already guarded by the filterText check)
+                if (multiple) selectState.activeValue = undefined;
             }
             return;
         }
@@ -586,11 +907,14 @@
         listOpen = true;
 
         if (multiple) {
-            activeValue = undefined;
+            selectState.activeValue = undefined;
         }
     }
 
     function handleFocus(e?: FocusEvent): void {
+        // The input is no longer natively `disabled`, so it can still be
+        // click-focused — keep a disabled Select non-interactive here.
+        if (disabled) return;
         if (focused && input === document?.activeElement) return;
         if (e) {
             onfocus?.(e);
@@ -599,17 +923,38 @@
         focused = true;
     }
 
+    // A blur while the list is scrolling is deferred, not dropped: DOM focus is
+    // already gone, so no further blur will ever fire — without a replay the list
+    // stays open and the window keydown handler keeps hijacking keys.
+    let pendingBlur: FocusEvent | boolean = false;
+
     async function handleBlur(e?: FocusEvent): Promise<void> {
-        if (isScrolling) return;
+        if (selectState.isScrolling) {
+            pendingBlur = e ?? true;
+            return;
+        }
+        pendingBlur = false;
         if (listOpen || focused) {
             if (e) onblur?.(e);
             closeList();
             focused = false;
-            activeValue = undefined;
+            selectState.activeValue = undefined;
             input?.blur();
         }
     }
 
+    // Replay a deferred blur once scrolling settles — unless focus is back on
+    // the input (the scroll itself blurred it only transiently)
+    $effect(() => {
+        selectState.isScrolling;
+        untrack(() => {
+            if (selectState.isScrolling || pendingBlur === false) return;
+            const deferred = pendingBlur === true ? undefined : pendingBlur;
+            pendingBlur = false;
+            if (document.activeElement !== input) void handleBlur(deferred);
+        });
+    });
+
     function handleClick(ev: MouseEvent) {
         ev.preventDefault();
         if (disabled) return;
@@ -622,17 +967,25 @@
             filterText = '';
         }
         listOpen = false;
-    }
-
-    function handleClickOutside(event: MouseEvent): void {
-        const target = event.target as Node;
-        if (!listOpen && !focused && container && !container.contains(target) && !list?.contains(target)) {
-            handleBlur();
-        }
+        // Reset Tab's commit-intent synchronously, not only in the listOpen
+        // effect below: a consumer callback that reopens the list in the same
+        // flush would otherwise carry stale intent into the reopened list (the
+        // effect would run once and only ever observe listOpen === true)
+        selectState.userNavigatedSinceOpen = false;
+        // A load armed by typing must not fire (spinner + stale items) on a closed list;
+        // reads through the effect miss this when clearFilterTextOnBlur is false
+        loadOptionsManager.cancelPendingFilterLoad();
     }
 
     onDestroy(() => {
+        // The floating list can outlive the component's own tree; remove it explicitly
+        // eslint-disable-next-line svelte/no-dom-manipulating
         list?.remove();
+        // A debounced load firing after unmount would fetch and invoke callbacks
+        // on a dead component
+        clearTimeout(timeout);
+        clearTimeout(prefloatTimeout);
+        loadOptionsManager.invalidateLoads();
     });
 
     function handleSelect(item: SelectItem): void {
@@ -641,23 +994,30 @@
     }
 
     function handleItemClick(item: SelectItem, i: number): void {
+        // Defence in depth: the disabled effect force-closes the list, but a
+        // pointer must never mutate a disabled control's value even if a list
+        // is momentarily rendered
+        if (disabled) return;
         if (item?.selectable === false) return;
-        if (!multiple && areItemsEqual(normalizedValue, item, itemId)) return closeList();
+        if (!multiple && !Array.isArray(normalizedValue) && areItemsEqual(normalizedValue, item, itemId))
+            return closeList();
         if (hoverManager.isItemSelectable(item)) {
             hoverItemIndex = i;
             handleSelect(item);
         }
     }
 
-    function setListWidth():void {
+    function setListWidth(): void {
         if (!container || !list) return;
         const { width } = container.getBoundingClientRect();
         list.style.width = listAutoWidth ? width + 'px' : 'auto';
     }
 
+    let prefloatTimeout: ReturnType<typeof setTimeout> | undefined;
     function listMounted(list: HTMLDivElement | undefined, listOpen: boolean) {
         if (!list || !listOpen) return (prefloat = true);
-        setTimeout(() => {
+        clearTimeout(prefloatTimeout);
+        prefloatTimeout = setTimeout(() => {
             prefloat = false;
         }, 0);
     }
@@ -665,23 +1025,35 @@
     function handleInput(ev: Event): void {
         const target = ev.target as HTMLInputElement;
         listOpen = true;
-        prev_filterText = filterText;
+        selectState.prevFilterText = filterText;
         filterText = target.value;
+        // Typing this session is commit-intent for Tab (see handleTabKey).
+        // Marked here — on the real input event — rather than gating on the
+        // current filterText, so a consumer-seeded initial value or text
+        // retained across a close (clearFilterTextOnBlur={false}) can't arm a
+        // commit the user never expressed.
+        selectState.userNavigatedSinceOpen = true;
     }
 
+    /**
+     * Instance export — call via a `bind:this` reference: clears the selection,
+     * filter text, and open/focus state back to an empty control. Does not fire
+     * `onclear` (it is a programmatic reset, not a user clear).
+     */
     export function reset(): void {
-        clearState = true;
+        selectState.clearState = true;
         value = undefined;
         filterText = '';
         listOpen = false;
         hoverItemIndex = 0;
-        activeValue = undefined;
+        selectState.activeValue = undefined;
         justValue = undefined;
         focused = false;
     }
 </script>
 
-<svelte:window onclick={handleClickOutside} onkeydown={handleKeyDown} />
+<!-- Outside clicks close the list via the input's native blur -->
+<svelte:window onkeydown={handleKeyDown} />
 
 <div
     class="svelte-select {rest.class}"
@@ -693,6 +1065,16 @@
     class:error={hasError}
     style={containerStyles}
     onpointerup={handleClick}
+    onmousedown={(ev) => {
+        // Pressing a non-input surface (the chevron area, a chip, multi-mode
+        // whitespace) must not blur the input: the blur handler closes the
+        // list, and this press's own pointerup — bubbling to handleClick —
+        // would read that fresh closed state and toggle the list straight
+        // back open. The input keeps its default behavior so caret placement
+        // and text selection still work. (The list has its own guard and
+        // stops propagation before reaching this one.)
+        if (ev.target !== input) ev.preventDefault();
+    }}
     bind:this={container}
     use:floatingRef
     role="none">
@@ -702,9 +1084,16 @@
             bind:this={list}
             class="svelte-select-list"
             class:prefloat
-            style={listStyle}
+            style={listStyles}
             onscroll={hoverManager.handleListScroll}
             onscrollend={hoverManager.handleListScrollEnd}
+            onmousemove={() => {
+                // Real pointer movement over the open list is commit-intent for
+                // Tab (see handleTabKey). mousemove — not mouseover — because
+                // browsers synthesize mouseover when the list renders under a
+                // stationary cursor, which is zero user action.
+                selectState.userNavigatedSinceOpen = true;
+            }}
             onpointerup={(ev) => {
                 if (ev.pointerType === 'mouse') ev.preventDefault();
                 ev.stopPropagation();
@@ -714,14 +1103,25 @@
                 ev.stopPropagation();
             }}
             role="listbox"
+            tabindex="-1"
+            aria-label={ariaLabel ?? listboxLabelText}
+            aria-labelledby={listboxLabelledby}
+            aria-busy={loading || undefined}
+            aria-multiselectable={multiple || undefined}
             id="listbox-{_id}">
             {#if listPrependSnippet}
                 {@render listPrependSnippet()}
             {/if}
             {#if listSnippet}
-                {@render listSnippet(filteredItems)}
+                {@render listSnippet(filteredItems as SelectRow<Item>[])}
             {:else if filteredItems?.length > 0}
-                {#each filteredItems as item, i}
+                {#snippet optionEntry(item: SelectItem, i: number)}
+                    <!-- Non-selectable group headers are aria-hidden rather than
+                         role="presentation": a listbox may only own option/group children,
+                         and groups are transparent for that check, so a presentational row
+                         inside one is an invalid listbox child (axe aria-required-children).
+                         The group's accessible name still resolves via aria-labelledby,
+                         which follows hidden targets. Selectable headers are real options. -->
                     <div
                         onmouseover={() => hoverManager.handleHover(i)}
                         onfocus={() => hoverManager.handleHover(i)}
@@ -735,34 +1135,55 @@
                         }}
                         class="list-item"
                         tabindex="-1"
-                        role={item.groupHeader ? 'presentation' : 'option'}
+                        role={isPresentationalHeader(item) ? undefined : 'option'}
                         id="listbox-{_id}-item-{i}"
-                        aria-selected={item.groupHeader ? undefined : hoverManager.isItemActive(item, normalizedValue, itemId) || false}>
+                        aria-hidden={isPresentationalHeader(item) ? true : undefined}
+                        aria-selected={isPresentationalHeader(item) ? undefined : hoverManager.isItemActive(item)}
+                        aria-disabled={isPresentationalHeader(item) || isItemSelectableCheck(item) ? undefined : true}>
                         <div
                             class="item"
                             class:list-group-title={item.groupHeader}
-                            class:active={hoverManager.isItemActive(item, normalizedValue, itemId)}
+                            class:active={hoverManager.isItemActive(item)}
                             class:first={i === 0}
+                            class:last={i === filteredItems.length - 1}
                             class:hover={hoverItemIndex === i}
                             class:group-item={item.groupItem}
-                            class:not-selectable={item?.selectable === false}
-                            role={item.groupHeader ? 'group' : undefined}
-                            aria-label={item.groupHeader ? item[label] : undefined}>
+                            class:not-selectable={item?.selectable === false}>
                             {#if itemSnippet}
-                                {@render itemSnippet(item, i)}
+                                {@render itemSnippet(item as SelectRow<Item>, i)}
                             {:else}
                                 {item?.[label]}
                             {/if}
                         </div>
                     </div>
+                {/snippet}
+                {#each groupedRows as row}
+                    {#if row.type === 'group'}
+                        <!-- A real listbox group named by its header (presentational or
+                             selectable) via aria-labelledby, wrapping that group's options -->
+                        <div role="group" aria-labelledby="listbox-{_id}-item-{row.headerIndex}">
+                            {@render optionEntry(row.header, row.headerIndex)}
+                            {#each row.options as opt}
+                                {@render optionEntry(opt.item, opt.index)}
+                            {/each}
+                        </div>
+                    {:else}
+                        {@render optionEntry(row.item, row.index)}
+                    {/if}
                 {/each}
             {:else if !hideEmptyState}
                 {#if emptySnippet}
                     {@render emptySnippet()}
                 {:else if !loading}
-                    <div class="empty">No options</div>
+                    <!-- Decorative: this state is announced via the role="status" live
+                         region below, so hide the visual copy from AT to avoid stray
+                         non-option text inside the listbox. The visible copy comes from
+                         the same ariaEmpty/ariaLoading props as the announcement, so a
+                         localized consumer never shows one language and announces
+                         another. -->
+                    <div class="empty" aria-hidden="true">{ariaEmpty()}</div>
                 {:else}
-                    <div class="empty">Loading Data</div>
+                    <div class="empty" aria-hidden="true">{ariaLoading()}</div>
                 {/if}
             {/if}
             {#if listAppendSnippet}
@@ -771,13 +1192,17 @@
         </div>
     {/if}
 
-    <span aria-live="polite" aria-atomic="false" aria-relevant="additions" class="a11y-text">
-        {#if focused}
-            <span id="aria-selection">{ariaSelection}</span>
-            <span id="aria-context">
-                {ariaContext}
-            </span>
-        {/if}
+    <!-- Two dedicated polite live regions (role="status" implies aria-live="polite"
+         + aria-atomic="true"). Atomic re-reads the whole region on any content change,
+         which announces edits and clears reliably across screen readers — unlike the
+         old aria-atomic="false"/aria-relevant="additions text" combination. The spans
+         persist (only their text is gated on focus) so they exist before content
+         changes, as live regions require. -->
+    <span id="aria-selection-{_id}" role="status" class="a11y-text a11y-selection">
+        {focused ? ariaSelection : ''}
+    </span>
+    <span id="aria-context-{_id}" role="status" class="a11y-text a11y-context">
+        {focused ? ariaContext : ''}
     </span>
 
     <div class="prepend">
@@ -789,20 +1214,55 @@
     <div class="value-container">
         {#if hasValue}
             {#if multiple}
-                {#each (Array.isArray(value) ? value : []) as item, i}
+                {#each Array.isArray(value) ? (value as Item[]) : [] as item, i}
+                    <!-- In multiFullItemClearable mode the whole chip is the remove control, so it
+                         must be a focusable button with a keyboard (Enter/Space) path — otherwise
+                         removal is mouse-only. Otherwise it stays a non-semantic wrapper around the
+                         dedicated remove button below. -->
+                    <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+                    <!-- tabindex and role="button" are set together under the same guard, so the
+                         element is interactive exactly when it is focusable (the linter can't see this). -->
                     <div
                         class="multi-item"
-                        class:active={activeValue === i}
+                        class:active={selectState.activeValue === i}
                         class:disabled
                         onclick={(ev) => {
                             ev.preventDefault();
-                            return multiFullItemClearable ? valueManager.handleMultiItemClear(i) : {};
+                            // Gated like the keydown path below: a pointer must never
+                            // mutate a disabled control's value (see handleItemClick)
+                            if (multiFullItemClearable && !disabled) {
+                                void valueManager.handleMultiItemClear(i);
+                                // Like the dedicated remove button below: focus returns
+                                // to the input so the removal announcement is not lost —
+                                // the live regions are gated on `focused`, and a chip
+                                // press that kept focus on the chip would otherwise
+                                // remove the chip from the DOM and drop focus to <body>
+                                // with the removal never announced.
+                                handleFocus();
+                            }
                         }}
-                        onkeydown={(ev) => {
-                            ev.preventDefault();
-                            ev.stopPropagation();
-                        }}
-                        role="none">
+                        onpointerup={multiFullItemClearable && !disabled
+                            ? (ev) => {
+                                  // Same containment as the dedicated remove button below:
+                                  // removing a tag must not bubble to the container's list
+                                  // toggle and pop the dropdown as a side effect
+                                  ev.stopPropagation();
+                              }
+                            : undefined}
+                        onkeydown={multiFullItemClearable && !disabled
+                            ? (ev) => {
+                                  if (ev.key !== 'Enter' && ev.key !== ' ') return;
+                                  ev.preventDefault();
+                                  ev.stopPropagation();
+                                  valueManager.handleMultiItemClear(i);
+                                  handleFocus();
+                              }
+                            : undefined}
+                        role={multiFullItemClearable && !disabled ? 'button' : 'none'}
+                        tabindex={multiFullItemClearable && !disabled ? 0 : undefined}
+                        aria-label={multiFullItemClearable && !disabled
+                            ? ariaRemoveItemLabel(String(item[label]))
+                            : undefined}>
                         <span class="multi-item-text">
                             {#if selectionSnippet}
                                 {@render selectionSnippet(item, i)}
@@ -812,26 +1272,33 @@
                         </span>
 
                         {#if !disabled && !multiFullItemClearable && ClearIcon}
-                            <div
+                            <!-- A real button: keyboard-focusable, Enter/Space activate via click.
+                                 mousedown is prevented so a mouse removal never steals focus from
+                                 the input; pointerup must not bubble to the container's list toggle. -->
+                            <button
+                                type="button"
                                 class="multi-item-clear"
-                                onpointerup={(ev) => {
-                                    if (ev.pointerType === 'mouse') ev.preventDefault();
+                                aria-label={ariaRemoveItemLabel(String(item[label]))}
+                                onmousedown={(ev) => ev.preventDefault()}
+                                onpointerup={(ev) => ev.stopPropagation()}
+                                onclick={(ev) => {
                                     ev.stopPropagation();
                                     valueManager.handleMultiItemClear(i);
+                                    handleFocus();
                                 }}>
                                 {#if multiClearIconSnippet}
                                     {@render multiClearIconSnippet()}
                                 {:else}
                                     <ClearIcon />
                                 {/if}
-                            </div>
+                            </button>
                         {/if}
                     </div>
                 {/each}
             {:else}
-                <div class="selected-item" class:hide-selected-item={hideSelectedItem}>
+                <div id="selected-{_id}" class="selected-item" class:hide-selected-item={hideSelectedItem}>
                     {#if selectionSnippet}
-                        {@render selectionSnippet(value as SelectItem)}
+                        {@render selectionSnippet(value as Item)}
                     {:else}
                         {!Array.isArray(normalizedValue) ? normalizedValue?.[label] : ''}
                     {/if}
@@ -844,13 +1311,11 @@
             onblur={handleBlur}
             oninput={handleInput}
             onfocus={handleFocus}
-            readOnly={!searchable}
             {..._inputAttributes}
             bind:this={input}
             value={filterText}
             placeholder={placeholderText}
-            style={inputStyles}
-            {disabled} />
+            style={inputStyles} />
     </div>
 
     <div class="indicators">
@@ -865,7 +1330,16 @@
         {/if}
 
         {#if showClear}
-            <button type="button" class="icon clear-select" onclick={handleClear}>
+            <!-- Same guards as the tag-remove buttons: mousedown is prevented so
+                 clearing never steals focus from the input, and pointerup must not
+                 bubble to the container's list toggle (a clear would reopen the list). -->
+            <button
+                type="button"
+                class="icon clear-select"
+                aria-label={ariaClearSelectLabel}
+                onmousedown={(ev) => ev.preventDefault()}
+                onpointerup={(ev) => ev.stopPropagation()}
+                onclick={handleClear}>
                 {#if clearIconSnippet}
                     {@render clearIconSnippet()}
                 {:else}
@@ -885,92 +1359,34 @@
         {/if}
     </div>
     {#if inputHiddenSnippet}
-        {@render inputHiddenSnippet(value as SelectValue)}
+        {@render inputHiddenSnippet(value)}
     {:else if multiple && Array.isArray(value) && value.length > 0}
-        {#each value as item}
+        {#each value as Item[] as item}
             <input {name} type="hidden" value={useJustValue ? item[itemId] : JSON.stringify(item)} />
         {/each}
     {:else if !multiple}
         <input {name} type="hidden" value={value ? (useJustValue ? justValue : JSON.stringify(value)) : ''} />
     {/if}
 
-    {#if required && (!value || value.length === 0)}
+    {#if required && (!value || (Array.isArray(value) && value.length === 0))}
         {#if requiredSnippet}
-            {@render requiredSnippet(value as SelectValue)}
+            {@render requiredSnippet(value)}
         {:else}
-            <select class="required" required tabindex="-1" aria-hidden="true"></select>
+            <!-- Constraint validation focuses the first invalid control — this one.
+                 An aria-hidden element must never hold focus (and this one is
+                 invisible), so forward it to the real combobox input immediately. -->
+            <select class="required" required tabindex="-1" aria-hidden="true" onfocus={() => handleFocus()}></select>
         {/if}
     {/if}
 </div>
 
 <style>.svelte-select {
-    /* deprecating camelCase custom props in favour of kebab-case for v5 */
-    --borderRadius: var(--border-radius);
-    --clearSelectColor: var(--clear-select-color);
-    --clearSelectWidth: var(--clear-select-width);
-    --disabledBackground: var(--disabled-background);
-    --disabledBorderColor: var(--disabled-border-color);
-    --disabledColor: var(--disabled-color);
-    --disabledPlaceholderColor: var(--disabled-placeholder-color);
-    --disabledPlaceholderOpacity: var(--disabled-placeholder-opacity);
-    --errorBackground: var(--error-background);
-    --errorBorder: var(--error-border);
-    --groupItemPaddingLeft: var(--group-item-padding-left);
-    --groupTitleColor: var(--group-title-color);
-    --groupTitleFontSize: var(--group-title-font-size);
-    --groupTitleFontWeight: var(--group-title-font-weight);
-    --groupTitlePadding: var(--group-title-padding);
-    --groupTitleTextTransform: var(--group-title-text-transform);
-    --groupTitleBorderColor: var(--group-title-border-color);
-    --groupTitleBorderWidth: var(--group-title-border-width);
-    --groupTitleBorderStyle: var(--group-title-border-style);
-    --indicatorColor: var(--chevron-color);
-    --indicatorHeight: var(--chevron-height);
-    --indicatorWidth: var(--chevron-width);
-    --inputColor: var(--input-color);
-    --inputLeft: var(--input-left);
-    --inputLetterSpacing: var(--input-letter-spacing);
-    --inputMargin: var(--input-margin);
-    --inputPadding: var(--input-padding);
-    --itemActiveBackground: var(--item-active-background);
-    --itemColor: var(--item-color);
-    --itemFirstBorderRadius: var(--item-first-border-radius);
-    --itemHoverBG: var(--item-hover-bg);
-    --itemHoverColor: var(--item-hover-color);
-    --itemIsActiveBG: var(--item-is-active-bg);
-    --itemIsActiveColor: var(--item-is-active-color);
-    --itemIsNotSelectableColor: var(--item-is-not-selectable-color);
-    --itemPadding: var(--item-padding);
-    --listBackground: var(--list-background);
-    --listBorder: var(--list-border);
-    --listBorderRadius: var(--list-border-radius);
-    --listEmptyColor: var(--list-empty-color);
-    --listEmptyPadding: var(--list-empty-padding);
-    --listEmptyTextAlign: var(--list-empty-text-align);
-    --listMaxHeight: var(--list-max-height);
-    --listPosition: var(--list-position);
-    --listShadow: var(--list-shadow);
-    --listZIndex: var(--list-z-index);
-    --multiItemBG: var(--multi-item-bg);
-    --multiItemBorderRadius: var(--multi-item-border-radius);
-    --multiItemDisabledHoverBg: var(--multi-item-disabled-hover-bg);
-    --multiItemDisabledHoverColor: var(--multi-item-disabled-hover-color);
-    --multiItemHeight: var(--multi-item-height);
-    --multiItemMargin: var(--multi-item-margin);
-    --multiItemPadding: var(--multi-item-padding);
-    --multiSelectInputMargin: var(--multi-select-input-margin);
-    --multiSelectInputPadding: var(--multi-select-input-padding);
-    --multiSelectPadding: var(--multi-select-padding);
-    --placeholderColor: var(--placeholder-color);
-    --placeholderOpacity: var(--placeholder-opacity);
-    --selectedItemPadding: var(--selected-item-padding);
-    --spinnerColor: var(--spinner-color);
-    --spinnerHeight: var(--spinner-height);
-    --spinnerWidth: var(--spinner-width);
-
     --internal-padding: 0 0 0 16px;
 
-    border: var(--border, 1px solid #d8dbdf);
+    /* #858a93 is 3.47:1 on the default #fff background. The old #d8dbdf was 1.39:1 —
+       the border is what identifies the control's boundary, so it needs 3:1
+       (WCAG 1.4.11 Non-text Contrast). Override --border to restyle. */
+    border: var(--border, 1px solid #858a93);
     border-radius: var(--border-radius, 6px);
     min-height: var(--height, 42px);
     position: relative;
@@ -989,7 +1405,9 @@
 }
 
 .svelte-select:hover {
-    border: var(--border-hover, 1px solid #b2b8bf);
+    /* Darker than --border so hover stays a visible change, and 4.91:1 on #fff
+       (the old #b2b8bf was 2.00:1) */
+    border: var(--border-hover, 1px solid #67727d);
 }
 
 .value-container {
@@ -1041,7 +1459,7 @@ input {
 }
 
 input::placeholder {
-    color: var(--placeholder-color, #78848f);
+    color: var(--placeholder-color, #67727d);
     opacity: var(--placeholder-opacity, 1);
 }
 
@@ -1052,6 +1470,10 @@ input:focus {
 .svelte-select.focused {
     border: var(--border-focused, 1px solid #006fe8);
     border-radius: var(--border-radius-focused, var(--border-radius, 6px));
+    /* A focus ring in addition to the border colour change: the input's own
+       outline is suppressed, so relying on the 1px border alone was a
+       colour-only cue (WCAG 2.4.7/2.4.11) that vanished if --border was overridden. */
+    box-shadow: var(--focused-box-shadow, 0 0 0 2px rgba(0, 111, 232, 0.4));
 }
 
 .disabled {
@@ -1108,7 +1530,7 @@ input:focus {
     flex-shrink: 0;
 }
 
-.clear-select:focus {
+.clear-select:focus-visible {
     outline: var(--clear-select-focus-outline, 1px solid #006fe8);
 }
 
@@ -1188,12 +1610,33 @@ input:focus {
 }
 
 .multi-item-clear {
+    all: unset;
     display: flex;
     align-items: center;
     justify-content: center;
+    cursor: pointer;
+    /* The button stretches to the chip's height (25px); without a width floor
+       it shrinks to the 20px icon, under the 24px activation-target minimum
+       (WCAG 2.2 2.5.8) */
+    min-width: var(--multi-item-clear-min-width, 24px);
     --clear-icon-color: var(--multi-item-clear-icon-color, #000);
 }
 
+.multi-item-clear:focus-visible {
+    outline: var(--multi-item-clear-focus-outline, 1px solid #006fe8);
+}
+
+/* With multiFullItemClearable the whole chip is a real tab stop (role="button",
+   tabindex="0"). .multi-item sets `outline` unconditionally, and an author outline
+   beats the UA's :focus-visible ring by cascade origin, so without this rule a
+   keyboard-focused chip looked identical to an unfocused one (WCAG 2.4.7 Focus
+   Visible). Distinct from .multi-item.active below, which is the arrow-key tag
+   cursor, not DOM focus. */
+.multi-item:focus-visible {
+    outline: var(--multi-item-focus-outline, 2px solid #006fe8);
+    outline-offset: -1px;
+}
+
 .multi-item.active {
     outline: var(--multi-item-active-outline, 1px solid #006fe8);
 }
@@ -1234,7 +1677,7 @@ input:focus {
 .empty {
     text-align: var(--list-empty-text-align, center);
     padding: var(--list-empty-padding, 20px 0);
-    color: var(--list-empty-color, #78848f);
+    color: var(--list-empty-color, #67727d);
 }
 
 .item {
@@ -1260,7 +1703,7 @@ input:focus {
 }
 
 .item.active {
-    background: var(--item-is-active-bg, #007aff);
+    background: var(--item-is-active-bg, #006fe8);
     color: var(--item-is-active-color, #fff);
 }
 
@@ -1268,9 +1711,28 @@ input:focus {
     border-radius: var(--item-first-border-radius, 4px 4px 0 0);
 }
 
+/* Mirror of .item.first: without it the last item's hover/selection background
+   (and the keyboard-cursor outline) square off against the list's rounded
+   bottom corners */
+.item.last {
+    border-radius: var(--item-last-border-radius, 0 0 4px 4px);
+}
+
+/* A single-option list is both first and last: round all corners (the two
+   shorthand variables above cannot compose, so this matches their defaults) */
+.item.first.last {
+    border-radius: 4px;
+}
+
 .item.hover:not(.active) {
     background: var(--item-hover-bg, #e7f2ff);
     color: var(--item-hover-color, inherit);
+    /* The background alone is ~1.13:1 against the default #fff list — a
+       colour-only cue for the keyboard cursor (WCAG 1.4.11 Non-text Contrast).
+       #006fe8 is 4.5:1 on #fff and ~4.1:1 on the hover background; set
+       --item-hover-outline to `none` to opt out. */
+    outline: var(--item-hover-outline, 2px solid #006fe8);
+    outline-offset: -2px;
 }
 
 .item.not-selectable,
@@ -1279,6 +1741,22 @@ input:focus {
 .item.not-selectable:active {
     color: var(--item-is-not-selectable-color, #999);
     background: transparent;
+    /* Not actionable, so it must not show the keyboard-cursor outline either */
+    outline: none;
+}
+
+/* Group titles are informative text, not disabled controls, so WCAG 1.4.3's
+   inactive-component exemption does not apply to them: the not-selectable
+   dimming above (#999 = 2.84:1) must not reach a header. Keep them at the
+   group-title color (default #000 = 21:1 on white). The hover variant must
+   win over `.item.hover.item.not-selectable` too: the first frame parks the
+   keyboard cursor on index 0 before the keep-hover effect moves it off a
+   header, and without it that frame paints #999 which then *animates* back
+   through `transition: all` — mid-transition greys fail contrast when
+   sampled (the CI-only axe flake). */
+.item.list-group-title.not-selectable,
+.item.hover.item.list-group-title.not-selectable {
+    color: var(--group-title-color, #000000);
 }
 
 .required {
@@ -1290,4 +1768,44 @@ input:focus {
     bottom: 0;
     right: 0;
 }
+
+@media (prefers-reduced-motion: reduce) {
+    .item {
+        transition: none;
+    }
+}
+
+@media (forced-colors: active) {
+    /* box-shadow is dropped in forced-colors mode, so the focus ring above is
+       invisible there — restore a real outline using a system colour. */
+    .svelte-select.focused {
+        outline: 2px solid Highlight;
+        outline-offset: 1px;
+    }
+
+    /* Custom background colours are also flattened, so distinguish the selected
+       option (filled) from the option under the keyboard cursor (outlined). */
+    .item.active {
+        background: Highlight;
+        color: HighlightText;
+    }
+
+    .item.hover:not(.active) {
+        outline: 2px solid Highlight;
+        outline-offset: -2px;
+    }
+
+    /* The chip's focus ring is an author colour, which is flattened here */
+    .multi-item:focus-visible {
+        outline: 2px solid Highlight;
+    }
+
+    /* Every chip carries a 1px outline and the arrow-key tag cursor differs
+       only by outline colour — flattened to the same system colour here, the
+       Backspace target vanished. Width + style survive the forced palette. */
+    .multi-item.active {
+        outline: 2px dashed Highlight;
+        outline-offset: -2px;
+    }
+}
 </style>