@svgrid/grid 2.2.16 → 2.2.17

package/src/board-view.svelte.ts

@@ -0,0 +1,33 @@
+/**
+ * board-view registry - the injection seam for the Kanban *board view of the
+ * grid*. Setting the `board` prop on `<SvGrid>` switches the table for lanes of
+ * cards, but the renderer itself ships in `@svgrid/enterprise` (a paid feature).
+ * This tiny reactive holder lets enterprise register that renderer at import
+ * time; the grid looks it up and mounts it, or shows an upsell placeholder when
+ * it is absent. Mirrors the `scheduler-view` / `editor-registry` pattern.
+ *
+ * ```ts
+ * // in @svgrid/enterprise, at module load:
+ * import { registerBoardView } from '@svgrid/grid'
+ * import SvGridBoard from './SvGridBoard.svelte'
+ * registerBoardView(SvGridBoard)
+ * ```
+ */
+import type { Component } from 'svelte'
+
+let renderer = $state<Component<any> | null>(null)
+
+/** Register the component that renders `board` mode. Enterprise calls this. */
+export function registerBoardView(component: Component<any>): void {
+  renderer = component
+}
+
+/** The registered board renderer, or null when enterprise is not installed. */
+export function getBoardView(): Component<any> | null {
+  return renderer
+}
+
+/** Whether a board renderer has been registered. */
+export function hasBoardView(): boolean {
+  return renderer != null
+}

package/src/build-api.coverage.test.ts

@@ -530,3 +530,104 @@ describe("SvGridApi - sort opt-out + refresh", () => {
     }
   });
 });
