@paragrav/rhf-utils 0.0.117 → 0.0.118

package/README.md

@@ -31,49 +31,51 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
   // optional (defaults to primitive HTML form)
   FormComponent: Form.Root,
 
+  // optional wrapper to inject your own hooks and components
+  // `children` prop is provided by RhfUtilsZodForm's Children prop
+  FormChildren: (
+    // UseRhfUtilsFormChildrenProps
+    {
+      formId, //          unique id string
+      formRef, //         ref
+      context, //         rhf UseFormReturn
+      options, //         RhfUtilsFormOptions
+      Controller, //      strictly-typed controller
+      FormSubmitError, // strictly-typed error class
+      children, //        RhfUtilsZodForm.Children
+    },
+  ) => {
+    // navigation blocker (using custom option)
+    useFormRouterBlocker(!!options?.prompter);
+
+    return (
+      <>
+        {/* specific form children -- e.g., fields, etc. */}
+        {children}
+
+        {/* global error list */}
+        <RootErrorsListFromFlatFieldErrorsContext />
+      </>
+    );
+  },
+
   // non-FormSubmitError throw in onSubmit
-  // use case: transform backend error
+  // example use case: transform backend error
   onSubmitUnknownError: (
     error, // unknown
   ) => {
     // if other error, re-throw to handle in ErrorBoundary
     if (!(error instanceof MyServerError)) throw error;
 
-    // return to be merged into RHF context errors
+    // return FormSubmitErrors object to be merged into RHF context errors
     return transformServerErrorToFormSubmitErrors(error);
   },
 
