formstand 0.19.0 → 0.21.0

package/dist/index.cjs

@@ -4,9 +4,9 @@ var vanilla = require('zustand/vanilla');
 var middleware = require('zustand/middleware');
 var zod = require('zod');
 var react = require('react');
-var jsxRuntime = require('react/jsx-runtime');
 var react$1 = require('zustand/react');
 var shallow = require('zustand/react/shallow');
+var jsxRuntime = require('react/jsx-runtime');
 
 // src/core/createForm.ts
 
@@ -153,11 +153,18 @@ var PARSE_CACHE_MAX = 4096;
 var parseCache = /* @__PURE__ */ new Map();
 var parsePath = (path) => {
   const cached = parseCache.get(path);
-  if (cached !== void 0) return cached;
+  if (cached !== void 0) {
+    parseCache.delete(path);
+    parseCache.set(path, cached);
+    return cached;
+  }
   const segments = Object.freeze(
     path === "" ? [] : path.split(".").map((s) => isIndexSegment(s) ? Number(s) : s)
   );
-  if (parseCache.size >= PARSE_CACHE_MAX) parseCache.clear();
+  if (parseCache.size >= PARSE_CACHE_MAX) {
+    const oldest = parseCache.keys().next().value;
+    if (oldest !== void 0) parseCache.delete(oldest);
+  }
   parseCache.set(path, segments);
   return segments;
 };
@@ -962,27 +969,25 @@ 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, "");
       }
+      store.setState(() => ({
+        ...next,
+        ...errorChannels(state, {
+          schemaErrors: next.schemaErrors,
+          serverErrors: next.serverErrors
+        })
+      }));
     },
     adoptValues: (values) => {
       sequences.clear();
@@ -1159,6 +1164,35 @@ var shouldValidateOn = (trigger, mode, reValidateMode, submitAttempted, touched
   }
 };
 
+// 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) => {
@@ -1233,28 +1267,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,
@@ -1317,6 +1336,241 @@ var useForm = (schema, options) => {
   }, [form, schema, options.initialValues]);
   return form;
 };
