@tangible/ui 0.0.1 → 0.0.3

package/components/Combobox/types.d.ts

@@ -0,0 +1,204 @@
+import type { FloatingContext, ReferenceType } from '@floating-ui/react';
+import type { RefObject, CSSProperties, MutableRefObject } from 'react';
+import type { SizeStandard } from '../../types/sizes';
+import type { OptionValue } from '../../utils/value-key';
+/**
+ * Controls when filtering should be active.
+ * - 'always': Consumer filters whenever inputValue changes (default)
+ * - 'when-searching': Query becomes empty when not actively searching,
+ *   allowing consumers to show all options when browsing a selection
+ */
+export type FilterMode = 'always' | 'when-searching';
+export type ComboboxProps = {
+    /**
+     * Control size.
+     * @default 'md'
+     */
+    size?: SizeStandard;
+    /**
+     * Controlled selected value.
+     */
+    value?: OptionValue;
+    /**
+     * Default value for uncontrolled usage.
+     */
+    defaultValue?: OptionValue;
+    /**
+     * Callback when selection changes.
+     * Called with the option's value when user selects, or undefined when cleared.
+     * Does NOT mutate inputValue — consumer should update inputValue in handler if desired.
+     */
+    onValueChange?: (value: OptionValue | undefined) => void;
+    /**
+     * Controlled input value for search/filter.
+     */
+    inputValue?: string;
+    /**
+     * Callback when input value changes (typing, clear).
+     */
+    onInputChange?: (value: string) => void;
+    /**
+     * Controls filtering behavior.
+     * - 'always': Filter on inputValue at all times (default)
+     * - 'when-searching': Query is empty when not actively typing,
+     *   so consumers can show all options when user is browsing a selection
+     * @default 'always'
+     */
+    filterMode?: FilterMode;
+    /**
+     * Callback when the effective query changes.
+     * Query differs from inputValue when filterMode='when-searching':
+     * it becomes empty after selection to show all options.
+     */
+    onQueryChange?: (query: string) => void;
+    /**
+     * Controlled open state.
+     */
+    open?: boolean;
+    /**
+     * Default open state for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Callback when open state changes.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Whether the combobox is disabled.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Placeholder text for the input.
+     */
+    placeholder?: string;
+    /**
+     * Whether to open the listbox when the input receives focus.
+     * @default true
+     */
+    openOnFocus?: boolean;
+    /**
+     * Accessible name for the combobox.
+     */
+    'aria-label'?: string;
+    /**
+     * ID of element that labels this combobox.
+     */
+    'aria-labelledby'?: string;
+    /**
+     * Class name applied directly to the `<input>` element.
+     * Use for utilities like `tui-input-reset` that must target the input itself.
+     */
+    inputClassName?: string;
+    children: React.ReactNode;
+};
+export type ComboboxContentProps = {
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    children: React.ReactNode;
+};
+export type ComboboxOptionProps = {
+    /**
+     * The value for this option. Required and must be unique.
+     * Can be string or number.
+     */
+    value: OptionValue;
+    /**
+     * Whether this option is disabled.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text value used for display when selected.
+     * Required when children is not a string.
+     * If children is a string, defaults to that.
+     */
+    textValue?: string;
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    children: React.ReactNode;
+};
+export type ComboboxGroupProps = {
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    children: React.ReactNode;
+};
+export type ComboboxLabelProps = {
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    children: React.ReactNode;
+};
+/**
+ * Registration record for an option.
+ */
+export type RegisteredOption = {
+    value: OptionValue;
+    ref: RefObject<HTMLElement | null>;
+    disabled: boolean;
+    textValue: string;
+};
+/**
+ * Stable context: config, IDs, refs, and stable callbacks.
+ */
+export type ComboboxActionsContextValue = {
+    disabled: boolean;
+    placeholder: string;
+    openOnFocus: boolean;
+    inputId: string;
+    listboxId: string;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+    setOpen: (open: boolean) => void;
+    setInputValue: (value: string) => void;
+    selectOption: (value: OptionValue) => void;
+    registerOption: (option: RegisteredOption) => void;
+    unregisterOption: (value: OptionValue) => void;
+    refs: {
+        reference: React.RefObject<ReferenceType | null>;
+        floating: React.RefObject<HTMLElement | null>;
+        setReference: (node: ReferenceType | null) => void;
+        setFloating: (node: HTMLElement | null) => void;
+    };
+    inputRef: RefObject<HTMLInputElement | null>;
+    listRef: MutableRefObject<(HTMLElement | null)[]>;
+    getReferenceProps: (userProps?: React.HTMLProps<Element>) => Record<string, unknown>;
+    getFloatingProps: (userProps?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
+    getItemProps: (userProps?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
+};
+/**
+ * State context: values that change during interaction.
+ */
+export type ComboboxStateContextValue = {
+    open: boolean;
+    value: OptionValue | undefined;
+    inputValue: string;
+    /**
+     * The effective query to filter on.
+     * When filterMode='when-searching', this is empty after selection
+     * (allowing all options to show). Otherwise equals inputValue.
+     */
+    query: string;
+    activeIndex: number;
+    activeOptionId: string | undefined;
+    orderedOptions: RegisteredOption[];
+    floatingStyles: CSSProperties;
+    floatingContext: FloatingContext;
+};
+/**
+ * Combined context value.
+ */
+export type ComboboxContextValue = ComboboxActionsContextValue & ComboboxStateContextValue;
+export type ComboboxContentContextValue = {
+    listRef: MutableRefObject<(HTMLElement | null)[]>;
+    activeIndex: number;
+    orderedOptions: RegisteredOption[];
+};

package/components/Combobox/types.js

@@ -0,0 +1 @@
+export {};

package/components/Dropdown/Dropdown.js

@@ -204,7 +204,7 @@ function DropdownItemComponent({ onSelect, href, target = '_self', disabled = fa
             });
         }
     }, [disabled, onSelect, keepOpen, setOpen, triggerRef]);
