@paragrav/rhf-utils 0.0.134 → 0.0.135

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present paragrav.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,7 +4,7 @@
 
 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.
+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.
 
 ## Features
 
@@ -18,11 +18,11 @@ If you have multiple forms and would like a more declarative API to manage their
 - 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`)
+- simpler/flatter `FieldErrors` structure (`FlatFieldErrors`)
+  - context groups errors into `all`, `fields`, `roots`, and `orphans` (`useFlatFieldErrorsContext`)
+  - `FormErrorMessageByPath` for displaying error message
 - `zod` support
-  - including `z.input` and `z.output` types for transformations
+  - including input/output types for transformations
 - safer `FieldValues` type (`SafeFieldValues`)
 - 3.3kB min+gzip core functionality (excluding [peer dependencies](#peer-dependencies))
 
@@ -221,12 +221,12 @@ 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>) { }
 ```
 
-## Component Hierarchy
+## Form Component Hierarchy
 
 ```tsx
 <ReactHookForm.FormProvider>
@@ -242,7 +242,7 @@ function Children({...}: RhfUtilsUseFormChildrenZodProps<typeof schema>) { }
 
 ## `FormSubmitError`
 
-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`.
+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`.
 
 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.
 
@@ -262,7 +262,7 @@ Example:
 />
 ```
 
-Any non-`FormSubmitError`s thrown from 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 in RHF's context 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 `FormSubmitErrors` 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.)
 
@@ -272,7 +272,7 @@ These options can be set globally and/or per form.
 
 ```ts
 type RhfUtilsFormOptions = {
-  /** Stop propagation of submit event. Useful for portals. */
+  /** Stop propagation of submit event. */
   stopSubmitPropagation?: boolean;
 
   /** Request submit via listener on form change. */
@@ -293,7 +293,7 @@ type RhfUtilsFormOptions = {
 };
 ```
 
-If you need access to options deeper in component structure, use `useRhfUtilsContext` to receive `RhfUtilsContext` object, which includes `formId`, `formRef`, and `options` settings.
+If you need access to options deeper in your component structure, use `useRhfUtilsContext` to receive `RhfUtilsContext` object, which includes `formId`, `formRef`, and `options` settings.
 
 Use `useRhfUtilsContextRequestSubmit` hook to get `requestSubmit` function for current form ref in context. This is useful when you need to trigger form submission programatically.
 
@@ -314,39 +314,56 @@ declare module '@paragrav/rhf-utils' {
 }
 ```
 
-## Errors
+## Field Errors
 
-You can configure via `RhfUtilsClientConfig` (example at the top) when form context errors are outputted -- i.e., via console and/or thrown error.
+### FlatFieldErrors
+
+`FlatFieldErrors` type is a flattened, simplified version of RHF's `FieldErrors`. Keys represent flattened, dot-notation field paths.
 
 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.
+### 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).
 
 ### 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.
+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 criteria for an orphan is any form context error that meets all of the following criteria:
+More technically, an "orphan" is any form state 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`)
+- 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
 
-To get accurate orphan analysis, you must either use `FormNonFieldErrorMarker` in any error you are displaying to user that 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.)
+Detected orphans can be accessed via any of the following:
 
-Alternatively, you can use `FormErrorMessageByPath` to display error message to user:
+- 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
+- `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`
 
-```tsx
-<FormErrorMessageByPath path="street.address" />
-```
+### FormNonFieldErrorMarker
 
-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.
+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.)
 
-Orphans are exposed in a few places.
+#### When is the marker required?
 
-- In errors outputted via console. (Configurable via `RhfUtilsClientConfig['errors']['output']`.)
-- 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`.
+For example, a field array with a minimum number of items -- e.g., `items: z.array(...).min(1)`.
+
+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`.
+
+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.
+
+```tsx
+<FormErrorMessageByPath path="items" />
+```
 
 ## Form Groups
 

package/dist/esm/client/utils.mjs

