@talelk/newui-data 1.0.0 → 1.1.0

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,
+  }
+}

package/src/form/config.test.tsx

@@ -0,0 +1,288 @@
+import { render, screen, waitFor } from '@solidjs/testing-library'
+import type { StandardSchemaV1 } from '@tanstack/solid-form'
+import userEvent from '@testing-library/user-event'
+import { createRoot } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import { type FieldConfig, hiddenPaths, pruneHiddenValues } from './config'
+import { createAppForm, Form } from './form'
+
+/** A minimal Standard Schema: `name` must be non-empty, `city` must be a URL. */
+function schema(): StandardSchemaV1<
+  Record<string, unknown>,
+  Record<string, unknown>
+> {
+  return {
+    '~standard': {
+      version: 1,
+      vendor: 'test',
+      validate: (value) => {
+        const issues: { message: string; path: { key: string }[] }[] = []
+        const doc = value as Record<string, unknown>
+        if (!doc['name'])
+          issues.push({ message: 'Name is required.', path: [{ key: 'name' }] })
+        if (doc['city'] && !String(doc['city']).startsWith('http'))
+          issues.push({
+            message: 'City must be a URL.',
+            path: [{ key: 'city' }],
+          })
+        return issues.length
+          ? { issues }
+          : { value: value as Record<string, unknown> }
+      },
+    },
+  }
+}
+
+describe('pruneHiddenValues', () => {
+  it('drops a hidden nested field and leaves the rest', () => {
+    const values = { mode: 'simple', smtp: { host: 'a', port: 25 } }
+    const pruned = pruneHiddenValues(values, {
+      smtp: { when: (v) => v.mode === 'advanced' },
+    })
+    expect(pruned).toEqual({ mode: 'simple' })
+    // The original is never mutated.
+    expect(values.smtp.host).toBe('a')
+  })
+
+  it('drops a hidden row field from its row and keeps the row', () => {
+    const values = {
+      items: [
+        { kind: 'file', url: 'x' },
+        { kind: 'link', url: 'y' },
+      ],
+    }
+    const pruned = pruneHiddenValues(values, rowUi)
+    expect(pruned.items).toEqual([{ kind: 'file' }, { kind: 'link', url: 'y' }])
+    expect(values.items[0]).toEqual({ kind: 'file', url: 'x' })
+  })
+})
+
+/** A repeater whose `url` row field shows only for `link` rows. */
+// biome-ignore lint/suspicious/noExplicitAny: fixtures shared across documents of different shapes.
+const rowUi: Record<string, FieldConfig<any>> = {
+  items: {
+    type: 'repeater',
+    fields: {
+      kind: { type: 'text' },
+      url: { when: (row: { kind: string }) => row.kind === 'link' },
+    },
+  },
+}
+
+describe('hiddenPaths', () => {
+  it('lists the paths whose when is false', () => {
+    const ui = {
+      a: { when: (v: { on: boolean }) => v.on },
+      b: { when: () => true },
+    }
+    expect(hiddenPaths({ on: false }, ui)).toEqual(['a'])
+  })
+
+  it('expands a row field per row, passing the row and the form values', () => {
+    const values = {
+      flag: true,
+      items: [{ kind: 'file' }, { kind: 'link' }, { kind: 'file' }],
+    }
+    expect(hiddenPaths(values, rowUi)).toEqual(['items[0].url', 'items[2].url'])
+    const seen: unknown[] = []
+    hiddenPaths(values, {
+      items: {
+        fields: {
+          url: {
+            when: (row: unknown, all: unknown) => {
+              seen.push([row, all])
+              return true
+            },
+          },
+        },
+      },
+    })
+    expect(seen[0]).toEqual([{ kind: 'file' }, values])
+  })
+
+  it('does not expand the rows of a hidden repeater', () => {
+    const values = { on: false, items: [{ kind: 'file' }] }
+    expect(
+      hiddenPaths(values, {
+        items: { ...rowUi['items'], when: (v: typeof values) => v.on },
+      }),
+    ).toEqual(['items'])
+  })
+})
+
+describe('createAppForm field-map keys', () => {
+  it('rejects a key that names an array position', () => {
+    expect(() =>
+      createRoot(() =>
+        createAppForm({
+          defaultValues: { items: [] as unknown[] },
+          ui: { 'items[1]': { when: () => false } },
+          onSubmit: () => {},
+        }),
+      ),
+    ).toThrow(/static path/)
+  })
+
+  it('does not block submit on an issue under a hidden row field', async () => {
+    const onSubmit = vi.fn()
+    const rowSchema: StandardSchemaV1<RowDoc, RowDoc> = {
+      '~standard': {
+        version: 1,
+        vendor: 'test',
+        validate: (value) => {
+          const doc = value as RowDoc
+          const issues = doc.items.flatMap((row, index) =>
+            row.url === undefined || row.url === ''
+              ? [
+                  {
+                    message: 'URL is required.',
+                    path: [{ key: 'items' }, { key: index }, { key: 'url' }],
+                  },
+                ]
+              : [],
+          )
+          return issues.length ? { issues } : { value: doc }
+        },
+      },
+    }
+    let app!: ReturnType<typeof createAppForm<RowDoc>>
+    createRoot(() => {
+      app = createAppForm<RowDoc>({
+        defaultValues: {
+          items: [
+            { kind: 'file', url: '' },
+            { kind: 'link', url: 'https://a' },
+          ],
+        },
+        schema: rowSchema,
+        ui: rowUi,
+        onSubmit,
+      })
+    })
+    await app.form.handleSubmit()
+    expect(onSubmit).toHaveBeenCalledWith(
+      { items: [{ kind: 'file' }, { kind: 'link', url: 'https://a' }] },
+      expect.anything(),
+    )
+  })
+})
+
+describe('createAppForm hidden requirements', () => {
+  it('does not block submit when the schema requires a hidden top-level field', async () => {
+    type Doc = { mode: string; host?: string }
+    const onSubmit = vi.fn()
+    let app!: ReturnType<typeof createAppForm<Doc>>
+    createRoot(() => {
+      app = createAppForm<Doc>({
+        defaultValues: { mode: 'simple', host: '' },
+        schema: {
+          '~standard': {
+            version: 1,
+            vendor: 'test',
+            validate: (value) =>
+              (value as Doc).host
+                ? { value: value as Doc }
+                : {
+                    issues: [{ message: 'Host is required.', path: ['host'] }],
+                  },
+          },
+        },
+        ui: { host: { when: (values) => values.mode === 'advanced' } },
+        onSubmit,
+      })
+    })
+    await app.form.handleSubmit()
+    expect(onSubmit).toHaveBeenCalledWith({ mode: 'simple' }, expect.anything())
+  })
+})
+
+interface RowDoc {
+  items: { kind: string; url?: string }[]
+}
+
+function Harness(props: {
+  onSubmit: (value: Record<string, unknown>) => void
+  pruneHidden?: boolean
+}): import('solid-js').JSX.Element {
+  // A test harness: `onSubmit`/`pruneHidden` configure the form once, so these
+  // are setup-time reads of static props, not tracked ones.
+  /* eslint-disable solid/reactivity */
+  const { form } = createAppForm<Record<string, unknown>>({
+    defaultValues: { mode: 'simple', name: '', city: '' },
+    schema: schema(),
+    ui: {
+      mode: { type: 'text' },
+      name: { type: 'text' },
+      city: {
+        type: 'text',
+        dependsOn: ['mode'],
+        when: (values) => values['mode'] === 'advanced',
+      },
+    },
+    pruneHidden: props.pruneHidden,
+    onSubmit: props.onSubmit,
+  })
+  /* eslint-enable solid/reactivity */
+  return (
+    <Form form={form}>
+      <form.Field name="mode">
+        {(field) => (
+          <select
+            aria-label="Mode"
+            value={field().state.value as string}
+            onChange={(event) =>
+              field().handleChange(event.currentTarget.value)
+            }
+          >
+            <option value="simple">simple</option>
+            <option value="advanced">advanced</option>
+          </select>
+        )}
+      </form.Field>
+      <form.Field name="name">
+        {(field) => (
+          <input
+            aria-label="Name"
+            value={field().state.value as string}
+            onInput={(event) => field().handleChange(event.currentTarget.value)}
+          />
+        )}
+      </form.Field>
+      <button type="submit">Save</button>
+    </Form>
+  )
+}
+
+describe('createAppForm with schema + ui', () => {
+  it('prunes a hidden field from the submitted document', async () => {
+    const onSubmit = vi.fn()
+    render(() => <Harness onSubmit={onSubmit} />)
+    await userEvent.type(screen.getByLabelText('Name'), 'Ada')
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+    // city is hidden under mode=simple, so it is not part of the document.
+    expect(onSubmit.mock.calls[0]?.[0]).toEqual({ mode: 'simple', name: 'Ada' })
+  })
+
+  it('keeps the field when pruneHidden is false', async () => {
+    const onSubmit = vi.fn()
+    render(() => <Harness onSubmit={onSubmit} pruneHidden={false} />)
+    await userEvent.type(screen.getByLabelText('Name'), 'Ada')
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+    expect(onSubmit.mock.calls[0]?.[0]).toEqual({
+      mode: 'simple',
+      name: 'Ada',
+      city: '',
+    })
+  })
+
+  it('blocks submit while a visible required field is empty', async () => {
+    const onSubmit = vi.fn()
+    render(() => <Harness onSubmit={onSubmit} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    // The schema rejects the empty name; onSubmit never runs.
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(onSubmit).not.toHaveBeenCalled()
+  })
+})

package/src/form/config.ts

@@ -0,0 +1,187 @@
+import type { JSX } from 'solid-js'
+
+/**
+ * One entry of a config form's field map: what the engine reads, and what the
+ * `ConfigForm` organism renders.
+ *
+ * The schema validates; the field map says how to render. A Standard Schema
+ * carries zero UI information, so `createAppForm` accepts a map of static
+ * field paths to these entries and reads only `when` and `dependsOn` from
+ * them — everything else is renderer vocabulary, and the same object serves
+ * both sides.
+ *
+ * `TScope` is what `when` sees first: the form's values for a top-level entry,
+ * the row for a repeater's row field.
+ */
+export interface FieldConfig<
+  TValues = Record<string, unknown>,
+  TScope = TValues,
+> {
+  /**
+   * Which control renders. The default mapping is the molecule
+   * `FormControl` vocabulary (`text`, `select`, `checkbox`, `date`, …), plus
+   * `repeater` for arrays of rows.
+   */
+  type?: string
+  /** Drawn by the resolved control (P5). */
+  label?: JSX.Element
+  /** Helper text (P5). */
+  description?: JSX.Element
+  /** Error text is drawn from the field's own state, not from here. */
+  placeholder?: string
+  /** Marks the control required (the label's asterisk); validation is the schema's. */
+  required?: boolean
+  disabled?: boolean
+  /** Choices for the choice controls. */
+  options?: readonly { value: string; label?: string }[]
+  /** Extra props handed to the resolved control. */
+  props?: Record<string, unknown>
+  /** Rendered instead of the `type` mapping. */
+  component?: (props: FieldControlProps) => JSX.Element
+  /**
+   * Other field paths whose changes revalidate this field (compiled onto
+   * TanStack's listeners with the `dynamic` cause). Visibility itself is
+   * reactive without this — `when` reads the form's values.
+   */
+  dependsOn?: readonly string[]
+  /**
+   * Returning `false` hides the field. Unless `pruneHidden` is off, a hidden
+   * field is also dropped from the submitted document — submitting a value
+   * for a setting that is not shown is a lie to the backend.
+   *
+   * `scope` is the form's values for a top-level entry and the row for a
+   * repeater's row field; `values` is always the whole form.
+   */
+  when?: (scope: TScope, values: TValues) => boolean
+  /**
+   * For `type: 'repeater'`: the row's fields, keyed by subfield name. Their
+   * `when` receives the row first.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: row fields erase their scope type.
+  fields?: Record<string, FieldConfig<TValues, any>>
+  /** For `type: 'repeater'`: the ceiling on rows. */
+  maxItems?: number
+}
+
+/** The binding a custom `component` receives for one field. */
+export interface FieldControlProps {
+  /** The field's path in the form. */
+  name: string
+  value: unknown
+  /** Commits the value and runs the `onChange` validators. */
+  onChange: (value: unknown) => void
+  /** Marks the field touched and runs the `onBlur` validators. */
+  onBlur: () => void
+  /** The field's error, joined to one string — the `Field` contract. */
+  error?: string
+  disabled?: boolean
+}
+
+/** The slice of a field-map entry the engine reads for visibility. */
+interface VisibilityEntry {
+  // biome-ignore lint/suspicious/noExplicitAny: the erased mirror of FieldConfig.
+  when?: (scope: any, values: any) => boolean
+  fields?: Record<string, VisibilityEntry>
+}
+
+/**
+ * Every path the field map currently hides.
+ *
+ * Top-level entries are called `when(values, values)`. A repeater's row fields
+ * are expanded per row — `when(row, values)` — and reported as
+ * `items[1].url`; a hidden repeater hides its rows with it, so they are not
+ * expanded.
+ */
+export function hiddenPaths<T>(
+  values: T,
+  ui: Record<string, VisibilityEntry>,
+): string[] {
+  const hidden: string[] = []
+  const walk = (
+    scope: unknown,
+    entries: Record<string, VisibilityEntry>,
+    prefix: string,
+  ) => {
+    for (const [key, config] of Object.entries(entries)) {
+      const path = prefix ? `${prefix}.${key}` : key
+      if (config.when && !config.when(scope, values)) {
+        hidden.push(path)
+        continue
+      }
+      if (!config.fields) continue
+      const rows = readPath(scope, key)
+      if (!Array.isArray(rows)) continue
+      rows.forEach((row, index) => {
+        walk(row, config.fields ?? {}, `${path}[${index}]`)
+      })
+    }
+  }
+  walk(values, ui, '')
+  return hidden
+}
+
+/**
+ * Drop every hidden field from `values`. Paths may nest (`smtp.host`) and,
+ * inside a repeater, address a row field (`items[1].url`) — the field leaves
+ * its row, the row stays. The result is a copy, never a mutation of the
+ * form's state.
+ */
+export function pruneHiddenValues<T extends object>(
+  values: T,
+  ui: Record<string, VisibilityEntry>,
+): T {
+  let pruned: T = values
+  for (const path of hiddenPaths(values, ui)) {
+    pruned = deletePath(pruned, path) as T
+  }
+  return pruned
+}
+
+/** True when `candidate` is the hidden path itself or lives under it. */
+export function isUnderHidden(
+  candidate: string,
+  hidden: readonly string[],
+): boolean {
+  return hidden.some(
+    (path) =>
+      candidate === path ||
+      candidate.startsWith(`${path}.`) ||
+      candidate.startsWith(`${path}[`),
+  )
+}
+
+function splitPath(path: string): string[] {
+  return path.replace(/\[/g, '.').replace(/\]/g, '').split('.').filter(Boolean)
+}
+
+function readPath(root: unknown, path: string): unknown {
+  let node = root
+  for (const key of splitPath(path)) {
+    if (node === null || typeof node !== 'object') return undefined
+    node = (node as Record<string, unknown>)[key]
+  }
+  return node
+}
+
+function deletePath(root: unknown, path: string): unknown {
+  const keys = splitPath(path)
+  if (keys.length === 0) return root
+  const [head, ...rest] = keys as [string, ...string[]]
+  if (root === null || typeof root !== 'object') return root
+  if (Array.isArray(root)) {
+    // A static field-map path never ends on a position: rows are not removed.
+    if (rest.length === 0) return root
+    const copy = [...(root as unknown[])]
+    copy[Number(head)] = deletePath(copy[Number(head)], rest.join('.'))
+    return copy
+  }
+  const copy: Record<string, unknown> = { ...(root as Record<string, unknown>) }
+  if (rest.length === 0) {
+    delete copy[head]
+    return copy
+  }
+  const child = (root as Record<string, unknown>)[head]
+  if (child === undefined) return root
+  copy[head] = deletePath(child, rest.join('.'))
+  return copy
+}