formstand 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+## 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
+
+- **`PersistHandle.restore()` is now `load()`** (breaking). The method's
+  DEFAULT application is `adoptValues` — a rebase that reads clean — and
+  the old name promised the setValues semantics it only has under
+  `apply: "restore"`. The name now describes what it does; the `apply`
+  mode names are unchanged. `usePersistForm`'s handle follows.
+- **Cleared inputs write `emptyValue` whenever the schema accepts it.**
+  `textInputProps`/`selectProps` (and the bound `TextField`/`SelectField`)
+  used to write the empty value only for nullable fields, so clearing
+  `z.string().optional()` left `""` behind — a documented asymmetry that
+  kept the field dirty against an `undefined` initial and made an optional
+  enum select unclearable. Clearing now writes `undefined` for optional
+  and defaulted fields and `null` for nullable ones; a REQUIRED string
+  cleared to `""` still stays `""`, so the schema judges a visible value
+  instead of a hole it rejects. `SelectField`'s empty option is
+  accordingly selectable for every clearable field, not just nullable
+  ones.
+
+### Added
+
+- **`field.clearable`** on `UseFieldReturn`: whether the schema accepts
+  the field's `emptyValue` (optional, nullable, or defaulted),
+  introspected from the zod schema with the same shallow walk as
+  `emptyValue` so the pair can never disagree. Schema-less forms fall
+  back to the null-initial heuristic. **`isClearableSchema(schema)`** is
+  the exported rule behind it, next to `emptyValueForSchema`.
+
+## formstand-cli 0.18.0 — 2026-09-17
+
+### Changed
+
+- **Generated kit adapters clear through `field.clearable`.** The
+  emitted text and select bindings wrote the empty value only for
+  nullable fields, mirroring the library's old rule; they now write
+  `field.emptyValue` whenever `field.clearable` says the schema accepts
+  it, so generated optional fields clear to `undefined` instead of
+  holding `""`. Kit output therefore needs formstand 0.18; regenerate
+  to pick the rule up, or keep the old adapter — both compile.
+
+## formstand-cli 0.17.0 — 2026-09-17
+
+### Added
+
+- **Containers inside array rows generate.** The remaining row-shape
+  TODO matrix is gone (formstand 0.17 types the paths): a tuple as the
+  row item or as a row-object field binds its positions inline at static
+  sub-indices (`points.${index}.0`, `segments.${index}.span.1`); a
+  discriminated union as a row-object FIELD binds on the holed template
+  (`invoices.${p0}.pay`), optional/nullable ones keeping the clearable
+  select; an array-of-arrays item extracts an inner Rows component; and
+  the same shapes under nested arrays work at any depth, union items
+  included (`teams.${p0}.methods.${index}`). Single-file extracts a
+  child component per site that needs hooks (rows render inside
+  rows.map); the module layout binds in the Row component, which already
+  is one. The one shape that still degrades to a TODO is a container
+  inside a union variant — binding it needs variant sub-paths the
+  library does not type.
+
 ## 0.17.0 — 2026-09-17
 
 ### Added

package/dist/{createForm-D0xLZH-Q.d.cts → createForm-B73p1TgL.d.cts}

