@tangible/ui 0.0.3 → 0.0.5

package/README.md

@@ -6,10 +6,12 @@ Design system for Tangible WordPress plugins. React components + CSS tokens + ut
 
 ## Components
 
-- **Primitives:** Button, Chip, Icon, IconButton, Progress, Rating, Tooltip
-- **Layout:** Accordion, Card, Modal, Notice, DataTable
-- **Composites:** Chips (multi-select chip group), StepIndicator
-- **Form Inputs:** Text, textarea, select, checkbox, radio, toggle, file (CSS-only)
+- **Primitives:** Button, Chip, ChipGroup, Icon, IconButton, Progress, Rating, Tooltip
+- **Layout:** Accordion, Card, Modal, Notice, Sidebar, Tabs, Toolbar
+- **Data:** DataTable, StepList, StepIndicator, Pager
+- **Form Controls:** Select, MultiSelect, Combobox, TextInput, Textarea, Checkbox, Switch, Radio
+- **Composites:** Avatar, Dropdown, MoveHandle, OverlapStack, SegmentedControl, Field
+- **CSS-only Inputs:** Text, textarea, select, checkbox, radio, toggle, file
 
 ## Getting Started
 
@@ -26,9 +28,9 @@ npm install @tangible/ui
 import '@tangible/ui/styles';
 ```
 
-Or in SCSS:
-```scss
-@use '@tangible/ui/styles/scss';
+Or for WordPress contexts (no CSS layers):
+```tsx
+import '@tangible/ui/styles/unlayered';
 ```
 
 ### Wrap your app
@@ -45,6 +47,8 @@ function App() {
 }
 ```
 
+Dark mode via `data-theme="dark"` on the wrapper.
+
 ### Use components
 
 ```tsx
@@ -82,11 +86,13 @@ npm run storybook   # Dev server on port 6006
 ## Commands
 
 ```bash
-npm run storybook      # Dev server
-npm run build:lib      # Build library (outputs to publish/)
-npm run lint           # ESLint
-npm run test           # Unit tests
-npm run test:storybook # Story tests (requires Playwright)
+npm run storybook          # Dev server
+npm run build:lib          # Build library (outputs to publish/)
+npm run lint               # ESLint
+npm run test               # Unit tests (vitest, jsdom)
+npm run test:storybook     # Story + a11y tests (vitest, Playwright chromium)
+npm run test:visual        # Visual regression (Playwright)
+npm run test:visual:update # Regenerate visual baselines
 ```
 
 ## Documentation
@@ -94,7 +100,9 @@ npm run test:storybook # Story tests (requires Playwright)
 - `CLAUDE.md` — Development guide (architecture, patterns, conventions)
 - `CONTEXT.md` — Project background and LMS requirements
 - `TIMELINE.md` — Development roadmap (Jan–Mar 2026)
+- `TESTING.md` — Testing strategy and infrastructure
+- `AGENTS.md` — Quality gate agent configurations
 
 ## Status
 
-Under active development for Course Viewer (LMS) and Quiz modules. Component APIs are stabilising but may change.
+Under active development for Course Builder (LMS) and Quiz modules. Component APIs are stabilising but may change before 1.0.

package/components/Accordion/Accordion.d.ts

