@paragrav/rhf-utils 0.0.136 → 0.0.137

package/README.md

@@ -2,29 +2,30 @@
 
 ## About
 
-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 global and form-level options, including transformation of backend errors, and debugging field errors.
+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
 
-- [TypeScript](https://www.typescriptlang.org/)-first
-- global configuration, such as:
-  - injecting your own hooks and UI (`FormChildrenWrapper`)
+- TypeScript-first
+- global configuration (`RhfUtilsClientConfig`)
+  - RHF (`UseFormProps`) and utilities (`RhfUtilsFormOptions`) options defaults
+  - inject 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
+  - RHF `FormState.errors` logging/throwing (`RhfUtilsClientConfig.fieldErrors`)
+- form-level configuration (`RhfUtilsZodForm`)
+  - RHF and utilities options overrides
+    - extendable utilities options type (`RhfUtilsFormOptions`)
+  - throw error (`FormSubmitError`) in submit handler to add errors to RHF context and fail submit
+  - handle submit error (`onSubmitError`)
+  - dependency injection for children (`RhfUtilsZodForm.Children`), including:
+    - formId, formRef, RHF context, utilities options
+    - schema-typed Controller component and FormSubmitError class
 - simpler/flatter `FieldErrors` structure (`FlatFieldErrors`)
   - context groups errors into `all`, `fields`, `roots`, and `orphans` (`useFlatFieldErrorsContext`)
-  - `FormErrorMessageByPath` for displaying error message
-- `zod` support
-  - including input/output types for transformations
+  - `RhfUtilsFieldErrorMessage` for displaying error message
 - safer `FieldValues` type (`SafeFieldValues`)
-- 3.3kB min+gzip core functionality (excluding [peer dependencies](#peer-dependencies))
+- `zod` support, including input/output types for transformations
+- ~3.9kB min+gzip (excluding [peer dependencies](#peer-dependencies))
 
 ## Install
 
@@ -34,9 +35,15 @@ pnpm install @paragrav/rhf-utils # pnpm
 yarn add @paragrav/rhf-utils     # yarn
 ```
 
+## Quick Start
+
+- 🔗 [Config](#config) (`RhfUtilsClientConfig`): define your desired global config (optional)
+- 🔗 [Provider](#provider) (`RhfUtilsClientForZodContextProvider`): add to your global stack
+- 🔗 [Form](#form) (`RhfUtilsZodForm`): use for your forms
+
 ## Config
 
-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.
+Create a config (`RhfUtilsClientConfig`) object with desired global and default options. This is global configuration across all forms, some of which can be overridden at the form level.
 
 ```tsx
 export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
@@ -77,10 +84,12 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
       children, //        RhfUtilsZodForm's Children instance
     },
   ) => {
-    // your own hooks/behaviors controlled via custom option props
+    useMyGlobalFormHook();
+
+    // form-level control of your own hooks/behaviors via custom option props
     // (see "Extend RhfUtilsFormOptions" section for more info)
-    useMyFormNavigationPrompt({
-      enabled: !!options?.enableMyFormNavigationPrompt,
+    useMyOptionalFormHook({
+      enabled: !!options?.enableMyOptionalFormHook,
     });
 
     return (
@@ -99,18 +108,13 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
   onSubmitErrorUnknown: (
     error, // unknown
   ) => {
-    // return FormSubmitErrors object to be merged to RHF context errors
+    // return FormSubmitFieldErrors object to be merged to RHF context errors
     if (isMyServerError(error))
-      return transformMyServerErrorToFormSubmitErrors(error);
-
-    // if other error
-    return {
-      root: { type: 'server', message: 'There was a problem.' },
-    } satisfies FormSubmitErrors;
+      return transformMyServerErrorToFormSubmitFieldErrors(error);
   },
 
-  // rhfContext.formState.errors output for debugging
-  FieldErrors: {
+  // RHF FormState.errors output for debugging
+  fieldErrors: {
     // callbacks to determine when to output information about field errors
     // provided `FlatFieldErrorsContext` (all, fields, roots, orphans, hasOrphans)
     // (See "Orphan Errors" section below for more info.)
@@ -133,7 +137,7 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
 
 ## Provider
 
-And add the context provider to your global provider stack:
+Add the context provider to your global provider stack.
 
 ```tsx
 <RhfUtilsClientForZodContextProvider config={rhfUtilsClientConfig}>
@@ -185,7 +189,7 @@ Currently, only `zod` is supported.
           <label>
             Email
             <input {...field} disabled={isSubmitting} />
-            <FormErrorMessageByPath path={field.name} />
+            <RhfUtilsFieldErrorMessage path={field.name} />
           </label>
         )}
       />
@@ -199,13 +203,9 @@ Currently, only `zod` is supported.
   }}
   utils={{
     submitOnChange: true,
-    resetOnSubmitted: {
-      onSuccess: { values: 'current' },
-      onError: { values: 'defaults' },
-    },
     // custom option props
     // (see "Extend RhfUtilsFormOptions" section)
-    enableMyFormNavigationPrompt: true,
+    enableMyOptionalFormHook: true,
   }}
   form={{
     // class names are merged together with global defaults
@@ -242,18 +242,17 @@ function Children({...}: RhfUtilsUseFormChildrenZodProps<typeof schema>) { }
 
 ## `FormSubmitError`
 
-This is an extended `Error` 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`.
+This is an `Error`-based class that you can use to throw a schema-typed error in your submit handler.
 
-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.
+(Internally, it uses `FormSubmitFieldErrors` type's structure, which is a flat, simplified version of RHF's `FieldErrors`. It differs from `FlatFieldError` only in that it is narrower. It allows field names from your schema and `root.${string}` keys. And only `type` (optional) and `message` props for error.)
 
-Example:
+### Example
 
 ```tsx
 <RhfUtilsZodForm
   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.' },
       });
 
@@ -262,9 +261,9 @@ Example:
 />
 ```
 
-Any non-`FormSubmitError` error thrown from your submit handler (e.g., fetch/axios error) can be transformed by `RhfUtilsClientConfig`'s `onSubmitErrorUnknown` callback. This takes an `unknown` error and can return a `FormSubmitErrors` object, which is merged into RHF's form state errors.
+Any non-`FormSubmitError` error thrown from your submit handler (e.g., fetch/axios error) can be transformed by `RhfUtilsClientConfig`'s `onSubmitErrorUnknown` callback. This takes an `unknown` error and can return a `FormSubmitFieldErrors` object, which is merged into RHF's form state errors.
 
-Most common use case will be transforming backend errors to frontend shape. (You can use `getOnSubmitTrpcClientErrorHandler` HOF provided by this library for TRPC backends.)
+Most common use case will be transforming backend errors to frontend shape.
 
 ## `RhfUtilsFormOptions`
 
@@ -312,7 +311,7 @@ declare module '@paragrav/rhf-utils' {
   export interface Register {
     RhfUtilsFormOptions: {
       /** Enable user prompt to confirm navigating away from dirty form. */
-      enableMyFormNavigationPrompt?: boolean;
+      enableMyOptionalFormHook?: boolean;
     };
   }
 }
@@ -328,47 +327,67 @@ Use `useFlatFieldErrorsContext()` hook, which returns an object with errors grou
 
 ### Output
 
-For the purposes of debugging and/or logging, you can configure when form state errors are outputted (i.e., console log and/or thrown) via `RhfUtilsClientConfig` (example at the top).
+For the purposes of debugging and/or logging, you can configure when form state errors are outputted (i.e., console and/or thrown) via `RhfUtilsClientConfig.fieldErrors.output` (example at the top).
 
 ### Orphan Errors
 
-The concept of "orphan" errors is any field error that is not being shown to user. (For example, a field in a schema that is prohibiting users from submitting a valid form.)
+The concept of an "orphan" error is any errant schema property that could prohibit users from submitting a valid form because its input is missing or non-existent.
+
+Programatically, an "orphan" is any form state error that meets ALL of the following criteria:
+
+- non-field -- i.e., no RHF-supplied `ref` on `FieldError` object
+- non-root -- i.e., not `root` or `root.${string}` path
+- no corresponding "marker" in DOM (i.e., `FormNonFieldErrorMarker`)
+
+This is because:
+
+- field errors (with `ref`s) are assumed to be displayed next to their respective input
+- root errors (non-field, without `ref`s) are assumed to always be listed for display
+- all other errors must be marked as displayed to distinguish from being an orphan
 
-More technically, an "orphan" is any form state error that meets ALL of the following criteria:
+_See [FormNonFieldErrorMarker](#formnonfielderrormarker) section below for more information about when and why marker is needed._
 
-- not a root error -- i.e., `root` and `root.${string}` paths
-  - these are assumed to be listed for users somewhere
-- has no `ref` -- RHF includes `ref` to the associated input for each error (when applicable)
-  - these are assumed to be shown next to their input fields
-- has no marker in DOM (i.e., `FormNonFieldErrorMarker`)
-  - see section further below for more information
+#### Using orphan errors
 
 Detected orphans can be accessed via any of the following:
 
-- via `RhfUtilsClientConfig.FieldErrors.output`; e.g.:
-  - console log to facilitate debugging on development
-  - console error to facilitate reporting on production (via your own error reporting service)
-  - throw error for developer during development
+- `RhfUtilsClientConfig.fieldErrors.output` -- e.g., config per environment:
+  - _development_: `throw` to facilitate discovery and debugging
+  - _production_: `console.error` to facilitate reporting
 - `useFlatFieldErrorsContext()` hook
   - returns an object with list of errors grouped by `all`, `fields` (with `ref`), `roots`, `orphans` records, and includes computed booleans `hasErrors` and `hasOrphans`
 - boolean value from `useFlatFieldErrorsContextHasOnlyOrphans`
 
 ### FormNonFieldErrorMarker
 
-To get accurate orphan detection, you must use `FormNonFieldErrorMarker` in all errors you are displaying to user. (Technically, "root" errors and field errors with a `ref` do not need the marker, because those do not match the first two criteria of an orphan (as listed above). But there is no harm in including it consistently for all error displayed.)
+_If you don't need orphan detection, you can skip this section. By default, orphan detection still occurs but doesn't otherwise do anything._
 
-#### When is the marker required?
+To get accurate orphan detection, you must use `FormNonFieldErrorMarker` when displaying any non-root non-field errors. (Example further below.)
 
-For example, a field array with a minimum number of items -- e.g., `items: z.array(...).min(1)`.
+There is little harm in including it consistently for all individual errors displayed. (DOM traversal to find marker only occurs if error is non-field AND non-root, which is not typical.)
 
-When there are zero items, the error is not "root" and is not associated with a specific field. Therefore, in order to NOT detect this as an orphan, it must be "marked" as displayed using `FormNonFieldErrorMarker`.
+#### When is the marker required? _(example of non-root non-field error)_
 
-You can incorporate `FormNonFieldErrorMarker` into your own component library, or use this library's `FormErrorMessageByPath` to display error message to user, which includes this marker.
+A typical example is a field array with a required minimum number of items -- e.g., `items: z.array(...).min(1)`.
+
+When there are zero items, the error is non-field and non-root. You would probably display this error (manually) near the field array, using something like RHF's [`ErrorMessage`](https://www.react-hook-form.com/api/useformstate/errormessage/) component.
+
+In order to NOT detect this as an orphan, it must be explicitly "marked" as displayed using `FormNonFieldErrorMarker`.
+
+You can incorporate `FormNonFieldErrorMarker` into your own component library, or use this library's `RhfUtilsFieldErrorMessage` to display error message to user, which includes this marker.
 
 ```tsx
-<FormErrorMessageByPath path="items" />
+<RhfUtilsFieldErrorMessage path="items" />
 ```
 
+Uncommon, but if you are ONLY listing a summary of all errors, without individual displays, you will need to use the marker manually.
+
+```tsx
+<FormNonFieldErrorMarker path="items" />
+```
+
+_If you include the marker for error lists, it will defeat the purpose of the marker. Only use marker for individual errors._
+
 ## Form Groups
 
 Sometimes you need to group multiple forms together.
@@ -396,9 +415,11 @@ Both hooks return `boolean` value indicating whether parent form is busy.
 
 ## Other
 
+### SafeFieldValues
+
 This library uses `SafeFieldValues` type which uses `unknown` instead of `any`.
 
-#### Peer dependencies:
+### Peer dependencies
 
 - [react](https://www.npmjs.com/package/react)
 - [react-dom](https://www.npmjs.com/package/react-dom)

package/dist/esm/client/zod/context/RhfUtilsClientForZodContextProvider.mjs

@@ -7,7 +7,9 @@ const d = ({
   config: r,
   children: i
 }) => {
-  const [t] = e.useState(r), [n] = e.useState(() => f(t));
+  const [t] = e.useState(r), [n] = e.useState(
+    () => f(t ?? {})
+  );
   return /* @__PURE__ */ o(l, { value: t, children: /* @__PURE__ */ o(s, { value: n, children: i }) });
 }, p = d;
 export {

package/dist/esm/errors/flat/getFlatFieldErrors.mjs

@@ -1,24 +1,24 @@
-import { get as c } from "react-hook-form";
-import n from "./flattenFieldErrors.mjs";
-const u = (t) => {
-  const s = n(t), a = Object.keys(s);
+import { get as d } from "react-hook-form";
+import a from "./flattenFieldErrors.mjs";
+const b = (t) => {
+  const s = a(t), n = Object.keys(s);
   return Object.fromEntries(
-    a.reduce(
+    n.reduce(
       (e, o) => {
         const r = o.replace(
-          d,
+          i,
           ""
         );
         if (r === o) return e;
-        const f = c(t, r, void 0);
+        const f = d(t, r, void 0);
         return f && e.push([r, f]), e;
       },
       []
       // entries
     )
   );
-}, d = /\.(?:type|message)\b$/;
+}, i = /\.(?:type|message)\b$/;
 export {
-  u as default,
-  d as regexMaybeFieldErrorLeafNodeSuffix
+  b as default,
+  i as regexMaybeFieldErrorLeafNodeSuffix
 };

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

@@ -0,0 +1,14 @@
+import { jsxs as n, Fragment as i, jsx as o } from "react/jsx-runtime";
+import { useFormState as a, get as l } from "react-hook-form";
+import f from "../nonfield/FormNonFieldErrorMarker.mjs";
+import g from "./FormErrorMessage.mjs";
+const F = ({ path: e, Component: s }) => {
+  const { errors: t } = a(), r = l(t, e, void 0), m = s ?? g;
+  return r != null && r.message ? /* @__PURE__ */ n(i, { children: [
+    /* @__PURE__ */ o(m, { message: r.message }),
+    /* @__PURE__ */ o(f, { path: e })
+  ] }) : null;
+}, E = F;
+export {
+  E as default
+};

package/dist/esm/errors/orphan/isOrphanFormError.mjs

@@ -2,9 +2,9 @@ import m from "../isFieldErrorRefd.mjs";
 import t from "../nonfield/isNonFieldErrorMarkerInDOM.mjs";
 import e from "../root/isFormErrorPathRoot.mjs";
 const d = (r, o, i) => (
-  // not root path
-  !e(r) && // non-field
-  !m(o) && // not marked in DOM
+  // non-field
+  !m(o) && // non-root
+  !e(r) && // not marked in DOM
   !t(r, i)
 );
 export {

package/dist/esm/exports.mjs

@@ -1,50 +1,46 @@
 import { default as e } from "./client/zod/context/RhfUtilsClientForZodContextProvider.mjs";
-import { default as a } from "./client/zod/context/RhfUtilsZodForm.mjs";
+import { default as s } from "./client/zod/context/RhfUtilsZodForm.mjs";
 import { default as u } from "./client/zod/context/useRhfUtilsZodForm.mjs";
 import { default as m } from "./errors/flat/context/useFlatFieldErrorsContext.mjs";
 import { default as d } from "./errors/flat/context/useFlatFieldErrorsContextHasOnlyOrphans.mjs";
-import { default as x } from "./errors/message/FormErrorMessageByPath.mjs";
+import { default as x } from "./errors/message/RhfUtilsFieldErrorMessage.mjs";
 import { default as F } from "./errors/nonfield/FormNonFieldErrorMarker.mjs";
 import { default as C } from "./errors/root/RootErrorsListFromFlatFieldErrorsContext.mjs";
-import { default as E } from "./errors/trpc/getOnSubmitTrpcClientErrorHandler.mjs";
-import { default as R } from "./errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs";
-import { default as b } from "./form/context/utils/useRhfUtilsContext.mjs";
-import { default as y } from "./form/context/utils/useRhfUtilsContextRequestSubmit.mjs";
-import { default as B } from "./form/context/group/FormGroupContextProvider.mjs";
-import { default as P } from "./form/context/group/useFormGroupChildIsMountedTracker.mjs";
-import { default as U } from "./form/context/group/useFormGroupChildIsSubmittingTracker.mjs";
-import { default as O } from "./form/context/group/useFormGroupChildTracker.mjs";
-import { default as Z } from "./form/context/group/useFormGroupIsAnyBusy.mjs";
-import { default as v } from "./form/context/group/useFormGroupIsChildBusy.mjs";
-import { default as A } from "./form/context/group/useFormGroupIsParentBusy.mjs";
-import { default as L } from "./form/context/group/useFormGroupParentTracker.mjs";
-import { default as j } from "./form/context/group/useFormOrParentIsBusy.mjs";
-import { default as z } from "./form/utils/getSubmitterButtonData.mjs";
-import { default as K } from "./form/utils/useFormRequestSubmit.mjs";
-import { FormSubmitError as V } from "./submit/error/FormSubmitError.mjs";
+import { default as R } from "./form/context/utils/useRhfUtilsContext.mjs";
+import { default as E } from "./form/context/utils/useRhfUtilsContextRequestSubmit.mjs";
+import { default as I } from "./form/context/group/FormGroupContextProvider.mjs";
+import { default as b } from "./form/context/group/useFormGroupChildIsMountedTracker.mjs";
+import { default as B } from "./form/context/group/useFormGroupChildIsSubmittingTracker.mjs";
+import { default as S } from "./form/context/group/useFormGroupChildTracker.mjs";
+import { default as T } from "./form/context/group/useFormGroupIsAnyBusy.mjs";
+import { default as M } from "./form/context/group/useFormGroupIsChildBusy.mjs";
+import { default as Z } from "./form/context/group/useFormGroupIsParentBusy.mjs";
+import { default as v } from "./form/context/group/useFormGroupParentTracker.mjs";
+import { default as D } from "./form/context/group/useFormOrParentIsBusy.mjs";
+import { default as L } from "./form/utils/getSubmitterButtonData.mjs";
+import { default as j } from "./form/utils/useFormRequestSubmit.mjs";
+import { FormSubmitError as z } from "./submit/error/FormSubmitError.mjs";
 export {
-  x as FormErrorMessageByPath,
-  B as FormGroupContextProvider,
+  I as FormGroupContextProvider,
   F as FormNonFieldErrorMarker,
-  V as FormSubmitError,
+  z as FormSubmitError,
   e as RhfUtilsClientForZodContextProvider,
-  a as RhfUtilsZodForm,
+  x as RhfUtilsFieldErrorMessage,
+  s as RhfUtilsZodForm,
   C as RootErrorsListFromFlatFieldErrorsContext,
-  E as getOnSubmitTrpcClientErrorHandler,
-  z as getSubmitterButtonData,
-  R as trpcClientErrorToFormSubmitErrorsSchemaTransformer,
+  L as getSubmitterButtonData,
   m as useFlatFieldErrorsContext,
   d as useFlatFieldErrorsContextHasOnlyOrphans,
-  P as useFormGroupChildIsMountedTracker,
-  U as useFormGroupChildIsSubmittingTracker,
-  O as useFormGroupChildTracker,
-  Z as useFormGroupIsAnyBusy,
-  v as useFormGroupIsChildBusy,
-  A as useFormGroupIsParentBusy,
-  L as useFormGroupParentTracker,
-  j as useFormOrParentIsBusy,
-  K as useFormRequestSubmit,
-  b as useRhfUtilsContext,
-  y as useRhfUtilsContextRequestSubmit,
+  b as useFormGroupChildIsMountedTracker,
+  B as useFormGroupChildIsSubmittingTracker,
+  S as useFormGroupChildTracker,
+  T as useFormGroupIsAnyBusy,
+  M as useFormGroupIsChildBusy,
+  Z as useFormGroupIsParentBusy,
+  v as useFormGroupParentTracker,
+  D as useFormOrParentIsBusy,
+  j as useFormRequestSubmit,
+  R as useRhfUtilsContext,
+  E as useRhfUtilsContextRequestSubmit,
   u as useRhfUtilsZodForm
 };

package/dist/esm/form/Form.mjs

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

package/dist/esm/form/context/utils/RhfUtilsContextProvider.mjs

@@ -1,23 +1,23 @@
-import { jsx as l } from "react/jsx-runtime";
-import d from "../../../client/config/useRhfUtilsClientConfigContext.mjs";
-import f from "../../../errors/flat/context/useFlatFieldErrorsContextOutput.mjs";
+import { jsx as f } from "react/jsx-runtime";
+import l from "../../../client/config/useRhfUtilsClientConfigContext.mjs";
+import d from "../../../errors/flat/context/useFlatFieldErrorsContextOutput.mjs";
 import b from "../../../submit/useResetFormOnSubmitted.mjs";
 import C from "../../../submit/useSubmitFormOnChange.mjs";
 import { _RhfUtilsContextProvider as h } from "./useRhfUtilsContext.mjs";
-const n = ({
+const v = ({
   formId: u,
   formRef: t,
   options: e,
   children: a
 }) => {
   var m;
-  const r = d();
-  return f((m = r == null ? void 0 : r.FieldErrors) == null ? void 0 : m.output), C(t, {
+  const r = l();
+  return d((m = r == null ? void 0 : r.fieldErrors) == null ? void 0 : m.output), C(t, {
     // check for false/undefined
     disabled: ((e == null ? void 0 : e.submitOnChange) ?? !1) === !1,
     debounce: typeof (e == null ? void 0 : e.submitOnChange) == "number" ? e.submitOnChange : void 0
-  }), b(e == null ? void 0 : e.resetOnSubmitted), /* @__PURE__ */ l(h, { value: { formId: u, formRef: t, options: e }, children: a });
+  }), b(e == null ? void 0 : e.resetOnSubmitted), /* @__PURE__ */ f(h, { value: { formId: u, formRef: t, options: e }, children: a });
 };
 export {
-  n as default
+  v as default
 };

package/dist/esm/submit/error/setCtxErrorsByFormSubmitFieldErrors.mjs

@@ -0,0 +1,12 @@
+const s = (r, t) => {
+  Object.entries(t).forEach(([e, o]) => {
+    r.setError(e, {
+      type: "FormSubmitFieldError",
+      // default
+      ...o
+    });
+  });
+};
+export {
+  s as default
+};

package/dist/esm/utils/useDebouncedOnChangeValue.mjs

@@ -9,7 +9,7 @@ const a = ({
     e.current && clearTimeout(e.current.timer);
   };
   return r.useEffect(
-    // return clear fn
+    // return timeout clearer
     () => t,
     []
   ), [(o) => {

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

@@ -2,7 +2,7 @@ import { UseFormProps } from 'react-hook-form';
 import { FlatFieldErrorsOutputConfig } from '../../errors/flat/context/FlatFieldErrorsOutputConfig';
 import { RhfUtilsFormOptions } from '../../form/RhfUtilsFormOptions';
 import { UseRhfUtilsFormChildrenProps } from '../../form/UseRhfUtilsFormChildrenProps';
-import { FormSubmitErrors } from '../../submit/error/FormSubmitErrors';
+import { FormSubmitFieldErrors } from '../../submit/error/FormSubmitFieldErrors';
 
 /**
  * Client configuration object.
@@ -51,14 +51,14 @@ export type RhfUtilsClientConfig = {
      * Global submit error handler when/if submit handler throws an error other than {@link FormSubmitError}.
      *
      * Example use case:
-     * - transform API errors to {@link FormSubmitErrors}.
+     * - transform API errors to {@link FormSubmitFieldErrors}.
      *
      * @returns
-     * - if {@link FormSubmitErrors}: merge into context errors.
+     * - if {@link FormSubmitFieldErrors}: merge into context errors.
      * - if `undefined`: do nothing.
      */
-    onSubmitErrorUnknown?: (error: unknown) => FormSubmitErrors | undefined;
-    FieldErrors?: {
+    onSubmitErrorUnknown?: (error: unknown) => FormSubmitFieldErrors | undefined;
+    fieldErrors?: {
         /**
          * Configure how/if errors should be outputted.
          */

package/dist/types/client/zod/context/RhfUtilsClientForZodContextProvider.d.ts

@@ -2,7 +2,7 @@ import { default as React } from 'react';
 import { RhfUtilsClientConfig } from '../../config/RhfUtilsClientConfig';
 
 type Props = React.PropsWithChildren<{
-    config: RhfUtilsClientConfig;
+    config?: RhfUtilsClientConfig;
 }>;
 declare const RhfUtilsClientForZodContextProvider: React.FC<Props>;
 export default RhfUtilsClientForZodContextProvider;

package/dist/types/errors/flat/flattenFieldErrors.d.ts

@@ -1,9 +1,10 @@
 import { FieldErrors } from 'react-hook-form';
 
 /**
- * Only flattens a {@link FieldErrors} object.
+ * Flatten a {@link FieldErrors} object.
+ *
  * @returns e.g.,
- * ```
+ * ```ts
  * {
  *   "address.street.type": "too_short",
  *   "address.street.ref.value": "123",

package/dist/types/errors/message/{FormErrorMessageByPath.d.ts → RhfUtilsFieldErrorMessage.d.ts}

@@ -6,5 +6,5 @@ type Props = {
         message: string;
     }>;
 };
-declare const FormErrorMessageByPath: React.FC<Props>;
-export default FormErrorMessageByPath;
+declare const RhfUtilsFieldErrorMessage: React.FC<Props>;
+export default RhfUtilsFieldErrorMessage;

package/dist/types/errors/trpc/getOnSubmitTrpcClientErrorHandler.d.ts

@@ -1,5 +1,5 @@
 import { RhfUtilsClientConfig } from '../../client/config/RhfUtilsClientConfig';
-import { FormSubmitErrors } from '../../submit/error/FormSubmitErrors';
+import { FormSubmitFieldErrors } from '../../submit/error/FormSubmitFieldErrors';
 
 /**
  * HOF that returns submit error handler for {@link RhfUtilsClientConfig.onSubmitErrorUnknown}.
@@ -7,5 +7,5 @@ import { FormSubmitErrors } from '../../submit/error/FormSubmitErrors';
  * @param onError Fallback for handling non-TRPC errors.
  * @returns FormSubmitError
  */
-declare const getOnSubmitTrpcClientErrorHandler: (onNotTrpcClientError: NonNullable<RhfUtilsClientConfig["onSubmitErrorUnknown"]>) => (error: unknown) => FormSubmitErrors | undefined;
+declare const getOnSubmitTrpcClientErrorHandler: (onNotTrpcClientError: NonNullable<RhfUtilsClientConfig["onSubmitErrorUnknown"]>) => (error: unknown) => FormSubmitFieldErrors | undefined;
 export default getOnSubmitTrpcClientErrorHandler;

package/dist/types/errors/trpc/trpcClientErrorToFormSubmitFieldErrorsSchemaTransformer.d.ts

@@ -0,0 +1,28 @@
+import { TRPCClientErrorLike } from '@trpc/client';
+import { AnyRouter } from '@trpc/server';
+import { z } from 'zod';
+import { FormSubmitFieldErrors } from '../../submit/error/FormSubmitFieldErrors';
+
+/**
+ * Schema that transforms {@link TRPCClientError} to RHF {@link FormSubmitFieldErrors}.
+ */
+declare const trpcClientErrorToFormSubmitFieldErrorsSchemaTransformer: z.ZodEffects<z.ZodEffects<z.ZodPipeline<z.ZodEffects<z.ZodEffects<z.ZodType<TRPCClientErrorLike<AnyRouter>, z.ZodTypeDef, TRPCClientErrorLike<AnyRouter>>, string, TRPCClientErrorLike<AnyRouter>>, unknown, TRPCClientErrorLike<AnyRouter>>, z.ZodArray<z.ZodObject<{
+    validation: z.ZodString;
+    code: z.ZodString;
+    message: z.ZodString;
+    path: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    code: string;
+    path: string[];
+    validation: string;
+}, {
+    message: string;
+    code: string;
+    path: string[];
+    validation: string;
+}>, "many">>, (readonly [string, {
+    type: string;
+    message: string;
+}])[], TRPCClientErrorLike<AnyRouter>>, FormSubmitFieldErrors, TRPCClientErrorLike<AnyRouter>>;
+export default trpcClientErrorToFormSubmitFieldErrorsSchemaTransformer;

package/dist/types/exports.d.ts

@@ -7,11 +7,9 @@ export type { RhfUtilsUseFormChildrenZodFC } from './client/zod/RhfUtilsUseFormC
 export type { RhfUtilsUseFormChildrenZodProps } from './client/zod/RhfUtilsUseFormChildrenZodProps';
 export { default as useFlatFieldErrorsContext } from './errors/flat/context/useFlatFieldErrorsContext';
 export { default as useFlatFieldErrorsContextHasOnlyOrphans } from './errors/flat/context/useFlatFieldErrorsContextHasOnlyOrphans';
-export { default as FormErrorMessageByPath } from './errors/message/FormErrorMessageByPath';
+export { default as RhfUtilsFieldErrorMessage } from './errors/message/RhfUtilsFieldErrorMessage';
 export { default as FormNonFieldErrorMarker } from './errors/nonfield/FormNonFieldErrorMarker';
 export { default as RootErrorsListFromFlatFieldErrorsContext } from './errors/root/RootErrorsListFromFlatFieldErrorsContext';
-export { default as getOnSubmitTrpcClientErrorHandler } from './errors/trpc/getOnSubmitTrpcClientErrorHandler';
-export { default as trpcClientErrorToFormSubmitErrorsSchemaTransformer } from './errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer';
 export type { RhfUtilsFormOptions } from './form/RhfUtilsFormOptions';
 export type { SafeFieldValues } from './form/SafeFieldValues';
 export type { UseRhfUtilsFormChildrenProps } from './form/UseRhfUtilsFormChildrenProps';

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

@@ -23,7 +23,7 @@ export type RhfUtilsFormOptions = {
      * (Lazy-loaded when truthy value supplied.
      * For zero bundle size in prod, be sure to check for dev environment.)
      */
-    devTool?: true | Pick<DevtoolUIProps, 'placement' | 'styles'>;
+    devTool?: boolean | Pick<DevtoolUIProps, 'placement' | 'styles'>;
 } & (Register extends {
     RhfUtilsFormOptions: infer _RhfUtilsFormOptions;
 } ? _RhfUtilsFormOptions : {});

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

@@ -1,6 +1,6 @@
-import { MaybePromise } from '@trpc/server/unstable-core-do-not-import';
 import { default as React } from 'react';
 import { SubmitErrorHandler, UseFormProps } from 'react-hook-form';
+import { MaybePromise } from '../utils/types';
 import { RhfUtilsFormOptions } from './RhfUtilsFormOptions';
 import { SafeFieldValues } from './SafeFieldValues';
 import { UseRhfUtilsFormChildrenProps } from './UseRhfUtilsFormChildrenProps';

package/dist/types/submit/error/FormSubmitError.d.ts

@@ -1,7 +1,7 @@
 import { SafeFieldValues } from '../../form/SafeFieldValues';
-import { FormSubmitErrors } from './FormSubmitErrors';
+import { FormSubmitFieldErrors } from './FormSubmitFieldErrors';
 
 export declare class FormSubmitError<TFieldValues extends SafeFieldValues = SafeFieldValues> extends Error {
-    errors: FormSubmitErrors<TFieldValues>;
-    constructor(errors: FormSubmitErrors<TFieldValues>, message?: string);
+    errors: FormSubmitFieldErrors<TFieldValues>;
+    constructor(errors: FormSubmitFieldErrors<TFieldValues>, message?: string);
 }

package/dist/types/submit/error/{FormSubmitErrors.d.ts → FormSubmitFieldErrors.d.ts}

@@ -9,7 +9,7 @@ import { SafeFieldValues } from '../../form/SafeFieldValues';
  *   - `root` is reserved for special use cases.
  * - simplified `ErrorOption` value.
  */
-export type FormSubmitErrors<TFieldValues extends SafeFieldValues = SafeFieldValues> = Record<FieldPath<TFieldValues> | `root.${string}`, {
+export type FormSubmitFieldErrors<TFieldValues extends SafeFieldValues = SafeFieldValues> = Record<FieldPath<TFieldValues> | `root.${string}`, {
     type?: string;
     message: string;
 }>;

package/dist/types/submit/error/setCtxErrorsByFormSubmitFieldErrors.d.ts

@@ -0,0 +1,10 @@
+import { UseFormReturn } from 'react-hook-form';
+import { SafeFieldValues } from '../../form/SafeFieldValues';
+import { FormSubmitFieldErrors } from './FormSubmitFieldErrors';
+
+/**
+ * Handle thrown {@link FormSubmitError}.
+ * Add key/values as name/message to RHF context errors.
+ */
+declare const setCtxErrorsByFormSubmitFieldErrors: <TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>(ctx: UseFormReturn<TFieldValues, unknown, TTransformedValues>, errors: FormSubmitFieldErrors) => void;
+export default setCtxErrorsByFormSubmitFieldErrors;

package/dist/types/submit/useFormOnSubmitSuccessfulAndReset.d.ts

@@ -1,4 +1,4 @@
-import { MaybePromise } from '@trpc/server/unstable-core-do-not-import';
+import { MaybePromise } from '../utils/types';
 
 /**
  * Calls a callback after a successful submit and after a form reset.

package/dist/types/submit/useFormOnSubmitted.d.ts

@@ -1,4 +1,4 @@
-import { MaybePromise } from '@trpc/server/unstable-core-do-not-import';
+import { MaybePromise } from '../utils/types';
 
 declare const useFormOnSubmitted: (callback?: (success: boolean) => MaybePromise<unknown>, options?: {
     successful?: boolean;

package/dist/types/utils/timeoutAsync.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Awaitable `setTimeout`.
+ * @param timeout milliseconds
+ * @returns `Promise<void>`
+ */
+export declare const timeoutAsync: (timeout: number) => Promise<void>;

package/package.json

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

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

@@ -1,14 +0,0 @@
-import { jsxs as n, Fragment as a, jsx as e } from "react/jsx-runtime";
-import { useFormState as g, get as i } from "react-hook-form";
-import F from "../nonfield/FormNonFieldErrorMarker.mjs";
-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(m, { message: r.message }),
-    /* @__PURE__ */ e(F, { path: o })
-  ] }) : null;
-}, E = f;
-export {
-  E as default
-};

package/dist/esm/errors/trpc/getOnSubmitTrpcClientErrorHandler.mjs

@@ -1,6 +0,0 @@
-import { TRPCClientError as n } from "@trpc/client";
-import e from "./trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs";
-const o = (t) => (r) => r instanceof n ? e.parse(r) : t(r), a = o;
-export {
-  a as default
-};

package/dist/esm/errors/trpc/trpcClientErrorMessageSchema.mjs

@@ -1,10 +0,0 @@
-import { z as r } from "zod";
-const a = r.object({
-  validation: r.string(),
-  code: r.string(),
-  message: r.string(),
-  path: r.array(r.string())
-});
-export {
-  a as default
-};

package/dist/esm/errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs

@@ -1,34 +0,0 @@
-import { TRPCClientError as o } from "@trpc/client";
-import { z as e } from "zod";
-import a from "./trpcClientErrorMessageSchema.mjs";
-const i = e.custom(
-  (r) => r instanceof o
-  // check instance type
-).transform((r) => r.message).transform((r) => {
-  try {
-    return JSON.parse(r);
-  } catch {
-    return [
-      {
-        validation: "root",
-        code: "server",
-        message: r,
-        path: ["root"]
-      }
-    ];
-  }
-}).pipe(e.array(a)).transform(
-  (r) => r.map(
-    (t) => [
-      t.path.join("."),
-      // flatten path (e.g., "street.name")
-      {
-        type: t.code,
-        message: t.message
-      }
-    ]
-  )
-).transform((r) => Object.fromEntries(r));
-export {
-  i as default
-};

package/dist/esm/submit/error/setCtxErrorsByFormSubmitErrors.mjs

@@ -1,12 +0,0 @@
-const s = (r, t) => {
-  Object.entries(t).forEach(([o, e]) => {
-    r.setError(o, {
-      type: "FormSubmitError",
-      // default
-      ...e
-    });
-  });
-};
-export {
-  s as default
-};

package/dist/types/errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer.d.ts

@@ -1,28 +0,0 @@
-import { TRPCClientErrorLike } from '@trpc/client';
-import { AnyRouter } from '@trpc/server';
-import { z } from 'zod';
-import { FormSubmitErrors } from '../../submit/error/FormSubmitErrors';
-
-/**
- * Schema that transforms {@link TRPCClientError} to RHF {@link FormSubmitErrors}.
- */
-declare const trpcClientErrorToFormSubmitErrorsSchemaTransformer: z.ZodEffects<z.ZodEffects<z.ZodPipeline<z.ZodEffects<z.ZodEffects<z.ZodType<TRPCClientErrorLike<AnyRouter>, z.ZodTypeDef, TRPCClientErrorLike<AnyRouter>>, string, TRPCClientErrorLike<AnyRouter>>, unknown, TRPCClientErrorLike<AnyRouter>>, z.ZodArray<z.ZodObject<{
-    validation: z.ZodString;
-    code: z.ZodString;
-    message: z.ZodString;
-    path: z.ZodArray<z.ZodString, "many">;
-}, "strip", z.ZodTypeAny, {
-    message: string;
-    code: string;
-    path: string[];
-    validation: string;
-}, {
-    message: string;
-    code: string;
-    path: string[];
-    validation: string;
-}>, "many">>, (readonly [string, {
-    type: string;
-    message: string;
-}])[], TRPCClientErrorLike<AnyRouter>>, FormSubmitErrors, TRPCClientErrorLike<AnyRouter>>;
-export default trpcClientErrorToFormSubmitErrorsSchemaTransformer;

package/dist/types/submit/error/setCtxErrorsByFormSubmitErrors.d.ts

@@ -1,10 +0,0 @@
-import { UseFormReturn } from 'react-hook-form';
-import { SafeFieldValues } from '../../form/SafeFieldValues';
-import { FormSubmitErrors } from './FormSubmitErrors';
-
-/**
- * Handle thrown {@link FormSubmitError}.
- * Add key/values as name/message to RHF context errors.
- */
-declare const setCtxErrorsByFormSubmitErrors: <TFieldValues extends SafeFieldValues, TTransformedValues extends SafeFieldValues>(ctx: UseFormReturn<TFieldValues, unknown, TTransformedValues>, errors: FormSubmitErrors) => void;
-export default setCtxErrorsByFormSubmitErrors;