@cfasim-ui/docs 0.4.10 → 0.4.12

package/shared/useUrlParams.ts

@@ -28,6 +28,13 @@ 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 & {});
+
 export type UrlParamsOptions<T> = {
   debounceMs?: number;
   /**
@@ -39,14 +46,15 @@ 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>[];
 };
 
 export type ResetOptions = {
@@ -74,16 +82,134 @@ 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[] = [],
+): 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];
+    if (isBranch(v)) {
+      yield* flattenLeaves(v as Record<string, unknown> | unknown[], path);
+    } else {
+      yield [path, v];
+    }
+  }
+}
+
+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[],
+): Record<string, unknown> | unknown[] {
+  for (const [k, v] of Object.entries(source)) {
+    const slot = (target as Record<string, unknown>)[k];
+    if (isContainer(v) && isContainer(slot)) {
+      deepMerge(slot, v);
+    } else {
+      (target as Record<string, unknown>)[k] = v;
+    }
+  }
+  return target;
+}
+
 export function paramsToQuery<T extends object>(
   params: T,
   defaults: T,
 ): 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]);
+  for (const [segments, defaultLeaf] of flattenLeaves(
+    defaults as Record<string, unknown>,
+  )) {
+    const paramLeaf = getAtSegments(params, segments);
+    if (paramLeaf === undefined) continue;
+    const serialized = serialize(paramLeaf);
+    const defaultSerialized = serialize(defaultLeaf);
     if (serialized !== defaultSerialized) {
-      query[key] = serialized;
+      query[encodeKey(segments)] = serialized;
     }
   }
   return query;
@@ -94,11 +220,14 @@ export function queryToParams<T extends object>(
   defaults: T,
 ): Partial<T> {
   const result: Record<string, unknown> = {};
-  const defaultsRecord = defaults as Record<string, unknown>;
   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 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 +256,38 @@ 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[][],
 ): 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>)) {
+    if (pathInScope(path, include, ignore)) {
+      setAtSegments(out, path, leaf, obj);
     }
   }
   return out as T;
@@ -151,7 +296,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
@@ -172,10 +318,14 @@ export function useUrlParams<T extends object>(
 ) {
   const debounceMs = options.debounceMs ?? 300;
   const { router, route, include, ignore } = options;
+  const includeSegments = include?.map((e) => String(e).split("."));
+  const ignoreSegments = ignore?.map((e) => String(e).split("."));
   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);
   };
 
   function readQuery(): Record<string, unknown> {
@@ -195,18 +345,20 @@ 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>);
+    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 +366,25 @@ 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 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 +396,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(() => {
@@ -281,7 +444,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({});