react-form-action 1.2.3 → 1.4.0

package/README.md

@@ -19,6 +19,11 @@ End-to-end typesafe success, error & validation state control for Next.js 14 for
 - ✅ `<Form />` component reads the action's response.
 - ✅ Computes progress meta-state like `isInvalid`, `isSuccess` and more.
 
+**Context**
+
+- ✅ Access the action state via `useFormContext()` hook.
+- ✅ Keeps JSX markup free of render-props.
+
 ## Install
 
 ```
@@ -50,7 +55,7 @@ const i18nMiddleware = async () => {
 const authAction = formAction
   .use(i18nMiddleware)
   .use(async ({ ctx: { t } }) =>
-    console.log("🎉 context enhanced by previous middlewares 🎉", t),
+    console.log("🎉 context enhanced by previous middlewares 🎉", t)
   )
   .error(({ error }) => {
     if (error instanceof DbError) {
@@ -85,7 +90,7 @@ export const signUp = authAction
       .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!
@@ -161,7 +166,7 @@ export const updateUser = createFormAction<
 
       return failure({ message: "Failed to update user." });
     }
-  },
+  }
 );
 ```
 
@@ -206,6 +211,50 @@ export function UpdateUserForm() {
 }
 ```
 
+### Context Form
+
+```tsx
+// Example route: /app/auth/signup/SignUpForm.tsx
+"use client";
+
+import { createForm, Pending, useFormContext } from "react-form-action/client";
+import { signupAction } from "./actions";
+
+// This call will succeed only in client component
+const { Form } = createForm(signupAction);
+
+function Error() {
+  // read any state from the FormContext:
+  const {
+    error,
+    data,
+    validationError,
+    isPending,
+    isFailure,
+    isInvalid,
+    isSuccess,
+    isInitial
+  } = useFormContext();
+
+  return isFailure && "Failed to submit". // use the error somehow
+}
+
+// render this form on your RSC page (/app/auth/signup/page.tsx)
+export function SignupForm() {
+  // This Form does not use render props.
+  return (
+    <Form>
+      <input name="email" />
+      <input name="password" />
+      <Pending>
+        {/* This renders only when the action is pending. */}
+        <p>Please wait...</p>
+      </Pending>
+    </Form>
+  );
+}
+```
+
 ### `<ZodFieldError>` Component
 
 Actions created with `formAction` builder will have the `validationError` of [`ZodFormattedError`](https://zod.dev/ERROR_HANDLING?id=formatting-errors) type.

package/dist/client.d.mts

@@ -1,29 +1,60 @@
-import * as React from 'react';
-import React__default, { FormHTMLAttributes } from 'react';
+import * as react from 'react';
+import react__default, { PropsWithChildren, FormHTMLAttributes } from 'react';
+import { b as FormAction, A as ActionState, a as InitialState, I as InvalidState, F as FailureState, S as SuccessState } from './createFormAction-4e719362.js';
 import { RenderProp } from 'react-render-prop-type';
-import { F as FormState, b as InitialState, I as InvalidState, a as FailureState, S as SuccessState } from './createFormAction-3a51310f.js';
 import { useFormStatus } from 'react-dom';
 import { ZodFormattedError } from 'zod';
 
+/**
+ * Creates a Form component which state is accessible via context - useFormContext() hook.
+ */
+declare function createForm<Data, Error = Data, ValidationError = Record<string, never>>(action: FormAction<Data, Error, ValidationError>): {
+    Form: ({ children, ...props }: PropsWithChildren<{
+        initialData: Data;
+    }>) => react__default.JSX.Element;
+};
+
 type FormStateProps<Data, Error, ValidationError, Payload> = {
-    action: (state: FormState<Data, Error, ValidationError>, payload: Payload) => Promise<FormState<Data, Error, ValidationError>>;
+    action: (state: ActionState<Data, Error, ValidationError>, payload: Payload) => Promise<ActionState<Data, Error, ValidationError>>;
     initialData: Data;
     permalink?: string;
+    /**
+     * Opt-in into automatic form reset by using the form "action" prop.
+     * By default, the onSubmit with a custom transition which opts-out of the implicit form reset.
+     * See for more. https://github.com/facebook/react/issues/29034
+     * @default false
+     */
+    autoReset?: boolean;
 };
 declare function initial<Data>(data: Data): InitialState<Data>;
-type FormStatusFlags<T extends FormState<unknown, unknown, unknown>["type"] | unknown = unknown> = {
+type FormStatusFlags<T extends ActionState<unknown, unknown, unknown>["type"] | unknown = unknown> = {
     isInitial: T extends "initial" ? true : false;
     isInvalid: T extends "invalid" ? true : false;
     isFailure: T extends "failure" ? true : false;
     isSuccess: T extends "success" ? true : false;
 };
-type FormMetaState<T extends FormState<unknown, unknown, unknown>> = T & FormStatusFlags<T["type"]> & {
+type FormMetaState<T extends ActionState<unknown, unknown, unknown>> = T & FormStatusFlags<T["type"]> & {
     isPending: boolean;
 };
 type FormProps<Data, Error, ValidationError> = Omit<FormHTMLAttributes<HTMLFormElement>, "action" | "children"> & FormStateProps<Data, Error, ValidationError, FormData> & RenderProp<FormMetaState<InitialState<Data>> | FormMetaState<InvalidState<ValidationError>> | FormMetaState<FailureState<Error>> | FormMetaState<SuccessState<Data>>>;
-declare function Form<Data, Error, ValidationError>({ children, action, initialData, permalink, ...props }: FormProps<Data, Error, ValidationError>): React__default.JSX.Element;
+declare function Form<Data, Error, ValidationError>({ children, action, initialData, permalink, autoReset, ...props }: FormProps<Data, Error, ValidationError>): react__default.JSX.Element;
+
+/**
+ * A context exposing the form action state.
+ * @private You don't need to use this component directly. Use the `createForm` function instead.
+ */
+declare const FormContext: react.Context<FormMetaState<ActionState<unknown, unknown, unknown>> | null>;
+/**
+ * A hook to consume the form action state from the context.
+ */
+declare const useFormContext: () => FormMetaState<ActionState<unknown, unknown, unknown>>;
+
+declare function FormStatus({ children, }: RenderProp<ReturnType<typeof useFormStatus>>): react.ReactNode;
 
-declare function FormStatus({ children, }: RenderProp<ReturnType<typeof useFormStatus>>): React.ReactNode;
+/**
+ * Conditionally renders the children, when the form action is in the "pending" state.
+ */
+declare function Pending({ children }: PropsWithChildren): react.ReactNode;
 
 declare const SEPARATOR: ".";
 type Paths<Err> = {
@@ -36,6 +67,6 @@ type ZodFieldErrorProps<Errors extends ZodFormattedError<any>> = {
 } & Partial<RenderProp<{
     errors: readonly string[];
 }>>;
-declare function ZodFieldError<Errors extends ZodFormattedError<any>>({ errors, name, children, }: ZodFieldErrorProps<Errors>): React__default.ReactNode;
+declare function ZodFieldError<Errors extends ZodFormattedError<any>>({ errors, name, children, }: ZodFieldErrorProps<Errors>): react__default.ReactNode;
 
-export { Form, FormProps, FormStateProps, FormStatus, InferZodErrorPaths, Paths, ZodFieldError, ZodFieldErrorProps, initial };
+export { Form, FormContext, FormMetaState, FormProps, FormStateProps, FormStatus, InferZodErrorPaths, Paths, Pending, ZodFieldError, ZodFieldErrorProps, createForm, initial, useFormContext };

package/dist/client.mjs

@@ -1 +1 @@
-"use client";import d from"react";import{useActionState as u}from"react";function c(t){return{type:"initial",data:t,error:null,validationError:null}}var i={isInitial:!1,isInvalid:!1,isFailure:!1,isSuccess:!1};function P({children:t,action:a,initialData:n,permalink:e,...o}){let[r,l,p]=u(a,c(n),e),m=r.type==="initial"?{...r,...i,isInitial:!0}:r.type==="invalid"?{...r,...i,isInvalid:!0}:r.type==="failure"?{...r,...i,isFailure:!0}:{...r,...i,isSuccess:!0};return d.createElement("form",{action:l,...o},t({...m,isPending:p}))}import{useFormStatus as E}from"react-dom";function D({children:t}){return t(E())}import s from"react";var f=".",F=Object.freeze({_errors:Object.freeze([])});function v({errors:t,name:a="",children:n=({errors:e})=>s.createElement(s.Fragment,null,e[0])}){if(a.length===0)return n({errors:t._errors});let e=a.split(f),o=t;for(;e.length;){let r=e.shift();o=o[r]??F}return n({errors:o._errors})}export{P as Form,D as FormStatus,v as ZodFieldError,c as initial};
+"use client";import f from"react";import x,{useTransition as P}from"react";import{useActionState as D}from"react";function k(r){return{type:"initial",data:r,error:null,validationError:null}}var s={isInitial:!1,isInvalid:!1,isFailure:!1,isSuccess:!1};function c({children:r,action:e,initialData:a,permalink:t,autoReset:o=!1,...m}){let[n,l,i]=D(e,k(a),t),[,E]=P(),S=n.type==="initial"?{...n,...s,isPending:i,isInitial:!0}:n.type==="invalid"?{...n,...s,isPending:i,isInvalid:!0}:n.type==="failure"?{...n,...s,isPending:i,isFailure:!0}:{...n,...s,isPending:i,isSuccess:!0};return x.createElement("form",{...o?{action:l}:{onSubmit:u=>{u.preventDefault();let y=u.currentTarget;E(()=>{l(new FormData(y))})}},...m},r(S))}import{createContext as A,use as h}from"react";var p=A(null),d=()=>{let r=h(p);if(!r)throw new Error("Form Context must be initialized before use.");return r};function z(r){return{Form:({children:a,...t})=>f.createElement(c,{action:r,...t},o=>f.createElement(p,{value:o},a))}}import{useFormStatus as T}from"react-dom";function W({children:r}){return r(T())}function $({children:r}){let{isPending:e}=d();return e&&r}import F from"react";var g=".",v=Object.freeze({_errors:Object.freeze([])});function G({errors:r,name:e="",children:a=({errors:t})=>F.createElement(F.Fragment,null,t[0])}){if(e.length===0)return a({errors:r._errors});let t=e.split(g),o=r;for(;t.length;){let m=t.shift();o=o[m]??v}return a({errors:o._errors})}export{c as Form,p as FormContext,W as FormStatus,$ as Pending,G as ZodFieldError,z as createForm,k as initial,d as useFormContext};

package/dist/{createFormAction-3a51310f.d.ts → createFormAction-4e719362.d.ts}

@@ -22,11 +22,12 @@ type SuccessState<T> = {
     error: null;
     validationError: null;
 };
-type FormState<Data, Error, ValidationError = Record<string, never>> = InitialState<Data> | InvalidState<ValidationError> | FailureState<Error> | SuccessState<Data>;
+type ActionState<Data, Error, ValidationError = Record<string, never>> = InitialState<Data> | InvalidState<ValidationError> | FailureState<Error> | SuccessState<Data>;
+type FormAction<Data, Error = Data, ValidationError = Record<string, never>, Payload = FormData> = (state: ActionState<Data, Error, ValidationError>, payload: Payload) => Promise<ActionState<Data, Error, ValidationError>>;
 declare function createFormAction<Data, Error = Data, ValidationError = Record<string, never>, Payload = FormData>(formAction: (params: {
     success: (data: Data) => SuccessState<Data>;
     failure: (error: Error) => FailureState<Error>;
     invalid: (validationError: ValidationError) => InvalidState<ValidationError>;
-}) => (state: FormState<Data, Error, ValidationError>, payload: Payload) => Promise<FormState<Data, Error, ValidationError>>): (state: FormState<Data, Error, ValidationError>, payload: Payload) => Promise<FormState<Data, Error, ValidationError>>;
+}) => FormAction<Data, Error, ValidationError, Payload>): (state: ActionState<Data, Error, ValidationError>, payload: Payload) => Promise<ActionState<Data, Error, ValidationError>>;
 
-export { FormState as F, InvalidState as I, SuccessState as S, FailureState as a, InitialState as b, createFormAction as c };
+export { ActionState as A, FailureState as F, InvalidState as I, SuccessState as S, InitialState as a, FormAction as b, createFormAction as c };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { F as FormState, I as InvalidState, a as FailureState, S as SuccessState } from './createFormAction-3a51310f.js';
-export { b as InitialState, c as createFormAction } from './createFormAction-3a51310f.js';
+import { A as ActionState, I as InvalidState, F as FailureState, S as SuccessState } from './createFormAction-4e719362.js';
+export { b as FormAction, a as InitialState, c as createFormAction } from './createFormAction-4e719362.js';
 import { ZodTypeAny, ZodType, ZodObject, ZodRawShape, objectUtil, z, ZodSchema, ZodEffects } from 'zod';
 
 declare const emptyInput: unique symbol;
@@ -30,7 +30,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: FormState<Data, Err, z.inferFormattedError<Schema>>, payload: FormData) => Promise<Flatten<InvalidState<z.inferFormattedError<Schema>> | FailureState<Err> | SuccessState<Data>>> : <Data>(action: Action<Data, Context>) => (state: FormState<Data, Err>, payload: FormData) => Promise<Flatten<FailureState<Err> | SuccessState<Data>>>;
+    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>>>;
     /**
      * 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.
@@ -52,4 +52,4 @@ type FormActionBuilder<Schema extends ZodTypeAny | EmptyInput, Err = Error, Cont
 };
 declare const formAction: FormActionBuilder<typeof emptyInput, Error, InitialContext>;
 
-export { FailureState, FormState, InvalidState, SuccessState, formAction };
+export { ActionState, FailureState, InvalidState, SuccessState, formAction };

package/dist/index.mjs

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

package/package.json

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