@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/url-serialize.ts

@@ -0,0 +1,93 @@
+/**
+ * The serialization half of URL state, shared by `createUrlState` and by the
+ * higher-level primitives that compose it (`createDashboardState`,
+ * `createTablePersist`).
+ *
+ * `encodeValue` is `createUrlState`'s encoding; a composing primitive needs to
+ * know what a key serializes to — to prune params that say nothing — so it
+ * lives here instead of being copied. The types live here for the same reason:
+ * `url-state.ts` re-exports them, so the public surface is unchanged.
+ */
+
+/** A value that serializes into a query parameter. */
+export type UrlStateValue =
+  | string
+  | number
+  | boolean
+  | readonly UrlStateValue[]
+  | { readonly [key: string]: UrlStateValue }
+
+/** The router side of {@link createUrlState}. */
+export interface UrlStateAdapter {
+  /**
+   * The current query string (`"?a=1"` or `"a=1"`). Read **once** on creation,
+   * so first paint renders from the URL and a shared link deep-links without
+   * a client redirect.
+   */
+  search(): string
+  /** Replace the query string. Must not push a history entry. */
+  replace(params: URLSearchParams): void
+}
+
+/** JSON with object keys in sorted order, so a round-trip is stable. */
+function stableStringify(value: unknown): string {
+  return JSON.stringify(value, (_key, part: unknown) => {
+    if (part !== null && typeof part === 'object' && !Array.isArray(part)) {
+      const record = part as Record<string, unknown>
+      const sorted: Record<string, unknown> = {}
+      for (const key of Object.keys(record).sort()) sorted[key] = record[key]
+      return sorted
+    }
+    return part
+  })
+}
+
+/** Encode one value for its query parameter. Primitives stay as-is. */
+export function encodeValue(value: UrlStateValue): string {
+  if (typeof value === 'string') return value
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value)
+  }
+  return stableStringify(value)
+}
+
+/**
+ * The params an initial record serializes to — what "default" means for a
+ * set of keys. A param that still carries its default value says nothing, so
+ * it should never reach a shared link.
+ */
+export function defaultsFor(
+  initial: Record<string, UrlStateValue>,
+): URLSearchParams {
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(initial)) {
+    params.set(key, encodeValue(value))
+  }
+  return params
+}
+
+/** Drop every param that still says what its default says. Mutates `params`. */
+export function pruneDefaults(
+  params: URLSearchParams,
+  defaults: URLSearchParams,
+): URLSearchParams {
+  for (const [key, value] of [...defaults]) {
+    if (params.get(key) === value) params.delete(key)
+  }
+  return params
+}
+
+/**
+ * An adapter wrapper that never writes a param back when it still holds its
+ * default. The composing primitive owns the keys; the pruning rule is the
+ * "link shares only what is not the default" contract, stated once.
+ */
+export function withPruning(
+  adapter: UrlStateAdapter,
+  defaults: URLSearchParams,
+): UrlStateAdapter {
+  return {
+    search: () => adapter.search(),
+    replace: (params) => adapter.replace(pruneDefaults(params, defaults)),
+  }
+}

package/src/url-state.test.ts

