@tangible/ui 0.0.4 → 0.0.6

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.d.ts

@@ -10,7 +10,7 @@ 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;
 }

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: "lg", 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: [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}`;
@@ -176,7 +247,7 @@ function AccordionTrigger({ children, className }) {
 function AccordionPanel({ landmark = false, children, className }) {
     const { triggerId, panelId, isOpen } = useAccordionItemContext();
     const state = isOpen ? 'open' : 'closed';
-    return (_jsx("div", { id: panelId, role: landmark ? 'region' : undefined, "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;
 };
@@ -40,7 +47,17 @@ export type AccordionItemProps = {
     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 = {
@@ -54,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/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';
@@ -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/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/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.');
     }