@@ -1,30 +1,39 @@
-const i = (l, ...t) => (
+const u = (n, ...r) => (
   // sequentially merge each set of props into defaults
-  t.reduce(
-    (s, e) => {
-      var f, o;
+  r.reduce(
+    (t, e) => {
+      var s, i, l, m, o, f;
       return {
         rhf: {
-          ...s == null ? void 0 : s.rhf,
+          ...t == null ? void 0 : t.rhf,
           ...e.rhf
         },
         utils: {
-          ...s == null ? void 0 : s.utils,
-          ...e.utils
+          ...t == null ? void 0 : t.utils,
+          ...e.utils,
+          // manual merges
+          // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- false positive
+          ...(((s = t == null ? void 0 : t.utils) == null ? void 0 : s.resetOnSubmitted) || ((i = e.utils) == null ? void 0 : i.resetOnSubmitted)) && {
+            resetOnSubmitted: {
+              ...(l = t == null ? void 0 : t.utils) == null ? void 0 : l.resetOnSubmitted,
+              ...(m = e.utils) == null ? void 0 : m.resetOnSubmitted
+            }
+          }
         },
         form: {
-          ...s == null ? void 0 : s.form,
+          ...t == null ? void 0 : t.form,
           ...e.form,
-          className: [(f = s == null ? void 0 : s.form) == null ? void 0 : f.className, (o = e.form) == null ? void 0 : o.className].filter(Boolean).join(" ")
-          // stringify
+          // manual merges
+          className: [(o = t == null ? void 0 : t.form) == null ? void 0 : o.className, (f = e.form) == null ? void 0 : f.className].filter(Boolean).join(" ") || void 0
+          // stringify (replace empty string with undefined)
         }
       };
     },
     // start with defaults
-    l
+    n
   )
 );
 export {
-  i as mergeRhfUtilsClientConfigDefaultsWithUseRhfUtilsFormProps
+  u as mergeRhfUtilsClientConfigDefaultsWithUseRhfUtilsFormProps
 };
 //# sourceMappingURL=utils.mjs.map

package/dist/esm/client/utils.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"utils.mjs","sources":["../../../src/client/utils.ts"],"sourcesContent":["import type { RhfUtilsFormOptions } from '@/form/RhfUtilsFormOptions';\nimport type { SafeFieldValues } from '@/form/SafeFieldValues';\nimport type { UseRhfUtilsFormProps } from '@/form/UseRhfUtilsFormProps';\n\nimport type { RhfUtilsClientConfig } from './config/RhfUtilsClientConfig';\n\n/**\n * Merge {@link RhfUtilsClientConfig.defaults} with array of {@link UseRhfUtilsFormProps}'s overrides.\n */\nexport const mergeRhfUtilsClientConfigDefaultsWithUseRhfUtilsFormProps = <\n  TFieldValues extends SafeFieldValues,\n  TTransformedValues extends SafeFieldValues,\n>(\n  defaults: RhfUtilsClientConfig['defaults'],\n  ...props: Pick<\n    UseRhfUtilsFormProps<TFieldValues, TTransformedValues>,\n    'rhf' | 'utils' | 'form'\n  >[]\n) =>\n  // sequentially merge each set of props into defaults\n  props.reduce(\n    (acc, curr) => ({\n      rhf: {\n        ...acc?.rhf,\n        ...curr.rhf,\n      },\n\n      utils: {\n        ...acc?.utils,\n        ...curr.utils,\n      } satisfies RhfUtilsFormOptions,\n\n      form: {\n        ...acc?.form,\n        ...curr.form,\n        className: [acc?.form?.className, curr.form?.className]\n          .filter(Boolean) // filter out falsy values\n          .join(' '), // stringify\n      },\n    }),\n\n    // start with defaults\n    defaults,\n  );\n"],"names":["mergeRhfUtilsClientConfigDefaultsWithUseRhfUtilsFormProps","defaults","props","acc","curr","_a","_b"],"mappings":"AASa,MAAAA,IAA4D,CAIvEC,MACGC;AAAA;AAAA,EAMHA,EAAM;AAAA,IACJ,CAACC,GAAKC,MAAU;AAZP,UAAAC,GAAAC;AAYO;AAAA,QACd,KAAK;AAAA,UACH,GAAGH,KAAA,gBAAAA,EAAK;AAAA,UACR,GAAGC,EAAK;AAAA,QACV;AAAA,QAEA,OAAO;AAAA,UACL,GAAGD,KAAA,gBAAAA,EAAK;AAAA,UACR,GAAGC,EAAK;AAAA,QACV;AAAA,QAEA,MAAM;AAAA,UACJ,GAAGD,KAAA,gBAAAA,EAAK;AAAA,UACR,GAAGC,EAAK;AAAA,UACR,WAAW,EAACC,IAAAF,KAAA,gBAAAA,EAAK,SAAL,gBAAAE,EAAW,YAAWC,IAAAF,EAAK,SAAL,gBAAAE,EAAW,SAAS,EACnD,OAAO,OAAO,EACd,KAAK,GAAG;AAAA;AAAA,QACb;AAAA,MAAA;AAAA;AAAA;AAAA,IAIFL;AAAA,EACF;AAAA;"}
+{"version":3,"file":"utils.mjs","sources":["../../../src/client/utils.ts"],"sourcesContent":["import type { RhfUtilsFormOptions } from '@/form/RhfUtilsFormOptions';\nimport type { SafeFieldValues } from '@/form/SafeFieldValues';\nimport type { UseRhfUtilsFormProps } from '@/form/UseRhfUtilsFormProps';\n\nimport type { RhfUtilsClientConfig } from './config/RhfUtilsClientConfig';\n\n/**\n * Merge {@link RhfUtilsClientConfig.defaults} with array of {@link UseRhfUtilsFormProps}'s overrides.\n */\nexport const mergeRhfUtilsClientConfigDefaultsWithUseRhfUtilsFormProps = <\n  TFieldValues extends SafeFieldValues,\n  TTransformedValues extends SafeFieldValues,\n>(\n  defaults: RhfUtilsClientConfig['defaults'],\n  ...props: Pick<\n    UseRhfUtilsFormProps<TFieldValues, TTransformedValues>,\n    'rhf' | 'utils' | 'form'\n  >[]\n) =>\n  // sequentially merge each set of props into defaults\n  props.reduce(\n    (acc, curr) => ({\n      rhf: {\n        ...acc?.rhf,\n        ...curr.rhf,\n      },\n\n      utils: {\n        ...acc?.utils,\n        ...curr.utils,\n\n        // manual merges\n\n        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- false positive\n        ...((acc?.utils?.resetOnSubmitted || curr.utils?.resetOnSubmitted) && {\n          resetOnSubmitted: {\n            ...acc?.utils?.resetOnSubmitted,\n            ...curr.utils?.resetOnSubmitted,\n          },\n        }),\n      } satisfies RhfUtilsFormOptions,\n\n      form: {\n        ...acc?.form,\n        ...curr.form,\n\n        // manual merges\n\n        className:\n          [acc?.form?.className, curr.form?.className]\n            .filter(Boolean) // filter out falsy values\n            .join(' ') || undefined, // stringify (replace empty string with undefined)\n      },\n    }),\n\n    // start with defaults\n    defaults,\n  );\n"],"names":["mergeRhfUtilsClientConfigDefaultsWithUseRhfUtilsFormProps","defaults","props","acc","curr","_a","_b","_c","_d","_e","_f"],"mappings":"AASa,MAAAA,IAA4D,CAIvEC,MACGC;AAAA;AAAA,EAMHA,EAAM;AAAA,IACJ,CAACC,GAAKC,MAAU;AAZP,UAAAC,GAAAC,GAAAC,GAAAC,GAAAC,GAAAC;AAYO;AAAA,QACd,KAAK;AAAA,UACH,GAAGP,KAAA,gBAAAA,EAAK;AAAA,UACR,GAAGC,EAAK;AAAA,QACV;AAAA,QAEA,OAAO;AAAA,UACL,GAAGD,KAAA,gBAAAA,EAAK;AAAA,UACR,GAAGC,EAAK;AAAA;AAAA;AAAA,UAKR,MAAKC,IAAAF,KAAA,gBAAAA,EAAK,UAAL,gBAAAE,EAAY,uBAAoBC,IAAAF,EAAK,UAAL,gBAAAE,EAAY,sBAAqB;AAAA,YACpE,kBAAkB;AAAA,cAChB,IAAGC,IAAAJ,KAAA,gBAAAA,EAAK,UAAL,gBAAAI,EAAY;AAAA,cACf,IAAGC,IAAAJ,EAAK,UAAL,gBAAAI,EAAY;AAAA,YACjB;AAAA,UACF;AAAA,QACF;AAAA,QAEA,MAAM;AAAA,UACJ,GAAGL,KAAA,gBAAAA,EAAK;AAAA,UACR,GAAGC,EAAK;AAAA;AAAA,UAIR,WACE,EAACK,IAAAN,KAAA,gBAAAA,EAAK,SAAL,gBAAAM,EAAW,YAAWC,IAAAN,EAAK,SAAL,gBAAAM,EAAW,SAAS,EACxC,OAAO,OAAO,EACd,KAAK,GAAG,KAAK;AAAA;AAAA,QACpB;AAAA,MAAA;AAAA;AAAA;AAAA,IAIFT;AAAA,EACF;AAAA;"}

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

@@ -8,7 +8,7 @@ import { Register } from '../register';
  * Can be extended using {@link Register.RhfUtilsFormOptions}.
  */
 export type RhfUtilsFormOptions = {
-    /** Stop propagation of submit event. Useful for portals. */
+    /** Stop propagation of submit event. */
     stopSubmitPropagation?: boolean;
     /** Request submit via listener on form change. */
     submitOnChange?: boolean;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@paragrav/rhf-utils",
   "author": "paragrav.dev",
   "license": "MIT",
-  "version": "0.0.134",
+  "version": "0.0.135",
   "description": "Integration utilities for react-hook-form.",
   "type": "module",
   "sideEffects": false,
@@ -30,6 +30,10 @@
     "react-hook-form": "7",
     "zod": "3"
   },
+  "resolutions": {
+    "@playwright/experimental-ct-react": "1.44.1",
+    "@playwright/test": "1.44.1"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/paragrav/rhf-utils.git"