@@ -0,0 +1,183 @@
+import { createRoot } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  createUrlState,
+  type UrlState,
+  type UrlStateAdapter,
+  type UrlStateOptions,
+  type UrlStateValue,
+} from './url-state'
+
+function setup<T extends Record<string, UrlStateValue>>(
+  initial: T,
+  options?: UrlStateOptions,
+) {
+  let dispose!: () => void
+  let state!: UrlState<T>
+  createRoot((d) => {
+    dispose = d
+    state = createUrlState(initial, options)
+  })
+  return { state, dispose }
+}
+
+interface FakeAdapter extends UrlStateAdapter {
+  /** The params handed to the last `replace`. */
+  last(): URLSearchParams
+}
+
+function adapter(search = ''): FakeAdapter {
+  let last = new URLSearchParams(search)
+  const replace = vi.fn((params: URLSearchParams) => {
+    last = params
+  })
+  return {
+    search: () => search,
+    replace,
+    last: () => last,
+  }
+}
+
+/** Let queued microtasks (the per-tick `replace`) run. */
+async function flushMicrotasks(): Promise<void> {
+  await Promise.resolve()
+  await Promise.resolve()
+}
+
+describe('createUrlState', () => {
+  it('behaves as a plain signal without an adapter, touching no URL', async () => {
+    const before = window.location.search
+    const { state, dispose } = setup({ view: 'list' })
+    expect(state.view()).toBe('list')
+
+    state.set('view', 'board')
+    await flushMicrotasks()
+    expect(state.view()).toBe('board')
+    expect(window.location.search).toBe(before)
+    expect(state.params().get('view')).toBe('board')
+    dispose()
+  })
+
+  it('reads the URL once on mount, so first paint renders from the link', () => {
+    const url = adapter('n=42&tags=["x","y"]&broken=abc')
+    const { state, dispose } = setup(
+      { n: 1, tags: [] as string[], broken: 7 },
+      { adapter: url },
+    )
+    expect(state.n()).toBe(42)
+    expect(state.tags()).toEqual(['x', 'y'])
+    // An unparseable value is not a crash: the initial value wins.
+    expect(state.broken()).toBe(7)
+    dispose()
+  })
+
+  it('serializes primitives as-is and objects with stable key order', async () => {
+    const url = adapter()
+    const { state, dispose } = setup(
+      { page: 1, flag: false as boolean, range: { to: 30, from: 10 } },
+      { adapter: url },
+    )
+    state.set('page', 3)
+    state.set('flag', true)
+    state.set('range', { to: 99, from: 0 })
+    await flushMicrotasks()
+
+    expect(url.replace).toHaveBeenCalledTimes(1)
+    const params = url.last()
+    expect(params.get('page')).toBe('3')
+    expect(params.get('flag')).toBe('true')
+    expect(params.get('range')).toBe('{"from":0,"to":99}')
+
+    const roundTrip = setup(
+      { page: 1, flag: false as boolean, range: { to: 0, from: 0 } },
+      { adapter: adapter(params.toString()) },
+    )
+    expect(roundTrip.state.page()).toBe(3)
+    expect(roundTrip.state.flag()).toBe(true)
+    expect(roundTrip.state.range()).toEqual({ from: 0, to: 99 })
+    dispose()
+    roundTrip.dispose()
+  })
+
+  it('treats undefined as absent — removed, never an empty string', async () => {
+    const url = adapter('q=hello')
+    const { state, dispose } = setup({ q: 'hello' }, { adapter: url })
+    state.set('q', undefined)
+    await flushMicrotasks()
+
+    expect(url.last().has('q')).toBe(false)
+    expect(url.last().get('q')).toBeNull()
+    expect(state.q()).toBe('hello')
+    dispose()
+  })
+
+  it('coalesces several writes in one tick into a single replace', async () => {
+    const url = adapter()
+    const { state, dispose } = setup({ a: 1, b: 2 }, { adapter: url })
+    state.set('a', 10)
+    state.set('b', 20)
+    await flushMicrotasks()
+    expect(url.replace).toHaveBeenCalledTimes(1)
+    expect(url.last().get('a')).toBe('10')
+    expect(url.last().get('b')).toBe('20')
+
+    state.set('a', 11)
+    await flushMicrotasks()
+    expect(url.replace).toHaveBeenCalledTimes(2)
+    dispose()
+  })
+
+  it('debounces search-like keys, resetting the window on every keystroke', async () => {
+    vi.useFakeTimers()
+    try {
+      const url = adapter()
+      const { state, dispose } = setup(
+        { q: '', page: 1 },
+        { adapter: url, debounce: ['q'] },
+      )
+      state.set('q', 'a')
+      expect(url.replace).not.toHaveBeenCalled()
+      vi.advanceTimersByTime(200)
+      state.set('q', 'ab')
+      expect(url.replace).not.toHaveBeenCalled()
+      vi.advanceTimersByTime(200)
+      expect(url.replace).not.toHaveBeenCalled()
+      vi.advanceTimersByTime(100)
+      expect(url.replace).toHaveBeenCalledTimes(1)
+      expect(url.last().get('q')).toBe('ab')
+
+      // A non-debounced key still writes immediately.
+      state.set('page', 4)
+      await vi.advanceTimersByTimeAsync(0)
+      expect(url.last().get('page')).toBe('4')
+      dispose()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('honours a custom debounce window', async () => {
+    vi.useFakeTimers()
+    try {
+      const url = adapter()
+      const { state, dispose } = setup(
+        { q: '' },
+        { adapter: url, debounce: ['q'], debounceMs: 50 },
+      )
+      state.set('q', 'x')
+      vi.advanceTimersByTime(50)
+      expect(url.last().get('q')).toBe('x')
+      dispose()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('exposes params() as a snapshot that cannot corrupt the state', () => {
+    const { state, dispose } = setup({ view: 'list' })
+    const snapshot = state.params()
+    snapshot.set('view', 'tampered')
+    expect(state.params().get('view')).toBe('list')
+    dispose()
+  })
+})

package/src/url-state.ts

@@ -0,0 +1,168 @@
+import { type Accessor, createSignal, onCleanup, type Setter } from 'solid-js'
+import {
+  encodeValue,
+  type UrlStateAdapter,
+  type UrlStateValue,
+} from './url-serialize'
+
+export type { UrlStateAdapter, UrlStateValue } from './url-serialize'
+
+/**
+ * URL state, router-agnostic by contract.
+ *
+ * `createUrlState` owns the signals whose values serialize to
+ * `URLSearchParams`: what makes a page reproducible by link — filters, view,
+ * page index, sort, density, time range. The app supplies the adapter, so the
+ * kit never imports a router: Solid Start's `useNavigate`, TanStack Router or
+ * a `history.replaceState` shim all satisfy {@link UrlStateAdapter}. Without
+ * an adapter the primitive is a plain controllable signal — tests and SSR stay
+ * clean, and the URL is simply never written.
+ *
+ * Writes **replace** the query string, never push (the back button leaves the
+ * page, it does not walk a filter history), and concurrent writes coalesce
+ * into one `replace` per frame. Search-like keys can be debounced so typing
+ * does not spam the history.
+ */
+
+/** Options for {@link createUrlState}. */
+export interface UrlStateOptions {
+  /** The router bridge. Absent means no URL access at all — pure signals. */
+  adapter?: UrlStateAdapter
+  /** Keys written after a debounce instead of immediately (search-like keys). */
+  debounce?: readonly string[]
+  /** Debounce window in ms. Defaults to `300`. */
+  debounceMs?: number
+}
+
+/** The handle {@link createUrlState} returns: one accessor per key. */
+export type UrlState<T extends Record<string, UrlStateValue>> = {
+  [K in keyof T]: Accessor<T[K]>
+} & {
+  /** Write one key. `undefined` means absent — it is removed, never `""`. */
+  set<K extends keyof T>(key: K, value: T[K] | undefined): void
+  /** The params every key serializes to right now (for "copy link"). */
+  params(): URLSearchParams
+}
+
+const DEFAULT_DEBOUNCE_MS = 300
+
+/** Decode one raw param back, trusting the initial value's type. */
+function decode(raw: string, initial: UrlStateValue): UrlStateValue {
+  if (typeof initial === 'string') return raw
+  if (typeof initial === 'number') {
+    const value = Number(raw)
+    return Number.isFinite(value) ? value : initial
+  }
+  if (typeof initial === 'boolean') return raw === 'true'
+  try {
+    return JSON.parse(raw) as UrlStateValue
+  } catch {
+    return initial
+  }
+}
+
+/**
+ * Controllable signals serialized to `URLSearchParams`.
+ *
+ * `initial` is what the page renders when the URL says nothing about a key;
+ * the URL wins when it does. Keys are the app's, not the table's — `view.sort`
+ * rather than `sort` — so one URL can host several surfaces without collisions.
+ */
+export function createUrlState<T extends Record<string, UrlStateValue>>(
+  initial: T,
+  options: UrlStateOptions = {},
+): UrlState<T> {
+  const keys = Object.keys(initial) as (keyof T & string)[]
+  const params = new URLSearchParams()
+  for (const key of keys) {
+    params.set(key, encodeValue(initial[key] as UrlStateValue))
+  }
+
+  const signals = new Map<
+    string,
+    [Accessor<UrlStateValue>, Setter<UrlStateValue>]
+  >()
+  const state: Record<string, unknown> = {}
+  for (const key of keys) {
+    const [get, set] = createSignal<UrlStateValue>(
+      initial[key] as UrlStateValue,
+    )
+    // Storing the accessor reference, not reading it — `state.view` is the
+    // signal, so the reactivity rule sees no tracked read to miss.
+    // eslint-disable-next-line solid/reactivity
+    signals.set(key, [get, set])
+    state[key] = get
+  }
+
+  // Read-once on mount: the URL seeds the signals, then signals drive.
+  if (options.adapter) {
+    try {
+      const search = new URLSearchParams(options.adapter.search())
+      for (const key of keys) {
+        const raw = search.get(key)
+        if (raw === null) continue
+        const value = decode(raw, initial[key] as UrlStateValue)
+        params.set(key, encodeValue(value))
+        signals.get(key)?.[1](() => value)
+      }
+    } catch {
+      // An unreadable URL is "absent everywhere": keep the initial values.
+    }
+  }
+
+  const debounceKeys = new Set(options.debounce ?? [])
+  const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let scheduled = false
+  let dirty = false
+
+  const flush = () => {
+    scheduled = false
+    dirty = false
+    options.adapter?.replace(new URLSearchParams(params))
+  }
+
+  /** Replace-not-push, batched per tick: one `replace` per coalesced write. */
+  const schedule = () => {
+    dirty = true
+    if (!options.adapter || scheduled) return
+    scheduled = true
+    queueMicrotask(flush)
+  }
+
+  onCleanup(() => {
+    if (timer) clearTimeout(timer)
+  })
+
+  const setKey = (
+    key: keyof T & string,
+    value: UrlStateValue | undefined,
+  ): void => {
+    const entry = signals.get(key)
+    if (!entry) return
+    const [, set] = entry
+    if (value === undefined) {
+      params.delete(key)
+      set(() => initial[key] as UrlStateValue)
+    } else {
+      params.set(key, encodeValue(value))
+      set(() => value)
+    }
+    if (debounceKeys.has(key)) {
+      // A search-like key waits out the debounce window before its value
+      // reaches the URL, so typing does not spam the history.
+      if (timer) clearTimeout(timer)
+      dirty = true
+      timer = setTimeout(() => {
+        timer = null
+        if (dirty) flush()
+      }, debounceMs)
+    } else {
+      schedule()
+    }
+  }
+  state['set'] = setKey
+
+  state['params'] = () => new URLSearchParams(params)
+  return state as unknown as UrlState<T>
+}