@tangible/ui 0.0.5 → 0.0.7

package/README.md

@@ -1,17 +1,17 @@
 # Tangible UI
 
-Design system for Tangible WordPress plugins. React components + CSS tokens + utility classes.
+Design system for Tangible WordPress plugins. React components, CSS custom property tokens, and CSS-only form elements.
 
 **Live Storybook:** https://storybook-tangible-ui.pages.dev
 
 ## Components
 
-- **Primitives:** Button, Chip, ChipGroup, Icon, IconButton, Progress, Rating, Tooltip
+- **Primitives:** Button, IconButton, Chip, ChipGroup, Icon, 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
+- **Form Controls:** Select, MultiSelect, Combobox, TextInput, Textarea, Checkbox, Switch, Radio/RadioGroup
 - **Composites:** Avatar, Dropdown, MoveHandle, OverlapStack, SegmentedControl, Field
-- **CSS-only Inputs:** Text, textarea, select, checkbox, radio, toggle, file
+- **CSS-only Inputs:** Text, textarea, select, checkbox, radio, toggle, file (no JS required)
 
 ## Getting Started
 
@@ -21,21 +21,40 @@ Design system for Tangible WordPress plugins. React components + CSS tokens + ut
 npm install @tangible/ui
 ```
 
+#### Optional peer dependencies
+
+Some components require additional packages. Install only what you use:
+
+| Package | Required by | Size |
+|---------|-------------|------|
+| `@floating-ui/react` | Select, MultiSelect, Combobox, Dropdown, Tooltip | ~90 KB |
+| `@tanstack/react-table` | DataTable | ~50 KB |
+
+```bash
+# If using Select, Dropdown, Tooltip, etc.
+npm install @floating-ui/react
+
+# If using DataTable
+npm install @tanstack/react-table
+```
+
+Components without these dependencies (Button, Card, Accordion, Modal, Tabs, etc.) work with zero additional installs.
+
 ### Import styles
 
 ```tsx
