@cfasim-ui/docs 0.4.11 → 0.4.13

package/shared/useUrlParams.ts

@@ -28,6 +28,50 @@ export interface UrlParamsRoute {
  */
 export type DefaultsInput<T> = T | Ref<T> | (() => T | undefined);
 
+/**
+ * A path into the params object. Either a top-level key (autocompleted from
+ * `T`) or a dotted path to a nested leaf (`"nested.foo"`). Matches the leaf
+ * exactly or any descendant when used as `include`/`ignore`.
+ */
+export type ParamPath<T> = keyof T | (string & {});
+
+/**
+ * Custom serializer/deserializer pair for a single path. Lets the consumer
+ * round-trip a value through one URL key as an opaque string instead of
+ * letting `useUrlParams` flatten through it. Use for tagged unions,
+ * polymorphic objects, or anything else whose shape can change at runtime —
+ * the default leaf-flattening can only enumerate fields present in
+ * `defaults`, so variants that aren't the default variant lose their
+ * fields.
+ */
+export type ParamCodec = {
+  serialize: (value: unknown) => string;
+  deserialize: (raw: string) => unknown;
+};
+
+/**
+ * Map of dotted path → codec. A path with a codec is treated as a single
+ * atomic leaf: its whole subtree round-trips through one URL key, and any
+ * descendant URL keys are ignored. Top-level keys (`"infectionRate"`) and
+ * nested paths (`"model.infectionRate"`) both work; segments in the path
+ * use `.` as the separator, matching the same convention as
+ * `include`/`ignore`.
+ */
+export type ParamCodecs = Record<string, ParamCodec>;
+
+/**
+ * Convenience codec that uses `JSON.stringify` / `JSON.parse`. Suitable
+ * for tagged unions and small object/array values. Note that comparison
+ * during URL writes is string-equality on the stringified form, so two
+ * objects with the same fields in different key orders will look distinct;
+ * provide a custom codec with a normalized stringifier if you need
+ * order-insensitive comparison.
+ */
+export const jsonCodec: ParamCodec = {
+  serialize: (value) => JSON.stringify(value),
+  deserialize: (raw) => JSON.parse(raw),
+};
+
 export type UrlParamsOptions<T> = {
   debounceMs?: number;
   /**
@@ -39,14 +83,23 @@ export type UrlParamsOptions<T> = {
   router?: UrlParamsRouter;
   route?: UrlParamsRoute;
   /**
-   * Only sync these keys. Useful when `defaults` contains labels, flags, or
-   * other fields the user never edits.
+   * Only sync these paths. Accepts top-level keys or dotted paths to nested
+   * leaves; a parent path implicitly covers all of its descendants.
    */
-  include?: (keyof T)[];
+  include?: ParamPath<T>[];
   /**
-   * Sync all keys except these. Ignored if `include` is provided.
+   * Sync all paths except these. Same matching rules as `include`. Ignored
+   * if `include` is provided.
    */
-  ignore?: (keyof T)[];
+  ignore?: ParamPath<T>[];
+  /**
+   * Per-path codecs. A path listed here is round-tripped as one opaque
+   * string under that key (using the codec's `serialize`/`deserialize`)
+   * instead of being flattened. URL keys nested inside a codec path are
+   * ignored, so a leftover `foo.bar=1` from an earlier shape doesn't
+   * punch through the atomic value.
+   */
+  codecs?: ParamCodecs;
 };
 
 export type ResetOptions = {
@@ -74,16 +127,169 @@ export function deserialize(raw: string, defaultValue: unknown): unknown {
   return raw;
 }
 
+// A "container" is any non-null object — plain object or array. A "branch"
+// is a container we recurse into when flattening defaults: plain objects
+// always recurse; arrays only recurse when at least one element is itself a
+// plain object (so `[1, 2, 3]` stays a comma-joined leaf, while
+// `[{foo: 1}, {foo: 2}]` becomes `items.0.foo=…&items.1.foo=…`).
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isContainer(
+  value: unknown,
+): value is Record<string, unknown> | unknown[] {
+  return value !== null && typeof value === "object";
+}
+
+function isBranch(value: unknown): boolean {
+  if (isPlainObject(value)) return true;
+  // Recurse into arrays whose elements are themselves containers (plain
+  // objects or arrays), so array-of-arrays and array-of-objects map onto
+  // indexed dotted paths. Arrays of primitives stay as comma-joined leaves.
+  if (Array.isArray(value)) return value.some(isContainer);
+  return false;
+}
+
+function* flattenLeaves(
+  obj: Record<string, unknown> | unknown[],
+  prefix: string[] = [],
+  stopPaths?: Set<string>,
+): Generator<[string[], unknown]> {
+  const entries: Array<[string, unknown]> = Array.isArray(obj)
+    ? obj.map((v, i) => [String(i), v])
+    : Object.entries(obj);
+  for (const [k, v] of entries) {
+    const path = [...prefix, k];
+    // `stopPaths` (codec paths) halt recursion: the whole subtree at that
+    // path is yielded as a single leaf value so a codec can serialize it
+    // atomically.
+    if (isBranch(v) && !stopPaths?.has(path.join("."))) {
+      yield* flattenLeaves(
+        v as Record<string, unknown> | unknown[],
+        path,
+        stopPaths,
+      );
+    } else {
+      yield [path, v];
+    }
+  }
+}
+
+// True iff some proper-prefix ancestor of `segments` is a codec path. Used
+// to drop URL keys that would punch through a codec boundary (e.g. a stale
+// `infectionRate.value=0.5` left over from before infectionRate gained a
+// codec).
+function pathIsInsideAnyCodec(
+  segments: string[],
+  codecPaths: Set<string>,
+): boolean {
+  for (let i = 1; i < segments.length; i++) {
+    if (codecPaths.has(segments.slice(0, i).join("."))) return true;
+  }
+  return false;
+}
+
+function getAtSegments(obj: unknown, segments: string[]): unknown {
+  let cur: unknown = obj;
+  for (const p of segments) {
+    if (!isContainer(cur)) return undefined;
+    cur = (cur as Record<string, unknown>)[p];
+  }
+  return cur;
+}
+
+// Sets `value` at `segments` inside `obj`. When `defaults` is supplied,
+// missing intermediate slots match the defaults' shape (array vs object) at
+// the same path — so a URL like `items.0.foo=5` rebuilds an array, not an
+// object with numeric keys.
+function setAtSegments(
+  obj: Record<string, unknown> | unknown[],
+  segments: string[],
+  value: unknown,
+  defaults?: unknown,
+): void {
+  let cur: Record<string, unknown> | unknown[] = obj;
+  let defCur: unknown = defaults;
+  for (let i = 0; i < segments.length - 1; i++) {
+    const p = segments[i];
+    const defNext = isContainer(defCur)
+      ? (defCur as Record<string, unknown>)[p]
+      : undefined;
+    const slot = (cur as Record<string, unknown>)[p];
+    if (!isContainer(slot)) {
+      (cur as Record<string, unknown>)[p] = Array.isArray(defNext) ? [] : {};
+    }
+    cur = (cur as Record<string, unknown>)[p] as
+      | Record<string, unknown>
+      | unknown[];
+    defCur = defNext;
+  }
+  (cur as Record<string, unknown>)[segments[segments.length - 1]] = value;
+}
+
+// Encode/decode segment arrays to/from URL query keys. Each segment is
+// percent-encoded so a literal `.` inside a key name won't collide with the
+// nesting separator. `encodeURIComponent` leaves `.` alone, so we replace
+// it manually to `%2E`. The encoded key still passes cleanly through
+// `URLSearchParams` and vue-router.
+function encodeKey(segments: string[]): string {
+  return segments
+    .map((s) => encodeURIComponent(s).replace(/\./g, "%2E"))
+    .join(".");
+}
+
+function decodeKey(key: string): string[] {
+  return key.split(".").map(decodeURIComponent);
+}
+
+// Recursive merge used to layer defaults onto the cloned current params.
+// Descends into matching containers (objects and arrays) so sibling
+// branches survive. URL overrides bypass this and use `setAtSegments`
+// directly, since a comma-encoded leaf array must replace its slot
+// wholesale rather than merge element-wise with the default.
+function deepMerge(
+  target: Record<string, unknown> | unknown[],
+  source: Record<string, unknown> | unknown[],
+  stopPaths?: Set<string>,
+  prefix: string[] = [],
+): Record<string, unknown> | unknown[] {
+  for (const [k, v] of Object.entries(source)) {
+    const slot = (target as Record<string, unknown>)[k];
+    const path = stopPaths ? [...prefix, k] : prefix;
+    const atStop = stopPaths?.has(path.join("."));
+    if (!atStop && isContainer(v) && isContainer(slot)) {
+      deepMerge(slot, v, stopPaths, path);
+    } else {
+      // Codec paths are atomic: overwrite the target subtree with source's
+      // value instead of merging the two variants field-by-field (which
+      // would produce a malformed hybrid for tagged unions).
+      (target as Record<string, unknown>)[k] = v;
+    }
+  }
+  return target;
+}
+
 export function paramsToQuery<T extends object>(
   params: T,
   defaults: T,
+  codecs?: ParamCodecs,
 ): Record<string, string> {
   const query: Record<string, string> = {};
-  for (const key of Object.keys(defaults) as (keyof T & string)[]) {
-    const serialized = serialize(params[key]);
-    const defaultSerialized = serialize(defaults[key]);
+  const stopPaths = codecs ? new Set(Object.keys(codecs)) : undefined;
+  for (const [segments, defaultLeaf] of flattenLeaves(
+    defaults as Record<string, unknown>,
+    [],
+    stopPaths,
+  )) {
+    const paramLeaf = getAtSegments(params, segments);
+    if (paramLeaf === undefined) continue;
+    const codec = codecs?.[segments.join(".")];
+    const serializeFn = codec ? codec.serialize : serialize;
+    const serialized = serializeFn(paramLeaf);
+    const defaultSerialized = serializeFn(defaultLeaf);
     if (serialized !== defaultSerialized) {
-      query[key] = serialized;
+      query[encodeKey(segments)] = serialized;
     }
   }
   return query;
@@ -92,13 +298,30 @@ export function paramsToQuery<T extends object>(
 export function queryToParams<T extends object>(
   query: Record<string, unknown>,
   defaults: T,
+  codecs?: ParamCodecs,
 ): Partial<T> {
   const result: Record<string, unknown> = {};
-  const defaultsRecord = defaults as Record<string, unknown>;
+  const codecPaths = codecs ? new Set(Object.keys(codecs)) : undefined;
   for (const [key, raw] of Object.entries(query)) {
-    if (!(key in defaultsRecord)) continue;
     if (typeof raw !== "string") continue;
-    result[key] = deserialize(raw, defaultsRecord[key]);
+    const segments = decodeKey(key);
+    const pathStr = segments.join(".");
+    const codec = codecs?.[pathStr];
+    if (codec) {
+      try {
+        setAtSegments(result, segments, codec.deserialize(raw), defaults);
+      } catch {
+        // Malformed codec value — skip rather than corrupt the params.
+      }
+      continue;
+    }
+    // Drop descendants of a codec path; the codec owns the whole subtree.
+    if (codecPaths && pathIsInsideAnyCodec(segments, codecPaths)) continue;
+    const defaultLeaf = getAtSegments(defaults, segments);
+    // Drop unknown dotted keys: matches the flat behavior and keeps the
+    // params shape stable.
+    if (defaultLeaf === undefined) continue;
+    setAtSegments(result, segments, deserialize(raw, defaultLeaf), defaults);
   }
   return result as Partial<T>;
 }
@@ -127,22 +350,43 @@ function toGetter<T>(input: DefaultsInput<T>): () => T | undefined {
   return () => input as T;
 }
 
-function filterKeys<T extends object>(
+// `include`/`ignore` entries are dotted strings using `.` as a JS-side path
+// separator (one segment per key). A path is in scope iff it (or any
+// ancestor) matches an include entry, or it (and all its ancestors) avoid
+// every ignore entry. `include` wins when both are supplied.
+function segmentsStartWith(path: string[], prefix: string[]): boolean {
+  if (prefix.length > path.length) return false;
+  for (let i = 0; i < prefix.length; i++) {
+    if (path[i] !== prefix[i]) return false;
+  }
+  return true;
+}
+
+function pathInScope(
+  path: string[],
+  include?: string[][],
+  ignore?: string[][],
+): boolean {
+  if (include) return include.some((entry) => segmentsStartWith(path, entry));
+  if (ignore) return !ignore.some((entry) => segmentsStartWith(path, entry));
+  return true;
+}
+
+function filterDefaults<T extends object>(
   obj: T,
-  include?: (keyof T)[],
-  ignore?: (keyof T)[],
+  include?: string[][],
+  ignore?: string[][],
+  stopPaths?: Set<string>,
 ): T {
   if (!include && !ignore) return obj;
-  const src = obj as Record<string, unknown>;
   const out: Record<string, unknown> = {};
-  for (const k of Object.keys(src)) {
-    const key = k as keyof T;
-    if (include) {
-      if (include.includes(key)) out[k] = src[k];
-    } else if (ignore) {
-      if (!ignore.includes(key)) out[k] = src[k];
-    } else {
-      out[k] = src[k];
+  for (const [path, leaf] of flattenLeaves(
+    obj as Record<string, unknown>,
+    [],
+    stopPaths,
+  )) {
+    if (pathInScope(path, include, ignore)) {
+      setAtSegments(out, path, leaf, obj);
     }
   }
   return out as T;
@@ -151,7 +395,8 @@ function filterKeys<T extends object>(
 /**
  * Syncs a reactive params object with the URL query string. Only values
  * that differ from defaults appear in the URL. Accepts either a `ref()`
- * or a `reactive()` object.
+ * or a `reactive()` object. Nested objects are encoded as dotted keys
+ * (`nested.foo=5`); arrays of primitives remain comma-joined leaves.
  *
  * For async defaults (e.g. loaded from WASM/network), pass a getter or ref
  * that returns `undefined` until ready, and call `hydrate()` once defaults
@@ -171,11 +416,16 @@ export function useUrlParams<T extends object>(
   options: UrlParamsOptions<T> = {},
 ) {
   const debounceMs = options.debounceMs ?? 300;
-  const { router, route, include, ignore } = options;
+  const { router, route, include, ignore, codecs } = options;
+  const includeSegments = include?.map((e) => String(e).split("."));
+  const ignoreSegments = ignore?.map((e) => String(e).split("."));
+  const codecPaths = codecs ? new Set(Object.keys(codecs)) : undefined;
   const getDefaults = toGetter<T>(defaults);
   const scopedDefaults = (): T | undefined => {
     const d = getDefaults();
-    return d === undefined ? undefined : filterKeys(d, include, ignore);
+    return d === undefined
+      ? undefined
+      : filterDefaults(d, includeSegments, ignoreSegments, codecPaths);
   };
 
   function readQuery(): Record<string, unknown> {
@@ -195,18 +445,24 @@ export function useUrlParams<T extends object>(
     return isRef(params) ? params.value : params;
   }
 
-  function apply(overrides: Partial<T>, d: T) {
+  function apply(overrides: Array<[string[], unknown]>, d: T) {
     // Layer order (later wins): current params -> defaults -> URL overrides.
     // Starting from current preserves keys outside the sync scope (i.e.
     // those filtered out by `include`/`ignore`), which matters when `params`
-    // is a ref and the whole object gets replaced below. `toRaw` unwraps
-    // reactive proxies so `structuredClone` doesn't choke.
-    const current = toRaw(read());
-    const merged = {
-      ...structuredClone(current),
-      ...structuredClone(toRaw(d)),
-      ...overrides,
-    } as T;
+    // is a ref and the whole object gets replaced below. Defaults deep-merge
+    // so sibling branches survive; URL overrides are applied at leaf
+    // precision so a leaf array like `tags=1,2` replaces the whole leaf
+    // instead of merging element-wise with the default array.
+    const current = structuredClone(toRaw(read())) as Record<string, unknown>;
+    deepMerge(
+      current,
+      structuredClone(toRaw(d)) as Record<string, unknown>,
+      codecPaths,
+    );
+    for (const [segments, value] of overrides) {
+      setAtSegments(current, segments, value, d);
+    }
+    const merged = current as T;
     if (isRef(params)) {
       params.value = merged;
     } else {
@@ -214,13 +470,36 @@ export function useUrlParams<T extends object>(
     }
   }
 
+  function readOverrides(d: T): Array<[string[], unknown]> {
+    const out: Array<[string[], unknown]> = [];
+    for (const [key, raw] of Object.entries(readQuery())) {
+      if (typeof raw !== "string") continue;
+      const segments = decodeKey(key);
+      const pathStr = segments.join(".");
+      const codec = codecs?.[pathStr];
+      if (codec) {
+        try {
+          out.push([segments, codec.deserialize(raw)]);
+        } catch {
+          // skip malformed codec values
+        }
+        continue;
+      }
+      if (codecPaths && pathIsInsideAnyCodec(segments, codecPaths)) continue;
+      const defaultLeaf = getAtSegments(d, segments);
+      if (defaultLeaf === undefined) continue;
+      out.push([segments, deserialize(raw, defaultLeaf)]);
+    }
+    return out;
+  }
+
   let hydrated = false;
 
   function hydrate(): boolean {
     const d = scopedDefaults();
     if (d === undefined) return false;
-    const overrides = queryToParams(readQuery(), d);
-    if (Object.keys(overrides).length > 0) apply(overrides, d);
+    const overrides = readOverrides(d);
+    if (overrides.length > 0) apply(overrides, d);
     hydrated = true;
     return true;
   }
@@ -232,8 +511,7 @@ export function useUrlParams<T extends object>(
     }
     const d = scopedDefaults();
     if (d === undefined) return;
-    const overrides = queryToParams(readQuery(), d);
-    apply(overrides, d);
+    apply(readOverrides(d), d);
   }
 
   onMounted(() => {
@@ -250,7 +528,7 @@ export function useUrlParams<T extends object>(
       debounceTimer = setTimeout(() => {
         const d = scopedDefaults();
         if (d === undefined) return;
-        writeQuery(paramsToQuery(read(), d));
+        writeQuery(paramsToQuery(read(), d, codecs));
       }, debounceMs);
     },
     { deep: true },
@@ -281,7 +559,7 @@ export function useUrlParams<T extends object>(
     const { clearUrl = true } = opts;
     const d = scopedDefaults();
     if (d === undefined) return;
-    apply({}, d);
+    apply([], d);
     if (clearUrl) {
       if (debounceTimer) clearTimeout(debounceTimer);
       writeQuery({});