Open History to see the last commit
1import type { FormOptions } from './FormApi/FormApi.public'
2import type { StandardSchemaV1 } from './standardSchema.public'
3import type { FormValidators } from './validation.public'
4β
5type Primitive = string | number | boolean | bigint | symbol | null | undefined
6β
7export type BuiltInType = Primitive | Date | RegExp | Function
8β
9export type Editable<T> = T extends BuiltInType
10 ? T | null | undefined
11 : T extends ReadonlyArray<unknown>
12 ? Array<Editable<T[number]>> | null | undefined
13 : T extends object
14 ? EditableObject<T> | null | undefined
15 : T | null | undefined
16β
17type EditableObject<in out T extends object> = {
18 [K in keyof T]?: Editable<T[K]>
19}
20β
21export type InferUnion<TBase, TIncoming> = TBase extends BuiltInType
22 ? TBase | TIncoming
23 : TIncoming extends BuiltInType
24 ? TBase | TIncoming
25 : TBase extends ReadonlyArray<unknown>
26 ? TIncoming extends ReadonlyArray<unknown>
27 ? Array<InferUnion<TBase[number], TIncoming[number]>>
28 : TBase | TIncoming
29 : TBase extends object
30 ? TIncoming extends object
31 ? InferUnionObject<TBase, TIncoming>
32 : TBase | TIncoming
33 : TBase | TIncoming
34β
35type InferUnionObject<
36 in out TBase extends object,
37 in out TIncoming extends object,
38> = {
39 [K in keyof TBase | keyof TIncoming]: K extends keyof TBase
40 ? K extends keyof TIncoming
41 ? InferUnion<TBase[K], TIncoming[K]>
42 : TBase[K]
43 : K extends keyof TIncoming
44 ? TIncoming[K] | undefined
45 : never
46}
47β
48export type FormValidatorData<TFormValidators extends FormValidators<any>> =
49 TFormValidators extends FormValidators<infer T> ? T : never
50β
51export type NullableSchemaData<TFormValidators extends FormValidators<any>> =
52 Editable<FormValidatorData<TFormValidators>>
53β
54type StandardSchemaInput<TSchema extends StandardSchemaV1<any, any>> =
55 TSchema extends StandardSchemaV1<infer TInput, any> ? TInput : never
56β
57type LooseSchemaFormOptions<
58 TSchemaInput,
59 TFormData extends Editable<TSchemaInput>,
60 TFormValidators extends FormValidators<
61 NoInfer<InferUnion<TFormData, TSchemaInput>>
62 >,
63 TSubmitReturn,
64> = Omit<
65 FormOptions<
66 InferUnion<TFormData, TSchemaInput>,
67 TFormValidators,
68 TSubmitReturn,
69 unknown
70 >,
71 'defaultValues'
72> & {
73 defaultValues: TFormData
74}
75β
76/**
77 * Types strict form options using a separate schema as the source of the form
78 * data type.
79 *
80 * The schema input fixes the form data type before the options are inferred,
81 * so `defaultValues` and each callback validator's `value` use the exact
82 * schema input type.
83 *
84 * The first argument is used only by TypeScript and is ignored at runtime.
85 * Include the schema in `validators` as well when it should validate the form.
86 * Parsed results are available in the corresponding `validatorOutputs` entries
87 * during submission.
88 *
89 * @example
90 * ```ts
91 * const profileSchema = z.object({ name: z.string().min(1) })
92 * const profileOptions = formOptions.strictSchema(profileSchema, {
93 * defaultValues: { name: '' },
94 * validators: [
95 * { triggers: ['change'], run: profileSchema },
96 * {
97 * triggers: ['change'],
98 * run: ({ value }) =>
99 * value.name.length === 0 ? 'Name is required' : undefined,
100 * },
101 * ],
102 * })
103 * ```
104 *
105 * @param schema - Supplies the form data type without registering a validator.
106 * @param options - The form options to type against the schema input.
107 * @returns The original options object, normalized to `FormOptions` with the
108 * schema input as its form data type.
109 * @typeParam TComponents - Library-managed. Do not specify explicitly.
110 * @typeParam TSchema - Library-managed. Do not specify explicitly.
111 * @typeParam TFormValidators - Library-managed. Do not specify explicitly.
112 * @typeParam TSubmitReturn - Library-managed. Do not specify explicitly.
113 */
114export type FormOptionsStrictSchemaFn<TComponents> = <
115 const TSchema extends StandardSchemaV1<any, any>,
116 const TFormValidators extends FormValidators<StandardSchemaInput<TSchema>>,
117 TSubmitReturn,
118>(
119 schema: TSchema,
120 options: FormOptions<
121 StandardSchemaInput<TSchema>,
122 TFormValidators,
123 TSubmitReturn,
124 unknown
125 >,
126) => FormOptions<
127 StandardSchemaInput<TSchema>,
128 TFormValidators,
129 TSubmitReturn,
130 TComponents
131>
132β
133/**
134 * Types loose schema form options using a separate schema as the source of the
135 * final valid form shape.
136 *
137 * `defaultValues` infer an editable form shape constrained by the schema input,
138 * so properties may be omitted or contain `null` or `undefined`. Callback
139 * validator `value` parameters use that editable shape merged with the schema
140 * input.
141 *
142 * The first argument is used only by TypeScript and is ignored at runtime.
143 * Include the schema in `validators` as well when it should validate the form.
144 * Parsed results are available in the corresponding `validatorOutputs` entries
145 * during submission.
146 *
147 * @example
148 * ```ts
149 * const bookingSchema = z.object({ startDate: z.date() })
150 * const bookingOptions = formOptions.looseSchema(bookingSchema, {
151 * defaultValues: { startDate: null },
152 * validators: [
153 * { triggers: ['blur'], run: bookingSchema },
154 * {
155 * triggers: ['change'],
156 * run: ({ value }) =>
157 * value.startDate === null ? 'Choose a date' : undefined,
158 * },
159 * ],
160 * })
161 * ```
162 *
163 * @param schema - Supplies the final valid form shape without registering a
164 * validator.
165 * @param options - The form options used to infer the editable form shape.
166 * @returns The original options object, normalized to `FormOptions` with the
167 * editable states merged into the schema input.
168 * @typeParam TComponents - Library-managed. Do not specify explicitly.
169 * @typeParam TSchema - Library-managed. Do not specify explicitly.
170 * @typeParam TFormData - Library-managed. Do not specify explicitly.
171 * @typeParam TFormValidators - Library-managed. Do not specify explicitly.
172 * @typeParam TSubmitReturn - Library-managed. Do not specify explicitly.
173 */
174export type FormOptionsLooseSchemaFn<TComponents> = <
175 const TSchema extends StandardSchemaV1<any, any>,
176 const TFormData extends Editable<StandardSchemaInput<TSchema>>,
177 const TFormValidators extends FormValidators<
178 NoInfer<InferUnion<TFormData, StandardSchemaInput<TSchema>>>
179 >,
180 TSubmitReturn,
181>(
182 schema: TSchema,
183 options: LooseSchemaFormOptions<
184 StandardSchemaInput<TSchema>,
185 TFormData,
186 TFormValidators,
187 TSubmitReturn
188 >,
189) => FormOptions<
190 InferUnion<TFormData, StandardSchemaInput<TSchema>>,
191 TFormValidators,
192 TSubmitReturn,
193 TComponents
194>
195β
196/**
197 * The callable API exposed by `formOptions`, including its schema-driven
198 * inference modes.
199 *
200 * Use `formOptions` directly instead of naming this interface in application
201 * code.
202 *
203 * @typeParam TComponents - Library-managed. Do not specify explicitly.
204 */
205export interface FormOptionsApi<out TComponents> {
206 /**
207 * Keeps types inferred from `defaultValues`, validators, and submission
208 * callbacks when form options are declared separately.
209 *
210 * `defaultValues` determine the form data shape in this mode. At runtime,
211 * this returns the original options object and does not create a form or run
212 * validation.
213 *
214 * @remarks
215 * **Important:** Although this returns the original object unchanged at
216 * runtime, its type is normalized to `FormOptions`. Optional properties such
217 * as `validators` therefore remain optional even when supplied. This
218 * tradeoff enables safer inference and reuse.
219 *
220 * @returns The original options object, normalized to `FormOptions` with its
221 * inferred form data, validator, and submission types.
222 * @typeParam TFormData - Library-managed. Do not specify explicitly.
223 * @typeParam TFormValidators - Library-managed. Do not specify explicitly.
224 * @typeParam TSubmitReturn - Library-managed. Do not specify explicitly.
225 */
226 <
227 TFormData,
228 const TFormValidators extends FormValidators<TFormData>,
229 TSubmitReturn,
230 >(
231 options: FormOptions<TFormData, TFormValidators, TSubmitReturn, unknown>,
232 ): FormOptions<TFormData, TFormValidators, TSubmitReturn, TComponents>
233β
234 /**
235 * Infers the form data type from a Standard Schema validator and requires
236 * `defaultValues` to match the schema input.
237 *
238 * Use this when the schema represents an input-to-output pipeline. Raw form
239 * state remains available as `value`; read each validator's parsed output
240 * from the corresponding `validatorOutputs` entry during submission.
241 *
242 * Pass the schema as the first argument and the options as the second. This
243 * fixes the form data to the schema input before the options are inferred, so
244 * each callback receives a typed `value`. The first argument is ignored at
245 * runtime; include the schema in `validators` when it should run.
246 *
247 * @remarks
248 * **Important:** Although this returns the original object unchanged at
249 * runtime, its type is normalized to `FormOptions`. Optional properties such
250 * as `validators` therefore remain optional even when supplied. This
251 * tradeoff enables safer inference and reuse.
252 *
253 * @example
254 * ```ts
255 * const profileSchema = z.object({ name: z.string().min(1) })
256 * const profileOptions = formOptions.strictSchema(profileSchema, {
257 * defaultValues: { name: '' },
258 * validators: [
259 * {
260 * triggers: ['change'],
261 * run: profileSchema,
262 * },
263 * {
264 * triggers: ['change'],
265 * run: ({ value }) =>
266 * value.name.length === 0 ? 'Name is required' : undefined,
267 * },
268 * ],
269 * onSubmit: ({ validatorOutputs }) => saveProfile(validatorOutputs[0]),
270 * })
271 * ```
272 *
273 * @returns The original options object, normalized to `FormOptions` with the
274 * schema's input shape.
275 * @typeParam TSchema - Library-managed. Do not specify explicitly.
276 * @typeParam TFormValidators - Library-managed. Do not specify explicitly.
277 * @typeParam TFormData - Library-managed. Do not specify explicitly.
278 * @typeParam TSubmitReturn - Library-managed. Do not specify explicitly.
279 */
280 strictSchema: FormOptionsStrictSchemaFn<TComponents>
281β
282 /**
283 * Infers the form data shape from a Standard Schema validator while allowing
284 * editable defaults to omit properties or contain `null` or `undefined`
285 * values.
286 *
287 * Use this when the schema represents the final valid shape but the UI needs
288 * intermediate empty states, such as an unselected date. Raw form state
289 * remains available as `value`; read each validator's parsed output from the
290 * corresponding `validatorOutputs` entry during submission.
291 *
292 * Pass the schema as the first argument and the options as the second.
293 * `defaultValues` infer an editable form shape constrained by the schema
294 * input, and callbacks receive that shape merged with the schema input. The
295 * first argument is ignored at runtime; include the schema in `validators`
296 * when it should run.
297 *
298 * @remarks
299 * **Important:** Although this returns the original object unchanged at
300 * runtime, its type is normalized to `FormOptions`. Optional properties such
301 * as `validators` therefore remain optional even when supplied. This
302 * tradeoff enables safer inference and reuse.
303 *
304 * @example
305 * ```ts
306 * const bookingSchema = z.object({ startDate: z.date() })
307 * const bookingOptions = formOptions.looseSchema(bookingSchema, {
308 * defaultValues: { startDate: null },
309 * validators: [
310 * {
311 * triggers: ['blur'],
312 * run: bookingSchema,
313 * },
314 * {
315 * triggers: ['change'],
316 * run: ({ value }) =>
317 * value.startDate === null ? 'Choose a date' : undefined,
318 * },
319 * ],
320 * onSubmit: ({ validatorOutputs }) => saveBooking(validatorOutputs[0]),
321 * })
322 * ```
323 *
324 * @returns The original options object, normalized to `FormOptions` with
325 * omitted, nullable, and undefined editable states merged into the schema's
326 * input shape.
327 * @typeParam TSchema - Library-managed. Do not specify explicitly.
328 * @typeParam TFormValidators - Library-managed. Do not specify explicitly.
329 * @typeParam TFormData - Library-managed. Do not specify explicitly.
330 * @typeParam TSubmitReturn - Library-managed. Do not specify explicitly.
331 */
332 looseSchema: FormOptionsLooseSchemaFn<TComponents>
333}
334β
335/**
336 * Keeps form data, validator, and submission types inferred when options are
337 * declared separately from a framework's form creation API.
338 *
339 * The regular helper takes `defaultValues` at face value as the form data
340 * shape. For schema-driven inference, use `formOptions.strictSchema` when the
341 * schema defines an input-to-output boundary, or `formOptions.looseSchema` when
342 * the schema defines the shape but editable defaults may omit properties or
343 * need `null` or `undefined` values.
344 *
345 * At runtime, this is an identity helper: it returns the original options
346 * object and does not create a form or run validation.
347 *
348 * @remarks
349 * **Important:** Although this returns the original object unchanged at
350 * runtime, its type is normalized to `FormOptions`. Optional properties such
351 * as `validators` therefore remain optional even when supplied. This tradeoff
352 * enables safer inference and reuse.
353 *
354 * @example
355 * ```ts
356 * const profileOptions = formOptions({
357 * defaultValues: { name: '' },
358 * validators: [
359 * {
360 * triggers: ['change'],
361 * run: ({ value }) =>
362 * value.name.length === 0 ? 'Name is required' : undefined,
363 * },
364 * ],
365 * })
366 *
367 * const form = useForm({
368 * ...profileOptions,
369 * onSubmit: ({ value }) => saveProfile(value),
370 * })
371 * ```
372 */
373const formOptions = ((opts) => opts) as FormOptionsApi<unknown>
374β
375formOptions.strictSchema = ((_schema: unknown, opts: unknown) => opts) as never
376formOptions.looseSchema = ((_schema: unknown, opts: unknown) => opts) as never
377β
378export { formOptions }