@@ -10,11 +10,11 @@ declare function AccordionItem({ value, disabled, headingLevel, children, classN
 declare namespace AccordionItem {
     var displayName: string;
 }
-declare function AccordionTrigger({ children, className }: AccordionTriggerProps): import("react/jsx-runtime").JSX.Element;
+declare function AccordionTrigger({ asChild, 'aria-label': ariaLabel, children, className }: AccordionTriggerProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AccordionTrigger {
     var displayName: string;
 }
-declare function AccordionPanel({ children, className }: AccordionPanelProps): import("react/jsx-runtime").JSX.Element;
+declare function AccordionPanel({ landmark, children, className }: AccordionPanelProps): import("react/jsx-runtime").JSX.Element;
 declare namespace AccordionPanel {
     var displayName: string;
 }

package/components/Accordion/Accordion.js

@@ -1,10 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { useCallback, useId, useMemo, useRef, useState } from 'react';
+import React, { cloneElement, isValidElement, useCallback, useId, useMemo, useRef, useState } from 'react';
 import { cx } from '../../utils/cx.js';
+import { composeRefs } from '../../utils/compose-refs.js';
+import { mergeProps } from '../../utils/merge-props.js';
 import { Icon } from '../Icon/index.js';
 import { AccordionContext, AccordionItemContext, useAccordionContext, useAccordionItemContext } from './AccordionContext.js';
 function AccordionRoot(props) {
-    const { type, children, className } = props;
+    const { type, variant = 'card', children, className } = props;
     // Track trigger refs for keyboard navigation
     const triggersRef = useRef(new Map());
     const registerTrigger = useCallback((value, element) => {
@@ -18,11 +20,11 @@ function AccordionRoot(props) {
     const getTriggers = useCallback(() => triggersRef.current, []);
     // State management differs by type
     if (type === 'single') {
-        return (_jsx(AccordionSingle, { ...props, registerTrigger: registerTrigger, getTriggers: getTriggers, className: className, children: children }));
+        return (_jsx(AccordionSingle, { ...props, variant: variant, registerTrigger: registerTrigger, getTriggers: getTriggers, className: className, children: children }));
     }
-    return (_jsx(AccordionMultiple, { ...props, registerTrigger: registerTrigger, getTriggers: getTriggers, className: className, children: children }));
+    return (_jsx(AccordionMultiple, { ...props, variant: variant, registerTrigger: registerTrigger, getTriggers: getTriggers, className: className, children: children }));
 }
-function AccordionSingle({ value: controlledValue, defaultValue, onValueChange, collapsible = false, children, className, registerTrigger, getTriggers, }) {
+function AccordionSingle({ value: controlledValue, defaultValue, onValueChange, collapsible = false, variant, children, className, registerTrigger, getTriggers, }) {
     const [internalValue, setInternalValue] = useState(defaultValue);
     const isControlled = controlledValue !== undefined;
     const currentValue = isControlled ? controlledValue : internalValue;
@@ -37,6 +39,8 @@ function AccordionSingle({ value: controlledValue, defaultValue, onValueChange,
             // Opening new item
             newValue = itemValue;
         }
+        if (newValue === currentValue)
+            return;
         if (!isControlled) {
             setInternalValue(newValue);
         }
@@ -50,9 +54,9 @@ function AccordionSingle({ value: controlledValue, defaultValue, onValueChange,
         registerTrigger,
         getTriggers,
     }), [collapsible, isOpen, toggle, registerTrigger, getTriggers]);
-    return (_jsx(AccordionContext.Provider, { value: contextValue, children: _jsx("div", { className: cx('tui-accordion', className), "data-type": "single", children: children }) }));
+    return (_jsx(AccordionContext.Provider, { value: contextValue, children: _jsx("div", { className: cx('tui-accordion', `is-variant-${variant}`, className), "data-type": "single", children: children }) }));
 }
-function AccordionMultiple({ value: controlledValue, defaultValue, onValueChange, children, className, registerTrigger, getTriggers, }) {
+function AccordionMultiple({ value: controlledValue, defaultValue, onValueChange, variant, children, className, registerTrigger, getTriggers, }) {
     const [internalValue, setInternalValue] = useState(defaultValue ?? []);
     const isControlled = controlledValue !== undefined;
     const currentValue = isControlled ? controlledValue : internalValue;
@@ -74,7 +78,7 @@ function AccordionMultiple({ value: controlledValue, defaultValue, onValueChange
         registerTrigger,
         getTriggers,
     }), [isOpen, toggle, registerTrigger, getTriggers]);
-    return (_jsx(AccordionContext.Provider, { value: contextValue, children: _jsx("div", { className: cx('tui-accordion', className), "data-type": "multiple", children: children }) }));
+    return (_jsx(AccordionContext.Provider, { value: contextValue, children: _jsx("div", { className: cx('tui-accordion', `is-variant-${variant}`, className), "data-type": "multiple", children: children }) }));
 }
 // =============================================================================
 // Accordion Item
@@ -99,21 +103,49 @@ function AccordionItem({ value, disabled = false, headingLevel, children, classN
 // =============================================================================
 // Accordion Trigger
 // =============================================================================
-function AccordionTrigger({ children, className }) {
+function AccordionTrigger({ asChild = false, 'aria-label': ariaLabel, children, className }) {
     const { toggle, registerTrigger, getTriggers } = useAccordionContext();
     const { value, disabled, headingLevel, triggerId, panelId, isOpen } = useAccordionItemContext();
-    const buttonRef = useRef(null);
+    const triggerRef = useRef(null);
     // Register trigger for keyboard navigation
     React.useEffect(() => {
-        registerTrigger(value, buttonRef.current);
+        registerTrigger(value, triggerRef.current);
         return () => registerTrigger(value, null);
     }, [value, registerTrigger]);
-    const handleClick = () => {
-        if (!disabled) {
-            toggle(value);
+    const handleClick = (event) => {
+        if (disabled)
+            return;
+        // In asChild mode, the trigger is a container with nested interactive elements.
+        // Only toggle when the click is on the trigger itself or passive content (text,
+        // chips, icons) — not when it originates from a nested button, link, or input.
+        if (asChild) {
+            const target = event.target;
+            const currentTarget = event.currentTarget;
+            if (target !== currentTarget) {
+                const interactive = target.closest('button, a, input, select, textarea, [role="button"], [role="link"]');
+                if (interactive && interactive !== currentTarget && currentTarget.contains(interactive)) {
+                    return;
+                }
+            }
         }
+        toggle(value);
     };
     const handleKeyDown = (event) => {
+        // In asChild mode, only handle keyboard events when the trigger element
+        // itself has focus — not when focus is on a nested interactive child.
+        // (A native <button> trigger can't have focusable children, so this
+        // check is only needed for asChild.)
+        if (asChild && event.target !== event.currentTarget)
+            return;
+        // Enter/Space activation for asChild mode. Native <button> elements fire
+        // click on Enter/Space automatically; role="button" elements do not.
+        if (asChild && (event.key === 'Enter' || event.key === ' ')) {
+            event.preventDefault();
+            if (!disabled) {
+                toggle(value);
+            }
+            return;
+        }
         const triggers = getTriggers();
         // Sort triggers by DOM order (not Map insertion order) to handle
         // conditional rendering, async mounting, or reordered items
@@ -124,14 +156,16 @@ function AccordionTrigger({ children, className }) {
             return 1;
         });
         const currentIndex = sortedTriggers.findIndex(([v]) => v === value);
-        // Find next/prev non-disabled trigger
+        // Find next/prev non-disabled trigger — check both native disabled (button)
+        // and aria-disabled (asChild elements)
+        const isElementDisabled = (el) => el.disabled || el.getAttribute('aria-disabled') === 'true';
         const findNextIndex = (start, direction) => {
             let index = start;
             const len = sortedTriggers.length;
             for (let i = 0; i < len; i++) {
                 index = (index + direction + len) % len;
                 const [, triggerElement] = sortedTriggers[index];
-                if (triggerElement && !triggerElement.disabled) {
+                if (triggerElement && !isElementDisabled(triggerElement)) {
                     return index;
                 }
             }
@@ -147,14 +181,24 @@ function AccordionTrigger({ children, className }) {
                 event.preventDefault();
                 targetIndex = findNextIndex(currentIndex, -1);
                 break;
-            case 'Home':
+            case 'Home': {
                 event.preventDefault();
-                targetIndex = findNextIndex(sortedTriggers.length - 1, 1); // Start from end, go forward
+                const first = sortedTriggers.findIndex(([, el]) => !isElementDisabled(el));
+                if (first !== -1)
+                    targetIndex = first;
                 break;
-            case 'End':
+            }
+            case 'End': {
                 event.preventDefault();
-                targetIndex = findNextIndex(0, -1); // Start from beginning, go backward
+                // Scan from end to find last non-disabled trigger
+                for (let i = sortedTriggers.length - 1; i >= 0; i--) {
+                    if (!isElementDisabled(sortedTriggers[i][1])) {
+                        targetIndex = i;
+                        break;
+                    }
+                }
                 break;
+            }
         }
         if (targetIndex !== null && targetIndex !== currentIndex) {
             const [, targetElement] = sortedTriggers[targetIndex];
@@ -162,7 +206,34 @@ function AccordionTrigger({ children, className }) {
         }
     };
     const state = isOpen ? 'open' : 'closed';
-    const button = (_jsxs("button", { ref: buttonRef, type: "button", id: triggerId, className: cx('tui-accordion__trigger', className), "aria-expanded": isOpen, "aria-controls": panelId, disabled: disabled, "data-state": state, "data-disabled": disabled || undefined, onClick: handleClick, onKeyDown: handleKeyDown, children: [_jsx("span", { className: "tui-accordion__trigger-content", children: children }), _jsx(Icon, { name: "system/chevron-down", size: "sm", className: "tui-accordion__indicator", "aria-hidden": "true" })] }));
+    // asChild: merge trigger props onto the child element
+    if (asChild && isValidElement(children)) {
+        const triggerProps = {
+            id: triggerId,
+            role: 'button',
+            tabIndex: disabled ? -1 : 0,
+            'aria-expanded': isOpen,
+            'aria-controls': panelId,
+            'aria-disabled': disabled || undefined,
+            'aria-label': ariaLabel,
+            'data-state': state,
+            'data-disabled': disabled || undefined,
+            className: cx('tui-accordion__trigger', className),
+            onClick: handleClick,
+            onKeyDown: handleKeyDown,
+        };
+        const childRef = children.ref;
+        const merged = mergeProps(children.props, triggerProps);
+        merged.ref = composeRefs(triggerRef, childRef);
+        const element = cloneElement(children, merged);
+        if (headingLevel) {
+            const Heading = `h${headingLevel}`;
+            return _jsx(Heading, { className: "tui-accordion__heading", children: element });
+        }
+        return element;
+    }
+    // Default: render as button with built-in chevron indicator
+    const button = (_jsxs("button", { ref: triggerRef, type: "button", id: triggerId, className: cx('tui-accordion__trigger', className), "aria-expanded": isOpen, "aria-controls": panelId, "aria-label": ariaLabel, disabled: disabled, "data-state": state, "data-disabled": disabled || undefined, onClick: handleClick, onKeyDown: handleKeyDown, children: [_jsx("span", { className: "tui-accordion__trigger-content", children: children }), _jsx(Icon, { name: "system/chevron-down", size: "lg", className: "tui-accordion__indicator", "aria-hidden": "true" })] }));
     // Wrap in heading if headingLevel is specified
     if (headingLevel) {
         const Heading = `h${headingLevel}`;
@@ -173,10 +244,10 @@ function AccordionTrigger({ children, className }) {
 // =============================================================================
 // Accordion Panel
 // =============================================================================
-function AccordionPanel({ children, className }) {
+function AccordionPanel({ landmark = false, children, className }) {
     const { triggerId, panelId, isOpen } = useAccordionItemContext();
     const state = isOpen ? 'open' : 'closed';
-    return (_jsx("div", { id: panelId, role: "region", "aria-labelledby": triggerId, className: cx('tui-accordion__panel', className), "data-state": state, "aria-hidden": !isOpen, 
+    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 }) }));
 }

package/components/Accordion/index.d.ts

@@ -1,2 +1,2 @@
 export { Accordion } from './Accordion';
-export type { AccordionProps, AccordionSingleProps, AccordionMultipleProps, AccordionItemProps, AccordionTriggerProps, AccordionPanelProps, } from './types';
+export type { AccordionProps, AccordionSingleProps, AccordionMultipleProps, AccordionItemProps, AccordionTriggerProps, AccordionPanelProps, AccordionVariant, } from './types';

package/components/Accordion/types.d.ts

@@ -1,5 +1,12 @@
 import type { ReactNode } from 'react';
+export type AccordionVariant = 'card' | 'flush';
 type AccordionBaseProps = {
+    /**
+     * Visual treatment.
+     * - `card` (default): Bordered cards with gap between items.
+     * - `flush`: Items share borders, no gap, no radius — denser layout.
+     */
+    variant?: AccordionVariant;
     children: ReactNode;
     className?: string;
 };
@@ -29,16 +36,33 @@ export type AccordionItemProps = {
     value: string;
     /** Prevent interaction */
     disabled?: boolean;
-    /** Wrap trigger in heading element */
+    /**
+     * Wrap trigger in heading element (h2–h6).
+     * Omitting this reduces discoverability for screen reader users who
+     * navigate by headings (NVDA/JAWS `H` key). Only omit when the
+     * accordion is already inside an appropriate heading context.
+     */
     headingLevel?: 2 | 3 | 4 | 5 | 6;
     children: ReactNode;
     className?: string;
 };
 export type AccordionTriggerProps = {
-    children: ReactNode;
+    /**
+     * When true, merges trigger props (aria attributes, event handlers, keyboard
+     * navigation) onto the child element instead of rendering a built-in button.
+     * The child must be a single React element that accepts ref and event handlers.
+     * The built-in chevron indicator is not rendered in asChild mode.
+     * @default false
+     */
+    asChild?: boolean;
+    /** Accessible label for the trigger. Required when children is empty (e.g. icon-only triggers). */
+    'aria-label'?: string;
+    children?: ReactNode;
     className?: string;
 };
 export type AccordionPanelProps = {
+    /** Render panel as a landmark region (role="region"). Default false to avoid landmark pollution with many panels. */
+    landmark?: boolean;
     children: ReactNode;
     className?: string;
 };
@@ -47,8 +71,8 @@ export type AccordionContextValue = {
     collapsible: boolean;
     isOpen: (value: string) => boolean;
     toggle: (value: string) => void;
-    registerTrigger: (value: string, element: HTMLButtonElement | null) => void;
-    getTriggers: () => Map<string, HTMLButtonElement>;
+    registerTrigger: (value: string, element: HTMLElement | null) => void;
+    getTriggers: () => Map<string, HTMLElement>;
 };
 export type AccordionItemContextValue = {
     value: string;

package/components/Avatar/Avatar.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 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';
 /**
  * Generate initials from a name.
@@ -45,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', className, }, ref) => {
+export const Avatar = React.forwardRef(({ src, name, size = 'md', shape = 'circle', color, indicator, indicatorLabel, indicatorPosition = 'bottom-right', tooltip, className, }, ref) => {
     const [imgError, setImgError] = useState(false);
     // Reset error state when src changes
     React.useEffect(() => {
@@ -56,12 +57,20 @@ export const Avatar = React.forwardRef(({ src, name, size = 'md', shape = 'circl
     const showImage = src && !imgError;
     const showInitials = !showImage && initials;
     const showPlaceholder = !showImage && !initials;
-    // Placeholder avatars are decorative (no meaningful identity)
-    const isDecorative = showPlaceholder;
-    return (_jsxs("span", { ref: ref, className: cx('tui-avatar', `is-size-${size}`, `is-shape-${shape}`, !showImage && `is-color-${derivedColor}`, className), ...(isDecorative
+    // Avatars with no name and no indicator label have no meaningful identity
+    const isDecorative = !name && !indicatorLabel;
+    const showTooltip = tooltip && !!name;
+    const avatarElement = (_jsxs("span", { ref: ref, className: cx('tui-avatar', `is-size-${size}`, `is-shape-${shape}`, !showImage && `is-color-${derivedColor}`, className), ...(isDecorative
             ? { 'aria-hidden': true }
-            : { role: 'img', 'aria-label': name }), 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}`), ...(indicatorLabel
-                    ? { role: 'img', 'aria-label': indicatorLabel }
-                    : { 'aria-hidden': true }), children: indicator }))] }));
+            : {
+                role: 'img',
+                'aria-label': name && indicatorLabel
+                    ? `${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

@@ -10,7 +10,7 @@ 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, children, className }, ref) => {
+export const AvatarGroup = React.forwardRef(({ max, size, shape, overlap = true, groupLabel: groupLabelFn, children, className }, ref) => {
     const childArray = Children.toArray(children).filter(isValidElement);
     const total = childArray.length;
     // Clone children to inject size/shape props if provided at group level
@@ -26,9 +26,11 @@ export const AvatarGroup = React.forwardRef(({ max, size, shape, overlap = true,
     // Descriptive label for the group
     const hasOverflow = max !== undefined && total > max;
     const visibleCount = hasOverflow ? max : total;
-    const groupLabel = hasOverflow
-        ? `${total} users, showing ${visibleCount}`
-        : `${total} users`;
+    const groupLabel = groupLabelFn
+        ? groupLabelFn(total, visibleCount)
+        : hasOverflow
+            ? `${total} users, showing ${visibleCount}`
+            : `${total} users`;
     // 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 }));
@@ -41,5 +43,5 @@ export const AvatarGroup = React.forwardRef(({ max, size, shape, overlap = true,
 });
 AvatarGroup.displayName = 'AvatarGroup';
 function AvatarOverflow({ count, size, shape }) {
-    return (_jsx("span", { className: cx('tui-avatar', 'tui-avatar--overflow', size && `is-size-${size}`, shape && `is-shape-${shape}`), role: "img", "aria-hidden": "true", children: _jsx("span", { className: "tui-avatar__content", children: _jsxs("span", { className: "tui-avatar__initials", children: ["+", count] }) }) }));
+    return (_jsx("span", { className: cx('tui-avatar', 'tui-avatar--overflow', size && `is-size-${size}`, shape && `is-shape-${shape}`), "aria-hidden": "true", children: _jsx("span", { className: "tui-avatar__content", children: _jsxs("span", { className: "tui-avatar__initials", children: ["+", count] }) }) }));
 }

package/components/Avatar/types.d.ts

@@ -25,6 +25,12 @@ export type AvatarProps = {
     indicatorLabel?: string;
     /** Position of the indicator */
     indicatorPosition?: IndicatorPosition;
+    /**
+     * When true, wraps the avatar with a Tooltip showing the `name`.
+     * Helps sighted users discover the user's name on hover/focus.
+     * Has no effect when `name` is not provided.
+     */
+    tooltip?: boolean;
     /** Additional CSS class */
     className?: string;
 };
@@ -37,6 +43,11 @@ export type AvatarGroupProps = {
     shape?: AvatarShape;
     /** Whether avatars overlap (default: true) */
     overlap?: boolean;
+    /**
+     * Custom label function for i18n. Receives total and visible counts.
+     * Default: "N users" or "N users, showing M".
+     */
+    groupLabel?: (total: number, visible: number) => string;
     /** Children (Avatar components) */
     children: React.ReactNode;
     /** Additional CSS class */

package/components/Button/Button.js

@@ -3,9 +3,16 @@ 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, leftIconName, rightIconName, leftIcon, rightIcon, iconSize = 'sm', className, target, rel, onClick, style, ...rest }, ref) => {
+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) => {
     const isLink = typeof rest.href === 'string';
     const isDisabled = disabled || loading;
+    // 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];
+    // Compose loading state into aria-label for screen readers
+    const loadingLabel = loading
+        ? (loadingLabelProp ?? (typeof label === 'string' ? `${label}, loading` : undefined))
+        : undefined;
     // Normalize destructive → danger for CSS class
     const themeClass = theme === 'destructive' ? 'danger' : theme;
     const classes = cx('tui-button', `is-size-${size}`, `is-theme-${themeClass}`, variant !== 'solid' && `is-style-${variant}`, fullWidth && 'is-width-full', isDisabled && 'is-disabled', className);
@@ -25,9 +32,9 @@ export const Button = forwardRef(({ label, children, size = 'md', theme = 'prima
             }
             onClick?.(e);
         };
-        return (_jsx("a", { ref: ref, href: isDisabled ? undefined : href, className: classes, "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 }));
+        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)" }))] }));
     }
     const buttonRest = rest;
-    return (_jsx("button", { ref: ref, type: buttonRest.type ?? 'button', className: classes, disabled: isDisabled, "aria-disabled": isDisabled || undefined, "aria-busy": loading || undefined, onClick: onClick, "data-loading": loading || undefined, style: style, ...buttonRest, children: content }));
+    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 }));
 });
 Button.displayName = 'Button';

package/components/Button/types.d.ts

@@ -6,7 +6,9 @@ export type { Size };
  * - `'primary'`: Primary action (default)
  * - `'secondary'`: Secondary/neutral action
  * - `'danger'`: Destructive action
- * - `'destructive'`: Alias for danger
+ * - `'destructive'`: Alias for `'danger'` — mapped internally before
+ *   class generation. Provided for readability in consumer code where
+ *   "destructive" better describes the intent (e.g. `theme="destructive"`).
  */
 export type Theme = ThemeIntent | 'destructive';
 /**
@@ -60,6 +62,12 @@ type CommonProps = {
      * @default false
      */
     loading?: boolean;
+    /**
+     * Accessible label override during loading state. For i18n support.
+     * When loading, this replaces the auto-composed label.
+     * @default `${label}, loading` (English)
+     */
+    loadingLabel?: string;
     /**
      * Link target (for anchor variant).
      */

package/components/Card/Card.js

@@ -1,26 +1,38 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { forwardRef, useRef, useEffect } from 'react';
+import React, { forwardRef, useRef, useEffect, createContext, useContext } from 'react';
 import { cx } from '../../utils/cx.js';
 import { isDev } from '../../utils/is-dev.js';
+const CardDisabledContext = createContext(false);
 export const Card = forwardRef(function Card({ as = 'article', inline, elevated, interactive, disabled, className, style, onClick, children, ...rest }, ref) {
     const Tag = as;
-    const hasCardLinkChild = React.Children.toArray(children).some((child) => {
-        if (!React.isValidElement(child))
-            return false;
-        const type = child.type;
-        return child.type === CardLink || type.displayName === 'Card.Link';
-    });
-    // Dev warning: suggest Card.Link for interactive cards
+    // Dev warning: suggest Card.Link for interactive cards.
+    // The recursive children walk is gated behind isDev() to avoid
+    // unnecessary work in production on every render.
     const warnedRef = useRef(false);
     useEffect(() => {
-        if (isDev() && !warnedRef.current && (interactive || onClick) && !hasCardLinkChild) {
+        if (!isDev() || warnedRef.current || !(interactive || onClick))
+            return;
+        const hasCardLinkChild = (function checkChildren(nodes) {
+            return React.Children.toArray(nodes).some((child) => {
+                if (!React.isValidElement(child))
+                    return false;
+                const type = child.type;
+                if (child.type === CardLink || type.displayName === 'Card.Link')
+                    return true;
+                const childProps = child.props;
+                if (childProps.children)
+                    return checkChildren(childProps.children);
+                return false;
+            });
+        })(children);
+        if (!hasCardLinkChild) {
             warnedRef.current = true;
             console.warn('[TUI Card] Interactive cards should use <Card.Link> for accessible click targets. ' +
                 '`interactive` and `onClick` provide visual hover styles but no keyboard/screen-reader semantics.');
         }
-    }, [interactive, onClick, hasCardLinkChild]);
+    });
     const classes = cx('tui-card', inline && 'is-layout-inline', elevated && 'is-style-elevated', interactive && 'has-interaction', className);
-    return (_jsx(Tag, { ref: ref, className: classes, style: style, "aria-disabled": disabled || undefined, onClick: disabled ? undefined : onClick, ...rest, children: _jsx("div", { className: "tui-card__inner", children: children }) }));
+    return (_jsx(Tag, { ref: ref, className: classes, style: style, "aria-disabled": disabled || undefined, onClick: disabled ? undefined : onClick, ...rest, children: _jsx(CardDisabledContext.Provider, { value: !!disabled, children: _jsx("div", { className: "tui-card__inner", children: children }) }) }));
 });
 function CardHead({ className, children, ...rest }) {
     return (_jsx("div", { className: cx('tui-card__head', className), ...rest, children: children }));
@@ -34,8 +46,9 @@ function CardFoot({ className, children, ...rest }) {
     return (_jsx("div", { className: cx('tui-card__foot', className), ...rest, children: children }));
 }
 CardFoot.displayName = 'Card.Foot';
-function CardLink({ className, children, rel, target, ...rest }) {
-    return (_jsx("a", { className: cx('tui-stretched-link', className), rel: target === '_blank' ? ['noopener', 'noreferrer', rel].filter(Boolean).join(' ') : rel, target: target, ...rest, children: children }));
+function CardLink({ className, children, rel, target, href, ...rest }) {
+    const isDisabled = useContext(CardDisabledContext);
+    return (_jsx("a", { className: cx('tui-stretched-link', className), rel: target === '_blank' ? ['noopener', 'noreferrer', rel].filter(Boolean).join(' ') : rel, target: isDisabled ? undefined : target, href: isDisabled ? undefined : href, role: isDisabled ? 'link' : undefined, "aria-disabled": isDisabled || undefined, tabIndex: isDisabled ? -1 : undefined, ...rest, children: children }));
 }
 CardLink.displayName = 'Card.Link';
 Card.Head = CardHead;

package/components/Checkbox/Checkbox.d.ts

@@ -1,4 +1,4 @@
-export declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<import("react").InputHTMLAttributes<HTMLInputElement>, "role" | "type" | "defaultChecked" | "onChange" | "checked"> & {
+export declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<import("react").InputHTMLAttributes<HTMLInputElement>, "role" | "type" | "onChange" | "defaultChecked" | "checked"> & {
     checked?: boolean;
     defaultChecked?: boolean;
     onCheckedChange?: (checked: boolean) => void;