formstand 0.8.0 → 0.10.0

package/dist/index.js

@@ -1,7 +1,8 @@
 import { createStore } from 'zustand/vanilla';
+import { devtools } from 'zustand/middleware';
 import { z } from 'zod';
-import { useRef, useEffect, createContext, useMemo, useCallback, useState, useId, useContext } from 'react';
-import { jsxs, jsx } from 'react/jsx-runtime';
+import { useRef, useEffect, createContext, useMemo, useCallback, useContext, useId, useState } from 'react';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { useStore } from 'zustand/react';
 import { useShallow } from 'zustand/react/shallow';
 
@@ -17,6 +18,20 @@ var moveFromTo = (from, to) => (n) => {
   return n;
 };
 var swapIndices = (a, b) => (n) => n === a ? b : n === b ? a : n;
+var invertMapper = (mapper, oldLength, newLength) => {
+  const oldByNew = new Map(
+    Array.from({ length: oldLength }, (_, oldIndex) => oldIndex).flatMap(
+      (oldIndex) => {
+        const newIndex = mapper(oldIndex);
+        return newIndex === null ? [] : [[newIndex, oldIndex]];
+      }
+    )
+  );
+  return Array.from(
+    { length: newLength },
+    (_, newIndex) => oldByNew.get(newIndex) ?? -1
+  );
+};
 var indexAndTail = (rest) => {
   const dotIdx = rest.indexOf(".");
   const idxStr = dotIdx === -1 ? rest : rest.slice(0, dotIdx);
@@ -40,6 +55,53 @@ var reKeyByArrayPath = (map, basePath, mapper) => {
   );
 };
 
