@tangible/ui 0.0.1 → 0.0.2

package/utils/compose-events.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Compose two event handlers into one.
+ * Internal handler runs first, then user handler (if not defaultPrevented).
+ *
+ * Use this instead of relying on spread order when combining handlers
+ * from different sources (e.g., Floating UI props + our handlers).
+ *
+ * @example
+ * const props = getReferenceProps({
+ *   onPointerDown: composeEventHandlers(ourHandler, floatingHandler),
+ * });
+ */
+export declare function composeEventHandlers<E extends {
+    defaultPrevented?: boolean;
+}>(internalHandler: ((event: E) => void) | undefined, userHandler: ((event: E) => void) | undefined): ((event: E) => void) | undefined;

package/utils/compose-events.js

@@ -0,0 +1,27 @@
+/**
+ * Compose two event handlers into one.
+ * Internal handler runs first, then user handler (if not defaultPrevented).
+ *
+ * Use this instead of relying on spread order when combining handlers
+ * from different sources (e.g., Floating UI props + our handlers).
+ *
+ * @example
+ * const props = getReferenceProps({
+ *   onPointerDown: composeEventHandlers(ourHandler, floatingHandler),
+ * });
+ */
+export function composeEventHandlers(internalHandler, userHandler) {
+    if (!internalHandler && !userHandler)
+        return undefined;
+    if (!internalHandler)
+        return userHandler;
+    if (!userHandler)
+        return internalHandler;
+    return (event) => {
+        internalHandler(event);
+        // Only call user handler if internal didn't prevent default
+        if (!event.defaultPrevented) {
+            userHandler(event);
+        }
+    };
+}

package/utils/hash.d.ts

@@ -0,0 +1,15 @@
+/**
+ * FNV-1a 32-bit hash function.
+ * Fast, deterministic, low collision risk for typical string inputs.
+ * Used for generating stable DOM IDs from arbitrary values.
+ */
+/**
+ * Generate a short, stable hash string from any value.
+ * Returns base36-encoded FNV-1a hash (6-7 chars).
+ *
+ * @example
+ * hashForId('apple') // 'k7x2m1'
+ * hashForId('foo/bar') // 'a3b4c5'
+ * hashForId('foo:bar') // 'd6e7f8' (different from foo/bar)
+ */
+export declare function hashForId(value: string | number): string;

package/utils/hash.js

@@ -0,0 +1,32 @@
+/**
+ * FNV-1a 32-bit hash function.
+ * Fast, deterministic, low collision risk for typical string inputs.
+ * Used for generating stable DOM IDs from arbitrary values.
+ */
+const FNV_OFFSET_BASIS = 2166136261;
+const FNV_PRIME = 16777619;
+/**
+ * Compute FNV-1a 32-bit hash of a string.
+ */
+function fnv1a32(str) {
+    let hash = FNV_OFFSET_BASIS;
+    for (let i = 0; i < str.length; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = Math.imul(hash, FNV_PRIME);
+    }
+    // Convert to unsigned 32-bit
+    return hash >>> 0;
+}
+/**
+ * Generate a short, stable hash string from any value.
+ * Returns base36-encoded FNV-1a hash (6-7 chars).
+ *
+ * @example
+ * hashForId('apple') // 'k7x2m1'
+ * hashForId('foo/bar') // 'a3b4c5'
+ * hashForId('foo:bar') // 'd6e7f8' (different from foo/bar)
+ */
+export function hashForId(value) {
+    const str = typeof value === 'string' ? value : String(value);
+    return fnv1a32(str).toString(36);
+}

package/utils/index.d.ts

@@ -8,3 +8,6 @@ export { mergeProps } from './merge-props';
 export { cx } from './cx';
 export { getContrastTone, getContrastForeground } from './color/contrast';
 export type { ContrastTone } from './color/contrast';
+export { hashForId } from './hash';
+export { composeEventHandlers } from './compose-events';
+export { useControllableState } from './use-controllable-state';

package/utils/index.js

