@svgrid/grid 2.2.16 → 2.2.18

package/dist/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/dist/SvForm.svelte.d.ts

@@ -1,5 +1,7 @@
 export type { FormField, FormFieldType, FormSection, FormEntry } from './form-field';
 import { type FormEntry } from './form-field';
+import { type FormMessages } from './createForm.svelte';
+import type { EditorDir } from './editor-contract';
 type Props = {
     fields: ReadonlyArray<FormEntry>;
     initial?: Record<string, any>;
@@ -16,9 +18,30 @@ type Props = {
     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>;
 };
 declare const SvForm: import("svelte").Component<Props, {}, "">;
 type SvForm = ReturnType<typeof SvForm>;

package/dist/SvGrid.controller.svelte.d.ts

@@ -12,8 +12,9 @@ import { getColumnBaseValue, isGroupRow, toolPanelHeaderLabel, formatSummaryNume
  * the component lifecycle) and consumed through the returned getters.
  */
 export type SvGridController<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData> = ReturnType<typeof createSvGridController<TFeatures, TData>>;
-export declare function createSvGridController<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData>(props: Props<TFeatures, TData>): {
+export declare function createSvGridController<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData>(rawProps: Props<TFeatures, TData>): {
     readonly props: Props<TFeatures, TData>;
+    optionOverrides: Record<string, unknown>;
     readonly editingEnabled: boolean;
     readonly paginationEnabled: boolean;
     readonly groupingControlsEnabled: boolean;
@@ -283,6 +284,16 @@ export declare function createSvGridController<TFeatures extends TableFeatures =
     readonly toolPanelHeaderLabel: typeof toolPanelHeaderLabel;
     readonly toggleColumnVisibleInPanel: (columnId: string) => void;
     readonly moveColumnInPanel: (columnId: string, dir: -1 | 1) => void;
+    readonly messages: import("./grid-messages").GridMessages;
+    readonly pivotConfig: import("./pivot-view.svelte").GridPivotConfig<TData> | null;
+    readonly pivotActive: boolean;
+    readonly pivotResult: {
+        rows: import("./pivot-view.svelte").GridPivotRow[];
+        columns: ColumnDef<TableFeatures, import("./pivot-view.svelte").GridPivotRow>[];
+    } | null;
+    readonly pivotModeOn: boolean;
+    readonly hasPivotEngine: boolean;
+    togglePivotMode: () => void;
     readonly chartingEnabled: boolean;
     readonly chartingConfig: {
         position: "right" | "bottom";

package/dist/SvGrid.controller.svelte.js

@@ -1,4 +1,4 @@
-import { applyExcelFilter, normalizeForFilter, createColumnVirtualizer, createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createSvelteVirtualizer, createSortedRowModel, createSvGrid, getGridCellDomId, rowsToChartSpec, sortFns, } from "./index";
+import { applyExcelFilter, normalizeForFilter, createColumnVirtualizer, createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createSvelteVirtualizer, createSortedRowModel, createSvGrid, getGridCellDomId, sortFns, } from "./index";
 import { createRowScrollScaling, resolveMaxDomHeight, } from "./virtualization/scroll-scaling";
 import "./sv-grid-scrollbar";
 import { computeColumnStat, formatsNeedingStats, formatNeedsStats, } from "./conditional-formatting";
@@ -18,6 +18,8 @@ import { resolveColumnTypes, } from "./column-types";
 import { computeColumnGroupMeta, hiddenLeavesForCollapse, } from "./column-groups";
 import { createGridApi, } from "./build-api";
 import { createClipboard, } from "./clipboard";
+import { resolveGridMessages } from "./grid-messages";
+import { getPivotEngine, hasPivotEngine } from "./pivot-view.svelte";
 import { filterOperatorOptions, fallbackOperatorOption, TEXT_OPERATORS, NUMBER_OPERATORS, DATE_OPERATORS, CHECKBOX_OPERATORS, operatorOption, operatorsForColumn, defaultOperatorFor, operatorLabelFor, } from "./filter-operators";
 import { isBucketableColumn, buildBuckets, isInBucket, } from "./facet-buckets";
 import { getColumnBaseValue, isGroupRow, toolPanelHeaderLabel, formatSummaryNumeric, getColumnAlign, getPinnedCellValue, getColumnAccessorValue, columnDefMatchesId, } from "./cell-values";
@@ -143,7 +145,26 @@ function observeSizeRaf(el, cb) {
         observer.disconnect();
     };
 }
-export function createSvGridController(props) {
+export function createSvGridController(rawProps) {
+    // 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({});
+    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);
+        },
+    });
     // Resolved capability gates. Capabilities are OFF by default - a bare
     // grid is a plain read-only table, and each power feature is opted into
     // via its shortcut (`editable` / `pageable` / `groupable`) or the matching
@@ -466,7 +487,8 @@ export function createSvGridController(props) {
         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: {},
@@ -808,10 +830,10 @@ export function createSvGridController(props) {
             return rawRows;
         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)
+                .some((cell) => normalizeForFilter(String(cell.getValue() ?? ""), (props.filterLocale ?? props.localization?.locale))
                 .includes(needle)));
         }
         // A single condition is "active" if it has the value(s) it needs.
@@ -822,7 +844,7 @@ export function createSvGridController(props) {
                 return value.trim().length > 0 && (valueTo ?? "").trim().length > 0;
             return value.trim().length > 0;
         };
-        const evalCond = (cellValue, columnId, op, value, valueTo) => applyExcelFilter(cellValue, { id: columnId, operator: op, value, valueTo: op === "between" ? valueTo : undefined }, { locale: props.filterLocale });
+        const evalCond = (cellValue, columnId, op, value, valueTo) => applyExcelFilter(cellValue, { id: columnId, operator: op, value, valueTo: op === "between" ? valueTo : undefined }, { 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]) => {
             const a = condActive(f.operator, f.value, f.valueTo);
@@ -1048,6 +1070,39 @@ export function createSvGridController(props) {
         return c === true ? {} : c;
     });
     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() {
+        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);
+    });
     const chartIsCustom = $derived(typeof chartCfg?.buildSpec === "function");
     const chartingConfig = $derived(chartCfg
         ? {
@@ -1300,6 +1355,17 @@ export function createSvGridController(props) {
             })),
         };
     };
+    // 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(null);
+    $effect(() => {
+        if (chartingEnabled && !chartEngine)
+            import("./chart").then((m) => (chartEngine = m.rowsToChartSpec));
+    });
     const chartSpec = $derived.by(() => {
         if (!chartingEnabled || !chartCfg)
             return null;
@@ -1327,8 +1393,11 @@ export function createSvGridController(props) {
         const values = effectiveChartMeasureIds.map((id) => fieldOf(id)).filter((f) => !!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(chartRows, {
+        const spec = chartEngine(chartRows, {
             type: chartType,
             category: category,
             value: values.length === 1 ? values[0] : values,
@@ -2142,6 +2211,8 @@ export function createSvGridController(props) {
     });
     const ctx = {
         get props() { return props; },
+        get optionOverrides() { return optionOverrides; },
+        set optionOverrides(v) { optionOverrides = v; },
         get editingEnabled() { return editingEnabled; },
         get paginationEnabled() { return paginationEnabled; },
         get groupingControlsEnabled() { return groupingControlsEnabled; },
@@ -2379,6 +2450,15 @@ export function createSvGridController(props) {
         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; },