@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/form/form.tsx

@@ -0,0 +1,205 @@
+import {
+  createForm,
+  type StandardSchemaV1,
+  standardSchemaValidators,
+} from '@tanstack/solid-form'
+import { type Accessor, type JSX, splitProps } from 'solid-js'
+import {
+  type FieldConfig,
+  hiddenPaths,
+  isUnderHidden,
+  pruneHiddenValues,
+} from './config'
+
+/**
+ * The form surface: the kit's answer to "how does a page submit".
+ *
+ * TanStack Form stays the engine — validators, field state, reset. What this
+ * adds is the three things every page was writing by hand: a submit lifecycle
+ * the button can read, a `<form>` that never lets the browser's native
+ * validation paint first, and one place that turns a field's error list into the
+ * single `error` string the kit's `Field` contract takes.
+ */
+
+export interface AppFormOptions<T extends object> {
+  defaultValues: T
+  /**
+   * Runs on submit. While the returned promise is pending the form reports
+   * `submitting()`, which is what a submit button's `loading` reads.
+   */
+  onSubmit: (value: T, api: { reset: () => void }) => void | Promise<void>
+  /**
+   * A Standard Schema (Zod, Valibot, Ark) — the document, validated on change
+   * and on submit, with issues mapped onto fields. The schema must validate
+   * synchronously; an async one belongs in the submit handler.
+   */
+  schema?: StandardSchemaV1<T, T>
+  /**
+   * The field map: how each field renders, keyed by static path (`smtp.host`,
+   * never `items[1]` — a repeater's row fields go under its `fields`). The
+   * engine reads `when` (for pruning and for dropping issues on hidden paths)
+   * and `dependsOn` (for revalidation); the rest is renderer vocabulary that
+   * the `ConfigForm` organism consumes from the same object.
+   */
+  ui?: Record<string, FieldConfig<T>>
+  /**
+   * Drop fields hidden by `when` from the submitted document.
+   * @default true
+   */
+  pruneHidden?: boolean
+}
+
+/** The `error` prop of a field, from TanStack's error list. */
+export function fieldError(field: {
+  state: { meta: { errors: unknown[] } }
+}): string | undefined {
+  const { errors } = field.state.meta
+  if (errors.length === 0) return undefined
+  const messages = errors.map((error) =>
+    typeof error === 'string'
+      ? error
+      : error && typeof error === 'object' && 'message' in error
+        ? String((error as { message: unknown }).message)
+        : String(error),
+  )
+  // A field usually declares the same message for `onChange` and `onSubmit`
+  // (validate as you type, and again on the way out). TanStack keeps one entry
+  // per validator, so the naive join prints the sentence twice.
+  return [...new Set(messages)].join(' ')
+}
+
+/**
+ * Throws on a field-map key that names an array position (`items[1]`). Keys
+ * are static paths; positions only arise when a repeater expands its rows.
+ */
+function assertStaticPaths(
+  ui: Record<string, { fields?: Record<string, unknown> }>,
+): void {
+  for (const [key, config] of Object.entries(ui)) {
+    if (key.includes('['))
+      throw new Error(
+        `newui form: field-map key "${key}" must be a static path — declare row fields under a repeater's \`fields\` instead of indexing.`,
+      )
+    if (config.fields)
+      assertStaticPaths(
+        config.fields as Record<string, { fields?: Record<string, unknown> }>,
+      )
+  }
+}
+
+export function createAppForm<T extends object>(options: AppFormOptions<T>) {
+  const ui = options.ui ?? {}
+  assertStaticPaths(ui)
+  const prune = options.pruneHidden !== false
+  const hasDeps = Object.values(ui).some((config) => config.dependsOn?.length)
+
+  /** The document the backend should see: hidden fields are not part of it. */
+  const submitted = (values: T): T =>
+    prune ? pruneHiddenValues(values, ui) : values
+
+  /**
+   * The schema validates the document that would be submitted, and issues on
+   * hidden paths are dropped: a field the user cannot see must not block the
+   * submit, and a hidden setting is not required of the document.
+   */
+  const schema = options.schema
+  const schemaValidator = schema
+    ? ({ value }: { value: unknown }) => {
+        const values = value as T
+        const issues = standardSchemaValidators.validate(
+          { value: submitted(values), validationSource: 'form' },
+          schema,
+        )
+        if (!issues?.fields) return issues
+        const hidden = hiddenPaths(values, ui)
+        if (hidden.length === 0) return issues
+        // The adapter reports every issue twice — per field and form-wide —
+        // so both maps are filtered, or a hidden issue still blocks submit.
+        const visible = (map: Record<string, unknown>) =>
+          Object.fromEntries(
+            Object.entries(map).filter(
+              ([path]) => !isUnderHidden(path, hidden),
+            ),
+          )
+        const fields = visible(issues.fields)
+        if (Object.keys(fields).length === 0) return undefined
+        return {
+          ...issues,
+          form:
+            issues.form && typeof issues.form === 'object'
+              ? visible(issues.form as Record<string, unknown>)
+              : issues.form,
+          fields,
+        }
+      }
+    : undefined
+
+  const form = createForm(() => ({
+    defaultValues: options.defaultValues,
+    validators: schemaValidator
+      ? { onChange: schemaValidator, onSubmit: schemaValidator }
+      : undefined,
+    // `dependsOn` compiles onto TanStack's listeners: a dependency's change
+    // revalidates the dependent field with the `dynamic` cause. Visibility
+    // itself needs no wiring — `when` reads the form's reactive values.
+    listeners: hasDeps
+      ? {
+          onChange: ({ formApi, fieldApi }) => {
+            for (const [path, config] of Object.entries(ui)) {
+              if (config.dependsOn?.includes(String(fieldApi.name))) {
+                void formApi.validateField(path, 'dynamic')
+              }
+            }
+          },
+        }
+      : undefined,
+    onSubmit: async ({ value, formApi }) => {
+      await options.onSubmit(submitted(value as T), {
+        reset: () => formApi.reset(),
+      })
+    },
+  }))
+  const submitting = form.useSelector((state) => state.isSubmitting)
+  return {
+    form,
+    /** True while the submit handler's promise is pending. */
+    submitting: submitting as Accessor<boolean>,
+    /** The field map, resolved. Pass it to `ConfigForm`'s `fields`. */
+    ui,
+    /**
+     * The document the backend sees for these values: hidden fields pruned
+     * unless `pruneHidden` is off. Submit sends it; so does `createAutoSave`.
+     */
+    document: submitted,
+  }
+}
+
+/**
+ * The `<form>` element, wired.
+ *
+ * `noValidate` because the kit's own field messages are the error UI; the native
+ * bubble would appear first, say less, and disappear on the next keystroke.
+ * `preventDefault` because this is a single-page app: a real submit would
+ * navigate.
+ */
+export function Form(props: {
+  form: { handleSubmit: () => unknown }
+  children: JSX.Element
+  class?: string
+}): JSX.Element {
+  const [local, rest] = splitProps(props, ['form', 'children', 'class'])
+  return (
+    <form
+      {...rest}
+      noValidate
+      class={local.class}
+      onSubmit={(event) => {
+        event.preventDefault()
+        event.stopPropagation()
+        void local.form.handleSubmit()
+      }}
+    >
+      {local.children}
+    </form>
+  )
+}

