@rio-cloud/rio-uikit 2.1.0 → 2.2.1

package/hooks/usePostMessage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usePostMessage.js","sources":["../../src/hooks/usePostMessage.ts"],"sourcesContent":["import { useEffect } from 'react';\nimport { isEmpty, noop } from 'es-toolkit/compat';\n\nexport type RemoteAction = {\n    /**\n     * The RemoteAction is inspired by a plain redux action where the type is the\n     * action identifier.\n     *\n     * @example\n     *\n     * ```json\n     * {\n     *      \"type\": \"EVENT_SET_VISIBLE_WIDGETS\",\n     *      \"payload\": [\"foo\", \"bar\"],\n     * }\n     * ```\n     */\n    type: string;\n\n    /**\n     * The action payload itself.\n     */\n    payload: any;\n};\n\n/**\n * A custom hook to ease the exchange of postMessage events between iframes and the parent window.\n *\n * @param messagePrefix a custom prefix to limit the event listener for these events\n * @param onReceiveMessage a callback function triggered when a message is received\n * @returns\n */\nconst usePostMessage = (messagePrefix: string, onReceiveMessage?: (eventData: any) => void) => {\n    const sendMessageToParent = (message: RemoteAction) => {\n        const referrer = document.referrer;\n        if (referrer) {\n            window.parent.postMessage(message, referrer);\n        }\n    };\n\n    const sendMessageToWidget = (message: RemoteAction, targetFrames: HTMLIFrameElement | HTMLIFrameElement[]) => {\n        if (!targetFrames || isEmpty(targetFrames)) {\n            return;\n        }\n\n        const frames = Array.isArray(targetFrames) ? [...targetFrames] : [targetFrames];\n\n        [...frames].forEach(target => {\n            const contentWindow = target.contentWindow;\n            if (contentWindow) {\n                contentWindow.postMessage(message, '*');\n            }\n        });\n    };\n\n    const receiveMessage = (event: MessageEvent, callback: (eventData: any) => void) => {\n        const actionType = event.data.type;\n        if (!actionType) {\n            return;\n        }\n\n        if (actionType.startsWith(messagePrefix)) {\n            callback(event.data);\n        }\n    };\n\n    useEffect(() => {\n        const listenerCallback = (event: MessageEvent) => receiveMessage(event, onReceiveMessage || noop);\n        window.addEventListener('message', listenerCallback, false);\n        return () => window.removeEventListener('message', listenerCallback, false);\n    }, []);\n\n    return {\n        sendMessageToParent,\n        sendMessageToWidget,\n    };\n};\n\nexport default usePostMessage;\n"],"names":["usePostMessage","messagePrefix","onReceiveMessage","sendMessageToParent","message","referrer","sendMessageToWidget","targetFrames","isEmpty","target","contentWindow","receiveMessage","event","callback","actionType","useEffect","listenerCallback","noop"],"mappings":";;AAgCA,MAAMA,IAAiB,CAACC,GAAuBC,MAAgD;AAC3F,QAAMC,IAAsB,CAACC,MAA0B;AACnD,UAAMC,IAAW,SAAS;AAC1B,IAAIA,KACA,OAAO,OAAO,YAAYD,GAASC,CAAQ;AAAA,EAEnD,GAEMC,IAAsB,CAACF,GAAuBG,MAA0D;AAC1G,QAAI,CAACA,KAAgBC,EAAQD,CAAY;AACrC;AAKJ,KAAC,GAFc,MAAM,QAAQA,CAAY,IAAI,CAAC,GAAGA,CAAY,IAAI,CAACA,CAAY,CAEpE,EAAE,QAAQ,CAAAE,MAAU;AAC1B,YAAMC,IAAgBD,EAAO;AAC7B,MAAIC,KACAA,EAAc,YAAYN,GAAS,GAAG;AAAA,IAE9C,CAAC;AAAA,EACL,GAEMO,IAAiB,CAACC,GAAqBC,MAAuC;AAChF,UAAMC,IAAaF,EAAM,KAAK;AAC9B,IAAKE,KAIDA,EAAW,WAAWb,CAAa,KACnCY,EAASD,EAAM,IAAI;AAAA,EAE3B;AAEA,SAAAG,EAAU,MAAM;AACZ,UAAMC,IAAmB,CAACJ,MAAwBD,EAAeC,GAAOV,KAAoBe,CAAI;AAChG,kBAAO,iBAAiB,WAAWD,GAAkB,EAAK,GACnD,MAAM,OAAO,oBAAoB,WAAWA,GAAkB,EAAK;AAAA,EAC9E,GAAG,CAAA,CAAE,GAEE;AAAA,IACH,qBAAAb;AAAA,IACA,qBAAAG;AAAA,EAAA;AAER;"}
+{"version":3,"file":"usePostMessage.js","sources":["../../src/hooks/usePostMessage.ts"],"sourcesContent":["import { useEffect } from 'react';\nimport { isEmpty, noop } from 'es-toolkit/compat';\n\nexport type RemoteAction = {\n    /**\n     * The RemoteAction is inspired by a plain redux action where the type is the\n     * action identifier.\n     *\n     * @example\n     *\n     * ```json\n     * {\n     *      \"type\": \"EVENT_SET_VISIBLE_WIDGETS\",\n     *      \"payload\": [\"foo\", \"bar\"],\n     * }\n     * ```\n     */\n    type: string;\n\n    /**\n     * The action payload itself.\n     */\n    payload: any;\n};\n\n/**\n * A custom hook to ease the exchange of postMessage events between iframes and the parent window.\n *\n * @param messagePrefix a custom prefix to limit the event listener for these events\n * @param onReceiveMessage a callback function triggered when a message is received\n * @deprecated Please use the {@link import('./useIncomingPostMessages')#default useIncomingPostMessages} and/or\n * {@link import('./usePostMessageSender')#default usePostMessageSender} hooks instead.\n */\nconst usePostMessage = (messagePrefix: string, onReceiveMessage?: (eventData: any) => void) => {\n    const sendMessageToParent = (message: RemoteAction) => {\n        const referrer = document.referrer;\n        if (referrer) {\n            window.parent.postMessage(message, referrer);\n        }\n    };\n\n    const sendMessageToWidget = (message: RemoteAction, targetFrames: HTMLIFrameElement | HTMLIFrameElement[]) => {\n        if (!targetFrames || isEmpty(targetFrames)) {\n            return;\n        }\n\n        const frames = Array.isArray(targetFrames) ? [...targetFrames] : [targetFrames];\n\n        [...frames].forEach(target => {\n            const contentWindow = target.contentWindow;\n            if (contentWindow) {\n                contentWindow.postMessage(message, '*');\n            }\n        });\n    };\n\n    const receiveMessage = (event: MessageEvent, callback: (eventData: any) => void) => {\n        const actionType = event.data.type;\n        if (!actionType) {\n            return;\n        }\n\n        if (actionType.startsWith(messagePrefix)) {\n            callback(event.data);\n        }\n    };\n\n    useEffect(() => {\n        const listenerCallback = (event: MessageEvent) => receiveMessage(event, onReceiveMessage || noop);\n        window.addEventListener('message', listenerCallback, false);\n        return () => window.removeEventListener('message', listenerCallback, false);\n    }, []);\n\n    return {\n        sendMessageToParent,\n        sendMessageToWidget,\n    };\n};\n\nexport default usePostMessage;\n"],"names":["usePostMessage","messagePrefix","onReceiveMessage","sendMessageToParent","message","referrer","sendMessageToWidget","targetFrames","isEmpty","target","contentWindow","receiveMessage","event","callback","actionType","useEffect","listenerCallback","noop"],"mappings":";;AAiCA,MAAMA,IAAiB,CAACC,GAAuBC,MAAgD;AAC3F,QAAMC,IAAsB,CAACC,MAA0B;AACnD,UAAMC,IAAW,SAAS;AAC1B,IAAIA,KACA,OAAO,OAAO,YAAYD,GAASC,CAAQ;AAAA,EAEnD,GAEMC,IAAsB,CAACF,GAAuBG,MAA0D;AAC1G,QAAI,CAACA,KAAgBC,EAAQD,CAAY;AACrC;AAKJ,KAAC,GAFc,MAAM,QAAQA,CAAY,IAAI,CAAC,GAAGA,CAAY,IAAI,CAACA,CAAY,CAEpE,EAAE,QAAQ,CAAAE,MAAU;AAC1B,YAAMC,IAAgBD,EAAO;AAC7B,MAAIC,KACAA,EAAc,YAAYN,GAAS,GAAG;AAAA,IAE9C,CAAC;AAAA,EACL,GAEMO,IAAiB,CAACC,GAAqBC,MAAuC;AAChF,UAAMC,IAAaF,EAAM,KAAK;AAC9B,IAAKE,KAIDA,EAAW,WAAWb,CAAa,KACnCY,EAASD,EAAM,IAAI;AAAA,EAE3B;AAEA,SAAAG,EAAU,MAAM;AACZ,UAAMC,IAAmB,CAACJ,MAAwBD,EAAeC,GAAOV,KAAoBe,CAAI;AAChG,kBAAO,iBAAiB,WAAWD,GAAkB,EAAK,GACnD,MAAM,OAAO,oBAAoB,WAAWA,GAAkB,EAAK;AAAA,EAC9E,GAAG,CAAA,CAAE,GAEE;AAAA,IACH,qBAAAb;AAAA,IACA,qBAAAG;AAAA,EAAA;AAER;"}

