@tangible/ui 0.0.1 → 0.0.2

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

@@ -0,0 +1,39 @@
+import { type MultiSelectProps, type MultiSelectTriggerProps, type MultiSelectContentProps, type MultiSelectOptionProps, type MultiSelectGroupProps, type MultiSelectLabelProps } from './types';
+declare function MultiSelectRoot({ id: triggerIdProp, value: controlledValue, defaultValue, onValueChange, open: controlledOpen, defaultOpen, onOpenChange, disabled, placeholder, size, display, maxChips, max, onMaxReached, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, 'aria-describedby': ariaDescribedBy, children, }: MultiSelectProps): import("react/jsx-runtime").JSX.Element;
+declare namespace MultiSelectRoot {
+    var displayName: string;
+}
+declare function MultiSelectTriggerComponent({ asChild, className, children, }: MultiSelectTriggerProps): import("react/jsx-runtime").JSX.Element;
+declare namespace MultiSelectTriggerComponent {
+    var displayName: string;
+}
+declare function MultiSelectContentComponent({ className, children }: MultiSelectContentProps): import("react/jsx-runtime").JSX.Element;
+declare namespace MultiSelectContentComponent {
+    var displayName: string;
+}
+declare function MultiSelectOptionComponent({ value: optionValue, disabled, textValue: explicitTextValue, className, children, }: MultiSelectOptionProps): import("react/jsx-runtime").JSX.Element;
+declare namespace MultiSelectOptionComponent {
+    var displayName: string;
+}
+declare function MultiSelectGroupComponent({ className, children }: MultiSelectGroupProps): import("react/jsx-runtime").JSX.Element;
+declare namespace MultiSelectGroupComponent {
+    var displayName: string;
+}
+declare function MultiSelectLabelComponent({ className, children }: MultiSelectLabelProps): import("react/jsx-runtime").JSX.Element;
+declare namespace MultiSelectLabelComponent {
+    var displayName: string;
+}
+type MultiSelectCompound = typeof MultiSelectRoot & {
+    Trigger: typeof MultiSelectTriggerComponent;
+    Content: typeof MultiSelectContentComponent;
+    Option: typeof MultiSelectOptionComponent;
+    Group: typeof MultiSelectGroupComponent;
+    Label: typeof MultiSelectLabelComponent;
+};
+export declare const MultiSelect: MultiSelectCompound;
+export declare const MultiSelectTrigger: typeof MultiSelectTriggerComponent;
+export declare const MultiSelectContent: typeof MultiSelectContentComponent;
+export declare const MultiSelectOption: typeof MultiSelectOptionComponent;
+export declare const MultiSelectGroup: typeof MultiSelectGroupComponent;
+export declare const MultiSelectLabel: typeof MultiSelectLabelComponent;
+export { useMultiSelectContext as useMultiSelect } from './MultiSelectContext';