@paragrav/rhf-utils 0.0.110 → 0.0.111

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
   ) => {
@@ -201,3 +201,34 @@ 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="phone" />
+```
+
+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.

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/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/package.json

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