formstand 0.19.0 → 0.21.0

package/dist/index.js

@@ -1,9 +1,11 @@
-import { getAtPath, slotAtPath, setAtPath, isPlainObject, hasOwnSlot, valuesEqual, isFieldDirty, useFormSelector, useFormSelectorShallow, parsePath } from './chunk-N7WPXYCU.js';
-export { getAtPath, parsePath, setAtPath, useFormSelector, useFormSelectorShallow } from './chunk-N7WPXYCU.js';
+import { getAtPath, slotAtPath, setAtPath, isPlainObject, hasOwnSlot, valuesEqual, useFormSelectorShallow, isFieldDirty, useFormSelector, parsePath } from './chunk-OB23TUKY.js';
+export { getAtPath, parsePath, setAtPath, useFormSelector, useFormSelectorShallow } from './chunk-OB23TUKY.js';
+import { shouldValidateOn } from './chunk-MQ6262S3.js';
+export { shouldValidateOn } from './chunk-MQ6262S3.js';
 import { createStore } from 'zustand/vanilla';
 import { devtools } from 'zustand/middleware';
 import { z } from 'zod';
-import { useRef, useEffect, useMemo, useCallback, useActionState, createContext, useState, useContext, useId } from 'react';
+import { useRef, useEffect, useMemo, useState, useCallback, useActionState, createContext, useContext, useId } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { useStore } from 'zustand/react';
 import { useShallow } from 'zustand/react/shallow';
@@ -828,27 +830,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();
@@ -1008,21 +1008,33 @@ var createForm = (schema, options) => {
   });
 };
 
-// src/core/mode.ts
-var shouldValidateOn = (trigger, mode, reValidateMode, submitAttempted, touched = false) => {
-  const effective = submitAttempted ? reValidateMode : mode;
-  switch (effective) {
-    case "onChange":
-      return trigger === "change";
-    case "onBlur":
-      return trigger === "blur";
-    case "onSubmit":
-      return false;
-    case "onTouched":
-      return trigger === "blur" || touched;
-    case "all":
-      return true;
-  }
+// 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
@@ -1099,28 +1111,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,
@@ -1183,6 +1180,233 @@ 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] = 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();
+    }
+  };
+};
+var useFormSteps = (form, steps) => {
+  const [step, setStep] = useState(0);
+  const [visited, setVisited] = useState(
+    () => /* @__PURE__ */ new Set([0])
+  );
+  const latest = useRef(steps);
+  useEffect(() => {
+    latest.current = steps;
+  });
+  const validateStep = 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 = 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 = useCallback(() => {
+    setStep((prev) => Math.max(prev - 1, 0));
+  }, []);
+  const goTo = 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 = useMemo(
+    () => steps.map(
+      (definition, index) => ({
+        name: definition.name,
+        visited: visited.has(index),
+        hasErrors: errorFlags[index] ?? false
+      })
+    ),
+    [steps, visited, errorFlags]
+  );
+  return 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(
@@ -1276,28 +1500,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 = 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 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);
@@ -1676,6 +1896,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,
@@ -1690,103 +1911,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 = useId();
   const errorId = `${id}-error`;
@@ -2079,6 +2207,6 @@ var focusField = (path, root) => {
   return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(namedControls(scope).filter(isFocusCandidate)) : focusFirstOf(pathCandidates(scope, [path]).filter(isFocusCandidate));
 };
 
-export { CheckboxField, DateField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, createFormHooks, dateInputProps, dateToInputText, emptyValueForSchema, flattenIssues, focusField, focusFirstError, hasFieldError, isAsyncRequiredError, isClearableSchema, numberInputProps, numberToInputText, parseDateText, parseNumberText, persistForm, selectProps, shouldValidateOn, textInputProps, useField, useFieldArray, useFields, useForm, useFormAction, useFormActionState, useFormError, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useNumberInput, usePersistForm, useSubmitCount, useVariantField, validateAsync, validateSync };
+export { CheckboxField, DateField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, createFormHooks, dateInputProps, dateToInputText, emptyValueForSchema, flattenIssues, focusField, focusFirstError, hasFieldError, isAsyncRequiredError, isClearableSchema, numberInputProps, numberToInputText, parseDateText, parseNumberText, persistForm, selectProps, textInputProps, useField, useFieldArray, useFields, useForm, useFormAction, useFormActionState, useFormError, useFormSteps, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useMaskedInput, useNumberInput, usePersistForm, useSubmitCount, useVariantField, validateAsync, validateSync };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map