react-form-action 2.4.2 → 2.5.1

package/README.md

@@ -1,498 +1,539 @@
-# 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>
-  );
-};
-```
+# 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.
+- ✅ Define bindable arguments with the `.args([])` 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");
+  });
+```
+
+#### Args binding
+
+The `formAction` builder supports action arguments binding:
+
+```ts
+// app/update-user/[userId]/action.tsx
+import { formAction } from "react-form-action";
+
+export const updateUser = formAction
+  .args([z.string().uuid()])
+  .run(async ({ args: [userId] }) => {
+    return userId;
+    //     ^? string
+  });
+```
+
+```tsx
+// app/update-user/[userId]/page.tsx
+import { Action } from "react-form-action/client";
+
+import { updateUser } from "./action";
+import { UpdateUserForm } from "./form";
+
+export default function Page({
+  params,
+}: {
+  params: Promise<{ userId: string }>;
+}) {
+  const { userId } = await params;
+
+  const action = updateUser.bind(null, userId);
+
+  return (
+    <Action action={action} initialData="">
+      <SubscribeForm />
+    </Action>
+  );
+}
+```
+
+### 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/index.d.mts

@@ -1,6 +1,6 @@
 import { A as ActionState, a as InvalidState, b as FailureState, S as SuccessState } from './createFormAction-DjhozgiG.mjs';
 export { F as FormAction, I as InitialState, c as createFormAction, i as initial } from './createFormAction-DjhozgiG.mjs';
-import { ZodTypeAny, ZodType, ZodObject, ZodRawShape, objectUtil, z, ZodSchema, ZodEffects } from 'zod';
+import { z, ZodTypeAny, AnyZodTuple, ZodTuple, ZodType, ZodObject, ZodRawShape, objectUtil, ZodSchema, ZodEffects } from 'zod';
 
 declare const emptyInput: unique symbol;
 type EmptyInput = typeof emptyInput;
@@ -16,25 +16,36 @@ type InitialContext = Record<"formData", FormData>;
 /**
  * Action without schema has no input.
  */