@@ -14,3 +14,9 @@ export { mergeProps } from './merge-props.js';
 export { cx } from './cx.js';
 // Contrast utilities (for user-selected colors)
 export { getContrastTone, getContrastForeground } from './color/contrast.js';
+// Hash utilities (for stable DOM IDs)
+export { hashForId } from './hash.js';
+// Event composition
+export { composeEventHandlers } from './compose-events.js';
+// Controllable state hook
+export { useControllableState } from './use-controllable-state.js';

package/utils/is-dev.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Check if we're in a development environment.
+ * Uses Vite's import.meta.env.DEV — safe for SSR and production builds.
+ */
+export declare function isDev(): boolean;

package/utils/is-dev.js

@@ -0,0 +1,7 @@
+/**
+ * Check if we're in a development environment.
+ * Uses Vite's import.meta.env.DEV — safe for SSR and production builds.
+ */
+export function isDev() {
+    return typeof import.meta !== 'undefined' && import.meta.env?.DEV === true;
+}

package/utils/use-controllable-state.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared controlled/uncontrolled state hook.
+ *
+ * - When `value` is provided (not `undefined`): controlled mode. Setter only fires `onChange`.
+ * - When `value` is `undefined`: uncontrolled mode. Setter updates internal state AND fires `onChange`.
+ * - `isControlled` override: for components where `undefined` is a valid controlled value
+ *   (e.g. ChipGroup single-select deselection). Pass `true` to force controlled mode
+ *   even when value is `undefined`.
+ * - Supports functional updates: `setValue(prev => next)`.
+ * - `defaultValue` seeds the internal state (callers decide their own fallback).
+ * - The returned setter is stable across renders.
+ */
+export declare function useControllableState<T>({ value, defaultValue, onChange, isControlled: isControlledOverride, }: {
+    value?: T;
+    defaultValue?: T;
+    onChange?: (value: T) => void;
+    /** Force controlled mode even when value is undefined. */
+    isControlled?: boolean;
+}): [T | undefined, (next: T | ((prev: T | undefined) => T)) => void];

package/utils/use-controllable-state.js

@@ -0,0 +1,59 @@
+import { useState, useCallback, useRef, useEffect } from 'react';
+import { isDev as checkIsDev } from './is-dev.js';
+/**
+ * Shared controlled/uncontrolled state hook.
+ *
+ * - When `value` is provided (not `undefined`): controlled mode. Setter only fires `onChange`.
+ * - When `value` is `undefined`: uncontrolled mode. Setter updates internal state AND fires `onChange`.
+ * - `isControlled` override: for components where `undefined` is a valid controlled value
+ *   (e.g. ChipGroup single-select deselection). Pass `true` to force controlled mode
+ *   even when value is `undefined`.
+ * - Supports functional updates: `setValue(prev => next)`.
+ * - `defaultValue` seeds the internal state (callers decide their own fallback).
+ * - The returned setter is stable across renders.
+ */
+export function useControllableState({ value, defaultValue, onChange, isControlled: isControlledOverride, }) {
+    const [internalValue, setInternalValue] = useState(defaultValue);
+    // Keep refs so the setter callback stays stable
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const internalRef = useRef(internalValue);
+    internalRef.current = internalValue;
+    const isControlled = isControlledOverride ?? value !== undefined;
+    const currentValue = isControlled ? value : internalValue;
+    // Ref for stable setter — tracks controlled state
+    const isControlledRef = useRef(isControlled);
+    isControlledRef.current = isControlled;
+    const controlledValueRef = useRef(value);
+    controlledValueRef.current = value;
+    // Dev-only: warn if component switches between controlled and uncontrolled
+    const wasControlledRef = useRef(isControlled);
+    useEffect(() => {
+        if (checkIsDev()) {
+            if (wasControlledRef.current && !isControlled) {
+                console.warn('useControllableState: Switching from controlled to uncontrolled. This is likely a bug. Decide between using a controlled or uncontrolled value for the lifetime of the component.');
+            }
+            if (!wasControlledRef.current && isControlled) {
+                console.warn('useControllableState: Switching from uncontrolled to controlled. This is likely a bug. Decide between using a controlled or uncontrolled value for the lifetime of the component.');
+            }
+            wasControlledRef.current = isControlled;
+        }
+    }, [isControlled]);
+    const setValue = useCallback((next) => {
+        // Resolve functional updates using the appropriate source of truth
+        const prev = isControlledRef.current
+            ? controlledValueRef.current
+            : internalRef.current;
+        const resolvedNext = typeof next === 'function'
+            ? next(prev)
+            : next;
+        if (!isControlledRef.current) {
+            // Uncontrolled — update internal state
+            setInternalValue(resolvedNext);
+            internalRef.current = resolvedNext;
+        }
+        onChangeRef.current?.(resolvedNext);
+    }, [] // Stable — reads everything from refs
+    );
+    return [currentValue, setValue];
+}

