formstand 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.15.0 — 2026-08-04
+
+### Fixed
+
+- **`persistForm` no longer applies a draft from a different schema shape.**
+  The stored JSON was cast straight to the values type and adopted, so a draft
+  written before a schema change rebased the form onto values its own schema
+  rejects. Because the default `adopt` mode clears errors and resets the
+  baseline, the form then read **clean** while holding them, which is the worst
+  version of the failure.
+
+  A draft is now ignored when its shape conflicts with the form's: a path
+  holding a string where the form expects an object, an array of strings where
+  it expects rows. Only overlapping paths are compared, and only their kinds,
+  so a half-filled draft still restores (a draft is work in progress and would
+  fail full validation by design), and so does one that filled an optional the
+  initial values left empty.
+
+### Added
+
+- **`persistForm`'s `version` option.** Renames and removals are invisible to
+  the shape guard above, because JSON drops undefined slots and an absent key
+  is indistinguishable from an unfilled optional. `version` covers those: it is
+  stored with the draft and a mismatch discards it. Leaving it unset keeps the
+  stored format byte-identical, so existing drafts survive the upgrade.
+
 ## 0.14.0 — 2026-07-31
 
 ### Added

package/README.md

@@ -12,6 +12,7 @@ Zod-schema-first form state for React 19, backed by zustand.
 - **Field arrays** with stable IDs that survive reorders, inserts, and removes.
 - **Bound input components** with the accessibility wiring already done.
 - **A generator**: [`formstand-cli`](https://scrumrot.github.io/formstand/documentation/cli/) writes the whole component from your schema, for six UI kits.
+- **[Devtools](https://scrumrot.github.io/formstand/documentation/devtools)**: `formstand/devtools` is a panel showing every field, both error channels, and the live diff. Renders nothing in production.
 
 ## Install
 
@@ -111,6 +112,7 @@ PATCH-ready payload of exactly what changed.
 | Components | `TextField`, `NumberField`, `DateField`, `CheckboxField`, `SelectField`, the prop builders, `useNumberInput`, `focusField`/`focusFirstError` | [Components & bindings](https://scrumrot.github.io/formstand/documentation/api/components) |
 | Validation | five modes plus `reValidateMode`, field-scoped passes, async refines with race handling, per-field `debounceMs` | [Validation](https://scrumrot.github.io/formstand/documentation/validation) |
 | Utilities | `parsePath`/`getAtPath`/`setAtPath`, `validateSync`/`validateAsync`, `persistForm`, and the full type list | [Utilities & types](https://scrumrot.github.io/formstand/documentation/api/utilities) |
+| Devtools | `<FormstandDevtools form={form} />` from `formstand/devtools` | [Devtools](https://scrumrot.github.io/formstand/documentation/devtools) |
 
 Coming from react-hook-form? The
 [migration guide](https://scrumrot.github.io/formstand/documentation/migrating-from-react-hook-form)

package/dist/index.cjs

@@ -1140,6 +1140,25 @@ var shouldValidateOn = (trigger, mode, reValidateMode, submitAttempted, touched
 };
 
 // src/core/persist.ts
+var kindOf = (value) => value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+var conflictsWith = (draft, reference) => {
+  if (draft === void 0 || draft === null) return false;
+  if (reference === void 0 || reference === null) return false;
+  const draftKind = kindOf(draft);
+  const referenceKind = kindOf(reference);
+  if (draftKind !== referenceKind) return true;
+  if (draftKind === "array") {
+    const [d] = draft;
+    const [r] = reference;
+    return conflictsWith(d, r);
+  }
+  if (draftKind === "object") {
+    const d = draft;
+    const r = reference;
+    return Object.keys(d).some((key) => conflictsWith(d[key], r[key]));
+  }
+  return false;
+};
 var defaultStorage = () => {
   try {
     return typeof globalThis.localStorage === "undefined" ? null : globalThis.localStorage;
@@ -1152,11 +1171,29 @@ var persistForm = (form, options) => {
   const debounceMs = options.debounceMs ?? 300;
   const apply = options.apply ?? "adopt";
   const applyDraft = (values) => apply === "restore" ? form.setValues(values) : form.adoptValues(values);
+  const referenceShape = () => {
+    try {
+      return JSON.parse(JSON.stringify(form.getState().initialValues));
+    } catch {
+      return void 0;
+    }
+  };
   const restore = () => {
     try {
       const raw = storage === null ? null : storage.getItem(options.key);
       if (raw === null) return false;
-      applyDraft(JSON.parse(raw));
+      const parsed = JSON.parse(raw);
+      const versioned = options.version !== void 0 && typeof parsed === "object" && parsed !== null && "__v" in parsed;
+      if (options.version !== void 0 && !versioned) return false;
+      const wrapper = parsed;
+      if (versioned && wrapper.__v !== options.version) return false;
+      if (versioned && wrapper.values === void 0) return false;
+      const values = versioned ? wrapper.values : parsed;
+      const reference = referenceShape();
+      if (reference !== void 0 && conflictsWith(values, reference)) {
+        return false;
+      }
+      applyDraft(values);
       return true;
     } catch {
       return false;
@@ -1164,7 +1201,12 @@ var persistForm = (form, options) => {
   };
   const writeDraft = (values) => {
     try {
-      storage?.setItem(options.key, JSON.stringify(values));
+      storage?.setItem(
+        options.key,
+        JSON.stringify(
+          options.version === void 0 ? values : { __v: options.version, values }
+        )
+      );
     } catch {
     }
   };