react-form-action 1.2.2 → 1.3.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
 
 ```
@@ -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,14 +1,30 @@
-import * as React from 'react';
-import React__default, { FormHTMLAttributes } from 'react';
+import * as react from 'react';
+import react__default, { PropsWithChildren, FormHTMLAttributes } from 'react';
+import { c as FormAction, F as FormState, b as InitialState, I as InvalidState, a as FailureState, S as SuccessState } from './createFormAction-252fadef.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>>;
     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> = {
@@ -21,9 +37,24 @@ type FormMetaState<T extends FormState<unknown, unknown, unknown>> = T & FormSta
     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<FormState<unknown, unknown, unknown>> | null>;
+/**
+ * A hook to consume the form action state from the context.
+ */
+declare const useFormContext: () => FormMetaState<FormState<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 p from"react";import{useActionState as E}from"react";import{useFormStatus as c}from"react-dom";function s({children:t}){return t(c())}function F(t){return{type:"initial",data:t,error:null,validationError:null}}var i={isInitial:!1,isInvalid:!1,isFailure:!1,isSuccess:!1};function T({children:t,action:a,initialData:n,permalink:e,...o}){let[r,m]=E(a,F(n),e),d=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 p.createElement("form",{action:m,...o},p.createElement(s,null,({pending:u})=>t({...d,isPending:u})))}import l from"react";var f=".",S=Object.freeze({_errors:Object.freeze([])});function g({errors:t,name:a="",children:n=({errors:e})=>l.createElement(l.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]??S}return n({errors:o._errors})}export{T as Form,s as FormStatus,g as ZodFieldError,F 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 d({children:r,action:e,initialData:n,permalink:t,autoReset:o=!1,...m}){let[a,l,i]=D(e,k(n),t),[,E]=P(),S=a.type==="initial"?{...a,...s,isPending:i,isInitial:!0}:a.type==="invalid"?{...a,...s,isPending:i,isInvalid:!0}:a.type==="failure"?{...a,...s,isPending:i,isFailure:!0}:{...a,...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 h,use as T}from"react";var p=h(null),c=()=>{let r=T(p);if(!r)throw new Error("Form Context must be initialized before use.");return r};function z(r){return{Form:({children:n,...t})=>F.createElement(d,{action:r,...t},o=>F.createElement(p,{value:o},n))}}import{useFormStatus as g}from"react-dom";function W({children:r}){return r(g())}function $({children:r}){let{isPending:e}=c();return e&&r}import f from"react";var v=".",w=Object.freeze({_errors:Object.freeze([])});function G({errors:r,name:e="",children:n=({errors:t})=>f.createElement(f.Fragment,null,t[0])}){if(e.length===0)return n({errors:r._errors});let t=e.split(v),o=r;for(;t.length;){let m=t.shift();o=o[m]??w}return n({errors:o._errors})}export{d as Form,p as FormContext,W as FormStatus,$ as Pending,G as ZodFieldError,z as createForm,k as initial,c as useFormContext};

package/dist/{createFormAction-3a51310f.d.ts → createFormAction-252fadef.d.ts}

@@ -23,10 +23,11 @@ type SuccessState<T> = {
     validationError: null;
 };
 type FormState<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: FormState<Data, Error, ValidationError>, payload: Payload) => Promise<FormState<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: FormState<Data, Error, ValidationError>, payload: Payload) => Promise<FormState<Data, Error, ValidationError>>;
 
-export { FormState as F, InvalidState as I, SuccessState as S, FailureState as a, InitialState as b, createFormAction as c };
+export { FormState as F, InvalidState as I, SuccessState as S, FailureState as a, InitialState as b, FormAction as c, createFormAction as d };

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 { F as FormState, I as InvalidState, a as FailureState, S as SuccessState } from './createFormAction-252fadef.js';
+export { c as FormAction, b as InitialState, d as createFormAction } from './createFormAction-252fadef.js';
 import { ZodTypeAny, ZodType, ZodObject, ZodRawShape, objectUtil, z, ZodSchema, ZodEffects } from 'zod';
 
 declare const emptyInput: unique symbol;

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,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=>y(({success:r,failure:i,invalid:u})=>{let m=w.formData(e);return async(x,c)=>{let f=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: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.2",
+  "version": "1.3.0",
   "description": "State management helpers for the react form actions.",
   "repository": {
     "type": "git",