formstand 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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

package/dist/index.cjs

@@ -1317,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 });
@@ -2207,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;