@explita/formly 0.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/README.md +261 -0
- package/README.old.md +141 -0
- package/dist/components/field-error.d.ts +2 -0
- package/dist/components/field-error.js +14 -0
- package/dist/components/field.d.ts +4 -0
- package/dist/components/field.js +120 -0
- package/dist/components/form-spy.d.ts +16 -0
- package/dist/components/form-spy.js +66 -0
- package/dist/components/index.d.ts +4 -0
- package/dist/components/index.js +20 -0
- package/dist/components/label.d.ts +2 -0
- package/dist/components/label.js +46 -0
- package/dist/hooks/use-field.d.ts +21 -0
- package/dist/hooks/use-field.js +66 -0
- package/dist/hooks/use-form-by-id.d.ts +6 -0
- package/dist/hooks/use-form-by-id.js +25 -0
- package/dist/hooks/use-form-context.d.ts +5 -0
- package/dist/hooks/use-form-context.js +17 -0
- package/dist/hooks/use-form.d.ts +43 -0
- package/dist/hooks/use-form.js +961 -0
- package/dist/index.d.ts +9 -0
- package/dist/index.js +25 -0
- package/dist/lib/array-helpers.d.ts +6 -0
- package/dist/lib/array-helpers.js +281 -0
- package/dist/lib/css.d.ts +1 -0
- package/dist/lib/css.js +45 -0
- package/dist/lib/debounce.d.ts +13 -0
- package/dist/lib/debounce.js +28 -0
- package/dist/lib/deep-path.d.ts +4 -0
- package/dist/lib/deep-path.js +60 -0
- package/dist/lib/drafts-helpter.d.ts +31 -0
- package/dist/lib/drafts-helpter.js +67 -0
- package/dist/lib/form-registry.d.ts +9 -0
- package/dist/lib/form-registry.js +24 -0
- package/dist/lib/group-helpers.d.ts +9 -0
- package/dist/lib/group-helpers.js +29 -0
- package/dist/lib/pub-sub.d.ts +13 -0
- package/dist/lib/pub-sub.js +38 -0
- package/dist/lib/utils.d.ts +17 -0
- package/dist/lib/utils.js +190 -0
- package/dist/lib/validation.d.ts +22 -0
- package/dist/lib/validation.js +46 -0
- package/dist/lib/zod-helpers.d.ts +5 -0
- package/dist/lib/zod-helpers.js +63 -0
- package/dist/providers/form.d.ts +51 -0
- package/dist/providers/form.js +63 -0
- package/dist/types/array.d.ts +197 -0
- package/dist/types/array.js +2 -0
- package/dist/types/field.d.ts +61 -0
- package/dist/types/field.js +2 -0
- package/dist/types/group.d.ts +16 -0
- package/dist/types/group.js +2 -0
- package/dist/types/path.d.ts +8 -0
- package/dist/types/path.js +2 -0
- package/dist/types/pub-sub.d.ts +2 -0
- package/dist/types/pub-sub.js +2 -0
- package/dist/types/utils.d.ts +310 -0
- package/dist/types/utils.js +2 -0
- package/dist/utils/index.d.ts +4 -0
- package/dist/utils/index.js +14 -0
- package/package.json +53 -0
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
import { Path } from "./path";
|
|
2
|
+
import { Compute, Computed, SetValues } from "./utils";
|
|
3
|
+
export type ArrayItem<T, P extends string> = P extends `${infer Key}.${infer Rest}` ? Key extends keyof T ? T[Key] extends Record<string, any> ? ArrayItem<T[Key], Rest> : never : never : P extends keyof T ? T[P] extends Array<infer U> ? U : never : never;
|
|
4
|
+
export type ArrayHelpers<T> = {
|
|
5
|
+
/**
|
|
6
|
+
* Returns the array of values for the specified path.
|
|
7
|
+
* @returns The array of values for the specified path.
|
|
8
|
+
*/
|
|
9
|
+
get: () => T[];
|
|
10
|
+
/**
|
|
11
|
+
* Returns the array of values for the specified path.
|
|
12
|
+
* @returns The array of values for the specified path.
|
|
13
|
+
*/
|
|
14
|
+
value: T[];
|
|
15
|
+
toObject: () => Record<number, T>;
|
|
16
|
+
/**
|
|
17
|
+
* Returns the length of the array for the specified path.
|
|
18
|
+
* @returns The length of the array for the specified path.
|
|
19
|
+
*/
|
|
20
|
+
length: number;
|
|
21
|
+
/**
|
|
22
|
+
* Sets the array of values for the specified path.
|
|
23
|
+
* @param arr The array of values to set for the specified path.
|
|
24
|
+
*/
|
|
25
|
+
/**
|
|
26
|
+
* Updates the item at the specified index.
|
|
27
|
+
* @param index The index of the item to update.
|
|
28
|
+
* @param item The new value for the item.
|
|
29
|
+
*/
|
|
30
|
+
updateAt: (index: number, item: T) => ArrayHelpers<T>;
|
|
31
|
+
/**
|
|
32
|
+
* Replaces all items in the array for the specified path with the new array.
|
|
33
|
+
* @param newArray The new array of values to set for the specified path.
|
|
34
|
+
*/
|
|
35
|
+
replaceAll: (newArray: T[]) => ArrayHelpers<T>;
|
|
36
|
+
/**
|
|
37
|
+
* Replaces the first item in the array that satisfies the provided testing function.
|
|
38
|
+
* @param fn The testing function to apply to each item in the array.
|
|
39
|
+
* @param newItem The new value for the item.
|
|
40
|
+
*/
|
|
41
|
+
replaceWhere: (fn: (item: T) => boolean, newItem: T) => ArrayHelpers<T>;
|
|
42
|
+
/**
|
|
43
|
+
* Adds a new value to the array at the end.
|
|
44
|
+
* @param value The value to add to the array.
|
|
45
|
+
*/
|
|
46
|
+
push: (value: T | T[]) => ArrayHelpers<T>;
|
|
47
|
+
/**
|
|
48
|
+
* Inserts a new value at the specified index.
|
|
49
|
+
* @param index The index at which to insert the value.
|
|
50
|
+
* @param value The value to insert into the array.
|
|
51
|
+
*/
|
|
52
|
+
insert: (index: number, value: T) => ArrayHelpers<T>;
|
|
53
|
+
/**
|
|
54
|
+
* Inserts a new value at the begining of the array.
|
|
55
|
+
* @param value The value to insert into the array.
|
|
56
|
+
*/
|
|
57
|
+
insertFirst: (value: T) => ArrayHelpers<T>;
|
|
58
|
+
/**
|
|
59
|
+
* Moves an item from one index to another.
|
|
60
|
+
* @param from The index of the item to move.
|
|
61
|
+
* @param to The index to move the item to.
|
|
62
|
+
*/
|
|
63
|
+
move: (from: number, to: number) => ArrayHelpers<T>;
|
|
64
|
+
/**
|
|
65
|
+
* Moves an item up by one index.
|
|
66
|
+
* @param index The index of the item to move up.
|
|
67
|
+
*/
|
|
68
|
+
moveUp: (index: number) => ArrayHelpers<T>;
|
|
69
|
+
/**
|
|
70
|
+
* Moves an item down by one index.
|
|
71
|
+
* @param index The index of the item to move down.
|
|
72
|
+
*/
|
|
73
|
+
moveDown: (index: number) => ArrayHelpers<T>;
|
|
74
|
+
/**
|
|
75
|
+
* Swaps the items at the specified indices.
|
|
76
|
+
* @param a The index of the first item to swap.
|
|
77
|
+
* @param b The index of the second item to swap.
|
|
78
|
+
*/
|
|
79
|
+
swap: (a: number, b: number) => ArrayHelpers<T>;
|
|
80
|
+
/**
|
|
81
|
+
* Merges the array with the new array.
|
|
82
|
+
* @param fn The callback function to apply to each item in the array.
|
|
83
|
+
*/
|
|
84
|
+
merge: (fn: (old: T[]) => T[]) => ArrayHelpers<T>;
|
|
85
|
+
/**
|
|
86
|
+
* Removes all falsey values from the array.
|
|
87
|
+
*/
|
|
88
|
+
compact: () => ArrayHelpers<T>;
|
|
89
|
+
/**
|
|
90
|
+
* Sorts the array.
|
|
91
|
+
* @param fn The callback function to apply to each item in the array.
|
|
92
|
+
*/
|
|
93
|
+
sort: (fn: (a: T, b: T) => number) => ArrayHelpers<T>;
|
|
94
|
+
/**
|
|
95
|
+
* Removes the item at the specified index from the array for the specified path and updates the form values.
|
|
96
|
+
* @param index The index of the item to remove.
|
|
97
|
+
*/
|
|
98
|
+
remove: (index: number) => void;
|
|
99
|
+
/**
|
|
100
|
+
* Removes all items from the array for the specified path and updates the form values.
|
|
101
|
+
*/
|
|
102
|
+
removeIf: (fn: (item: T, index: number) => boolean) => ArrayHelpers<T>;
|
|
103
|
+
/**
|
|
104
|
+
* Removes all items from the array for the specified path and updates the form values.
|
|
105
|
+
*/
|
|
106
|
+
clear: () => void;
|
|
107
|
+
/**
|
|
108
|
+
* Maps the array for the specified path and updates the form values.
|
|
109
|
+
* @param fn The callback function to apply to each item in the array.
|
|
110
|
+
*/
|
|
111
|
+
map: (fn: (item: T, index: number) => T) => ArrayHelpers<T>;
|
|
112
|
+
/**
|
|
113
|
+
* Filters the array for the specified path and updates the form values.
|
|
114
|
+
* @param fn The testing function to apply to each item in the array.
|
|
115
|
+
*/
|
|
116
|
+
filter: (fn: (item: T, index: number) => boolean) => ArrayHelpers<T>;
|
|
117
|
+
/**
|
|
118
|
+
* Finds the index of the first item in the array for the specified path that satisfies the provided testing function.
|
|
119
|
+
* @param fn The testing function to apply to each item in the array.
|
|
120
|
+
* @returns The index of the first item in the array for the specified path that satisfies the provided testing function, or -1 if no such item is found.
|
|
121
|
+
*/
|
|
122
|
+
findIndex: (fn: (item: T) => boolean) => number;
|
|
123
|
+
/**
|
|
124
|
+
* Checks if the item at the specified index is the first item in the array.
|
|
125
|
+
* @param index The index of the item to check.
|
|
126
|
+
* @returns True if the item is the first item in the array, false otherwise.
|
|
127
|
+
*/
|
|
128
|
+
isFirst: (index: number) => boolean;
|
|
129
|
+
/**
|
|
130
|
+
* Checks if the item at the specified index is the last item in the array.
|
|
131
|
+
* @param index The index of the item to check.
|
|
132
|
+
* @returns True if the item is the last item in the array, false otherwise.
|
|
133
|
+
*/
|
|
134
|
+
isLast: (index: number) => boolean;
|
|
135
|
+
/**
|
|
136
|
+
* Returns the first item in the array for the specified path.
|
|
137
|
+
* @returns The first item in the array for the specified path.
|
|
138
|
+
*/
|
|
139
|
+
first: () => T;
|
|
140
|
+
/**
|
|
141
|
+
* Returns the last item in the array for the specified path.
|
|
142
|
+
* @returns The last item in the array for the specified path.
|
|
143
|
+
*/
|
|
144
|
+
last: () => T;
|
|
145
|
+
/**
|
|
146
|
+
* Checks if the array for the specified path contains at least one item that satisfies the provided testing function.
|
|
147
|
+
* @param fn The testing function to apply to each item in the array.
|
|
148
|
+
* @returns True if the array for the specified path contains at least one item that satisfies the provided testing function, false otherwise.
|
|
149
|
+
*/
|
|
150
|
+
some: (fn: (item: T, index: number) => boolean) => boolean;
|
|
151
|
+
/**
|
|
152
|
+
* Checks if all items in the array for the specified path satisfy the provided testing function.
|
|
153
|
+
* @param fn The testing function to apply to each item in the array.
|
|
154
|
+
* @returns True if all items in the array for the specified path satisfy the provided testing function, false otherwise.
|
|
155
|
+
*/
|
|
156
|
+
every: (fn: (item: T, index: number) => boolean) => boolean;
|
|
157
|
+
};
|
|
158
|
+
export type ArrayHelperProps<T> = {
|
|
159
|
+
path: Path<T>;
|
|
160
|
+
formValues: T;
|
|
161
|
+
setValues: SetValues<T>;
|
|
162
|
+
computed?: Computed<T>;
|
|
163
|
+
compute: Compute<T>;
|
|
164
|
+
getCurrentArrayValue: () => T[];
|
|
165
|
+
};
|
|
166
|
+
export type HandlerArrayHelpers<T> = {
|
|
167
|
+
/**
|
|
168
|
+
* Returns the modified form object.
|
|
169
|
+
* @returns Returns the modified form object.
|
|
170
|
+
*/
|
|
171
|
+
snapshot: () => T;
|
|
172
|
+
/**
|
|
173
|
+
* Returns the array of values for the specified path.
|
|
174
|
+
* @returns The array of values for the specified path.
|
|
175
|
+
*/
|
|
176
|
+
get: () => T[];
|
|
177
|
+
/**
|
|
178
|
+
* Returns the array of values for the specified path.
|
|
179
|
+
* @returns The array of values for the specified path.
|
|
180
|
+
*/
|
|
181
|
+
value: T[];
|
|
182
|
+
/**
|
|
183
|
+
* Filters the array for the specified path and updates the form values.
|
|
184
|
+
* @param fn The testing function to apply to each item in the array.
|
|
185
|
+
*/
|
|
186
|
+
filter: (fn: (item: T) => boolean) => HandlerArrayHelpers<T>;
|
|
187
|
+
/**
|
|
188
|
+
* Removes all items from the array for the specified path and updates the form values.
|
|
189
|
+
* @param fn The testing function to apply to each item in the array.
|
|
190
|
+
*/
|
|
191
|
+
removeIf: (fn: (item: T) => boolean) => HandlerArrayHelpers<T>;
|
|
192
|
+
/**
|
|
193
|
+
* Maps the array for the specified path and updates the form values.
|
|
194
|
+
* @param fn The callback function to apply to each item in the array.
|
|
195
|
+
*/
|
|
196
|
+
map: (fn: (item: T, index: number) => T) => HandlerArrayHelpers<T>;
|
|
197
|
+
};
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
export type FieldHelpers<T> = {
|
|
2
|
+
/**
|
|
3
|
+
* Retrieves the value of the form field.
|
|
4
|
+
*
|
|
5
|
+
* @returns The value of the form field.
|
|
6
|
+
*/
|
|
7
|
+
get: () => T;
|
|
8
|
+
/**
|
|
9
|
+
* Sets the value of the form field.
|
|
10
|
+
*
|
|
11
|
+
* @param value - The value to set for the form field.
|
|
12
|
+
*/
|
|
13
|
+
set: (value: T) => void;
|
|
14
|
+
/**
|
|
15
|
+
* Transforms the value of the form field using the provided function.
|
|
16
|
+
*
|
|
17
|
+
* @param fn - The function to transform the value of the form field.
|
|
18
|
+
*/
|
|
19
|
+
transform(fn: (val: T) => unknown): void;
|
|
20
|
+
/**
|
|
21
|
+
* Validates a specific form field value using the provided schema. If validation fails,
|
|
22
|
+
* the error is parsed and set in the form errors. The function is debounced to prevent
|
|
23
|
+
* excessive validation calls.
|
|
24
|
+
*
|
|
25
|
+
* @param name - The name of the form field to validate.
|
|
26
|
+
* @param inputValue - The value of the form field to be validated.
|
|
27
|
+
*/
|
|
28
|
+
validate: () => void;
|
|
29
|
+
/**
|
|
30
|
+
* Focuses the form field.
|
|
31
|
+
*/
|
|
32
|
+
focus: () => void;
|
|
33
|
+
/**
|
|
34
|
+
* Resets the form field to its default value.
|
|
35
|
+
*/
|
|
36
|
+
reset: () => void;
|
|
37
|
+
/**
|
|
38
|
+
* Retrieves the error of the form field.
|
|
39
|
+
*
|
|
40
|
+
* @returns The error of the form field.
|
|
41
|
+
*/
|
|
42
|
+
error: string;
|
|
43
|
+
/**
|
|
44
|
+
* Indicates whether the form field has an error.
|
|
45
|
+
*
|
|
46
|
+
* @returns `true` if the form field has an error, `false` otherwise.
|
|
47
|
+
*/
|
|
48
|
+
hasError: boolean;
|
|
49
|
+
/**
|
|
50
|
+
* Indicates whether the form field has been touched.
|
|
51
|
+
*
|
|
52
|
+
* @returns `true` if the form field has been touched, `false` otherwise.
|
|
53
|
+
*/
|
|
54
|
+
isTouched: boolean;
|
|
55
|
+
/**
|
|
56
|
+
* Indicates whether the form field has been modified.
|
|
57
|
+
*
|
|
58
|
+
* @returns `true` if the form field has been modified, `false` otherwise.
|
|
59
|
+
*/
|
|
60
|
+
isDirty: boolean;
|
|
61
|
+
};
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { Path, PathValue } from "./path";
|
|
2
|
+
import { SetValues } from "./utils";
|
|
3
|
+
export type GroupHelpersProps<T> = {
|
|
4
|
+
path: Path<T>;
|
|
5
|
+
defaultValues: T;
|
|
6
|
+
formValues: T;
|
|
7
|
+
setValues: SetValues<T>;
|
|
8
|
+
getCurrentValue: () => PathValue<T, Path<T>>;
|
|
9
|
+
validatePartial: (values: Partial<T>) => Promise<void>;
|
|
10
|
+
};
|
|
11
|
+
export type GroupHelpers<T> = {
|
|
12
|
+
get: () => T;
|
|
13
|
+
set: (value: Partial<T>) => void;
|
|
14
|
+
reset: () => void;
|
|
15
|
+
validate: () => void;
|
|
16
|
+
};
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
type DotPrefix<T extends string> = T extends "" ? "" : `.${T}`;
|
|
2
|
+
type PathImpl<T, D extends number = 5> = D extends 0 ? never : T extends object ? {
|
|
3
|
+
[K in Extract<keyof T, string>]: T[K] extends Array<infer U> ? `${K}` | `${K}.${number}` | (D extends 1 ? never : `${K}.${number}${DotPrefix<PathImpl<U, Prev[D]>>}`) : `${K}` | (D extends 1 ? never : `${K}${DotPrefix<PathImpl<T[K], Prev[D]>>}`);
|
|
4
|
+
}[Extract<keyof T, string>] : "";
|
|
5
|
+
type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
|
|
6
|
+
export type Path<T> = PathImpl<T>;
|
|
7
|
+
export type PathValue<T, P extends string | undefined> = string extends P ? unknown : P extends keyof NonNullable<T> ? NonNullable<T>[P] : P extends `${infer Key}.${infer Rest}` ? Key extends keyof NonNullable<T> ? PathValue<NonNullable<T>[Key], Rest> : Key extends `${number}` ? NonNullable<T> extends ReadonlyArray<infer U> ? PathValue<U, Rest> : never : never : P extends `${number}` ? NonNullable<T> extends ReadonlyArray<infer U> ? U : never : never;
|
|
8
|
+
export {};
|
|
@@ -0,0 +1,310 @@
|
|
|
1
|
+
import type { z, ZodObject } from "zod";
|
|
2
|
+
import { Path, PathValue } from "./path";
|
|
3
|
+
import { ArrayHelpers, ArrayItem, HandlerArrayHelpers } from "./array";
|
|
4
|
+
import { GroupHelpers } from "./group";
|
|
5
|
+
import { FieldHelpers } from "./field";
|
|
6
|
+
import { Field } from "../components";
|
|
7
|
+
import { createFormBus } from "../lib/pub-sub";
|
|
8
|
+
export type FormShape<F> = F extends FormInstance<infer T> ? T : never;
|
|
9
|
+
export type FormValues<TSchema extends z.ZodObject | undefined = undefined, DefaultValues = TSchema extends undefined ? Record<string, any> : Partial<z.infer<TSchema>>> = TSchema extends z.ZodObject<any> ? FormOptions<TSchema, Partial<z.infer<TSchema>>> : FormOptions<TSchema, DefaultValues>;
|
|
10
|
+
export type SchemaType<TSchema, TValues> = TSchema extends ZodObject<any> ? z.infer<TSchema> : TValues;
|
|
11
|
+
export type InputValue = string | undefined;
|
|
12
|
+
export type InputEvent = React.FormEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | HTMLButtonElement>;
|
|
13
|
+
export type InputChangeEvent = React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | HTMLButtonElement> | React.FormEvent<HTMLButtonElement>;
|
|
14
|
+
type InputMeta = {
|
|
15
|
+
name?: string;
|
|
16
|
+
value: string;
|
|
17
|
+
error?: string;
|
|
18
|
+
hasError: boolean;
|
|
19
|
+
onChange: (value: any) => void;
|
|
20
|
+
internalRef: string;
|
|
21
|
+
};
|
|
22
|
+
export type FieldRegistration = {
|
|
23
|
+
name: string;
|
|
24
|
+
id: string;
|
|
25
|
+
value: string;
|
|
26
|
+
onChange: (e: InputChangeEvent) => void;
|
|
27
|
+
onBlur: () => void;
|
|
28
|
+
"data-input-error": boolean;
|
|
29
|
+
"data-input-ref": string;
|
|
30
|
+
};
|
|
31
|
+
export type FieldRegistrationOptions<T, P extends Path<T>> = {
|
|
32
|
+
defaultValue?: PathValue<T, P>;
|
|
33
|
+
transform?: ((val: PathValue<T, P>) => unknown) | ((val: PathValue<T, P>) => unknown)[];
|
|
34
|
+
validate?: (value: PathValue<T, P>) => string | undefined;
|
|
35
|
+
};
|
|
36
|
+
export type FieldProps<T, P extends Path<T> = Path<T>> = {
|
|
37
|
+
id?: string;
|
|
38
|
+
name: P;
|
|
39
|
+
label?: string;
|
|
40
|
+
as?: "checkbox" | "select" | "date";
|
|
41
|
+
required?: boolean;
|
|
42
|
+
hideError?: boolean;
|
|
43
|
+
className?: string;
|
|
44
|
+
render?: (props: FieldRegistration, meta: InputMeta) => React.ReactNode;
|
|
45
|
+
children?: (props: FieldRegistration, meta: InputMeta) => React.ReactNode;
|
|
46
|
+
transform?: ((val: PathValue<T, P>) => unknown) | ((val: PathValue<T, P>) => unknown)[];
|
|
47
|
+
validate?: (value: PathValue<T, P>) => string | undefined;
|
|
48
|
+
defaultValue?: PathValue<T, P>;
|
|
49
|
+
};
|
|
50
|
+
export type FieldContextType = {
|
|
51
|
+
name?: string;
|
|
52
|
+
label?: string;
|
|
53
|
+
id?: string;
|
|
54
|
+
message?: string;
|
|
55
|
+
required?: boolean;
|
|
56
|
+
hasError: boolean;
|
|
57
|
+
};
|
|
58
|
+
export type HandlerContext<T> = {
|
|
59
|
+
setErrors: SetErrors<T>;
|
|
60
|
+
mapErrors: MapErrors;
|
|
61
|
+
setValues: SetValues<T>;
|
|
62
|
+
reset: () => void;
|
|
63
|
+
focus: (name: Path<T>) => void;
|
|
64
|
+
array: <P extends Path<T>>(path: P) => HandlerArrayHelpers<ArrayItem<T, P>>;
|
|
65
|
+
};
|
|
66
|
+
export type FormInstance<T> = {
|
|
67
|
+
/**
|
|
68
|
+
* Indicates whether the form is currently submitting.
|
|
69
|
+
*/
|
|
70
|
+
isSubmitting: boolean;
|
|
71
|
+
/**
|
|
72
|
+
* Indicates whether the form is validated.
|
|
73
|
+
*/
|
|
74
|
+
isValidated: boolean;
|
|
75
|
+
/**
|
|
76
|
+
* Retrieves the current values of the form.
|
|
77
|
+
*/
|
|
78
|
+
values: T;
|
|
79
|
+
/**
|
|
80
|
+
* Retrieves the errors of the form.
|
|
81
|
+
*/
|
|
82
|
+
errors: Partial<Record<Path<T>, string>>;
|
|
83
|
+
/**
|
|
84
|
+
* Retrieves the current values of the form.
|
|
85
|
+
*/
|
|
86
|
+
getValues: () => T;
|
|
87
|
+
/**
|
|
88
|
+
* Validates the form using the current schema.
|
|
89
|
+
* @returns void
|
|
90
|
+
*/
|
|
91
|
+
validate: () => void;
|
|
92
|
+
/**
|
|
93
|
+
* Validates a partial set of form field values using the provided schema. If validation fails,
|
|
94
|
+
* the error is parsed and set in the form errors. The function is debounced to prevent
|
|
95
|
+
* excessive validation calls.
|
|
96
|
+
*
|
|
97
|
+
* @param values - An object containing key-value pairs to validate.
|
|
98
|
+
*/
|
|
99
|
+
validatePartial: <V extends Path<T>>(values: Record<V, any>) => void;
|
|
100
|
+
/**
|
|
101
|
+
* Updates the value of a specific form field. If the form is in uncontrolled mode
|
|
102
|
+
* or the field name is not provided, the function exits without making changes.
|
|
103
|
+
*
|
|
104
|
+
* @param name - The name of the form field to update.
|
|
105
|
+
* @param value - The new value to set for the specified form field.
|
|
106
|
+
*/
|
|
107
|
+
setValue: <P extends Path<T>>(name: P, value: PathValue<T, P>) => void;
|
|
108
|
+
/**
|
|
109
|
+
* Merges the provided values into the current form values. This function does not
|
|
110
|
+
* update values in uncontrolled mode.
|
|
111
|
+
*
|
|
112
|
+
* @param values - An object containing key-value pairs to update the form with.
|
|
113
|
+
*/
|
|
114
|
+
setValues: (values: Partial<T>, options?: {
|
|
115
|
+
overwrite?: boolean;
|
|
116
|
+
}) => void;
|
|
117
|
+
/**
|
|
118
|
+
* Retrieves the value of a single form field.
|
|
119
|
+
*/
|
|
120
|
+
getValue: <P extends Path<T>>(name: P) => PathValue<T, P>;
|
|
121
|
+
/**
|
|
122
|
+
* Updates the form errors with the provided errors. If the form is in uncontrolled mode
|
|
123
|
+
* or the field name is not provided, the function exits without making changes.
|
|
124
|
+
*
|
|
125
|
+
* @param errors - The errors to set for the form.
|
|
126
|
+
*/
|
|
127
|
+
setErrors: SetErrors<T>;
|
|
128
|
+
/**
|
|
129
|
+
* Retrieves the error of a single form field.
|
|
130
|
+
*/
|
|
131
|
+
getError: <P extends Path<T>>(name: P) => string | undefined;
|
|
132
|
+
/**
|
|
133
|
+
* Retrieves the errors of the form.
|
|
134
|
+
*/
|
|
135
|
+
getErrors: () => Partial<Record<Path<T>, string>>;
|
|
136
|
+
/**
|
|
137
|
+
* Clears the form values and errors, and if persistKey is provided, it will
|
|
138
|
+
* also remove the persisted state from localStorage.
|
|
139
|
+
*/
|
|
140
|
+
reset: () => void;
|
|
141
|
+
/**
|
|
142
|
+
* Resets the value of a specific form field to its default value.
|
|
143
|
+
*
|
|
144
|
+
* @param name - The name of the form field to reset.
|
|
145
|
+
*/
|
|
146
|
+
/**
|
|
147
|
+
* A utility function to be used as a form's `onSubmit` handler.
|
|
148
|
+
*
|
|
149
|
+
* When called, it will validate the form using the current schema, if provided.
|
|
150
|
+
* If the form is valid, it will call the `onValid` function with the validated form values.
|
|
151
|
+
* If the form is invalid, it will set the `isValidated` state to `false` and update the `formErrors` state.
|
|
152
|
+
*
|
|
153
|
+
* If no schema is provided, it will simply call the `onValid` function with the current `formValues`.
|
|
154
|
+
*
|
|
155
|
+
* @param onValid - A function that will be called with the validated form values if the form is valid.
|
|
156
|
+
* @returns A function that can be used as a form's `onSubmit` handler.
|
|
157
|
+
*/
|
|
158
|
+
handleSubmit: (onValid: (data: T, ctx: HandlerContext<T>) => void | Promise<void>) => (event: React.FormEvent<HTMLFormElement>) => void | Promise<void>;
|
|
159
|
+
/**
|
|
160
|
+
* A utility function to register a form field.
|
|
161
|
+
*
|
|
162
|
+
* @param name - The name of the form field to register.
|
|
163
|
+
* @returns An object containing the form field properties.
|
|
164
|
+
*/
|
|
165
|
+
register: <P extends Path<T>>(name: P, options?: FieldRegistrationOptions<T, P>) => FieldRegistration;
|
|
166
|
+
/**
|
|
167
|
+
* A utility function to access and modify a specific form field.
|
|
168
|
+
*
|
|
169
|
+
* @param name - The name of the form field to access.
|
|
170
|
+
* @returns An object containing field helper functions.
|
|
171
|
+
*/
|
|
172
|
+
field: <P extends Path<T>>(name: P) => FieldHelpers<PathValue<T, P>>;
|
|
173
|
+
/**
|
|
174
|
+
* A utility function to access and modify array fields in the form.
|
|
175
|
+
*
|
|
176
|
+
* @param path - The path to the array field in the form values.
|
|
177
|
+
* @returns An object containing array helper functions.
|
|
178
|
+
*/
|
|
179
|
+
array: <P extends Path<T>>(path: P) => ArrayHelpers<ArrayItem<T, P>>;
|
|
180
|
+
/**
|
|
181
|
+
* A utility function to access and modify group fields in the form.
|
|
182
|
+
*
|
|
183
|
+
* @param path - The path to the group field in the form values.
|
|
184
|
+
* @returns An object containing group helper functions.
|
|
185
|
+
*/
|
|
186
|
+
group: <P extends Path<T>>(path: P) => GroupHelpers<PathValue<T, P>>;
|
|
187
|
+
isDirty: (name?: Path<T>) => boolean;
|
|
188
|
+
focus: (name: Path<T>) => void;
|
|
189
|
+
/**
|
|
190
|
+
* A utility function to compute a value based on the form values.
|
|
191
|
+
*
|
|
192
|
+
* @param name - The name of the form field to compute.
|
|
193
|
+
* @param depsOrFn - The dependencies of the form field or a function to compute the value.
|
|
194
|
+
* @param maybeFn - A function to compute the value.
|
|
195
|
+
*/
|
|
196
|
+
compute: Compute<T>;
|
|
197
|
+
/**
|
|
198
|
+
* Watches specified fields for changes and returns reactive values.
|
|
199
|
+
*
|
|
200
|
+
* @param field(s) - The name of the form field(s) to watch
|
|
201
|
+
* @returns The value(s) of the watched field(s)
|
|
202
|
+
*/
|
|
203
|
+
watch: WatchFn<T>;
|
|
204
|
+
/**
|
|
205
|
+
* Subscribes to changes in the form values.
|
|
206
|
+
*
|
|
207
|
+
* @param nameOrCallback - The name/names of the form field/fields to subscribe to or a callback function.
|
|
208
|
+
* @param callback - A callback function that will be called with the value of the subscribed field.
|
|
209
|
+
* @returns A function that can be called to unsubscribe from the changes.
|
|
210
|
+
*/
|
|
211
|
+
subscribe: <P extends Path<T> | undefined = undefined>(nameOrCallback: P | P[] | Subscriber<T, P>, callback?: Subscriber<T, P>) => () => void;
|
|
212
|
+
/**
|
|
213
|
+
* Transforms the value of a specific form field using the provided function.
|
|
214
|
+
*
|
|
215
|
+
* @param name - The name of the form field to transform.
|
|
216
|
+
* @param fn - The function to transform the value of the form field.
|
|
217
|
+
*/
|
|
218
|
+
transform: <P extends Path<T>>(name: P, fn: (val: PathValue<T, P>) => unknown) => void;
|
|
219
|
+
/**
|
|
220
|
+
* A utility function to conditionally show or hide a form field.
|
|
221
|
+
*
|
|
222
|
+
* @param name - The name of the form field to conditionally show or hide.
|
|
223
|
+
* @param deps - The dependencies of the form field.
|
|
224
|
+
* @param fn - The function to conditionally show or hide the form field.
|
|
225
|
+
*/
|
|
226
|
+
debug: () => {
|
|
227
|
+
values: T;
|
|
228
|
+
errors: Record<Path<T>, string>;
|
|
229
|
+
dirty: Record<Path<T>, boolean>;
|
|
230
|
+
touched: Record<Path<T>, boolean>;
|
|
231
|
+
computed: Record<Path<T>, any>;
|
|
232
|
+
subscriptions: {
|
|
233
|
+
fields: Record<Path<T>, Subscriber<T, Path<T>>>;
|
|
234
|
+
errors: Record<Path<T>, Subscriber<T, Path<T>>>;
|
|
235
|
+
};
|
|
236
|
+
state: {
|
|
237
|
+
isSubmitting: boolean;
|
|
238
|
+
isValidated: boolean;
|
|
239
|
+
};
|
|
240
|
+
};
|
|
241
|
+
Field: typeof Field<T>;
|
|
242
|
+
channel: ReturnType<typeof createFormBus<T>>["channel"];
|
|
243
|
+
meta: {
|
|
244
|
+
get<T = unknown>(key: string): T | undefined;
|
|
245
|
+
set: (key: string, value: unknown) => void;
|
|
246
|
+
delete: (key: string) => void;
|
|
247
|
+
has: (key: string) => boolean;
|
|
248
|
+
keys: () => MapIterator<string>;
|
|
249
|
+
values: () => MapIterator<unknown>;
|
|
250
|
+
clear: () => void;
|
|
251
|
+
};
|
|
252
|
+
};
|
|
253
|
+
export type SetValues<T> = (values: Partial<T>, options?: {
|
|
254
|
+
overwrite?: boolean;
|
|
255
|
+
}) => void;
|
|
256
|
+
export type SetErrors<T> = (errors?: Partial<Record<Path<T>, string>> | z.ZodError["issues"]) => void;
|
|
257
|
+
export type FormOptions<TSchema extends ZodObject<any> | undefined, TValues> = {
|
|
258
|
+
schema?: TSchema;
|
|
259
|
+
defaultValues?: TValues;
|
|
260
|
+
errors?: Partial<Record<Path<SchemaType<TSchema, TValues>>, string>>;
|
|
261
|
+
errorParser?: (message: string) => string;
|
|
262
|
+
check?: CheckFn<SchemaType<TSchema, TValues>>;
|
|
263
|
+
computed?: Record<string, Computed<SchemaType<TSchema, TValues>>>;
|
|
264
|
+
onSubmit?: (values: SchemaType<TSchema, TValues>, ctx: HandlerContext<SchemaType<TSchema, TValues>>) => void;
|
|
265
|
+
onReady?: (values: SchemaType<TSchema, TValues>) => void;
|
|
266
|
+
mode?: "controlled" | "uncontrolled";
|
|
267
|
+
/**
|
|
268
|
+
* The validation trigger.
|
|
269
|
+
*
|
|
270
|
+
* @default "change-submit"
|
|
271
|
+
*/
|
|
272
|
+
validateOn?: "change" | "blur" | "submit" | "change-submit";
|
|
273
|
+
/**
|
|
274
|
+
* Used to register the form so it can be accessed outside the hook.
|
|
275
|
+
*/
|
|
276
|
+
id?: string;
|
|
277
|
+
persistKey?: string;
|
|
278
|
+
autoFocusOnError?: boolean;
|
|
279
|
+
savedFormFirst?: boolean;
|
|
280
|
+
};
|
|
281
|
+
type CheckFn<T> = (data: T, ctx: {
|
|
282
|
+
multiPathError: (paths: Path<T>[], message: string) => void;
|
|
283
|
+
focus: (name: Path<T>) => void;
|
|
284
|
+
}) => Promise<Partial<Record<Path<T>, string>> | void> | Partial<Record<Path<T>, string>> | void;
|
|
285
|
+
type MapErrors = <E extends Record<string, any>>(errObj: E, path?: string) => void;
|
|
286
|
+
export type Compute<T> = <P extends Path<T>>(name: string, depsOrFn: P[] | ((values: T, index: number) => any), maybeFn?: (values: T, index: number) => any) => void;
|
|
287
|
+
export type ComputedField<T> = {
|
|
288
|
+
deps?: Path<T>[];
|
|
289
|
+
fn: (values: T, index: number) => any;
|
|
290
|
+
};
|
|
291
|
+
export type Computed<T> = ComputedField<T>;
|
|
292
|
+
export type Subscriber<T, P extends Path<T> | undefined = undefined> = (value: P extends undefined ? T : PathValue<T, P>) => void;
|
|
293
|
+
type WatchFn<T> = {
|
|
294
|
+
(): T;
|
|
295
|
+
<P extends Path<T>>(fields: P[]): {
|
|
296
|
+
[K in P]: PathValue<T, K>;
|
|
297
|
+
} & Array<PathValue<T, P[number]>>;
|
|
298
|
+
<P extends Path<T>>(field: P): PathValue<T, P>;
|
|
299
|
+
};
|
|
300
|
+
type ConditionalEffects = {
|
|
301
|
+
visible?: boolean;
|
|
302
|
+
clear?: boolean;
|
|
303
|
+
unregister?: boolean;
|
|
304
|
+
};
|
|
305
|
+
export type ConditionalConfig<T> = {
|
|
306
|
+
when: (values: T) => boolean;
|
|
307
|
+
then?: Partial<ConditionalEffects>;
|
|
308
|
+
else?: Partial<ConditionalEffects>;
|
|
309
|
+
};
|
|
310
|
+
export {};
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.cn = exports.deleteDraft = exports.readDraft = exports.writeDraftImmediate = exports.writeDraft = exports.validateForm = exports.debounce = void 0;
|
|
4
|
+
var debounce_1 = require("../lib/debounce");
|
|
5
|
+
Object.defineProperty(exports, "debounce", { enumerable: true, get: function () { return debounce_1.debounce; } });
|
|
6
|
+
var validation_1 = require("../lib/validation");
|
|
7
|
+
Object.defineProperty(exports, "validateForm", { enumerable: true, get: function () { return validation_1.validateForm; } });
|
|
8
|
+
var drafts_helpter_1 = require("../lib/drafts-helpter");
|
|
9
|
+
Object.defineProperty(exports, "writeDraft", { enumerable: true, get: function () { return drafts_helpter_1.writeDraft; } });
|
|
10
|
+
Object.defineProperty(exports, "writeDraftImmediate", { enumerable: true, get: function () { return drafts_helpter_1.writeDraftImmediate; } });
|
|
11
|
+
Object.defineProperty(exports, "readDraft", { enumerable: true, get: function () { return drafts_helpter_1.readDraft; } });
|
|
12
|
+
Object.defineProperty(exports, "deleteDraft", { enumerable: true, get: function () { return drafts_helpter_1.deleteDraft; } });
|
|
13
|
+
var utils_1 = require("../lib/utils");
|
|
14
|
+
Object.defineProperty(exports, "cn", { enumerable: true, get: function () { return utils_1.cn; } });
|