-    return (_jsx(Button, { variant: "ghost", href: disabled ? undefined : href, target: href ? target : undefined, disabled: disabled, onClick: handleClick, className: cx('tui-dropdown__item', className), ...props, children: children }));
+    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';
 export const Dropdown = DropdownRoot;
@@ -216,4 +216,5 @@ export const DropdownTrigger = DropdownTriggerComponent;
 export const DropdownContent = DropdownContentComponent;
 export const DropdownItem = DropdownItemComponent;
 // 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/Field/Field.d.ts

@@ -0,0 +1,39 @@
+import React from 'react';
+export type FieldProps = {
+    /** Whether the field has an error state */
+    error?: boolean;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Whether the field is disabled */
+    disabled?: boolean;
+    /** Inline layout: label and control on same row */
+    inline?: boolean;
+    /** Additional class name for the field wrapper */
+    className?: string;
+    children?: React.ReactNode;
+};
+type LabelProps = React.LabelHTMLAttributes<HTMLLabelElement> & {
+    /** Visually hide the label while keeping it accessible */
+    hidden?: boolean;
+    className?: string;
+    children?: React.ReactNode;
+};
+type ControlProps = {
+    children: React.ReactElement;
+};
+type HelperTextProps = React.HTMLAttributes<HTMLDivElement> & {
+    className?: string;
+    children?: React.ReactNode;
+};
+type ErrorProps = React.HTMLAttributes<HTMLDivElement> & {
+    className?: string;
+    children?: React.ReactNode;
+};
+type FieldCompound = React.ForwardRefExoticComponent<FieldProps & React.RefAttributes<HTMLDivElement>> & {
+    Label: React.FC<LabelProps>;
+    Control: React.FC<ControlProps>;
+    HelperText: React.FC<HelperTextProps>;
+    Error: React.FC<ErrorProps>;
+};
+export declare const Field: FieldCompound;
+export {};

