@tangible/ui 0.0.7 → 0.0.9

package/components/Dropdown/Dropdown.js

@@ -112,12 +112,23 @@ DropdownTriggerComponent.displayName = 'Dropdown.Trigger';
 // =============================================================================
 // DropdownContent
 // =============================================================================
-function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset = 4, className, style, children, }) {
-    const { open, setOpen, triggerRef, contentId, activeIndex, setActiveIndex, openedVia } = useDropdownContext();
+// Gate component: reads context to decide whether to mount the real content.
+// This ensures useFloating and all Floating UI hooks in DropdownContentInner
+// only run when the dropdown is actually open — not on every render cycle.
+function DropdownContentComponent(props) {
+    const { open } = useDropdownContext();
+    if (!open)
+        return null;
+    return _jsx(DropdownContentInner, { ...props });
+}
+DropdownContentComponent.displayName = 'Dropdown.Content';
+// Inner component: only mounted when open. All Floating UI hooks live here.
+function DropdownContentInner({ side = 'bottom', align = 'start', sideOffset = 4, className, style, children, }) {
+    const { setOpen, triggerRef, contentId, activeIndex, setActiveIndex, openedVia } = useDropdownContext();
     const listRef = useRef([]);
     const { refs, floatingStyles, context } = useFloating({
         placement: toPlacement(side, align),
-        open,
+        open: true, // Always true when mounted (gate handles the conditional)
         onOpenChange: setOpen,
         middleware: [offset(sideOffset), flip(), shift({ padding: 8 })],
         whileElementsMounted: autoUpdate,
@@ -130,9 +141,10 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
     }, [triggerRef, refs]);
     // Classify children: count navigable items and collect disabled indices.
     // Separator and Header sub-components are non-navigable.
-    const { disabledIndices, totalItemCount } = useMemo(() => {
+    const { disabledIndices, totalItemCount, firstEnabledIndex } = useMemo(() => {
         const disabled = [];
         let itemIdx = 0;
+        let firstEnabled = -1;
         Children.forEach(children, (child) => {
             if (!isValidElement(child))
                 return;
@@ -146,13 +158,16 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
             if (props.disabled) {
                 disabled.push(itemIdx);
             }
+            else if (firstEnabled === -1) {
+                firstEnabled = itemIdx;
+            }
             itemIdx++;
         });
-        return { disabledIndices: disabled, totalItemCount: itemIdx };
+        return { disabledIndices: disabled, totalItemCount: itemIdx, firstEnabledIndex: firstEnabled };
     }, [children]);
     // ArrowUp focus-last: set activeIndex to last valid item before paint
     useLayoutEffect(() => {
-        if (open && openedVia.current === 'ArrowUp') {
+        if (openedVia.current === 'ArrowUp') {
             let lastValid = totalItemCount - 1;
             while (lastValid >= 0 && disabledIndices.includes(lastValid)) {
                 lastValid--;
@@ -162,7 +177,7 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
             }
             openedVia.current = null;
         }
-    }, [open, openedVia, totalItemCount, disabledIndices, setActiveIndex]);
+    }, [openedVia, totalItemCount, disabledIndices, setActiveIndex]);
     const dismiss = useDismiss(context);
     const role = useRole(context, { role: 'menu' });
     const listNavigation = useListNavigation(context, {
@@ -180,8 +195,6 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
     ]);
     // Get portal root inside .tui-interface
     const portalRoot = getPortalRootFor(triggerRef.current);
-    if (!open)
-        return null;
     // Clone children to inject item props and role.
     // Non-navigable children (Separator, Header) are rendered as-is.
     let itemIndex = 0;
@@ -203,8 +216,16 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
                 ref: (node) => {
                     listRef.current[currentIndex] = node;
                 },
-                // Disabled items get tabIndex -1 always
-                tabIndex: isDisabled ? -1 : (activeIndex === currentIndex ? 0 : -1),
+                // Disabled items get tabIndex -1 always.
+                // When activeIndex is null (initial render before floating-ui
+                // activates), the first non-disabled item gets tabIndex 0 so at
+                // least one item is always keyboard-reachable.
+                tabIndex: isDisabled
+                    ? -1
+                    : (activeIndex === currentIndex
+                        || (activeIndex === null && !disabledIndices.includes(currentIndex) && currentIndex === firstEnabledIndex))
+                        ? 0
+                        : -1,
             }),
             // Add menuitem role if not already specified
             role: existingRole || 'menuitem',
@@ -217,7 +238,6 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
                     ...style,
                 }, ...getFloatingProps(), children: items }) }) }));
 }
-DropdownContentComponent.displayName = 'Dropdown.Content';
 // =============================================================================
 // DropdownItem
 // =============================================================================

