formstand 0.20.0 → 0.22.0

package/dist/index.js

@@ -1,7 +1,7 @@
-import { getAtPath, slotAtPath, setAtPath, isPlainObject, hasOwnSlot, valuesEqual, useFormSelectorShallow, isFieldDirty, useFormSelector, parsePath } from './chunk-N7WPXYCU.js';
-export { getAtPath, parsePath, setAtPath, useFormSelector, useFormSelectorShallow } from './chunk-N7WPXYCU.js';
-import { shouldValidateOn } from './chunk-MQ6262S3.js';
-export { shouldValidateOn } from './chunk-MQ6262S3.js';
+import { isDevToolsBuild, getAtPath, isDevBuild, slotAtPath, setAtPath, isPlainObject, hasOwnSlot, valuesEqual, useFormSelectorShallow, isFieldDirty, useFormSelector, parsePath } from './chunk-BMXIZEI4.js';
+export { getAtPath, parsePath, setAtPath, useFormSelector, useFormSelectorShallow } from './chunk-BMXIZEI4.js';
+import { flagAt, entryAt, shouldValidateOn } from './chunk-V3PDMTPP.js';
+export { shouldValidateOn } from './chunk-V3PDMTPP.js';
 import { createStore } from 'zustand/vanilla';
 import { devtools } from 'zustand/middleware';
 import { z } from 'zod';
