@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/table-persist.test.ts

@@ -0,0 +1,258 @@
+import { createRoot } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import type { ConfigStorage } from './config-store'
+import {
+  createTablePersist,
+  type TablePersist,
+  type TablePersistOptions,
+} from './table-persist'
+import type { UrlStateAdapter } from './url-state'
+
+/** A Map-backed storage that records what was written. */
+function memoryStorage(): ConfigStorage & { map: Map<string, string> } {
+  const map = new Map<string, string>()
+  return {
+    map,
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => void map.set(key, value),
+    removeItem: (key) => void map.delete(key),
+    keys: () => [...map.keys()],
+  }
+}
+
+function adapter(
+  search = '',
+): UrlStateAdapter & { last: () => URLSearchParams } {
+  let last = new URLSearchParams(search)
+  return {
+    search: () => search,
+    replace: vi.fn((params: URLSearchParams) => {
+      last = params
+    }),
+    last: () => last,
+  }
+}
+
+async function flushMicrotasks(): Promise<void> {
+  await Promise.resolve()
+  await Promise.resolve()
+}
+
+function setup(
+  options: Omit<TablePersistOptions, 'id'> & { id?: string } = {},
+) {
+  let dispose!: () => void
+  let persist!: TablePersist
+  createRoot((d) => {
+    dispose = d
+    persist = createTablePersist({ id: 'orders', ...options })
+  })
+  return { persist, dispose }
+}
+
+const layout = {
+  visibility: { date: true, amount: false },
+  order: ['date', 'amount'],
+  sizing: { date: 140 },
+  pinning: { left: ['date'], right: [] },
+}
+
+describe('createTablePersist', () => {
+  it('round-trips the whole state through the document', () => {
+    const storage = memoryStorage()
+    const { persist: first, dispose } = setup({ storage })
+
+    first.commit({
+      columns: layout,
+      sorting: [{ id: 'date', desc: true }],
+      columnFilters: [{ id: 'region', value: 'EMEA' }],
+      density: 'compact',
+      pageSize: 25,
+    })
+
+    const { persist: second } = setup({ storage })
+    expect(second.hydrate(['date', 'amount'])).toEqual({
+      columns: layout,
+      sorting: [{ id: 'date', desc: true }],
+      columnFilters: [{ id: 'region', value: 'EMEA' }],
+      density: 'compact',
+      pageSize: 25,
+      dropped: [],
+    })
+
+    // The document is a versioned envelope with the table-view type.
+    const raw = JSON.parse(
+      storage.map.get('newui.tables:orders') ?? '',
+    ) as Record<string, unknown>
+    expect(raw['v']).toBe(1)
+    expect(raw['type']).toBe('table-view')
+    dispose()
+  })
+
+  it('commits keep fields the table did not mention', () => {
+    const storage = memoryStorage()
+    const { persist, dispose } = setup({ storage })
+    persist.commit({ density: 'compact', pageSize: 25 })
+    persist.commit({ sorting: [{ id: 'amount', desc: false }] })
+
+    const { persist: reloaded } = setup({ storage })
+    const state = reloaded.hydrate([])
+    expect(state.density).toBe('compact')
+    expect(state.pageSize).toBe(25)
+    expect(state.sorting).toEqual([{ id: 'amount', desc: false }])
+    dispose()
+  })
+
+  it('drops persisted columns that no longer exist', () => {
+    const storage = memoryStorage()
+    const { persist, dispose } = setup({ storage })
+    persist.commit({
+      columns: {
+        visibility: { date: true, ghost: false, amount: true },
+        order: ['date', 'ghost', 'amount'],
+        sizing: { ghost: 100 },
+        pinning: { left: ['ghost'], right: [] },
+      },
+    })
+
+    const { persist: reloaded } = setup({ storage })
+    const state = reloaded.hydrate(['date', 'amount', 'new'])
+    expect(state.dropped).toEqual(['ghost'])
+    expect(state.columns).toEqual({
+      visibility: { date: true, amount: true },
+      order: ['date', 'amount', 'new'],
+      sizing: {},
+      pinning: { left: [], right: [] },
+    })
+    dispose()
+  })
+
+  it('migrates a document that predates the versioned shape', () => {
+    const storage = memoryStorage()
+    // What an older release wrote: visible ids in `columns`, `sort` not `sorting`.
+    storage.setItem(
+      'newui.tables:legacy',
+      JSON.stringify({
+        v: 1,
+        name: 'legacy',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+        doc: {
+          columns: ['date', 'amount'],
+          sort: [{ id: 'date', desc: true }],
+        },
+      }),
+    )
+    const { persist, dispose } = setup({ storage, id: 'legacy' })
+    const state = persist.hydrate(['date', 'amount'])
+    expect(state.sorting).toEqual([{ id: 'date', desc: true }])
+    expect(state.columns).toEqual({
+      visibility: { date: true, amount: true },
+      order: ['date', 'amount'],
+      sizing: {},
+      pinning: { left: [], right: [] },
+    })
+    dispose()
+  })
+
+  it('writes the view half to the URL and reads it back', async () => {
+    const bridge = adapter()
+    const storage = memoryStorage()
+    const { persist, dispose } = setup({
+      storage,
+      url: { adapter: bridge },
+    })
+
+    persist.commit({
+      sorting: [{ id: 'amount', desc: true }],
+      columnFilters: [{ id: 'region', value: 'EMEA' }],
+      density: 'compact',
+      pageSize: 50,
+      columns: layout,
+    })
+    await flushMicrotasks()
+
+    const params = bridge.last()
+    expect(JSON.parse(params.get('orders.sort') ?? '')).toEqual([
+      { id: 'amount', desc: true },
+    ])
+    expect(params.get('orders.pageSize')).toBe('50')
+    expect(params.get('orders.density')).toBe('compact')
+    // The column layout is a preference, not a link — never in the URL.
+    expect([...params.keys()].some((key) => key.includes('columns'))).toBe(
+      false,
+    )
+
+    const deep = adapter(new URLSearchParams(params).toString())
+    const { persist: reloaded } = setup({ storage, url: { adapter: deep } })
+    const state = reloaded.hydrate(['date', 'amount'])
+    expect(state.sorting).toEqual([{ id: 'amount', desc: true }])
+    expect(state.columnFilters).toEqual([{ id: 'region', value: 'EMEA' }])
+    expect(state.density).toBe('compact')
+    expect(state.pageSize).toBe(50)
+    expect(state.columns).toEqual(layout)
+    dispose()
+  })
+
+  it('lets the URL win over the document', () => {
+    const storage = memoryStorage()
+    const { persist, dispose } = setup({ storage })
+    persist.commit({ sorting: [{ id: 'date', desc: true }], pageSize: 10 })
+
+    const deep = adapter(
+      '?orders.sort=%5B%7B%22id%22%3A%22amount%22%2C%22desc%22%3Afalse%7D%5D',
+    )
+    const { persist: reloaded } = setup({ storage, url: { adapter: deep } })
+    expect(reloaded.hydrate([]).sorting).toEqual([
+      { id: 'amount', desc: false },
+    ])
+    dispose()
+  })
+
+  it('reports a storage backend that rejects the write', () => {
+    const rejecting: ConfigStorage = {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error('quota')
+      },
+      removeItem: () => {},
+      keys: () => [],
+    }
+    const onPersistError = vi.fn()
+    const { persist, dispose } = setup({ storage: rejecting, onPersistError })
+    persist.commit({ pageSize: 25 })
+    expect(onPersistError).toHaveBeenCalledTimes(1)
+    expect(onPersistError.mock.calls[0]?.[0]?.message).toContain('orders')
+    dispose()
+  })
+
+  it('reports a stored document that no longer parses', () => {
+    const storage = memoryStorage()
+    storage.setItem('newui.tables:orders', '{not json')
+    const onPersistError = vi.fn()
+    const { persist, dispose } = setup({ storage, onPersistError })
+    expect(persist.hydrate(['date'])).toEqual({ dropped: [] })
+    expect(onPersistError).toHaveBeenCalledTimes(1)
+    dispose()
+  })
+
+  it('forgets everything on reset', async () => {
+    const bridge = adapter()
+    const storage = memoryStorage()
+    const { persist, dispose } = setup({ storage, url: { adapter: bridge } })
+    persist.commit({
+      columns: layout,
+      sorting: [{ id: 'date', desc: true }],
+      pageSize: 25,
+    })
+    await flushMicrotasks()
+
+    persist.reset()
+    await flushMicrotasks()
+
+    expect(storage.map.has('newui.tables:orders')).toBe(false)
+    expect([...bridge.last()].length).toBe(0)
+    const { persist: reloaded } = setup({ storage })
+    expect(reloaded.hydrate(['date', 'amount'])).toEqual({ dropped: [] })
+    dispose()
+  })
+})

