@cfasim-ui/shared 0.3.6 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/shared",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "description": "Shared utilities for cfasim-ui",
   "license": "Apache-2.0",
@@ -17,5 +17,8 @@
   ],
   "exports": {
     ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
   }
 }

package/src/index.ts

@@ -14,3 +14,11 @@ export type {
   ModelOutputsWire,
 } from "./ModelOutput.js";
 export { modelOutputToCSV } from "./csv.js";
+export {
+  useUrlParams,
+  serialize,
+  deserialize,
+  paramsToQuery,
+  queryToParams,
+} from "./useUrlParams.js";
+export type { UrlParamsOptions } from "./useUrlParams.js";

package/src/useUrlParams.test.ts

@@ -0,0 +1,361 @@
+import { describe, it, expect, vi } from "vitest";
+import { defineComponent, h, ref, reactive, nextTick } from "vue";
+import { mount } from "@vue/test-utils";
+import {
+  serialize,
+  deserialize,
+  paramsToQuery,
+  queryToParams,
+  useUrlParams,
+  type UrlParamsRouter,
+  type UrlParamsRoute,
+} from "./useUrlParams.js";
+
+describe("serialize", () => {
+  it("stringifies numbers and booleans", () => {
+    expect(serialize(42)).toBe("42");
+    expect(serialize(true)).toBe("true");
+    expect(serialize(false)).toBe("false");
+  });
+
+  it("joins arrays with commas", () => {
+    expect(serialize([1, 2, 3])).toBe("1,2,3");
+    expect(serialize(["a", "b"])).toBe("a,b");
+  });
+});
+
+describe("deserialize", () => {
+  it("coerces based on default type", () => {
+    expect(deserialize("true", false)).toBe(true);
+    expect(deserialize("false", true)).toBe(false);
+    expect(deserialize("3.14", 0)).toBe(3.14);
+    expect(deserialize("hello", "x")).toBe("hello");
+  });
+
+  it("falls back to default on NaN", () => {
+    expect(deserialize("not-a-number", 7)).toBe(7);
+  });
+
+  it("parses comma-separated arrays of numbers", () => {
+    expect(deserialize("1,2,3", [0])).toEqual([1, 2, 3]);
+  });
+
+  it("keeps non-numeric array entries as strings", () => {
+    expect(deserialize("a,b,c", [""])).toEqual(["a", "b", "c"]);
+  });
+});
+
+describe("paramsToQuery", () => {
+  it("omits values that match defaults", () => {
+    const defaults = { a: 1, b: 2, c: 3 };
+    expect(paramsToQuery({ a: 1, b: 2, c: 3 }, defaults)).toEqual({});
+  });
+
+  it("includes only changed values", () => {
+    const defaults = { a: 1, b: 2, c: 3 };
+    expect(paramsToQuery({ a: 1, b: 5, c: 3 }, defaults)).toEqual({ b: "5" });
+  });
+
+  it("serializes arrays", () => {
+    const defaults = { k: [1, 2] };
+    expect(paramsToQuery({ k: [3, 4] }, defaults)).toEqual({ k: "3,4" });
+  });
+
+  it("handles booleans", () => {
+    const defaults = { on: false };
+    expect(paramsToQuery({ on: true }, defaults)).toEqual({ on: "true" });
+    expect(paramsToQuery({ on: false }, defaults)).toEqual({});
+  });
+});
+
+describe("queryToParams", () => {
+  it("returns empty when query has no overlap", () => {
+    const defaults = { a: 1 };
+    expect(queryToParams({ unrelated: "x" }, defaults)).toEqual({});
+  });
+
+  it("ignores unknown keys", () => {
+    const defaults = { a: 1 };
+    expect(queryToParams({ a: "2", b: "3" }, defaults)).toEqual({ a: 2 });
+  });
+
+  it("ignores non-string query values", () => {
+    const defaults = { a: 1 };
+    expect(queryToParams({ a: ["2", "3"] }, defaults)).toEqual({});
+  });
+
+  it("coerces types from defaults", () => {
+    const defaults = { n: 0, b: false, s: "", arr: [0] };
+    expect(
+      queryToParams({ n: "5", b: "true", s: "hi", arr: "1,2" }, defaults),
+    ).toEqual({ n: 5, b: true, s: "hi", arr: [1, 2] });
+  });
+});
+
+function makeRouterStub(initialQuery: Record<string, unknown> = {}) {
+  const route = reactive<UrlParamsRoute>({ query: { ...initialQuery } });
+  const replace = vi.fn(({ query }: { query: Record<string, string> }) => {
+    route.query = { ...query };
+  });
+  const router: UrlParamsRouter = { replace };
+  return { router, route, replace };
+}
+
+function mountWith<R>(factory: () => R) {
+  let api!: R;
+  const wrapper = mount(
+    defineComponent({
+      setup() {
+        api = factory();
+        return () => h("div");
+      },
+    }),
+  );
+  return { wrapper, api: api as R };
+}
+
+describe("useUrlParams (composable)", () => {
+  it("hydrates a reactive params object from initial query", async () => {
+    const { router, route } = makeRouterStub({ a: "5" });
+    const params = reactive({ a: 1, b: 2 });
+    mountWith(() =>
+      useUrlParams(
+        params,
+        { a: 1, b: 2 },
+        {
+          router,
+          route,
+          debounceMs: 0,
+        },
+      ),
+    );
+    await nextTick();
+    expect(params.a).toBe(5);
+    expect(params.b).toBe(2);
+  });
+
+  it("hydrates a ref params object from initial query", async () => {
+    const { router, route } = makeRouterStub({ a: "9" });
+    const params = ref({ a: 1, b: 2 });
+    mountWith(() =>
+      useUrlParams(
+        params,
+        { a: 1, b: 2 },
+        {
+          router,
+          route,
+          debounceMs: 0,
+        },
+      ),
+    );
+    await nextTick();
+    expect(params.value).toEqual({ a: 9, b: 2 });
+  });
+
+  it("writes changed params back to the URL", async () => {
+    const { router, route, replace } = makeRouterStub();
+    const params = reactive({ a: 1, b: 2 });
+    mountWith(() =>
+      useUrlParams(
+        params,
+        { a: 1, b: 2 },
+        {
+          router,
+          route,
+          debounceMs: 0,
+        },
+      ),
+    );
+    await nextTick();
+    params.a = 7;
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 5));
+    expect(replace).toHaveBeenCalled();
+    expect(route.query).toEqual({ a: "7" });
+  });
+
+  describe("include / ignore", () => {
+    it("include limits the keys that sync to the URL", async () => {
+      const { router, route } = makeRouterStub();
+      const params = reactive({ a: 1, b: 2, c: 3 });
+      mountWith(() =>
+        useUrlParams(
+          params,
+          { a: 1, b: 2, c: 3 },
+          { router, route, debounceMs: 0, include: ["a"] },
+        ),
+      );
+      await nextTick();
+      params.a = 5;
+      params.b = 99;
+      await nextTick();
+      await new Promise((r) => setTimeout(r, 5));
+      expect(route.query).toEqual({ a: "5" });
+    });
+
+    it("ignore skips listed keys but syncs the rest", async () => {
+      const { router, route } = makeRouterStub();
+      const params = reactive({ a: 1, b: 2, c: 3 });
+      mountWith(() =>
+        useUrlParams(
+          params,
+          { a: 1, b: 2, c: 3 },
+          { router, route, debounceMs: 0, ignore: ["c"] },
+        ),
+      );
+      await nextTick();
+      params.a = 5;
+      params.c = 99;
+      await nextTick();
+      await new Promise((r) => setTimeout(r, 5));
+      expect(route.query).toEqual({ a: "5" });
+    });
+
+    it("include takes precedence over ignore", async () => {
+      const { router, route } = makeRouterStub();
+      const params = reactive({ a: 1, b: 2, c: 3 });
+      mountWith(() =>
+        useUrlParams(
+          params,
+          { a: 1, b: 2, c: 3 },
+          {
+            router,
+            route,
+            debounceMs: 0,
+            include: ["a"],
+            ignore: ["a"],
+          },
+        ),
+      );
+      await nextTick();
+      params.a = 5;
+      params.b = 99;
+      await nextTick();
+      await new Promise((r) => setTimeout(r, 5));
+      expect(route.query).toEqual({ a: "5" });
+    });
+
+    it("does not hydrate keys outside the include set", async () => {
+      const { router, route } = makeRouterStub({ a: "5", b: "99" });
+      const params = reactive({ a: 1, b: 2 });
+      mountWith(() =>
+        useUrlParams(
+          params,
+          { a: 1, b: 2 },
+          { router, route, debounceMs: 0, include: ["a"] },
+        ),
+      );
+      await nextTick();
+      expect(params.a).toBe(5);
+      expect(params.b).toBe(2);
+    });
+
+    it("preserves ignored keys on a reactive params object across hydrate", async () => {
+      const { router, route } = makeRouterStub({ a: "5" });
+      const params = reactive({ a: 1, ephemeral: "keep-me" });
+      mountWith(() =>
+        useUrlParams(
+          params,
+          { a: 1, ephemeral: "default" },
+          { router, route, debounceMs: 0, ignore: ["ephemeral"] },
+        ),
+      );
+      await nextTick();
+      expect(params.a).toBe(5);
+      expect(params.ephemeral).toBe("keep-me");
+    });
+  });
+
+  describe("reset", () => {
+    it("resets params to defaults and clears URL by default", async () => {
+      const { router, route, replace } = makeRouterStub({ a: "5" });
+      const params = reactive({ a: 1, b: 2 });
+      const { api } = mountWith(() =>
+        useUrlParams(
+          params,
+          { a: 1, b: 2 },
+          {
+            router,
+            route,
+            debounceMs: 0,
+          },
+        ),
+      );
+      await nextTick();
+      expect(params.a).toBe(5);
+      api.reset();
+      await nextTick();
+      expect(params).toEqual({ a: 1, b: 2 });
+      expect(replace).toHaveBeenLastCalledWith({ query: {} });
+    });
+
+    it("does not touch the URL when clearUrl: false", async () => {
+      const { router, route, replace } = makeRouterStub({ a: "5" });
+      const params = reactive({ a: 1, b: 2 });
+      const { api } = mountWith(() =>
+        useUrlParams(
+          params,
+          { a: 1, b: 2 },
+          {
+            router,
+            route,
+            debounceMs: 0,
+          },
+        ),
+      );
+      await nextTick();
+      replace.mockClear();
+      api.reset({ clearUrl: false });
+      await nextTick();
+      expect(params).toEqual({ a: 1, b: 2 });
+      expect(replace).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("defaults variants", () => {
+    it("accepts a Ref as defaults", async () => {
+      const { router, route } = makeRouterStub({ a: "7" });
+      const params = reactive({ a: 0 });
+      const defaults = ref({ a: 0 });
+      mountWith(() =>
+        useUrlParams(params, defaults, { router, route, debounceMs: 0 }),
+      );
+      await nextTick();
+      expect(params.a).toBe(7);
+    });
+
+    it("accepts a getter and hydrates lazily once defaults are ready", async () => {
+      const { router, route } = makeRouterStub({ a: "7" });
+      const params = reactive({ a: 0 });
+      let ready: { a: number } | undefined = undefined;
+      const { api } = mountWith(() =>
+        useUrlParams(params, () => ready, {
+          router,
+          route,
+          debounceMs: 0,
+        }),
+      );
+      await nextTick();
+      // getter returned undefined on mount — no hydration yet
+      expect(params.a).toBe(0);
+      ready = { a: 0 };
+      expect(api.hydrate()).toBe(true);
+      expect(params.a).toBe(7);
+    });
+
+    it("hydrate() returns false while defaults are unavailable", async () => {
+      const { router, route } = makeRouterStub({ a: "7" });
+      const params = reactive({ a: 0 });
+      const { api } = mountWith(() =>
+        useUrlParams(params, () => undefined as { a: number } | undefined, {
+          router,
+          route,
+          debounceMs: 0,
+        }),
+      );
+      await nextTick();
+      expect(api.hydrate()).toBe(false);
+      expect(params.a).toBe(0);
+    });
+  });
+});

package/src/useUrlParams.ts

@@ -0,0 +1,296 @@
+import { isRef, onMounted, onUnmounted, toRaw, watch, type Ref } from "vue";
+
+/**
+ * Minimal shape of vue-router's `Router` that `useUrlParams` needs.
+ * Typed structurally so `@cfasim-ui/shared` does not depend on vue-router.
+ */
+export interface UrlParamsRouter {
+  replace(to: { query: Record<string, string> }): unknown;
+}
+
+/**
+ * Minimal shape of vue-router's `RouteLocationNormalized` that
+ * `useUrlParams` reads to hydrate initial state. `query` is typed as
+ * `Record<string, unknown>` because vue-router yields `string | string[] |
+ * null`; `deserialize` silently ignores non-string entries.
+ */
+export interface UrlParamsRoute {
+  query: Record<string, unknown>;
+}
+
+/**
+ * Defaults can be:
+ *  - a plain object (sync, always available),
+ *  - a Ref<T> (reactive; useful when defaults are computed),
+ *  - a getter `() => T | undefined` (useful for async loads; return
+ *    `undefined` until defaults are ready, then call `hydrate()` from
+ *    the consumer).
+ */
+export type DefaultsInput<T> = T | Ref<T> | (() => T | undefined);
+
+export type UrlParamsOptions<T> = {
+  debounceMs?: number;
+  /**
+   * Optional vue-router integration. Pass `useRouter()` and `useRoute()` from
+   * the calling component. When provided, URL reads/writes go through the
+   * router so `route.query` stays reactive. When omitted, the composable
+   * uses the browser History API directly.
+   */
+  router?: UrlParamsRouter;
+  route?: UrlParamsRoute;
+  /**
+   * Only sync these keys. Useful when `defaults` contains labels, flags, or
+   * other fields the user never edits.
+   */
+  include?: (keyof T)[];
+  /**
+   * Sync all keys except these. Ignored if `include` is provided.
+   */
+  ignore?: (keyof T)[];
+};
+
+export type ResetOptions = {
+  /** Whether to clear the URL query in addition to resetting params. Default: true. */
+  clearUrl?: boolean;
+};
+
+export function serialize(value: unknown): string {
+  if (Array.isArray(value)) return value.join(",");
+  return String(value);
+}
+
+export function deserialize(raw: string, defaultValue: unknown): unknown {
+  if (typeof defaultValue === "boolean") return raw === "true";
+  if (typeof defaultValue === "number") {
+    const n = Number(raw);
+    return Number.isNaN(n) ? defaultValue : n;
+  }
+  if (Array.isArray(defaultValue)) {
+    return raw.split(",").map((s) => {
+      const n = Number(s);
+      return Number.isNaN(n) ? s : n;
+    });
+  }
+  return raw;
+}
+
+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]);
+    if (serialized !== defaultSerialized) {
+      query[key] = serialized;
+    }
+  }
+  return query;
+}
+
+export function queryToParams<T extends object>(
+  query: Record<string, unknown>,
+  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]);
+  }
+  return result as Partial<T>;
+}
+
+function readLocationQuery(): Record<string, string> {
+  const out: Record<string, string> = {};
+  const search = new URLSearchParams(window.location.search);
+  for (const [k, v] of search) out[k] = v;
+  return out;
+}
+
+function writeLocationQuery(query: Record<string, string>) {
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) params.set(k, v);
+  const qs = params.toString();
+  const url =
+    window.location.pathname + (qs ? `?${qs}` : "") + window.location.hash;
+  // Preserve whatever state object the current history entry holds (vue-router
+  // stores its own bookkeeping there) so we don't clobber it.
+  window.history.replaceState(window.history.state, "", url);
+}
+
+function toGetter<T>(input: DefaultsInput<T>): () => T | undefined {
+  if (typeof input === "function") return input as () => T | undefined;
+  if (isRef(input)) return () => (input as Ref<T>).value;
+  return () => input as T;
+}
+
+function filterKeys<T extends object>(
+  obj: T,
+  include?: (keyof T)[],
+  ignore?: (keyof T)[],
+): 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];
+    }
+  }
+  return out as T;
+}
+
+/**
+ * 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.
+ *
+ * For async defaults (e.g. loaded from WASM/network), pass a getter or ref
+ * that returns `undefined` until ready, and call `hydrate()` once defaults
+ * are available. The composable also attempts hydration on mount; the
+ * first successful attempt "locks in" writes going forward.
+ *
+ * Browser back/forward and external `route.query` changes are picked up
+ * automatically (via `popstate` or a route watcher).
+ *
+ * By default, uses the browser History API directly. Consumers using
+ * vue-router can pass `{ router: useRouter(), route: useRoute() }` so that
+ * `route.query` stays reactive.
+ */
+export function useUrlParams<T extends object>(
+  params: T | Ref<T>,
+  defaults: DefaultsInput<T>,
+  options: UrlParamsOptions<T> = {},
+) {
+  const debounceMs = options.debounceMs ?? 300;
+  const { router, route, include, ignore } = options;
+  const getDefaults = toGetter<T>(defaults);
+  const scopedDefaults = (): T | undefined => {
+    const d = getDefaults();
+    return d === undefined ? undefined : filterKeys(d, include, ignore);
+  };
+
+  function readQuery(): Record<string, unknown> {
+    if (route) return route.query;
+    return readLocationQuery();
+  }
+
+  function writeQuery(query: Record<string, string>) {
+    if (router) {
+      router.replace({ query });
+    } else {
+      writeLocationQuery(query);
+    }
+  }
+
+  function read(): T {
+    return isRef(params) ? params.value : params;
+  }
+
+  function apply(overrides: Partial<T>, 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;
+    if (isRef(params)) {
+      params.value = merged;
+    } else {
+      Object.assign(params, merged);
+    }
+  }
+
+  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);
+    hydrated = true;
+    return true;
+  }
+
+  function syncFromUrl() {
+    if (!hydrated) {
+      hydrate();
+      return;
+    }
+    const d = scopedDefaults();
+    if (d === undefined) return;
+    const overrides = queryToParams(readQuery(), d);
+    apply(overrides, d);
+  }
+
+  onMounted(() => {
+    hydrate();
+  });
+
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  watch(
+    () => read(),
+    () => {
+      if (!hydrated) return;
+      if (debounceTimer) clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(() => {
+        const d = scopedDefaults();
+        if (d === undefined) return;
+        writeQuery(paramsToQuery(read(), d));
+      }, debounceMs);
+    },
+    { deep: true },
+  );
+
+  // React to external query changes (back/forward, programmatic nav).
+  let stopRouteWatch: (() => void) | null = null;
+  function onPopState() {
+    syncFromUrl();
+  }
+  onMounted(() => {
+    if (route) {
+      stopRouteWatch = watch(
+        () => route.query,
+        () => syncFromUrl(),
+        { deep: true },
+      );
+    } else {
+      window.addEventListener("popstate", onPopState);
+    }
+  });
+  onUnmounted(() => {
+    if (stopRouteWatch) stopRouteWatch();
+    else window.removeEventListener("popstate", onPopState);
+  });
+
+  function reset(opts: ResetOptions = {}) {
+    const { clearUrl = true } = opts;
+    const d = scopedDefaults();
+    if (d === undefined) return;
+    apply({}, d);
+    if (clearUrl) {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      writeQuery({});
+    }
+  }
+
+  onUnmounted(() => {
+    if (debounceTimer) clearTimeout(debounceTimer);
+  });
+
+  return { reset, hydrate };
+}