@bolttech/form-engine 3.1.0-beta.9 → 3.1.0
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/CHANGELOG.md +25 -0
- package/README.md +349 -86
- package/index.d.ts +326 -0
- package/index.esm.js +684 -2100
- package/package.json +18 -7
- package/index.esm.d.ts +0 -1
- package/src/components/AsFormField/AsFormField.d.ts +0 -13
- package/src/components/AsFormField/AsFormField.type.d.ts +0 -9
- package/src/components/AsFormFieldBuilder/AsFormFieldBuilder.d.ts +0 -11
- package/src/components/AsFormFieldBuilder/AsFormFieldBuilder.type.d.ts +0 -21
- package/src/components/FieldWrapper/FieldWrapper.d.ts +0 -11
- package/src/components/FieldWrapper/FieldWrapper.type.d.ts +0 -32
- package/src/components/Form/Form.d.ts +0 -9
- package/src/components/Form/Form.type.d.ts +0 -11
- package/src/components/index.d.ts +0 -3
- package/src/context/FormGroupContext.d.ts +0 -19
- package/src/context/FormGroupContext.type.d.ts +0 -48
- package/src/generators/formBuilder.d.ts +0 -9
- package/src/helpers/helpers.d.ts +0 -7
- package/src/helpers/mapper.d.ts +0 -7
- package/src/hooks/index.d.ts +0 -2
- package/src/hooks/useForm/useForm.d.ts +0 -7
- package/src/hooks/useForm/useForm.type.d.ts +0 -12
- package/src/hooks/useFormGroup/useFormGroup.d.ts +0 -4
- package/src/hooks/useFormGroup/useFormGroup.type.d.ts +0 -17
- package/src/index.d.ts +0 -5
- package/src/types/index.d.ts +0 -32
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Form Engine React Adapter
|
|
2
2
|
|
|
3
|
-
This is an adapter to be used with the bolttech form engine. Compatible with Next.js 13
|
|
3
|
+
This is an adapter to be used with the bolttech form engine. Compatible with Next.js 13, 14 and 15 (App Router SSR supported), React 18 and 19.
|
|
4
4
|
|
|
5
5
|
1. [Sample](#sample)
|
|
6
6
|
2. [mappers](#mappers)
|
|
@@ -17,7 +17,7 @@ This is an adapter to be used with the bolttech form engine. Compatible with Nex
|
|
|
17
17
|
6. [schema components](#schema-components)
|
|
18
18
|
|
|
19
19
|
- 6.1 [formatters](#formatters)
|
|
20
|
-
- 6.2 [masks]
|
|
20
|
+
- 6.2 [masks](#masks)
|
|
21
21
|
- 6.3 [nameToSubmit](#nametosubmit)
|
|
22
22
|
- 6.4 [props](#props)
|
|
23
23
|
- 6.5 [validations](#validations)
|
|
@@ -25,6 +25,8 @@ This is an adapter to be used with the bolttech form engine. Compatible with Nex
|
|
|
25
25
|
- 6.7 [resetValues](#resetvalues)
|
|
26
26
|
- 6.8 [visibilityConditions](#visibilityconditions)
|
|
27
27
|
- 6.9 [resetPropertyValues](#resetpropertyvalues)
|
|
28
|
+
- 6.10 [visibility](#visibility)
|
|
29
|
+
- 6.11 [persistValue](#persistValue)
|
|
28
30
|
|
|
29
31
|
7. [templating](#templating)
|
|
30
32
|
|
|
@@ -35,6 +37,8 @@ This is an adapter to be used with the bolttech form engine. Compatible with Nex
|
|
|
35
37
|
|
|
36
38
|
9. [AsFormField](#asformfield)
|
|
37
39
|
10. [AsFormFieldBuilder](#asformfieldbuilder)
|
|
40
|
+
11. [AsFormFieldRepeater](#asformfieldrepeater)
|
|
41
|
+
12. [Server-Side Rendering (SSR)](#ssr)
|
|
38
42
|
|
|
39
43
|
<a id="sample"></a>
|
|
40
44
|
|
|
@@ -122,7 +126,7 @@ Mappers are the configuration that needs to be provided in order to use componen
|
|
|
122
126
|
The mapper configuration goes as it follows:
|
|
123
127
|
|
|
124
128
|
| Prop | Type | Description |
|
|
125
|
-
|
|
129
|
+
| ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
126
130
|
| componentName | string | name to be used onto schema to identify the component to be rendered on a field |
|
|
127
131
|
| events | TComponentPropsMapping | events mapping that will reference the component prop with the respective form-engine prop that will handle it's content |
|
|
128
132
|
| valueChangeEvent | TValueChangeEvent | component handle function to define how the value is extracted from the 'onChange' event of the component |
|
|
@@ -132,7 +136,7 @@ The mapper configuration goes as it follows:
|
|
|
132
136
|
`events` are optional and will reference component props that will provide it's dynamic behaviour:
|
|
133
137
|
|
|
134
138
|
| Prop | Type | Description |
|
|
135
|
-
|
|
139
|
+
| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
136
140
|
| getValue | string | component property that will contain the value |
|
|
137
141
|
| setValue | string | component property that handles onChange events triggered by the component |
|
|
138
142
|
| onBlur | string | component property that handles onBlur events triggered by the component |
|
|
@@ -419,33 +423,40 @@ After configuring the provider, `<Form />` components lets you render a form
|
|
|
419
423
|
|
|
420
424
|
### Props
|
|
421
425
|
|
|
422
|
-
| Prop | Type | Description
|
|
423
|
-
| ----------------------------------- | ---------------------------------------------------------------------------------- |
|
|
424
|
-
| [DEPRECIATED] disable | boolean | Disable all form inputs. It will use the default htm disable attribute
|
|
426
|
+
| Prop | Type | Description |
|
|
427
|
+
| ----------------------------------- | ---------------------------------------------------------------------------------- | ------------ |
|
|
428
|
+
| [DEPRECIATED] disable | boolean | Disable all form inputs. It will use the default htm disable attribute |
|
|
425
429
|
| [DEPRECIATED] group | string | Form group identifier. Used be able to group several forms and then get data with useGroupForm. One will be generated as default if omitted |
|
|
426
|
-
| index | string | Form identified. One will be generated as default if omitted
|
|
427
|
-
| [DEPRECIATED] hooks | THooks | Provide functions to run on certain life-cycle events
|
|
428
|
-
| iVars | Object | One object with internal variables to be used in form with data binding
|
|
429
|
-
| initialValues | Object | Object with form initial values that will map to a field.
|
|
430
|
-
| Schema | TSchema | Form Schema
|
|
431
|
-
| [DEPRECIATED] autoComplete | string | HTML autocomplete
|
|
432
|
-
| className | string | Allow to style form
|
|
433
|
-
| onSubmit | callback(TFormValues) | Will be called when there is a submit action in the form
|
|
434
|
-
| onData | callback(TFormData) | Will be called when any field data change. The arguments will let you know which field changed and the field configuration
|
|
435
|
-
| onBlur | callback(TFieldEvent) | Will be called when any field blured. The arguments will let you know which field blured and the field configuration
|
|
436
|
-
| onFocus | callback(TFieldEvent) | Will be called when any field focused change. The arguments will let you know which field focused and the field configuration
|
|
437
|
-
| onMount | callback(TFormValues,TComponent, TField) | Will be called when some field mounted. Its called with the field that information that mounted.
|
|
438
|
-
| [DEPRECIATED] onStep | callback(TFormValues) | Called when a form step changed
|
|
439
|
-
| [DEPRECIATED] onLog | callback(TLoggingEvent) | Called on each log, if the logging is enabled
|
|
440
|
-
| [DEPRECIATED] onScopeChange | onScopeChange?(scope: TScope, namespace: string, key: string): void; | Called everything scope change with the changing information (namespace and key) and the changed scope
|
|
441
|
-
| onClick | onClick(TFieldEvent) | Callback function that runs on each component click
|
|
442
|
-
| onApiResponse | onApiResponse(TFieldEvent) | Callback function that runs on each component after api call.
|
|
443
|
-
| [DEPRECIATED] onFieldRehydrate | onFieldRehydrate?(values: TFormValues, component: TComponent, field: TField): void | This callback is called whenever some form field was rehydrated
|
|
444
|
-
| [DEPRECIATED] renderLoading | renderLoading?(): ReactElement; | Component to render while the schema has not rendered
|
|
445
|
-
| [DEPRECIATED] onFormMount | onFormMount?(values: TFormValues): void; | Called when the form finished mounted
|
|
446
|
-
| [DEPRECIATED] formattedDataDefaults | Object | Some default data to fields when they are undefined
|
|
447
|
-
| [DEPRECIATED] submitOnValidOnly | boolean | Boolean indicating if form can be submitted even if it is invalid
|
|
448
|
-
| [DEPRECIATED] renderFieldWrapper | renderFieldWrapper(component: TComponent, children: ReactElement[]) | Function that allows to insert a wrapper in place of a component or wrapping the component
|
|
430
|
+
| index | string | Form identified. One will be generated as default if omitted |
|
|
431
|
+
| [DEPRECIATED] hooks | THooks | Provide functions to run on certain life-cycle events |
|
|
432
|
+
| iVars | Object | One object with internal variables to be used in form with data binding |
|
|
433
|
+
| initialValues | Object | Object with form initial values that will map to a field. |
|
|
434
|
+
| Schema | TSchema | Form Schema |
|
|
435
|
+
| [DEPRECIATED] autoComplete | string | HTML autocomplete |
|
|
436
|
+
| className | string | Allow to style form |
|
|
437
|
+
| onSubmit | callback(TFormValues) | Will be called when there is a submit action in the form |
|
|
438
|
+
| onData | callback(TFormData) | Will be called when any field data change. The arguments will let you know which field changed and the field configuration |
|
|
439
|
+
| onBlur | callback(TFieldEvent) | Will be called when any field blured. The arguments will let you know which field blured and the field configuration |
|
|
440
|
+
| onFocus | callback(TFieldEvent) | Will be called when any field focused change. The arguments will let you know which field focused and the field configuration |
|
|
441
|
+
| onMount | callback(TFormValues,TComponent, TField) | Will be called when some field mounted. Its called with the field that information that mounted. |
|
|
442
|
+
| [DEPRECIATED] onStep | callback(TFormValues) | Called when a form step changed |
|
|
443
|
+
| [DEPRECIATED] onLog | callback(TLoggingEvent) | Called on each log, if the logging is enabled |
|
|
444
|
+
| [DEPRECIATED] onScopeChange | onScopeChange?(scope: TScope, namespace: string, key: string): void; | Called everything scope change with the changing information (namespace and key) and the changed scope |
|
|
445
|
+
| onClick | onClick(TFieldEvent) | Callback function that runs on each component click |
|
|
446
|
+
| onApiResponse | onApiResponse(TFieldEvent) | Callback function that runs on each component after api call. |
|
|
447
|
+
| [DEPRECIATED] onFieldRehydrate | onFieldRehydrate?(values: TFormValues, component: TComponent, field: TField): void | This callback is called whenever some form field was rehydrated |
|
|
448
|
+
| [DEPRECIATED] renderLoading | renderLoading?(): ReactElement; | Component to render while the schema has not rendered |
|
|
449
|
+
| [DEPRECIATED] onFormMount | onFormMount?(values: TFormValues): void; | Called when the form finished mounted |
|
|
450
|
+
| [DEPRECIATED] formattedDataDefaults | Object | Some default data to fields when they are undefined |
|
|
451
|
+
| [DEPRECIATED] submitOnValidOnly | boolean | Boolean indicating if form can be submitted even if it is invalid |
|
|
452
|
+
| [DEPRECIATED] renderFieldWrapper | renderFieldWrapper(component: TComponent, children: ReactElement[]) | Function that allows to insert a wrapper in place of a component or wrapping the component |
|
|
453
|
+
| onApiRequest | onApiRequest(TFieldEvent) | Callback function that runs when an api call starts |
|
|
454
|
+
| onChange | onFieldChange(TFieldEvent) | Callback function that runs on each component value changes
|
|
455
|
+
| onKeyDown | onKeyDown(TFieldEvent) | Callback function that runs on each key down event |
|
|
456
|
+
| onKeyUp | onKeyUp(TFieldEvent) | Callback function that runs on each key up event |
|
|
457
|
+
| onCleared | onCleared(TFieldEvent) | Callback function that runs on a value that has been changed by resetValues event |
|
|
458
|
+
| onUnmount | onUnmount(TFieldEvent) | Callback function that runs when a field is unmounted or hidden by a visibility condition rule (use with caution) |
|
|
459
|
+
|
|
449
460
|
|
|
450
461
|
### Example
|
|
451
462
|
|
|
@@ -521,15 +532,15 @@ have a `Form` component and event callback functions needs to be setted
|
|
|
521
532
|
|
|
522
533
|
Schema is the structure of the form, it will contain the logic to be rendered and configurations of the fields to apply dynamic logic
|
|
523
534
|
|
|
524
|
-
| Prop
|
|
525
|
-
|
|
|
526
|
-
| index
|
|
527
|
-
| action?
|
|
528
|
-
| method?
|
|
529
|
-
| config?
|
|
530
|
-
| initialValues? | Record<string, unknown> | initial values to be loaded on the form |
|
|
531
|
-
| iVars?
|
|
532
|
-
| components?
|
|
535
|
+
| Prop | Type | Description |
|
|
536
|
+
| ----------------------------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------- |
|
|
537
|
+
| [index](../../docs/form-engine-core/src/interfaces/schema/interfaces/IFormSchema.md#index) | string | unique form id to handle multiple form on form group |
|
|
538
|
+
| [action](../../docs/form-engine-core/src/interfaces/schema/interfaces/IFormSchema.md#action)? | string | WIP: HTML form native action property to handle native form submissions |
|
|
539
|
+
| [method](../../docs/form-engine-core/src/interfaces/schema/interfaces/IFormSchema.md#method)? | string | WIP: HTML form native method property to handle native form submissions |
|
|
540
|
+
| [config](../../docs/form-engine-core/src/interfaces/schema/interfaces/IFormSchema.md#config)? | TSchemaFormConfig | Optional configuration object to set api and events debounce time |
|
|
541
|
+
| [initialValues](../../docs/form-engine-core/src/interfaces/schema/interfaces/IFormSchema.md#initialvalues)? | Record<string, unknown> | initial values to be loaded on the form |
|
|
542
|
+
| [iVars](../../docs/form-engine-core/src/interfaces/schema/interfaces/IFormSchema.md#ivars)? | Record<string, unknown> | dynamic values that can be changed externally to be used onto the form |
|
|
543
|
+
| [components](../../docs/form-engine-core/src/interfaces/schema/interfaces/IFormSchema.md#components)? | IComponentSchema[] | components to be rendered defined on the mappers |
|
|
533
544
|
|
|
534
545
|
this root configuration can be defined onto the `Form` component except the `components`
|
|
535
546
|
|
|
@@ -563,19 +574,19 @@ const schema: IFormSchema = {
|
|
|
563
574
|
|
|
564
575
|
Schema components contains the information of the component that will be rendered and the configurations he will exectute
|
|
565
576
|
|
|
566
|
-
| Prop
|
|
567
|
-
|
|
|
568
|
-
| component
|
|
569
|
-
| props?
|
|
570
|
-
| name
|
|
571
|
-
| nameToSubmit?
|
|
572
|
-
| validations?
|
|
573
|
-
| api?
|
|
574
|
-
| visibilityConditions? | TVisibility[] | visibilityConditions configuration described below |
|
|
575
|
-
| resetValues?
|
|
576
|
-
| formatters?
|
|
577
|
-
| masks?
|
|
578
|
-
| children?
|
|
577
|
+
| Prop | Type | Description |
|
|
578
|
+
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------- |
|
|
579
|
+
| [component](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#component) | string | component name defined on schema to render the correspondent component |
|
|
580
|
+
| [props](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#props)? | TProps | props of the component ex: label |
|
|
581
|
+
| [name](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#name) | string | unique id to identify the field onto form-engine |
|
|
582
|
+
| [nameToSubmit](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#nametosubmit)? | string | dot notation to submit a custom path to the component value ex: 'person.profile.firstName' |
|
|
583
|
+
| [validations](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#validations)? | TValidations | validations configuration described below |
|
|
584
|
+
| [api](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#api)? | TApiEvent | api configuration described below |
|
|
585
|
+
| [visibilityConditions](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#visibilityconditions)? | TVisibility[] | visibilityConditions configuration described below |
|
|
586
|
+
| [resetValues](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#resetvalues)? | TResetValueMethods[] | resetValues configuration described below |
|
|
587
|
+
| [formatters](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#formatters)? | TFormatters | formatters configuration described below |
|
|
588
|
+
| [masks](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#masks)? | TMasks | masks configuration described below |
|
|
589
|
+
| [children](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md#children)? | IComponentSchema[] | nested components to be rendered (if the current parent component accepts child components) |
|
|
579
590
|
|
|
580
591
|
### Example
|
|
581
592
|
|
|
@@ -628,25 +639,54 @@ Schema components contains the information of the component that will be rendere
|
|
|
628
639
|
}
|
|
629
640
|
```
|
|
630
641
|
|
|
642
|
+
Check the [TSDocs](../../docs/form-engine-core/src/interfaces/schema/interfaces/IComponentSchema.md) from `IComponentSchema` on form-engine-core
|
|
643
|
+
|
|
631
644
|
<a id="formatters"></a>
|
|
632
645
|
|
|
633
646
|
## **formatters**
|
|
634
647
|
|
|
635
|
-
formatters are methods that will format the input inserted on any field, they will format a value, regardless the event type
|
|
648
|
+
formatters are methods that will format the input inserted on any field, they will format a value, regardless the event type.
|
|
649
|
+
|
|
650
|
+
| Prop | Type | Description |
|
|
651
|
+
| ------------------------------------------------------------------------------------------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
652
|
+
| [callback](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#callback)? | (value) => void | Custom formatter callback function |
|
|
653
|
+
| [capitalize](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#capitalize)? | boolean | Capitalize the value |
|
|
654
|
+
| [dotEvery3chars](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#dotevery3chars)? | boolean | Add a dot every 3 characters |
|
|
655
|
+
| [gapsCreditCard](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#gapscreditcard) | string[] | Gaps to insert in credit card numbers |
|
|
656
|
+
| [maxLength](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#maxlength)? | number | Truncates the input value to a specified maximum length if necessary |
|
|
657
|
+
| [onlyFloatNumber](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#onlyfloatnumber)? | TCurrencyMask | Allow only float numbers with specific precision and decimal |
|
|
658
|
+
| [onlyLetters](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#onlyletters)? | boolean | Allow only letters |
|
|
659
|
+
| [onlyNumbers](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#onlynumbers)? | boolean | Allow only numbers |
|
|
660
|
+
| [regex](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#regex)? | string | Regular expression for formatting |
|
|
661
|
+
| [splitter](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#splitter)? | TSplitterFormatterValue[] | Splitter values for formatting |
|
|
662
|
+
| [trim](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#trim)? | boolean | Removes whitespace from both ends of this string and returns a new string, without modifying the original string |
|
|
663
|
+
| [uppercase](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md#uppercase)? | boolean | Convert the value to uppercase |
|
|
636
664
|
|
|
637
665
|
### Avaliable formatters
|
|
638
666
|
|
|
639
|
-
Check the TSDocs from `TFormatters` on form-engine-core
|
|
667
|
+
Check the [TSDocs](../../docs/form-engine-core/src/types/schema/type-aliases/TFormatters.md) from `TFormatters` on form-engine-core
|
|
640
668
|
|
|
641
669
|
<a id="masks"></a>
|
|
642
670
|
|
|
643
671
|
## **masks**
|
|
644
672
|
|
|
645
|
-
masks are methods that will format the input inserted on any field, they will show to the user a formatted value, but the submission value will be the original input of the user
|
|
673
|
+
masks are methods that will format the input inserted on any field, they will show to the user a formatted value, but the submission value will be the original input of the user.
|
|
674
|
+
|
|
675
|
+
| Prop | Type | Description |
|
|
676
|
+
| --------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------ |
|
|
677
|
+
| [card](../../docs/form-engine-core/src/types/schema/type-aliases/TMasks.md#card)? | boolean | Mask for card values |
|
|
678
|
+
| [cardDate](../../docs/form-engine-core/src/types/schema/type-aliases/TMasks.md#carddate)? | boolean | Mask for card date values |
|
|
679
|
+
| [currency](../../docs/form-engine-core/src/types/schema/type-aliases/TMasks.md#currency)? | TCurrencyMask | Mask for currency values |
|
|
680
|
+
| [custom](../../docs/form-engine-core/src/types/schema/type-aliases/TMasks.md#custom) | string | Custom mask pattern |
|
|
681
|
+
| [fein](../../docs/form-engine-core/src/types/schema/type-aliases/TMasks.md#fein)? | boolean | Mask for FEIN (Federal Employer Identification Number) |
|
|
682
|
+
| [generic](../../docs/form-engine-core/src/types/schema/type-aliases/TMasks.md#generic)? | TMaskGeneric[] | Array of generic masks |
|
|
683
|
+
| [replaceAll](../../docs/form-engine-core/src/types/schema/type-aliases/TMasks.md#replaceall)? | string | Value to replace all matches |
|
|
684
|
+
| [secureCreditCard](../../docs/form-engine-core/src/types/schema/type-aliases/TMasks.md#securecreditcard)? | boolean | Mask for securing credit card values |
|
|
685
|
+
| [callback](../../docs/form-engine-core/src/types/schema/type-aliases/TMasks.md#callback)? | (value, masks) => void | Custom mask callback function |
|
|
646
686
|
|
|
647
687
|
### Avaliable masks
|
|
648
688
|
|
|
649
|
-
Check the TSDocs from `TMasks` on form-engine-core
|
|
689
|
+
Check the [TSDocs](../../docs/form-engine-core/src/types/schema/type-aliases/TMasks.md) from `TMasks` on form-engine-core
|
|
650
690
|
|
|
651
691
|
### From v2 to v3
|
|
652
692
|
|
|
@@ -729,7 +769,7 @@ validations let you set rules in order to validate a field, then show errorMessa
|
|
|
729
769
|
|
|
730
770
|
### Avaliable validations
|
|
731
771
|
|
|
732
|
-
Check the TSDocs from `TValidationMethods` on form-engine-core
|
|
772
|
+
Check the [TSDocs](../../docs/form-engine-core/src/types/schema/type-aliases/TValidationMethods.md) from `TValidationMethods` on form-engine-core
|
|
733
773
|
|
|
734
774
|
### From v2 to v3
|
|
735
775
|
|
|
@@ -816,18 +856,18 @@ The configuration is as it follows:
|
|
|
816
856
|
|
|
817
857
|
Each config you opt to use, needs to be filled with an API configuration, the configuration is as it follows:
|
|
818
858
|
|
|
819
|
-
| Prop
|
|
820
|
-
|
|
|
821
|
-
| method
|
|
822
|
-
| url
|
|
823
|
-
| body?
|
|
824
|
-
| headers?
|
|
825
|
-
| queryParams?
|
|
826
|
-
| resultPath?
|
|
827
|
-
| fallbackValue?
|
|
828
|
-
| preConditions?
|
|
829
|
-
| blockRequestWhenInvalid? | boolean | flag to only request the api config if the field is valid |
|
|
830
|
-
| transform?
|
|
859
|
+
| Prop | Type | Description |
|
|
860
|
+
| --------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------- |
|
|
861
|
+
| [method](../../docs/form-engine-core/src/types/schema/type-aliases/TApiConfig.md#method) | 'GET' or 'POST' | HTTP method (only GET or POST) |
|
|
862
|
+
| [url](../../docs/form-engine-core/src/types/schema/type-aliases/TApiConfig.md#url) | string | Request url ex: http://mockapi.org |
|
|
863
|
+
| [body](../../docs/form-engine-core/src/types/schema/type-aliases/TApiConfig.md#body)? | Record<string, unknown> | Request body (only POST requests) |
|
|
864
|
+
| [headers](../../docs/form-engine-core/src/types/schema/type-aliases/TApiConfig.md#headers)? | OutgoingHttpHeaders | Avaliable HTTP headers |
|
|
865
|
+
| [queryParams](../../docs/form-engine-core/src/types/schema/type-aliases/TApiConfig.md#queryparams)? | Record<string,string> | url query params (to be appended to the already existing ones) |
|
|
866
|
+
| [resultPath](../../docs/form-engine-core/src/types/schema/type-aliases/TApiConfig.md#resultpath)? | string | response dot notation path to the value needed from the response |
|
|
867
|
+
| [fallbackValue](../../docs/form-engine-core/src/types/schema/type-aliases/TApiConfig.md#fallbackvalue)? | unknown | default value to return if the API returns error |
|
|
868
|
+
| [preConditions](../../docs/form-engine-core/src/types/schema/type-aliases/TApiConfig.md#preconditions)? | TSchemaValidation | validations to occur before the request is made (check validations section) |
|
|
869
|
+
| [blockRequestWhenInvalid](../../docs/form-engine-core/src/types/schema/type-aliases/TApiConfig.md#blockrequestwheninvalid)? | boolean | flag to only request the api config if the field is valid |
|
|
870
|
+
| [transform](../../docs/form-engine-core/src/types/schema/type-aliases/TApiConfig.md#transform)? | { callback:(payload) => unknown } | custom function to be passed as callback to transform the request in any other format |
|
|
831
871
|
|
|
832
872
|
### From v2 to v3
|
|
833
873
|
|
|
@@ -867,7 +907,7 @@ const api = {
|
|
|
867
907
|
};
|
|
868
908
|
```
|
|
869
909
|
|
|
870
|
-
the API result is commonly used with `templating`, check [templating](#
|
|
910
|
+
the API result is commonly used with `templating`, check [templating](#templating) section
|
|
871
911
|
|
|
872
912
|
<a id="resetvalues"></a>
|
|
873
913
|
|
|
@@ -875,14 +915,14 @@ the API result is commonly used with `templating`, check [templating](#markdown-
|
|
|
875
915
|
|
|
876
916
|
resetValues lets you change input values with the same rules as validations
|
|
877
917
|
|
|
878
|
-
| Prop
|
|
879
|
-
|
|
|
880
|
-
| validations
|
|
881
|
-
| fields
|
|
882
|
-
| events
|
|
883
|
-
| resettledValue
|
|
918
|
+
| Prop | Type | Description |
|
|
919
|
+
| --------------------------------------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------- |
|
|
920
|
+
| [validations](../../docs/form-engine-core/src/types/schema/type-aliases/TSchemaValidation.md) | TSchemaValidation | validations rules to be validated to reset the value to the configuration provided |
|
|
921
|
+
| fields | string[] or string | field or fields that will recieve the resettled value |
|
|
922
|
+
| events | Partial<TEvents>[] | events that will trigger the validation |
|
|
923
|
+
| resettledValue | unknown[] or unknown | value or values to be set on the specified fields |
|
|
884
924
|
|
|
885
|
-
if the event occurs and all the validations returns `true` the resettled value will trigger and the `fields` specified will be filled with the `resettledValue` values
|
|
925
|
+
if the event occurs and all the validations returns `true` the resettled value will trigger and the `fields` specified will be filled with the `resettledValue` values, also, the event ON_FIELD_CLEARED is triggered on the fields that gets the resettled value instead of ON_FIELD_CHANGE.
|
|
886
926
|
|
|
887
927
|
### from v2 to v3
|
|
888
928
|
|
|
@@ -1000,9 +1040,21 @@ resetPropertyValues: [
|
|
|
1000
1040
|
bool: false,
|
|
1001
1041
|
},
|
|
1002
1042
|
},
|
|
1003
|
-
]
|
|
1043
|
+
];
|
|
1004
1044
|
```
|
|
1005
1045
|
|
|
1046
|
+
<a id="visibility"></a>
|
|
1047
|
+
|
|
1048
|
+
## **visibility**
|
|
1049
|
+
|
|
1050
|
+
visibility prop is used to initiate the component with an initial visibility flag, before visibilityConditions take place, used on SSR
|
|
1051
|
+
|
|
1052
|
+
<a id="persistValue"></a>
|
|
1053
|
+
|
|
1054
|
+
## **persistValue**
|
|
1055
|
+
|
|
1056
|
+
persistValue is a flag that deremines if the field gets hidden, the moment it comes back visible, it will hold the previous value or not
|
|
1057
|
+
|
|
1006
1058
|
<a id="templating"></a>
|
|
1007
1059
|
|
|
1008
1060
|
## **templating**
|
|
@@ -1090,9 +1142,12 @@ The avalialbe callback methods are:
|
|
|
1090
1142
|
| onFocus | TFieldEvent | same as above |
|
|
1091
1143
|
| onKeyDown | TFieldEvent | same as above |
|
|
1092
1144
|
| onKeyUp | TFieldEvent | same as above |
|
|
1093
|
-
| onMount | TFieldEvent | same as above |
|
|
1094
|
-
| onApiResponse | TFieldEvent | same as above |
|
|
1095
1145
|
| onClick | TFieldEvent | same as above |
|
|
1146
|
+
| onApiResponse | TFieldEvent | event occuring when a api response is ready |
|
|
1147
|
+
| onApiRequest | TFieldEvent | event occuring when a api resquest is started |
|
|
1148
|
+
| onMount | TFieldEvent | event occuring when a field is mounted or set visible |
|
|
1149
|
+
| onUnmount | TFieldEvent | event occuring when a field is unmounted or hidden |
|
|
1150
|
+
| onCleared | TFieldEvent | event occuring when the field value is set with resetValues |
|
|
1096
1151
|
| onFormMount | TFormValues<T> | event occuring on form mount |
|
|
1097
1152
|
| onData | TFormData<T> | event occuring when a value is changing via input or logic |
|
|
1098
1153
|
| onSubmit | TFormValues<T> | event occuring when pressing the submit button defined on the form |
|
|
@@ -1109,7 +1164,7 @@ useFormGroup({ ids: ['form1', 'form2'], onData: (payload) => console.log(payload
|
|
|
1109
1164
|
As `useForm`, `useFormGroup` serves the same purpose, but the difference is that it handles multiple forms and has limited callback functions to set:
|
|
1110
1165
|
|
|
1111
1166
|
| method | payload | description |
|
|
1112
|
-
|
|
1167
|
+
| -------- | --------------------------------- | ----------------------------------------------------------- |
|
|
1113
1168
|
| onData | TFormGroupOnDataEventPayload<T> | event occurring when a value is changing via input or logic |
|
|
1114
1169
|
| onValid | TFormGroupOnValidEventPayload | event occurring when validation status changes on the form |
|
|
1115
1170
|
| onSubmit | TFormGroupOnSubmitEventPayload<T> | event occurring when form submission is trigger |
|
|
@@ -1167,8 +1222,216 @@ Ex:
|
|
|
1167
1222
|
|
|
1168
1223
|
Other than schema component properties like `validations`, `api`, etc.., it has additional properties to define the component, the associated form id and the name
|
|
1169
1224
|
|
|
1170
|
-
| method | type | description
|
|
1171
|
-
| --------- | ---------- |
|
|
1172
|
-
| mapper | TMapper<T> | mapper configuration to define the component
|
|
1173
|
-
| name | string | field name to be identified on the form
|
|
1174
|
-
| formIndex | string | index of the form to be identified on the formGroup
|
|
1225
|
+
| method | type | description |
|
|
1226
|
+
| --------- | ---------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
1227
|
+
| mapper | TMapper<T> | mapper configuration to define the component |
|
|
1228
|
+
| name | string | field name to be identified on the form |
|
|
1229
|
+
| formIndex | string | index of the form to be identified on the formGroup |
|
|
1230
|
+
| component | string | if mappers is provided from the formgroup context, you can assign the mapper by it's name instead of whole mapper config |
|
|
1231
|
+
|
|
1232
|
+
<a id="asformfieldrepeater"></a>
|
|
1233
|
+
|
|
1234
|
+
## **AsFormFieldRepeater**
|
|
1235
|
+
|
|
1236
|
+
Component adapter to aid managing multiple forms that shares the same inputs
|
|
1237
|
+
|
|
1238
|
+
Props:
|
|
1239
|
+
|
|
1240
|
+
| Attr | Type | Description |
|
|
1241
|
+
| ----------------- | --------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
1242
|
+
| RepeaterComponent | ElementType<{ formIndex: string }> | Component with form schema or AsFormFieldBuilder elements |
|
|
1243
|
+
| addFieldName | string | name of the button in the RepeaterComponent to add forms |
|
|
1244
|
+
| removeFieldName | string | name of the button in the RepeaterComponent to remove forms |
|
|
1245
|
+
| existingElements | Record<string, unknown>[] | existing values emmitted from stateUpdater to restore previous used values |
|
|
1246
|
+
| initialElements | number | elements to be pre-rendered when the form is presented |
|
|
1247
|
+
| stateUpdater | (payload: TFormGroupOnDataEventPayload<unknown>) => void; | callback function that reacts to RepeaterComponet values changes |
|
|
1248
|
+
| formPrefix | string | prefix for form names ex, prefix: foo, forms: ["foo1","foo2","foo3"] |
|
|
1249
|
+
| RepeaterFooter | ElementType<{ formIndex: string }> | Component with a button to add forms on the last position |
|
|
1250
|
+
|
|
1251
|
+
Common use case for this Adapter is to manage multiple forms that collects the same data ex: multiple person personal data
|
|
1252
|
+
|
|
1253
|
+
# Example
|
|
1254
|
+
|
|
1255
|
+
## RepeaterComponent
|
|
1256
|
+
|
|
1257
|
+
```javascript
|
|
1258
|
+
const FormElement = ({ formIndex }: { formIndex: string }) => {
|
|
1259
|
+
return (
|
|
1260
|
+
<>
|
|
1261
|
+
<AsFormFieldBuilder formIndex={formIndex} name="foo" component="input" props={{ label: 'foo' }} />
|
|
1262
|
+
<AsFormFieldBuilder formIndex={formIndex} name="bar" component="input" props={{ label: 'bar' }} />
|
|
1263
|
+
<AsFormFieldBuilder
|
|
1264
|
+
formIndex={formIndex}
|
|
1265
|
+
name="addForm"
|
|
1266
|
+
component="button"
|
|
1267
|
+
props={{
|
|
1268
|
+
text: 'add element',
|
|
1269
|
+
}}
|
|
1270
|
+
/>
|
|
1271
|
+
<AsFormFieldBuilder
|
|
1272
|
+
formIndex={formIndex}
|
|
1273
|
+
name="removeForm"
|
|
1274
|
+
component="button"
|
|
1275
|
+
props={{
|
|
1276
|
+
text: 'remove element',
|
|
1277
|
+
}}
|
|
1278
|
+
/>
|
|
1279
|
+
</>
|
|
1280
|
+
);
|
|
1281
|
+
};
|
|
1282
|
+
```
|
|
1283
|
+
|
|
1284
|
+
Important notes when developing this component is that it needs to receive an object with a key **formIndex**
|
|
1285
|
+
|
|
1286
|
+
Optionally, but to add form management functionality, add two buttons with **ON_FIELD_CLICK** event capture (can't be of type submit)
|
|
1287
|
+
both that Field button names will be needed on the next step
|
|
1288
|
+
|
|
1289
|
+
## RepeaterFooter
|
|
1290
|
+
|
|
1291
|
+
Optionally, you can develop a footer component with a button that will be added the bottom of the repeated forms
|
|
1292
|
+
and when you press that button will add a form at the bottom of the list
|
|
1293
|
+
|
|
1294
|
+
It's props needs to be an objet with a **formIndex** key, the button needs to have **ON_FIELD_CLICK** event capture (can't be of type submit)
|
|
1295
|
+
Note: the button name needs to be different from the names you gave to the buttons you are passing on the RepeaterComponent
|
|
1296
|
+
|
|
1297
|
+
```javascript
|
|
1298
|
+
const FormElementFooter = ({ formIndex }: { formIndex: string }) => {
|
|
1299
|
+
return (
|
|
1300
|
+
<AsFormFieldBuilder
|
|
1301
|
+
formIndex={formIndex}
|
|
1302
|
+
name="addFormBelow"
|
|
1303
|
+
component="button"
|
|
1304
|
+
props={{
|
|
1305
|
+
text: 'add element below',
|
|
1306
|
+
}}
|
|
1307
|
+
/>
|
|
1308
|
+
);
|
|
1309
|
+
};
|
|
1310
|
+
```
|
|
1311
|
+
|
|
1312
|
+
## AsFormFieldRepeater
|
|
1313
|
+
|
|
1314
|
+
Set the AsFormFieldRepeater adapter with the element you created above and the names that you gave to the button fields
|
|
1315
|
+
|
|
1316
|
+
```javascript
|
|
1317
|
+
<AsFormFieldRepeater
|
|
1318
|
+
RepeaterComponent={FormElement}
|
|
1319
|
+
RepeaterFooter={FormElementFooter}
|
|
1320
|
+
addFieldName="addForm"
|
|
1321
|
+
removeFieldName="removeForm"
|
|
1322
|
+
formPrefix="insured"
|
|
1323
|
+
stateUpdater={(payload) => {
|
|
1324
|
+
console.log(payload);
|
|
1325
|
+
}}
|
|
1326
|
+
/>
|
|
1327
|
+
```
|
|
1328
|
+
|
|
1329
|
+
**RepeaterComponent** and **RepeaterFooter** you set the elements created above
|
|
1330
|
+
|
|
1331
|
+
**addFieldName** you set the name to the button that will add a form on the position it's being clicked
|
|
1332
|
+
|
|
1333
|
+
**removeFieldName** you set the name to the button that will remove a form on the position it's being clicked
|
|
1334
|
+
|
|
1335
|
+
**formPrefix** the prefix for the forms emmited on **stateUpdater** enumerated
|
|
1336
|
+
|
|
1337
|
+
**stateUpdater** callback function that will receive the form values (similar to onData)
|
|
1338
|
+
|
|
1339
|
+
|
|
1340
|
+
<a id="ssr"></a>
|
|
1341
|
+
|
|
1342
|
+
## **Server-Side Rendering (SSR)**
|
|
1343
|
+
|
|
1344
|
+
Form Engine supports SSR with React frameworks like Next.js (App Router and Pages Router) and Remix. The form produces meaningful HTML on the server, reducing time-to-first-paint and improving SEO.
|
|
1345
|
+
|
|
1346
|
+
### How it works
|
|
1347
|
+
|
|
1348
|
+
1. **Server render**: The `<Form />` component creates the `FormCore` instance synchronously during render via `useMemo`. Static props (non-template) are rendered directly. Template expressions (`${...}`) are stripped by `filterProps` to avoid raw expressions in the HTML.
|
|
1349
|
+
|
|
1350
|
+
2. **Client hydration**: After hydration, `useEffect` hooks activate field mounting, RxJS subscriptions, and the template system (`subscribedTemplates` + `refreshTemplates`). Template props resolve at this point with their dynamic values.
|
|
1351
|
+
|
|
1352
|
+
### What renders during SSR
|
|
1353
|
+
|
|
1354
|
+
| Content | SSR behavior |
|
|
1355
|
+
|---------|-------------|
|
|
1356
|
+
| Form structure (`<form>`, fields) | ✅ Rendered with correct components |
|
|
1357
|
+
| Static props (`label`, `placeholder`, etc.) | ✅ Rendered normally |
|
|
1358
|
+
| Template props (`${iVars.*}`, `${fields.*}`) | Stripped during SSR, resolved after hydration |
|
|
1359
|
+
| `visibility: false` fields | ✅ Correctly hidden |
|
|
1360
|
+
| Field interactivity (onChange, validation) | Activates after hydration |
|
|
1361
|
+
| API calls (`ON_FIELD_MOUNT`) | Execute after hydration |
|
|
1362
|
+
|
|
1363
|
+
### `prefetchedData` prop
|
|
1364
|
+
|
|
1365
|
+
For fields that depend on API responses (e.g., dropdowns loaded from a backend), you can pre-fetch data on the server and pass it to the form. This populates the field's internal API response cache so that `refreshTemplates` can resolve API-based templates immediately after hydration — without making a new request.
|
|
1366
|
+
|
|
1367
|
+
```typescript
|
|
1368
|
+
import { Form, FormGroupContextProvider } from '@bolttech/form-engine';
|
|
1369
|
+
|
|
1370
|
+
// Server-side: fetch data before render
|
|
1371
|
+
const countries = await fetch('https://api.example.com/countries').then(r => r.json());
|
|
1372
|
+
|
|
1373
|
+
// Pass to form
|
|
1374
|
+
<FormGroupContextProvider mappers={mappers}>
|
|
1375
|
+
<Form
|
|
1376
|
+
schema={schema}
|
|
1377
|
+
iVars={{ title: 'Insurance Form' }}
|
|
1378
|
+
initialValues={{ name: 'John' }}
|
|
1379
|
+
prefetchedData={{
|
|
1380
|
+
countryField: {
|
|
1381
|
+
defaultResponse: countries,
|
|
1382
|
+
},
|
|
1383
|
+
stateField: {
|
|
1384
|
+
namedResponses: {
|
|
1385
|
+
byCountry: [{ id: 'SP', label: 'São Paulo' }],
|
|
1386
|
+
},
|
|
1387
|
+
},
|
|
1388
|
+
}}
|
|
1389
|
+
/>
|
|
1390
|
+
</FormGroupContextProvider>
|
|
1391
|
+
```
|
|
1392
|
+
|
|
1393
|
+
### `TPrefetchedFieldData` interface
|
|
1394
|
+
|
|
1395
|
+
```typescript
|
|
1396
|
+
interface TPrefetchedFieldData {
|
|
1397
|
+
/** Pre-fetched response for the field's default API config */
|
|
1398
|
+
defaultResponse?: unknown;
|
|
1399
|
+
/** Pre-fetched responses keyed by named API config name */
|
|
1400
|
+
namedResponses?: Record<string, unknown>;
|
|
1401
|
+
}
|
|
1402
|
+
```
|
|
1403
|
+
|
|
1404
|
+
### Next.js App Router
|
|
1405
|
+
|
|
1406
|
+
The package includes `'use client'` directive in the built output. Use it inside a client component:
|
|
1407
|
+
|
|
1408
|
+
```typescript
|
|
1409
|
+
// app/form/page.tsx (Server Component)
|
|
1410
|
+
import { FormClient } from './FormClient';
|
|
1411
|
+
|
|
1412
|
+
export default async function Page() {
|
|
1413
|
+
const countries = await fetch('https://api.example.com/countries').then(r => r.json());
|
|
1414
|
+
return <FormClient countries={countries} />;
|
|
1415
|
+
}
|
|
1416
|
+
|
|
1417
|
+
// app/form/FormClient.tsx (Client Component)
|
|
1418
|
+
'use client';
|
|
1419
|
+
import { Form, FormGroupContextProvider } from '@bolttech/form-engine';
|
|
1420
|
+
|
|
1421
|
+
export function FormClient({ countries }) {
|
|
1422
|
+
return (
|
|
1423
|
+
<FormGroupContextProvider mappers={mappers}>
|
|
1424
|
+
<Form
|
|
1425
|
+
schema={schema}
|
|
1426
|
+
prefetchedData={{ country: { defaultResponse: countries } }}
|
|
1427
|
+
/>
|
|
1428
|
+
</FormGroupContextProvider>
|
|
1429
|
+
);
|
|
1430
|
+
}
|
|
1431
|
+
```
|
|
1432
|
+
|
|
1433
|
+
### Minimum requirements
|
|
1434
|
+
|
|
1435
|
+
- Node.js 18+ (for native `fetch` support in the core)
|
|
1436
|
+
- React 18+ (for SSR/Streaming support)
|
|
1437
|
+
- `@bolttech/form-engine-core` >= 1.1.0
|