@svgrid/grid 2.2.16 → 2.2.17

package/src/SvForm.svelte

@@ -12,18 +12,30 @@
    * a flat `FormField[]` or mix in titled `FormSection`s; with `stepper` the
    * sections become a validated wizard. Emits `onSubmit(values)` only when valid.
    */
+  import { untrack } from 'svelte'
   import SvNumberInput from './SvNumberInput.svelte'
   import SvPasswordInput from './SvPasswordInput.svelte'
   import SvDropDownList from './SvDropDownList.svelte'
+  import SvMultiSelect from './SvMultiSelect.svelte'
   import SvCheckBox from './SvCheckBox.svelte'
   import SvSwitchButton from './SvSwitchButton.svelte'
   import SvDateTimePicker from './SvDateTimePicker.svelte'
   import SvColorInput from './SvColorInput.svelte'
   import SvRating from './SvRating.svelte'
+  import SvRadioGroup from './SvRadioGroup.svelte'
+  import SvSlider from './SvSlider.svelte'
+  import SvTagsInput from './SvTagsInput.svelte'
+  import SvPhoneInput from './SvPhoneInput.svelte'
+  import SvCountryInput from './SvCountryInput.svelte'
+  import SvMaskedInput from './SvMaskedInput.svelte'
+  import SvComboBox from './SvComboBox.svelte'
+  import SvFileUpload from './SvFileUpload.svelte'
   import SvButton from './SvButton.svelte'
   import SvStepper from './SvStepper.svelte'
+  import SvTabs from './SvTabs.svelte'
   import { isFormSection, type FormField, type FormEntry, type FormSection } from './form-field'
-  import { createForm } from './createForm.svelte'
+  import { createForm, type FormMessages } from './createForm.svelte'
+  import type { EditorDir } from './editor-contract'
 
   type Props = {
     fields: ReadonlyArray<FormEntry>
@@ -41,25 +53,97 @@
     resetLabel?: string
     /** Render titled sections as a validated multi-step wizard (requires sections). */
     stepper?: boolean
+    /** Render titled sections as tabs (requires sections; ignored with `stepper`). */
+    tabs?: boolean
     /** Columns in the responsive field grid (a section can override its own). */
     columns?: number
     disabled?: boolean
+    /** Inject server-side errors (`{ field: message }`); applied reactively. */
+    serverErrors?: Record<string, string>
+    /** A form-level error message shown in a banner above the fields. */
+    formError?: string
+    /** Show a summary of field errors (with focus links) above the form after a
+     *  failed submit. */
+    errorSummary?: boolean
+    /** Heading for the error summary. Default "Please fix the following:". */
+    errorSummaryTitle?: string
+    /**
+     * Re-seed the form when the `initial` object identity changes (e.g. editing a
+     * different record). `off` (default) seeds once; `always` re-seeds on every
+     * change; `ifPristine` re-seeds only when the user has no unsaved edits.
+     */
+    reinitialize?: 'off' | 'always' | 'ifPristine'
+    /** Text direction; `rtl` mirrors the form layout. */
+    dir?: EditorDir
+    /** Override the built-in generated strings (required / min-max items / checking). */
+    messages?: Partial<FormMessages>
   }
 
   let {
     fields, initial = {}, onSubmit, onChange, onCancel,
     submitLabel = 'Submit', cancelLabel = 'Cancel', showReset = false, resetLabel = 'Reset',
-    stepper = false, columns = 1, disabled = false,
+    stepper = false, tabs = false, columns = 1, disabled = false,
+    serverErrors, formError, errorSummary = false, errorSummaryTitle = 'Please fix the following:',
+    reinitialize = 'off', dir, messages,
   }: Props = $props()
 
