@provex/components 1.2.3

package/dist/useUrlState.d.cts

@@ -0,0 +1,237 @@
+import { Hex } from 'viem';
+import { ChainId } from '@provex/utils/chain';
+
+/**
+ * @fileoverview URL state management hook for React Router.
+ *
+ * Provides a type-safe way to manage URL query parameters as application state.
+ * The URL is the single source of truth - no useState needed.
+ *
+ * @remarks
+ * **Key Design Principles:**
+ * - URL is the source of truth (no bi-directional sync)
+ * - Type-safe parsing and serialization
+ * - Built-in parsers for common types (bigint, hex, chainId, boolean)
+ * - Preserves other URL params when updating
+ *
+ * **When to Use:**
+ * - Filter state that should persist in URL (currencies, payment methods)
+ * - Page state that should be shareable (deposit ID, chain)
+ * - Replacing useState + useEffect URL sync anti-patterns
+ *
+ * @see MultiSelectFilter for a component that uses this hook pattern
+ */
+
+/**
+ * Configuration for a single URL parameter managed by useUrlState.
+ *
+ * @template T - The TypeScript type of the parsed value
+ *
+ * @example
+ * ```ts
+ * // Simple string param
+ * const providerConfig: UrlParamConfig<string> = {
+ *   key: 'provider',
+ *   defaultValue: 'venmo',
+ * }
+ *
+ * // Param with custom parse/serialize
+ * const pageConfig: UrlParamConfig<number> = {
+ *   key: 'page',
+ *   defaultValue: 1,
+ *   parse: (raw) => parseInt(raw, 10),
+ *   serialize: (val) => String(val),
+ * }
+ * ```
+ */
+interface UrlParamConfig<T> {
+    /** The URL query parameter key (e.g., "provider", "currency", "page") */
+    key: string;
+    /** Default value when the URL param is missing or invalid */
+    defaultValue: T;
+    /**
+     * Custom parser to transform URL string to typed value.
+     * If not provided, the raw string is returned (for string types).
+     * Return undefined to fall back to defaultValue.
+     */
+    parse?: (raw: string) => T | undefined;
+    /**
+     * Custom serializer to transform typed value to URL string.
+     * If not provided, String(value) is used.
+     */
+    serialize?: (value: T) => string;
+}
+/**
+ * Type helper to extract the value type from a UrlParamConfig.
+ */
+type ConfigValue<C> = C extends UrlParamConfig<infer T> ? T : never;
+/**
+ * Type helper to create the state object type from a config record.
+ * Maps each config key to its parsed value type.
+ */
+type UrlStateValues<C extends Record<string, UrlParamConfig<unknown>>> = {
+    [K in keyof C]: ConfigValue<C[K]>;
+};
+/**
+ * Return type of useUrlState hook.
+ * Includes all state values plus a setParam function for updates.
+ */
+interface UseUrlStateResult<C extends Record<string, UrlParamConfig<unknown>>> {
+    /** Current state values derived from URL params */
+    state: UrlStateValues<C>;
+    /**
+     * Update a single URL parameter.
+     * This updates the URL which triggers a re-render with new state.
+     *
+     * @param key - The config key (not the URL param key)
+     * @param value - The new value to set
+     *
+     * @example
+     * ```ts
+     * const { state, setParam } = useUrlState(config)
+     * setParam('provider', 'revolut')  // Updates ?provider=revolut
+     * ```
+     */
+    setParam: <K extends keyof C>(key: K, value: ConfigValue<C[K]>) => void;
+    /** The raw URL hash (without the # prefix), or null if none */
+    hash: string | null;
+    /** The raw search params object for advanced use cases */
+    searchParams: URLSearchParams;
+}
+/**
+ * Built-in parsers for common URL parameter types.
+ * Use these with the `parse` option in UrlParamConfig.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   chainId: {
+ *     key: 'chain',
+ *     defaultValue: 8453 as ChainId,
+ *     parse: urlParsers.chainId,
+ *     serialize: urlSerializers.chainId,
+ *   },
+ * }
+ * ```
+ */
+declare const urlParsers: {
+    /**
+     * Parse a chain name or ID to ChainId.
+     * Accepts: "base", "pulsechain", "8453", "369"
+     */
+    chainId: (raw: string) => ChainId | undefined;
+    /**
+     * Parse a string to bigint.
+     * Returns undefined if not a valid integer string.
+     */
+    bigint: (raw: string) => bigint | undefined;
+    /**
+     * Parse a string to number.
+     * Returns undefined if not a valid number.
+     */
+    number: (raw: string) => number | undefined;
+    /**
+     * Parse a string to integer.
+     * Returns undefined if not a valid integer.
+     */
+    integer: (raw: string) => number | undefined;
+    /**
+     * Parse a hex string (validates 0x prefix).
+     * Returns undefined if not a valid hex string.
+     */
+    hex: (raw: string) => Hex | undefined;
+    /**
+     * Parse a boolean string.
+     * Accepts: "true", "false", "1", "0"
+     */
+    boolean: (raw: string) => boolean | undefined;
+    /**
+     * Parse an uppercase string (e.g., for currency tickers).
+     */
+    uppercase: (raw: string) => string;
+    /**
+     * Parse a lowercase string (e.g., for provider keys).
+     */
+    lowercase: (raw: string) => string;
+};
+/**
+ * Built-in serializers for common URL parameter types.
+ * Use these with the `serialize` option in UrlParamConfig.
+ */
+declare const urlSerializers: {
+    /**
+     * Serialize ChainId to chain name.
+     */
+    chainId: (chainId: ChainId) => string;
+    /**
+     * Serialize bigint to string.
+     */
+    bigint: (value: bigint) => string;
+    /**
+     * Serialize boolean to string.
+     */
+    boolean: (value: boolean) => string;
+};
+/**
+ * Hook for managing multiple URL query parameters as typed state.
+ * Uses URL as the single source of truth - no internal useState.
+ *
+ * **Key benefits:**
+ * - No bi-directional state sync (URL is the only source of truth)
+ * - Type-safe parsing and serialization
+ * - Preserves other URL params when updating
+ * - Shareable URLs with full state
+ * - Access to URL hash fragment
+ * - Built-in parsers for common types
+ *
+ * **When to use:**
+ * - UI state that should persist in the URL (filters, selections, pagination)
+ * - State that should be shareable via URL
+ * - Replacing useState + useEffect URL sync anti-patterns
+ *
+ * @template C - Record of config objects keyed by state property names
+ * @param config - Configuration object mapping state keys to URL param configs
+ * @returns Object with current state values, setParam function, hash, and raw searchParams
+ *
+ * @example
+ * ```tsx
+ * // Define config outside component (stable reference)
+ * const depositDetailsConfig = {
+ *   depositId: {
+ *     key: 'id',
+ *     defaultValue: null as bigint | null,
+ *     parse: urlParsers.bigint,
+ *     serialize: urlSerializers.bigint,
+ *   },
+ *   chainId: {
+ *     key: 'chain',
+ *     defaultValue: 8453 as ChainId,
+ *     parse: urlParsers.chainId,
+ *     serialize: urlSerializers.chainId,
+ *   },
+ *   escrow: {
+ *     key: 'escrow',
+ *     defaultValue: null as Hex | null,
+ *     parse: urlParsers.hex,
+ *   },
+ * } as const
+ *
+ * function DepositDetails() {
+ *   const { state, setParam, hash } = useUrlState(depositDetailsConfig)
+ *
+ *   // state.depositId, state.chainId, state.escrow derived from URL
+ *   // hash contains any #fragment if present
+ *
+ *   return (
+ *     <div>
+ *       <p>Deposit: {state.depositId?.toString()}</p>
+ *       <p>Chain: {state.chainId}</p>
+ *       {hash && <p>Section: {hash}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useUrlState<C extends Record<string, UrlParamConfig<unknown>>>(config: C): UseUrlStateResult<C>;
+
+export { type UrlParamConfig, type UseUrlStateResult, urlParsers, urlSerializers, useUrlState };

package/dist/useUrlState.d.ts

@@ -0,0 +1,237 @@
+import { Hex } from 'viem';
+import { ChainId } from '@provex/utils/chain';
+
+/**
+ * @fileoverview URL state management hook for React Router.
+ *
+ * Provides a type-safe way to manage URL query parameters as application state.
+ * The URL is the single source of truth - no useState needed.
+ *
+ * @remarks
+ * **Key Design Principles:**
+ * - URL is the source of truth (no bi-directional sync)
+ * - Type-safe parsing and serialization
+ * - Built-in parsers for common types (bigint, hex, chainId, boolean)
+ * - Preserves other URL params when updating
+ *
+ * **When to Use:**
+ * - Filter state that should persist in URL (currencies, payment methods)
+ * - Page state that should be shareable (deposit ID, chain)
+ * - Replacing useState + useEffect URL sync anti-patterns
+ *
+ * @see MultiSelectFilter for a component that uses this hook pattern
+ */
+
+/**
+ * Configuration for a single URL parameter managed by useUrlState.
+ *
+ * @template T - The TypeScript type of the parsed value
+ *
+ * @example
+ * ```ts
+ * // Simple string param
+ * const providerConfig: UrlParamConfig<string> = {
+ *   key: 'provider',
+ *   defaultValue: 'venmo',
+ * }
+ *
+ * // Param with custom parse/serialize
+ * const pageConfig: UrlParamConfig<number> = {
+ *   key: 'page',
+ *   defaultValue: 1,
+ *   parse: (raw) => parseInt(raw, 10),
+ *   serialize: (val) => String(val),
+ * }
+ * ```
+ */
+interface UrlParamConfig<T> {
+    /** The URL query parameter key (e.g., "provider", "currency", "page") */
+    key: string;
+    /** Default value when the URL param is missing or invalid */
+    defaultValue: T;
+    /**
+     * Custom parser to transform URL string to typed value.
+     * If not provided, the raw string is returned (for string types).
+     * Return undefined to fall back to defaultValue.
+     */
+    parse?: (raw: string) => T | undefined;
+    /**
+     * Custom serializer to transform typed value to URL string.
+     * If not provided, String(value) is used.
+     */
+    serialize?: (value: T) => string;
+}
+/**
+ * Type helper to extract the value type from a UrlParamConfig.
+ */
+type ConfigValue<C> = C extends UrlParamConfig<infer T> ? T : never;
+/**
+ * Type helper to create the state object type from a config record.
+ * Maps each config key to its parsed value type.
+ */
+type UrlStateValues<C extends Record<string, UrlParamConfig<unknown>>> = {
+    [K in keyof C]: ConfigValue<C[K]>;
+};
+/**
+ * Return type of useUrlState hook.
+ * Includes all state values plus a setParam function for updates.
+ */
+interface UseUrlStateResult<C extends Record<string, UrlParamConfig<unknown>>> {
+    /** Current state values derived from URL params */
+    state: UrlStateValues<C>;
+    /**
+     * Update a single URL parameter.
+     * This updates the URL which triggers a re-render with new state.
+     *
+     * @param key - The config key (not the URL param key)
+     * @param value - The new value to set
+     *
+     * @example
+     * ```ts
+     * const { state, setParam } = useUrlState(config)
+     * setParam('provider', 'revolut')  // Updates ?provider=revolut
+     * ```
+     */
+    setParam: <K extends keyof C>(key: K, value: ConfigValue<C[K]>) => void;
+    /** The raw URL hash (without the # prefix), or null if none */
+    hash: string | null;
+    /** The raw search params object for advanced use cases */
+    searchParams: URLSearchParams;
+}
+/**
+ * Built-in parsers for common URL parameter types.
+ * Use these with the `parse` option in UrlParamConfig.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   chainId: {
+ *     key: 'chain',
+ *     defaultValue: 8453 as ChainId,
+ *     parse: urlParsers.chainId,
+ *     serialize: urlSerializers.chainId,
+ *   },
+ * }
+ * ```
+ */
+declare const urlParsers: {
+    /**
+     * Parse a chain name or ID to ChainId.
+     * Accepts: "base", "pulsechain", "8453", "369"
+     */
+    chainId: (raw: string) => ChainId | undefined;
+    /**
+     * Parse a string to bigint.
+     * Returns undefined if not a valid integer string.
+     */
+    bigint: (raw: string) => bigint | undefined;
+    /**
+     * Parse a string to number.
+     * Returns undefined if not a valid number.
+     */
+    number: (raw: string) => number | undefined;
+    /**
+     * Parse a string to integer.
+     * Returns undefined if not a valid integer.
+     */
+    integer: (raw: string) => number | undefined;
+    /**
+     * Parse a hex string (validates 0x prefix).
+     * Returns undefined if not a valid hex string.
+     */
+    hex: (raw: string) => Hex | undefined;
+    /**
+     * Parse a boolean string.
+     * Accepts: "true", "false", "1", "0"
+     */
+    boolean: (raw: string) => boolean | undefined;
+    /**
+     * Parse an uppercase string (e.g., for currency tickers).
+     */
+    uppercase: (raw: string) => string;
+    /**
+     * Parse a lowercase string (e.g., for provider keys).
+     */
+    lowercase: (raw: string) => string;
+};
+/**
+ * Built-in serializers for common URL parameter types.
+ * Use these with the `serialize` option in UrlParamConfig.
+ */
+declare const urlSerializers: {
+    /**
+     * Serialize ChainId to chain name.
+     */
+    chainId: (chainId: ChainId) => string;
+    /**
+     * Serialize bigint to string.
+     */
+    bigint: (value: bigint) => string;
+    /**
+     * Serialize boolean to string.
+     */
+    boolean: (value: boolean) => string;
+};
+/**
+ * Hook for managing multiple URL query parameters as typed state.
+ * Uses URL as the single source of truth - no internal useState.
+ *
+ * **Key benefits:**
+ * - No bi-directional state sync (URL is the only source of truth)
+ * - Type-safe parsing and serialization
+ * - Preserves other URL params when updating
+ * - Shareable URLs with full state
+ * - Access to URL hash fragment
+ * - Built-in parsers for common types
+ *
+ * **When to use:**
+ * - UI state that should persist in the URL (filters, selections, pagination)
+ * - State that should be shareable via URL
+ * - Replacing useState + useEffect URL sync anti-patterns
+ *
+ * @template C - Record of config objects keyed by state property names
+ * @param config - Configuration object mapping state keys to URL param configs
+ * @returns Object with current state values, setParam function, hash, and raw searchParams
+ *
+ * @example
+ * ```tsx
+ * // Define config outside component (stable reference)
+ * const depositDetailsConfig = {
+ *   depositId: {
+ *     key: 'id',
+ *     defaultValue: null as bigint | null,
+ *     parse: urlParsers.bigint,
+ *     serialize: urlSerializers.bigint,
+ *   },
+ *   chainId: {
+ *     key: 'chain',
+ *     defaultValue: 8453 as ChainId,
+ *     parse: urlParsers.chainId,
+ *     serialize: urlSerializers.chainId,
+ *   },
+ *   escrow: {
+ *     key: 'escrow',
+ *     defaultValue: null as Hex | null,
+ *     parse: urlParsers.hex,
+ *   },
+ * } as const
+ *
+ * function DepositDetails() {
+ *   const { state, setParam, hash } = useUrlState(depositDetailsConfig)
+ *
+ *   // state.depositId, state.chainId, state.escrow derived from URL
+ *   // hash contains any #fragment if present
+ *
+ *   return (
+ *     <div>
+ *       <p>Deposit: {state.depositId?.toString()}</p>
+ *       <p>Chain: {state.chainId}</p>
+ *       {hash && <p>Section: {hash}</p>}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useUrlState<C extends Record<string, UrlParamConfig<unknown>>>(config: C): UseUrlStateResult<C>;
+
+export { type UrlParamConfig, type UseUrlStateResult, urlParsers, urlSerializers, useUrlState };

package/dist/useUrlState.js

@@ -0,0 +1,149 @@
+import { useRef, useMemo, useCallback } from 'react';
+import { useSearchParams, useLocation } from 'react-router-dom';
+import { chains } from '@provex/utils/chain';
+
+// src/useUrlState.ts
+var urlParsers = {
+  /**
+   * Parse a chain name or ID to ChainId.
+   * Accepts: "base", "pulsechain", "8453", "369"
+   */
+  chainId: (raw) => {
+    const byName = chains.find((c) => c.name.toLowerCase() === raw.toLowerCase());
+    if (byName) return byName.id;
+    const parsed = parseInt(raw, 10);
+    if (!isNaN(parsed)) {
+      const byId = chains.find((c) => c.id === parsed);
+      if (byId) return byId.id;
+    }
+    return void 0;
+  },
+  /**
+   * Parse a string to bigint.
+   * Returns undefined if not a valid integer string.
+   */
+  bigint: (raw) => {
+    try {
+      return BigInt(raw);
+    } catch {
+      return void 0;
+    }
+  },
+  /**
+   * Parse a string to number.
+   * Returns undefined if not a valid number.
+   */
+  number: (raw) => {
+    const parsed = Number(raw);
+    return isNaN(parsed) ? void 0 : parsed;
+  },
+  /**
+   * Parse a string to integer.
+   * Returns undefined if not a valid integer.
+   */
+  integer: (raw) => {
+    const parsed = parseInt(raw, 10);
+    return isNaN(parsed) ? void 0 : parsed;
+  },
+  /**
+   * Parse a hex string (validates 0x prefix).
+   * Returns undefined if not a valid hex string.
+   */
+  hex: (raw) => {
+    if (raw.startsWith("0x") && /^0x[0-9a-fA-F]*$/.test(raw)) {
+      return raw;
+    }
+    return void 0;
+  },
+  /**
+   * Parse a boolean string.
+   * Accepts: "true", "false", "1", "0"
+   */
+  boolean: (raw) => {
+    if (raw === "true" || raw === "1") return true;
+    if (raw === "false" || raw === "0") return false;
+    return void 0;
+  },
+  /**
+   * Parse an uppercase string (e.g., for currency tickers).
+   */
+  uppercase: (raw) => raw.toUpperCase(),
+  /**
+   * Parse a lowercase string (e.g., for provider keys).
+   */
+  lowercase: (raw) => raw.toLowerCase()
+};
+var urlSerializers = {
+  /**
+   * Serialize ChainId to chain name.
+   */
+  chainId: (chainId) => {
+    const chain = chains.find((c) => c.id === chainId);
+    return chain?.name.toLowerCase() ?? String(chainId);
+  },
+  /**
+   * Serialize bigint to string.
+   */
+  bigint: (value) => value.toString(),
+  /**
+   * Serialize boolean to string.
+   */
+  boolean: (value) => value ? "true" : "false"
+};
+function parseParam(searchParams, config) {
+  const raw = searchParams.get(config.key);
+  if (raw === null) {
+    return config.defaultValue;
+  }
+  if (config.parse) {
+    const parsed = config.parse(raw);
+    return parsed !== void 0 ? parsed : config.defaultValue;
+  }
+  return raw;
+}
+function serializeParam(value, config) {
+  if (config.serialize) {
+    return config.serialize(value);
+  }
+  return String(value);
+}
+function useUrlState(config) {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const location = useLocation();
+  const configRef = useRef(config);
+  configRef.current = config;
+  const hash = useMemo(() => {
+    const rawHash = location.hash;
+    return rawHash && rawHash.length > 1 ? rawHash.slice(1) : null;
+  }, [location.hash]);
+  const state = useMemo(() => {
+    const result = {};
+    for (const [key, paramConfig] of Object.entries(configRef.current)) {
+      result[key] = parseParam(
+        searchParams,
+        paramConfig
+      );
+    }
+    return result;
+  }, [searchParams]);
+  const setParam = useCallback(
+    (key, value) => {
+      const paramConfig = configRef.current[key];
+      const serialized = serializeParam(value, paramConfig);
+      setSearchParams(
+        (prev) => {
+          const next = new URLSearchParams(prev);
+          next.set(paramConfig.key, serialized);
+          return next;
+        },
+        { replace: true }
+      );
+    },
+    [setSearchParams]
+  );
+  return { state, setParam, hash, searchParams };
+}
+
+export { urlParsers, urlSerializers, useUrlState };
+//# sourceMappingURL=useUrlState.js.map
+//# sourceMappingURL=useUrlState.js.map