package/src/form/index.ts

@@ -0,0 +1,3 @@
+export * from './autosave'
+export * from './config'
+export * from './form'

package/src/format.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { bytes, count, isEmail, usd, usdK } from './format'
+
+describe('format', () => {
+  it('formats money, counts and sizes the way the pages did', () => {
+    expect(usd(128430)).toBe('$128,430')
+    expect(usd(0)).toBe('$0')
+    expect(usdK(42500)).toBe('$43k')
+    expect(usdK(400)).toBe('$0k')
+    expect(count(128430)).toBe('128,430')
+    expect(bytes(512)).toBe('512 B')
+    expect(bytes(2048)).toBe('2.0 KB')
+    expect(bytes(5 * 1024 * 1024)).toBe('5.0 MB')
+  })
+
+  it('accepts ordinary addresses and rejects the rest', () => {
+    expect(isEmail('rhea@example.com')).toBe(true)
+    expect(isEmail('rhea@example')).toBe(false)
+    expect(isEmail('rhea kapoor@example.com')).toBe(false)
+    expect(isEmail('')).toBe(false)
+  })
+})

package/src/format.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared formatting: money, counts, sizes, addresses.
+ *
+ * Built once at module scope — an `Intl.NumberFormat` per render is the kind of
+ * cost that never shows in a profile and always shows in a list. The examples
+ * had four near-identical USD copies; this is the one.
+ */
+
+const usdFormat = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  maximumFractionDigits: 0,
+})
+
+/** Whole-dollar USD: `usd(128430)` → `$128,430`. */
+export const usd = (value: number): string => usdFormat.format(value)
+
+/** Compact axis form: `usdK(42500)` → `$43k`. */
+export const usdK = (value: number): string => `$${Math.round(value / 1000)}k`
+
+const countFormat = new Intl.NumberFormat('en-US')
+
+/** Grouped integer: `count(128430)` → `128,430`. */
+export const count = (value: number): string => countFormat.format(value)
+
+/** Human file size: `bytes(2048)` → `2.0 KB`. */
+export const bytes = (value: number): string =>
+  value < 1024
+    ? `${value} B`
+    : value < 1024 * 1024
+      ? `${(value / 1024).toFixed(1)} KB`
+      : `${(value / (1024 * 1024)).toFixed(1)} MB`
+
+/** The one address check every example form shares. */
+export const isEmail = (value: string): boolean =>
+  /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './aggregate'
+export * from './config-store'
+export * from './csv-export'
+export * from './dashboard'
+export * from './download'
+export * from './format'
+export * from './select'
+export * from './table-persist'
+export * from './undo'
+export * from './url-state'

