UNPKG

201 kBTypeScriptView Raw
1/**
2 * @license Angular v17.3.5
3 * (c) 2010-2024 Google LLC. https://angular.io/
4 * License: MIT
5 */
6
7
8import { AfterViewInit } from '@angular/core';
9import { ChangeDetectorRef } from '@angular/core';
10import { ElementRef } from '@angular/core';
11import { EventEmitter } from '@angular/core';
12import * as i0 from '@angular/core';
13import { InjectionToken } from '@angular/core';
14import { Injector } from '@angular/core';
15import { ModuleWithProviders } from '@angular/core';
16import { Observable } from 'rxjs';
17import { OnChanges } from '@angular/core';
18import { OnDestroy } from '@angular/core';
19import { OnInit } from '@angular/core';
20import { Provider } from '@angular/core';
21import { Renderer2 } from '@angular/core';
22import { SimpleChanges } from '@angular/core';
23import { Type } from '@angular/core';
24import { Version } from '@angular/core';
25
26/**
27 * This is the base class for `FormControl`, `FormGroup`, and `FormArray`.
28 *
29 * It provides some of the shared behavior that all controls and groups of controls have, like
30 * running validators, calculating status, and resetting state. It also defines the properties
31 * that are shared between all sub-classes, like `value`, `valid`, and `dirty`. It shouldn't be
32 * instantiated directly.
33 *
34 * The first type parameter TValue represents the value type of the control (`control.value`).
35 * The optional type parameter TRawValue represents the raw value type (`control.getRawValue()`).
36 *
37 * @see [Forms Guide](/guide/forms)
38 * @see [Reactive Forms Guide](/guide/reactive-forms)
39 * @see [Dynamic Forms Guide](/guide/dynamic-form)
40 *
41 * @publicApi
42 */
43export declare abstract class AbstractControl<TValue = any, TRawValue extends TValue = TValue> {
44 private _parent;
45 private _asyncValidationSubscription;
46 /**
47 * The current value of the control.
48 *
49 * * For a `FormControl`, the current value.
50 * * For an enabled `FormGroup`, the values of enabled controls as an object
51 * with a key-value pair for each member of the group.
52 * * For a disabled `FormGroup`, the values of all controls as an object
53 * with a key-value pair for each member of the group.
54 * * For a `FormArray`, the values of enabled controls as an array.
55 *
56 */
57 readonly value: TValue;
58 /**
59 * Initialize the AbstractControl instance.
60 *
61 * @param validators The function or array of functions that is used to determine the validity of
62 * this control synchronously.
63 * @param asyncValidators The function or array of functions that is used to determine validity of
64 * this control asynchronously.
65 */
66 constructor(validators: ValidatorFn | ValidatorFn[] | null, asyncValidators: AsyncValidatorFn | AsyncValidatorFn[] | null);
67 /**
68 * Returns the function that is used to determine the validity of this control synchronously.
69 * If multiple validators have been added, this will be a single composed function.
70 * See `Validators.compose()` for additional information.
71 */
72 get validator(): ValidatorFn | null;
73 set validator(validatorFn: ValidatorFn | null);
74 /**
75 * Returns the function that is used to determine the validity of this control asynchronously.
76 * If multiple validators have been added, this will be a single composed function.
77 * See `Validators.compose()` for additional information.
78 */
79 get asyncValidator(): AsyncValidatorFn | null;
80 set asyncValidator(asyncValidatorFn: AsyncValidatorFn | null);
81 /**
82 * The parent control.
83 */
84 get parent(): FormGroup | FormArray | null;
85 /**
86 * The validation status of the control.
87 *
88 * @see {@link FormControlStatus}
89 *
90 * These status values are mutually exclusive, so a control cannot be
91 * both valid AND invalid or invalid AND disabled.
92 */
93 readonly status: FormControlStatus;
94 /**
95 * A control is `valid` when its `status` is `VALID`.
96 *
97 * @see {@link AbstractControl.status}
98 *
99 * @returns True if the control has passed all of its validation tests,
100 * false otherwise.
101 */
102 get valid(): boolean;
103 /**
104 * A control is `invalid` when its `status` is `INVALID`.
105 *
106 * @see {@link AbstractControl.status}
107 *
108 * @returns True if this control has failed one or more of its validation checks,
109 * false otherwise.
110 */
111 get invalid(): boolean;
112 /**
113 * A control is `pending` when its `status` is `PENDING`.
114 *
115 * @see {@link AbstractControl.status}
116 *
117 * @returns True if this control is in the process of conducting a validation check,
118 * false otherwise.
119 */
120 get pending(): boolean;
121 /**
122 * A control is `disabled` when its `status` is `DISABLED`.
123 *
124 * Disabled controls are exempt from validation checks and
125 * are not included in the aggregate value of their ancestor
126 * controls.
127 *
128 * @see {@link AbstractControl.status}
129 *
130 * @returns True if the control is disabled, false otherwise.
131 */
132 get disabled(): boolean;
133 /**
134 * A control is `enabled` as long as its `status` is not `DISABLED`.
135 *
136 * @returns True if the control has any status other than 'DISABLED',
137 * false if the status is 'DISABLED'.
138 *
139 * @see {@link AbstractControl.status}
140 *
141 */
142 get enabled(): boolean;
143 /**
144 * An object containing any errors generated by failing validation,
145 * or null if there are no errors.
146 */
147 readonly errors: ValidationErrors | null;
148 /**
149 * A control is `pristine` if the user has not yet changed
150 * the value in the UI.
151 *
152 * @returns True if the user has not yet changed the value in the UI; compare `dirty`.
153 * Programmatic changes to a control's value do not mark it dirty.
154 */
155 readonly pristine: boolean;
156 /**
157 * A control is `dirty` if the user has changed the value
158 * in the UI.
159 *
160 * @returns True if the user has changed the value of this control in the UI; compare `pristine`.
161 * Programmatic changes to a control's value do not mark it dirty.
162 */
163 get dirty(): boolean;
164 /**
165 * True if the control is marked as `touched`.
166 *
167 * A control is marked `touched` once the user has triggered
168 * a `blur` event on it.
169 */
170 readonly touched: boolean;
171 /**
172 * True if the control has not been marked as touched
173 *
174 * A control is `untouched` if the user has not yet triggered
175 * a `blur` event on it.
176 */
177 get untouched(): boolean;
178 /**
179 * A multicasting observable that emits an event every time the value of the control changes, in
180 * the UI or programmatically. It also emits an event each time you call enable() or disable()
181 * without passing along {emitEvent: false} as a function argument.
182 *
183 * **Note**: the emit happens right after a value of this control is updated. The value of a
184 * parent control (for example if this FormControl is a part of a FormGroup) is updated later, so
185 * accessing a value of a parent control (using the `value` property) from the callback of this
186 * event might result in getting a value that has not been updated yet. Subscribe to the
187 * `valueChanges` event of the parent control instead.
188 */
189 readonly valueChanges: Observable<TValue>;
190 /**
191 * A multicasting observable that emits an event every time the validation `status` of the control
192 * recalculates.
193 *
194 * @see {@link FormControlStatus}
195 * @see {@link AbstractControl.status}
196 *
197 */
198 readonly statusChanges: Observable<FormControlStatus>;
199 /**
200 * Reports the update strategy of the `AbstractControl` (meaning
201 * the event on which the control updates itself).
202 * Possible values: `'change'` | `'blur'` | `'submit'`
203 * Default value: `'change'`
204 */
205 get updateOn(): FormHooks;
206 /**
207 * Sets the synchronous validators that are active on this control. Calling
208 * this overwrites any existing synchronous validators.
209 *
210 * When you add or remove a validator at run time, you must call
211 * `updateValueAndValidity()` for the new validation to take effect.
212 *
213 * If you want to add a new validator without affecting existing ones, consider
214 * using `addValidators()` method instead.
215 */
216 setValidators(validators: ValidatorFn | ValidatorFn[] | null): void;
217 /**
218 * Sets the asynchronous validators that are active on this control. Calling this
219 * overwrites any existing asynchronous validators.
220 *
221 * When you add or remove a validator at run time, you must call
222 * `updateValueAndValidity()` for the new validation to take effect.
223 *
224 * If you want to add a new validator without affecting existing ones, consider
225 * using `addAsyncValidators()` method instead.
226 */
227 setAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[] | null): void;
228 /**
229 * Add a synchronous validator or validators to this control, without affecting other validators.
230 *
231 * When you add or remove a validator at run time, you must call
232 * `updateValueAndValidity()` for the new validation to take effect.
233 *
234 * Adding a validator that already exists will have no effect. If duplicate validator functions
235 * are present in the `validators` array, only the first instance would be added to a form
236 * control.
237 *
238 * @param validators The new validator function or functions to add to this control.
239 */
240 addValidators(validators: ValidatorFn | ValidatorFn[]): void;
241 /**
242 * Add an asynchronous validator or validators to this control, without affecting other
243 * validators.
244 *
245 * When you add or remove a validator at run time, you must call
246 * `updateValueAndValidity()` for the new validation to take effect.
247 *
248 * Adding a validator that already exists will have no effect.
249 *
250 * @param validators The new asynchronous validator function or functions to add to this control.
251 */
252 addAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void;
253 /**
254 * Remove a synchronous validator from this control, without affecting other validators.
255 * Validators are compared by function reference; you must pass a reference to the exact same
256 * validator function as the one that was originally set. If a provided validator is not found,
257 * it is ignored.
258 *
259 * @usageNotes
260 *
261 * ### Reference to a ValidatorFn
262 *
263 * ```
264 * // Reference to the RequiredValidator
265 * const ctrl = new FormControl<string | null>('', Validators.required);
266 * ctrl.removeValidators(Validators.required);
267 *
268 * // Reference to anonymous function inside MinValidator
269 * const minValidator = Validators.min(3);
270 * const ctrl = new FormControl<string | null>('', minValidator);
271 * expect(ctrl.hasValidator(minValidator)).toEqual(true)
272 * expect(ctrl.hasValidator(Validators.min(3))).toEqual(false)
273 *
274 * ctrl.removeValidators(minValidator);
275 * ```
276 *
277 * When you add or remove a validator at run time, you must call
278 * `updateValueAndValidity()` for the new validation to take effect.
279 *
280 * @param validators The validator or validators to remove.
281 */
282 removeValidators(validators: ValidatorFn | ValidatorFn[]): void;
283 /**
284 * Remove an asynchronous validator from this control, without affecting other validators.
285 * Validators are compared by function reference; you must pass a reference to the exact same
286 * validator function as the one that was originally set. If a provided validator is not found, it
287 * is ignored.
288 *
289 * When you add or remove a validator at run time, you must call
290 * `updateValueAndValidity()` for the new validation to take effect.
291 *
292 * @param validators The asynchronous validator or validators to remove.
293 */
294 removeAsyncValidators(validators: AsyncValidatorFn | AsyncValidatorFn[]): void;
295 /**
296 * Check whether a synchronous validator function is present on this control. The provided
297 * validator must be a reference to the exact same function that was provided.
298 *
299 * @usageNotes
300 *
301 * ### Reference to a ValidatorFn
302 *
303 * ```
304 * // Reference to the RequiredValidator
305 * const ctrl = new FormControl<number | null>(0, Validators.required);
306 * expect(ctrl.hasValidator(Validators.required)).toEqual(true)
307 *
308 * // Reference to anonymous function inside MinValidator
309 * const minValidator = Validators.min(3);
310 * const ctrl = new FormControl<number | null>(0, minValidator);
311 * expect(ctrl.hasValidator(minValidator)).toEqual(true)
312 * expect(ctrl.hasValidator(Validators.min(3))).toEqual(false)
313 * ```
314 *
315 * @param validator The validator to check for presence. Compared by function reference.
316 * @returns Whether the provided validator was found on this control.
317 */
318 hasValidator(validator: ValidatorFn): boolean;
319 /**
320 * Check whether an asynchronous validator function is present on this control. The provided
321 * validator must be a reference to the exact same function that was provided.
322 *
323 * @param validator The asynchronous validator to check for presence. Compared by function
324 * reference.
325 * @returns Whether the provided asynchronous validator was found on this control.
326 */
327 hasAsyncValidator(validator: AsyncValidatorFn): boolean;
328 /**
329 * Empties out the synchronous validator list.
330 *
331 * When you add or remove a validator at run time, you must call
332 * `updateValueAndValidity()` for the new validation to take effect.
333 *
334 */
335 clearValidators(): void;
336 /**
337 * Empties out the async validator list.
338 *
339 * When you add or remove a validator at run time, you must call
340 * `updateValueAndValidity()` for the new validation to take effect.
341 *
342 */
343 clearAsyncValidators(): void;
344 /**
345 * Marks the control as `touched`. A control is touched by focus and
346 * blur events that do not change the value.
347 *
348 * @see {@link markAsUntouched()}
349 * @see {@link markAsDirty()}
350 * @see {@link markAsPristine()}
351 *
352 * @param opts Configuration options that determine how the control propagates changes
353 * and emits events after marking is applied.
354 * * `onlySelf`: When true, mark only this control. When false or not supplied,
355 * marks all direct ancestors. Default is false.
356 */
357 markAsTouched(opts?: {
358 onlySelf?: boolean;
359 }): void;
360 /**
361 * Marks the control and all its descendant controls as `touched`.
362 * @see {@link markAsTouched()}
363 */
364 markAllAsTouched(): void;
365 /**
366 * Marks the control as `untouched`.
367 *
368 * If the control has any children, also marks all children as `untouched`
369 * and recalculates the `touched` status of all parent controls.
370 *
371 * @see {@link markAsTouched()}
372 * @see {@link markAsDirty()}
373 * @see {@link markAsPristine()}
374 *
375 * @param opts Configuration options that determine how the control propagates changes
376 * and emits events after the marking is applied.
377 * * `onlySelf`: When true, mark only this control. When false or not supplied,
378 * marks all direct ancestors. Default is false.
379 */
380 markAsUntouched(opts?: {
381 onlySelf?: boolean;
382 }): void;
383 /**
384 * Marks the control as `dirty`. A control becomes dirty when
385 * the control's value is changed through the UI; compare `markAsTouched`.
386 *
387 * @see {@link markAsTouched()}
388 * @see {@link markAsUntouched()}
389 * @see {@link markAsPristine()}
390 *
391 * @param opts Configuration options that determine how the control propagates changes
392 * and emits events after marking is applied.
393 * * `onlySelf`: When true, mark only this control. When false or not supplied,
394 * marks all direct ancestors. Default is false.
395 */
396 markAsDirty(opts?: {
397 onlySelf?: boolean;
398 }): void;
399 /**
400 * Marks the control as `pristine`.
401 *
402 * If the control has any children, marks all children as `pristine`,
403 * and recalculates the `pristine` status of all parent
404 * controls.
405 *
406 * @see {@link markAsTouched()}
407 * @see {@link markAsUntouched()}
408 * @see {@link markAsDirty()}
409 *
410 * @param opts Configuration options that determine how the control emits events after
411 * marking is applied.
412 * * `onlySelf`: When true, mark only this control. When false or not supplied,
413 * marks all direct ancestors. Default is false.
414 */
415 markAsPristine(opts?: {
416 onlySelf?: boolean;
417 }): void;
418 /**
419 * Marks the control as `pending`.
420 *
421 * A control is pending while the control performs async validation.
422 *
423 * @see {@link AbstractControl.status}
424 *
425 * @param opts Configuration options that determine how the control propagates changes and
426 * emits events after marking is applied.
427 * * `onlySelf`: When true, mark only this control. When false or not supplied,
428 * marks all direct ancestors. Default is false.
429 * * `emitEvent`: When true or not supplied (the default), the `statusChanges`
430 * observable emits an event with the latest status the control is marked pending.
431 * When false, no events are emitted.
432 *
433 */
434 markAsPending(opts?: {
435 onlySelf?: boolean;
436 emitEvent?: boolean;
437 }): void;
438 /**
439 * Disables the control. This means the control is exempt from validation checks and
440 * excluded from the aggregate value of any parent. Its status is `DISABLED`.
441 *
442 * If the control has children, all children are also disabled.
443 *
444 * @see {@link AbstractControl.status}
445 *
446 * @param opts Configuration options that determine how the control propagates
447 * changes and emits events after the control is disabled.
448 * * `onlySelf`: When true, mark only this control. When false or not supplied,
449 * marks all direct ancestors. Default is false.
450 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
451 * `valueChanges`
452 * observables emit events with the latest status and value when the control is disabled.
453 * When false, no events are emitted.
454 */
455 disable(opts?: {
456 onlySelf?: boolean;
457 emitEvent?: boolean;
458 }): void;
459 /**
460 * Enables the control. This means the control is included in validation checks and
461 * the aggregate value of its parent. Its status recalculates based on its value and
462 * its validators.
463 *
464 * By default, if the control has children, all children are enabled.
465 *
466 * @see {@link AbstractControl.status}
467 *
468 * @param opts Configure options that control how the control propagates changes and
469 * emits events when marked as untouched
470 * * `onlySelf`: When true, mark only this control. When false or not supplied,
471 * marks all direct ancestors. Default is false.
472 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
473 * `valueChanges`
474 * observables emit events with the latest status and value when the control is enabled.
475 * When false, no events are emitted.
476 */
477 enable(opts?: {
478 onlySelf?: boolean;
479 emitEvent?: boolean;
480 }): void;
481 private _updateAncestors;
482 /**
483 * Sets the parent of the control
484 *
485 * @param parent The new parent.
486 */
487 setParent(parent: FormGroup | FormArray | null): void;
488 /**
489 * Sets the value of the control. Abstract method (implemented in sub-classes).
490 */
491 abstract setValue(value: TRawValue, options?: Object): void;
492 /**
493 * Patches the value of the control. Abstract method (implemented in sub-classes).
494 */
495 abstract patchValue(value: TValue, options?: Object): void;
496 /**
497 * Resets the control. Abstract method (implemented in sub-classes).
498 */
499 abstract reset(value?: TValue, options?: Object): void;
500 /**
501 * The raw value of this control. For most control implementations, the raw value will include
502 * disabled children.
503 */
504 getRawValue(): any;
505 /**
506 * Recalculates the value and validation status of the control.
507 *
508 * By default, it also updates the value and validity of its ancestors.
509 *
510 * @param opts Configuration options determine how the control propagates changes and emits events
511 * after updates and validity checks are applied.
512 * * `onlySelf`: When true, only update this control. When false or not supplied,
513 * update all direct ancestors. Default is false.
514 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
515 * `valueChanges`
516 * observables emit events with the latest status and value when the control is updated.
517 * When false, no events are emitted.
518 */
519 updateValueAndValidity(opts?: {
520 onlySelf?: boolean;
521 emitEvent?: boolean;
522 }): void;
523 private _setInitialStatus;
524 private _runValidator;
525 private _runAsyncValidator;
526 private _cancelExistingSubscription;
527 /**
528 * Sets errors on a form control when running validations manually, rather than automatically.
529 *
530 * Calling `setErrors` also updates the validity of the parent control.
531 *
532 * @param opts Configuration options that determine how the control propagates
533 * changes and emits events after the control errors are set.
534 * * `emitEvent`: When true or not supplied (the default), the `statusChanges`
535 * observable emits an event after the errors are set.
536 *
537 * @usageNotes
538 *
539 * ### Manually set the errors for a control
540 *
541 * ```
542 * const login = new FormControl('someLogin');
543 * login.setErrors({
544 * notUnique: true
545 * });
546 *
547 * expect(login.valid).toEqual(false);
548 * expect(login.errors).toEqual({ notUnique: true });
549 *
550 * login.setValue('someOtherLogin');
551 *
552 * expect(login.valid).toEqual(true);
553 * ```
554 */
555 setErrors(errors: ValidationErrors | null, opts?: {
556 emitEvent?: boolean;
557 }): void;
558 /**
559 * Retrieves a child control given the control's name or path.
560 *
561 * This signature for get supports strings and `const` arrays (`.get(['foo', 'bar'] as const)`).
562 */
563 get<P extends string | (readonly (string | number)[])>(path: P): AbstractControl<ɵGetProperty<TRawValue, P>> | null;
564 /**
565 * Retrieves a child control given the control's name or path.
566 *
567 * This signature for `get` supports non-const (mutable) arrays. Inferred type
568 * information will not be as robust, so prefer to pass a `readonly` array if possible.
569 */
570 get<P extends string | Array<string | number>>(path: P): AbstractControl<ɵGetProperty<TRawValue, P>> | null;
571 /**
572 * @description
573 * Reports error data for the control with the given path.
574 *
575 * @param errorCode The code of the error to check
576 * @param path A list of control names that designates how to move from the current control
577 * to the control that should be queried for errors.
578 *
579 * @usageNotes
580 * For example, for the following `FormGroup`:
581 *
582 * ```
583 * form = new FormGroup({
584 * address: new FormGroup({ street: new FormControl() })
585 * });
586 * ```
587 *
588 * The path to the 'street' control from the root form would be 'address' -> 'street'.
589 *
590 * It can be provided to this method in one of two formats:
591 *
592 * 1. An array of string control names, e.g. `['address', 'street']`
593 * 1. A period-delimited list of control names in one string, e.g. `'address.street'`
594 *
595 * @returns error data for that particular error. If the control or error is not present,
596 * null is returned.
597 */
598 getError(errorCode: string, path?: Array<string | number> | string): any;
599 /**
600 * @description
601 * Reports whether the control with the given path has the error specified.
602 *
603 * @param errorCode The code of the error to check
604 * @param path A list of control names that designates how to move from the current control
605 * to the control that should be queried for errors.
606 *
607 * @usageNotes
608 * For example, for the following `FormGroup`:
609 *
610 * ```
611 * form = new FormGroup({
612 * address: new FormGroup({ street: new FormControl() })
613 * });
614 * ```
615 *
616 * The path to the 'street' control from the root form would be 'address' -> 'street'.
617 *
618 * It can be provided to this method in one of two formats:
619 *
620 * 1. An array of string control names, e.g. `['address', 'street']`
621 * 1. A period-delimited list of control names in one string, e.g. `'address.street'`
622 *
623 * If no path is given, this method checks for the error on the current control.
624 *
625 * @returns whether the given error is present in the control at the given path.
626 *
627 * If the control is not present, false is returned.
628 */
629 hasError(errorCode: string, path?: Array<string | number> | string): boolean;
630 /**
631 * Retrieves the top-level ancestor of this control.
632 */
633 get root(): AbstractControl;
634 private _calculateStatus;
635 /**
636 * Internal implementation of the `setValidators` method. Needs to be separated out into a
637 * different method, because it is called in the constructor and it can break cases where
638 * a control is extended.
639 */
640 private _assignValidators;
641 /**
642 * Internal implementation of the `setAsyncValidators` method. Needs to be separated out into a
643 * different method, because it is called in the constructor and it can break cases where
644 * a control is extended.
645 */
646 private _assignAsyncValidators;
647}
648
649/**
650 * @description
651 * Base class for control directives.
652 *
653 * This class is only used internally in the `ReactiveFormsModule` and the `FormsModule`.
654 *
655 * @publicApi
656 */
657export declare abstract class AbstractControlDirective {
658 /**
659 * @description
660 * A reference to the underlying control.
661 *
662 * @returns the control that backs this directive. Most properties fall through to that instance.
663 */
664 abstract get control(): AbstractControl | null;
665 /**
666 * @description
667 * Reports the value of the control if it is present, otherwise null.
668 */
669 get value(): any;
670 /**
671 * @description
672 * Reports whether the control is valid. A control is considered valid if no
673 * validation errors exist with the current value.
674 * If the control is not present, null is returned.
675 */
676 get valid(): boolean | null;
677 /**
678 * @description
679 * Reports whether the control is invalid, meaning that an error exists in the input value.
680 * If the control is not present, null is returned.
681 */
682 get invalid(): boolean | null;
683 /**
684 * @description
685 * Reports whether a control is pending, meaning that async validation is occurring and
686 * errors are not yet available for the input value. If the control is not present, null is
687 * returned.
688 */
689 get pending(): boolean | null;
690 /**
691 * @description
692 * Reports whether the control is disabled, meaning that the control is disabled
693 * in the UI and is exempt from validation checks and excluded from aggregate
694 * values of ancestor controls. If the control is not present, null is returned.
695 */
696 get disabled(): boolean | null;
697 /**
698 * @description
699 * Reports whether the control is enabled, meaning that the control is included in ancestor
700 * calculations of validity or value. If the control is not present, null is returned.
701 */
702 get enabled(): boolean | null;
703 /**
704 * @description
705 * Reports the control's validation errors. If the control is not present, null is returned.
706 */
707 get errors(): ValidationErrors | null;
708 /**
709 * @description
710 * Reports whether the control is pristine, meaning that the user has not yet changed
711 * the value in the UI. If the control is not present, null is returned.
712 */
713 get pristine(): boolean | null;
714 /**
715 * @description
716 * Reports whether the control is dirty, meaning that the user has changed
717 * the value in the UI. If the control is not present, null is returned.
718 */
719 get dirty(): boolean | null;
720 /**
721 * @description
722 * Reports whether the control is touched, meaning that the user has triggered
723 * a `blur` event on it. If the control is not present, null is returned.
724 */
725 get touched(): boolean | null;
726 /**
727 * @description
728 * Reports the validation status of the control. Possible values include:
729 * 'VALID', 'INVALID', 'DISABLED', and 'PENDING'.
730 * If the control is not present, null is returned.
731 */
732 get status(): string | null;
733 /**
734 * @description
735 * Reports whether the control is untouched, meaning that the user has not yet triggered
736 * a `blur` event on it. If the control is not present, null is returned.
737 */
738 get untouched(): boolean | null;
739 /**
740 * @description
741 * Returns a multicasting observable that emits a validation status whenever it is
742 * calculated for the control. If the control is not present, null is returned.
743 */
744 get statusChanges(): Observable<any> | null;
745 /**
746 * @description
747 * Returns a multicasting observable of value changes for the control that emits every time the
748 * value of the control changes in the UI or programmatically.
749 * If the control is not present, null is returned.
750 */
751 get valueChanges(): Observable<any> | null;
752 /**
753 * @description
754 * Returns an array that represents the path from the top-level form to this control.
755 * Each index is the string name of the control on that level.
756 */
757 get path(): string[] | null;
758 /**
759 * Contains the result of merging synchronous validators into a single validator function
760 * (combined using `Validators.compose`).
761 */
762 private _composedValidatorFn;
763 /**
764 * Contains the result of merging asynchronous validators into a single validator function
765 * (combined using `Validators.composeAsync`).
766 */
767 private _composedAsyncValidatorFn;
768 /**
769 * @description
770 * Synchronous validator function composed of all the synchronous validators registered with this
771 * directive.
772 */
773 get validator(): ValidatorFn | null;
774 /**
775 * @description
776 * Asynchronous validator function composed of all the asynchronous validators registered with
777 * this directive.
778 */
779 get asyncValidator(): AsyncValidatorFn | null;
780 private _onDestroyCallbacks;
781 /**
782 * @description
783 * Resets the control with the provided value if the control is present.
784 */
785 reset(value?: any): void;
786 /**
787 * @description
788 * Reports whether the control with the given path has the error specified.
789 *
790 * @param errorCode The code of the error to check
791 * @param path A list of control names that designates how to move from the current control
792 * to the control that should be queried for errors.
793 *
794 * @usageNotes
795 * For example, for the following `FormGroup`:
796 *
797 * ```
798 * form = new FormGroup({
799 * address: new FormGroup({ street: new FormControl() })
800 * });
801 * ```
802 *
803 * The path to the 'street' control from the root form would be 'address' -> 'street'.
804 *
805 * It can be provided to this method in one of two formats:
806 *
807 * 1. An array of string control names, e.g. `['address', 'street']`
808 * 1. A period-delimited list of control names in one string, e.g. `'address.street'`
809 *
810 * If no path is given, this method checks for the error on the current control.
811 *
812 * @returns whether the given error is present in the control at the given path.
813 *
814 * If the control is not present, false is returned.
815 */
816 hasError(errorCode: string, path?: Array<string | number> | string): boolean;
817 /**
818 * @description
819 * Reports error data for the control with the given path.
820 *
821 * @param errorCode The code of the error to check
822 * @param path A list of control names that designates how to move from the current control
823 * to the control that should be queried for errors.
824 *
825 * @usageNotes
826 * For example, for the following `FormGroup`:
827 *
828 * ```
829 * form = new FormGroup({
830 * address: new FormGroup({ street: new FormControl() })
831 * });
832 * ```
833 *
834 * The path to the 'street' control from the root form would be 'address' -> 'street'.
835 *
836 * It can be provided to this method in one of two formats:
837 *
838 * 1. An array of string control names, e.g. `['address', 'street']`
839 * 1. A period-delimited list of control names in one string, e.g. `'address.street'`
840 *
841 * @returns error data for that particular error. If the control or error is not present,
842 * null is returned.
843 */
844 getError(errorCode: string, path?: Array<string | number> | string): any;
845}
846
847/**
848 * Interface for options provided to an `AbstractControl`.
849 *
850 * @publicApi
851 */
852export declare interface AbstractControlOptions {
853 /**
854 * @description
855 * The list of validators applied to a control.
856 */
857 validators?: ValidatorFn | ValidatorFn[] | null;
858 /**
859 * @description
860 * The list of async validators applied to control.
861 */
862 asyncValidators?: AsyncValidatorFn | AsyncValidatorFn[] | null;
863 /**
864 * @description
865 * The event name for control to update upon.
866 */
867 updateOn?: 'change' | 'blur' | 'submit';
868}
869
870declare class AbstractControlStatus {
871 private _cd;
872 constructor(cd: AbstractControlDirective | null);
873 protected get isTouched(): boolean;
874 protected get isUntouched(): boolean;
875 protected get isPristine(): boolean;
876 protected get isDirty(): boolean;
877 protected get isValid(): boolean;
878 protected get isInvalid(): boolean;
879 protected get isPending(): boolean;
880 protected get isSubmitted(): boolean;
881}
882
883/**
884 * @description
885 * A base class for code shared between the `NgModelGroup` and `FormGroupName` directives.
886 *
887 * @publicApi
888 */
889export declare class AbstractFormGroupDirective extends ControlContainer implements OnInit, OnDestroy {
890 /** @nodoc */
891 ngOnInit(): void;
892 /** @nodoc */
893 ngOnDestroy(): void;
894 /**
895 * @description
896 * The `FormGroup` bound to this directive.
897 */
898 get control(): FormGroup;
899 /**
900 * @description
901 * The path to this group from the top-level directive.
902 */
903 get path(): string[];
904 /**
905 * @description
906 * The top-level directive for this group if present, otherwise null.
907 */
908 get formDirective(): Form | null;
909 static ɵfac: i0.ɵɵFactoryDeclaration<AbstractFormGroupDirective, never>;
910 static ɵdir: i0.ɵɵDirectiveDeclaration<AbstractFormGroupDirective, never, never, {}, {}, never, never, false, never>;
911}
912
913/**
914 * A base class for Validator-based Directives. The class contains common logic shared across such
915 * Directives.
916 *
917 * For internal use only, this class is not intended for use outside of the Forms package.
918 */
919declare abstract class AbstractValidatorDirective implements Validator, OnChanges {
920 private _validator;
921 private _onChange;
922 /** @nodoc */
923 ngOnChanges(changes: SimpleChanges): void;
924 /** @nodoc */
925 validate(control: AbstractControl): ValidationErrors | null;
926 /** @nodoc */
927 registerOnValidatorChange(fn: () => void): void;
928 /**
929 * @description
930 * Determines whether this validator should be active or not based on an input.
931 * Base class implementation checks whether an input is defined (if the value is different from
932 * `null` and `undefined`). Validator classes that extend this base class can override this
933 * function with the logic specific to a particular validator directive.
934 */
935 enabled(input: unknown): boolean;
936 static ɵfac: i0.ɵɵFactoryDeclaration<AbstractValidatorDirective, never>;
937 static ɵdir: i0.ɵɵDirectiveDeclaration<AbstractValidatorDirective, never, never, {}, {}, never, never, false, never>;
938}
939
940/**
941 * @description
942 * An interface implemented by classes that perform asynchronous validation.
943 *
944 * @usageNotes
945 *
946 * ### Provide a custom async validator directive
947 *
948 * The following example implements the `AsyncValidator` interface to create an
949 * async validator directive with a custom error key.
950 *
951 * ```typescript
952 * import { of } from 'rxjs';
953 *
954 * @Directive({
955 * selector: '[customAsyncValidator]',
956 * providers: [{provide: NG_ASYNC_VALIDATORS, useExisting: CustomAsyncValidatorDirective, multi:
957 * true}]
958 * })
959 * class CustomAsyncValidatorDirective implements AsyncValidator {
960 * validate(control: AbstractControl): Observable<ValidationErrors|null> {
961 * return of({'custom': true});
962 * }
963 * }
964 * ```
965 *
966 * @publicApi
967 */
968export declare interface AsyncValidator extends Validator {
969 /**
970 * @description
971 * Method that performs async validation against the provided control.
972 *
973 * @param control The control to validate against.
974 *
975 * @returns A promise or observable that resolves a map of validation errors
976 * if validation fails, otherwise null.
977 */
978 validate(control: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
979}
980
981/**
982 * @description
983 * A function that receives a control and returns a Promise or observable
984 * that emits validation errors if present, otherwise null.
985 *
986 * @publicApi
987 */
988export declare interface AsyncValidatorFn {
989 (control: AbstractControl): Promise<ValidationErrors | null> | Observable<ValidationErrors | null>;
990}
991
992/**
993 * Base class for all ControlValueAccessor classes defined in Forms package.
994 * Contains common logic and utility functions.
995 *
996 * Note: this is an *internal-only* class and should not be extended or used directly in
997 * applications code.
998 */
999declare class BaseControlValueAccessor {
1000 private _renderer;
1001 private _elementRef;
1002 /**
1003 * The registered callback function called when a change or input event occurs on the input
1004 * element.
1005 * @nodoc
1006 */
1007 onChange: (_: any) => void;
1008 /**
1009 * The registered callback function called when a blur event occurs on the input element.
1010 * @nodoc
1011 */
1012 onTouched: () => void;
1013 constructor(_renderer: Renderer2, _elementRef: ElementRef);
1014 /**
1015 * Helper method that sets a property on a target element using the current Renderer
1016 * implementation.
1017 * @nodoc
1018 */
1019 protected setProperty(key: string, value: any): void;
1020 /**
1021 * Registers a function called when the control is touched.
1022 * @nodoc
1023 */
1024 registerOnTouched(fn: () => void): void;
1025 /**
1026 * Registers a function called when the control value changes.
1027 * @nodoc
1028 */
1029 registerOnChange(fn: (_: any) => {}): void;
1030 /**
1031 * Sets the "disabled" property on the range input element.
1032 * @nodoc
1033 */
1034 setDisabledState(isDisabled: boolean): void;
1035 static ɵfac: i0.ɵɵFactoryDeclaration<BaseControlValueAccessor, never>;
1036 static ɵdir: i0.ɵɵDirectiveDeclaration<BaseControlValueAccessor, never, never, {}, {}, never, never, false, never>;
1037}
1038
1039/**
1040 * Base class for all built-in ControlValueAccessor classes (except DefaultValueAccessor, which is
1041 * used in case no other CVAs can be found). We use this class to distinguish between default CVA,
1042 * built-in CVAs and custom CVAs, so that Forms logic can recognize built-in CVAs and treat custom
1043 * ones with higher priority (when both built-in and custom CVAs are present).
1044 *
1045 * Note: this is an *internal-only* class and should not be extended or used directly in
1046 * applications code.
1047 */
1048declare class BuiltInControlValueAccessor extends BaseControlValueAccessor {
1049 static ɵfac: i0.ɵɵFactoryDeclaration<BuiltInControlValueAccessor, never>;
1050 static ɵdir: i0.ɵɵDirectiveDeclaration<BuiltInControlValueAccessor, never, never, {}, {}, never, never, false, never>;
1051}
1052
1053/**
1054 * Token to provide to allow SetDisabledState to always be called when a CVA is added, regardless of
1055 * whether the control is disabled or enabled.
1056 *
1057 * @see {@link FormsModule#withconfig}
1058 */
1059declare const CALL_SET_DISABLED_STATE: InjectionToken<SetDisabledStateOption>;
1060
1061/**
1062 * @description
1063 * Provider which adds `CheckboxRequiredValidator` to the `NG_VALIDATORS` multi-provider list.
1064 */
1065declare const CHECKBOX_REQUIRED_VALIDATOR: Provider;
1066
1067/**
1068 * @description
1069 * A `ControlValueAccessor` for writing a value and listening to changes on a checkbox input
1070 * element.
1071 *
1072 * @usageNotes
1073 *
1074 * ### Using a checkbox with a reactive form.
1075 *
1076 * The following example shows how to use a checkbox with a reactive form.
1077 *
1078 * ```ts
1079 * const rememberLoginControl = new FormControl();
1080 * ```
1081 *
1082 * ```
1083 * <input type="checkbox" [formControl]="rememberLoginControl">
1084 * ```
1085 *
1086 * @ngModule ReactiveFormsModule
1087 * @ngModule FormsModule
1088 * @publicApi
1089 */
1090export declare class CheckboxControlValueAccessor extends BuiltInControlValueAccessor implements ControlValueAccessor {
1091 /**
1092 * Sets the "checked" property on the input element.
1093 * @nodoc
1094 */
1095 writeValue(value: any): void;
1096 static ɵfac: i0.ɵɵFactoryDeclaration<CheckboxControlValueAccessor, never>;
1097 static ɵdir: i0.ɵɵDirectiveDeclaration<CheckboxControlValueAccessor, "input[type=checkbox][formControlName],input[type=checkbox][formControl],input[type=checkbox][ngModel]", never, {}, {}, never, never, false, never>;
1098}
1099
1100/**
1101 * A Directive that adds the `required` validator to checkbox controls marked with the
1102 * `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
1103 *
1104 * @see [Form Validation](guide/form-validation)
1105 *
1106 * @usageNotes
1107 *
1108 * ### Adding a required checkbox validator using template-driven forms
1109 *
1110 * The following example shows how to add a checkbox required validator to an input attached to an
1111 * ngModel binding.
1112 *
1113 * ```
1114 * <input type="checkbox" name="active" ngModel required>
1115 * ```
1116 *
1117 * @publicApi
1118 * @ngModule FormsModule
1119 * @ngModule ReactiveFormsModule
1120 */
1121export declare class CheckboxRequiredValidator extends RequiredValidator {
1122 static ɵfac: i0.ɵɵFactoryDeclaration<CheckboxRequiredValidator, never>;
1123 static ɵdir: i0.ɵɵDirectiveDeclaration<CheckboxRequiredValidator, "input[type=checkbox][required][formControlName],input[type=checkbox][required][formControl],input[type=checkbox][required][ngModel]", never, {}, {}, never, never, false, never>;
1124}
1125
1126/**
1127 * @description
1128 * Provide this token to control if form directives buffer IME input until
1129 * the "compositionend" event occurs.
1130 * @publicApi
1131 */
1132export declare const COMPOSITION_BUFFER_MODE: InjectionToken<boolean>;
1133
1134/**
1135 * ControlConfig<T> is a tuple containing a value of type T, plus optional validators and async
1136 * validators.
1137 *
1138 * @publicApi
1139 */
1140export declare type ControlConfig<T> = [T | FormControlState<T>, (ValidatorFn | (ValidatorFn[]))?, (AsyncValidatorFn | AsyncValidatorFn[])?];
1141
1142/**
1143 * @description
1144 * A base class for directives that contain multiple registered instances of `NgControl`.
1145 * Only used by the forms module.
1146 *
1147 * @publicApi
1148 */
1149export declare abstract class ControlContainer extends AbstractControlDirective {
1150 /**
1151 * @description
1152 * The name for the control
1153 */
1154 name: string | number | null;
1155 /**
1156 * @description
1157 * The top-level form directive for the control.
1158 */
1159 get formDirective(): Form | null;
1160 /**
1161 * @description
1162 * The path to this group.
1163 */
1164 get path(): string[] | null;
1165}
1166
1167/**
1168 * @description
1169 * Defines an interface that acts as a bridge between the Angular forms API and a
1170 * native element in the DOM.
1171 *
1172 * Implement this interface to create a custom form control directive
1173 * that integrates with Angular forms.
1174 *
1175 * @see {@link DefaultValueAccessor}
1176 *
1177 * @publicApi
1178 */
1179export declare interface ControlValueAccessor {
1180 /**
1181 * @description
1182 * Writes a new value to the element.
1183 *
1184 * This method is called by the forms API to write to the view when programmatic
1185 * changes from model to view are requested.
1186 *
1187 * @usageNotes
1188 * ### Write a value to the element
1189 *
1190 * The following example writes a value to the native DOM element.
1191 *
1192 * ```ts
1193 * writeValue(value: any): void {
1194 * this._renderer.setProperty(this._elementRef.nativeElement, 'value', value);
1195 * }
1196 * ```
1197 *
1198 * @param obj The new value for the element
1199 */
1200 writeValue(obj: any): void;
1201 /**
1202 * @description
1203 * Registers a callback function that is called when the control's value
1204 * changes in the UI.
1205 *
1206 * This method is called by the forms API on initialization to update the form
1207 * model when values propagate from the view to the model.
1208 *
1209 * When implementing the `registerOnChange` method in your own value accessor,
1210 * save the given function so your class calls it at the appropriate time.
1211 *
1212 * @usageNotes
1213 * ### Store the change function
1214 *
1215 * The following example stores the provided function as an internal method.
1216 *
1217 * ```ts
1218 * registerOnChange(fn: (_: any) => void): void {
1219 * this._onChange = fn;
1220 * }
1221 * ```
1222 *
1223 * When the value changes in the UI, call the registered
1224 * function to allow the forms API to update itself:
1225 *
1226 * ```ts
1227 * host: {
1228 * '(change)': '_onChange($event.target.value)'
1229 * }
1230 * ```
1231 *
1232 * @param fn The callback function to register
1233 */
1234 registerOnChange(fn: any): void;
1235 /**
1236 * @description
1237 * Registers a callback function that is called by the forms API on initialization
1238 * to update the form model on blur.
1239 *
1240 * When implementing `registerOnTouched` in your own value accessor, save the given
1241 * function so your class calls it when the control should be considered
1242 * blurred or "touched".
1243 *
1244 * @usageNotes
1245 * ### Store the callback function
1246 *
1247 * The following example stores the provided function as an internal method.
1248 *
1249 * ```ts
1250 * registerOnTouched(fn: any): void {
1251 * this._onTouched = fn;
1252 * }
1253 * ```
1254 *
1255 * On blur (or equivalent), your class should call the registered function to allow
1256 * the forms API to update itself:
1257 *
1258 * ```ts
1259 * host: {
1260 * '(blur)': '_onTouched()'
1261 * }
1262 * ```
1263 *
1264 * @param fn The callback function to register
1265 */
1266 registerOnTouched(fn: any): void;
1267 /**
1268 * @description
1269 * Function that is called by the forms API when the control status changes to
1270 * or from 'DISABLED'. Depending on the status, it enables or disables the
1271 * appropriate DOM element.
1272 *
1273 * @usageNotes
1274 * The following is an example of writing the disabled property to a native DOM element:
1275 *
1276 * ```ts
1277 * setDisabledState(isDisabled: boolean): void {
1278 * this._renderer.setProperty(this._elementRef.nativeElement, 'disabled', isDisabled);
1279 * }
1280 * ```
1281 *
1282 * @param isDisabled The disabled status to set on the element
1283 */
1284 setDisabledState?(isDisabled: boolean): void;
1285}
1286
1287declare const DEFAULT_VALUE_ACCESSOR: Provider;
1288
1289/**
1290 * The default `ControlValueAccessor` for writing a value and listening to changes on input
1291 * elements. The accessor is used by the `FormControlDirective`, `FormControlName`, and
1292 * `NgModel` directives.
1293 *
1294 * {@searchKeywords ngDefaultControl}
1295 *
1296 * @usageNotes
1297 *
1298 * ### Using the default value accessor
1299 *
1300 * The following example shows how to use an input element that activates the default value accessor
1301 * (in this case, a text field).
1302 *
1303 * ```ts
1304 * const firstNameControl = new FormControl();
1305 * ```
1306 *
1307 * ```
1308 * <input type="text" [formControl]="firstNameControl">
1309 * ```
1310 *
1311 * This value accessor is used by default for `<input type="text">` and `<textarea>` elements, but
1312 * you could also use it for custom components that have similar behavior and do not require special
1313 * processing. In order to attach the default value accessor to a custom element, add the
1314 * `ngDefaultControl` attribute as shown below.
1315 *
1316 * ```
1317 * <custom-input-component ngDefaultControl [(ngModel)]="value"></custom-input-component>
1318 * ```
1319 *
1320 * @ngModule ReactiveFormsModule
1321 * @ngModule FormsModule
1322 * @publicApi
1323 */
1324export declare class DefaultValueAccessor extends BaseControlValueAccessor implements ControlValueAccessor {
1325 private _compositionMode;
1326 /** Whether the user is creating a composition string (IME events). */
1327 private _composing;
1328 constructor(renderer: Renderer2, elementRef: ElementRef, _compositionMode: boolean);
1329 /**
1330 * Sets the "value" property on the input element.
1331 * @nodoc
1332 */
1333 writeValue(value: any): void;
1334 static ɵfac: i0.ɵɵFactoryDeclaration<DefaultValueAccessor, [null, null, { optional: true; }]>;
1335 static ɵdir: i0.ɵɵDirectiveDeclaration<DefaultValueAccessor, "input:not([type=checkbox])[formControlName],textarea[formControlName],input:not([type=checkbox])[formControl],textarea[formControl],input:not([type=checkbox])[ngModel],textarea[ngModel],[ngDefaultControl]", never, {}, {}, never, never, false, never>;
1336}
1337
1338/**
1339 * @description
1340 * Provider which adds `EmailValidator` to the `NG_VALIDATORS` multi-provider list.
1341 */
1342declare const EMAIL_VALIDATOR: any;
1343
1344/**
1345 * A directive that adds the `email` validator to controls marked with the
1346 * `email` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list.
1347 *
1348 * The email validation is based on the WHATWG HTML specification with some enhancements to
1349 * incorporate more RFC rules. More information can be found on the [Validators.email
1350 * page](api/forms/Validators#email).
1351 *
1352 * @see [Form Validation](guide/form-validation)
1353 *
1354 * @usageNotes
1355 *
1356 * ### Adding an email validator
1357 *
1358 * The following example shows how to add an email validator to an input attached to an ngModel
1359 * binding.
1360 *
1361 * ```
1362 * <input type="email" name="email" ngModel email>
1363 * <input type="email" name="email" ngModel email="true">
1364 * <input type="email" name="email" ngModel [email]="true">
1365 * ```
1366 *
1367 * @publicApi
1368 * @ngModule FormsModule
1369 * @ngModule ReactiveFormsModule
1370 */
1371export declare class EmailValidator extends AbstractValidatorDirective {
1372 /**
1373 * @description
1374 * Tracks changes to the email attribute bound to this directive.
1375 */
1376 email: boolean | string;
1377 /** @nodoc */
1378 enabled(input: boolean): boolean;
1379 static ɵfac: i0.ɵɵFactoryDeclaration<EmailValidator, never>;
1380 static ɵdir: i0.ɵɵDirectiveDeclaration<EmailValidator, "[email][formControlName],[email][formControl],[email][ngModel]", never, { "email": { "alias": "email"; "required": false; }; }, {}, never, never, false, never>;
1381}
1382
1383/**
1384 * @description
1385 * An interface implemented by `FormGroupDirective` and `NgForm` directives.
1386 *
1387 * Only used by the `ReactiveFormsModule` and `FormsModule`.
1388 *
1389 * @publicApi
1390 */
1391export declare interface Form {
1392 /**
1393 * @description
1394 * Add a control to this form.
1395 *
1396 * @param dir The control directive to add to the form.
1397 */
1398 addControl(dir: NgControl): void;
1399 /**
1400 * @description
1401 * Remove a control from this form.
1402 *
1403 * @param dir: The control directive to remove from the form.
1404 */
1405 removeControl(dir: NgControl): void;
1406 /**
1407 * @description
1408 * The control directive from which to get the `FormControl`.
1409 *
1410 * @param dir: The control directive.
1411 */
1412 getControl(dir: NgControl): FormControl;
1413 /**
1414 * @description
1415 * Add a group of controls to this form.
1416 *
1417 * @param dir: The control group directive to add.
1418 */
1419 addFormGroup(dir: AbstractFormGroupDirective): void;
1420 /**
1421 * @description
1422 * Remove a group of controls to this form.
1423 *
1424 * @param dir: The control group directive to remove.
1425 */
1426 removeFormGroup(dir: AbstractFormGroupDirective): void;
1427 /**
1428 * @description
1429 * The `FormGroup` associated with a particular `AbstractFormGroupDirective`.
1430 *
1431 * @param dir: The form group directive from which to get the `FormGroup`.
1432 */
1433 getFormGroup(dir: AbstractFormGroupDirective): FormGroup;
1434 /**
1435 * @description
1436 * Update the model for a particular control with a new value.
1437 *
1438 * @param dir: The control directive to update.
1439 * @param value: The new value for the control.
1440 */
1441 updateModel(dir: NgControl, value: any): void;
1442}
1443
1444/**
1445 * Tracks the value and validity state of an array of `FormControl`,
1446 * `FormGroup` or `FormArray` instances.
1447 *
1448 * A `FormArray` aggregates the values of each child `FormControl` into an array.
1449 * It calculates its status by reducing the status values of its children. For example, if one of
1450 * the controls in a `FormArray` is invalid, the entire array becomes invalid.
1451 *
1452 * `FormArray` accepts one generic argument, which is the type of the controls inside.
1453 * If you need a heterogenous array, use {@link UntypedFormArray}.
1454 *
1455 * `FormArray` is one of the four fundamental building blocks used to define forms in Angular,
1456 * along with `FormControl`, `FormGroup`, and `FormRecord`.
1457 *
1458 * @usageNotes
1459 *
1460 * ### Create an array of form controls
1461 *
1462 * ```
1463 * const arr = new FormArray([
1464 * new FormControl('Nancy', Validators.minLength(2)),
1465 * new FormControl('Drew'),
1466 * ]);
1467 *
1468 * console.log(arr.value); // ['Nancy', 'Drew']
1469 * console.log(arr.status); // 'VALID'
1470 * ```
1471 *
1472 * ### Create a form array with array-level validators
1473 *
1474 * You include array-level validators and async validators. These come in handy
1475 * when you want to perform validation that considers the value of more than one child
1476 * control.
1477 *
1478 * The two types of validators are passed in separately as the second and third arg
1479 * respectively, or together as part of an options object.
1480 *
1481 * ```
1482 * const arr = new FormArray([
1483 * new FormControl('Nancy'),
1484 * new FormControl('Drew')
1485 * ], {validators: myValidator, asyncValidators: myAsyncValidator});
1486 * ```
1487 *
1488 * ### Set the updateOn property for all controls in a form array
1489 *
1490 * The options object is used to set a default value for each child
1491 * control's `updateOn` property. If you set `updateOn` to `'blur'` at the
1492 * array level, all child controls default to 'blur', unless the child
1493 * has explicitly specified a different `updateOn` value.
1494 *
1495 * ```ts
1496 * const arr = new FormArray([
1497 * new FormControl()
1498 * ], {updateOn: 'blur'});
1499 * ```
1500 *
1501 * ### Adding or removing controls from a form array
1502 *
1503 * To change the controls in the array, use the `push`, `insert`, `removeAt` or `clear` methods
1504 * in `FormArray` itself. These methods ensure the controls are properly tracked in the
1505 * form's hierarchy. Do not modify the array of `AbstractControl`s used to instantiate
1506 * the `FormArray` directly, as that result in strange and unexpected behavior such
1507 * as broken change detection.
1508 *
1509 * @publicApi
1510 */
1511export declare class FormArray<TControl extends AbstractControl<any> = any> extends AbstractControl<ɵTypedOrUntyped<TControl, ɵFormArrayValue<TControl>, any>, ɵTypedOrUntyped<TControl, ɵFormArrayRawValue<TControl>, any>> {
1512 /**
1513 * Creates a new `FormArray` instance.
1514 *
1515 * @param controls An array of child controls. Each child control is given an index
1516 * where it is registered.
1517 *
1518 * @param validatorOrOpts A synchronous validator function, or an array of
1519 * such functions, or an `AbstractControlOptions` object that contains validation functions
1520 * and a validation trigger.
1521 *
1522 * @param asyncValidator A single async validator or array of async validator functions
1523 *
1524 */
1525 constructor(controls: Array<TControl>, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null);
1526 controls: ɵTypedOrUntyped<TControl, Array<TControl>, Array<AbstractControl<any>>>;
1527 /**
1528 * Get the `AbstractControl` at the given `index` in the array.
1529 *
1530 * @param index Index in the array to retrieve the control. If `index` is negative, it will wrap
1531 * around from the back, and if index is greatly negative (less than `-length`), the result is
1532 * undefined. This behavior is the same as `Array.at(index)`.
1533 */
1534 at(index: number): ɵTypedOrUntyped<TControl, TControl, AbstractControl<any>>;
1535 /**
1536 * Insert a new `AbstractControl` at the end of the array.
1537 *
1538 * @param control Form control to be inserted
1539 * @param options Specifies whether this FormArray instance should emit events after a new
1540 * control is added.
1541 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
1542 * `valueChanges` observables emit events with the latest status and value when the control is
1543 * inserted. When false, no events are emitted.
1544 */
1545 push(control: TControl, options?: {
1546 emitEvent?: boolean;
1547 }): void;
1548 /**
1549 * Insert a new `AbstractControl` at the given `index` in the array.
1550 *
1551 * @param index Index in the array to insert the control. If `index` is negative, wraps around
1552 * from the back. If `index` is greatly negative (less than `-length`), prepends to the array.
1553 * This behavior is the same as `Array.splice(index, 0, control)`.
1554 * @param control Form control to be inserted
1555 * @param options Specifies whether this FormArray instance should emit events after a new
1556 * control is inserted.
1557 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
1558 * `valueChanges` observables emit events with the latest status and value when the control is
1559 * inserted. When false, no events are emitted.
1560 */
1561 insert(index: number, control: TControl, options?: {
1562 emitEvent?: boolean;
1563 }): void;
1564 /**
1565 * Remove the control at the given `index` in the array.
1566 *
1567 * @param index Index in the array to remove the control. If `index` is negative, wraps around
1568 * from the back. If `index` is greatly negative (less than `-length`), removes the first
1569 * element. This behavior is the same as `Array.splice(index, 1)`.
1570 * @param options Specifies whether this FormArray instance should emit events after a
1571 * control is removed.
1572 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
1573 * `valueChanges` observables emit events with the latest status and value when the control is
1574 * removed. When false, no events are emitted.
1575 */
1576 removeAt(index: number, options?: {
1577 emitEvent?: boolean;
1578 }): void;
1579 /**
1580 * Replace an existing control.
1581 *
1582 * @param index Index in the array to replace the control. If `index` is negative, wraps around
1583 * from the back. If `index` is greatly negative (less than `-length`), replaces the first
1584 * element. This behavior is the same as `Array.splice(index, 1, control)`.
1585 * @param control The `AbstractControl` control to replace the existing control
1586 * @param options Specifies whether this FormArray instance should emit events after an
1587 * existing control is replaced with a new one.
1588 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
1589 * `valueChanges` observables emit events with the latest status and value when the control is
1590 * replaced with a new one. When false, no events are emitted.
1591 */
1592 setControl(index: number, control: TControl, options?: {
1593 emitEvent?: boolean;
1594 }): void;
1595 /**
1596 * Length of the control array.
1597 */
1598 get length(): number;
1599 /**
1600 * Sets the value of the `FormArray`. It accepts an array that matches
1601 * the structure of the control.
1602 *
1603 * This method performs strict checks, and throws an error if you try
1604 * to set the value of a control that doesn't exist or if you exclude the
1605 * value of a control.
1606 *
1607 * @usageNotes
1608 * ### Set the values for the controls in the form array
1609 *
1610 * ```
1611 * const arr = new FormArray([
1612 * new FormControl(),
1613 * new FormControl()
1614 * ]);
1615 * console.log(arr.value); // [null, null]
1616 *
1617 * arr.setValue(['Nancy', 'Drew']);
1618 * console.log(arr.value); // ['Nancy', 'Drew']
1619 * ```
1620 *
1621 * @param value Array of values for the controls
1622 * @param options Configure options that determine how the control propagates changes and
1623 * emits events after the value changes
1624 *
1625 * * `onlySelf`: When true, each change only affects this control, and not its parent. Default
1626 * is false.
1627 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
1628 * `valueChanges`
1629 * observables emit events with the latest status and value when the control value is updated.
1630 * When false, no events are emitted.
1631 * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
1632 * updateValueAndValidity} method.
1633 */
1634 setValue(value: ɵFormArrayRawValue<TControl>, options?: {
1635 onlySelf?: boolean;
1636 emitEvent?: boolean;
1637 }): void;
1638 /**
1639 * Patches the value of the `FormArray`. It accepts an array that matches the
1640 * structure of the control, and does its best to match the values to the correct
1641 * controls in the group.
1642 *
1643 * It accepts both super-sets and sub-sets of the array without throwing an error.
1644 *
1645 * @usageNotes
1646 * ### Patch the values for controls in a form array
1647 *
1648 * ```
1649 * const arr = new FormArray([
1650 * new FormControl(),
1651 * new FormControl()
1652 * ]);
1653 * console.log(arr.value); // [null, null]
1654 *
1655 * arr.patchValue(['Nancy']);
1656 * console.log(arr.value); // ['Nancy', null]
1657 * ```
1658 *
1659 * @param value Array of latest values for the controls
1660 * @param options Configure options that determine how the control propagates changes and
1661 * emits events after the value changes
1662 *
1663 * * `onlySelf`: When true, each change only affects this control, and not its parent. Default
1664 * is false.
1665 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
1666 * `valueChanges` observables emit events with the latest status and value when the control
1667 * value is updated. When false, no events are emitted. The configuration options are passed to
1668 * the {@link AbstractControl#updateValueAndValidity updateValueAndValidity} method.
1669 */
1670 patchValue(value: ɵFormArrayValue<TControl>, options?: {
1671 onlySelf?: boolean;
1672 emitEvent?: boolean;
1673 }): void;
1674 /**
1675 * Resets the `FormArray` and all descendants are marked `pristine` and `untouched`, and the
1676 * value of all descendants to null or null maps.
1677 *
1678 * You reset to a specific form state by passing in an array of states
1679 * that matches the structure of the control. The state is a standalone value
1680 * or a form state object with both a value and a disabled status.
1681 *
1682 * @usageNotes
1683 * ### Reset the values in a form array
1684 *
1685 * ```ts
1686 * const arr = new FormArray([
1687 * new FormControl(),
1688 * new FormControl()
1689 * ]);
1690 * arr.reset(['name', 'last name']);
1691 *
1692 * console.log(arr.value); // ['name', 'last name']
1693 * ```
1694 *
1695 * ### Reset the values in a form array and the disabled status for the first control
1696 *
1697 * ```
1698 * arr.reset([
1699 * {value: 'name', disabled: true},
1700 * 'last'
1701 * ]);
1702 *
1703 * console.log(arr.value); // ['last']
1704 * console.log(arr.at(0).status); // 'DISABLED'
1705 * ```
1706 *
1707 * @param value Array of values for the controls
1708 * @param options Configure options that determine how the control propagates changes and
1709 * emits events after the value changes
1710 *
1711 * * `onlySelf`: When true, each change only affects this control, and not its parent. Default
1712 * is false.
1713 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
1714 * `valueChanges`
1715 * observables emit events with the latest status and value when the control is reset.
1716 * When false, no events are emitted.
1717 * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
1718 * updateValueAndValidity} method.
1719 */
1720 reset(value?: ɵTypedOrUntyped<TControl, ɵFormArrayValue<TControl>, any>, options?: {
1721 onlySelf?: boolean;
1722 emitEvent?: boolean;
1723 }): void;
1724 /**
1725 * The aggregate value of the array, including any disabled controls.
1726 *
1727 * Reports all values regardless of disabled status.
1728 */
1729 getRawValue(): ɵFormArrayRawValue<TControl>;
1730 /**
1731 * Remove all controls in the `FormArray`.
1732 *
1733 * @param options Specifies whether this FormArray instance should emit events after all
1734 * controls are removed.
1735 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
1736 * `valueChanges` observables emit events with the latest status and value when all controls
1737 * in this FormArray instance are removed. When false, no events are emitted.
1738 *
1739 * @usageNotes
1740 * ### Remove all elements from a FormArray
1741 *
1742 * ```ts
1743 * const arr = new FormArray([
1744 * new FormControl(),
1745 * new FormControl()
1746 * ]);
1747 * console.log(arr.length); // 2
1748 *
1749 * arr.clear();
1750 * console.log(arr.length); // 0
1751 * ```
1752 *
1753 * It's a simpler and more efficient alternative to removing all elements one by one:
1754 *
1755 * ```ts
1756 * const arr = new FormArray([
1757 * new FormControl(),
1758 * new FormControl()
1759 * ]);
1760 *
1761 * while (arr.length) {
1762 * arr.removeAt(0);
1763 * }
1764 * ```
1765 */
1766 clear(options?: {
1767 emitEvent?: boolean;
1768 }): void;
1769 private _registerControl;
1770}
1771
1772/**
1773 * @description
1774 *
1775 * Syncs a nested `FormArray` to a DOM element.
1776 *
1777 * This directive is designed to be used with a parent `FormGroupDirective` (selector:
1778 * `[formGroup]`).
1779 *
1780 * It accepts the string name of the nested `FormArray` you want to link, and
1781 * will look for a `FormArray` registered with that name in the parent
1782 * `FormGroup` instance you passed into `FormGroupDirective`.
1783 *
1784 * @see [Reactive Forms Guide](guide/reactive-forms)
1785 * @see {@link AbstractControl}
1786 *
1787 * @usageNotes
1788 *
1789 * ### Example
1790 *
1791 * {@example forms/ts/nestedFormArray/nested_form_array_example.ts region='Component'}
1792 *
1793 * @ngModule ReactiveFormsModule
1794 * @publicApi
1795 */
1796export declare class FormArrayName extends ControlContainer implements OnInit, OnDestroy {
1797 /**
1798 * @description
1799 * Tracks the name of the `FormArray` bound to the directive. The name corresponds
1800 * to a key in the parent `FormGroup` or `FormArray`.
1801 * Accepts a name as a string or a number.
1802 * The name in the form of a string is useful for individual forms,
1803 * while the numerical form allows for form arrays to be bound
1804 * to indices when iterating over arrays in a `FormArray`.
1805 */
1806 name: string | number | null;
1807 constructor(parent: ControlContainer, validators: (Validator | ValidatorFn)[], asyncValidators: (AsyncValidator | AsyncValidatorFn)[]);
1808 /**
1809 * A lifecycle method called when the directive's inputs are initialized. For internal use only.
1810 * @throws If the directive does not have a valid parent.
1811 * @nodoc
1812 */
1813 ngOnInit(): void;
1814 /**
1815 * A lifecycle method called before the directive's instance is destroyed. For internal use only.
1816 * @nodoc
1817 */
1818 ngOnDestroy(): void;
1819 /**
1820 * @description
1821 * The `FormArray` bound to this directive.
1822 */
1823 get control(): FormArray;
1824 /**
1825 * @description
1826 * The top-level directive for this group if present, otherwise null.
1827 */
1828 get formDirective(): FormGroupDirective | null;
1829 /**
1830 * @description
1831 * Returns an array that represents the path from the top-level form to this control.
1832 * Each index is the string name of the control on that level.
1833 */
1834 get path(): string[];
1835 private _checkParentType;
1836 static ɵfac: i0.ɵɵFactoryDeclaration<FormArrayName, [{ optional: true; host: true; skipSelf: true; }, { optional: true; self: true; }, { optional: true; self: true; }]>;
1837 static ɵdir: i0.ɵɵDirectiveDeclaration<FormArrayName, "[formArrayName]", never, { "name": { "alias": "formArrayName"; "required": false; }; }, {}, never, never, false, never>;
1838}
1839
1840declare const formArrayNameProvider: any;
1841
1842/**
1843 * @description
1844 * Creates an `AbstractControl` from a user-specified configuration.
1845 *
1846 * The `FormBuilder` provides syntactic sugar that shortens creating instances of a
1847 * `FormControl`, `FormGroup`, or `FormArray`. It reduces the amount of boilerplate needed to
1848 * build complex forms.
1849 *
1850 * @see [Reactive Forms Guide](guide/reactive-forms)
1851 *
1852 * @publicApi
1853 */
1854export declare class FormBuilder {
1855 private useNonNullable;
1856 /**
1857 * @description
1858 * Returns a FormBuilder in which automatically constructed `FormControl` elements
1859 * have `{nonNullable: true}` and are non-nullable.
1860 *
1861 * **Constructing non-nullable controls**
1862 *
1863 * When constructing a control, it will be non-nullable, and will reset to its initial value.
1864 *
1865 * ```ts
1866 * let nnfb = new FormBuilder().nonNullable;
1867 * let name = nnfb.control('Alex'); // FormControl<string>
1868 * name.reset();
1869 * console.log(name); // 'Alex'
1870 * ```
1871 *
1872 * **Constructing non-nullable groups or arrays**
1873 *
1874 * When constructing a group or array, all automatically created inner controls will be
1875 * non-nullable, and will reset to their initial values.
1876 *
1877 * ```ts
1878 * let nnfb = new FormBuilder().nonNullable;
1879 * let name = nnfb.group({who: 'Alex'}); // FormGroup<{who: FormControl<string>}>
1880 * name.reset();
1881 * console.log(name); // {who: 'Alex'}
1882 * ```
1883 * **Constructing *nullable* fields on groups or arrays**
1884 *
1885 * It is still possible to have a nullable field. In particular, any `FormControl` which is
1886 * *already* constructed will not be altered. For example:
1887 *
1888 * ```ts
1889 * let nnfb = new FormBuilder().nonNullable;
1890 * // FormGroup<{who: FormControl<string|null>}>
1891 * let name = nnfb.group({who: new FormControl('Alex')});
1892 * name.reset(); console.log(name); // {who: null}
1893 * ```
1894 *
1895 * Because the inner control is constructed explicitly by the caller, the builder has
1896 * no control over how it is created, and cannot exclude the `null`.
1897 */
1898 get nonNullable(): NonNullableFormBuilder;
1899 /**
1900 * @description
1901 * Constructs a new `FormGroup` instance. Accepts a single generic argument, which is an object
1902 * containing all the keys and corresponding inner control types.
1903 *
1904 * @param controls A collection of child controls. The key for each child is the name
1905 * under which it is registered.
1906 *
1907 * @param options Configuration options object for the `FormGroup`. The object should have the
1908 * `AbstractControlOptions` type and might contain the following fields:
1909 * * `validators`: A synchronous validator function, or an array of validator functions.
1910 * * `asyncValidators`: A single async validator or array of async validator functions.
1911 * * `updateOn`: The event upon which the control should be updated (options: 'change' | 'blur'
1912 * | submit').
1913 */
1914 group<T extends {}>(controls: T, options?: AbstractControlOptions | null): FormGroup<{
1915 [K in keyof T]: ɵElement<T[K], null>;
1916 }>;
1917 /**
1918 * @description
1919 * Constructs a new `FormGroup` instance.
1920 *
1921 * @deprecated This API is not typesafe and can result in issues with Closure Compiler renaming.
1922 * Use the `FormBuilder#group` overload with `AbstractControlOptions` instead.
1923 * Note that `AbstractControlOptions` expects `validators` and `asyncValidators` to be valid
1924 * validators. If you have custom validators, make sure their validation function parameter is
1925 * `AbstractControl` and not a sub-class, such as `FormGroup`. These functions will be called
1926 * with an object of type `AbstractControl` and that cannot be automatically downcast to a
1927 * subclass, so TypeScript sees this as an error. For example, change the `(group: FormGroup) =>
1928 * ValidationErrors|null` signature to be `(group: AbstractControl) => ValidationErrors|null`.
1929 *
1930 * @param controls A record of child controls. The key for each child is the name
1931 * under which the control is registered.
1932 *
1933 * @param options Configuration options object for the `FormGroup`. The legacy configuration
1934 * object consists of:
1935 * * `validator`: A synchronous validator function, or an array of validator functions.
1936 * * `asyncValidator`: A single async validator or array of async validator functions
1937 * Note: the legacy format is deprecated and might be removed in one of the next major versions
1938 * of Angular.
1939 */
1940 group(controls: {
1941 [key: string]: any;
1942 }, options: {
1943 [key: string]: any;
1944 }): FormGroup;
1945 /**
1946 * @description
1947 * Constructs a new `FormRecord` instance. Accepts a single generic argument, which is an object
1948 * containing all the keys and corresponding inner control types.
1949 *
1950 * @param controls A collection of child controls. The key for each child is the name
1951 * under which it is registered.
1952 *
1953 * @param options Configuration options object for the `FormRecord`. The object should have the
1954 * `AbstractControlOptions` type and might contain the following fields:
1955 * * `validators`: A synchronous validator function, or an array of validator functions.
1956 * * `asyncValidators`: A single async validator or array of async validator functions.
1957 * * `updateOn`: The event upon which the control should be updated (options: 'change' | 'blur'
1958 * | submit').
1959 */
1960 record<T>(controls: {
1961 [key: string]: T;
1962 }, options?: AbstractControlOptions | null): FormRecord<ɵElement<T, null>>;
1963 /** @deprecated Use `nonNullable` instead. */
1964 control<T>(formState: T | FormControlState<T>, opts: FormControlOptions & {
1965 initialValueIsDefault: true;
1966 }): FormControl<T>;
1967 control<T>(formState: T | FormControlState<T>, opts: FormControlOptions & {
1968 nonNullable: true;
1969 }): FormControl<T>;
1970 /**
1971 * @deprecated When passing an `options` argument, the `asyncValidator` argument has no effect.
1972 */
1973 control<T>(formState: T | FormControlState<T>, opts: FormControlOptions, asyncValidator: AsyncValidatorFn | AsyncValidatorFn[]): FormControl<T | null>;
1974 control<T>(formState: T | FormControlState<T>, validatorOrOpts?: ValidatorFn | ValidatorFn[] | FormControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null): FormControl<T | null>;
1975 /**
1976 * Constructs a new `FormArray` from the given array of configurations,
1977 * validators and options. Accepts a single generic argument, which is the type of each control
1978 * inside the array.
1979 *
1980 * @param controls An array of child controls or control configs. Each child control is given an
1981 * index when it is registered.
1982 *
1983 * @param validatorOrOpts A synchronous validator function, or an array of such functions, or an
1984 * `AbstractControlOptions` object that contains
1985 * validation functions and a validation trigger.
1986 *
1987 * @param asyncValidator A single async validator or array of async validator functions.
1988 */
1989 array<T>(controls: Array<T>, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null): FormArray<ɵElement<T, null>>;
1990 static ɵfac: i0.ɵɵFactoryDeclaration<FormBuilder, never>;
1991 static ɵprov: i0.ɵɵInjectableDeclaration<FormBuilder>;
1992}
1993
1994/**
1995 * Tracks the value and validation status of an individual form control.
1996 *
1997 * This is one of the four fundamental building blocks of Angular forms, along with
1998 * `FormGroup`, `FormArray` and `FormRecord`. It extends the `AbstractControl` class that
1999 * implements most of the base functionality for accessing the value, validation status,
2000 * user interactions and events.
2001 *
2002 * `FormControl` takes a single generic argument, which describes the type of its value. This
2003 * argument always implicitly includes `null` because the control can be reset. To change this
2004 * behavior, set `nonNullable` or see the usage notes below.
2005 *
2006 * See [usage examples below](#usage-notes).
2007 *
2008 * @see {@link AbstractControl}
2009 * @see [Reactive Forms Guide](guide/reactive-forms)
2010 * @see [Usage Notes](#usage-notes)
2011 *
2012 * @publicApi
2013 *
2014 * @overriddenImplementation ɵFormControlCtor
2015 *
2016 * @usageNotes
2017 *
2018 * ### Initializing Form Controls
2019 *
2020 * Instantiate a `FormControl`, with an initial value.
2021 *
2022 * ```ts
2023 * const control = new FormControl('some value');
2024 * console.log(control.value); // 'some value'
2025 * ```
2026 *
2027 * The following example initializes the control with a form state object. The `value`
2028 * and `disabled` keys are required in this case.
2029 *
2030 * ```ts
2031 * const control = new FormControl({ value: 'n/a', disabled: true });
2032 * console.log(control.value); // 'n/a'
2033 * console.log(control.status); // 'DISABLED'
2034 * ```
2035 *
2036 * The following example initializes the control with a synchronous validator.
2037 *
2038 * ```ts
2039 * const control = new FormControl('', Validators.required);
2040 * console.log(control.value); // ''
2041 * console.log(control.status); // 'INVALID'
2042 * ```
2043 *
2044 * The following example initializes the control using an options object.
2045 *
2046 * ```ts
2047 * const control = new FormControl('', {
2048 * validators: Validators.required,
2049 * asyncValidators: myAsyncValidator
2050 * });
2051 * ```
2052 *
2053 * ### The single type argument
2054 *
2055 * `FormControl` accepts a generic argument, which describes the type of its value.
2056 * In most cases, this argument will be inferred.
2057 *
2058 * If you are initializing the control to `null`, or you otherwise wish to provide a
2059 * wider type, you may specify the argument explicitly:
2060 *
2061 * ```
2062 * let fc = new FormControl<string|null>(null);
2063 * fc.setValue('foo');
2064 * ```
2065 *
2066 * You might notice that `null` is always added to the type of the control.
2067 * This is because the control will become `null` if you call `reset`. You can change
2068 * this behavior by setting `{nonNullable: true}`.
2069 *
2070 * ### Configure the control to update on a blur event
2071 *
2072 * Set the `updateOn` option to `'blur'` to update on the blur `event`.
2073 *
2074 * ```ts
2075 * const control = new FormControl('', { updateOn: 'blur' });
2076 * ```
2077 *
2078 * ### Configure the control to update on a submit event
2079 *
2080 * Set the `updateOn` option to `'submit'` to update on a submit `event`.
2081 *
2082 * ```ts
2083 * const control = new FormControl('', { updateOn: 'submit' });
2084 * ```
2085 *
2086 * ### Reset the control back to a specific value
2087 *
2088 * You reset to a specific form state by passing through a standalone
2089 * value or a form state object that contains both a value and a disabled state
2090 * (these are the only two properties that cannot be calculated).
2091 *
2092 * ```ts
2093 * const control = new FormControl('Nancy');
2094 *
2095 * console.log(control.value); // 'Nancy'
2096 *
2097 * control.reset('Drew');
2098 *
2099 * console.log(control.value); // 'Drew'
2100 * ```
2101 *
2102 * ### Reset the control to its initial value
2103 *
2104 * If you wish to always reset the control to its initial value (instead of null),
2105 * you can pass the `nonNullable` option:
2106 *
2107 * ```
2108 * const control = new FormControl('Nancy', {nonNullable: true});
2109 *
2110 * console.log(control.value); // 'Nancy'
2111 *
2112 * control.reset();
2113 *
2114 * console.log(control.value); // 'Nancy'
2115 * ```
2116 *
2117 * ### Reset the control back to an initial value and disabled
2118 *
2119 * ```
2120 * const control = new FormControl('Nancy');
2121 *
2122 * console.log(control.value); // 'Nancy'
2123 * console.log(control.status); // 'VALID'
2124 *
2125 * control.reset({ value: 'Drew', disabled: true });
2126 *
2127 * console.log(control.value); // 'Drew'
2128 * console.log(control.status); // 'DISABLED'
2129 * ```
2130 */
2131export declare interface FormControl<TValue = any> extends AbstractControl<TValue> {
2132 /**
2133 * The default value of this FormControl, used whenever the control is reset without an explicit
2134 * value. See {@link FormControlOptions#nonNullable} for more information on configuring
2135 * a default value.
2136 */
2137 readonly defaultValue: TValue;
2138 /**
2139 * Sets a new value for the form control.
2140 *
2141 * @param value The new value for the control.
2142 * @param options Configuration options that determine how the control propagates changes
2143 * and emits events when the value changes.
2144 * The configuration options are passed to the {@link AbstractControl#updateValueAndValidity
2145 * updateValueAndValidity} method.
2146 *
2147 * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is
2148 * false.
2149 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
2150 * `valueChanges`
2151 * observables emit events with the latest status and value when the control value is updated.
2152 * When false, no events are emitted.
2153 * * `emitModelToViewChange`: When true or not supplied (the default), each change triggers an
2154 * `onChange` event to
2155 * update the view.
2156 * * `emitViewToModelChange`: When true or not supplied (the default), each change triggers an
2157 * `ngModelChange`
2158 * event to update the model.
2159 *
2160 */
2161 setValue(value: TValue, options?: {
2162 onlySelf?: boolean;
2163 emitEvent?: boolean;
2164 emitModelToViewChange?: boolean;
2165 emitViewToModelChange?: boolean;
2166 }): void;
2167 /**
2168 * Patches the value of a control.
2169 *
2170 * This function is functionally the same as {@link FormControl#setValue setValue} at this level.
2171 * It exists for symmetry with {@link FormGroup#patchValue patchValue} on `FormGroups` and
2172 * `FormArrays`, where it does behave differently.
2173 *
2174 * @see {@link FormControl#setValue} for options
2175 */
2176 patchValue(value: TValue, options?: {
2177 onlySelf?: boolean;
2178 emitEvent?: boolean;
2179 emitModelToViewChange?: boolean;
2180 emitViewToModelChange?: boolean;
2181 }): void;
2182 /**
2183 * Resets the form control, marking it `pristine` and `untouched`, and resetting
2184 * the value. The new value will be the provided value (if passed), `null`, or the initial value
2185 * if `nonNullable` was set in the constructor via {@link FormControlOptions}.
2186 *
2187 * ```ts
2188 * // By default, the control will reset to null.
2189 * const dog = new FormControl('spot');
2190 * dog.reset(); // dog.value is null
2191 *
2192 * // If this flag is set, the control will instead reset to the initial value.
2193 * const cat = new FormControl('tabby', {nonNullable: true});
2194 * cat.reset(); // cat.value is "tabby"
2195 *
2196 * // A value passed to reset always takes precedence.
2197 * const fish = new FormControl('finn', {nonNullable: true});
2198 * fish.reset('bubble'); // fish.value is "bubble"
2199 * ```
2200 *
2201 * @param formState Resets the control with an initial value,
2202 * or an object that defines the initial value and disabled state.
2203 *
2204 * @param options Configuration options that determine how the control propagates changes
2205 * and emits events after the value changes.
2206 *
2207 * * `onlySelf`: When true, each change only affects this control, and not its parent. Default is
2208 * false.
2209 * * `emitEvent`: When true or not supplied (the default), both the `statusChanges` and
2210 * `valueChanges`
2211 * observables emit events with the latest status and value when the control is reset.
2212 * When false, no events are emitted.
2213 *
2214 */
2215 reset(formState?: TValue | FormControlState<TValue>, options?: {
2216 onlySelf?: boolean;
2217 emitEvent?: boolean;
2218 }): void;
2219 /**
2220 * For a simple FormControl, the raw value is equivalent to the value.
2221 */
2222 getRawValue(): TValue;
2223 /**
2224 * Register a listener for change events.
2225 *
2226 * @param fn The method that is called when the value changes
2227 */
2228 registerOnChange(fn: Function): void;
2229 /**
2230 * Register a listener for disabled events.
2231 *
2232 * @param fn The method that is called when the disabled status changes.
2233 */
2234 registerOnDisabledChange(fn: (isDisabled: boolean) => void): void;
2235}
2236
2237export declare const FormControl: ɵFormControlCtor;
2238
2239/**
2240 * @description
2241 * Synchronizes a standalone `FormControl` instance to a form control element.
2242 *
2243 * Note that support for using the `ngModel` input property and `ngModelChange` event with reactive
2244 * form directives was deprecated in Angular v6 and is scheduled for removal in
2245 * a future version of Angular.
2246 * For details, see [Deprecated features](guide/deprecations#ngmodel-with-reactive-forms).
2247 *
2248 * @see [Reactive Forms Guide](guide/reactive-forms)
2249 * @see {@link FormControl}
2250 * @see {@link AbstractControl}
2251 *
2252 * @usageNotes
2253 *
2254 * The following example shows how to register a standalone control and set its value.
2255 *
2256 * {@example forms/ts/simpleFormControl/simple_form_control_example.ts region='Component'}
2257 *
2258 * @ngModule ReactiveFormsModule
2259 * @publicApi
2260 */
2261export declare class FormControlDirective extends NgControl implements OnChanges, OnDestroy {
2262 private _ngModelWarningConfig;
2263 private callSetDisabledState?;
2264 /**
2265 * Internal reference to the view model value.
2266 * @nodoc
2267 */
2268 viewModel: any;
2269 /**
2270 * @description
2271 * Tracks the `FormControl` instance bound to the directive.
2272 */
2273 form: FormControl;
2274 /**
2275 * @description
2276 * Triggers a warning in dev mode that this input should not be used with reactive forms.
2277 */
2278 set isDisabled(isDisabled: boolean);
2279 /** @deprecated as of v6 */
2280 model: any;
2281 /** @deprecated as of v6 */
2282 update: EventEmitter<any>;
2283 constructor(validators: (Validator | ValidatorFn)[], asyncValidators: (AsyncValidator | AsyncValidatorFn)[], valueAccessors: ControlValueAccessor[], _ngModelWarningConfig: string | null, callSetDisabledState?: SetDisabledStateOption | undefined);
2284 /** @nodoc */
2285 ngOnChanges(changes: SimpleChanges): void;
2286 /** @nodoc */
2287 ngOnDestroy(): void;
2288 /**
2289 * @description
2290 * Returns an array that represents the path from the top-level form to this control.
2291 * Each index is the string name of the control on that level.
2292 */
2293 get path(): string[];
2294 /**
2295 * @description
2296 * The `FormControl` bound to this directive.
2297 */
2298 get control(): FormControl;
2299 /**
2300 * @description
2301 * Sets the new value for the view model and emits an `ngModelChange` event.
2302 *
2303 * @param newValue The new value for the view model.
2304 */
2305 viewToModelUpdate(newValue: any): void;
2306 private _isControlChanged;
2307 static ɵfac: i0.ɵɵFactoryDeclaration<FormControlDirective, [{ optional: true; self: true; }, { optional: true; self: true; }, { optional: true; self: true; }, { optional: true; }, { optional: true; }]>;
2308 static ɵdir: i0.ɵɵDirectiveDeclaration<FormControlDirective, "[formControl]", ["ngForm"], { "form": { "alias": "formControl"; "required": false; }; "isDisabled": { "alias": "disabled"; "required": false; }; "model": { "alias": "ngModel"; "required": false; }; }, { "update": "ngModelChange"; }, never, never, false, never>;
2309}
2310
2311/**
2312 * @description
2313 * Syncs a `FormControl` in an existing `FormGroup` to a form control
2314 * element by name.
2315 *
2316 * @see [Reactive Forms Guide](guide/reactive-forms)
2317 * @see {@link FormControl}
2318 * @see {@link AbstractControl}
2319 *
2320 * @usageNotes
2321 *
2322 * ### Register `FormControl` within a group
2323 *
2324 * The following example shows how to register multiple form controls within a form group
2325 * and set their value.
2326 *
2327 * {@example forms/ts/simpleFormGroup/simple_form_group_example.ts region='Component'}
2328 *
2329 * To see `formControlName` examples with different form control types, see:
2330 *
2331 * * Radio buttons: `RadioControlValueAccessor`
2332 * * Selects: `SelectControlValueAccessor`
2333 *
2334 * ### Use with ngModel is deprecated
2335 *
2336 * Support for using the `ngModel` input property and `ngModelChange` event with reactive
2337 * form directives has been deprecated in Angular v6 and is scheduled for removal in
2338 * a future version of Angular.
2339 *
2340 * For details, see [Deprecated features](guide/deprecations#ngmodel-with-reactive-forms).
2341 *
2342 * @ngModule ReactiveFormsModule
2343 * @publicApi
2344 */
2345export declare class FormControlName extends NgControl implements OnChanges, OnDestroy {
2346 private _ngModelWarningConfig;
2347 private _added;
2348 /**
2349 * @description
2350 * Tracks the `FormControl` instance bound to the directive.
2351 */
2352 readonly control: FormControl;
2353 /**
2354 * @description
2355 * Tracks the name of the `FormControl` bound to the directive. The name corresponds
2356 * to a key in the parent `FormGroup` or `FormArray`.
2357 * Accepts a name as a string or a number.
2358 * The name in the form of a string is useful for individual forms,
2359 * while the numerical form allows for form controls to be bound
2360 * to indices when iterating over controls in a `FormArray`.
2361 */
2362 name: string | number | null;
2363 /**
2364 * @description
2365 * Triggers a warning in dev mode that this input should not be used with reactive forms.
2366 */
2367 set isDisabled(isDisabled: boolean);
2368 /** @deprecated as of v6 */
2369 model: any;
2370 /** @deprecated as of v6 */
2371 update: EventEmitter<any>;
2372 constructor(parent: ControlContainer, validators: (Validator | ValidatorFn)[], asyncValidators: (AsyncValidator | AsyncValidatorFn)[], valueAccessors: ControlValueAccessor[], _ngModelWarningConfig: string | null);
2373 /** @nodoc */
2374 ngOnChanges(changes: SimpleChanges): void;
2375 /** @nodoc */
2376 ngOnDestroy(): void;
2377 /**
2378 * @description
2379 * Sets the new value for the view model and emits an `ngModelChange` event.
2380 *
2381 * @param newValue The new value for the view model.
2382 */
2383 viewToModelUpdate(newValue: any): void;
2384 /**
2385 * @description
2386 * Returns an array that represents the path from the top-level form to this control.
2387 * Each index is the string name of the control on that level.
2388 */
2389 get path(): string[];
2390 /**
2391 * @description
2392 * The top-level directive for this group if present, otherwise null.
2393 */
2394 get formDirective(): any;
2395 private _checkParentType;
2396 private _setUpControl;
2397 static ɵfac: i0.ɵɵFactoryDeclaration<FormControlName, [{ optional: true; host: true; skipSelf: true; }, { optional: true; self: true; }, { optional: true; self: true; }, { optional: true; self: true; }, { optional: true; }]>;
2398 static ɵdir: i0.ɵɵDirectiveDeclaration<FormControlName, "[formControlName]", never, { "name": { "alias": "formControlName"; "required": false; }; "isDisabled": { "alias": "disabled"; "required": false; }; "model": { "alias": "ngModel"; "required": false; }; }, { "update": "ngModelChange"; }, never, never, false, never>;
2399}
2400
2401/**
2402 * Interface for options provided to a `FormControl`.
2403 *
2404 * This interface extends all options from {@link AbstractControlOptions}, plus some options
2405 * unique to `FormControl`.
2406 *
2407 * @publicApi
2408 */
2409export declare interface FormControlOptions extends AbstractControlOptions {
2410 /**
2411 * @description
2412 * Whether to use the initial value used to construct the `FormControl` as its default value
2413 * as well. If this option is false or not provided, the default value of a FormControl is `null`.
2414 * When a FormControl is reset without an explicit value, its value reverts to
2415 * its default value.
2416 */
2417 nonNullable?: boolean;
2418 /**
2419 * @deprecated Use `nonNullable` instead.
2420 */
2421 initialValueIsDefault?: boolean;
2422}
2423
2424/**
2425 * FormControlState is a boxed form value. It is an object with a `value` key and a `disabled` key.
2426 *
2427 * @publicApi
2428 */
2429export declare interface FormControlState<T> {
2430 value: T;
2431 disabled: boolean;
2432}
2433
2434/**
2435 * A form can have several different statuses. Each
2436 * possible status is returned as a string literal.
2437 *
2438 * * **VALID**: Reports that a control is valid, meaning that no errors exist in the input
2439 * value.
2440 * * **INVALID**: Reports that a control is invalid, meaning that an error exists in the input
2441 * value.
2442 * * **PENDING**: Reports that a control is pending, meaning that async validation is
2443 * occurring and errors are not yet available for the input value.
2444 * * **DISABLED**: Reports that a control is
2445 * disabled, meaning that the control is exempt from ancestor calculations of validity or value.
2446 *
2447 * @publicApi
2448 */
2449export declare type FormControlStatus = 'VALID' | 'INVALID' | 'PENDING' | 'DISABLED';
2450
2451/**
2452 * Tracks the value and validity state of a group of `FormControl` instances.
2453 *
2454 * A `FormGroup` aggregates the values of each child `FormControl` into one object,
2455 * with each control name as the key. It calculates its status by reducing the status values
2456 * of its children. For example, if one of the controls in a group is invalid, the entire
2457 * group becomes invalid.
2458 *
2459 * `FormGroup` is one of the four fundamental building blocks used to define forms in Angular,
2460 * along with `FormControl`, `FormArray`, and `FormRecord`.
2461 *
2462 * When instantiating a `FormGroup`, pass in a collection of child controls as the first
2463 * argument. The key for each child registers the name for the control.
2464 *
2465 * `FormGroup` is intended for use cases where the keys are known ahead of time.
2466 * If you need to dynamically add and remove controls, use {@link FormRecord} instead.
2467 *
2468 * `FormGroup` accepts an optional type parameter `TControl`, which is an object type with inner
2469 * control types as values.
2470 *
2471 * @usageNotes
2472 *
2473 * ### Create a form group with 2 controls
2474 *
2475 * ```
2476 * const form = new FormGroup({
2477 * first: new FormControl('Nancy', Validators.minLength(2)),
2478 * last: new FormControl('Drew'),
2479 * });
2480 *
2481 * console.log(form.value); // {first: 'Nancy', last; 'Drew'}
2482 * console.log(form.status); // 'VALID'
2483 * ```
2484 *
2485 * ### The type argument, and optional controls
2486 *
2487 * `FormGroup` accepts one generic argument, which is an object containing its inner controls.
2488 * This type will usually be inferred automatically, but you can always specify it explicitly if you
2489 * wish.
2490 *
2491 * If you have controls that are optional (i.e. they can be removed, you can use the `?` in the
2492 * type):
2493 *
2494 * ```
2495 * const form = new FormGroup<{
2496 * first: FormControl<string|null>,
2497 * middle?: FormControl<string|null>, // Middle name is optional.
2498 * last: FormControl<string|null>,
2499 * }>({
2500 * first: new FormControl('Nancy'),
2501 * last: new FormControl('Drew'),
2502 * });
2503 * ```
2504 *
2505 * ### Create a form group with a group-level validator
2506 *
2507 * You include group-level validators as the second arg, or group-level async
2508 * validators as the third arg. These come in handy when you want to perform validation
2509 * that considers the value of more than one child control.
2510 *
2511 * ```
2512 * const form = new FormGroup({
2513 * password: new FormControl('', Validators.minLength(2)),
2514 * passwordConfirm: new FormControl('', Validators.minLength(2)),
2515 * }, passwordMatchValidator);
2516 *
2517 *
2518 * function passwordMatchValidator(g: FormGroup) {
2519 * return g.get('password').value === g.get('passwordConfirm').value
2520 * ? null : {'mismatch': true};
2521 * }
2522 * ```
2523 *
2524 * Like `FormControl` instances, you choose to pass in
2525 * validators and async validators as part of an options object.
2526 *
2527 * ```
2528 * const form = new FormGroup({
2529 * password: new FormControl('')
2530 * passwordConfirm: new FormControl('')
2531 * }, { validators: passwordMatchValidator, asyncValidators: otherValidator });
2532 * ```
2533 *
2534 * ### Set the updateOn property for all controls in a form group
2535 *
2536 * The options object is used to set a default value for each child
2537 * control's `updateOn` property. If you set `updateOn` to `'blur'` at the
2538 * group level, all child controls default to 'blur', unless the child
2539 * has explicitly specified a different `updateOn` value.
2540 *
2541 * ```ts
2542 * const c = new FormGroup({
2543 * one: new FormControl()
2544 * }, { updateOn: 'blur' });
2545 * ```
2546 *
2547 * ### Using a FormGroup with optional controls
2548 *
2549 * It is possible to have optional controls in a FormGroup. An optional control can be removed later
2550 * using `removeControl`, and can be omitted when calling `reset`. Optional controls must be
2551 * declared optional in the group's type.
2552 *
2553 * ```ts
2554 * const c = new FormGroup<{one?: FormControl<string>}>({
2555 * one: new FormControl('')
2556 * });
2557 * ```
2558 *
2559 * Notice that `c.value.one` has type `string|null|undefined`. This is because calling `c.reset({})`
2560 * without providing the optional key `one` will cause it to become `null`.
2561 *
2562 * @publicApi
2563 */