@paragrav/rhf-utils 0.0.110 → 0.0.112

package/README.md

@@ -34,7 +34,7 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
   FormComponent: Form.Root,
 
   // transform backend error
-  // use `getOnSubmitTrpcClientErrorHandler` for TRPC backends
+  // use `getOnSubmitTrpcClientErrorHandler` HOF for TRPC backends
   onSubmitError: (
     error, // unknown
   ) => {
@@ -117,7 +117,7 @@ Currently, only `zod` is supported.
   }) => {
     onError(error);
   }}
-  // children/fields
+  // fields
   Children={({
     // UseRhfUtilsFormChildrenProps
     formId, //     unique id string
@@ -130,13 +130,10 @@ Currently, only `zod` is supported.
       <Controller
         name="email" // strongly-typed field name
         render={({ field, formState: { isSubmitting } }) => (
-          <input
-            autoFocus
-            label="Email"
-            autoComplete="email"
-            disabled={isSubmitting}
-            {...field}
-          />
+          <label>
+            Email
+            <input {...field} disabled={isSubmitting} />
+          </label>
         )}
       />
 
@@ -151,7 +148,9 @@ Currently, only `zod` is supported.
 If you prefer to define your `Children` component as standalone:
 
 ```tsx
-const Children: RhfUtilsUseFormChildrenZodFC<typeof schema> = () => {};
+const Children: RhfUtilsUseFormChildrenZodFC<typeof schema> = ({ ... }) => { };
+
+function Children({...}: RhfUtilsUseFormChildrenZodProps<typeof schema>) { }
 ```
 
 ## `RhfUtilsFormOptions`
@@ -201,3 +200,59 @@ declare module '@paragrav/rhf-utils' {
   }
 }
 ```
+
+## Errors
+
+You can configure via `RhfUtilsClientConfig` (example at the top) when form context errors are outputted -- i.e., via console and/or thrown error.
+
+### Orphans
+
+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.
+
+The criteria for an orphan is any form context error that meets all of the following criteria:
+
+- not a root error -- e.g., `root` or `root.${string}`
+- has no `ref` -- RHF includes `ref` to the associated input on each error object (when applicable)
+- has no marker in DOM (e.g., `FormNonFieldErrorMarker`)
+
+To get accurate orphan analysis, you must either use `FormNonFieldErrorMarker` in any error you are displaying to user which is not "root" and doesn't have a `ref`. (There is no harm in using this consistently across all errors, even those expected to have a ref.)
+
+Alternatively, you can use `FormErrorMessageByPath` to display error message to user:
+
+```tsx
+<FormErrorMessageByPath path="street.address" />
+```
+
+Example use case: Field array with minimum items. (When there are no items, the error is not associated with a field and is displayed separately.)
+
+Orphans are optionally exposed in a few places.
+
+- In errors outputted via console.
+- And `useFlatFieldErrorsContext()` hook, which returns an object with divided into `all`, `root`, and `orphans` errors.
+
+`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.
+
+Use case: disable parent form when any child is "busy"; disable all children when parent is "busy".
+
+Use `FormGroupContextProvider` to wrap your children and parent forms.
+
+```tsx
+<FormGroupContextProvider>
+  <ChildForm1 />
+  <ChildForm2 />
+  <ParentForm />
+</FormGroupContextProvider>
+```
+
+In your parent form, use the hook `useFormGroupParentTracker`, which returns `boolean` value indicating whether any child forms is busy.
+
+In children forms, there are two options. You can choose to consider form "busy" when:
+
+- `isSubmitting` is `true` by using `useFormGroupChildIsSubmittingTracker` hook
+- it is mounted by using `useFormGroupChildIsMountedTracker` hook
+
+Both hooks return `boolean` value indicating whether parent form is busy.

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

@@ -2,13 +2,13 @@ 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 p = ({ path: o, ...s }) => {
-  const { errors: m } = g(), r = i(m, o, void 0), t = s.Component ?? c;
-  return /* @__PURE__ */ n(a, { children: [
+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 }),
-    (r == null ? void 0 : r.message) && /* @__PURE__ */ e(t, { message: r.message })
-  ] });
-}, l = p;
+    /* @__PURE__ */ e(m, { message: r.message })
+  ] }) : null;
+}, E = f;
 export {
-  l as default
+  E as default
 };

