@maestro-js/components 1.0.0-alpha.18 → 1.0.0-alpha.2

package/src/utils/use-query-state.ts

@@ -1,626 +0,0 @@
-import { useLocation, useNavigation, useSearchParams as useSearchParamsRR } from 'react-router'
-import { dateFns, dateTimeFns, durationFns, type Iso } from 'iso-fns'
-import React from 'react'
-import { useStableAccessor } from './use-stable-accessor'
-
-// ────────────────────────────────────────────────────────────────
-// Types
-// ────────────────────────────────────────────────────────────────
-
-interface QueryStateNavigateOptions {
-  replace?: boolean
-  preventScrollReset?: boolean
-  /** When true, updates the URL via `history.pushState`/`replaceState` without triggering a React Router navigation. */
-  shallow?: boolean
-}
-
-interface CodecDef<T> {
-  name: string
-  defaultValue?: T
-  ['~type']: T
-  /** When true, the param is removed from the URL when the value matches `defaultValue`. */
-  clearOnDefault?: boolean
-}
-
-interface Codec<Def extends CodecDef<any>> {
-  _def: Def
-  encode(value: Def['~type']): string | null
-  decode(value: string | null): Def['~type']
-}
-
-interface CodecConfigurator<Def extends CodecDef<any>> extends Codec<Def> {
-  default(defaultValue: Def['~type']): CodecConfigurator<Def>
-  clearOnDefault(clear: boolean): CodecConfigurator<Def>
-}
-
-function makeConfigurator<Def extends CodecDef<any>>(codec: Codec<Def>): CodecConfigurator<Def> {
-  return {
-    ...codec,
-    default(defaultValue) {
-      return makeConfigurator({ ...codec, _def: { ...codec._def, defaultValue } })
-    },
-    clearOnDefault(clear) {
-      return makeConfigurator({ ...codec, _def: { ...codec._def, clearOnDefault: clear } })
-    }
-  }
-}
-
-// ────────────────────────────────────────────────────────────────
-// Codec defs
-// ────────────────────────────────────────────────────────────────
-
-interface NoopDef extends CodecDef<string | null> {
-  name: 'noop'
-  ['~type']: string | null
-}
-
-interface StringDef extends CodecDef<string | null> {
-  name: 'string'
-  ['~type']: string | null
-}
-
-interface ValidatedDef<T extends string> extends CodecDef<T | null> {
-  name: string
-  ['~type']: T | null
-  isValid: (v: string) => v is T
-}
-
-interface RelativeDateTimeRangeDef extends CodecDef<Iso.Duration | { start: Iso.DateTime; end: Iso.DateTime } | null> {
-  name: 'relativeDateTimeRange'
-  ['~type']: Iso.Duration | { start: Iso.DateTime; end: Iso.DateTime } | null
-}
-
-interface IntDef extends CodecDef<number | null> {
-  name: 'int'
-  ['~type']: number | null
-}
-
-interface FloatDef extends CodecDef<number | null> {
-  name: 'float'
-  ['~type']: number | null
-}
-
-interface HexDef extends CodecDef<number | null> {
-  name: 'hex'
-  ['~type']: number | null
-}
-
-interface IndexDef extends CodecDef<number | null> {
-  name: 'index'
-  ['~type']: number | null
-}
-
-interface BooleanDef extends CodecDef<boolean | null> {
-  name: 'boolean'
-  ['~type']: boolean | null
-}
-
-interface EnumDef<T extends string> extends CodecDef<T | null> {
-  name: 'enum'
-  ['~type']: T | null
-  values: readonly T[]
-}
-
-interface EnumArrayDef<T extends string> extends CodecDef<T[]> {
-  name: 'enumArray'
-  ['~type']: T[]
-  values: readonly T[]
-}
-
-// ────────────────────────────────────────────────────────────────
-// Codec factories
-// ────────────────────────────────────────────────────────────────
-
-/** Pass-through — no transformation, value is `string | null`. */
-function noop(def: Omit<NoopDef, '~type'>): Codec<NoopDef> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => value,
-    decode: (value) => value
-  }
-}
-
-/** String codec — pass-through with `string | null` type. */
-function string(def: Omit<StringDef, '~type'>): Codec<StringDef> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => value,
-    decode: (value) => value
-  }
-}
-
-/** Validates a string against a guard function. Used for date, dateTime, duration. */
-function validated<T extends string>(def: Omit<ValidatedDef<T>, '~type'>): Codec<ValidatedDef<T>> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => (value != null && def.isValid(value) ? value : null),
-    decode: (value) => (value !== null && def.isValid(value) ? value : null)
-  }
-}
-
-/**
- * Either an ISO duration (relative range) or a `start~end` pair of ISO
- * date-times (absolute range). Useful for "last 7 days" vs a custom window.
- */
-function relativeDateTimeRange(def: Omit<RelativeDateTimeRangeDef, '~type'>): Codec<RelativeDateTimeRangeDef> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => {
-      if (value == null) return null
-      if (durationFns.isValid(value)) return value
-      if (typeof value === 'object' && 'start' in value && 'end' in value) {
-        return dateTimeFns.isValid(value.start) && dateTimeFns.isValid(value.end) ? `${value.start}~${value.end}` : null
-      }
-      return null
-    },
-    decode: (value) => {
-      if (value === null) return null
-      if (durationFns.isValid(value)) return value
-      const [start, end] = value.split('~')
-      return dateTimeFns.isValid(start) && dateTimeFns.isValid(end) ? { start, end } : null
-    }
-  }
-}
-
-/** Integer (base-10). Non-integer or missing values decode to `null`. */
-function int(def: Omit<IntDef, '~type'>): Codec<IntDef> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => (value != null && Number.isInteger(value) ? value.toString() : null),
-    decode: (value) => {
-      if (value === null) return null
-      const num = Number(value)
-      return Number.isInteger(num) ? num : null
-    }
-  }
-}
-
-/** Finite floating-point number. `NaN` / `Infinity` decode to `null`. */
-function float(def: Omit<FloatDef, '~type'>): Codec<FloatDef> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => (value != null && Number.isFinite(value) ? value.toString() : null),
-    decode: (value) => {
-      if (value === null) return null
-      const num = Number(value)
-      return Number.isFinite(num) ? num : null
-    }
-  }
-}
-
-/** Hexadecimal integer (with or without `0x` prefix). Stored without prefix. */
-function hex(def: Omit<HexDef, '~type'>): Codec<HexDef> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => (typeof value === 'number' && Number.isFinite(value) ? value.toString(16) : null),
-    decode: (value) => {
-      if (value === null) return null
-      const body = value.trim().toLowerCase().replace(/^0x/, '')
-      if (body.length === 0 || /[^0-9a-f]/i.test(body)) return null
-      const num = parseInt(body, 16)
-      return Number.isFinite(num) ? num : null
-    }
-  }
-}
-
-/**
- * Zero-based index stored as a **1-based** number in the URL.
- * `?page=1` decodes to `0`, `0` encodes to `"1"`.
- */
-function index(def: Omit<IndexDef, '~type'>): Codec<IndexDef> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => (typeof value === 'number' && Number.isInteger(value) && value >= 0 ? (value + 1).toString() : null),
-    decode: (value) => {
-      if (value === null) return null
-      const num = Number(value)
-      return Number.isInteger(num) && num >= 1 ? num - 1 : null
-    }
-  }
-}
-
-/** Boolean accepting common truthy/falsy strings (`1`, `true`, `yes`, `on`, etc). Encodes as `"1"` / `"0"`. */
-function boolean(def: Omit<BooleanDef, '~type'>): Codec<BooleanDef> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => (value == null ? null : value ? '1' : '0'),
-    decode: (value) => {
-      if (value === null) return null
-      const v = value.trim().toLowerCase()
-      if (v === '1' || v === 'true' || v === 't' || v === 'yes' || v === 'y' || v === 'on') return true
-      if (v === '0' || v === 'false' || v === 'f' || v === 'no' || v === 'n' || v === 'off') return false
-      return null
-    }
-  }
-}
-
-/** Constrained to one of the provided `values`. Anything else decodes to `null`. */
-function enumCodec<T extends string>(def: Omit<EnumDef<T>, '~type'>): Codec<EnumDef<T>> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => value ?? null,
-    decode: (value) => {
-      if (value === null) return null
-      return (def.values as readonly string[]).includes(value) ? (value as T) : null
-    }
-  }
-}
-
-/**
- * Comma-separated list constrained to the provided `values`.
- * Decodes to `T[]` (empty array when missing). Encodes in the canonical
- * order of `values` so the same selection always produces the same URL.
- */
-function enumArray<T extends string>(def: Omit<EnumArrayDef<T>, '~type'>): Codec<EnumArrayDef<T>> {
-  return {
-    _def: { ...def, ['~type']: null as any },
-    encode: (value) => {
-      if (!value.length) return null
-      return value
-        .sort((v1, v2) => def.values.indexOf(v1) - def.values.indexOf(v2))
-        .map((v) => encodeURIComponent(v))
-        .join(',')
-    },
-    decode: (value) => {
-      if (value === null) return []
-      return value
-        .split(',')
-        .map((v) => decodeURIComponent(v))
-        .filter((v) => def.values.includes(v as T)) as T[]
-    }
-  }
-}
-
-// ────────────────────────────────────────────────────────────────
-// Serialize / Deserialize
-// ────────────────────────────────────────────────────────────────
-
-/** Extract the serializable def from a codec. */
-function serializeCodec<Def extends CodecDef<any>>(codec: Codec<Def>): Def {
-  return codec._def
-}
-
-type CodecFactory = (def: any) => Codec<any>
-
-const defaultFactories: Record<string, CodecFactory> = {
-  noop,
-  string,
-  date: validated,
-  dateTime: validated,
-  duration: validated,
-  relativeDateTimeRange,
-  int,
-  float,
-  hex,
-  index,
-  boolean,
-  enum: enumCodec,
-  enumArray
-}
-
-/** Reconstruct a codec from a serialized def. */
-function deserializeCodec<Def extends CodecDef<any>>(
-  def: Def,
-  factories: Record<string, CodecFactory> = defaultFactories
-): Codec<Def> {
-  const factory = factories[def.name]
-  if (!factory) throw new Error(`Unknown codec: ${def.name}`)
-  return factory(def) as Codec<Def>
-}
-
-type SerializedCodec<C extends Codec<CodecDef<any>>> = C['_def']
-
-type SerializedLoader<L extends QueryStateLoader> = { [K in keyof L]: SerializedCodec<L[K]> }
-
-/** Serialize a loader into a plain object of defs, keyed by param name. */
-function serializeLoader<L extends QueryStateLoader>(loader: L): SerializedLoader<L> {
-  return Object.fromEntries(
-    Object.entries(loader).map(([name, codec]) => [name, serializeCodec(codec)])
-  ) as SerializedLoader<L>
-}
-
-/** Reconstruct a loader from a serialized object of defs. */
-function deserializeLoader<L extends QueryStateLoader>(
-  defs: SerializedLoader<L>,
-  factories: Record<string, CodecFactory> = defaultFactories
-): L {
-  return Object.fromEntries(
-    Object.entries(defs).map(([name, def]) => [name, deserializeCodec(def as CodecDef<any>, factories)])
-  ) as L
-}
-
-// ────────────────────────────────────────────────────────────────
-// Built-in codecs
-// ────────────────────────────────────────────────────────────────
-
-/**
- * Library of built-in codecs for common URL search-param types.
- *
- * Each codec converts between a URL string and a typed value, returning `null`
- * for missing or invalid params. Chain `.default(v)` to substitute a
- * fallback, or `.clearOnDefault(true)` to remove the param when it matches the default.
- */
-const codecs = {
-  /** Pass-through — no transformation, value is `string | null`. */
-  noop: () => makeConfigurator(noop({ name: 'noop' })),
-
-  /** String codec — pass-through defaulting to `''` (never null). */
-  string: () => makeConfigurator(string({ name: 'string' })).default(''),
-
-  /** ISO date (`YYYY-MM-DD`). Invalid strings decode to `null`. */
-  date: () => makeConfigurator(validated({ name: 'date', isValid: dateFns.isValid })),
-
-  /** ISO date-time (`YYYY-MM-DDTHH:mm:ss`). Invalid strings decode to `null`. */
-  dateTime: () => makeConfigurator(validated({ name: 'dateTime', isValid: dateTimeFns.isValid })),
-
-  /** ISO duration (`P1DT2H`, etc). Invalid strings decode to `null`. */
-  duration: () => makeConfigurator(validated({ name: 'duration', isValid: durationFns.isValid })),
-
-  /**
-   * Either an ISO duration (relative range) or a `start~end` pair of ISO
-   * date-times (absolute range). Useful for "last 7 days" vs a custom window.
-   */
-  relativeDateTimeRange: () => makeConfigurator(relativeDateTimeRange({ name: 'relativeDateTimeRange' })),
-
-  /** Integer (base-10). Non-integer or missing values decode to `null`. */
-  int: () => makeConfigurator(int({ name: 'int' })),
-
-  /** Finite floating-point number. `NaN` / `Infinity` decode to `null`. */
-  float: () => makeConfigurator(float({ name: 'float' })),
-
-  /** Hexadecimal integer (with or without `0x` prefix). Stored without prefix. */
-  hex: () => makeConfigurator(hex({ name: 'hex' })),
-
-  /**
-   * Zero-based index stored as a **1-based** number in the URL.
-   * `?page=1` decodes to `0`, `0` encodes to `"1"`.
-   */
-  index: () => makeConfigurator(index({ name: 'index' })),
-
-  /** Boolean accepting common truthy/falsy strings (`1`, `true`, `yes`, `on`, etc). Encodes as `"1"` / `"0"`. */
-  boolean: () => makeConfigurator(boolean({ name: 'boolean' })),
-
-  /** Constrained to one of the provided `values`. Anything else decodes to `null`. */
-  enum: <T extends string>(values: readonly T[]) => makeConfigurator(enumCodec({ name: 'enum', values })),
-
-  /**
-   * Comma-separated list constrained to the provided `values`.
-   * Decodes to `T[]` (empty array when missing). Encodes in the canonical
-   * order of `values` so the same selection always produces the same URL.
-   */
-  enumArray: <T extends string>(values: readonly T[]) => makeConfigurator(enumArray({ name: 'enumArray', values }))
-}
-
-// ────────────────────────────────────────────────────────────────
-// Loader types
-// ────────────────────────────────────────────────────────────────
-
-/** A map of param names to codecs, defining the shape of search-param state. */
-type QueryStateLoader<T extends { [key: string]: any } = { [key: string]: any }> = {
-  [key in keyof T]: Codec<CodecDef<T[key]>>
-}
-
-type ExtractTypeFromLoader<L extends QueryStateLoader> = {
-  [key in keyof L]: L[key] extends Codec<infer S> ? S['~type'] : never
-}
-
-// ────────────────────────────────────────────────────────────────
-// Internal helpers
-// ────────────────────────────────────────────────────────────────
-
-function getQueryParam<T>(naturalValue: string | null, codec: Codec<CodecDef<T>>): T {
-  try {
-    const decoded = codec.decode(naturalValue)
-    return (decoded ?? codec?._def?.defaultValue ?? null) as T
-  } catch {
-    return (codec?._def?.defaultValue ?? null) as T
-  }
-}
-
-function setQueryParam<V>({
-  searchParams,
-  name,
-  value,
-  codec
-}: {
-  searchParams: URLSearchParams
-  name: string
-  value: V
-  codec: Codec<CodecDef<V>>
-}): void {
-  const encoded = codec.encode(value)
-  if (
-    encoded === null ||
-    (codec._def?.defaultValue != null && codec._def?.clearOnDefault && encoded === codec.encode(codec._def?.defaultValue))
-  ) {
-    searchParams.delete(name)
-  } else {
-    searchParams.set(name, encoded)
-  }
-}
-
-function queryParamsToObject<L extends QueryStateLoader>(params: URLSearchParams, loader: L) {
-  return Object.fromEntries(
-    Object.entries(loader).map(([name, codec]) => [name, getQueryParam(params.get(name), codec)])
-  ) as ExtractTypeFromLoader<L>
-}
-
-// ────────────────────────────────────────────────────────────────
-// Public API
-// ────────────────────────────────────────────────────────────────
-
-/**
- * Decode search params from various sources (URL string, `Request`, `URLSearchParams`, or
- * an object with a `.search` property) using a loader. Useful in loaders/actions on the server side.
- */
-function getSearchParamsState<L extends QueryStateLoader>(
-  searchParams: URLSearchParams | string | Request | { search: string },
-  loader: L
-) {
-  if (typeof searchParams === 'string') {
-    return queryParamsToObject(new URL(searchParams).searchParams, loader)
-  } else if ('url' in searchParams) {
-    return queryParamsToObject(new URL(searchParams.url).searchParams, loader)
-  } else if ('search' in searchParams) {
-    return queryParamsToObject(new URLSearchParams(searchParams.search), loader)
-  } else {
-    return queryParamsToObject(searchParams, loader)
-  }
-}
-
-/**
- * React hook that binds a single search param to component state via a codec.
- * Returns `[value, setValue]` like `React.useState`. The setter accepts a value
- * or updater function and optional {@link QueryStateNavigateOptions}.
- *
- * Reads from the pending navigation location when one is in flight so the UI
- * reflects optimistic state during transitions.
- */
-function useState<S>(name: string, codec: Codec<CodecDef<S>>): [S, (val: S | ((prevState: S) => S), navigateOpts?: QueryStateNavigateOptions) => void] {
-  const [searchParamsRaw, setSearchParams] = useSearchParamsRR()
-  const navigation = useNavigation()
-
-  const naturalValue = React.useMemo(
-    () => (navigation.location?.search ? new URLSearchParams(navigation.location.search) : searchParamsRaw).get(name),
-    [name, searchParamsRaw, navigation.location]
-  )
-  const value = React.useMemo(
-    () => getQueryParam<S>(naturalValue, codec),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [naturalValue]
-  )
-
-  const setValue = React.useCallback(
-    (val: S | ((prevState: S) => S), navigateOpts?: QueryStateNavigateOptions) => {
-      const { replace = true, preventScrollReset = false, shallow = false } = { ...codec, ...navigateOpts }
-
-      function updateParams(params: URLSearchParams) {
-        const newParams = new URLSearchParams(params)
-        const oldValue = getQueryParam(newParams.get(name), codec)
-        const newValue = typeof val === 'function' ? (val as (prevState: S) => S)(oldValue) : val
-        setQueryParam({ searchParams: newParams, name, value: newValue, codec })
-        return newParams
-      }
-      if (shallow) {
-        const params = new URLSearchParams(window.location.search)
-        const newUrl = [
-          [window.location.pathname, updateParams(params).toString()].filter(Boolean).join('?'),
-          window.location.hash
-        ].join('#')
-        if (replace) {
-          window.history.replaceState(null, '', newUrl)
-        } else {
-          window.history.pushState(null, '', newUrl)
-        }
-      } else {
-        setSearchParams(updateParams, { replace, preventScrollReset })
-      }
-    },
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [name, setSearchParams]
-  )
-
-  return [value, setValue] as const
-}
-
-/**
- * React hook that decodes *all* search params defined by a loader into a typed object.
- * Read-only — for read/write access to individual params, use {@link useState}.
- *
- * Reads from the pending navigation location when one is in flight.
- */
-function useSearchParams<L extends QueryStateLoader>(
-  loader: L
-): [
-  state: ExtractTypeFromLoader<L>,
-  setState: (
-    val: ExtractTypeFromLoader<L> | ((prevState: ExtractTypeFromLoader<L>) => ExtractTypeFromLoader<L>),
-    navigateOpts?: QueryStateNavigateOptions
-  ) => void
-] {
-  const location = useLocation()
-  const { location: pendingLocation } = useNavigation()
-
-  const search = pendingLocation?.search ?? location.search
-
-  const getLoader = useStableAccessor(loader)
-  const [_, setSearchParamsRaw] = useSearchParamsRR()
-
-  const setSearchParam = React.useCallback(
-    (
-      val: ExtractTypeFromLoader<L> | ((prevState: ExtractTypeFromLoader<L>) => ExtractTypeFromLoader<L>),
-      navigateOpts?: QueryStateNavigateOptions
-    ) => {
-      const loader = getLoader()
-      const { replace = true, preventScrollReset = false, shallow = false } = { ...navigateOpts }
-
-      function updateParams(params: URLSearchParams) {
-        const newParams = new URLSearchParams(params)
-        const oldValue = queryParamsToObject(new URLSearchParams(search), loader)
-        const newValue = typeof val === 'function' ? val(oldValue) : val
-        Object.entries(loader).forEach(([name, codec]) =>
-          setQueryParam({ searchParams: newParams, name, value: newValue[name], codec })
-        )
-        return newParams
-      }
-      if (shallow) {
-        const params = new URLSearchParams(window.location.search)
-        const newUrl = [
-          [window.location.pathname, updateParams(params).toString()].filter(Boolean).join('?'),
-          window.location.hash
-        ].join('#')
-        if (replace) {
-          window.history.replaceState(null, '', newUrl)
-        } else {
-          window.history.pushState(null, '', newUrl)
-        }
-      } else {
-        setSearchParamsRaw(updateParams, { replace, preventScrollReset })
-      }
-    },
-    [getLoader, setSearchParamsRaw]
-  )
-
-  const searchParams = React.useMemo(() => queryParamsToObject(new URLSearchParams(search), loader), [search, loader])
-
-  return [searchParams, setSearchParam]
-}
-
-/**
- * Identity function that provides type inference for a loader definition.
- *
- * @example
- * ```ts
- * const loader = SearchParams.createLoader({
- *   page: SearchParams.codecs.int.withDefaultValue(0),
- *   sort: SearchParams.codecs.enum(['name', 'date'] as const)
- * })
- * ```
- */
-function createLoader<L extends QueryStateLoader>(loader: L): L {
-  return loader
-}
-
-export const SearchParams = {
-  codecs,
-  serializeCodec,
-  deserializeCodec,
-  serializeLoader,
-  deserializeLoader,
-  createLoader,
-  getSearchParamsState,
-  useState,
-  useSearchParams
-}
-
-export declare namespace SearchParams {
-  export {
-    Codec,
-    CodecDef,
-    QueryStateLoader,
-    ExtractTypeFromLoader,
-    QueryStateNavigateOptions,
-    SerializedCodec,
-    SerializedLoader
-  }
-}