@paragrav/rhf-utils 0.0.132 → 0.0.134

package/README.md

@@ -2,7 +2,29 @@
 
 ## About
 
-Integration and utility library for react-hook-form.
+Integration and utility library for [react-hook-form](https://www.react-hook-form.com/).
+
+If you have multiple forms and would like a more declarative API to manage their behavior (via built-in and custom options), including transformation of backend errors, and debugging field errors.
+
+## Features
+
+- built with and for [TypeScript](https://www.typescriptlang.org/)
+- global configuration, such as:
+  - injecting your own hooks and UI (`FormChildrenWrapper`)
+  - server error transformation (`onSubmitErrorUnknown`)
+  - FieldErrors logging/throwing (`RhfUtilsClientConfig.FieldErrors`)
+  - extendable options type (`RhfUtilsFormOptions`)
+- form-specific overrides
+- schema-typed Controller component
+- schema-typed FormSubmitError class
+  - throw in submit handler to add errors to RHF context and fail submit
+- flatter `FieldErrors` structure (`FlatFieldErrors`)
+  - grouped into `all`, `fields`, `roots`, and `orphans`
+  - `FormErrorMessageByPath` for displaying error message (with `FormNonFieldErrorMarker`)
+- `zod` support
+  - including `z.input` and `z.output` types for transformations
+- safer `FieldValues` type (`SafeFieldValues`)
+- 3.3kB min+gzip core functionality (excluding [peer dependencies](#peer-dependencies))
 
 ## Install
 
@@ -14,7 +36,7 @@ yarn add @paragrav/rhf-utils     # yarn
 
 ## Config
 
-To configure, create a file `config.tsx` with desired configuration settings. This is global configuration across all forms.
+To configure, create a file like `config.tsx` with desired configuration settings. This is global configuration across all forms, some of which can be overridden at the form level.
 
 ```tsx
 export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
@@ -50,8 +72,8 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
       formRef, //         ref
       context, //         rhf UseFormReturn
       options, //         RhfUtilsFormOptions (with any custom props)
-      Controller, //      strictly-typed rhf controller
-      FormSubmitError, // strictly-typed error class
+      Controller, //      rhf controller (SafeFieldValues-typed; no schema at this level)
+      FormSubmitError, // error class (SafeFieldValues-typed; no schema at this level)
       children, //        RhfUtilsZodForm's Children instance
     },
   ) => {
@@ -132,7 +154,7 @@ Currently, only `zod` is supported.
   // submit handler
   onSubmit={async (
     data, //    schema output
-    context, // UseRhfUtilsFormOnSubmitContext (id, ref, rhf context, utils options, strictly-typed FormSubmitError class)
+    context, // UseRhfUtilsFormOnSubmitContext (id, ref, rhf context, utils options, schema-typed FormSubmitError class)
     event, //   SubmitEvent
   ) => {
     await loginService(data);
@@ -153,12 +175,12 @@ Currently, only `zod` is supported.
     formRef, //         ref
     context, //         rhf UseFormReturn
     options, //         RhfUtilsFormOptions
-    Controller, //      strictly-typed rhf controller
-    FormSubmitError, // strictly-typed error class
+    Controller, //      schema-typed rhf controller
+    FormSubmitError, // schema-typed error class
   }) => (
     <>
       <Controller
-        name="email" // strictly-typed field name
+        name="email" // schema-typed field name
         render={({ field, formState: { isSubmitting } }) => (
           <label>
             Email
@@ -220,16 +242,16 @@ 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 from your schema and `root`/`root.{string}` keys.
+This is an `Error`-based class that you can use to throw a structured error in your submit handler. It uses `FormSubmitErrors` (with an "s") type's structure, which is a flat, simplified version of RHF's `FieldErrors`.
 
-It uses `FormSubmitErrors` type's structure, which is a flat, simplified version of RHF's `FieldErrors`.
+It differs from `FlatFieldError` only in that it is narrower. Namely, it is schema-typed, so it allows field names from your schema and `root.${string}` keys. And only `type` (optional) and `message` props for error.
 
 Example:
 
 ```tsx
 <RhfUtilsZodForm
-  onSubmit={async ({ FormSubmitError }) => {
-    if (isProblem())
+  onSubmit={async (data, { FormSubmitError }) => {
+    if (isProblem(data))
       throw new FormSubmitError({
         root: { message: 'There was a problem with the form.' },
         'street.address': { message: 'Street address invalid.' },
@@ -298,6 +320,8 @@ You can configure via `RhfUtilsClientConfig` (example at the top) when form cont
 
 Use `useFlatFieldErrorsContext()` hook, which returns an object with errors grouped by `all`, `fields`, `roots`, `orphans` records, and `hasErrors` and `hasErrors` and `hasOrphans` booleans.
 
+`FlatFieldErrors` type is a flattened, simplified version of RHF's `FieldErrors`. Keys represent flattened, dot-notation field paths.
+
 ### Orphan Errors
 
 The concept of orphan errors is any error that is not being shown to user. An example would be a stray field in a schema that is prohibiting users from successfully submitting a form.
@@ -324,8 +348,6 @@ Orphans are exposed in a few places.
 - And `useFlatFieldErrorsContext()` hook, which returns an object with errors grouped by `all`, `fields`, `roots`, `orphans` records, and `hasErrors` and `hasOrphans` boolean.
 - Boolean value from `useFlatFieldErrorsContextHasOnlyOrphans`.
 
-`FlatFieldErrors` is a flattened, simplified version of RHF's `FieldErrors`. Keys represent field paths flattened to dot notation.
-
 ## Form Groups
 
 Sometimes you need to group multiple forms together.
@@ -350,3 +372,17 @@ In children forms, there are two options. You can choose to consider form "busy"
 - it is mounted by using `useFormGroupChildIsMountedTracker` hook
 
 Both hooks return `boolean` value indicating whether parent form is busy.
+
+## Other
+
+This library uses `SafeFieldValues` type which uses `unknown` instead of `any`.
+
+#### Peer dependencies:
+
+- [react](https://www.npmjs.com/package/react)
+- [react-dom](https://www.npmjs.com/package/react-dom)
+- [react-hook-form](https://www.npmjs.com/package/react-hook-form)
+- [zod](https://www.npmjs.com/package/zod)
+- [flat](https://www.npmjs.com/package/flat)
+- [@hookform/resolvers](https://www.npmjs.com/package/@hookform/resolvers)
+- [@hookform/devtools](https://www.npmjs.com/package/@hookform/devtools) (optional)

package/dist/esm/errors/message/FormErrorMessageByPath.mjs

@@ -5,8 +5,8 @@ import c from "./FormErrorMessage.mjs";
 const f = ({ path: o, Component: s }) => {
   const { errors: t } = g(), r = i(t, o, void 0), m = s ?? c;
   return r != null && r.message ? /* @__PURE__ */ n(a, { children: [
-    /* @__PURE__ */ e(F, { path: o }),
-    /* @__PURE__ */ e(m, { message: r.message })
+    /* @__PURE__ */ e(m, { message: r.message }),
+    /* @__PURE__ */ e(F, { path: o })
   ] }) : null;
 }, E = f;
 export {

package/dist/esm/errors/message/FormErrorMessageByPath.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"FormErrorMessageByPath.mjs","sources":["../../../../src/errors/message/FormErrorMessageByPath.tsx"],"sourcesContent":["import type { FieldError } from 'react-hook-form';\nimport { get, useFormState } from 'react-hook-form';\n\nimport FormNonFieldErrorMarker from '../nonfield/FormNonFieldErrorMarker';\n\nimport FormErrorMessage from './FormErrorMessage';\n\ntype Props = {\n  /** Field name as flat path. (e.g., \"address.street\") */\n  path: string;\n  /** Optional component to use to display message. (Defaults to {@link FormErrorMessage}) */\n  Component?: React.FC<{ message: string }>;\n};\n\nconst FormErrorMessageByPath: React.FC<Props> = ({ path, Component }) => {\n  const { errors } = useFormState();\n\n  const error = get(errors, path, undefined) as FieldError | undefined;\n\n  const _Component = Component ?? FormErrorMessage;\n\n  if (!error?.message) return null;\n\n  return (\n    <>\n      {/* marker (only required for non-root non-field errors) */}\n      <FormNonFieldErrorMarker path={path} />\n\n      {/* error message */}\n      <_Component message={error.message} />\n    </>\n  );\n};\n\nexport default FormErrorMessageByPath;\n"],"names":["FormErrorMessageByPath","path","Component","errors","useFormState","error","get","_Component","FormErrorMessage","jsxs","Fragment","jsx","FormNonFieldErrorMarker","FormErrorMessageByPath$1"],"mappings":";;;;AAcA,MAAMA,IAA0C,CAAC,EAAE,MAAAC,GAAM,WAAAC,QAAgB;AACjE,QAAA,EAAE,QAAAC,MAAWC,KAEbC,IAAQC,EAAIH,GAAQF,GAAM,MAAS,GAEnCM,IAAaL,KAAaM;AAE5B,SAACH,KAAA,QAAAA,EAAO,UAKR,gBAAAI,EAAAC,GAAA,EAAA,UAAA;AAAA,IAAA,gBAAAC,EAACC,KAAwB,MAAAX,GAAY;AAAA,IAGpC,gBAAAU,EAAAJ,GAAA,EAAW,SAASF,EAAM,QAAS,CAAA;AAAA,EACtC,EAAA,CAAA,IAT0B;AAW9B,GAEAQ,IAAeb;"}
+{"version":3,"file":"FormErrorMessageByPath.mjs","sources":["../../../../src/errors/message/FormErrorMessageByPath.tsx"],"sourcesContent":["import type { FieldError } from 'react-hook-form';\nimport { get, useFormState } from 'react-hook-form';\n\nimport FormNonFieldErrorMarker from '../nonfield/FormNonFieldErrorMarker';\n\nimport FormErrorMessage from './FormErrorMessage';\n\ntype Props = {\n  /** Field name as flat path. (e.g., \"address.street\") */\n  path: string;\n  /** Optional component to use to display message. (Defaults to {@link FormErrorMessage}) */\n  Component?: React.FC<{ message: string }>;\n};\n\nconst FormErrorMessageByPath: React.FC<Props> = ({ path, Component }) => {\n  const { errors } = useFormState();\n\n  const error = get(errors, path, undefined) as FieldError | undefined;\n\n  const _Component = Component ?? FormErrorMessage;\n\n  if (!error?.message) return null;\n\n  return (\n    <>\n      {/* error message */}\n      <_Component message={error.message} />\n\n      {/* marker (only required for non-root non-field errors) */}\n      <FormNonFieldErrorMarker path={path} />\n    </>\n  );\n};\n\nexport default FormErrorMessageByPath;\n"],"names":["FormErrorMessageByPath","path","Component","errors","useFormState","error","get","_Component","FormErrorMessage","jsxs","Fragment","jsx","FormNonFieldErrorMarker","FormErrorMessageByPath$1"],"mappings":";;;;AAcA,MAAMA,IAA0C,CAAC,EAAE,MAAAC,GAAM,WAAAC,QAAgB;AACjE,QAAA,EAAE,QAAAC,MAAWC,KAEbC,IAAQC,EAAIH,GAAQF,GAAM,MAAS,GAEnCM,IAAaL,KAAaM;AAE5B,SAACH,KAAA,QAAAA,EAAO,UAKR,gBAAAI,EAAAC,GAAA,EAAA,UAAA;AAAA,IAAC,gBAAAC,EAAAJ,GAAA,EAAW,SAASF,EAAM,QAAS,CAAA;AAAA,IAGpC,gBAAAM,EAACC,KAAwB,MAAAX,GAAY;AAAA,EACvC,EAAA,CAAA,IAT0B;AAW9B,GAEAY,IAAeb;"}

package/dist/esm/form/Form.mjs

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

package/dist/esm/form/Form.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Form.mjs","sources":["../../../src/form/Form.tsx"],"sourcesContent":["import React from 'react';\nimport type { UseFormHandleSubmit } from 'react-hook-form';\nimport { useFormContext } from 'react-hook-form';\n\nimport useRhfUtilsClientConfigMaybeContext from '@/client/config/useRhfUtilsClientConfigContext';\n\nimport LazyDevTool from '@/devtool/LazyDevTool';\n\nimport { FormSubmitError } from '@/submit/error/FormSubmitError';\nimport setCtxErrorsByFormSubmitErrors from '@/submit/error/setCtxErrorsByFormSubmitErrors';\n\nimport PassthroughChildren from '@/utils/PassthroughChildren';\n\nimport _Controller from './_Controller';\nimport type { SafeFieldValues } from './SafeFieldValues';\nimport type { UseRhfUtilsFormChildrenProps } from './UseRhfUtilsFormChildrenProps';\nimport type {\n  UseRhfUtilsFormOnSubmitContext,\n  UseRhfUtilsFormOnSubmitErrorContext,\n} from './UseRhfUtilsFormOnSubmitContext';\nimport type { UseRhfUtilsFormProps } from './UseRhfUtilsFormProps';\n\nexport type FormChildrenSlots = 'top' | 'bottom';\n\nexport type FormProps<\n  TFieldValues extends SafeFieldValues,\n  TTransformedValues extends SafeFieldValues,\n> = {\n  formId: string;\n  formRef: React.RefObject<HTMLFormElement>;\n} & Pick<\n  UseRhfUtilsFormProps<TFieldValues, TTransformedValues>,\n  | 'onSubmit'\n  | 'onSubmitError'\n  | 'onSubmitInvalid'\n  //\n  | 'Children'\n  //\n  | 'form'\n  | 'utils'\n>;\n\nfunction _Form<\n  TFieldValues extends SafeFieldValues,\n  TTransformedValues extends SafeFieldValues,\n>({\n  formId,\n  formRef,\n  //\n  onSubmit,\n  onSubmitError,\n  onSubmitInvalid,\n  Children,\n  //\n  form,\n  utils,\n}: FormProps<TFieldValues, TTransformedValues>) {\n  const rhfContext = useFormContext<\n    TFieldValues,\n    unknown,\n    TTransformedValues\n  >();\n\n  const config = useRhfUtilsClientConfigMaybeContext();\n\n  // handlers\n\n  const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {\n    // cannot stop propagation in handleSubmitValid, b/c it receives a different event object\n    if (utils?.stopSubmitPropagation) event.stopPropagation();\n\n    try {\n      await rhfContext.handleSubmit(handleSubmitValid, onSubmitInvalid)(event);\n    } catch (error) {\n      handleSubmitError(error, event);\n    }\n  };\n\n  const handleSubmitValid = ((\n    data: TTransformedValues,\n    event?: React.BaseSyntheticEvent,\n  ) => {\n    return onSubmit?.(\n      data,\n      {\n        formId,\n        formRef,\n        context: rhfContext,\n        utils,\n        FormSubmitError: FormSubmitError<TFieldValues>,\n      } satisfies UseRhfUtilsFormOnSubmitContext<\n        TFieldValues,\n        TTransformedValues\n      >,\n      event as React.BaseSyntheticEvent<SubmitEvent>, // `as` required due to conditional generic\n    );\n  }) as Parameters<UseFormHandleSubmit<TFieldValues, TTransformedValues>>[0];\n\n  const handleSubmitError = (\n    error: unknown,\n    event: React.BaseSyntheticEvent,\n  ) => {\n    // get `FormSubmitErrors`, if possible\n    const formSubmitErrors =\n      error instanceof FormSubmitError\n        ? // consumer can manually throw FormSubmitError (e.g., manual validation)\n          (error as FormSubmitError).errors // `as` to avoid `<any>`\n        : // if error is not FormSubmitError, consumer can provide global handler\n          config?.onSubmitErrorUnknown?.(error);\n\n    if (formSubmitErrors)\n      setCtxErrorsByFormSubmitErrors(rhfContext, formSubmitErrors);\n\n    onSubmitError?.(\n      error,\n      {\n        formId,\n        formRef,\n        context: rhfContext,\n        utils,\n      } satisfies UseRhfUtilsFormOnSubmitErrorContext<\n        TFieldValues,\n        TTransformedValues\n      >,\n      event as React.BaseSyntheticEvent<SubmitEvent>, // `as` required due to conditional generic\n    );\n  };\n\n  const childrenProps: UseRhfUtilsFormChildrenProps<\n    TFieldValues,\n    TTransformedValues\n  > = {\n    formId,\n    formRef,\n    context: rhfContext,\n    utils,\n    Controller: _Controller<TFieldValues>,\n    FormSubmitError: FormSubmitError<TFieldValues>,\n  };\n\n  const FormComponent = config?.FormComponent ?? 'form';\n\n  const FormChildrenWrapper =\n    config?.FormChildrenWrapper ?? PassthroughChildren;\n\n  return (\n    <FormComponent\n      {...form}\n      ref={formRef}\n      onSubmit={(e) => void handleSubmit(e)}\n    >\n      <FormChildrenWrapper {...childrenProps}>\n        {utils?.devTool && (\n          <LazyDevTool\n            props={\n              typeof utils.devTool === 'object' ? utils.devTool : undefined\n            }\n          />\n        )}\n\n        <Children {...childrenProps} />\n      </FormChildrenWrapper>\n    </FormComponent>\n  );\n}\n\nexport default _Form;\n"],"names":["_Form","formId","formRef","onSubmit","onSubmitError","onSubmitInvalid","Children","form","utils","rhfContext","useFormContext","config","useRhfUtilsClientConfigMaybeContext","handleSubmit","event","handleSubmitValid","error","handleSubmitError","data","FormSubmitError","formSubmitErrors","_a","setCtxErrorsByFormSubmitErrors","childrenProps","_Controller","FormComponent","FormChildrenWrapper","PassthroughChildren","jsx","e","jsxs","LazyDevTool"],"mappings":";;;;;;;;;AA0CA,SAASA,EAGP;AAAA,EACA,QAAAC;AAAA,EACA,SAAAC;AAAA;AAAA,EAEA,UAAAC;AAAA,EACA,eAAAC;AAAA,EACA,iBAAAC;AAAA,EACA,UAAAC;AAAA;AAAA,EAEA,MAAAC;AAAA,EACA,OAAAC;AACF,GAAgD;AAC9C,QAAMC,IAAaC,KAMbC,IAASC,KAITC,IAAe,OAAOC,MAA4C;AAElE,IAAAN,KAAA,QAAAA,EAAO,yBAAuBM,EAAM,gBAAgB;AAEpD,QAAA;AACF,YAAML,EAAW,aAAaM,GAAmBV,CAAe,EAAES,CAAK;AAAA,aAChEE,GAAO;AACd,MAAAC,EAAkBD,GAAOF,CAAK;AAAA,IAChC;AAAA,EAAA,GAGIC,IAAqB,CACzBG,GACAJ,MAEOX,KAAA,gBAAAA;AAAA,IACLe;AAAA,IACA;AAAA,MACE,QAAAjB;AAAA,MACA,SAAAC;AAAA,MACA,SAASO;AAAA,MACT,OAAAD;AAAA,MACA,iBAAAW;AAAA,IACF;AAAA,IAIAL;AAAA,KAIEG,IAAoB,CACxBD,GACAF,MACG;;AAEH,UAAMM,IACJJ,aAAiBG;AAAA;AAAA,MAEZH,EAA0B;AAAA;AAAA;AAAA,OAE3BK,IAAAV,KAAA,gBAAAA,EAAQ,yBAAR,gBAAAU,EAAA,KAAAV,GAA+BK;AAAA;AAEjC,IAAAI,KACFE,EAA+Bb,GAAYW,CAAgB,GAE7DhB,KAAA,QAAAA;AAAA,MACEY;AAAA,MACA;AAAA,QACE,QAAAf;AAAA,QACA,SAAAC;AAAA,QACA,SAASO;AAAA,QACT,OAAAD;AAAA,MACF;AAAA,MAIAM;AAAA;AAAA,EACF,GAGIS,IAGF;AAAA,IACF,QAAAtB;AAAA,IACA,SAAAC;AAAA,IACA,SAASO;AAAA,IACT,OAAAD;AAAA,IACA,YAAYgB;AAAA,IACZ,iBAAAL;AAAA,EAAA,GAGIM,KAAgBd,KAAA,gBAAAA,EAAQ,kBAAiB,QAEzCe,KACJf,KAAA,gBAAAA,EAAQ,wBAAuBgB;AAG/B,SAAA,gBAAAC;AAAA,IAACH;AAAA,IAAA;AAAA,MACE,GAAGlB;AAAA,MACJ,KAAKL;AAAA,MACL,UAAU,CAAC2B,MAAM,KAAKhB,EAAagB,CAAC;AAAA,MAEpC,UAAA,gBAAAC,EAACJ,GAAqB,EAAA,GAAGH,GACtB,UAAA;AAAA,SAAAf,KAAA,gBAAAA,EAAO,YACN,gBAAAoB;AAAA,UAACG;AAAA,UAAA;AAAA,YACC,OACE,OAAOvB,EAAM,WAAY,WAAWA,EAAM,UAAU;AAAA,UAAA;AAAA,QAExD;AAAA,QAGF,gBAAAoB,EAACtB,GAAU,EAAA,GAAGiB,GAAe;AAAA,MAAA,GAC/B;AAAA,IAAA;AAAA,EAAA;AAGN;"}
+{"version":3,"file":"Form.mjs","sources":["../../../src/form/Form.tsx"],"sourcesContent":["import React from 'react';\nimport type { UseFormHandleSubmit } from 'react-hook-form';\nimport { useFormContext } from 'react-hook-form';\n\nimport type { RhfUtilsFormChildrenWrapperProps } from '@/client/config/RhfUtilsClientConfig';\nimport useRhfUtilsClientConfigMaybeContext from '@/client/config/useRhfUtilsClientConfigContext';\n\nimport LazyDevTool from '@/devtool/LazyDevTool';\n\nimport { FormSubmitError } from '@/submit/error/FormSubmitError';\nimport setCtxErrorsByFormSubmitErrors from '@/submit/error/setCtxErrorsByFormSubmitErrors';\n\nimport PassthroughChildren from '@/utils/PassthroughChildren';\n\nimport _Controller from './_Controller';\nimport type { SafeFieldValues } from './SafeFieldValues';\nimport type { UseRhfUtilsFormChildrenProps } from './UseRhfUtilsFormChildrenProps';\nimport type {\n  UseRhfUtilsFormOnSubmitContext,\n  UseRhfUtilsFormOnSubmitErrorContext,\n} from './UseRhfUtilsFormOnSubmitContext';\nimport type { UseRhfUtilsFormProps } from './UseRhfUtilsFormProps';\n\nexport type FormChildrenSlots = 'top' | 'bottom';\n\nexport type FormProps<\n  TFieldValues extends SafeFieldValues,\n  TTransformedValues extends SafeFieldValues,\n> = {\n  formId: string;\n  formRef: React.RefObject<HTMLFormElement>;\n} & Pick<\n  UseRhfUtilsFormProps<TFieldValues, TTransformedValues>,\n  | 'onSubmit'\n  | 'onSubmitError'\n  | 'onSubmitInvalid'\n  //\n  | 'Children'\n  //\n  | 'form'\n  | 'utils'\n>;\n\nfunction _Form<\n  TFieldValues extends SafeFieldValues,\n  TTransformedValues extends SafeFieldValues,\n>({\n  formId,\n  formRef,\n  //\n  onSubmit,\n  onSubmitError,\n  onSubmitInvalid,\n  Children,\n  //\n  form,\n  utils,\n}: FormProps<TFieldValues, TTransformedValues>) {\n  const rhfContext = useFormContext<\n    TFieldValues,\n    unknown,\n    TTransformedValues\n  >();\n\n  const config = useRhfUtilsClientConfigMaybeContext();\n\n  // handlers\n\n  const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {\n    // cannot stop propagation in handleSubmitValid, b/c it receives a different event object\n    if (utils?.stopSubmitPropagation) event.stopPropagation();\n\n    try {\n      await rhfContext.handleSubmit(handleSubmitValid, onSubmitInvalid)(event);\n    } catch (error) {\n      handleSubmitError(error, event);\n    }\n  };\n\n  const handleSubmitValid = ((\n    data: TTransformedValues,\n    event?: React.BaseSyntheticEvent,\n  ) => {\n    return onSubmit?.(\n      data,\n      {\n        formId,\n        formRef,\n        context: rhfContext,\n        utils,\n        FormSubmitError: FormSubmitError<TFieldValues>,\n      } satisfies UseRhfUtilsFormOnSubmitContext<\n        TFieldValues,\n        TTransformedValues\n      >,\n      event as React.BaseSyntheticEvent<SubmitEvent>, // `as` required due to conditional generic\n    );\n  }) as Parameters<UseFormHandleSubmit<TFieldValues, TTransformedValues>>[0];\n\n  const handleSubmitError = (\n    error: unknown,\n    event: React.BaseSyntheticEvent,\n  ) => {\n    // get `FormSubmitErrors`, if possible\n    const formSubmitErrors =\n      error instanceof FormSubmitError\n        ? // consumer can manually throw FormSubmitError (e.g., manual validation)\n          (error as FormSubmitError).errors // `as` to avoid `<any>`\n        : // if error is not FormSubmitError, consumer can provide global handler\n          config?.onSubmitErrorUnknown?.(error);\n\n    if (formSubmitErrors)\n      setCtxErrorsByFormSubmitErrors(rhfContext, formSubmitErrors);\n\n    onSubmitError?.(\n      error,\n      {\n        formId,\n        formRef,\n        context: rhfContext,\n        utils,\n      } satisfies UseRhfUtilsFormOnSubmitErrorContext<\n        TFieldValues,\n        TTransformedValues\n      >,\n      event as React.BaseSyntheticEvent<SubmitEvent>, // `as` required due to conditional generic\n    );\n  };\n\n  const childrenProps: UseRhfUtilsFormChildrenProps<\n    TFieldValues,\n    TTransformedValues\n  > = {\n    formId,\n    formRef,\n    context: rhfContext,\n    utils,\n    Controller: _Controller<TFieldValues>,\n    FormSubmitError: FormSubmitError<TFieldValues>,\n  };\n\n  // children wrapper is not specific to schema (not possible)\n  const childrenWrapperProps =\n    childrenProps as RhfUtilsFormChildrenWrapperProps;\n\n  const FormComponent = config?.FormComponent ?? 'form';\n\n  const FormChildrenWrapper =\n    config?.FormChildrenWrapper ?? PassthroughChildren;\n\n  return (\n    <FormComponent\n      {...form}\n      ref={formRef}\n      onSubmit={(e) => void handleSubmit(e)}\n    >\n      <FormChildrenWrapper {...childrenWrapperProps}>\n        {utils?.devTool && (\n          <LazyDevTool\n            props={\n              typeof utils.devTool === 'object' ? utils.devTool : undefined\n            }\n          />\n        )}\n\n        <Children {...childrenProps} />\n      </FormChildrenWrapper>\n    </FormComponent>\n  );\n}\n\nexport default _Form;\n"],"names":["_Form","formId","formRef","onSubmit","onSubmitError","onSubmitInvalid","Children","form","utils","rhfContext","useFormContext","config","useRhfUtilsClientConfigMaybeContext","handleSubmit","event","handleSubmitValid","error","handleSubmitError","data","FormSubmitError","formSubmitErrors","_a","setCtxErrorsByFormSubmitErrors","childrenProps","_Controller","childrenWrapperProps","FormComponent","FormChildrenWrapper","PassthroughChildren","jsx","e","jsxs","LazyDevTool"],"mappings":";;;;;;;;;AA2CA,SAASA,EAGP;AAAA,EACA,QAAAC;AAAA,EACA,SAAAC;AAAA;AAAA,EAEA,UAAAC;AAAA,EACA,eAAAC;AAAA,EACA,iBAAAC;AAAA,EACA,UAAAC;AAAA;AAAA,EAEA,MAAAC;AAAA,EACA,OAAAC;AACF,GAAgD;AAC9C,QAAMC,IAAaC,KAMbC,IAASC,KAITC,IAAe,OAAOC,MAA4C;AAElE,IAAAN,KAAA,QAAAA,EAAO,yBAAuBM,EAAM,gBAAgB;AAEpD,QAAA;AACF,YAAML,EAAW,aAAaM,GAAmBV,CAAe,EAAES,CAAK;AAAA,aAChEE,GAAO;AACd,MAAAC,EAAkBD,GAAOF,CAAK;AAAA,IAChC;AAAA,EAAA,GAGIC,IAAqB,CACzBG,GACAJ,MAEOX,KAAA,gBAAAA;AAAA,IACLe;AAAA,IACA;AAAA,MACE,QAAAjB;AAAA,MACA,SAAAC;AAAA,MACA,SAASO;AAAA,MACT,OAAAD;AAAA,MACA,iBAAAW;AAAA,IACF;AAAA,IAIAL;AAAA,KAIEG,IAAoB,CACxBD,GACAF,MACG;;AAEH,UAAMM,IACJJ,aAAiBG;AAAA;AAAA,MAEZH,EAA0B;AAAA;AAAA;AAAA,OAE3BK,IAAAV,KAAA,gBAAAA,EAAQ,yBAAR,gBAAAU,EAAA,KAAAV,GAA+BK;AAAA;AAEjC,IAAAI,KACFE,EAA+Bb,GAAYW,CAAgB,GAE7DhB,KAAA,QAAAA;AAAA,MACEY;AAAA,MACA;AAAA,QACE,QAAAf;AAAA,QACA,SAAAC;AAAA,QACA,SAASO;AAAA,QACT,OAAAD;AAAA,MACF;AAAA,MAIAM;AAAA;AAAA,EACF,GAGIS,IAGF;AAAA,IACF,QAAAtB;AAAA,IACA,SAAAC;AAAA,IACA,SAASO;AAAA,IACT,OAAAD;AAAA,IACA,YAAYgB;AAAA,IACZ,iBAAAL;AAAA,EAAA,GAIIM,IACJF,GAEIG,KAAgBf,KAAA,gBAAAA,EAAQ,kBAAiB,QAEzCgB,KACJhB,KAAA,gBAAAA,EAAQ,wBAAuBiB;AAG/B,SAAA,gBAAAC;AAAA,IAACH;AAAA,IAAA;AAAA,MACE,GAAGnB;AAAA,MACJ,KAAKL;AAAA,MACL,UAAU,CAAC4B,MAAM,KAAKjB,EAAaiB,CAAC;AAAA,MAEpC,UAAA,gBAAAC,EAACJ,GAAqB,EAAA,GAAGF,GACtB,UAAA;AAAA,SAAAjB,KAAA,gBAAAA,EAAO,YACN,gBAAAqB;AAAA,UAACG;AAAA,UAAA;AAAA,YACC,OACE,OAAOxB,EAAM,WAAY,WAAWA,EAAM,UAAU;AAAA,UAAA;AAAA,QAExD;AAAA,QAGF,gBAAAqB,EAACvB,GAAU,EAAA,GAAGiB,GAAe;AAAA,MAAA,GAC/B;AAAA,IAAA;AAAA,EAAA;AAGN;"}

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

@@ -1,7 +1,6 @@
 import { UseFormProps } from 'react-hook-form';
 import { FlatFieldErrorsOutputConfig } from '../../errors/flat/context/FlatFieldErrorsOutputConfig';
 import { RhfUtilsFormOptions } from '../../form/RhfUtilsFormOptions';
-import { SafeFieldValues } from '../../form/SafeFieldValues';
 import { UseRhfUtilsFormChildrenProps } from '../../form/UseRhfUtilsFormChildrenProps';
 import { FormSubmitErrors } from '../../submit/error/FormSubmitErrors';
 
@@ -41,11 +40,13 @@ export type RhfUtilsClientConfig = {
     /**
      * Wrap all form bodies with your own hooks, components, etc.
      *
+     * (NOTE: not schema-typed as not possible at this level)
+     *
      * Use cases:
      * - custom hooks/behaviors based on `options`
      * - shared header, footer
      */
-    FormChildrenWrapper?: <TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>(props: React.PropsWithChildren<UseRhfUtilsFormChildrenProps<TFieldValues, TTransformedValues>>) => React.ReactNode;
+    FormChildrenWrapper?: (props: RhfUtilsFormChildrenWrapperProps) => React.ReactNode;
     /**
      * Global submit error handler when/if submit handler throws an error other than {@link FormSubmitError}.
      *
@@ -64,3 +65,7 @@ export type RhfUtilsClientConfig = {
         output?: FlatFieldErrorsOutputConfig;
     };
 };
+/**
+ * Non-schema-typed version of `UseRhfUtilsFormChildrenProps` for global config.
+ */
+export type RhfUtilsFormChildrenWrapperProps = React.PropsWithChildren<UseRhfUtilsFormChildrenProps>;

package/package.json

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