@talelk/newui-data 0.0.0-stage → 1.1.0

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

package/src/form/form.test.tsx

@@ -0,0 +1,102 @@
+import { render, screen, waitFor } from '@solidjs/testing-library'
+import userEvent from '@testing-library/user-event'
+import { untrack } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import { createAppForm, Form, fieldError } from './form'
+
+function Harness(props: {
+  onSubmit: (value: { name: string }) => Promise<void>
+}): import('solid-js').JSX.Element {
+  const { form, submitting } = createAppForm({
+    defaultValues: { name: '' },
+    onSubmit: untrack(() => props.onSubmit),
+  })
+  return (
+    <Form form={form} class="flex flex-col gap-2">
+      <form.Field
+        name="name"
+        validators={{
+          onChange: ({ value }) =>
+            value.length < 3 ? 'Use at least 3 characters.' : undefined,
+          onSubmit: ({ value }) =>
+            value.length < 3 ? 'Use at least 3 characters.' : undefined,
+        }}
+      >
+        {(field) => (
+          <>
+            <input
+              aria-label="Name"
+              value={field().state.value}
+              onInput={(event) =>
+                field().handleChange(event.currentTarget.value)
+              }
+            />
+            <p role="alert">{fieldError(field())}</p>
+            <button type="submit" disabled={submitting()}>
+              Save
+            </button>
+          </>
+        )}
+      </form.Field>
+    </Form>
+  )
+}
+
+describe('createAppForm', () => {
+  it('submits a valid value and blocks an invalid one', async () => {
+    const onSubmit = vi.fn(async (_value: { name: string }) => {})
+    render(() => <Harness onSubmit={onSubmit} />)
+    const field = screen.getByRole('textbox', { name: 'Name' })
+
+    await userEvent.type(field, 'ab')
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    expect(onSubmit).not.toHaveBeenCalled()
+    await waitFor(() =>
+      expect(screen.getByRole('alert').textContent).toContain(
+        'at least 3 characters',
+      ),
+    )
+
+    await userEvent.type(field, 'c')
+    await userEvent.click(screen.getByRole('button', { name: 'Save' }))
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+    expect(onSubmit.mock.calls[0]?.[0]).toEqual({ name: 'abc' })
+  })
+
+  it('reports submitting while the handler is pending, and disables the button', async () => {
+    let finish!: () => void
+    const onSubmit = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          finish = resolve
+        }),
+    )
+    render(() => <Harness onSubmit={onSubmit} />)
+    await userEvent.type(screen.getByRole('textbox', { name: 'Name' }), 'abc')
+    const button = screen.getByRole('button', { name: 'Save' })
+    await userEvent.click(button)
+    await waitFor(() => expect(onSubmit).toHaveBeenCalled())
+    await waitFor(() => expect(button).toBeDisabled())
+
+    finish()
+    await waitFor(() => expect(button).not.toBeDisabled())
+  })
+})
+
+describe('fieldError', () => {
+  it('turns TanStack’s error list into the single string a field takes', () => {
+    expect(fieldError({ state: { meta: { errors: [] } } })).toBeUndefined()
+    expect(fieldError({ state: { meta: { errors: ['Required.'] } } })).toBe(
+      'Required.',
+    )
+    expect(
+      fieldError({
+        state: { meta: { errors: [{ message: 'Required.' }, 'Too short.'] } },
+      }),
+    ).toBe('Required. Too short.')
+    // The same message from `onChange` and `onSubmit` is one sentence, not two.
+    expect(
+      fieldError({ state: { meta: { errors: ['Required.', 'Required.'] } } }),
+    ).toBe('Required.')
+  })
+})