package/utils/use-roving-group.d.ts

@@ -0,0 +1,33 @@
+import type { OptionValue } from './value-key';
+export type RovingItemRecord = {
+    value: OptionValue;
+    element: HTMLElement;
+    disabled: boolean;
+    /** Internal — assigned by registry on first mount */
+    mountIndex: number;
+};
+type UseRovingGroupOptions = {
+    selectedValue: OptionValue | undefined;
+    onSelect: (value: OptionValue) => void;
+    /** Group-level disabled. Default false. */
+    disabled?: boolean;
+    /** Wrap around at boundaries. Default true. */
+    loop?: boolean;
+    /** Layout orientation. Default 'horizontal'. */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Whether only orientation-matching arrow keys navigate.
+     *
+     * - `false` (default): All 4 arrows work — WAI-ARIA APG Radio Group pattern.
+     * - `true`: Only orientation-matching arrows work — Tabs/Toolbar pattern.
+     */
+    orientationKeyboard?: boolean;
+};
+export declare function useRovingGroup({ selectedValue, onSelect, disabled, loop, orientation, orientationKeyboard, }: UseRovingGroupOptions): {
+    registerItem: (record: Omit<RovingItemRecord, "mountIndex">) => void;
+    unregisterItem: (value: OptionValue) => void;
+    getOrderedItems: () => readonly RovingItemRecord[];
+    focusableValue: OptionValue | undefined;
+    handleKeyDown: (event: React.KeyboardEvent) => void;
+};
+export {};

package/utils/use-roving-group.js

