@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/download.ts

@@ -0,0 +1,39 @@
+/**
+ * Saving a file, without the Blob/anchor/revoke dance every page wrote.
+ *
+ * `downloadCsv` quotes every cell and doubles inner quotes, which is the part
+ * that is easy to get subtly wrong.
+ */
+
+/** Save a Blob (or a local `File`) under `name`. */
+export function downloadBlob(name: string, blob: Blob): void {
+  const url = URL.createObjectURL(blob)
+  const link = document.createElement('a')
+  link.href = url
+  link.download = name
+  link.click()
+  URL.revokeObjectURL(url)
+}
+
+/** Save text under `name`; plain text unless the caller names a type. */
+export function downloadText(
+  name: string,
+  text: string,
+  mime = 'text/plain;charset=utf-8',
+): void {
+  downloadBlob(name, new Blob([text], { type: mime }))
+}
+
+/** Rows → CSV text, every cell quoted, quotes doubled. */
+export function csvText(rows: (string | number)[][]): string {
+  return rows
+    .map((row) =>
+      row.map((value) => `"${String(value).replaceAll('"', '""')}"`).join(','),
+    )
+    .join('\r\n')
+}
+
+/** Save rows as a CSV file under `name`. */
+export function downloadCsv(name: string, rows: (string | number)[][]): void {
+  downloadText(name, csvText(rows), 'text/csv;charset=utf-8')
+}

package/src/exports.test.ts

@@ -0,0 +1,135 @@
+/**
+ * The logic layer's public surface, asserted by name and by entry point.
+ *
+ * The data package has four entries (`.`, `/query`, `/form`, `/resource`),
+ * which is exactly
+ * the shape an accidental `export *` or a stray
+ * re-export slips into. An entry's cost is part of its contract — 0.77 kB for
+ * the helpers, 15.5 for the query — so a new name on an entry is a decision, not
+ * a detail.
+ */
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import * as form from './form'
+import * as root from './index'
+import * as query from './query'
+import * as resource from './resource'
+
+const ENTRIES = {
+  '.': root,
+  './query': query,
+  './form': form,
+  './resource': resource,
+} as const
+
+const SURFACE: Record<keyof typeof ENTRIES, string[]> = {
+  // Formatting, selection, undo, downloads — and nothing that renders.
+  '.': [
+    'CONFIG_DOCUMENT_LIMIT',
+    'CONFIG_SCHEMA_VERSION',
+    'DashboardProvider',
+    'aggregate',
+    'bytes',
+    'count',
+    'createConfigStore',
+    'createDashboardState',
+    'createTablePersist',
+    'createUndo',
+    'createUrlState',
+    'csvText',
+    'downloadBlob',
+    'downloadCsv',
+    'downloadText',
+    'exportCsv',
+    'first',
+    'isEmail',
+    'optionsOf',
+    'rollup',
+    'timeBucket',
+    'usd',
+    'usdK',
+    'useDashboardState',
+  ],
+  './query': [
+    'DataProvider',
+    'createCollection',
+    'createDataClient',
+    'createListQuery',
+    'createServerTableState',
+  ],
+  './form': [
+    'Form',
+    'createAppForm',
+    'createAutoSave',
+    'fieldError',
+    'hiddenPaths',
+    'isUnderHidden',
+    'pruneHiddenValues',
+  ],
+  './resource': [
+    'RequestError',
+    'connectRealtime',
+    'createDocumentResource',
+    'createIdbStore',
+    'createListResource',
+    'createLocalStore',
+    'createRealtime',
+    'createResource',
+    'getConfig',
+    'isAbortError',
+    'normalizeError',
+    'request',
+    'resetConfig',
+    'setConfig',
+    'useCall',
+    'useDoc',
+    'useDoctype',
+    'useList',
+    'useNewDoc',
+  ],
+}
+
+const manifest = JSON.parse(
+  readFileSync(path.join(process.cwd(), 'packages/data/package.json'), 'utf8'),
+) as { exports: Record<string, unknown> }
+
+describe('@talelk/newui-data', () => {
+  it('publishes exactly the entries this test pins', () => {
+    expect(Object.keys(manifest.exports).sort()).toEqual(
+      Object.keys(ENTRIES).sort(),
+    )
+  })
+
+  for (const [entry, module] of Object.entries(ENTRIES)) {
+    it(`${entry} exports exactly its surface`, () => {
+      expect(Object.keys(module).sort()).toEqual(
+        SURFACE[entry as keyof typeof ENTRIES],
+      )
+    })
+  }
+
+  it('keeps the root entry headless', () => {
+    // The root is the only entry with no component, no query client and no
+    // validator; every value it exports is a function over plain data — with
+    // the exception of the config-store constants, plain numbers by design.
+    for (const [name, value] of Object.entries(root)) {
+      if (
+        name === 'CONFIG_SCHEMA_VERSION' ||
+        name === 'CONFIG_DOCUMENT_LIMIT'
+      ) {
+        expect(typeof value).toBe('number')
+        continue
+      }
+      expect(typeof value).toBe('function')
+    }
+  })
+
+  it('keeps the Frappe resource client off the root', () => {
+    // The DocType fetching layer is app-specific cost (fetch + IndexedDB +
+    // realtime multiplexer); it must stay behind its earned subpath.
+    for (const name of ['useDoc', 'useDoctype', 'frappeRequest', 'request']) {
+      expect(name in root).toBe(false)
+    }
+  })
+})

