@svgrid/grid 2.1.21 → 2.1.23

package/src/SvForm.svelte

@@ -1,31 +1,16 @@
 <script lang="ts" module>
-  import type { Validator } from './validators'
-
-  export type FormFieldType =
-    | 'text' | 'email' | 'tel' | 'textarea' | 'number' | 'password'
-    | 'select' | 'checkbox' | 'switch' | 'date' | 'color' | 'rating'
-
-  export type FormField = {
-    name: string
-    label: string
-    type?: FormFieldType
-    required?: boolean
-    placeholder?: string
-    options?: Array<{ value: string | number; label: string }>
-    /** Declarative validation rules (see `rules` - email/pattern/min/compare...). */
-    rules?: ReadonlyArray<Validator>
-    /** Return an error message, or null/undefined when valid. */
-    validate?: (value: any, values: Record<string, any>) => string | null | undefined
-    /** Span full width in the grid. */
-    full?: boolean
-  }
+  // FormField/FormFieldType live in a plain `.ts` (breaks a Vite dev import
+  // cycle); re-exported so `import { type FormField } from './SvForm.svelte'`
+  // sites keep working.
+  export type { FormField, FormFieldType, FormSection, FormEntry } from './form-field'
 </script>
 
 <script lang="ts">
   /**
    * SvForm - a schema-driven form that renders the SvGrid UI-kit controls with
-   * labels, required + custom validation, and a submit handler. Parity: Smart
-   * `smart-form`. Emits `onSubmit(values)` only when valid; `onChange` on edits.
+   * labels, required + custom validation, and a submit handler. The schema may be
+   * a flat `FormField[]` or mix in titled `FormSection`s; with `stepper` the
+   * sections become a validated wizard. Emits `onSubmit(values)` only when valid.
    */
   import SvNumberInput from './SvNumberInput.svelte'
   import SvPasswordInput from './SvPasswordInput.svelte'
@@ -36,105 +21,211 @@
   import SvColorInput from './SvColorInput.svelte'
   import SvRating from './SvRating.svelte'
   import SvButton from './SvButton.svelte'
-  import { runRules } from './validators'
+  import SvStepper from './SvStepper.svelte'
+  import { isFormSection, type FormField, type FormEntry, type FormSection } from './form-field'
+  import { createForm } from './createForm.svelte'
 
   type Props = {
-    fields: ReadonlyArray<FormField>
+    fields: ReadonlyArray<FormEntry>
     initial?: Record<string, any>
-    onSubmit?: (values: Record<string, any>) => void
+    /** Called with the visible-field values on a valid submit. May be async -
+     *  the Submit button shows a loading state until it settles. */
+    onSubmit?: (values: Record<string, any>) => void | Promise<void>
     onChange?: (values: Record<string, any>) => void
+    /** When set, a secondary Cancel button renders next to Submit. */
+    onCancel?: () => void
     submitLabel?: string
-    /** Columns in the responsive field grid. */
+    cancelLabel?: string
+    /** Show a Reset button that restores the initial values. */
+    showReset?: boolean
+    resetLabel?: string
+    /** Render titled sections as a validated multi-step wizard (requires sections). */
+    stepper?: boolean
+    /** Columns in the responsive field grid (a section can override its own). */
     columns?: number
     disabled?: boolean
   }
 
-  let { fields, initial = {}, onSubmit, onChange, submitLabel = 'Submit', columns = 1, disabled = false }: Props = $props()
+  let {
+    fields, initial = {}, onSubmit, onChange, onCancel,
+    submitLabel = 'Submit', cancelLabel = 'Cancel', showReset = false, resetLabel = 'Reset',
+    stepper = false, columns = 1, disabled = false,
+  }: Props = $props()
 
-  let values = $state<Record<string, any>>({})
-  let errors = $state<Record<string, string>>({})
-  let touched = $state<Record<string, boolean>>({})
-  let seededForm = false
-  $effect(() => { if (!seededForm) { seededForm = true; values = { ...initial } } })
+  const form = createForm({ fields: () => fields, initial, onSubmit, onChange })
+  const submit = (e: Event) => { e.preventDefault(); form.submit() }
+  const dateVal = (v: any): Date | null => (v instanceof Date ? v : v ? new Date(v) : null)
 