@@ -0,0 +1,123 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { toKey } from './value-key.js';
+export function useRovingGroup({ selectedValue, onSelect, disabled = false, loop = true, orientation = 'horizontal', orientationKeyboard = false, }) {
+    const [registryVersion, setRegistryVersion] = useState(0);
+    const itemsRef = useRef(new Map());
+    const mountCounterRef = useRef(0);
+    // ── Item registration ──────────────────────────────────────────────────
+    const registerItem = useCallback((record) => {
+        const key = toKey(record.value);
+        const existing = itemsRef.current.get(key);
+        itemsRef.current.set(key, {
+            ...record,
+            mountIndex: existing?.mountIndex ?? mountCounterRef.current++,
+        });
+        setRegistryVersion((v) => v + 1);
+    }, []);
+    const unregisterItem = useCallback((value) => {
+        itemsRef.current.delete(toKey(value));
+        setRegistryVersion((v) => v + 1);
+    }, []);
+    // ── DOM-order sort ─────────────────────────────────────────────────────
+    const getOrderedItems = useCallback(() => {
+        const items = [...itemsRef.current.values()];
+        return items.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;
+            return a.mountIndex - b.mountIndex;
+        });
+    }, []);
+    // ── Focusable value (which item gets tabIndex={0}) ─────────────────────
+    const focusableValue = useMemo(() => {
+        const items = getOrderedItems();
+        const enabledItems = items.filter((item) => !item.disabled && !disabled);
+        if (enabledItems.length === 0)
+            return undefined;
+        // Selected + enabled item gets focus
+        if (selectedValue !== undefined) {
+            const selectedItem = items.find((item) => toKey(item.value) === toKey(selectedValue));
+            if (selectedItem && !selectedItem.disabled && !disabled) {
+                return selectedValue;
+            }
+        }
+        // Otherwise first enabled item
+        return enabledItems[0].value;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [selectedValue, disabled, getOrderedItems, registryVersion]);
+    // ── Keyboard navigation ────────────────────────────────────────────────
+    const handleKeyDown = useCallback((event) => {
+        const items = getOrderedItems().filter((item) => !item.disabled && !disabled);
+        if (items.length === 0)
+            return;
+        let currentIndex = selectedValue !== undefined
+            ? items.findIndex((item) => toKey(item.value) === toKey(selectedValue))
+            : -1;
+        if (currentIndex === -1)
+            currentIndex = 0;
+        // Determine which keys map to next/prev
+        let nextKeys;
+        let prevKeys;
+        if (orientationKeyboard) {
+            // Only orientation-matching arrows (Tabs/Toolbar pattern)
+            nextKeys =
+                orientation === 'horizontal' ? ['ArrowRight'] : ['ArrowDown'];
+            prevKeys =
+                orientation === 'horizontal' ? ['ArrowLeft'] : ['ArrowUp'];
+        }
+        else {
+            // All 4 arrows (Radio Group pattern)
+            nextKeys = ['ArrowRight', 'ArrowDown'];
+            prevKeys = ['ArrowLeft', 'ArrowUp'];
+        }
+        let targetIndex = null;
+        if (nextKeys.includes(event.key)) {
+            event.preventDefault();
+            if (loop) {
+                targetIndex = (currentIndex + 1) % items.length;
+            }
+            else {
+                targetIndex = Math.min(currentIndex + 1, items.length - 1);
+            }
+        }
+        else if (prevKeys.includes(event.key)) {
+            event.preventDefault();
+            if (loop) {
+                targetIndex = (currentIndex - 1 + items.length) % items.length;
+            }
+            else {
+                targetIndex = Math.max(currentIndex - 1, 0);
+            }
+        }
+        else if (event.key === 'Home') {
+            event.preventDefault();
+            targetIndex = 0;
+        }
+        else if (event.key === 'End') {
+            event.preventDefault();
+            targetIndex = items.length - 1;
+        }
+        if (targetIndex !== null && targetIndex !== currentIndex) {
+            const targetItem = items[targetIndex];
+            targetItem.element.focus();
+            onSelect(targetItem.value);
+        }
+    }, [
+        getOrderedItems,
+        disabled,
+        selectedValue,
+        orientationKeyboard,
+        orientation,
+        loop,
+        onSelect,
+    ]);
+    return {
+        registerItem,
+        unregisterItem,
+        getOrderedItems,
+        focusableValue,
+        handleKeyDown,
+    };
+}

package/utils/value-key.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared value-key utility for selection components.
+ *
+ * All components that track selection by value (Select, MultiSelect, Combobox,
+ * Radio, ChipGroup) use this to normalise string | number values into string
+ * keys for Map/Set lookups and equality comparisons.
+ */
+/**
+ * Value type accepted by selection components.
+ */
+export type OptionValue = string | number;
+/**
+ * Normalise a value to a string key for Map/Set lookups.
+ * Prefixes with type indicator to avoid collisions between 1 (number) and "1" (string).
+ */
+export declare function toKey(value: OptionValue): string;

package/utils/value-key.js

@@ -0,0 +1,14 @@
+/**
+ * Shared value-key utility for selection components.
+ *
+ * All components that track selection by value (Select, MultiSelect, Combobox,
+ * Radio, ChipGroup) use this to normalise string | number values into string
+ * keys for Map/Set lookups and equality comparisons.
+ */
+/**
+ * Normalise a value to a string key for Map/Set lookups.
+ * Prefixes with type indicator to avoid collisions between 1 (number) and "1" (string).
+ */
+export function toKey(value) {
+    return typeof value === 'number' ? `n:${value}` : `s:${value}`;
+}