formstand 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var vanilla = require('zustand/vanilla');
+var middleware = require('zustand/middleware');
 var zod = require('zod');
 var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
@@ -59,7 +60,7 @@ var valuesEqual = (a, b) => {
   if (isPlainObject(a) && isPlainObject(b)) {
     const aKeys = Object.keys(a);
     const bKeys = Object.keys(b);
-    return aKeys.length === bKeys.length && aKeys.every((k) => valuesEqual(a[k], b[k]));
+    return aKeys.length === bKeys.length && aKeys.every((k) => Object.hasOwn(b, k) && valuesEqual(a[k], b[k]));
   }
   return false;
 };
@@ -87,21 +88,33 @@ 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;
   if (Array.isArray(obj)) {
     return typeof segment === "number" ? obj[segment] : void 0;
   }
-  return isPlainRecord(obj) ? obj[String(segment)] : void 0;
+  return isPlainRecord(obj) && Object.hasOwn(obj, String(segment)) ? obj[String(segment)] : void 0;
 };
 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 }
   );
@@ -137,6 +150,12 @@ var writeSegments = (obj, segments, value) => {
     return writeIntoArray(obj, head, rest, value);
   }
   if (isPlainRecord(obj)) {
+    if (!isPlainObject(obj)) {
+      console.warn(
+        `[formstand] cannot write key "${String(head)}" through a non-plain object (Date/Map/Set/class instance); value left unchanged.`
+      );
+      return obj;
+    }
     const key = String(head);
     return { ...obj, [key]: writeSegments(obj[key], rest, value) };
   }
@@ -259,7 +278,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(
@@ -269,9 +288,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__";
@@ -333,7 +354,18 @@ var createForm = (schema, options) => {
     mode: initialMode,
     reValidateMode: initialReValidateMode
   };
-  const store = vanilla.createStore(() => initial);
+  const store = options.devtools === void 0 || options.devtools === false ? vanilla.createStore(() => initial) : vanilla.createStore()(
+    middleware.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)
   });
@@ -362,7 +394,38 @@ var createForm = (schema, options) => {
       return result.kind === "pending" ? result.promise.then((r) => r.kind === "valid") : result.kind === "valid";
     }
     try {
-      const result = validateSync(schema, store.getState().values);
+      const values = store.getState().values;
+      const scopes = paths.map((path) => ({
+        path,
+        scope: fieldScopeFor(path, values)
+      }));
+      if (scopes.every(
+        ({ scope }) => scope.kind === "skip" || scope.kind === "parse" && scope.viaSubschema
+      )) {
+        const merged = scopes.reduce(
+          (acc, { path, scope }) => scope.kind === "skip" ? acc : {
+            ...acc,
+            ...scopeSettledResult(
+              validateSync(scope.schema, scope.value),
+              path,
+              true
+            )
+          },
+          {}
+        );
+        store.setState((state) => ({
+          ...state,
+          ...errorChannels(state, {
+            schemaErrors: reuseErrorRefs(
+              mergeScopedErrors(state.schemaErrors, merged, paths),
+              state.schemaErrors
+            ),
+            serverErrors: omitScope(state.serverErrors, paths)
+          })
+        }));
+        return Object.values(merged).flat().length === 0;
+      }
+      const result = validateSync(schema, values);
       const fullErrors = result.kind === "invalid" ? result.errors : emptyErrors;
       store.setState((state) => ({
         ...state,
@@ -670,7 +733,11 @@ var createForm = (schema, options) => {
           });
         }
         const merged = stale ? result.errors : store.getState().errors;
-        onInvalid?.(merged);
+        try {
+          onInvalid?.(merged);
+        } catch (error) {
+          return { kind: "error", error };
+        }
         return { kind: "invalid", errors: merged };
       }
       if (!stale) {
@@ -930,9 +997,13 @@ var createForm = (schema, options) => {
         // 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.
+        // 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
+        isValidatingForm: false,
+        isSubmitting: inFlight.count > 0
       };
     })
   });
@@ -954,21 +1025,91 @@ 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 = react.useRef(null);
   if (formRef.current === null) {
     formRef.current = createForm(schema, options);
   }
   const form = formRef.current;
+  const mountInitialsRef = react.useRef(options.initialValues);
   const warnedRef = react.useRef(false);
   react.useEffect(() => {
-    if (!warnedRef.current && form.schema !== schema) {
+    const changedInitials = !Object.is(options.initialValues, mountInitialsRef.current) && !valuesEqual(options.initialValues, mountInitialsRef.current);
+    if (!warnedRef.current && (form.schema !== schema || changedInitials)) {
       warnedRef.current = true;
       console.warn(
-        "[formstand] useForm received a different schema reference after the first render; schema and options changes are ignored for the life of the component. If the schema is defined inline this is harmless (but consider hoisting it to module scope). For initial values that arrive later (e.g. from a fetch), call form.adoptValues(values) or form.reset(values) instead."
+        "[formstand] useForm received a different schema or initial values after the first render; schema and options changes are ignored for the life of the component. If the schema is defined inline this is harmless (but consider hoisting it to module scope). For initial values that arrive later (e.g. from a fetch), call form.adoptValues(values) or form.reset(values) instead."
       );
     }
-  }, [form, schema]);
+  }, [form, schema, options.initialValues]);
   return form;
 };
 var createFormContext = () => {
@@ -1114,6 +1255,14 @@ function useField(form, pathArg, options) {
     [slice, emptyValue, setValue, setTouched, setError, clearError, validate, validateAsync2, onBlur]
   );
 }