-  Children: {
-    top: (
-      // UseRhfUtilsFormChildrenProps
-      {
-        formId, //          unique id string
-        formRef, //         ref
-        context, //         rhf UseFormReturn
-        options, //         RhfUtilsFormOptions
-        Controller, //      strictly-typed controller
-        FormSubmitError, // strictly-typed error class
-      },
-    ) => {
-      // navigation blocker (using custom option)
-      useFormRouterBlocker(!!options?.prompter);
-
-      return null;
-    },
-
-    bottom: () => (
-      <>
-        {/* global error list */}
-        <RootErrorsListFromFlatFieldErrorsContext />
-      </>
-    ),
-  },
-
   errors: {
     output: {
       // callback to determine when to output form context errors to console ("debug" or "error")
       console: ({ hasOrphans }) =>
-        (hasOrphans && { type: 'error' }) || // report all orphan errors
+        (hasOrphans && { type: 'error' }) || // console error for reporting on prod
         (import.meta.env.DEV && { type: 'debug' }), // facilitate debugging on dev
 
       // callback to determine when to throw an error based on context
@@ -159,9 +161,9 @@ function Children({...}: RhfUtilsUseFormChildrenZodProps<typeof schema>) { }
 
 ## `FormSubmitError`
 
-This is an `Error`-based class you can use to throw a structured error in your submit handler. It is strictly-typed, so it only allows field names in schema and `root`/`root.{string}` keys.
+This is an `Error`-based class you can use to throw a structured error in your submit handler. It is strictly-typed, so it only allows field names from your schema and `root`/`root.{string}` keys.
 
-It uses `FormSubmitErrors` shape, which is a flat (dot notation) equivalent of RHF's `FieldErrors`.
+It uses `FormSubmitErrors` type's structure, which is a flat, simplified version of RHF's `FieldErrors`.
 
 Example:
 

package/dist/esm/client/index.mjs

@@ -4,28 +4,26 @@ import d from "../form/useRhfUtilsForm.mjs";
 const R = (e) => (r) => {
   const m = F(e, r);
   return {
-    useForm: (i, s) => {
-      const t = m(i, s);
+    useForm: (o, s) => {
+      const t = m(o, s);
       return {
         ...d(t),
-        FormWithProviders: ({
-          children: o
-        }) => /* @__PURE__ */ h(f, { ...t, children: o })
+        FormWithProviders: () => /* @__PURE__ */ h(f, { ...t })
       };
     },
     FormWithProviders: a(e, r)
   };
-}, F = (e, r) => function(i, s) {
-  var t, o, l, n, u;
+}, F = (e, r) => function(o, s) {
+  var t, i, l, n, u;
   return {
     ...s,
     rhf: {
       ...(t = r.defaults) == null ? void 0 : t.rhf,
       ...s.rhf,
-      resolver: e(i)
+      resolver: e(o)
     },
     utils: {
-      ...(o = r.defaults) == null ? void 0 : o.utils,
+      ...(i = r.defaults) == null ? void 0 : i.utils,
       ...s.utils,
       classNames: [
         ...((n = (l = r.defaults) == null ? void 0 : l.utils) == null ? void 0 : n.classNames) ?? [],
@@ -34,15 +32,15 @@ const R = (e) => (r) => {
     }
   };
 }, a = (e, r) => function({
-  schema: i,
+  schema: o,
   children: s,
   ...t
 }) {
-  const o = F(e, r);
+  const i = F(e, r);
   return /* @__PURE__ */ h(
     f,
     {
-      ...o(i, t),
+      ...i(o, t),
       children: s
     }
   );

package/dist/esm/form/Form.mjs

@@ -1,98 +1,92 @@
-import { jsxs as _, jsx as d } from "react/jsx-runtime";
+import { jsx as c, jsxs as E, Fragment as N } from "react/jsx-runtime";
 import "react";
-import { useFormContext as v } from "react-hook-form";
-import N from "../client/config/useRhfUtilsClientConfigContext.mjs";
-import P from "../devtool/LazyDevTool.mjs";
-import { FormSubmitError as x } from "../submit/error/FormSubmitError.mjs";
-import S from "../submit/error/setCtxErrorsByFormSubmitErrors.mjs";
-import w from "./_Controller.mjs";
-import E from "./_FormBase.mjs";
+import { useFormContext as P } from "react-hook-form";
+import f from "../client/config/useRhfUtilsClientConfigContext.mjs";
+import w from "../devtool/LazyDevTool.mjs";
+import { FormSubmitError as C } from "../submit/error/FormSubmitError.mjs";
+import B from "../submit/error/setCtxErrorsByFormSubmitErrors.mjs";
+import S from "./_Controller.mjs";
 function A({
-  formId: s,
+  formId: e,
   formRef: m,
   //
-  onSubmit: c,
-  onSubmitError: C,
-  onSubmitInvalid: b,
+  onSubmit: s,
+  onSubmitError: d,
+  onSubmitInvalid: y,
   Children: h,
   //
   form: p,
-  utils: o,
-  //
-  children: i
+  utils: o
 }) {
-  const n = v(), r = N(), j = async (t) => {
+  const n = P(), r = f(), i = async (t) => {
     o != null && o.stopSubmitPropagation && t.stopPropagation();
     try {
-      await n.handleSubmit(B, b)(t);
-    } catch (e) {
-      T(e, t);
+      await n.handleSubmit(b, y)(t);
+    } catch (a) {
+      j(a, t);
     }
-  }, B = (t, e) => c == null ? void 0 : c(
+  }, b = (t, a) => s == null ? void 0 : s(
     t,
     {
-      formId: s,
+      formId: e,
       formRef: m,
       context: n,
       utils: o,
-      FormSubmitError: x
+      FormSubmitError: C
     },
-    e
-  ), T = (t, e) => {
-    var F;
-    const a = t instanceof x ? (
+    a
+  ), j = (t, a) => {
+    var l;
+    const F = t instanceof C ? (
       // consumer can manually throw FormSubmitError (e.g., manual validation)
       t.errors
     ) : (
       // if error is not FormSubmitError, consumer can provide global handler
-      (F = r == null ? void 0 : r.onSubmitUnknownError) == null ? void 0 : F.call(r, t)
+      (l = r == null ? void 0 : r.onSubmitUnknownError) == null ? void 0 : l.call(r, t)
     );
-    a && S(n, a), C == null || C(
+    F && B(n, F), d == null || d(
       t,
       {
-        formId: s,
+        formId: e,
         formRef: m,
         context: n,
         utils: o
       },
-      e
+      a
     );
-  }, l = {
-    formId: s,
+  }, x = {
+    formId: e,
     formRef: m,
     context: n,
     utils: o,
-    Controller: w,
-    FormSubmitError: x
-  }, y = (t) => {
-    var a;
-    const e = (a = r == null ? void 0 : r.Children) == null ? void 0 : a[t];
-    return e && /* @__PURE__ */ d(e, { ...l });
-  };
-  return /* @__PURE__ */ _(
-    E,
+    Controller: S,
+    FormSubmitError: C
+  }, T = (r == null ? void 0 : r.FormComponent) ?? "form", v = (r == null ? void 0 : r.FormChildren) ?? U;
+  return /* @__PURE__ */ c(
+    T,
     {
       noValidate: !0,
-      Component: r == null ? void 0 : r.FormComponent,
-      formRef: m,
+      ref: m,
       ...p,
       className: [o == null ? void 0 : o.classNames, p == null ? void 0 : p.className].filter(Boolean).join(" "),
-      onSubmit: j,
-      children: [
-        y("top"),
-        (o == null ? void 0 : o.devTool) && /* @__PURE__ */ d(
-          P,
+      onSubmit: i,
+      children: /* @__PURE__ */ E(v, { ...x, children: [
+        (o == null ? void 0 : o.devTool) && /* @__PURE__ */ c(
+          w,
           {
             props: typeof o.devTool == "object" ? o.devTool : void 0
           }
         ),
-        h && /* @__PURE__ */ d(h, { ...l }),
-        i,
-        y("bottom")
-      ]
+        h && /* @__PURE__ */ c(h, { ...x })
+      ] })
     }
   );
 }
+function U({
+  children: e
+}) {
+  return /* @__PURE__ */ c(N, { children: e });
+}
 export {
   A as default
 };

package/dist/esm/form/FormWithProviders.mjs

@@ -1,14 +1,11 @@
 import { jsx as o } from "react/jsx-runtime";
-import t from "./Form.mjs";
-import f from "./RhfUtilsFormProviders.mjs";
-import s from "./useRhfUtilsForm.mjs";
-function h({
-  children: m,
-  ...i
-}) {
-  const r = s(i);
-  return /* @__PURE__ */ o(f, { ...r.providerProps, children: /* @__PURE__ */ o(t, { ...r.formProps, children: m }) });
+import i from "./Form.mjs";
+import t from "./RhfUtilsFormProviders.mjs";
+import f from "./useRhfUtilsForm.mjs";
+function n(m) {
+  const r = f(m);
+  return /* @__PURE__ */ o(t, { ...r.providerProps, children: /* @__PURE__ */ o(i, { ...r.formProps }) });
 }
 export {
-  h as default
+  n as default
 };

package/dist/types/client/config/RhfUtilsClientConfig.d.ts

@@ -1,7 +1,7 @@
 import { UseFormProps } from 'react-hook-form';
 import { FlatFieldErrorsOutputConfig } from '../../errors/flat/context/FlatFieldErrorsOutputConfig';
-import { FormChildrenSlots } from '../../form/Form';
 import { RhfUtilsFormOptions } from '../../form/RhfUtilsFormOptions';
+import { SafeFieldValues } from '../../form/SafeFieldValues';
 import { UseRhfUtilsFormChildrenProps } from '../../form/UseRhfUtilsFormChildrenProps';
 import { FormSubmitErrors } from '../../submit/error/FormSubmitErrors';
 
@@ -34,6 +34,14 @@ export type RhfUtilsClientConfig = {
      * By default, a primitive `<form>` element is used.
      */
     FormComponent?: React.FC<React.PropsWithChildren<React.HTMLAttributes<HTMLFormElement>>>;
+    /**
+     * Wrap all form bodies with your own hooks, components, etc.
+     *
+     * Use cases:
+     * - custom hooks/behaviors based on `options`
+     * - shared header, footer
+     */
+    FormChildren?: <TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>(props: React.PropsWithChildren<UseRhfUtilsFormChildrenProps<TFieldValues, TTransformedValues>>) => React.ReactNode;
     /**
      * Global submit error handler when/if submit handler throws an error other than {@link FormSubmitError}.
      *
@@ -45,14 +53,6 @@ export type RhfUtilsClientConfig = {
      * - if `undefined`: do nothing.
      */
     onSubmitUnknownError?: (error: unknown) => FormSubmitErrors | undefined;
-    /**
-     * Components injected by slot across all forms.
-     * (Per-form injection can be done via `Children` prop.)
-     *
-     * - `top`: e.g., block navigation on dirty form.
-     * - `bottom`: e.g., root errors list.
-     */
-    Children?: Partial<Record<FormChildrenSlots, React.FC<UseRhfUtilsFormChildrenProps>>>;
     errors?: {
         /**
          * Configure how/if errors should be outputted.

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

@@ -3,9 +3,9 @@ import { SafeFieldValues } from './SafeFieldValues';
 import { UseRhfUtilsFormProps } from './UseRhfUtilsFormProps';
 
 export type FormChildrenSlots = 'top' | 'bottom';
-export type FormProps<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues> = React.PropsWithChildren<{
+export type FormProps<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues> = {
     formId: string;
     formRef: React.RefObject<HTMLFormElement>;
-} & Pick<UseRhfUtilsFormProps<TFieldValues, TTransformedValues>, 'onSubmit' | 'onSubmitError' | 'onSubmitInvalid' | 'Children' | 'form' | 'utils'>>;
-declare function _Form<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>({ formId, formRef, onSubmit, onSubmitError, onSubmitInvalid, Children, form, utils, children, }: FormProps<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
+} & Pick<UseRhfUtilsFormProps<TFieldValues, TTransformedValues>, 'onSubmit' | 'onSubmitError' | 'onSubmitInvalid' | 'Children' | 'form' | 'utils'>;
+declare function _Form<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>({ formId, formRef, onSubmit, onSubmitError, onSubmitInvalid, Children, form, utils, }: FormProps<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
 export default _Form;

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

@@ -9,5 +9,5 @@ export type FormWithProvidersProps<TFieldValues extends SafeFieldValues, TTransf
  * Use {@link useRhfUtilsForm} if you need to specific nesting hierarchy.
  * (e.g., wrapping `<tr>` with provider and nesting `<form>` within `<td>` to appease HTML rules.)
  */
-declare function FormWithProviders<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>({ children, ...props }: FormWithProvidersProps<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
+declare function FormWithProviders<TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>(props: FormWithProvidersProps<TFieldValues, TTransformedValues>): import("react/jsx-runtime").JSX.Element;
 export default FormWithProviders;

package/package.json

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

package/dist/esm/form/_FormBase.mjs

@@ -1,11 +0,0 @@
-import { jsx as m } from "react/jsx-runtime";
-import "react";
-const s = ({
-  formRef: o,
-  Component: r,
-  children: t,
-  ...e
-}) => /* @__PURE__ */ m(r ?? "form", { role: "form", ...e, ref: o, children: t });
-export {
-  s as default
-};