/** * @license * Copyright Google LLC All Rights Reserved. * * Use of this source code is governed by an MIT-style license that can be * found in the LICENSE file at https://angular.io/license */ import {Directive, forwardRef, Input, OnChanges, SimpleChanges, StaticProvider} from '@angular/core'; import {Observable} from 'rxjs'; import {AbstractControl} from '../model'; import {emailValidator, maxLengthValidator, maxValidator, minLengthValidator, minValidator, NG_VALIDATORS, nullValidator, patternValidator, requiredTrueValidator, requiredValidator} from '../validators'; /** * @description * Defines the map of errors returned from failed validation checks. * * @publicApi */ export type ValidationErrors = { [key: string]: any }; /** * @description * An interface implemented by classes that perform synchronous validation. * * @usageNotes * * ### Provide a custom validator * * The following example implements the `Validator` interface to create a * validator directive with a custom error key. * * ```typescript * @Directive({ * selector: '[customValidator]', * providers: [{provide: NG_VALIDATORS, useExisting: CustomValidatorDirective, multi: true}] * }) * class CustomValidatorDirective implements Validator { * validate(control: AbstractControl): ValidationErrors|null { * return {'custom': true}; * } * } * ``` * * @publicApi */ export interface Validator { /** * @description * Method that performs synchronous validation against the provided control. * * @param control The control to validate against. * * @returns A map of validation errors if validation fails, * otherwise null. */ validate(control: AbstractControl): ValidationErrors|null; /** * @description * Registers a callback function to call when the validator inputs change. * * @param fn The callback function */ registerOnValidatorChange?(fn: () => void): void; } /** * A base class for Validator-based Directives. The class contains common logic shared across such * Directives. * * For internal use only, this class is not intended for use outside of the Forms package. */ @Directive() abstract class AbstractValidatorDirective implements Validator { private _validator: ValidatorFn = nullValidator; private _onChange!: () => void; /** * Name of an input that matches directive selector attribute (e.g. `minlength` for * `MinLengthDirective`). An input with a given name might contain configuration information (like * `minlength='10'`) or a flag that indicates whether validator should be enabled (like * `[required]='false'`). * * @internal */ abstract inputName: string; /** * Creates an instance of a validator (specific to a directive that extends this base class). * * @internal */ abstract createValidator(input: unknown): ValidatorFn; /** * Performs the necessary input normalization based on a specific logic of a Directive. * For example, the function might be used to convert string-based representation of the * `minlength` input to an integer value that can later be used in the `Validators.minLength` * validator. * * @internal */ abstract normalizeInput(input: unknown): unknown; /** * Helper function invoked from child classes to process changes (from `ngOnChanges` hook). * @nodoc */ handleChanges(changes: SimpleChanges): void { if (this.inputName in changes) { const input = this.normalizeInput(changes[this.inputName].currentValue); this._validator = this.createValidator(input); if (this._onChange) { this._onChange(); } } } /** @nodoc */ validate(control: AbstractControl): ValidationErrors|null { return this._validator(control); } /** @nodoc */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } } /** * @description * Provider which adds `MaxValidator` to the `NG_VALIDATORS` multi-provider list. */ export const MAX_VALIDATOR: StaticProvider = { provide: NG_VALIDATORS, useExisting: forwardRef(() => MaxValidator), multi: true }; /** * A directive which installs the {@link MaxValidator} for any `formControlName`, * `formControl`, or control with `ngModel` that also has a `max` attribute. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding a max validator * * The following example shows how to add a max validator to an input attached to an * ngModel binding. * * ```html * * ``` * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ @Directive({ selector: 'input[type=number][max][formControlName],input[type=number][max][formControl],input[type=number][max][ngModel]', providers: [MAX_VALIDATOR], host: {'[attr.max]': 'max ? max : null'} }) export class MaxValidator extends AbstractValidatorDirective implements OnChanges { /** * @description * Tracks changes to the max bound to this directive. */ @Input() max!: string|number; /** @internal */ inputName = 'max'; /** @internal */ normalizeInput = (input: string): number => parseInt(input, 10); /** @internal */ createValidator = (max: number): ValidatorFn => maxValidator(max); /** * Declare `ngOnChanges` lifecycle hook at the main directive level (vs keeping it in base class) * to avoid differences in handling inheritance of lifecycle hooks between Ivy and ViewEngine in * AOT mode. This could be refactored once ViewEngine is removed. * @nodoc */ ngOnChanges(changes: SimpleChanges): void { this.handleChanges(changes); } } /** * @description * Provider which adds `MinValidator` to the `NG_VALIDATORS` multi-provider list. */ export const MIN_VALIDATOR: StaticProvider = { provide: NG_VALIDATORS, useExisting: forwardRef(() => MinValidator), multi: true }; /** * A directive which installs the {@link MinValidator} for any `formControlName`, * `formControl`, or control with `ngModel` that also has a `min` attribute. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding a min validator * * The following example shows how to add a min validator to an input attached to an * ngModel binding. * * ```html * * ``` * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ @Directive({ selector: 'input[type=number][min][formControlName],input[type=number][min][formControl],input[type=number][min][ngModel]', providers: [MIN_VALIDATOR], host: {'[attr.min]': 'min ? min : null'} }) export class MinValidator extends AbstractValidatorDirective implements OnChanges { /** * @description * Tracks changes to the min bound to this directive. */ @Input() min!: string|number; /** @internal */ inputName = 'min'; /** @internal */ normalizeInput = (input: string): number => parseInt(input, 10); /** @internal */ createValidator = (min: number): ValidatorFn => minValidator(min); /** * Declare `ngOnChanges` lifecycle hook at the main directive level (vs keeping it in base class) * to avoid differences in handling inheritance of lifecycle hooks between Ivy and ViewEngine in * AOT mode. This could be refactored once ViewEngine is removed. * @nodoc */ ngOnChanges(changes: SimpleChanges): void { this.handleChanges(changes); } } /** * @description * An interface implemented by classes that perform asynchronous validation. * * @usageNotes * * ### Provide a custom async validator directive * * The following example implements the `AsyncValidator` interface to create an * async validator directive with a custom error key. * * ```typescript * import { of } from 'rxjs'; * * @Directive({ * selector: '[customAsyncValidator]', * providers: [{provide: NG_ASYNC_VALIDATORS, useExisting: CustomAsyncValidatorDirective, multi: * true}] * }) * class CustomAsyncValidatorDirective implements AsyncValidator { * validate(control: AbstractControl): Observable { * return of({'custom': true}); * } * } * ``` * * @publicApi */ export interface AsyncValidator extends Validator { /** * @description * Method that performs async validation against the provided control. * * @param control The control to validate against. * * @returns A promise or observable that resolves a map of validation errors * if validation fails, otherwise null. */ validate(control: AbstractControl): Promise|Observable; } /** * @description * Provider which adds `RequiredValidator` to the `NG_VALIDATORS` multi-provider list. */ export const REQUIRED_VALIDATOR: StaticProvider = { provide: NG_VALIDATORS, useExisting: forwardRef(() => RequiredValidator), multi: true }; /** * @description * Provider which adds `CheckboxRequiredValidator` to the `NG_VALIDATORS` multi-provider list. */ export const CHECKBOX_REQUIRED_VALIDATOR: StaticProvider = { provide: NG_VALIDATORS, useExisting: forwardRef(() => CheckboxRequiredValidator), multi: true }; /** * @description * A directive that adds the `required` validator to any controls marked with the * `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding a required validator using template-driven forms * * ``` * * ``` * * @ngModule FormsModule * @ngModule ReactiveFormsModule * @publicApi */ @Directive({ selector: ':not([type=checkbox])[required][formControlName],:not([type=checkbox])[required][formControl],:not([type=checkbox])[required][ngModel]', providers: [REQUIRED_VALIDATOR], host: {'[attr.required]': 'required ? "" : null'} }) export class RequiredValidator implements Validator { private _required = false; private _onChange?: () => void; /** * @description * Tracks changes to the required attribute bound to this directive. */ @Input() get required(): boolean|string { return this._required; } set required(value: boolean|string) { this._required = value != null && value !== false && `${value}` !== 'false'; if (this._onChange) this._onChange(); } /** * Method that validates whether the control is empty. * Returns the validation result if enabled, otherwise null. * @nodoc */ validate(control: AbstractControl): ValidationErrors|null { return this.required ? requiredValidator(control) : null; } /** * Registers a callback function to call when the validator inputs change. * @nodoc */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } } /** * A Directive that adds the `required` validator to checkbox controls marked with the * `required` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding a required checkbox validator using template-driven forms * * The following example shows how to add a checkbox required validator to an input attached to an * ngModel binding. * * ``` * * ``` * * @publicApi * @ngModule FormsModule * @ngModule ReactiveFormsModule */ @Directive({ selector: 'input[type=checkbox][required][formControlName],input[type=checkbox][required][formControl],input[type=checkbox][required][ngModel]', providers: [CHECKBOX_REQUIRED_VALIDATOR], host: {'[attr.required]': 'required ? "" : null'} }) export class CheckboxRequiredValidator extends RequiredValidator { /** * Method that validates whether or not the checkbox has been checked. * Returns the validation result if enabled, otherwise null. * @nodoc */ validate(control: AbstractControl): ValidationErrors|null { return this.required ? requiredTrueValidator(control) : null; } } /** * @description * Provider which adds `EmailValidator` to the `NG_VALIDATORS` multi-provider list. */ export const EMAIL_VALIDATOR: any = { provide: NG_VALIDATORS, useExisting: forwardRef(() => EmailValidator), multi: true }; /** * A directive that adds the `email` validator to controls marked with the * `email` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding an email validator * * The following example shows how to add an email validator to an input attached to an ngModel * binding. * * ``` * * * * ``` * * @publicApi * @ngModule FormsModule * @ngModule ReactiveFormsModule */ @Directive({ selector: '[email][formControlName],[email][formControl],[email][ngModel]', providers: [EMAIL_VALIDATOR] }) export class EmailValidator implements Validator { private _enabled = false; private _onChange?: () => void; /** * @description * Tracks changes to the email attribute bound to this directive. */ @Input() set email(value: boolean|string) { this._enabled = value === '' || value === true || value === 'true'; if (this._onChange) this._onChange(); } /** * Method that validates whether an email address is valid. * Returns the validation result if enabled, otherwise null. * @nodoc */ validate(control: AbstractControl): ValidationErrors|null { return this._enabled ? emailValidator(control) : null; } /** * Registers a callback function to call when the validator inputs change. * @nodoc */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } } /** * @description * A function that receives a control and synchronously returns a map of * validation errors if present, otherwise null. * * @publicApi */ export interface ValidatorFn { (control: AbstractControl): ValidationErrors|null; } /** * @description * A function that receives a control and returns a Promise or observable * that emits validation errors if present, otherwise null. * * @publicApi */ export interface AsyncValidatorFn { (control: AbstractControl): Promise|Observable; } /** * @description * Provider which adds `MinLengthValidator` to the `NG_VALIDATORS` multi-provider list. */ export const MIN_LENGTH_VALIDATOR: any = { provide: NG_VALIDATORS, useExisting: forwardRef(() => MinLengthValidator), multi: true }; /** * A directive that adds minimum length validation to controls marked with the * `minlength` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding a minimum length validator * * The following example shows how to add a minimum length validator to an input attached to an * ngModel binding. * * ```html * * ``` * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ @Directive({ selector: '[minlength][formControlName],[minlength][formControl],[minlength][ngModel]', providers: [MIN_LENGTH_VALIDATOR], host: {'[attr.minlength]': 'minlength ? minlength : null'} }) export class MinLengthValidator implements Validator, OnChanges { private _validator: ValidatorFn = nullValidator; private _onChange?: () => void; /** * @description * Tracks changes to the minimum length bound to this directive. */ @Input() minlength!: string|number; // This input is always defined, since the name matches selector. /** @nodoc */ ngOnChanges(changes: SimpleChanges): void { if ('minlength' in changes) { this._createValidator(); if (this._onChange) this._onChange(); } } /** * Method that validates whether the value meets a minimum length requirement. * Returns the validation result if enabled, otherwise null. * @nodoc */ validate(control: AbstractControl): ValidationErrors|null { return this.minlength == null ? null : this._validator(control); } /** * Registers a callback function to call when the validator inputs change. * @nodoc */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } private _createValidator(): void { this._validator = minLengthValidator( typeof this.minlength === 'number' ? this.minlength : parseInt(this.minlength, 10)); } } /** * @description * Provider which adds `MaxLengthValidator` to the `NG_VALIDATORS` multi-provider list. */ export const MAX_LENGTH_VALIDATOR: any = { provide: NG_VALIDATORS, useExisting: forwardRef(() => MaxLengthValidator), multi: true }; /** * A directive that adds max length validation to controls marked with the * `maxlength` attribute. The directive is provided with the `NG_VALIDATORS` multi-provider list. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding a maximum length validator * * The following example shows how to add a maximum length validator to an input attached to an * ngModel binding. * * ```html * * ``` * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ @Directive({ selector: '[maxlength][formControlName],[maxlength][formControl],[maxlength][ngModel]', providers: [MAX_LENGTH_VALIDATOR], host: {'[attr.maxlength]': 'maxlength ? maxlength : null'} }) export class MaxLengthValidator implements Validator, OnChanges { private _validator: ValidatorFn = nullValidator; private _onChange?: () => void; /** * @description * Tracks changes to the maximum length bound to this directive. */ @Input() maxlength!: string|number; // This input is always defined, since the name matches selector. /** @nodoc */ ngOnChanges(changes: SimpleChanges): void { if ('maxlength' in changes) { this._createValidator(); if (this._onChange) this._onChange(); } } /** * Method that validates whether the value exceeds the maximum length requirement. * @nodoc */ validate(control: AbstractControl): ValidationErrors|null { return this.maxlength != null ? this._validator(control) : null; } /** * Registers a callback function to call when the validator inputs change. * @nodoc */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } private _createValidator(): void { this._validator = maxLengthValidator( typeof this.maxlength === 'number' ? this.maxlength : parseInt(this.maxlength, 10)); } } /** * @description * Provider which adds `PatternValidator` to the `NG_VALIDATORS` multi-provider list. */ export const PATTERN_VALIDATOR: any = { provide: NG_VALIDATORS, useExisting: forwardRef(() => PatternValidator), multi: true }; /** * @description * A directive that adds regex pattern validation to controls marked with the * `pattern` attribute. The regex must match the entire control value. * The directive is provided with the `NG_VALIDATORS` multi-provider list. * * @see [Form Validation](guide/form-validation) * * @usageNotes * * ### Adding a pattern validator * * The following example shows how to add a pattern validator to an input attached to an * ngModel binding. * * ```html * * ``` * * @ngModule ReactiveFormsModule * @ngModule FormsModule * @publicApi */ @Directive({ selector: '[pattern][formControlName],[pattern][formControl],[pattern][ngModel]', providers: [PATTERN_VALIDATOR], host: {'[attr.pattern]': 'pattern ? pattern : null'} }) export class PatternValidator implements Validator, OnChanges { private _validator: ValidatorFn = nullValidator; private _onChange?: () => void; /** * @description * Tracks changes to the pattern bound to this directive. */ @Input() pattern!: string|RegExp; // This input is always defined, since the name matches selector. /** @nodoc */ ngOnChanges(changes: SimpleChanges): void { if ('pattern' in changes) { this._createValidator(); if (this._onChange) this._onChange(); } } /** * Method that validates whether the value matches the pattern requirement. * @nodoc */ validate(control: AbstractControl): ValidationErrors|null { return this._validator(control); } /** * Registers a callback function to call when the validator inputs change. * @nodoc */ registerOnValidatorChange(fn: () => void): void { this._onChange = fn; } private _createValidator(): void { this._validator = patternValidator(this.pattern); } }