@tangible/ui 0.0.1

package/components/Tabs/Tabs.js

@@ -0,0 +1,309 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { cx } from '../../utils/cx.js';
+import { Icon } from '../Icon/index.js';
+import { TabsContext, useTabsContext } from './TabsContext.js';
+// =============================================================================
+// Utility: Sanitize ID
+// =============================================================================
+const sanitizeId = (str) => str.replace(/[^a-zA-Z0-9-_]/g, '-');
+function TabsRoot({ variant = 'underline', activationMode = 'auto', value: controlledValue, defaultValue, onValueChange, orientation = 'horizontal', className, children, }) {
+    const baseId = useId();
+    const [internalValue, setInternalValue] = useState(defaultValue);
+    const [focusedValue, setFocusedValue] = useState(undefined);
+    const [registryVersion, setRegistryVersion] = useState(0);
+    const tabsRef = useRef(new Map());
+    const panelsRef = useRef(new Set());
+    const mountCounterRef = useRef(0);
+    const prevDisabledRef = useRef(new Map());
+    const isControlled = controlledValue !== undefined;
+    const activeValue = isControlled ? controlledValue : internalValue;
+    // ID generators
+    const getTabId = useCallback((value) => `${baseId}-tab-${sanitizeId(value)}`, [baseId]);
+    const getPanelId = useCallback((value) => `${baseId}-panel-${sanitizeId(value)}`, [baseId]);
+    // Tab registration
+    const registerTab = useCallback((record) => {
+        const existing = tabsRef.current.get(record.value);
+        tabsRef.current.set(record.value, {
+            ...record,
+            mountIndex: existing?.mountIndex ?? mountCounterRef.current++,
+        });
+        setRegistryVersion((v) => v + 1);
+    }, []);
+    const unregisterTab = useCallback((value) => {
+        tabsRef.current.delete(value);
+        setRegistryVersion((v) => v + 1);
+    }, []);
+    // Panel registration
+    const registerPanel = useCallback((value) => {
+        panelsRef.current.add(value);
+        setRegistryVersion((v) => v + 1);
+    }, []);
+    const unregisterPanel = useCallback((value) => {
+        panelsRef.current.delete(value);
+        setRegistryVersion((v) => v + 1);
+    }, []);
+    // Get tabs sorted by DOM order, falling back to mount order for disconnected nodes
+    const getOrderedTabs = useCallback(() => {
+        const tabs = Array.from(tabsRef.current.values());
+        return tabs.sort((a, b) => {
+            const position = a.element.compareDocumentPosition(b.element);
+            if (position & Node.DOCUMENT_POSITION_FOLLOWING)
+                return -1;
+            if (position & Node.DOCUMENT_POSITION_PRECEDING)
+                return 1;
+            // Disconnected or same node: fall back to stable mount order
+            return a.mountIndex - b.mountIndex;
+        });
+    }, []);
+    // Selection handler
+    const onSelect = useCallback((newValue) => {
+        if (isControlled) {
+            // Controlled: ONLY call callback, never touch internal state
+            onValueChange?.(newValue);
+        }
+        else {
+            // Uncontrolled: update internal state, then notify
+            setInternalValue(newValue);
+            onValueChange?.(newValue);
+        }
+    }, [isControlled, onValueChange]);
+    // Handle dynamic disable: if active or focused tab becomes disabled, move selection/focus
+    useEffect(() => {
+        const enabledTabs = getOrderedTabs().filter((t) => !t.disabled);
+        if (enabledTabs.length === 0)
+            return; // Edge case: all disabled
+        // 1. If ACTIVE tab became disabled, move selection
+        const activeTab = tabsRef.current.get(activeValue ?? '');
+        const activeWasDisabled = prevDisabledRef.current.get(activeValue ?? '');
+        if (activeTab?.disabled && !activeWasDisabled) {
+            const firstEnabled = enabledTabs[0];
+            if (isControlled) {
+                onValueChange?.(firstEnabled.value);
+            }
+            else {
+                setInternalValue(firstEnabled.value);
+                onValueChange?.(firstEnabled.value);
+            }
+        }
+        // 2. If FOCUSED tab became disabled, move focus to nearest enabled
+        const focusedTab = tabsRef.current.get(focusedValue ?? '');
+        const focusedWasDisabled = prevDisabledRef.current.get(focusedValue ?? '');
+        if (focusedTab?.disabled && !focusedWasDisabled) {
+            // Find next enabled tab after current, or wrap to first
+            const currentIdx = enabledTabs.findIndex((t) => t.mountIndex > focusedTab.mountIndex);
+            const nextEnabled = enabledTabs[currentIdx >= 0 ? currentIdx : 0];
+            setFocusedValue(nextEnabled.value);
+            nextEnabled.element.focus();
+        }
+        // Update tracking
+        tabsRef.current.forEach((record, val) => {
+            prevDisabledRef.current.set(val, record.disabled);
+        });
+    }, [registryVersion, activeValue, focusedValue, isControlled, onValueChange, getOrderedTabs]);
+    // Dev-only: Tab-Panel pairing validation
+    useEffect(() => {
+        if (import.meta.env.DEV) {
+            // Defer validation to next microtask so all tabs/panels have registered
+            queueMicrotask(() => {
+                const tabValues = new Set(Array.from(tabsRef.current.keys()));
+                const panelValues = panelsRef.current;
+                // Tabs without panels
+                tabValues.forEach((v) => {
+                    if (!panelValues.has(v)) {
+                        console.warn(`Tabs: Tab "${v}" has no matching Panel.`);
+                    }
+                });
+                // Panels without tabs
+                panelValues.forEach((v) => {
+                    if (!tabValues.has(v)) {
+                        console.warn(`Tabs: Panel "${v}" has no matching Tab.`);
+                    }
+                });
+            });
+        }
+    }, [registryVersion]);
+    const contextValue = useMemo(() => ({
+        variant,
+        orientation,
+        activationMode,
+        activeValue,
+        focusedValue,
+        baseId,
+        registerTab,
+        unregisterTab,
+        registerPanel,
+        unregisterPanel,
+        getOrderedTabs,
+        onSelect,
+        setFocusedValue,
+        getTabId,
+        getPanelId,
+        tabsRef,
+    }), [
+        variant,
+        orientation,
+        activationMode,
+        activeValue,
+        focusedValue,
+        baseId,
+        registerTab,
+        unregisterTab,
+        registerPanel,
+        unregisterPanel,
+        getOrderedTabs,
+        onSelect,
+        setFocusedValue,
+        getTabId,
+        getPanelId,
+    ]);
+    return (_jsx(TabsContext.Provider, { value: contextValue, children: _jsx("div", { className: cx('tui-tabs', className), "data-variant": variant, "data-orientation": orientation, children: children }) }));
+}
+// =============================================================================
+// Tabs.List
+// =============================================================================
+function TabsList({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, className, children, }) {
+    const { orientation, activationMode, activeValue, focusedValue, getOrderedTabs, onSelect, setFocusedValue, tabsRef, } = useTabsContext();
+    // Dev-only: Warn if missing accessible name
+    useEffect(() => {
+        if (import.meta.env.DEV) {
+            if (!ariaLabel && !ariaLabelledBy) {
+                console.warn('Tabs.List: Missing accessible name. Provide aria-label or aria-labelledby.');
+            }
+        }
+    }, [ariaLabel, ariaLabelledBy]);
+    // Focus tracking via real focus events (O(1) lookup via data attribute)
+    const handleFocusIn = (event) => {
+        const tab = event.target.closest('[role="tab"]');
+        if (!tab)
+            return;
+        // O(1) lookup via data attribute
+        const value = tab.getAttribute('data-tui-tab-value');
+        if (!value)
+            return;
+        const record = tabsRef.current.get(value);
+        if (record && !record.disabled) {
+            setFocusedValue(value);
+            // In auto mode, select on focus
+            if (activationMode === 'auto') {
+                onSelect(value);
+            }
+        }
+    };
+    // Keyboard navigation
+    const handleKeyDown = (event) => {
+        const tabs = getOrderedTabs().filter((t) => !t.disabled);
+        // Guard: no enabled tabs
+        if (tabs.length === 0)
+            return;
+        // Find current index; if focusedValue unset or not found, start from first/active tab
+        let currentIndex = tabs.findIndex((t) => t.value === focusedValue);
+        if (currentIndex === -1) {
+            // Fall back to active tab, or first tab
+            currentIndex = tabs.findIndex((t) => t.value === activeValue);
+            if (currentIndex === -1)
+                currentIndex = 0;
+        }
+        const prevKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
+        const nextKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
+        let targetIndex = null;
+        switch (event.key) {
+            case nextKey:
+                event.preventDefault();
+                targetIndex = (currentIndex + 1) % tabs.length;
+                break;
+            case prevKey:
+                event.preventDefault();
+                targetIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+                break;
+            case 'Home':
+                event.preventDefault();
+                targetIndex = 0;
+                break;
+            case 'End':
+                event.preventDefault();
+                targetIndex = tabs.length - 1;
+                break;
+            case 'Enter':
+            case ' ':
+                if (activationMode === 'manual' && focusedValue) {
+                    event.preventDefault();
+                    onSelect(focusedValue);
+                }
+                return;
+        }
+        if (targetIndex !== null) {
+            const targetTab = tabs[targetIndex];
+            targetTab.element.focus();
+            // Focus event handler will update focusedValue and (in auto mode) call onSelect
+        }
+    };
+    return (_jsx("div", { role: "tablist", className: cx('tui-tabs__list', className), "aria-orientation": orientation, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, onKeyDown: handleKeyDown, onFocusCapture: handleFocusIn, children: children }));
+}
+// =============================================================================
+// Tabs.Tab
+// =============================================================================
+function Tab({ value, icon, disabled = false, className, children }) {
+    const { activationMode, activeValue, focusedValue, registerTab, unregisterTab, onSelect, getTabId, getPanelId, } = useTabsContext();
+    const tabId = getTabId(value);
+    const panelId = getPanelId(value);
+    const isActive = activeValue === value;
+    // Determine which tab gets tabIndex={0}
+    const getFocusableValue = () => {
+        if (activationMode === 'auto') {
+            return activeValue;
+        }
+        // Manual: focused tab gets tabIndex=0, or fall back to active
+        return focusedValue ?? activeValue;
+    };
+    const isFocusable = value === getFocusableValue();
+    // Callback ref for registration (handles null during unmount)
+    const callbackRef = useCallback((node) => {
+        if (node) {
+            registerTab({ value, element: node, disabled, tabId, panelId });
+        }
+        else {
+            unregisterTab(value);
+        }
+    }, [value, disabled, tabId, panelId, registerTab, unregisterTab]);
+    // Click handler
+    const handleClick = () => {
+        if (disabled)
+            return;
+        // In manual mode, explicitly select. In auto mode, focus handler will select.
+        if (activationMode === 'manual') {
+            onSelect(value);
+        }
+    };
+    return (_jsxs("button", { ref: callbackRef, type: "button", role: "tab", id: tabId, className: cx('tui-tabs__tab', className), "data-tui-tab-value": value, "data-state": isActive ? 'active' : 'inactive', "aria-selected": isActive, "aria-controls": panelId, tabIndex: disabled ? -1 : isFocusable ? 0 : -1, disabled: disabled, onClick: handleClick, children: [icon && _jsx(Icon, { name: icon, size: "sm", "aria-hidden": "true" }), children && _jsx("span", { className: "tui-tabs__tab-label", children: children })] }));
+}
+// =============================================================================
+// Tabs.Panel
+// =============================================================================
+function TabPanel({ value, className, children }) {
+    const { activeValue, registerPanel, unregisterPanel, getTabId, getPanelId } = useTabsContext();
+    const tabId = getTabId(value);
+    const panelId = getPanelId(value);
+    const isActive = activeValue === value;
+    // Register panel on mount
+    useEffect(() => {
+        registerPanel(value);
+        return () => unregisterPanel(value);
+    }, [value, registerPanel, unregisterPanel]);
+    return (_jsx("div", { role: "tabpanel", id: panelId, className: cx('tui-tabs__panel', className), "data-state": isActive ? 'active' : 'inactive', "aria-labelledby": tabId, "aria-hidden": !isActive, 
+        // tabIndex={0} allows direct focus on panel for screen reader navigation
+        tabIndex: isActive ? 0 : undefined, 
+        // inert prevents Tab navigation into hidden panel content
+        inert: !isActive || undefined, children: children }));
+}
+// =============================================================================
+// Compound Component Export
+// =============================================================================
+TabsList.displayName = 'Tabs.List';
+Tab.displayName = 'Tabs.Tab';
+TabPanel.displayName = 'Tabs.Panel';
+export const Tabs = TabsRoot;
+Tabs.displayName = 'Tabs';
+Tabs.List = TabsList;
+Tabs.Tab = Tab;
+Tabs.Panel = TabPanel;