-// In your app entry point
 import '@tangible/ui/styles';
 ```
 
-Or for WordPress contexts (no CSS layers):
+For WordPress plugin contexts where CSS layers can lose to unlayered theme styles:
+
 ```tsx
 import '@tangible/ui/styles/unlayered';
 ```
 
-### Wrap your app
+### Set up the interface wrapper
 
-Components require the `.tui-interface` wrapper to access design tokens:
+All components require the `.tui-interface` wrapper to access design tokens:
 
 ```tsx
 function App() {
@@ -47,34 +66,112 @@ function App() {
 }
 ```
 
-Dark mode via `data-theme="dark"` on the wrapper.
+### Dark mode
+
+Set `data-theme` on the wrapper:
+
+```tsx
+<div className="tui-interface" data-theme="dark">
+```
+
+- `"dark"` — force dark mode
+- `"auto"` — follow `prefers-color-scheme`
+- Omit attribute — light mode (inherits host colour)
 
 ### Use components
 
 ```tsx
-import { Button, Card, Tooltip, IconButton } from '@tangible/ui';
+import { Button, Card, Select, SelectOption } from '@tangible/ui';
 
 function Example() {
   return (
     <Card>
       <Card.Body>
-        <Button label="Click me" theme="primary" />
-
-        <IconButton icon="system/settings" label="Settings" showTooltip />
-
-        <Tooltip>
-          <Tooltip.Trigger asChild>
-            <Button label="Hover me" variant="outline" />
-          </Tooltip.Trigger>
-          <Tooltip.Content>Hello!</Tooltip.Content>
-        </Tooltip>
+        <Button label="Save" theme="primary" />
+
+        <Select placeholder="Choose..." onValueChange={(v) => console.log(v)}>
+          <Select.Trigger />
+          <Select.Content>
+            <Select.Option value="a">Option A</Select.Option>
+            <Select.Option value="b">Option B</Select.Option>
+          </Select.Content>
+        </Select>
       </Card.Body>
     </Card>
   );
 }
 ```
 
-See the [Storybook](https://storybook-tangible-ui.pages.dev) for full component documentation and examples.
+### Tree-shaking
+
+Individual component imports are available if your bundler doesn't tree-shake the barrel export:
+
+```tsx
+import { Button } from '@tangible/ui/components/Button';
+import { Tooltip } from '@tangible/ui/components/Tooltip';
+```
+
+## Customisation
+
+### Token overrides
+
+Components are styled via CSS custom properties. Override them on `.tui-interface` or any ancestor:
+
+```css
+/* Global overrides */
+.tui-interface {
+  --tui-radius-md: 2px;
+  --tui-focus-ring-color: hotpink;
+}
+
+/* Scoped to a specific context */
+.my-sidebar .tui-interface {
+  --tui-button-radius: 0;
+  --tui-control-height-md: 32px;
+}
+```
+
+### Component API tokens
+
+Each component reads its own `--tui-{component}-*` tokens via fallback chains. These are never defined by TUI — only read. Set them from consuming code:
+
+```css
+.compact-form {
+  --tui-accordion-padding: 8px;
+  --tui-select-trigger-radius: 2px;
+  --tui-modal-spacing: 24px;
+}
+```
+
+See each component's `styles.scss` header for its full token API.
+
+### Form control sizing
+
+All form controls share a unified sizing system:
+
+```css
+.my-context .tui-interface {
+  --tui-control-height-sm: 28px;
+  --tui-control-height-md: 32px;
+  --tui-control-height-lg: 40px;
+
+  /* Optional: decouple font size from size tier */
+  --tui-control-font-size-sm: 13px;
+  --tui-control-font-size-md: 13px;
+  --tui-control-font-size-lg: 14px;
+}
+```
+
+### Icons
+
+Four icon sets available via the registry: `system`, `cred`, `reaction`, `player`.
+
+```tsx
+import { Icon } from '@tangible/ui';
+
+<Icon name="system/check" />
+<Icon name="reaction/clap-fill" size="lg" />
+```
 
 ## Development
 
@@ -83,7 +180,7 @@ npm install
 npm run storybook   # Dev server on port 6006
 ```
 
-## Commands
+### Commands
 
 ```bash
 npm run storybook          # Dev server
@@ -97,12 +194,12 @@ npm run test:visual:update # Regenerate visual baselines
 
 ## Documentation
 
-- `CLAUDE.md` — Development guide (architecture, patterns, conventions)
-- `CONTEXT.md` — Project background and LMS requirements
-- `TIMELINE.md` — Development roadmap (Jan–Mar 2026)
+- `CLAUDE.md` — Architecture, patterns, conventions, gotchas
+- `CONTEXT.md` — Project background and design philosophy
+- `TIMELINE.md` — Development roadmap
 - `TESTING.md` — Testing strategy and infrastructure
-- `AGENTS.md` — Quality gate agent configurations
+- `CHANGELOG.md` — Release history
 
 ## Status
 
-Under active development for Course Builder (LMS) and Quiz modules. Component APIs are stabilising but may change before 1.0.
+Under active development. Component APIs are stabilising but may change before 1.0.

package/components/Accordion/Accordion.js

@@ -233,7 +233,7 @@ function AccordionTrigger({ asChild = false, 'aria-label': ariaLabel, children,
         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" })] }));
+    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: [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}`;

package/components/Combobox/Combobox.d.ts

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

package/components/Combobox/Combobox.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import React, { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { isDev } from '../../utils/is-dev.js';
 import { useFloating, offset, flip, shift, size as sizeMiddleware, autoUpdate, FloatingPortal, useDismiss, useInteractions, useListNavigation, useRole, } from '@floating-ui/react';
 import { cx } from '../../utils/cx.js';
 import { toKey } from '../../utils/value-key.js';
@@ -11,7 +12,7 @@ import { ComboboxActionsContext, ComboboxStateContext, ComboboxContentContext, u
 // =============================================================================
 // Combobox Root
 // =============================================================================
-function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inputValue: controlledInputValue, onInputChange, open: controlledOpen, defaultOpen, onOpenChange, disabled = false, placeholder = '', size = 'md', openOnFocus = true, filterMode = 'always', onQueryChange, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, inputClassName, children, }) {
+function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inputValue: controlledInputValue, onInputChange, open: controlledOpen, defaultOpen, onOpenChange, disabled = false, placeholder = '', size = 'md', openOnFocus = true, filterMode = 'always', onQueryChange, clearable = true, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, inputClassName, children, }) {
     // Controlled/uncontrolled value (initialize from defaultValue)
     const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
     const isValueControlled = controlledValue !== undefined;
@@ -364,7 +365,7 @@ function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inp
     return (_jsx(ComboboxActionsContext.Provider, { value: actionsValue, children: _jsx(ComboboxStateContext.Provider, { value: stateValue, children: _jsxs("div", { className: "tui-combobox", children: [_jsxs("div", { className: "tui-combobox__input-wrapper", children: [_jsx("input", { ref: (node) => {
                                     inputRef.current = node;
                                     refs.setReference(node);
-                                }, type: "text", id: inputId, className: cx('tui-combobox__input', size !== 'md' && `is-size-${size}`, inputClassName), role: "combobox", "aria-expanded": open, "aria-controls": listboxId, "aria-autocomplete": "list", "aria-activedescendant": activeOptionId, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, placeholder: placeholder, value: inputValue, autoComplete: "off", ...referenceProps, onChange: handleInputChange }), inputValue && !disabled && (_jsx("span", { className: "tui-combobox__clear", onPointerDown: handleClear, "aria-hidden": "true", children: _jsx(Icon, { name: "system/close", size: "sm" }) })), _jsx("span", { className: "tui-combobox__icon", "aria-hidden": "true", children: _jsx(Icon, { name: "system/chevron-down", size: "sm" }) })] }), children] }) }) }));
+                                }, type: "text", id: inputId, className: cx('tui-combobox__input', size !== 'md' && `is-size-${size}`, inputClassName), role: "combobox", "aria-expanded": open, "aria-controls": listboxId, "aria-autocomplete": "list", "aria-activedescendant": activeOptionId, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, placeholder: placeholder, value: inputValue, autoComplete: "off", ...referenceProps, onChange: handleInputChange }), clearable && inputValue && !disabled && (_jsx("span", { className: "tui-combobox__clear", onPointerDown: handleClear, "aria-hidden": "true", children: _jsx(Icon, { name: "system/close", size: "sm" }) })), _jsx("span", { className: "tui-combobox__icon", "aria-hidden": "true", children: _jsx(Icon, { name: "system/chevron-down", size: "sm" }) })] }), children] }) }) }));
 }
 ComboboxRoot.displayName = 'Combobox';
 // =============================================================================
