@tangible/ui 0.0.6 → 0.0.8

package/components/Field/Field.js

@@ -1,20 +1,29 @@
 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,
         helperTextId,
         errorId,
         hasError: error,
         required,
         disabled,
-    }), [controlId, 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 }) }));
 });
@@ -22,16 +31,20 @@ export const Field = forwardRef(function Field({ error = false, required = false
 // Field.Label
 // =============================================================================
 function FieldLabel({ hidden = false, className, children, ...rest }) {
-    const { controlId, 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", { 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, 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');
@@ -48,10 +61,28 @@ function FieldControl({ children }) {
         describedByParts.push(errorId);
     }
     const describedBy = describedByParts.join(' ');
+    // 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, {
         id: controlId,
+        'aria-labelledby': labelledBy,
         'aria-describedby': describedBy,
         'aria-invalid': hasError ? 'true' : undefined,
         'aria-required': required ? 'true' : undefined,

package/components/Field/FieldContext.d.ts

@@ -1,6 +1,16 @@
+/**
+ * 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;
+    /** ID for the label element (for aria-labelledby on non-labelable controls) */
+    labelId: string;
     /** ID for helper text (for aria-describedby) */
     helperTextId: string;
     /** ID for error message (for aria-describedby) */
@@ -11,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/MoveHandle/MoveHandle.js

@@ -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;

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,15 +6,17 @@ 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
@@ -273,6 +275,7 @@ function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultVal
         maxChips,
         max,
         size,
+        labels,
         // ARIA IDs (stable)
         triggerId,
         listboxId,
@@ -300,6 +303,7 @@ function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultVal
         maxChips,
         max,
         size,
+        labels,
         // IDs are stable (from useId)
         triggerId,
         listboxId,
@@ -356,7 +360,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 +426,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 +448,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 +482,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 +507,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) => {
@@ -532,7 +534,7 @@ function MultiSelectContentComponent({ className, children }) {
         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 && (_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 +550,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 +597,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 +615,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';

package/components/MultiSelect/types.d.ts

@@ -11,6 +11,34 @@ export type MultiSelectValue = Array<string | number>;
  * Display mode for the trigger.
  */
 export type DisplayMode = 'count' | 'chips';
+/**
+ * Overridable label strings for i18n.
+ *
+ * Static strings use plain `string`, dynamic strings use function signatures.
+ * All keys are optional — defaults are English.
+ */
+export type MultiSelectLabels = {
+    /**
+     * Trigger text in count display mode.
+     * @default (count) => `${count} selected`
+     */
+    selected?: (count: number) => string;
+    /**
+     * Overflow badge text in chips display mode.
+     * @default (count) => `+${count} more`
+     */
+    more?: (count: number) => string;
+    /**
+     * Screen reader status announcement. Called on every selection change.
+     * When `max` is defined and `count >= max`, include a "maximum reached" note.
+     * @default (count, max) => count === 0 ? '0 items selected' : `${count} item${count === 1 ? '' : 's'} selected${max !== undefined && count >= max ? `. Maximum of ${max} reached` : ''}`
+     */
+    status?: (count: number, max?: number) => string;
+};
+/**
+ * Default English labels. Exported for reference or spread-override patterns.
+ */
+export declare const defaultMultiSelectLabels: Required<MultiSelectLabels>;
 export type MultiSelectProps = {
     /**
      * Control size.
@@ -73,6 +101,11 @@ export type MultiSelectProps = {
      * Callback when max selections is reached.
      */
     onMaxReached?: () => void;
+    /**
+     * Override internal display and screen reader strings for i18n.
+     * All keys are optional — omitted keys use English defaults.
+     */
+    labels?: MultiSelectLabels;
     /**
      * Accessible name for the select.
      */
@@ -169,6 +202,7 @@ export type MultiSelectActionsContextValue = {
     maxChips: number;
     max: number | undefined;
     size: SizeStandard;
+    labels: Required<MultiSelectLabels>;
     triggerId: string;
     listboxId: string;
     ariaLabel?: string;

package/components/MultiSelect/types.js

@@ -1,3 +1,13 @@
 import { toKey } from '../../utils/value-key.js';
 // Re-export shared value-key types so existing consumers don't break
 export { toKey };
+/**
+ * Default English labels. Exported for reference or spread-override patterns.
+ */
+export const defaultMultiSelectLabels = {
+    selected: (count) => `${count} selected`,
+    more: (count) => `+${count} more`,
+    status: (count, max) => count === 0
+        ? '0 items selected'
+        : `${count} item${count === 1 ? '' : 's'} selected${max !== undefined && count >= max ? `. Maximum of ${max} reached` : ''}`,
+};

package/components/Pager/Pager.d.ts

@@ -1,3 +1,4 @@
+import { type PagerLabels } from './types';
 export type PagerMode = 'simple' | 'ends' | 'full' | 'smart';
 export type PagerProps = {
     /** Current page (1-indexed) */
@@ -22,5 +23,10 @@ export type PagerProps = {
     hidden?: boolean;
     /** Additional class name */
     className?: string;
+    /**
+     * Overridable label strings for i18n.
+     * All keys are optional — defaults are English.
+     */
+    labels?: PagerLabels;
 };
-export declare function Pager({ currentPage, totalPages, onPageChange, pageSize, pageSizeOptions, onPageSizeChange, mode, maxNumbers, navStyle, hidden, className, }: PagerProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function Pager({ currentPage, totalPages, onPageChange, pageSize, pageSizeOptions, onPageSizeChange, mode, maxNumbers, navStyle, hidden, className, labels: labelsProp, }: PagerProps): import("react/jsx-runtime").JSX.Element | null;

package/components/Pager/Pager.js

@@ -3,6 +3,7 @@ import * as React from 'react';
 import { cx } from '../../utils/cx.js';
 import { Button } from '../Button/index.js';
 import { IconButton } from '../IconButton/index.js';
+import { defaultPagerLabels } from './types.js';
 // =============================================================================
 // Pager Component
 // =============================================================================
@@ -121,7 +122,8 @@ function buildItems(total, current, mode, maxNumbers) {
 // -----------------------------------------------------------------------------
 // Component
 // -----------------------------------------------------------------------------
-export function Pager({ currentPage, totalPages, onPageChange, pageSize, pageSizeOptions, onPageSizeChange, mode = 'smart', maxNumbers = DEFAULT_MAX_SLOTS, navStyle = 'text', hidden = false, className, }) {
+export function Pager({ currentPage, totalPages, onPageChange, pageSize, pageSizeOptions, onPageSizeChange, mode = 'smart', maxNumbers = DEFAULT_MAX_SLOTS, navStyle = 'text', hidden = false, className, labels: labelsProp, }) {
+    const labels = React.useMemo(() => ({ ...defaultPagerLabels, ...labelsProp }), [labelsProp]);
     // Normalise inputs
     const total = Math.max(1, totalPages);
     const current = Math.min(total, Math.max(1, currentPage));
@@ -130,13 +132,13 @@ export function Pager({ currentPage, totalPages, onPageChange, pageSize, pageSiz
     if (hidden)
         return null;
     const showPageSizeSelector = pageSizeOptions && pageSizeOptions.length > 0 && onPageSizeChange;
-    return (_jsxs("div", { className: cx('tui-pager', className), children: [_jsx("nav", { className: "tui-pager__nav", "aria-label": "Pagination", children: items.map((it, i) => {
+    return (_jsxs("div", { className: cx('tui-pager', className), children: [_jsx("nav", { className: "tui-pager__nav", "aria-label": labels.navigation, children: items.map((it, i) => {
                     if (it.kind === 'ellipsis') {
                         return (_jsx("span", { className: "tui-pager__ellipsis", "aria-hidden": true, children: "..." }, `e${i}`));
                     }
                     if (it.kind === 'prev' || it.kind === 'next') {
                         const isPrev = it.kind === 'prev';
-                        const label = isPrev ? 'Previous page' : 'Next page';
+                        const label = isPrev ? labels.previous : labels.next;
                         if (navStyle === 'icon') {
                             return (_jsx(IconButton, { icon: isPrev ? 'system/chevron-left' : 'system/chevron-right', label: label, showTooltip: true, size: "sm", theme: "secondary", variant: "outline", disabled: it.disabled, onClick: () => go(it.page), className: "tui-pager__item" }, it.kind));
                         }
@@ -144,8 +146,8 @@ export function Pager({ currentPage, totalPages, onPageChange, pageSize, pageSiz
                     }
                     // Page number
                     if (it.kind === 'page') {
-                        return (_jsx(Button, { size: "sm", theme: it.current ? 'primary' : 'secondary', variant: it.current ? 'solid' : 'outline', "aria-current": it.current ? 'page' : undefined, "aria-label": `Page ${it.page}`, onClick: () => go(it.page), className: "tui-pager__item", children: it.page }, it.page));
+                        return (_jsx(Button, { size: "sm", theme: it.current ? 'primary' : 'secondary', variant: it.current ? 'solid' : 'outline', "aria-current": it.current ? 'page' : undefined, "aria-label": labels.page(it.page), onClick: () => go(it.page), className: "tui-pager__item", children: it.page }, it.page));
                     }
                     return null;
-                }) }), _jsxs("div", { className: "tui-pager__info", children: [_jsxs("span", { children: ["Page ", _jsx("strong", { children: current }), " of ", total] }), showPageSizeSelector && (_jsxs("label", { className: "tui-pager__page-size-label", children: [_jsx("span", { className: "tui-visually-hidden", children: "Items per page" }), _jsx("select", { className: "tui-input", value: pageSize, onChange: (e) => onPageSizeChange(Number(e.target.value)), children: pageSizeOptions.map((s) => (_jsxs("option", { value: s, children: [s, " / page"] }, s))) })] }))] })] }));
+                }) }), _jsxs("div", { className: "tui-pager__info", children: [_jsx("span", { children: labels.pageStatus(current, total) }), showPageSizeSelector && (_jsxs("label", { className: "tui-pager__page-size-label", children: [_jsx("span", { className: "tui-visually-hidden", children: labels.itemsPerPage }), _jsx("select", { className: "tui-input", value: pageSize, onChange: (e) => onPageSizeChange(Number(e.target.value)), children: pageSizeOptions.map((s) => (_jsx("option", { value: s, children: labels.perPage(s) }, s))) })] }))] })] }));
 }

package/components/Pager/index.d.ts

@@ -1,2 +1,4 @@
 export { Pager } from './Pager';
 export type { PagerProps, PagerMode } from './Pager';
+export { defaultPagerLabels } from './types';
+export type { PagerLabels } from './types';

package/components/Pager/index.js

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

package/components/Pager/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Overridable label strings for i18n.
+ *
+ * Static strings use plain `string`, dynamic strings use function signatures.
+ * All keys are optional — defaults are English.
+ */
+export type PagerLabels = {
+    /** Label for previous page button (aria-label on icon style, aria-label on text style).
+     * @default "Previous page"
+     */
+    previous?: string;
+    /** Label for next page button.
+     * @default "Next page"
+     */
+    next?: string;
+    /** Label for individual page buttons.
+     * @default (n) => `Page ${n}`
+     */
+    page?: (n: number) => string;
+    /** aria-label for the nav landmark.
+     * @default "Pagination"
+     */
+    navigation?: string;
+    /** "Page X of Y" status text.
+     * @default (current, total) => `Page ${current} of ${total}`
+     */
+    pageStatus?: (current: number, total: number) => string;
+    /** Visually-hidden label for the page size selector.
+     * @default "Items per page"
+     */
+    itemsPerPage?: string;
+    /** Option text in the page size selector.
+     * @default (n) => `${n} / page`
+     */
+    perPage?: (n: number) => string;
+};
+export declare const defaultPagerLabels: Required<PagerLabels>;

package/components/Pager/types.js

@@ -0,0 +1,12 @@
+// =============================================================================
+// Pager Types
+// =============================================================================
+export const defaultPagerLabels = {
+    previous: 'Previous page',
+    next: 'Next page',
+    page: (n) => `Page ${n}`,
+    navigation: 'Pagination',
+    pageStatus: (current, total) => `Page ${current} of ${total}`,
+    itemsPerPage: 'Items per page',
+    perPage: (n) => `${n} / page`,
+};

package/components/Radio/Radio.d.ts

@@ -1,2 +1,6 @@
 import type { RadioProps } from './types';
+/**
+ * Ref targets the inner `<button role="radio">`, not the outer wrapper `<div>`.
+ * This is intentional — roving tabindex and focus management operate on the button.
+ */
 export declare const Radio: import("react").ForwardRefExoticComponent<RadioProps & import("react").RefAttributes<HTMLButtonElement>>;

package/components/Radio/Radio.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useCallback, useEffect, useRef } from 'react';
+import { forwardRef, useCallback, useEffect, useId, useRef } from 'react';
 import { cx } from '../../utils/cx.js';
 import { composeRefs } from '../../utils/compose-refs.js';
 import { toKey } from '../../utils/value-key.js';
@@ -14,8 +14,14 @@ import { useRadioGroupContext } from './RadioGroupContext.js';
 // Arrow keys in the group move focus AND select.
 //
 // =============================================================================
-export const Radio = forwardRef(function Radio({ value, label, disabled = false, className }, externalRef) {
+/**
+ * Ref targets the inner `<button role="radio">`, not the outer wrapper `<div>`.
+ * This is intentional — roving tabindex and focus management operate on the button.
+ */
+export const Radio = forwardRef(function Radio({ value, label, description, disabled = false, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, }, externalRef) {
     const { selectedValue, focusableValue, rootDisabled, registerItem, unregisterItem, onSelect, } = useRadioGroupContext();
+    const id = useId();
+    const descriptionId = `${id}-desc`;
     const isSelected = selectedValue !== undefined && toKey(selectedValue) === toKey(value);
     const isDisabled = rootDisabled || disabled;
     const isFocusable = focusableValue !== undefined && toKey(focusableValue) === toKey(value);
@@ -24,8 +30,8 @@ export const Radio = forwardRef(function Radio({ value, label, disabled = false,
     useEffect(() => {
         if (hasWarnedRef.current)
             return;
-        if (isDev() && !label) {
-            console.warn('Radio: Missing accessible name. Provide a label prop.');
+        if (isDev() && !label && !ariaLabel && !ariaLabelledBy) {
+            console.warn('Radio: Missing accessible name. Provide a label, aria-label, or aria-labelledby prop.');
             hasWarnedRef.current = true;
         }
         // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -45,6 +51,10 @@ export const Radio = forwardRef(function Radio({ value, label, disabled = false,
             return;
         onSelect(value);
     };
-    return (_jsxs("button", { ref: composeRefs(callbackRef, externalRef), type: "button", role: "radio", className: cx('tui-radio', className), "aria-checked": isSelected, disabled: isDisabled, tabIndex: isFocusable ? 0 : -1, onClick: handleClick, children: [_jsx("span", { className: "tui-radio__indicator", "aria-hidden": "true" }), label && _jsx("span", { className: "tui-radio__label", children: label })] }));
+    const hasExpandedContent = !!(description || children);
+    return (_jsxs("div", { className: cx('tui-radio', hasExpandedContent && 'has-content', className), children: [_jsxs("button", { ref: composeRefs(callbackRef, externalRef), type: "button", role: "radio", className: "tui-radio__control", "aria-checked": isSelected, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": description ? descriptionId : undefined, 
+                // Item-level disabled: native disabled (removes from focus cycle).
+                // Group-level disabled: aria-disabled (preserves AT group context).
+                disabled: disabled || undefined, "aria-disabled": rootDisabled || undefined, tabIndex: isFocusable ? 0 : -1, onClick: handleClick, children: [_jsx("span", { className: "tui-radio__indicator", "aria-hidden": "true" }), label && _jsx("span", { className: "tui-radio__label", children: label })] }), hasExpandedContent && (_jsxs("div", { className: "tui-radio__body", children: [description && (_jsx("p", { id: descriptionId, className: "tui-radio__description", children: description })), children] }))] }));
 });
 Radio.displayName = 'Radio';

package/components/Radio/RadioGroup.d.ts

@@ -1,2 +1,2 @@
 import type { RadioGroupProps } from './types';
-export declare function RadioGroup({ value: controlledValue, defaultValue, onValueChange, disabled, orientation, loop, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, }: RadioGroupProps): import("react/jsx-runtime").JSX.Element;
+export declare function RadioGroup({ value: controlledValue, defaultValue, onValueChange, disabled, orientation, loop, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-required': ariaRequired, className, children, }: RadioGroupProps): import("react/jsx-runtime").JSX.Element;

package/components/Radio/RadioGroup.js

@@ -17,7 +17,7 @@ import { isDev } from '../../utils/is-dev.js';
 //   --tui-radio-accent    Accent color for selected state
 //
 // =============================================================================
-export function RadioGroup({ value: controlledValue, defaultValue, onValueChange, disabled = false, orientation = 'vertical', loop = true, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, }) {
+export function RadioGroup({ value: controlledValue, defaultValue, onValueChange, disabled = false, orientation = 'vertical', loop = true, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, 'aria-required': ariaRequired, className, children, }) {
     const [selectedValue, setSelectedValue] = useControllableState({
         value: controlledValue,
         defaultValue,
@@ -50,5 +50,5 @@ export function RadioGroup({ value: controlledValue, defaultValue, onValueChange
         unregisterItem,
         onSelect,
     }), [selectedValue, focusableValue, disabled, orientation, registerItem, unregisterItem, onSelect]);
-    return (_jsx(RadioGroupContext.Provider, { value: contextValue, children: _jsx("div", { role: "radiogroup", className: cx('tui-radio-group', orientation === 'horizontal' && 'is-horizontal', className), "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-disabled": disabled || undefined, "aria-orientation": orientation === 'horizontal' ? 'horizontal' : undefined, onKeyDown: handleKeyDown, children: children }) }));
+    return (_jsx(RadioGroupContext.Provider, { value: contextValue, children: _jsx("div", { role: "radiogroup", className: cx('tui-radio-group', orientation === 'horizontal' && 'is-horizontal', className), "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, "aria-disabled": disabled || undefined, "aria-orientation": orientation, onKeyDown: handleKeyDown, children: children }) }));
 }