@rio-cloud/rio-uikit 2.1.0 → 2.2.0

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

package/hooks/useUrlState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUrlState.js","sources":["../../src/hooks/useUrlState.ts"],"sourcesContent":["import { useEffect, useRef } from 'react';\nimport { isEqual, isNil } from 'es-toolkit';\n\nimport { deserializeValue, serializeValue, toQueryString, type UrlConfigItem } from '../utils/routeUtils';\nimport useAfterMount from './useAfterMount';\nimport useLatest from './useLatest';\n\ntype QueryString = string;\n\n/**\n * Configuration contract for `useUrlState`.\n *\n * Use this hook when your application uses **store/redux as source of truth**\n * and you want a centralized URL synchronizer:\n * - URL -> store: parse incoming search params and dispatch updates\n * - store -> URL: serialize current store values and navigate with push/replace\n *\n * Recommended setup:\n * - Mount one top-level synchronizer component near the router\n * - Pass only URL-managed store values via `storeValues`\n * - Keep URL writing centralized through this hook\n *\n * Not intended for \"URL-only state\" screens where you directly read/write\n * params via router APIs (for example `useSearchParams`) without store sync.\n */\ntype UseUrlStateProps<TState> = {\n    /**\n     * URL sync configuration.\n     * Each entry maps one query param key to a store selector and update action.\n     */\n    config: readonly UrlConfigItem<TState, any>[];\n\n    /**\n     * Current URL search string (for example `location.search`).\n     * Expected shape: `'?q=test&sort=-name'` or `''`.\n     */\n    searchString: QueryString;\n\n    /**\n     * Current store values used by the configured selectors. This could be values from a redux store.\n     * Keys should match the `config` keys, values are compared against URL/defaults.\n     */\n    storeValues: Record<string, unknown>;\n\n    /**\n     * Optional localStorage key for sticky URL state restore on initial load\n     * when managed URL params are missing.\n     */\n    localStorageKey?: string;\n\n    /**\n     * Router navigation type (typically from React Router `useNavigationType`).\n     * `POP` indicates browser back/forward navigation.\n     */\n    navigationType?: 'POP' | 'PUSH' | 'REPLACE' | string;\n\n    /**\n     * Store update callback invoked when URL -> store sync detects a change.\n     * Usually wraps `dispatch(...)`.\n     */\n    onUpdateStore: (action: any) => void;\n\n    /**\n     * Navigation callback used for store -> URL sync writes.\n     * `historyMode` controls whether to `push` or `replace` the history entry.\n     */\n    onNavigate: (search: string, historyMode: 'push' | 'replace') => void;\n};\n\n// Helper for URL for Comparison:\n// Browsers/Routers might decode parts of the string automatically.\n// We force everything to a standard encoded format for reliable diffing.\nconst normalizeSearch = (search: string) => {\n    const clean = search.replace(/^\\?/, '');\n    return new URLSearchParams(clean).toString();\n};\n\nconst parseConfigValue = (item: UrlConfigItem<any, any>, urlRawValue: string | null) =>\n    item.customDeserialize ? item.customDeserialize(urlRawValue) : deserializeValue(urlRawValue, item.type ?? 'string');\n\nconst getValueToApply = (parsedValue: unknown, defaultValue: unknown) => parsedValue ?? defaultValue;\n\nconst shouldDispatchParsedValue = (params: {\n    valueToApply: unknown;\n    currentStoreValue: unknown;\n    urlRawValue: string | null;\n    defaultValue: unknown;\n}) => {\n    const { valueToApply, currentStoreValue, urlRawValue, defaultValue } = params;\n\n    if (typeof valueToApply === 'undefined' || isEqual(valueToApply, currentStoreValue)) {\n        return false;\n    }\n\n    const isUrlMissing = isNil(urlRawValue);\n    const isStoreDefault = isEqual(currentStoreValue, defaultValue);\n    return !(isUrlMissing && isStoreDefault);\n};\n\nconst serializeConfigValue = (\n    item: UrlConfigItem<any, any>,\n    storeValue: unknown,\n    isDefault: boolean\n): string | null => {\n    if (isDefault) {\n        return null;\n    }\n    if (item.customSerialize) {\n        return item.customSerialize(storeValue as never);\n    }\n    return serializeValue(storeValue as never, item.type ?? 'string');\n};\n\nconst applySearchParamUpdate = (params: {\n    nextParams: URLSearchParams;\n    key: string;\n    serializedValue: string | null;\n}) => {\n    const { nextParams, key, serializedValue } = params;\n\n    if (isNil(serializedValue)) {\n        if (!nextParams.has(key)) {\n            return false;\n        }\n        nextParams.delete(key);\n        return true;\n    }\n\n    nextParams.set(key, serializedValue);\n    return true;\n};\n\nconst isUrlValueDefault = (item: UrlConfigItem<any, any>, urlRawValue: string | null) => {\n    if (isNil(urlRawValue)) {\n        return true;\n    }\n    const parsedValue = parseConfigValue(item, urlRawValue);\n    const valueFromUrl = getValueToApply(parsedValue, item.defaultValue);\n    return isEqual(valueFromUrl, item.defaultValue);\n};\n\n/**\n * ----------------------------------------------------------------------------\n * 1. URL -> Redux\n * ----------------------------------------------------------------------------\n * Responsibilities:\n * - Listen to searchString changes.\n * - Check against the \"Loop Lock\" (ignore if we just wrote this URL).\n * - Parse and Dispatch actions.\n */\ntype UseSyncUrlToStoreProps = {\n    config: readonly UrlConfigItem<any, any>[];\n    searchString: string;\n    storeValues: Record<string, unknown>;\n    navigationType?: string;\n    onUpdateStore: (a: any) => void;\n    lastWrittenNormalizedSearchRef: React.MutableRefObject<string | null>;\n    isRestoringRef: React.MutableRefObject<boolean>;\n    hasCheckedStorageRef: React.MutableRefObject<boolean>;\n};\n\nconst useSyncUrlToStore = ({\n    config,\n    searchString,\n    storeValues,\n    navigationType,\n    onUpdateStore,\n    lastWrittenNormalizedSearchRef,\n    isRestoringRef,\n    hasCheckedStorageRef,\n}: UseSyncUrlToStoreProps) => {\n    // Keep latest values stable for URL-driven effect without adding them to deps.\n    const latestConfigRef = useLatest(config);\n    const latestStoreValuesRef = useLatest(storeValues);\n    const latestOnUpdateStoreRef = useLatest(onUpdateStore);\n\n    useEffect(() => {\n        // SAFETY: Wait for Storage Check (Sticky State)\n        if (!hasCheckedStorageRef.current) {\n            return;\n        }\n\n        // 1. Check Loop Lock (Did we just write this URL?)\n        const currentStandard = normalizeSearch(searchString);\n        if (lastWrittenNormalizedSearchRef.current === currentStandard) {\n            // Match found. Release marker and continue parsing.\n            // This avoids skipping browser POP navigation when search equals\n            // a previously written URL.\n            lastWrittenNormalizedSearchRef.current = null;\n        }\n\n        // 2. Check Restoration Block\n        if (isRestoringRef.current) {\n            return;\n        }\n\n        // 3. Parse & Diff\n        const currentParams = new URLSearchParams(searchString);\n\n        latestConfigRef.current.forEach(item => {\n            const urlRawValue = currentParams.get(item.key);\n            const parsedValue = parseConfigValue(item, urlRawValue);\n            const valueToApply = getValueToApply(parsedValue, item.defaultValue);\n            const currentStoreValue = latestStoreValuesRef.current[item.key];\n\n            if (\n                shouldDispatchParsedValue({\n                    valueToApply,\n                    currentStoreValue,\n                    urlRawValue,\n                    defaultValue: item.defaultValue,\n                })\n            ) {\n                // Missing URL params should not reset store on regular in-app navigations.\n                // We only apply \"missing => default\" during POP (back/forward) transitions.\n                if (isNil(urlRawValue) && navigationType !== 'POP') {\n                    return;\n                }\n                latestOnUpdateStoreRef.current(item.action(valueToApply));\n            }\n        });\n\n        // CRITICAL: This dependency array MUST NOT include 'onUpdateStore' or 'storeValues'.\n        // It should ONLY run when the URL string physically changes.\n    }, [searchString, lastWrittenNormalizedSearchRef, isRestoringRef, hasCheckedStorageRef]);\n};\n\n/**\n * ----------------------------------------------------------------------------\n * 2. Redux -> URL\n * ----------------------------------------------------------------------------\n * Responsibilities:\n * - Listen to Redux changes.\n * - Calculate Ideal URL.\n * - Diff against Current URL.\n * - Handle Navigation Type ('POP' prevention).\n * - Set \"Loop Lock\" and Navigate.\n */\ntype UseSyncStoreToUrlProps = {\n    config: readonly UrlConfigItem<any, any>[];\n    searchString: string;\n    storeValues: Record<string, unknown>;\n    onNavigate: (s: string, m: 'push' | 'replace') => void;\n    lastWrittenNormalizedSearchRef: React.MutableRefObject<string | null>;\n    localStorageKey?: string;\n    navigationType?: string;\n};\n\nconst useSyncStoreToUrl = (props: UseSyncStoreToUrlProps) => {\n    const {\n        config,\n        searchString,\n        storeValues,\n        onNavigate,\n        lastWrittenNormalizedSearchRef,\n        localStorageKey,\n        navigationType,\n    } = props;\n\n    // Keep navigate callback stable inside effect.\n    const latestOnNavigateRef = useLatest(onNavigate);\n    const previousSearchRef = useRef<string | null>(normalizeSearch(searchString));\n\n    // Skip initial render (Reader handles hydration)\n    useAfterMount(() => {\n        const currentStandardSearch = normalizeSearch(searchString);\n        const hasSearchChanged = previousSearchRef.current !== currentStandardSearch;\n        previousSearchRef.current = currentStandardSearch;\n\n        // POP navigation should be URL -> store only for the transition step.\n        // If we write here, we can overwrite the forward stack.\n        // This prevents the writer from immediately rewriting URL during back/forward\n        // transitions (which can overwrite forward history).\n        const isPopNavigationSync = navigationType === 'POP' && hasSearchChanged;\n        if (isPopNavigationSync) {\n            return;\n        }\n\n        const currentParams = new URLSearchParams(searchString);\n        const nextParams = new URLSearchParams(searchString);\n\n        let hasChanges = false;\n        let hasPushChange = false;\n        let isAllDefaults = true;\n\n        config.forEach(item => {\n            const storeVal = storeValues[item.key];\n            const currentUrlVal = currentParams.get(item.key);\n            const isDefault = isEqual(storeVal, item.defaultValue);\n\n            if (!isDefault) isAllDefaults = false;\n\n            const serializedVal = serializeConfigValue(item, storeVal, isDefault);\n\n            if (serializedVal !== currentUrlVal) {\n                hasChanges =\n                    applySearchParamUpdate({ nextParams, key: item.key, serializedValue: serializedVal }) || hasChanges;\n\n                // Determine history mode preference for changed fields.\n                // Global rule:\n                // - 'push' items always push when changed.\n                // - 'replace' items push once on default -> non-default, then replace thereafter.\n                const historyMode = item.history ?? 'push';\n                if (historyMode === 'push') {\n                    hasPushChange = true;\n                } else if (!isDefault && isUrlValueDefault(item, currentUrlVal)) {\n                    hasPushChange = true;\n                }\n            }\n        });\n\n        if (hasChanges) {\n            // 1. Generate URLs\n            const prettyString = toQueryString(nextParams, config);\n            const strictString = nextParams.toString();\n\n            // 2. Set loop lock (Crucial: Use strict string for comparison)\n            lastWrittenNormalizedSearchRef.current = strictString;\n\n            // 3. Persist to Storage (if key provided)\n            if (localStorageKey) {\n                if (isAllDefaults && prettyString === '') {\n                    localStorage.removeItem(localStorageKey);\n                } else {\n                    localStorage.setItem(localStorageKey, prettyString);\n                }\n            }\n\n            // 4. Calculate Mode\n            const mode = hasPushChange ? 'push' : 'replace';\n\n            latestOnNavigateRef.current(prettyString, mode);\n        }\n    }, [storeValues, searchString, config, localStorageKey, navigationType]);\n    // ^ onNavigate excluded from deps (used via ref) to be safe,\n    // though storeValues changing is the main trigger.\n};\n\n/**\n * ----------------------------------------------------------------------------\n * 3. RESTORER HOOK (LocalStorage -> Redux)\n * ----------------------------------------------------------------------------\n * Responsibilities:\n * - Run once on mount.\n * - If URL is empty & Storage exists -> Force Redux update & URL Replace.\n */\n\ntype UseInitialRestoreFromStorageProps = {\n    config: readonly UrlConfigItem<any, any>[];\n    searchString: string;\n    localStorageKey?: string;\n    onUpdateStore: (a: any) => void;\n    onNavigate: (s: string, m: 'push' | 'replace') => void;\n    isRestoringRef: React.MutableRefObject<boolean>;\n    lastWrittenNormalizedSearchRef: React.MutableRefObject<string | null>;\n    hasCheckedStorageRef: React.MutableRefObject<boolean>;\n};\n\nconst useInitialRestoreFromStorage = (props: UseInitialRestoreFromStorageProps) => {\n    const {\n        config,\n        searchString,\n        localStorageKey,\n        onUpdateStore,\n        onNavigate,\n        isRestoringRef,\n        lastWrittenNormalizedSearchRef,\n        hasCheckedStorageRef,\n    } = props;\n\n    useEffect(() => {\n        if (!localStorageKey) {\n            hasCheckedStorageRef.current = true;\n            return;\n        }\n\n        const currentParams = new URLSearchParams(searchString);\n        const hasManagedParams = config.some(item => currentParams.has(item.key));\n\n        // Only restore if URL is \"empty\" regarding our config\n        if (!hasManagedParams) {\n            const savedString = localStorage.getItem(localStorageKey);\n\n            if (savedString) {\n                // Block the Reader from interfering\n                isRestoringRef.current = true;\n\n                // 1. Hydrate Redux (conceptually similar to Reader logic but forced)\n                const savedParams = new URLSearchParams(savedString);\n                config.forEach(item => {\n                    const val = savedParams.get(item.key);\n                    const deserialized = parseConfigValue(item, val);\n\n                    if (deserialized !== null && typeof deserialized !== 'undefined') {\n                        onUpdateStore(item.action(deserialized));\n                    }\n                });\n\n                // 2. Hydrate URL (Visual)\n                const cleanSaved = savedString.replace(/^\\?/, '');\n                const cleanCurrent = searchString.replace(/^\\?/, '');\n\n                if (cleanSaved !== cleanCurrent) {\n                    // Set Lock so Reader doesn't freak out\n                    lastWrittenNormalizedSearchRef.current = new URLSearchParams(savedString).toString();\n                    onNavigate(savedString, 'replace');\n                }\n\n                // Unlock after tick\n                setTimeout(() => {\n                    isRestoringRef.current = false;\n                }, 0);\n            }\n        }\n\n        hasCheckedStorageRef.current = true;\n    }, [localStorageKey]); // Run once\n};\n\n/**\n * ----------------------------------------------------------------------------\n * MAIN EXPORT\n * ----------------------------------------------------------------------------\n */\nconst useUrlState = <TState>(props: UseUrlStateProps<TState>) => {\n    // Shared communication channel between hooks\n\n    // Stores the last URL search string written by this hook (normalized encoding).\n    const lastWrittenNormalizedSearchRef = useRef<string | null>(null);\n\n    // Shared flag for Restoration phase\n    const isRestoringRef = useRef(false);\n    const hasCheckedStorageRef = useRef(!props.localStorageKey);\n\n    // 1. Sticky State (Restorer)\n    useInitialRestoreFromStorage({\n        ...props,\n        lastWrittenNormalizedSearchRef,\n        isRestoringRef,\n        hasCheckedStorageRef,\n    });\n\n    // 2. Read from URL (URL -> Redux)\n    useSyncUrlToStore({\n        ...props,\n        lastWrittenNormalizedSearchRef,\n        isRestoringRef,\n        hasCheckedStorageRef,\n    });\n\n    // 3. Write to URL (Redux -> URL)\n    useSyncStoreToUrl({\n        ...props,\n        lastWrittenNormalizedSearchRef,\n    });\n};\n\nexport default useUrlState;\n"],"names":["normalizeSearch","search","clean","parseConfigValue","item","urlRawValue","deserializeValue","getValueToApply","parsedValue","defaultValue","shouldDispatchParsedValue","params","valueToApply","currentStoreValue","isEqual","isUrlMissing","isNil","isStoreDefault","serializeConfigValue","storeValue","isDefault","serializeValue","applySearchParamUpdate","nextParams","key","serializedValue","isUrlValueDefault","valueFromUrl","useSyncUrlToStore","config","searchString","storeValues","navigationType","onUpdateStore","lastWrittenNormalizedSearchRef","isRestoringRef","hasCheckedStorageRef","latestConfigRef","useLatest","latestStoreValuesRef","latestOnUpdateStoreRef","useEffect","currentStandard","currentParams","useSyncStoreToUrl","props","onNavigate","localStorageKey","latestOnNavigateRef","previousSearchRef","useRef","useAfterMount","currentStandardSearch","hasSearchChanged","hasChanges","hasPushChange","isAllDefaults","storeVal","currentUrlVal","serializedVal","prettyString","toQueryString","strictString","mode","useInitialRestoreFromStorage","savedString","savedParams","val","deserialized","cleanSaved","cleanCurrent","useUrlState"],"mappings":"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"}

package/mergeClassNameOverrides.d.ts

@@ -0,0 +1 @@
+export * from './utils/mergeClassNameOverrides';

package/mergeClassNameOverrides.js

@@ -0,0 +1,5 @@
+import { mergeClassNameOverrides as m } from "./utils/mergeClassNameOverrides.js";
+export {
+  m as mergeClassNameOverrides
+};
+//# sourceMappingURL=mergeClassNameOverrides.js.map

package/mergeClassNameOverrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mergeClassNameOverrides.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}