@tangible/ui 0.0.2 → 0.0.4

package/components/Dropdown/Dropdown.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { useCallback, useEffect, useId, useMemo, useRef, useState, cloneElement, isValidElement, Children, } from 'react';
+import React, { useCallback, useEffect, useLayoutEffect, useId, useMemo, useRef, useState, cloneElement, isValidElement, Children, } from 'react';
 import { useFloating, offset, flip, shift, autoUpdate, FloatingPortal, useDismiss, useInteractions, useListNavigation, useRole, FloatingFocusManager, } from '@floating-ui/react';
 import { cx } from '../../utils/cx.js';
 import { getPortalRootFor } from '../../utils/portal.js';
@@ -25,6 +25,7 @@ function DropdownRoot({ open: controlledOpen, onOpenChange, defaultOpen = false,
     }, [isControlled, onOpenChange]);
     const triggerRef = useRef(null);
     const contentId = useId();
+    const openedVia = useRef(null);
     // Focus restoration: track if we need to restore focus on close
     const shouldRestoreFocus = useRef(false);
     const prevOpen = useRef(open);
@@ -47,6 +48,7 @@ function DropdownRoot({ open: controlledOpen, onOpenChange, defaultOpen = false,
         contentId,
         activeIndex,
         setActiveIndex,
+        openedVia,
     }), [open, setOpen, contentId, activeIndex]);
     return (_jsx(DropdownContext.Provider, { value: contextValue, children: children }));
 }