+
+describe("SvGridApi - setOption / getOption (runtime prop overrides)", () => {
+  it("getOption returns the incoming prop when no override is set", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      expect(api.getOption("rowHeight")).toBe(36);
+      expect(api.getOption("zebraRows")).toBeUndefined();
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setOption overrides a prop, getOption reflects it, undefined clears it", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setOption("rowHeight", 48);
+      await flush();
+      expect(api.getOption("rowHeight")).toBe(48);
+
+      api.setOption("zebraRows", true);
+      await flush();
+      expect(api.getOption("zebraRows")).toBe(true);
+
+      // Clearing an override falls back to the incoming prop.
+      api.setOption("rowHeight", undefined);
+      await flush();
+      expect(api.getOption("rowHeight")).toBe(36);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setOption('sortable', true) turns sorting on at runtime; false turns it off", async () => {
+    // Mount with NO features so sorting starts disabled - only the runtime
+    // override can inject rowSortingFeature (mirrors resolveEffectiveFeatures).
+    const { api, destroy } = await mountGrid({}, tableFeatures({}));
+    try {
+      // Off by default: setSort is guarded to a no-op.
+      api.setSort("salary", "asc");
+      await flush();
+      expect(api.getState().sorting).toEqual([]);
+
+      // Turn sorting on via the override, then setSort takes effect.
+      api.setOption("sortable", true);
+      await flush();
+      api.setSort("salary", "asc");
+      await flush();
+      expect(api.getState().sorting).toEqual([{ id: "salary", desc: false }]);
+
+      // Turn it back off: setSort is guarded again.
+      api.setOption("sortable", false);
+      await flush();
+      api.clearSort();
+      await flush();
+      api.setSort("team", "asc");
+      await flush();
+      expect(api.getState().sorting).toEqual([]);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("a view-direct prop (zebraRows) visually re-renders on override", async () => {
+    const { api, target, destroy } = await mountGrid();
+    try {
+      // No striping to start.
+      expect(target.querySelectorAll(".sv-grid-row-alt").length).toBe(0);
+
+      api.setOption("zebraRows", true);
+      await flush();
+      await flush();
+      // Odd rows now carry the alternate-row class (view reads props.zebraRows,
+      // which is the effective proxy).
+      expect(target.querySelectorAll(".sv-grid-row-alt").length).toBeGreaterThan(0);
+
+      api.setOption("zebraRows", undefined);
+      await flush();
+      await flush();
+      expect(target.querySelectorAll(".sv-grid-row-alt").length).toBe(0);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("resetOptions clears every override", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setOption("rowHeight", 60);
+      api.setOption("zebraRows", true);
+      await flush();
+      expect(api.getOption("rowHeight")).toBe(60);
+
+      api.resetOptions();
+      await flush();
+      expect(api.getOption("rowHeight")).toBe(36);
+      expect(api.getOption("zebraRows")).toBeUndefined();
+    } finally {
+      destroy();
+    }
+  });
+});

package/src/build-api.ts

@@ -48,17 +48,14 @@ import {
   getDateFormatter,
   resolveDatePattern,
 } from "./cell-formatting";
-import {
-  projectGridRows,
-  serializeDelimited,
-  serializeJson,
-  serializeMarkdown,
-  downloadTextFile,
-  copyTextToClipboard,
-  type GridExportColumn,
-  type GridExportScope,
-  type GridExportOptions,
-  type GridClipboardOptions,
+// The export serializers load lazily (their own chunk) so export-format.ts stays
+// out of the base bundle - it is fetched only when an export/copy method is
+// actually invoked (an explicit, already-async user action).
+import type {
+  GridExportColumn,
+  GridExportScope,
+  GridExportOptions,
+  GridClipboardOptions,
 } from "./export-format";
 import {
   RenderSnippetConfig,
@@ -166,16 +163,18 @@ export function createGridApi<
       }
       return out;
     };
-    const projectForExport = (
+    const projectForExport = async (
       scope: GridExportScope,
       columns: ReadonlyArray<string> | undefined,
       rawValues: boolean | undefined,
-    ) =>
-      projectGridRows(
+    ) => {
+      const { projectGridRows } = await import("./export-format");
+      return projectGridRows(
         exportScopeRows(scope) as ReadonlyArray<Record<string, unknown>>,
         exportColumns(),
         { columns, rawValues },
       );
+    };
 
     return {
       getCellValue(rowIndex, columnId) {
@@ -372,6 +371,28 @@ export function createGridApi<
       setGroupBy(columnIds) {
         ctx.grid.setGrouping([...columnIds]);
       },
+      setOption(key, value) {
+        // Runtime prop override. Writes into the controller's `optionOverrides`
+        // store, which the effective-props proxy merges over the incoming prop, so
+        // the grid re-renders exactly as if the parent had changed that prop.
+        // `undefined` clears the override (falls back to the prop). Reassign the
+        // whole object for reliable reactivity; `untrack` per the `setFilter` note.
+        untrack(() => {
+          const next: Record<string, unknown> = { ...ctx.optionOverrides };
+          if (value === undefined) delete next[key as string];
+          else next[key as string] = value;
+          ctx.optionOverrides = next;
+        });
+      },
+      getOption(key) {
+        // The effective value: the override if set, otherwise the incoming prop.
+        return (ctx.props as Record<string, unknown>)[key as string] as never;
+      },
+      resetOptions() {
+        untrack(() => {
+          ctx.optionOverrides = {};
+        });
+      },
       setFilter(columnId, filter) {
         // `untrack`: these imperative mutators read the same filter state they
         // write (read-modify-write on `filterMenuValues`). When a consumer
@@ -511,7 +532,8 @@ export function createGridApi<
       },
       // ---- Free data export (CSV / TSV / JSON + clipboard) -----------------
       async exportCsv(options: GridExportOptions = {}) {
-        const { records, fields } = projectForExport(
+        const { serializeDelimited, downloadTextFile } = await import("./export-format");
+        const { records, fields } = await projectForExport(
           options.rows ?? "displayed",
           options.columns,
           options.rawValues,
@@ -526,7 +548,8 @@ export function createGridApi<
         return text;
       },
       async exportTsv(options: GridExportOptions = {}) {
-        const { records, fields } = projectForExport(
+        const { serializeDelimited, downloadTextFile } = await import("./export-format");
+        const { records, fields } = await projectForExport(
           options.rows ?? "displayed",
           options.columns,
           options.rawValues,
@@ -541,7 +564,8 @@ export function createGridApi<
         return text;
       },
       async exportJson(options: GridExportOptions = {}) {
-        const { records, fields } = projectForExport(
+        const { serializeJson, downloadTextFile } = await import("./export-format");
+        const { records, fields } = await projectForExport(
           options.rows ?? "displayed",
           options.columns,
           options.rawValues,
@@ -555,7 +579,8 @@ export function createGridApi<
         return text;
       },
       async copyToClipboard(options: GridClipboardOptions = {}) {
-        const { records, fields, align } = projectForExport(
+        const { serializeDelimited, serializeMarkdown, copyTextToClipboard } = await import("./export-format");
+        const { records, fields, align } = await projectForExport(
           options.rows ?? "displayed",
           options.columns,
           options.rawValues,

package/src/builtin-editors.grid.test.ts

@@ -77,7 +77,7 @@ describe('registerBuiltinEditors in SvGrid', () => {
       api.startEditing(0, 'estimate')
       await tick()
       await tick()
-      expect(target.querySelector('.sv-dur')).not.toBeNull()
+      expect(target.querySelector('.sv-dur__input')).not.toBeNull()
     } finally {
       destroy()
     }

package/src/cell-formatting.ts

@@ -60,7 +60,7 @@ export function resolveDatePattern(
 
 type NumericFormatInput = {
   type: 'number' | 'currency' | 'percent'
-  locales?: string | string[]
+  locales?: string | readonly string[]
   currency?: string
   /** When type is percent: treat value as 0–100 instead of Intl’s 0–1 fraction */
   valueIsPercentPoints?: boolean
@@ -75,7 +75,7 @@ type NumericFormatInput = {
  */
 const numberFormatterCache = new Map<string, Intl.NumberFormat>()
 function getNumberFormatter(
-  locales: string | string[] | undefined,
+  locales: string | readonly string[] | undefined,
   options: Intl.NumberFormatOptions,
 ): Intl.NumberFormat {
   // Stable key - for normal column configs the options object is reused
@@ -98,7 +98,7 @@ function getNumberFormatter(
     (options.notation ?? '')
   let fmt = numberFormatterCache.get(key)
   if (!fmt) {
-    fmt = new Intl.NumberFormat(locales, options)
+    fmt = new Intl.NumberFormat(locales as string | string[] | undefined, options)
     numberFormatterCache.set(key, fmt)
   }
   return fmt
@@ -107,7 +107,7 @@ function getNumberFormatter(
 /** Cache of `Intl.DateTimeFormat` by `(locale, options)` signature. */
 const dateFormatterCache = new Map<string, Intl.DateTimeFormat>()
 export function getDateFormatter(
-  locales: string | string[] | undefined,
+  locales: string | readonly string[] | undefined,
   options: Intl.DateTimeFormatOptions,
 ): Intl.DateTimeFormat {
   const key =
@@ -134,7 +134,7 @@ export function getDateFormatter(
     (options.hour12 ?? '')
   let fmt = dateFormatterCache.get(key)
   if (!fmt) {
-    fmt = new Intl.DateTimeFormat(locales, options)
+    fmt = new Intl.DateTimeFormat(locales as string | string[] | undefined, options)
     dateFormatterCache.set(key, fmt)
   }
   return fmt

package/src/cell-render.ts

@@ -332,7 +332,7 @@ export function createCellRender<
     ) {
       return formatNumericWithConfig(value, {
         type: formatConfig.type,
-        locales: formatConfig.locales,
+        locales: (formatConfig.locales ?? ctx.props.localization?.locale),
         currency:
           formatConfig.type === "currency"
             ? (formatConfig.currency ?? "USD")
@@ -365,7 +365,7 @@ export function createCellRender<
                   minute: "2-digit",
                 };
 
-        return getDateFormatter(formatConfig.locales, merged).format(
+        return getDateFormatter((formatConfig.locales ?? ctx.props.localization?.locale), merged).format(
           parsedDate,
         );
       }
@@ -406,7 +406,7 @@ export function createCellRender<
     ) {
       return formatNumericWithConfig(value, {
         type: formatConfig.type,
-        locales: formatConfig.locales,
+        locales: (formatConfig.locales ?? ctx.props.localization?.locale),
         currency:
           formatConfig.type === "currency"
             ? (formatConfig.currency ?? "USD")
@@ -428,7 +428,7 @@ export function createCellRender<
             : formatConfig.type === "date"
               ? { year: "numeric", month: "2-digit", day: "2-digit" }
               : { year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit" };
-        return getDateFormatter(formatConfig.locales, merged).format(parsedDate);
+        return getDateFormatter((formatConfig.locales ?? ctx.props.localization?.locale), merged).format(parsedDate);
       }
     }
     return String(value ?? "");

package/src/chart-view.svelte.ts

@@ -0,0 +1,36 @@
+/**
+ * chart-view registry - the injection seam for the *chart view of the grid*.
+ * Setting the `chart` prop on `<SvGrid>` swaps the table for a chart driven by
+ * the grid's filtered + sorted rows. Mirrors the `board-view` / `scheduler-view`
+ * seam, with one difference: the chart renderer is NOT a paid feature. The chart
+ * primitive (`SvChart` / `SvGridChart`) already ships in the free `@svgrid/grid`,
+ * so the grid lazy-loads a built-in default renderer (`SvGridChartView`) out of
+ * the box. This seam exists only so a host (or enterprise) can *override* that
+ * default with a richer renderer - it is not required for the view to work.
+ *
+ * ```ts
+ * // optional: replace the built-in chart view with your own renderer
+ * import { registerChartView } from '@svgrid/grid'
+ * import MyChartView from './MyChartView.svelte'
+ * registerChartView(MyChartView)
+ * ```
+ */
+import type { Component } from 'svelte'
+
+let renderer = $state<Component<any> | null>(null)
+
+/** Override the built-in chart-view renderer. Optional - the grid ships a
+ *  free default, so this is only for hosts that want a custom renderer. */
+export function registerChartView(component: Component<any>): void {
+  renderer = component
+}
+
+/** The registered chart-view override, or null to use the built-in default. */
+export function getChartView(): Component<any> | null {
+  return renderer
+}
+
+/** Whether a chart-view override has been registered. */
+export function hasChartView(): boolean {
+  return renderer != null
+}

package/src/createCombobox.svelte.ts

@@ -30,6 +30,8 @@ export type ComboboxConfig = {
   value: () => ComboboxValue
   onChange?: (value: ComboboxValue) => void
   disabled?: () => boolean
+  /** Read-only: value shown, input focusable, but not editable and the panel will not open. */
+  readonly?: () => boolean
   ariaLabel?: () => string | undefined
   /** Filter the options locally by the query. Set false for server-side search. */
   localFilter?: () => boolean
@@ -51,6 +53,7 @@ export function createCombobox(config: ComboboxConfig) {
   const listId = `${id}-list`
   const opts = () => config.options()
   const disabled = () => config.disabled?.() ?? false
+  const readonly = () => config.readonly?.() ?? false
 
   let open = $state(false)
   let query = $state('')
@@ -76,25 +79,31 @@ export function createCombobox(config: ComboboxConfig) {
     ariaLabel: config.ariaLabel?.(),
   })
 
-  function openPanel() { if (disabled() || open) return; open = true; active = 0 }
+  function openPanel() { if (disabled() || readonly() || open) return; open = true; active = 0 }
   function close(revert = true) {
     open = false; editing = false
     if (revert) query = selected?.label ?? ''
   }
   function toggle() { if (open) { close() } else { config.focusInput?.(); openPanel() } }
   function pick(o: ListOption | undefined) {
-    if (!o || o.disabled) return
+    if (readonly() || !o || o.disabled) return
     config.onChange?.(o.value); query = o.label; editing = false; open = false; config.blurInput?.()
   }
+  /** Clear the selection (value -> null) and reset the shown text. */
+  function clear() {
+    if (readonly() || disabled()) return
+    config.onChange?.(null); query = ''; editing = false; open = false
+  }
   function setActive(i: number) { const o = filtered[i]; if (o && !o.disabled) active = i }
   function onInput(e: Event) {
+    if (readonly()) return
     query = (e.currentTarget as HTMLInputElement).value
     editing = true; active = 0
     if (!open) openPanel()
   }
-  function onFocus() { editing = true; query = selected?.label ?? ''; openPanel() }
+  function onFocus() { if (readonly()) return; editing = true; query = selected?.label ?? ''; openPanel() }
   function onKeydown(e: KeyboardEvent) {
-    if (disabled()) return
+    if (disabled() || readonly()) return
     if (!open && e.key === 'ArrowDown') { e.preventDefault(); editing = true; openPanel(); return }
     if (e.key === 'ArrowDown') { e.preventDefault(); active = Math.min(active + 1, filtered.length - 1) }
     else if (e.key === 'ArrowUp') { e.preventDefault(); active = Math.max(active - 1, 0) }
@@ -128,6 +137,7 @@ export function createCombobox(config: ComboboxConfig) {
     close,
     toggle,
     pick,
+    clear,
     onInput,
     onFocus,
     onKeydown,
@@ -140,8 +150,10 @@ export function createCombobox(config: ComboboxConfig) {
       'aria-autocomplete': 'list' as const,
       'aria-activedescendant': open && filtered[active] ? optionId(active) : undefined,
       ...editorAria(ariaState()),
+      'aria-readonly': readonly() || undefined,
       value: shownText,
       disabled: disabled(),
+      readonly: readonly() || undefined,
       oninput: onInput,
       onfocus: onFocus,
       onkeydown: onKeydown,
@@ -151,7 +163,7 @@ export function createCombobox(config: ComboboxConfig) {
       type: 'button' as const,
       tabindex: -1,
       'aria-label': 'Toggle',
-      disabled: disabled(),
+      disabled: disabled() || readonly(),
       onclick: toggle,
     }),
     /** Spread onto the listbox container. */

package/src/createDropdownList.svelte.ts

@@ -30,6 +30,8 @@ export type DropdownListConfig = {
   value: () => DropdownValue
   onChange?: (value: string | number) => void
   disabled?: () => boolean
+  /** Read-only: value shown, trigger focusable, but the panel will not open. */
+  readonly?: () => boolean
   ariaLabel?: () => string | undefined
   /** DOM focus hook provided by the renderer; the core never touches the DOM. */
   focusTrigger?: () => void
@@ -48,6 +50,7 @@ export function createDropdownList(config: DropdownListConfig) {
   const optionId = (index: number) => `${listId}-opt-${index}`
   const opts = () => config.options()
   const disabled = () => config.disabled?.() ?? false
+  const readonly = () => config.readonly?.() ?? false
 
   const ariaState = (): EditorAriaState => ({
     id: config.id?.(),
@@ -65,13 +68,14 @@ export function createDropdownList(config: DropdownListConfig) {
   const enabledIdx = $derived(opts().map((o, i) => (o.disabled ? -1 : i)).filter((i) => i >= 0))
 
   function openPanel() {
-    if (disabled() || open) return
+    if (disabled() || readonly() || open) return
     open = true
     active = Math.max(0, opts().findIndex((o) => o.value === config.value()))
   }
   function close() { open = false }
   function toggle() { if (open) { close() } else { openPanel() } }
   function pick(i: number) {
+    if (readonly()) return
     const o = opts()[i]
     if (!o || o.disabled) return
     config.onChange?.(o.value); close(); config.focusTrigger?.()
@@ -85,6 +89,7 @@ export function createDropdownList(config: DropdownListConfig) {
   // when the list is closed, matching a native <select>).
   const typeahead = createTypeaheadBuffer()
   function onTypeahead(char: string) {
+    if (readonly()) return
     const buffer = typeahead.push(char.toLowerCase())
     const from = active >= 0 ? active : opts().findIndex((o) => o.value === config.value())
     const next = nextTypeaheadIndex(opts(), buffer, from)
@@ -93,7 +98,7 @@ export function createDropdownList(config: DropdownListConfig) {
     if (!open) config.onChange?.(opts()[next]!.value)
   }
   function onKeydown(e: KeyboardEvent) {
-    if (disabled()) return
+    if (disabled() || readonly()) return
     if (isTypeaheadKey(e)) { onTypeahead(e.key); return }
     if (!open && (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ')) { e.preventDefault(); openPanel(); return }
     if (!open) return
@@ -132,6 +137,7 @@ export function createDropdownList(config: DropdownListConfig) {
       'aria-controls': listId,
       'aria-activedescendant': open && opts()[active] ? optionId(active) : undefined,
       ...editorAria(ariaState()),
+      'aria-readonly': readonly() || undefined,
       disabled: disabled(),
       onclick: toggle,
       onkeydown: onKeydown,

package/src/createForm.svelte.ts

@@ -22,6 +22,22 @@
 import { flattenFields, type FormField, type FormEntry } from './form-field'
 import { runRules } from './validators'
 
+/** Localizable strings the form generates itself (override via `messages`). */
+export type FormMessages = {
+  required: (label: string) => string
+  minItems: (label: string, n: number) => string
+  maxItems: (label: string, n: number) => string
+  /** Shown by SvForm while an async validator runs. */
+  checking: string
+}
+
+const DEFAULT_FORM_MESSAGES: FormMessages = {
+  required: (l) => `${l} is required`,
+  minItems: (_l, n) => `Add at least ${n} item(s)`,
+  maxItems: (_l, n) => `At most ${n} item(s)`,
+  checking: 'Checking…',
+}
+
 export type FormConfig = {
   /** The schema - a mix of flat fields and titled sections. */
   fields: () => ReadonlyArray<FormEntry>
@@ -31,6 +47,8 @@ export type FormConfig = {
    *  `submitting` stays true until the returned promise settles. */
   onSubmit?: (values: Record<string, any>) => void | Promise<void>
   onChange?: (values: Record<string, any>) => void
+  /** Override the built-in generated strings (required / min-max items / checking). */
+  messages?: Partial<FormMessages>
 }
 
 /** Deep-ish equality for dirty tracking: identity for primitives, structural
@@ -54,6 +72,7 @@ function resolveFlag(
 }
 
 export function createForm(config: FormConfig) {
+  const M: FormMessages = { ...DEFAULT_FORM_MESSAGES, ...(config.messages ?? {}) }
   let values = $state<Record<string, any>>({ ...(config.initial ?? {}) })
   let errors = $state<Record<string, string>>({})
   let touched = $state<Record<string, boolean>>({})
@@ -85,7 +104,7 @@ export function createForm(config: FormConfig) {
    *  rows (so within-row cross-field rules work). */
   function syncError(field: FormField, v: any, ctx: Record<string, any> = values): string | null {
     if (field.required && (v == null || v === '' || (Array.isArray(v) && !v.length)))
-      return `${field.label} is required`
+      return M.required(field.label)
     if (field.rules) { const e = runRules(v, field.rules, ctx); if (e) return e }
     if (field.validate) { const e = field.validate(v, ctx); if (e) return e }
     return null
@@ -128,6 +147,8 @@ export function createForm(config: FormConfig) {
   function validateField(name: string): boolean {
     const field = fieldOf(name)
     if (!field) return true
+    // Computed fields are derived + read-only - never validated, never block submit.
+    if (field.computed) { setError(name, null); return true }
     // Hidden fields never block submit; clear any stale error + pending check.
     if (!isVisible(name)) { setError(name, null); cancelAsync(name); return true }
     if (field.type === 'array') return validateArray(field)
@@ -196,9 +217,9 @@ export function createForm(config: FormConfig) {
     const name = field.name
     const items = arrayItems(name)
     let arrErr: string | null = null
-    if (field.required && items.length === 0) arrErr = `${field.label} is required`
-    else if (field.minItems != null && items.length < field.minItems) arrErr = `Add at least ${field.minItems} item(s)`
-    else if (field.maxItems != null && items.length > field.maxItems) arrErr = `At most ${field.maxItems} item(s)`
+    if (field.required && items.length === 0) arrErr = M.required(field.label)
+    else if (field.minItems != null && items.length < field.minItems) arrErr = M.minItems(field.label, field.minItems)
+    else if (field.maxItems != null && items.length > field.maxItems) arrErr = M.maxItems(field.label, field.maxItems)
     setError(name, arrErr)
     let ok = !arrErr
     clearNamespacedErrors(name) // rebuild fresh per-item errors
@@ -208,8 +229,23 @@ export function createForm(config: FormConfig) {
     return ok
   }
 
+  /** True when `field` depends on `name` (cascading). */
+  function dependsOnName(field: FormField, name: string): boolean {
+    const dep = field.dependsOn
+    return dep == null ? false : Array.isArray(dep) ? dep.includes(name) : dep === name
+  }
+
   function setValue(name: string, v: any) {
-    values = { ...values, [name]: v }
+    let next = { ...values, [name]: v }
+    // Cascading: clear any fields that depend on this one so a stale child
+    // selection (e.g. a city under the old country) does not linger.
+    for (const f of flat()) {
+      if (dependsOnName(f, name) && next[f.name] != null) {
+        next = { ...next, [f.name]: null }
+        setError(f.name, null)
+      }
+    }
+    values = next
     config.onChange?.(values)
     // Re-validate live once the field has been blurred at least once.
     if (touched[name]) validateField(name)
@@ -240,6 +276,8 @@ export function createForm(config: FormConfig) {
     // Exclude hidden fields from the submitted payload; keep any non-field keys.
     const payload = { ...values }
     for (const f of flat()) if (!isVisible(f.name)) delete payload[f.name]
+    // Inject computed (derived) values so the payload carries them.
+    for (const f of flat()) if (f.computed && isVisible(f.name)) payload[f.name] = f.computed(values)
     submitting = true
     try {
       await config.onSubmit?.(payload)
@@ -294,6 +332,17 @@ export function createForm(config: FormConfig) {
 
   const isFieldDirty = (name: string) => !eq(values[name], baseline[name])
 
+  /** Top-level field errors (visible fields only), for a form-level summary. */
+  function errorList(): { name: string; label: string; message: string }[] {
+    const out: { name: string; label: string; message: string }[] = []
+    for (const f of flat()) {
+      const m = errors[f.name]
+      if (m && isVisible(f.name)) out.push({ name: f.name, label: f.label, message: m })
+    }
+    return out
+  }
+  const firstErrorField = (): string | undefined => errorList()[0]?.name
+
   return {
     get values() { return values },
     get submitting() { return submitting },
@@ -302,7 +351,7 @@ export function createForm(config: FormConfig) {
       for (const k of keys) if (!eq(values[k], baseline[k])) return true
       return false
     },
-    value: (name: string) => values[name],
+    value: (name: string) => { const f = fieldOf(name); return f?.computed ? f.computed(values) : values[name] },
     error: (name: string): string | undefined => errors[name],
     isTouched: (name: string) => !!touched[name],
     hasError: (name: string) => !!errors[name],
@@ -327,6 +376,10 @@ export function createForm(config: FormConfig) {
     submit,
     reset,
     setErrors,
+    errorList,
+    firstErrorField,
+    /** The resolved message strings (defaults merged with `config.messages`). */
+    messages: M,
   }
 }