package/hooks/useRioCookieConsent.d.ts

@@ -0,0 +1,49 @@
+export type RioCookieConsentStatus = 'missing' | 'invalid' | 'ux-cookies-accepted' | 'marketing-cookies-accepted' | 'custom';
+export type RioCookieConsentInfo = {
+    /**
+     * Name of the RIO consent cookie.
+     */
+    cookieName: 'cookie_settings';
+    /**
+     * Indicates whether the consent cookie exists.
+     */
+    isSet: boolean;
+    /**
+     * Raw cookie value as read from `document.cookie`.
+     */
+    rawValue?: string;
+    /**
+     * Parsed and normalized cookie switches when JSON parsing succeeds.
+     */
+    parsedValue?: Record<string, number>;
+    /**
+     * True when UX cookies are accepted (`switch-49 === 1`).
+     */
+    uxCookiesAccepted: boolean;
+    /**
+     * True when marketing cookies are accepted (`switch-2 === 1`).
+     */
+    marketingCookiesAccepted: boolean;
+    /**
+     * Computed consent status derived from parsed cookie values.
+     */
+    status: RioCookieConsentStatus;
+};
+export type UseRioCookieConsentResult = {
+    /**
+     * Reads and parses the RIO cookie consent settings.
+     */
+    getRioCookieConsentInfo: () => RioCookieConsentInfo;
+};
+/**
+ * Returns helpers for reading RIO's cookie consent state from `cookie_settings`.
+ *
+ * @returns {UseRioCookieConsentResult} Cookie consent helper functions.
+ *
+ * @example
+ * const { getRioCookieConsentInfo } = useRioCookieConsent();
+ * const consent = getRioCookieConsentInfo();
+ * const uxAccepted = consent.uxCookiesAccepted;
+ */
+declare const useRioCookieConsent: () => UseRioCookieConsentResult;
+export default useRioCookieConsent;

package/hooks/useRioCookieConsent.js

@@ -0,0 +1,44 @@
+import { useCallback as c } from "react";
+import n from "./useCookies.js";
+const a = (e) => {
+  if (!e)
+    return {
+      cookieName: "cookie_settings",
+      isSet: !1,
+      uxCookiesAccepted: !1,
+      marketingCookiesAccepted: !1,
+      status: "missing"
+    };
+  try {
+    const t = JSON.parse(e), s = t["switch-49"] === 1, o = t["switch-2"] === 1;
+    let i = "custom";
+    return s && !o ? i = "ux-cookies-accepted" : !s && o && (i = "marketing-cookies-accepted"), {
+      cookieName: "cookie_settings",
+      isSet: !0,
+      rawValue: e,
+      parsedValue: {
+        "switch-2": Number(t["switch-2"]),
+        "switch-49": Number(t["switch-49"])
+      },
+      uxCookiesAccepted: s,
+      marketingCookiesAccepted: o,
+      status: i
+    };
+  } catch {
+    return {
+      cookieName: "cookie_settings",
+      isSet: !0,
+      rawValue: e,
+      uxCookiesAccepted: !1,
+      marketingCookiesAccepted: !1,
+      status: "invalid"
+    };
+  }
+}, u = () => {
+  const { getCookie: e } = n();
+  return { getRioCookieConsentInfo: c(() => a(e("cookie_settings")), [e]) };
+};
+export {
+  u as default
+};
+//# sourceMappingURL=useRioCookieConsent.js.map

package/hooks/useRioCookieConsent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRioCookieConsent.js","sources":["../../src/hooks/useRioCookieConsent.ts"],"sourcesContent":["import { useCallback } from 'react';\n\nimport useCookies from './useCookies';\n\nexport type RioCookieConsentStatus =\n    | 'missing'\n    | 'invalid'\n    | 'ux-cookies-accepted'\n    | 'marketing-cookies-accepted'\n    | 'custom';\n\nexport type RioCookieConsentInfo = {\n    /**\n     * Name of the RIO consent cookie.\n     */\n    cookieName: 'cookie_settings';\n\n    /**\n     * Indicates whether the consent cookie exists.\n     */\n    isSet: boolean;\n\n    /**\n     * Raw cookie value as read from `document.cookie`.\n     */\n    rawValue?: string;\n\n    /**\n     * Parsed and normalized cookie switches when JSON parsing succeeds.\n     */\n    parsedValue?: Record<string, number>;\n\n    /**\n     * True when UX cookies are accepted (`switch-49 === 1`).\n     */\n    uxCookiesAccepted: boolean;\n\n    /**\n     * True when marketing cookies are accepted (`switch-2 === 1`).\n     */\n    marketingCookiesAccepted: boolean;\n\n    /**\n     * Computed consent status derived from parsed cookie values.\n     */\n    status: RioCookieConsentStatus;\n};\n\nexport type UseRioCookieConsentResult = {\n    /**\n     * Reads and parses the RIO cookie consent settings.\n     */\n    getRioCookieConsentInfo: () => RioCookieConsentInfo;\n};\n\nconst evaluateRioCookieSettings = (cookieValue?: string): RioCookieConsentInfo => {\n    if (!cookieValue) {\n        return {\n            cookieName: 'cookie_settings',\n            isSet: false,\n            uxCookiesAccepted: false,\n            marketingCookiesAccepted: false,\n            status: 'missing',\n        };\n    }\n\n    try {\n        const parsed = JSON.parse(cookieValue) as Record<string, unknown>;\n        const uxCookiesAccepted = parsed['switch-49'] === 1;\n        const marketingCookiesAccepted = parsed['switch-2'] === 1;\n\n        let status: RioCookieConsentStatus = 'custom';\n        if (uxCookiesAccepted && !marketingCookiesAccepted) {\n            status = 'ux-cookies-accepted';\n        } else if (!uxCookiesAccepted && marketingCookiesAccepted) {\n            status = 'marketing-cookies-accepted';\n        }\n\n        return {\n            cookieName: 'cookie_settings',\n            isSet: true,\n            rawValue: cookieValue,\n            parsedValue: {\n                'switch-2': Number(parsed['switch-2']),\n                'switch-49': Number(parsed['switch-49']),\n            },\n            uxCookiesAccepted,\n            marketingCookiesAccepted,\n            status,\n        };\n    } catch {\n        return {\n            cookieName: 'cookie_settings',\n            isSet: true,\n            rawValue: cookieValue,\n            uxCookiesAccepted: false,\n            marketingCookiesAccepted: false,\n            status: 'invalid',\n        };\n    }\n};\n\n/**\n * Returns helpers for reading RIO's cookie consent state from `cookie_settings`.\n *\n * @returns {UseRioCookieConsentResult} Cookie consent helper functions.\n *\n * @example\n * const { getRioCookieConsentInfo } = useRioCookieConsent();\n * const consent = getRioCookieConsentInfo();\n * const uxAccepted = consent.uxCookiesAccepted;\n */\nconst useRioCookieConsent = (): UseRioCookieConsentResult => {\n    const { getCookie } = useCookies();\n\n    const getRioCookieConsentInfo = useCallback(() => {\n        return evaluateRioCookieSettings(getCookie('cookie_settings'));\n    }, [getCookie]);\n\n    return { getRioCookieConsentInfo };\n};\n\nexport default useRioCookieConsent;\n"],"names":["evaluateRioCookieSettings","cookieValue","parsed","uxCookiesAccepted","marketingCookiesAccepted","status","useRioCookieConsent","getCookie","useCookies","useCallback"],"mappings":";;AAuDA,MAAMA,IAA4B,CAACC,MAA+C;AAC9E,MAAI,CAACA;AACD,WAAO;AAAA,MACH,YAAY;AAAA,MACZ,OAAO;AAAA,MACP,mBAAmB;AAAA,MACnB,0BAA0B;AAAA,MAC1B,QAAQ;AAAA,IAAA;AAIhB,MAAI;AACA,UAAMC,IAAS,KAAK,MAAMD,CAAW,GAC/BE,IAAoBD,EAAO,WAAW,MAAM,GAC5CE,IAA2BF,EAAO,UAAU,MAAM;AAExD,QAAIG,IAAiC;AACrC,WAAIF,KAAqB,CAACC,IACtBC,IAAS,wBACF,CAACF,KAAqBC,MAC7BC,IAAS,+BAGN;AAAA,MACH,YAAY;AAAA,MACZ,OAAO;AAAA,MACP,UAAUJ;AAAA,MACV,aAAa;AAAA,QACT,YAAY,OAAOC,EAAO,UAAU,CAAC;AAAA,QACrC,aAAa,OAAOA,EAAO,WAAW,CAAC;AAAA,MAAA;AAAA,MAE3C,mBAAAC;AAAA,MACA,0BAAAC;AAAA,MACA,QAAAC;AAAA,IAAA;AAAA,EAER,QAAQ;AACJ,WAAO;AAAA,MACH,YAAY;AAAA,MACZ,OAAO;AAAA,MACP,UAAUJ;AAAA,MACV,mBAAmB;AAAA,MACnB,0BAA0B;AAAA,MAC1B,QAAQ;AAAA,IAAA;AAAA,EAEhB;AACJ,GAYMK,IAAsB,MAAiC;AACzD,QAAM,EAAE,WAAAC,EAAA,IAAcC,EAAA;AAMtB,SAAO,EAAE,yBAJuBC,EAAY,MACjCT,EAA0BO,EAAU,iBAAiB,CAAC,GAC9D,CAACA,CAAS,CAAC,EAEL;AACb;"}