-type Action<Data, Context> = (params: {
+type Action<Data, Context, Args extends AnyZodTuple> = (params: {
+    args: z.infer<Args>;
     ctx: Context;
 }) => Promise<Data>;
 /**
  * Action with schema will get parsed formData as the input.
  */
-type SchemaAction<Data, Context, Schema extends ZodSchema> = (params: {
+type SchemaAction<Data, Context, Args extends AnyZodTuple, Schema extends ZodSchema> = (params: {
+    args: z.infer<Args>;
     ctx: Context;
     input: z.infer<Schema>;
 }) => Promise<Data>;
 type AnyZodEffects = ZodEffects<any, any, any>;
-type FormActionBuilder<Schema extends ZodTypeAny | EmptyInput, Err = Error, Context = InitialContext> = {
-    input: <T extends ZodTypeAny>(newInput: T extends ZodType<infer Out extends Record<string, unknown>> ? Schema extends AnyZodEffects ? "Extending schema with effect is not possible." : Schema extends EmptyInput ? T : Schema extends ZodTypeAny ? T extends AnyZodEffects ? "Your input contains effect which prevents merging it with the previous inputs." : T : T : "The schema output must be an object.") => FormActionBuilder<Schema extends ZodObject<infer O1 extends ZodRawShape> ? T extends ZodObject<infer O2 extends ZodRawShape> ? ZodObject<objectUtil.extendShape<O1, O2>> : never : T, Err, Context>;
+type FormActionBuilder<Schema extends ZodTypeAny | EmptyInput, Err = Error, Context = InitialContext, Args extends AnyZodTuple = ZodTuple<[], null>> = {
+    args: <T extends [ZodTypeAny, ...ZodTypeAny[]]>(args: T) => FormActionBuilder<Schema, Err, Context, ZodTuple<T, null>>;
+    input: <T extends ZodTypeAny>(newInput: T extends ZodType<infer Out extends Record<string, unknown>> ? Schema extends AnyZodEffects ? "Extending schema with effect is not possible." : Schema extends EmptyInput ? T : Schema extends ZodTypeAny ? T extends AnyZodEffects ? "Your input contains effect which prevents merging it with the previous inputs." : T : T : "The schema output must be an object.") => FormActionBuilder<Schema extends ZodObject<infer O1 extends ZodRawShape> ? T extends ZodObject<infer O2 extends ZodRawShape> ? ZodObject<objectUtil.extendShape<O1, O2>> : never : T, Err, Context, Args>;
     /**
      * A finishing call on the builder completing your action.
      * @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, 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>>>;
+    run: Schema extends ZodTypeAny ? <Data>(action: SchemaAction<Data, Flatten<Context>, Args, Schema>) => (...args: [
+        ...z.infer<Args>,
+        state: ActionState<Data, Error, z.inferFormattedError<Schema> & z.inferFormattedError<Args>>,
+        payload: FormData
+    ]) => Promise<Flatten<InvalidState<z.inferFormattedError<Schema> & z.inferFormattedError<Args>> | FailureState<Err> | SuccessState<Data>>> : <Data>(action: Action<Data, Flatten<Context>, Args>) => (...args: [
+        ...z.infer<Args>,
+        state: ActionState<Data, Error, z.inferFormattedError<Args>>,
+        payload: FormData
+    ]) => Promise<Flatten<InvalidState<z.inferFormattedError<Args>> | 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.
@@ -42,15 +53,15 @@ type FormActionBuilder<Schema extends ZodTypeAny | EmptyInput, Err = Error, Cont
      */
     use: <NewContext extends Record<string, unknown>>(middleware: ({ ctx }: {
         ctx: Context;
-    }) => Promise<NewContext>) => FormActionBuilder<Schema, Err, Context & NewContext>;
+    }) => Promise<NewContext>) => FormActionBuilder<Schema, Err, Context & NewContext, Args>;
     /**
      * A chainable error handler to handle errors thrown while running the action passed to .run().
      * It does not receive errors thrown from the context/middleware.
      * @param processError A function which receives action's errors.
      * @returns FormActionBuilder
      */
-    error: <Err>(processError: ErrorHandler<Context, Err>) => FormActionBuilder<Schema, Err, Context>;
+    error: <Err>(processError: ErrorHandler<Context, Err>) => FormActionBuilder<Schema, Err, Context, Args>;
 };
-declare const formAction: FormActionBuilder<typeof emptyInput, Error, InitialContext>;
+declare const formAction: FormActionBuilder<typeof emptyInput, Error, InitialContext, z.ZodTuple<[], null>>;
 
 export { ActionState, FailureState, InvalidState, SuccessState, formAction };

package/dist/index.mjs

@@ -1 +1 @@
-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};
+import{a as w,b as y}from"./chunk-LPB4R2UB.mjs";import{z as S,ZodFirstPartyTypeKind as h}from"zod";import{zfd as C}from"zod-form-data";var x=Symbol();function c(e,s=[],o,a){async function A(t){let r={formData:t};for(let d of s){let i=await d({ctx:r});r={...r,...i}}return r}return{args(t){return c(e,s,o,S.tuple(t))},input(t){if(e===x)return c(t,s,o,a);if(e._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(e._def.typeName===h.ZodObject){let r=e.merge(t);return c(r,s)}else throw Error("Merging inputs works only for object schemas without effects.")},use(t){return c(e,[...s,t],o,a)},error(t){return c(e,s,t,a)},run:e===x?t=>y(({success:r,failure:d,invalid:i},...u)=>async(l,E)=>{let m=await A(E);if(a){let n=a.safeParse(u);if(!n.success)return i(n.error.format())}try{return r(await t({args:u,ctx:m}))}catch(n){if(o)return d(await o({error:n,ctx:m}));throw n}}):e===x?void 0:t=>y(({success:r,failure:d,invalid:i},...u)=>{let l=C.formData(e);return async(E,m)=>{let n=await A(m);if(a){let f=a.safeParse(u);if(!f.success)return i(f.error.format())}let p=l.safeParse(m);if(!p.success)return i(p.error.format());let g=p.data;try{return r(await t({args:u,input:g,ctx:n}))}catch(f){if(o)return d(await o({error:f,ctx:n}));throw f}}})}}var k=c(x);export{y as createFormAction,k as formAction,w as initial};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-form-action",
-  "version": "2.4.2",
+  "version": "2.5.1",
   "description": "State management helpers for the react form actions.",
   "repository": {
     "type": "git",
@@ -17,7 +17,8 @@
     "typecheck": "vitest --typecheck",
     "format": "prettier . --write",
     "format:check": "prettier . --check",
-    "ncu": "ncu --interactive --format group"
+    "ncu": "ncu --interactive --format group",
+    "pub:next": "npm publish --tag next"
   },
   "exports": {
     ".": {