package/src/table-persist.ts

@@ -0,0 +1,371 @@
+import type { Accessor } from 'solid-js'
+import { type ConfigStorage, createConfigStore } from './config-store'
+import { defaultsFor, withPruning } from './url-serialize'
+import {
+  createUrlState,
+  type UrlStateAdapter,
+  type UrlStateValue,
+} from './url-state'
+
+/**
+ * What a table remembers, and where it lives.
+ *
+ * `createTablePersist` splits table state by *who owns the question*:
+ *
+ * - The **URL half** — sorting, column filters, density, page size — is what
+ *   makes a link reproducible, so it serializes through `createUrlState`
+ *   behind the app's router adapter, pruned to only what differs from the
+ *   default.
+ * - The **storage half** — the column layout (visibility, order, sizing,
+ *   pinning) — is a personal preference that should survive a shared link,
+ *   so it lives in a versioned `createConfigStore` document.
+ *
+ * The document carries the whole state, so a returning user gets their sort
+ * back even when the URL says nothing; the URL wins when it does. A persisted
+ * column that no longer exists in the table is dropped on read, not hidden
+ * forever.
+ */
+
+/** Envelope-free payload version: a document without `v` predates this shape. */
+const TABLE_PERSIST_SCHEMA_VERSION = 1
+
+/** The `type` discriminator on the stored envelope. */
+const TABLE_PERSIST_DOC_TYPE = 'table-view'
+
+/** How the table's columns are laid out. Mirrors the TanStack column state. */
+export interface TableColumnLayout {
+  /** Sparse visibility map — an absent column is visible. */
+  visibility: Record<string, boolean>
+  /** Left-to-right column ids. */
+  order: string[]
+  /** Pixel widths, keyed by column id. */
+  sizing: Record<string, number>
+  /** Pinned column ids, in pinned order. */
+  pinning: { left: string[]; right: string[] }
+}
+
+/** One sort entry. */
+export type TableSorting = { id: string; desc: boolean }
+
+/** One active column filter. */
+export type TableColumnFilter = { id: string; value: UrlStateValue }
+
+/** Row density, matching the table organism's axis. */
+export type TableDensity = 'comfortable' | 'compact'
+
+/** Everything `createTablePersist` remembers. */
+export interface TablePersistState {
+  columns?: TableColumnLayout
+  sorting?: TableSorting[]
+  columnFilters?: TableColumnFilter[]
+  density?: TableDensity
+  pageSize?: number
+}
+
+/** The stored document: the state plus its payload version. */
+export interface TablePersistDoc extends TablePersistState {
+  v?: number
+}
+
+/** Options for {@link createTablePersist}. */
+export interface TablePersistOptions {
+  /** Stable id — namespaces the URL keys and the document name. */
+  id: string
+  /** Router bridge for the URL half. Absent means the URL is never touched. */
+  url?: { adapter?: UrlStateAdapter }
+  /** Backend for the document. Defaults to `localStorage`. */
+  storage?: ConfigStorage
+  /**
+   * Called when a persist fails — a storage backend that rejects the write,
+   * or a document that no longer parses. The table keeps working either way;
+   * the app decides whether to say so.
+   */
+  onPersistError?: (error: Error) => void
+}
+
+/** The result of {@link createTablePersist}. */
+export interface TablePersist {
+  /**
+   * Read the persisted state for a table with these column ids. A persisted
+   * column that is gone from the table is dropped from the layout and named
+   * in `dropped`; new columns are appended to the order, visible.
+   */
+  hydrate(columns: readonly string[]): TablePersistState & { dropped: string[] }
+  /** Write the table's current state — both halves, whatever is present. */
+  commit(state: Partial<TablePersistState>): void
+  /** Forget everything persisted for this id. */
+  reset(): void
+}
+
+/** The storage namespace every persisted table shares. */
+const STORE_KEY = 'newui.tables'
+
+function isLayout(value: unknown): value is TableColumnLayout {
+  if (value === null || typeof value !== 'object') return false
+  const layout = value as Partial<TableColumnLayout>
+  return (
+    typeof layout.visibility === 'object' &&
+    layout.visibility !== null &&
+    Array.isArray(layout.order) &&
+    typeof layout.sizing === 'object' &&
+    layout.sizing !== null &&
+    typeof layout.pinning === 'object' &&
+    layout.pinning !== null &&
+    Array.isArray(layout.pinning.left) &&
+    Array.isArray(layout.pinning.right)
+  )
+}
+
+function isSorting(value: unknown): value is TableSorting[] {
+  return (
+    Array.isArray(value) &&
+    value.every(
+      (entry) =>
+        entry !== null &&
+        typeof entry === 'object' &&
+        typeof (entry as TableSorting).id === 'string' &&
+        typeof (entry as TableSorting).desc === 'boolean',
+    )
+  )
+}
+
+function isColumnFilters(value: unknown): value is TableColumnFilter[] {
+  return (
+    Array.isArray(value) &&
+    value.every(
+      (entry) =>
+        entry !== null &&
+        typeof entry === 'object' &&
+        typeof (entry as TableColumnFilter).id === 'string',
+    )
+  )
+}
+
+/**
+ * Upgrade anything a store hands back to the current shape. A payload with
+ * no `v` predates the versioned document: it wrote `columns` as the visible
+ * ids and `sort` instead of `sorting`. Fields that fail validation are
+ * dropped rather than trusted — a half-readable document is still better
+ * than none.
+ */
+function normalizeDoc(payload: unknown): TablePersistState {
+  if (payload === null || typeof payload !== 'object') return {}
+  const doc = payload as Record<string, unknown>
+  const legacy = doc['v'] === undefined
+  const state: TablePersistState = {}
+
+  const sorting = legacy ? doc['sort'] : doc['sorting']
+  if (isSorting(sorting)) state.sorting = sorting
+
+  const filters = doc['columnFilters']
+  if (isColumnFilters(filters)) state.columnFilters = filters
+
+  const density = doc['density']
+  if (density === 'comfortable' || density === 'compact')
+    state.density = density
+
+  const pageSize = doc['pageSize']
+  if (
+    typeof pageSize === 'number' &&
+    Number.isInteger(pageSize) &&
+    pageSize > 0
+  ) {
+    state.pageSize = pageSize
+  }
+
+  const columns = doc['columns']
+  if (legacy && Array.isArray(columns)) {
+    // v0: the array of visible ids was the whole layout.
+    const ids = columns.filter((id): id is string => typeof id === 'string')
+    state.columns = {
+      visibility: Object.fromEntries(ids.map((id) => [id, true])),
+      order: ids,
+      sizing: {},
+      pinning: { left: [], right: [] },
+    }
+  } else if (isLayout(columns)) {
+    state.columns = columns
+  }
+  return state
+}
+
+/**
+ * Create the persistence binding for one table. Call it once per table id,
+ * `hydrate` with the current column ids before first paint, and `commit`
+ * with the table's state whenever it changes.
+ */
+export function createTablePersist(options: TablePersistOptions): TablePersist {
+  const { id } = options
+  const reportError = (error: Error): void => {
+    options.onPersistError?.(error)
+  }
+
+  const urlKeys: Record<string, UrlStateValue> = {
+    [`${id}.sort`]: [],
+    [`${id}.filters`]: [],
+    [`${id}.density`]: '',
+    [`${id}.pageSize`]: 0,
+  }
+  const url = createUrlState(urlKeys, {
+    ...(options.url?.adapter
+      ? {
+          adapter: withPruning(options.url.adapter, defaultsFor(urlKeys)),
+        }
+      : {}),
+  })
+
+  // Reading `createUrlState`'s record by key runs into the
+  // `noUncheckedIndexedAccess` wall; this keeps every accessor honest.
+  const read = (key: string): UrlStateValue => {
+    const accessor = (
+      url as unknown as Record<string, Accessor<UrlStateValue> | undefined>
+    )[key]
+    return accessor ? accessor() : ''
+  }
+
+  const store = createConfigStore({
+    key: STORE_KEY,
+    ...(options.storage ? { storage: options.storage } : {}),
+    migrate: (doc) => normalizeDoc(doc),
+  })
+
+  function readDoc(): TablePersistState {
+    const loaded = store.load<TablePersistDoc>(id)
+    if (loaded) return normalizeDoc(loaded.doc)
+    // Absent is silence; present-but-unreadable is a story the app hears once.
+    if (options.storage?.getItem(`${STORE_KEY}:${id}`) !== null) {
+      reportError(
+        new Error(
+          `createTablePersist: the stored document for "${id}" is unreadable and was treated as absent.`,
+        ),
+      )
+    }
+    return {}
+  }
+
+  function readUrl(): Partial<TablePersistState> {
+    const state: Partial<TablePersistState> = {}
+    const sort = read(`${id}.sort`)
+    if (isSorting(sort) && sort.length > 0) state.sorting = sort
+    const filters = read(`${id}.filters`)
+    if (isColumnFilters(filters) && filters.length > 0)
+      state.columnFilters = filters
+    const density = read(`${id}.density`)
+    if (density === 'comfortable' || density === 'compact')
+      state.density = density
+    const pageSize = read(`${id}.pageSize`)
+    if (
+      typeof pageSize === 'number' &&
+      Number.isInteger(pageSize) &&
+      pageSize > 0
+    ) {
+      state.pageSize = pageSize
+    }
+    return state
+  }
+
+  /**
+   * Fit a persisted layout to the table that exists now: gone columns are
+   * dropped, new ones appended visible, everything else in order.
+   */
+  function fitColumns(
+    persisted: TableColumnLayout,
+    current: readonly string[],
+    dropped: Set<string>,
+  ): TableColumnLayout {
+    const keep = new Set(current)
+    const order: string[] = []
+    for (const column of persisted.order) {
+      if (typeof column !== 'string') continue
+      if (keep.has(column)) {
+        if (!order.includes(column)) order.push(column)
+      } else {
+        dropped.add(column)
+      }
+    }
+    for (const column of current) {
+      if (!order.includes(column)) order.push(column)
+    }
+
+    const visibility: Record<string, boolean> = {}
+    for (const [column, visible] of Object.entries(persisted.visibility)) {
+      if (!keep.has(column)) dropped.add(column)
+      else if (typeof visible === 'boolean') visibility[column] = visible
+    }
+    const sizing: Record<string, number> = {}
+    for (const [column, width] of Object.entries(persisted.sizing)) {
+      if (!keep.has(column)) dropped.add(column)
+      else if (typeof width === 'number' && width > 0) sizing[column] = width
+    }
+    const pin = (side: readonly unknown[]): string[] =>
+      side.filter((column): column is string => {
+        if (typeof column !== 'string') return false
+        if (keep.has(column)) return true
+        dropped.add(column)
+        return false
+      })
+
+    return {
+      visibility,
+      order,
+      sizing,
+      pinning: {
+        left: pin(persisted.pinning.left),
+        right: pin(persisted.pinning.right),
+      },
+    }
+  }
+
+  return {
+    hydrate(columns: readonly string[]) {
+      const persisted = readDoc()
+      const state: TablePersistState & { dropped: string[] } = {
+        ...persisted,
+        ...readUrl(),
+        dropped: [],
+      }
+      if (persisted.columns) {
+        const dropped = new Set(state.dropped)
+        state.columns = fitColumns(persisted.columns, columns, dropped)
+        state.dropped = [...dropped]
+      }
+      return state
+    },
+
+    commit(state: Partial<TablePersistState>) {
+      if (state.sorting) url.set(`${id}.sort`, state.sorting)
+      if (state.columnFilters) url.set(`${id}.filters`, state.columnFilters)
+      if (state.density) url.set(`${id}.density`, state.density)
+      if (state.pageSize) url.set(`${id}.pageSize`, state.pageSize)
+
+      const current = readDoc()
+      const next: TablePersistDoc = {
+        ...current,
+        ...state,
+        v: TABLE_PERSIST_SCHEMA_VERSION,
+      }
+      try {
+        if (!store.save(id, next, { type: TABLE_PERSIST_DOC_TYPE })) {
+          reportError(
+            new Error(
+              `createTablePersist: the storage backend rejected the write for "${id}" (quota or disabled storage). The table state is not persisted.`,
+            ),
+          )
+        }
+      } catch (error) {
+        reportError(
+          error instanceof Error
+            ? error
+            : new Error(`createTablePersist: persisting "${id}" failed.`),
+        )
+      }
+    },
+
+    reset() {
+      store.remove(id)
+      for (const key of Object.keys(urlKeys)) {
+        url.set(key, undefined)
+      }
+    },
+  }
+}

