@tangible/ui 0.0.6 → 0.0.8

package/components/Select/Select.js

@@ -6,15 +6,16 @@ import { cx } from '../../utils/cx.js';
 import { toKey } from '../../utils/value-key.js';
 import { getPortalRootFor } from '../../utils/portal.js';
 import { Icon } from '../Icon/index.js';
-import { SelectActionsContext, SelectStateContext, SelectContentContext, useSelectContext, useSelectContentContext, } from './SelectContext.js';
+import { SelectContext, SelectContentContext, useSelectContext, useSelectContentContext, } from './SelectContext.js';
 import { toPlacement, } from './types.js';
 // =============================================================================
 // Select Root
 // =============================================================================
 function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, onValueChange, open: controlledOpen, defaultOpen, onOpenChange, disabled = false, placeholder = '', size = 'md', side = 'bottom', align = 'start', sideOffset = 4, clearable = false, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, children, }) {
-    // Controlled/uncontrolled value
+    // Controlled/uncontrolled value — lock decision at mount time to prevent
+    // switching modes when controlled value is cleared to undefined
     const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
-    const isValueControlled = controlledValue !== undefined;
+    const isValueControlled = useRef(controlledValue !== undefined).current;
     const value = isValueControlled ? controlledValue : uncontrolledValue;
     // Store display text separately so it persists when dropdown is closed
     const [displayText, setDisplayText] = useState(undefined);
@@ -28,20 +29,16 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
         }
         onValueChange?.(newValue);
     }, [isValueControlled, onValueChange]);
-    // Sync displayText when value changes (handles controlled updates and clears)
-    const prevValue = useRef(value);
+    // Sync displayText when controlled value changes externally (parent prop update)
     useEffect(() => {
-        if (prevValue.current !== value) {
-            if (value === undefined) {
-                setDisplayText(undefined);
-            }
-            else {
-                const option = optionsRef.current.get(toKey(value));
-                if (option) {
-                    setDisplayText(option.textValue);
-                }
+        if (value === undefined) {
+            setDisplayText(undefined);
+        }
+        else {
+            const option = optionsRef.current.get(toKey(value));
+            if (option) {
+                setDisplayText(option.textValue);
             }
-            prevValue.current = value;
         }
     }, [value]);
     // Initialize displayText when options register (handles defaultValue case)
@@ -58,9 +55,15 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
     const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen ?? false);
     const isOpenControlled = controlledOpen !== undefined;
     const open = isOpenControlled ? controlledOpen : uncontrolledOpen;
+    // Guard flag: when Backspace/Delete clears a closed Select, Floating UI's
+    // composed handlers (useTypeahead/useListNavigation) also fire and call
+    // setOpen(true). This ref rejects that open request within the same microtask.
+    const justClearedRef = useRef(false);
     const setOpen = useCallback((nextOpen) => {
         if (disabled)
             return;
+        if (nextOpen && justClearedRef.current)
+            return;
         if (!isOpenControlled) {
             setUncontrolledOpen(nextOpen);
         }
@@ -100,6 +103,15 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
         return options;
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [registryVersion]);
+    // O(1) index lookup map — rebuilt when orderedOptions changes
+    const optionIndexMap = useMemo(() => {
+        const map = new Map();
+        orderedOptions.forEach((opt, i) => map.set(toKey(opt.value), i));
+        return map;
+    }, [orderedOptions]);
+    // Ref for stable handleSelect — avoids recreating on registry changes
+    const orderedOptionsRef = useRef(orderedOptions);
+    orderedOptionsRef.current = orderedOptions;
     // Floating UI setup - in Root so Trigger and Content can share
     const { refs, floatingStyles, context } = useFloating({
         placement,
@@ -121,16 +133,16 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
         ],
         whileElementsMounted: autoUpdate,
     });
-    // Handle selection
+    // Handle selection — reads orderedOptionsRef to avoid recreating on registry changes
     const handleSelect = useCallback((index) => {
         if (index === null)
             return;
-        const option = orderedOptions[index];
+        const option = orderedOptionsRef.current[index];
         if (option && !option.disabled) {
             setValue(option.value, option.textValue);
             setOpen(false);
         }
-    }, [orderedOptions, setValue, setOpen]);
+    }, [setValue, setOpen]);
     // Floating UI interactions
     // Use 'click' (not 'mousedown') so button has focus when dropdown opens
     // This ensures keyboard navigation works immediately