package/components/Field/Field.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { forwardRef, useId, useMemo, cloneElement, isValidElement, Children, } from 'react';
+import { cx } from '../../utils/cx.js';
+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 helperTextId = `${baseId}-helper`;
+    const errorId = `${baseId}-error`;
+    const contextValue = useMemo(() => ({
+        controlId,
+        helperTextId,
+        errorId,
+        hasError: error,
+        required,
+        disabled,
+    }), [controlId, 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 }) }));
+});
+// =============================================================================
+// Field.Label
+// =============================================================================
+function FieldLabel({ hidden = false, className, children, ...rest }) {
+    const { controlId, 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" })] }))] }));
+}
+FieldLabel.displayName = 'Field.Label';
+// =============================================================================
+// Field.Control
+// =============================================================================
+function FieldControl({ children }) {
+    const { controlId, 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');
+    }
+    const childProps = child.props;
+    // Build aria-describedby, merging with any existing value from child
+    // Per ARIA spec, referencing non-existent IDs is valid (AT ignores them)
+    const describedByParts = [];
+    if (typeof childProps['aria-describedby'] === 'string') {
+        describedByParts.push(childProps['aria-describedby']);
+    }
+    describedByParts.push(helperTextId);
+    if (hasError) {
+        describedByParts.push(errorId);
+    }
+    const describedBy = describedByParts.join(' ');
+    // Clone child with a11y props
+    // Note: aria-invalid and aria-required must be string "true", not boolean
+    return cloneElement(child, {
+        id: controlId,
+        'aria-describedby': describedBy,
+        'aria-invalid': hasError ? 'true' : undefined,
+        'aria-required': required ? 'true' : undefined,
+        disabled: disabled || childProps.disabled,
+    });
+}
+FieldControl.displayName = 'Field.Control';
+// =============================================================================
+// Field.HelperText
+// =============================================================================
+function FieldHelperText({ className, children, ...rest }) {
+    const { helperTextId } = useFieldContext();
+    if (!children)
+        return null;
+    const classes = cx('tui-field__helper', className);
+    return (_jsx("div", { id: helperTextId, className: classes, ...rest, children: children }));
+}
+FieldHelperText.displayName = 'Field.HelperText';
+// =============================================================================
+// Field.Error
+// =============================================================================
+function FieldError({ className, children, ...rest }) {
+    const { errorId, hasError } = useFieldContext();
+    // Only render if there's an error and content
+    if (!hasError || !children)
+        return null;
+    const classes = cx('tui-field__error', className);
+    // role="alert" implies aria-live="assertive" - no need to add aria-live
+    return (_jsx("div", { id: errorId, className: classes, role: "alert", ...rest, children: children }));
+}
+FieldError.displayName = 'Field.Error';
+// =============================================================================
+// Compound Export
+// =============================================================================
+Field.Label = FieldLabel;
+Field.Control = FieldControl;
+Field.HelperText = FieldHelperText;
+Field.Error = FieldError;

package/components/Field/FieldContext.d.ts

@@ -0,0 +1,16 @@
+export type FieldContextValue = {
+    /** ID for the form control element */
+    controlId: string;
+    /** ID for helper text (for aria-describedby) */
+    helperTextId: string;
+    /** ID for error message (for aria-describedby) */
+    errorId: string;
+    /** Whether the field has an error */
+    hasError: boolean;
+    /** Whether the field is required */
+    required: boolean;
+    /** Whether the field is disabled */
+    disabled: boolean;
+};
+export declare const FieldContext: import("react").Context<FieldContextValue | null>;
+export declare function useFieldContext(): FieldContextValue;

package/components/Field/FieldContext.js

@@ -0,0 +1,10 @@
+import { createContext, useContext } from 'react';
+export const FieldContext = createContext(null);
+export function useFieldContext() {
+    const context = useContext(FieldContext);
+    if (!context) {
+        throw new Error('Field compound components must be used within a Field. ' +
+            'Wrap your Field.Label, Field.Control, Field.HelperText, and Field.Error in a <Field> component.');
+    }
+    return context;
+}

package/components/Field/index.d.ts

@@ -0,0 +1,2 @@
+export { Field } from './Field';
+export type { FieldProps } from './Field';

package/components/Field/index.js

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

package/components/Modal/Modal.d.ts

@@ -2,13 +2,13 @@ import React from 'react';
 import type { SizeStandard } from '../../types';
 type Size = SizeStandard;
 export type ModalProps = {
-    isOpen: boolean;
+    open: boolean;
     onClose: () => void;
     size?: Size;
     stickyHead?: boolean;
     stickyFoot?: boolean;
-    labelledBy?: string;
-    describedBy?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
     initialFocusSelector?: string;
     container?: Element | null;
     showCloseButton?: boolean;
@@ -17,7 +17,7 @@ export type ModalProps = {
     closeOnEscape?: boolean;
     children?: React.ReactNode;
 };
-declare function ModalRoot({ isOpen, onClose, size, stickyHead, stickyFoot, labelledBy, describedBy, initialFocusSelector, container, showCloseButton, closeLabel, closeOnBackdropClick, closeOnEscape, children, }: ModalProps): React.ReactPortal | null;
+declare function ModalRoot({ open, onClose, size, stickyHead, stickyFoot, 'aria-labelledby': labelledBy, 'aria-describedby': describedBy, initialFocusSelector, container, showCloseButton, closeLabel, closeOnBackdropClick, closeOnEscape, children, }: ModalProps): React.ReactPortal | null;
 type ModalCloseProps = {
     label?: string;
     className?: string;

package/components/Modal/Modal.js

@@ -8,7 +8,7 @@ import { useFocusTrap, getInitialFocus } from '../../utils/focus-trap.js';
 import { ModalContext, useModalContext } from './context.js';
 import { IconButton } from '../IconButton/index.js';
 const isBrowser = typeof document !== 'undefined';
-function ModalRoot({ isOpen, onClose, size = 'md', stickyHead, stickyFoot, labelledBy, describedBy, initialFocusSelector, container, showCloseButton, closeLabel = 'Close', closeOnBackdropClick = true, closeOnEscape = true, children, }) {
+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 [mount, setMount] = useState(null);
@@ -21,7 +21,7 @@ function ModalRoot({ isOpen, onClose, size = 'md', stickyHead, stickyFoot, label
     // the captured element may not be meaningful — focus restore still works,
     // portal scoping may fall back to global interface.
     useLayoutEffect(() => {
-        if (!isOpen || !isBrowser) {
+        if (!open || !isBrowser) {
             return;
         }
         if (mount)
@@ -29,10 +29,10 @@ function ModalRoot({ isOpen, onClose, size = 'md', stickyHead, stickyFoot, label
         const trigger = document.activeElement;
         restoreRef.current = trigger;
         setMount(container ?? getPortalRootFor(trigger));
-    }, [isOpen, container, mount]);
+    }, [open, container, mount]);
     // Reset state when modal closes, restore focus to trigger.
     useEffect(() => {
-        if (isOpen)
+        if (open)
             return;
         const el = restoreRef.current;
         if (el && typeof el.focus === 'function') {
@@ -40,25 +40,27 @@ function ModalRoot({ isOpen, onClose, size = 'md', stickyHead, stickyFoot, label
         }
         restoreRef.current = null;
         setMount(null);
-    }, [isOpen]);
+    }, [open]);
     // Body scroll lock.
     useEffect(() => {
-        if (!isOpen)
+        if (!open)
             return;
         document.body.classList.add('tui-modal-open');
         return () => {
             document.body.classList.remove('tui-modal-open');
         };
-    }, [isOpen]);
+    }, [open]);
     // Focus trap (handles Tab cycling and ESC to close).
     useFocusTrap(dialogRef, {
-        isActive: isOpen,
+        // Modal mount is two-phase (capture portal root, then render portal).
+        // Activate trap only once dialog is actually mounted.
+        isActive: open && !!mount,
         onEscape: onClose,
         escapeDeactivates: closeOnEscape,
     });
     // Make scrollable region focusable; set initial focus.
     useEffect(() => {
-        if (!isOpen)
+        if (!open)
             return;
         const dialog = dialogRef.current;
         if (!dialog)
@@ -96,12 +98,12 @@ function ModalRoot({ isOpen, onClose, size = 'md', stickyHead, stickyFoot, label
                     `Ensure an element with id="${labelledBy}" exists inside the modal.`);
             }
         }
-    }, [isOpen, initialFocusSelector, labelledBy]);
+    }, [open, mount, initialFocusSelector, labelledBy]);
     // Memoize context value to prevent unnecessary re-renders
     const contextValue = useMemo(() => ({ onClose }), [onClose]);
-    if (!isOpen || !mount)
+    if (!open || !mount)
         return null;
-    return createPortal(_jsx(ModalContext.Provider, { value: contextValue, children: _jsxs("div", { className: "tui-modal", "data-state": "open", children: [_jsx("div", { className: "tui-modal__backdrop", onClick: closeOnBackdropClick ? onClose : undefined }), _jsxs("div", { ref: dialogRef, role: "dialog", "aria-modal": "true", "aria-labelledby": labelledBy, "aria-describedby": describedBy, className: cx('tui-modal__dialog', `is-size-${size}`, stickyHead && 'is-sticky-head', stickyFoot && 'is-sticky-foot'), tabIndex: -1, children: [showCloseButton && (_jsx(IconButton, { icon: "system/close", label: closeLabel, variant: "ghost", size: "sm", onClick: onClose, className: "tui-modal__close", showTooltip: true })), children] })] }) }), mount);
+    return createPortal(_jsx(ModalContext.Provider, { value: contextValue, children: _jsxs("div", { className: "tui-modal", "data-state": "open", style: { pointerEvents: 'auto' }, children: [_jsx("div", { className: "tui-modal__backdrop", onClick: closeOnBackdropClick ? onClose : undefined }), _jsxs("div", { ref: dialogRef, role: "dialog", "aria-modal": "true", "aria-labelledby": labelledBy, "aria-describedby": describedBy, className: cx('tui-modal__dialog', `is-size-${size}`, stickyHead && 'is-sticky-head', stickyFoot && 'is-sticky-foot'), tabIndex: -1, children: [showCloseButton && (_jsx(IconButton, { icon: "system/close", label: closeLabel, variant: "ghost", size: "sm", onClick: onClose, className: "tui-modal__close", showTooltip: true })), children] })] }) }), mount);
 }
 function ModalClose({ label = 'Close', className }) {
     const { onClose } = useModalContext();

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('.tui-move-handle__up:not(:disabled), .tui-move-handle__down:not(:disabled)') ??
+                group.querySelector('.tui-move-handle__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", "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", "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", "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';

package/components/MoveHandle/types.d.ts

@@ -0,0 +1,43 @@
+import type { HTMLAttributes } from 'react';
+export type MoveHandleSize = 'sm' | 'md';
+export type MoveHandleMode = 'full' | 'handle';
+export interface MoveHandleLabels {
+    /** Label for the move-up button. Include item name for clear AT context, e.g. "Move Introduction up". Default: "Move up" */
+    moveUp?: string;
+    /** Label for the move-down button. Include item name for clear AT context, e.g. "Move Introduction down". Default: "Move down" */
+    moveDown?: string;
+    /**
+     * Label for the drag handle button. Default: "Drag to reorder".
+     * Consumers add position info if needed. dragHandleProps['aria-label'] takes precedence.
+     */
+    drag?: string;
+    /** Descriptive text announced when locked (via aria-describedby). Default: "This item is locked and cannot be reordered". */
+    locked?: string;
+}
+export interface MoveHandleProps {
+    /** Structural mode. 'full' (default) shows background panel with arrows/index. 'handle' shows only the bare drag icon button. */
+    mode?: MoveHandleMode;
+    /** Component scale. sm = 32px, md = 40px. Ignored when mode is 'handle'. */
+    size?: MoveHandleSize;
+    /** Position index. When provided, shows number at rest, drag handle on hover. */
+    index?: number;
+    /** When true, shows lock icon and disables all interaction. */
+    locked?: boolean;
+    /** Called when the "move up" button is clicked. Button not rendered when omitted. */
+    onMoveUp?: () => void;
+    /** Called when the "move down" button is clicked. Button not rendered when omitted. */
+    onMoveDown?: () => void;
+    /** When false, disables the move-up button without hiding it. Default: true. */
+    canMoveUp?: boolean;
+    /** When false, disables the move-down button without hiding it. Default: true. */
+    canMoveDown?: boolean;
+    /** Override internal button labels for i18n. */
+    labels?: MoveHandleLabels;
+    /** Props to spread on the drag handle button (e.g., from dnd-kit useSortable). */
+    dragHandleProps?: HTMLAttributes<HTMLButtonElement>;
+    /** Accessible label for the control group. Required if aria-labelledby is not set. */
+    'aria-label'?: string;
+    /** ID of element labelling this group. Required if aria-label is not set. */
+    'aria-labelledby'?: string;
+    className?: string;
+}

package/components/MoveHandle/types.js

@@ -0,0 +1 @@
+export {};