package/src/query/client.tsx

@@ -0,0 +1,53 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/solid-query'
+import { type JSX, onCleanup, untrack } from 'solid-js'
+
+/**
+ * The query client an app boots with.
+ *
+ * The defaults are the kit's opinion, stated once: local data is not a
+ * dashboard (no refetch on window focus), a transient failure is worth one retry,
+ * and an error is data the page renders rather than an exception that tears the
+ * tree down. A page overrides any of them per query.
+ */
+export interface DataClientOptions {
+  /** How long a list is fresh. Default `30_000`. */
+  staleTime?: number
+  /** Retries after the first failure. Default `1`. */
+  retry?: number
+}
+
+export function createDataClient(options: DataClientOptions = {}): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: options.staleTime ?? 30_000,
+        retry: options.retry ?? 1,
+        refetchOnWindowFocus: false,
+        throwOnError: false,
+      },
+      mutations: { retry: 0 },
+    },
+  })
+}
+
+/**
+ * The provider a page wraps its workspace in.
+ *
+ * Pass `client` to share one (a workspace with several panes shares its cache);
+ * omit it and the provider owns a client and clears it on unmount, so a route
+ * change never leaves timers or caches behind.
+ */
+export function DataProvider(props: {
+  client?: QueryClient
+  options?: DataClientOptions
+  children: JSX.Element
+}): JSX.Element {
+  // Chosen once, by design: swapping a provider's client mid-tree would orphan
+  // the cache every consumer is reading from.
+  const provided = untrack(() => props.client)
+  const client = provided ?? createDataClient(untrack(() => props.options))
+  if (!provided) onCleanup(() => client.clear())
+  return (
+    <QueryClientProvider client={client}>{props.children}</QueryClientProvider>
+  )
+}

package/src/query/collection.test.tsx