@@ -396,7 +397,7 @@ function ComboboxOptionComponent({ value: optionValue, disabled = false, textVal
     const textValue = explicitTextValue ?? (typeof children === 'string' ? children : '');
     // Warn in dev if textValue couldn't be derived
     useEffect(() => {
-        if (import.meta.env.DEV && !textValue) {
+        if (isDev() && !textValue) {
             console.warn(`Combobox.Option with value="${optionValue}" has no textValue. Provide textValue prop when children is not a string.`);
         }
     }, [textValue, optionValue]);

package/components/Combobox/types.d.ts

@@ -86,6 +86,11 @@ export type ComboboxProps = {
      * ID of element that labels this combobox.
      */
     'aria-labelledby'?: string;
+    /**
+     * Whether to show the clear button when a value is present.
+     * @default true
+     */
+    clearable?: boolean;
     /**
      * Class name applied directly to the `<input>` element.
      * Use for utilities like `tui-input-reset` that must target the input itself.

package/components/Field/Field.js

@@ -5,16 +5,18 @@ import { FieldContext, useFieldContext } from './FieldContext.js';
 export const Field = forwardRef(function Field({ error = false, required = false, disabled = false, inline = false, className, children, }, ref) {
     const baseId = useId();
     const controlId = `${baseId}-control`;
+    const labelId = `${baseId}-label`;
     const helperTextId = `${baseId}-helper`;
     const errorId = `${baseId}-error`;
     const contextValue = useMemo(() => ({
         controlId,
+        labelId,
         helperTextId,
         errorId,
         hasError: error,
         required,
         disabled,
-    }), [controlId, helperTextId, errorId, error, required, disabled]);
+    }), [controlId, labelId, helperTextId, errorId, error, required, disabled]);
     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 +24,16 @@ 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 } = useFieldContext();
     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: "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, } = useFieldContext();
     const child = Children.only(children);
     if (!isValidElement(child)) {
         throw new Error('Field.Control expects a single React element as its child');
@@ -48,10 +50,18 @@ function FieldControl({ children }) {
         describedByParts.push(errorId);
     }
     const describedBy = describedByParts.join(' ');
+    // Build aria-labelledby for non-labelable elements (<button>, <div>, etc.)
+    // <label htmlFor> only works with labelable elements (input, textarea, select,
+    // meter, output, progress). For everything else (Switch, future Slider, etc.)
+    // aria-labelledby provides the accessible name. For native inputs this is
+    // redundant with htmlFor but harmless — aria-labelledby takes priority in the
+    // accessible name algorithm and points at the same label text.
+    const labelledBy = childProps['aria-labelledby'] ?? labelId;
     // 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,8 @@
 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) */

package/components/Icon/Icon.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from 'react';
 import { cx } from '../../utils/cx.js';
+import { isDev } from '../../utils/is-dev.js';
 import { iconRegistry } from '../../icons/registry.js';
 /**
  * Icon component for SVG icons from the registry or emoji characters.
@@ -12,7 +13,7 @@ import { iconRegistry } from '../../icons/registry.js';
 export const Icon = React.forwardRef(({ name, emoji, label, size, className }, ref) => {
     const SvgIcon = name ? iconRegistry[name] : null;
     // Dev warning for invalid icon name
-    if (import.meta.env.DEV && name && !SvgIcon) {
+    if (isDev() && name && !SvgIcon) {
         console.warn(`[Icon] Unknown icon name: "${name}". Check the registry.`);
     }
     // Decorative if no label provided

package/components/Modal/Modal.js

@@ -108,7 +108,7 @@ function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-l
         let target = null;
         if (initialFocusSelector) {
             target = dialog.querySelector(initialFocusSelector);
-            if (!target && import.meta.env.DEV) {
+            if (!target && isDev()) {
                 console.warn(`Modal: initialFocusSelector="${initialFocusSelector}" did not match any element. ` +
                     `Falling back to first focusable element.`);
             }
@@ -118,7 +118,7 @@ function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-l
         }
         target.focus({ preventScroll: true });
         // Development warning for missing labelledBy target
-        if (import.meta.env.DEV && labelledBy) {
+        if (isDev() && labelledBy) {
             const labelElement = document.getElementById(labelledBy);
             if (!labelElement) {
                 console.warn(`Modal: aria-labelledby="${labelledBy}" references a non-existent element. ` +

package/components/MoveHandle/MoveHandle.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useCallback, useEffect, useId, useRef } from 'react';
+import { forwardRef, useCallback, useEffect, useId, useRef, useState } from 'react';
 import { cx } from '../../utils/cx.js';
 import { isDev } from '../../utils/is-dev.js';
 import { Icon } from '../Icon/index.js';
@@ -64,6 +64,17 @@ export const MoveHandle = forwardRef(function MoveHandle({ mode = 'full', size =
             fallback?.focus();
         }
     }, [mode, canMoveUp, canMoveDown]);
+    // Debounce the lock icon — prevents visual jitter when `locked` flashes
+    // briefly (e.g. during a save). Behaviour (disabled buttons) applies
+    // immediately; only the icon swap is delayed.
+    const [showLockIcon, setShowLockIcon] = useState(locked);
+    useEffect(() => {
+        if (locked) {
+            const id = setTimeout(() => setShowLockIcon(true), 150);
+            return () => clearTimeout(id);
+        }
+        setShowLockIcon(false);
+    }, [locked]);
     // Drag handle label precedence: dragHandleProps > labels.drag > default
     const resolvedDragLabel = dragHandleProps?.['aria-label'] ?? labels?.drag ?? 'Drag to reorder';
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -80,5 +91,5 @@ export const MoveHandle = forwardRef(function MoveHandle({ mode = 'full', size =
     const resolvedLockedDesc = locked
         ? (labels?.locked ?? 'This item is locked and cannot be reordered')
         : undefined;
-    return (_jsxs("div", { ref: mergedRef, role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": locked ? lockedDescId : undefined, "aria-disabled": locked || undefined, className: cx('tui-move-handle', `is-size-${size}`, locked && 'is-locked', hasIndex && 'has-index', className), children: [locked && (_jsx("span", { id: lockedDescId, className: "tui-visually-hidden", children: resolvedLockedDesc })), onMoveUp && (_jsx("button", { type: "button", className: "tui-move-handle__up", "data-direction": "up", "aria-label": labels?.moveUp ?? 'Move up', disabled: locked || !canMoveUp, onClick: onMoveUp, children: _jsx(Icon, { name: "system/chevron-up" }) })), _jsx("div", { className: "tui-move-handle__center", children: locked ? (_jsx("span", { className: "tui-move-handle__lock", "aria-hidden": "true", children: _jsx(Icon, { name: "system/lock" }) })) : (_jsxs(_Fragment, { children: [hasIndex && (_jsx("span", { className: "tui-move-handle__index", "aria-hidden": "true", children: index })), _jsx("button", { type: "button", className: "tui-move-handle__handle", "data-role": "drag-handle", "aria-label": resolvedDragLabel, tabIndex: hasArrows ? -1 : 0, ...restDragProps, children: _jsx(Icon, { name: "system/handle-alt" }) })] })) }), onMoveDown && (_jsx("button", { type: "button", className: "tui-move-handle__down", "data-direction": "down", "aria-label": labels?.moveDown ?? 'Move down', disabled: locked || !canMoveDown, onClick: onMoveDown, children: _jsx(Icon, { name: "system/chevron-down" }) }))] }));
+    return (_jsxs("div", { ref: mergedRef, role: "group", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": locked ? lockedDescId : undefined, "aria-disabled": locked || undefined, className: cx('tui-move-handle', `is-size-${size}`, locked && 'is-locked', hasIndex && 'has-index', className), children: [locked && (_jsx("span", { id: lockedDescId, className: "tui-visually-hidden", children: resolvedLockedDesc })), onMoveUp && (_jsx("button", { type: "button", className: "tui-move-handle__up", "data-direction": "up", "aria-label": labels?.moveUp ?? 'Move up', disabled: locked || !canMoveUp, onClick: onMoveUp, children: _jsx(Icon, { name: "system/chevron-up" }) })), _jsx("div", { className: "tui-move-handle__center", children: showLockIcon ? (_jsx("span", { className: "tui-move-handle__lock", "aria-hidden": "true", children: _jsx(Icon, { name: "system/lock" }) })) : (_jsxs(_Fragment, { children: [hasIndex && (_jsx("span", { className: "tui-move-handle__index", "aria-hidden": "true", children: index })), _jsx("button", { type: "button", className: "tui-move-handle__handle", "data-role": "drag-handle", "aria-label": resolvedDragLabel, tabIndex: hasArrows ? -1 : 0, ...restDragProps, children: _jsx(Icon, { name: "system/handle-alt" }) })] })) }), onMoveDown && (_jsx("button", { type: "button", className: "tui-move-handle__down", "data-direction": "down", "aria-label": labels?.moveDown ?? 'Move down', disabled: locked || !canMoveDown, onClick: onMoveDown, children: _jsx(Icon, { name: "system/chevron-down" }) }))] }));
 });

package/components/MultiSelect/MultiSelect.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import React, { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, cloneElement, isValidElement, } from 'react';
+import { isDev } from '../../utils/is-dev.js';
 import { useFloating, offset, flip, shift, size as sizeMiddleware, autoUpdate, FloatingPortal, useDismiss, useInteractions, useListNavigation, useTypeahead, useRole, useClick, } from '@floating-ui/react';
 import { cx } from '../../utils/cx.js';
 import { getPortalRootFor } from '../../utils/portal.js';
@@ -549,7 +550,7 @@ function MultiSelectOptionComponent({ value: optionValue, disabled = false, text
     const textValue = explicitTextValue ?? (typeof children === 'string' ? children : '');
     // Warn in dev if textValue couldn't be derived
     useEffect(() => {
-        if (import.meta.env.DEV && !textValue) {
+        if (isDev() && !textValue) {
             console.warn(`MultiSelect.Option with value="${optionValue}" has no textValue. Provide textValue prop when children is not a string.`);
         }
     }, [textValue, optionValue]);

package/components/Progress/Progress.js

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import React from 'react';
 import { useProgressSegments } from './useProgressSegments.js';
 import { cx } from '../../utils/cx.js';
+import { isDev } from '../../utils/is-dev.js';
 // =============================================================================
 // COMPONENT
 // =============================================================================
@@ -23,7 +24,7 @@ export function Progress(props) {
     // Calculate percentages for standard mode
     const pct = Math.max(0, Math.min(100, (value / max) * 100));
     // Dev warning: inside position only supports labelStart (or children)
-    if (import.meta.env.DEV && labelPosition === 'inside' && labelStart && labelEnd) {
+    if (isDev() && labelPosition === 'inside' && labelStart && labelEnd) {
         console.warn('Progress: labelPosition="inside" only supports a single label. ' +
             'labelEnd will be ignored. Use labelStart or children for inside content.');
     }

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 }) }));
 }

package/components/Radio/types.d.ts

@@ -10,14 +10,24 @@ export type RadioGroupProps = {
     loop?: boolean;
     'aria-label'?: string;
     'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: boolean | 'true' | 'false';
+    'aria-required'?: boolean | 'true' | 'false';
     className?: string;
     children: ReactNode;
 };
 export type RadioProps = {
     value: OptionValue;
     label?: ReactNode;
+    /**
+     * Description text displayed below the label.
+     */
+    description?: string;
     disabled?: boolean;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
     className?: string;
+    children?: ReactNode;
 };
 export type RadioItemRecord = RovingItemRecord;
 export type RadioGroupContextValue = {

package/components/Select/Select.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import React, { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, cloneElement, isValidElement, } from 'react';
+import { isDev } from '../../utils/is-dev.js';
 import { useFloating, offset, flip, shift, size as sizeMiddleware, autoUpdate, FloatingPortal, useDismiss, useInteractions, useListNavigation, useTypeahead, useRole, useClick, } from '@floating-ui/react';
 import { cx } from '../../utils/cx.js';
 import { toKey } from '../../utils/value-key.js';
@@ -435,7 +436,7 @@ function SelectOptionComponent({ value: optionValue, disabled = false, textValue
     const textValue = explicitTextValue ?? (typeof children === 'string' ? children : '');
     // Warn in dev if textValue couldn't be derived
     useEffect(() => {
-        if (import.meta.env.DEV && !textValue) {
+        if (isDev() && !textValue) {
             console.warn(`Select.Option with value="${optionValue}" has no textValue. Provide textValue prop when children is not a string.`);
         }
     }, [textValue, optionValue]);

package/components/StepList/StepList.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from 'react';
 import { cx } from '../../utils/cx.js';
+import { isDev } from '../../utils/is-dev.js';
 import { StepListContext, useStepListContext } from './StepListContext.js';
 import { StepIndicator } from '../StepIndicator/index.js';
 // =============================================================================
@@ -9,7 +10,7 @@ import { StepIndicator } from '../StepIndicator/index.js';
 function StepListRoot(props) {
     const { 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ariaCurrent = 'step', current, onSelect, children, className, } = props;
     // Dev warning for missing nav label
-    if (import.meta.env.DEV && !ariaLabel && !ariaLabelledBy) {
+    if (isDev() && !ariaLabel && !ariaLabelledBy) {
         console.warn('StepList: Navigation landmark requires a label. ' +
             'Provide either `aria-label` or `aria-labelledby` prop for screen reader users.');
     }