package/components/Tabs/TabsContext.d.ts

@@ -0,0 +1,3 @@
+import type { TabsContextValue } from './types';
+export declare const TabsContext: import("react").Context<TabsContextValue | null>;
+export declare function useTabsContext(): TabsContextValue;

package/components/Tabs/TabsContext.js

@@ -0,0 +1,12 @@
+import { createContext, useContext } from 'react';
+// =============================================================================
+// Tabs Context
+// =============================================================================
+export const TabsContext = createContext(null);
+export function useTabsContext() {
+    const context = useContext(TabsContext);
+    if (!context) {
+        throw new Error('Tabs compound components must be used within a Tabs component');
+    }
+    return context;
+}

package/components/Tabs/index.d.ts

@@ -0,0 +1,2 @@
+export { Tabs } from './Tabs';
+export type { TabsProps, TabsListProps, TabProps, TabPanelProps, TabsVariant, TabsActivationMode, TabsOrientation, } from './types';

package/components/Tabs/index.js

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

package/components/Tabs/types.d.ts

@@ -0,0 +1,75 @@
+import type { ReactNode } from 'react';
+import type { IconName } from '../../icons/registry';
+export type TabsVariant = 'pill' | 'underline' | 'outline';
+export type TabsActivationMode = 'auto' | 'manual';
+export type TabsOrientation = 'horizontal' | 'vertical';
+export type TabsProps = {
+    /** Visual style */
+    variant?: TabsVariant;
+    /** Auto: select on focus. Manual: arrow keys move focus only, Enter/Space selects. */
+    activationMode?: TabsActivationMode;
+    /** Controlled active tab */
+    value?: string;
+    /** Uncontrolled initial tab */
+    defaultValue?: string;
+    /** Callback when active tab changes */
+    onValueChange?: (value: string) => void;
+    /** Affects arrow key mapping and aria-orientation */
+    orientation?: TabsOrientation;
+    /** Additional classes */
+    className?: string;
+    children: ReactNode;
+};
+export type TabsListProps = {
+    /** Accessible label (required) */
+    'aria-label'?: string;
+    /** Alternative to aria-label */
+    'aria-labelledby'?: string;
+    /** Additional classes */
+    className?: string;
+    children: ReactNode;
+};
+export type TabProps = {
+    /** Unique identifier, must match a Panel */
+    value: string;
+    /** Icon name from registry */
+    icon?: IconName;
+    /** Disable tab (skipped in keyboard nav) */
+    disabled?: boolean;
+    /** Additional classes */
+    className?: string;
+    children?: ReactNode;
+};
+export type TabPanelProps = {
+    /** Must match a Tab value */
+    value: string;
+    /** Additional classes */
+    className?: string;
+    children?: ReactNode;
+};
+export type TabRecord = {
+    value: string;
+    element: HTMLButtonElement;
+    disabled: boolean;
+    tabId: string;
+    panelId: string;
+    mountIndex: number;
+};
+export type TabsContextValue = {
+    variant: TabsVariant;
+    orientation: TabsOrientation;
+    activationMode: TabsActivationMode;
+    activeValue: string | undefined;
+    focusedValue: string | undefined;
+    baseId: string;
+    registerTab: (record: Omit<TabRecord, 'mountIndex'>) => void;
+    unregisterTab: (value: string) => void;
+    registerPanel: (value: string) => void;
+    unregisterPanel: (value: string) => void;
+    getOrderedTabs: () => TabRecord[];
+    onSelect: (value: string) => void;
+    setFocusedValue: (value: string | undefined) => void;
+    getTabId: (value: string) => string;
+    getPanelId: (value: string) => string;
+    tabsRef: React.MutableRefObject<Map<string, TabRecord>>;
+};