@@ -114,10 +114,17 @@ 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 = (Object.hasOwn(acc, path) ? acc[path] : void 0) ?? [];
-  return existing.includes(message) ? acc : { ...acc, [path]: [...existing, message] };
-}, {});
+var flattenIssues = (issues) => Object.fromEntries(
+  issues.flatMap((issue) => expandIssue(issue, [])).reduce((acc, { path, message }) => {
+    const existing = acc.get(path);
+    if (existing === void 0) {
+      acc.set(path, [message]);
+    } else if (!existing.includes(message)) {
+      existing.push(message);
+    }
+    return acc;
+  }, /* @__PURE__ */ new Map())
+);
 var validateSync = (schema, values) => {
   const result = schema.safeParse(values);
   return result.success ? { kind: "valid", data: result.data } : { kind: "invalid", errors: flattenIssues(result.error.issues) };
@@ -182,6 +189,34 @@ var hasChecks = (s) => {
   const checks = s.def.checks;
   return checks !== void 0 && checks.length > 0;
 };
+var fieldSchemaForIntrospection = (schema, path) => {
+  const childOf = (s, segment) => {
+    const inner = unwrapForWalk(s);
+    if (inner !== null) return childOf(inner, segment);
+    if (s instanceof z.ZodObject && typeof segment === "string") {
+      const shape = s.shape;
+      return Object.hasOwn(shape, segment) ? shape[segment] ?? null : null;
+    }
+    if (s instanceof z.ZodArray && typeof segment === "number") {
+      return s.element;
+    }
+    if (s instanceof z.ZodTuple && typeof segment === "number") {
+      return s.def.items[segment] ?? null;
+    }
+    if (s instanceof z.ZodDiscriminatedUnion || s instanceof z.ZodUnion) {
+      const options = s.def.options;
+      return options.reduce(
+        (found, option) => found ?? childOf(option, segment),
+        null
+      );
+    }
+    return null;
+  };
+  return parsePath(path).reduce(
+    (current, segment) => current === null ? null : childOf(current, segment),
+    schema
+  );
+};
 var fieldSchemaAtPath = (schema, path) => parsePath(path).reduce((current, segment) => {
   if (current === null || hasChecks(current)) return null;
   if (current instanceof z.ZodObject && typeof segment === "string") {
@@ -200,6 +235,12 @@ var emptyErrors = {};
 var emptyBools = {};
 var identityMapper = (n) => n;
 var omitKey = (map, key) => Object.fromEntries(Object.entries(map).filter(([k]) => k !== key));
+var omitKeys = (map, keys) => {
+  if (keys.size === 0) return map;
+  const entries = Object.entries(map);
+  const kept = entries.filter(([k]) => !keys.has(k));
+  return kept.length === entries.length ? map : Object.fromEntries(kept);
+};
 var inScopeOfAny = (key, paths) => paths.some((p) => isPathOrChild(key, p));
 var omitScope = (map, paths) => {
   const entries = Object.entries(map);
@@ -238,13 +279,13 @@ var stringArraysEqual = (a, b) => a === b || a.length === b.length && a.every((v
 var reuseErrorRefs = (next, prev) => {
   if (next === prev) return prev;
   const entries = Object.entries(next).map(([k, v]) => {
-    const old = prev[k];
+    const old = entryAt(prev, k);
     return [
       k,
       old !== void 0 && stringArraysEqual(old, v) ? old : v
     ];
   });
-  const sameShape = entries.length === Object.keys(prev).length && entries.every(([k, v]) => prev[k] === v);
+  const sameShape = entries.length === Object.keys(prev).length && entries.every(([k, v]) => entryAt(prev, k) === v);
   return sameShape ? prev : Object.fromEntries(entries);
 };
 var scopeSettledResult = (result, path, viaSubschema) => result.kind !== "invalid" ? emptyErrors : viaSubschema ? prefixErrorKeys(result.errors, path) : path === "" ? result.errors : pickScope(result.errors, [path]);
@@ -301,9 +342,10 @@ var createForm = (schema, options) => {
       // 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"
+      // real memory + serialization cost. Fail-closed gate: a runtime
+      // without a readable NODE_ENV (CDN/ESM, Deno, a worker) reads as
+      // production here, unlike the console-warning gate.
+      enabled: isDevToolsBuild()
     })
   );
   const commitFullPass = (state, next) => errorChannels(state, {
@@ -419,13 +461,19 @@ var createForm = (schema, options) => {
     const slot = slotAtPath(values, path);
     return slot.exists ? { kind: "parse", schema: sub, value: slot.value, viaSubschema: true } : { kind: "skip" };
   };
-  const scopedFieldErrorsAsync = async (path, values) => {
-    const scope = fieldScopeFor(path, values);
-    return scope.kind === "skip" ? emptyErrors : scopeSettledResult(
-      await validateAsync(scope.schema, scope.value),
-      path,
-      scope.viaSubschema
-    );
+  const parseScopeAsync = async (path, scope) => scope.kind === "skip" ? emptyErrors : scopeSettledResult(
+    await validateAsync(scope.schema, scope.value),
+    path,
+    scope.viaSubschema
+  );
+  const scopeStale = (scope, path, valuesAtStart, live) => {
+    if (live === valuesAtStart) return false;
+    switch (scope.kind) {
+      case "skip":
+        return slotAtPath(live, path).exists;
+      case "parse":
+        return scope.viaSubschema ? !Object.is(getAtPath(live, path), scope.value) : true;
+    }
   };
   const fieldResult = (scoped) => {
     const messages = Object.values(scoped).flat();
@@ -473,10 +521,10 @@ var createForm = (schema, options) => {
     const value = getAtPath(state.values, path);
     return {
       value,
-      error: state.errors[path],
-      touched: state.touched[path] ?? false,
+      error: entryAt(state.errors, path),
+      touched: flagAt(state.touched, path),
       dirty: isFieldDirty(value, getAtPath(state.initialValues, path)),
-      isValidating: state.isValidating[path] ?? false
+      isValidating: flagAt(state.isValidating, path)
     };
   };
   const sequences = /* @__PURE__ */ new Map();
@@ -515,44 +563,66 @@ var createForm = (schema, options) => {
     }
     const passes = new Map(paths.map((p) => [p, claimPass(p)]));
     const valuesAtStart = store.getState().values;
+    const scopes = paths.map((path) => ({
+      path,
+      scope: fieldScopeFor(path, valuesAtStart)
+    }));
+    const allViaSubschema = scopes.every(
+      ({ scope }) => scope.kind === "skip" || scope.kind === "parse" && scope.viaSubschema
+    );
     store.setState((state) => ({
       ...state,
-      isValidating: paths.reduce(
-        (acc, p) => ({ ...acc, [p]: true }),
-        { ...state.isValidating }
-      )
+      isValidating: {
+        ...state.isValidating,
+        ...Object.fromEntries(paths.map((p) => [p, true]))
+      }
     }));
-    const result = await validateAsync(schema, valuesAtStart);
-    const fullErrors = result.kind === "invalid" ? result.errors : emptyErrors;
-    const requestedErrors = pickScope(fullErrors, paths);
+    const parsed = allViaSubschema ? {
+      kind: "slots",
+      byPath: new Map(
+        await Promise.all(
+          scopes.map(
+            async ({ path, scope }) => [path, await parseScopeAsync(path, scope)]
+          )
+        )
+      )
+    } : {
+      kind: "full",
+      errors: await validateAsync(schema, valuesAtStart).then(
+        (result) => result.kind === "invalid" ? result.errors : emptyErrors
+      )
+    };
+    const errorsFor = (path) => {
+      switch (parsed.kind) {
+        case "slots":
+          return parsed.byPath.get(path) ?? emptyErrors;
+        case "full":
+          return pickScope(parsed.errors, [path]);
+      }
+    };
+    const requestedErrors = Object.fromEntries(
+      paths.flatMap((path) => Object.entries(errorsFor(path)))
+    );
     const requested = settledFields(requestedErrors);
     const live = store.getState();
-    const stillCurrent = paths.filter(
-      (p) => sequences.get(p) === passes.get(p)
+    const owned = scopes.filter(
+      ({ path }) => sequences.get(path) === passes.get(path)
     );
-    if (live.values !== valuesAtStart) {
-      if (stillCurrent.length > 0) {
-        store.setState((state) => ({
-          ...state,
-          isValidating: stillCurrent.reduce(
-            (acc, p) => omitKey(acc, p),
-            state.isValidating
-          )
-        }));
-      }
-      return requested;
-    }
+    const fresh = owned.filter(
+      ({ path, scope }) => !scopeStale(scope, path, valuesAtStart, live.values)
+    ).map(({ path }) => path);
+    const ownedKeys = new Set(owned.map(({ path }) => path));
+    if (owned.length === 0) return requested;
     store.setState((state) => ({
       ...state,
-      ...commitScopedErrors(
+      ...fresh.length === 0 ? {} : commitScopedErrors(
         state,
-        pickScope(fullErrors, stillCurrent),
-        stillCurrent
+        Object.fromEntries(
+          fresh.flatMap((path) => Object.entries(errorsFor(path)))
+        ),
+        fresh
       ),
-      isValidating: stillCurrent.reduce(
-        (acc, p) => omitKey(acc, p),
-        state.isValidating
-      )
+      isValidating: omitKeys(state.isValidating, ownedKeys)
     }));
     return requested;
   };
@@ -566,14 +636,15 @@ var createForm = (schema, options) => {
     }
     const pass = claimPass(path);
     const valuesAtStart = store.getState().values;
+    const scope = fieldScopeFor(path, valuesAtStart);
     store.setState((state) => ({
       ...state,
       isValidating: { ...state.isValidating, [path]: true }
     }));
-    const scoped = await scopedFieldErrorsAsync(path, valuesAtStart);
+    const scoped = await parseScopeAsync(path, scope);
     const live = store.getState();
     const stillOwns = sequences.get(path) === pass;
-    if (!stillOwns || live.values !== valuesAtStart) {
+    if (!stillOwns || scopeStale(scope, path, valuesAtStart, live.values)) {
       if (stillOwns) {
         store.setState((state) => ({
           ...state,
@@ -808,17 +879,24 @@ var createForm = (schema, options) => {
       ...state,
       ...errorChannels(state, { serverErrors: errors })
     })),
-    addErrors: (errors) => store.setState((state) => ({
-      ...state,
-      ...errorChannels(state, {
-        serverErrors: Object.entries(errors).reduce(
-          // Computed keys throughout, so a server field named
-          // "__proto__" lands as an own property like everywhere else.
-          (acc, [key, list]) => list === void 0 || list.length === 0 ? omitKey(acc, key) : { ...acc, [key]: list },
-          state.serverErrors
-        )
-      })
-    })),
+    addErrors: (errors) => store.setState((state) => {
+      const entries = Object.entries(errors);
+      const removed = new Set(
+        entries.filter(([, list]) => list === void 0 || list.length === 0).map(([key]) => key)
+      );
+      const added = Object.fromEntries(
+        entries.filter(([, list]) => list !== void 0 && list.length > 0)
+      );
+      return {
+        ...state,
+        ...errorChannels(state, {
+          serverErrors: {
+            ...omitKeys(state.serverErrors, removed),
+            ...added
+          }
+        })
+      };
+    }),
     clearErrors: (path) => store.setState((state) => {
       const scrub = (map) => path === void 0 ? emptyErrors : omitScope(map, [path]);
       return {
@@ -830,27 +908,26 @@ var createForm = (schema, options) => {
       };
     }),
     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) {
+      const state = store.getState();
+      const patch = updater(state);
+      if (Object.keys(patch).length === 0) return;
+      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 };
+      if (next.values !== state.values) {
         clearArrayOpsUnder(store, "");
       }
+      const serverErrors = patch.serverErrors !== void 0 ? patch.serverErrors : next.values !== state.values ? releaseChangedSlices(state.serverErrors, state.values, next.values) : state.serverErrors;
+      store.setState(() => ({
+        ...next,
+        ...errorChannels(state, {
+          schemaErrors: next.schemaErrors,
+          serverErrors
+        })
+      }));
     },
     adoptValues: (values) => {
       sequences.clear();
@@ -959,7 +1036,7 @@ var createForm = (schema, options) => {
     handleSubmit: (onValid, onInvalid, opts) => async (event) => {
       event?.preventDefault();
       const result = await submit(onValid, onInvalid, opts);
-      if (result.kind === "error" && opts?.onError === void 0 && process.env.NODE_ENV !== "production") {
+      if (result.kind === "error" && opts?.onError === void 0 && isDevBuild()) {
         console.warn(
           "[formstand] submit handler threw and nothing observed it \u2014 the form shows no feedback. Pass { onError } to handleSubmit (or setError inside your handler):",
           result.error
@@ -1010,6 +1087,35 @@ var createForm = (schema, options) => {
   });
 };
 
+// src/core/debounce.ts
+var createDebouncer = (ms) => {
+  const timer = {
+    current: null
+  };
+  const cancel = () => {
+    if (timer.current !== null) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+  };
+  const schedule = (run) => {
+    cancel();
+    if (ms === 0) {
+      run();
+      return;
+    }
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      run();
+    }, ms);
+  };
+  return Object.freeze({
+    schedule,
+    cancel,
+    pending: () => timer.current !== null
+  });
+};
+
 // src/core/persist.ts
 var kindOf = (value) => value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
 var conflictsWith = (draft, reference) => {
@@ -1041,7 +1147,7 @@ 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 applyDraft = (values) => apply === "edit" || apply === "restore" ? form.setValues(values) : form.adoptValues(values);
   const referenceShape = () => {
     try {
       return JSON.parse(JSON.stringify(form.getState().initialValues));
@@ -1063,6 +1169,7 @@ var persistForm = (form, options) => {
       if (versioned && wrapper.__v !== options.version) return false;
       if (versioned && wrapper.values === void 0) return false;
       const values = versioned ? wrapper.values : parsed;
+      if (values === null || values === void 0) return false;
       const reference = referenceShape();
       if (reference !== void 0 && conflictsWith(values, reference)) {
         return false;
@@ -1084,28 +1191,13 @@ var persistForm = (form, options) => {
     } catch {
     }
   };
-  const timerRef = {
-    current: null
-  };
-  const cancelPending = () => {
-    if (timerRef.current !== null) {
-      clearTimeout(timerRef.current);
-      timerRef.current = null;
-    }
-  };
+  const writes = createDebouncer(debounceMs);
+  const cancelPending = () => writes.cancel();
   if (apply !== "manual") {
     load();
   }
   const unsubscribe = form.watchValues((values) => {
-    cancelPending();
-    if (debounceMs === 0) {
-      writeDraft(values);
-    } else {
-      timerRef.current = setTimeout(() => {
-        timerRef.current = null;
-        writeDraft(values);
-      }, debounceMs);
-    }
+    writes.schedule(() => writeDraft(values));
   });
   return Object.freeze({
     load,
@@ -1287,7 +1379,7 @@ var useMaskedInput = (field, options) => {
           field.setValue(parsed.value);
           return;
         case "empty": {
-          const empty = field.emptyValue;
+          const empty = field.clearable || typeof field.initialValue !== "string" ? field.emptyValue : "";
           setEdit({ raw: text, pushed: empty });
           field.setValue(empty);
           return;
@@ -1327,9 +1419,14 @@ var useFormSteps = (form, steps) => {
     },
     [form]
   );
+  const currentStep = useRef(step);
+  useEffect(() => {
+    currentStep.current = step;
+  });
   const next = useCallback(async () => {
     const ok = await validateStep(step);
     if (!ok) return false;
+    if (currentStep.current !== step) return false;
     const target = Math.min(step + 1, latest.current.length - 1);
     setStep(target);
     setVisited((prev) => /* @__PURE__ */ new Set([...prev, target]));
@@ -1351,6 +1448,7 @@ var useFormSteps = (form, steps) => {
         return await validateStep(from) ? walk(from + 1) : from;
       };
       const landed = await walk(step);
+      if (currentStep.current !== step) return currentStep.current;
       setStep(landed);
       setVisited(
         (prev) => /* @__PURE__ */ new Set([
@@ -1396,7 +1494,7 @@ var useFormSteps = (form, steps) => {
   );
 };
 var warnUnobserved = (result, options, site) => {
-  if (result.kind === "error" && options?.onError === void 0 && process.env.NODE_ENV !== "production") {
+  if (result.kind === "error" && options?.onError === void 0 && isDevBuild()) {
     console.warn(
       `[formstand] action handler threw and nothing observed it \u2014 the form shows no feedback. Pass { onError } to ${site} (or setError inside your handler):`,
       result.error
@@ -1465,10 +1563,12 @@ function useField(form, pathArg, options) {
         path: p,
         value,
         initialValue: initialValue2,
-        error: state.errors[p],
-        touched: state.touched[p] ?? false,
+        // Own-key reads: a field named "constructor" or "toString" would
+        // otherwise read Object.prototype's function as its error/flag.
+        error: entryAt(state.errors, p),
+        touched: flagAt(state.touched, p),
         dirty: isFieldDirty(value, initialValue2),
-        isValidating: state.isValidating[p] ?? false
+        isValidating: flagAt(state.isValidating, p)
       };
     })
   );
@@ -1477,7 +1577,7 @@ function useField(form, pathArg, options) {
   const initialValue = slice.initialValue;
   const { emptyValue, clearable } = useMemo(() => {
     if (formSchema !== void 0) {
-      const sub = fieldSchemaAtPath(formSchema, path);
+      const sub = fieldSchemaForIntrospection(formSchema, path);
       if (sub !== null) {
         return {
           emptyValue: emptyValueForSchema(sub),
@@ -1488,28 +1588,26 @@ function useField(form, pathArg, options) {
     return initialValue === null ? { emptyValue: null, clearable: true } : { emptyValue: void 0, clearable: false };
   }, [formSchema, path, initialValue]);
   const debounceMs = options?.debounceMs;
-  const debounceTimerRef = useRef(null);
+  const debouncerRef = useRef(null);
   useEffect(() => {
     return () => {
-      if (debounceTimerRef.current !== null) {
-        clearTimeout(debounceTimerRef.current);
-        debounceTimerRef.current = null;
-      }
+      debouncerRef.current?.cancel();
+      debouncerRef.current = null;
     };
   }, [form, path, debounceMs]);
   const triggerValidate = useCallback(() => {
     if (debounceMs !== void 0 && debounceMs > 0) {
-      if (debounceTimerRef.current !== null) {
-        clearTimeout(debounceTimerRef.current);
-      }
-      const scheduled = getAtPath(form.store.getState().values, path);
-      debounceTimerRef.current = setTimeout(() => {
-        debounceTimerRef.current = null;
+      const debouncer = debouncerRef.current ?? createDebouncer(debounceMs);
+      debouncerRef.current = debouncer;
+      const scheduledValues = form.store.getState().values;
+      const scheduled = getAtPath(scheduledValues, path);
+      debouncer.schedule(() => {
         const state = form.store.getState();
-        if (state.values === state.initialValues) return;
+        const rebased = state.values !== scheduledValues && state.values === state.initialValues;
+        if (rebased) return;
         if (!Object.is(getAtPath(state.values, path), scheduled)) return;
         void form.validateFieldAsync(path);
-      }, debounceMs);
+      });
       return;
     }
     form.validateField(path);
@@ -1525,7 +1623,7 @@ function useField(form, pathArg, options) {
         state.mode,
         state.reValidateMode,
         state.submitCount > 0,
-        state.touched[path] ?? false
+        flagAt(state.touched, path)
       )) {
         triggerValidate();
       }
@@ -1606,7 +1704,11 @@ var reconcileIds = (prev, nextItems) => {
   if (prev.items.length === nextItems.length && prev.items.every((item, i) => Object.is(item, nextItems[i]))) {
     return { ...prev, items: nextItems };
   }
+  const keptAtIndex = nextItems.map(
+    (item, i) => i < prev.items.length && Object.is(item, prev.items[i])
+  );
   const buckets = prev.items.reduce((acc, item, i) => {
+    if (keptAtIndex[i] === true) return acc;
     const bucket = acc.get(item);
     if (bucket === void 0) {
       acc.set(item, [i]);
@@ -1615,7 +1717,8 @@ var reconcileIds = (prev, nextItems) => {
     }
     return acc;
   }, /* @__PURE__ */ new Map());
-  const matchedIds = nextItems.map((item) => {
+  const matchedIds = nextItems.map((item, i) => {
+    if (keptAtIndex[i] === true) return prev.ids[i] ?? null;
     const prevIndex = buckets.get(item)?.shift();
     return prevIndex === void 0 ? null : prev.ids[prevIndex] ?? null;
   });
@@ -1709,7 +1812,9 @@ function useFieldArray(form, pathArg) {
       const value = getAtPath(state.values, path);
       return {
         items: Array.isArray(value) ? value : EMPTY_ITEMS,
-        error: state.errors[path]
+        // Own-key read, like useField: an array named "constructor" must
+        // not read Object as its error list.
+        error: entryAt(state.errors, path)
       };
     })
   );
@@ -1723,7 +1828,7 @@ function useFieldArray(form, pathArg) {
       state.mode,
       state.reValidateMode,
       state.submitCount > 0,
-      state.touched[path] ?? false
+      flagAt(state.touched, path)
     )) {
       form.validateField?.(path);
     }