@talelk/newui-data 1.0.0 → 1.1.0

package/src/config-store.test.ts

@@ -0,0 +1,157 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  CONFIG_DOCUMENT_LIMIT,
+  type ConfigStorage,
+  createConfigStore,
+} from './config-store'
+
+/** 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()],
+  }
+}
+
+describe('createConfigStore', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-03-01T10:00:00Z'))
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('wraps saves in a versioned envelope and loads them back', () => {
+    const storage = memoryStorage()
+    const store = createConfigStore({ key: 'acme.views', storage })
+
+    expect(store.save('revenue', { columns: ['date', 'usd'] })).toBe(true)
+    const loaded = store.load<{ columns: string[] }>('revenue')
+    expect(loaded?.v).toBe(1)
+    expect(loaded?.name).toBe('revenue')
+    expect(loaded?.updatedAt).toBe('2026-03-01T10:00:00.000Z')
+    expect(loaded?.doc).toEqual({ columns: ['date', 'usd'] })
+
+    // The store namespaces its keys, so a sibling store cannot collide.
+    expect([...storage.map.keys()]).toEqual(['acme.views:revenue'])
+  })
+
+  it('carries the type discriminator through save and list', () => {
+    const store = createConfigStore({
+      key: 'acme',
+      storage: memoryStorage(),
+    })
+    store.save('week-only', { filters: [] }, { type: 'saved-view' })
+    store.save('layout', { widgets: [] }, { type: 'dashboard-config' })
+
+    const listed = store.list()
+    expect(listed).toHaveLength(2)
+    expect(listed.map((row) => row.type).sort()).toEqual([
+      'dashboard-config',
+      'saved-view',
+    ])
+  })
+
+  it('lists documents newest first and skips unreadable entries', () => {
+    const storage = memoryStorage()
+    const store = createConfigStore({ key: 'acme', storage })
+    store.save('old', { n: 1 })
+    vi.setSystemTime(new Date('2026-03-02T10:00:00Z'))
+    store.save('new', { n: 2 })
+    storage.map.set('acme:garbage', '{not json')
+
+    expect(store.list().map((row) => row.name)).toEqual(['new', 'old'])
+    expect(store.load('garbage')).toBeUndefined()
+  })
+
+  it('removes and renames, reporting whether the document existed', () => {
+    const storage = memoryStorage()
+    const store = createConfigStore({ key: 'acme', storage })
+    store.save('draft', { n: 1 })
+
+    expect(store.remove('draft')).toBe(true)
+    expect(store.remove('draft')).toBe(false)
+    expect(store.load('draft')).toBeUndefined()
+
+    store.save('draft', { n: 1 })
+    vi.setSystemTime(new Date('2026-03-03T10:00:00Z'))
+    expect(store.rename('draft', 'keeper')).toBe(true)
+    expect(store.rename('draft', 'ghost')).toBe(false)
+
+    const keeper = store.load<{ n: number }>('keeper')
+    expect(keeper?.name).toBe('keeper')
+    expect(keeper?.updatedAt).toBe('2026-03-03T10:00:00.000Z')
+    expect(keeper?.doc).toEqual({ n: 1 })
+    expect(storage.map.has('acme:draft')).toBe(false)
+  })
+
+  it('migrates older envelopes instead of reading them wrong', () => {
+    const storage = memoryStorage()
+    storage.map.set(
+      'acme:old',
+      JSON.stringify({ v: 0, name: 'old', updatedAt: 'x', doc: { a: 1 } }),
+    )
+
+    const migrated = createConfigStore({
+      key: 'acme',
+      storage,
+      migrate: (doc) => ({ ...(doc as object), migrated: true }),
+    })
+    const loaded = migrated.load<{ a: number; migrated: boolean }>('old')
+    expect(loaded?.v).toBe(1)
+    expect(loaded?.doc).toEqual({ a: 1, migrated: true })
+
+    // Without a migrate, a version mismatch is unreadable, not corrupted.
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const strict = createConfigStore({ key: 'acme', storage })
+    expect(strict.load('old')).toBeUndefined()
+    expect(warn).toHaveBeenCalled()
+  })
+
+  it('caps documents at 64KB with a loud dev warning', () => {
+    const storage = memoryStorage()
+    const store = createConfigStore({ key: 'acme', storage })
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const huge = 'x'.repeat(CONFIG_DOCUMENT_LIMIT + 1)
+    expect(store.save('huge', { data: huge })).toBe(false)
+    expect(storage.map.has('acme:huge')).toBe(false)
+    expect(warn).toHaveBeenCalledTimes(1)
+
+    // Just under the cap still saves.
+    expect(store.save('big', { data: 'y' })).toBe(true)
+    expect(store.load('big')).toBeDefined()
+  })
+
+  it('drops writes when the backend fails, warning once per failure site', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const failing: ConfigStorage = {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error('QuotaExceeded')
+      },
+      removeItem: () => {},
+      keys: () => [],
+    }
+    const store = createConfigStore({ key: 'acme', storage: failing })
+    expect(store.save('one', { n: 1 })).toBe(false)
+    expect(warn).toHaveBeenCalled()
+  })
+
+  it('falls back to memory under SSR, where localStorage is absent', () => {
+    vi.stubGlobal('localStorage', undefined)
+    try {
+      const store = createConfigStore({ key: 'acme' })
+      expect(store.save('page', { n: 1 })).toBe(true)
+      expect(store.load<{ n: number }>('page')?.doc.n).toBe(1)
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+})

package/src/config-store.ts

@@ -0,0 +1,295 @@
+/**
+ * Versioned documents for user-authored views.
+ *
+ * `createConfigStore` is one storage abstraction with two consumers: saved
+ * filters (the "saved view" side) and dashboard config (the widget-layout
+ * side). Both are documents in the same store, distinguished by a `type`
+ * discriminator in the envelope — never by separate stores.
+ *
+ * Documents are versioned envelopes so a future shape migrates per-store, not
+ * globally, and the envelope carries `updatedAt` so conflict resolution stays
+ * a later decision rather than a later accident. Storage is a seam: the
+ * default is `localStorage`, and a server-backed adapter (Frappe `/resource`
+ * or any REST) drops in without touching consumers.
+ */
+
+/** The current envelope shape. A breaking change bumps this and migrates. */
+export const CONFIG_SCHEMA_VERSION = 1
+
+/** The byte cap on one stored document — a widget grid that grows forever. */
+export const CONFIG_DOCUMENT_LIMIT = 64 * 1024
+
+/** One stored document, with its version and metadata around the payload. */
+export interface ConfigDocument<T = unknown> {
+  /** Envelope schema version; see {@link CONFIG_SCHEMA_VERSION}. */
+  v: number
+  name: string
+  /** What kind of document this is (`'saved-view'`, `'dashboard-config'`, …). */
+  type?: string
+  /** ISO timestamp of the last {@link ConfigStore.save}. */
+  updatedAt: string
+  /** The document's payload, owned by the consumer. */
+  doc: T
+}
+
+/** The row {@link ConfigStore.list} returns per stored document. */
+export interface ConfigSummary {
+  name: string
+  type?: string
+  updatedAt: string
+}
+
+/**
+ * The storage seam. Keys are globally unique; the store namespaces them with
+ * its `key` prefix, so `keys()` must enumerate every key the store may read.
+ */
+export interface ConfigStorage {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+  /** Every key the storage holds, for the store's namespace scan. */
+  keys(): string[]
+}
+
+/** Options for {@link createConfigStore}. */
+export interface ConfigStoreOptions {
+  /** Namespace prefix, so several stores share one storage. */
+  key: string
+  /** Backend. Defaults to `localStorage` (in-memory under SSR). */
+  storage?: ConfigStorage
+  /**
+   * Upgrade a document written against an older envelope version. Return the
+   * document in the current shape; return `undefined` to reject it. Without a
+   * `migrate`, a version mismatch is unreadable rather than silently wrong.
+   */
+  migrate?: (doc: unknown, from: number) => unknown
+}
+
+/** The document API {@link createConfigStore} returns. */
+export interface ConfigStore {
+  /** Every stored document, newest first. Unreadable entries are skipped. */
+  list(): ConfigSummary[]
+  /** Load one document through `migrate`; `undefined` when absent or stale. */
+  load<T>(name: string): ConfigDocument<T> | undefined
+  /** Store a document in a fresh envelope. False when over the 64KB cap. */
+  save<T>(name: string, doc: T, options?: { type?: string }): boolean
+  /** Delete one document. Returns whether it existed. */
+  remove(name: string): boolean
+  /** Move a document to a new name. False when the source is absent. */
+  rename(from: string, to: string): boolean
+}
+
+function defaultStorage(): ConfigStorage {
+  const memory = new Map<string, string>()
+  let backend: Storage | null = null
+  try {
+    backend = typeof localStorage === 'undefined' ? null : localStorage
+  } catch {
+    // A sandboxed or disabled `localStorage` throws on access, not on use.
+    backend = null
+  }
+  if (!backend) {
+    return {
+      getItem: (key) => memory.get(key) ?? null,
+      setItem: (key, value) => void memory.set(key, value),
+      removeItem: (key) => void memory.delete(key),
+      keys: () => [...memory.keys()],
+    }
+  }
+  return {
+    getItem(key) {
+      try {
+        return backend.getItem(key)
+      } catch {
+        return null
+      }
+    },
+    setItem(key, value) {
+      // Failures surface to the caller's `save`, which warns and no-ops.
+      backend.setItem(key, value)
+    },
+    removeItem(key) {
+      try {
+        backend.removeItem(key)
+      } catch {
+        // The entry is already unreachable.
+      }
+    },
+    keys() {
+      const all: string[] = []
+      try {
+        for (let index = 0; index < backend.length; index++) {
+          const key = backend.key(index)
+          if (key !== null) all.push(key)
+        }
+      } catch {
+        return all
+      }
+      return all
+    },
+  }
+}
+
+/**
+ * True outside a production build. Bundlers replace `process.env.NODE_ENV`,
+ * and this package is type-checked against Node's types, not `vite/client`,
+ * so the read goes through `globalThis` with a guard for non-Node hosts.
+ */
+function isProduction(): boolean {
+  return (
+    (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env
+      ?.NODE_ENV === 'production'
+  )
+}
+
+function warnStorageFailure(): void {
+  if (!isProduction()) {
+    console.warn(
+      '[newui-data] createConfigStore: the storage backend rejected a write (quota or disabled storage). The document is dropped, not fatal.',
+    )
+  }
+}
+
+function warnOverLimit(name: string, bytes: number): void {
+  if (!isProduction()) {
+    console.warn(
+      `[newui-data] createConfigStore: document "${name}" is ${bytes} bytes, over the ${CONFIG_DOCUMENT_LIMIT}-byte cap. It was not saved — check what grew (a widget grid that appends forever is the usual suspect).`,
+    )
+  }
+}
+
+function byteLength(text: string): number {
+  return new TextEncoder().encode(text).length
+}
+
+function isEnvelope(value: unknown): value is ConfigDocument {
+  if (value === null || typeof value !== 'object') return false
+  const candidate = value as Partial<ConfigDocument>
+  return (
+    typeof candidate.v === 'number' &&
+    typeof candidate.name === 'string' &&
+    typeof candidate.updatedAt === 'string' &&
+    'doc' in candidate
+  )
+}
+
+/**
+ * Create a store of named, versioned documents.
+ *
+ * `save` wraps the payload in a {@link ConfigDocument} envelope; `load` reads
+ * it back and runs `migrate` when the stored version is older than the
+ * current one. Documents are capped at 64KB with a loud dev warning, so an
+ * unbounded document is caught in development instead of in a quota error.
+ */
+export function createConfigStore(options: ConfigStoreOptions): ConfigStore {
+  const storage = options.storage ?? defaultStorage()
+  const namespace = `${options.key}:`
+  const scoped = (name: string) => `${namespace}${name}`
+  let warned = false
+  const warn = (message: string) => {
+    if (warned) return
+    warned = true
+    console.warn(message)
+  }
+
+  /** A backend that throws drops the write and says so, once. */
+  const write = (name: string, raw: string): boolean => {
+    try {
+      storage.setItem(scoped(name), raw)
+      return true
+    } catch {
+      warnStorageFailure()
+      return false
+    }
+  }
+
+  const read = <T>(name: string): ConfigDocument<T> | undefined => {
+    const raw = storage.getItem(scoped(name))
+    if (raw === null) return undefined
+    let value: unknown
+    try {
+      value = JSON.parse(raw)
+    } catch {
+      return undefined
+    }
+    if (!isEnvelope(value)) return undefined
+    const envelope = value as ConfigDocument<T>
+    if (envelope.v === CONFIG_SCHEMA_VERSION) return envelope
+    if (!options.migrate) {
+      warn(
+        `[newui-data] createConfigStore: "${name}" is v${envelope.v}, the store reads v${CONFIG_SCHEMA_VERSION}, and no migrate was supplied. It is unreadable, not corrupted.`,
+      )
+      return undefined
+    }
+    const migrated = options.migrate(envelope.doc, envelope.v)
+    if (migrated === undefined) return undefined
+    return { ...envelope, v: CONFIG_SCHEMA_VERSION, doc: migrated as T }
+  }
+
+  return {
+    list() {
+      const summaries: ConfigSummary[] = []
+      for (const key of storage.keys()) {
+        if (!key.startsWith(namespace)) continue
+        const name = key.slice(namespace.length)
+        const envelope = read(name)
+        if (!envelope) continue
+        const summary: ConfigSummary = {
+          name,
+          updatedAt: envelope.updatedAt,
+        }
+        if (envelope.type !== undefined) summary.type = envelope.type
+        summaries.push(summary)
+      }
+      return summaries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+    },
+    load<T>(name: string) {
+      return read<T>(name)
+    },
+    save<T>(name: string, doc: T, saveOptions: { type?: string } = {}) {
+      const envelope: ConfigDocument<T> = {
+        v: CONFIG_SCHEMA_VERSION,
+        name,
+        ...(saveOptions.type !== undefined ? { type: saveOptions.type } : {}),
+        updatedAt: new Date().toISOString(),
+        doc,
+      }
+      const raw = JSON.stringify(envelope)
+      const bytes = byteLength(raw)
+      if (bytes > CONFIG_DOCUMENT_LIMIT) {
+        warnOverLimit(name, bytes)
+        return false
+      }
+      return write(name, raw)
+    },
+    remove(name: string) {
+      const existed = storage.getItem(scoped(name)) !== null
+      try {
+        storage.removeItem(scoped(name))
+      } catch {
+        // The entry is unreachable to the store either way.
+      }
+      return existed
+    },
+    rename(from: string, to: string) {
+      const envelope = read(from)
+      if (!envelope) return false
+      const raw = JSON.stringify({
+        ...envelope,
+        name: to,
+        updatedAt: new Date().toISOString(),
+      } satisfies ConfigDocument)
+      if (byteLength(raw) > CONFIG_DOCUMENT_LIMIT) {
+        warnOverLimit(to, byteLength(raw))
+        return false
+      }
+      if (!write(to, raw)) return false
+      try {
+        storage.removeItem(scoped(from))
+      } catch {
+        // The renamed copy is saved; the source is already gone for us.
+      }
+      return true
+    },
+  }
+}

package/src/csv-export.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest'
+import {
+  type CsvExportTable,
+  type CsvExportTableRow,
+  exportCsv,
+} from './csv-export'
+
+interface FakeColumn {
+  id: string
+  visible?: boolean
+  meta?: Record<string, unknown>
+}
+
+function row(values: Record<string, unknown>): CsvExportTableRow {
+  return { getValue: (columnId) => values[columnId] }
+}
+
+function fakeTable(options: {
+  columns: FakeColumn[]
+  /** The raw data — what the core model returns. */
+  rows: Record<string, unknown>[]
+  /** The filtered, sorted view — what the filtered model returns. */
+  filtered?: Record<string, unknown>[]
+  pageIndex?: number
+  pageSize?: number
+}): CsvExportTable {
+  const leaf = (visibleOnly: boolean) =>
+    options.columns
+      .filter((column) => !visibleOnly || column.visible !== false)
+      .map((column) => ({
+        id: column.id,
+        columnDef: column.meta ? { meta: column.meta } : {},
+      }))
+  return {
+    getAllLeafColumns: () => leaf(false),
+    getVisibleLeafColumns: () => leaf(true),
+    getCoreRowModel: () => ({ rows: options.rows.map(row) }),
+    getFilteredRowModel: () => ({
+      rows: (options.filtered ?? options.rows).map(row),
+    }),
+    getState: () => ({
+      pagination: {
+        pageIndex: options.pageIndex ?? 0,
+        pageSize: options.pageSize ?? 10,
+      },
+    }),
+  }
+}
+
+async function csv(blob: Blob): Promise<string> {
+  return blob.text()
+}
+
+const five = [
+  { id: 1, name: 'a' },
+  { id: 2, name: 'b' },
+  { id: 3, name: 'c' },
+  { id: 4, name: 'd' },
+  { id: 5, name: 'e' },
+]
+
+describe('exportCsv', () => {
+  it('exports the filtered view with visible columns by default', async () => {
+    const table = fakeTable({
+      columns: [{ id: 'id' }, { id: 'name' }, { id: 'secret', visible: false }],
+      rows: five,
+      filtered: five.slice(0, 2),
+    })
+    const blob = await exportCsv(table)
+    expect(blob.type).toBe('text/csv;charset=utf-8')
+    expect(await csv(blob)).toBe('"id","name"\r\n"1","a"\r\n"2","b"')
+  })
+
+  it('scope page takes the current page slice', async () => {
+    const table = fakeTable({
+      columns: [{ id: 'id' }, { id: 'name' }],
+      rows: five,
+      pageIndex: 1,
+      pageSize: 2,
+    })
+    expect(await csv(await exportCsv(table, { scope: 'page' }))).toBe(
+      '"id","name"\r\n"3","c"\r\n"4","d"',
+    )
+  })
+
+  it('scope all ignores the filtered model', async () => {
+    const table = fakeTable({
+      columns: [{ id: 'id' }],
+      rows: five,
+      filtered: five.slice(0, 1),
+    })
+    const text = await csv(await exportCsv(table, { scope: 'all' }))
+    expect(text.split('\r\n')).toHaveLength(6)
+    expect(text).toContain('"5"')
+  })
+
+  it('columns all ships hidden columns too', async () => {
+    const table = fakeTable({
+      columns: [{ id: 'id' }, { id: 'secret', visible: false }],
+      rows: [{ id: 1, secret: 'x' }],
+    })
+    expect(await csv(await exportCsv(table, { columns: 'all' }))).toBe(
+      '"id","secret"\r\n"1","x"',
+    )
+  })
+
+  it('honours the export meta keys: name, format, exportable', async () => {
+    const table = fakeTable({
+      columns: [
+        { id: 'name', meta: { exportName: 'Full name' } },
+        {
+          id: 'amount',
+          meta: { format: (value: unknown) => `$${Number(value).toFixed(2)}` },
+        },
+        { id: 'internal', meta: { exportable: false } },
+      ],
+      rows: [{ name: 'ada', amount: 12.5, internal: 'keep out' }],
+    })
+    expect(await csv(await exportCsv(table))).toBe(
+      '"Full name","amount"\r\n"ada","$12.50"',
+    )
+  })
+
+  it('renders null and undefined as empty cells', async () => {
+    const table = fakeTable({
+      columns: [{ id: 'a' }, { id: 'b' }],
+      rows: [{ a: null, b: undefined }],
+    })
+    expect(await csv(await exportCsv(table))).toBe('"a","b"\r\n"",""')
+  })
+
+  it('quotes and escapes through csvText, including inner quotes', async () => {
+    const table = fakeTable({
+      columns: [{ id: 'quote' }],
+      rows: [{ quote: 'said "hi", loudly' }],
+    })
+    expect(await csv(await exportCsv(table))).toBe(
+      '"quote"\r\n"said ""hi"", loudly"',
+    )
+  })
+
+  it('falls back to String for values that are neither text nor numbers', async () => {
+    const table = fakeTable({
+      columns: [{ id: 'flag' }],
+      rows: [{ flag: true }],
+    })
+    expect(await csv(await exportCsv(table))).toBe('"flag"\r\n"true"')
+  })
+
+  it('is a promise — the call site never blocks', async () => {
+    const table = fakeTable({ columns: [{ id: 'id' }], rows: five })
+    const pending = exportCsv(table)
+    expect(pending).toBeInstanceOf(Promise)
+    await pending
+  })
+})