package/src/undo.test.ts

@@ -0,0 +1,24 @@
+import { createRoot } from 'solid-js'
+import { describe, expect, it } from 'vitest'
+import { createUndo } from './undo'
+
+describe('undo', () => {
+  it('captures, restores once, then reports nothing left', () => {
+    createRoot((dispose) => {
+      const undo = createUndo<number[]>()
+      expect(undo.snapshot()).toBeUndefined()
+      expect(undo.undo(() => {})).toBe(false)
+
+      undo.capture([1, 2])
+      const restored: number[][] = []
+      expect(undo.undo((value) => restored.push(value))).toBe(true)
+      expect(restored).toEqual([[1, 2]])
+      expect(undo.snapshot()).toBeUndefined()
+
+      undo.capture([3])
+      undo.clear()
+      expect(undo.snapshot()).toBeUndefined()
+      dispose()
+    })
+  })
+})

package/src/undo.ts

@@ -0,0 +1,37 @@
+import { type Accessor, createSignal } from 'solid-js'
+
+/**
+ * One-step undo.
+ *
+ * A snapshot signal, captured before a mutation, restored once. The page keeps
+ * owning its data and its notice copy; this owns the signal.
+ */
+export interface Undo<T> {
+  /** The captured value, or `undefined` when there is nothing to undo. */
+  snapshot: Accessor<T | undefined>
+  /** Remember `value` as the state an undo returns to. */
+  capture: (value: T) => void
+  /**
+   * Hand the snapshot back to `restore` and clear it. Returns whether a
+   * snapshot existed, so the caller can word its notice either way.
+   */
+  undo: (restore: (value: T) => void) => boolean
+  /** Drop the snapshot without restoring. */
+  clear: () => void
+}
+
+export function createUndo<T>(): Undo<T> {
+  const [snapshot, setSnapshot] = createSignal<T | undefined>(undefined)
+  return {
+    snapshot,
+    capture: (value) => setSnapshot(() => value),
+    undo: (restore) => {
+      const previous = snapshot()
+      if (previous === undefined) return false
+      restore(previous)
+      setSnapshot(undefined)
+      return true
+    },
+    clear: () => setSnapshot(undefined),
+  }
+}