package/components/Tabs/types.js

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

package/components/Toolbar/Toolbar.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { ToolbarProps, ToolbarGroupProps, ToolbarItemProps } from './types';
+type ToolbarCompound = {
+    (props: ToolbarProps): React.JSX.Element;
+    displayName?: string;
+    Group: typeof ToolbarGroup;
+    Item: typeof ToolbarItem;
+};
+declare function ToolbarGroup({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, children, className, }: ToolbarGroupProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ToolbarGroup {
+    var displayName: string;
+}
+declare function ToolbarItem({ children }: ToolbarItemProps): React.ReactElement<Record<string, unknown>, string | React.JSXElementConstructor<any>> | null;
+declare namespace ToolbarItem {
+    var displayName: string;
+}
+export declare const Toolbar: ToolbarCompound;
+export {};

package/components/Toolbar/Toolbar.js

@@ -0,0 +1,241 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { useCallback, useEffect, useRef, cloneElement, isValidElement, } from 'react';
+import { cx } from '../../utils/cx.js';
+// =============================================================================
+// Toolbar Component
+// =============================================================================
+//
+// WAI-ARIA toolbar pattern with roving tabindex. Only elements marked with
+// data-tui-toolbar-item participate in keyboard navigation - this prevents
+// hijacking nested focusables (inputs, menus, etc.).
+//
+// Per APG: Use toolbars for groups of 3+ controls. For 1-2 controls, standard
+// button groups without role="toolbar" avoid unnecessary keyboard complexity.
+//
+// Usage:
+//   <Toolbar aria-label="Actions">
+//     <Toolbar.Group aria-label="Navigation">
+//       <Toolbar.Item>
+//         <IconButton icon="system/chevron-left" label="Previous" />
+//       </Toolbar.Item>
+//     </Toolbar.Group>
+//   </Toolbar>
+//
+// =============================================================================
+// Selectors for toolbar items
+const ITEM_SELECTOR = '[data-tui-toolbar-item]';
+const DISABLED_SELECTOR = ':disabled, [aria-disabled="true"]';
+// Elements that should not have arrow keys intercepted (composite widgets per APG)
+const ARROW_EXEMPT_SELECTOR = 'input, textarea, select, [contenteditable="true"], ' +
+    '[role="textbox"], [role="combobox"], [role="listbox"], ' +
+    '[role="menu"], [role="tree"], [role="grid"], [role="spinbutton"], [role="slider"], ' +
+    '[role="radiogroup"]';
+// -----------------------------------------------------------------------------
+// Helper: Find next/prev enabled item
+// -----------------------------------------------------------------------------
+function findNextItem(items, currentIndex, direction, loop) {
+    const len = items.length;
+    if (len === 0)
+        return null;
+    let index = currentIndex;
+    for (let i = 0; i < len; i++) {
+        index += direction;
+        // Handle boundaries
+        if (index >= len) {
+            if (!loop)
+                return null;
+            index = 0;
+        }
+        else if (index < 0) {
+            if (!loop)
+                return null;
+            index = len - 1;
+        }
+        // Skip disabled items
+        const item = items[index];
+        if (!item.matches(DISABLED_SELECTOR)) {
+            return index;
+        }
+    }
+    return null; // All items disabled
+}
+function ToolbarRoot({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, orientation = 'horizontal', loop = true, children, className, style, }) {
+    const containerRef = useRef(null);
+    const focusedIndexRef = useRef(0);
+    // Instance-scoped map for storing original tabindex values
+    const originalTabIndexMapRef = useRef(new WeakMap());
+    // Dev warning for missing accessible name
+    useEffect(() => {
+        if (import.meta.env?.DEV && !ariaLabel && !ariaLabelledBy) {
+            console.warn('[Toolbar] aria-label or aria-labelledby is required for accessibility.');
+        }
+    }, [ariaLabel, ariaLabelledBy]);
+    // -------------------------------------------------------------------------
+    // Item discovery
+    // -------------------------------------------------------------------------
+    const getItems = useCallback(() => {
+        if (!containerRef.current)
+            return [];
+        return Array.from(containerRef.current.querySelectorAll(ITEM_SELECTOR));
+    }, []);
+    // -------------------------------------------------------------------------
+    // Roving tabindex management
+    // -------------------------------------------------------------------------
+    const updateTabIndices = useCallback((items, focusIdx) => {
+        const map = originalTabIndexMapRef.current;
+        items.forEach((item, i) => {
+            // Store original tabindex if not already stored
+            if (!map.has(item)) {
+                map.set(item, item.hasAttribute('tabindex') ? item.tabIndex : null);
+            }
+            // Disabled items get tabIndex=-1 (not in Tab order)
+            const isDisabled = item.matches(DISABLED_SELECTOR);
+            if (isDisabled) {
+                item.setAttribute('tabindex', '-1');
+            }
+            else {
+                item.setAttribute('tabindex', i === focusIdx ? '0' : '-1');
+            }
+        });
+    }, []);
+    // Initialize tabindex and observe for dynamic item changes
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        const initializeTabIndices = () => {
+            const items = getItems();
+            if (items.length === 0)
+                return;
+            // If current focused item is still valid, keep it
+            const currentItems = getItems();
+            const currentFocusedItem = currentItems[focusedIndexRef.current];
+            if (currentFocusedItem && !currentFocusedItem.matches(DISABLED_SELECTOR)) {
+                updateTabIndices(items, focusedIndexRef.current);
+                return;
+            }
+            // Otherwise find first enabled item
+            const firstEnabled = items.findIndex((el) => !el.matches(DISABLED_SELECTOR));
+            const newIdx = Math.max(0, firstEnabled);
+            focusedIndexRef.current = newIdx;
+            updateTabIndices(items, newIdx);
+        };
+        // Initial setup
+        initializeTabIndices();
+        // Watch for items being added/removed
+        const observer = new MutationObserver((mutations) => {
+            // Only re-init if toolbar items changed
+            const relevantChange = mutations.some((m) => m.type === 'childList' ||
+                (m.type === 'attributes' && m.attributeName === 'data-tui-toolbar-item'));
+            if (relevantChange) {
+                initializeTabIndices();
+            }
+        });
+        observer.observe(container, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ['data-tui-toolbar-item', 'disabled', 'aria-disabled'],
+        });
+        return () => observer.disconnect();
+    }, [getItems, updateTabIndices]);
+    // -------------------------------------------------------------------------
+    // Focus sync - DOM is source of truth
+    // -------------------------------------------------------------------------
+    const handleFocusIn = useCallback((e) => {
+        // Target may be inner element (SVG, span) - find closest toolbar item
+        const item = e.target.closest(ITEM_SELECTOR);
+        if (!item)
+            return;
+        const items = getItems();
+        const idx = items.indexOf(item);
+        if (idx !== -1) {
+            focusedIndexRef.current = idx;
+            // Defer DOM mutation to avoid React hydration mismatches in SSR contexts
+            queueMicrotask(() => updateTabIndices(items, idx));
+        }
+    }, [getItems, updateTabIndices]);
+    // -------------------------------------------------------------------------
+    // Keyboard navigation
+    // -------------------------------------------------------------------------
+    const handleKeyDown = useCallback((e) => {
+        // Bail if modifier keys held
+        if (e.ctrlKey || e.altKey || e.metaKey || e.shiftKey)
+            return;
+        // Bail if target is or is inside exempt element (input, textarea, composite widget)
+        if (e.target.closest(ARROW_EXEMPT_SELECTOR))
+            return;
+        const items = getItems();
+        if (items.length === 0)
+            return;
+        // Find which item currently has focus (using closest for inner elements)
+        const activeItem = document.activeElement?.closest(ITEM_SELECTOR);
+        if (!activeItem)
+            return;
+        const currentIdx = items.indexOf(activeItem);
+        if (currentIdx === -1)
+            return;
+        const nextKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
+        const prevKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
+        let targetIdx = null;
+        switch (e.key) {
+            case nextKey:
+                targetIdx = findNextItem(items, currentIdx, 1, loop);
+                break;
+            case prevKey:
+                targetIdx = findNextItem(items, currentIdx, -1, loop);
+                break;
+            case 'Home':
+                targetIdx = findNextItem(items, -1, 1, false);
+                break;
+            case 'End':
+                targetIdx = findNextItem(items, items.length, -1, false);
+                break;
+            default:
+                return;
+        }
+        if (targetIdx !== null && targetIdx !== currentIdx) {
+            e.preventDefault();
+            items[targetIdx].focus();
+            // focusin handler will update state
+        }
+    }, [getItems, orientation, loop]);
+    return (_jsx("div", { ref: containerRef, role: "toolbar", "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-orientation": orientation, className: cx('tui-toolbar', className), style: style, 
+        // Capture phase catches focus on inner elements (SVG icons, spans) before
+        // they handle it, allowing us to update roving tabindex correctly
+        onFocusCapture: handleFocusIn, onKeyDown: handleKeyDown, children: children }));
+}
+// =============================================================================
+// Toolbar Group
+// =============================================================================
+function ToolbarGroup({ 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, children, className, }) {
+    // Only add role="group" if accessible name is provided
+    // Unnamed groups are worse than no group
+    const hasLabel = ariaLabel || ariaLabelledBy;
+    return (_jsx("div", { role: hasLabel ? 'group' : undefined, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className: cx('tui-toolbar__group', className), children: children }));
+}
+// =============================================================================
+// Toolbar Item
+// =============================================================================
+function ToolbarItem({ children }) {
+    if (!isValidElement(children)) {
+        console.warn('[Toolbar.Item] Expected a single valid React element as child');
+        return null;
+    }
+    const child = children;
+    // cloneElement preserves the child's ref automatically - don't touch it
+    // Only add the data attribute for toolbar item registration
+    return cloneElement(child, {
+        ...child.props,
+        'data-tui-toolbar-item': '',
+    });
+}
+// =============================================================================
+// Export Compound Component
+// =============================================================================
+ToolbarGroup.displayName = 'Toolbar.Group';
+ToolbarItem.displayName = 'Toolbar.Item';
+export const Toolbar = ToolbarRoot;
+Toolbar.displayName = 'Toolbar';
+Toolbar.Group = ToolbarGroup;
+Toolbar.Item = ToolbarItem;

package/components/Toolbar/index.d.ts

@@ -0,0 +1,2 @@
+export { Toolbar } from './Toolbar';
+export type { ToolbarProps, ToolbarGroupProps, ToolbarItemProps, ToolbarOrientation, } from './types';