-  const form = createForm({ fields: () => fields, initial, onSubmit, onChange })
-  const submit = (e: Event) => { e.preventDefault(); form.submit() }
+  const resolvedDir = $derived(dir === 'ltr' || dir === 'rtl' ? dir : undefined)
+  const form = createForm({ fields: () => fields, initial, onSubmit, onChange, messages })
+  async function submit(e: Event) {
+    e.preventDefault()
+    const ok = await form.submit()
+    // In tabs mode, surface the first tab that has an error so it is not hidden.
+    if (!ok && tabbed) {
+      const first = form.firstErrorField()
+      const s = first ? sections.find((sec) => sec.fields.some((f) => f.name === first)) : undefined
+      if (s) activeTab = s.section
+    }
+  }
+
+  let formEl = $state<HTMLFormElement | null>(null)
+  // Apply server-side errors reactively (e.g. after a failed API submit). The
+  // write is untracked so reading `errors` inside setErrors does not make this
+  // effect depend on (and re-run from) its own write.
+  $effect(() => {
+    const se = serverErrors
+    if (se) untrack(() => form.setErrors(se))
+  })
+
+  // Opt-in re-seed when the `initial` identity changes. Only `initial` is tracked
+  // (read outside `untrack`); the isDirty check + reset run untracked so this
+  // never re-fires from its own writes.
+  let seeded = false
+  $effect(() => {
+    const init = initial
+    untrack(() => {
+      if (!seeded) { seeded = true; return } // the seed-once mount pass
+      if (reinitialize === 'off') return
+      if (reinitialize === 'ifPristine' && form.isDirty) return
+      form.reset(init)
+    })
+  })
+
+  const summaryItems = $derived(errorSummary ? form.errorList() : [])
+  function focusField(name: string) {
+    const wrap = formEl?.querySelector<HTMLElement>(`[data-field="${name}"]`)
+    wrap?.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+    wrap?.querySelector<HTMLElement>('input, select, textarea, button, [tabindex]')?.focus()
+  }
   const dateVal = (v: any): Date | null => (v instanceof Date ? v : v ? new Date(v) : null)
+  // Resolve a field's options, running the function form (cascading) against the
+  // live values so a child list updates when its parent changes.
+  const resolveOptions = (field: FormField) =>
+    typeof field.options === 'function' ? field.options(form.values) : (field.options ?? [])
 
   const sections = $derived(fields.filter(isFormSection) as FormSection[])
   const wizard = $derived(stepper && sections.length > 0)
+  const tabbed = $derived(tabs && !stepper && sections.length > 0)
   const stepItems = $derived(sections.map((s) => ({ label: s.section, description: s.description })))
 
+  let activeTab = $state<string | undefined>(undefined)
+  const sectionHasError = (s: FormSection) => s.fields.some((f) => form.error(f.name))
+  const tabItems = $derived(sections.map((s) => ({ id: s.section, label: sectionHasError(s) ? `${s.section} ⚠` : s.section })))
+
   let step = $state(0)
   async function next() {
     const s = sections[step]
@@ -79,32 +163,57 @@
     onChange: (v: any) => void
     onBlur?: () => void
     disabled: boolean
+    readonly?: boolean
+    invalid?: boolean
+    describedby?: string
     placeholder?: string
     options?: ReadonlyArray<{ value: string | number; label: string; color?: string }>
+    /** The source field, for type-specific extras (mask, min/max, loadOptions...). */
+    field?: FormField
   }
 </script>
 
 {#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>
+    <textarea id={o.id} class="sv-form__control sv-form__textarea" rows="3" disabled={o.disabled} readonly={o.readonly} placeholder={o.placeholder} value={o.value ?? ''} aria-invalid={o.invalid ? 'true' : undefined} aria-describedby={o.describedby} 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} />
+    <SvNumberInput id={o.id} value={o.value ?? null} disabled={o.disabled} readonly={o.readonly} invalid={o.invalid} block min={o.field?.min ?? -Infinity} max={o.field?.max ?? Infinity} step={o.field?.step ?? 1} precision={o.field?.precision} prefix={o.field?.prefix ?? ''} suffix={o.field?.suffix ?? ''} onChange={o.onChange} />
   {:else if o.type === 'password'}
