@tangible/ui 0.0.2 → 0.0.4

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

@@ -14,7 +14,7 @@ declare function AccordionTrigger({ children, className }: AccordionTriggerProps
 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

@@ -162,7 +162,7 @@ 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" })] }));
+    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: "lg", className: "tui-accordion__indicator", "aria-hidden": "true" })] }));
     // Wrap in heading if headingLevel is specified
     if (headingLevel) {
         const Heading = `h${headingLevel}`;
@@ -173,10 +173,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": triggerId, 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/types.d.ts

@@ -29,7 +29,12 @@ 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;
@@ -39,6 +44,8 @@ export type AccordionTriggerProps = {
     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;
 };

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;

package/components/Chip/Chip.d.ts

@@ -5,6 +5,15 @@ type Size = SizeCompact;
 type Theme = ThemeFull;
 type Variant = 'default' | 'outline' | 'ghost' | 'solid' | 'flush';
 export type ChipProps = {
+    /**
+     * HTML element to render.
+     * - `'span'` (default): Inline element. Use for chips within text flow,
+     *   inline lists, or inside `<p>`/`<li>` elements.
+     * - `'div'`: Block element. Use when the chip contains block-level content
+     *   or needs to be a flex/grid child without inline constraints.
+     * - `'a'`: Anchor element. Use for navigational chips with an `href`.
+     * @default 'span'
+     */
     as?: 'span' | 'div' | 'a';
     href?: string;
     target?: React.HTMLAttributeAnchorTarget;
@@ -23,5 +32,32 @@ export type ChipProps = {
     /** When inside ChipGroup, identifies this chip for selection tracking */
     value?: OptionValue;
 } & Omit<React.HTMLAttributes<HTMLSpanElement>, 'onClick'>;
-export declare function Chip({ as, href, target, rel, children, size, theme, variant, selected: selectedProp, disabled: disabledProp, interactive, className, leftIcon, rightIcon, onClick: onClickProp, value, ...rest }: ChipProps): import("react/jsx-runtime").JSX.Element;
+export declare const Chip: React.ForwardRefExoticComponent<{
+    /**
+     * HTML element to render.
+     * - `'span'` (default): Inline element. Use for chips within text flow,
+     *   inline lists, or inside `<p>`/`<li>` elements.
+     * - `'div'`: Block element. Use when the chip contains block-level content
+     *   or needs to be a flex/grid child without inline constraints.
+     * - `'a'`: Anchor element. Use for navigational chips with an `href`.
+     * @default 'span'
+     */
+    as?: "span" | "div" | "a";
+    href?: string;
+    target?: React.HTMLAttributeAnchorTarget;
+    rel?: string;
+    children: React.ReactNode;
+    size?: Size;
+    theme?: Theme;
+    variant?: Variant;
+    selected?: boolean;
+    disabled?: boolean;
+    interactive?: boolean;
+    className?: string;
+    leftIcon?: React.ReactNode;
+    rightIcon?: React.ReactNode;
+    onClick?: React.MouseEventHandler<HTMLElement>;
+    /** When inside ChipGroup, identifies this chip for selection tracking */
+    value?: OptionValue;
+} & Omit<React.HTMLAttributes<HTMLSpanElement>, "onClick"> & React.RefAttributes<HTMLElement>>;
 export {};

package/components/Chip/Chip.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from 'react';
-import { useCallback, useEffect } from 'react';
+import { useCallback, useEffect, forwardRef } from 'react';
 import { cx } from '../../utils/cx.js';
 import { toKey } from '../../utils/value-key.js';
 import { isDev } from '../../utils/is-dev.js';
 import { useChipGroupContext } from '../ChipGroup/ChipGroupContext.js';
-export function Chip({ as = 'span', href, target, rel, children, size = 'md', theme = 'secondary', variant = 'default', selected: selectedProp, disabled: disabledProp, interactive, className, leftIcon, rightIcon, onClick: onClickProp, value, ...rest }) {
+export const Chip = forwardRef(function Chip({ as = 'span', href, target, rel, children, size = 'md', theme = 'secondary', variant = 'default', selected: selectedProp, disabled: disabledProp, interactive, className, leftIcon, rightIcon, onClick: onClickProp, value, ...rest }, ref) {
     const groupContext = useChipGroupContext();
     // Dev warning: inside ChipGroup without value
     useEffect(() => {
@@ -25,7 +25,7 @@ export function Chip({ as = 'span', href, target, rel, children, size = 'md', th
     const onClick = isManaged ? managedClick : onClickProp;
     const Tag = (as === 'a' ? 'a' : as);
     // Determine if this chip is clickable (needs button semantics)
-    const isClickable = (interactive || onClick || isManaged) && !disabled;
+    const isClickable = (!!onClick || isManaged) && !disabled;
     // Keyboard handler for interactive chips
     const handleKeyDown = useCallback((e) => {
         if (!isClickable || !onClick)
@@ -38,7 +38,7 @@ export function Chip({ as = 'span', href, target, rel, children, size = 'md', th
     const classes = cx('tui-chip', size && `is-size-${size}`, theme && `is-theme-${theme}`, variant !== 'default' && `is-style-${variant}`, selected && 'is-selected', (interactive || isManaged) && 'is-interactive', className);
     const anchorProps = as === 'a'
         ? {
-            href: disabled ? undefined : href ?? '#',
+            href: disabled || isManaged ? undefined : href ?? '#',
             target,
             rel,
             'aria-disabled': disabled || undefined,
@@ -49,14 +49,16 @@ export function Chip({ as = 'span', href, target, rel, children, size = 'md', th
     // Non-anchor clickable chips always need role="button".
     // Managed anchor chips also get role="button" — toggle semantics
     // take priority over link semantics inside a ChipGroup.
-    const needsButtonRole = isClickable && (as !== 'a' || isManaged);
+    // Disabled managed chips keep role="button" so they remain visible to AT.
+    const needsButtonRole = (isClickable || (isManaged && disabled)) && (as !== 'a' || isManaged);
     const buttonProps = needsButtonRole
         ? {
             role: 'button',
-            tabIndex: as !== 'a' ? 0 : undefined, // anchors are natively focusable
+            tabIndex: disabled ? -1 : (as !== 'a' ? 0 : undefined),
             onKeyDown: handleKeyDown,
             'aria-pressed': isManaged ? (selected ?? false) : undefined,
+            'aria-disabled': disabled || undefined,
         }
         : {};
-    return (_jsxs(Tag, { className: classes, ...anchorProps, ...buttonProps, onClick: disabled ? undefined : onClick, ...rest, children: [leftIcon && leftIcon, _jsx("span", { className: "tui-chip__text", children: children }), rightIcon && rightIcon] }));
-}
+    return (_jsxs(Tag, { ref: ref, className: classes, ...anchorProps, ...buttonProps, onClick: disabled ? undefined : onClick, ...rest, children: [leftIcon && leftIcon, _jsx("span", { className: "tui-chip__text", children: children }), rightIcon && rightIcon] }));
+});

package/components/ChipGroup/ChipGroup.js

@@ -1,5 +1,5 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { useCallback, useEffect, useMemo } from 'react';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useMemo } from 'react';
 import { cx } from '../../utils/cx.js';
 import { useControllableState } from '../../utils/use-controllable-state.js';
 import { toKey } from '../../utils/value-key.js';
@@ -17,7 +17,7 @@ import { isDev } from '../../utils/is-dev.js';
 //
 // =============================================================================
 export function ChipGroup(props) {
-    const { multiple = false, disabled = false, density = 'sm', direction = 'inline', alignment, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, } = props;
+    const { multiple = false, disabled = false, density = 'sm', direction = 'inline', alignment, multipleLabel = 'Multiple selections allowed', 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, } = props;
     // --- Single mode ---
     // isControlled override: 'value' in props detects explicit value={undefined}
     // (deselection) vs prop not passed at all (uncontrolled).
@@ -57,12 +57,13 @@ export function ChipGroup(props) {
         }
     }, [multiple, setSingleValue, setMultiValue]);
     const contextValue = useMemo(() => ({ selectedValues, multiple, disabled, onSelect }), [selectedValues, multiple, disabled, onSelect]);
+    const descriptionId = useId();
     // Dev-only: warn if group has no accessible name
     useEffect(() => {
         if (isDev() && !ariaLabel && !ariaLabelledBy) {
             console.warn('ChipGroup: Missing accessible name. Provide aria-label or aria-labelledby.');
         }
     }, [ariaLabel, ariaLabelledBy]);
-    return (_jsx(ChipGroupContext.Provider, { value: contextValue, children: _jsx("div", { role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className: cx('tui-chip-group', `is-density-${density}`, direction === 'stack' && 'is-direction-stack', alignment && `is-align-${alignment}`, className), children: children }) }));
+    return (_jsx(ChipGroupContext.Provider, { value: contextValue, children: _jsxs("div", { role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-disabled": disabled || undefined, "aria-describedby": multiple ? descriptionId : undefined, className: cx('tui-chip-group', `is-density-${density}`, direction === 'stack' && 'is-direction-stack', alignment && `is-align-${alignment}`, className), children: [children, multiple && (_jsx("span", { id: descriptionId, className: "tui-visually-hidden", children: multipleLabel }))] }) }));
 }
 ChipGroup.displayName = 'ChipGroup';

package/components/ChipGroup/types.d.ts

@@ -8,6 +8,9 @@ type ChipGroupBaseProps = {
     direction?: 'inline' | 'stack';
     /** Alignment along main axis. */
     alignment?: 'start' | 'center' | 'end';
+    /** Visually hidden label describing multi-select behaviour. For i18n support.
+     *  @default 'Multiple selections allowed' */
+    multipleLabel?: string;
     'aria-label'?: string;
     'aria-labelledby'?: string;
     className?: string;

package/components/Dropdown/Dropdown.d.ts

@@ -1,4 +1,4 @@
-import type { DropdownProps, DropdownTriggerProps, DropdownContentProps, DropdownItemProps } from './types';
+import type { DropdownProps, DropdownTriggerProps, DropdownContentProps, DropdownItemProps, DropdownSeparatorProps, DropdownHeaderProps } from './types';
 declare function DropdownRoot({ open: controlledOpen, onOpenChange, defaultOpen, children, }: DropdownProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DropdownRoot {
     var displayName: string;
@@ -19,13 +19,31 @@ declare function DropdownItemComponent({ onSelect, href, target, disabled, keepO
 declare namespace DropdownItemComponent {
     var displayName: string;
 }
+/**
+ * Non-interactive separator for visually grouping menu items.
+ */
+declare function DropdownSeparatorComponent({ className }: DropdownSeparatorProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownSeparatorComponent {
+    var displayName: string;
+}
+/**
+ * Non-interactive section label for grouping menu items.
+ */
+declare function DropdownHeaderComponent({ className, children }: DropdownHeaderProps): import("react/jsx-runtime").JSX.Element;
+declare namespace DropdownHeaderComponent {
+    var displayName: string;
+}
 type DropdownCompound = typeof DropdownRoot & {
     Trigger: typeof DropdownTriggerComponent;
     Content: typeof DropdownContentComponent;
     Item: typeof DropdownItemComponent;
+    Separator: typeof DropdownSeparatorComponent;
+    Header: typeof DropdownHeaderComponent;
 };
 export declare const Dropdown: DropdownCompound;
 export declare const DropdownTrigger: typeof DropdownTriggerComponent;
 export declare const DropdownContent: typeof DropdownContentComponent;
 export declare const DropdownItem: typeof DropdownItemComponent;
+export declare const DropdownSeparator: typeof DropdownSeparatorComponent;
+export declare const DropdownHeader: typeof DropdownHeaderComponent;
 export { useDropdownContext as useDropdown } from './DropdownContext';