package/src/form/autosave.test.ts

@@ -0,0 +1,186 @@
+import { type AnyFormApi, createForm } from '@tanstack/solid-form'
+import { createEffect, createRoot } from 'solid-js'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createAutoSave } from './autosave'
+import { createAppForm } from './form'
+
+function memoryStorage() {
+  const map = new Map<string, string>()
+  return {
+    getItem: (key: string) => map.get(key) ?? null,
+    setItem: (key: string, value: string) => void map.set(key, value),
+    removeItem: (key: string) => void map.delete(key),
+    keys: () => [...map.keys()],
+  }
+}
+
+function harness() {
+  // `createRoot` runs its callback synchronously, so `form` is set by return.
+  let form!: AnyFormApi
+  createRoot((dispose) => {
+    form = createForm(() => ({
+      defaultValues: { name: '' } satisfies { name: string },
+      validators: {
+        onChange: ({ value }: { value: { name: string } }) =>
+          value.name.length < 3 ? 'Too short.' : undefined,
+      },
+    }))
+    // Keep the root alive for the duration of the test.
+    void dispose
+  })
+  return form
+}
+
+beforeEach(() => vi.useFakeTimers())
+
+describe('createAutoSave', () => {
+  it('saves a valid dirty value after the debounce', async () => {
+    const form = harness()
+    const save = vi.fn()
+    const auto = createAutoSave<{ name: string }>(form, { save, debounce: 100 })
+
+    form.setFieldValue('name', 'Ada Lovelace')
+    await vi.advanceTimersByTimeAsync(100)
+
+    expect(save).toHaveBeenCalledTimes(1)
+    expect(save.mock.calls[0]?.[0]).toEqual({ name: 'Ada Lovelace' })
+    expect(auto.saved()).toBe(true)
+    expect(auto.dirty()).toBe(false)
+  })
+
+  it('does not save while the form is invalid', async () => {
+    const form = harness()
+    const save = vi.fn()
+    createAutoSave<{ name: string }>(form, { save, debounce: 50 })
+
+    form.setFieldValue('name', 'ad')
+    await vi.advanceTimersByTimeAsync(50)
+
+    expect(save).not.toHaveBeenCalled()
+  })
+
+  it('skips the write when the filter rejects', async () => {
+    const form = harness()
+    const save = vi.fn()
+    createAutoSave<{ name: string }>(form, {
+      save,
+      debounce: 50,
+      filter: (values) => values.name !== 'skip',
+    })
+
+    form.setFieldValue('name', 'skip')
+    await vi.advanceTimersByTimeAsync(50)
+
+    expect(save).not.toHaveBeenCalled()
+  })
+
+  it('persists a draft and clears it after a successful save', async () => {
+    const form = harness()
+    const storage = memoryStorage()
+    const save = vi.fn()
+    const auto = createAutoSave<{ name: string }>(form, {
+      save,
+      debounce: 50,
+      id: 'profile',
+      storage,
+    })
+
+    form.setFieldValue('name', 'Ada Lovelace')
+    // The draft is written on the change, before the debounce fires.
+    expect(auto.hasDraft()).toBe(true)
+    expect(auto.restoreDraft()).toEqual({ name: 'Ada Lovelace' })
+
+    await vi.advanceTimersByTimeAsync(50)
+    expect(save).toHaveBeenCalled()
+    expect(auto.hasDraft()).toBe(false)
+  })
+
+  it('tracks hasDraft reactively', async () => {
+    const form = harness()
+    const seen: boolean[] = []
+    createRoot(() => {
+      const auto = createAutoSave<{ name: string }>(form, {
+        save: vi.fn(),
+        debounce: 50,
+        id: 'reactive',
+        storage: memoryStorage(),
+      })
+      createEffect(() => {
+        seen.push(auto.hasDraft())
+      })
+    })
+    form.setFieldValue('name', 'Ada Lovelace')
+    await vi.advanceTimersByTimeAsync(50)
+    expect(seen).toEqual([false, true, false])
+  })
+})
+
+interface Doc {
+  mode: string
+  host: string
+  name: string
+}
+
+/** An app form whose `host` is hidden unless `mode` is `advanced`. */
+function appHarness(onSubmit: (doc: Doc) => void = () => {}) {
+  let app!: ReturnType<typeof createAppForm<Doc>>
+  createRoot(() => {
+    app = createAppForm<Doc>({
+      defaultValues: { mode: 'simple', host: 'stale.example', name: '' },
+      ui: { host: { when: (values) => values.mode === 'advanced' } },
+      onSubmit,
+    })
+  })
+  return app
+}
+
+describe('createAutoSave with an app form', () => {
+  it('saves the pruned document, the one submit sends', async () => {
+    const app = appHarness()
+    const save = vi.fn()
+    createAutoSave<Doc>(app, { save, debounce: 50 })
+
+    app.form.setFieldValue('name', 'Ada')
+    await vi.advanceTimersByTimeAsync(50)
+
+    expect(save).toHaveBeenCalledWith({ mode: 'simple', name: 'Ada' })
+  })
+
+  it('keeps the draft unpruned', () => {
+    const app = appHarness()
+    const auto = createAutoSave<Doc>(app, {
+      save: vi.fn(),
+      debounce: 50,
+      id: 'settings',
+      storage: memoryStorage(),
+    })
+
+    app.form.setFieldValue('name', 'Ada')
+
+    expect(auto.restoreDraft()).toEqual({
+      mode: 'simple',
+      host: 'stale.example',
+      name: 'Ada',
+    })
+  })
+
+  it('drops the draft on a successful submit and does not autosave after it', async () => {
+    const app = appHarness()
+    const save = vi.fn()
+    const auto = createAutoSave<Doc>(app, {
+      save,
+      debounce: 50,
+      id: 'settings',
+      storage: memoryStorage(),
+    })
+
+    app.form.setFieldValue('name', 'Ada')
+    expect(auto.hasDraft()).toBe(true)
+    await app.form.handleSubmit()
+
+    expect(auto.hasDraft()).toBe(false)
+    expect(auto.dirty()).toBe(false)
+    await vi.advanceTimersByTimeAsync(50)
+    expect(save).not.toHaveBeenCalled()
+  })
+})

