@tangible/ui 0.0.7 → 0.0.9

package/components/Accordion/Accordion.js

@@ -246,10 +246,18 @@ function AccordionTrigger({ asChild = false, 'aria-label': ariaLabel, children,
 // =============================================================================
 function AccordionPanel({ landmark = false, children, className }) {
     const { triggerId, panelId, isOpen } = useAccordionItemContext();
+    const panelRef = useRef(null);
     const state = isOpen ? 'open' : 'closed';
-    return (_jsx("div", { id: panelId, role: landmark ? 'region' : undefined, "aria-labelledby": landmark ? triggerId : undefined, className: cx('tui-accordion__panel', className), "data-state": state, "aria-hidden": !isOpen, 
-        // Prevent keyboard focus into collapsed panels
-        inert: !isOpen || undefined, children: _jsx("div", { className: "tui-accordion__panel-content", children: children }) }));
+    // Set inert via DOM property for React 18 compatibility.
+    // React 18 doesn't handle `inert` as a boolean prop — it renders it as a
+    // string attribute and may not reliably remove it on re-renders.
+    // Setting the DOM property directly works across React 18 and 19.
+    React.useEffect(() => {
+        if (panelRef.current) {
+            panelRef.current.inert = !isOpen;
+        }
+    }, [isOpen]);
+    return (_jsx("div", { ref: panelRef, id: panelId, role: landmark ? 'region' : undefined, "aria-labelledby": landmark ? triggerId : undefined, className: cx('tui-accordion__panel', className), "data-state": state, "aria-hidden": !isOpen, children: _jsx("div", { className: "tui-accordion__panel-content", children: children }) }));
 }
 // =============================================================================
 // Export Compound Component

package/components/Avatar/Avatar.d.ts

@@ -8,4 +8,4 @@ import type { AvatarProps } from './types';
  * - Shows placeholder icon if neither `src` nor `name` provided
  * - Colors for initials are derived from the name hash for consistency
  */
-export declare const Avatar: React.ForwardRefExoticComponent<AvatarProps & React.RefAttributes<HTMLSpanElement>>;
+export declare const Avatar: React.NamedExoticComponent<AvatarProps & React.RefAttributes<HTMLSpanElement>>;

package/components/Avatar/Avatar.js

@@ -3,7 +3,7 @@ import React, { useState, useMemo } from 'react';
 import { cx } from '../../utils/cx.js';
 import { Icon } from '../Icon/index.js';
 import { Tooltip } from '../Tooltip/index.js';
-import { AVATAR_COLORS } from './types.js';
+import { AVATAR_COLORS, defaultAvatarLabels } from './types.js';
 /**
  * Generate initials from a name.
  * "Mary Ghen" → "MG", "Bob" → "B", "Jean-Luc Picard" → "JP"
@@ -46,7 +46,7 @@ function getColorFromName(name, colors) {
  * - Shows placeholder icon if neither `src` nor `name` provided
  * - Colors for initials are derived from the name hash for consistency
  */
-export const Avatar = React.forwardRef(({ src, name, size = 'md', shape = 'circle', color, indicator, indicatorLabel, indicatorPosition = 'bottom-right', tooltip, className, }, ref) => {
+export const Avatar = React.memo(React.forwardRef(({ src, name, size = 'md', shape = 'circle', color, indicator, indicatorLabel, indicatorPosition = 'bottom-right', tooltip, labels: labelsProp, className, }, ref) => {
     const [imgError, setImgError] = useState(false);
     // Reset error state when src changes
     React.useEffect(() => {
@@ -54,6 +54,7 @@ export const Avatar = React.forwardRef(({ src, name, size = 'md', shape = 'circl
     }, [src]);
     const initials = useMemo(() => (name ? getInitials(name) : ''), [name]);
     const derivedColor = useMemo(() => color ?? (name ? getColorFromName(name, AVATAR_COLORS) : 'slate'), [color, name]);
+    const labels = useMemo(() => ({ ...defaultAvatarLabels, ...labelsProp }), [labelsProp]);
     const showImage = src && !imgError;
     const showInitials = !showImage && initials;
     const showPlaceholder = !showImage && !initials;
@@ -65,12 +66,12 @@ export const Avatar = React.forwardRef(({ src, name, size = 'md', shape = 'circl
             : {
                 role: 'img',
                 'aria-label': name && indicatorLabel
-                    ? `${name}, ${indicatorLabel}`
+                    ? labels.description(name, indicatorLabel)
                     : name || indicatorLabel,
             }), children: [_jsxs("span", { className: "tui-avatar__content", children: [showImage && (_jsx("img", { src: src, alt: "", className: "tui-avatar__image", onError: () => setImgError(true) })), showInitials && (_jsx("span", { className: "tui-avatar__initials", "aria-hidden": "true", children: initials })), showPlaceholder && (_jsx(Icon, { name: "system/user-circle-outline", className: "tui-avatar__placeholder" }))] }), indicator && (_jsx("span", { className: cx('tui-avatar__indicator', `is-position-${indicatorPosition}`), "aria-hidden": "true", children: indicator }))] }));
     if (showTooltip) {
         return (_jsxs(Tooltip, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: avatarElement }), _jsx(Tooltip.Content, { "aria-hidden": "true", children: name })] }));
     }
     return avatarElement;
-});
+}));
 Avatar.displayName = 'Avatar';

