@tangible/ui 0.0.1 → 0.0.2

package/components/Combobox/Combobox.js

@@ -0,0 +1,466 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React, { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { useFloating, offset, flip, shift, size as sizeMiddleware, autoUpdate, FloatingPortal, useDismiss, useInteractions, useListNavigation, useRole, } from '@floating-ui/react';
+import { cx } from '../../utils/cx.js';
+import { toKey } from '../../utils/value-key.js';
+import { getPortalRootFor } from '../../utils/portal.js';
+import { hashForId } from '../../utils/hash.js';
+import { composeEventHandlers } from '../../utils/compose-events.js';
+import { Icon } from '../Icon/index.js';
+import { ComboboxActionsContext, ComboboxStateContext, ComboboxContentContext, useComboboxContext, useComboboxContentContext, } from './ComboboxContext.js';
+// =============================================================================
+// Combobox Root
+// =============================================================================
+function ComboboxRoot({ value: controlledValue, defaultValue, onValueChange, inputValue: controlledInputValue, onInputChange, open: controlledOpen, defaultOpen, onOpenChange, disabled = false, placeholder = '', size = 'md', openOnFocus = true, filterMode = 'always', onQueryChange, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, inputClassName, children, }) {
+    // Controlled/uncontrolled value (initialize from defaultValue)
+    const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+    const isValueControlled = controlledValue !== undefined;
+    const value = isValueControlled ? controlledValue : uncontrolledValue;
+    // Controlled/uncontrolled inputValue
+    const [uncontrolledInputValue, setUncontrolledInputValue] = useState('');
+    const isInputControlled = controlledInputValue !== undefined;
+    const inputValue = isInputControlled ? controlledInputValue : uncontrolledInputValue;
+    // Controlled/uncontrolled open
+    const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen ?? false);
+    const isOpenControlled = controlledOpen !== undefined;
+    const open = isOpenControlled ? controlledOpen : uncontrolledOpen;
+    // Internal searching state (private - not exposed)
+    // True only when user is actively typing, false after selection/clear/escape
+    const [searching, setSearching] = useState(false);
+    // Compute effective query for filtering
+    const query = filterMode === 'when-searching' && !searching ? '' : inputValue;
+    // Track previous query to fire onQueryChange
+    const prevQueryRef = useRef(query);
+    useEffect(() => {
+        if (prevQueryRef.current !== query) {
+            prevQueryRef.current = query;
+            onQueryChange?.(query);
+        }
+    }, [query, onQueryChange]);
+    // Option registration
+    const optionsRef = useRef(new Map());
+    const [registryVersion, setRegistryVersion] = useState(0);
+    // IDs
+    const baseId = useId();
+    const inputId = `${baseId}-input`;
+    const listboxId = `${baseId}-listbox`;
+    // Refs
+    const inputRef = useRef(null);
+    const listRef = useRef([]);
+    // Active index for navigation (-1 means no active option)
+    const [activeIndex, setActiveIndex] = useState(-1);
+    // Track previous highlighted value to maintain selection across filter changes
+    const prevHighlightedValueRef = useRef(null);
+    // Set open state
+    const setOpen = useCallback((nextOpen) => {
+        if (disabled)
+            return;
+        if (!isOpenControlled) {
+            setUncontrolledOpen(nextOpen);
+        }
+        onOpenChange?.(nextOpen);
+    }, [disabled, isOpenControlled, onOpenChange]);
+    // Set input value
+    const setInputValue = useCallback((nextValue) => {
+        if (!isInputControlled) {
+            setUncontrolledInputValue(nextValue);
+        }
+        onInputChange?.(nextValue);
+    }, [isInputControlled, onInputChange]);
+    // Select an option
+    const selectOption = useCallback((optionValue) => {
+        if (!isValueControlled) {
+            setUncontrolledValue(optionValue);
+        }
+        onValueChange?.(optionValue);
+        setSearching(false); // End searching mode on selection
+        setOpen(false);
+    }, [isValueControlled, onValueChange, setOpen]);
+    // Clear the selected value
+    // Always clear uncontrolled state - we can't predict what state we'll be in
+    // after the callback runs (controlled value might become undefined)
+    const clearValue = useCallback(() => {
+        setUncontrolledValue(undefined);
+        onValueChange?.(undefined);
+        setSearching(false); // End searching mode on clear
+    }, [onValueChange]);
+    // Get ordered options
+    const getOrderedOptions = useCallback(() => {
+        const options = Array.from(optionsRef.current.values());
+        return options.sort((a, b) => {
+            if (!a.ref.current || !b.ref.current)
+                return 0;
+            const position = a.ref.current.compareDocumentPosition(b.ref.current);
+            if (position & Node.DOCUMENT_POSITION_FOLLOWING)
+                return -1;
+            if (position & Node.DOCUMENT_POSITION_PRECEDING)
+                return 1;
+            return 0;
+        });
+    }, []);
+    // Memoized ordered options
+    const orderedOptions = useMemo(() => {
+        return getOrderedOptions();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [registryVersion]);
+    // Compute disabled indices for keyboard navigation
+    const disabledIndices = useMemo(() => orderedOptions.reduce((acc, opt, i) => {
+        if (opt.disabled)
+            acc.push(i);
+        return acc;
+    }, []), [orderedOptions]);
+    // Floating UI setup
+    const { refs, floatingStyles, context } = useFloating({
+        placement: 'bottom-start',
+        open,
+        onOpenChange: setOpen,
+        middleware: [
+            offset(4),
+            flip({ padding: 8 }),
+            shift({ padding: 8 }),
+            sizeMiddleware({
+                apply({ availableHeight, rects, elements }) {
+                    Object.assign(elements.floating.style, {
+                        maxHeight: `${Math.min(availableHeight - 16, 300)}px`,
+                        minWidth: `${rects.reference.width}px`,
+                    });
+                },
+                padding: 8,
+            }),
+        ],
+        whileElementsMounted: autoUpdate,
+    });
+    // Floating UI interactions
+    const dismiss = useDismiss(context);
+    const role = useRole(context, { role: 'listbox' });
+    const listNavigation = useListNavigation(context, {
+        listRef,
+        activeIndex: activeIndex >= 0 ? activeIndex : null,
+        onNavigate: (index) => setActiveIndex(index ?? -1),
+        loop: true,
+        virtual: true,
+        disabledIndices,
+    });
+    const { getReferenceProps, getFloatingProps, getItemProps } = useInteractions([
+        dismiss,
+        role,
+        listNavigation,
+    ]);
+    // Register option
+    const registerOption = useCallback((option) => {
+        optionsRef.current.set(toKey(option.value), option);
+        setRegistryVersion((v) => v + 1);
+    }, []);
+    const unregisterOption = useCallback((optionValue) => {
+        optionsRef.current.delete(toKey(optionValue));
+        setRegistryVersion((v) => v + 1);
+    }, []);
+    // Active option ID for aria-activedescendant (hash-based for stability during filtering)
+    const activeOptionId = activeIndex >= 0 && orderedOptions[activeIndex]
+        ? `${listboxId}-opt-${hashForId(toKey(orderedOptions[activeIndex].value))}`
+        : undefined;
+    // Update activeIndex when options change (filtering)
+    // Stable logic: keep highlighted if still present, else first enabled, else -1
+    useEffect(() => {
+        if (!open)
+            return;
+        const prevValue = prevHighlightedValueRef.current;
+        const enabledOptions = orderedOptions.filter((opt) => !opt.disabled);
+        if (enabledOptions.length === 0) {
+            setActiveIndex(-1);
+            prevHighlightedValueRef.current = null;
+            return;
+        }
+        // If previously highlighted value still exists and is enabled, keep it
+        if (prevValue !== null) {
+            const prevIndex = orderedOptions.findIndex((opt) => toKey(opt.value) === toKey(prevValue) && !opt.disabled);
+            if (prevIndex >= 0) {
+                setActiveIndex(prevIndex);
+                return;
+            }
+        }
+        // Otherwise, set to first enabled option
+        const firstEnabledIndex = orderedOptions.findIndex((opt) => !opt.disabled);
+        setActiveIndex(firstEnabledIndex >= 0 ? firstEnabledIndex : -1);
+        if (firstEnabledIndex >= 0) {
+            prevHighlightedValueRef.current = orderedOptions[firstEnabledIndex].value;
+        }
+    }, [open, orderedOptions]);
+    // Track highlighted value when activeIndex changes
+    useEffect(() => {
+        if (activeIndex >= 0 && orderedOptions[activeIndex]) {
+            prevHighlightedValueRef.current = orderedOptions[activeIndex].value;
+        }
+    }, [activeIndex, orderedOptions]);
+    // Reset activeIndex when closing
+    useEffect(() => {
+        if (!open) {
+            setActiveIndex(-1);
+            prevHighlightedValueRef.current = null;
+        }
+    }, [open]);
+    // Scroll active option into view
+    useEffect(() => {
+        if (open && activeIndex >= 0 && listRef.current[activeIndex]) {
+            listRef.current[activeIndex]?.scrollIntoView({ block: 'nearest' });
+        }
+    }, [open, activeIndex]);
+    // Handle input change (user typing)
+    const handleInputChange = useCallback((e) => {
+        const newValue = e.target.value;
+        setInputValue(newValue);
+        // Clear selection when input is emptied (clearValue sets searching=false)
+        if (newValue === '' && value !== undefined) {
+            clearValue();
+        }
+        else {
+            // User is actively typing - enter searching mode
+            setSearching(true);
+        }
+        if (!open) {
+            setOpen(true);
+        }
+    }, [setInputValue, open, setOpen, value, clearValue]);
+    // Handle input focus
+    const handleInputFocus = useCallback(() => {
+        if (openOnFocus && !disabled && !open) {
+            setOpen(true);
+        }
+    }, [openOnFocus, disabled, open, setOpen]);
+    // Handle input keydown
+    const handleInputKeyDown = useCallback((e) => {
+        if (disabled)
+            return;
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                if (!open) {
+                    setOpen(true);
+                }
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                if (!open) {
+                    setOpen(true);
+                }
+                break;
+            case 'Enter':
+                if (open && activeIndex >= 0) {
+                    e.preventDefault();
+                    const option = orderedOptions[activeIndex];
+                    if (option && !option.disabled) {
+                        selectOption(option.value);
+                    }
+                }
+                break;
+            case 'Escape':
+                if (open) {
+                    e.preventDefault();
+                    setSearching(false); // End searching mode on escape
+                    setOpen(false);
+                }
+                break;
+            case 'Tab':
+                if (open) {
+                    setSearching(false); // End searching mode on tab away
+                    setOpen(false);
+                }
+                break;
+        }
+    }, [disabled, open, setOpen, activeIndex, orderedOptions, selectOption]);
+    // Handle input blur with blur guard
+    const handleInputBlur = useCallback((e) => {
+        if (!open)
+            return;
+        const relatedTarget = e.relatedTarget;
+        // Focus left document
+        if (relatedTarget === null) {
+            setSearching(false); // End searching mode on blur
+            setOpen(false);
+            return;
+        }
+        // Check if focus moved to floating content
+        const floating = refs.floating.current;
+        if (floating && relatedTarget && floating.contains(relatedTarget)) {
+            return;
+        }
+        setSearching(false); // End searching mode on blur
+        setOpen(false);
+    }, [open, setOpen, refs.floating]);
+    // Handle clear button - clears both input text and selected value
+    const handleClear = useCallback((e) => {
+        e.preventDefault(); // Keep focus in input
+        setInputValue('');
+        clearValue();
+        inputRef.current?.focus();
+    }, [setInputValue, clearValue]);
+    // ==========================================================================
+    // Split Context Values
+    // ==========================================================================
+    const actionsValue = useMemo(() => ({
+        disabled,
+        placeholder,
+        openOnFocus,
+        inputId,
+        listboxId,
+        ariaLabel,
+        ariaLabelledBy,
+        setOpen,
+        setInputValue,
+        selectOption,
+        registerOption,
+        unregisterOption,
+        refs,
+        inputRef,
+        listRef,
+        getReferenceProps,
+        getFloatingProps,
+        getItemProps,
+    }), [
+        disabled,
+        placeholder,
+        openOnFocus,
+        inputId,
+        listboxId,
+        ariaLabel,
+        ariaLabelledBy,
+        setOpen,
+        setInputValue,
+        selectOption,
+        registerOption,
+        unregisterOption,
+        refs,
+        getReferenceProps,
+        getFloatingProps,
+        getItemProps,
+    ]);
+    const stateValue = useMemo(() => ({
+        open,
+        value,
+        inputValue,
+        query,
+        activeIndex,
+        activeOptionId,
+        orderedOptions,
+        floatingStyles,
+        floatingContext: context,
+    }), [
+        open,
+        value,
+        inputValue,
+        query,
+        activeIndex,
+        activeOptionId,
+        orderedOptions,
+        floatingStyles,
+        context,
+    ]);
+    // Get reference props for input (onChange handled separately to ensure it runs)
+    const referenceProps = getReferenceProps({
+        onFocus: handleInputFocus,
+        onBlur: handleInputBlur,
+        onKeyDown: handleInputKeyDown,
+    });
+    return (_jsx(ComboboxActionsContext.Provider, { value: actionsValue, children: _jsx(ComboboxStateContext.Provider, { value: stateValue, children: _jsxs("div", { className: "tui-combobox", children: [_jsxs("div", { className: "tui-combobox__input-wrapper", children: [_jsx("input", { ref: (node) => {
+                                    inputRef.current = node;
+                                    refs.setReference(node);
+                                }, type: "text", id: inputId, className: cx('tui-combobox__input', size !== 'md' && `is-size-${size}`, inputClassName), role: "combobox", "aria-expanded": open, "aria-controls": listboxId, "aria-autocomplete": "list", "aria-activedescendant": activeOptionId, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, disabled: disabled, placeholder: placeholder, value: inputValue, autoComplete: "off", ...referenceProps, onChange: handleInputChange }), inputValue && !disabled && (_jsx("span", { className: "tui-combobox__clear", onPointerDown: handleClear, "aria-hidden": "true", children: _jsx(Icon, { name: "system/close", size: "sm" }) })), _jsx("span", { className: "tui-combobox__icon", "aria-hidden": "true", children: _jsx(Icon, { name: "system/chevron-down", size: "sm" }) })] }), children] }) }) }));
+}
+ComboboxRoot.displayName = 'Combobox';
+// =============================================================================
+// Combobox.Content
+// =============================================================================
+function ComboboxContentComponent({ className, children }) {
+    const { open, listboxId, inputId, refs, floatingStyles, getFloatingProps, listRef, activeIndex, orderedOptions, } = useComboboxContext();
+    const portalRoot = getPortalRootFor(refs.reference.current);
+    const contentContext = useMemo(() => ({
+        listRef,
+        activeIndex,
+        orderedOptions,
+    }), [listRef, activeIndex, orderedOptions]);
+    // Always render for option registration
+    return (_jsxs(_Fragment, { children: [!open && (_jsx("div", { style: { display: 'none' }, "aria-hidden": "true", children: _jsx(ComboboxContentContext.Provider, { value: contentContext, children: children }) })), open && (_jsx(FloatingPortal, { root: portalRoot, children: _jsx("div", { ref: refs.setFloating, id: listboxId, role: "listbox", "aria-labelledby": inputId, className: cx('tui-combobox__content', className), style: {
+                        ...floatingStyles,
+                        minWidth: refs.reference.current?.offsetWidth,
+                        pointerEvents: 'auto',
+                    }, tabIndex: -1, ...getFloatingProps(), children: _jsx(ComboboxContentContext.Provider, { value: contentContext, children: children }) }) }))] }));
+}
+ComboboxContentComponent.displayName = 'Combobox.Content';
+// =============================================================================
+// Combobox.Option
+// =============================================================================
+function ComboboxOptionComponent({ value: optionValue, disabled = false, textValue: explicitTextValue, className, children, }) {
+    const { value: selectedValue, selectOption, listboxId, registerOption, unregisterOption, getItemProps, } = useComboboxContext();
+    const { listRef, activeIndex, orderedOptions } = useComboboxContentContext();
+    const ref = useRef(null);
+    const textValue = explicitTextValue ?? (typeof children === 'string' ? children : '');
+    // Warn in dev if textValue couldn't be derived
+    useEffect(() => {
+        if (import.meta.env.DEV && !textValue) {
+            console.warn(`Combobox.Option with value="${optionValue}" has no textValue. Provide textValue prop when children is not a string.`);
+        }
+    }, [textValue, optionValue]);
+    // Register option
+    useLayoutEffect(() => {
+        registerOption({ value: optionValue, ref, disabled, textValue });
+        return () => unregisterOption(optionValue);
+    }, [optionValue, disabled, textValue, registerOption, unregisterOption]);
+    // Find this option's index
+    const index = orderedOptions.findIndex((opt) => toKey(opt.value) === toKey(optionValue));
+    // Assign ref to listRef for navigation
+    useEffect(() => {
+        if (index >= 0) {
+            listRef.current[index] = ref.current;
+        }
+    }, [index, listRef]);
+    const isSelected = selectedValue !== undefined && toKey(selectedValue) === toKey(optionValue);
+    const isHighlighted = activeIndex === index;
+    const handleClick = useCallback(() => {
+        if (disabled)
+            return;
+        selectOption(optionValue);
+    }, [disabled, optionValue, selectOption]);
+    // Prevent blur on input when clicking option (must run before any Floating UI handler)
+    const handlePointerDown = useCallback((e) => {
+        e.preventDefault();
+    }, []);
+    // Hash-based ID for stability during filtering (aria-activedescendant references this)
+    // Use toKey() before hashing to differentiate number 1 from string "1"
+    const optionId = `${listboxId}-opt-${hashForId(toKey(optionValue))}`;
+    // Get item props and compose our pointerdown handler with any from Floating UI
+    const itemProps = getItemProps({
+        onClick: handleClick,
+    });
+    return (_jsxs("div", { ref: ref, id: optionId, role: "option", className: cx('tui-combobox__option', className), "aria-selected": isSelected, "aria-disabled": disabled || undefined, "data-highlighted": isHighlighted || undefined, "data-disabled": disabled || undefined, ...itemProps, onPointerDown: composeEventHandlers(handlePointerDown, itemProps.onPointerDown), children: [_jsx("span", { className: "tui-combobox__option-content", children: children }), isSelected && (_jsx(Icon, { name: "system/check", size: "sm", className: "tui-combobox__option-check", "aria-hidden": "true" }))] }));
+}
+ComboboxOptionComponent.displayName = 'Combobox.Option';
+// =============================================================================
+// Combobox.Group
+// =============================================================================
+function ComboboxGroupComponent({ className, children }) {
+    const groupId = useId();
+    return (_jsx("div", { role: "group", "aria-labelledby": `${groupId}-label`, className: cx('tui-combobox__group', className), children: _jsx(ComboboxGroupContext.Provider, { value: { groupId }, children: children }) }));
+}
+ComboboxGroupComponent.displayName = 'Combobox.Group';
+const ComboboxGroupContext = React.createContext(null);
+// =============================================================================
+// Combobox.Label
+// =============================================================================
+function ComboboxLabelComponent({ className, children }) {
+    const groupContext = React.useContext(ComboboxGroupContext);
+    return (_jsx("div", { id: groupContext ? `${groupContext.groupId}-label` : undefined, className: cx('tui-combobox__label', className), children: children }));
+}
+ComboboxLabelComponent.displayName = 'Combobox.Label';
+export const Combobox = ComboboxRoot;
+Combobox.Content = ComboboxContentComponent;
+Combobox.Option = ComboboxOptionComponent;
+Combobox.Group = ComboboxGroupComponent;
+Combobox.Label = ComboboxLabelComponent;
+// Named exports
+export const ComboboxContent = ComboboxContentComponent;
+export const ComboboxOption = ComboboxOptionComponent;
+export const ComboboxGroup = ComboboxGroupComponent;
+export const ComboboxLabel = ComboboxLabelComponent;
+// Hook for advanced use cases
+// eslint-disable-next-line react-refresh/only-export-components
+export { useComboboxContext as useCombobox } from './ComboboxContext.js';