+
+// src/react/inputProps.ts
+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" };
+  const parsed = Number(text);
+  return Number.isFinite(parsed) ? { kind: "number", value: parsed } : { kind: "invalid" };
+};
+var textInputProps = (field) => ({
+  name: field.path,
+  value: field.value ?? "",
+  "aria-invalid": ariaInvalid(field),
+  onChange: (e) => {
+    const text = e.target.value;
+    field.setValue(text === "" && field.clearable ? field.emptyValue : text);
+  },
+  onBlur: field.onBlur
+});
+var numberInputProps = (field) => ({
+  type: "number",
+  name: field.path,
+  value: numberToInputText(field.value),
+  "aria-invalid": ariaInvalid(field),
+  onChange: (e) => {
+    const parsed = parseNumberText(e.target.value);
+    if (parsed.kind === "invalid") return;
+    field.setValue(
+      parsed.kind === "number" ? parsed.value : field.emptyValue
+    );
+  },
+  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,
+  checked: field.value ?? false,
+  "aria-invalid": ariaInvalid(field),
+  onChange: (e) => field.setValue(e.target.checked),
+  onBlur: field.onBlur
+});
+var selectProps = (field) => ({
+  name: field.path,
+  value: field.value ?? "",
+  "aria-invalid": ariaInvalid(field),
+  onChange: (e) => {
+    const v = e.target.value;
+    field.setValue(v === "" && field.clearable ? field.emptyValue : v);
+  },
+  onBlur: field.onBlur
+});
+
+// src/react/useMaskedInput.ts
+var useMaskedInput = (field, options) => {
+  const [edit, setEdit] = react.useState({
+    raw: null,
+    pushed: void 0
+  });
+  const externallyChanged = edit.raw !== null && !Object.is(field.value, edit.pushed);
+  if (externallyChanged) {
+    setEdit({ raw: null, pushed: void 0 });
+  }
+  const raw = externallyChanged ? null : edit.raw;
+  return {
+    name: field.path,
+    value: raw ?? (field.value === void 0 || field.value === null ? "" : options.format(field.value)),
+    "aria-invalid": hasFieldError(field.error) ? true : void 0,
+    onChange: (e) => {
+      const text = e.target.value;
+      const parsed = options.parse(text);
+      switch (parsed.kind) {
+        case "value":
+          setEdit({ raw: text, pushed: parsed.value });
+          field.setValue(parsed.value);
+          return;
+        case "empty": {
+          const empty = field.emptyValue;
+          setEdit({ raw: text, pushed: empty });
+          field.setValue(empty);
+          return;
+        }
+        case "invalid":
+          setEdit({ raw: text, pushed: field.value });
+          return;
+      }
+    },
+    onBlur: () => {
+      setEdit({ raw: null, pushed: void 0 });
+      field.onBlur();
+    }
+  };
+};
+function useFormSelector(form, selector) {
+  return react$1.useStore(form.store, selector);
+}
+function useFormSelectorShallow(form, selector) {
+  return react$1.useStore(form.store, shallow.useShallow(selector));
+}
+
+// src/react/useFormSteps.ts
+var useFormSteps = (form, steps) => {
+  const [step, setStep] = react.useState(0);
+  const [visited, setVisited] = react.useState(
+    () => /* @__PURE__ */ new Set([0])
+  );
+  const latest = react.useRef(steps);
+  react.useEffect(() => {
+    latest.current = steps;
+  });
+  const validateStep = react.useCallback(
+    async (index) => {
+      const definition = latest.current[index];
+      if (definition === void 0) return true;
+      const result = await form.validateFieldsAsync(definition.fields);
+      if (result.kind === "invalid") {
+        Object.keys(result.errors).forEach((key) => {
+          form.setTouched(key, true);
+        });
+        return false;
+      }
+      return true;
+    },
+    [form]
+  );
+  const next = react.useCallback(async () => {
+    const ok = await validateStep(step);
+    if (!ok) return false;
+    const target = Math.min(step + 1, latest.current.length - 1);
+    setStep(target);
+    setVisited((prev) => /* @__PURE__ */ new Set([...prev, target]));
+    return true;
+  }, [validateStep, step]);
+  const back = react.useCallback(() => {
+    setStep((prev) => Math.max(prev - 1, 0));
+  }, []);
+  const goTo = react.useCallback(
+    async (target) => {
+      const count = latest.current.length;
+      const clamped = Math.max(0, Math.min(target, count - 1));
+      if (clamped <= step) {
+        setStep(clamped);
+        return clamped;
+      }
+      const walk = async (from) => {
+        if (from >= clamped) return clamped;
+        return await validateStep(from) ? walk(from + 1) : from;
+      };
+      const landed = await walk(step);
+      setStep(landed);
+      setVisited(
+        (prev) => /* @__PURE__ */ new Set([
+          ...prev,
+          ...Array.from({ length: landed - step + 1 }, (_, i) => step + i)
+        ])
+      );
+      return landed;
+    },
+    [validateStep, step]
+  );
+  const errorFlags = useFormSelectorShallow(
+    form,
+    (state) => steps.map(
+      (definition) => definition.fields.some(
+        (path) => Object.keys(state.errors).some((key) => isPathOrChild(key, path))
+      )
+    )
+  );
+  const statuses = react.useMemo(
+    () => steps.map(
+      (definition, index) => ({
+        name: definition.name,
+        visited: visited.has(index),
+        hasErrors: errorFlags[index] ?? false
+      })
+    ),
+    [steps, visited, errorFlags]
+  );
+  return react.useMemo(
+    () => ({
+      step,
+      name: steps[step]?.name,
+      count: steps.length,
+      isFirst: step === 0,
+      isLast: step === steps.length - 1,
+      next,
+      back,
+      goTo,
+      steps: statuses
+    }),
+    [step, steps, next, back, goTo, statuses]
+  );
+};
 var warnUnobserved = (result, options, site) => {
   if (result.kind === "error" && options?.onError === void 0 && process.env.NODE_ENV !== "production") {
     console.warn(
@@ -1410,28 +1664,24 @@ 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 = react.useRef(null);
+  const debouncerRef = react.useRef(null);
   react.useEffect(() => {
     return () => {
-      if (debounceTimerRef.current !== null) {
-        clearTimeout(debounceTimerRef.current);
-        debounceTimerRef.current = null;
-      }
+      debouncerRef.current?.cancel();
+      debouncerRef.current = null;
     };
   }, [form, path, debounceMs]);
   const triggerValidate = react.useCallback(() => {
     if (debounceMs !== void 0 && debounceMs > 0) {
-      if (debounceTimerRef.current !== null) {
-        clearTimeout(debounceTimerRef.current);
-      }
+      const debouncer = debouncerRef.current ?? createDebouncer(debounceMs);
+      debouncerRef.current = debouncer;
       const scheduled = getAtPath(form.store.getState().values, path);
-      debounceTimerRef.current = setTimeout(() => {
-        debounceTimerRef.current = null;
+      debouncer.schedule(() => {
         const state = form.store.getState();
         if (state.values === state.initialValues) return;
         if (!Object.is(getAtPath(state.values, path), scheduled)) return;
         void form.validateFieldAsync(path);
-      }, debounceMs);
+      });
       return;
     }
     form.validateField(path);
@@ -1785,12 +2035,6 @@ function useIsValidating(form, path) {
 }
 var useIsSubmitting = (form) => react$1.useStore(form.store, (state) => state.isSubmitting);
 var useSubmitCount = (form) => react$1.useStore(form.store, (state) => state.submitCount);
-function useFormSelector(form, selector) {
-  return react$1.useStore(form.store, selector);
-}
-function useFormSelectorShallow(form, selector) {
-  return react$1.useStore(form.store, shallow.useShallow(selector));
-}
 
 // src/react/createFormHooks.ts
 var capitalize = (name) => name.length === 0 ? name : name.charAt(0).toUpperCase() + name.slice(1);
@@ -1816,6 +2060,7 @@ var createFormHooks = (form, name) => {
     paths
   );
   const useBoundSubmitCount = () => useSubmitCount(structural);
+  const useBoundSteps = (steps) => useFormSteps(form, steps);
   const prefix = capitalize(name ?? "");
   return {
     [`use${prefix}Field`]: useBoundField,
@@ -1830,103 +2075,10 @@ var createFormHooks = (form, name) => {
     [`use${prefix}IsSubmitting`]: useBoundIsSubmitting,
     [`use${prefix}SubmitCount`]: useBoundSubmitCount,
     [`use${prefix}Values`]: useBoundValues,
-    [`use${prefix}Fields`]: useBoundFields
+    [`use${prefix}Fields`]: useBoundFields,
+    [`use${prefix}Steps`]: useBoundSteps
   };
 };
-
-// src/react/inputProps.ts
-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" };
-  const parsed = Number(text);
-  return Number.isFinite(parsed) ? { kind: "number", value: parsed } : { kind: "invalid" };
-};
-var textInputProps = (field) => ({
-  name: field.path,
-  value: field.value ?? "",
-  "aria-invalid": ariaInvalid(field),
-  onChange: (e) => {
-    const text = e.target.value;
-    field.setValue(text === "" && field.clearable ? field.emptyValue : text);
-  },
-  onBlur: field.onBlur
-});
-var numberInputProps = (field) => ({
-  type: "number",
-  name: field.path,
-  value: numberToInputText(field.value),
-  "aria-invalid": ariaInvalid(field),
-  onChange: (e) => {
-    const parsed = parseNumberText(e.target.value);
-    if (parsed.kind === "invalid") return;
-    field.setValue(
-      parsed.kind === "number" ? parsed.value : field.emptyValue
-    );
-  },
-  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,
-  checked: field.value ?? false,
-  "aria-invalid": ariaInvalid(field),
-  onChange: (e) => field.setValue(e.target.checked),
-  onBlur: field.onBlur
-});
-var selectProps = (field) => ({
-  name: field.path,
-  value: field.value ?? "",
-  "aria-invalid": ariaInvalid(field),
-  onChange: (e) => {
-    const v = e.target.value;
-    field.setValue(v === "" && field.clearable ? field.emptyValue : v);
-  },
-  onBlur: field.onBlur
-});
 var useFieldA11y = (error) => {
   const id = react.useId();
   const errorId = `${id}-error`;
@@ -2257,11 +2409,13 @@ exports.useFormActionState = useFormActionState;
 exports.useFormError = useFormError;
 exports.useFormSelector = useFormSelector;
 exports.useFormSelectorShallow = useFormSelectorShallow;
+exports.useFormSteps = useFormSteps;
 exports.useFormValues = useFormValues;
 exports.useIsDirty = useIsDirty;
 exports.useIsSubmitting = useIsSubmitting;
 exports.useIsValid = useIsValid;
 exports.useIsValidating = useIsValidating;
+exports.useMaskedInput = useMaskedInput;
 exports.useNumberInput = useNumberInput;
 exports.usePersistForm = usePersistForm;
 exports.useSubmitCount = useSubmitCount;