@paragrav/rhf-utils 0.0.143 → 0.0.145

package/README.md

@@ -2,7 +2,7 @@
 
 ## About
 
-Integration and utility library for [react-hook-form](https://www.react-hook-form.com/) and [zod](https://www.npmjs.com/package/zod). Declaratively configure your forms via global and form-level options.
+Integration and utility library for [react-hook-form](https://www.react-hook-form.com/) (and [zod](https://www.npmjs.com/package/zod)). Declaratively configure your forms via global and form-level options.
 
 ## Features
 
@@ -69,7 +69,7 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
   // optional form component (defaults to primitive HTML form)
   FormComponent: Form.Root,
 
-  // optional wrapper to inject your own hooks and components
+  // optional wrapper component to inject your own hooks and components
   // around all RhfUtilsZodForm instances
   FormChildrenWrapper: (
     // UseRhfUtilsFormChildrenProps
@@ -93,7 +93,7 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
 
     return (
       <>
-        {/* RhfUtilsZodForm.Children outlet (see "Component Hierarchy" section) */}
+        {/* RhfUtilsZodForm.Children "outlet" (see "Component Hierarchy" section) */}
         {children}
 
         {/* root errors list */}
@@ -103,7 +103,7 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
   },
 
   // non-FormSubmitError thrown in onSubmit
-  // use case: handle and transform error data for frontend
+  // use case: handle and transform server error data for frontend
   onSubmitErrorUnknown: (
     error, // unknown
   ) => {
@@ -166,7 +166,7 @@ Currently, only `zod` is supported.
   // handle error declaratively (i.e., no throw/catch)
   onSubmitError={({
     error, //   unknown
-    context, // UseRhfUtilsFormOnSubmitErrorContext (id, ref, rhf context, utils options)
+    context, // UseRhfUtilsFormOnSubmitErrorContext (id, ref, rhf context, utils options, `FormSubmitFieldErrors` from `onSubmitErrorUnknown`)
     event, //   SubmitEvent
   }) => {
     props.onError(error);
@@ -227,12 +227,14 @@ function Children({...}: RhfUtilsUseFormChildrenZodProps<typeof schema>) { }
 
 ## Form Component Hierarchy
 
+`RhfUtilsZodForm` renders as:
+
 ```tsx
-<ReactHookForm.FormProvider>
-  <RhfUtilsProviders>
-    <RhfUtilsClientConfig.FormComponent>
-      <RhfUtilsClientConfig.FormChildrenWrapper>
-        <RhfUtilsZodForm.Children />
+<ReactHookForm.FormProvider> // standard rhf provider
+  <RhfUtilsProviders> // rhf utils internal providers
+    <RhfUtilsClientConfig.FormComponent> // from global config (or default)
+      <RhfUtilsClientConfig.FormChildrenWrapper> // from global config (if provided)
+        <RhfUtilsZodForm.Children /> // form instance component prop
       </RhfUtilsClientConfig.FormChildrenWrapper>
     </RhfUtilsClientConfig.FormComponent>
   <RhfUtilsProviders>
@@ -266,7 +268,7 @@ Most common use case will be transforming backend errors to frontend shape.
 
 ## `RhfUtilsFormOptions`
 
-These options can be set globally and/or per form.
+These built-in options can be set globally and/or per form.
 
 ```ts
 type RhfUtilsFormOptions = {
@@ -301,7 +303,7 @@ Use `useRhfUtilsContextRequestSubmit` hook to get `requestSubmit` function for c
 
 ## Extend `RhfUtilsFormOptions`
 
-Extend `RhfUtilsFormOptions` with custom options, which get passed to `Children` component in `options` prop. These can take any shape, and allow you to override your own functionality at form-level.
+Extend `RhfUtilsFormOptions` with custom options, which get passed to `RhfUtilsClientConfig`'s `ChildrenWrapper` and `RhfUtilsZodForm`'s `Children` components via `options` prop. These can take any shape, and allow you to override your own functionality at form-level.
 
 ```tsx
 import '@paragrav/rhf-utils';
@@ -309,8 +311,9 @@ import '@paragrav/rhf-utils';
 declare module '@paragrav/rhf-utils' {
   export interface Register {
     RhfUtilsFormOptions: {
-      /** Enable user prompt to confirm navigating away from dirty form. */
+      /** Custom props for your custom hooks/behaviors. */
       enableMyOptionalFormHook?: boolean;
+      configMyOptionalFormHook?: MyCustomFormHookConfig;
     };
   }
 }

package/dist/esm/index.mjs

@@ -1,6 +1,6 @@
 import { jsx as i, Fragment as B, jsxs as Z } from "react/jsx-runtime";
 import a from "react";
-import { c as E } from "./createContext.mjs";
+import { c as C } from "./createContext.mjs";
 import { zodResolver as I } from "@hookform/resolvers/zod";
 import { useFormContext as b, Controller as L, get as z, useFormState as x, FormProvider as A, useForm as $ } from "react-hook-form";
 import { i as O, _ as H, u as g } from "./useFlatFieldErrorsContext.mjs";
@@ -8,7 +8,7 @@ import { flatten as Q } from "flat";
 const {
   Provider: G,
   useMaybe: _
-} = E(), J = a.lazy(
+} = C(), J = a.lazy(
   () => import("@hookform/devtools").then((r) => ({
     default: r.DevTool
   }))
@@ -51,11 +51,11 @@ function er({
   const m = b(), d = _(), c = async (h) => {
     u != null && u.stopSubmitPropagation && h.stopPropagation();
     try {
-      await m.handleSubmit(v, s)(h);
+      await m.handleSubmit(p, s)(h);
     } catch (f) {
-      p(f, h);
+      P(f, h);
     }
-  }, v = (h, f) => e == null ? void 0 : e(
+  }, p = (h, f) => e == null ? void 0 : e(
     h,
     {
       formId: r,
@@ -65,33 +65,34 @@ function er({
       FormSubmitError: F
     },
     f
-  ), p = (h, f) => {
+  ), P = (h, f) => {
     var y;
-    const R = h instanceof F ? (
+    const E = h instanceof F ? (
       // consumer can manually throw FormSubmitError (e.g., manual validation)
       h.errors
     ) : (
       // if error is not FormSubmitError, consumer can provide global handler
       (y = d == null ? void 0 : d.onSubmitErrorUnknown) == null ? void 0 : y.call(d, h)
     );
-    R && X(m, R), o == null || o(
+    E && X(m, E), o == null || o(
       h,
       {
         formId: r,
         formRef: t,
         context: m,
-        utils: u
+        utils: u,
+        errors: E
       },
       f
     );
-  }, P = {
+  }, R = {
     formId: r,
     formRef: t,
     context: m,
     utils: u,
     Controller: rr,
     FormSubmitError: F
-  }, V = P, N = (d == null ? void 0 : d.FormComponent) ?? "form", q = (d == null ? void 0 : d.FormChildrenWrapper) ?? Y;
+  }, V = R, N = (d == null ? void 0 : d.FormComponent) ?? "form", q = (d == null ? void 0 : d.FormChildrenWrapper) ?? Y;
   return /* @__PURE__ */ i(
     N,
     {
@@ -106,18 +107,18 @@ function er({
             props: typeof (u == null ? void 0 : u.devTool) == "object" ? u.devTool : void 0
           }
         ),
-        /* @__PURE__ */ i(n, { ...P })
+        /* @__PURE__ */ i(n, { ...R })
       ] })
     }
   );
 }
-const C = (r) => (t) => (
+const v = (r) => (t) => (
   // re-create object from entries
   Object.fromEntries(
     // break down to entries
     Object.entries(t).filter(r)
   )
-), k = (r) => !!r.ref, tr = ([, r]) => k(r), or = C(
+), k = (r) => !!r.ref, tr = ([, r]) => k(r), or = v(
   tr
 ), W = "data-rhfutils-nonfield-error-marker-path", sr = (r, t) => (
   // list of selector variants
@@ -144,9 +145,9 @@ const C = (r) => (t) => (
   !k(t) && // non-root
   !j(r) && // not marked in DOM
   !ur(r, e)
-), ir = (r) => ([t, e]) => lr(t, e, r), dr = (r, t) => C(
+), ir = (r) => ([t, e]) => lr(t, e, r), dr = (r, t) => v(
   ir(t)
-)(r), ar = ([r]) => j(r), mr = C(
+)(r), ar = ([r]) => j(r), mr = v(
   ar
 ), hr = (r) => Q(r), cr = (r) => {
   const t = hr(r), e = Object.keys(t);
@@ -289,7 +290,7 @@ const C = (r) => (t) => (
       n.removeEventListener("change", l);
     };
   }, []);
-}, { Provider: Sr, useRequired: Ur } = E(), Zr = Ur, xr = ({
+}, { Provider: Sr, useRequired: Ur } = C(), Zr = Ur, xr = ({
   formId: r,
   formRef: t,
   options: e,
@@ -438,7 +439,7 @@ const _r = (r, ...t) => (
 }, jr = kr(I), {
   Provider: wr,
   useRequired: D
-} = E(), Ir = ({
+} = C(), Ir = ({
   config: r,
   children: t
 }) => {

package/dist/types/form/UseRhfUtilsFormOnSubmitContext.d.ts

@@ -1,6 +1,7 @@
 import { default as React } from 'react';
 import { UseFormReturn } from 'react-hook-form';
 import { FormSubmitError } from '../submit/error/FormSubmitError';
+import { FormSubmitFieldErrors } from '../submit/error/FormSubmitFieldErrors';
 import { RhfUtilsFormOptions } from './RhfUtilsFormOptions';
 import { SafeFieldValues } from './SafeFieldValues';
 /**
@@ -23,4 +24,5 @@ export type UseRhfUtilsFormOnSubmitErrorContext<TFieldValues extends SafeFieldVa
     formRef: React.RefObject<HTMLFormElement>;
     context: UseFormReturn<TFieldValues, unknown, TTransformedValues>;
     utils?: RhfUtilsFormOptions;
+    errors?: FormSubmitFieldErrors;
 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@paragrav/rhf-utils",
   "author": "paragrav.dev",
   "license": "MIT",
-  "version": "0.0.143",
+  "version": "0.0.145",
   "description": "Integration utilities for react-hook-form.",
   "type": "module",
   "sideEffects": false,