react-form-action 2.4.1 → 2.4.2

package/README.md

@@ -1,497 +1,498 @@
-# react-form-action
-
-End-to-end typesafe success, error & validation state control for Next.js form actions.
-
-## Features
-
-**Action Creator**
-
-- ✅ Provides envelope objects with `"initial" | "invalid" | "success" | "failure"` response types.
-- ✅ Define generic payload for each of the response type.
-
-**tRPC-like Form Action builder**
-
-- ✅ Define payload schema with the `.input(zodSchema)` to validate the `formData`
-- ✅ Reuse business logic with the `.use(middleware)` method.
-- ✅ Reuse error handling with the `.error(handler)`.
-
-**React Context access with the `<Action action={myFormAction} />` component**
-
-- ✅ The `useActionState()` accessible via the `useActionContext()` hook.
-- ✅ Computes progress flags like `isInvalid`, `isSuccess` based on the envelope type.
-
-**Context-bound `<Form />` component**
-
-- ✅ Reads the `action` from the `<Action />` context.
-- ✅ Opt-out from the default form reset after action submit.
-
-## Install
-
-```
-npm i react-form-action zod-form-data
-```
-
-<a aria-label="NPM version" href="https://www.npmjs.com/package/react-form-action">
-  <img alt="NPM Version" src="https://img.shields.io/npm/v/react-form-action?style=for-the-badge&labelColor=24292e">
-</a>
-
-## Getting Started
-
-#### 1️⃣ Create a Server Action
-
-```tsx
-// app/subscribe/action.ts
-"use server";
-
-import { formAction } from "react-form-action";
-import { z } from "zod";
-
-export const subscribeAction = formAction
-  .input(z.object({ email: z.string().email() }))
-  .run(async ({ input }) => {
-    return input.email;
-  });
-```
-
-#### 2️⃣ Create a Client Form Component
-
-```tsx
-// app/subscribe/form.tsx
-"use client";
-
-import {
-  Form,
-  Pending,
-  createComponents,
-  useActionContext,
-} from "react-form-action/client";
-
-import { subscribeAction } from "./action";
-
-const { FieldError, Success } = createComponents(subscribeAction);
-
-export function SubscribeForm() {
-  const { isPending, isFailure, error, data } =
-    useActionContext(subscribeAction);
-
-  return (
-    <Form>
-      <Success>
-        <p>✅ Email {data} was registered.</p>
-      </Success>
-      <input name="email" />
-      {/*💡 The FieldError "name" prop supports autocompletion */}
-      <FieldError name="email" />
-      <button type="submit" disabled={isPending}>
-        {isPending ? "🌀 Submitting..." : "Submit"}
-      </button>
-      <Pending>Please wait...</Pending>
-    </Form>
-  );
-}
-```
-
-#### 3️⃣ Provide the `<Action>` context on a Page
-
-```tsx
-// app/subscribe/page.tsx
-
-import { Action } from "react-form-action/client";
-
-import { subscribeAction } from "./action";
-import { SubscribeForm } from "./form";
-
-export default function Page() {
-  return (
-    <Action action={subscribeAction} initialData="">
-      <SubscribeForm />
-    </Action>
-  );
-}
-```
-
-## Usage
-
-### `formAction` builder
-
-The [`zod-form-data`](https://www.npmjs.com/package/zod-form-data) powered action builder.
-
-```ts
-// app/actions/auth.ts
-"use server";
-
-import { formAction } from "react-form-action";
-import { z } from "zod";
-import { cookies } from "next/headers";
-
-const i18nMiddleware = async () => {
-  const { t } = await useTranslation("auth", cookies().get("i18n")?.value);
-  // will be added to context
-  return { t };
-};
-
-const authAction = formAction
-  .use(i18nMiddleware)
-  .use(async ({ ctx: { t } }) =>
-    console.log("🎉 context enhanced by previous middlewares 🎉", t)
-  )
-  .error(async ({ error }) => {
-    if (error instanceof DbError) {
-      return error.custom.code;
-    } else {
-      // unknown error
-      // default Next.js error handling (error.js boundary)
-      throw error;
-    }
-  });
-
-export const signIn = authAction
-  .input(z.object({ email: z.string().email() }))
-  // 🎉 extend the previous input (only without refinements and transforms)
-  .input(z.object({ password: z.string() }))
-  .run(async ({ ctx: { t }, input: { email, password } }) => {
-    // Type inferred: {email: string, password: string}
-
-    await db.signIn({ email, password });
-
-    return t("verificationEmail.success");
-  });
-
-export const signUp = authAction
-  .input(
-    z
-      .object({
-        email: z.string().email(),
-        password: z.string(),
-        confirm: z.string(),
-      })
-      .refine((data) => data.password === data.confirm, {
-        message: "Passwords don't match",
-        path: ["confirm"],
-      })
-  ) // if using refinement, only one input call is permited, as schema with ZodEffects is not extendable.
-  .run(async ({ ctx: { t }, input: { email, password } }) => {
-    // 🎉 passwords match!
-
-    const tokenData = await db.signUp({ email, password });
-
-    if (!tokenData) {
-      return t("signUp.emailVerificationRequired");
-    }
-
-    return t("singUp.success");
-  });
-```
-
-### Action Creator
-
-Low-level action creator, which provides the `success`, `failure` and `invalid` envelope constructors. With the `createFormAction` you must handle the native `FormData` by yourself.
-
-```ts
-"use server";
-
-import { createFormAction } from "react-form-action";
-import { z } from "zod";
-
-// Define custom serializable error & success data types
-type ErrorData = {
-  message: string;
-};
-
-type SuccessData = {
-  message: string;
-};
-
-type ValiationError = {
-  name?: string;
-};
-
-const updateUserSchema = z.object({ name: z.string() });
-
-export const updateUser = createFormAction<
-  SuccessData,
-  ErrorData,
-  ValiationError
->(({ success, failure, invalid }) =>
-  // success and failure helper functions create wrappers for success & error data respectively
-  async (prevState, formData) => {
-    if (prevState.type === "initial") {
-      // use the initialData passed to <Form /> here
-      // prevState.data === "foobar"
-    }
-
-    try {
-      const { name } = updateUserSchema.parse({
-        name: formData.get("name"),
-      });
-
-      const user = await updateCurrentUser(name);
-
-      if (user) {
-        // {type: "success", data: "Your profile has been updated.", error: null, validationError: null}
-        return success({
-          message: "Your profile has been updated.",
-        });
-      } else {
-        // {type: "error", data: null, error: { message: "No current user." }, validationError: null}
-        return failure({ message: "No current user." });
-      }
-    } catch (error) {
-      if (error instanceof ZodError) {
-        // {type: "invalid", data: null, error: null, validationError: {name: "Invalid input"}}
-        return invalid({
-          name: error.issues[0]?.message ?? "Validation error",
-        });
-      }
-
-      return failure({ message: "Failed to update user." });
-    }
-  }
-);
-```
-
-The action creator supports arguments binding:
-
-```ts
-export const updateUser = createFormAction(
-  (
-    { success, failure, invalid },
-    userId: string /* Here you can specify multiple arguments */
-  ) =>
-    async (prevState, formData) => {
-      try {
-        const { name } = updateUserSchema.parse({
-          name: formData.get("name"),
-        });
-
-        const user = await db.users.findById(userId);
-
-        if (!user) {
-          return failure({ message: "No such user." });
-        }
-
-        const updated = await user.update({ name });
-
-        if (updated) {
-          return success({
-            message: "User has been updated.",
-          });
-        } else {
-          return failure({ message: "Failed to update." });
-        }
-      } catch (error) {
-        // handle error
-      }
-    }
-);
-
-// call bind as usuall, the "123" becomes the "userId"
-updateUser.bind(null, "123");
-```
-
-### Action Context
-
-The `<Action>` components enables you to access your `action`'s state with the `useActionContext()` hook:
-
-```tsx
-// 👉 Define standalone client form component (e.g. /app/auth/signup/SignUpForm.tsx)
-"use client";
-
-import { Action, Form, useActionContext } from "react-form-action/client";
-import type { PropsWithChildren } from "react";
-
-import { signupAction } from "./action";
-
-function Pending({ children }: PropsWithChildren) {
-  // read any state from the ActionContext:
-  const {
-    error,
-    data,
-    validationError,
-    isPending,
-    isFailure,
-    isInvalid,
-    isSuccess,
-    isInitial,
-  } = useActionContext();
-
-  return isPending && children;
-}
-
-// 💡 render this form on your RSC page (/app/auth/signup/page.tsx)
-export function SignupForm() {
-  return (
-    <Action action={signupAction}>
-      <Form>
-        <input name="email" />
-        <input name="password" />
-      </Form>
-      {/* 🎆 Read the pending state outside the <Form> */}
-      <Pending>
-        {/* This renders only when the action is pending. 😎 */}
-        <p>Please wait...</p>
-      </Pending>
-    </Action>
-  );
-}
-```
-
-### `<Form>` Component
-
-The `<form>` submits the action in `onSubmit` handler to [prevent automatic form reset](https://github.com/facebook/react/issues/29034).
-Pass `autoReset` prop to use the `action` prop instead and keep the default reset.
-
-```tsx
-"use client";
-
-import { Action, Form } from "react-form-action/client";
-
-import { updateUser } from "./action";
-
-export function UpdateUserForm() {
-  return (
-    <Action action={updateUser}>
-      <Form autoReset>{/* ... */}</Form>
-    </Action>
-  );
-}
-```
-
-### Context Bound Components `createComponents()`
-
-Use the `createComponents(action)` helper to create components which use the ActionContext and have types bound to the action type.
-
-#### `<FielError>` Component
-
-```tsx
-"use client";
-
-// ⚠️ createComponents is usable only in "use client" components
-import { Form, createComponents } from "react-form-action/client";
-
-import { authAction } from "./actions";
-
-export const signUpAction = authAction
-  .input(
-    z
-      .object({
-        user: z.object({
-          email: z.string().email(),
-          name: z.string(),
-        }),
-        password: z.string().min(8),
-        confirm: z.string(),
-      })
-      .refine((data) => data.password === data.confirm, {
-        message: "Passwords don't match",
-      })
-  )
-  .run(async ({ ctx, input }) => {
-    return null;
-  });
-
-// 🌟 The FieldError is now bound do the signUpAction input schema which allows autocompletion for its "name" prop
-// ⚠️ Usable only with actions created with the formAction builder
-const { FieldError } = createComponents(signUpAction);
-
-export function SignUpForm() {
-  return (
-    <Action action={signUpAction} initialData={null}>
-      <Form>
-        {/* 1️⃣ When the "name" prop is ommited, the top-level error will be rendered e.g.:
-          "Passwords don't match" */}
-        <FieldError />
-        {/* 2️⃣ Access fields by their name: */}
-        <FieldError name="password" />
-        {/* 3️⃣ Access nested fields by dot access notation: */}
-        <FieldError name="user.email" />
-      </Form>
-    </Action>
-  );
-}
-```
-
-#### `<Success>`
-
-#### When children are JSX
-
-```tsx
-import { Action, createComponents } from "react-form-action/client";
-
-const { Success } = createComponents(signUpAction);
-
-function MyForm() {
-  return (
-    <Action action={signUpAction}>
-      <Success>
-        {/* 👉 The message will render only after the action has succeeded */}
-        <p>You've been signed up!</p>
-      </Success>
-    </Action>
-  );
-}
-```
-
-#### When children is a render prop
-
-```tsx
-import { createComponents } from "react-form-action/client";
-
-const { Success } = createComponents(signUpAction);
-
-function Label({children}: PropsWithChildren) {
-  return (
-    <Success>
-      {({ isSuccess, data }) => (
-        {/* 👉 With a render prop, the children are always mounted, regardles of the isSuccess flag */}
-        <label className={isSuccess ? "green" : ""}>
-          {children}
-        </label>
-      )}
-    </Success>
-  );
-};
-```
-
-### `<Pending>`
-
-Render children when the action is pending:
-
-#### When children are JSX
-
-```tsx
-import { Action, Pending } from "react-form-action/client";
-
-import { Spinner } from "./components";
-
-function MyForm() {
-  return (
-    <Action action={action}>
-      {/* 👉 Unlike the React.useFormStatus() hook, we don't need here the <form> element at all. */}
-      <Pending>
-        {/* 👉 The spinner will UNMOUNT when the action is NOT pending */}
-        <Spinner />
-      </Pending>
-    </Action>
-  );
-}
-```
-
-#### When children is a render prop
-
-```tsx
-import { Pending } from "react-form-action/client";
-
-function SubmitButton() {
-  return (
-    <Pending>
-      {({ isPending }) => (
-        {/* 👉 With a render prop, the children are always mounted, regardles of the isPending flag */}
-        <button type="submit" disabled={isPending}>
-          {isPending ? "Submitting..." : "Submit"}
-        </button>
-      )}
-    </Pending>
-  );
-};
-```
+# react-form-action
+
+End-to-end typesafe success, error & validation state control for Next.js form actions.
+
+## Features
+
+**Action Creator**
+
+- ✅ Provides envelope objects with `"initial" | "invalid" | "success" | "failure"` response types.
+- ✅ Define generic payload for each of the response type.
+- ✅ Bind action arguments.
+
+**tRPC-like Form Action builder**
+
+- ✅ Define payload schema with the `.input(zodSchema)` to validate the `formData`
+- ✅ Reuse business logic with the `.use(middleware)` method.
+- ✅ Reuse error handling with the `.error(handler)`.
+
+**React Context access with the `<Action action={myFormAction} />` component**
+
+- ✅ The `useActionState()` accessible via the `useActionContext()` hook.
+- ✅ Computes progress flags like `isInvalid`, `isSuccess` based on the envelope type.
+
+**Context-bound `<Form />` component**
+
+- ✅ Reads the `action` from the `<Action />` context.
+- ✅ Opt-out from the default form reset after action submit.
+
+## Install
+
+```
+npm i react-form-action zod-form-data
+```
+
+<a aria-label="NPM version" href="https://www.npmjs.com/package/react-form-action">
+  <img alt="NPM Version" src="https://img.shields.io/npm/v/react-form-action?style=for-the-badge&labelColor=24292e">
+</a>
+
+## Getting Started
+
+#### 1️⃣ Create a Server Action
+
+```tsx
+// app/subscribe/action.ts
+"use server";
+
+import { formAction } from "react-form-action";
+import { z } from "zod";
+
+export const subscribeAction = formAction
+  .input(z.object({ email: z.string().email() }))
+  .run(async ({ input }) => {
+    return input.email;
+  });
+```
+
+#### 2️⃣ Create a Client Form Component
+
+```tsx
+// app/subscribe/form.tsx
+"use client";
+
+import {
+  Form,
+  Pending,
+  createComponents,
+  useActionContext,
+} from "react-form-action/client";
+
+import { subscribeAction } from "./action";
+
+const { FieldError, Success } = createComponents(subscribeAction);
+
+export function SubscribeForm() {
+  const { isPending, isFailure, error, data } =
+    useActionContext(subscribeAction);
+
+  return (
+    <Form>
+      <Success>
+        <p>✅ Email {data} was registered.</p>
+      </Success>
+      <input name="email" />
+      {/*💡 The FieldError "name" prop supports autocompletion */}
+      <FieldError name="email" />
+      <button type="submit" disabled={isPending}>
+        {isPending ? "🌀 Submitting..." : "Submit"}
+      </button>
+      <Pending>Please wait...</Pending>
+    </Form>
+  );
+}
+```
+
+#### 3️⃣ Provide the `<Action>` context on a Page
+
+```tsx
+// app/subscribe/page.tsx
+
+import { Action } from "react-form-action/client";
+
+import { subscribeAction } from "./action";
+import { SubscribeForm } from "./form";
+
+export default function Page() {
+  return (
+    <Action action={subscribeAction} initialData="">
+      <SubscribeForm />
+    </Action>
+  );
+}
+```
+
+## Usage
+
+### `formAction` builder
+
+The [`zod-form-data`](https://www.npmjs.com/package/zod-form-data) powered action builder.
+
+```ts
+// app/actions/auth.ts
+"use server";
+
+import { formAction } from "react-form-action";
+import { z } from "zod";
+import { cookies } from "next/headers";
+
+const i18nMiddleware = async () => {
+  const { t } = await useTranslation("auth", cookies().get("i18n")?.value);
+  // will be added to context
+  return { t };
+};
+
+const authAction = formAction
+  .use(i18nMiddleware)
+  .use(async ({ ctx: { t } }) =>
+    console.log("🎉 context enhanced by previous middlewares 🎉", t)
+  )
+  .error(async ({ error }) => {
+    if (error instanceof DbError) {
+      return error.custom.code;
+    } else {
+      // unknown error
+      // default Next.js error handling (error.js boundary)
+      throw error;
+    }
+  });
+
+export const signIn = authAction
+  .input(z.object({ email: z.string().email() }))
+  // 🎉 extend the previous input (only without refinements and transforms)
+  .input(z.object({ password: z.string() }))
+  .run(async ({ ctx: { t }, input: { email, password } }) => {
+    // Type inferred: {email: string, password: string}
+
+    await db.signIn({ email, password });
+
+    return t("verificationEmail.success");
+  });
+
+export const signUp = authAction
+  .input(
+    z
+      .object({
+        email: z.string().email(),
+        password: z.string(),
+        confirm: z.string(),
+      })
+      .refine((data) => data.password === data.confirm, {
+        message: "Passwords don't match",
+        path: ["confirm"],
+      })
+  ) // if using refinement, only one input call is permited, as schema with ZodEffects is not extendable.
+  .run(async ({ ctx: { t }, input: { email, password } }) => {
+    // 🎉 passwords match!
+
+    const tokenData = await db.signUp({ email, password });
+
+    if (!tokenData) {
+      return t("signUp.emailVerificationRequired");
+    }
+
+    return t("singUp.success");
+  });
+```
+
+### Action Creator
+
+Low-level action creator, which provides the `success`, `failure` and `invalid` envelope constructors. With the `createFormAction` you must handle the native `FormData` by yourself.
+
+```ts
+"use server";
+
+import { createFormAction } from "react-form-action";
+import { z } from "zod";
+
+// Define custom serializable error & success data types
+type ErrorData = {
+  message: string;
+};
+
+type SuccessData = {
+  message: string;
+};
+
+type ValiationError = {
+  name?: string;
+};
+
+const updateUserSchema = z.object({ name: z.string() });
+
+export const updateUser = createFormAction<
+  SuccessData,
+  ErrorData,
+  ValiationError
+>(({ success, failure, invalid }) =>
+  // success and failure helper functions create wrappers for success & error data respectively
+  async (prevState, formData) => {
+    if (prevState.type === "initial") {
+      // use the initialData passed to <Form /> here
+      // prevState.data === "foobar"
+    }
+
+    try {
+      const { name } = updateUserSchema.parse({
+        name: formData.get("name"),
+      });
+
+      const user = await updateCurrentUser(name);
+
+      if (user) {
+        // {type: "success", data: "Your profile has been updated.", error: null, validationError: null}
+        return success({
+          message: "Your profile has been updated.",
+        });
+      } else {
+        // {type: "error", data: null, error: { message: "No current user." }, validationError: null}
+        return failure({ message: "No current user." });
+      }
+    } catch (error) {
+      if (error instanceof ZodError) {
+        // {type: "invalid", data: null, error: null, validationError: {name: "Invalid input"}}
+        return invalid({
+          name: error.issues[0]?.message ?? "Validation error",
+        });
+      }
+
+      return failure({ message: "Failed to update user." });
+    }
+  }
+);
+```
+
+The action creator supports arguments binding:
+
+```ts
+export const updateUser = createFormAction(
+  (
+    { success, failure, invalid },
+    userId: string /* Here you can specify multiple arguments */
+  ) =>
+    async (prevState, formData) => {
+      try {
+        const { name } = updateUserSchema.parse({
+          name: formData.get("name"),
+        });
+
+        const user = await db.users.findById(userId);
+
+        if (!user) {
+          return failure({ message: "No such user." });
+        }
+
+        const updated = await user.update({ name });
+
+        if (updated) {
+          return success({
+            message: "User has been updated.",
+          });
+        } else {
+          return failure({ message: "Failed to update." });
+        }
+      } catch (error) {
+        // handle error
+      }
+    }
+);
+
+// call bind as usuall, the "123" becomes the "userId"
+updateUser.bind(null, "123");
+```
+
+### Action Context
+
+The `<Action>` components enables you to access your `action`'s state with the `useActionContext()` hook:
+
+```tsx
+// 👉 Define standalone client form component (e.g. /app/auth/signup/SignUpForm.tsx)
+"use client";
+
+import { Action, Form, useActionContext } from "react-form-action/client";
+import type { PropsWithChildren } from "react";
+
+import { signupAction } from "./action";
+
+function Pending({ children }: PropsWithChildren) {
+  // read any state from the ActionContext:
+  const {
+    error,
+    data,
+    validationError,
+    isPending,
+    isFailure,
+    isInvalid,
+    isSuccess,
+    isInitial,
+  } = useActionContext();
+
+  return isPending && children;
+}
+
+// 💡 render this form on your RSC page (/app/auth/signup/page.tsx)
+export function SignupForm() {
+  return (
+    <Action action={signupAction}>
+      <Form>
+        <input name="email" />
+        <input name="password" />
+      </Form>
+      {/* 🎆 Read the pending state outside the <Form> */}
+      <Pending>
+        {/* This renders only when the action is pending. 😎 */}
+        <p>Please wait...</p>
+      </Pending>
+    </Action>
+  );
+}
+```
+
+### `<Form>` Component
+
+The `<form>` submits the action in `onSubmit` handler to [prevent automatic form reset](https://github.com/facebook/react/issues/29034).
+Pass `autoReset` prop to use the `action` prop instead and keep the default reset.
+
+```tsx
+"use client";
+
+import { Action, Form } from "react-form-action/client";
+
+import { updateUser } from "./action";
+
+export function UpdateUserForm() {
+  return (
+    <Action action={updateUser}>
+      <Form autoReset>{/* ... */}</Form>
+    </Action>
+  );
+}
+```
+
+### Context Bound Components `createComponents()`
+
+Use the `createComponents(action)` helper to create components which use the ActionContext and have types bound to the action type.
+
+#### `<FielError>` Component
+
+```tsx
+"use client";
+
+// ⚠️ createComponents is usable only in "use client" components
+import { Form, createComponents } from "react-form-action/client";
+
+import { authAction } from "./actions";
+
+export const signUpAction = authAction
+  .input(
+    z
+      .object({
+        user: z.object({
+          email: z.string().email(),
+          name: z.string(),
+        }),
+        password: z.string().min(8),
+        confirm: z.string(),
+      })
+      .refine((data) => data.password === data.confirm, {
+        message: "Passwords don't match",
+      })
+  )
+  .run(async ({ ctx, input }) => {
+    return null;
+  });
+
+// 🌟 The FieldError is now bound do the signUpAction input schema which allows autocompletion for its "name" prop
+// ⚠️ Usable only with actions created with the formAction builder
+const { FieldError } = createComponents(signUpAction);
+
+export function SignUpForm() {
+  return (
+    <Action action={signUpAction} initialData={null}>
+      <Form>
+        {/* 1️⃣ When the "name" prop is ommited, the top-level error will be rendered e.g.:
+          "Passwords don't match" */}
+        <FieldError />
+        {/* 2️⃣ Access fields by their name: */}
+        <FieldError name="password" />
+        {/* 3️⃣ Access nested fields by dot access notation: */}
+        <FieldError name="user.email" />
+      </Form>
+    </Action>
+  );
+}
+```
+
+#### `<Success>`
+
+#### When children are JSX
+
+```tsx
+import { Action, createComponents } from "react-form-action/client";
+
+const { Success } = createComponents(signUpAction);
+
+function MyForm() {
+  return (
+    <Action action={signUpAction}>
+      <Success>
+        {/* 👉 The message will render only after the action has succeeded */}
+        <p>You've been signed up!</p>
+      </Success>
+    </Action>
+  );
+}
+```
+
+#### When children is a render prop
+
+```tsx
+import { createComponents } from "react-form-action/client";
+
+const { Success } = createComponents(signUpAction);
+
+function Label({children}: PropsWithChildren) {
+  return (
+    <Success>
+      {({ isSuccess, data }) => (
+        {/* 👉 With a render prop, the children are always mounted, regardles of the isSuccess flag */}
+        <label className={isSuccess ? "green" : ""}>
+          {children}
+        </label>
+      )}
+    </Success>
+  );
+};
+```
+
+### `<Pending>`
+
+Render children when the action is pending:
+
+#### When children are JSX
+
+```tsx
+import { Action, Pending } from "react-form-action/client";
+
+import { Spinner } from "./components";
+
+function MyForm() {
+  return (
+    <Action action={action}>
+      {/* 👉 Unlike the React.useFormStatus() hook, we don't need here the <form> element at all. */}
+      <Pending>
+        {/* 👉 The spinner will UNMOUNT when the action is NOT pending */}
+        <Spinner />
+      </Pending>
+    </Action>
+  );
+}
+```
+
+#### When children is a render prop
+
+```tsx
+import { Pending } from "react-form-action/client";
+
+function SubmitButton() {
+  return (
+    <Pending>
+      {({ isPending }) => (
+        {/* 👉 With a render prop, the children are always mounted, regardles of the isPending flag */}
+        <button type="submit" disabled={isPending}>
+          {isPending ? "Submitting..." : "Submit"}
+        </button>
+      )}
+    </Pending>
+  );
+};
+```

package/dist/chunk-LPB4R2UB.mjs

@@ -0,0 +1 @@
+function u(a){return{type:"initial",data:a,error:null,validationError:null}}function d(a){function t(r){return{type:"success",data:r,error:null,validationError:null}}function o(r){return{type:"failure",data:null,error:r,validationError:null}}function n(r){return{type:"invalid",data:null,error:null,validationError:r}}return(...r)=>{let e=r.pop(),i=r.pop(),l=[...r];return a({success:t,failure:o,invalid:n},...l)(i,e)}}export{u as a,d as b};

package/dist/client.mjs

@@ -1 +1 @@
-"use client";import{a as m}from"./chunk-22TNX3DL.mjs";import y from"react";import{createContext as P,use as S}from"react";import{useActionState as F}from"react";var p={isInitial:!1,isInvalid:!1,isFailure:!1,isSuccess:!1},u=P(null);function a(o){let t=S(u);if(!t)throw new Error("ActionContext must be initialized before use. Is your useActionContext hook wrapped with an <Action> Component?");return t}function I({children:o,action:t,initialData:i,permalink:e}){let[r,n,s]=F(t,m(i),e),l=r.type==="initial"?{...r,...p,action:n,isPending:s,isInitial:!0}:r.type==="invalid"?{...r,...p,action:n,isPending:s,isInvalid:!0}:r.type==="failure"?{...r,...p,action:n,isPending:s,isFailure:!0}:{...r,...p,action:n,isPending:s,isSuccess:!0};return y.createElement(u,{value:l},o)}import A,{startTransition as C}from"react";function V({autoReset:o=!1,...t}){let{action:i}=a();return A.createElement("form",{...o?{action:i}:{onSubmit:r=>{r.preventDefault();let n=r.currentTarget;C(()=>{i(new FormData(n))})}},...t})}import c from"react";import f from"react";var h=".",d=Object.freeze({_errors:Object.freeze([])});function E({errors:o,name:t,children:i=({error:e})=>f.createElement(f.Fragment,null,e)}){if(t.length===0)return i({name:t,error:o._errors[0],errors:o._errors});let e=t.split(h),r=o;for(;e.length;){let n=e.shift();r=r[n]??d}return i({name:t,error:r._errors[0],errors:r._errors})}function $(o){function t({name:e,children:r}){let{isInvalid:n,validationError:s}=a(o);return c.createElement(E,{errors:s??d,name:e},r??(({error:x})=>n&&c.createElement(c.Fragment,null,x)))}function i({children:e}){let{isSuccess:r,data:n}=a(o);return typeof e=="function"?e(r?{isSuccess:r,data:n}:{isSuccess:r,data:n}):r&&e}return{FieldError:t,Success:i}}function X({children:o}){let{isPending:t}=a();return typeof o=="function"?o({isPending:t}):t&&o}export{I as Action,V as Form,X as Pending,E as ZodFieldError,$ as createComponents,d as noError,a as useActionContext};
+"use client";import{a as m}from"./chunk-LPB4R2UB.mjs";import y from"react";import{createContext as P,use as S}from"react";import{useActionState as F}from"react";var p={isInitial:!1,isInvalid:!1,isFailure:!1,isSuccess:!1},u=P(null);function a(o){let t=S(u);if(!t)throw new Error("ActionContext must be initialized before use. Is your useActionContext hook wrapped with an <Action> Component?");return t}function I({children:o,action:t,initialData:i,permalink:e}){let[r,n,s]=F(t,m(i),e),l=r.type==="initial"?{...r,...p,action:n,isPending:s,isInitial:!0}:r.type==="invalid"?{...r,...p,action:n,isPending:s,isInvalid:!0}:r.type==="failure"?{...r,...p,action:n,isPending:s,isFailure:!0}:{...r,...p,action:n,isPending:s,isSuccess:!0};return y.createElement(u,{value:l},o)}import A,{startTransition as C}from"react";function V({autoReset:o=!1,...t}){let{action:i}=a();return A.createElement("form",{...o?{action:i}:{onSubmit:r=>{r.preventDefault();let n=r.currentTarget;C(()=>{i(new FormData(n))})}},...t})}import c from"react";import f from"react";var h=".",d=Object.freeze({_errors:Object.freeze([])});function E({errors:o,name:t,children:i=({error:e})=>f.createElement(f.Fragment,null,e)}){if(t.length===0)return i({name:t,error:o._errors[0],errors:o._errors});let e=t.split(h),r=o;for(;e.length;){let n=e.shift();r=r[n]??d}return i({name:t,error:r._errors[0],errors:r._errors})}function $(o){function t({name:e,children:r}){let{isInvalid:n,validationError:s}=a(o);return c.createElement(E,{errors:s??d,name:e},r??(({error:x})=>n&&c.createElement(c.Fragment,null,x)))}function i({children:e}){let{isSuccess:r,data:n}=a(o);return typeof e=="function"?e(r?{isSuccess:r,data:n}:{isSuccess:r,data:n}):r&&e}return{FieldError:t,Success:i}}function X({children:o}){let{isPending:t}=a();return typeof o=="function"?o({isPending:t}):t&&o}export{I as Action,V as Form,X as Pending,E as ZodFieldError,$ as createComponents,d as noError,a as useActionContext};

package/dist/index.d.mts

@@ -34,7 +34,7 @@ type FormActionBuilder<Schema extends ZodTypeAny | EmptyInput, Err = Error, Cont
      * @param action async function to execute. It will receive parsed formData as input, when the builder was initialized with a schema.
      * @returns runnable server action exportable from a module.
      */
-    run: Schema extends ZodTypeAny ? <Data>(action: SchemaAction<Data, Context, Schema>) => (state: ActionState<Data, Err, z.inferFormattedError<Schema>>, payload: FormData) => Promise<Flatten<InvalidState<z.inferFormattedError<Schema>> | FailureState<Err> | SuccessState<Data>>> : <Data>(action: Action<Data, Context>) => (state: ActionState<Data, Err>, payload: FormData) => Promise<Flatten<FailureState<Err> | SuccessState<Data>>>;
+    run: Schema extends ZodTypeAny ? <Data>(action: SchemaAction<Data, Flatten<Context>, Schema>) => (state: ActionState<Data, Err, z.inferFormattedError<Schema>>, payload: FormData) => Promise<Flatten<InvalidState<z.inferFormattedError<Schema>> | FailureState<Err> | SuccessState<Data>>> : <Data>(action: Action<Data, Flatten<Context>>) => (state: ActionState<Data, Err>, payload: FormData) => Promise<Flatten<FailureState<Err> | SuccessState<Data>>>;
     /**
      * A chainable context enhancing helper.
      * @param middleware A function which receives the current context, and returns an object which will be added to the context.

package/dist/index.mjs

@@ -1 +1 @@
-import{a as A,b as p}from"./chunk-22TNX3DL.mjs";import{ZodFirstPartyTypeKind as C}from"zod";import{zfd as E}from"zod-form-data";var d=Symbol();function i(n,o=[],r){async function f(t){let e={formData:t};for(let a of o){let s=await a({ctx:e});e={...e,...s}}return e}return{input(t){if(n===d)return i(t,o,r);if(n._def.effect)throw new Error("Previous input is not augmentable because it contains an effect.");if(t._def.effect)throw new Error("Your input contains effect which prevents merging it with the previous inputs.");if(n._def.typeName===C.ZodObject){let e=n.merge(t);return i(e,o)}else throw Error("Merging inputs works only for object schemas without effects.")},use(t){return i(n,[...o,t],r)},error(t){return i(n,o,t)},run:n===d?t=>p(({success:e,failure:a})=>async(s,x)=>{let m=await f(x);try{return e(await t({ctx:m}))}catch(c){if(r)return a(await r({error:c,ctx:m}));throw c}}):n===d?void 0:t=>p(({success:e,failure:a,invalid:s})=>{let x=E.formData(n);return async(m,c)=>{let y=await f(c),u=x.safeParse(c);if(!u.success)return s(u.error.format());let h=u.data;try{return e(await t({input:h,ctx:y}))}catch(S){if(r)return a(await r({error:S,ctx:y}));throw S}}})}}var N=i(d);export{p as createFormAction,N as formAction,A as initial};
+import{a as A,b as p}from"./chunk-LPB4R2UB.mjs";import{ZodFirstPartyTypeKind as E}from"zod";import{zfd as C}from"zod-form-data";var d=Symbol();function i(r,o=[],n){async function f(t){let e={formData:t};for(let a of o){let s=await a({ctx:e});e={...e,...s}}return e}return{input(t){if(r===d)return i(t,o,n);if(r._def.effect)throw new Error("Previous input is not augmentable because it contains an effect.");if(t._def.effect)throw new Error("Your input contains effect which prevents merging it with the previous inputs.");if(r._def.typeName===E.ZodObject){let e=r.merge(t);return i(e,o)}else throw Error("Merging inputs works only for object schemas without effects.")},use(t){return i(r,[...o,t],n)},error(t){return i(r,o,t)},run:r===d?t=>p(({success:e,failure:a})=>async(s,m)=>{let x=await f(m);try{return e(await t({ctx:x}))}catch(c){if(n)return a(await n({error:c,ctx:x}));throw c}}):r===d?void 0:t=>p(({success:e,failure:a,invalid:s})=>{let m=C.formData(r);return async(x,c)=>{let y=await f(c),u=m.safeParse(c);if(!u.success)return s(u.error.format());let h=u.data;try{return e(await t({input:h,ctx:y}))}catch(S){if(n)return a(await n({error:S,ctx:y}));throw S}}})}}var P=i(d);export{p as createFormAction,P as formAction,A as initial};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-form-action",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "State management helpers for the react form actions.",
   "repository": {
     "type": "git",

package/dist/chunk-22TNX3DL.mjs

@@ -1 +0,0 @@
-function d(a){return{type:"initial",data:a,error:null,validationError:null}}function u(a){function t(r){return{type:"success",data:r,error:null,validationError:null}}function o(r){return{type:"failure",data:null,error:r,validationError:null}}function e(r){return{type:"invalid",data:null,error:null,validationError:r}}return(...r)=>{let[n,i,...l]=r.reverse();return a({success:t,failure:o,invalid:e},...l)(i,n)}}export{d as a,u as b};