+// src/core/arrayOpLog.ts
+var OP_LOG_LIMIT = 16;
+var MAX_LOG_PATHS = 256;
+var composeOps = (first, second) => ({
+  from: first.from,
+  to: second.to,
+  mapping: second.mapping.map(
+    (mid) => mid === -1 ? -1 : first.mapping[mid] ?? -1
+  )
+});
+var logs = /* @__PURE__ */ new WeakMap();
+var boundOps = (ops) => {
+  const [head, second] = ops;
+  if (ops.length <= OP_LOG_LIMIT || head === void 0 || second === void 0) {
+    return ops;
+  }
+  return head.to === second.from ? [composeOps(head, second), ...ops.slice(2)] : ops.slice(1);
+};
+var recordArrayOp = (store, path, record) => {
+  const existing = logs.get(store);
+  const byPath = existing ?? /* @__PURE__ */ new Map();
+  if (existing === void 0) logs.set(store, byPath);
+  const bounded = boundOps([...byPath.get(path) ?? [], record]);
+  byPath.delete(path);
+  byPath.set(path, bounded);
+  if (byPath.size > MAX_LOG_PATHS) {
+    const oldest = byPath.keys().next().value;
+    if (oldest !== void 0) byPath.delete(oldest);
+  }
+};
+var arrayOpsFor = (store, path) => logs.get(store)?.get(path) ?? [];
+var clearArrayOps = (store, path) => {
+  logs.get(store)?.delete(path);
+};
+var clearArrayOpsUnder = (store, path, keepSelf = false) => {
+  const byPath = logs.get(store);
+  if (byPath === void 0) return;
+  if (path === "") {
+    byPath.clear();
+    return;
+  }
+  const related = [...byPath.keys()].filter(
+    (p) => p === path && !keepSelf || p.startsWith(`${path}.`)
+  );
+  related.forEach((p) => byPath.delete(p));
+};
+
 // src/core/equality.ts
 var isPlainObject = (v) => {
   if (typeof v !== "object" || v === null) return false;
@@ -85,7 +147,18 @@ var isIndexSegment = (s) => {
   const n = Number(s);
   return Number.isInteger(n) && n >= 0 && String(n) === s;
 };
-var parsePath = (path) => path === "" ? [] : path.split(".").map((s) => isIndexSegment(s) ? Number(s) : s);
+var PARSE_CACHE_MAX = 4096;
+var parseCache = /* @__PURE__ */ new Map();
+var parsePath = (path) => {
+  const cached = parseCache.get(path);
+  if (cached !== void 0) return cached;
+  const segments = Object.freeze(
+    path === "" ? [] : path.split(".").map((s) => isIndexSegment(s) ? Number(s) : s)
+  );
+  if (parseCache.size >= PARSE_CACHE_MAX) parseCache.clear();
+  parseCache.set(path, segments);
+  return segments;
+};
 var isPlainRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 var readSegment = (obj, segment) => {
   if (obj == null) return void 0;
@@ -98,8 +171,9 @@ var getAtPath = (obj, path) => parsePath(path).reduce(readSegment, obj);
 var slotAtPath = (obj, path) => {
   const walked = parsePath(path).reduce(
     (acc, segment) => {
-      const outOfBounds = typeof segment === "number" && (Array.isArray(acc.current) ? segment >= acc.current.length : !isPlainRecord(acc.current));
-      return !acc.ok || outOfBounds ? { ok: false, current: void 0 } : { ok: true, current: readSegment(acc.current, segment) };
+      const container = acc.current;
+      const addressable = typeof segment === "number" ? Array.isArray(container) ? segment < container.length : isPlainRecord(container) : isPlainRecord(container);
+      return !acc.ok || !addressable ? { ok: false, current: void 0 } : { ok: true, current: readSegment(container, segment) };
     },
     { ok: true, current: obj }
   );
@@ -163,7 +237,7 @@ var expandIssue = (issue, prefix) => {
   return [{ path: issuePathToFormPath(at), message: issue.message }];
 };
 var flattenIssues = (issues) => issues.flatMap((issue) => expandIssue(issue, [])).reduce((acc, { path, message }) => {
-  const existing = acc[path] ?? [];
+  const existing = (Object.hasOwn(acc, path) ? acc[path] : void 0) ?? [];
   return existing.includes(message) ? acc : { ...acc, [path]: [...existing, message] };
 }, {});
 var validateSync = (schema, values) => {
@@ -263,7 +337,7 @@ var releaseAncestorEntries = (map, path) => {
   return kept.length === entries.length ? map : Object.fromEntries(kept);
 };
 var dirtyPathsOf = (values, initial, prefix) => {
-  if (valuesEqual(values, initial)) return [];
+  if (Object.is(values, initial)) return [];
   if (isPlainObject(values) && isPlainObject(initial)) {
     const keys = /* @__PURE__ */ new Set([...Object.keys(values), ...Object.keys(initial)]);
     const childPaths = [...keys].flatMap(
@@ -273,9 +347,11 @@ var dirtyPathsOf = (values, initial, prefix) => {
         prefix === "" ? k : `${prefix}.${k}`
       )
     );
-    return childPaths.length > 0 ? childPaths : [prefix];
+    if (childPaths.length > 0) return childPaths;
+    const sameKeySet = Object.keys(values).length === Object.keys(initial).length && Object.keys(values).every((k) => Object.hasOwn(initial, k));
+    return sameKeySet ? [] : [prefix];
   }
-  return [prefix];
+  return valuesEqual(values, initial) ? [] : [prefix];
 };
 var FORM_SEQ_KEY = "__form__";
 var SUBMIT_SEQ_KEY = "__submit__";
@@ -294,7 +370,9 @@ var reuseErrorRefs = (next, prev) => {
 };
 var scopeSettledResult = (result, path, viaSubschema) => result.kind !== "invalid" ? emptyErrors : viaSubschema ? prefixErrorKeys(result.errors, path) : path === "" ? result.errors : pickScope(result.errors, [path]);
 var mergeErrorChannels = (schema, server) => {
-  const extra = Object.entries(server).filter(([k]) => schema[k] === void 0);
+  const extra = Object.entries(server).filter(
+    ([k]) => !Object.hasOwn(schema, k)
+  );
   return extra.length === 0 ? schema : { ...schema, ...Object.fromEntries(extra) };
 };
 var errorChannels = (state, patch) => {
@@ -337,13 +415,27 @@ var createForm = (schema, options) => {
     mode: initialMode,
     reValidateMode: initialReValidateMode
   };
-  const store = createStore(() => initial);
+  const store = options.devtools === void 0 || options.devtools === false ? createStore(() => initial) : createStore()(
+    devtools(() => initial, {
+      name: typeof options.devtools === "string" ? options.devtools : "formstand",
+      // Non-production only, matching zustand's own devtools default:
+      // opting in during development must NOT stream every keystroke to
+      // an end user who happens to have the extension installed, where
+      // a module-singleton form's unbounded time-travel history is a
+      // real memory + serialization cost. Guarded for environments
+      // without process (a bundler defines NODE_ENV in real dev).
+      enabled: typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production"
+    })
+  );
   const commitFullPass = (state, next) => errorChannels(state, {
     schemaErrors: reuseErrorRefs(next, state.schemaErrors)
   });
   const validate = () => {
+    if (asyncScopes.has("")) {
+      return { kind: "pending", promise: validateAsyncOnForm() };
+    }
     try {
-      const result = validateSync(schema, store.getState().values);
+      const result = validateSyncLatched("", schema, store.getState().values);
       store.setState((state) => ({
         ...state,
         ...commitFullPass(
@@ -360,33 +452,65 @@ var createForm = (schema, options) => {
     }
   };
   const validateFields = (paths) => {
-    if (paths.length === 0) return true;
+    if (paths.length === 0) return { kind: "valid" };
     if (paths.some((p) => p === "")) {
       const result = validate();
-      return result.kind === "pending" ? result.promise.then((r) => r.kind === "valid") : result.kind === "valid";
+      return result.kind === "pending" ? { kind: "pending", promise: result.promise.then(settledFormResult) } : settledFormResult(result);
+    }
+    const values = store.getState().values;
+    const scopes = paths.map((path) => ({
+      path,
+      scope: fieldScopeFor(path, values)
+    }));
+    const allViaSubschema = scopes.every(
+      ({ scope }) => scope.kind === "skip" || scope.kind === "parse" && scope.viaSubschema
+    );
+    const anyLatched = allViaSubschema ? scopes.some(
+      ({ path, scope }) => scope.kind === "parse" && asyncScopes.has(path)
+    ) : asyncScopes.has("");
+    if (anyLatched) {
+      return { kind: "pending", promise: validateFieldsAsync(paths) };
     }
     try {
-      const result = validateSync(schema, store.getState().values);
+      if (allViaSubschema) {
+        const merged = scopes.reduce(
+          (acc, { path, scope }) => scope.kind === "skip" ? acc : {
+            ...acc,
+            ...scopeSettledResult(
+              validateSyncLatched(path, scope.schema, scope.value),
+              path,
+              true
+            )
+          },
+          {}
+        );
+        store.setState((state) => ({
+          ...state,
+          ...commitScopedErrors(state, merged, paths)
+        }));
+        return settledFields(merged);
+      }
+      const result = validateSyncLatched("", schema, values);
       const fullErrors = result.kind === "invalid" ? result.errors : emptyErrors;
+      const requestedErrors = pickScope(fullErrors, paths);
       store.setState((state) => ({
         ...state,
-        ...errorChannels(state, {
-          schemaErrors: reuseErrorRefs(
-            mergeScopedErrors(
-              state.schemaErrors,
-              pickScope(fullErrors, paths),
-              paths
-            ),
-            state.schemaErrors
-          ),
-          // A validation explicitly targeting these paths supersedes any
-          // server verdict on them.
-          serverErrors: omitScope(state.serverErrors, paths)
-        })
+        ...commitScopedErrors(state, requestedErrors, paths)
       }));
-      return Object.keys(fullErrors).every((k) => !inScopeOfAny(k, paths));
+      return settledFields(requestedErrors);
+    } catch (e) {
+      if (isAsyncRequiredError(e)) {
+        return { kind: "pending", promise: validateFieldsAsync(paths) };
+      }
+      throw e;
+    }
+  };
+  const asyncScopes = /* @__PURE__ */ new Set();
+  const validateSyncLatched = (key, scopeSchema, value) => {
+    try {
+      return validateSync(scopeSchema, value);
     } catch (e) {
-      if (isAsyncRequiredError(e)) return validateFieldsAsync(paths);
+      if (isAsyncRequiredError(e)) asyncScopes.add(key);
       throw e;
     }
   };
@@ -416,15 +540,6 @@ var createForm = (schema, options) => {
     const slot = slotAtPath(values, path);
     return slot.exists ? { kind: "parse", schema: sub, value: slot.value, viaSubschema: true } : { kind: "skip" };
   };
-  const scopedFieldErrors = (path) => {
-    const values = store.getState().values;
-    const scope = fieldScopeFor(path, values);
-    return scope.kind === "skip" ? emptyErrors : scopeSettledResult(
-      validateSync(scope.schema, scope.value),
-      path,
-      scope.viaSubschema
-    );
-  };
   const scopedFieldErrorsAsync = async (path, values) => {
     const scope = fieldScopeFor(path, values);
     return scope.kind === "skip" ? emptyErrors : scopeSettledResult(
@@ -437,17 +552,32 @@ var createForm = (schema, options) => {
     const messages = Object.values(scoped).flat();
     return messages.length === 0 ? { kind: "valid" } : { kind: "invalid", errors: messages };
   };
-  const commitFieldErrors = (state, scoped, path) => path === "" ? commitFullPass(state, scoped) : errorChannels(state, {
+  const settledFields = (scoped) => Object.keys(scoped).length === 0 ? { kind: "valid" } : { kind: "invalid", errors: scoped };
+  const settledFormResult = (result) => settledFields(result.kind === "invalid" ? result.errors : emptyErrors);
+  const commitScopedErrors = (state, scoped, paths) => errorChannels(state, {
     schemaErrors: reuseErrorRefs(
-      mergeScopedErrors(state.schemaErrors, scoped, [path]),
+      mergeScopedErrors(state.schemaErrors, scoped, paths),
       state.schemaErrors
     ),
-    serverErrors: omitScope(state.serverErrors, [path])
+    serverErrors: omitScope(state.serverErrors, paths)
   });
+  const commitFieldErrors = (state, scoped, path) => path === "" ? commitFullPass(state, scoped) : commitScopedErrors(state, scoped, [path]);
   const validateField = (path) => {
     warnMissingSchemaPath("validateField", path);
+    const scope = fieldScopeFor(path, store.getState().values);
+    if (scope.kind === "parse" && asyncScopes.has(scope.viaSubschema ? path : "")) {
+      return { kind: "pending", promise: validateFieldAsync(path) };
+    }
     try {
-      const scoped = scopedFieldErrors(path);
+      const scoped = scope.kind === "skip" ? emptyErrors : scopeSettledResult(
+        validateSyncLatched(
+          scope.viaSubschema ? path : "",
+          scope.schema,
+          scope.value
+        ),
+        path,
+        scope.viaSubschema
+      );
       store.setState((state) => ({
         ...state,
         ...commitFieldErrors(state, scoped, path)
@@ -500,10 +630,9 @@ var createForm = (schema, options) => {
     return result;
   };
   const validateFieldsAsync = async (paths) => {
-    if (paths.length === 0) return true;
+    if (paths.length === 0) return { kind: "valid" };
     if (paths.some((p) => p === "")) {
-      const result2 = await validateAsyncOnForm();
-      return result2.kind === "valid";
+      return settledFormResult(await validateAsyncOnForm());
     }
     const passes = new Map(paths.map((p) => [p, claimPass(p)]));
     const valuesAtStart = store.getState().values;
@@ -516,9 +645,8 @@ var createForm = (schema, options) => {
     }));
     const result = await validateAsync(schema, valuesAtStart);
     const fullErrors = result.kind === "invalid" ? result.errors : emptyErrors;
-    const requestedValid = Object.keys(fullErrors).every(
-      (k) => !inScopeOfAny(k, paths)
-    );
+    const requestedErrors = pickScope(fullErrors, paths);
+    const requested = settledFields(requestedErrors);
     const live = store.getState();
     const stillCurrent = paths.filter(
       (p) => sequences.get(p) === passes.get(p)
@@ -533,27 +661,21 @@ var createForm = (schema, options) => {
           )
         }));
       }
-      return requestedValid;
+      return requested;
     }
     store.setState((state) => ({
       ...state,
-      ...errorChannels(state, {
-        schemaErrors: reuseErrorRefs(
-          mergeScopedErrors(
-            state.schemaErrors,
-            pickScope(fullErrors, stillCurrent),
-            stillCurrent
-          ),
-          state.schemaErrors
-        ),
-        serverErrors: omitScope(state.serverErrors, stillCurrent)
-      }),
+      ...commitScopedErrors(
+        state,
+        pickScope(fullErrors, stillCurrent),
+        stillCurrent
+      ),
       isValidating: stillCurrent.reduce(
         (acc, p) => omitKey(acc, p),
         state.isValidating
       )
     }));
-    return requestedValid;
+    return requested;
   };
   const validateFieldAsync = async (path) => {
     warnMissingSchemaPath("validateFieldAsync", path);
@@ -603,12 +725,21 @@ var createForm = (schema, options) => {
       );
       return;
     }
+    const arr = Array.isArray(current) ? current : [];
+    const next = nextArray(arr);
+    const written = setAtPath(store.getState().values, path, next);
+    clearArrayOpsUnder(store, path, true);
+    if (Array.isArray(current) && getAtPath(written, path) === next) {
+      recordArrayOp(store, path, {
+        from: current,
+        to: next,
+        mapping: invertMapper(mapper, current.length, next.length)
+      });
+    }
     store.setState((state) => {
-      const live = getAtPath(state.values, path);
-      const arr = Array.isArray(live) ? live : [];
       return {
         ...state,
-        values: setAtPath(state.values, path, nextArray(arr)),
+        values: written,
         ...errorChannels(state, {
           schemaErrors: reKeyByArrayPath(state.schemaErrors, path, mapper),
           // Server entries on rows follow their rows through the index
@@ -749,24 +880,30 @@ var createForm = (schema, options) => {
         }
       });
     },
-    setValue: (path, value) => store.setState((state) => ({
-      ...state,
-      values: setAtPath(state.values, path, value),
-      ...errorChannels(state, {
-        serverErrors: releaseSpine(state.serverErrors, path)
-      })
-    })),
-    setValues: (next) => store.setState((state) => ({
-      ...state,
-      values: next,
-      ...errorChannels(state, {
-        serverErrors: releaseChangedSlices(
-          state.serverErrors,
-          state.values,
-          next
-        )
-      })
-    })),
+    setValue: (path, value) => {
+      clearArrayOpsUnder(store, path);
+      store.setState((state) => ({
+        ...state,
+        values: setAtPath(state.values, path, value),
+        ...errorChannels(state, {
+          serverErrors: releaseSpine(state.serverErrors, path)
+        })
+      }));
+    },
+    setValues: (next) => {
+      clearArrayOpsUnder(store, "");
+      store.setState((state) => ({
+        ...state,
+        values: next,
+        ...errorChannels(state, {
+          serverErrors: releaseChangedSlices(
+            state.serverErrors,
+            state.values,
+            next
+          )
+        })
+      }));
+    },
     setTouched: (path, touched = true) => store.setState((state) => ({
       ...state,
       touched: { ...state.touched, [path]: touched }
@@ -797,25 +934,32 @@ var createForm = (schema, options) => {
         })
       };
     }),
-    updateState: (updater) => store.setState((state) => {
-      const patch = updater(state);
-      if (Object.keys(patch).length === 0) return state;
-      if (patch.errors !== void 0 && patch.errors !== state.errors) {
-        console.warn(
-          "[formstand] `errors` is derived from schemaErrors/serverErrors \u2014 patch those channels instead; the direct `errors` patch is ignored."
-        );
+    updateState: (updater) => {
+      const valuesBefore = store.getState().values;
+      store.setState((state) => {
+        const patch = updater(state);
+        if (Object.keys(patch).length === 0) return state;
+        if (patch.errors !== void 0 && patch.errors !== state.errors) {
+          console.warn(
+            "[formstand] `errors` is derived from schemaErrors/serverErrors \u2014 patch those channels instead; the direct `errors` patch is ignored."
+          );
+        }
+        const next = { ...state, ...patch };
+        return {
+          ...next,
+          ...errorChannels(state, {
+            schemaErrors: next.schemaErrors,
+            serverErrors: next.serverErrors
+          })
+        };
+      });
+      if (store.getState().values !== valuesBefore) {
+        clearArrayOpsUnder(store, "");
       }
-      const next = { ...state, ...patch };
-      return {
-        ...next,
-        ...errorChannels(state, {
-          schemaErrors: next.schemaErrors,
-          serverErrors: next.serverErrors
-        })
-      };
-    }),
+    },
     adoptValues: (values) => {
       sequences.clear();
+      clearArrayOpsUnder(store, "");
       store.setState((state) => ({
         ...state,
         values,
@@ -833,6 +977,7 @@ var createForm = (schema, options) => {
     },
     reset: (nextInitial, resetOptions) => {
       sequences.clear();
+      clearArrayOpsUnder(store, "");
       store.setState((state) => {
         const init = nextInitial === void 0 ? state.initialValues : isPlainObject(state.initialValues) && isPlainObject(nextInitial) ? {
           ...state.initialValues,
@@ -854,23 +999,33 @@ var createForm = (schema, options) => {
         };
       });
     },
-    resetField: (path) => store.setState((state) => ({
-      ...state,
-      values: setAtPath(
-        state.values,
-        path,
-        getAtPath(state.initialValues, path)
-      ),
-      // A runtime "" path scopes the whole form (the imperative surface is
-      // string-typed even though FieldPath excludes ""). Server entries
-      // follow the setValue release contract (releaseSpine).
-      ...errorChannels(state, {
-        schemaErrors: path === "" ? emptyErrors : omitScope(state.schemaErrors, [path]),
-        serverErrors: releaseSpine(state.serverErrors, path)
-      }),
-      touched: path === "" ? emptyBools : omitScope(state.touched, [path]),
-      isValidating: path === "" ? emptyBools : omitScope(state.isValidating, [path])
-    })),
+    resetField: (path) => {
+      const initialSlot = slotAtPath(
+        store.getState().initialValues,
+        path
+      );
+      if (!initialSlot.exists) {
+        console.warn(
+          `[formstand] resetField("${path}"): path has no initial value (e.g. an appended array row); value left unchanged, field state cleared.`
+        );
+      }
+      if (initialSlot.exists) {
+        clearArrayOpsUnder(store, path);
+      }
+      store.setState((state) => ({
+        ...state,
+        values: initialSlot.exists ? setAtPath(state.values, path, initialSlot.value) : state.values,
+        // A runtime "" path scopes the whole form (the imperative surface is
+        // string-typed even though FieldPath excludes ""). Server entries
+        // follow the setValue release contract (releaseSpine).
+        ...errorChannels(state, {
+          schemaErrors: path === "" ? emptyErrors : omitScope(state.schemaErrors, [path]),
+          serverErrors: releaseSpine(state.serverErrors, path)
+        }),
+        touched: path === "" ? emptyBools : omitScope(state.touched, [path]),
+        isValidating: path === "" ? emptyBools : omitScope(state.isValidating, [path])
+      }));
+    },
     validate,
     validateField,
     validateFields,
@@ -924,29 +1079,32 @@ var createForm = (schema, options) => {
       return dirtyPathsOf(state.values, state.initialValues, "");
     },
     snapshot: () => store.getState(),
-    restore: (snap) => store.setState(() => {
-      const schemaErrors = snap.schemaErrors ?? emptyErrors;
-      const serverErrors = snap.serverErrors ?? emptyErrors;
-      return {
-        ...snap,
-        schemaErrors,
-        serverErrors,
-        errors: reuseErrorRefs(
-          mergeErrorChannels(schemaErrors, serverErrors),
-          snap.errors ?? emptyErrors
-        ),
-        // In-flight state is owned by live passes, never by snapshots: a
-        // snapshotted flag has no pass left to clear it (the pass that set
-        // it cleared its ORIGINAL entry when it settled), so restoring one
-        // would stick it forever. isSubmitting follows the same rule — a
-        // mid-submit snapshot restored later must not disable submit
-        // buttons forever, so it reflects the LIVE submit count instead of
-        // the snapshotted flag (a live pass's finally still resets it).
-        isValidating: emptyBools,
-        isValidatingForm: false,
-        isSubmitting: inFlight.count > 0
-      };
-    })
+    restore: (snap) => {
+      clearArrayOpsUnder(store, "");
+      store.setState(() => {
+        const schemaErrors = snap.schemaErrors ?? emptyErrors;
+        const serverErrors = snap.serverErrors ?? emptyErrors;
+        return {
+          ...snap,
+          schemaErrors,
+          serverErrors,
+          errors: reuseErrorRefs(
+            mergeErrorChannels(schemaErrors, serverErrors),
+            snap.errors ?? emptyErrors
+          ),
+          // In-flight state is owned by live passes, never by snapshots: a
+          // snapshotted flag has no pass left to clear it (the pass that set
+          // it cleared its ORIGINAL entry when it settled), so restoring one
+          // would stick it forever. isSubmitting follows the same rule — a
+          // mid-submit snapshot restored later must not disable submit
+          // buttons forever, so it reflects the LIVE submit count instead of
+          // the snapshotted flag (a live pass's finally still resets it).
+          isValidating: emptyBools,
+          isValidatingForm: false,
+          isSubmitting: inFlight.count > 0
+        };
+      });
+    }
   });
 };
 
@@ -966,6 +1124,74 @@ var shouldValidateOn = (trigger, mode, reValidateMode, submitAttempted, touched
       return true;
   }
 };
+
+// src/core/persist.ts
+var defaultStorage = () => {
+  try {
+    return typeof globalThis.localStorage === "undefined" ? null : globalThis.localStorage;
+  } catch {
+    return null;
+  }
+};
+var persistForm = (form, options) => {
+  const storage = options.storage ?? defaultStorage();
+  const debounceMs = options.debounceMs ?? 300;
+  const apply = options.apply ?? "adopt";
+  const applyDraft = (values) => apply === "restore" ? form.setValues(values) : form.adoptValues(values);
+  const restore = () => {
+    try {
+      const raw = storage === null ? null : storage.getItem(options.key);
+      if (raw === null) return false;
+      applyDraft(JSON.parse(raw));
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const writeDraft = (values) => {
+    try {
+      storage?.setItem(options.key, JSON.stringify(values));
+    } catch {
+    }
+  };
+  const timerRef = {
+    current: null
+  };
+  const cancelPending = () => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  };
+  if (apply !== "manual") {
+    restore();
+  }
+  const unsubscribe = form.watchValues((values) => {
+    cancelPending();
+    if (debounceMs === 0) {
+      writeDraft(values);
+    } else {
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        writeDraft(values);
+      }, debounceMs);
+    }
+  });
+  return Object.freeze({
+    restore,
+    clear: () => {
+      cancelPending();
+      try {
+        storage?.removeItem(options.key);
+      } catch {
+      }
+    },
+    dispose: () => {
+      cancelPending();
+      unsubscribe();
+    }
+  });
+};
 var useForm = (schema, options) => {
   const formRef = useRef(null);
   if (formRef.current === null) {
@@ -1048,15 +1274,7 @@ function useField(form, pathArg, options) {
       }, debounceMs);
       return;
     }
-    try {
-      form.validateField(path);
-    } catch (e) {
-      if (isAsyncRequiredError(e)) {
-        void form.validateFieldAsync(path);
-        return;
-      }
-      throw e;
-    }
+    form.validateField(path);
   }, [form, path, debounceMs]);
   const setValue = useCallback(
     (value) => {
@@ -1128,12 +1346,22 @@ function useField(form, pathArg, options) {
     [slice, emptyValue, setValue, setTouched, setError, clearError, validate, validateAsync2, onBlur]
   );
 }
-var EMPTY_ID_STATE = { items: [], ids: [], counter: 0 };
+
+// src/react/useVariantField.ts
+function useVariantField(form, unionPath, field) {
+  return useField(
+    form,
+    `${unionPath}.${field}`
+  );
+}
 var EMPTY_ITEMS = [];
+var mintNumbers = (needsMint) => new Map(
+  needsMint.flatMap((mint, i) => mint ? [i] : []).map((position, k) => [position, k + 1])
+);
 var reconcileIds = (prev, nextItems) => {
   if (prev.items === nextItems) return prev;
   if (prev.items.length === nextItems.length && prev.items.every((item, i) => Object.is(item, nextItems[i]))) {
-    return prev;
+    return { ...prev, items: nextItems };
   }
   const buckets = prev.items.reduce((acc, item, i) => {
     const bucket = acc.get(item);
@@ -1155,15 +1383,77 @@ var reconcileIds = (prev, nextItems) => {
     })
   );
   const reused = matchedIds.map((id, i) => id ?? leftoverAt.get(i) ?? null);
-  const mintCounts = reused.reduce((acc, id) => {
-    const count = acc[acc.length - 1] ?? 0;
-    return [...acc, id === null ? count + 1 : count];
-  }, []);
-  const minted = mintCounts[mintCounts.length - 1] ?? 0;
+  const mints = mintNumbers(reused.map((id) => id === null));
   const ids = reused.map(
-    (id, i) => id ?? `__zfa_${prev.counter + (mintCounts[i] ?? 0)}`
+    (id, i) => id ?? `${prev.prefix}${prev.counter + (mints.get(i) ?? 0)}`
   );
-  return { items: nextItems, ids, counter: prev.counter + minted };
+  return {
+    items: nextItems,
+    ids,
+    counter: prev.counter + mints.size,
+    prefix: prev.prefix
+  };
+};
+var mappedIdState = (prev, mapping, liveItems) => {
+  if (liveItems.length !== mapping.length) return null;
+  const aligned = mapping.every(
+    (src, i) => src === -1 ? true : prev.ids[src] !== void 0 && Object.is(liveItems[i], prev.items[src])
+  );
+  if (!aligned) return null;
+  const mints = mintNumbers(mapping.map((src) => src === -1));
+  const ids = mapping.map(
+    (src, i) => src === -1 ? `${prev.prefix}${prev.counter + (mints.get(i) ?? 0)}` : prev.ids[src]
+  );
+  return {
+    items: liveItems,
+    ids,
+    counter: prev.counter + mints.size,
+    prefix: prev.prefix
+  };
+};
+var MAX_ID_PATHS = 4096;
+var sharedIdEntries = /* @__PURE__ */ new WeakMap();
+var sharedIdEntry = (store, path) => {
+  const existingStore = sharedIdEntries.get(store);
+  const forStore = existingStore ?? { byPath: /* @__PURE__ */ new Map(), seq: 1 };
+  if (existingStore === void 0) sharedIdEntries.set(store, forStore);
+  const existing = forStore.byPath.get(path);
+  if (existing !== void 0) {
+    forStore.byPath.delete(path);
+    forStore.byPath.set(path, existing);
+    return existing;
+  }
+  const created = {
+    state: {
+      items: EMPTY_ITEMS,
+      ids: [],
+      counter: 0,
+      prefix: `__zfa_${forStore.seq}_`
+    }
+  };
+  forStore.seq += 1;
+  forStore.byPath.set(path, created);
+  if (forStore.byPath.size > MAX_ID_PATHS) {
+    const oldest = forStore.byPath.keys().next().value;
+    if (oldest !== void 0) forStore.byPath.delete(oldest);
+  }
+  return created;
+};
+var walkOps = (start, items, ops) => {
+  const walked = ops.reduce((acc, op) => {
+    const base = acc.items === op.from ? acc : reconcileIds(acc, op.from);
+    return mappedIdState(base, op.mapping, op.to) ?? base;
+  }, start);
+  return walked.items === items ? walked : reconcileIds(walked, items);
+};
+var deriveIds = (store, path, items) => {
+  const entry = sharedIdEntry(store, path);
+  if (entry.state.items === items) return entry.state;
+  const ops = arrayOpsFor(store, path);
+  if (ops.length > 0) clearArrayOps(store, path);
+  const next = walkOps(entry.state, items, ops);
+  entry.state = next;
+  return next;
 };
 function useFieldArray(form, pathArg) {
   const path = useStore(
@@ -1182,13 +1472,7 @@ function useFieldArray(form, pathArg) {
   );
   const items = slice.items;
   const error = slice.error;
-  const [idEntry, setIdEntry] = useState({ form, path, state: EMPTY_ID_STATE });
-  const base = idEntry.form === form && idEntry.path === path ? idEntry.state : { ...EMPTY_ID_STATE, counter: idEntry.state.counter };
-  const nextIdState = reconcileIds(base, items);
-  if (idEntry.form !== form || idEntry.path !== path || idEntry.state !== nextIdState) {
-    setIdEntry({ form, path, state: nextIdState });
-  }
-  const ids = nextIdState.ids;
+  const ids = deriveIds(form.store, path, items).ids;
   const push = useCallback(
     (item) => form.arrayPush(path, item),
     [form, path]
@@ -1269,6 +1553,11 @@ var capitalize = (name) => name.length === 0 ? name : name.charAt(0).toUpperCase
 var createFormHooks = (form, name) => {
   const structural = form;
   const useBoundField = (path, options) => useField(structural, path, options);
+  const useBoundVariantField = (unionPath, field) => useVariantField(
+    structural,
+    unionPath,
+    field
+  );
   const useBoundFieldArray = (path) => useFieldArray(structural, path);
   const useBoundSelector = (selector) => useFormSelector(structural, selector);
   const useBoundSelectorShallow = (selector) => useFormSelectorShallow(structural, selector);
@@ -1280,6 +1569,7 @@ var createFormHooks = (form, name) => {
   const prefix = capitalize(name ?? "");
   return {
     [`use${prefix}Field`]: useBoundField,
+    [`use${prefix}VariantField`]: useBoundVariantField,
     [`use${prefix}FieldArray`]: useBoundFieldArray,
     [`use${prefix}Selector`]: useBoundSelector,
     [`use${prefix}SelectorShallow`]: useBoundSelectorShallow,
@@ -1292,7 +1582,8 @@ var createFormHooks = (form, name) => {
 };
 
 // src/react/inputProps.ts
-var ariaInvalid = (field) => field.error !== void 0 && field.error.length > 0 ? true : void 0;
+var hasFieldError = (error) => error !== void 0 && error.length > 0;
+var ariaInvalid = (field) => hasFieldError(field.error) ? true : void 0;
 var numberToInputText = (value) => value === void 0 || value === null || Number.isNaN(value) ? "" : String(value);
 var parseNumberText = (text) => {
   if (text.trim() === "") return { kind: "empty" };
@@ -1324,6 +1615,48 @@ var numberInputProps = (field) => ({
   },
   onBlur: field.onBlur
 });
+var dateToInputText = (value) => {
+  if (value === void 0 || value === null || Number.isNaN(value.getTime())) {
+    return "";
+  }
+  const pad = (part) => String(part).padStart(2, "0");
+  return `${String(value.getFullYear()).padStart(4, "0")}-${pad(value.getMonth() + 1)}-${pad(value.getDate())}`;
+};
+var parseDateText = (text) => {
+  if (text.trim() === "") return { kind: "empty" };
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+  if (match === null) return { kind: "invalid" };
+  const [, year, month, day] = match;
+  const y = Number(year);
+  const date = new Date(y, Number(month) - 1, Number(day));
+  if (y < 100) date.setFullYear(y);
+  return date.getFullYear() === y && date.getMonth() === Number(month) - 1 && date.getDate() === Number(day) ? { kind: "date", value: date } : { kind: "invalid" };
+};
+var dateInputProps = (field) => ({
+  type: "date",
+  name: field.path,
+  value: dateToInputText(field.value),
+  "aria-invalid": ariaInvalid(field),
+  onChange: (e) => {
+    const parsed = parseDateText(e.target.value);
+    if (parsed.kind !== "date") {
+      field.setValue(field.emptyValue);
+      return;
+    }
+    const current = field.value;
+    const next = current instanceof Date && !Number.isNaN(current.getTime()) ? new Date(
+      parsed.value.getFullYear(),
+      parsed.value.getMonth(),
+      parsed.value.getDate(),
+      current.getHours(),
+      current.getMinutes(),
+      current.getSeconds(),
+      current.getMilliseconds()
+    ) : parsed.value;
+    field.setValue(next);
+  },
+  onBlur: field.onBlur
+});
 var checkboxProps = (field) => ({
   type: "checkbox",
   name: field.path,
@@ -1344,11 +1677,37 @@ var selectProps = (field) => ({
   },
   onBlur: field.onBlur
 });
-var hasError = (error) => error !== void 0 && error.length > 0;
+var useFieldA11y = (error) => {
+  const id = useId();
+  const errorId = `${id}-error`;
+  return {
+    id,
+    errorId,
+    describedBy: hasFieldError(error) ? errorId : void 0
+  };
+};
 var ErrorText = ({
   id,
   error
-}) => hasError(error) ? /* @__PURE__ */ jsx("span", { className: "zf-error", id, role: "alert", children: error?.[0] }) : null;
+}) => hasFieldError(error) ? /* @__PURE__ */ jsx("span", { className: "zf-error", id, role: "alert", children: error?.[0] }) : null;
+var FieldShell = ({
+  id,
+  errorId,
+  label,
+  error,
+  wrapLabel,
+  children
+}) => /* @__PURE__ */ jsxs("div", { className: "zf-field", children: [
+  wrapLabel === true ? /* @__PURE__ */ jsxs("label", { htmlFor: id, className: "zf-label", children: [
+    children,
+    " ",
+    label
+  ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+    label !== void 0 ? /* @__PURE__ */ jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
+    children
+  ] }),
+  /* @__PURE__ */ jsx(ErrorText, { id: errorId, error })
+] });
 var TextField = ({
   form,
   path,
@@ -1358,25 +1717,60 @@ var TextField = ({
   autoComplete,
   ref
 }) => {
-  const id = useId();
-  const errorId = `${id}-error`;
   const field = useField(form, path);
-  return /* @__PURE__ */ jsxs("div", { className: "zf-field", children: [
-    label !== void 0 ? /* @__PURE__ */ jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
-    /* @__PURE__ */ jsx(
-      "input",
-      {
-        id,
-        ref,
-        ...textInputProps(field),
-        type,
-        placeholder,
-        autoComplete,
-        "aria-describedby": hasError(field.error) ? errorId : void 0
-      }
-    ),
-    /* @__PURE__ */ jsx(ErrorText, { id: errorId, error: field.error })
-  ] });
+  const a11y = useFieldA11y(field.error);
+  return /* @__PURE__ */ jsx(
+    FieldShell,
+    {
+      id: a11y.id,
+      errorId: a11y.errorId,
+      label,
+      error: field.error,
+      children: /* @__PURE__ */ jsx(
+        "input",
+        {
+          id: a11y.id,
+          ref,
+          ...textInputProps(field),
+          type,
+          placeholder,
+          autoComplete,
+          "aria-describedby": a11y.describedBy
+        }
+      )
+    }
+  );
+};
+var DateField = ({
+  form,
+  path,
+  label,
+  min,
+  max,
+  ref
+}) => {
+  const field = useField(form, path);
+  const a11y = useFieldA11y(field.error);
+  return /* @__PURE__ */ jsx(
+    FieldShell,
+    {
+      id: a11y.id,
+      errorId: a11y.errorId,
+      label,
+      error: field.error,
+      children: /* @__PURE__ */ jsx(
+        "input",
+        {
+          id: a11y.id,
+          ref,
+          ...dateInputProps(field),
+          min,
+          max,
+          "aria-describedby": a11y.describedBy
+        }
+      )
+    }
+  );
 };
 var IDLE_EDIT = { raw: null, pushed: void 0 };
 var useNumberInput = (field) => {
@@ -1390,7 +1784,7 @@ var useNumberInput = (field) => {
     name: field.path,
     value: raw ?? numberToInputText(field.value),
     inputMode: "decimal",
-    "aria-invalid": hasError(field.error) ? true : void 0,
+    "aria-invalid": hasFieldError(field.error) ? true : void 0,
     onChange: (e) => {
       const text = e.target.value;
       const parsed = parseNumberText(text);
@@ -1423,25 +1817,29 @@ var NumberField = ({
   placeholder,
   ref
 }) => {
-  const id = useId();
-  const errorId = `${id}-error`;
   const field = useField(form, path);
   const binding = useNumberInput(field);
-  return /* @__PURE__ */ jsxs("div", { className: "zf-field", children: [
-    label !== void 0 ? /* @__PURE__ */ jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
-    /* @__PURE__ */ jsx(
-      "input",
-      {
-        id,
-        ref,
-        type: "text",
-        ...binding,
-        placeholder,
-        "aria-describedby": hasError(field.error) ? errorId : void 0
-      }
-    ),
-    /* @__PURE__ */ jsx(ErrorText, { id: errorId, error: field.error })
-  ] });
+  const a11y = useFieldA11y(field.error);
+  return /* @__PURE__ */ jsx(
+    FieldShell,
+    {
+      id: a11y.id,
+      errorId: a11y.errorId,
+      label,
+      error: field.error,
+      children: /* @__PURE__ */ jsx(
+        "input",
+        {
+          id: a11y.id,
+          ref,
+          type: "text",
+          ...binding,
+          placeholder,
+          "aria-describedby": a11y.describedBy
+        }
+      )
+    }
+  );
 };
 var CheckboxField = ({
   form,
@@ -1449,25 +1847,27 @@ var CheckboxField = ({
   label,
   ref
 }) => {
-  const id = useId();
-  const errorId = `${id}-error`;
   const field = useField(form, path);
-  return /* @__PURE__ */ jsxs("div", { className: "zf-field", children: [
-    /* @__PURE__ */ jsxs("label", { htmlFor: id, className: "zf-label", children: [
-      /* @__PURE__ */ jsx(
+  const a11y = useFieldA11y(field.error);
+  return /* @__PURE__ */ jsx(
+    FieldShell,
+    {
+      id: a11y.id,
+      errorId: a11y.errorId,
+      label,
+      error: field.error,
+      wrapLabel: true,
+      children: /* @__PURE__ */ jsx(
         "input",
         {
-          id,
+          id: a11y.id,
           ref,
           ...checkboxProps(field),
-          "aria-describedby": hasError(field.error) ? errorId : void 0
+          "aria-describedby": a11y.describedBy
         }
-      ),
-      " ",
-      label
-    ] }),
-    /* @__PURE__ */ jsx(ErrorText, { id: errorId, error: field.error })
-  ] });
+      )
+    }
+  );
 };
 var SelectField = ({
   form,
@@ -1477,43 +1877,48 @@ var SelectField = ({
   placeholder,
   ref
 }) => {
-  const id = useId();
-  const errorId = `${id}-error`;
   const field = useField(form, path);
+  const a11y = useFieldA11y(field.error);
+  const select = selectProps(field);
   const clearable = field.emptyValue === null;
-  const showEmptyOption = clearable || field.value === void 0 || field.value === null || placeholder !== void 0;
-  return /* @__PURE__ */ jsxs("div", { className: "zf-field", children: [
-    label !== void 0 ? /* @__PURE__ */ jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
-    /* @__PURE__ */ jsxs(
-      "select",
-      {
-        id,
-        ref,
-        ...selectProps(field),
-        "aria-describedby": hasError(field.error) ? errorId : void 0,
-        children: [
-          showEmptyOption ? /* @__PURE__ */ jsx("option", { value: "", disabled: !clearable, children: placeholder ?? "" }) : null,
-          options.map((opt, index) => (
-            // Index-qualified: option lists may legitimately repeat a value
-            // (e.g. differently-labelled aliases), and bare value keys would
-            // collide.
-            /* @__PURE__ */ jsx("option", { value: opt.value, children: opt.label }, `${index}-${opt.value}`)
-          ))
-        ]
-      }
-    ),
-    /* @__PURE__ */ jsx(ErrorText, { id: errorId, error: field.error })
-  ] });
+  const hasExplicitEmptyOption = options.some((opt) => opt.value === "");
+  const showEmptyOption = !hasExplicitEmptyOption && (clearable || select.value === "" || placeholder !== void 0);
+  return /* @__PURE__ */ jsx(
+    FieldShell,
+    {
+      id: a11y.id,
+      errorId: a11y.errorId,
+      label,
+      error: field.error,
+      children: /* @__PURE__ */ jsxs(
+        "select",
+        {
+          id: a11y.id,
+          ref,
+          ...select,
+          "aria-describedby": a11y.describedBy,
+          children: [
+            showEmptyOption ? /* @__PURE__ */ jsx("option", { value: "", disabled: !clearable, children: placeholder ?? "" }) : null,
+            options.map((opt, index) => (
+              // Index-qualified: option lists may legitimately repeat a value
+              // (e.g. differently-labelled aliases), and bare value keys would
+              // collide.
+              /* @__PURE__ */ jsx("option", { value: opt.value, children: opt.label }, `${index}-${opt.value}`)
+            ))
+          ]
+        }
+      )
+    }
+  );
 };
 
 // src/react/focusError.ts
-var focusableControls = (scope) => [
+var namedControls = (scope) => [
   ...scope.querySelectorAll(
     "input[name], select[name], textarea[name]"
   )
-].filter(
-  (el) => !el.matches(':disabled, [type="hidden"]') && el.closest("dialog:not([open])") === null
-);
+];
+var isFocusCandidate = (el) => !el.matches(':disabled, [type="hidden"]') && el.closest("dialog:not([open])") === null;
 var holdsFocus = (el) => {
   const rootNode = el.getRootNode();
   const active = rootNode instanceof Document || rootNode instanceof ShadowRoot ? rootNode.activeElement : document.activeElement;
@@ -1533,19 +1938,19 @@ var focusFirstError = (errors, root) => {
     (k) => k !== "" && (errors[k]?.length ?? 0) > 0
   );
   const hasRootError = (errors[""]?.length ?? 0) > 0;
-  const controls = focusableControls(scope);
-  const fieldMatches = controls.filter(
-    (el) => nameMatchesAny(el, erroredPaths)
-  );
+  const controls = namedControls(scope);
+  const fieldMatches = controls.filter((el) => nameMatchesAny(el, erroredPaths)).filter(isFocusCandidate);
   const rootFallbackApplies = hasRootError && (root !== void 0 || document.querySelectorAll("form").length <= 1);
-  const candidates = fieldMatches.length > 0 ? fieldMatches : rootFallbackApplies ? controls : [];
+  const candidates = fieldMatches.length > 0 ? fieldMatches : rootFallbackApplies ? controls.filter(isFocusCandidate) : [];
   return focusFirstOf(candidates);
 };
 var focusField = (path, root) => {
-  const controls = focusableControls(root ?? document);
-  return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(controls) : focusFirstOf(controls.filter((el) => nameMatchesAny(el, [path])));
+  const controls = namedControls(root ?? document);
+  return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(controls.filter(isFocusCandidate)) : focusFirstOf(
+    controls.filter((el) => nameMatchesAny(el, [path])).filter(isFocusCandidate)
+  );
 };
 
-export { CheckboxField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, createFormHooks, emptyValueForSchema, flattenIssues, focusField, focusFirstError, getAtPath, isAsyncRequiredError, numberInputProps, numberToInputText, parseNumberText, parsePath, selectProps, setAtPath, shouldValidateOn, textInputProps, useField, useFieldArray, useForm, useFormError, useFormSelector, useFormSelectorShallow, useIsDirty, useIsSubmitting, useIsValid, useSubmitCount, validateAsync, validateSync };
+export { CheckboxField, DateField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, createFormHooks, dateInputProps, dateToInputText, emptyValueForSchema, flattenIssues, focusField, focusFirstError, getAtPath, hasFieldError, isAsyncRequiredError, numberInputProps, numberToInputText, parseDateText, parseNumberText, parsePath, persistForm, selectProps, setAtPath, shouldValidateOn, textInputProps, useField, useFieldArray, useForm, useFormError, useFormSelector, useFormSelectorShallow, useIsDirty, useIsSubmitting, useIsValid, useSubmitCount, useVariantField, validateAsync, validateSync };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map