@@ -150,7 +162,7 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
         loop: true,
         virtual: true,
         focusItemOnOpen: true,
-        selectedIndex: orderedOptions.findIndex((opt) => value !== undefined && toKey(opt.value) === toKey(value)),
+        selectedIndex: value !== undefined ? (optionIndexMap.get(toKey(value)) ?? -1) : -1,
         disabledIndices,
     });
     const typeahead = useTypeahead(context, {
@@ -179,10 +191,6 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
         optionsRef.current.delete(toKey(optionValue));
         setRegistryVersion((v) => v + 1);
     }, []);
-    // Get selected option's text value
-    const getSelectedTextValue = useCallback(() => {
-        return displayText;
-    }, [displayText]);
     // Highlighted value for keyboard navigation
     const highlightedValue = activeIndex !== null ? orderedOptions[activeIndex]?.value ?? null : null;
     // Reset active index when closing
@@ -192,7 +200,7 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
         }
         else {
             // When opening, set active index to selected value or first enabled
-            const selectedIndex = orderedOptions.findIndex((opt) => value !== undefined && toKey(opt.value) === toKey(value));
+            const selectedIndex = value !== undefined ? (optionIndexMap.get(toKey(value)) ?? -1) : -1;
             if (selectedIndex >= 0 && !orderedOptions[selectedIndex]?.disabled) {
                 setActiveIndex(selectedIndex);
             }
@@ -201,7 +209,7 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
                 setActiveIndex(firstEnabled >= 0 ? firstEnabled : null);
             }
         }
-    }, [open, orderedOptions, value]);
+    }, [open, orderedOptions, optionIndexMap, value]);
     // Scroll active option into view
     useEffect(() => {
         if (open && activeIndex !== null && listRef.current[activeIndex]) {
@@ -209,98 +217,82 @@ function SelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, o
         }
     }, [open, activeIndex]);
     // ==========================================================================
-    // Split Context Values
-    // ==========================================================================
-    // Actions: stable config, IDs, refs, callbacks — rarely changes
-    // State: open, value, activeIndex, etc. — changes on interaction
+    // Context Value
     // ==========================================================================
