@cfasim-ui/docs 0.3.11

package/shared/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 };
+}

package/theme/all.js

@@ -0,0 +1,5 @@
+import "@cfasim-ui/components/style.css";
+import "@cfasim-ui/charts/style.css";
+import "./base.css";
+import "./theme.css";
+import "./utilities.css";

package/theme/base.css

@@ -0,0 +1,176 @@
+@layer base {
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  /* Root & Color Scheme */
+
+  :root {
+    color-scheme: light dark;
+    -webkit-text-size-adjust: 100%;
+    scroll-behavior: smooth;
+    /* Add this if you have scrollable content */
+    /* scrollbar-gutter: stable; */
+    --text-wrap-heading: balance;
+    --text-wrap-body: balance;
+  }
+
+  /* Accessibility */
+
+  :target {
+    scroll-margin-block: 5ex;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    html {
+      scroll-behavior: auto;
+    }
+  }
+
+  /* Typography */
+
+  body {
+    min-block-size: 100svb;
+    line-height: 1.5;
+    margin: 0;
+    hanging-punctuation: first allow-end last;
+    overflow-wrap: break-word;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    line-height: 1.1;
+  }
+
+  p,
+  li,
+  figcaption {
+    text-wrap: pretty;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6,
+  figcaption {
+    text-wrap: balance;
+  }
+
+  a:not([class]) {
+    color: currentColor;
+    text-decoration-skip-ink: auto;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 0.15em;
+    text-decoration-color: color-mix(in srgb, currentColor, transparent 67%);
+
+    &:hover {
+      text-decoration-color: currentColor;
+    }
+  }
+
+  pre,
+  code {
+    tab-size: 2;
+  }
+
+  /* Lists */
+
+  ul[role="list"],
+  ol[role="list"] {
+    list-style: none;
+  }
+
+  /* Forms */
+
+  input,
+  button,
+  textarea,
+  select {
+    font: inherit;
+    /* https://adactio.com/journal/21027 */
+    hanging-punctuation: none;
+  }
+
+  textarea:not([rows]) {
+    min-height: 10em;
+  }
+
+  /* Media */
+
+  img,
+  video,
+  picture,
+  canvas,
+  svg {
+    max-width: 100%;
+    display: block;
+    height: auto;
+  }
+}
+
+/* Base styles (applied after reset) */
+
+:root {
+  font-family: var(--font-family);
+  line-height: var(--line-height-normal);
+  color: var(--color-text);
+  background-color: var(--color-bg-0);
+}
+
+body {
+  font-size: var(--font-size-md);
+}
+
+:root,
+body {
+  overflow: hidden;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: var(--font-family-heading);
+  font-weight: var(--font-weight-heading);
+  line-height: var(--line-height-tight);
+  margin-bottom: var(--space-3);
+}
+
+h1 {
+  font-size: var(--font-size-2xl);
+}
+
+h2 {
+  font-size: var(--font-size-xl);
+}
+
+p {
+  margin-bottom: var(--space-2);
+}
+
+section {
+  margin-bottom: var(--space-6);
+}
+
+code {
+  font-family: var(--font-family-mono);
+}
+
+a {
+  color: var(--color-link);
+  text-decoration: none;
+}
+
+a:hover {
+  text-decoration: underline;
+}

package/theme/cfasim.css

@@ -0,0 +1,3 @@
+@import "./base.css";
+@import "./theme.css";
+@import "./utilities.css";

package/theme/theme.css

@@ -0,0 +1,113 @@
+:root {
+  color-scheme: light dark;
+}
+
+:root.light {
+  color-scheme: light;
+}
+
+:root.dark {
+  color-scheme: dark;
+}
+
+:root {
+  /* Primary */
+  --color-primary: light-dark(#0066ff, #4d94ff);
+  --color-primary-hover: light-dark(#0052cc, #66a3ff);
+  --color-primary-active: light-dark(#0047b3, #3385ff);
+  --color-text-on-primary: #ffffff;
+
+  /* Backgrounds */
+  --color-bg-0: light-dark(#ffffff, #1a1a1a);
+  --color-bg-1: light-dark(#f8f9fa, #2d2d2d);
+  --color-bg-2: light-dark(#e9ecef, #3d3d3d);
+  --color-bg-3: light-dark(#dee2e6, #4d4d4d);
+
+  /* Text */
+  --color-text: light-dark(#212529, #f8f9fa);
+  --color-text-secondary: light-dark(#495057, #adb5bd);
+  --color-text-tertiary: light-dark(#adb5bd, #6c757d);
+  --color-text-disabled: light-dark(#ced4da, #495057);
+
+  /* Links */
+  --color-link: var(--color-primary);
+
+  /* Borders */
+  --color-border: light-dark(#dee2e6, #3a3f44);
+  --color-border-header: light-dark(#c4c9ce, #555d64);
+  --color-border-hover: light-dark(#adb5bd, #555d64);
+  --color-border-focus: var(--color-primary);
+
+  /* Status */
+  --color-error: light-dark(#dc3545, #ff6b6b);
+  --color-success: light-dark(#28a745, #40c057);
+  --color-warning: light-dark(#ffc107, #ffd43b);
+
+  /* Typography */
+  --font-family:
+    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial,
+    sans-serif;
+  --font-family-heading: var(--font-family);
+  --font-weight-heading: bold;
+  --font-family-mono: "Consolas", "Monaco", "Courier New", monospace;
+  --font-size-xs: 0.75rem;
+  --font-size-sm: 0.875rem;
+  --font-size-md: 1rem;
+  --font-size-lg: 1.25rem;
+  --font-size-xl: 1.5rem;
+  --font-size-2xl: 2rem;
+  --line-height-tight: 1.25;
+  --line-height-normal: 1.5;
+
+  /* Spacing (rem — consistent regardless of font-size context) */
+  --space-1: 0.25rem;
+  --space-2: 0.5rem;
+  --space-3: 0.75rem;
+  --space-4: 1rem;
+  --space-6: 1.5rem;
+  --space-8: 2rem;
+  --space-12: 3rem;
+  --space-20: 5rem;
+
+  /* Radius */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-full: 9999px;
+
+  /* Shadows */
+  --shadow-sm: light-dark(
+    0 1px 2px 0 rgba(0, 0, 0, 0.05),
+    0 1px 2px 0 rgba(0, 0, 0, 0.3)
+  );
+  --shadow-md: light-dark(
+    0 4px 6px -1px rgba(0, 0, 0, 0.1),
+    0 4px 6px -1px rgba(0, 0, 0, 0.4)
+  );
+  --shadow-focus: light-dark(
+    0 0 0 3px rgba(0, 102, 255, 0.2),
+    0 0 0 3px rgba(77, 148, 255, 0.3)
+  );
+
+  /* Transitions */
+  --transition-fast: 150ms ease-in-out;
+  --transition-normal: 250ms ease-in-out;
+
+  /* Box variants */
+  --color-box-info-bg: light-dark(#e6eefa, #1a2a45);
+  --color-box-info-text: light-dark(#1a3a6b, #8fb8f0);
+  --color-box-success-bg: light-dark(#ecfdf5, #1a3d2a);
+  --color-box-success-text: light-dark(#065f46, #a8f0c8);
+  --color-box-warning-bg: light-dark(#fef6e7, #3d3210);
+  --color-box-warning-text: light-dark(#7a5d0e, #f5d882);
+  --color-box-error-bg: light-dark(#fef2f2, #3d1a1a);
+  --color-box-error-text: light-dark(#991b1b, #f0a8a8);
+  --color-baseline-bg: light-dark(#fef3e6, #3d2a10);
+  --color-baseline-text: light-dark(#7a3d00, #f5c882);
+
+  /* Component sizes (em — scales with font-size context) */
+  --input-height: 2.5em;
+  --button-height: 2.5em;
+  --sidebar-width: 400px;
+  --toggle-size: 2.5rem;
+}

package/theme/themes/cdc.css

@@ -0,0 +1,22 @@
+[data-theme="cdc"] {
+  --font-family:
+    "Nunito", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica,
+    Arial, sans-serif;
+  --font-family-heading:
+    "Poppins", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica,
+    Arial, sans-serif;
+  --font-weight-heading: 200;
+  --font-size-md: 1.125rem;
+  --font-size-2xl: 2.625rem;
+  --color-bg-0: light-dark(#ffffff, #0f1e21);
+  --color-bg-1: light-dark(#f4fbfc, #162a2e);
+  --color-bg-2: light-dark(#e9f5f8, #1e373c);
+  --color-bg-3: light-dark(#dff2f6, #264349);
+  --color-primary: light-dark(#007a99, #33b5d6);
+  --color-primary-hover: light-dark(#006680, #4dc4e0);
+  --color-primary-active: light-dark(#005c73, #1fa8cc);
+  --color-link: light-dark(#005ea2, #73b3e7);
+  --color-border: light-dark(#c5e4ec, #264349);
+  --color-border-hover: light-dark(#a0d4e0, #3a5d64);
+  --color-border-focus: var(--color-primary);
+}