-    <SvPasswordInput value={o.value ?? ''} disabled={o.disabled} onChange={o.onChange} />
+    <SvPasswordInput id={o.id} value={o.value ?? ''} disabled={o.disabled} readonly={o.readonly} invalid={o.invalid} block onChange={o.onChange} />
+  {:else if o.type === 'mask'}
+    <SvMaskedInput id={o.id} value={o.value ?? ''} mask={o.field?.mask ?? ''} disabled={o.disabled} readonly={o.readonly} invalid={o.invalid} block placeholder={o.placeholder} onChange={(m) => o.onChange(m)} />
+  {:else if o.type === 'phone'}
+    <SvPhoneInput id={o.id} value={o.value ?? ''} disabled={o.disabled} invalid={o.invalid} block placeholder={o.placeholder} onChange={(v) => o.onChange(v)} />
+  {:else if o.type === 'country'}
+    <SvCountryInput id={o.id} value={o.value ?? null} disabled={o.disabled} invalid={o.invalid} 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} />
+    <SvDropDownList id={o.id} options={o.options ?? []} value={o.value ?? null} disabled={o.disabled} readonly={o.readonly} invalid={o.invalid} placeholder={o.placeholder} onChange={o.onChange} />
+  {:else if o.type === 'combobox'}
+    <SvComboBox id={o.id} options={o.options ?? []} value={o.value ?? null} disabled={o.disabled} readonly={o.readonly} invalid={o.invalid} clearable placeholder={o.placeholder} loadOptions={o.field?.loadOptions ? (q) => o.field!.loadOptions!(q, form.values) : undefined} onChange={o.onChange} />
+  {:else if o.type === 'multiselect'}
+    <SvMultiSelect id={o.id} options={o.options ?? []} value={Array.isArray(o.value) ? o.value : []} disabled={o.disabled} readonly={o.readonly} invalid={o.invalid} placeholder={o.placeholder} onChange={o.onChange} />
+  {:else if o.type === 'radio'}
+    <SvRadioGroup id={o.id} options={o.options ?? []} value={o.value ?? null} disabled={o.disabled} readonly={o.readonly} invalid={o.invalid} orientation="horizontal" onChange={o.onChange} />
+  {:else if o.type === 'tags'}
+    <SvTagsInput id={o.id} value={Array.isArray(o.value) ? o.value : []} disabled={o.disabled} invalid={o.invalid} placeholder={o.placeholder} onChange={o.onChange} />
+  {:else if o.type === 'slider'}
+    <SvSlider id={o.id} value={o.value ?? o.field?.min ?? 0} min={o.field?.min ?? 0} max={o.field?.max ?? 100} step={o.field?.step ?? 1} disabled={o.disabled} readonly={o.readonly} invalid={o.invalid} showValue onChange={o.onChange} />
   {:else if o.type === 'checkbox'}
-    <SvCheckBox checked={!!o.value} disabled={o.disabled} onChange={o.onChange}>{o.label}</SvCheckBox>
+    <SvCheckBox checked={!!o.value} disabled={o.disabled} readonly={o.readonly} invalid={o.invalid} 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>
+    <div class="sv-form__inline"><SvSwitchButton checked={!!o.value} disabled={o.disabled} readonly={o.readonly} 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 === 'datetime'}
+    <SvDateTimePicker value={dateVal(o.value)} dropDownDisplayMode="both" disabled={o.disabled} onChange={o.onChange} />
   {:else if o.type === 'color'}
-    <SvColorInput value={o.value ?? '#3b82f6'} disabled={o.disabled} onChange={o.onChange} />
+    <SvColorInput id={o.id} value={o.value ?? '#3b82f6'} disabled={o.disabled} invalid={o.invalid} onChange={o.onChange} />
+  {:else if o.type === 'file'}
+    <SvFileUpload accept={o.field?.accept} multiple={o.field?.multiple ?? false} onChange={o.onChange} />
   {:else if o.type === 'rating'}
-    <SvRating value={o.value ?? 0} disabled={o.disabled} onChange={o.onChange} />
+    <SvRating id={o.id} value={o.value ?? 0} disabled={o.disabled} readonly={o.readonly} invalid={o.invalid} 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} />
+    <input id={o.id} class="sv-form__control" type={o.type} disabled={o.disabled} readonly={o.readonly} placeholder={o.placeholder} value={o.value ?? ''} aria-invalid={o.invalid ? 'true' : undefined} aria-describedby={o.describedby} oninput={(e) => o.onChange(e.currentTarget.value)} onblur={o.onBlur} />
   {/if}
 {/snippet}
 
@@ -116,12 +225,13 @@
     {#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}
+    {@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, readonly: itf.readonly, invalid: !!err, describedby: err ? `${id}__error` : undefined, placeholder: itf.placeholder, options: resolveOptions(itf), field: itf })}
+    {#if err}<span class="sv-form__error" id={`${id}__error`} role="alert">{err}</span>{/if}
   </div>
 {/snippet}
 
 {#snippet renderArray(field: FormField)}
+  {@const count = form.arrayItems(field.name).length}
   <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)}
@@ -129,7 +239,15 @@
         <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 class="sv-form__arow-tools">