package/src/form/autosave.ts

@@ -0,0 +1,194 @@
+import type { AnyFormApi } from '@tanstack/solid-form'
+import { type Accessor, createSignal, onCleanup } from 'solid-js'
+import { type ConfigStorage, createConfigStore } from '../config-store'
+
+/**
+ * Autosave and drafts for a live form.
+ *
+ * Two stores, two rules. The **autosave** is a debounced backend write of a
+ * valid, pruned document: every change re-arms the timer, and when it fires
+ * the form validates itself before anything is written — an invalid document
+ * is never saved behind the user's back. It is not a submit; the submit
+ * lifecycle does not move. The **draft** is the local, unpruned copy written
+ * on every change (through the config store under `newui.form-draft`, document
+ * name = `id`), so a closed tab loses nothing and re-showing a hidden field
+ * gives back what was typed. A successful autosave or submit drops the draft.
+ */
+export interface AutoSaveOptions<T extends object> {
+  /** Persists the valid, dirty document — usually a query mutation. */
+  save: (values: T) => void | Promise<void>
+  /**
+   * Milliseconds a change waits before it is saved.
+   * @default 800
+   */
+  debounce?: number
+  /** Skips the write when it returns `false` (an unfinished required section). */
+  filter?: (values: T) => boolean
+  /** Draft identity. Omit it to autosave without persisting drafts. */
+  id?: string
+  /** Draft storage backend. Defaults to `localStorage`, like the config store. */
+  storage?: ConfigStorage
+}
+
+/**
+ * What autosave watches: a TanStack form, or the `createAppForm` result —
+ * pass the latter so `save` receives the same pruned document submit sends.
+ */
+export type AutoSaveSource<T extends object> =
+  | AnyFormApi
+  | { form: AnyFormApi; document: (values: T) => T }
+
+/** What `createAutoSave` returns; the chrome reads the accessors. */
+export interface AutoSave<T extends object = Record<string, unknown>> {
+  /** True while a save is in flight. */
+  saving: Accessor<boolean>
+  /** True once a save has landed and nothing has changed since. */
+  saved: Accessor<boolean>
+  /** True when the form holds an unsaved change. */
+  dirty: Accessor<boolean>
+  /** Save now instead of waiting out the debounce. */
+  flush: () => Promise<void>
+  /** Whether a stored draft exists, reactive. */
+  hasDraft: Accessor<boolean>
+  /**
+   * The stored draft, if any — the app decides whether to apply it. A draft
+   * may predate the current schema or field map: treat it as untrusted input
+   * and let the form's validation report what no longer fits.
+   */
+  restoreDraft: () => T | undefined
+  /** Drop the stored draft (on submit, discard, or after `restoreDraft`). */
+  discardDraft: () => void
+}
+
+function clone<T>(value: T): T {
+  return structuredClone(value)
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime()
+  if (
+    a === null ||
+    b === null ||
+    typeof a !== 'object' ||
+    typeof b !== 'object'
+  )
+    return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  const aKeys = Object.keys(a as object)
+  const bKeys = Object.keys(b as object)
+  if (aKeys.length !== bKeys.length) return false
+  return aKeys.every(
+    (key) =>
+      Object.hasOwn(b, key) &&
+      deepEqual(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key],
+      ),
+  )
+}
+
+function isAppForm<T extends object>(
+  source: AutoSaveSource<T>,
+): source is { form: AnyFormApi; document: (values: T) => T } {
+  return 'document' in source && typeof source.document === 'function'
+}
+
+export function createAutoSave<T extends object>(
+  source: AutoSaveSource<T>,
+  options: AutoSaveOptions<T>,
+): AutoSave<T> {
+  const form = isAppForm(source) ? source.form : source
+  const document = isAppForm(source) ? source.document : (values: T) => values
+  const debounce = options.debounce ?? 800
+  const store = options.id
+    ? createConfigStore({ key: 'newui.form-draft', storage: options.storage })
+    : undefined
+  const id = options.id
+
+  let lastSaved: T = clone(form.state.values as T)
+  let running: Promise<void> = Promise.resolve()
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const [saving, setSaving] = createSignal(false)
+  const [saved, setSaved] = createSignal(false)
+  const [dirty, setDirty] = createSignal(false)
+  const [hasDraft, setHasDraft] = createSignal(
+    store !== undefined && id !== undefined && store.load(id) !== undefined,
+  )
+  const writeDraft = (values: T) => {
+    if (!store || !id) return
+    store.save(id, values, { type: 'form-draft' })
+    setHasDraft(true)
+  }
+  const dropDraft = () => {
+    if (!store || !id) return
+    store.remove(id)
+    setHasDraft(false)
+  }
+  let submissions = form.state.submissionAttempts as number
+
+  const run = async (): Promise<void> => {
+    const values = clone(form.state.values as T)
+    if (deepEqual(values, lastSaved)) return
+    if (options.filter && !options.filter(values)) return
+    setSaving(true)
+    try {
+      await form.validateAllFields('submit')
+      if ((form.state.errors as unknown[]).length === 0) {
+        await options.save(document(values))
+        lastSaved = values
+        setSaved(true)
+        setDirty(false)
+        dropDraft()
+      }
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const subscription = form.store.subscribe(() => {
+    const state = form.state
+    // A successful submit wrote the document: nothing is unsaved, the draft
+    // goes, and the values it sent are the new baseline.
+    if (
+      state.isSubmitSuccessful &&
+      (state.submissionAttempts as number) !== submissions
+    ) {
+      submissions = state.submissionAttempts as number
+      clearTimeout(timer)
+      lastSaved = clone(state.values as T)
+      setDirty(false)
+      dropDraft()
+      return
+    }
+    // Mid-submit changes (an `onSubmit` reset) are the submit's, not edits.
+    if (state.isSubmitting) return
+    const values = state.values as T
+    if (deepEqual(values, lastSaved)) return
+    setDirty(true)
+    setSaved(false)
+    writeDraft(values)
+    clearTimeout(timer)
+    timer = setTimeout(() => {
+      running = run()
+    }, debounce)
+  })
+  onCleanup(() => {
+    clearTimeout(timer)
+    subscription.unsubscribe()
+  })
+
+  return {
+    saving,
+    saved,
+    dirty,
+    async flush() {
+      clearTimeout(timer)
+      await running
+      await run()
+    },
+    hasDraft,
+    restoreDraft: () => (store && id ? store.load<T>(id)?.doc : undefined),
+    discardDraft: dropDraft,
+  }
+}