@@ -55,24 +57,28 @@ DropdownRoot.displayName = 'Dropdown';
 // DropdownTrigger
 // =============================================================================
 function DropdownTriggerComponent({ asChild = false, children }) {
-    const { open, setOpen, triggerRef, contentId } = useDropdownContext();
+    const { open, setOpen, triggerRef, openedVia } = useDropdownContext();
     const handleClick = useCallback(() => {
+        openedVia.current = 'click';
         setOpen(!open);
-    }, [open, setOpen]);
+    }, [open, setOpen, openedVia]);
     const handleKeyDown = useCallback((e) => {
         if (e.key === 'Enter' || e.key === ' ') {
             e.preventDefault();
+            openedVia.current = 'click';
             setOpen(!open);
         }
         else if (e.key === 'ArrowDown') {
             e.preventDefault();
+            openedVia.current = 'ArrowDown';
             setOpen(true);
         }
         else if (e.key === 'ArrowUp') {
             e.preventDefault();
+            openedVia.current = 'ArrowUp';
             setOpen(true);
         }
-    }, [open, setOpen]);
+    }, [open, setOpen, openedVia]);
     // Merge child ref with our triggerRef
     const setRefs = useCallback((node) => {
         triggerRef.current = node;
@@ -91,7 +97,6 @@ function DropdownTriggerComponent({ asChild = false, children }) {
         onKeyDown: handleKeyDown,
         'aria-haspopup': 'menu',
         'aria-expanded': open,
-        'aria-controls': open ? contentId : undefined,
         'data-dropdown-open': open || undefined,
     };
     if (asChild && isValidElement(children)) {
@@ -108,7 +113,7 @@ DropdownTriggerComponent.displayName = 'Dropdown.Trigger';
 // DropdownContent
 // =============================================================================
 function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset = 4, className, style, children, }) {
-    const { open, setOpen, triggerRef, contentId, activeIndex, setActiveIndex } = useDropdownContext();
+    const { open, setOpen, triggerRef, contentId, activeIndex, setActiveIndex, openedVia } = useDropdownContext();
     const listRef = useRef([]);
     const { refs, floatingStyles, context } = useFloating({
         placement: toPlacement(side, align),
@@ -123,19 +128,41 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
             refs.setReference(triggerRef.current);
         }
     }, [triggerRef, refs]);
-    // Collect disabled indices from children for keyboard navigation
-    const disabledIndices = useMemo(() => {
-        const indices = [];
-        Children.forEach(children, (child, index) => {
-            if (isValidElement(child)) {
-                const props = child.props;
-                if (props.disabled) {
-                    indices.push(index);
-                }
+    // Classify children: count navigable items and collect disabled indices.
+    // Separator and Header sub-components are non-navigable.
+    const { disabledIndices, totalItemCount } = useMemo(() => {
+        const disabled = [];
+        let itemIdx = 0;
+        Children.forEach(children, (child) => {
+            if (!isValidElement(child))
+                return;
+            // Skip non-navigable sub-components
+            const childType = child.type;
+            if (childType === DropdownSeparatorComponent ||
+                childType === DropdownHeaderComponent) {
+                return;
             }
+            const props = child.props;
+            if (props.disabled) {
+                disabled.push(itemIdx);
+            }
+            itemIdx++;
         });
-        return indices;
+        return { disabledIndices: disabled, totalItemCount: itemIdx };
     }, [children]);
+    // ArrowUp focus-last: set activeIndex to last valid item before paint
+    useLayoutEffect(() => {
+        if (open && openedVia.current === 'ArrowUp') {
+            let lastValid = totalItemCount - 1;
+            while (lastValid >= 0 && disabledIndices.includes(lastValid)) {
+                lastValid--;
+            }
+            if (lastValid >= 0) {
+                setActiveIndex(lastValid);
+            }
+            openedVia.current = null;
+        }
+    }, [open, openedVia, totalItemCount, disabledIndices, setActiveIndex]);
     const dismiss = useDismiss(context);
     const role = useRole(context, { role: 'menu' });
     const listNavigation = useListNavigation(context, {
@@ -155,25 +182,34 @@ function DropdownContentComponent({ side = 'bottom', align = 'start', sideOffset
     const portalRoot = getPortalRootFor(triggerRef.current);
     if (!open)
         return null;
-    // Clone children to inject item props and role
-    const items = Children.map(children, (child, index) => {
+    // Clone children to inject item props and role.
+    // Non-navigable children (Separator, Header) are rendered as-is.
+    let itemIndex = 0;
+    const items = Children.map(children, (child) => {
         if (!isValidElement(child))
             return child;
+        // Non-navigable sub-components — render without list navigation props
+        const childType = child.type;
+        if (childType === DropdownSeparatorComponent ||
+            childType === DropdownHeaderComponent) {
+            return child;
+        }
+        const currentIndex = itemIndex++;
         const childProps = child.props;
         const isDisabled = childProps.disabled === true;
         const existingRole = childProps.role;
         return cloneElement(child, {
             ...getItemProps({
                 ref: (node) => {
-                    listRef.current[index] = node;
+                    listRef.current[currentIndex] = node;
                 },
                 // Disabled items get tabIndex -1 always
-                tabIndex: isDisabled ? -1 : (activeIndex === index ? 0 : -1),
+                tabIndex: isDisabled ? -1 : (activeIndex === currentIndex ? 0 : -1),
             }),
             // Add menuitem role if not already specified
             role: existingRole || 'menuitem',
             'aria-disabled': isDisabled || undefined,
-            'data-active': activeIndex === index || undefined,
+            'data-active': activeIndex === currentIndex || undefined,
         });
     });
     return (_jsx(FloatingPortal, { root: portalRoot, children: _jsx(FloatingFocusManager, { context: context, modal: false, initialFocus: -1, children: _jsx("div", { ref: refs.setFloating, id: contentId, className: cx('tui-dropdown', className), style: {
@@ -190,31 +226,51 @@ DropdownContentComponent.displayName = 'Dropdown.Content';
  * When href is provided, renders as an anchor.
  */
 function DropdownItemComponent({ onSelect, href, target = '_self', disabled = false, keepOpen = false, className, children, ...props }) {
-    const { setOpen, triggerRef } = useDropdownContext();
+    const { setOpen } = useDropdownContext();
     const handleClick = useCallback(() => {
         if (disabled)
             return;
         onSelect?.();
         if (!keepOpen) {
+            // Focus restoration is handled by DropdownRoot's useEffect on `open`
             setOpen(false);
-            // Explicitly restore focus after programmatic close
-            // Small delay to let the dropdown unmount first
-            requestAnimationFrame(() => {
-                triggerRef.current?.focus();
-            });
         }
-    }, [disabled, onSelect, keepOpen, setOpen, triggerRef]);
+    }, [disabled, onSelect, keepOpen, setOpen]);
     return (_jsx(Button, { ...props, variant: "ghost", href: disabled ? undefined : href, target: href ? target : undefined, disabled: disabled, onClick: handleClick, className: cx('tui-dropdown__item', className), children: children }));
 }
 DropdownItemComponent.displayName = 'Dropdown.Item';
+// =============================================================================
+// DropdownSeparator
+// =============================================================================
+/**
+ * Non-interactive separator for visually grouping menu items.
+ */
+function DropdownSeparatorComponent({ className }) {
+    return (_jsx("hr", { role: "separator", className: cx('tui-dropdown__separator', className) }));
+}
+DropdownSeparatorComponent.displayName = 'Dropdown.Separator';
+// =============================================================================
+// DropdownHeader
+// =============================================================================
+/**
+ * Non-interactive section label for grouping menu items.
+ */
+function DropdownHeaderComponent({ className, children }) {
+    return (_jsx("div", { role: "presentation", className: cx('tui-dropdown__header', className), children: children }));
+}
+DropdownHeaderComponent.displayName = 'Dropdown.Header';
 export const Dropdown = DropdownRoot;
 Dropdown.Trigger = DropdownTriggerComponent;
 Dropdown.Content = DropdownContentComponent;
 Dropdown.Item = DropdownItemComponent;
+Dropdown.Separator = DropdownSeparatorComponent;
+Dropdown.Header = DropdownHeaderComponent;
 // Named exports for direct imports
 export const DropdownTrigger = DropdownTriggerComponent;
 export const DropdownContent = DropdownContentComponent;
 export const DropdownItem = DropdownItemComponent;
+export const DropdownSeparator = DropdownSeparatorComponent;
+export const DropdownHeader = DropdownHeaderComponent;
 // Hook for advanced use cases (custom items that need to close the dropdown)
 // eslint-disable-next-line react-refresh/only-export-components
 export { useDropdownContext as useDropdown } from './DropdownContext.js';

package/components/Dropdown/index.d.ts

@@ -1,2 +1,2 @@
-export { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, useDropdown, } from './Dropdown';
-export type { DropdownProps, DropdownTriggerProps, DropdownContentProps, DropdownItemProps, } from './types';
+export { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownSeparator, DropdownHeader, useDropdown, } from './Dropdown';
+export type { DropdownProps, DropdownTriggerProps, DropdownContentProps, DropdownItemProps, DropdownSeparatorProps, DropdownHeaderProps, } from './types';

package/components/Dropdown/index.js

@@ -1 +1 @@
-export { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, useDropdown, } from './Dropdown.js';
+export { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownSeparator, DropdownHeader, useDropdown, } from './Dropdown.js';

package/components/Dropdown/types.d.ts

@@ -88,6 +88,19 @@ export type DropdownItemProps = {
     className?: string;
     children: React.ReactNode;
 };
+export type DropdownSeparatorProps = {
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+};
+export type DropdownHeaderProps = {
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    children: React.ReactNode;
+};
 export type DropdownContextValue = {
     open: boolean;
     setOpen: (open: boolean) => void;
@@ -95,6 +108,8 @@ export type DropdownContextValue = {
     contentId: string;
     activeIndex: number | null;
     setActiveIndex: (index: number | null) => void;
+    /** Tracks how the dropdown was opened (e.g. 'ArrowUp') for initial focus. */
+    openedVia: React.MutableRefObject<string | null>;
 };
 /**
  * Convert side + align to Floating UI placement.

package/components/IconButton/IconButton.js

@@ -17,10 +17,11 @@ import { getSafeRel } from '../../utils/polymorphic.js';
 //
 // =============================================================================
 export const IconButton = forwardRef((props, ref) => {
-    const { icon, label, size = 'sm', theme = 'secondary', variant = 'ghost', disabled = false, loading = false, pressed, showTooltip = false, tooltipSide = 'top', className, ...rest } = props;
+    const { icon, label, size = 'sm', theme = 'secondary', variant = 'ghost', disabled = false, loading = false, loadingLabel: loadingLabelProp, pressed, shape = 'square', showTooltip = false, tooltipSide = 'top', className, ...rest } = props;
     const isLink = typeof rest.href === 'string';
     const isDisabled = disabled || loading;
-    const classes = cx('tui-icon-button', `is-size-${size}`, `is-theme-${theme}`, `is-style-${variant}`, isDisabled && 'is-disabled', className);
+    const resolvedLabel = loading ? (loadingLabelProp ?? `${label}, loading`) : label;
+    const classes = cx('tui-icon-button', `is-size-${size}`, `is-theme-${theme}`, `is-style-${variant}`, isDisabled && 'is-disabled', shape === 'circle' && 'is-shape-circle', className);
     const iconContent = (_jsxs(_Fragment, { children: [_jsx(Icon, { name: icon }), loading && _jsx("span", { className: "tui-icon-button__spinner", "aria-hidden": "true" })] }));
     // Render the base element (button or anchor)
     let element;
@@ -35,11 +36,11 @@ export const IconButton = forwardRef((props, ref) => {
             }
             onClick?.(e);
         };
-        element = (_jsx("a", { ref: ref, href: isDisabled ? undefined : href, className: classes, "aria-label": label, "aria-disabled": isDisabled || undefined, "aria-busy": loading || undefined, tabIndex: isDisabled ? -1 : tabIndex, onClick: handleClick, target: target, rel: safeRel, ...anchorRest, children: iconContent }));
+        element = (_jsx("a", { ref: ref, href: isDisabled ? undefined : href, className: classes, "aria-label": resolvedLabel, "aria-disabled": isDisabled || undefined, "aria-busy": loading || undefined, tabIndex: isDisabled ? -1 : tabIndex, onClick: handleClick, target: target, rel: safeRel, ...anchorRest, children: iconContent }));
     }
     else {
         const buttonRest = rest;
-        element = (_jsx("button", { ref: ref, type: buttonRest.type ?? 'button', className: classes, "aria-label": label, disabled: isDisabled, "aria-busy": loading || undefined, "aria-pressed": pressed, ...buttonRest, children: iconContent }));
+        element = (_jsx("button", { ref: ref, type: buttonRest.type ?? 'button', className: classes, "aria-label": resolvedLabel, disabled: isDisabled, "aria-busy": loading || undefined, "aria-pressed": pressed, ...buttonRest, children: iconContent }));
     }
     // Wrap in tooltip if requested
     if (showTooltip) {

package/components/IconButton/index.d.ts

@@ -1,2 +1,2 @@
 export { IconButton } from './IconButton';
-export type { IconButtonProps, Size, Theme, Variant } from './types';
+export type { IconButtonProps, Shape, Size, Theme, Variant } from './types';

package/components/IconButton/types.d.ts

@@ -3,6 +3,7 @@ import type { Size, ThemeIntent } from '../../types';
 export type { Size };
 export type Theme = ThemeIntent;
 export type Variant = 'solid' | 'outline' | 'ghost';
+export type Shape = 'square' | 'circle';
 type IconButtonBaseProps = {
     /**
      * Icon to display. Required — this is the button's visual content.
@@ -17,7 +18,10 @@ type IconButtonBaseProps = {
     label: string;
     /**
      * Size of the button.
-     * - `'xs'`: 24px
+     * - `'xs'`: 24px — below WCAG 2.5.8 minimum target size (24×24 CSS px).
+     *   Use only in dense, mouse-first UIs (toolbars, table rows) where touch
+     *   is not expected. Consider pairing with adequate spacing or a larger
+     *   touch target via padding/margin.
      * - `'sm'`: 32px (default)
      * - `'md'`: 40px
      * - `'lg'`: 48px
@@ -35,7 +39,9 @@ type IconButtonBaseProps = {
      * Visual style variant.
      * - `'solid'`: Filled background
      * - `'outline'`: Border only, transparent background
-     * - `'ghost'`: No border or background, icon only
+     * - `'ghost'`: No border or background, icon only — has no at-rest visual
+     *   affordance. Best suited for toolbar groups, icon bars, or other contexts
+     *   where surrounding UI makes the interactive nature obvious.
      * @default 'ghost'
      */
     variant?: Variant;
@@ -47,6 +53,11 @@ type IconButtonBaseProps = {
      * Loading state — shows spinner, disables interaction.
      */
     loading?: boolean;
+    /**
+     * Accessible label override during loading state. For i18n support.
+     * @default `${label}, loading` (English)
+     */
+    loadingLabel?: string;
     /**
      * Pressed state for toggle buttons.
      * When true, applies aria-pressed="true" and active styling.
@@ -55,8 +66,11 @@ type IconButtonBaseProps = {
     pressed?: boolean;
     /**
      * Show the label as a tooltip on hover.
-     * Since icon-only buttons have no visible text, this helps sighted
-     * users discover what the button does.
+     * Since icon-only buttons have no visible text, enabling this helps
+     * sighted users discover what the button does. Recommended for most
+     * standalone icon buttons. Can be omitted in toolbars where a shared
+     * Tooltip provider handles it, or where adjacent visible text already
+     * communicates the action.
      * @default false
      */
     showTooltip?: boolean;
@@ -65,6 +79,12 @@ type IconButtonBaseProps = {
      * @default 'top'
      */
     tooltipSide?: 'top' | 'right' | 'bottom' | 'left';
+    /**
+     * Button shape. Use `'circle'` for avatar-adjacent actions, FABs,
+     * or anywhere a round affordance is expected.
+     * @default 'square'
+     */
+    shape?: Shape;
     /**
      * Additional CSS class names.
      */

package/components/Modal/Modal.d.ts

@@ -7,6 +7,8 @@ export type ModalProps = {
     size?: Size;
     stickyHead?: boolean;
     stickyFoot?: boolean;
+    /** ID of the element that labels this dialog. Omitting this leaves the dialog
+     *  without an accessible name, which violates WCAG 4.1.2 (Name, Role, Value). */
     'aria-labelledby'?: string;
     'aria-describedby'?: string;
     initialFocusSelector?: string;
@@ -30,11 +32,23 @@ type ModalSlotProps = {
     className?: string;
     children?: React.ReactNode;
 } & React.HTMLAttributes<HTMLDivElement>;
-declare function ModalHead({ className, children, ...rest }: ModalSlotProps): import("react/jsx-runtime").JSX.Element;
+type ModalHeadProps = ModalSlotProps & {
+    /** Optional subtitle displayed below the title in smaller, muted text. */
+    subtitle?: React.ReactNode;
+    /** Optional icon displayed to the left of the title/subtitle block. */
+    icon?: React.ReactNode;
+};
+declare function ModalHead({ className, children, subtitle, icon, ...rest }: ModalHeadProps): import("react/jsx-runtime").JSX.Element;
 declare namespace ModalHead {
     var displayName: string;
 }
-declare function ModalBody({ className, children, ...rest }: ModalSlotProps): import("react/jsx-runtime").JSX.Element;
+type ModalBodyProps = ModalSlotProps & {
+    /** Accessible label for the scrollable region. Passed to the inner scroll container.
+     *  When the body content overflows, screen readers announce this as the region name.
+     *  Omitting this on a scrollable modal body leaves the scroll region unlabelled. */
+    scrollLabel?: string;
+};
+declare function ModalBody({ className, children, scrollLabel, ...rest }: ModalBodyProps): import("react/jsx-runtime").JSX.Element;
 declare namespace ModalBody {
     var displayName: string;
 }

package/components/Modal/Modal.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { cx } from '../../utils/cx.js';
-import { PREFIX } from '../../constants.js';
+import { isDev } from '../../utils/is-dev.js';
 import { getPortalRootFor } from '../../utils/portal.js';
 import { useFocusTrap, getInitialFocus } from '../../utils/focus-trap.js';
 import { ModalContext, useModalContext } from './context.js';
@@ -11,7 +11,16 @@ const isBrowser = typeof document !== 'undefined';
 function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-labelledby': labelledBy, 'aria-describedby': describedBy, initialFocusSelector, container, showCloseButton, closeLabel = 'Close', closeOnBackdropClick = true, closeOnEscape = true, children, }) {
     const dialogRef = useRef(null);
     const restoreRef = useRef(null);
+    const warnedRef = useRef(false);
     const [mount, setMount] = useState(null);
+    // Dev warning: Modal should have an accessible name
+    useEffect(() => {
+        if (isDev() && !warnedRef.current && open && !labelledBy) {
+            warnedRef.current = true;
+            console.warn('[TUI Modal] Missing `aria-labelledby` prop. Dialogs should reference a visible heading ' +
+                'to provide an accessible name (WCAG 4.1.2).');
+        }
+    }, [open, labelledBy]);
     // Capture trigger element and compute portal mount point when modal opens.
     // Uses useLayoutEffect to run before paint — both renders complete before
     // the browser shows anything, so no visible delay.
@@ -50,6 +59,36 @@ function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-l
             document.body.classList.remove('tui-modal-open');
         };
     }, [open]);
+    // Inert sibling trees so screen readers cannot escape the dialog.
+    // aria-modal alone is unreliable — NVDA/JAWS virtual cursor can still
+    // reach background content via arrow keys and document-structure shortcuts.
+    useEffect(() => {
+        if (!open || !mount)
+            return;
+        const inerted = [];
+        // Walk from the portal root up to <body>, inerting siblings at each level.
+        let node = mount;
+        while (node && node !== document.body) {
+            const parent = node.parentElement;
+            if (parent) {
+                const children = Array.from(parent.children);
+                for (const sibling of children) {
+                    if (sibling === node || sibling.tagName === 'SCRIPT' || sibling.tagName === 'STYLE')
+                        continue;
+                    if (!sibling.hasAttribute('inert')) {
+                        sibling.inert = true;
+                        inerted.push(sibling);
+                    }
+                }
+            }
+            node = parent;
+        }
+        return () => {
+            for (const el of inerted) {
+                el.inert = false;
+            }
+        };
+    }, [open, mount]);
     // Focus trap (handles Tab cycling and ESC to close).
     useFocusTrap(dialogRef, {
         // Modal mount is two-phase (capture portal root, then render portal).
@@ -65,18 +104,6 @@ function ModalRoot({ open, onClose, size = 'md', stickyHead, stickyFoot, 'aria-l
         const dialog = dialogRef.current;
         if (!dialog)
             return;
-        // Ensure scrollable body section is keyboard-focusable for a11y audits.
-        // WCAG 4.1.2: focusable elements need accessible names.
-        const scrollables = dialog.querySelectorAll(`.${PREFIX}-modal__body-inner, [data-scrollable="true"]`);
-        scrollables.forEach((el) => {
-            const hasOverflow = el.scrollHeight > el.clientHeight || el.scrollWidth > el.clientWidth;
-            if (hasOverflow && !el.hasAttribute('tabindex')) {
-                el.setAttribute('tabindex', '0');
-                if (!el.hasAttribute('aria-label') && !el.hasAttribute('aria-labelledby')) {
-                    el.setAttribute('aria-label', 'Scrollable content');
-                }
-            }
-        });
         // Initial focus target.
         let target = null;
         if (initialFocusSelector) {
@@ -110,15 +137,13 @@ function ModalClose({ label = 'Close', className }) {
     return (_jsx(IconButton, { icon: "system/close", label: label, variant: "ghost", size: "sm", onClick: onClose, className: cx('tui-modal__close', className), showTooltip: true }));
 }
 ModalClose.displayName = 'Modal.Close';
-function ModalHead({ className, children, ...rest }) {
-    return (_jsx("div", { className: cx('tui-modal__head', className), ...rest, children: children }));
+function ModalHead({ className, children, subtitle, icon, ...rest }) {
+    const hasIcon = !!icon;
+    return (_jsxs("div", { className: cx('tui-modal__head', hasIcon && 'has-icon', className), ...rest, children: [hasIcon && _jsx("div", { className: "tui-modal__head-icon", children: icon }), _jsxs("div", { className: "tui-modal__head-content", children: [children, subtitle && _jsx("div", { className: "tui-modal__head-subtitle", children: subtitle })] })] }));
 }
 ModalHead.displayName = 'Modal.Head';
-// =============================================================================
-// Modal.Body — Scrollable content area with min-height
-// =============================================================================
-function ModalBody({ className, children, ...rest }) {
-    return (_jsx("div", { className: cx('tui-modal__body', className), ...rest, children: _jsx("div", { className: "tui-modal__body-inner", children: children }) }));
+function ModalBody({ className, children, scrollLabel, ...rest }) {
+    return (_jsx("div", { className: cx('tui-modal__body', className), ...rest, children: _jsx("div", { className: "tui-modal__body-inner", "aria-label": scrollLabel, tabIndex: scrollLabel ? 0 : undefined, role: scrollLabel ? 'region' : undefined, children: children }) }));
 }
 ModalBody.displayName = 'Modal.Body';
 // =============================================================================

package/components/MoveHandle/MoveHandle.d.ts

@@ -0,0 +1,2 @@
+import type { MoveHandleProps } from './types';
+export declare const MoveHandle: import("react").ForwardRefExoticComponent<MoveHandleProps & import("react").RefAttributes<HTMLElement>>;

package/components/MoveHandle/MoveHandle.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useCallback, useEffect, useId, useRef } from 'react';
+import { cx } from '../../utils/cx.js';
+import { isDev } from '../../utils/is-dev.js';
+import { Icon } from '../Icon/index.js';
+// =============================================================================
+// MoveHandle Component
+// =============================================================================
+//
+// Compact reorder control for sortable lists. Shows a drag handle with optional
+// up/down chevron buttons and a position index badge.
+//
+// When `index` is provided, shows the number at rest and swaps to the drag
+// handle icon on hover/focus-within (CSS-driven, no JS state).
+//
+// Forwards ref to the root element (div for full, button for handle).
+//
+// Modes:
+//   full    — Background panel with arrows, index, lock (default)
+//   handle  — Bare drag icon button, no chrome
+//
+// CSS token API (never defined, read via fallback):
+//   --tui-move-handle-size       Override container size
+//   --tui-move-handle-icon-size  Override icon size
+//
+// =============================================================================
+export const MoveHandle = forwardRef(function MoveHandle({ mode = 'full', size = 'md', index, locked = false, onMoveUp, onMoveDown, canMoveUp = true, canMoveDown = true, labels, dragHandleProps, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, }, ref) {
+    // All hooks must be called unconditionally (rules of hooks)
+    const innerRef = useRef(null);
+    const mergedRef = useCallback((node) => {
+        innerRef.current = node;
+        if (typeof ref === 'function')
+            ref(node);
+        else if (ref)
+            ref.current = node;
+    }, [ref]);
+    const hasWarnedRef = useRef(false);
+    useEffect(() => {
+        if (mode === 'handle')
+            return;
+        if (hasWarnedRef.current)
+            return;
+        if (isDev() && !ariaLabel && !ariaLabelledBy) {
+            console.warn('MoveHandle: Missing accessible name. Provide aria-label or aria-labelledby.');
+            hasWarnedRef.current = true;
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const lockedDescId = useId();
+    // Focus recovery: when a move button becomes disabled after a reorder,
+    // redirect focus to the opposite button or drag handle
+    useEffect(() => {
+        if (mode === 'handle')
+            return;
+        const group = innerRef.current;
+        if (!group)
+            return;
+        const active = document.activeElement;
+        if (active instanceof HTMLButtonElement &&
+            active.disabled &&
+            group.contains(active)) {
+            const fallback = group.querySelector('[data-direction="up"]:not(:disabled), [data-direction="down"]:not(:disabled)') ??
+                group.querySelector('[data-role="drag-handle"]');
+            fallback?.focus();
+        }
+    }, [mode, canMoveUp, canMoveDown]);
+    // 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
+    const { 'aria-label': _dhLabel, ...restDragProps } = dragHandleProps ?? {};
+    // ----- Handle mode: just the drag icon button -----
+    // Uses ref directly (not mergedRef) — innerRef is unused for this path.
+    // Focus recovery and dev warning effects early-return for handle mode.
+    if (mode === 'handle') {
+        return (_jsx("button", { ref: ref, type: "button", className: cx('tui-move-handle', 'is-handle', className), "aria-label": resolvedDragLabel, ...restDragProps, children: _jsx(Icon, { name: "system/drag" }) }));
+    }
+    // ----- Full mode -----
+    const hasIndex = index != null;
+    const hasArrows = !!(onMoveUp || onMoveDown);
+    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" }) }))] }));
+});

package/components/MoveHandle/index.d.ts

@@ -0,0 +1,2 @@
+export { MoveHandle } from './MoveHandle';
+export type { MoveHandleLabels, MoveHandleProps, MoveHandleSize, MoveHandleMode } from './types';

package/components/MoveHandle/index.js

@@ -0,0 +1 @@
+export { MoveHandle } from './MoveHandle.js';