entangle-ui 0.8.2 → 0.10.0

package/dist/esm/hooks/useDebounced/useDebouncedCallback.js

@@ -0,0 +1,102 @@
+"use client";
+import { useRef, useCallback, useMemo, useEffect } from 'react';
+import { useEventCallback } from '../useEventCallback/useEventCallback.js';
+
+/**
+ * Wrap a function so rapid calls collapse into one. By default the call
+ * fires on the trailing edge — pass `leading: true` to also fire
+ * immediately. `maxWait` forces a call even when calls keep coming.
+ *
+ * The wrapper identity is stable; passing fresh inline functions across
+ * renders is safe and does not reset pending timers.
+ *
+ * @example
+ * ```tsx
+ * const onResize = useDebouncedCallback(measure, 150);
+ * useEffect(() => {
+ *   window.addEventListener('resize', onResize);
+ *   return () => window.removeEventListener('resize', onResize);
+ * }, [onResize]);
+ * ```
+ */
+function useDebouncedCallback(fn, delay, options = {}) {
+    const { leading = false, maxWait } = options;
+    // Stable wrapper that always invokes the current callback, refreshed via
+    // useInsertionEffect so the debounced wrapper never goes stale.
+    const stableFn = useEventCallback(fn);
+    const timerRef = useRef(null);
+    const maxTimerRef = useRef(null);
+    const lastArgsRef = useRef(null);
+    const lastInvokeRef = useRef(0);
+    const clearTimers = useCallback(() => {
+        if (timerRef.current !== null) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+        if (maxTimerRef.current !== null) {
+            clearTimeout(maxTimerRef.current);
+            maxTimerRef.current = null;
+        }
+    }, []);
+    const invoke = useCallback(() => {
+        const args = lastArgsRef.current;
+        lastArgsRef.current = null;
+        lastInvokeRef.current = Date.now();
+        clearTimers();
+        if (args)
+            stableFn(...args);
+    }, [clearTimers, stableFn]);
+    const debounced = useMemo(() => {
+        const wrapper = (...args) => {
+            lastArgsRef.current = args;
+            // Date.now() runs only when the wrapper is invoked from an event/timer,
+            // never during render, so it is not a render-purity concern here.
+            // eslint-disable-next-line react-hooks/purity
+            const now = Date.now();
+            const isLeadingCall = leading && timerRef.current === null && maxTimerRef.current === null;
+            if (isLeadingCall) {
+                // Fire immediately, then suppress trailing for `delay` ms unless
+                // additional calls happen — in that case the trailing handler will
+                // pick them up.
+                lastArgsRef.current = null;
+                lastInvokeRef.current = now;
+                stableFn(...args);
+            }
+            if (timerRef.current !== null)
+                clearTimeout(timerRef.current);
+            timerRef.current = setTimeout(() => {
+                timerRef.current = null;
+                if (lastArgsRef.current !== null)
+                    invoke();
+                else if (maxTimerRef.current !== null) {
+                    clearTimeout(maxTimerRef.current);
+                    maxTimerRef.current = null;
+                }
+            }, delay);
+            if (maxWait !== undefined && maxTimerRef.current === null) {
+                maxTimerRef.current = setTimeout(() => {
+                    maxTimerRef.current = null;
+                    if (lastArgsRef.current !== null)
+                        invoke();
+                }, maxWait);
+            }
+        };
+        wrapper.cancel = () => {
+            lastArgsRef.current = null;
+            clearTimers();
+        };
+        wrapper.flush = () => {
+            if (lastArgsRef.current !== null)
+                invoke();
+            else
+                clearTimers();
+        };
+        return wrapper;
+    }, [delay, leading, maxWait, invoke, clearTimers, stableFn]);
+    // Cleanup on unmount.
+    useEffect(() => clearTimers, [clearTimers]);
+    return debounced;
+}
+
+export { useDebouncedCallback };
+//# sourceMappingURL=useDebouncedCallback.js.map

package/dist/esm/hooks/useDebounced/useDebouncedCallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedCallback.js","sources":["../../../../../src/hooks/useDebounced/useDebouncedCallback.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAWA;;;;;;;;;;;;;;;;AAgBG;AACG;;;;AASJ;AAEA;AACA;AACA;AACA;AAEA;AACE;AACE;AACA;;AAEF;AACE;AACA;;;AAIJ;AACE;AACA;AACA;AACA;AACA;AAAU;AACZ;AAEA;AACE;AACE;;;;AAIA;AACA;;;;;AAOE;AACA;AACA;;AAGF;AAA+B;AAC/B;AACE;AACA;AAAkC;AAC7B;AACH;AACA;;;;AAKF;AACE;AACA;AAAkC;;;AAGxC;AAEA;AACE;AACA;AACF;AACA;AACE;AAAkC;;AAC7B;AACP;AAEA;AACF;;;AAKA;AACF;;"}