@@ -108,6 +108,7 @@ declare const validateSync: <TSchema extends z.ZodType>(schema: TSchema, values:
 declare const validateAsync: <TSchema extends z.ZodType>(schema: TSchema, values: z.input<TSchema>) => Promise<SettledValidationResult<z.output<TSchema>>>;
 declare const isAsyncRequiredError: (e: unknown) => boolean;
 declare const emptyValueForSchema: (schema: z.ZodType) => null | undefined;
+declare const isClearableSchema: (schema: z.ZodType) => boolean;
 
 type ReadonlyStoreApi<T> = Pick<StoreApi<T>, "getState" | "getInitialState" | "subscribe">;
 type CreateFormOptions<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = Readonly<{
@@ -197,4 +198,4 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
 }>;
 declare const createForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(schema: TSchema, options: CreateFormOptions<TSchema, D>) => Form<TSchema, D>;
 
-export { type BoolMap as B, type CreateFormOptions as C, type DefaultPathDepth as D, type ErrorMap as E, type Form as F, type InvalidSubmitHandler as I, type PathDepth as P, type ReadonlyStoreApi as R, type SettledFieldValidationResult as S, type ValidationMode as V, type FieldValidationResult as a, type FormState as b, type FieldPath as c, type FieldValue as d, type FieldSnapshot as e, type FieldsValidationResult as f, type ResetOptions as g, type SettledFieldsValidationResult as h, type SettledValidationResult as i, type SubmitHandler as j, type SubmitOptions as k, type SubmitResult as l, type ValidationResult as m, type ValidationTrigger as n, createForm as o, emptyValueForSchema as p, flattenIssues as q, isAsyncRequiredError as r, shouldValidateOn as s, validateSync as t, validateAsync as v };
+export { type BoolMap as B, type CreateFormOptions as C, type DefaultPathDepth as D, type ErrorMap as E, type Form as F, type InvalidSubmitHandler as I, type PathDepth as P, type ReadonlyStoreApi as R, type SettledFieldValidationResult as S, type ValidationMode as V, type FieldValidationResult as a, type FormState as b, type FieldPath as c, type FieldValue as d, type FieldSnapshot as e, type FieldsValidationResult as f, type ResetOptions as g, type SettledFieldsValidationResult as h, type SettledValidationResult as i, type SubmitHandler as j, type SubmitOptions as k, type SubmitResult as l, type ValidationResult as m, type ValidationTrigger as n, createForm as o, emptyValueForSchema as p, flattenIssues as q, isAsyncRequiredError as r, isClearableSchema as s, shouldValidateOn as t, validateSync as u, validateAsync as v };

package/dist/{createForm-D0xLZH-Q.d.ts → createForm-B73p1TgL.d.ts}

@@ -108,6 +108,7 @@ declare const validateSync: <TSchema extends z.ZodType>(schema: TSchema, values:
 declare const validateAsync: <TSchema extends z.ZodType>(schema: TSchema, values: z.input<TSchema>) => Promise<SettledValidationResult<z.output<TSchema>>>;
 declare const isAsyncRequiredError: (e: unknown) => boolean;
 declare const emptyValueForSchema: (schema: z.ZodType) => null | undefined;
+declare const isClearableSchema: (schema: z.ZodType) => boolean;
 
 type ReadonlyStoreApi<T> = Pick<StoreApi<T>, "getState" | "getInitialState" | "subscribe">;
 type CreateFormOptions<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = Readonly<{
@@ -197,4 +198,4 @@ type Form<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = R
 }>;
 declare const createForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(schema: TSchema, options: CreateFormOptions<TSchema, D>) => Form<TSchema, D>;
 
-export { type BoolMap as B, type CreateFormOptions as C, type DefaultPathDepth as D, type ErrorMap as E, type Form as F, type InvalidSubmitHandler as I, type PathDepth as P, type ReadonlyStoreApi as R, type SettledFieldValidationResult as S, type ValidationMode as V, type FieldValidationResult as a, type FormState as b, type FieldPath as c, type FieldValue as d, type FieldSnapshot as e, type FieldsValidationResult as f, type ResetOptions as g, type SettledFieldsValidationResult as h, type SettledValidationResult as i, type SubmitHandler as j, type SubmitOptions as k, type SubmitResult as l, type ValidationResult as m, type ValidationTrigger as n, createForm as o, emptyValueForSchema as p, flattenIssues as q, isAsyncRequiredError as r, shouldValidateOn as s, validateSync as t, validateAsync as v };
+export { type BoolMap as B, type CreateFormOptions as C, type DefaultPathDepth as D, type ErrorMap as E, type Form as F, type InvalidSubmitHandler as I, type PathDepth as P, type ReadonlyStoreApi as R, type SettledFieldValidationResult as S, type ValidationMode as V, type FieldValidationResult as a, type FormState as b, type FieldPath as c, type FieldValue as d, type FieldSnapshot as e, type FieldsValidationResult as f, type ResetOptions as g, type SettledFieldsValidationResult as h, type SettledValidationResult as i, type SubmitHandler as j, type SubmitOptions as k, type SubmitResult as l, type ValidationResult as m, type ValidationTrigger as n, createForm as o, emptyValueForSchema as p, flattenIssues as q, isAsyncRequiredError as r, isClearableSchema as s, shouldValidateOn as t, validateSync as u, validateAsync as v };

package/dist/devtools/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { z } from 'zod';
-import { F as Form } from '../createForm-D0xLZH-Q.cjs';
+import { F as Form } from '../createForm-B73p1TgL.cjs';
 import 'zustand/vanilla';
 
 type DevtoolsPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";

package/dist/devtools/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { z } from 'zod';
-import { F as Form } from '../createForm-D0xLZH-Q.js';
+import { F as Form } from '../createForm-B73p1TgL.js';
 import 'zustand/vanilla';
 
 type DevtoolsPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";

package/dist/index.cjs

@@ -276,6 +276,7 @@ var emptyValueForSchema = (schema) => {
   };
   return walk(schema, false);
 };
+var isClearableSchema = (schema) => schema instanceof zod.z.ZodOptional || schema instanceof zod.z.ZodNullable || schema instanceof zod.z.ZodDefault || schema instanceof zod.z.ZodPrefault;
 var unwrapForWalk = (s) => {
   if (s instanceof zod.z.ZodOptional || s instanceof zod.z.ZodNullable) {
     return s.unwrap();
@@ -1197,7 +1198,7 @@ var persistForm = (form, options) => {
       return void 0;
     }
   };
-  const restore = () => {
+  const load = () => {
     try {
       const raw = storage === null ? null : storage.getItem(options.key);
       if (raw === null) return false;
@@ -1242,7 +1243,7 @@ var persistForm = (form, options) => {
     }
   };
   if (apply !== "manual") {
-    restore();
+    load();
   }
   const unsubscribe = form.watchValues((values) => {
     cancelPending();
@@ -1256,7 +1257,7 @@ var persistForm = (form, options) => {
     }
   });
   return Object.freeze({
-    restore,
+    load,
     clear: () => {
       cancelPending();
       try {
@@ -1287,7 +1288,7 @@ var usePersistForm = (form, options) => {
   }, [form, key]);
   return react.useMemo(
     () => ({
-      restore: () => inner.current?.restore() ?? false,
+      load: () => inner.current?.load() ?? false,
       clear: () => inner.current?.clear(),
       // dispose stops THIS component's watching early; the effect cleanup
       // still runs its own dispose harmlessly (persistForm's dispose is
@@ -1316,6 +1317,51 @@ var useForm = (schema, options) => {
   }, [form, schema, options.initialValues]);
   return form;
 };
+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 });
@@ -1351,12 +1397,17 @@ function useField(form, pathArg, options) {
   const path = slice.path;
   const formSchema = form.schema;
   const initialValue = slice.initialValue;
-  const emptyValue = react.useMemo(() => {
+  const { emptyValue, clearable } = react.useMemo(() => {
     if (formSchema !== void 0) {
       const sub = fieldSchemaAtPath(formSchema, path);
-      if (sub !== null) return emptyValueForSchema(sub);
+      if (sub !== null) {
+        return {
+          emptyValue: emptyValueForSchema(sub),
+          clearable: isClearableSchema(sub)
+        };
+      }
     }
-    return initialValue === null ? null : void 0;
+    return initialValue === null ? { emptyValue: null, clearable: true } : { emptyValue: void 0, clearable: false };
   }, [formSchema, path, initialValue]);
   const debounceMs = options?.debounceMs;
   const debounceTimerRef = react.useRef(null);
@@ -1442,6 +1493,7 @@ function useField(form, pathArg, options) {
       value: slice.value,
       initialValue: slice.initialValue,
       emptyValue,
+      clearable,
       error: slice.error,
       // `?.[0]` covers both the undefined channel and an empty array.
       firstError: slice.error?.[0],
@@ -1456,7 +1508,7 @@ function useField(form, pathArg, options) {
       validateAsync: validateAsync2,
       onBlur
     }),
-    [slice, emptyValue, setValue, setTouched, setError, clearError, validate, validateAsync2, onBlur]
+    [slice, emptyValue, clearable, setValue, setTouched, setError, clearError, validate, validateAsync2, onBlur]
   );
 }
 
@@ -1797,9 +1849,7 @@ var textInputProps = (field) => ({
   "aria-invalid": ariaInvalid(field),
   onChange: (e) => {
     const text = e.target.value;
-    field.setValue(
-      text === "" && field.emptyValue === null ? null : text
-    );
+    field.setValue(text === "" && field.clearable ? field.emptyValue : text);
   },
   onBlur: field.onBlur
 });
@@ -1873,9 +1923,7 @@ var selectProps = (field) => ({
   "aria-invalid": ariaInvalid(field),
   onChange: (e) => {
     const v = e.target.value;
-    field.setValue(
-      v === "" && field.emptyValue === null ? null : v
-    );
+    field.setValue(v === "" && field.clearable ? field.emptyValue : v);
   },
   onBlur: field.onBlur
 });
@@ -2082,7 +2130,7 @@ var SelectField = ({
   const field = useField(form, path);
   const a11y = useFieldA11y(field.error);
   const select = selectProps(field);
-  const clearable = field.emptyValue === null;
+  const clearable = field.clearable;
   const hasExplicitEmptyOption = options.some((opt) => opt.value === "");
   const showEmptyOption = !hasExplicitEmptyOption && (clearable || select.value === "" || placeholder !== void 0);
   return /* @__PURE__ */ jsxRuntime.jsx(
@@ -2189,6 +2237,7 @@ exports.focusFirstError = focusFirstError;
 exports.getAtPath = getAtPath;
 exports.hasFieldError = hasFieldError;
 exports.isAsyncRequiredError = isAsyncRequiredError;
+exports.isClearableSchema = isClearableSchema;
 exports.numberInputProps = numberInputProps;
 exports.numberToInputText = numberToInputText;
 exports.parseDateText = parseDateText;
@@ -2203,6 +2252,8 @@ 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;