-    const actionsValue = useMemo(() => ({
-        // Config (from props, stable for component lifetime)
+    const contextValue = useMemo(() => ({
+        // Config
         disabled,
         placeholder,
         clearable,
         size,
-        // ARIA IDs (stable)
+        // ARIA IDs
         triggerId,
         listboxId,
         ariaLabel,
         ariaLabelledBy,
         ariaDescribedBy,
-        // Stable callbacks
+        // Callbacks
         setOpen,
         setValue,
         registerOption,
         unregisterOption,
         handleSelect,
-        // Refs (stable objects)
+        // Refs
         refs,
         listRef,
-        // Floating UI interaction props (stable functions from useInteractions)
+        justClearedRef,
+        // Floating UI interaction props
         getReferenceProps,
         getFloatingProps,
         getItemProps,
+        // State
+        open,
+        value,
+        displayText,
+        activeIndex,
+        highlightedValue,
+        orderedOptions,
+        optionIndexMap,
+        floatingStyles,
     }), [
-        // Config props - only change if parent rerenders with new props
         disabled,
         placeholder,
         clearable,
         size,
-        // IDs are stable (from useId)
         triggerId,
         listboxId,
         ariaLabel,
         ariaLabelledBy,
         ariaDescribedBy,
-        // Callbacks are stable (useCallback with stable deps)
         setOpen,
         setValue,
         registerOption,
         unregisterOption,
         handleSelect,
-        // Refs are stable objects
         refs,
         listRef,
-        // Interaction props from useInteractions (stable)
         getReferenceProps,
         getFloatingProps,
         getItemProps,
-    ]);
-    const stateValue = useMemo(() => ({
-        // Open state
-        open,
-        // Selection state
-        value,
-        // Selection helper
-        getSelectedTextValue,
-        // Navigation state
-        activeIndex,
-        highlightedValue,
-        // Derived (changes when registry changes)
-        orderedOptions,
-        // Floating UI (changes on open/position)
-        floatingStyles,
-        floatingContext: context,
-    }), [
         open,
         value,
-        getSelectedTextValue,
+        displayText,
         activeIndex,
         highlightedValue,
         orderedOptions,
+        optionIndexMap,
         floatingStyles,
-        context,
     ]);
-    return (_jsx(SelectActionsContext.Provider, { value: actionsValue, children: _jsx(SelectStateContext.Provider, { value: stateValue, children: children }) }));
+    return (_jsx(SelectContext.Provider, { value: contextValue, children: children }));
 }
 SelectRoot.displayName = 'Select';
 // =============================================================================
 // Select.Trigger
 // =============================================================================
 function SelectTriggerComponent({ asChild = false, className, children, }) {
-    const { open, setOpen, disabled, placeholder, clearable, size, triggerId, listboxId, ariaLabel, ariaLabelledBy, ariaDescribedBy, getSelectedTextValue, setValue, refs, getReferenceProps, activeIndex, handleSelect, } = useSelectContext();
+    const { open, setOpen, disabled, placeholder, clearable, size, triggerId, listboxId, ariaLabel, ariaLabelledBy, ariaDescribedBy, displayText, setValue, refs, getReferenceProps, activeIndex, handleSelect, justClearedRef, } = useSelectContext();
     const sizeClass = size !== 'md' ? `is-size-${size}` : undefined;
-    const displayValue = getSelectedTextValue();
-    const hasValue = displayValue !== undefined;
+    const hasValue = displayText !== undefined;
     // Ensure trigger has focus when dropdown opens (Safari doesn't focus buttons on click)
     useEffect(() => {
         if (open && refs.reference.current) {
@@ -315,9 +307,11 @@ function SelectTriggerComponent({ asChild = false, className, children, }) {
         }
         if (!open && clearable && hasValue && (e.key === 'Delete' || e.key === 'Backspace')) {
             e.preventDefault();
+            justClearedRef.current = true;
+            queueMicrotask(() => { justClearedRef.current = false; });
             setValue(undefined);
         }
-    }, [open, activeIndex, handleSelect, clearable, hasValue, setValue]);
+    }, [open, activeIndex, handleSelect, clearable, hasValue, setValue, justClearedRef]);
     // Close dropdown when focus leaves trigger
     // Uses blur guard pattern: only close if focus moved outside controlled elements
     const handleBlur = useCallback((e) => {
@@ -344,7 +338,9 @@ function SelectTriggerComponent({ asChild = false, className, children, }) {
         if (disabled)
             return;
         setValue(undefined);
-    }, [disabled, setValue]);
+        // Return focus to trigger after clearing
+        refs.reference.current?.focus();
+    }, [disabled, setValue, refs.reference]);
     // Get Floating UI's reference props - pass our handlers so they get composed
     const floatingProps = getReferenceProps({
         'aria-activedescendant': activeIndex !== null ? `${listboxId}-option-${activeIndex}` : undefined,
@@ -356,9 +352,8 @@ function SelectTriggerComponent({ asChild = false, className, children, }) {
         'aria-label': ariaLabel,
         'aria-labelledby': ariaLabelledBy,
         'aria-describedby': ariaDescribedBy,
-        'aria-disabled': disabled || undefined,
+        'aria-keyshortcuts': clearable && hasValue ? 'Delete' : undefined,
         'data-state': open ? 'open' : 'closed',
-        'data-disabled': disabled || undefined,
         ...floatingProps,
     };
     if (asChild && isValidElement(children)) {
@@ -390,6 +385,7 @@ function SelectTriggerComponent({ asChild = false, className, children, }) {
             'aria-controls': floatingProps['aria-controls'],
             'aria-activedescendant': floatingProps['aria-activedescendant'],
             'aria-describedby': ariaDescribedBy,
+            // asChild: use aria-disabled + data-disabled since element may not support native disabled
             'aria-disabled': disabled || undefined,
             'data-state': open ? 'open' : 'closed',
             'data-disabled': disabled || undefined,
@@ -402,14 +398,18 @@ function SelectTriggerComponent({ asChild = false, className, children, }) {
             onPointerDown: composeHandler(triggerProps.onPointerDown, childProps.onPointerDown),
         });
     }
-    return (_jsxs("button", { ref: refs.setReference, type: "button", className: cx('tui-select__trigger', sizeClass, className), disabled: disabled, ...triggerProps, children: [_jsx("span", { className: "tui-select__value", children: displayValue || _jsx("span", { className: "tui-select__placeholder", children: placeholder }) }), clearable && hasValue && !disabled && (_jsx("span", { className: "tui-select__clear", onPointerDown: handleClear, "aria-hidden": "true", children: _jsx(Icon, { name: "system/close", size: "sm" }) })), _jsx(Icon, { name: "system/chevron-down", size: "sm", className: "tui-select__icon", "aria-hidden": "true" })] }));
+    const showClear = clearable && hasValue && !disabled;
+    // Wrap in a relative container so the clear button can be a sibling of the
+    // trigger <button> — nesting <button> inside <button> is invalid HTML and
+    // causes browsers to eject the inner button via the adoption agency algorithm.
+    return (_jsxs("div", { className: cx('tui-select__trigger-wrap', showClear && 'has-clear'), children: [_jsxs("button", { ref: refs.setReference, type: "button", className: cx('tui-select__trigger', sizeClass, className), disabled: disabled, ...triggerProps, children: [_jsx("span", { className: "tui-select__value", children: displayText ?? _jsx("span", { className: "tui-select__placeholder", children: placeholder }) }), _jsx(Icon, { name: "system/chevron-down", size: "sm", className: "tui-select__icon", "aria-hidden": "true" })] }), showClear && (_jsx("button", { type: "button", className: "tui-select__clear", onClick: handleClear, "aria-label": "Clear selection", tabIndex: -1, children: _jsx(Icon, { name: "system/close", size: "sm" }) }))] }));
 }
 SelectTriggerComponent.displayName = 'Select.Trigger';
 // =============================================================================
 // Select.Content
 // =============================================================================
 function SelectContentComponent({ className, children, }) {
-    const { open, listboxId, triggerId, refs, floatingStyles, getFloatingProps, listRef, activeIndex, handleSelect, orderedOptions, } = useSelectContext();
+    const { open, listboxId, triggerId, refs, floatingStyles, getFloatingProps, listRef, activeIndex, handleSelect, orderedOptions, optionIndexMap, } = useSelectContext();
     const portalRoot = getPortalRootFor(refs.reference.current);
     // Memoized context for options
     const contentContext = useMemo(() => ({
@@ -417,8 +417,9 @@ function SelectContentComponent({ className, children, }) {
         activeIndex,
         handleSelect,
         orderedOptions,
-    }), [listRef, activeIndex, handleSelect, orderedOptions]);
-    return (_jsxs(_Fragment, { children: [!open && (_jsx("div", { style: { display: 'none' }, "aria-hidden": "true", children: _jsx(SelectContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": triggerId, className: cx('tui-select__content', className), style: {
+        optionIndexMap,
+    }), [listRef, activeIndex, handleSelect, orderedOptions, optionIndexMap]);
+    return (_jsxs(_Fragment, { children: [!open && (_jsx("div", { id: listboxId, role: "listbox", style: { display: 'none' }, "aria-hidden": "true", children: _jsx(SelectContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": triggerId, className: cx('tui-select__content', className), style: {
                         ...floatingStyles,
                         minWidth: refs.reference.current?.offsetWidth,
                         pointerEvents: 'auto',
@@ -430,13 +431,15 @@ SelectContentComponent.displayName = 'Select.Content';
 // =============================================================================
 function SelectOptionComponent({ value: optionValue, disabled = false, textValue: explicitTextValue, className, children, }) {
     const { value: selectedValue, setValue, setOpen, listboxId, registerOption, unregisterOption, highlightedValue, getItemProps, } = useSelectContext();
-    const { listRef, orderedOptions } = useSelectContentContext();
+    const { listRef, optionIndexMap } = useSelectContentContext();
     const ref = useRef(null);
     // Derive textValue from children if not explicitly provided
     const textValue = explicitTextValue ?? (typeof children === 'string' ? children : '');
-    // Warn in dev if textValue couldn't be derived
+    // Warn in dev if textValue couldn't be derived (once per mount)
+    const warnedTextValueRef = useRef(false);
     useEffect(() => {
-        if (isDev() && !textValue) {
+        if (isDev() && !textValue && !warnedTextValueRef.current) {
+            warnedTextValueRef.current = true;
             console.warn(`Select.Option with value="${optionValue}" has no textValue. Provide textValue prop when children is not a string.`);
         }
     }, [textValue, optionValue]);
@@ -445,8 +448,8 @@ function SelectOptionComponent({ value: optionValue, disabled = false, textValue
         registerOption({ value: optionValue, ref, disabled, textValue });
         return () => unregisterOption(optionValue);
     }, [optionValue, disabled, textValue, registerOption, unregisterOption]);
-    // Find this option's index in ordered list
-    const index = orderedOptions.findIndex((opt) => toKey(opt.value) === toKey(optionValue));
+    // O(1) index lookup via Map
+    const index = optionIndexMap.get(toKey(optionValue)) ?? -1;
     // Assign ref to listRef for navigation
     useEffect(() => {
         if (index >= 0) {
@@ -471,7 +474,27 @@ SelectOptionComponent.displayName = 'Select.Option';
 // =============================================================================
 function SelectGroupComponent({ className, children }) {
     const groupId = useId();
-    return (_jsx("div", { role: "group", "aria-labelledby": `${groupId}-label`, className: cx('tui-select__group', className), children: _jsx(SelectGroupContext.Provider, { value: { groupId }, children: children }) }));
+    const groupRef = useRef(null);
+    // Guard aria-labelledby: only set when a Label child actually exists in the DOM.
+    // Without this, aria-labelledby points to a non-existent ID, which per AccName 1.2
+    // step 2B overrides all other name sources and resolves to empty string.
+    // useLayoutEffect runs before paint, so AT never sees the dangling reference.
+    // groupId is stable (from useId) and label presence is stable after mount —
+    // only run once to avoid a DOM query on every render.
+    useLayoutEffect(() => {
+        const groupEl = groupRef.current;
+        if (!groupEl)
+            return;
+        const labelId = `${groupId}-label`;
+        const labelEl = groupEl.querySelector(`#${CSS.escape(labelId)}`);
+        if (labelEl) {
+            groupEl.setAttribute('aria-labelledby', labelId);
+        }
+        else {
+            groupEl.removeAttribute('aria-labelledby');
+        }
+    }, [groupId]);
+    return (_jsx("div", { ref: groupRef, role: "group", className: cx('tui-select__group', className), children: _jsx(SelectGroupContext.Provider, { value: { groupId }, children: children }) }));
 }
 SelectGroupComponent.displayName = 'Select.Group';
 const SelectGroupContext = React.createContext(null);
@@ -480,6 +503,15 @@ const SelectGroupContext = React.createContext(null);
 // =============================================================================
 function SelectLabelComponent({ className, children }) {
     const groupContext = React.useContext(SelectGroupContext);
+    // DEV: warn if Label is used outside a Group — it has no semantic effect there
+    const warnedRef = useRef(false);
+    useEffect(() => {
+        if (isDev() && !groupContext && !warnedRef.current) {
+            warnedRef.current = true;
+            console.warn('Select.Label rendered outside Select.Group has no effect. ' +
+                'Wrap in Select.Group so aria-labelledby is wired correctly.');
+        }
+    }, [groupContext]);
     // No aria-hidden — aria-labelledby on Group references this element,
     // so screen readers need access to read the label text.
     return (_jsx("div", { id: groupContext ? `${groupContext.groupId}-label` : undefined, className: cx('tui-select__label', className), children: children }));

package/components/Select/SelectContext.d.ts

@@ -1,20 +1,8 @@
-import type { SelectActionsContextValue, SelectStateContextValue, SelectContentContextValue } from './types';
-export declare const SelectActionsContext: import("react").Context<SelectActionsContextValue | null>;
-export declare const SelectStateContext: import("react").Context<SelectStateContextValue | null>;
+import type { SelectContextValue, SelectContentContextValue } from './types';
+export declare const SelectContext: import("react").Context<SelectContextValue | null>;
 /**
- * Access stable config, IDs, refs, and callbacks.
- * Safe to use without causing rerenders on navigation changes.
+ * Access Select context: config, IDs, refs, callbacks, and reactive state.
  */
-export declare function useSelectActions(): SelectActionsContextValue;
-/**
- * Access reactive state: open, value, activeIndex, orderedOptions.
- * Subscribing causes rerender when these values change.
- */
-export declare function useSelectState(): SelectStateContextValue;
-/**
- * Combined hook for components that need both.
- * Convenience for Trigger/Content that need everything.
- */
-export declare function useSelectContext(): SelectActionsContextValue & SelectStateContextValue;
+export declare function useSelectContext(): SelectContextValue;
 export declare const SelectContentContext: import("react").Context<SelectContentContextValue | null>;
 export declare function useSelectContentContext(): SelectContentContextValue;

package/components/Select/SelectContext.js

@@ -1,48 +1,18 @@
 import { createContext, useContext } from 'react';
 // =============================================================================
-// Split Contexts for Performance
+// Select Context
 // =============================================================================
-// Actions context: stable config, IDs, refs, callbacks — rarely changes
-// State context: open, value, activeIndex, etc. — changes on interaction
-//
-// Components subscribe to what they need:
-// - Options: actions (register) + minimal state (isSelected check)
-// - Trigger: both (needs state for display, actions for handlers)
-// - Content: both (needs floating styles, refs)
-// =============================================================================
-export const SelectActionsContext = createContext(null);
-export const SelectStateContext = createContext(null);
+export const SelectContext = createContext(null);
 /**
- * Access stable config, IDs, refs, and callbacks.
- * Safe to use without causing rerenders on navigation changes.
+ * Access Select context: config, IDs, refs, callbacks, and reactive state.
  */
-export function useSelectActions() {
-    const context = useContext(SelectActionsContext);
-    if (!context) {
-        throw new Error('Select components must be used within a Select');
-    }
-    return context;
-}
-/**
- * Access reactive state: open, value, activeIndex, orderedOptions.
- * Subscribing causes rerender when these values change.
- */
-export function useSelectState() {
-    const context = useContext(SelectStateContext);
+export function useSelectContext() {
+    const context = useContext(SelectContext);
     if (!context) {
         throw new Error('Select components must be used within a Select');
     }
     return context;
 }
-/**
- * Combined hook for components that need both.
- * Convenience for Trigger/Content that need everything.
- */
-export function useSelectContext() {
-    const actions = useSelectActions();
-    const state = useSelectState();
-    return { ...actions, ...state };
-}
 // =============================================================================
 // Content Context (for Option registration)
 // =============================================================================

package/components/Select/types.d.ts

@@ -1,4 +1,4 @@
-import type { Placement, FloatingContext, ReferenceType } from '@floating-ui/react';
+import type { Placement, ReferenceType } from '@floating-ui/react';
 import type { RefObject, CSSProperties, MutableRefObject } from 'react';
 import type { SizeStandard } from '../../types/sizes';
 import type { OptionValue } from '../../utils/value-key';
@@ -92,8 +92,14 @@ export type SelectProps = {
 };
 export type SelectTriggerProps = {
     /**
-     * When true, merges props onto the child element instead of wrapping.
-     * Child must be a single React element that accepts ref and event handlers.
+     * When true, merges props onto the child element instead of rendering
+     * the default trigger button. Child must be a single React element that
+     * accepts ref, ARIA attributes, and event handlers (onClick, onKeyDown,
+     * onBlur, onMouseDown, onPointerDown).
+     *
+     * Note: `aria-label` and `aria-labelledby` from Select Root are spread
+     * onto the child but may be overridden by the child's own props.
+     * Ensure the child does not silently replace these if the Root provides them.
      * @default false
      */
     asChild?: boolean;
@@ -156,10 +162,10 @@ export type RegisteredOption = {
     textValue: string;
 };
 /**
- * Stable context: config, IDs, refs, and stable callbacks.
- * Rarely changes — safe to subscribe without rerender concerns.
+ * Select context: config, IDs, refs, callbacks, and reactive state.
+ * All sub-components subscribe to one context.
  */
-export type SelectActionsContextValue = {
+export type SelectContextValue = {
     disabled: boolean;
     placeholder: string;
     clearable: boolean;
@@ -181,34 +187,28 @@ export type SelectActionsContextValue = {
         setFloating: (node: HTMLElement | null) => void;
     };
     listRef: MutableRefObject<(HTMLElement | null)[]>;
+    /** Guard flag — prevents Floating UI from opening dropdown during a clear */
+    justClearedRef: MutableRefObject<boolean>;
     getReferenceProps: (userProps?: React.HTMLProps<Element>) => Record<string, unknown>;
     getFloatingProps: (userProps?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
     getItemProps: (userProps?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
-};
-/**
- * State context: values that change during interaction.
- * Subscribe only when you need reactive updates.
- */
-export type SelectStateContextValue = {
     open: boolean;
     value: OptionValue | undefined;
-    getSelectedTextValue: () => string | undefined;
+    displayText: string | undefined;
     activeIndex: number | null;
     highlightedValue: OptionValue | null;
     orderedOptions: RegisteredOption[];
+    /** O(1) index lookup: toKey(value) → index in orderedOptions */
+    optionIndexMap: Map<string, number>;
     floatingStyles: CSSProperties;
-    floatingContext: FloatingContext;
 };
-/**
- * Combined context value (for backwards compat and convenience hooks).
- * @deprecated Prefer using useSelectActions + useSelectState separately.
- */
-export type SelectContextValue = SelectActionsContextValue & SelectStateContextValue;
 export type SelectContentContextValue = {
     listRef: MutableRefObject<(HTMLElement | null)[]>;
     activeIndex: number | null;
     handleSelect: (index: number | null) => void;
     orderedOptions: RegisteredOption[];
+    /** O(1) index lookup: toKey(value) → index in orderedOptions */
+    optionIndexMap: Map<string, number>;
 };
 /**
  * Convert side + align to Floating UI placement.

package/components/Sidebar/Sidebar.js

@@ -25,45 +25,50 @@ function SidebarRoot(props) {
     }, [open]);
     const isClosing = drawer && !open && visible;
     const shouldRender = drawer && (open || visible);
+    // Dismiss: set visible false and restore focus to the element that opened
+    // the drawer. Called from both the reduced-motion layout effect and the
+    // animation-end handler — these are the actual unmount points, so focus
+    // must be restored here (not in a useEffect, which may not fire before
+    // the synchronous re-render unmounts the component).
+    const dismiss = useCallback(() => {
+        setVisible(false);
+        const el = restoreRef.current;
+        if (el && typeof el.focus === 'function' && document.contains(el)) {
+            el.focus();
+        }
+        restoreRef.current = null;
+    }, []);
     // When closing, check if animation will actually play (reduced motion).
-    // If not, unmount immediately to avoid getting stuck.
+    // If not, dismiss immediately to avoid getting stuck.
     useLayoutEffect(() => {
         if (!isClosing)
             return;
         const panel = panelRef.current;
         if (!panel) {
-            setVisible(false);
+            dismiss();
             return;
         }
         const style = getComputedStyle(panel);
         if (!style.animationName || style.animationName === 'none') {
-            setVisible(false);
+            dismiss();
         }
-    }, [isClosing]);
+    }, [isClosing, dismiss]);
     const handleAnimationEnd = useCallback((e) => {
         if (e.target === panelRef.current) {
-            setVisible(false);
+            dismiss();
         }
-    }, []);
+    }, [dismiss]);
     const rootClassName = ['tui-sidebar', className].filter(Boolean).join(' ');
     // ---------------------------------------------------------------------------
     // Drawer mode: capture trigger for focus restoration
     // ---------------------------------------------------------------------------
-    useEffect(() => {
-        if (!drawer || !isBrowser)
+    // Capture the element that had focus when the drawer opens.
+    // Must be a layout effect so it runs BEFORE the initial focus layout effect
+    // moves focus into the drawer. Focus restoration is handled by `dismiss()`.
+    useLayoutEffect(() => {
+        if (!drawer || !isBrowser || !open)
             return;
-        if (open) {
-            // Capture focus target when opening
-            restoreRef.current = document.activeElement;
-        }
-        else {
-            // Restore focus when closing (with DOM containment guard)
-            const el = restoreRef.current;
-            if (el && typeof el.focus === 'function' && document.contains(el)) {
-                el.focus();
-            }
-            restoreRef.current = null;
-        }
+        restoreRef.current = document.activeElement;
     }, [drawer, open]);
     // ---------------------------------------------------------------------------
     // Drawer mode: body scroll lock