package/dist/esm/hooks/useDebounced/useDebouncedValue.js

@@ -0,0 +1,47 @@
+"use client";
+import { useState, useEffect } from 'react';
+
+/**
+ * Returns a copy of `value` that updates only after `delay` ms have elapsed
+ * without further changes (trailing-edge debounce).
+ *
+ * @deprecated Prefer React's `useDeferredValue` for the common case — keeping
+ * an input responsive while an expensive derivation (filtering, search) lags
+ * behind it. It needs no fixed delay, integrates with concurrent rendering,
+ * and gives better interactivity on large lists. Reach for `useDebouncedCallback`
+ * when you need to debounce a *side effect* (a network request, an analytics
+ * ping) rather than a rendered value. This hook stays exported for now but
+ * will not see further work.
+ *
+ * @example
+ * ```tsx
+ * // Preferred: defer the value that drives the expensive derivation.
+ * const deferredQuery = useDeferredValue(query);
+ * const results = useMemo(
+ *   () => filter(items, deferredQuery),
+ *   [items, deferredQuery]
+ * );
+ * ```
+ */
+function useDebouncedValue(value, delay) {
+    const [debounced, setDebounced] = useState(value);
+    useEffect(() => {
+        if (delay <= 0) {
+            // Synchronous passthrough when debouncing is disabled; this hook's whole
+            // purpose is to mirror an external value into state.
+            // eslint-disable-next-line react-hooks/set-state-in-effect
+            setDebounced(value);
+            return;
+        }
+        const id = setTimeout(() => {
+            setDebounced(value);
+        }, delay);
+        return () => {
+            clearTimeout(id);
+        };
+    }, [value, delay]);
+    return debounced;
+}
+
+export { useDebouncedValue };
+//# sourceMappingURL=useDebouncedValue.js.map

package/dist/esm/hooks/useDebounced/useDebouncedValue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedValue.js","sources":["../../../../../src/hooks/useDebounced/useDebouncedValue.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACG;;;AAIF;;;;;;;AAOA;;;AAGA;;AAEA;AACF;AAEA;AACF;;"}

package/dist/esm/hooks/useDisclosure/useDisclosure.js.map

