@paragrav/rhf-utils 0.0.117 → 0.0.119

package/README.md

@@ -16,7 +16,7 @@ To configure, create a file `config.tsx` with desired configuration settings. Th
 export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
   // defaults -- overridable per form instance
   defaults: {
-    // globally relevant subset of RHF's `UseFormProps` options
+    // globally-relevant subset of RHF's `UseFormProps` options
     rhf: {
       mode: 'onBlur',
     },
@@ -26,54 +26,62 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
       // enable dev tool on dev env
       devTool: import.meta.env.DEV,
     },
+
+    // default form props
+    form: {
+      noValidate: true,
+      className: 'my-form-class',
+    },
   },
 
   // 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 +167,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:
 
@@ -189,11 +197,6 @@ These options can be set globally and/or per form.
 
 ```ts
 type RhfUtilsFormOptions = {
-  /**
-   * Style via your own classes.
-   */
-  classNames?: string[];
-
   /** Request submit via listener on form change. */
   submitOnChange?: boolean;
 

package/dist/esm/client/index.mjs

@@ -1,52 +1,51 @@
-import { jsx as h } from "react/jsx-runtime";
-import f from "../form/FormWithProviders.mjs";
-import d from "../form/useRhfUtilsForm.mjs";
-const R = (e) => (r) => {
-  const m = F(e, r);
+import { jsx as u } from "react/jsx-runtime";
+import a from "../form/FormWithProviders.mjs";
+import F from "../form/useRhfUtilsForm.mjs";
+const v = (e) => (r) => {
+  const m = d(e, r);
   return {
-    useForm: (i, s) => {
-      const t = m(i, s);
+    useForm: (s, t) => {
+      const o = m(s, t);
       return {
-        ...d(t),
-        FormWithProviders: ({
-          children: o
-        }) => /* @__PURE__ */ h(f, { ...t, children: o })
+        ...F(o),
+        FormWithProviders: () => /* @__PURE__ */ u(a, { ...o })
       };
     },
-    FormWithProviders: a(e, r)
+    FormWithProviders: P(e, r)
   };
-}, F = (e, r) => function(i, s) {
-  var t, o, l, n, u;
+}, d = (e, r) => function(s, t) {
+  var o, i, f, l, n, h;
   return {
-    ...s,
+    ...t,
     rhf: {
-      ...(t = r.defaults) == null ? void 0 : t.rhf,
-      ...s.rhf,
-      resolver: e(i)
+      ...(o = r.defaults) == null ? void 0 : o.rhf,
+      ...t.rhf,
+      resolver: e(s)
     },
     utils: {
-      ...(o = r.defaults) == null ? void 0 : o.utils,
-      ...s.utils,
-      classNames: [
-        ...((n = (l = r.defaults) == null ? void 0 : l.utils) == null ? void 0 : n.classNames) ?? [],
-        ...((u = s.utils) == null ? void 0 : u.classNames) ?? []
-      ]
+      ...(i = r.defaults) == null ? void 0 : i.utils,
+      ...t.utils
+    },
+    form: {
+      ...(f = r.defaults) == null ? void 0 : f.form,
+      ...t.form,
+      className: [(n = (l = r.defaults) == null ? void 0 : l.form) == null ? void 0 : n.className, (h = t.form) == null ? void 0 : h.className].filter(Boolean).join(" ")
     }
   };
-}, a = (e, r) => function({
-  schema: i,
-  children: s,
-  ...t
+}, P = (e, r) => function({
+  schema: s,
+  children: t,
+  ...o
 }) {
-  const o = F(e, r);
-  return /* @__PURE__ */ h(
-    f,
+  const i = d(e, r);
+  return /* @__PURE__ */ u(
+    a,
     {
-      ...o(i, t),
-      children: s
+      ...i(s, o),
+      children: t
     }
   );
 };
 export {
-  R as createRhfUtilsClient
+  v as createRhfUtilsClient
 };

package/dist/esm/form/Form.mjs

@@ -1,98 +1,82 @@
-import { jsxs as _, jsx as d } from "react/jsx-runtime";
+import { jsx as a, jsxs as v, Fragment as E } 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";
-function A({
-  formId: s,
-  formRef: m,
+import { useFormContext as P } from "react-hook-form";
+import w from "../client/config/useRhfUtilsClientConfigContext.mjs";
+import S from "../devtool/LazyDevTool.mjs";
+import { FormSubmitError as h } from "../submit/error/FormSubmitError.mjs";
+import U from "../submit/error/setCtxErrorsByFormSubmitErrors.mjs";
+import _ from "./_Controller.mjs";
+function G({
+  formId: n,
+  formRef: p,
   //
   onSubmit: c,
-  onSubmitError: C,
-  onSubmitInvalid: b,
-  Children: h,
+  onSubmitError: d,
+  onSubmitInvalid: F,
+  Children: i,
   //
-  form: p,
-  utils: o,
-  //
-  children: i
+  form: l,
+  utils: o
 }) {
-  const n = v(), r = N(), j = async (t) => {
+  const e = P(), r = w(), y = async (t) => {
     o != null && o.stopSubmitPropagation && t.stopPropagation();
     try {
-      await n.handleSubmit(B, b)(t);
-    } catch (e) {
-      T(e, t);
+      await e.handleSubmit(f, F)(t);
+    } catch (m) {
+      b(m, t);
     }
-  }, B = (t, e) => c == null ? void 0 : c(
+  }, f = (t, m) => c == null ? void 0 : c(
     t,
     {
-      formId: s,
-      formRef: m,
-      context: n,
+      formId: n,
+      formRef: p,
+      context: e,
       utils: o,
-      FormSubmitError: x
+      FormSubmitError: h
     },
-    e
-  ), T = (t, e) => {
-    var F;
-    const a = t instanceof x ? (
+    m
+  ), b = (t, m) => {
+    var x;
+    const C = t instanceof h ? (
       // 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)
+      (x = r == null ? void 0 : r.onSubmitUnknownError) == null ? void 0 : x.call(r, t)
     );
-    a && S(n, a), C == null || C(
+    C && U(e, C), d == null || d(
       t,
       {
-        formId: s,
-        formRef: m,
-        context: n,
+        formId: n,
+        formRef: p,
+        context: e,
         utils: o
       },
-      e
+      m
     );
-  }, l = {
-    formId: s,
-    formRef: m,
-    context: n,
+  }, s = {
+    formId: n,
+    formRef: p,
+    context: e,
     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,
-    {
-      noValidate: !0,
-      Component: r == null ? void 0 : r.FormComponent,
-      formRef: 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,
-          {
-            props: typeof o.devTool == "object" ? o.devTool : void 0
-          }
-        ),
-        h && /* @__PURE__ */ d(h, { ...l }),
-        i,
-        y("bottom")
-      ]
-    }
-  );
+    Controller: _,
+    FormSubmitError: h
+  }, T = (r == null ? void 0 : r.FormComponent) ?? "form", j = (r == null ? void 0 : r.FormChildren) ?? k;
+  return /* @__PURE__ */ a(T, { ...l, ref: p, onSubmit: y, children: /* @__PURE__ */ v(j, { ...s, children: [
+    (o == null ? void 0 : o.devTool) && /* @__PURE__ */ a(
+      S,
+      {
+        props: typeof o.devTool == "object" ? o.devTool : void 0
+      }
+    ),
+    /* @__PURE__ */ a(i, { ...s })
+  ] }) });
+}
+function k({
+  children: n
+}) {
+  return /* @__PURE__ */ a(E, { children: n });
 }
 export {
-  A as default
+  G 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';
 
@@ -27,6 +27,10 @@ export type RhfUtilsClientConfig = {
          * (Extend this type via `Register` type to inject custom options/functionality via `Children` component.)
          */
         utils?: RhfUtilsFormOptions;
+        /**
+         * Default props for form element.
+         */
+        form?: Omit<React.PropsWithoutRef<JSX.IntrinsicElements['form']>, 'onSubmit'>;
     };
     /**
      * Supply your own `<form>` component.
@@ -34,6 +38,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 +57,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/dist/types/form/RhfUtilsFormOptions.d.ts

@@ -8,11 +8,6 @@ import { Register } from '../register';
  * Can be extended using {@link Register.RhfUtilsFormOptions}.
  */
 export type RhfUtilsFormOptions = {
-    /**
-     * Style via your own classes.
-     * (Defaults merged with individual class names.)
-     */
-    classNames?: string[];
     /** Request submit via listener on form change. */
     submitOnChange?: boolean;
     /** Reset form values if submit throw errors. (Use case: optimistic UI toggle form that submits on each change.) */

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

@@ -12,11 +12,11 @@ export type UseRhfUtilsFormProps<TFieldValues extends SafeFieldValues, TTransfor
     /** Submit handler when form is invalid. */
     onSubmitInvalid?: SubmitErrorHandler<TFieldValues>;
     defaultValues?: UseFormProps<TFieldValues>['defaultValues'];
-    Children?: React.FC<UseRhfUtilsFormChildrenProps<TFieldValues, TTransformedValues>>;
+    Children: React.FC<UseRhfUtilsFormChildrenProps<TFieldValues, TTransformedValues>>;
     /** {@link RhfUseFormProps} props for RHF's {@link useForm}. */
     rhf?: Omit<UseFormProps<TFieldValues>, 'defaultValues'>;
-    /** {@link FormProps} props for Form. */
-    form?: React.PropsWithoutRef<JSX.IntrinsicElements['form']>;
     /** {@link RhfUtilsFormOptions} to enabled utils functionality. */
     utils?: RhfUtilsFormOptions;
+    /** {@link FormProps} props for Form. */
+    form?: Omit<React.PropsWithoutRef<JSX.IntrinsicElements['form']>, 'onSubmit'>;
 };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@paragrav/rhf-utils",
   "author": "paragrav.dev",
   "license": "MIT",
-  "version": "0.0.117",
+  "version": "0.0.119",
   "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
-};