formstand 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 0.20.0 — 2026-09-18
+
+### Added
+
+- **`useMaskedInput(field, { parse, format })`.** The raw-text editing
+  pattern behind `useNumberInput`, generalized to any parsed/formatted
+  value (phone, currency, locale formats): partial entries stay visible
+  as local text without touching the form, keystrokes that parse push
+  the REAL value immediately (the schema validates data, never display
+  text), `"empty"` writes the field's schema-aware `emptyValue`, blur
+  snaps the display to `format(value)`, and an external write wins over
+  local text. Recipes gains a phone-mask walkthrough.
+- **`formstand/testing`: drive a form in tests the way the hooks do.**
+  `fillField` writes and validates under the CHANGE gate (no-op guard
+  included), `blurField` marks touched and validates under the BLUR
+  gate, `fillAndBlurField` is the edit-then-leave a user performs,
+  `fillFields` applies a fixture object through the full recipe, and
+  `submitForm` hands back the `SubmitResult` to switch on. Tests using
+  the imperative `form.setValue` were skipping the validation gates by
+  design; these helpers restate `useField`'s own recipes over the core
+  API, so a store-level test sees exactly what a rendered input would —
+  without mounting one. Framework-agnostic; new Testing forms guide.
+- **Variant sub-paths: `useVariantField`'s field argument is a PATH.**
+  `useVariantField(form, "payment", "billing.zip")` reaches inside a
+  variant-only object and `"span.0"` binds a variant-only tuple
+  position — the last shape the typed paths could not carry. The field
+  offer is `VariantFieldPath` (exported): every member's `FieldPath`,
+  minus paths rooted at a common key (those bind with plain `useField`,
+  the discriminant included), riding the same leaf classification,
+  tuple positionality, and depth budget as everywhere else. The value
+  distributes over the members that resolve the path, widened with
+  `| undefined` as before; `VariantFieldValue` now derives through
+  `FieldValue`, and the runtime is unchanged (the joined path always
+  worked — only its type was unreachable).
+
+- **`useFormSteps(form, steps)`: the multi-step story.** One form, one
+  schema, and per-step validation scopes: `next()` validates the current
+  step's fields (async refines included; the full schema parses, so
+  cross-field rules inside a step fire, with errors scoped to the step)
+  and advances only on clean, marking errored fields touched exactly
+  like a failed submit; `back()` never validates; a forward `goTo()`
+  validates every step on the way and lands on the first one that
+  fails, so clickable step headers cannot skip past an invalid step.
+  `steps` is index-aligned live status (`name`, `visited`, `hasErrors`)
+  for progress UIs. The step index is React state on purpose — it is
+  navigation, not form data. `createFormHooks` binds it as
+  `use{Name}Steps`, and the docs gain a Multi-step forms guide.
+
+## 0.19.0 — 2026-09-17
+
+### Added
+
+- **The React 19 form-actions bridge.** `useFormAction(form, onValid,
+  options?)` returns an action for `<form action={...}>` that validates
+  first and hands the handler parsed `z.output` data (plus the raw
+  `FormData` last, for file pickers and uncontrolled co-inputs) under
+  the full submit lifecycle — isSubmitting/submitCount, errors written
+  and marked touched on failure, `onInvalid`/`onError` mirroring
+  `handleSubmit`, the same dev warning when a failure resolves
+  unobserved, and a reference-stable identity. `useFormActionState(form,
+  action, initialState, options?)` is `useActionState` with
+  schema-validated data: the handler's `(prevState, data, formData)`
+  shape lets a `"use server"` function slot straight in, and invalid,
+  skipped, or throwing submissions keep the previous state, because
+  field errors already live in the form store. Client-side integration
+  by design: no-JS progressive enhancement bypasses any client wrapper,
+  so that path validates server-side with the same zod schema.
+
 ## 0.18.0 — 2026-09-17
 
 ### Changed
@@ -30,6 +98,21 @@
   back to the null-initial heuristic. **`isClearableSchema(schema)`** is
   the exported rule behind it, next to `emptyValueForSchema`.
 
+## formstand-cli Unreleased
+
+### Added
+
+- **Containers inside union variants generate.** The generator's last
+  TODO class: an object or tuple nested in a variant flattens to its
+  scalar leaves, each bound as a dotted variant sub-path
+  (`useVariantField(form, path, "billing.zip")`, formstand 0.20+) — in
+  both layouts, every emission site (static unions, union rows, union
+  row-object fields, unions under nested arrays), with joined labels
+  ("Billing Zip") and the kit number-props hoists riding along. Depth
+  is judged on the full bound path (a too-deep leaf keeps the depth
+  TODO), and an array or union inside a variant still degrades — their
+  bindings need hooks and row machinery of their own.
+
 ## formstand-cli 0.18.0 — 2026-09-17
 
 ### Changed