@@ -1 +1 @@
-{"version":3,"file":"useDisclosure.js","sources":["../../../../../src/hooks/useDisclosure/useDisclosure.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AASA;;;;;;;;;;;;;;;;;;;AAmBG;AACG;;AAKJ;AACE;AACA;AACA;AACA;AACD;AAED;;AAGE;AAIF;;AAEA;AAEA;;AAEA;AAEA;;AAEA;AAEA;AAIF;;"}
+{"version":3,"file":"useDisclosure.js","sources":["../../../../../src/hooks/useDisclosure/useDisclosure.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAWA;;;;;;;;;;;;;;;;;;;AAmBG;AACG;;AAKJ;AACE;AACA;AACA;AACA;AACD;AAED;;AAGE;AAIF;;AAEA;AAEA;;AAEA;AAEA;;AAEA;AAEA;AAIF;;"}

package/dist/esm/hooks/useEventCallback/useEventCallback.js

@@ -0,0 +1,49 @@
+"use client";
+import { useRef, useInsertionEffect, useCallback } from 'react';
+
+/**
+ * Wrap a callback so its identity stays stable for the component lifetime
+ * while it always invokes the most recently rendered version — the
+ * `useEffectEvent` pattern, backed by `useInsertionEffect`.
+ *
+ * The stored callback is refreshed in `useInsertionEffect`, which commits
+ * before any layout effect. So the freshness guarantee holds even for
+ * consumers that read it during the same commit: a child's
+ * `useLayoutEffect`, a synchronous external-store subscription, an
+ * imperative handle. A passively updated ref (e.g. `useLatest`, which writes
+ * in `useEffect`) would still be one render stale in those cases.
+ *
+ * Pass the result to memoized children, dependency arrays, or external
+ * subscriptions without re-subscribing — the reference never changes, yet it
+ * still closes over the latest props and state.
+ *
+ * The one rule: do not call it during render. Like an event handler it reads
+ * through a ref, so a render-phase call has no meaningful "latest" value to
+ * read. Use it in event handlers, effects, layout effects, timers, and
+ * subscriptions only.
+ *
+ * @example
+ * ```tsx
+ * const handleChange = useEventCallback((value: string) => {
+ *   onChange?.(value, internalState);
+ * });
+ * useEffect(() => store.subscribe(handleChange), [handleChange]);
+ * ```
+ */
+function useEventCallback(fn) {
+    const ref = useRef(fn);
+    // Refresh the stored callback before layout effects run. useInsertionEffect
+    // commits earlier than useEffect / useLayoutEffect, so children's layout
+    // effects and synchronous subscriptions firing in the same commit already
+    // observe the latest callback.
+    useInsertionEffect(() => {
+        ref.current = fn;
+    }, [fn]);
+    // Stable wrapper for the component lifetime. Reading `ref.current` happens
+    // only when the wrapper is invoked from an event, effect, or timer — never
+    // during render.
+    return useCallback((...args) => ref.current(...args), []);
+}
+
+export { useEventCallback };
+//# sourceMappingURL=useEventCallback.js.map

package/dist/esm/hooks/useEventCallback/useEventCallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEventCallback.js","sources":["../../../../../src/hooks/useEventCallback/useEventCallback.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BG;AACG;AAGJ;;;;;;AAOE;AACF;;;;AAKA;AACF;;"}

package/dist/esm/hooks/useFocusTrap/useFocusTrap.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFocusTrap.js","sources":["../../../../../src/hooks/useFocusTrap/useFocusTrap.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;;AAOC;AAaD;;;;;;;;;;;;;AAaG;AACG;AAIJ;AAEI;;AAEA;AACA;;AAEA;AAIA;;;;AAKA;;AAKA;AACE;;;;;;AAKA;;;;;AAKJ;AAGJ;;"}
+{"version":3,"file":"useFocusTrap.js","sources":["../../../../../src/hooks/useFocusTrap/useFocusTrap.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAMA;;;;;;;AAOC;AAaD;;;;;;;;;;;;;AAaG;AACG;AAIJ;AAEI;;AAEA;AACA;;AAEA;AAIA;;;;AAKA;;AAKA;AACE;;;;;;AAKA;;;;;AAKJ;AAGJ;;"}

package/dist/esm/hooks/useHotkey/useHotkey.js

@@ -1,5 +1,6 @@
 "use client";
-import { useRef, useMemo, useEffect } from 'react';
+import { useMemo, useRef, useEffect } from 'react';
+import { useLatest } from '../useLatest/useLatest.js';
 import { parseShortcut, getPlatform } from '../../utils/platform.js';
 
 function isRefObject(value) {
@@ -136,23 +137,17 @@ function matches(parsed, event) {
  */
 function useHotkey(combo, handler, options = {}) {
     const { enabled = true, enableInInputs = false, preventDefault = true, stopPropagation = false, target, } = options;
-    const handlerRef = useRef(handler);
-    handlerRef.current = handler;
-    const optionsRef = useRef({
+    // Latest handler / options / parsed combo, refreshed after each commit so
+    // the document listener reads live values without re-subscribing.
+    const handlerRef = useLatest(handler);
+    const optionsRef = useLatest({
         enabled,
         enableInInputs,
         preventDefault,
         stopPropagation,
     });
-    optionsRef.current = {
-        enabled,
-        enableInInputs,
-        preventDefault,
-        stopPropagation,
-    };
     const parsed = useMemo(() => parseCombo(combo), [combo]);
-    const parsedRef = useRef(parsed);
-    parsedRef.current = parsed;
+    const parsedRef = useLatest(parsed);
     const attachedTargetRef = useRef(null);
     const listenerRef = useRef(null);
     // Runs every render so a ref whose `.current` becomes available after the

package/dist/esm/hooks/useHotkey/useHotkey.js.map

@@ -1 +1 @@
-{"version":3,"file":"useHotkey.js","sources":["../../../../../src/hooks/useHotkey/useHotkey.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAMA;AACE;AAEE;;AAGJ;AAEA;AACE;AACE;;;AAEmB;;;AAErB;AACF;AAWA;AAEA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGF;AACE;AACA;AACF;AAEA;AACE;AACA;AAAwB;AAExB;AACA;;;;;;AAQA;AACE;AACA;;AAEI;;;AAGA;;;;;;;;;AAQA;;;AAGA;AACA;;;AAGA;;;;;;AAKF;;;;AAIc;;AAEpB;AAEA;AACE;AAAsC;;AACR;AAC9B;AACA;;;AAGE;;;;;;;;;;AAUC;AACD;;AAEF;AACF;AAEA;AACE;AAAmC;AACnC;AAAmC;AACnC;AAAiC;AACjC;AAAqC;;AAGrC;AACF;AAEA;;;;;;;;;;;;;;;;;AAiBG;AACG;;AAaJ;AACA;;;;;;AAOC;;;;;;;AAQD;AACA;AACA;AAEA;AACA;;;;;;AAOE;AACA;;;;;AAQA;AACA;AACE;;;AAIF;;AAEE;AACA;AACA;;AACA;;;;;;AAIA;;;AAEF;AACA;AACA;AACF;AAEA;;;;AAQI;AACA;;AAIN;;"}
+{"version":3,"file":"useHotkey.js","sources":["../../../../../src/hooks/useHotkey/useHotkey.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAUA;AACE;AAEE;;AAGJ;AAEA;AACE;AACE;;;AAEmB;;;AAErB;AACF;AAWA;AAEA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGF;AACE;AACA;AACF;AAEA;AACE;AACA;AAAwB;AAExB;AACA;;;;;;AAQA;AACE;AACA;;AAEI;;;AAGA;;;;;;;;;AAQA;;;AAGA;AACA;;;AAGA;;;;;;AAKF;;;;AAIc;;AAEpB;AAEA;AACE;AAAsC;;AACR;AAC9B;AACA;;;AAGE;;;;;;;;;;AAUC;AACD;;AAEF;AACF;AAEA;AACE;AAAmC;AACnC;AAAmC;AACnC;AAAiC;AACjC;AAAqC;;AAGrC;AACF;AAEA;;;;;;;;;;;;;;;;;AAiBG;AACG;;;;AAeJ;;;;;;AAMC;AAED;AACA;AAEA;AACA;;;;;;AAOE;AACA;;;;;AAQA;AACA;AACE;;;AAIF;;AAEE;AACA;AACA;;AACA;;;;;;AAIA;;;AAEF;AACA;AACA;AACF;AAEA;;;;AAQI;AACA;;AAIN;;"}

package/dist/esm/hooks/useIntersectionObserver/useIntersectionObserver.js

@@ -0,0 +1,75 @@
+"use client";
+import { useState, useRef, useCallback, useEffect } from 'react';
+
+/**
+ * Observe whether an element intersects a root (defaults to the viewport).
+ * Returns a ref callback to attach to the observed element plus the latest
+ * `IntersectionObserverEntry`. SSR-safe: returns a no-op ref and `null`
+ * entry when `IntersectionObserver` is unavailable.
+ *
+ * @example
+ * ```tsx
+ * const { ref, isIntersecting } = useIntersectionObserver<HTMLDivElement>({
+ *   rootMargin: '200px',
+ * });
+ * useEffect(() => {
+ *   if (isIntersecting) loadMore();
+ * }, [isIntersecting]);
+ * return <div ref={ref} />;
+ * ```
+ */
+function useIntersectionObserver(options = {}) {
+    const { root, rootMargin, threshold, enabled = true } = options;
+    const [entry, setEntry] = useState(null);
+    const observerRef = useRef(null);
+    const nodeRef = useRef(null);
+    const ref = useCallback(node => {
+        if (typeof IntersectionObserver === 'undefined') {
+            nodeRef.current = node;
+            return;
+        }
+        if (observerRef.current) {
+            observerRef.current.disconnect();
+            observerRef.current = null;
+        }
+        nodeRef.current = node;
+        if (!enabled || !node) {
+            setEntry(null);
+            return;
+        }
+        const observer = new IntersectionObserver(entries => {
+            const next = entries[0];
+            if (next)
+                setEntry(next);
+        }, { root: root ?? null, rootMargin, threshold });
+        observer.observe(node);
+        observerRef.current = observer;
+    }, [root, rootMargin, threshold, enabled]);
+    // When toggled off via `enabled`, disconnect proactively so consumers don't
+    // have to detach the ref to stop observing.
+    useEffect(() => {
+        if (enabled)
+            return;
+        if (observerRef.current) {
+            observerRef.current.disconnect();
+            observerRef.current = null;
+        }
+        // Sync state to the external observer being torn down when disabled.
+        // eslint-disable-next-line react-hooks/set-state-in-effect
+        setEntry(null);
+    }, [enabled]);
+    // Final cleanup on unmount.
+    useEffect(() => () => {
+        observerRef.current?.disconnect();
+        observerRef.current = null;
+        nodeRef.current = null;
+    }, []);
+    return {
+        ref,
+        entry,
+        isIntersecting: entry?.isIntersecting ?? false,
+    };
+}
+
+export { useIntersectionObserver };
+//# sourceMappingURL=useIntersectionObserver.js.map

package/dist/esm/hooks/useIntersectionObserver/useIntersectionObserver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIntersectionObserver.js","sources":["../../../../../src/hooks/useIntersectionObserver/useIntersectionObserver.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAUA;;;;;;;;;;;;;;;;AAgBG;AACG;AAGJ;;AAGA;AACA;AAEA;AAEI;AACE;;;AAIF;AACE;AACA;;AAGF;AACA;;;;AAKA;AAEI;AACA;;AACF;AAGF;AACA;;;;;AAQF;;AACA;AACE;AACA;;;;;AAKJ;;AAGA;AAEI;AACA;AACA;;;;;AAQF;;AAEJ;;"}

package/dist/esm/hooks/useIsMounted/useIsMounted.js

@@ -0,0 +1,43 @@
+"use client";
+import { useRef, useEffect, useCallback } from 'react';
+
+/**
+ * Returns a stable getter that reports whether the component is still
+ * mounted. Call it inside async continuations (promises, timers, fetches)
+ * before committing state, so a resolution that lands after unmount becomes
+ * a no-op instead of a "set state on an unmounted component" warning.
+ *
+ * The getter identity is stable for the component lifetime, so it is safe to
+ * include in — or omit from — dependency arrays without churn. It reports
+ * `false` until the mount effect commits and `false` again after unmount,
+ * which also covers the double mount/unmount of React StrictMode.
+ *
+ * Prefer real cancellation (`AbortController`, effect cleanup) where the
+ * async source supports it; reach for this only when the source cannot be
+ * cancelled.
+ *
+ * @example
+ * ```tsx
+ * const isMounted = useIsMounted();
+ * useEffect(() => {
+ *   void load().then(data => {
+ *     if (isMounted()) setData(data);
+ *   });
+ * }, [isMounted]);
+ * ```
+ */
+function useIsMounted() {
+    const mountedRef = useRef(false);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    // Reading `mountedRef.current` happens only when the getter is invoked from
+    // an async continuation or effect — never during render.
+    return useCallback(() => mountedRef.current, []);
+}
+
+export { useIsMounted };
+//# sourceMappingURL=useIsMounted.js.map

package/dist/esm/hooks/useIsMounted/useIsMounted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsMounted.js","sources":["../../../../../src/hooks/useIsMounted/useIsMounted.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;;;;;;;;;;AAwBG;;AAED;;AAGE;AACA;AACE;AACF;;;;;AAMJ;;"}

package/dist/esm/hooks/useKeyboard/useKeyboard.js.map

@@ -1 +1 @@
-{"version":3,"file":"useKeyboard.js","sources":["../../../../../src/hooks/useKeyboard/useKeyboard.tsx"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BG;AACI;AACL;AAIA;AACE;;AAGF;AACE;;;AAIA;AACA;AAEA;AACE;AACA;AACF;AACF;AAEA;AACF;;"}
+{"version":3,"file":"useKeyboard.js","sources":["../../../../../src/hooks/useKeyboard/useKeyboard.tsx"],"sourcesContent":[null],"names":[],"mappings":";;;;;AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BG;AACI;AACL;AAIA;AACE;;AAGF;AACE;;;AAIA;AACA;AAEA;AACE;AACA;AACF;AACF;AAEA;AACF;;"}

package/dist/esm/hooks/useKeyboard/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sources":["../../../../../src/hooks/useKeyboard/utils.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAQO,MAAM,aAAa,GAAG,CAAC,GAAW,KAAyB;AAChE,IAAA,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;AAClE;AAEA,MAAM,cAAc,GAAG,CACrB,SAA6B,EAC7B,GAAY,KACU;AACtB,IAAA,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;AACtB,QAAA,OAAO,SAAS;IAClB;AACA,IAAA,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC;AACnC,IAAA,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;AACjB,IAAA,OAAO,QAAQ;AACjB,CAAC;AAED,MAAM,gBAAgB,GAAG,CACvB,SAA6B,EAC7B,GAAY,KACU;IACtB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;AACvB,QAAA,OAAO,SAAS;IAClB;AACA,IAAA,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC;AACnC,IAAA,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC;AACpB,IAAA,OAAO,QAAQ;AACjB,CAAC;MAEY,WAAW,GAAG,CACzB,SAA6B,EAC7B,KAAoB,KACE;IACtB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE;AACnC,IAAA,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI;IAC5B,QAAQ,SAAS;AACf,QAAA,KAAK,SAAS;AACZ,YAAA,OAAO,cAAc,CAAC,SAAS,EAAE,GAAG,CAAC;AACvC,QAAA,KAAK,OAAO;AACV,YAAA,OAAO,gBAAgB,CAAC,SAAS,EAAE,GAAG,CAAC;AACzC,QAAA;AACE,YAAA,OAAO,CAAC,CAAA,sBAAA,EAAyB,SAAS,CAAA,CAAE,CAAC;AAC7C,YAAA,OAAO,SAAS;;AAEtB;AAEO,MAAM,oBAAoB,GAAG,CAClC,UAA8B,KACb;AACjB,IAAA,MAAM,SAAS,GAA+B;AAC5C,QAAA,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC;AAC5D,QAAA,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC;AAC9B,QAAA,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;AAC1B,QAAA,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC;KAC7B;IACD,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAC7E,OAAO;QACL,WAAW;QACX,SAAS;KACV;AACH;MAEa,YAAY,GAAG,CAC1B,aAA4B,EAC5B,GAAY,KACD;AACX,IAAA,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE;AACtB,QAAA,OAAO,aAAa,CAAC,SAAS,CAAC,GAAG,CAAC;IACrC;IACA,OAAO,aAAa,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC;AAChD;;;;"}
+{"version":3,"file":"utils.js","sources":["../../../../../src/hooks/useKeyboard/utils.ts"],"sourcesContent":[null],"names":[],"mappings":";;AASO,MAAM,aAAa,GAAG,CAAC,GAAW,KAAyB;AAChE,IAAA,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;AAClE;AAEA,MAAM,cAAc,GAAG,CACrB,SAA6B,EAC7B,GAAY,KACU;AACtB,IAAA,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;AACtB,QAAA,OAAO,SAAS;IAClB;AACA,IAAA,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC;AACnC,IAAA,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;AACjB,IAAA,OAAO,QAAQ;AACjB,CAAC;AAED,MAAM,gBAAgB,GAAG,CACvB,SAA6B,EAC7B,GAAY,KACU;IACtB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;AACvB,QAAA,OAAO,SAAS;IAClB;AACA,IAAA,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC;AACnC,IAAA,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC;AACpB,IAAA,OAAO,QAAQ;AACjB,CAAC;MAEY,WAAW,GAAG,CACzB,SAA6B,EAC7B,KAAoB,KACE;IACtB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE;AACnC,IAAA,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI;IAC5B,QAAQ,SAAS;AACf,QAAA,KAAK,SAAS;AACZ,YAAA,OAAO,cAAc,CAAC,SAAS,EAAE,GAAG,CAAC;AACvC,QAAA,KAAK,OAAO;AACV,YAAA,OAAO,gBAAgB,CAAC,SAAS,EAAE,GAAG,CAAC;AACzC,QAAA;AACE,YAAA,OAAO,CAAC,CAAA,sBAAA,EAAyB,SAAS,CAAA,CAAE,CAAC;AAC7C,YAAA,OAAO,SAAS;;AAEtB;AAEO,MAAM,oBAAoB,GAAG,CAClC,UAA8B,KACb;AACjB,IAAA,MAAM,SAAS,GAA+B;AAC5C,QAAA,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC;AAC5D,QAAA,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC;AAC9B,QAAA,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;AAC1B,QAAA,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC;KAC7B;IACD,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAC7E,OAAO;QACL,WAAW;QACX,SAAS;KACV;AACH;MAEa,YAAY,GAAG,CAC1B,aAA4B,EAC5B,GAAY,KACD;AACX,IAAA,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE;AACtB,QAAA,OAAO,aAAa,CAAC,SAAS,CAAC,GAAG,CAAC;IACrC;IACA,OAAO,aAAa,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC;AAChD;;;;"}

package/dist/esm/hooks/useLatest/useLatest.js

@@ -0,0 +1,31 @@
+"use client";
+import { useRef, useEffect } from 'react';
+
+/**
+ * Keep a ref synced to the latest value of `value` after each render.
+ *
+ * Useful for reading "live" props/state inside event handlers, timers,
+ * or external store subscriptions without re-attaching the listener on
+ * every render. The ref is updated in `useEffect` so its value reflects
+ * the most recently committed render.
+ *
+ * @example
+ * ```ts
+ * const latestOnChange = useLatest(onChange);
+ * useEffect(() => {
+ *   const handler = (e: Event) => latestOnChange.current(e);
+ *   target.addEventListener('change', handler);
+ *   return () => target.removeEventListener('change', handler);
+ * }, [target]);
+ * ```
+ */
+function useLatest(value) {
+    const ref = useRef(value);
+    useEffect(() => {
+        ref.current = value;
+    });
+    return ref;
+}
+
+export { useLatest };
+//# sourceMappingURL=useLatest.js.map

package/dist/esm/hooks/useLatest/useLatest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLatest.js","sources":["../../../../../src/hooks/useLatest/useLatest.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAMA;;;;;;;;;;;;;;;;;AAiBG;AACG;AACJ;;AAEE;AACF;AACA;AACF;;"}

package/dist/esm/hooks/useListboxNav/useListboxNav.js

@@ -0,0 +1,197 @@
+"use client";
+import { useState, useRef, useEffect, useCallback, useMemo } from 'react';
+import { useEventCallback } from '../useEventCallback/useEventCallback.js';
+
+/**
+ * Shared keyboard navigation for listbox-like surfaces (Select, MultiSelect,
+ * Combobox, CommandPalette). Tracks an `activeIndex`, skips disabled items,
+ * and exposes a single `handleKeyDown` covering Arrow / Home / End / Enter /
+ * Escape semantics.
+ *
+ * The hook is purely logical — consumers render the list and bind the handler
+ * to an input or the listbox container. Scroll-into-view is the consumer's
+ * concern.
+ *
+ * @example
+ * ```tsx
+ * const { activeIndex, handleKeyDown } = useListboxNav({
+ *   items: filtered,
+ *   isItemDisabled: o => o.disabled ?? false,
+ *   onSelect: (item) => commit(item),
+ *   onEscape: () => close(),
+ * });
+ * ```
+ */
+function useListboxNav(options) {
+    const { items, isItemDisabled, defaultActiveIndex = -1, loop = true, resetOnItemsChange = true, onSelect, onEscape, } = options;
+    const [activeIndex, setActiveIndex] = useState(defaultActiveIndex);
+    // Stable refs so handlers don't churn when callers pass inline closures.
+    const itemsRef = useRef(items);
+    const isItemDisabledRef = useRef(isItemDisabled);
+    const onSelectRef = useRef(onSelect);
+    const loopRef = useRef(loop);
+    useEffect(() => {
+        itemsRef.current = items;
+    }, [items]);
+    useEffect(() => {
+        isItemDisabledRef.current = isItemDisabled;
+    }, [isItemDisabled]);
+    useEffect(() => {
+        onSelectRef.current = onSelect;
+    }, [onSelect]);
+    useEffect(() => {
+        loopRef.current = loop;
+    }, [loop]);
+    // Reset active index when items reference changes (e.g. filter).
+    const prevItemsRef = useRef(items);
+    useEffect(() => {
+        if (!resetOnItemsChange)
+            return;
+        if (prevItemsRef.current !== items) {
+            setActiveIndex(defaultActiveIndex);
+            prevItemsRef.current = items;
+        }
+    }, [items, resetOnItemsChange, defaultActiveIndex]);
+    const getNavigableIndices = useCallback(() => {
+        const list = itemsRef.current;
+        const disabled = isItemDisabledRef.current;
+        if (!disabled)
+            return list.map((_, i) => i);
+        const out = [];
+        for (let i = 0; i < list.length; i += 1) {
+            const item = list[i];
+            if (!disabled(item, i))
+                out.push(i);
+        }
+        return out;
+    }, []);
+    // Reactive navigable-index list for the returned value. Derived from the
+    // live props rather than the latest-refs above, which exist only for reads
+    // inside the event-time keyboard handlers.
+    const navigableIndices = useMemo(() => {
+        if (!isItemDisabled)
+            return items.map((_, i) => i);
+        const out = [];
+        for (let i = 0; i < items.length; i += 1) {
+            const item = items[i];
+            if (!isItemDisabled(item, i))
+                out.push(i);
+        }
+        return out;
+    }, [items, isItemDisabled]);
+    const move = useCallback((direction) => {
+        const navigable = getNavigableIndices();
+        if (navigable.length === 0) {
+            setActiveIndex(-1);
+            return;
+        }
+        setActiveIndex(current => {
+            const currentNavIdx = navigable.indexOf(current);
+            switch (direction) {
+                case 'first':
+                    return navigable[0] ?? -1;
+                case 'last':
+                    return navigable[navigable.length - 1] ?? -1;
+                case 'next': {
+                    if (currentNavIdx === -1)
+                        return navigable[0] ?? -1;
+                    const nextIdx = currentNavIdx + 1;
+                    if (nextIdx >= navigable.length) {
+                        return loopRef.current
+                            ? (navigable[0] ?? -1)
+                            : (navigable[navigable.length - 1] ?? -1);
+                    }
+                    return navigable[nextIdx] ?? -1;
+                }
+                case 'prev': {
+                    if (currentNavIdx === -1)
+                        return navigable[navigable.length - 1] ?? -1;
+                    const prevIdx = currentNavIdx - 1;
+                    if (prevIdx < 0) {
+                        return loopRef.current
+                            ? (navigable[navigable.length - 1] ?? -1)
+                            : (navigable[0] ?? -1);
+                    }
+                    return navigable[prevIdx] ?? -1;
+                }
+            }
+        });
+    }, [getNavigableIndices]);
+    const next = useCallback(() => {
+        move('next');
+    }, [move]);
+    const prev = useCallback(() => {
+        move('prev');
+    }, [move]);
+    const first = useCallback(() => {
+        move('first');
+    }, [move]);
+    const last = useCallback(() => {
+        move('last');
+    }, [move]);
+    const selectActive = useCallback(() => {
+        const list = itemsRef.current;
+        const disabled = isItemDisabledRef.current;
+        setActiveIndex(current => {
+            if (current < 0 || current >= list.length)
+                return current;
+            const item = list[current];
+            if (disabled?.(item, current))
+                return current;
+            onSelectRef.current?.(item, current);
+            return current;
+        });
+    }, []);
+    // Escape handling via useEventCallback: stable identity (so handleKeyDown
+    // does not churn when callers pass an inline onEscape) while always seeing
+    // the latest onEscape and reporting whether it actually handled the key.
+    const handleEscape = useEventCallback((event) => {
+        if (!onEscape)
+            return false;
+        event.preventDefault();
+        onEscape();
+        return true;
+    });
+    const handleKeyDown = useCallback((event) => {
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault();
+                next();
+                return true;
+            case 'ArrowUp':
+                event.preventDefault();
+                prev();
+                return true;
+            case 'Home':
+                event.preventDefault();
+                first();
+                return true;
+            case 'End':
+                event.preventDefault();
+                last();
+                return true;
+            case 'Enter':
+                event.preventDefault();
+                selectActive();
+                return true;
+            case 'Escape':
+                return handleEscape(event);
+            default:
+                return false;
+        }
+    }, [next, prev, first, last, selectActive, handleEscape]);
+    return {
+        activeIndex,
+        setActiveIndex,
+        next,
+        prev,
+        first,
+        last,
+        selectActive,
+        handleKeyDown,
+        navigableIndices,
+    };
+}
+
+export { useListboxNav };
+//# sourceMappingURL=useListboxNav.js.map

package/dist/esm/hooks/useListboxNav/useListboxNav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useListboxNav.js","sources":["../../../../../src/hooks/useListboxNav/useListboxNav.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAiEA;;;;;;;;;;;;;;;;;;;AAmBG;AACG;;;;AAgBJ;AACA;AACA;AACA;;AAGE;AACF;;AAEE;AACF;;AAEE;AACF;;AAEE;AACF;;AAGA;;AAEE;;AACA;;AAEE;;;AAIJ;AACE;AACA;AACA;AAAe;;AAEf;AACE;AACA;AAAwB;;AAE1B;;;;;AAMF;AACE;AAAqB;;AAErB;AACE;AACA;AAA8B;;AAEhC;AACF;AAEA;AAEI;AACA;AACE;;;;;;AAOE;AACE;AACF;;;;AAG4B;AAC1B;AACA;;;AAGI;;AAEJ;;;;;AAKA;AACA;;AAEI;;;AAGJ;;;AAGN;AACF;AAIF;;AAEA;AACA;;AAEA;AACA;;AAEA;AACA;;AAEA;AAEA;AACE;AACA;;;AAE6C;AAC3C;AACA;AAA+B;;AAE/B;AACF;;;;;AAMF;AAEI;AAAe;;AAEf;AACA;AACF;AAGF;AAEI;AACE;;AAEE;AACA;AACF;;AAEE;AACA;AACF;;AAEE;AACA;AACF;;AAEE;AACA;AACF;;AAEE;AACA;AACF;AACE;AACF;AACE;;AAEN;;;;;;;;;;;;AAeJ;;"}