@@ -0,0 +1,278 @@
+import { render, screen, waitFor } from '@solidjs/testing-library'
+import type { QueryKey } from '@tanstack/solid-query'
+import { createSignal, For, type JSX, untrack } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import { DataProvider } from './client'
+import {
+  type Collection,
+  createCollection,
+  createListQuery,
+} from './collection'
+import type { Repository } from './repository'
+
+interface Row {
+  id: string
+  title: string
+}
+
+interface Deferred<T> {
+  promise: Promise<T>
+  resolve: (value: T) => void
+  reject: (error: unknown) => void
+}
+
+function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((ok, fail) => {
+    resolve = ok
+    reject = fail
+  })
+  return { promise, resolve, reject }
+}
+
+function makeRepository(initial: Row[]) {
+  let rows = [...initial]
+  const repository: Repository<Row, { title: string }> = {
+    list: async () => [...rows],
+    create: async (input) => {
+      const row = { id: `R-${rows.length + 1}`, title: input.title }
+      rows = [row, ...rows]
+      return row
+    },
+    update: vi.fn(async (id, patch) => {
+      rows = rows.map((row) => (row.id === id ? { ...row, ...patch } : row))
+      return rows.find((row) => row.id === id) as Row
+    }),
+    remove: async (ids) => {
+      const gone = new Set(ids)
+      rows = rows.filter((row) => !gone.has(row.id))
+    },
+  }
+  return { repository, rows: () => rows }
+}
+
+function Harness(props: {
+  repository: Repository<Row, { title: string }>
+  ready: (collection: Collection<Row, { title: string }>) => void
+  interval?: number | false
+}): JSX.Element {
+  const collection = createCollection(() => ({
+    key: ['rows'],
+    repository: props.repository,
+    retry: false,
+    ...(props.interval !== undefined
+      ? { refetchInterval: props.interval }
+      : {}),
+  }))
+  untrack(() => props.ready(collection))
+  return (
+    <ul>
+      <For each={collection.query.rows()}>{(row) => <li>{row.title}</li>}</For>
+    </ul>
+  )
+}
+
+function mount(
+  repository: Repository<Row, { title: string }>,
+  interval?: number | false,
+) {
+  let collection!: Collection<Row, { title: string }>
+  render(() => (
+    <DataProvider>
+      <Harness
+        repository={repository}
+        interval={interval}
+        ready={(value) => (collection = value)}
+      />
+    </DataProvider>
+  ))
+  return () => collection
+}
+
+describe('createCollection', () => {
+  it('loads the list and reports its pending and error states', async () => {
+    const failing = deferred<Row[]>()
+    const { repository } = makeRepository([{ id: '1', title: 'One' }])
+    const broken: Repository<Row, { title: string }> = {
+      ...repository,
+      list: () => failing.promise,
+    }
+    const collection = mount(broken)
+    expect(collection().query.isPending()).toBe(true)
+
+    failing.reject(new Error('The service is down'))
+    await waitFor(() => expect(collection().query.isError()).toBe(true))
+    expect(collection().query.error()?.message).toBe('The service is down')
+  })
+
+  it('patches optimistically and restores the list when the request fails', async () => {
+    const gate = deferred<Row>()
+    const { repository } = makeRepository([
+      { id: '1', title: 'One' },
+      { id: '2', title: 'Two' },
+    ])
+    const gated: Repository<Row, { title: string }> = {
+      ...repository,
+      update: (id, patch) => {
+        gate.promise.then(
+          () => repository.update(id, patch),
+          () => {},
+        )
+        return gate.promise
+      },
+    }
+    const collection = mount(gated)
+    await waitFor(() => expect(screen.getByText('One')).toBeTruthy())
+
+    collection().update.mutate({ id: '1', patch: { title: 'Changed' } })
+    // On screen before the request settles — that is the point of optimistic.
+    await waitFor(() => expect(screen.getByText('Changed')).toBeTruthy())
+
+    gate.reject(new Error('nope'))
+    await waitFor(() => expect(screen.getByText('One')).toBeTruthy())
+    expect(screen.queryByText('Changed')).toBeNull()
+  })
+
+  it('creates through the repository and refreshes the list', async () => {
+    const { repository, rows } = makeRepository([{ id: '1', title: 'One' }])
+    const collection = mount(repository)
+    await waitFor(() => expect(screen.getByText('One')).toBeTruthy())
+
+    await collection().create.mutateAsync({ title: 'New' })
+    expect(rows()[0]?.title).toBe('New')
+    await waitFor(() => expect(screen.getByText('New')).toBeTruthy())
+  })
+
+  it('completes many at once and removes through the same seam', async () => {
+    const { repository } = makeRepository([
+      { id: '1', title: 'One' },
+      { id: '2', title: 'Two' },
+    ])
+    const collection = mount(repository)
+    await waitFor(() => expect(screen.getByText('One')).toBeTruthy())
+
+    await collection().updateMany.mutateAsync({
+      ids: ['1', '2'],
+      patch: { title: 'Done' },
+    })
+    await waitFor(() => expect(screen.getAllByText('Done')).toHaveLength(2))
+
+    await collection().remove.mutateAsync({ ids: ['1', '2'] })
+    await waitFor(() => expect(screen.queryByText('Done')).toBeNull())
+  })
+
+  it('polls the list on the interval it is given', async () => {
+    const { repository } = makeRepository([{ id: '1', title: 'One' }])
+    const list = vi.fn(repository.list)
+    const polled: Repository<Row, { title: string }> = { ...repository, list }
+    mount(polled, 30)
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(1))
+
+    // The explicit dial: focus-refetch stays off, the interval does the work.
+    await waitFor(
+      () => expect(list.mock.calls.length).toBeGreaterThanOrEqual(3),
+      {
+        timeout: 2000,
+      },
+    )
+  })
+
+  it('never polls when refetchInterval is false', async () => {
+    const { repository } = makeRepository([{ id: '1', title: 'One' }])
+    const list = vi.fn(repository.list)
+    const quiet: Repository<Row, { title: string }> = { ...repository, list }
+    mount(quiet, false)
+    await waitFor(() => expect(list).toHaveBeenCalledTimes(1))
+
+    await new Promise((resolve) => setTimeout(resolve, 120))
+    expect(list).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('createListQuery keepPreviousData', () => {
+  /** One deferred response per key tag, so a key change gates on demand. */
+  function keyedRepository(tag: () => string) {
+    const pending = new Map<string, Deferred<Row[]>>()
+    const repository: Repository<Row, never> = {
+      list: () => {
+        const gate = deferred<Row[]>()
+        pending.set(tag(), gate)
+        return gate.promise
+      },
+      create: async () => {
+        throw new Error('not used')
+      },
+      update: async () => {
+        throw new Error('not used')
+      },
+      remove: async () => {},
+    }
+    return { repository, pending }
+  }
+
+  function ListHarness(props: {
+    queryKey: () => QueryKey
+    repository: Repository<Row, never>
+    keepPreviousData?: boolean
+  }): JSX.Element {
+    const list = createListQuery(() => ({
+      key: props.queryKey(),
+      repository: props.repository,
+      retry: false,
+      ...(props.keepPreviousData ? { keepPreviousData: true } : {}),
+    }))
+    return (
+      <ul>
+        <For each={list.rows()}>{(row) => <li>{row.title}</li>}</For>
+      </ul>
+    )
+  }
+
+  function mountList(keepPreviousData?: boolean) {
+    const [key, setKey] = createSignal<QueryKey>(['list', 'a'])
+    const { repository, pending } = keyedRepository(() =>
+      String(untrack(key)[1]),
+    )
+    render(() => (
+      <DataProvider>
+        <ListHarness
+          queryKey={key}
+          repository={repository}
+          keepPreviousData={keepPreviousData}
+        />
+      </DataProvider>
+    ))
+    return {
+      setKey: (tag: string) => setKey(['list', tag]),
+      pending,
+    }
+  }
+
+  it('holds the old page while the new key is in flight', async () => {
+    const { setKey, pending } = mountList(true)
+    await waitFor(() => {
+      pending.get('a')?.resolve([{ id: '1', title: 'One' }])
+      expect(screen.getByText('One')).toBeTruthy()
+    })
+
+    setKey('b')
+    // The request is in flight; the table must not blank.
+    await waitFor(() => expect(screen.getByText('One')).toBeTruthy())
+    pending.get('b')?.resolve([{ id: '2', title: 'Two' }])
+    await waitFor(() => expect(screen.getByText('Two')).toBeTruthy())
+    expect(screen.queryByText('One')).toBeNull()
+  })
+
+  it('without it the rows clear while the new key loads', async () => {
+    const { setKey, pending } = mountList(false)
+    await waitFor(() => {
+      pending.get('a')?.resolve([{ id: '1', title: 'One' }])
+      expect(screen.getByText('One')).toBeTruthy()
+    })
+    setKey('b')
+    await waitFor(() => expect(screen.queryByText('One')).toBeNull())
+    pending.get('b')?.resolve([{ id: '2', title: 'Two' }])
+    await waitFor(() => expect(screen.getByText('Two')).toBeTruthy())
+  })
+})