package/dist/esm/src/form/context/group/useFormGroupChildIsMountedTracker.mjs

@@ -1,7 +1,6 @@
 import r from "./useFormGroupChildTracker.mjs";
-const o = () => {
-  r(!0);
-}, u = o;
+import o from "./useFormGroupIsParentBusy.mjs";
+const e = () => (r(!0), o()), t = e;
 export {
-  u as default
+  t as default
 };

package/dist/esm/src/form/context/group/useFormGroupChildIsSubmittingTracker.mjs

@@ -1,9 +1,10 @@
 import { useFormState as o } from "react-hook-form";
 import t from "./useFormGroupChildTracker.mjs";
-const i = () => {
+import u from "./useFormGroupIsParentBusy.mjs";
+const m = () => {
   const { isSubmitting: r } = o();
-  t(r);
-}, u = i;
+  return t(r), u();
+}, n = m;
 export {
-  u as default
+  n as default
 };

package/dist/esm/src/form/context/group/useFormGroupIsParentBusy.mjs

@@ -2,7 +2,7 @@ import { _useFormGroupContextMaybe as o } from "./index.mjs";
 const s = () => {
   const r = o();
   return !!(r != null && r.parent.isBusy);
-}, t = s;
+};
 export {
-  t as default
+  s as default
 };

package/dist/esm/src/form/context/group/useFormGroupParentTracker.mjs

@@ -1,12 +1,13 @@
 import s from "react";
 import t from "../../useFormIsBusy.mjs";
 import { _useFormGroupContext as e } from "./index.mjs";
-const u = () => {
+import u from "./useFormGroupIsChildBusy.mjs";
+const m = () => {
   const r = t(), { setIsBusy: o } = e().parent;
-  s.useEffect(() => {
+  return s.useEffect(() => {
     o(r);
-  }, [o, r]);
-}, n = u;
+  }, [o, r]), u();
+}, f = m;
 export {
-  n as default
+  f as default
 };

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

@@ -8,9 +8,15 @@ import { FlatFieldErrors } from './types';
  * @param errors {@link FieldErrors} object.
  * @returns FlatFieldErrors object.
  *
- * e.g.,
+ * @example
  * ```
- * [ "address.street", { "address.street": { type: "too_short", ref: { value: "123" }, message: "Required." } } ]
+ * {
+ *   "address.street": {
+ *     type: "too_short",
+ *     ref: { value: "123" },
+ *     message: "Required." }
+ *   }
+ * }
  * ```
  */
 declare const getFlatFieldErrors: (errors: FieldErrors) => FlatFieldErrors;

package/dist/types/errors/nonfield/FormNonFieldErrorMarker.d.ts

@@ -5,6 +5,10 @@ type Props = {
 };
 /**
  * Empty, hidden marker to indicate a non-field/non-root error is being displayed to user.
+ *
+ * Example use case:
+ * Field array with minimum items.
+ * (When there are no items, the error is not associated with a field and is displayed separately.)
  */
 declare const FormNonFieldErrorMarker: React.FC<Props>;
 export default FormNonFieldErrorMarker;

package/dist/types/form/context/group/useFormGroupChildIsMountedTracker.d.ts

@@ -1,5 +1,5 @@
 /**
  * Mark "child" form as "busy" when mounted.
  */
-declare const useFormGroupChildIsMountedTracker: () => void;
+declare const useFormGroupChildIsMountedTracker: () => boolean;
 export default useFormGroupChildIsMountedTracker;

package/dist/types/form/context/group/useFormGroupChildIsSubmittingTracker.d.ts

@@ -1,5 +1,5 @@
 /**
  * Mark "child" form as "busy" when submitting.
  */
-declare const useFormGroupChildIsSubmittingTracker: () => void;
+declare const useFormGroupChildIsSubmittingTracker: () => boolean;
 export default useFormGroupChildIsSubmittingTracker;

package/dist/types/form/context/group/useFormGroupParentTracker.d.ts

@@ -3,5 +3,5 @@
  *
  * Requires usage of provider.
  */
-declare const useFormGroupParentTracker: () => void;
+declare const useFormGroupParentTracker: () => boolean;
 export default useFormGroupParentTracker;

package/package.json

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