-  function setValue(name: string, v: any) {
-    values = { ...values, [name]: v }
-    onChange?.(values)
-    if (touched[name]) validateField(name)
-  }
+  const sections = $derived(fields.filter(isFormSection) as FormSection[])
+  const wizard = $derived(stepper && sections.length > 0)
+  const stepItems = $derived(sections.map((s) => ({ label: s.section, description: s.description })))
 
-  function validateField(name: string): boolean {
-    const field = fields.find((f) => f.name === name)
-    if (!field) return true
-    const v = values[name]
-    let err: string | null | undefined = null
-    if (field.required && (v == null || v === '' || (Array.isArray(v) && !v.length))) err = `${field.label} is required`
-    if (!err && field.rules) err = runRules(v, field.rules, values)
-    if (!err && field.validate) err = field.validate(v, values)
-    const next = { ...errors }
-    if (err) next[name] = err
-    else delete next[name]
-    errors = next
-    return !err
+  let step = $state(0)
+  async function next() {
+    const s = sections[step]
+    if (!s) return
+    const ok = await form.validateFields(s.fields.map((f) => f.name))
+    if (ok && step < sections.length - 1) step += 1
   }
+  const back = () => { if (step > 0) step -= 1 }
 
-  function submit(e: Event) {
-    e.preventDefault()
-    let ok = true
-    const t: Record<string, boolean> = {}
-    for (const f of fields) { t[f.name] = true; if (!validateField(f.name)) ok = false }
-    touched = t
-    if (ok) onSubmit?.({ ...values })
+  // Shared shape passed to the `control` snippet so top-level fields and array
+  // item fields render the same set of controls without duplication.
+  type ControlOpts = {
+    id: string
+    type: string
+    label: string
+    value: any
+    onChange: (v: any) => void
+    onBlur?: () => void
+    disabled: boolean
+    placeholder?: string
+    options?: ReadonlyArray<{ value: string | number; label: string; color?: string }>
   }
-
-  const dateVal = (v: any): Date | null => (v instanceof Date ? v : v ? new Date(v) : null)
 </script>
 
-<form class="sv-form" style:--cols={columns} onsubmit={submit} novalidate>
-  <div class="sv-form__grid">
-    {#each fields as field (field.name)}
-      {@const type = field.type ?? 'text'}
-      <div class="sv-form__field" class:is-full={field.full || columns === 1} class:has-error={errors[field.name]}>
+{#snippet control(o: ControlOpts)}
+  {#if o.type === 'textarea'}
+    <textarea id={o.id} class="sv-form__control sv-form__textarea" rows="3" disabled={o.disabled} placeholder={o.placeholder} value={o.value ?? ''} oninput={(e) => o.onChange(e.currentTarget.value)} onblur={o.onBlur}></textarea>
+  {:else if o.type === 'number'}
+    <SvNumberInput value={o.value ?? null} disabled={o.disabled} onChange={o.onChange} />
+  {:else if o.type === 'password'}
+    <SvPasswordInput value={o.value ?? ''} disabled={o.disabled} onChange={o.onChange} />
+  {:else if o.type === 'select'}
+    <SvDropDownList options={o.options ?? []} value={o.value ?? null} disabled={o.disabled} placeholder={o.placeholder} onChange={o.onChange} />
+  {:else if o.type === 'checkbox'}
+    <SvCheckBox checked={!!o.value} disabled={o.disabled} onChange={o.onChange}>{o.label}</SvCheckBox>
+  {:else if o.type === 'switch'}
+    <div class="sv-form__inline"><SvSwitchButton checked={!!o.value} disabled={o.disabled} onChange={o.onChange} ariaLabel={o.label} /><span>{o.label}</span></div>
+  {:else if o.type === 'date'}
+    <SvDateTimePicker value={dateVal(o.value)} dropDownDisplayMode="calendar" formatString="yyyy-MM-dd" disabled={o.disabled} onChange={o.onChange} />
+  {:else if o.type === 'color'}
+    <SvColorInput value={o.value ?? '#3b82f6'} disabled={o.disabled} onChange={o.onChange} />
+  {:else if o.type === 'rating'}
+    <SvRating value={o.value ?? 0} disabled={o.disabled} onChange={o.onChange} />
+  {:else}
+    <input id={o.id} class="sv-form__control" type={o.type} disabled={o.disabled} placeholder={o.placeholder} value={o.value ?? ''} oninput={(e) => o.onChange(e.currentTarget.value)} onblur={o.onBlur} />
+  {/if}
+{/snippet}
+
+{#snippet renderItemField(arrayName: string, i: number, itf: FormField)}
+  {@const type = itf.type ?? 'text'}
+  {@const id = `f-${arrayName}-${i}-${itf.name}`}
+  {@const err = form.itemError(arrayName, i, itf.name)}
+  <div class="sv-form__field" class:has-error={err}>
+    {#if type !== 'checkbox' && type !== 'switch'}
+      <label class="sv-form__label" for={id}>{itf.label}{#if itf.required}<span class="sv-form__req" aria-hidden="true"> *</span>{/if}</label>
+    {/if}
+    {@render control({ id, type, label: itf.label, value: form.itemValue(arrayName, i, itf.name), onChange: (v) => form.setItemValue(arrayName, i, itf.name, v), onBlur: () => form.handleItemBlur(arrayName, i, itf.name), disabled, placeholder: itf.placeholder, options: itf.options })}
+    {#if err}<span class="sv-form__error" role="alert">{err}</span>{/if}
+  </div>
+{/snippet}
+
+{#snippet renderArray(field: FormField)}
+  <div class="sv-form__field is-full sv-form__array" class:has-error={form.error(field.name)}>
+    <label class="sv-form__label">{field.label}{#if field.required}<span class="sv-form__req" aria-hidden="true"> *</span>{/if}</label>
+    {#each form.arrayItems(field.name) as _item, i (i)}
+      <div class="sv-form__arow">
+        <div class="sv-form__grid" style:--cols={field.itemFields?.length ?? 1}>
+          {#each field.itemFields ?? [] as itf (itf.name)}{@render renderItemField(field.name, i, itf)}{/each}
+        </div>
+        <button type="button" class="sv-form__aremove" disabled={disabled} onclick={() => form.removeItem(field.name, i)} aria-label="Remove item">&times;</button>
+      </div>
+    {/each}
+    <div><SvButton type="button" variant="outline" size="sm" disabled={disabled} onclick={() => form.addItem(field.name)}>{field.addLabel ?? '+ Add'}</SvButton></div>
+    {#if form.error(field.name)}<span class="sv-form__error" role="alert">{form.error(field.name)}</span>{/if}
+  </div>
+{/snippet}
+
+{#snippet renderField(field: FormField, cols: number)}
+  {#if form.isVisible(field.name)}
+    {@const type = field.type ?? 'text'}
+    {#if type === 'array'}
+      {@render renderArray(field)}
+    {:else}
+      {@const fieldDisabled = disabled || form.isDisabled(field.name)}
+      <div class="sv-form__field" class:is-full={field.full || cols === 1} class:has-error={form.error(field.name)}>
         {#if type !== 'checkbox' && type !== 'switch'}
           <label class="sv-form__label" for={`f-${field.name}`}>
             {field.label}{#if field.required}<span class="sv-form__req" aria-hidden="true"> *</span>{/if}
           </label>
         {/if}
-
-        {#if type === 'textarea'}
-          <textarea id={`f-${field.name}`} class="sv-form__control sv-form__textarea" rows="3" {disabled} placeholder={field.placeholder} value={values[field.name] ?? ''} oninput={(e) => setValue(field.name, e.currentTarget.value)} onblur={() => { touched[field.name] = true; validateField(field.name) }}></textarea>
-        {:else if type === 'number'}
-          <SvNumberInput value={values[field.name] ?? null} {disabled} onChange={(v) => setValue(field.name, v)} />
-        {:else if type === 'password'}
-          <SvPasswordInput value={values[field.name] ?? ''} {disabled} onChange={(v) => setValue(field.name, v)} />
-        {:else if type === 'select'}
-          <SvDropDownList options={field.options ?? []} value={values[field.name] ?? null} {disabled} placeholder={field.placeholder} onChange={(v) => setValue(field.name, v)} />
-        {:else if type === 'checkbox'}
-          <SvCheckBox checked={!!values[field.name]} {disabled} onChange={(v) => setValue(field.name, v)}>{field.label}</SvCheckBox>
-        {:else if type === 'switch'}
-          <div class="sv-form__inline"><SvSwitchButton checked={!!values[field.name]} {disabled} onChange={(v) => setValue(field.name, v)} ariaLabel={field.label} /><span>{field.label}</span></div>
-        {:else if type === 'date'}
-          <SvDateTimePicker value={dateVal(values[field.name])} dropDownDisplayMode="calendar" formatString="yyyy-MM-dd" {disabled} onChange={(v) => setValue(field.name, v)} />
-        {:else if type === 'color'}
-          <SvColorInput value={values[field.name] ?? '#3b82f6'} {disabled} onChange={(v) => setValue(field.name, v)} />
-        {:else if type === 'rating'}
-          <SvRating value={values[field.name] ?? 0} {disabled} onChange={(v) => setValue(field.name, v)} />
-        {:else}
-          <input id={`f-${field.name}`} class="sv-form__control" type={type} {disabled} placeholder={field.placeholder} value={values[field.name] ?? ''} oninput={(e) => setValue(field.name, e.currentTarget.value)} onblur={() => { touched[field.name] = true; validateField(field.name) }} />
+        {@render control({ id: `f-${field.name}`, type, label: field.label, value: form.value(field.name), onChange: (v) => form.setValue(field.name, v), onBlur: () => form.handleBlur(field.name), disabled: fieldDisabled, placeholder: field.placeholder, options: field.options })}
+        {#if form.error(field.name)}
+          <span class="sv-form__error" role="alert">{form.error(field.name)}</span>
+        {:else if form.isValidating(field.name)}
+          <span class="sv-form__checking" role="status"><span class="sv-form__spinner" aria-hidden="true"></span>Checking…</span>
         {/if}
-
-        {#if errors[field.name]}<span class="sv-form__error" role="alert">{errors[field.name]}</span>{/if}
       </div>
-    {/each}
+    {/if}
+  {/if}
+{/snippet}
+
+{#snippet grid(flds: ReadonlyArray<FormField>, cols: number)}
+  <div class="sv-form__grid" style:--cols={cols}>
+    {#each flds as field (field.name)}{@render renderField(field, cols)}{/each}
   </div>
+{/snippet}
+
+{#snippet actions()}
   <div class="sv-form__actions">
-    <SvButton type="submit" {disabled}>{submitLabel}</SvButton>
+    {#if showReset}
+      <SvButton type="button" variant="ghost" disabled={disabled || form.submitting} onclick={() => form.reset()}>{resetLabel}</SvButton>
+    {/if}
+    {#if onCancel}
+      <SvButton type="button" variant="secondary" disabled={disabled || form.submitting} onclick={onCancel}>{cancelLabel}</SvButton>
+    {/if}
+    <SvButton type="submit" loading={form.submitting} disabled={disabled || form.submitting}>{submitLabel}</SvButton>
   </div>
+{/snippet}
+
+<form class="sv-form" onsubmit={submit} novalidate>
+  {#if wizard}
+    {@const s = sections[Math.min(step, sections.length - 1)]!}
+    <SvStepper steps={stepItems} current={step} onChange={(n) => (step = n)} linear />
+    <fieldset class="sv-form__section">
+      {#if s.description}<p class="sv-form__section-desc">{s.description}</p>{/if}
+      {@render grid(s.fields, s.columns ?? columns)}
+    </fieldset>
+    <div class="sv-form__actions">
+      {#if step > 0}
+        <SvButton type="button" variant="secondary" disabled={form.submitting} onclick={back}>Back</SvButton>
+      {/if}
+      <span class="sv-form__spacer"></span>
+      {#if step < sections.length - 1}
+        <SvButton type="button" disabled={form.submitting} onclick={next}>Next</SvButton>
+      {:else}
+        {#if showReset}
+          <SvButton type="button" variant="ghost" disabled={disabled || form.submitting} onclick={() => { form.reset(); step = 0 }}>{resetLabel}</SvButton>
+        {/if}
+        <SvButton type="submit" loading={form.submitting} disabled={disabled || form.submitting}>{submitLabel}</SvButton>
+      {/if}
+    </div>
+  {:else if sections.length > 0}
+    {#each fields as entry (isFormSection(entry) ? entry.section : entry.name)}
+      {#if isFormSection(entry)}
+        <fieldset class="sv-form__section">
+          <legend class="sv-form__section-title">{entry.section}</legend>
+          {#if entry.description}<p class="sv-form__section-desc">{entry.description}</p>{/if}
+          {@render grid(entry.fields, entry.columns ?? columns)}
+        </fieldset>
+      {:else}
+        {@render grid([entry], columns)}
+      {/if}
+    {/each}
+    {@render actions()}
+  {:else}
+    {@render grid(fields as ReadonlyArray<FormField>, columns)}
+    {@render actions()}
+  {/if}
 </form>
 
 <style>
-  .sv-form { --_accent: var(--sg-accent, #2563eb); width: 100%; }
+  .sv-form { --_accent: var(--sg-accent, #2563eb); width: 100%; display: flex; flex-direction: column; gap: 16px; }
   .sv-form__grid { display: grid; grid-template-columns: repeat(var(--cols, 1), minmax(0, 1fr)); gap: 14px 18px; }
+  .sv-form__section { border: 1px solid var(--sg-border, #e2e8f0); border-radius: 10px; padding: 16px; margin: 0; min-inline-size: 0; }
+  .sv-form__section-title { font-size: 13px; font-weight: 700; color: var(--sg-fg, #0f172a); padding: 0 4px; }
+  .sv-form__section-desc { margin: 0 0 12px; font-size: 12px; color: var(--sg-muted, #64748b); }
   .sv-form__field { display: flex; flex-direction: column; gap: 5px; }
   .sv-form__field.is-full { grid-column: 1 / -1; }
   .sv-form__label { font-size: 12.5px; font-weight: 600; color: var(--sg-fg, #0f172a); }
@@ -149,5 +240,24 @@
   .sv-form__field.has-error .sv-form__control { border-color: var(--sg-danger, #dc2626); }
   .sv-form__inline { display: flex; align-items: center; gap: 8px; font-size: 13px; }
   .sv-form__error { font-size: 11.5px; color: var(--sg-danger, #dc2626); }
-  .sv-form__actions { margin-top: 16px; }
+  .sv-form__checking { display: inline-flex; align-items: center; gap: 5px; font-size: 11.5px; color: var(--sg-muted, #64748b); }
+  .sv-form__spinner {
+    width: 11px; height: 11px; border-radius: 50%;
+    border: 2px solid color-mix(in srgb, var(--_accent) 30%, transparent);
+    border-top-color: var(--_accent); animation: sv-form-spin 0.6s linear infinite;
+  }
+  @keyframes sv-form-spin { to { transform: rotate(360deg); } }
+  @media (prefers-reduced-motion: reduce) { .sv-form__spinner { animation: none; } }
+  .sv-form__actions { display: flex; align-items: center; justify-content: flex-end; gap: 8px; }
+  .sv-form__spacer { flex: 1; }
+  .sv-form__array { gap: 8px; }
+  .sv-form__arow { display: flex; align-items: flex-start; gap: 8px; }
+  .sv-form__arow > .sv-form__grid { flex: 1; padding: 10px; border: 1px solid var(--sg-border, #e2e8f0); border-radius: 8px; }
+  .sv-form__aremove {
+    flex: none; width: 28px; height: 28px; margin-top: 10px; border-radius: 6px; cursor: pointer;
+    border: 1px solid var(--sg-border, #cbd5e1); background: var(--sg-input-bg, #fff);
+    color: var(--sg-muted, #64748b); font-size: 16px; line-height: 1;
+  }
+  .sv-form__aremove:hover:not(:disabled) { color: var(--sg-danger, #dc2626); border-color: var(--sg-danger, #dc2626); }
+  .sv-form__aremove:disabled { opacity: 0.5; cursor: default; }
 </style>

package/src/SvForm.test.ts

@@ -0,0 +1,299 @@
+/**
+ * Component tests for SvForm, exercising the shared createForm core: required +
+ * custom validation block submit and surface errors, a valid form submits its
+ * values, and onChange fires on edits.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { mount, unmount, flushSync } from 'svelte'
+import SvForm from './SvForm.svelte'
+
+function mountForm(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvForm, { target, props: props as any })
+  flushSync()
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+const submitForm = (target: HTMLElement) => {
+  target.querySelector('form.sv-form')!.dispatchEvent(new Event('submit', { cancelable: true, bubbles: true }))
+  flushSync()
+}
+const setInput = (target: HTMLElement, id: string, value: string) => {
+  const el = target.querySelector<HTMLInputElement>(`#${id}`)!
+  el.value = value
+  el.dispatchEvent(new Event('input', { bubbles: true }))
+  flushSync()
+}
+const tick = async () => { await new Promise((r) => setTimeout(r)); flushSync() }
+const byText = (target: HTMLElement, text: string) =>
+  [...target.querySelectorAll('button')].find((b) => b.textContent?.trim() === text)!
+
+const fields = [
+  { name: 'name', label: 'Name', required: true },
+  { name: 'email', label: 'Email', type: 'email' as const,
+    validate: (v: any) => (v && !String(v).includes('@') ? 'Invalid email' : null) },
+]
+
+describe('SvForm', () => {
+  it('blocks submit and shows an error when a required field is empty', () => {
+    const onSubmit = vi.fn()
+    const { target, destroy } = mountForm({ fields, onSubmit })
+    try {
+      submitForm(target)
+      expect(onSubmit).not.toHaveBeenCalled()
+      const err = target.querySelector('.sv-form__error[role="alert"]')
+      expect(err?.textContent).toContain('Name is required')
+    } finally { destroy() }
+  })
+
+  it('submits the collected values when valid', () => {
+    const onSubmit = vi.fn()
+    const { target, destroy } = mountForm({ fields, onSubmit })
+    try {
+      setInput(target, 'f-name', 'Ada')
+      submitForm(target)
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+      expect(onSubmit.mock.calls[0]![0]).toMatchObject({ name: 'Ada' })
+    } finally { destroy() }
+  })
+
+  it('runs a custom validator', () => {
+    const onSubmit = vi.fn()
+    const { target, destroy } = mountForm({ fields, onSubmit })
+    try {
+      setInput(target, 'f-name', 'Ada')
+      setInput(target, 'f-email', 'nope')
+      submitForm(target)
+      expect(onSubmit).not.toHaveBeenCalled()
+      expect([...target.querySelectorAll('.sv-form__error')].some((e) => e.textContent?.includes('Invalid email'))).toBe(true)
+    } finally { destroy() }
+  })
+
+  it('fires onChange as fields are edited', () => {
+    const onChange = vi.fn()
+    const { target, destroy } = mountForm({ fields, onChange })
+    try {
+      setInput(target, 'f-name', 'A')
+      expect(onChange).toHaveBeenCalled()
+      expect(onChange.mock.calls.at(-1)![0]).toMatchObject({ name: 'A' })
+    } finally { destroy() }
+  })
+})
+
+describe('SvForm - conditional fields', () => {
+  const flds = [
+    { name: 'kind', label: 'Kind' },
+    { name: 'other', label: 'Other', required: true, visible: (v: any) => v.kind === 'x' },
+  ]
+
+  it('hides a field until its condition is met, and excludes hidden fields from validation + submit', () => {
+    const onSubmit = vi.fn()
+    const { target, destroy } = mountForm({ fields: flds, initial: { kind: '' }, onSubmit })
+    try {
+      // 'other' is hidden -> not rendered
+      expect(target.querySelector('#f-other')).toBeNull()
+      // ...and its `required` does not block submit; it's absent from the payload
+      setInput(target, 'f-kind', 'y')
+      submitForm(target)
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+      expect(onSubmit.mock.calls[0]![0]).not.toHaveProperty('other')
+      // Meeting the condition reveals the field
+      setInput(target, 'f-kind', 'x')
+      expect(target.querySelector('#f-other')).not.toBeNull()
+      // Now visible + required + empty -> blocks submit
+      onSubmit.mockClear()
+      submitForm(target)
+      expect(onSubmit).not.toHaveBeenCalled()
+    } finally { destroy() }
+  })
+
+  it('derives a field disabled state from other values', () => {
+    const dflds = [
+      { name: 'lock', label: 'Lock', type: 'switch' as const },
+      { name: 'note', label: 'Note', disabled: (v: any) => !!v.lock },
+    ]
+    const { target, destroy } = mountForm({ fields: dflds, initial: { lock: true } })
+    try {
+      expect(target.querySelector<HTMLInputElement>('#f-note')!.disabled).toBe(true)
+    } finally { destroy() }
+  })
+})
+
+describe('SvForm - reset + async submit', () => {
+  it('reset restores the initial values', () => {
+    const { target, destroy } = mountForm({ fields: [{ name: 'name', label: 'Name' }], initial: { name: 'Ada' }, showReset: true })
+    try {
+      setInput(target, 'f-name', 'Grace')
+      expect(target.querySelector<HTMLInputElement>('#f-name')!.value).toBe('Grace')
+      const reset = [...target.querySelectorAll('button')].find((b) => b.textContent?.trim() === 'Reset')!
+      reset.click(); flushSync()
+      expect(target.querySelector<HTMLInputElement>('#f-name')!.value).toBe('Ada')
+    } finally { destroy() }
+  })
+
+  it('disables the submit button while an async onSubmit is in flight', async () => {
+    let release: () => void = () => {}
+    const gate = new Promise<void>((r) => { release = r })
+    const onSubmit = vi.fn(() => gate)
+    const { target, destroy } = mountForm({ fields: [{ name: 'name', label: 'Name' }], initial: { name: 'Ada' }, onSubmit })
+    try {
+      submitForm(target)
+      const btn = target.querySelector<HTMLButtonElement>('button[type="submit"]')!
+      expect(btn.disabled).toBe(true) // submitting
+      release()
+      await gate; await Promise.resolve(); await Promise.resolve(); flushSync()
+      expect(btn.disabled).toBe(false)
+    } finally { destroy() }
+  })
+})
+
+describe('SvForm - async validation', () => {
+  const flush = async () => { await new Promise((r) => setTimeout(r)); flushSync() }
+
+  it('async validator blocks submit on error and passes once it clears', async () => {
+    const onSubmit = vi.fn()
+    const check = vi.fn(async (v: string) => (v === 'taken' ? 'Already taken' : null))
+    const flds = [{ name: 'user', label: 'User', asyncValidate: check, asyncDebounce: 0 }]
+    const { target, destroy } = mountForm({ fields: flds, initial: { user: 'taken' }, onSubmit })
+    try {
+      submitForm(target)
+      await flush()
+      expect(onSubmit).not.toHaveBeenCalled()
+      expect([...target.querySelectorAll('.sv-form__error')].some((e) => e.textContent?.includes('Already taken'))).toBe(true)
+      setInput(target, 'f-user', 'free')
+      submitForm(target)
+      await flush()
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+    } finally { destroy() }
+  })
+
+  it('shows a checking indicator while an async validator runs, then clears', async () => {
+    let resolve: (m: string | null) => void = () => {}
+    const check = () => new Promise<string | null>((r) => { resolve = r })
+    const flds = [{ name: 'user', label: 'User', asyncValidate: check, asyncDebounce: 0 }]
+    const { target, destroy } = mountForm({ fields: flds, initial: { user: 'x' } })
+    try {
+      target.querySelector('#f-user')!.dispatchEvent(new Event('blur', { bubbles: true }))
+      flushSync()
+      await flush() // debounce timer fires -> runAsync -> validating
+      expect(target.querySelector('.sv-form__checking')).not.toBeNull()
+      resolve(null)
+      await flush()
+      expect(target.querySelector('.sv-form__checking')).toBeNull()
+    } finally { destroy() }
+  })
+
+  it('drops a stale async response (only the latest wins)', async () => {
+    const resolvers: Array<(m: string | null) => void> = []
+    const check = () => new Promise<string | null>((r) => resolvers.push(r))
+    const flds = [{ name: 'user', label: 'User', asyncValidate: check, asyncDebounce: 0 }]
+    const { target, destroy } = mountForm({ fields: flds, initial: { user: '' } })
+    try {
+      target.querySelector('#f-user')!.dispatchEvent(new Event('blur', { bubbles: true }))
+      flushSync()
+      setInput(target, 'f-user', 'a')
+      await flush() // run #1 (resolvers[0])
+      setInput(target, 'f-user', 'ab')
+      await flush() // run #2 (resolvers[1])
+      resolvers[1]?.(null)        // latest resolves clean
+      resolvers[0]?.('stale err') // earlier resolves with an error - must be ignored
+      await flush()
+      expect(target.querySelectorAll('.sv-form__error').length).toBe(0)
+    } finally { destroy() }
+  })
+})
+
+describe('SvForm - sections', () => {
+  const schema = [
+    { section: 'Account', fields: [{ name: 'user', label: 'User', required: true }] },
+    { section: 'Profile', description: 'About you', fields: [{ name: 'bio', label: 'Bio', type: 'textarea' as const }] },
+  ]
+
+  it('renders sections as fieldsets with legends, showing all fields', () => {
+    const { target, destroy } = mountForm({ fields: schema })
+    try {
+      expect(target.querySelectorAll('fieldset.sv-form__section').length).toBe(2)
+      expect([...target.querySelectorAll('legend')].map((l) => l.textContent?.trim())).toEqual(['Account', 'Profile'])
+      expect(target.querySelector('#f-user')).not.toBeNull()
+      expect(target.querySelector('#f-bio')).not.toBeNull()
+    } finally { destroy() }
+  })
+})
+
+describe('SvForm - stepper wizard', () => {
+  const schema = [
+    { section: 'Step 1', fields: [{ name: 'user', label: 'User', required: true }] },
+    { section: 'Step 2', fields: [{ name: 'bio', label: 'Bio' }] },
+  ]
+
+  it('shows one step, gates Next on validation, reveals Submit on the last step', async () => {
+    const onSubmit = vi.fn()
+    const { target, destroy } = mountForm({ fields: schema, stepper: true, onSubmit })
+    try {
+      // Only step 1 is rendered
+      expect(target.querySelector('#f-user')).not.toBeNull()
+      expect(target.querySelector('#f-bio')).toBeNull()
+      // Next is blocked while the required field is empty
+      byText(target, 'Next').click(); await tick()
+      expect(target.querySelector('#f-bio')).toBeNull()
+      expect(target.querySelector('.sv-form__error')?.textContent).toContain('User is required')
+      // Fill and advance
+      setInput(target, 'f-user', 'ada')
+      byText(target, 'Next').click(); await tick()
+      expect(target.querySelector('#f-bio')).not.toBeNull()
+      expect(target.querySelector('#f-user')).toBeNull()
+      // Last step: Submit is present and fires
+      expect(target.querySelector('button[type="submit"]')).not.toBeNull()
+      submitForm(target); await tick()
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+      expect(onSubmit.mock.calls[0]![0]).toMatchObject({ user: 'ada' })
+    } finally { destroy() }
+  })
+})
+
+describe('SvForm - field arrays', () => {
+  const schema = [
+    { name: 'contacts', label: 'Contacts', type: 'array' as const, required: true, itemFields: [
+      { name: 'name', label: 'Name', required: true },
+      { name: 'email', label: 'Email', type: 'email' as const },
+    ] },
+  ]
+
+  it('adds and removes item rows', () => {
+    const { target, destroy } = mountForm({ fields: schema, initial: { contacts: [] } })
+    try {
+      expect(target.querySelectorAll('.sv-form__arow').length).toBe(0)
+      byText(target, '+ Add').click(); flushSync()
+      expect(target.querySelectorAll('.sv-form__arow').length).toBe(1)
+      expect(target.querySelector('#f-contacts-0-name')).not.toBeNull()
+      byText(target, '+ Add').click(); flushSync()
+      expect(target.querySelectorAll('.sv-form__arow').length).toBe(2)
+      ;(target.querySelectorAll<HTMLButtonElement>('.sv-form__aremove')[0]!).click(); flushSync()
+      expect(target.querySelectorAll('.sv-form__arow').length).toBe(1)
+    } finally { destroy() }
+  })
+
+  it('validates item fields and includes the array in the submitted payload', async () => {
+    const onSubmit = vi.fn()
+    const { target, destroy } = mountForm({ fields: schema, initial: { contacts: [{ name: '', email: '' }] }, onSubmit })
+    try {
+      submitForm(target); await tick()
+      expect(onSubmit).not.toHaveBeenCalled()
+      expect([...target.querySelectorAll('.sv-form__error')].some((e) => e.textContent?.includes('Name is required'))).toBe(true)
+      setInput(target, 'f-contacts-0-name', 'Ada')
+      submitForm(target); await tick()
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+      expect(onSubmit.mock.calls[0]![0].contacts).toEqual([{ name: 'Ada', email: '' }])
+    } finally { destroy() }
+  })
+
+  it('array `required` blocks submit when empty', async () => {
+    const onSubmit = vi.fn()
+    const { target, destroy } = mountForm({ fields: schema, initial: { contacts: [] }, onSubmit })
+    try {
+      submitForm(target); await tick()
+      expect(onSubmit).not.toHaveBeenCalled()
+      expect([...target.querySelectorAll('.sv-form__error')].some((e) => e.textContent?.includes('Contacts is required'))).toBe(true)
+    } finally { destroy() }
+  })
+})