+          {#if count > 1}
+            <div class="sv-form__amove">
+              <button type="button" class="sv-form__amove-btn" disabled={disabled || i === 0} onclick={() => form.moveItem(field.name, i, i - 1)} aria-label="Move up" title="Move up">&#8593;</button>
+              <button type="button" class="sv-form__amove-btn" disabled={disabled || i === count - 1} onclick={() => form.moveItem(field.name, i, i + 1)} aria-label="Move down" title="Move down">&#8595;</button>
+            </div>
+          {/if}
+          <button type="button" class="sv-form__aremove" disabled={disabled} onclick={() => form.removeItem(field.name, i)} aria-label="Remove item">&times;</button>
+        </div>
       </div>
     {/each}
     <div><SvButton type="button" variant="outline" size="sm" disabled={disabled} onclick={() => form.addItem(field.name)}>{field.addLabel ?? '+ Add'}</SvButton></div>
@@ -144,17 +262,19 @@
       {@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)}>
+      <div class="sv-form__field" data-field={field.name} class:is-full={(field.full || (field.span ?? 1) >= cols) || cols === 1} class:has-error={form.error(field.name)} style:grid-column={field.span && field.span > 1 && field.span < cols ? `span ${field.span}` : undefined}>
         {#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}
-        {@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 })}
+        {@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, readonly: field.readonly || !!field.computed, invalid: !!form.error(field.name), describedby: form.error(field.name) ? `f-${field.name}__error` : undefined, placeholder: field.placeholder, options: resolveOptions(field), field })}
         {#if form.error(field.name)}
-          <span class="sv-form__error" role="alert">{form.error(field.name)}</span>
+          <span class="sv-form__error" id={`f-${field.name}__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>
+          <span class="sv-form__checking" role="status"><span class="sv-form__spinner" aria-hidden="true"></span>{form.messages.checking}</span>
+        {:else if field.help}
+          <span class="sv-form__help">{field.help}</span>
         {/if}
       </div>
     {/if}
@@ -179,7 +299,20 @@
   </div>
 {/snippet}
 
-<form class="sv-form" onsubmit={submit} novalidate>
+<form class="sv-form" bind:this={formEl} dir={resolvedDir} onsubmit={submit} novalidate>
+  {#if formError}
+    <div class="sv-form__banner" role="alert">{formError}</div>
+  {/if}
+  {#if errorSummary && summaryItems.length}
+    <div class="sv-form__summary" role="alert">
+      <p class="sv-form__summary-title">{errorSummaryTitle}</p>
+      <ul>
+        {#each summaryItems as it (it.name)}
+          <li><button type="button" class="sv-form__summary-link" onclick={() => focusField(it.name)}>{it.label}: {it.message}</button></li>
+        {/each}
+      </ul>
+    </div>
+  {/if}
   {#if wizard}
     {@const s = sections[Math.min(step, sections.length - 1)]!}
     <SvStepper steps={stepItems} current={step} onChange={(n) => (step = n)} linear />
@@ -201,6 +334,17 @@
         <SvButton type="submit" loading={form.submitting} disabled={disabled || form.submitting}>{submitLabel}</SvButton>
       {/if}
     </div>
+  {:else if tabbed}
+    <SvTabs tabs={tabItems} bind:value={activeTab} ariaLabel="Form sections">
+      {#snippet panel(id)}
+        {@const s = sections.find((sec) => sec.section === id)}
+        {#if s}
+          {#if s.description}<p class="sv-form__section-desc">{s.description}</p>{/if}
+          {@render grid(s.fields, s.columns ?? columns)}
+        {/if}
+      {/snippet}
+    </SvTabs>
+    {@render actions()}
   {:else if sections.length > 0}
     {#each fields as entry (isFormSection(entry) ? entry.section : entry.name)}
       {#if isFormSection(entry)}
@@ -240,6 +384,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__help { font-size: 11.5px; color: var(--sg-muted, #64748b); }
+  .sv-form__banner {
+    padding: 10px 12px; border-radius: 8px; font-size: 13px;
+    background: color-mix(in srgb, var(--sg-danger, #dc2626) 10%, transparent);
+    color: var(--sg-danger, #dc2626); border: 1px solid color-mix(in srgb, var(--sg-danger, #dc2626) 35%, transparent);
+  }
+  .sv-form__summary {
+    padding: 12px 14px; border-radius: 8px;
+    background: color-mix(in srgb, var(--sg-danger, #dc2626) 7%, transparent);
+    border: 1px solid color-mix(in srgb, var(--sg-danger, #dc2626) 30%, transparent);
+  }
+  .sv-form__summary-title { margin: 0 0 6px; font-size: 13px; font-weight: 700; color: var(--sg-danger, #dc2626); }
+  .sv-form__summary ul { margin: 0; padding-inline-start: 18px; display: flex; flex-direction: column; gap: 3px; }
+  .sv-form__summary-link {
+    background: none; border: 0; padding: 0; font: inherit; font-size: 12.5px; text-align: start;
+    color: var(--sg-danger, #dc2626); cursor: pointer; text-decoration: underline;
+  }
+  .sv-form__summary-link:hover { color: var(--sg-fg, #0f172a); }
   .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%;
@@ -260,4 +422,16 @@
   }
   .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; }
+  .sv-form__arow-tools { display: flex; align-items: center; gap: 4px; margin-top: 10px; }
+  .sv-form__amove { display: inline-flex; flex-direction: column; }
+  .sv-form__amove-btn {
+    width: 22px; height: 14px; display: grid; place-items: center; padding: 0; cursor: pointer;
+    border: 1px solid var(--sg-border, #cbd5e1); background: var(--sg-input-bg, #fff); color: var(--sg-muted, #64748b);
+    font-size: 10px; line-height: 1;
+  }
+  .sv-form__amove-btn:first-child { border-radius: 6px 6px 0 0; border-bottom: 0; }
+  .sv-form__amove-btn:last-child { border-radius: 0 0 6px 6px; }
+  .sv-form__amove-btn:hover:not(:disabled) { color: var(--sg-accent, #2563eb); }
+  .sv-form__amove-btn:disabled { opacity: 0.4; cursor: default; }
+  .sv-form__arow-tools .sv-form__aremove { margin-top: 0; }
 </style>

package/src/SvForm.test.ts

@@ -78,6 +78,79 @@ describe('SvForm', () => {
       expect(onChange.mock.calls.at(-1)![0]).toMatchObject({ name: 'A' })
     } finally { destroy() }
   })
+
+  it('renders an error summary after a failed submit', () => {
+    const { target, destroy } = mountForm({ fields, errorSummary: true })
+    try {
+      submitForm(target)
+      const summary = target.querySelector('.sv-form__summary[role="alert"]')
+      expect(summary).not.toBeNull()
+      const links = target.querySelectorAll('.sv-form__summary-link')
+      expect(links.length).toBeGreaterThan(0)
+      expect(links[0]!.textContent).toContain('is required')
+    } finally { destroy() }
+  })
+
+  it('applies serverErrors reactively', () => {
+    const { target, destroy } = mountForm({ fields, serverErrors: { name: 'Name already taken' } })
+    try {
+      expect([...target.querySelectorAll('.sv-form__error')].some((e) => e.textContent?.includes('already taken'))).toBe(true)
+    } finally { destroy() }
+  })
+
+  it('overrides the built-in required message and links the error via aria-describedby', () => {
+    const { target, destroy } = mountForm({ fields, messages: { required: (l: string) => `${l} manquant` } })
+    try {
+      submitForm(target)
+      const err = target.querySelector('#f-name__error')
+      expect(err?.textContent).toBe('Name manquant')
+      // aria wiring: the input points at the error id
+      expect(target.querySelector('#f-name')?.getAttribute('aria-describedby')).toBe('f-name__error')
+      expect(target.querySelector('#f-name')?.getAttribute('aria-invalid')).toBe('true')
+    } finally { destroy() }
+  })
+
+  it('mirrors dir onto the form element', () => {
+    const { target, destroy } = mountForm({ fields, dir: 'rtl' })
+    try {
+      expect(target.querySelector('form.sv-form')?.getAttribute('dir')).toBe('rtl')
+    } finally { destroy() }
+  })
+
+  it('computed fields derive their value, render read-only, and are in the payload', async () => {
+    const onSubmit = vi.fn()
+    const cf = [
+      { name: 'qty', label: 'Qty', type: 'number' as const },
+      { name: 'price', label: 'Price', type: 'number' as const },
+      { name: 'total', label: 'Total', type: 'text' as const, computed: (v: any) => (v.qty ?? 0) * (v.price ?? 0) },
+    ]
+    const { target, destroy } = mountForm({ fields: cf, initial: { qty: 3, price: 4 }, onSubmit })
+    try {
+      const totalInput = target.querySelector<HTMLInputElement>('#f-total')!
+      expect(totalInput.value).toBe('12')     // derived
+      expect(totalInput.readOnly).toBe(true)  // read-only
+      submitForm(target); await tick()
+      expect(onSubmit).toHaveBeenCalledTimes(1)
+      expect(onSubmit.mock.calls[0]![0].total).toBe(12) // computed value in payload
+    } finally { destroy() }
+  })
+
+  it('cascading: changing a parent clears fields that dependOn it (onChange payload)', () => {
+    const onChange = vi.fn()
+    const cf = [
+      { name: 'country', label: 'Country', options: [{ value: 'us', label: 'US' }, { value: 'ca', label: 'CA' }] },
+      { name: 'state', label: 'State', dependsOn: 'country', options: (v: any) => (v.country === 'us' ? [{ value: 'ny', label: 'NY' }] : []) },
+    ]
+    // country + state are plain text inputs here (default type) so we can drive them via the DOM.
+    const { target, destroy } = mountForm({ fields: cf, initial: { country: 'us', state: 'ny' }, onChange })
+    try {
+      setInput(target, 'f-country', 'ca')
+      // The last onChange payload has the parent updated AND the child cleared.
+      const last = onChange.mock.calls.at(-1)![0]
+      expect(last.country).toBe('ca')
+      expect(last.state).toBeNull()
+    } finally { destroy() }
+  })
 })
 
 describe('SvForm - conditional fields', () => {
@@ -251,6 +324,33 @@ describe('SvForm - stepper wizard', () => {
   })
 })
 
+describe('SvForm - tabs layout', () => {
+  const schema = [
+    { section: 'Profile', fields: [{ name: 'user', label: 'User', required: true }] },
+    { section: 'Bio', fields: [{ name: 'bio', label: 'Bio' }] },
+  ]
+
+  it('renders sections as tabs, one panel at a time; failed submit jumps to the erroring tab', async () => {
+    const onSubmit = vi.fn()
+    const { target, destroy } = mountForm({ fields: schema, tabs: true, onSubmit })
+    try {
+      const tabEls = target.querySelectorAll('[role="tab"]')
+      expect(tabEls.length).toBe(2)
+      // First tab active -> only its field is in the DOM
+      expect(target.querySelector('#f-user')).not.toBeNull()
+      expect(target.querySelector('#f-bio')).toBeNull()
+      // Switch to the Bio tab
+      ;[...target.querySelectorAll<HTMLElement>('[role="tab"]')].find((t) => t.textContent?.includes('Bio'))!.click()
+      flushSync()
+      expect(target.querySelector('#f-bio')).not.toBeNull()
+      // Submit with the required User empty -> blocked and jumps back to Profile
+      submitForm(target); await tick()
+      expect(onSubmit).not.toHaveBeenCalled()
+      expect(target.querySelector('#f-user')).not.toBeNull() // Profile tab is active again
+    } finally { destroy() }
+  })
+})
+
 describe('SvForm - field arrays', () => {
   const schema = [
     { name: 'contacts', label: 'Contacts', type: 'array' as const, required: true, itemFields: [
@@ -296,4 +396,16 @@ describe('SvForm - field arrays', () => {
       expect([...target.querySelectorAll('.sv-form__error')].some((e) => e.textContent?.includes('Contacts is required'))).toBe(true)
     } finally { destroy() }
   })
+
+  it('reorder buttons move an item up/down', () => {
+    const { target, destroy } = mountForm({ fields: schema, initial: { contacts: [{ name: 'A', email: '' }, { name: 'B', email: '' }] } })
+    try {
+      const nameVals = () => [...target.querySelectorAll<HTMLInputElement>('.sv-form__array [id$="-name"]')].map((i) => i.value)
+      expect(nameVals()).toEqual(['A', 'B'])
+      ;(target.querySelectorAll<HTMLButtonElement>('button[aria-label="Move down"]')[0]!).click(); flushSync()
+      expect(nameVals()).toEqual(['B', 'A'])
+      ;(target.querySelectorAll<HTMLButtonElement>('button[aria-label="Move up"]')[1]!).click(); flushSync()
+      expect(nameVals()).toEqual(['A', 'B'])
+    } finally { destroy() }
+  })
 })

package/src/SvGrid.controller.svelte.ts

@@ -10,7 +10,6 @@ import {
     createSortedRowModel,
     createSvGrid,
     getGridCellDomId,
-    rowsToChartSpec,
     sortFns,
     tableFeatures,
     rowSortingFeature,
@@ -94,6 +93,8 @@ import {
 import {
     createClipboard,
   } from "./clipboard";
+import { resolveGridMessages } from "./grid-messages";
+import { getPivotEngine, hasPivotEngine } from "./pivot-view.svelte";
 import {
     filterOperatorOptions,
     fallbackOperatorOption,
@@ -269,7 +270,28 @@ export type SvGridController<
 export function createSvGridController<
   TFeatures extends TableFeatures = TableFeatures,
   TData extends RowData = RowData,
->(props: Props<TFeatures, TData>) {
+>(rawProps: Props<TFeatures, TData>) {
+
+  // Runtime option overrides set via the imperative api (`api.setOption(key, value)`).
+  // Every controller read of a prop goes through the `props` proxy below (and the view
+  // reads controller-resolved gates like `_features` / `editingEnabled`, not the raw
+  // prop), so an override wins over the incoming prop and re-renders reactively -
+  // identical to the parent flipping that prop. A get-only Proxy (not a fresh spread)
+  // preserves reference identity for non-overridden keys, which the columns-identity
+  // column cache and the `data`/`columns` sync effects rely on.
+  let optionOverrides = $state<Record<string, unknown>>({});
+  const props = new Proxy(rawProps, {
+    // Read the override as a PROPERTY (tracked by `$state`), not via `in` (the `has`
+    // trap is not tracked) - so a reactive read of `props.X` re-runs when an override
+    // is set. `undefined` means "no override" and falls back to the incoming prop;
+    // `setOption(key, undefined)` clears by removing the key, which lands here as
+    // undefined too. Whole-object reassignment on write makes the signal fire.
+    get: (t, k) => {
+      const v =
+        typeof k === "string" ? optionOverrides[k] : undefined;
+      return v !== undefined ? v : Reflect.get(t, k);
+    },
+  }) as Props<TFeatures, TData>;
 
   // Resolved capability gates. Capabilities are OFF by default - a bare
   // grid is a plain read-only table, and each power feature is opted into
@@ -670,7 +692,8 @@ export function createSvGridController<
     state: {
       columnFilters: [],
       grouping: [],
-      sorting: [],
+      // svelte-ignore state_referenced_locally
+      sorting: props.initialSorting ?? [],
       // svelte-ignore state_referenced_locally
       pagination: { pageIndex: 0, pageSize: props.pageSize ?? 10 },
       rowSelection: {},
@@ -1092,12 +1115,12 @@ export function createSvGridController<
 
     let rows = rawRows;
     if (globalFilter.trim()) {
-      const needle = normalizeForFilter(globalFilter, props.filterLocale);
+      const needle = normalizeForFilter(globalFilter, (props.filterLocale ?? props.localization?.locale));
       rows = rows.filter((row) =>
         row
           .getAllCells()
           .some((cell) =>
-            normalizeForFilter(String(cell.getValue() ?? ""), props.filterLocale)
+            normalizeForFilter(String(cell.getValue() ?? ""), (props.filterLocale ?? props.localization?.locale))
               .includes(needle),
           ),
       );
@@ -1119,7 +1142,7 @@ export function createSvGridController<
       applyExcelFilter(
         cellValue,
         { id: columnId, operator: op, value, valueTo: op === "between" ? valueTo : undefined },
-        { locale: props.filterLocale },
+        { locale: (props.filterLocale ?? props.localization?.locale) },
       );
     // A column filter is active if either of its (up to two) conditions is.
     const menuFilters = Object.entries(filterMenuValues).filter(([_, f]) => {
@@ -1348,6 +1371,39 @@ export function createSvGridController<
     return c === true ? ({} as ChartingConfig<TData>) : (c as ChartingConfig<TData>);
   });
   const chartingEnabled = $derived(!!chartCfg);
+  // Resolved chrome messages (English defaults merged with `localeText`). One
+  // map every consumer (SvGrid.svelte, GridFooter, menus, filter labels) reads.
+  const gridMessages = $derived(resolveGridMessages(props.localization?.text));
+
+  // ---- In-grid pivot mode ----
+  // The pivot ENGINE ships in @svgrid/enterprise (registered via the pivot-view
+  // seam). When `pivot` is set and the engine is present, the grid runs it over
+  // the already filtered + sorted leaf rows and renders the pivot result in
+  // place. `pivotModeOn` is uncontrolled (seeded from the prop) so a toolbar
+  // toggle can flip between the pivot and the flat table over the same data.
+  const pivotConfig = $derived(props.pivot ?? null);
+  // Controlled when `pivotMode` prop is provided; otherwise internal state
+  // (seeded to on when `pivot` is set) drives it, flipped by the toolbar toggle.
+  let pivotModeInternal = $state(props.pivotMode ?? (props.pivot != null));
+  const pivotModeOn = $derived(props.pivotMode ?? pivotModeInternal);
+  function togglePivotMode(): void {
+    const next = !pivotModeOn;
+    pivotModeInternal = next;
+    props.onPivotModeChange?.(next);
+  }
+  const pivotActive = $derived(!!pivotConfig && pivotModeOn && hasPivotEngine());
+  const pivotResult = $derived.by(() => {
+    if (!pivotActive || !pivotConfig) return null;
+    const engine = getPivotEngine();
+    if (!engine) return null;
+    // Feed the pivot the filtered + sorted LEAF rows (drop any group rows); its
+    // output must not be re-run through the column-filter pipeline.
+    const leaves = allRowsBeforePagination
+      .filter((r) => !r.subRows)
+      .map((r) => r.original);
+    return engine(leaves, pivotConfig as never);
+  });
+
   const chartIsCustom = $derived(typeof chartCfg?.buildSpec === "function");
   const chartingConfig = $derived(
     chartCfg
@@ -1609,6 +1665,18 @@ export function createSvGridController<
     };
   };
 
+  // The chart derivation engine (rowsToChartSpec) is loaded lazily the first time
+  // charting is enabled, keeping chart.ts (~11 KB gzip) out of the base <SvGrid>
+  // bundle - it rides in the same lazy chunk as the chart panel. `chartSpec` stays
+  // null until it resolves, a tick after the panel itself starts loading (which it
+  // already does). The `getAggregate` server path uses the local bucketsToSpec and
+  // does not need the engine.
+  let chartEngine = $state<typeof import("./chart").rowsToChartSpec | null>(null);
+  $effect(() => {
+    if (chartingEnabled && !chartEngine)
+      import("./chart").then((m) => (chartEngine = m.rowsToChartSpec));
+  });
+
   const chartSpec = $derived.by<ChartSpec | null>(() => {
     if (!chartingEnabled || !chartCfg) return null;
     if (chartCfg.getAggregate) {
@@ -1627,9 +1695,11 @@ export function createSvGridController<
     const category = fieldOf(effectiveChartDimensionId);
     const values = effectiveChartMeasureIds.map((id) => fieldOf(id)).filter((f): f is string => !!f);
     if (!category || !values.length) return null;
+    // Engine not loaded yet (lazy): render nothing until it resolves.
+    if (!chartEngine) return null;
     const seriesField = fieldOf(effectiveChartSeriesId);
 
-    const spec = rowsToChartSpec<Record<string, unknown>>(chartRows as Array<Record<string, unknown>>, {
+    const spec = chartEngine<Record<string, unknown>>(chartRows as Array<Record<string, unknown>>, {
       type: chartType,
       category: category as string,
       value: values.length === 1 ? values[0]! : values,
@@ -2576,6 +2646,8 @@ export function createSvGridController<
 
   const ctx = {
     get props() { return props; },
+    get optionOverrides() { return optionOverrides; },
+    set optionOverrides(v) { optionOverrides = v as never; },
     get editingEnabled() { return editingEnabled; },
     get paginationEnabled() { return paginationEnabled; },
     get groupingControlsEnabled() { return groupingControlsEnabled; },
@@ -2813,6 +2885,15 @@ export function createSvGridController<
     get toolPanelHeaderLabel() { return toolPanelHeaderLabel; },
     get toggleColumnVisibleInPanel() { return toggleColumnVisibleInPanel; },
     get moveColumnInPanel() { return moveColumnInPanel; },
+    // ---- Localized chrome strings ----
+    get messages() { return gridMessages; },
+    // ---- In-grid pivot mode ----
+    get pivotConfig() { return pivotConfig; },
+    get pivotActive() { return pivotActive; },
+    get pivotResult() { return pivotResult; },
+    get pivotModeOn() { return pivotModeOn; },
+    get hasPivotEngine() { return hasPivotEngine(); },
+    togglePivotMode,
     // ---- Integrated charting ----
     get chartingEnabled() { return chartingEnabled; },
     get chartingConfig() { return chartingConfig; },