package/components/Avatar/AvatarGroup.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { Children, isValidElement, cloneElement } from 'react';
 import { cx } from '../../utils/cx.js';
 import { OverlapStack } from '../OverlapStack/index.js';
+import { defaultAvatarGroupLabels } from './types.js';
 /**
  * AvatarGroup displays multiple avatars with optional overlap.
  *
@@ -10,7 +11,8 @@ import { OverlapStack } from '../OverlapStack/index.js';
  * - Non-overlap mode uses flex with gap
  * - Override overlap amount via `--tui-avatar-group-overlap` CSS property
  */
-export const AvatarGroup = React.forwardRef(({ max, size, shape, overlap = true, groupLabel: groupLabelFn, children, className }, ref) => {
+export const AvatarGroup = React.forwardRef(({ max, size, shape, overlap = true, groupLabel: groupLabelFn, labels: labelsProp, children, className }, ref) => {
+    const labels = { ...defaultAvatarGroupLabels, ...labelsProp };
     const childArray = Children.toArray(children).filter(isValidElement);
     const total = childArray.length;
     // Clone children to inject size/shape props if provided at group level
@@ -23,14 +25,14 @@ export const AvatarGroup = React.forwardRef(({ max, size, shape, overlap = true,
         }
         return child;
     });
-    // Descriptive label for the group
+    // Descriptive label for the group — groupLabel prop takes precedence over labels bag
     const hasOverflow = max !== undefined && total > max;
     const visibleCount = hasOverflow ? max : total;
     const groupLabel = groupLabelFn
         ? groupLabelFn(total, visibleCount)
         : hasOverflow
-            ? `${total} users, showing ${visibleCount}`
-            : `${total} users`;
+            ? labels.group(total, visibleCount)
+            : labels.groupAll(total);
     // Non-overlap mode: simple flex layout
     if (!overlap) {
         return (_jsx("div", { ref: ref, className: cx('tui-avatar-group', className), role: "group", "aria-label": groupLabel, children: clonedChildren }));
@@ -39,7 +41,7 @@ export const AvatarGroup = React.forwardRef(({ max, size, shape, overlap = true,
     // Note: We don't use OverlapStack's `frame` prop because its border-radius
     // wouldn't match each avatar's shape. Instead, we apply ring styles via CSS
     // directly to avatars inside .is-overlap groups.
-    return (_jsx(OverlapStack, { ref: ref, className: cx('tui-avatar-group', 'is-overlap', className), max: max, renderOverflow: (count) => (_jsx(AvatarOverflow, { count: count, size: size, shape: shape })), overflowLabel: (count) => `${count} more users`, "aria-label": groupLabel, children: clonedChildren }));
+    return (_jsx(OverlapStack, { ref: ref, className: cx('tui-avatar-group', 'is-overlap', className), max: max, renderOverflow: (count) => (_jsx(AvatarOverflow, { count: count, size: size, shape: shape })), overflowLabel: labels.overflow, "aria-label": groupLabel, children: clonedChildren }));
 });
 AvatarGroup.displayName = 'AvatarGroup';
 function AvatarOverflow({ count, size, shape }) {

package/components/Avatar/index.d.ts

@@ -1,7 +1,7 @@
 import { Avatar as AvatarBase } from './Avatar';
 import { AvatarGroup } from './AvatarGroup';
-export type { AvatarProps, AvatarGroupProps, AvatarSize, AvatarShape, AvatarColor, IndicatorPosition, } from './types';
-export { AVATAR_COLORS } from './types';
+export type { AvatarProps, AvatarGroupProps, AvatarGroupLabels, AvatarLabels, AvatarSize, AvatarShape, AvatarColor, IndicatorPosition, } from './types';
+export { AVATAR_COLORS, defaultAvatarGroupLabels, defaultAvatarLabels } from './types';
 type AvatarCompound = typeof AvatarBase & {
     Group: typeof AvatarGroup;
 };

package/components/Avatar/index.js

@@ -1,6 +1,6 @@
 import { Avatar as AvatarBase } from './Avatar.js';
 import { AvatarGroup } from './AvatarGroup.js';
-export { AVATAR_COLORS } from './types.js';
+export { AVATAR_COLORS, defaultAvatarGroupLabels, defaultAvatarLabels } from './types.js';
 export const Avatar = AvatarBase;
 Avatar.Group = AvatarGroup;
 // Named export for direct import

package/components/Avatar/types.d.ts

@@ -8,6 +8,14 @@ export type IndicatorPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bott
  */
 export type AvatarColor = 'coral' | 'amber' | 'lime' | 'teal' | 'cyan' | 'blue' | 'violet' | 'pink' | 'slate' | 'emerald';
 export declare const AVATAR_COLORS: AvatarColor[];
+/**
+ * Overridable strings for Avatar i18n.
+ */
+export type AvatarLabels = {
+    /** Accessible label when both name and indicator are present. @default `"${name}, ${indicatorLabel}"` */
+    description?: (name: string, indicatorLabel: string) => string;
+};
+export declare const defaultAvatarLabels: Required<AvatarLabels>;
 export type AvatarProps = {
     /** Image source URL */
     src?: string;
@@ -31,9 +39,23 @@ export type AvatarProps = {
      * Has no effect when `name` is not provided.
      */
     tooltip?: boolean;
+    /** Overridable strings for i18n. */
+    labels?: AvatarLabels;
     /** Additional CSS class */
     className?: string;
 };
+/**
+ * Overridable strings for AvatarGroup i18n.
+ */
+export type AvatarGroupLabels = {
+    /** Label when some avatars are hidden. Default: `"${total} users, showing ${visible}"` */
+    group?: (total: number, visible: number) => string;
+    /** Label when all avatars are visible. Default: `"${total} users"` */
+    groupAll?: (total: number) => string;
+    /** Overflow badge label (AT-only). Default: `"${count} more users"` */
+    overflow?: (count: number) => string;
+};
+export declare const defaultAvatarGroupLabels: Required<AvatarGroupLabels>;
 export type AvatarGroupProps = {
     /** Maximum avatars to show before "+N" overflow */
     max?: number;
@@ -48,6 +70,11 @@ export type AvatarGroupProps = {
      * Default: "N users" or "N users, showing M".
      */
     groupLabel?: (total: number, visible: number) => string;
+    /**
+     * Overridable strings for i18n. Coexists with `groupLabel` —
+     * `groupLabel` takes precedence for the group aria-label when provided.
+     */
+    labels?: AvatarGroupLabels;
     /** Children (Avatar components) */
     children: React.ReactNode;
     /** Additional CSS class */

package/components/Avatar/types.js

@@ -10,3 +10,11 @@ export const AVATAR_COLORS = [
     'slate',
     'emerald',
 ];
+export const defaultAvatarLabels = {
+    description: (name, indicatorLabel) => `${name}, ${indicatorLabel}`,
+};
+export const defaultAvatarGroupLabels = {
+    group: (total, visible) => `${total} users, showing ${visible}`,
+    groupAll: (total) => `${total} users`,
+    overflow: (count) => `${count} more users`,
+};

package/components/Button/Button.js

@@ -3,9 +3,11 @@ import React, { forwardRef } from 'react';
 import { cx } from '../../utils/cx.js';
 import { Icon } from '../Icon/index.js';
 import { getSafeRel } from '../../utils/polymorphic.js';
-export const Button = forwardRef(({ label, children, size = 'md', theme = 'primary', variant = 'solid', fullWidth, disabled = false, loading = false, loadingLabel: loadingLabelProp, leftIconName, rightIconName, leftIcon, rightIcon, iconSize: iconSizeProp, className, target, rel, onClick, style, ...rest }, ref) => {
+import { defaultButtonLabels } from './types.js';
+export const Button = forwardRef(({ label, children, size = 'md', theme = 'primary', variant = 'solid', fullWidth, disabled = false, loading = false, loadingLabel: loadingLabelProp, labels: labelsProp, leftIconName, rightIconName, leftIcon, rightIcon, iconSize: iconSizeProp, className, target, rel, onClick, style, ...rest }, ref) => {
     const isLink = typeof rest.href === 'string';
     const isDisabled = disabled || loading;
+    const labels = { ...defaultButtonLabels, ...labelsProp };
     // Auto-scale icon size with button size when not explicitly set
     const iconSizeMap = { xs: 'xs', sm: 'xs', md: 'sm', lg: 'md' };
     const iconSize = iconSizeProp ?? iconSizeMap[size];
@@ -32,7 +34,7 @@ export const Button = forwardRef(({ label, children, size = 'md', theme = 'prima
             }
             onClick?.(e);
         };
-        return (_jsxs("a", { ref: ref, href: isDisabled ? undefined : href, className: classes, "aria-label": loadingLabel, "aria-disabled": isDisabled || undefined, "aria-busy": loading || undefined, tabIndex: isDisabled ? -1 : tabIndex, onClick: handleClick, "data-loading": loading || undefined, target: target, rel: safeRel, style: style, ...anchorRest, children: [content, target === '_blank' && (_jsx("span", { className: "tui-visually-hidden", children: " (opens in new tab)" }))] }));
+        return (_jsxs("a", { ref: ref, href: isDisabled ? undefined : href, className: classes, "aria-label": loadingLabel, "aria-disabled": isDisabled || undefined, "aria-busy": loading || undefined, tabIndex: isDisabled ? -1 : tabIndex, onClick: handleClick, "data-loading": loading || undefined, target: target, rel: safeRel, style: style, ...anchorRest, children: [content, target === '_blank' && (_jsx("span", { className: "tui-visually-hidden", children: labels.newTab }))] }));
     }
     const buttonRest = rest;
     return (_jsx("button", { ref: ref, type: buttonRest.type ?? 'button', className: classes, "aria-label": loadingLabel, disabled: isDisabled, "aria-busy": loading || undefined, onClick: onClick, "data-loading": loading || undefined, style: style, ...buttonRest, children: content }));

package/components/Button/index.d.ts

@@ -1,2 +1,3 @@
 export { Button } from './Button';
-export type { ButtonProps } from './Button';
+export type { ButtonProps, ButtonLabels } from './types';
+export { defaultButtonLabels } from './types';

package/components/Button/index.js

@@ -1 +1,2 @@
 export { Button } from './Button.js';
+export { defaultButtonLabels } from './types.js';

package/components/Button/types.d.ts

@@ -19,6 +19,11 @@ export type Theme = ThemeIntent | 'destructive';
  * - `'link'`: Text-link styling, no background
  */
 export type Variant = 'solid' | 'outline' | 'ghost' | 'link';
+export type ButtonLabels = {
+    /** Label for the "(opens in new tab)" visually-hidden hint on external links. */
+    newTab?: string;
+};
+export declare const defaultButtonLabels: Required<ButtonLabels>;
 type CommonProps = {
     /**
      * Button label text. If provided, renders as the button content.
@@ -68,6 +73,11 @@ type CommonProps = {
      * @default `${label}, loading` (English)
      */
     loadingLabel?: string;
+    /**
+     * Override default English strings for i18n.
+     * Covers strings not already handled by existing props (e.g. `loadingLabel`).
+     */
+    labels?: ButtonLabels;
     /**
      * Link target (for anchor variant).
      */

package/components/Button/types.js

@@ -1 +1,3 @@
-export {};
+export const defaultButtonLabels = {
+    newTab: ' (opens in new tab)',
+};

package/components/Checkbox/Checkbox.js

@@ -8,13 +8,21 @@ import { isDev } from '../../utils/is-dev.js';
 // Checkbox Component
 // =============================================================================
 //
-// Native <input type="checkbox"> with accent-color, reusing tui-inline-choice CSS.
+// Custom <input type="checkbox"> with appearance: none, SVG checkmark/indeterminate
+// icons via background-image, and token-driven colors.
 //
 // Bare (no label): returns <input> directly for Field.Control cloneElement.
 // With label: wraps in <label class="tui-inline-choice">.
 //
-// CSS token API (inherited from input styles):
-//   --tui-input-accent    Accent color for checked state
+// CSS token API (component layer, read via fallback):
+//   --tui-checkbox-accent            Accent color → --tui-input-accent → --tui-theme-primary-base
+//   --tui-checkbox-border            Border color → --tui-color-border
+//   --tui-checkbox-border-invalid    Invalid border → --tui-theme-danger-base
+//   --tui-checkbox-radius            Border radius → --tui-radius-sm
+//   --tui-checkbox-bg                Background → --tui-color-bg
+//   --tui-checkbox-size              Font-size (controls box size via em units)
+//   --tui-checkbox-gap               Gap between checkbox and label (labeled mode)
+//   --tui-checkbox-label-color       Label text colour (labeled mode)
 //
 // =============================================================================
 // Props that should route to the <input>, not the wrapper label
@@ -23,6 +31,7 @@ const INPUT_PROPS = new Set([
     'name',
     'value',
     'aria-describedby',
+    'aria-errormessage',
     'aria-invalid',
     'aria-required',
     'aria-label',
@@ -31,6 +40,9 @@ const INPUT_PROPS = new Set([
     'required',
     'tabIndex',
     'autoFocus',
+    'onClick',
+    'onKeyDown',
+    'onKeyUp',
     'onFocus',
     'onBlur',
 ]);
@@ -67,16 +79,21 @@ export const Checkbox = forwardRef(function Checkbox({ checked: controlledChecke
         }
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
-    const handleChange = () => {
-        // Clicking an indeterminate checkbox produces checked=true (native behaviour)
-        setChecked((prev) => !prev);
+    const handleChange = (e) => {
+        // Use native checked value — clicking an indeterminate checkbox produces
+        // checked=true, which !prev would incorrectly invert to false.
+        setChecked(e.target.checked);
     };
     const isChecked = checked ?? false;
-    // Bare: no label — Field.Control can inject id/aria-* directly
+    // Shared input element — single source of truth for both render paths.
+    // In labeled mode, extraProps contains only INPUT_PROPS; in bare mode,
+    // all rest props go directly on the input.
+    const renderInput = (extraProps, extraClass) => (_jsx("input", { ref: composeRefs(internalRef, externalRef), type: "checkbox", checked: isChecked, disabled: disabled, className: extraClass, "aria-checked": indeterminate && !isChecked ? 'mixed' : undefined, onChange: handleChange, ...extraProps }));
+    // Bare: no label — Field.Control can inject id/aria-* via cloneElement
     if (!label) {
-        return (_jsx("input", { ref: composeRefs(internalRef, externalRef), type: "checkbox", checked: isChecked, disabled: disabled, className: className, "data-indeterminate": indeterminate || undefined, "aria-checked": indeterminate ? 'mixed' : undefined, onChange: handleChange, ...rest }));
+        return renderInput(rest, className);
     }
-    // Split rest props: some go on input, some on wrapper
+    // Labeled: split rest props between input and wrapper
     const inputProps = {};
     const wrapperProps = {};
     for (const [key, val] of Object.entries(rest)) {
@@ -87,6 +104,24 @@ export const Checkbox = forwardRef(function Checkbox({ checked: controlledChecke
             wrapperProps[key] = val;
         }
     }
-    // With label: wrap in tui-inline-choice
-    return (_jsxs("label", { className: cx('tui-inline-choice', disabled && 'is-disabled', className), ...wrapperProps, children: [_jsx("input", { ref: composeRefs(internalRef, externalRef), type: "checkbox", checked: isChecked, disabled: disabled, "data-indeterminate": indeterminate || undefined, "aria-checked": indeterminate ? 'mixed' : undefined, onChange: handleChange, ...inputProps }), _jsx("span", { children: label })] }));
+    // DEV: warn if input-like props leaked to the wrapper
+    if (isDev()) {
+        const suspect = Object.keys(wrapperProps).filter((k) => k.startsWith('aria-') || k.startsWith('on') || k === 'tabIndex');
+        if (suspect.length > 0) {
+            console.warn(`Checkbox: Props [${suspect.join(', ')}] ended up on the <label> wrapper. ` +
+                'Add them to INPUT_PROPS if they belong on the <input>.');
+        }
+        // Warn about dual-labelling conflicts
+        if (inputProps['aria-labelledby']) {
+            console.warn('Checkbox: Both `label` prop and `aria-labelledby` are present. ' +
+                '`aria-labelledby` takes precedence — the `label` prop text will not be the accessible name. ' +
+                'Prefer one labelling mechanism.');
+        }
+        if (inputProps['aria-label']) {
+            console.warn('Checkbox: Both `label` prop and `aria-label` are present. ' +
+                '`aria-label` takes precedence — the visible label text will not be the accessible name.');
+        }
+    }
+    return (_jsxs("label", { className: cx('tui-inline-choice', disabled && 'is-disabled', className), ...wrapperProps, children: [renderInput(inputProps), _jsx("span", { children: label })] }));
 });
+Checkbox.displayName = 'Checkbox';

package/components/Checkbox/types.d.ts

@@ -4,6 +4,15 @@ export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' |
     defaultChecked?: boolean;
     onCheckedChange?: (checked: boolean) => void;
     indeterminate?: boolean;
+    /**
+     * When provided, renders the checkbox inside a `<label>` with this content.
+     * When omitted, renders a bare `<input>` — you must provide an accessible name
+     * via `aria-label`, `aria-labelledby`, or a wrapping `Field.Control` + `Field.Label`.
+     *
+     * @remarks When used inside `Field.Control`, `Field.Label` injects `aria-labelledby`
+     * onto the input. If both `label` and `Field.Label` are present, AT may concatenate
+     * both names. Prefer one labelling mechanism — either `label` prop or `Field.Label`.
+     */
     label?: ReactNode;
     disabled?: boolean;
     className?: string;

package/components/Combobox/Combobox.d.ts

@@ -1,5 +1,5 @@
 import type { ComboboxProps, ComboboxContentProps, ComboboxOptionProps, ComboboxGroupProps, ComboboxLabelProps } from './types';
-declare function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inputValue: controlledInputValue, onInputChange, open: controlledOpen, defaultOpen, onOpenChange, disabled, placeholder, size, openOnFocus, filterMode, onQueryChange, clearable, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, inputClassName, children, }: ComboboxProps): import("react/jsx-runtime").JSX.Element;
+declare function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inputValue: controlledInputValue, onInputChange, open: controlledOpen, defaultOpen, onOpenChange, disabled, placeholder, size, openOnFocus, filterMode, onQueryChange, clearable, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, inputClassName, labels: labelsProp, children, }: ComboboxProps): import("react/jsx-runtime").JSX.Element;
 declare namespace ComboboxRoot {
     var displayName: string;
 }

package/components/Combobox/Combobox.js

@@ -9,13 +9,15 @@ import { hashForId } from '../../utils/hash.js';
 import { composeEventHandlers } from '../../utils/compose-events.js';
 import { Icon } from '../Icon/index.js';
 import { ComboboxActionsContext, ComboboxStateContext, ComboboxContentContext, useComboboxContext, useComboboxContentContext, } from './ComboboxContext.js';
+import { defaultComboboxLabels } from './types.js';
 // =============================================================================
 // Combobox Root
 // =============================================================================
-function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inputValue: controlledInputValue, onInputChange, open: controlledOpen, defaultOpen, onOpenChange, disabled = false, placeholder = '', size = 'md', openOnFocus = true, filterMode = 'always', onQueryChange, clearable = true, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, inputClassName, children, }) {
+function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inputValue: controlledInputValue, onInputChange, open: controlledOpen, defaultOpen, onOpenChange, disabled = false, placeholder = '', size = 'md', openOnFocus = true, filterMode = 'always', onQueryChange, clearable = true, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, inputClassName, labels: labelsProp, children, }) {
+    const labels = { ...defaultComboboxLabels, ...labelsProp };
     // Controlled/uncontrolled value (initialize from defaultValue)
     const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
-    const isValueControlled = controlledValue !== undefined;
+    const isValueControlled = useRef(controlledValue !== undefined).current;
     const value = isValueControlled ? controlledValue : uncontrolledValue;
     // Controlled/uncontrolled inputValue
     const [uncontrolledInputValue, setUncontrolledInputValue] = useState('');
@@ -41,6 +43,9 @@ function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inp
     // 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);
+    openRef.current = open;
     // IDs
     const baseId = useId();
     const inputId = `${baseId}-input`;
@@ -153,9 +158,22 @@ function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inp
         setRegistryVersion((v) => v + 1);
     }, []);
     const unregisterOption = useCallback((optionValue) => {
+        // When the dropdown closes, options unmount and call unregister in cleanup.
+        // Skip the delete to preserve the registry — filtering and input display
+        // depend on it while closed. 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]);
     // Active option ID for aria-activedescendant (hash-based for stability during filtering)
     const activeOptionId = activeIndex >= 0 && orderedOptions[activeIndex]
         ? `${listboxId}-opt-${hashForId(toKey(orderedOptions[activeIndex].value))}`
@@ -291,6 +309,7 @@ function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inp
     // Handle clear button - clears both input text and selected value
     const handleClear = useCallback((e) => {
         e.preventDefault(); // Keep focus in input
+        e.stopPropagation(); // Don't open dropdown
         setInputValue('');
         clearValue();
         inputRef.current?.focus();
@@ -365,7 +384,7 @@ function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inp
     return (_jsx(ComboboxActionsContext.Provider, { value: actionsValue, children: _jsx(ComboboxStateContext.Provider, { value: stateValue, children: _jsxs("div", { className: "tui-combobox", children: [_jsxs("div", { className: "tui-combobox__input-wrapper", children: [_jsx("input", { ref: (node) => {
                                     inputRef.current = node;
                                     refs.setReference(node);
-                                }, type: "text", id: inputId, className: cx('tui-combobox__input', size !== 'md' && `is-size-${size}`, inputClassName), role: "combobox", "aria-expanded": open, "aria-controls": listboxId, "aria-autocomplete": "list", "aria-activedescendant": activeOptionId, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, placeholder: placeholder, value: inputValue, autoComplete: "off", ...referenceProps, onChange: handleInputChange }), clearable && inputValue && !disabled && (_jsx("span", { className: "tui-combobox__clear", onPointerDown: handleClear, "aria-hidden": "true", children: _jsx(Icon, { name: "system/close", size: "sm" }) })), _jsx("span", { className: "tui-combobox__icon", "aria-hidden": "true", children: _jsx(Icon, { name: "system/chevron-down", size: "sm" }) })] }), children] }) }) }));
+                                }, type: "text", id: inputId, className: cx('tui-combobox__input', size !== 'md' && `is-size-${size}`, inputClassName), role: "combobox", "aria-expanded": open, "aria-controls": listboxId, "aria-autocomplete": "list", "aria-activedescendant": activeOptionId, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, placeholder: placeholder, value: inputValue, autoComplete: "off", ...referenceProps, onChange: handleInputChange }), clearable && inputValue && !disabled && (_jsx("button", { type: "button", className: "tui-combobox__clear", onClick: handleClear, onMouseDown: (e) => e.preventDefault(), "aria-label": labels.clear, tabIndex: -1, children: _jsx(Icon, { name: "system/close", size: "sm" }) })), _jsx("span", { className: "tui-combobox__icon", "aria-hidden": "true", children: _jsx(Icon, { name: "system/chevron-down", size: "sm" }) })] }), children] }) }) }));
 }
 ComboboxRoot.displayName = 'Combobox';
 // =============================================================================
@@ -373,6 +392,12 @@ ComboboxRoot.displayName = 'Combobox';
 // =============================================================================
 function ComboboxContentComponent({ className, children }) {
     const { open, listboxId, inputId, refs, floatingStyles, getFloatingProps, listRef, activeIndex, orderedOptions, } = useComboboxContext();
+    // Track whether dropdown has ever been opened. Before first open, mount
+    // children in a hidden div for option registration (defaultValue resolution).
+    // After first open, only mount children when open (in portal).
+    const hasEverOpened = useRef(false);
+    if (open)
+        hasEverOpened.current = true;
     const portalRoot = getPortalRootFor(refs.reference.current);
     const contentContext = useMemo(() => ({
         listRef,
@@ -380,7 +405,7 @@ function ComboboxContentComponent({ className, children }) {
         orderedOptions,
     }), [listRef, activeIndex, orderedOptions]);
     // Always render for option registration
-    return (_jsxs(_Fragment, { children: [!open && (_jsx("div", { style: { display: 'none' }, "aria-hidden": "true", children: _jsx(ComboboxContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": inputId, className: cx('tui-combobox__content', className), style: {
+    return (_jsxs(_Fragment, { children: [!open && !hasEverOpened.current && (_jsx("div", { id: listboxId, role: "listbox", style: { display: 'none' }, "aria-hidden": "true", children: _jsx(ComboboxContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": inputId, className: cx('tui-combobox__content', className), style: {
                         ...floatingStyles,
                         minWidth: refs.reference.current?.offsetWidth,
                         pointerEvents: 'auto',
@@ -395,9 +420,11 @@ function ComboboxOptionComponent({ value: optionValue, disabled = false, textVal
     const { listRef, activeIndex, orderedOptions } = useComboboxContentContext();
     const ref = useRef(null);
     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(`Combobox.Option with value="${optionValue}" has no textValue. Provide textValue prop when children is not a string.`);
         }
     }, [textValue, optionValue]);
@@ -440,7 +467,16 @@ ComboboxOptionComponent.displayName = 'Combobox.Option';
 // =============================================================================
 function ComboboxGroupComponent({ className, children }) {
     const groupId = useId();
-    return (_jsx("div", { role: "group", "aria-labelledby": `${groupId}-label`, className: cx('tui-combobox__group', className), children: _jsx(ComboboxGroupContext.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-combobox__group', className), children: _jsx(ComboboxGroupContext.Provider, { value: { groupId }, children: children }) }));
 }
 ComboboxGroupComponent.displayName = 'Combobox.Group';
 const ComboboxGroupContext = React.createContext(null);
@@ -449,6 +485,13 @@ const ComboboxGroupContext = React.createContext(null);
 // =============================================================================
 function ComboboxLabelComponent({ className, children }) {
     const groupContext = React.useContext(ComboboxGroupContext);
+    const warnedRef = useRef(false);
+    useEffect(() => {
+        if (isDev() && !groupContext && !warnedRef.current) {
+            warnedRef.current = true;
+            console.warn('Combobox.Label should be used inside Combobox.Group for accessibility.');
+        }
+    }, [groupContext]);
     return (_jsx("div", { id: groupContext ? `${groupContext.groupId}-label` : undefined, className: cx('tui-combobox__label', className), children: children }));
 }
 ComboboxLabelComponent.displayName = 'Combobox.Label';

package/components/Combobox/index.d.ts

@@ -1,2 +1,3 @@
 export { Combobox, ComboboxContent, ComboboxOption, ComboboxGroup, ComboboxLabel, useCombobox, } from './Combobox';
-export type { ComboboxProps, ComboboxContentProps, ComboboxOptionProps, ComboboxGroupProps, ComboboxLabelProps, FilterMode as ComboboxFilterMode, RegisteredOption as ComboboxRegisteredOption, } from './types';
+export type { ComboboxProps, ComboboxContentProps, ComboboxOptionProps, ComboboxGroupProps, ComboboxLabelProps, ComboboxLabels, FilterMode as ComboboxFilterMode, RegisteredOption as ComboboxRegisteredOption, } from './types';
+export { defaultComboboxLabels } from './types';

package/components/Combobox/index.js

@@ -1 +1,2 @@
 export { Combobox, ComboboxContent, ComboboxOption, ComboboxGroup, ComboboxLabel, useCombobox, } from './Combobox.js';
+export { defaultComboboxLabels } from './types.js';

package/components/Combobox/types.d.ts

@@ -2,6 +2,11 @@ import type { FloatingContext, 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';
+export type ComboboxLabels = {
+    /** Label for the clear button. */
+    clear?: string;
+};
+export declare const defaultComboboxLabels: Required<ComboboxLabels>;
 /**
  * Controls when filtering should be active.
  * - 'always': Consumer filters whenever inputValue changes (default)
@@ -96,6 +101,10 @@ export type ComboboxProps = {
      * Use for utilities like `tui-input-reset` that must target the input itself.
      */
     inputClassName?: string;
+    /**
+     * Override default English strings for i18n.
+     */
+    labels?: ComboboxLabels;
     children: React.ReactNode;
 };
 export type ComboboxContentProps = {

package/components/Combobox/types.js

@@ -1 +1,3 @@
-export {};
+export const defaultComboboxLabels = {
+    clear: 'Clear selection',
+};

package/components/Dropdown/Dropdown.d.ts

@@ -7,7 +7,7 @@ declare function DropdownTriggerComponent({ asChild, children }: DropdownTrigger
 declare namespace DropdownTriggerComponent {
     var displayName: string;
 }
-declare function DropdownContentComponent({ side, align, sideOffset, className, style, children, }: DropdownContentProps): import("react/jsx-runtime").JSX.Element | null;
+declare function DropdownContentComponent(props: DropdownContentProps): import("react/jsx-runtime").JSX.Element | null;
 declare namespace DropdownContentComponent {
     var displayName: string;
 }