package/components/Combobox/ComboboxContext.d.ts

@@ -0,0 +1,8 @@
+import type { ComboboxActionsContextValue, ComboboxStateContextValue, ComboboxContentContextValue } from './types';
+export declare const ComboboxActionsContext: import("react").Context<ComboboxActionsContextValue | null>;
+export declare const ComboboxStateContext: import("react").Context<ComboboxStateContextValue | null>;
+export declare function useComboboxActions(): ComboboxActionsContextValue;
+export declare function useComboboxState(): ComboboxStateContextValue;
+export declare function useComboboxContext(): ComboboxActionsContextValue & ComboboxStateContextValue;
+export declare const ComboboxContentContext: import("react").Context<ComboboxContentContextValue | null>;
+export declare function useComboboxContentContext(): ComboboxContentContextValue;

package/components/Combobox/ComboboxContext.js

@@ -0,0 +1,36 @@
+import { createContext, useContext } from 'react';
+// =============================================================================
+// Split Contexts for Performance
+// =============================================================================
+export const ComboboxActionsContext = createContext(null);
+export const ComboboxStateContext = createContext(null);
+export function useComboboxActions() {
+    const context = useContext(ComboboxActionsContext);
+    if (!context) {
+        throw new Error('Combobox components must be used within a Combobox');
+    }
+    return context;
+}
+export function useComboboxState() {
+    const context = useContext(ComboboxStateContext);
+    if (!context) {
+        throw new Error('Combobox components must be used within a Combobox');
+    }
+    return context;
+}
+export function useComboboxContext() {
+    const actions = useComboboxActions();
+    const state = useComboboxState();
+    return { ...actions, ...state };
+}
+// =============================================================================
+// Content Context (for Option registration)
+// =============================================================================
+export const ComboboxContentContext = createContext(null);
+export function useComboboxContentContext() {
+    const context = useContext(ComboboxContentContext);
+    if (!context) {
+        throw new Error('Combobox.Option must be used within Combobox.Content');
+    }
+    return context;
+}

package/components/Combobox/index.d.ts

@@ -0,0 +1,2 @@
+export { Combobox, ComboboxContent, ComboboxOption, ComboboxGroup, ComboboxLabel, useCombobox, } from './Combobox';
+export type { ComboboxProps, ComboboxContentProps, ComboboxOptionProps, ComboboxGroupProps, ComboboxLabelProps, FilterMode as ComboboxFilterMode, RegisteredOption as ComboboxRegisteredOption, } from './types';

package/components/Combobox/index.js

@@ -0,0 +1 @@
+export { Combobox, ComboboxContent, ComboboxOption, ComboboxGroup, ComboboxLabel, useCombobox, } from './Combobox.js';