@paragrav/rhf-utils 0.0.135 → 0.0.137
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.
- package/README.md +90 -65
- package/dist/esm/client/config/useRhfUtilsClientConfigContext.mjs +0 -1
- package/dist/esm/client/index.mjs +0 -1
- package/dist/esm/client/utils.mjs +0 -1
- package/dist/esm/client/zod/context/RhfUtilsClientForZodContextProvider.mjs +3 -2
- package/dist/esm/client/zod/context/RhfUtilsZodForm.mjs +0 -1
- package/dist/esm/client/zod/context/useRhfUtilsClientForZodContext.mjs +0 -1
- package/dist/esm/client/zod/context/useRhfUtilsZodForm.mjs +0 -1
- package/dist/esm/client/zod/createRhfUtilsClientForZod.mjs +0 -1
- package/dist/esm/devtool/LazyDevTool.mjs +0 -1
- package/dist/esm/errors/flat/FlatFieldErrorsList.mjs +0 -1
- package/dist/esm/errors/flat/context/FlatFieldErrorsContextProvider.mjs +0 -1
- package/dist/esm/errors/flat/context/useFlatFieldErrorsContext.mjs +0 -1
- package/dist/esm/errors/flat/context/useFlatFieldErrorsContextHasOnlyOrphans.mjs +0 -1
- package/dist/esm/errors/flat/context/useFlatFieldErrorsContextOutput.mjs +0 -1
- package/dist/esm/errors/flat/filterFlatFieldErrors.mjs +0 -1
- package/dist/esm/errors/flat/flattenFieldErrors.mjs +0 -1
- package/dist/esm/errors/flat/getFlatFieldErrors.mjs +10 -11
- package/dist/esm/errors/getRefdFromFlatFieldErrors.mjs +0 -1
- package/dist/esm/errors/isFieldErrorRefd.mjs +0 -1
- package/dist/esm/errors/isFlatFieldErrorEntryRefd.mjs +0 -1
- package/dist/esm/errors/message/FormErrorMessage.mjs +0 -1
- package/dist/esm/errors/message/RhfUtilsFieldErrorMessage.mjs +14 -0
- package/dist/esm/errors/nonfield/FormNonFieldErrorMarker.mjs +0 -1
- package/dist/esm/errors/nonfield/FormNonFieldErrorMarker.utils.mjs +0 -1
- package/dist/esm/errors/nonfield/FormNonFieldErrorMarkerHtmlAttribute.mjs +0 -1
- package/dist/esm/errors/nonfield/isNonFieldErrorMarkerInDOM.mjs +0 -1
- package/dist/esm/errors/orphan/getIsOrphanFormErrorWithParentElement.mjs +0 -1
- package/dist/esm/errors/orphan/getOrphansFromFlatFieldErrors.mjs +0 -1
- package/dist/esm/errors/orphan/isOrphanFormError.mjs +3 -4
- package/dist/esm/errors/output/consoleErrors.mjs +0 -1
- package/dist/esm/errors/root/RootErrorsListFromFlatFieldErrorsContext.mjs +0 -1
- package/dist/esm/errors/root/consts.mjs +0 -1
- package/dist/esm/errors/root/getRootsFromFlatFieldErrors.mjs +0 -1
- package/dist/esm/errors/root/isFlatFieldErrorEntryPathRoot.mjs +0 -1
- package/dist/esm/errors/root/isFormErrorPathRoot.mjs +0 -1
- package/dist/esm/exports.mjs +32 -37
- package/dist/esm/form/Form.mjs +14 -15
- package/dist/esm/form/FormWithProviders.mjs +0 -1
- package/dist/esm/form/RhfUtilsFormProviders.mjs +0 -1
- package/dist/esm/form/_Controller.mjs +0 -1
- package/dist/esm/form/context/group/FormGroupContextProvider.mjs +0 -1
- package/dist/esm/form/context/group/index.mjs +0 -1
- package/dist/esm/form/context/group/useFormGroupChildIsMountedTracker.mjs +0 -1
- package/dist/esm/form/context/group/useFormGroupChildIsSubmittingTracker.mjs +0 -1
- package/dist/esm/form/context/group/useFormGroupChildTracker.mjs +0 -1
- package/dist/esm/form/context/group/useFormGroupIsAnyBusy.mjs +0 -1
- package/dist/esm/form/context/group/useFormGroupIsChildBusy.mjs +0 -1
- package/dist/esm/form/context/group/useFormGroupIsParentBusy.mjs +0 -1
- package/dist/esm/form/context/group/useFormGroupParentTracker.mjs +0 -1
- package/dist/esm/form/context/group/useFormOrParentIsBusy.mjs +0 -1
- package/dist/esm/form/context/utils/RhfUtilsContextProvider.mjs +15 -14
- package/dist/esm/form/context/utils/useRhfUtilsContext.mjs +0 -1
- package/dist/esm/form/context/utils/useRhfUtilsContextRequestSubmit.mjs +0 -1
- package/dist/esm/form/useFormIsBusy.mjs +0 -1
- package/dist/esm/form/useRhfUtilsForm.mjs +0 -1
- package/dist/esm/form/utils/getSubmitterButtonData.mjs +0 -1
- package/dist/esm/form/utils/useFormRequestSubmit.mjs +9 -6
- package/dist/esm/submit/error/FormSubmitError.mjs +0 -1
- package/dist/esm/submit/error/setCtxErrorsByFormSubmitFieldErrors.mjs +12 -0
- package/dist/esm/submit/useFormOnSubmitted.mjs +0 -1
- package/dist/esm/submit/useResetFormOnSubmitted.mjs +0 -1
- package/dist/esm/submit/useSubmitFormOnChange.mjs +18 -12
- package/dist/esm/utils/PassthroughChildren.mjs +0 -1
- package/dist/esm/utils/createContext.mjs +0 -1
- package/dist/esm/utils/isEmptyObject.mjs +0 -1
- package/dist/esm/utils/useDebouncedOnChangeValue.mjs +26 -0
- package/dist/esm/utils/useRefIfValueWasTrue.mjs +0 -1
- package/dist/types/client/config/RhfUtilsClientConfig.d.ts +5 -5
- package/dist/types/client/zod/context/RhfUtilsClientForZodContextProvider.d.ts +1 -1
- package/dist/types/errors/flat/flattenFieldErrors.d.ts +3 -2
- package/dist/types/errors/message/{FormErrorMessageByPath.d.ts → RhfUtilsFieldErrorMessage.d.ts} +2 -2
- package/dist/types/errors/trpc/getOnSubmitTrpcClientErrorHandler.d.ts +2 -2
- package/dist/types/errors/trpc/trpcClientErrorToFormSubmitFieldErrorsSchemaTransformer.d.ts +28 -0
- package/dist/types/exports.d.ts +1 -3
- package/dist/types/form/RhfUtilsFormOptions.d.ts +7 -3
- package/dist/types/form/UseRhfUtilsFormProps.d.ts +1 -1
- package/dist/types/form/utils/useFormRequestSubmit.d.ts +5 -0
- package/dist/types/submit/error/FormSubmitError.d.ts +3 -3
- package/dist/types/submit/error/{FormSubmitErrors.d.ts → FormSubmitFieldErrors.d.ts} +1 -1
- package/dist/types/submit/error/setCtxErrorsByFormSubmitFieldErrors.d.ts +10 -0
- package/dist/types/submit/useFormOnSubmitSuccessfulAndReset.d.ts +1 -1
- package/dist/types/submit/useFormOnSubmitted.d.ts +1 -1
- package/dist/types/submit/useSubmitFormOnChange.d.ts +3 -1
- package/dist/types/utils/timeoutAsync.d.ts +6 -0
- package/dist/types/utils/useDebouncedOnChangeValue.d.ts +14 -0
- package/package.json +1 -1
- package/dist/esm/client/config/useRhfUtilsClientConfigContext.mjs.map +0 -1
- package/dist/esm/client/index.mjs.map +0 -1
- package/dist/esm/client/utils.mjs.map +0 -1
- package/dist/esm/client/zod/context/RhfUtilsClientForZodContextProvider.mjs.map +0 -1
- package/dist/esm/client/zod/context/RhfUtilsZodForm.mjs.map +0 -1
- package/dist/esm/client/zod/context/useRhfUtilsClientForZodContext.mjs.map +0 -1
- package/dist/esm/client/zod/context/useRhfUtilsZodForm.mjs.map +0 -1
- package/dist/esm/client/zod/createRhfUtilsClientForZod.mjs.map +0 -1
- package/dist/esm/devtool/LazyDevTool.mjs.map +0 -1
- package/dist/esm/errors/flat/FlatFieldErrorsList.mjs.map +0 -1
- package/dist/esm/errors/flat/context/FlatFieldErrorsContextProvider.mjs.map +0 -1
- package/dist/esm/errors/flat/context/useFlatFieldErrorsContext.mjs.map +0 -1
- package/dist/esm/errors/flat/context/useFlatFieldErrorsContextHasOnlyOrphans.mjs.map +0 -1
- package/dist/esm/errors/flat/context/useFlatFieldErrorsContextOutput.mjs.map +0 -1
- package/dist/esm/errors/flat/filterFlatFieldErrors.mjs.map +0 -1
- package/dist/esm/errors/flat/flattenFieldErrors.mjs.map +0 -1
- package/dist/esm/errors/flat/getFlatFieldErrors.mjs.map +0 -1
- package/dist/esm/errors/getRefdFromFlatFieldErrors.mjs.map +0 -1
- package/dist/esm/errors/isFieldErrorRefd.mjs.map +0 -1
- package/dist/esm/errors/isFlatFieldErrorEntryRefd.mjs.map +0 -1
- package/dist/esm/errors/message/FormErrorMessage.mjs.map +0 -1
- package/dist/esm/errors/message/FormErrorMessageByPath.mjs +0 -15
- package/dist/esm/errors/message/FormErrorMessageByPath.mjs.map +0 -1
- package/dist/esm/errors/nonfield/FormNonFieldErrorMarker.mjs.map +0 -1
- package/dist/esm/errors/nonfield/FormNonFieldErrorMarker.utils.mjs.map +0 -1
- package/dist/esm/errors/nonfield/FormNonFieldErrorMarkerHtmlAttribute.mjs.map +0 -1
- package/dist/esm/errors/nonfield/isNonFieldErrorMarkerInDOM.mjs.map +0 -1
- package/dist/esm/errors/orphan/getIsOrphanFormErrorWithParentElement.mjs.map +0 -1
- package/dist/esm/errors/orphan/getOrphansFromFlatFieldErrors.mjs.map +0 -1
- package/dist/esm/errors/orphan/isOrphanFormError.mjs.map +0 -1
- package/dist/esm/errors/output/consoleErrors.mjs.map +0 -1
- package/dist/esm/errors/root/RootErrorsListFromFlatFieldErrorsContext.mjs.map +0 -1
- package/dist/esm/errors/root/consts.mjs.map +0 -1
- package/dist/esm/errors/root/getRootsFromFlatFieldErrors.mjs.map +0 -1
- package/dist/esm/errors/root/isFlatFieldErrorEntryPathRoot.mjs.map +0 -1
- package/dist/esm/errors/root/isFormErrorPathRoot.mjs.map +0 -1
- package/dist/esm/errors/trpc/getOnSubmitTrpcClientErrorHandler.mjs +0 -7
- package/dist/esm/errors/trpc/getOnSubmitTrpcClientErrorHandler.mjs.map +0 -1
- package/dist/esm/errors/trpc/trpcClientErrorMessageSchema.mjs +0 -11
- package/dist/esm/errors/trpc/trpcClientErrorMessageSchema.mjs.map +0 -1
- package/dist/esm/errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs +0 -35
- package/dist/esm/errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer.mjs.map +0 -1
- package/dist/esm/exports.mjs.map +0 -1
- package/dist/esm/form/Form.mjs.map +0 -1
- package/dist/esm/form/FormWithProviders.mjs.map +0 -1
- package/dist/esm/form/RhfUtilsFormProviders.mjs.map +0 -1
- package/dist/esm/form/_Controller.mjs.map +0 -1
- package/dist/esm/form/context/group/FormGroupContextProvider.mjs.map +0 -1
- package/dist/esm/form/context/group/index.mjs.map +0 -1
- package/dist/esm/form/context/group/useFormGroupChildIsMountedTracker.mjs.map +0 -1
- package/dist/esm/form/context/group/useFormGroupChildIsSubmittingTracker.mjs.map +0 -1
- package/dist/esm/form/context/group/useFormGroupChildTracker.mjs.map +0 -1
- package/dist/esm/form/context/group/useFormGroupIsAnyBusy.mjs.map +0 -1
- package/dist/esm/form/context/group/useFormGroupIsChildBusy.mjs.map +0 -1
- package/dist/esm/form/context/group/useFormGroupIsParentBusy.mjs.map +0 -1
- package/dist/esm/form/context/group/useFormGroupParentTracker.mjs.map +0 -1
- package/dist/esm/form/context/group/useFormOrParentIsBusy.mjs.map +0 -1
- package/dist/esm/form/context/utils/RhfUtilsContextProvider.mjs.map +0 -1
- package/dist/esm/form/context/utils/useRhfUtilsContext.mjs.map +0 -1
- package/dist/esm/form/context/utils/useRhfUtilsContextRequestSubmit.mjs.map +0 -1
- package/dist/esm/form/useFormIsBusy.mjs.map +0 -1
- package/dist/esm/form/useRhfUtilsForm.mjs.map +0 -1
- package/dist/esm/form/utils/getSubmitterButtonData.mjs.map +0 -1
- package/dist/esm/form/utils/useFormRequestSubmit.mjs.map +0 -1
- package/dist/esm/submit/error/FormSubmitError.mjs.map +0 -1
- package/dist/esm/submit/error/setCtxErrorsByFormSubmitErrors.mjs +0 -13
- package/dist/esm/submit/error/setCtxErrorsByFormSubmitErrors.mjs.map +0 -1
- package/dist/esm/submit/useFormOnSubmitted.mjs.map +0 -1
- package/dist/esm/submit/useResetFormOnSubmitted.mjs.map +0 -1
- package/dist/esm/submit/useSubmitFormOnChange.mjs.map +0 -1
- package/dist/esm/utils/PassthroughChildren.mjs.map +0 -1
- package/dist/esm/utils/createContext.mjs.map +0 -1
- package/dist/esm/utils/isEmptyObject.mjs.map +0 -1
- package/dist/esm/utils/useRefIfValueWasTrue.mjs.map +0 -1
- package/dist/types/errors/trpc/trpcClientErrorToFormSubmitErrorsSchemaTransformer.d.ts +0 -28
- package/dist/types/submit/error/setCtxErrorsByFormSubmitErrors.d.ts +0 -10
package/README.md
CHANGED
|
@@ -2,29 +2,30 @@
|
|
|
2
2
|
|
|
3
3
|
## About
|
|
4
4
|
|
|
5
|
-
Integration and utility library for [react-hook-form](https://www.react-hook-form.com/).
|
|
6
|
-
|
|
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.
|
|
5
|
+
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.
|
|
8
6
|
|
|
9
7
|
## Features
|
|
10
8
|
|
|
11
|
-
-
|
|
12
|
-
- global configuration
|
|
13
|
-
-
|
|
9
|
+
- TypeScript-first
|
|
10
|
+
- global configuration (`RhfUtilsClientConfig`)
|
|
11
|
+
- RHF (`UseFormProps`) and utilities (`RhfUtilsFormOptions`) options defaults
|
|
12
|
+
- inject your own hooks and UI (`FormChildrenWrapper`)
|
|
14
13
|
- server error transformation (`onSubmitErrorUnknown`)
|
|
15
|
-
-
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
14
|
+
- RHF `FormState.errors` logging/throwing (`RhfUtilsClientConfig.fieldErrors`)
|
|
15
|
+
- form-level configuration (`RhfUtilsZodForm`)
|
|
16
|
+
- RHF and utilities options overrides
|
|
17
|
+
- extendable utilities options type (`RhfUtilsFormOptions`)
|
|
18
|
+
- throw error (`FormSubmitError`) in submit handler to add errors to RHF context and fail submit
|
|
19
|
+
- handle submit error (`onSubmitError`)
|
|
20
|
+
- dependency injection for children (`RhfUtilsZodForm.Children`), including:
|
|
21
|
+
- formId, formRef, RHF context, utilities options
|
|
22
|
+
- schema-typed Controller component and FormSubmitError class
|
|
21
23
|
- simpler/flatter `FieldErrors` structure (`FlatFieldErrors`)
|
|
22
24
|
- context groups errors into `all`, `fields`, `roots`, and `orphans` (`useFlatFieldErrorsContext`)
|
|
23
|
-
- `
|
|
24
|
-
- `zod` support
|
|
25
|
-
- including input/output types for transformations
|
|
25
|
+
- `RhfUtilsFieldErrorMessage` for displaying error message
|
|
26
26
|
- safer `FieldValues` type (`SafeFieldValues`)
|
|
27
|
-
-
|
|
27
|
+
- `zod` support, including input/output types for transformations
|
|
28
|
+
- ~3.9kB min+gzip (excluding [peer dependencies](#peer-dependencies))
|
|
28
29
|
|
|
29
30
|
## Install
|
|
30
31
|
|
|
@@ -34,9 +35,15 @@ pnpm install @paragrav/rhf-utils # pnpm
|
|
|
34
35
|
yarn add @paragrav/rhf-utils # yarn
|
|
35
36
|
```
|
|
36
37
|
|
|
38
|
+
## Quick Start
|
|
39
|
+
|
|
40
|
+
- 🔗 [Config](#config) (`RhfUtilsClientConfig`): define your desired global config (optional)
|
|
41
|
+
- 🔗 [Provider](#provider) (`RhfUtilsClientForZodContextProvider`): add to your global stack
|
|
42
|
+
- 🔗 [Form](#form) (`RhfUtilsZodForm`): use for your forms
|
|
43
|
+
|
|
37
44
|
## Config
|
|
38
45
|
|
|
39
|
-
|
|
46
|
+
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.
|
|
40
47
|
|
|
41
48
|
```tsx
|
|
42
49
|
export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
|
|
@@ -77,10 +84,12 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
|
|
|
77
84
|
children, // RhfUtilsZodForm's Children instance
|
|
78
85
|
},
|
|
79
86
|
) => {
|
|
80
|
-
|
|
87
|
+
useMyGlobalFormHook();
|
|
88
|
+
|
|
89
|
+
// form-level control of your own hooks/behaviors via custom option props
|
|
81
90
|
// (see "Extend RhfUtilsFormOptions" section for more info)
|
|
82
|
-
|
|
83
|
-
enabled: !!options?.
|
|
91
|
+
useMyOptionalFormHook({
|
|
92
|
+
enabled: !!options?.enableMyOptionalFormHook,
|
|
84
93
|
});
|
|
85
94
|
|
|
86
95
|
return (
|
|
@@ -99,18 +108,13 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
|
|
|
99
108
|
onSubmitErrorUnknown: (
|
|
100
109
|
error, // unknown
|
|
101
110
|
) => {
|
|
102
|
-
// return
|
|
111
|
+
// return FormSubmitFieldErrors object to be merged to RHF context errors
|
|
103
112
|
if (isMyServerError(error))
|
|
104
|
-
return
|
|
105
|
-
|
|
106
|
-
// if other error
|
|
107
|
-
return {
|
|
108
|
-
root: { type: 'server', message: 'There was a problem.' },
|
|
109
|
-
} satisfies FormSubmitErrors;
|
|
113
|
+
return transformMyServerErrorToFormSubmitFieldErrors(error);
|
|
110
114
|
},
|
|
111
115
|
|
|
112
|
-
//
|
|
113
|
-
|
|
116
|
+
// RHF FormState.errors output for debugging
|
|
117
|
+
fieldErrors: {
|
|
114
118
|
// callbacks to determine when to output information about field errors
|
|
115
119
|
// provided `FlatFieldErrorsContext` (all, fields, roots, orphans, hasOrphans)
|
|
116
120
|
// (See "Orphan Errors" section below for more info.)
|
|
@@ -133,7 +137,7 @@ export const rhfUtilsClientConfig: RhfUtilsClientConfig = {
|
|
|
133
137
|
|
|
134
138
|
## Provider
|
|
135
139
|
|
|
136
|
-
|
|
140
|
+
Add the context provider to your global provider stack.
|
|
137
141
|
|
|
138
142
|
```tsx
|
|
139
143
|
<RhfUtilsClientForZodContextProvider config={rhfUtilsClientConfig}>
|
|
@@ -185,7 +189,7 @@ Currently, only `zod` is supported.
|
|
|
185
189
|
<label>
|
|
186
190
|
Email
|
|
187
191
|
<input {...field} disabled={isSubmitting} />
|
|
188
|
-
<
|
|
192
|
+
<RhfUtilsFieldErrorMessage path={field.name} />
|
|
189
193
|
</label>
|
|
190
194
|
)}
|
|
191
195
|
/>
|
|
@@ -199,13 +203,9 @@ Currently, only `zod` is supported.
|
|
|
199
203
|
}}
|
|
200
204
|
utils={{
|
|
201
205
|
submitOnChange: true,
|
|
202
|
-
resetOnSubmitted: {
|
|
203
|
-
onSuccess: { values: 'current' },
|
|
204
|
-
onError: { values: 'defaults' },
|
|
205
|
-
},
|
|
206
206
|
// custom option props
|
|
207
207
|
// (see "Extend RhfUtilsFormOptions" section)
|
|
208
|
-
|
|
208
|
+
enableMyOptionalFormHook: true,
|
|
209
209
|
}}
|
|
210
210
|
form={{
|
|
211
211
|
// class names are merged together with global defaults
|
|
@@ -242,18 +242,17 @@ function Children({...}: RhfUtilsUseFormChildrenZodProps<typeof schema>) { }
|
|
|
242
242
|
|
|
243
243
|
## `FormSubmitError`
|
|
244
244
|
|
|
245
|
-
This is an
|
|
245
|
+
This is an `Error`-based class that you can use to throw a schema-typed error in your submit handler.
|
|
246
246
|
|
|
247
|
-
It differs from `FlatFieldError` only in that it is narrower.
|
|
247
|
+
(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.)
|
|
248
248
|
|
|
249
|
-
Example
|
|
249
|
+
### Example
|
|
250
250
|
|
|
251
251
|
```tsx
|
|
252
252
|
<RhfUtilsZodForm
|
|
253
253
|
onSubmit={async (data, { FormSubmitError }) => {
|
|
254
254
|
if (isProblem(data))
|
|
255
255
|
throw new FormSubmitError({
|
|
256
|
-
root: { message: 'There was a problem with the form.' },
|
|
257
256
|
'street.address': { message: 'Street address invalid.' },
|
|
258
257
|
});
|
|
259
258
|
|
|
@@ -262,9 +261,9 @@ Example:
|
|
|
262
261
|
/>
|
|
263
262
|
```
|
|
264
263
|
|
|
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 `
|
|
264
|
+
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.
|
|
266
265
|
|
|
267
|
-
Most common use case will be transforming backend errors to frontend shape.
|
|
266
|
+
Most common use case will be transforming backend errors to frontend shape.
|
|
268
267
|
|
|
269
268
|
## `RhfUtilsFormOptions`
|
|
270
269
|
|
|
@@ -275,8 +274,12 @@ type RhfUtilsFormOptions = {
|
|
|
275
274
|
/** Stop propagation of submit event. */
|
|
276
275
|
stopSubmitPropagation?: boolean;
|
|
277
276
|
|
|
278
|
-
/**
|
|
279
|
-
|
|
277
|
+
/**
|
|
278
|
+
* Request submit via listener on form change.
|
|
279
|
+
* - `true`: no debounce
|
|
280
|
+
* - number: milliseconds to debounce
|
|
281
|
+
*/
|
|
282
|
+
submitOnChange?: boolean | number;
|
|
280
283
|
|
|
281
284
|
/**
|
|
282
285
|
* Reset form values and state (e.g., isDirty, etc.) after submit -- on success and/or error.
|
|
@@ -308,7 +311,7 @@ declare module '@paragrav/rhf-utils' {
|
|
|
308
311
|
export interface Register {
|
|
309
312
|
RhfUtilsFormOptions: {
|
|
310
313
|
/** Enable user prompt to confirm navigating away from dirty form. */
|
|
311
|
-
|
|
314
|
+
enableMyOptionalFormHook?: boolean;
|
|
312
315
|
};
|
|
313
316
|
}
|
|
314
317
|
}
|
|
@@ -324,47 +327,67 @@ Use `useFlatFieldErrorsContext()` hook, which returns an object with errors grou
|
|
|
324
327
|
|
|
325
328
|
### Output
|
|
326
329
|
|
|
327
|
-
For the purposes of debugging and/or logging, you can configure when form state errors are outputted (i.e., console
|
|
330
|
+
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).
|
|
328
331
|
|
|
329
332
|
### Orphan Errors
|
|
330
333
|
|
|
331
|
-
The concept of "orphan"
|
|
334
|
+
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.
|
|
335
|
+
|
|
336
|
+
Programatically, an "orphan" is any form state error that meets ALL of the following criteria:
|
|
337
|
+
|
|
338
|
+
- non-field -- i.e., no RHF-supplied `ref` on `FieldError` object
|
|
339
|
+
- non-root -- i.e., not `root` or `root.${string}` path
|
|
340
|
+
- no corresponding "marker" in DOM (i.e., `FormNonFieldErrorMarker`)
|
|
341
|
+
|
|
342
|
+
This is because:
|
|
332
343
|
|
|
333
|
-
|
|
344
|
+
- field errors (with `ref`s) are assumed to be displayed next to their respective input
|
|
345
|
+
- root errors (non-field, without `ref`s) are assumed to always be listed for display
|
|
346
|
+
- all other errors must be marked as displayed to distinguish from being an orphan
|
|
334
347
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
- these are assumed to be shown next to their input fields
|
|
339
|
-
- has no marker in DOM (i.e., `FormNonFieldErrorMarker`)
|
|
340
|
-
- see section further below for more information
|
|
348
|
+
_See [FormNonFieldErrorMarker](#formnonfielderrormarker) section below for more information about when and why marker is needed._
|
|
349
|
+
|
|
350
|
+
#### Using orphan errors
|
|
341
351
|
|
|
342
352
|
Detected orphans can be accessed via any of the following:
|
|
343
353
|
|
|
344
|
-
-
|
|
345
|
-
-
|
|
346
|
-
- console
|
|
347
|
-
- throw error for developer during development
|
|
354
|
+
- `RhfUtilsClientConfig.fieldErrors.output` -- e.g., config per environment:
|
|
355
|
+
- _development_: `throw` to facilitate discovery and debugging
|
|
356
|
+
- _production_: `console.error` to facilitate reporting
|
|
348
357
|
- `useFlatFieldErrorsContext()` hook
|
|
349
358
|
- returns an object with list of errors grouped by `all`, `fields` (with `ref`), `roots`, `orphans` records, and includes computed booleans `hasErrors` and `hasOrphans`
|
|
350
359
|
- boolean value from `useFlatFieldErrorsContextHasOnlyOrphans`
|
|
351
360
|
|
|
352
361
|
### FormNonFieldErrorMarker
|
|
353
362
|
|
|
354
|
-
|
|
363
|
+
_If you don't need orphan detection, you can skip this section. By default, orphan detection still occurs but doesn't otherwise do anything._
|
|
364
|
+
|
|
365
|
+
To get accurate orphan detection, you must use `FormNonFieldErrorMarker` when displaying any non-root non-field errors. (Example further below.)
|
|
366
|
+
|
|
367
|
+
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.)
|
|
368
|
+
|
|
369
|
+
#### When is the marker required? _(example of non-root non-field error)_
|
|
370
|
+
|
|
371
|
+
A typical example is a field array with a required minimum number of items -- e.g., `items: z.array(...).min(1)`.
|
|
355
372
|
|
|
356
|
-
|
|
373
|
+
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.
|
|
357
374
|
|
|
358
|
-
|
|
375
|
+
In order to NOT detect this as an orphan, it must be explicitly "marked" as displayed using `FormNonFieldErrorMarker`.
|
|
359
376
|
|
|
360
|
-
|
|
377
|
+
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.
|
|
361
378
|
|
|
362
|
-
|
|
379
|
+
```tsx
|
|
380
|
+
<RhfUtilsFieldErrorMessage path="items" />
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
Uncommon, but if you are ONLY listing a summary of all errors, without individual displays, you will need to use the marker manually.
|
|
363
384
|
|
|
364
385
|
```tsx
|
|
365
|
-
<
|
|
386
|
+
<FormNonFieldErrorMarker path="items" />
|
|
366
387
|
```
|
|
367
388
|
|
|
389
|
+
_If you include the marker for error lists, it will defeat the purpose of the marker. Only use marker for individual errors._
|
|
390
|
+
|
|
368
391
|
## Form Groups
|
|
369
392
|
|
|
370
393
|
Sometimes you need to group multiple forms together.
|
|
@@ -392,9 +415,11 @@ Both hooks return `boolean` value indicating whether parent form is busy.
|
|
|
392
415
|
|
|
393
416
|
## Other
|
|
394
417
|
|
|
418
|
+
### SafeFieldValues
|
|
419
|
+
|
|
395
420
|
This library uses `SafeFieldValues` type which uses `unknown` instead of `any`.
|
|
396
421
|
|
|
397
|
-
|
|
422
|
+
### Peer dependencies
|
|
398
423
|
|
|
399
424
|
- [react](https://www.npmjs.com/package/react)
|
|
400
425
|
- [react-dom](https://www.npmjs.com/package/react-dom)
|
|
@@ -7,10 +7,11 @@ const d = ({
|
|
|
7
7
|
config: r,
|
|
8
8
|
children: i
|
|
9
9
|
}) => {
|
|
10
|
-
const [t] = e.useState(r), [n] = e.useState(
|
|
10
|
+
const [t] = e.useState(r), [n] = e.useState(
|
|
11
|
+
() => f(t ?? {})
|
|
12
|
+
);
|
|
11
13
|
return /* @__PURE__ */ o(l, { value: t, children: /* @__PURE__ */ o(s, { value: n, children: i }) });
|
|
12
14
|
}, p = d;
|
|
13
15
|
export {
|
|
14
16
|
p as default
|
|
15
17
|
};
|
|
16
|
-
//# sourceMappingURL=RhfUtilsClientForZodContextProvider.mjs.map
|
|
@@ -1,25 +1,24 @@
|
|
|
1
|
-
import { get as
|
|
2
|
-
import
|
|
3
|
-
const
|
|
4
|
-
const s =
|
|
1
|
+
import { get as d } from "react-hook-form";
|
|
2
|
+
import a from "./flattenFieldErrors.mjs";
|
|
3
|
+
const b = (t) => {
|
|
4
|
+
const s = a(t), n = Object.keys(s);
|
|
5
5
|
return Object.fromEntries(
|
|
6
|
-
|
|
6
|
+
n.reduce(
|
|
7
7
|
(e, o) => {
|
|
8
8
|
const r = o.replace(
|
|
9
|
-
|
|
9
|
+
i,
|
|
10
10
|
""
|
|
11
11
|
);
|
|
12
12
|
if (r === o) return e;
|
|
13
|
-
const f =
|
|
13
|
+
const f = d(t, r, void 0);
|
|
14
14
|
return f && e.push([r, f]), e;
|
|
15
15
|
},
|
|
16
16
|
[]
|
|
17
17
|
// entries
|
|
18
18
|
)
|
|
19
19
|
);
|
|
20
|
-
},
|
|
20
|
+
}, i = /\.(?:type|message)\b$/;
|
|
21
21
|
export {
|
|
22
|
-
|
|
23
|
-
|
|
22
|
+
b as default,
|
|
23
|
+
i as regexMaybeFieldErrorLeafNodeSuffix
|
|
24
24
|
};
|
|
25
|
-
//# sourceMappingURL=getFlatFieldErrors.mjs.map
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { jsxs as n, Fragment as i, jsx as o } from "react/jsx-runtime";
|
|
2
|
+
import { useFormState as a, get as l } from "react-hook-form";
|
|
3
|
+
import f from "../nonfield/FormNonFieldErrorMarker.mjs";
|
|
4
|
+
import g from "./FormErrorMessage.mjs";
|
|
5
|
+
const F = ({ path: e, Component: s }) => {
|
|
6
|
+
const { errors: t } = a(), r = l(t, e, void 0), m = s ?? g;
|
|
7
|
+
return r != null && r.message ? /* @__PURE__ */ n(i, { children: [
|
|
8
|
+
/* @__PURE__ */ o(m, { message: r.message }),
|
|
9
|
+
/* @__PURE__ */ o(f, { path: e })
|
|
10
|
+
] }) : null;
|
|
11
|
+
}, E = F;
|
|
12
|
+
export {
|
|
13
|
+
E as default
|
|
14
|
+
};
|
|
@@ -2,12 +2,11 @@ import m from "../isFieldErrorRefd.mjs";
|
|
|
2
2
|
import t from "../nonfield/isNonFieldErrorMarkerInDOM.mjs";
|
|
3
3
|
import e from "../root/isFormErrorPathRoot.mjs";
|
|
4
4
|
const d = (r, o, i) => (
|
|
5
|
-
//
|
|
6
|
-
!
|
|
7
|
-
!
|
|
5
|
+
// non-field
|
|
6
|
+
!m(o) && // non-root
|
|
7
|
+
!e(r) && // not marked in DOM
|
|
8
8
|
!t(r, i)
|
|
9
9
|
);
|
|
10
10
|
export {
|
|
11
11
|
d as default
|
|
12
12
|
};
|
|
13
|
-
//# sourceMappingURL=isOrphanFormError.mjs.map
|