@paragrav/rhf-utils 0.0.134 → 0.0.136

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +53 -32
  3. package/dist/esm/client/config/useRhfUtilsClientConfigContext.mjs +0 -1
  4. package/dist/esm/client/index.mjs +0 -1
  5. package/dist/esm/client/utils.mjs +21 -13
  6. package/dist/esm/client/zod/context/RhfUtilsClientForZodContextProvider.mjs +0 -1
  7. package/dist/esm/client/zod/context/RhfUtilsZodForm.mjs +0 -1
  8. package/dist/esm/client/zod/context/useRhfUtilsClientForZodContext.mjs +0 -1
  9. package/dist/esm/client/zod/context/useRhfUtilsZodForm.mjs +0 -1
  10. package/dist/esm/client/zod/createRhfUtilsClientForZod.mjs +0 -1
  11. package/dist/esm/devtool/LazyDevTool.mjs +0 -1
  12. package/dist/esm/errors/flat/FlatFieldErrorsList.mjs +0 -1
  13. package/dist/esm/errors/flat/context/FlatFieldErrorsContextProvider.mjs +0 -1
  14. package/dist/esm/errors/flat/context/useFlatFieldErrorsContext.mjs +0 -1
  15. package/dist/esm/errors/flat/context/useFlatFieldErrorsContextHasOnlyOrphans.mjs +0 -1
  16. package/dist/esm/errors/flat/context/useFlatFieldErrorsContextOutput.mjs +0 -1
  17. package/dist/esm/errors/flat/filterFlatFieldErrors.mjs +0 -1
  18. package/dist/esm/errors/flat/flattenFieldErrors.mjs +0 -1
  19. package/dist/esm/errors/flat/getFlatFieldErrors.mjs +0 -1
  20. package/dist/esm/errors/getRefdFromFlatFieldErrors.mjs +0 -1
  21. package/dist/esm/errors/isFieldErrorRefd.mjs +0 -1
  22. package/dist/esm/errors/isFlatFieldErrorEntryRefd.mjs +0 -1
  23. package/dist/esm/errors/message/FormErrorMessage.mjs +0 -1
  24. package/dist/esm/errors/message/FormErrorMessageByPath.mjs +0 -1
  25. package/dist/esm/errors/nonfield/FormNonFieldErrorMarker.mjs +0 -1
  26. package/dist/esm/errors/nonfield/FormNonFieldErrorMarker.utils.mjs +0 -1
  27. package/dist/esm/errors/nonfield/FormNonFieldErrorMarkerHtmlAttribute.mjs +0 -1
  28. package/dist/esm/errors/nonfield/isNonFieldErrorMarkerInDOM.mjs +0 -1
  29. package/dist/esm/errors/orphan/getIsOrphanFormErrorWithParentElement.mjs +0 -1
  30. package/dist/esm/errors/orphan/getOrphansFromFlatFieldErrors.mjs +0 -1
  31. package/dist/esm/errors/orphan/isOrphanFormError.mjs +0 -1
  32. package/dist/esm/errors/output/consoleErrors.mjs +0 -1
  33. package/dist/esm/errors/root/RootErrorsListFromFlatFieldErrorsContext.mjs +0 -1
  34. package/dist/esm/errors/root/consts.mjs +0 -1
  35. package/dist/esm/errors/root/getRootsFromFlatFieldErrors.mjs +0 -1
  36. package/dist/esm/errors/root/isFlatFieldErrorEntryPathRoot.mjs +0 -1
  37. package/dist/esm/errors/root/isFormErrorPathRoot.mjs +0 -1
  38. package/dist/esm/errors/trpc/getOnSubmitTrpcClientErrorHandler.mjs +0 -1
  39. package/dist/esm/errors/trpc/trpcClientErrorMessageSchema.mjs +0 -1
  40. package/dist/esm/errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs +0 -1
  41. package/dist/esm/exports.mjs +0 -1
  42. package/dist/esm/form/Form.mjs +0 -1
  43. package/dist/esm/form/FormWithProviders.mjs +0 -1
  44. package/dist/esm/form/RhfUtilsFormProviders.mjs +0 -1
  45. package/dist/esm/form/_Controller.mjs +0 -1
  46. package/dist/esm/form/context/group/FormGroupContextProvider.mjs +0 -1
  47. package/dist/esm/form/context/group/index.mjs +0 -1
  48. package/dist/esm/form/context/group/useFormGroupChildIsMountedTracker.mjs +0 -1
  49. package/dist/esm/form/context/group/useFormGroupChildIsSubmittingTracker.mjs +0 -1
  50. package/dist/esm/form/context/group/useFormGroupChildTracker.mjs +0 -1
  51. package/dist/esm/form/context/group/useFormGroupIsAnyBusy.mjs +0 -1
  52. package/dist/esm/form/context/group/useFormGroupIsChildBusy.mjs +0 -1
  53. package/dist/esm/form/context/group/useFormGroupIsParentBusy.mjs +0 -1
  54. package/dist/esm/form/context/group/useFormGroupParentTracker.mjs +0 -1
  55. package/dist/esm/form/context/group/useFormOrParentIsBusy.mjs +0 -1
  56. package/dist/esm/form/context/utils/RhfUtilsContextProvider.mjs +13 -12
  57. package/dist/esm/form/context/utils/useRhfUtilsContext.mjs +0 -1
  58. package/dist/esm/form/context/utils/useRhfUtilsContextRequestSubmit.mjs +0 -1
  59. package/dist/esm/form/useFormIsBusy.mjs +0 -1
  60. package/dist/esm/form/useRhfUtilsForm.mjs +0 -1
  61. package/dist/esm/form/utils/getSubmitterButtonData.mjs +0 -1
  62. package/dist/esm/form/utils/useFormRequestSubmit.mjs +9 -6
  63. package/dist/esm/submit/error/FormSubmitError.mjs +0 -1
  64. package/dist/esm/submit/error/setCtxErrorsByFormSubmitErrors.mjs +0 -1
  65. package/dist/esm/submit/useFormOnSubmitted.mjs +0 -1
  66. package/dist/esm/submit/useResetFormOnSubmitted.mjs +0 -1
  67. package/dist/esm/submit/useSubmitFormOnChange.mjs +18 -12
  68. package/dist/esm/utils/PassthroughChildren.mjs +0 -1
  69. package/dist/esm/utils/createContext.mjs +0 -1
  70. package/dist/esm/utils/isEmptyObject.mjs +0 -1
  71. package/dist/esm/utils/useDebouncedOnChangeValue.mjs +26 -0
  72. package/dist/esm/utils/useRefIfValueWasTrue.mjs +0 -1
  73. package/dist/types/form/RhfUtilsFormOptions.d.ts +7 -3
  74. package/dist/types/form/utils/useFormRequestSubmit.d.ts +5 -0
  75. package/dist/types/submit/useSubmitFormOnChange.d.ts +3 -1
  76. package/dist/types/utils/useDebouncedOnChangeValue.d.ts +14 -0
  77. package/package.json +5 -1
  78. package/dist/esm/client/config/useRhfUtilsClientConfigContext.mjs.map +0 -1
  79. package/dist/esm/client/index.mjs.map +0 -1
  80. package/dist/esm/client/utils.mjs.map +0 -1
  81. package/dist/esm/client/zod/context/RhfUtilsClientForZodContextProvider.mjs.map +0 -1
  82. package/dist/esm/client/zod/context/RhfUtilsZodForm.mjs.map +0 -1
  83. package/dist/esm/client/zod/context/useRhfUtilsClientForZodContext.mjs.map +0 -1
  84. package/dist/esm/client/zod/context/useRhfUtilsZodForm.mjs.map +0 -1
  85. package/dist/esm/client/zod/createRhfUtilsClientForZod.mjs.map +0 -1
  86. package/dist/esm/devtool/LazyDevTool.mjs.map +0 -1
  87. package/dist/esm/errors/flat/FlatFieldErrorsList.mjs.map +0 -1
  88. package/dist/esm/errors/flat/context/FlatFieldErrorsContextProvider.mjs.map +0 -1
  89. package/dist/esm/errors/flat/context/useFlatFieldErrorsContext.mjs.map +0 -1
  90. package/dist/esm/errors/flat/context/useFlatFieldErrorsContextHasOnlyOrphans.mjs.map +0 -1
  91. package/dist/esm/errors/flat/context/useFlatFieldErrorsContextOutput.mjs.map +0 -1
  92. package/dist/esm/errors/flat/filterFlatFieldErrors.mjs.map +0 -1
  93. package/dist/esm/errors/flat/flattenFieldErrors.mjs.map +0 -1
  94. package/dist/esm/errors/flat/getFlatFieldErrors.mjs.map +0 -1
  95. package/dist/esm/errors/getRefdFromFlatFieldErrors.mjs.map +0 -1
  96. package/dist/esm/errors/isFieldErrorRefd.mjs.map +0 -1
  97. package/dist/esm/errors/isFlatFieldErrorEntryRefd.mjs.map +0 -1
  98. package/dist/esm/errors/message/FormErrorMessage.mjs.map +0 -1
  99. package/dist/esm/errors/message/FormErrorMessageByPath.mjs.map +0 -1
  100. package/dist/esm/errors/nonfield/FormNonFieldErrorMarker.mjs.map +0 -1
  101. package/dist/esm/errors/nonfield/FormNonFieldErrorMarker.utils.mjs.map +0 -1
  102. package/dist/esm/errors/nonfield/FormNonFieldErrorMarkerHtmlAttribute.mjs.map +0 -1
  103. package/dist/esm/errors/nonfield/isNonFieldErrorMarkerInDOM.mjs.map +0 -1
  104. package/dist/esm/errors/orphan/getIsOrphanFormErrorWithParentElement.mjs.map +0 -1
  105. package/dist/esm/errors/orphan/getOrphansFromFlatFieldErrors.mjs.map +0 -1
  106. package/dist/esm/errors/orphan/isOrphanFormError.mjs.map +0 -1
  107. package/dist/esm/errors/output/consoleErrors.mjs.map +0 -1
  108. package/dist/esm/errors/root/RootErrorsListFromFlatFieldErrorsContext.mjs.map +0 -1
  109. package/dist/esm/errors/root/consts.mjs.map +0 -1
  110. package/dist/esm/errors/root/getRootsFromFlatFieldErrors.mjs.map +0 -1
  111. package/dist/esm/errors/root/isFlatFieldErrorEntryPathRoot.mjs.map +0 -1
  112. package/dist/esm/errors/root/isFormErrorPathRoot.mjs.map +0 -1
  113. package/dist/esm/errors/trpc/getOnSubmitTrpcClientErrorHandler.mjs.map +0 -1
  114. package/dist/esm/errors/trpc/trpcClientErrorMessageSchema.mjs.map +0 -1
  115. package/dist/esm/errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs.map +0 -1
  116. package/dist/esm/exports.mjs.map +0 -1
  117. package/dist/esm/form/Form.mjs.map +0 -1
  118. package/dist/esm/form/FormWithProviders.mjs.map +0 -1
  119. package/dist/esm/form/RhfUtilsFormProviders.mjs.map +0 -1
  120. package/dist/esm/form/_Controller.mjs.map +0 -1
  121. package/dist/esm/form/context/group/FormGroupContextProvider.mjs.map +0 -1
  122. package/dist/esm/form/context/group/index.mjs.map +0 -1
  123. package/dist/esm/form/context/group/useFormGroupChildIsMountedTracker.mjs.map +0 -1
  124. package/dist/esm/form/context/group/useFormGroupChildIsSubmittingTracker.mjs.map +0 -1
  125. package/dist/esm/form/context/group/useFormGroupChildTracker.mjs.map +0 -1
  126. package/dist/esm/form/context/group/useFormGroupIsAnyBusy.mjs.map +0 -1
  127. package/dist/esm/form/context/group/useFormGroupIsChildBusy.mjs.map +0 -1
  128. package/dist/esm/form/context/group/useFormGroupIsParentBusy.mjs.map +0 -1
  129. package/dist/esm/form/context/group/useFormGroupParentTracker.mjs.map +0 -1
  130. package/dist/esm/form/context/group/useFormOrParentIsBusy.mjs.map +0 -1
  131. package/dist/esm/form/context/utils/RhfUtilsContextProvider.mjs.map +0 -1
  132. package/dist/esm/form/context/utils/useRhfUtilsContext.mjs.map +0 -1
  133. package/dist/esm/form/context/utils/useRhfUtilsContextRequestSubmit.mjs.map +0 -1
  134. package/dist/esm/form/useFormIsBusy.mjs.map +0 -1
  135. package/dist/esm/form/useRhfUtilsForm.mjs.map +0 -1
  136. package/dist/esm/form/utils/getSubmitterButtonData.mjs.map +0 -1
  137. package/dist/esm/form/utils/useFormRequestSubmit.mjs.map +0 -1
  138. package/dist/esm/submit/error/FormSubmitError.mjs.map +0 -1
  139. package/dist/esm/submit/error/setCtxErrorsByFormSubmitErrors.mjs.map +0 -1
  140. package/dist/esm/submit/useFormOnSubmitted.mjs.map +0 -1
  141. package/dist/esm/submit/useResetFormOnSubmitted.mjs.map +0 -1
  142. package/dist/esm/submit/useSubmitFormOnChange.mjs.map +0 -1
  143. package/dist/esm/utils/PassthroughChildren.mjs.map +0 -1
  144. package/dist/esm/utils/createContext.mjs.map +0 -1
  145. package/dist/esm/utils/isEmptyObject.mjs.map +0 -1
  146. package/dist/esm/utils/useRefIfValueWasTrue.mjs.map +0 -1