package/components/Field/Field.d.ts

@@ -1,4 +1,6 @@
 import React from 'react';
+import type { FieldLabels } from './FieldContext';
+export type { FieldLabels };
 export type FieldProps = {
     /** Whether the field has an error state */
     error?: boolean;
@@ -8,6 +10,8 @@ export type FieldProps = {
     disabled?: boolean;
     /** Inline layout: label and control on same row */
     inline?: boolean;
+    /** Overridable strings for i18n. */
+    labels?: FieldLabels;
     /** Additional class name for the field wrapper */
     className?: string;
     children?: React.ReactNode;
@@ -36,4 +40,3 @@ type FieldCompound = React.ForwardRefExoticComponent<FieldProps & React.RefAttri
     Error: React.FC<ErrorProps>;
 };
 export declare const Field: FieldCompound;
-export {};

package/components/Field/Field.js

@@ -1,13 +1,18 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { forwardRef, useId, useMemo, cloneElement, isValidElement, Children, } from 'react';
+import React, { forwardRef, useEffect, useId, useMemo, useRef, cloneElement, isValidElement, Children, } from 'react';
 import { cx } from '../../utils/cx.js';
-import { FieldContext, useFieldContext } from './FieldContext.js';
-export const Field = forwardRef(function Field({ error = false, required = false, disabled = false, inline = false, className, children, }, ref) {
+import { isDev } from '../../utils/is-dev.js';
+import { FieldContext, useFieldContext, defaultFieldLabels } from './FieldContext.js';
+export const Field = forwardRef(function Field({ error = false, required = false, disabled = false, inline = false, labels: labelsProp, className, children, }, ref) {
     const baseId = useId();
     const controlId = `${baseId}-control`;
     const labelId = `${baseId}-label`;
     const helperTextId = `${baseId}-helper`;
     const errorId = `${baseId}-error`;
+    const labelRendered = useRef(false);
+    // Reset on each render — Label will set it back to true during its render
+    labelRendered.current = false;
+    const labels = useMemo(() => ({ ...defaultFieldLabels, ...labelsProp }), [labelsProp]);
     const contextValue = useMemo(() => ({
         controlId,
         labelId,
@@ -16,7 +21,9 @@ export const Field = forwardRef(function Field({ error = false, required = false
         hasError: error,
         required,
         disabled,
-    }), [controlId, labelId, helperTextId, errorId, error, required, disabled]);
+        labelRendered,
+        labels,
+    }), [controlId, labelId, helperTextId, errorId, error, required, disabled, labels]);
     const classes = cx('tui-field', error && 'is-error', disabled && 'is-disabled', inline && 'is-layout-inline', className);
     return (_jsx(FieldContext.Provider, { value: contextValue, children: _jsx("div", { ref: ref, className: classes, children: children }) }));
 });
@@ -24,16 +31,20 @@ export const Field = forwardRef(function Field({ error = false, required = false
 // Field.Label
 // =============================================================================
 function FieldLabel({ hidden = false, className, children, ...rest }) {
-    const { controlId, labelId, required } = useFieldContext();
+    const { controlId, labelId, required, labelRendered, labels } = useFieldContext();
+    // Signal to Field.Control that a label element exists in the tree.
+    // This is read synchronously during the same render pass (Label renders
+    // before Control in JSX order) to decide whether aria-labelledby is safe.
+    labelRendered.current = true;
     const classes = cx('tui-field__label', hidden && 'tui-visually-hidden', className);
-    return (_jsxs("label", { id: labelId, htmlFor: controlId, className: classes, ...rest, children: [children, required && (_jsxs(_Fragment, { children: [_jsx("span", { className: "tui-field__required", "aria-hidden": "true", children: "*" }), _jsx("span", { className: "tui-visually-hidden", children: "required" })] }))] }));
+    return (_jsxs("label", { id: labelId, htmlFor: controlId, className: classes, ...rest, children: [children, required && (_jsxs(_Fragment, { children: [_jsx("span", { className: "tui-field__required", "aria-hidden": "true", children: "*" }), _jsx("span", { className: "tui-visually-hidden", children: labels.required })] }))] }));
 }
 FieldLabel.displayName = 'Field.Label';
 // =============================================================================
 // Field.Control
 // =============================================================================
 function FieldControl({ children }) {
-    const { controlId, labelId, helperTextId, errorId, hasError, required, disabled, } = useFieldContext();
+    const { controlId, labelId, helperTextId, errorId, hasError, required, disabled, labelRendered, } = useFieldContext();
     const child = Children.only(children);
     if (!isValidElement(child)) {
         throw new Error('Field.Control expects a single React element as its child');
@@ -50,13 +61,23 @@ function FieldControl({ children }) {
         describedByParts.push(errorId);
     }
     const describedBy = describedByParts.join(' ');
-    // Build aria-labelledby for non-labelable elements (<button>, <div>, etc.)
-    // <label htmlFor> only works with labelable elements (input, textarea, select,
-    // meter, output, progress). For everything else (Switch, future Slider, etc.)
-    // aria-labelledby provides the accessible name. For native inputs this is
-    // redundant with htmlFor but harmless — aria-labelledby takes priority in the
-    // accessible name algorithm and points at the same label text.
-    const labelledBy = childProps['aria-labelledby'] ?? labelId;
+    // Only inject aria-labelledby when Field.Label is present in the tree.
+    // Without a rendered label, the ID points at nothing — and per AccName 1.2
+    // step 2B, aria-labelledby overrides ALL other name sources (including
+    // implicit <label> wrapping). A phantom ID produces an empty name, which
+    // strips the accessible name from self-labelling controls like Checkbox.
+    const childLabelledBy = childProps['aria-labelledby'];
+    const injectedLabelledBy = labelRendered.current;
+    const labelledBy = childLabelledBy ?? (injectedLabelledBy ? labelId : undefined);
+    // DEV: warn if Field.Label appears after Field.Control in JSX order —
+    // labelRendered will be false at render time but true after mount.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    useEffect(() => {
+        if (isDev() && !injectedLabelledBy && !childLabelledBy && labelRendered.current) {
+            console.warn('Field: Field.Label appears after Field.Control in the JSX tree. ' +
+                'Move Field.Label before Field.Control so aria-labelledby is wired correctly.');
+        }
+    }, []);
     // Clone child with a11y props
     // Note: aria-invalid and aria-required must be string "true", not boolean
     return cloneElement(child, {

package/components/Field/FieldContext.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Overridable strings for Field i18n.
+ */
+export type FieldLabels = {
+    /** Visually-hidden text appended to required field labels. @default "required" */
+    required?: string;
+};
+export declare const defaultFieldLabels: Required<FieldLabels>;
 export type FieldContextValue = {
     /** ID for the form control element */
     controlId: string;
@@ -13,6 +21,14 @@ export type FieldContextValue = {
     required: boolean;
     /** Whether the field is disabled */
     disabled: boolean;
+    /** Mutable flag — set by Field.Label during render so Field.Control knows
+     *  whether to inject aria-labelledby. Avoids injecting a phantom ID that
+     *  overrides implicit <label> associations in the accessible name algorithm. */
+    labelRendered: {
+        current: boolean;
+    };
+    /** Resolved i18n labels for Field sub-components */
+    labels: Required<FieldLabels>;
 };
 export declare const FieldContext: import("react").Context<FieldContextValue | null>;
 export declare function useFieldContext(): FieldContextValue;

package/components/Field/FieldContext.js

@@ -1,4 +1,7 @@
 import { createContext, useContext } from 'react';
+export const defaultFieldLabels = {
+    required: 'required',
+};
 export const FieldContext = createContext(null);
 export function useFieldContext() {
     const context = useContext(FieldContext);

package/components/Field/index.d.ts

@@ -1,2 +1,3 @@
 export { Field } from './Field';
-export type { FieldProps } from './Field';
+export type { FieldProps, FieldLabels } from './Field';
+export { defaultFieldLabels } from './FieldContext';

package/components/Field/index.js

@@ -1 +1,2 @@
 export { Field } from './Field.js';
+export { defaultFieldLabels } from './FieldContext.js';

package/components/Icon/Icon.d.ts

@@ -19,4 +19,4 @@ export interface IconProps {
  * - Decorative icons (no label): automatically hidden from screen readers
  * - Informative icons: provide a `label` prop for screen reader announcement
  */
-export declare const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<HTMLSpanElement>>;
+export declare const Icon: React.NamedExoticComponent<IconProps & React.RefAttributes<HTMLSpanElement>>;

package/components/Icon/Icon.js

@@ -10,7 +10,7 @@ import { iconRegistry } from '../../icons/registry.js';
  * - Decorative icons (no label): automatically hidden from screen readers
  * - Informative icons: provide a `label` prop for screen reader announcement
  */
-export const Icon = React.forwardRef(({ name, emoji, label, size, className }, ref) => {
+export const Icon = React.memo(React.forwardRef(({ name, emoji, label, size, className }, ref) => {
     const SvgIcon = name ? iconRegistry[name] : null;
     // Dev warning for invalid icon name
     if (isDev() && name && !SvgIcon) {
@@ -21,5 +21,5 @@ export const Icon = React.forwardRef(({ name, emoji, label, size, className }, r
     return (_jsxs("span", { ref: ref, className: cx('tui-icon', size && `is-size-${size}`, className), ...(isDecorative
             ? { 'aria-hidden': true }
             : { role: 'img', 'aria-label': label }), children: [SvgIcon && _jsx(SvgIcon, { "aria-hidden": "true", focusable: "false" }), !SvgIcon && emoji] }));
-});
+}));
 Icon.displayName = 'Icon';

package/components/Modal/Modal.d.ts

@@ -17,9 +17,13 @@ export type ModalProps = {
     closeLabel?: string;
     closeOnBackdropClick?: boolean;
     closeOnEscape?: boolean;
+    /** When true, prevents the browser from scrolling to the trigger element
+     *  when focus is restored on close. Useful when the trigger may be off-screen
+     *  inside a scrollable container. Default: false. */
+    preventScrollOnRestore?: boolean;
     children?: React.ReactNode;
 };
-declare function ModalRoot({ open, onClose, size, stickyHead, stickyFoot, 'aria-labelledby': labelledBy, 'aria-describedby': describedBy, initialFocusSelector, container, showCloseButton, closeLabel, closeOnBackdropClick, closeOnEscape, children, }: ModalProps): React.ReactPortal | null;
+declare function ModalRoot({ open, onClose, size, stickyHead, stickyFoot, 'aria-labelledby': labelledBy, 'aria-describedby': describedBy, initialFocusSelector, container, showCloseButton, closeLabel, closeOnBackdropClick, closeOnEscape, preventScrollOnRestore, children, }: ModalProps): React.ReactPortal | null;
 type ModalCloseProps = {
     label?: string;
     className?: string;

package/components/Modal/Modal.js

@@ -8,7 +8,7 @@ import { useFocusTrap, getInitialFocus } from '../../utils/focus-trap.js';
 import { ModalContext, useModalContext } from './context.js';
 import { IconButton } from '../IconButton/index.js';
 const isBrowser = typeof document !== 'undefined';
-function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-labelledby': labelledBy, 'aria-describedby': describedBy, initialFocusSelector, container, showCloseButton, closeLabel = 'Close', closeOnBackdropClick = true, closeOnEscape = true, children, }) {
+function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-labelledby': labelledBy, 'aria-describedby': describedBy, initialFocusSelector, container, showCloseButton, closeLabel = 'Close', closeOnBackdropClick = true, closeOnEscape = true, preventScrollOnRestore = false, children, }) {
     const dialogRef = useRef(null);
     const restoreRef = useRef(null);
     const warnedRef = useRef(false);
@@ -45,7 +45,7 @@ function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-l
             return;
         const el = restoreRef.current;
         if (el && typeof el.focus === 'function') {
-            el.focus();
+            el.focus({ preventScroll: preventScrollOnRestore });
         }
         restoreRef.current = null;
         setMount(null);

package/components/MoveHandle/MoveHandle.d.ts

@@ -1,2 +1,2 @@
 import type { MoveHandleProps } from './types';
-export declare const MoveHandle: import("react").ForwardRefExoticComponent<MoveHandleProps & import("react").RefAttributes<HTMLElement>>;
+export declare const MoveHandle: import("react").NamedExoticComponent<MoveHandleProps & import("react").RefAttributes<HTMLElement>>;

package/components/MoveHandle/MoveHandle.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useCallback, useEffect, useId, useRef, useState } from 'react';
+import { forwardRef, memo, useCallback, useEffect, useId, useRef, useState } from 'react';
 import { cx } from '../../utils/cx.js';
 import { isDev } from '../../utils/is-dev.js';
 import { Icon } from '../Icon/index.js';
@@ -24,7 +24,7 @@ import { Icon } from '../Icon/index.js';
 //   --tui-move-handle-icon-size  Override icon size
 //
 // =============================================================================
-export const MoveHandle = forwardRef(function MoveHandle({ mode = 'full', size = 'md', index, locked = false, onMoveUp, onMoveDown, canMoveUp = true, canMoveDown = true, labels, dragHandleProps, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, }, ref) {
+export const MoveHandle = memo(forwardRef(function MoveHandle({ mode = 'full', size = 'md', index, locked = false, onMoveUp, onMoveDown, canMoveUp = true, canMoveDown = true, labels, dragHandleProps, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, }, ref) {
     // All hooks must be called unconditionally (rules of hooks)
     const innerRef = useRef(null);
     const mergedRef = useCallback((node) => {
@@ -83,7 +83,7 @@ export const MoveHandle = forwardRef(function MoveHandle({ mode = 'full', size =
     // Uses ref directly (not mergedRef) — innerRef is unused for this path.
     // Focus recovery and dev warning effects early-return for handle mode.
     if (mode === 'handle') {
-        return (_jsx("button", { ref: ref, type: "button", className: cx('tui-move-handle', 'is-handle', className), "aria-label": resolvedDragLabel, ...restDragProps, children: _jsx(Icon, { name: "system/drag" }) }));
+        return (_jsx("button", { ref: ref, type: "button", className: cx('tui-move-handle', 'is-handle', `is-size-${size}`, className), "aria-label": resolvedDragLabel, ...restDragProps, children: _jsx(Icon, { name: "system/drag" }) }));
     }
     // ----- Full mode -----
     const hasIndex = index != null;
@@ -92,4 +92,4 @@ export const MoveHandle = forwardRef(function MoveHandle({ mode = 'full', size =
         ? (labels?.locked ?? 'This item is locked and cannot be reordered')
         : undefined;
     return (_jsxs("div", { ref: mergedRef, role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": locked ? lockedDescId : undefined, "aria-disabled": locked || undefined, className: cx('tui-move-handle', `is-size-${size}`, locked && 'is-locked', hasIndex && 'has-index', className), children: [locked && (_jsx("span", { id: lockedDescId, className: "tui-visually-hidden", children: resolvedLockedDesc })), onMoveUp && (_jsx("button", { type: "button", className: "tui-move-handle__up", "data-direction": "up", "aria-label": labels?.moveUp ?? 'Move up', disabled: locked || !canMoveUp, onClick: onMoveUp, children: _jsx(Icon, { name: "system/chevron-up" }) })), _jsx("div", { className: "tui-move-handle__center", children: showLockIcon ? (_jsx("span", { className: "tui-move-handle__lock", "aria-hidden": "true", children: _jsx(Icon, { name: "system/lock" }) })) : (_jsxs(_Fragment, { children: [hasIndex && (_jsx("span", { className: "tui-move-handle__index", "aria-hidden": "true", children: index })), _jsx("button", { type: "button", className: "tui-move-handle__handle", "data-role": "drag-handle", "aria-label": resolvedDragLabel, tabIndex: hasArrows ? -1 : 0, ...restDragProps, children: _jsx(Icon, { name: "system/handle-alt" }) })] })) }), onMoveDown && (_jsx("button", { type: "button", className: "tui-move-handle__down", "data-direction": "down", "aria-label": labels?.moveDown ?? 'Move down', disabled: locked || !canMoveDown, onClick: onMoveDown, children: _jsx(Icon, { name: "system/chevron-down" }) }))] }));
-});
+}));

package/components/MoveHandle/types.d.ts

@@ -17,7 +17,7 @@ export interface MoveHandleLabels {
 export interface MoveHandleProps {
     /** Structural mode. 'full' (default) shows background panel with arrows/index. 'handle' shows only the bare drag icon button. */
     mode?: MoveHandleMode;
-    /** Component scale. sm = 32px, md = 40px. Ignored when mode is 'handle'. */
+    /** Component scale. Full mode: sm = 32px, md = 40px. Handle mode: sm = 24px, md = 32px. */
     size?: MoveHandleSize;
     /** Position index. When provided, shows number at rest, drag handle on hover. */
     index?: number;

package/components/MultiSelect/MultiSelect.d.ts

@@ -1,5 +1,5 @@
 import { type MultiSelectProps, type MultiSelectTriggerProps, type MultiSelectContentProps, type MultiSelectOptionProps, type MultiSelectGroupProps, type MultiSelectLabelProps } from './types';
-declare function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, onValueChange, open: controlledOpen, defaultOpen, onOpenChange, disabled, placeholder, size, display, maxChips, max, onMaxReached, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, children, }: MultiSelectProps): import("react/jsx-runtime").JSX.Element;
+declare function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, onValueChange, open: controlledOpen, defaultOpen, onOpenChange, disabled, placeholder, size, display, maxChips, max, onMaxReached, labels: labelsProp, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, children, }: MultiSelectProps): import("react/jsx-runtime").JSX.Element;
 declare namespace MultiSelectRoot {
     var displayName: string;
 }

package/components/MultiSelect/MultiSelect.js

@@ -6,20 +6,24 @@ import { cx } from '../../utils/cx.js';
 import { getPortalRootFor } from '../../utils/portal.js';
 import { Icon } from '../Icon/index.js';
 import { MultiSelectActionsContext, MultiSelectStateContext, MultiSelectContentContext, useMultiSelectContext, useMultiSelectContentContext, } from './MultiSelectContext.js';
-import { toKey, } from './types.js';
+import { toKey, defaultMultiSelectLabels, } from './types.js';
 // =============================================================================
 // MultiSelect Root
 // =============================================================================
-function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, onValueChange, open: controlledOpen, defaultOpen, onOpenChange, disabled = false, placeholder = '', size = 'md', display = 'count', maxChips = 3, max, onMaxReached, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, children, }) {
+function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, onValueChange, open: controlledOpen, defaultOpen, onOpenChange, disabled = false, placeholder = '', size = 'md', display = 'count', maxChips = 3, max, onMaxReached, labels: labelsProp, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, children, }) {
+    // Merge caller labels with defaults
+    const labels = useMemo(() => ({ ...defaultMultiSelectLabels, ...labelsProp }), [labelsProp]);
     // Controlled/uncontrolled value
     const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue ?? []);
-    const isValueControlled = controlledValue !== undefined;
-    const value = isValueControlled ? controlledValue : uncontrolledValue;
+    const isValueControlled = useRef(controlledValue !== undefined).current;
+    const value = (isValueControlled ? controlledValue : uncontrolledValue);
     // Track selected text values for display when closed
     const selectedTextMapRef = useRef(new Map());
     // Option registration
     const optionsRef = useRef(new Map());
     const [registryVersion, setRegistryVersion] = useState(0);
+    // Track open state via ref so unregisterOption can check synchronously
+    const openRef = useRef(false);
     // Is selected helper
     const isSelected = useCallback((optionValue) => {
         const key = toKey(optionValue);
@@ -104,6 +108,7 @@ function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultVal
     const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen ?? false);
     const isOpenControlled = controlledOpen !== undefined;
     const open = isOpenControlled ? controlledOpen : uncontrolledOpen;
+    openRef.current = open;
     const setOpen = useCallback((nextOpen) => {
         if (disabled)
             return;
@@ -213,9 +218,21 @@ function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultVal
         setRegistryVersion((v) => v + 1);
     }, []);
     const unregisterOption = useCallback((optionValue) => {
+        // Skip when closing — preserve registry for chip display text.
+        // Options re-register on next open (same keys).
+        if (!openRef.current)
+            return;
         optionsRef.current.delete(toKey(optionValue));
         setRegistryVersion((v) => v + 1);
     }, []);
+    // Flush stale registry on open. Options that were registered before close
+    // may no longer exist (parent changed children while closed). Clearing
+    // before the new options mount ensures no orphaned entries accumulate.
+    useLayoutEffect(() => {
+        if (open) {
+            optionsRef.current.clear();
+        }
+    }, [open]);
     // Get selected options for trigger display
     const getSelectedOptions = useCallback(() => {
         return value
@@ -273,6 +290,7 @@ function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultVal
         maxChips,
         max,
         size,
+        labels,
         // ARIA IDs (stable)
         triggerId,
         listboxId,
@@ -300,6 +318,7 @@ function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultVal
         maxChips,
         max,
         size,
+        labels,
         // IDs are stable (from useId)
         triggerId,
         listboxId,
@@ -356,7 +375,7 @@ MultiSelectRoot.displayName = 'MultiSelect';
 // MultiSelect.Trigger
 // =============================================================================
 function MultiSelectTriggerComponent({ asChild = false, className, children, }) {
-    const { open, setOpen, disabled, placeholder, size, display, maxChips, max, maxReached, triggerId, listboxId, ariaLabel, ariaLabelledBy, ariaDescribedBy, getSelectedOptions, clearAll, refs, getReferenceProps, activeIndex, orderedOptions, toggleOption, isSelected, } = useMultiSelectContext();
+    const { open, setOpen, disabled, placeholder, size, display, maxChips, max, maxReached, labels, triggerId, listboxId, ariaLabel, ariaLabelledBy, ariaDescribedBy, getSelectedOptions, clearAll, refs, getReferenceProps, activeIndex, orderedOptions, toggleOption, isSelected, } = useMultiSelectContext();
     const sizeClass = size !== 'md' ? `is-size-${size}` : undefined;
     const selectedOptions = getSelectedOptions();
     const hasSelection = selectedOptions.length > 0;
@@ -422,19 +441,17 @@ function MultiSelectTriggerComponent({ asChild = false, className, children, })
             return _jsx("span", { className: "tui-multiselect__placeholder", children: placeholder });
         }
         if (display === 'count') {
-            return (_jsxs("span", { className: "tui-multiselect__count", children: [selectedOptions.length, " selected"] }));
+            return (_jsx("span", { className: "tui-multiselect__count", children: labels.selected(selectedOptions.length) }));
         }
         // chips mode
         const visibleChips = selectedOptions.slice(0, maxChips);
         const overflow = selectedOptions.length - maxChips;
-        return (_jsxs("span", { className: "tui-multiselect__chips", children: [visibleChips.map((opt) => (_jsx("span", { className: "tui-multiselect__chip", children: opt.textValue }, toKey(opt.value)))), overflow > 0 && (_jsxs("span", { className: "tui-multiselect__more", children: ["+", overflow, " more"] }))] }));
+        return (_jsxs("span", { className: "tui-multiselect__chips", children: [visibleChips.map((opt) => (_jsx("span", { className: "tui-multiselect__chip", children: opt.textValue }, toKey(opt.value)))), overflow > 0 && (_jsx("span", { className: "tui-multiselect__more", children: labels.more(overflow) }))] }));
     };
     // Default trigger content (when not using asChild or custom children)
     const defaultTriggerContent = (_jsxs(_Fragment, { children: [_jsx("span", { className: "tui-multiselect__value", children: renderTriggerContent() }), hasSelection && (_jsx("span", { className: "tui-multiselect__clear", onClick: handleClearClick, "aria-hidden": "true", children: _jsx(Icon, { name: "system/close", size: "sm" }) })), _jsx(Icon, { name: "system/chevron-down", size: "sm", className: "tui-multiselect__icon", "aria-hidden": "true" })] }));
     // Generate status message for screen readers
-    const statusMessage = hasSelection
-        ? `${selectedOptions.length} item${selectedOptions.length === 1 ? '' : 's'} selected${maxReached && max ? `. Maximum of ${max} reached` : ''}`
-        : '';
+    const statusMessage = labels.status(selectedOptions.length, max);
     // Live region (rendered outside button, sibling to trigger)
     const liveRegion = (_jsx("span", { className: "tui-visually-hidden", role: "status", "aria-live": "polite", "aria-atomic": "true", children: statusMessage }));
     // Base trigger props
@@ -446,9 +463,8 @@ function MultiSelectTriggerComponent({ asChild = false, className, children, })
         'aria-haspopup': 'listbox',
         'aria-expanded': open,
         'aria-controls': listboxId,
-        'aria-disabled': disabled || undefined,
+        'aria-keyshortcuts': hasSelection && !open ? 'Delete' : undefined,
         'data-state': open ? 'open' : 'closed',
-        'data-disabled': disabled || undefined,
         ...floatingProps,
     };
     // asChild: merge props onto child element
@@ -481,6 +497,7 @@ function MultiSelectTriggerComponent({ asChild = false, className, children, })
                     'aria-controls': listboxId,
                     '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,
@@ -505,7 +522,7 @@ function MultiSelectTriggerComponent({ asChild = false, className, children, })
     }
     // Default: render button with optional custom content
     const triggerContent = children ?? defaultTriggerContent;
-    return (_jsxs(_Fragment, { children: [_jsx("button", { ref: refs.setReference, type: "button", id: triggerId, className: cx('tui-multiselect__trigger', sizeClass, className), disabled: disabled, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": listboxId, "aria-disabled": disabled || undefined, "data-state": open ? 'open' : 'closed', "data-disabled": disabled || undefined, ...floatingProps, 
+    return (_jsxs(_Fragment, { children: [_jsx("button", { ref: refs.setReference, type: "button", id: triggerId, className: cx('tui-multiselect__trigger', sizeClass, className), disabled: disabled, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": listboxId, "data-state": open ? 'open' : 'closed', ...floatingProps, 
                 // Handle Backspace/Delete AFTER floatingProps to ensure we catch it
                 // (typeahead may intercept these for its buffer)
                 onKeyDown: (e) => {
@@ -526,13 +543,19 @@ MultiSelectTriggerComponent.displayName = 'MultiSelect.Trigger';
 function MultiSelectContentComponent({ className, children }) {
     const { open, listboxId, triggerId, refs, floatingStyles, getFloatingProps, listRef, activeIndex, orderedOptions, } = useMultiSelectContext();
     const portalRoot = getPortalRootFor(refs.reference.current);
+    // Track whether dropdown has ever been opened. Before first open, mount
+    // children in a hidden div for option registration. After first open,
+    // only mount children when open (in portal).
+    const hasEverOpened = useRef(false);
+    if (open)
+        hasEverOpened.current = true;
     // Memoized context for options
     const contentContext = useMemo(() => ({
         listRef,
         activeIndex,
         orderedOptions,
     }), [listRef, activeIndex, orderedOptions]);
-    return (_jsxs(_Fragment, { children: [!open && (_jsx("div", { style: { display: 'none' }, "aria-hidden": "true", children: _jsx(MultiSelectContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": triggerId, "aria-multiselectable": "true", className: cx('tui-multiselect__content', className), style: {
+    return (_jsxs(_Fragment, { children: [!open && !hasEverOpened.current && (_jsx("div", { id: listboxId, role: "listbox", style: { display: 'none' }, "aria-hidden": "true", children: _jsx(MultiSelectContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": triggerId, "aria-multiselectable": "true", className: cx('tui-multiselect__content', className), style: {
                         ...floatingStyles,
                         minWidth: refs.reference.current?.offsetWidth,
                         pointerEvents: 'auto',
@@ -548,9 +571,11 @@ function MultiSelectOptionComponent({ value: optionValue, disabled = false, text
     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 (fire once per mount)
+    const warnedTextValueRef = useRef(false);
     useEffect(() => {
-        if (isDev() && !textValue) {
+        if (isDev() && !textValue && !warnedTextValueRef.current) {
+            warnedTextValueRef.current = true;
             console.warn(`MultiSelect.Option with value="${optionValue}" has no textValue. Provide textValue prop when children is not a string.`);
         }
     }, [textValue, optionValue]);
@@ -593,7 +618,16 @@ MultiSelectOptionComponent.displayName = 'MultiSelect.Option';
 // =============================================================================
 function MultiSelectGroupComponent({ className, children }) {
     const groupId = useId();
-    return (_jsx("div", { role: "group", "aria-labelledby": `${groupId}-label`, className: cx('tui-multiselect__group', className), children: _jsx(MultiSelectGroupContext.Provider, { value: { groupId }, children: children }) }));
+    const groupRef = useRef(null);
+    const [hasLabel, setHasLabel] = useState(false);
+    // Check if a Label child rendered — guard aria-labelledby to prevent dangling reference
+    useLayoutEffect(() => {
+        if (groupRef.current) {
+            const labelEl = groupRef.current.querySelector(`#${CSS.escape(`${groupId}-label`)}`);
+            setHasLabel(!!labelEl);
+        }
+    }, [groupId, children]);
+    return (_jsx("div", { ref: groupRef, role: "group", "aria-labelledby": hasLabel ? `${groupId}-label` : undefined, className: cx('tui-multiselect__group', className), children: _jsx(MultiSelectGroupContext.Provider, { value: { groupId }, children: children }) }));
 }
 MultiSelectGroupComponent.displayName = 'MultiSelect.Group';
 const MultiSelectGroupContext = React.createContext(null);
@@ -602,8 +636,13 @@ const MultiSelectGroupContext = React.createContext(null);
 // =============================================================================
 function MultiSelectLabelComponent({ className, children }) {
     const groupContext = React.useContext(MultiSelectGroupContext);
-    // No aria-hidden or role="presentation" — aria-labelledby on Group references this element,
-    // so screen readers need access to read the label text.
+    const warnedRef = useRef(false);
+    useEffect(() => {
+        if (isDev() && !groupContext && !warnedRef.current) {
+            warnedRef.current = true;
+            console.warn('MultiSelect.Label should be used inside MultiSelect.Group for accessibility.');
+        }
+    }, [groupContext]);
     return (_jsx("div", { id: groupContext ? `${groupContext.groupId}-label` : undefined, className: cx('tui-multiselect__label', className), children: children }));
 }
 MultiSelectLabelComponent.displayName = 'MultiSelect.Label';

package/components/MultiSelect/index.d.ts

@@ -1,2 +1,3 @@
 export { MultiSelect, MultiSelectTrigger, MultiSelectContent, MultiSelectOption, MultiSelectGroup, MultiSelectLabel, useMultiSelect, } from './MultiSelect';
-export type { MultiSelectProps, MultiSelectTriggerProps, MultiSelectContentProps, MultiSelectOptionProps, MultiSelectGroupProps, MultiSelectLabelProps, MultiSelectValue, OptionValue, DisplayMode, RegisteredOption as MultiSelectRegisteredOption, } from './types';
+export { defaultMultiSelectLabels } from './types';
+export type { MultiSelectProps, MultiSelectTriggerProps, MultiSelectContentProps, MultiSelectOptionProps, MultiSelectGroupProps, MultiSelectLabelProps, MultiSelectLabels, MultiSelectValue, OptionValue, DisplayMode, RegisteredOption as MultiSelectRegisteredOption, } from './types';

package/components/MultiSelect/index.js

@@ -1 +1,2 @@
 export { MultiSelect, MultiSelectTrigger, MultiSelectContent, MultiSelectOption, MultiSelectGroup, MultiSelectLabel, useMultiSelect, } from './MultiSelect.js';
+export { defaultMultiSelectLabels } from './types.js';