package/hooks/useSearch.d.ts

@@ -57,7 +57,7 @@ type UseSearchOptions<T> = {
  */
 declare const useSearch: <T extends object>(list: T[], options?: UseSearchOptions<T>) => {
     searchValue: string;
-    setSearchValue: import('react').Dispatch<import('react').SetStateAction<string>> | import('es-toolkit/function').DebouncedFunction<(q: string) => void>;
+    setSearchValue: (query: string) => void;
     filteredList: T[];
 };
 export default useSearch;

package/hooks/useSearch.js

@@ -1,31 +1,42 @@
-import { useState as d, useCallback as b, useMemo as m } from "react";
-import { debounce as S } from "es-toolkit/function";
-const g = (r, e) => e.split(".").reduce((t, u) => t ? t[u] : void 0, r), h = (r) => Object.keys(r).filter((e) => {
+import { useState as i, useMemo as b, useCallback as V, useEffect as h } from "react";
+import { debounce as v } from "es-toolkit/function";
+const y = (r, e) => e.split(".").reduce((t, s) => t ? t[s] : void 0, r), C = (r) => Object.keys(r).filter((e) => {
   const t = r[e];
   return typeof t == "string" || typeof t == "number";
-}), M = (r, e = {}) => {
-  const [t, u] = d(""), o = b(
-    e.debounceMs ? S((n) => u(n), e.debounceMs) : u,
-    [e.debounceMs]
-  ), f = m(() => {
+}), w = (r, e = {}) => {
+  const [t, s] = i(""), [l, a] = i(""), f = b(() => e.debounceMs ? v((c) => a(c), e.debounceMs) : null, [e.debounceMs]), m = V(
+    (u) => {
+      if (s(u), !f) {
+        a(u);
+        return;
+      }
+      f(u);
+    },
+    [f]
+  );
+  h(() => {
+    e.debounceMs || a(t);
+  }, [e.debounceMs, t]);
+  const S = b(() => {
+    const u = e.debounceMs ? l : t;
     if (!t)
       return r;
     if (r.length === 0)
       return [];
-    const n = e.caseSensitive ?? !1, a = n ? t : t.toLowerCase();
+    const c = e.caseSensitive ?? !1, d = c ? u : u.toLowerCase();
     if (e.customFilter)
-      return r.filter((c) => e.customFilter?.(c, t));
-    const l = e.fields ?? h(r[0]);
+      return r.filter((o) => e.customFilter?.(o, u));
+    const g = e.fields ?? C(r[0]);
     return r.filter(
-      (c) => l.some((i) => {
-        const s = g(c, i.toString());
-        return typeof s == "string" ? (n ? s : s.toLowerCase()).includes(a) : typeof s == "number" ? s.toString().includes(a) : !1;
+      (o) => g.some((M) => {
+        const n = y(o, M.toString());
+        return typeof n == "string" ? (c ? n : n.toLowerCase()).includes(d) : typeof n == "number" ? n.toString().includes(d) : !1;
       })
     );
-  }, [r, e, t]);
-  return { searchValue: t, setSearchValue: o, filteredList: f };
+  }, [l, r, e, t]);
+  return { searchValue: t, setSearchValue: m, filteredList: S };
 };
 export {
-  M as default
+  w as default
 };
 //# sourceMappingURL=useSearch.js.map

package/hooks/useSearch.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSearch.js","sources":["../../src/hooks/useSearch.ts"],"sourcesContent":["import { useMemo, useState, useCallback } from 'react';\nimport { debounce } from 'es-toolkit/function';\n\n/**\n * Options for configuring the `useSearch` hook.\n */\ntype UseSearchOptions<T> = {\n    /**\n     * List of object fields to search within. Dot notation (e.g. `'address.city'`) is supported for nested properties.\n     * If omitted, all top-level string and number fields will be used.\n     */\n    fields?: (keyof T | string)[]; // `string` to allow dot notation\n\n    /**\n     * Optional custom filtering function.\n     * If provided, this takes precedence over field-based filtering.\n     *\n     * @param item - The current item in the list.\n     * @param query - The current search query string.\n     * @returns `true` if the item should be included in the filtered list.\n     */\n    customFilter?: (item: T, query: string) => boolean;\n\n    /**\n     * Number of milliseconds to debounce the search input.\n     * If omitted, debounce is disabled.\n     */\n    debounceMs?: number;\n\n    /**\n     * Whether to perform a case-sensitive match.\n     * Default is `false` (case-insensitive).\n     *\n     * @default false\n     */\n    caseSensitive?: boolean;\n};\n\n/**\n * Gets the value of a nested field from an object using dot notation.\n *\n * @param obj - The object to traverse.\n * @param path - The dot-notated path string.\n * @returns The value at the specified path, or undefined.\n */\nconst getNestedValue = (obj: any, path: string): unknown =>\n    path.split('.').reduce((val, key) => (val ? val[key] : undefined), obj);\n\nconst inferSearchableFields = <T extends object>(item: T): string[] =>\n    Object.keys(item).filter(key => {\n        const value = (item as any)[key];\n        return typeof value === 'string' || typeof value === 'number';\n    });\n\n/**\n * A hook to filter a list of objects by a search value.\n * Supports field-based filtering, custom filtering logic, debounce, and case sensitivity.\n *\n * @template T - The type of items in the list (must be an object).\n *\n * @param list - The array of objects to search through.\n * @param options - Configuration options for the search behavior.\n * @param options.fields - Fields to search through. If omitted, all top-level string/number fields are used.\n * @param options.customFilter - Optional custom filter function overriding field-based filtering.\n * @param options.debounceMs - Debounce time in milliseconds.\n * @param options.caseSensitive - Whether the search should be case-sensitive.\n *\n * @returns An object containing:\n * - `searchValue`: The current search input string.\n * - `setSearchValue`: A setter function to update the search query.\n * - `filteredList`: The list of items matching the current search query.\n *\n * @example\n * ```ts\n * const { searchValue, setSearchValue, filteredList } = useSearch(users, {\n *   fields: ['name', 'email'],\n *   debounceMs: 300,\n * });\n * ```\n */\nconst useSearch = <T extends object>(list: T[], options: UseSearchOptions<T> = {}) => {\n    const [searchValue, _setSearchValue] = useState('');\n\n    // Debounced setter\n    const setSearchValue = useCallback(\n        options.debounceMs ? debounce((q: string) => _setSearchValue(q), options.debounceMs) : _setSearchValue,\n        [options.debounceMs]\n    );\n\n    const filteredList = useMemo(() => {\n        if (!searchValue) {\n            return list;\n        }\n        if (list.length === 0) {\n            return [];\n        }\n\n        const isCaseSensitive = options.caseSensitive ?? false;\n        const query = isCaseSensitive ? searchValue : searchValue.toLowerCase();\n\n        // Custom filter takes precedence\n        if (options.customFilter) {\n            return list.filter(item => options.customFilter?.(item, searchValue));\n        }\n\n        const fields = options.fields ?? inferSearchableFields(list[0]);\n\n        return list.filter(item =>\n            fields.some(field => {\n                const value = getNestedValue(item, field.toString());\n\n                if (typeof value === 'string') {\n                    const target = isCaseSensitive ? value : value.toLowerCase();\n                    return target.includes(query);\n                }\n\n                if (typeof value === 'number') {\n                    return value.toString().includes(query);\n                }\n\n                return false;\n            })\n        );\n    }, [list, options, searchValue]);\n\n    return { searchValue, setSearchValue, filteredList };\n};\n\nexport default useSearch;\n"],"names":["getNestedValue","obj","path","val","key","inferSearchableFields","item","value","useSearch","list","options","searchValue","_setSearchValue","useState","setSearchValue","useCallback","debounce","q","filteredList","useMemo","isCaseSensitive","query","fields","field"],"mappings":";;AA6CA,MAAMA,IAAiB,CAACC,GAAUC,MAC9BA,EAAK,MAAM,GAAG,EAAE,OAAO,CAACC,GAAKC,MAASD,IAAMA,EAAIC,CAAG,IAAI,QAAYH,CAAG,GAEpEI,IAAwB,CAAmBC,MAC7C,OAAO,KAAKA,CAAI,EAAE,OAAO,CAAAF,MAAO;AAC5B,QAAMG,IAASD,EAAaF,CAAG;AAC/B,SAAO,OAAOG,KAAU,YAAY,OAAOA,KAAU;AACzD,CAAC,GA4BCC,IAAY,CAAmBC,GAAWC,IAA+B,OAAO;AAClF,QAAM,CAACC,GAAaC,CAAe,IAAIC,EAAS,EAAE,GAG5CC,IAAiBC;AAAA,IACnBL,EAAQ,aAAaM,EAAS,CAACC,MAAcL,EAAgBK,CAAC,GAAGP,EAAQ,UAAU,IAAIE;AAAA,IACvF,CAACF,EAAQ,UAAU;AAAA,EAAA,GAGjBQ,IAAeC,EAAQ,MAAM;AAC/B,QAAI,CAACR;AACD,aAAOF;AAEX,QAAIA,EAAK,WAAW;AAChB,aAAO,CAAA;AAGX,UAAMW,IAAkBV,EAAQ,iBAAiB,IAC3CW,IAAQD,IAAkBT,IAAcA,EAAY,YAAA;AAG1D,QAAID,EAAQ;AACR,aAAOD,EAAK,OAAO,CAAAH,MAAQI,EAAQ,eAAeJ,GAAMK,CAAW,CAAC;AAGxE,UAAMW,IAASZ,EAAQ,UAAUL,EAAsBI,EAAK,CAAC,CAAC;AAE9D,WAAOA,EAAK;AAAA,MAAO,CAAAH,MACfgB,EAAO,KAAK,CAAAC,MAAS;AACjB,cAAMhB,IAAQP,EAAeM,GAAMiB,EAAM,UAAU;AAEnD,eAAI,OAAOhB,KAAU,YACFa,IAAkBb,IAAQA,EAAM,YAAA,GACjC,SAASc,CAAK,IAG5B,OAAOd,KAAU,WACVA,EAAM,WAAW,SAASc,CAAK,IAGnC;AAAA,MACX,CAAC;AAAA,IAAA;AAAA,EAET,GAAG,CAACZ,GAAMC,GAASC,CAAW,CAAC;AAE/B,SAAO,EAAE,aAAAA,GAAa,gBAAAG,GAAgB,cAAAI,EAAA;AAC1C;"}
+{"version":3,"file":"useSearch.js","sources":["../../src/hooks/useSearch.ts"],"sourcesContent":["import { useMemo, useState, useCallback, useEffect } from 'react';\nimport { debounce } from 'es-toolkit/function';\n\n/**\n * Options for configuring the `useSearch` hook.\n */\ntype UseSearchOptions<T> = {\n    /**\n     * List of object fields to search within. Dot notation (e.g. `'address.city'`) is supported for nested properties.\n     * If omitted, all top-level string and number fields will be used.\n     */\n    fields?: (keyof T | string)[]; // `string` to allow dot notation\n\n    /**\n     * Optional custom filtering function.\n     * If provided, this takes precedence over field-based filtering.\n     *\n     * @param item - The current item in the list.\n     * @param query - The current search query string.\n     * @returns `true` if the item should be included in the filtered list.\n     */\n    customFilter?: (item: T, query: string) => boolean;\n\n    /**\n     * Number of milliseconds to debounce the search input.\n     * If omitted, debounce is disabled.\n     */\n    debounceMs?: number;\n\n    /**\n     * Whether to perform a case-sensitive match.\n     * Default is `false` (case-insensitive).\n     *\n     * @default false\n     */\n    caseSensitive?: boolean;\n};\n\n/**\n * Gets the value of a nested field from an object using dot notation.\n *\n * @param obj - The object to traverse.\n * @param path - The dot-notated path string.\n * @returns The value at the specified path, or undefined.\n */\nconst getNestedValue = (obj: any, path: string): unknown =>\n    path.split('.').reduce((val, key) => (val ? val[key] : undefined), obj);\n\nconst inferSearchableFields = <T extends object>(item: T): string[] =>\n    Object.keys(item).filter(key => {\n        const value = (item as any)[key];\n        return typeof value === 'string' || typeof value === 'number';\n    });\n\n/**\n * A hook to filter a list of objects by a search value.\n * Supports field-based filtering, custom filtering logic, debounce, and case sensitivity.\n *\n * @template T - The type of items in the list (must be an object).\n *\n * @param list - The array of objects to search through.\n * @param options - Configuration options for the search behavior.\n * @param options.fields - Fields to search through. If omitted, all top-level string/number fields are used.\n * @param options.customFilter - Optional custom filter function overriding field-based filtering.\n * @param options.debounceMs - Debounce time in milliseconds.\n * @param options.caseSensitive - Whether the search should be case-sensitive.\n *\n * @returns An object containing:\n * - `searchValue`: The current search input string.\n * - `setSearchValue`: A setter function to update the search query.\n * - `filteredList`: The list of items matching the current search query.\n *\n * @example\n * ```ts\n * const { searchValue, setSearchValue, filteredList } = useSearch(users, {\n *   fields: ['name', 'email'],\n *   debounceMs: 300,\n * });\n * ```\n */\nconst useSearch = <T extends object>(list: T[], options: UseSearchOptions<T> = {}) => {\n    // what the input renders (must update immediately)\n    const [searchValue, _setSearchValue] = useState('');\n\n    // what filtering uses (debounced if configured)\n    const [debouncedValue, setDebouncedValue] = useState('');\n\n    // stable debounced updater\n    const debouncedUpdate = useMemo(() => {\n        if (!options.debounceMs) {\n            return null;\n        }\n\n        const fn = debounce((query: string) => setDebouncedValue(query), options.debounceMs);\n        return fn;\n    }, [options.debounceMs]);\n\n    // setter exposed to consumers\n    const setSearchValue = useCallback(\n        (query: string) => {\n            _setSearchValue(query);\n\n            if (!debouncedUpdate) {\n                setDebouncedValue(query);\n                return;\n            }\n\n            debouncedUpdate(query);\n        },\n        [debouncedUpdate]\n    );\n\n    // keep debouncedValue in sync for the \"no debounce\" case and initial render\n    useEffect(() => {\n        if (!options.debounceMs) {\n            setDebouncedValue(searchValue);\n        }\n    }, [options.debounceMs, searchValue]);\n\n    const filteredList = useMemo(() => {\n        const activeQueryValue = options.debounceMs ? debouncedValue : searchValue;\n\n        if (!searchValue) {\n            return list;\n        }\n        if (list.length === 0) {\n            return [];\n        }\n\n        const isCaseSensitive = options.caseSensitive ?? false;\n        const query = isCaseSensitive ? activeQueryValue : activeQueryValue.toLowerCase();\n\n        // Custom filter takes precedence\n        if (options.customFilter) {\n            return list.filter(item => options.customFilter?.(item, activeQueryValue));\n        }\n\n        const fields = options.fields ?? inferSearchableFields(list[0]);\n\n        return list.filter(item =>\n            fields.some(field => {\n                const value = getNestedValue(item, field.toString());\n\n                if (typeof value === 'string') {\n                    const target = isCaseSensitive ? value : value.toLowerCase();\n                    return target.includes(query);\n                }\n\n                if (typeof value === 'number') {\n                    return value.toString().includes(query);\n                }\n\n                return false;\n            })\n        );\n    }, [debouncedValue, list, options, searchValue]);\n\n    return { searchValue, setSearchValue, filteredList };\n};\n\nexport default useSearch;\n"],"names":["getNestedValue","obj","path","val","key","inferSearchableFields","item","value","useSearch","list","options","searchValue","_setSearchValue","useState","debouncedValue","setDebouncedValue","debouncedUpdate","useMemo","debounce","query","setSearchValue","useCallback","useEffect","filteredList","activeQueryValue","isCaseSensitive","fields","field"],"mappings":";;AA6CA,MAAMA,IAAiB,CAACC,GAAUC,MAC9BA,EAAK,MAAM,GAAG,EAAE,OAAO,CAACC,GAAKC,MAASD,IAAMA,EAAIC,CAAG,IAAI,QAAYH,CAAG,GAEpEI,IAAwB,CAAmBC,MAC7C,OAAO,KAAKA,CAAI,EAAE,OAAO,CAAAF,MAAO;AAC5B,QAAMG,IAASD,EAAaF,CAAG;AAC/B,SAAO,OAAOG,KAAU,YAAY,OAAOA,KAAU;AACzD,CAAC,GA4BCC,IAAY,CAAmBC,GAAWC,IAA+B,OAAO;AAElF,QAAM,CAACC,GAAaC,CAAe,IAAIC,EAAS,EAAE,GAG5C,CAACC,GAAgBC,CAAiB,IAAIF,EAAS,EAAE,GAGjDG,IAAkBC,EAAQ,MACvBP,EAAQ,aAIFQ,EAAS,CAACC,MAAkBJ,EAAkBI,CAAK,GAAGT,EAAQ,UAAU,IAHxE,MAKZ,CAACA,EAAQ,UAAU,CAAC,GAGjBU,IAAiBC;AAAA,IACnB,CAACF,MAAkB;AAGf,UAFAP,EAAgBO,CAAK,GAEjB,CAACH,GAAiB;AAClB,QAAAD,EAAkBI,CAAK;AACvB;AAAA,MACJ;AAEA,MAAAH,EAAgBG,CAAK;AAAA,IACzB;AAAA,IACA,CAACH,CAAe;AAAA,EAAA;AAIpB,EAAAM,EAAU,MAAM;AACZ,IAAKZ,EAAQ,cACTK,EAAkBJ,CAAW;AAAA,EAErC,GAAG,CAACD,EAAQ,YAAYC,CAAW,CAAC;AAEpC,QAAMY,IAAeN,EAAQ,MAAM;AAC/B,UAAMO,IAAmBd,EAAQ,aAAaI,IAAiBH;AAE/D,QAAI,CAACA;AACD,aAAOF;AAEX,QAAIA,EAAK,WAAW;AAChB,aAAO,CAAA;AAGX,UAAMgB,IAAkBf,EAAQ,iBAAiB,IAC3CS,IAAQM,IAAkBD,IAAmBA,EAAiB,YAAA;AAGpE,QAAId,EAAQ;AACR,aAAOD,EAAK,OAAO,CAAAH,MAAQI,EAAQ,eAAeJ,GAAMkB,CAAgB,CAAC;AAG7E,UAAME,IAAShB,EAAQ,UAAUL,EAAsBI,EAAK,CAAC,CAAC;AAE9D,WAAOA,EAAK;AAAA,MAAO,CAAAH,MACfoB,EAAO,KAAK,CAAAC,MAAS;AACjB,cAAMpB,IAAQP,EAAeM,GAAMqB,EAAM,UAAU;AAEnD,eAAI,OAAOpB,KAAU,YACFkB,IAAkBlB,IAAQA,EAAM,YAAA,GACjC,SAASY,CAAK,IAG5B,OAAOZ,KAAU,WACVA,EAAM,WAAW,SAASY,CAAK,IAGnC;AAAA,MACX,CAAC;AAAA,IAAA;AAAA,EAET,GAAG,CAACL,GAAgBL,GAAMC,GAASC,CAAW,CAAC;AAE/C,SAAO,EAAE,aAAAA,GAAa,gBAAAS,GAAgB,cAAAG,EAAA;AAC1C;"}

package/hooks/useSearchHighlight.d.ts

@@ -0,0 +1,60 @@
+export declare const SEARCH_HIGHLIGHT_CLASS = "search-result-highlight";
+export type UseSearchHighlightParams = {
+    /**
+     * Ref to the element whose text content should be searched.
+     */
+    ref: React.RefObject<HTMLElement>;
+    /**
+     * Search query used for highlighting.
+     */
+    query: string;
+    /**
+     * Name of the CSS highlight.
+     *
+     * @default 'search-result-highlight'
+     */
+    highlightClassName?: string;
+    /**
+     * Optional selector to limit the search scope
+     * (e.g. '.ListMenuGroup' or '.OptionLabel').
+     */
+    scopeSelector?: string;
+    /**
+     * Whether to perform a case-sensitive match.
+     *
+     * @default false
+     */
+    caseSensitive?: boolean;
+    /**
+     * Optional dependencies that should trigger re-collecting and applying ranges.
+     * Useful when the DOM changes after the query changes (e.g. debounced filtering).
+     */
+    deps?: unknown[];
+};
+/**
+ * React hook for visually highlighting search query matches
+ * using the native CSS Highlight API.
+ *
+ * The hook scans the text content of the referenced element
+ * and applies a named CSS highlight to all matching substrings.
+ *
+ * Key characteristics:
+ * - Progressive enhancement: safely no-ops in unsupported browsers
+ * - Does not modify or re-render DOM markup
+ * - Designed for search UIs (Autocomplete, ListMenu, Dropdown, etc.)
+ *
+ * Usage notes:
+ * - The hook must always be called unconditionally
+ * - Use `useSearchHighlight.supported()` only for render-time
+ *   fallback decisions (e.g. `<mark>` rendering)
+ *
+ * @param ref           Ref to the element whose text should be searched
+ * @param query         Search query to highlight
+ * @param highlightName Optional CSS highlight name
+ * @param scopeSelector Optional selector to limit the search scope
+ */
+declare const useSearchHighlight: {
+    (params: UseSearchHighlightParams): void;
+    supported(): boolean;
+};
+export default useSearchHighlight;

package/hooks/useSearchHighlight.js

@@ -0,0 +1,54 @@
+import { useMemo as d, useEffect as x } from "react";
+const m = "search-result-highlight", u = () => typeof window < "u" && "CSS" in window && "highlights" in CSS && typeof Highlight < "u", w = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), H = (s, c, h) => {
+  const t = [];
+  if (!c)
+    return t;
+  const n = new RegExp(w(c), h ? "g" : "gi"), a = document.createTreeWalker(s, NodeFilter.SHOW_TEXT);
+  let e = a.nextNode();
+  for (; e; ) {
+    const o = e.textContent ?? "";
+    n.lastIndex = 0;
+    let r = n.exec(o);
+    for (; r; ) {
+      const i = document.createRange();
+      i.setStart(e, r.index), i.setEnd(e, r.index + r[0].length), t.push(i), r = n.exec(o);
+    }
+    e = a.nextNode();
+  }
+  return t;
+}, C = (s) => {
+  const {
+    ref: c,
+    query: h,
+    highlightClassName: t = m,
+    scopeSelector: n,
+    caseSensitive: a = !1,
+    deps: e
+  } = s, o = d(() => h.trim(), [h]), r = d(() => e ?? [], [e]);
+  x(() => {
+    if (!u())
+      return;
+    const i = c.current;
+    if (!i)
+      return;
+    const g = CSS.highlights.get(t) ?? new Highlight();
+    CSS.highlights.set(t, g);
+    const p = () => {
+      if (g.clear(), !o)
+        return;
+      const l = n ? i.querySelector(n) : i;
+      if (l)
+        for (const f of H(l, o, a))
+          g.add(f);
+    }, S = window.requestAnimationFrame(p);
+    return () => {
+      window.cancelAnimationFrame(S), g.clear();
+    };
+  }, [a, t, o, c, n, r]);
+};
+C.supported = () => u();
+export {
+  m as SEARCH_HIGHLIGHT_CLASS,
+  C as default
+};
+//# sourceMappingURL=useSearchHighlight.js.map

package/hooks/useSearchHighlight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSearchHighlight.js","sources":["../../src/hooks/useSearchHighlight.ts"],"sourcesContent":["import { useEffect, useMemo } from 'react';\n\nexport const SEARCH_HIGHLIGHT_CLASS = 'search-result-highlight';\n\nexport type UseSearchHighlightParams = {\n    /**\n     * Ref to the element whose text content should be searched.\n     */\n    ref: React.RefObject<HTMLElement>;\n\n    /**\n     * Search query used for highlighting.\n     */\n    query: string;\n\n    /**\n     * Name of the CSS highlight.\n     *\n     * @default 'search-result-highlight'\n     */\n    highlightClassName?: string;\n\n    /**\n     * Optional selector to limit the search scope\n     * (e.g. '.ListMenuGroup' or '.OptionLabel').\n     */\n    scopeSelector?: string;\n\n    /**\n     * Whether to perform a case-sensitive match.\n     *\n     * @default false\n     */\n    caseSensitive?: boolean;\n\n    /**\n     * Optional dependencies that should trigger re-collecting and applying ranges.\n     * Useful when the DOM changes after the query changes (e.g. debounced filtering).\n     */\n    deps?: unknown[];\n};\n\n// Guard for browser support of the CSS Highlight API.\nconst isSearchHighlightSupported = () =>\n    typeof window !== 'undefined' && 'CSS' in window && 'highlights' in CSS && typeof Highlight !== 'undefined';\n\nconst escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n\n/**\n * Collects DOM Ranges for all matches of a search query\n * within the text content of a given root element.\n *\n * Purpose:\n * This utility is used by `useSearchHighlight` to translate a plain-text\n * search query into DOM `Range` objects that can be consumed by the\n * native CSS Highlight API (`Highlight` / `CSS.highlights`).\n *\n * Why this exists:\n * - The Highlight API does not accept strings or selectors, only `Range`s.\n * - React nodes may contain arbitrary nested markup; injecting `<mark>`\n *   elements would break component structure and semantics.\n * - Walking the DOM text nodes allows highlighting without mutating\n *   the rendered output.\n *\n * What it does:\n * - Traverses all text nodes inside `root` using a `TreeWalker`\n * - Finds all matches of `query`\n * - Creates a `Range` for each match, precisely spanning the matched text\n * - Returns all collected ranges in document order\n *\n * What it does NOT do:\n * - It does not modify the DOM\n * - It does not register or apply highlights\n * - It does not perform filtering or visibility logic\n *\n * Performance notes:\n * - Intended for reasonably sized, already-filtered DOM trees\n *   (e.g. visible menu items, dropdown options)\n * - Consumers should avoid running this on large, unbounded documents\n *\n * @param root           The root element whose text content should be searched\n * @param query          The normalized (trimmed) search query\n * @param caseSensitive  Whether matches should be case-sensitive\n * @returns     An array of DOM Ranges matching the query\n */\nconst collectRanges = (root: HTMLElement, query: string, caseSensitive: boolean): Range[] => {\n    const ranges: Range[] = [];\n\n    if (!query) {\n        return ranges;\n    }\n\n    const regex = new RegExp(escapeRegExp(query), caseSensitive ? 'g' : 'gi');\n\n    // Walk text nodes only to avoid splitting markup.\n    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);\n\n    let node: Node | null = walker.nextNode();\n\n    while (node) {\n        const text = node.textContent ?? '';\n        regex.lastIndex = 0;\n\n        let match: RegExpExecArray | null = regex.exec(text);\n\n        while (match) {\n            const range = document.createRange();\n            range.setStart(node, match.index);\n            range.setEnd(node, match.index + match[0].length);\n            ranges.push(range);\n\n            match = regex.exec(text);\n        }\n\n        node = walker.nextNode();\n    }\n\n    return ranges;\n};\n\n/**\n * React hook for visually highlighting search query matches\n * using the native CSS Highlight API.\n *\n * The hook scans the text content of the referenced element\n * and applies a named CSS highlight to all matching substrings.\n *\n * Key characteristics:\n * - Progressive enhancement: safely no-ops in unsupported browsers\n * - Does not modify or re-render DOM markup\n * - Designed for search UIs (Autocomplete, ListMenu, Dropdown, etc.)\n *\n * Usage notes:\n * - The hook must always be called unconditionally\n * - Use `useSearchHighlight.supported()` only for render-time\n *   fallback decisions (e.g. `<mark>` rendering)\n *\n * @param ref           Ref to the element whose text should be searched\n * @param query         Search query to highlight\n * @param highlightName Optional CSS highlight name\n * @param scopeSelector Optional selector to limit the search scope\n */\nconst useSearchHighlight = (params: UseSearchHighlightParams) => {\n    const {\n        ref,\n        query,\n        highlightClassName = SEARCH_HIGHLIGHT_CLASS,\n        scopeSelector,\n        caseSensitive = false,\n        deps,\n    } = params;\n\n    const normalizedQuery = useMemo(() => query.trim(), [query]);\n\n    const extraDeps = useMemo(() => deps ?? [], [deps]);\n\n    useEffect(() => {\n        if (!isSearchHighlightSupported()) {\n            return;\n        }\n\n        const container = ref.current;\n        if (!container) {\n            return;\n        }\n\n        // Reuse the named highlight so multiple renders update the same layer.\n        const highlight = CSS.highlights.get(highlightClassName) ?? new Highlight();\n        CSS.highlights.set(highlightClassName, highlight);\n\n        const applyHighlight = () => {\n            // Always clear before re-adding to avoid stale ranges.\n            highlight.clear();\n\n            if (!normalizedQuery) {\n                return;\n            }\n\n            const scopeRoot = scopeSelector\n                ? (container.querySelector(scopeSelector) as HTMLElement | null)\n                : container;\n\n            if (!scopeRoot) {\n                return;\n            }\n\n            for (const range of collectRanges(scopeRoot, normalizedQuery, caseSensitive)) {\n                highlight.add(range);\n            }\n        };\n\n        // Defer until after layout so text nodes are in place.\n        const raf = window.requestAnimationFrame(applyHighlight);\n\n        return () => {\n            window.cancelAnimationFrame(raf);\n            // Ensure highlights are removed when query or component unmounts.\n            highlight.clear();\n        };\n    }, [caseSensitive, highlightClassName, normalizedQuery, ref, scopeSelector, extraDeps]);\n};\n\n/**\n * Indicates whether the current environment supports\n * the native CSS Highlight API.\n *\n * Can be used to decide whether to render a `<mark>` fallback.\n */\nuseSearchHighlight.supported = () => isSearchHighlightSupported();\n\nexport default useSearchHighlight;\n"],"names":["SEARCH_HIGHLIGHT_CLASS","isSearchHighlightSupported","escapeRegExp","value","collectRanges","root","query","caseSensitive","ranges","regex","walker","node","text","match","range","useSearchHighlight","params","ref","highlightClassName","scopeSelector","deps","normalizedQuery","useMemo","extraDeps","useEffect","container","highlight","applyHighlight","scopeRoot","raf"],"mappings":";AAEO,MAAMA,IAAyB,2BAyChCC,IAA6B,MAC/B,OAAO,SAAW,OAAe,SAAS,UAAU,gBAAgB,OAAO,OAAO,YAAc,KAE9FC,IAAe,CAACC,MAAkBA,EAAM,QAAQ,uBAAuB,MAAM,GAuC7EC,IAAgB,CAACC,GAAmBC,GAAeC,MAAoC;AACzF,QAAMC,IAAkB,CAAA;AAExB,MAAI,CAACF;AACD,WAAOE;AAGX,QAAMC,IAAQ,IAAI,OAAOP,EAAaI,CAAK,GAAGC,IAAgB,MAAM,IAAI,GAGlEG,IAAS,SAAS,iBAAiBL,GAAM,WAAW,SAAS;AAEnE,MAAIM,IAAoBD,EAAO,SAAA;AAE/B,SAAOC,KAAM;AACT,UAAMC,IAAOD,EAAK,eAAe;AACjC,IAAAF,EAAM,YAAY;AAElB,QAAII,IAAgCJ,EAAM,KAAKG,CAAI;AAEnD,WAAOC,KAAO;AACV,YAAMC,IAAQ,SAAS,YAAA;AACvB,MAAAA,EAAM,SAASH,GAAME,EAAM,KAAK,GAChCC,EAAM,OAAOH,GAAME,EAAM,QAAQA,EAAM,CAAC,EAAE,MAAM,GAChDL,EAAO,KAAKM,CAAK,GAEjBD,IAAQJ,EAAM,KAAKG,CAAI;AAAA,IAC3B;AAEA,IAAAD,IAAOD,EAAO,SAAA;AAAA,EAClB;AAEA,SAAOF;AACX,GAwBMO,IAAqB,CAACC,MAAqC;AAC7D,QAAM;AAAA,IACF,KAAAC;AAAA,IACA,OAAAX;AAAA,IACA,oBAAAY,IAAqBlB;AAAA,IACrB,eAAAmB;AAAA,IACA,eAAAZ,IAAgB;AAAA,IAChB,MAAAa;AAAA,EAAA,IACAJ,GAEEK,IAAkBC,EAAQ,MAAMhB,EAAM,QAAQ,CAACA,CAAK,CAAC,GAErDiB,IAAYD,EAAQ,MAAMF,KAAQ,CAAA,GAAI,CAACA,CAAI,CAAC;AAElD,EAAAI,EAAU,MAAM;AACZ,QAAI,CAACvB;AACD;AAGJ,UAAMwB,IAAYR,EAAI;AACtB,QAAI,CAACQ;AACD;AAIJ,UAAMC,IAAY,IAAI,WAAW,IAAIR,CAAkB,KAAK,IAAI,UAAA;AAChE,QAAI,WAAW,IAAIA,GAAoBQ,CAAS;AAEhD,UAAMC,IAAiB,MAAM;AAIzB,UAFAD,EAAU,MAAA,GAEN,CAACL;AACD;AAGJ,YAAMO,IAAYT,IACXM,EAAU,cAAcN,CAAa,IACtCM;AAEN,UAAKG;AAIL,mBAAWd,KAASV,EAAcwB,GAAWP,GAAiBd,CAAa;AACvE,UAAAmB,EAAU,IAAIZ,CAAK;AAAA,IAE3B,GAGMe,IAAM,OAAO,sBAAsBF,CAAc;AAEvD,WAAO,MAAM;AACT,aAAO,qBAAqBE,CAAG,GAE/BH,EAAU,MAAA;AAAA,IACd;AAAA,EACJ,GAAG,CAACnB,GAAeW,GAAoBG,GAAiBJ,GAAKE,GAAeI,CAAS,CAAC;AAC1F;AAQAR,EAAmB,YAAY,MAAMd,EAAA;"}

package/hooks/useTimeout.js

@@ -4,30 +4,30 @@ const f = (s, t) => {
   return l(() => {
     c.current = s;
   }, [s]), l(() => {
-    const r = () => c.current();
+    const n = () => c.current();
     if (typeof t == "number")
-      return e.current = window.setTimeout(r, t), () => {
-        e.current !== null && window.clearTimeout(e.current);
+      return e.current = setTimeout(n, t), () => {
+        e.current !== null && clearTimeout(e.current);
       };
   }, [t]), e;
 }, _ = () => {
   const t = (u, i, o) => {
-    const n = o - Date.now();
-    u.current = n <= 2147483647 ? setTimeout(i, n) : setTimeout(() => t(u, i, o), 2147483647);
-  }, e = m(null), { set: c, clear: r } = T(() => {
+    const r = o - Date.now();
+    u.current = r <= 2147483647 ? setTimeout(i, r) : setTimeout(() => t(u, i, o), 2147483647);
+  }, e = m(null), { set: c, clear: n } = T(() => {
     const u = () => clearTimeout(e.current);
     return {
-      set: (o, n = 0) => {
-        u(), n <= 2147483647 ? e.current = setTimeout(o, n) : t(e, o, Date.now() + n);
+      set: (o, r = 0) => {
+        u(), r <= 2147483647 ? e.current = setTimeout(o, r) : t(e, o, Date.now() + r);
       },
       clear: u
     };
   }, []);
   return l(() => () => {
-    r();
-  }, [r]), {
+    n();
+  }, [n]), {
     set: c,
-    clear: r,
+    clear: n,
     handleRef: e
   };
 };

package/hooks/useTimeout.js.map

@@ -1 +1 @@
-{"version":3,"file":"useTimeout.js","sources":["../../src/hooks/useTimeout.ts"],"sourcesContent":["import type React from 'react';\nimport { useEffect, useMemo, useRef } from 'react';\n\n// See www.joshwcomeau.com/snippets/react-hooks/use-timeout/\n\n/**\n * A custom hook for handling timeout events.\n *\n * @param callback The callback function to execute after the timeout.\n * @param delay The duration of the timeout in milliseconds. Pass `null` to cancel the timeout.\n *\n * @returns A mutable ref object to manage the timeout ID.\n */\nconst useTimeout = (callback: () => void, delay: number | null): React.MutableRefObject<number | null> => {\n    const timeoutRef = useRef<number | null>(null);\n    const savedCallback = useRef<() => void>(callback);\n\n    // Update the saved callback when the callback prop changes\n    useEffect(() => {\n        savedCallback.current = callback;\n    }, [callback]);\n\n    // Set up the timeout when the delay changes\n    useEffect(() => {\n        const tick = () => savedCallback.current();\n\n        // If delay is a number, set up the timeout\n        if (typeof delay === 'number') {\n            timeoutRef.current = window.setTimeout(tick, delay);\n\n            // Cleanup function to clear the timeout when delay changes or component unmounts\n            return () => {\n                if (timeoutRef.current !== null) {\n                    window.clearTimeout(timeoutRef.current);\n                }\n            };\n        }\n    }, [delay]);\n\n    return timeoutRef;\n};\n\nexport const useChainedTimeout = () => {\n    const MAX_DELAY_MS = 2 ** 31 - 1;\n\n    const setChainedTimeout = (ref: React.MutableRefObject<any>, fn: () => void, timeoutAtMs: number) => {\n        const delayMs = timeoutAtMs - Date.now();\n\n        ref.current =\n            delayMs <= MAX_DELAY_MS\n                ? setTimeout(fn, delayMs)\n                : setTimeout(() => setChainedTimeout(ref, fn, timeoutAtMs), MAX_DELAY_MS);\n    };\n\n    const handleRef = useRef<any>(null);\n\n    const { set, clear } = useMemo(() => {\n        const clear = () => clearTimeout(handleRef.current);\n\n        const set = (fn: () => void, delayMs = 0): void => {\n            clear();\n\n            if (delayMs <= MAX_DELAY_MS) {\n                // For simplicity, if the timeout is short, just set a normal timeout.\n                handleRef.current = setTimeout(fn, delayMs);\n            } else {\n                setChainedTimeout(handleRef, fn, Date.now() + delayMs);\n            }\n        };\n\n        return {\n            set,\n            clear,\n        };\n    }, []);\n\n    useEffect(() => {\n        return () => {\n            clear();\n        };\n    }, [clear]);\n\n    return {\n        set,\n        clear,\n        handleRef,\n    };\n};\n\nexport default useTimeout;\n"],"names":["useTimeout","callback","delay","timeoutRef","useRef","savedCallback","useEffect","tick","useChainedTimeout","setChainedTimeout","ref","fn","timeoutAtMs","delayMs","handleRef","set","clear","useMemo"],"mappings":";AAaA,MAAMA,IAAa,CAACC,GAAsBC,MAAgE;AACtG,QAAMC,IAAaC,EAAsB,IAAI,GACvCC,IAAgBD,EAAmBH,CAAQ;AAGjD,SAAAK,EAAU,MAAM;AACZ,IAAAD,EAAc,UAAUJ;AAAA,EAC5B,GAAG,CAACA,CAAQ,CAAC,GAGbK,EAAU,MAAM;AACZ,UAAMC,IAAO,MAAMF,EAAc,QAAA;AAGjC,QAAI,OAAOH,KAAU;AACjB,aAAAC,EAAW,UAAU,OAAO,WAAWI,GAAML,CAAK,GAG3C,MAAM;AACT,QAAIC,EAAW,YAAY,QACvB,OAAO,aAAaA,EAAW,OAAO;AAAA,MAE9C;AAAA,EAER,GAAG,CAACD,CAAK,CAAC,GAEHC;AACX,GAEaK,IAAoB,MAAM;AAGnC,QAAMC,IAAoB,CAACC,GAAkCC,GAAgBC,MAAwB;AACjG,UAAMC,IAAUD,IAAc,KAAK,IAAA;AAEnC,IAAAF,EAAI,UACAG,KAAW,aACL,WAAWF,GAAIE,CAAO,IACtB,WAAW,MAAMJ,EAAkBC,GAAKC,GAAIC,CAAW,GAAG,UAAY;AAAA,EACpF,GAEME,IAAYV,EAAY,IAAI,GAE5B,EAAE,KAAAW,GAAK,OAAAC,EAAA,IAAUC,EAAQ,MAAM;AACjC,UAAMD,IAAQ,MAAM,aAAaF,EAAU,OAAO;AAalD,WAAO;AAAA,MACH,KAZQ,CAACH,GAAgBE,IAAU,MAAY;AAC/CG,QAAAA,EAAAA,GAEIH,KAAW,aAEXC,EAAU,UAAU,WAAWH,GAAIE,CAAO,IAE1CJ,EAAkBK,GAAWH,GAAI,KAAK,IAAA,IAAQE,CAAO;AAAA,MAE7D;AAAA,MAII,OAAAG;AAAAA,IAAA;AAAA,EAER,GAAG,CAAA,CAAE;AAEL,SAAAV,EAAU,MACC,MAAM;AACT,IAAAU,EAAA;AAAA,EACJ,GACD,CAACA,CAAK,CAAC,GAEH;AAAA,IACH,KAAAD;AAAA,IACA,OAAAC;AAAA,IACA,WAAAF;AAAA,EAAA;AAER;"}
+{"version":3,"file":"useTimeout.js","sources":["../../src/hooks/useTimeout.ts"],"sourcesContent":["import type React from 'react';\nimport { useEffect, useMemo, useRef } from 'react';\n\n// See www.joshwcomeau.com/snippets/react-hooks/use-timeout/\n\n/**\n * A custom hook for handling timeout events.\n *\n * @param callback The callback function to execute after the timeout.\n * @param delay The duration of the timeout in milliseconds. Pass `null` to cancel the timeout.\n *\n * @returns A mutable ref object to manage the timeout ID.\n */\nconst useTimeout = (callback: () => void, delay: number | null): React.MutableRefObject<number | null> => {\n    const timeoutRef = useRef<number | null>(null);\n    const savedCallback = useRef<() => void>(callback);\n\n    // Update the saved callback when the callback prop changes\n    useEffect(() => {\n        savedCallback.current = callback;\n    }, [callback]);\n\n    // Set up the timeout when the delay changes\n    useEffect(() => {\n        const tick = () => savedCallback.current();\n\n        // If delay is a number, set up the timeout\n        if (typeof delay === 'number') {\n            timeoutRef.current = setTimeout(tick, delay) as unknown as number;\n\n            // Cleanup function to clear the timeout when delay changes or component unmounts\n            return () => {\n                if (timeoutRef.current !== null) {\n                    clearTimeout(timeoutRef.current);\n                }\n            };\n        }\n    }, [delay]);\n\n    return timeoutRef;\n};\n\nexport const useChainedTimeout = () => {\n    const MAX_DELAY_MS = 2 ** 31 - 1;\n\n    const setChainedTimeout = (ref: React.MutableRefObject<any>, fn: () => void, timeoutAtMs: number) => {\n        const delayMs = timeoutAtMs - Date.now();\n\n        ref.current =\n            delayMs <= MAX_DELAY_MS\n                ? setTimeout(fn, delayMs)\n                : setTimeout(() => setChainedTimeout(ref, fn, timeoutAtMs), MAX_DELAY_MS);\n    };\n\n    const handleRef = useRef<any>(null);\n\n    const { set, clear } = useMemo(() => {\n        const clear = () => clearTimeout(handleRef.current);\n\n        const set = (fn: () => void, delayMs = 0): void => {\n            clear();\n\n            if (delayMs <= MAX_DELAY_MS) {\n                // For simplicity, if the timeout is short, just set a normal timeout.\n                handleRef.current = setTimeout(fn, delayMs);\n            } else {\n                setChainedTimeout(handleRef, fn, Date.now() + delayMs);\n            }\n        };\n\n        return {\n            set,\n            clear,\n        };\n    }, []);\n\n    useEffect(() => {\n        return () => {\n            clear();\n        };\n    }, [clear]);\n\n    return {\n        set,\n        clear,\n        handleRef,\n    };\n};\n\nexport default useTimeout;\n"],"names":["useTimeout","callback","delay","timeoutRef","useRef","savedCallback","useEffect","tick","useChainedTimeout","setChainedTimeout","ref","fn","timeoutAtMs","delayMs","handleRef","set","clear","useMemo"],"mappings":";AAaA,MAAMA,IAAa,CAACC,GAAsBC,MAAgE;AACtG,QAAMC,IAAaC,EAAsB,IAAI,GACvCC,IAAgBD,EAAmBH,CAAQ;AAGjD,SAAAK,EAAU,MAAM;AACZ,IAAAD,EAAc,UAAUJ;AAAA,EAC5B,GAAG,CAACA,CAAQ,CAAC,GAGbK,EAAU,MAAM;AACZ,UAAMC,IAAO,MAAMF,EAAc,QAAA;AAGjC,QAAI,OAAOH,KAAU;AACjB,aAAAC,EAAW,UAAU,WAAWI,GAAML,CAAK,GAGpC,MAAM;AACT,QAAIC,EAAW,YAAY,QACvB,aAAaA,EAAW,OAAO;AAAA,MAEvC;AAAA,EAER,GAAG,CAACD,CAAK,CAAC,GAEHC;AACX,GAEaK,IAAoB,MAAM;AAGnC,QAAMC,IAAoB,CAACC,GAAkCC,GAAgBC,MAAwB;AACjG,UAAMC,IAAUD,IAAc,KAAK,IAAA;AAEnC,IAAAF,EAAI,UACAG,KAAW,aACL,WAAWF,GAAIE,CAAO,IACtB,WAAW,MAAMJ,EAAkBC,GAAKC,GAAIC,CAAW,GAAG,UAAY;AAAA,EACpF,GAEME,IAAYV,EAAY,IAAI,GAE5B,EAAE,KAAAW,GAAK,OAAAC,EAAA,IAAUC,EAAQ,MAAM;AACjC,UAAMD,IAAQ,MAAM,aAAaF,EAAU,OAAO;AAalD,WAAO;AAAA,MACH,KAZQ,CAACH,GAAgBE,IAAU,MAAY;AAC/CG,QAAAA,EAAAA,GAEIH,KAAW,aAEXC,EAAU,UAAU,WAAWH,GAAIE,CAAO,IAE1CJ,EAAkBK,GAAWH,GAAI,KAAK,IAAA,IAAQE,CAAO;AAAA,MAE7D;AAAA,MAII,OAAAG;AAAAA,IAAA;AAAA,EAER,GAAG,CAAA,CAAE;AAEL,SAAAV,EAAU,MACC,MAAM;AACT,IAAAU,EAAA;AAAA,EACJ,GACD,CAACA,CAAK,CAAC,GAEH;AAAA,IACH,KAAAD;AAAA,IACA,OAAAC;AAAA,IACA,WAAAF;AAAA,EAAA;AAER;"}

package/hooks/useUrlState.d.ts

@@ -0,0 +1,62 @@
+import { UrlConfigItem } from '../utils/routeUtils';
+type QueryString = string;
+/**
+ * Configuration contract for `useUrlState`.
+ *
+ * Use this hook when your application uses **store/redux as source of truth**
+ * and you want a centralized URL synchronizer:
+ * - URL -> store: parse incoming search params and dispatch updates
+ * - store -> URL: serialize current store values and navigate with push/replace
+ *
+ * Recommended setup:
+ * - Mount one top-level synchronizer component near the router
+ * - Pass only URL-managed store values via `storeValues`
+ * - Keep URL writing centralized through this hook
+ *
+ * Not intended for "URL-only state" screens where you directly read/write
+ * params via router APIs (for example `useSearchParams`) without store sync.
+ */
+type UseUrlStateProps<TState> = {
+    /**
+     * URL sync configuration.
+     * Each entry maps one query param key to a store selector and update action.
+     */
+    config: readonly UrlConfigItem<TState, any>[];
+    /**
+     * Current URL search string (for example `location.search`).
+     * Expected shape: `'?q=test&sort=-name'` or `''`.
+     */
+    searchString: QueryString;
+    /**
+     * Current store values used by the configured selectors. This could be values from a redux store.
+     * Keys should match the `config` keys, values are compared against URL/defaults.
+     */
+    storeValues: Record<string, unknown>;
+    /**
+     * Optional localStorage key for sticky URL state restore on initial load
+     * when managed URL params are missing.
+     */
+    localStorageKey?: string;
+    /**
+     * Router navigation type (typically from React Router `useNavigationType`).
+     * `POP` indicates browser back/forward navigation.
+     */
+    navigationType?: 'POP' | 'PUSH' | 'REPLACE' | string;
+    /**
+     * Store update callback invoked when URL -> store sync detects a change.
+     * Usually wraps `dispatch(...)`.
+     */
+    onUpdateStore: (action: any) => void;
+    /**
+     * Navigation callback used for store -> URL sync writes.
+     * `historyMode` controls whether to `push` or `replace` the history entry.
+     */
+    onNavigate: (search: string, historyMode: 'push' | 'replace') => void;
+};
+/**
+ * ----------------------------------------------------------------------------
+ * MAIN EXPORT
+ * ----------------------------------------------------------------------------
+ */
+declare const useUrlState: <TState>(props: UseUrlStateProps<TState>) => void;
+export default useUrlState;

package/hooks/useUrlState.js

@@ -0,0 +1,137 @@
+import { useRef as R, useEffect as D } from "react";
+import { isNil as z, isEqual as v } from "es-toolkit";
+import { deserializeValue as T, toQueryString as M, serializeValue as A } from "../utils/routeUtils.js";
+import E from "./useAfterMount.js";
+import U from "./useLatest.js";
+const C = (r) => {
+  const e = r.replace(/^\?/, "");
+  return new URLSearchParams(e).toString();
+}, L = (r, e) => r.customDeserialize ? r.customDeserialize(e) : T(e, r.type ?? "string"), N = (r, e) => r ?? e, I = (r) => {
+  const { valueToApply: e, currentStoreValue: t, urlRawValue: a, defaultValue: d } = r;
+  if (typeof e > "u" || v(e, t))
+    return !1;
+  const l = z(a), n = v(t, d);
+  return !(l && n);
+}, O = (r, e, t) => t ? null : r.customSerialize ? r.customSerialize(e) : A(e, r.type ?? "string"), x = (r) => {
+  const { nextParams: e, key: t, serializedValue: a } = r;
+  return z(a) ? e.has(t) ? (e.delete(t), !0) : !1 : (e.set(t, a), !0);
+}, K = (r, e) => {
+  if (z(e))
+    return !0;
+  const t = L(r, e), a = N(t, r.defaultValue);
+  return v(a, r.defaultValue);
+}, F = ({
+  config: r,
+  searchString: e,
+  storeValues: t,
+  navigationType: a,
+  onUpdateStore: d,
+  lastWrittenNormalizedSearchRef: l,
+  isRestoringRef: n,
+  hasCheckedStorageRef: g
+}) => {
+  const h = U(r), p = U(t), y = U(d);
+  D(() => {
+    if (!g.current)
+      return;
+    const s = C(e);
+    if (l.current === s && (l.current = null), n.current)
+      return;
+    const P = new URLSearchParams(e);
+    h.current.forEach((c) => {
+      const u = P.get(c.key), i = L(c, u), f = N(i, c.defaultValue), S = p.current[c.key];
+      if (I({
+        valueToApply: f,
+        currentStoreValue: S,
+        urlRawValue: u,
+        defaultValue: c.defaultValue
+      })) {
+        if (z(u) && a !== "POP")
+          return;
+        y.current(c.action(f));
+      }
+    });
+  }, [e, l, n, g]);
+}, q = (r) => {
+  const {
+    config: e,
+    searchString: t,
+    storeValues: a,
+    onNavigate: d,
+    lastWrittenNormalizedSearchRef: l,
+    localStorageKey: n,
+    navigationType: g
+  } = r, h = U(d), p = R(C(t));
+  E(() => {
+    const y = C(t), s = p.current !== y;
+    if (p.current = y, g === "POP" && s)
+      return;
+    const c = new URLSearchParams(t), u = new URLSearchParams(t);
+    let i = !1, f = !1, S = !0;
+    if (e.forEach((o) => {
+      const V = a[o.key], m = c.get(o.key), k = v(V, o.defaultValue);
+      k || (S = !1);
+      const w = O(o, V, k);
+      w !== m && (i = x({ nextParams: u, key: o.key, serializedValue: w }) || i, ((o.history ?? "push") === "push" || !k && K(o, m)) && (f = !0));
+    }), i) {
+      const o = M(u, e), V = u.toString();
+      l.current = V, n && (S && o === "" ? localStorage.removeItem(n) : localStorage.setItem(n, o));
+      const m = f ? "push" : "replace";
+      h.current(o, m);
+    }
+  }, [a, t, e, n, g]);
+}, Q = (r) => {
+  const {
+    config: e,
+    searchString: t,
+    localStorageKey: a,
+    onUpdateStore: d,
+    onNavigate: l,
+    isRestoringRef: n,
+    lastWrittenNormalizedSearchRef: g,
+    hasCheckedStorageRef: h
+  } = r;
+  D(() => {
+    if (!a) {
+      h.current = !0;
+      return;
+    }
+    const p = new URLSearchParams(t);
+    if (!e.some((s) => p.has(s.key))) {
+      const s = localStorage.getItem(a);
+      if (s) {
+        n.current = !0;
+        const P = new URLSearchParams(s);
+        e.forEach((i) => {
+          const f = P.get(i.key), S = L(i, f);
+          S !== null && typeof S < "u" && d(i.action(S));
+        });
+        const c = s.replace(/^\?/, ""), u = t.replace(/^\?/, "");
+        c !== u && (g.current = new URLSearchParams(s).toString(), l(s, "replace")), setTimeout(() => {
+          n.current = !1;
+        }, 0);
+      }
+    }
+    h.current = !0;
+  }, [a]);
+}, J = (r) => {
+  const e = R(null), t = R(!1), a = R(!r.localStorageKey);
+  Q({
+    ...r,
+    lastWrittenNormalizedSearchRef: e,
+    isRestoringRef: t,
+    hasCheckedStorageRef: a
+  }), F({
+    ...r,
+    lastWrittenNormalizedSearchRef: e,
+    isRestoringRef: t,
+    hasCheckedStorageRef: a
+  }), q({
+    ...r,
+    lastWrittenNormalizedSearchRef: e
+  });
+};
+export {
+  J as default
+};
+//# sourceMappingURL=useUrlState.js.map