package/LICENSE.md ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024-present paragrav.dev
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -4,11 +4,11 @@
4
4
 
5
5
  Integration and utility library for [react-hook-form](https://www.react-hook-form.com/).
6
6
 
7
- 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.
7
+ 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.
8
8
 
9
9
  ## Features
10
10
 
11
- - built with and for [TypeScript](https://www.typescriptlang.org/)
11
+ - [TypeScript](https://www.typescriptlang.org/)-first
12
12
  - global configuration, such as:
13
13
  - injecting your own hooks and UI (`FormChildrenWrapper`)
14
14
  - server error transformation (`onSubmitErrorUnknown`)
@@ -18,11 +18,11 @@ If you have multiple forms and would like a more declarative API to manage their
18
18
  - schema-typed Controller component
19
19
  - schema-typed FormSubmitError class
20
20
  - throw in submit handler to add errors to RHF context and fail submit
21
- - flatter `FieldErrors` structure (`FlatFieldErrors`)
22
- - grouped into `all`, `fields`, `roots`, and `orphans`
23
- - `FormErrorMessageByPath` for displaying error message (with `FormNonFieldErrorMarker`)
21
+ - simpler/flatter `FieldErrors` structure (`FlatFieldErrors`)
22
+ - context groups errors into `all`, `fields`, `roots`, and `orphans` (`useFlatFieldErrorsContext`)
23
+ - `FormErrorMessageByPath` for displaying error message
24
24
  - `zod` support
25
- - including `z.input` and `z.output` types for transformations
25
+ - including input/output types for transformations
26
26
  - safer `FieldValues` type (`SafeFieldValues`)
27
27
  - 3.3kB min+gzip core functionality (excluding [peer dependencies](#peer-dependencies))
28
28
 
@@ -221,12 +221,12 @@ Currently, only `zod` is supported.
221
221
  If you prefer to define your `Children` component as standalone:
222
222
 
223
223
  ```tsx
224
- const Children: RhfUtilsUseFormChildrenZodFC<typeof schema> = ({ ... }) => { };
224
+ const Children: RhfUtilsUseFormChildrenZodFC<typeof schema> = ({...}) => { };
225
225
 
226
226
  function Children({...}: RhfUtilsUseFormChildrenZodProps<typeof schema>) { }
227
227
  ```
228
228
 
229
- ## Component Hierarchy
229
+ ## Form Component Hierarchy
230
230
 
231
231
  ```tsx
232
232
  <ReactHookForm.FormProvider>
@@ -242,7 +242,7 @@ function Children({...}: RhfUtilsUseFormChildrenZodProps<typeof schema>) { }
242
242
 
243
243
  ## `FormSubmitError`
244
244
 
245
- 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`.
245
+ 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`.
246
246
 
247
247
  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.
248
248
 
@@ -262,7 +262,7 @@ Example:
262
262
  />
263
263
  ```
264
264
 
265
- 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.
265
+ 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.
266
266
 
267
267
  Most common use case will be transforming backend errors to frontend shape. (You can use `getOnSubmitTrpcClientErrorHandler` HOF provided by this library for TRPC backends.)
268
268
 
@@ -272,11 +272,15 @@ These options can be set globally and/or per form.
272
272
 
273
273
  ```ts
274
274
  type RhfUtilsFormOptions = {
275
- /** Stop propagation of submit event. Useful for portals. */
275
+ /** Stop propagation of submit event. */
276
276
  stopSubmitPropagation?: boolean;
277
277
 
278
- /** Request submit via listener on form change. */
279
- submitOnChange?: boolean;
278
+ /**
279
+ * Request submit via listener on form change.
280
+ * - `true`: no debounce
281
+ * - number: milliseconds to debounce
282
+ */
283
+ submitOnChange?: boolean | number;
280
284
 
281
285
  /**
282
286
  * Reset form values and state (e.g., isDirty, etc.) after submit -- on success and/or error.
@@ -293,7 +297,7 @@ type RhfUtilsFormOptions = {
293
297
  };
294
298
  ```
295
299
 
296
- If you need access to options deeper in component structure, use `useRhfUtilsContext` to receive `RhfUtilsContext` object, which includes `formId`, `formRef`, and `options` settings.
300
+ If you need access to options deeper in your component structure, use `useRhfUtilsContext` to receive `RhfUtilsContext` object, which includes `formId`, `formRef`, and `options` settings.
297
301
 
298
302
  Use `useRhfUtilsContextRequestSubmit` hook to get `requestSubmit` function for current form ref in context. This is useful when you need to trigger form submission programatically.
299
303
 
@@ -314,39 +318,56 @@ declare module '@paragrav/rhf-utils' {
314
318
  }
315
319
  ```
316
320
 
317
- ## Errors
321
+ ## Field Errors
318
322
 
319
- You can configure via `RhfUtilsClientConfig` (example at the top) when form context errors are outputted -- i.e., via console and/or thrown error.
323
+ ### FlatFieldErrors
324
+
325
+ `FlatFieldErrors` type is a flattened, simplified version of RHF's `FieldErrors`. Keys represent flattened, dot-notation field paths.
320
326
 
321
327
  Use `useFlatFieldErrorsContext()` hook, which returns an object with errors grouped by `all`, `fields`, `roots`, `orphans` records, and `hasErrors` and `hasErrors` and `hasOrphans` booleans.
322
328
 
323
- `FlatFieldErrors` type is a flattened, simplified version of RHF's `FieldErrors`. Keys represent flattened, dot-notation field paths.
329
+ ### Output
330
+
331
+ 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).
324
332
 
325
333
  ### Orphan Errors
326
334
 
327
- 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.
335
+ 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.)
328
336
 
329
- The criteria for an orphan is any form context error that meets all of the following criteria:
337
+ More technically, an "orphan" is any form state error that meets ALL of the following criteria:
330
338
 
331
- - not a root error -- e.g., `root` or `root.${string}`
332
- - has no `ref` -- RHF includes `ref` to the associated input on each error object (when applicable)
333
- - has no marker in DOM (e.g., `FormNonFieldErrorMarker`)
339
+ - not a root error -- i.e., `root` and `root.${string}` paths
340
+ - these are assumed to be listed for users somewhere
341
+ - has no `ref` -- RHF includes `ref` to the associated input for each error (when applicable)
342
+ - these are assumed to be shown next to their input fields
343
+ - has no marker in DOM (i.e., `FormNonFieldErrorMarker`)
344
+ - see section further below for more information
334
345
 
335
- 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.)
346
+ Detected orphans can be accessed via any of the following:
336
347
 
337
- Alternatively, you can use `FormErrorMessageByPath` to display error message to user:
348
+ - via `RhfUtilsClientConfig.FieldErrors.output`; e.g.:
349
+ - console log to facilitate debugging on development
350
+ - console error to facilitate reporting on production (via your own error reporting service)
351
+ - throw error for developer during development
352
+ - `useFlatFieldErrorsContext()` hook
353
+ - returns an object with list of errors grouped by `all`, `fields` (with `ref`), `roots`, `orphans` records, and includes computed booleans `hasErrors` and `hasOrphans`
354
+ - boolean value from `useFlatFieldErrorsContextHasOnlyOrphans`
338
355
 
339
- ```tsx
340
- <FormErrorMessageByPath path="street.address" />
341
- ```
356
+ ### FormNonFieldErrorMarker
357
+
358
+ 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.)
359
+
360
+ #### When is the marker required?
342
361
 
343
- 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.
362
+ For example, a field array with a minimum number of items -- e.g., `items: z.array(...).min(1)`.
344
363
 
345
- Orphans are exposed in a few places.
364
+ 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`.
346
365
 
347
- - In errors outputted via console. (Configurable via `RhfUtilsClientConfig['errors']['output']`.)
348
- - And `useFlatFieldErrorsContext()` hook, which returns an object with errors grouped by `all`, `fields`, `roots`, `orphans` records, and `hasErrors` and `hasOrphans` boolean.
349
- - Boolean value from `useFlatFieldErrorsContextHasOnlyOrphans`.
366
+ 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.
367
+
368
+ ```tsx
369
+ <FormErrorMessageByPath path="items" />
370
+ ```
350
371
 
351
372
  ## Form Groups
352
373
 
@@ -7,4 +7,3 @@ export {
7
7
  o as _RhfUtilsClientConfigContextProvider,
8
8
  i as default
9
9
  };
10
- //# sourceMappingURL=useRhfUtilsClientConfigContext.mjs.map
@@ -47,4 +47,3 @@ const c = (r) => (o) => {
47
47
  export {
48
48
  c as createRhfUtilsClient
49
49
  };
50
- //# sourceMappingURL=index.mjs.map
@@ -1,30 +1,38 @@
1
- const i = (l, ...t) => (
1
+ const u = (n, ...r) => (
2
2
  // sequentially merge each set of props into defaults
3
- t.reduce(
4
- (s, e) => {
5
- var f, o;
3
+ r.reduce(
4
+ (t, e) => {
5
+ var s, i, l, m, o, f;
6
6
  return {
7
7
  rhf: {
8
- ...s == null ? void 0 : s.rhf,
8
+ ...t == null ? void 0 : t.rhf,
9
9
  ...e.rhf
10
10
  },
11
11
  utils: {
12
- ...s == null ? void 0 : s.utils,
13
- ...e.utils
12
+ ...t == null ? void 0 : t.utils,
13
+ ...e.utils,
14
+ // manual merges
15
+ // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- false positive
16
+ ...(((s = t == null ? void 0 : t.utils) == null ? void 0 : s.resetOnSubmitted) || ((i = e.utils) == null ? void 0 : i.resetOnSubmitted)) && {
17
+ resetOnSubmitted: {
18
+ ...(l = t == null ? void 0 : t.utils) == null ? void 0 : l.resetOnSubmitted,
19
+ ...(m = e.utils) == null ? void 0 : m.resetOnSubmitted
20
+ }
21
+ }
14
22
  },
15
23
  form: {
16
- ...s == null ? void 0 : s.form,
24
+ ...t == null ? void 0 : t.form,
17
25
  ...e.form,
18
- className: [(f = s == null ? void 0 : s.form) == null ? void 0 : f.className, (o = e.form) == null ? void 0 : o.className].filter(Boolean).join(" ")
19
- // stringify
26
+ // manual merges
27
+ 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
28
+ // stringify (replace empty string with undefined)
20
29
  }
21
30
  };
22
31
  },
23
32
  // start with defaults
24
- l
33
+ n
25
34
  )
26
35
  );
27
36
  export {
28
- i as mergeRhfUtilsClientConfigDefaultsWithUseRhfUtilsFormProps
37
+ u as mergeRhfUtilsClientConfigDefaultsWithUseRhfUtilsFormProps
29
38
  };
30
- //# sourceMappingURL=utils.mjs.map
@@ -13,4 +13,3 @@ const d = ({
13
13
  export {
14
14
  p as default
15
15
  };
16
- //# sourceMappingURL=RhfUtilsClientForZodContextProvider.mjs.map
@@ -10,4 +10,3 @@ function m({
10
10
  export {
11
11
  m as default
12
12
  };
13
- //# sourceMappingURL=RhfUtilsZodForm.mjs.map
@@ -7,4 +7,3 @@ export {
7
7
  o as _RhfUtilsClientForZodContextProvider,
8
8
  r as default
9
9
  };
10
- //# sourceMappingURL=useRhfUtilsClientForZodContext.mjs.map
@@ -3,4 +3,3 @@ const e = (o, t) => s().useForm(o, t), f = e;
3
3
  export {
4
4
  f as default
5
5
  };
6
- //# sourceMappingURL=useRhfUtilsZodForm.mjs.map
@@ -4,4 +4,3 @@ const i = e(t);
4
4
  export {
5
5
  i as default
6
6
  };
7
- //# sourceMappingURL=createRhfUtilsClientForZod.mjs.map
@@ -13,4 +13,3 @@ const a = e.lazy(
13
13
  export {
14
14
  u as default
15
15
  };
16
- //# sourceMappingURL=LazyDevTool.mjs.map
@@ -15,4 +15,3 @@ const o = ({ errors: e }) => {
15
15
  export {
16
16
  o as default
17
17
  };
18
- //# sourceMappingURL=FlatFieldErrorsList.mjs.map
@@ -25,4 +25,3 @@ const C = ({
25
25
  export {
26
26
  C as default
27
27
  };
28
- //# sourceMappingURL=FlatFieldErrorsContextProvider.mjs.map
@@ -7,4 +7,3 @@ export {
7
7
  o as _FormErrorsFlatContextProvider,
8
8
  s as default
9
9
  };
10
- //# sourceMappingURL=useFlatFieldErrorsContext.mjs.map
@@ -7,4 +7,3 @@ const t = () => {
7
7
  export {
8
8
  l as default
9
9
  };
10
- //# sourceMappingURL=useFlatFieldErrorsContextHasOnlyOrphans.mjs.map
@@ -22,4 +22,3 @@ const C = (r) => {
22
22
  export {
23
23
  C as default
24
24
  };
25
- //# sourceMappingURL=useFlatFieldErrorsContextOutput.mjs.map
@@ -8,4 +8,3 @@ const r = (e) => (t) => (
8
8
  export {
9
9
  r as default
10
10
  };
11
- //# sourceMappingURL=filterFlatFieldErrors.mjs.map
@@ -3,4 +3,3 @@ const o = (t) => r(t);
3
3
  export {
4
4
  o as default
5
5
  };
6
- //# sourceMappingURL=flattenFieldErrors.mjs.map
@@ -22,4 +22,3 @@ export {
22
22
  u as default,
23
23
  d as regexMaybeFieldErrorLeafNodeSuffix
24
24
  };
25
- //# sourceMappingURL=getFlatFieldErrors.mjs.map
@@ -6,4 +6,3 @@ const l = r(
6
6
  export {
7
7
  l as default
8
8
  };
9
- //# sourceMappingURL=getRefdFromFlatFieldErrors.mjs.map
@@ -2,4 +2,3 @@ const r = (e) => !!e.ref;
2
2
  export {
3
3
  r as default
4
4
  };
5
- //# sourceMappingURL=isFieldErrorRefd.mjs.map
@@ -3,4 +3,3 @@ const t = ([, r]) => e(r);
3
3
  export {
4
4
  t as default
5
5
  };
6
- //# sourceMappingURL=isFlatFieldErrorEntryRefd.mjs.map
@@ -12,4 +12,3 @@ const i = ({ message: r, className: e }) => /* @__PURE__ */ o(
12
12
  export {
13
13
  i as default
14
14
  };
15
- //# sourceMappingURL=FormErrorMessage.mjs.map
@@ -12,4 +12,3 @@ const f = ({ path: o, Component: s }) => {
12
12
  export {
13
13
  E as default
14
14
  };
15
- //# sourceMappingURL=FormErrorMessageByPath.mjs.map
@@ -17,4 +17,3 @@ const a = ({ path: r }) => {
17
17
  export {
18
18
  d as default
19
19
  };
20
- //# sourceMappingURL=FormNonFieldErrorMarker.mjs.map
@@ -21,4 +21,3 @@ const m = (r, e) => (
21
21
  export {
22
22
  m as getFormNonFieldErrorMarkerQuerySelector
23
23
  };
24
- //# sourceMappingURL=FormNonFieldErrorMarker.utils.mjs.map
@@ -2,4 +2,3 @@ const r = "data-paragrav-rhf-utils-nonfield-error-marker-path";
2
2
  export {
3
3
  r as default
4
4
  };
5
- //# sourceMappingURL=FormNonFieldErrorMarkerHtmlAttribute.mjs.map
@@ -3,4 +3,3 @@ const l = (r, e) => !!e.querySelector(o(r));
3
3
  export {
4
4
  l as default
5
5
  };
6
- //# sourceMappingURL=isNonFieldErrorMarkerInDOM.mjs.map
@@ -3,4 +3,3 @@ const n = (r) => ([t, e]) => o(t, e, r);
3
3
  export {
4
4
  n as default
5
5
  };
6
- //# sourceMappingURL=getIsOrphanFormErrorWithParentElement.mjs.map
@@ -6,4 +6,3 @@ const F = (r, t) => e(
6
6
  export {
7
7
  F as default
8
8
  };
9
- //# sourceMappingURL=getOrphansFromFlatFieldErrors.mjs.map
@@ -10,4 +10,3 @@ const d = (r, o, i) => (
10
10
  export {
11
11
  d as default
12
12
  };
13
- //# sourceMappingURL=isOrphanFormError.mjs.map
@@ -4,4 +4,3 @@ const c = (o, e, s, r = "debug") => {
4
4
  export {
5
5
  c as default
6
6
  };
7
- //# sourceMappingURL=consoleErrors.mjs.map
@@ -8,4 +8,3 @@ const e = () => {
8
8
  export {
9
9
  m as default
10
10
  };
11
- //# sourceMappingURL=RootErrorsListFromFlatFieldErrorsContext.mjs.map
@@ -2,4 +2,3 @@ const o = "root";
2
2
  export {
3
3
  o as FormErrorPathRoot
4
4
  };
5
- //# sourceMappingURL=consts.mjs.map
@@ -6,4 +6,3 @@ const l = r(
6
6
  export {
7
7
  l as default
8
8
  };
9
- //# sourceMappingURL=getRootsFromFlatFieldErrors.mjs.map
@@ -3,4 +3,3 @@ const a = ([o]) => r(o);
3
3
  export {
4
4
  a as default
5
5
  };
6
- //# sourceMappingURL=isFlatFieldErrorEntryPathRoot.mjs.map
@@ -3,4 +3,3 @@ const s = (o) => o === r || o.startsWith(r + ".");
3
3
  export {
4
4
  s as default
5
5
  };
6
- //# sourceMappingURL=isFormErrorPathRoot.mjs.map
@@ -4,4 +4,3 @@ const o = (t) => (r) => r instanceof n ? e.parse(r) : t(r), a = o;
4
4
  export {
5
5
  a as default
6
6
  };
7
- //# sourceMappingURL=getOnSubmitTrpcClientErrorHandler.mjs.map
@@ -8,4 +8,3 @@ const a = r.object({
8
8
  export {
9
9
  a as default
10
10
  };
11
- //# sourceMappingURL=trpcClientErrorMessageSchema.mjs.map
@@ -32,4 +32,3 @@ const i = e.custom(
32
32
  export {
33
33
  i as default
34
34
  };
35
- //# sourceMappingURL=trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs.map
@@ -48,4 +48,3 @@ export {
48
48
  y as useRhfUtilsContextRequestSubmit,
49
49
  u as useRhfUtilsZodForm
50
50
  };
51
- //# sourceMappingURL=exports.mjs.map
@@ -84,4 +84,3 @@ function G({
84
84
  export {
85
85
  G as default
86
86
  };
87
- //# sourceMappingURL=Form.mjs.map
@@ -9,4 +9,3 @@ function n(m) {
9
9
  export {
10
10
  n as default
11
11
  };
12
- //# sourceMappingURL=FormWithProviders.mjs.map
@@ -22,4 +22,3 @@ function v({
22
22
  export {
23
23
  v as default
24
24
  };
25
- //# sourceMappingURL=RhfUtilsFormProviders.mjs.map
@@ -6,4 +6,3 @@ function n(r) {
6
6
  export {
7
7
  n as default
8
8
  };
9
- //# sourceMappingURL=_Controller.mjs.map
@@ -28,4 +28,3 @@ const B = ({ children: o }) => {
28
28
  export {
29
29
  h as default
30
30
  };
31
- //# sourceMappingURL=FormGroupContextProvider.mjs.map
@@ -9,4 +9,3 @@ export {
9
9
  t as _useFormGroupContext,
10
10
  u as _useFormGroupContextMaybe
11
11
  };
12
- //# sourceMappingURL=index.mjs.map
@@ -4,4 +4,3 @@ const e = () => (r(!0), o()), t = e;
4
4
  export {
5
5
  t as default
6
6
  };
7
- //# sourceMappingURL=useFormGroupChildIsMountedTracker.mjs.map
@@ -8,4 +8,3 @@ const m = () => {
8
8
  export {
9
9
  n as default
10
10
  };
11
- //# sourceMappingURL=useFormGroupChildIsSubmittingTracker.mjs.map
@@ -11,4 +11,3 @@ const u = (s) => {
11
11
  export {
12
12
  d as default
13
13
  };
14
- //# sourceMappingURL=useFormGroupChildTracker.mjs.map
@@ -6,4 +6,3 @@ const r = () => {
6
6
  export {
7
7
  e as default
8
8
  };
9
- //# sourceMappingURL=useFormGroupIsAnyBusy.mjs.map
@@ -6,4 +6,3 @@ const s = () => {
6
6
  export {
7
7
  e as default
8
8
  };
9
- //# sourceMappingURL=useFormGroupIsChildBusy.mjs.map
@@ -6,4 +6,3 @@ const s = () => {
6
6
  export {
7
7
  s as default
8
8
  };
9
- //# sourceMappingURL=useFormGroupIsParentBusy.mjs.map
@@ -11,4 +11,3 @@ const m = () => {
11
11
  export {
12
12
  f as default
13
13
  };
14
- //# sourceMappingURL=useFormGroupParentTracker.mjs.map
@@ -8,4 +8,3 @@ const u = () => {
8
8
  export {
9
9
  a as default
10
10
  };
11
- //# sourceMappingURL=useFormOrParentIsBusy.mjs.map
@@ -1,22 +1,23 @@
1
- import { jsx as d } from "react/jsx-runtime";
2
- import i from "../../../client/config/useRhfUtilsClientConfigContext.mjs";
3
- import a from "../../../errors/flat/context/useFlatFieldErrorsContextOutput.mjs";
4
- import f from "../../../submit/useResetFormOnSubmitted.mjs";
1
+ import { jsx as l } from "react/jsx-runtime";
2
+ import d from "../../../client/config/useRhfUtilsClientConfigContext.mjs";
3
+ import f from "../../../errors/flat/context/useFlatFieldErrorsContextOutput.mjs";
4
+ import b from "../../../submit/useResetFormOnSubmitted.mjs";
5
5
  import C from "../../../submit/useSubmitFormOnChange.mjs";
6
- import { _RhfUtilsContextProvider as s } from "./useRhfUtilsContext.mjs";
6
+ import { _RhfUtilsContextProvider as h } from "./useRhfUtilsContext.mjs";
7
7
  const n = ({
8
8
  formId: u,
9
9
  formRef: t,
10
- options: r,
11
- children: l
10
+ options: e,
11
+ children: a
12
12
  }) => {
13
13
  var m;
14
- const e = i();
15
- return a((m = e == null ? void 0 : e.FieldErrors) == null ? void 0 : m.output), C(t, {
16
- disabled: !(r != null && r.submitOnChange)
17
- }), f(r == null ? void 0 : r.resetOnSubmitted), /* @__PURE__ */ d(s, { value: { formId: u, formRef: t, options: r }, children: l });
14
+ const r = d();
15
+ return f((m = r == null ? void 0 : r.FieldErrors) == null ? void 0 : m.output), C(t, {
16
+ // check for false/undefined
17
+ disabled: ((e == null ? void 0 : e.submitOnChange) ?? !1) === !1,
18
+ debounce: typeof (e == null ? void 0 : e.submitOnChange) == "number" ? e.submitOnChange : void 0
19
+ }), b(e == null ? void 0 : e.resetOnSubmitted), /* @__PURE__ */ l(h, { value: { formId: u, formRef: t, options: e }, children: a });
18
20
  };
19
21
  export {
20
22
  n as default
21
23
  };
22
- //# sourceMappingURL=RhfUtilsContextProvider.mjs.map
@@ -4,4 +4,3 @@ export {
4
4
  r as _RhfUtilsContextProvider,
5
5
  i as default
6
6
  };
7
- //# sourceMappingURL=useRhfUtilsContext.mjs.map
@@ -7,4 +7,3 @@ const o = () => {
7
7
  export {
8
8
  m as default
9
9
  };
10
- //# sourceMappingURL=useRhfUtilsContextRequestSubmit.mjs.map
@@ -6,4 +6,3 @@ const e = () => {
6
6
  export {
7
7
  e as default
8
8
  };
9
- //# sourceMappingURL=useFormIsBusy.mjs.map
@@ -41,4 +41,3 @@ const v = ({
41
41
  export {
42
42
  v as default
43
43
  };
44
- //# sourceMappingURL=useRhfUtilsForm.mjs.map