package/dist/chunk-MQ6262S3.js

@@ -0,0 +1,20 @@
+// 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;
+  }
+};
+
+export { shouldValidateOn };
+//# sourceMappingURL=chunk-MQ6262S3.js.map
+//# sourceMappingURL=chunk-MQ6262S3.js.map

package/dist/chunk-MQ6262S3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/mode.ts"],"names":[],"mappings":";AAWO,IAAM,mBAAmB,CAC9B,OAAA,EACA,MACA,cAAA,EACA,eAAA,EACA,UAAmB,KAAA,KACP;AACZ,EAAA,MAAM,SAAA,GAAY,kBAAkB,cAAA,GAAiB,IAAA;AACrD,EAAA,QAAQ,SAAA;AAAW,IACjB,KAAK,UAAA;AACH,MAAA,OAAO,OAAA,KAAY,QAAA;AAAA,IACrB,KAAK,QAAA;AACH,MAAA,OAAO,OAAA,KAAY,MAAA;AAAA,IACrB,KAAK,UAAA;AACH,MAAA,OAAO,KAAA;AAAA,IACT,KAAK,WAAA;AACH,MAAA,OAAO,YAAY,MAAA,IAAU,OAAA;AAAA,IAC/B,KAAK,KAAA;AACH,MAAA,OAAO,IAAA;AAAA;AAEb","file":"chunk-MQ6262S3.js","sourcesContent":["export type ValidationMode =\n  | \"onChange\"\n  | \"onBlur\"\n  | \"onSubmit\"\n  // Validate on blur always; on change only once the field has been touched.\n  | \"onTouched\"\n  // Validate on both change and blur.\n  | \"all\";\n\nexport type ValidationTrigger = \"change\" | \"blur\";\n\nexport const shouldValidateOn = (\n  trigger: ValidationTrigger,\n  mode: ValidationMode,\n  reValidateMode: ValidationMode,\n  submitAttempted: boolean,\n  touched: boolean = false,\n): boolean => {\n  const effective = submitAttempted ? reValidateMode : mode;\n  switch (effective) {\n    case \"onChange\":\n      return trigger === \"change\";\n    case \"onBlur\":\n      return trigger === \"blur\";\n    case \"onSubmit\":\n      return false;\n    case \"onTouched\":\n      return trigger === \"blur\" || touched;\n    case \"all\":\n      return true;\n  }\n};\n"]}

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
 
@@ -1317,6 +1317,286 @@ 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(
+      `[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
+    );
+  }
+};
+var useFormAction = (form, onValid, options) => {
+  const latest = react.useRef({ onValid, options });
+  react.useEffect(() => {
+    latest.current = { onValid, options };
+  });
+  return react.useCallback(
+    async (formData) => {
+      const { onValid: handler, options: opts } = latest.current;
+      const result = await form.submit(
+        (data) => handler(data, formData),
+        opts?.onInvalid,
+        opts?.onError === void 0 ? void 0 : { onError: opts.onError }
+      );
+      warnUnobserved(result, opts, "useFormAction");
+    },
+    [form]
+  );
+};
+var useFormActionState = (form, action, initialState, options) => {
+  const [state, formAction, isPending] = react.useActionState(
+    async (prevState, formData) => {
+      const prev = prevState;
+      const nextRef = { current: prev };
+      const result = await form.submit(
+        async (data) => {
+          nextRef.current = await action(prev, data, formData);
+        },
+        options?.onInvalid,
+        options?.onError === void 0 ? void 0 : { onError: options.onError }
+      );
+      warnUnobserved(result, options, "useFormActionState");
+      return nextRef.current;
+    },
+    initialState
+  );
+  return [state, formAction, isPending];
+};
 var createFormContext = () => {
   const Context = react.createContext(null);
   const Provider = ({ form, children }) => /* @__PURE__ */ jsxRuntime.jsx(Context.Provider, { value: form, children });
@@ -1740,12 +2020,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);
@@ -1771,6 +2045,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,
@@ -1785,103 +2060,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`;
@@ -2207,14 +2389,18 @@ exports.useField = useField;
 exports.useFieldArray = useFieldArray;
 exports.useFields = useFields;
 exports.useForm = useForm;
+exports.useFormAction = useFormAction;
+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;