+
+// src/react/useVariantField.ts
+function useVariantField(form, unionPath, field) {
+  return useField(
+    form,
+    `${unionPath}.${field}`
+  );
+}
 var EMPTY_ID_STATE = { items: [], ids: [], counter: 0 };
 var EMPTY_ITEMS = [];
 var reconcileIds = (prev, nextItems) => {
@@ -1134,23 +1283,22 @@ var reconcileIds = (prev, nextItems) => {
     const prevIndex = buckets.get(item)?.shift();
     return prevIndex === void 0 ? null : prev.ids[prevIndex] ?? null;
   });
-  const leftover = [...buckets.values()].flat().sort((a, b) => a - b).map((i) => prev.ids[i]).filter((id) => id !== void 0);
-  const ordinals = matchedIds.reduce((acc, id) => {
-    const count = acc.length === 0 ? 0 : acc[acc.length - 1] ?? 0;
-    acc.push(id === null ? count + 1 : count);
-    return acc;
+  const leftoverAt = new Map(
+    [...buckets.values()].flat().flatMap((i) => {
+      const id = prev.ids[i];
+      return id === void 0 ? [] : [[i, id]];
+    })
+  );
+  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 unmatched = ordinals.length === 0 ? 0 : ordinals[ordinals.length - 1] ?? 0;
-  const ids = matchedIds.map((id, i) => {
-    if (id !== null) return id;
-    const ordinal = ordinals[i] ?? 0;
-    return leftover[ordinal - 1] ?? `__zfa_${prev.counter + (ordinal - leftover.length)}`;
-  });
-  return {
-    items: nextItems,
-    ids,
-    counter: prev.counter + Math.max(0, unmatched - leftover.length)
-  };
+  const minted = mintCounts[mintCounts.length - 1] ?? 0;
+  const ids = reused.map(
+    (id, i) => id ?? `__zfa_${prev.counter + (mintCounts[i] ?? 0)}`
+  );
+  return { items: nextItems, ids, counter: prev.counter + minted };
 };
 function useFieldArray(form, pathArg) {
   const path = react$1.useStore(
@@ -1256,6 +1404,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);
@@ -1267,6 +1420,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,
@@ -1311,6 +1465,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,
@@ -1365,6 +1561,33 @@ var TextField = ({
     /* @__PURE__ */ jsxRuntime.jsx(ErrorText, { id: errorId, error: field.error })
   ] });
 };
+var DateField = ({
+  form,
+  path,
+  label,
+  min,
+  max,
+  ref
+}) => {
+  const id = react.useId();
+  const errorId = `${id}-error`;
+  const field = useField(form, path);
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "zf-field", children: [
+    label !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "input",
+      {
+        id,
+        ref,
+        ...dateInputProps(field),
+        min,
+        max,
+        "aria-describedby": hasError(field.error) ? errorId : void 0
+      }
+    ),
+    /* @__PURE__ */ jsxRuntime.jsx(ErrorText, { id: errorId, error: field.error })
+  ] });
+};
 var IDLE_EDIT = { raw: null, pushed: void 0 };
 var useNumberInput = (field) => {
   const [edit, setEdit] = react.useState(IDLE_EDIT);
@@ -1467,7 +1690,8 @@ var SelectField = ({
   const id = react.useId();
   const errorId = `${id}-error`;
   const field = useField(form, path);
-  const showEmptyOption = field.value === void 0 || field.value === null || placeholder !== void 0;
+  const clearable = field.emptyValue === null;
+  const showEmptyOption = clearable || field.value === void 0 || field.value === null || placeholder !== void 0;
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "zf-field", children: [
     label !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
     /* @__PURE__ */ jsxRuntime.jsxs(
@@ -1478,7 +1702,7 @@ var SelectField = ({
         ...selectProps(field),
         "aria-describedby": hasError(field.error) ? errorId : void 0,
         children: [
-          showEmptyOption ? /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", disabled: true, children: placeholder ?? "" }) : null,
+          showEmptyOption ? /* @__PURE__ */ jsxRuntime.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
@@ -1493,13 +1717,12 @@ var SelectField = ({
 };
 
 // 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;
@@ -1519,20 +1742,21 @@ 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)
+  );
 };
 
 exports.CheckboxField = CheckboxField;
+exports.DateField = DateField;
 exports.NumberField = NumberField;
 exports.SelectField = SelectField;
 exports.TextField = TextField;
@@ -1540,6 +1764,8 @@ exports.checkboxProps = checkboxProps;
 exports.createForm = createForm;
 exports.createFormContext = createFormContext;
 exports.createFormHooks = createFormHooks;
+exports.dateInputProps = dateInputProps;
+exports.dateToInputText = dateToInputText;
 exports.emptyValueForSchema = emptyValueForSchema;
 exports.flattenIssues = flattenIssues;
 exports.focusField = focusField;
@@ -1548,8 +1774,10 @@ exports.getAtPath = getAtPath;
 exports.isAsyncRequiredError = isAsyncRequiredError;
 exports.numberInputProps = numberInputProps;
 exports.numberToInputText = numberToInputText;
+exports.parseDateText = parseDateText;
 exports.parseNumberText = parseNumberText;
 exports.parsePath = parsePath;
+exports.persistForm = persistForm;
 exports.selectProps = selectProps;
 exports.setAtPath = setAtPath;
 exports.shouldValidateOn = shouldValidateOn;
@@ -1564,6 +1792,7 @@ exports.useIsDirty = useIsDirty;
 exports.useIsSubmitting = useIsSubmitting;
 exports.useIsValid = useIsValid;
 exports.useSubmitCount = useSubmitCount;
+exports.useVariantField = useVariantField;
 exports.validateAsync = validateAsync;
 exports.validateSync = validateSync;
 //# sourceMappingURL=index.cjs.map