@tangible/ui 0.0.7 → 0.0.8

package/components/Rating/types.d.ts

@@ -0,0 +1,41 @@
+import type { SizeStandard, Theme as ThemeFull } from '../../types';
+export type Size = SizeStandard;
+export type Theme = ThemeFull;
+export type RatingLabels = {
+    /** Group label for the radiogroup/img. Receives current value and max. */
+    rating?: (value: number, max: number) => string;
+    /** Visually-hidden label for each star. Receives star number and max. */
+    value?: (n: number, max: number) => string;
+};
+export declare const defaultRatingLabels: Required<RatingLabels>;
+export type RatingProps = {
+    /** Controlled value (1..max). Use with onValueChange */
+    value?: number;
+    /** Uncontrolled initial value */
+    defaultValue?: number;
+    /** Maximum icons shown */
+    max?: number;
+    /** Disable interaction (keeps semantics) */
+    disabled?: boolean;
+    /** Presentational readOnly (no form semantics) */
+    readOnly?: boolean;
+    /** Name for the radio group (if you care about form posts) */
+    name?: string;
+    /** Size maps to icon + spacing */
+    size?: Size;
+    /** Theme feeds foreground color tokens */
+    theme?: Theme;
+    /** Called when the value changes */
+    onValueChange?: (value: number) => void;
+    /** Allow clicking the current selection to clear back to 0 */
+    allowClear?: boolean;
+    className?: string;
+    /** Gap override (e.g. '0.25rem') – otherwise uses density utilities */
+    gap?: string;
+    /** Accessible label for the rating group. Defaults to "Rating: X of Y" */
+    'aria-label'?: string;
+    /**
+     * Override default English strings for i18n.
+     */
+    labels?: RatingLabels;
+};

package/components/Rating/types.js

@@ -0,0 +1,4 @@
+export const defaultRatingLabels = {
+    rating: (value, max) => `Rating: ${value} of ${max}`,
+    value: (n, max) => `${n} of ${max}`,
+};

package/components/SegmentedControl/SegmentedControl.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { cx } from '../../utils/cx.js';
 import { isDev } from '../../utils/is-dev.js';
 import { toKey } from '../../utils/value-key.js';
@@ -8,9 +8,10 @@ import { SegmentedControlContext, useSegmentedControlContext } from './Segmented
 // =============================================================================
 // SegmentedControl Root
 // =============================================================================
-function SegmentedControlRoot({ value: controlledValue, defaultValue, onValueChange, variant = 'pill', size = 'md', orientation = 'horizontal', loop = true, disabled = false, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, }) {
+function SegmentedControlRoot({ value: controlledValue, defaultValue, onValueChange, variant = 'pill', size = 'md', orientation = 'horizontal', loop = true, wrap = false, disabled = false, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, }) {
     const [internalValue, setInternalValue] = useState(defaultValue);
-    const isControlled = controlledValue !== undefined;
+    // Lock controlled/uncontrolled decision at mount to prevent mode switching
+    const isControlled = useRef(controlledValue !== undefined).current;
     const selectedValue = isControlled ? controlledValue : internalValue;
     // Selection handler
     const onSelect = useCallback((newValue) => {
@@ -28,7 +29,7 @@ function SegmentedControlRoot({ value: controlledValue, defaultValue, onValueCha
         disabled,
         loop,
         orientation,
-        orientationKeyboard: true,
+        orientationKeyboard: false,
     });
     // Dev-only: Warn if missing accessible name
     useEffect(() => {
@@ -60,7 +61,7 @@ function SegmentedControlRoot({ value: controlledValue, defaultValue, onValueCha
         unregisterItem,
         onSelect,
     ]);
-    return (_jsx(SegmentedControlContext.Provider, { value: contextValue, children: _jsx("div", { role: "radiogroup", className: cx('tui-segmented', `is-variant-${variant}`, `is-size-${size}`, orientation === 'vertical' && 'is-vertical', className), "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-disabled": disabled || undefined, "aria-orientation": orientation, onKeyDown: handleKeyDown, children: children }) }));
+    return (_jsx(SegmentedControlContext.Provider, { value: contextValue, children: _jsx("div", { role: "radiogroup", className: cx('tui-segmented', `is-variant-${variant}`, `is-size-${size}`, orientation === 'vertical' && 'is-vertical', wrap && 'is-wrap', className), "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-disabled": disabled || undefined, "aria-orientation": orientation, onKeyDown: handleKeyDown, children: children }) }));
 }
 // =============================================================================
 // SegmentedControl.Item

package/components/SegmentedControl/types.d.ts

@@ -1,8 +1,9 @@
 import type { ReactNode } from 'react';
 import type { RovingItemRecord } from '../../utils/use-roving-group';
+import type { SizeStandard } from '../../types/sizes';
 export type SegmentedControlValue = string | number;
 export type SegmentedControlVariant = 'pill' | 'outline' | 'underline';
-export type SegmentedControlSize = 'sm' | 'md';
+export type SegmentedControlSize = SizeStandard;
 export type SegmentedControlOrientation = 'horizontal' | 'vertical';
 export type SegmentedControlProps = {
     /** Controlled selected value */
@@ -19,11 +20,19 @@ export type SegmentedControlProps = {
     orientation?: SegmentedControlOrientation;
     /** Whether arrow keys wrap around */
     loop?: boolean;
+    /** Allow items to wrap to multiple lines (default: false) */
+    wrap?: boolean;
     /** Disable all items */
     disabled?: boolean;
-    /** Accessible label */
+    /**
+     * Accessible label for the radiogroup.
+     * At least one of `aria-label` or `aria-labelledby` is required.
+     */
     'aria-label'?: string;
-    /** ID of element that labels this control */
+    /**
+     * ID of element that labels this control.
+     * At least one of `aria-label` or `aria-labelledby` is required.
+     */
     'aria-labelledby'?: string;
     /** Additional classes */
     className?: string;
@@ -34,9 +43,12 @@ export type SegmentedControlItemProps = {
     value: SegmentedControlValue;
     /** Disable this item */
     disabled?: boolean;
-    /** Icon element */
+    /**
+     * Icon element rendered before the label.
+     * @remarks Icon-only items (no `children`) must provide `aria-label`.
+     */
     icon?: ReactNode;
-    /** Accessible label for icon-only items */
+    /** Accessible label — required for icon-only items */
     'aria-label'?: string;
     /** Additional classes */
     className?: string;

package/components/Select/Select.d.ts

@@ -37,3 +37,4 @@ export declare const SelectOption: typeof SelectOptionComponent;
 export declare const SelectGroup: typeof SelectGroupComponent;
 export declare const SelectLabel: typeof SelectLabelComponent;
 export { useSelectContext as useSelect } from './SelectContext';
+export type { SelectContextValue } from './types';

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)
 // =============================================================================