package/dist/useUrlState.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useUrlState.ts"],"names":[],"mappings":"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","file":"useUrlState.js","sourcesContent":["/**\n * @fileoverview URL state management hook for React Router.\n *\n * Provides a type-safe way to manage URL query parameters as application state.\n * The URL is the single source of truth - no useState needed.\n *\n * @remarks\n * **Key Design Principles:**\n * - URL is the source of truth (no bi-directional sync)\n * - Type-safe parsing and serialization\n * - Built-in parsers for common types (bigint, hex, chainId, boolean)\n * - Preserves other URL params when updating\n *\n * **When to Use:**\n * - Filter state that should persist in URL (currencies, payment methods)\n * - Page state that should be shareable (deposit ID, chain)\n * - Replacing useState + useEffect URL sync anti-patterns\n *\n * @see MultiSelectFilter for a component that uses this hook pattern\n */\n\nimport { useCallback, useMemo, useRef } from 'react'\nimport { useSearchParams, useLocation } from 'react-router-dom'\nimport type { Hex } from 'viem'\nimport { type ChainId, chains } from '@provex/utils/chain'\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * Configuration for a single URL parameter managed by useUrlState.\n *\n * @template T - The TypeScript type of the parsed value\n *\n * @example\n * ```ts\n * // Simple string param\n * const providerConfig: UrlParamConfig<string> = {\n *   key: 'provider',\n *   defaultValue: 'venmo',\n * }\n *\n * // Param with custom parse/serialize\n * const pageConfig: UrlParamConfig<number> = {\n *   key: 'page',\n *   defaultValue: 1,\n *   parse: (raw) => parseInt(raw, 10),\n *   serialize: (val) => String(val),\n * }\n * ```\n */\nexport interface UrlParamConfig<T> {\n  /** The URL query parameter key (e.g., \"provider\", \"currency\", \"page\") */\n  key: string\n  /** Default value when the URL param is missing or invalid */\n  defaultValue: T\n  /**\n   * Custom parser to transform URL string to typed value.\n   * If not provided, the raw string is returned (for string types).\n   * Return undefined to fall back to defaultValue.\n   */\n  parse?: (raw: string) => T | undefined\n  /**\n   * Custom serializer to transform typed value to URL string.\n   * If not provided, String(value) is used.\n   */\n  serialize?: (value: T) => string\n}\n\n/**\n * Type helper to extract the value type from a UrlParamConfig.\n */\ntype ConfigValue<C> = C extends UrlParamConfig<infer T> ? T : never\n\n/**\n * Type helper to create the state object type from a config record.\n * Maps each config key to its parsed value type.\n */\ntype UrlStateValues<C extends Record<string, UrlParamConfig<unknown>>> = {\n  [K in keyof C]: ConfigValue<C[K]>\n}\n\n/**\n * Return type of useUrlState hook.\n * Includes all state values plus a setParam function for updates.\n */\nexport interface UseUrlStateResult<C extends Record<string, UrlParamConfig<unknown>>> {\n  /** Current state values derived from URL params */\n  state: UrlStateValues<C>\n  /**\n   * Update a single URL parameter.\n   * This updates the URL which triggers a re-render with new state.\n   *\n   * @param key - The config key (not the URL param key)\n   * @param value - The new value to set\n   *\n   * @example\n   * ```ts\n   * const { state, setParam } = useUrlState(config)\n   * setParam('provider', 'revolut')  // Updates ?provider=revolut\n   * ```\n   */\n  setParam: <K extends keyof C>(key: K, value: ConfigValue<C[K]>) => void\n  /** The raw URL hash (without the # prefix), or null if none */\n  hash: string | null\n  /** The raw search params object for advanced use cases */\n  searchParams: URLSearchParams\n}\n\n// =============================================================================\n// Built-in Parsers\n// =============================================================================\n\n/**\n * Built-in parsers for common URL parameter types.\n * Use these with the `parse` option in UrlParamConfig.\n *\n * @example\n * ```ts\n * const config = {\n *   chainId: {\n *     key: 'chain',\n *     defaultValue: 8453 as ChainId,\n *     parse: urlParsers.chainId,\n *     serialize: urlSerializers.chainId,\n *   },\n * }\n * ```\n */\nexport const urlParsers = {\n  /**\n   * Parse a chain name or ID to ChainId.\n   * Accepts: \"base\", \"pulsechain\", \"8453\", \"369\"\n   */\n  chainId: (raw: string): ChainId | undefined => {\n    // Try by name first\n    const byName = chains.find(c => c.name.toLowerCase() === raw.toLowerCase())\n    if (byName) return byName.id as ChainId\n\n    // Try by ID\n    const parsed = parseInt(raw, 10)\n    if (!isNaN(parsed)) {\n      const byId = chains.find(c => c.id === parsed)\n      if (byId) return byId.id as ChainId\n    }\n\n    return undefined\n  },\n\n  /**\n   * Parse a string to bigint.\n   * Returns undefined if not a valid integer string.\n   */\n  bigint: (raw: string): bigint | undefined => {\n    try {\n      return BigInt(raw)\n    } catch {\n      return undefined\n    }\n  },\n\n  /**\n   * Parse a string to number.\n   * Returns undefined if not a valid number.\n   */\n  number: (raw: string): number | undefined => {\n    const parsed = Number(raw)\n    return isNaN(parsed) ? undefined : parsed\n  },\n\n  /**\n   * Parse a string to integer.\n   * Returns undefined if not a valid integer.\n   */\n  integer: (raw: string): number | undefined => {\n    const parsed = parseInt(raw, 10)\n    return isNaN(parsed) ? undefined : parsed\n  },\n\n  /**\n   * Parse a hex string (validates 0x prefix).\n   * Returns undefined if not a valid hex string.\n   */\n  hex: (raw: string): Hex | undefined => {\n    if (raw.startsWith('0x') && /^0x[0-9a-fA-F]*$/.test(raw)) {\n      return raw as Hex\n    }\n    return undefined\n  },\n\n  /**\n   * Parse a boolean string.\n   * Accepts: \"true\", \"false\", \"1\", \"0\"\n   */\n  boolean: (raw: string): boolean | undefined => {\n    if (raw === 'true' || raw === '1') return true\n    if (raw === 'false' || raw === '0') return false\n    return undefined\n  },\n\n  /**\n   * Parse an uppercase string (e.g., for currency tickers).\n   */\n  uppercase: (raw: string): string => raw.toUpperCase(),\n\n  /**\n   * Parse a lowercase string (e.g., for provider keys).\n   */\n  lowercase: (raw: string): string => raw.toLowerCase(),\n}\n\n/**\n * Built-in serializers for common URL parameter types.\n * Use these with the `serialize` option in UrlParamConfig.\n */\nexport const urlSerializers = {\n  /**\n   * Serialize ChainId to chain name.\n   */\n  chainId: (chainId: ChainId): string => {\n    const chain = chains.find(c => c.id === chainId)\n    return chain?.name.toLowerCase() ?? String(chainId)\n  },\n\n  /**\n   * Serialize bigint to string.\n   */\n  bigint: (value: bigint): string => value.toString(),\n\n  /**\n   * Serialize boolean to string.\n   */\n  boolean: (value: boolean): string => value ? 'true' : 'false',\n}\n\n// =============================================================================\n// Hook Implementation\n// =============================================================================\n\n/**\n * Parse a URL parameter value using the provided config.\n * Returns the parsed value or defaultValue if parsing fails or param is missing.\n */\nfunction parseParam<T>(\n  searchParams: URLSearchParams,\n  config: UrlParamConfig<T>\n): T {\n  const raw = searchParams.get(config.key)\n\n  if (raw === null) {\n    return config.defaultValue\n  }\n\n  if (config.parse) {\n    const parsed = config.parse(raw)\n    return parsed !== undefined ? parsed : config.defaultValue\n  }\n\n  // For string types, return raw value directly\n  // TypeScript doesn't know T is string here, but this is safe\n  // because if no parse is provided, T should be string\n  return raw as T\n}\n\n/**\n * Serialize a value to URL string using the provided config.\n */\nfunction serializeParam<T>(value: T, config: UrlParamConfig<T>): string {\n  if (config.serialize) {\n    return config.serialize(value)\n  }\n  return String(value)\n}\n\n/**\n * Hook for managing multiple URL query parameters as typed state.\n * Uses URL as the single source of truth - no internal useState.\n *\n * **Key benefits:**\n * - No bi-directional state sync (URL is the only source of truth)\n * - Type-safe parsing and serialization\n * - Preserves other URL params when updating\n * - Shareable URLs with full state\n * - Access to URL hash fragment\n * - Built-in parsers for common types\n *\n * **When to use:**\n * - UI state that should persist in the URL (filters, selections, pagination)\n * - State that should be shareable via URL\n * - Replacing useState + useEffect URL sync anti-patterns\n *\n * @template C - Record of config objects keyed by state property names\n * @param config - Configuration object mapping state keys to URL param configs\n * @returns Object with current state values, setParam function, hash, and raw searchParams\n *\n * @example\n * ```tsx\n * // Define config outside component (stable reference)\n * const depositDetailsConfig = {\n *   depositId: {\n *     key: 'id',\n *     defaultValue: null as bigint | null,\n *     parse: urlParsers.bigint,\n *     serialize: urlSerializers.bigint,\n *   },\n *   chainId: {\n *     key: 'chain',\n *     defaultValue: 8453 as ChainId,\n *     parse: urlParsers.chainId,\n *     serialize: urlSerializers.chainId,\n *   },\n *   escrow: {\n *     key: 'escrow',\n *     defaultValue: null as Hex | null,\n *     parse: urlParsers.hex,\n *   },\n * } as const\n *\n * function DepositDetails() {\n *   const { state, setParam, hash } = useUrlState(depositDetailsConfig)\n *\n *   // state.depositId, state.chainId, state.escrow derived from URL\n *   // hash contains any #fragment if present\n *\n *   return (\n *     <div>\n *       <p>Deposit: {state.depositId?.toString()}</p>\n *       <p>Chain: {state.chainId}</p>\n *       {hash && <p>Section: {hash}</p>}\n *     </div>\n *   )\n * }\n * ```\n */\nexport function useUrlState<C extends Record<string, UrlParamConfig<unknown>>>(\n  config: C\n): UseUrlStateResult<C> {\n  const [searchParams, setSearchParams] = useSearchParams()\n  const location = useLocation()\n\n  // Use ref for stable config reference to avoid re-creating memoized values\n  // when config object identity changes (but contents are the same)\n  const configRef = useRef(config)\n  configRef.current = config\n\n  // Extract hash without the # prefix\n  const hash = useMemo(() => {\n    const rawHash = location.hash\n    return rawHash && rawHash.length > 1 ? rawHash.slice(1) : null\n  }, [location.hash])\n\n  // Derive all state values from URL params via useMemo\n  // This is the key insight: URL is source of truth, state is derived\n  const state = useMemo(() => {\n    const result = {} as UrlStateValues<C>\n    for (const [key, paramConfig] of Object.entries(configRef.current)) {\n      ; (result as Record<string, unknown>)[key] = parseParam(\n        searchParams,\n        paramConfig as UrlParamConfig<unknown>\n      )\n    }\n    return result\n  }, [searchParams])\n\n  // Create setter that updates URL params\n  // Other params are preserved, only the specified param is updated\n  const setParam = useCallback(\n    <K extends keyof C>(key: K, value: ConfigValue<C[K]>) => {\n      const paramConfig = configRef.current[key] as UrlParamConfig<ConfigValue<C[K]>>\n      const serialized = serializeParam(value, paramConfig)\n\n      setSearchParams(\n        (prev) => {\n          const next = new URLSearchParams(prev)\n          next.set(paramConfig.key, serialized)\n          return next\n        },\n        { replace: true }\n      )\n    },\n    [setSearchParams]\n  )\n\n  return { state, setParam, hash, searchParams }\n}\n"]}