@formwright/core 0.1.0 → 0.2.2

package/dist/index.cjs

@@ -1,165 +1,9 @@
 'use strict';
 
+var reactive = require('@formwright/reactive');
 var schema = require('@formwright/schema');
 
 // src/reactive.ts
-var activeObserver = null;
-var batchDepth = 0;
-var pendingEffects = /* @__PURE__ */ new Set();
-var flushing = false;
-function link(source) {
-  const obs = activeObserver;
-  if (obs === null) return;
-  if (!source.observers.has(obs)) {
-    source.observers.add(obs);
-    obs.sources.add(source);
-  }
-}
-function clearSources(obs) {
-  for (const src of obs.sources) src.observers.delete(obs);
-  obs.sources.clear();
-}
-function flush() {
-  if (flushing) return;
-  flushing = true;
-  try {
-    while (pendingEffects.size > 0) {
-      const next = pendingEffects.values().next().value;
-      pendingEffects.delete(next);
-      next.run();
-    }
-  } finally {
-    flushing = false;
-  }
-}
-var SignalNode = class {
-  constructor(value) {
-    this.value = value;
-  }
-  value;
-  observers = /* @__PURE__ */ new Set();
-  get() {
-    link(this);
-    return this.value;
-  }
-  peek() {
-    return this.value;
-  }
-  set(next) {
-    if (Object.is(next, this.value)) return;
-    this.value = next;
-    for (const obs of [...this.observers]) obs.notify();
-    if (batchDepth === 0) flush();
-  }
-  update(fn) {
-    this.set(fn(this.value));
-  }
-};
-var ComputedNode = class {
-  constructor(fn) {
-    this.fn = fn;
-  }
-  fn;
-  observers = /* @__PURE__ */ new Set();
-  sources = /* @__PURE__ */ new Set();
-  value;
-  dirty = true;
-  notify() {
-    if (this.dirty) return;
-    this.dirty = true;
-    for (const obs of [...this.observers]) obs.notify();
-  }
-  get() {
-    link(this);
-    if (this.dirty) this.recompute();
-    return this.value;
-  }
-  peek() {
-    if (this.dirty) this.recompute();
-    return this.value;
-  }
-  recompute() {
-    clearSources(this);
-    const prev = activeObserver;
-    activeObserver = this;
-    try {
-      this.value = this.fn();
-      this.dirty = false;
-    } finally {
-      activeObserver = prev;
-    }
-  }
-};
-var EffectNode = class {
-  constructor(fn) {
-    this.fn = fn;
-    this.run();
-  }
-  fn;
-  sources = /* @__PURE__ */ new Set();
-  cleanup = void 0;
-  disposed = false;
-  notify() {
-    if (this.disposed) return;
-    pendingEffects.add(this);
-  }
-  run() {
-    if (this.disposed) return;
-    this.runCleanup();
-    clearSources(this);
-    const prev = activeObserver;
-    activeObserver = this;
-    try {
-      this.cleanup = this.fn();
-    } finally {
-      activeObserver = prev;
-    }
-  }
-  runCleanup() {
-    if (typeof this.cleanup === "function") {
-      this.cleanup();
-      this.cleanup = void 0;
-    }
-  }
-  dispose() {
-    if (this.disposed) return;
-    this.disposed = true;
-    this.runCleanup();
-    clearSources(this);
-    pendingEffects.delete(this);
-  }
-};
-function signal(initial) {
-  return new SignalNode(initial);
-}
-function computed(fn) {
-  return new ComputedNode(fn);
-}
-function effect(fn) {
-  const node = new EffectNode(fn);
-  return () => node.dispose();
-}
-function untrack(fn) {
-  const prev = activeObserver;
-  activeObserver = null;
-  try {
-    return fn();
-  } finally {
-    activeObserver = prev;
-  }
-}
-function batch(fn) {
-  batchDepth++;
-  try {
-    return fn();
-  } finally {
-    batchDepth--;
-    if (batchDepth === 0) flush();
-  }
-}
-function isTracking() {
-  return activeObserver !== null;
-}
 
 // src/conditions.ts
 function isOp(cond, key) {
@@ -249,35 +93,42 @@ function isEmpty(value) {
   return value === void 0 || value === null || value === "";
 }
 function compileValidator(schema) {
+  const overrides = schema.messages ?? {};
+  const msg = (rule, fallback) => overrides[rule] ?? (typeof schema.message === "string" ? schema.message : fallback);
   return (value) => {
-    const msg = (fallback) => typeof schema.message === "string" ? schema.message : fallback;
     if (isEmpty(value)) {
-      return schema.required ? msg("This field is required") : null;
+      return schema.required ? msg("required", "This field is required") : null;
     }
     if (schema.kind === "string" || schema.format) {
       const str = String(value);
       if (schema.minLength !== void 0 && str.length < schema.minLength) {
-        return msg(`Must be at least ${schema.minLength} characters`);
+        return msg("minLength", `Must be at least ${schema.minLength} characters`);
       }
       if (schema.maxLength !== void 0 && str.length > schema.maxLength) {
-        return msg(`Must be at most ${schema.maxLength} characters`);
+        return msg("maxLength", `Must be at most ${schema.maxLength} characters`);
       }
       if (schema.pattern !== void 0 && !new RegExp(schema.pattern).test(str)) {
-        return msg("Invalid format");
+        return msg("pattern", "Invalid format");
       }
-      if (schema.format === "email" && !EMAIL.test(str)) return msg("Enter a valid email");
-      if (schema.format === "url" && !URL.test(str)) return msg("Enter a valid URL");
-      if (schema.format === "uuid" && !UUID.test(str)) return msg("Enter a valid UUID");
+      if (schema.format === "email" && !EMAIL.test(str))
+        return msg("format", "Enter a valid email");
+      if (schema.format === "url" && !URL.test(str)) return msg("format", "Enter a valid URL");
+      if (schema.format === "uuid" && !UUID.test(str)) return msg("format", "Enter a valid UUID");
     }
     if (schema.kind === "number") {
       const num = Number(value);
-      if (Number.isNaN(num)) return msg("Must be a number");
-      if (schema.min !== void 0 && num < schema.min) return msg(`Must be \u2265 ${schema.min}`);
-      if (schema.max !== void 0 && num > schema.max) return msg(`Must be \u2264 ${schema.max}`);
+      if (Number.isNaN(num)) return msg("type", "Must be a number");
+      if (schema.min !== void 0 && num < schema.min)
+        return msg("min", `Must be \u2265 ${schema.min}`);
+      if (schema.max !== void 0 && num > schema.max)
+        return msg("max", `Must be \u2264 ${schema.max}`);
     }
     return null;
   };
 }
+function requiredMessage(schema) {
+  return schema?.messages?.required ?? (typeof schema?.message === "string" ? schema.message : "This field is required");
+}
 
 // src/providers.ts
 function isProviderRef(value) {
@@ -317,10 +168,14 @@ function defaultValueFor(type) {
       return "";
   }
 }
+var uidSeq = 0;
 var FieldState = class {
   /** Discriminant for the {@link FieldNode} union (leaf vs group/collection). */
   kind = "field";
   id;
+  /** A globally-unique DOM id for the control (collection rows reuse `id`, so this must be unique). */
+  domId = `fw-${(uidSeq++).toString(36)}`;
+  /** The field's schema — mutable at runtime via {@link patchSchema}. */
   schema;
   value;
   error;
@@ -328,32 +183,55 @@ var FieldState = class {
   visible;
   enabled;
   required;
+  /** Bumps whenever the schema is patched — renderers re-render the field on change. */
+  revision;
   validator;
-  constructor(schema, initial, getValue) {
+  rev = reactive.signal(0);
+  stepActive;
+  constructor(schema, initial, getValue, stepActive) {
     this.id = schema.id;
     this.schema = schema;
-    this.value = signal(initial);
-    this.error = signal(null);
-    this.touched = signal(false);
+    this.stepActive = stepActive;
+    this.value = reactive.signal(initial);
+    this.error = reactive.signal(null);
+    this.touched = reactive.signal(false);
     this.validator = schema.validation ? compileValidator(schema.validation) : null;
-    this.visible = computed(() => evaluateCondition(schema.visibleWhen, getValue, true));
-    this.enabled = computed(() => evaluateCondition(schema.enabledWhen, getValue, true));
-    this.required = computed(() => {
-      if (schema.requiredWhen !== void 0) {
-        return evaluateCondition(schema.requiredWhen, getValue, false);
+    this.revision = this.rev;
+    this.visible = reactive.computed(() => {
+      this.rev.get();
+      return evaluateCondition(this.schema.visibleWhen, getValue, true);
+    });
+    this.enabled = reactive.computed(() => {
+      this.rev.get();
+      return evaluateCondition(this.schema.enabledWhen, getValue, true);
+    });
+    this.required = reactive.computed(() => {
+      this.rev.get();
+      if (this.schema.requiredWhen !== void 0) {
+        return evaluateCondition(this.schema.requiredWhen, getValue, false);
       }
-      return schema.validation?.required ?? false;
+      return this.schema.validation?.required ?? false;
     });
   }
-  /** Run validation, store and return the error (or null). Hidden fields never error. */
-  validate() {
+  /** Merge a partial schema in at runtime (change type, label, options, validation, …). */
+  patchSchema(partial) {
+    this.schema = { ...this.schema, ...partial };
+    this.validator = this.schema.validation ? compileValidator(this.schema.validation) : null;
+    this.rev.update((n) => n + 1);
+  }
+  /** Run validation, store and return the error (or null). Hidden / inactive-step fields never error. */
+  validate(options) {
     if (!this.visible.peek()) {
       this.error.set(null);
       return null;
     }
+    if (!options?.allSteps && this.stepActive && !this.stepActive.peek()) {
+      this.error.set(null);
+      return null;
+    }
     let result = null;
     if (this.required.peek() && isEmpty2(this.value.peek())) {
-      result = "This field is required";
+      result = requiredMessage(this.schema.validation);
     } else if (this.validator) {
       result = this.validator(this.value.peek());
     }
@@ -371,26 +249,40 @@ function isEmpty2(value) {
 }
 
 // src/nodes.ts
+var PRESENTATIONAL = /* @__PURE__ */ new Set(["heading", "separator", "paragraph"]);
+function isPresentational(type) {
+  return PRESENTATIONAL.has(type);
+}
 function nodeValue(node) {
   return node.value.get();
 }
 function collectValues(nodes) {
   const out = {};
-  for (const node of nodes) out[node.id] = nodeValue(node);
+  for (const node of nodes) {
+    if (node.schema.omit || isPresentational(node.schema.type)) continue;
+    if (!node.visible.get()) continue;
+    out[node.id] = nodeValue(node);
+  }
   return out;
 }
-function buildNodes(schemas, scope, initial) {
+function buildNodes(schemas, scope, initial, stepActive) {
   const nodes = [];
   const byName = /* @__PURE__ */ new Map();
   for (const schema of schemas) {
     let node;
     if (schema.type === "group") {
-      node = new GroupNode(schema, scope, asDict(initial[schema.id]));
+      node = new GroupNode(schema, scope, asDict(initial[schema.id]), stepActive);
+    } else if (schema.type === "step") {
+      if (!stepActive)
+        throw new Error('Field type "step" must be nested inside a "steps" container');
+      node = new StepNode(schema, scope, asDict(initial[schema.id]), stepActive);
     } else if (schema.type === "collection") {
       node = new CollectionNode(schema, scope, asArray(initial[schema.id]));
+    } else if (schema.type === "steps") {
+      node = new StepsNode(schema, scope, asDict(initial[schema.id]));
     } else {
       const init = initial[schema.id] ?? schema.defaultValue ?? defaultValueFor(schema.type);
-      node = new FieldState(schema, init, scope);
+      node = new FieldState(schema, init, scope, stepActive);
     }
     nodes.push(node);
     byName.set(schema.id, node);
@@ -408,7 +300,9 @@ function resetNodes(nodes, initial) {
     if (node.kind === "field") {
       const init = initial[node.id] ?? node.schema.defaultValue ?? defaultValueFor(node.schema.type);
       node.reset(init);
-    } else if (node.kind === "group") {
+    } else if (node.kind === "group" || node.kind === "step") {
+      node.reset(asDict(initial[node.id]));
+    } else if (node.kind === "steps") {
       node.reset(asDict(initial[node.id]));
     } else {
       node.reset(asArray(initial[node.id]));
@@ -426,19 +320,19 @@ var GroupNode = class {
   enabled;
   /** The scope a child uses: resolve a name among siblings, else delegate upward. */
   scope;
-  constructor(schema, parentScope, initial) {
+  constructor(schema, parentScope, initial, stepActive) {
     this.id = schema.id;
     this.schema = schema;
     this.scope = (name) => {
       const child = this.byName.get(name);
       return child ? nodeValue(child) : parentScope(name);
     };
-    const built = buildNodes(schema.fields ?? [], this.scope, initial);
+    const built = buildNodes(schema.fields ?? [], this.scope, initial, stepActive);
     this.children = built.nodes;
     this.byName = built.byName;
-    this.value = computed(() => collectValues(this.children));
-    this.visible = computed(() => evaluateCondition(schema.visibleWhen, parentScope, true));
-    this.enabled = computed(() => evaluateCondition(schema.enabledWhen, parentScope, true));
+    this.value = reactive.computed(() => collectValues(this.children));
+    this.visible = reactive.computed(() => evaluateCondition(schema.visibleWhen, parentScope, true));
+    this.enabled = reactive.computed(() => evaluateCondition(schema.enabledWhen, parentScope, true));
   }
   reset(initial) {
     resetNodes(this.children, initial);
@@ -461,10 +355,10 @@ var CollectionNode = class {
     this.parentScope = parentScope;
     this.itemSchema = { id: schema.id, type: "group", fields: schema.fields ?? [] };
     const seed = this.seedRows(initial);
-    this.rows = signal(seed);
-    this.value = computed(() => this.rows.get().map((row) => row.group.value.get()));
-    this.visible = computed(() => evaluateCondition(schema.visibleWhen, parentScope, true));
-    this.enabled = computed(() => evaluateCondition(schema.enabledWhen, parentScope, true));
+    this.rows = reactive.signal(seed);
+    this.value = reactive.computed(() => this.rows.get().map((row) => row.group.value.get()));
+    this.visible = reactive.computed(() => evaluateCondition(schema.visibleWhen, parentScope, true));
+    this.enabled = reactive.computed(() => evaluateCondition(schema.enabledWhen, parentScope, true));
   }
   /** Reactive list of rows (subscribes the caller to add/remove). */
   get items() {
@@ -496,6 +390,109 @@ var CollectionNode = class {
     this.rows.set(this.seedRows(initial));
   }
 };
+var StepNode = class {
+  kind = "step";
+  id;
+  schema;
+  children;
+  byName;
+  value;
+  visible;
+  enabled;
+  scope;
+  /** True when this step is the active step in its parent wizard. */
+  active;
+  constructor(schema, parentScope, initial, active) {
+    this.id = schema.id;
+    this.schema = schema;
+    this.active = active;
+    this.scope = (name) => {
+      const child = this.byName.get(name);
+      return child ? nodeValue(child) : parentScope(name);
+    };
+    const built = buildNodes(schema.fields ?? [], this.scope, initial, active);
+    this.children = built.nodes;
+    this.byName = built.byName;
+    this.value = reactive.computed(() => collectValues(this.children));
+    this.visible = reactive.computed(() => evaluateCondition(schema.visibleWhen, parentScope, true));
+    this.enabled = reactive.computed(() => evaluateCondition(schema.enabledWhen, parentScope, true));
+  }
+  reset(initial) {
+    resetNodes(this.children, initial);
+  }
+};
+var StepsNode = class {
+  kind = "steps";
+  id;
+  schema;
+  steps;
+  byName;
+  value;
+  visible;
+  enabled;
+  currentStep;
+  scope;
+  constructor(schema, parentScope, initial) {
+    this.id = schema.id;
+    this.schema = schema;
+    this.currentStep = reactive.signal(0);
+    this.byName = /* @__PURE__ */ new Map();
+    this.scope = (name) => {
+      const step = this.byName.get(name);
+      return step ? step.value.get() : parentScope(name);
+    };
+    const stepSchemas = schema.fields ?? [];
+    const steps = stepSchemas.map((stepSchema, index) => {
+      const active = reactive.computed(() => this.currentStep.get() === index);
+      const stepInitial = asDict(initial[stepSchema.id]);
+      const step = new StepNode(stepSchema, this.scope, stepInitial, active);
+      this.byName.set(stepSchema.id, step);
+      return step;
+    });
+    this.steps = steps;
+    this.value = reactive.computed(() => {
+      const out = {};
+      for (const step of this.steps) out[step.id] = step.value.get();
+      return out;
+    });
+    this.visible = reactive.computed(() => evaluateCondition(schema.visibleWhen, parentScope, true));
+    this.enabled = reactive.computed(() => evaluateCondition(schema.enabledWhen, parentScope, true));
+  }
+  /** Validate every leaf in the step at `index` (defaults to the current step). */
+  validateStep(index) {
+    const i = index ?? this.currentStep.peek();
+    const step = this.steps[i];
+    if (!step) return true;
+    let ok = true;
+    eachLeaf([step], (leaf) => {
+      if (leaf.validate() !== null) ok = false;
+    });
+    return ok;
+  }
+  /** Advance to the next step after optionally validating the current one. Returns false if blocked. */
+  next() {
+    const validate = this.schema.validateOnNext !== false;
+    if (validate && !this.validateStep()) return false;
+    const cur = this.currentStep.peek();
+    if (cur < this.steps.length - 1) {
+      this.currentStep.set(cur + 1);
+      return true;
+    }
+    return false;
+  }
+  /** Go back one step (no validation). */
+  prev() {
+    this.currentStep.update((i) => Math.max(0, i - 1));
+  }
+  /** Jump to a step by index (does not validate). */
+  goTo(index) {
+    if (index >= 0 && index < this.steps.length) this.currentStep.set(index);
+  }
+  reset(initial) {
+    this.currentStep.set(0);
+    for (const step of this.steps) step.reset(asDict(initial[step.id]));
+  }
+};
 function buildTree(schemas, initial) {
   let byName;
   const scope = (name) => {
@@ -509,8 +506,10 @@ function buildTree(schemas, initial) {
 function eachLeaf(nodes, visit) {
   for (const node of nodes) {
     if (node.kind === "field") visit(node);
-    else if (node.kind === "group") eachLeaf(node.children, visit);
-    else for (const row of node.items.peek()) eachLeaf(row.group.children, visit);
+    else if (node.kind === "group" || node.kind === "step") eachLeaf(node.children, visit);
+    else if (node.kind === "steps") {
+      for (const step of node.steps) eachLeaf(step.children, visit);
+    } else for (const row of node.items.peek()) eachLeaf(row.group.children, visit);
   }
 }
 var defaultRenderer = null;
@@ -529,24 +528,37 @@ var Form = class {
   isDirty;
   /** True when no visible field currently has an error. */
   isValid;
-  submitting = signal(false);
+  submitting = reactive.signal(false);
   initialValues;
   initialSnapshot;
   rootByName;
   listeners = /* @__PURE__ */ new Map();
   disposeRenderer = null;
+  disposePersist = null;
   constructor(schema$1, initialValues = {}, options = {}) {
     this.schema = schema.parseSchema(schema$1);
     this.options = options;
     this.initialValues = initialValues;
-    const tree = buildTree(this.schema.fields, initialValues);
+    const fields = this.schema.locales?.length ? expandLocalized(this.schema.fields, this.schema.locales) : this.schema.fields;
+    const seed = loadPersisted(options.persistKey, initialValues);
+    const tree = buildTree(fields, seed);
     this.tree = tree.nodes;
     this.rootByName = tree.byName;
-    this.order = this.schema.fields.map((f) => f.id);
-    this.values = computed(() => collectTree(this.tree));
-    this.initialSnapshot = JSON.stringify(untrack(() => this.values.peek()));
-    this.isDirty = computed(() => JSON.stringify(this.values.get()) !== this.initialSnapshot);
-    this.isValid = computed(() => {
+    this.order = fields.map((f) => f.id);
+    this.values = reactive.computed(() => collectTree(this.tree));
+    if (options.persistKey) {
+      const key = options.persistKey;
+      this.disposePersist = reactive.effect(() => {
+        const v = this.values.get();
+        try {
+          localStorage.setItem(key, JSON.stringify(v));
+        } catch {
+        }
+      });
+    }
+    this.initialSnapshot = JSON.stringify(reactive.untrack(() => this.values.peek()));
+    this.isDirty = reactive.computed(() => JSON.stringify(this.values.get()) !== this.initialSnapshot);
+    this.isValid = reactive.computed(() => {
       let valid = true;
       eachLeaf(this.tree, (leaf) => {
         if (leaf.visible.get() && leaf.error.get() !== null) valid = false;
@@ -574,14 +586,24 @@ var Form = class {
   setFieldValue(field, value) {
     field.value.set(value);
     field.touched.set(true);
-    if (field.error.peek() !== null) field.validate();
+    field.validate();
     this.emit("change", { id: field.id, value });
   }
   setError(id, error) {
     this.field(id)?.error.set(error);
   }
+  /** Patch one field's schema at runtime (change type, label, options, validation, …). */
+  setFieldSchema(path, partial) {
+    this.field(path)?.patchSchema(partial);
+  }
+  /** Patch many fields' schemas at once: `form.patch({ state: { type: "text" }, … })`. */
+  patch(updates) {
+    reactive.batch(() => {
+      for (const [path, partial] of Object.entries(updates)) this.setFieldSchema(path, partial);
+    });
+  }
   setErrors(errors) {
-    batch(() => {
+    reactive.batch(() => {
       for (const [id, error] of Object.entries(errors)) this.setError(id, error);
     });
   }
@@ -590,47 +612,70 @@ var Form = class {
   }
   // ---- lifecycle ----------------------------------------------------------
   /** Validate every (visible) leaf field; returns true when the whole form is valid. */
-  validate() {
-    return untrack(() => {
+  validate(options) {
+    const allSteps = options?.allSteps ?? false;
+    return reactive.untrack(() => {
       let ok = true;
-      batch(() => {
+      reactive.batch(() => {
         eachLeaf(this.tree, (leaf) => {
-          if (leaf.validate() !== null) ok = false;
+          if (leaf.validate({ allSteps }) !== null) ok = false;
         });
       });
       return ok;
     });
   }
-  /** Run the submission pipeline: validate → transform → send → onSuccess/onError. */
-  async submit() {
-    if (!this.validate()) {
-      const error = new FormValidationError(this.collectErrors());
+  /** Find the first `steps` container in the field tree (if any). */
+  findSteps() {
+    return findSteps(this.tree);
+  }
+  /**
+   * Run the submission pipeline: validate → transform → send → onSuccess/onError.
+   * Pass an inline `transform` to shape the final payload, e.g.
+   * `form.submit((values) => ({ ...values, source: "web" }))`.
+   *
+   * Always **resolves** with a {@link SubmitResult} — never throws — so you can
+   * handle both outcomes from the API in one place:
+   * `const res = await form.submit(); res.ok ? res.data : res.error`.
+   */
+  async submit(transform) {
+    if (!this.validate({ allSteps: true })) {
+      const errors = this.collectErrors();
+      const error = new FormValidationError(errors);
       this.runErrorHandler(error);
       this.emit("error", error);
-      throw error;
+      return { ok: false, error, errors };
     }
     this.submitting.set(true);
-    const values = untrack(() => this.values.peek());
-    const payload = this.applyTransform(values);
+    const values = reactive.untrack(() => this.values.peek());
+    const named = this.applyTransform(values);
+    const payload = transform ? transform(named, this) : named;
     this.emit("submit", payload);
     try {
-      const result = await this.send(payload);
-      this.runSuccessHandler(result);
-      this.emit("success", result);
-      return result;
+      const data = await this.send(payload);
+      this.clearPersisted();
+      this.runSuccessHandler(data);
+      this.emit("success", data);
+      return { ok: true, data };
     } catch (error) {
       this.runErrorHandler(error);
       this.emit("error", error);
-      throw error;
+      return { ok: false, error };
     } finally {
       this.submitting.set(false);
     }
   }
   reset(values = this.initialValues) {
-    batch(() => {
+    reactive.batch(() => {
       resetNodes(this.tree, values);
     });
   }
+  /** Trigger a named form action: runs its handler (from options) and emits "action". */
+  action(name) {
+    const def = this.schema.actions?.find((a) => a.name === name);
+    const handler = def?.handler ? this.options.handlers?.[def.handler] : void 0;
+    handler?.(this);
+    this.emit("action", { name });
+  }
   /** Mount into a host element using the given renderer (or the registered default). */
   mount(host, renderer = defaultRenderer) {
     if (!renderer) {
@@ -645,8 +690,19 @@ var Form = class {
   destroy() {
     this.disposeRenderer?.();
     this.disposeRenderer = null;
+    this.disposePersist?.();
+    this.disposePersist = null;
     this.listeners.clear();
   }
+  /** Remove the cached draft from `localStorage` (called on a successful submit). */
+  clearPersisted() {
+    const key = this.options.persistKey;
+    if (!key || typeof localStorage === "undefined") return;
+    try {
+      localStorage.removeItem(key);
+    } catch {
+    }
+  }
   // ---- events -------------------------------------------------------------
   on(event, listener) {
     let set = this.listeners.get(event);
@@ -708,14 +764,64 @@ var FormValidationError = class extends Error {
 function collectTree(tree) {
   return collectValues(tree);
 }
+function loadPersisted(key, initial) {
+  if (!key || typeof localStorage === "undefined") return initial;
+  try {
+    const saved = localStorage.getItem(key);
+    if (saved) return { ...initial, ...JSON.parse(saved) };
+  } catch {
+  }
+  return initial;
+}
+function expandLocalized(fields, locales) {
+  return fields.map((f) => {
+    if (f.localized) {
+      const leafType = f.type === "group" || f.type === "collection" ? "text" : f.type;
+      const child = (loc) => {
+        const c = { id: loc, type: leafType, label: loc };
+        if (f.placeholder !== void 0) c["placeholder"] = f.placeholder;
+        if (f.validation !== void 0) c["validation"] = f.validation;
+        if (f.options !== void 0) c["options"] = f.options;
+        if (f.widget !== void 0) c["widget"] = f.widget;
+        if (f.tooltip !== void 0) c["tooltip"] = f.tooltip;
+        return c;
+      };
+      const group = {
+        id: f.id,
+        type: "group",
+        // Keep the `localized` flag so the renderer shows ONE input + a language
+        // switcher (instead of one input per locale). Value stays `{ en, ar }`.
+        localized: true,
+        fields: locales.map(child)
+      };
+      if (f.defaultLocale !== void 0) group["defaultLocale"] = f.defaultLocale;
+      for (const key of [
+        "label",
+        "visibleWhen",
+        "enabledWhen",
+        "class",
+        "classes",
+        "help",
+        "tooltip"
+      ]) {
+        if (f[key] !== void 0) group[key] = f[key];
+      }
+      return group;
+    }
+    if (f.fields) return { ...f, fields: expandLocalized(f.fields, locales) };
+    return f;
+  });
+}
 function collectLeaves(tree) {
   const out = /* @__PURE__ */ new Map();
   const walk = (nodes, prefix) => {
     for (const node of nodes) {
       const path = prefix ? `${prefix}.${node.id}` : node.id;
       if (node.kind === "field") out.set(path, node);
-      else if (node.kind === "group") walk(node.children, path);
-      else {
+      else if (node.kind === "group" || node.kind === "step") walk(node.children, path);
+      else if (node.kind === "steps") {
+        for (const step of node.steps) walk(step.children, `${path}.${step.id}`);
+      } else {
         node.items.peek().forEach((row, i) => walk(row.group.children, `${path}.${i}`));
       }
     }
@@ -728,7 +834,9 @@ function resolveLeaf(tree, rootByName, path) {
   let node = rootByName.get(parts[0]);
   for (let i = 1; i < parts.length && node; i++) {
     const part = parts[i];
-    if (node instanceof GroupNode) {
+    if (node instanceof GroupNode || node instanceof StepNode) {
+      node = node.byName.get(part);
+    } else if (node instanceof StepsNode) {
       node = node.byName.get(part);
     } else if (node instanceof CollectionNode) {
       node = node.items.peek()[Number(part)]?.group;
@@ -738,27 +846,63 @@ function resolveLeaf(tree, rootByName, path) {
   }
   return node && node.kind === "field" ? node : void 0;
 }
+function findSteps(tree) {
+  for (const node of tree) {
+    if (node.kind === "steps") return node;
+    if (node.kind === "group" || node.kind === "step") {
+      const found = findSteps(node.children);
+      if (found) return found;
+    } else if (node.kind === "collection") {
+      for (const row of node.items.peek()) {
+        const found = findSteps(row.group.children);
+        if (found) return found;
+      }
+    }
+  }
+  return void 0;
+}
 
+Object.defineProperty(exports, "batch", {
+  enumerable: true,
+  get: function () { return reactive.batch; }
+});
+Object.defineProperty(exports, "computed", {
+  enumerable: true,
+  get: function () { return reactive.computed; }
+});
+Object.defineProperty(exports, "effect", {
+  enumerable: true,
+  get: function () { return reactive.effect; }
+});
+Object.defineProperty(exports, "isTracking", {
+  enumerable: true,
+  get: function () { return reactive.isTracking; }
+});
+Object.defineProperty(exports, "signal", {
+  enumerable: true,
+  get: function () { return reactive.signal; }
+});
+Object.defineProperty(exports, "untrack", {
+  enumerable: true,
+  get: function () { return reactive.untrack; }
+});
 exports.CollectionNode = CollectionNode;
 exports.FieldState = FieldState;
 exports.Form = Form;
 exports.FormValidationError = FormValidationError;
 exports.GroupNode = GroupNode;
-exports.batch = batch;
+exports.StepNode = StepNode;
+exports.StepsNode = StepsNode;
 exports.buildTree = buildTree;
 exports.compileValidator = compileValidator;
-exports.computed = computed;
 exports.defaultValueFor = defaultValueFor;
 exports.eachLeaf = eachLeaf;
-exports.effect = effect;
 exports.evaluateCondition = evaluateCondition;
+exports.isPresentational = isPresentational;
 exports.isProviderRef = isProviderRef;
-exports.isTracking = isTracking;
 exports.referencedFields = referencedFields;
 exports.resolve = resolve;
 exports.resolveQuery = resolveQuery;
 exports.setDefaultRenderer = setDefaultRenderer;
-exports.signal = signal;
-exports.untrack = untrack;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map