fix(forms): consistent treatment of empty (#63456)

Removes custom handling of emptiness in several of the validators and
replaces it with a common `isEmpty` check. The common empty check
considered the following values to be empty: `null`, `undefined`, `''`,
`false`, `NaN`

Generally most validators should treat an empty value as valid. This
aligns with both the behavior or native HTML validators and reactive
forms validators.

As an example, consider an optional email field. If the email validator
considered empty string to be an invalid email, there would be no way
for the user to not enter it.

There are several exceptions to this rule:
- `required` whose entire purpose is to ensure that the field is *not*
  empty
- `validateStandardSchema` which should subject all values including
  empty ones to the specified standard schema. It is up to the schema to
  decide whether an empty value is valid or not
- `validate`/`validateAsync` which leaves it up to the user's custom
  validation logic to decide if an empty value is valid.

PR Close #63456

Author: mmalerba

goldens/public-api/forms/signals/index.api.md

@@ -458,7 +458,6 @@ export const REQUIRED: AggregateProperty<boolean, boolean>;
 
 // @public
 export function required<TValue, TPathKind extends PathKind = PathKind.Root>(path: FieldPath<TValue, TPathKind>, config?: BaseValidatorConfig<TValue, TPathKind> & {
-    emptyPredicate?: (value: TValue) => boolean;
     when?: NoInfer<LogicFn<TValue, boolean, TPathKind>>;
 }): void;
 

packages/forms/signals/src/api/validators/email.ts

@@ -9,7 +9,7 @@
 import {validate} from '../logic';
 import {FieldPath, PathKind} from '../types';
 import {emailError} from '../validation_errors';
-import {BaseValidatorConfig, getOption} from './util';
+import {BaseValidatorConfig, getOption, isEmpty} from './util';
 
 /**
  * A regular expression that matches valid e-mail addresses.
@@ -59,6 +59,9 @@ export function email<TPathKind extends PathKind = PathKind.Root>(
   config?: BaseValidatorConfig<string, TPathKind>,
 ) {
   validate(path, (ctx) => {
+    if (isEmpty(ctx.value())) {
+      return undefined;
+    }
     if (!EMAIL_REGEXP.test(ctx.value())) {
       if (config?.error) {
         return getOption(config.error, ctx);

packages/forms/signals/src/api/validators/max.ts

@@ -11,7 +11,7 @@ import {aggregateProperty, property, validate} from '../logic';
 import {MAX} from '../property';
 import {FieldPath, LogicFn, PathKind} from '../types';
 import {maxError} from '../validation_errors';
-import {BaseValidatorConfig, getOption} from './util';
+import {BaseValidatorConfig, getOption, isEmpty} from './util';
 
 /**
  * Binds a validator to the given path that requires the value to be less than or equal to the
@@ -36,6 +36,9 @@ export function max<TPathKind extends PathKind = PathKind.Root>(
   );
   aggregateProperty(path, MAX, ({state}) => state.property(MAX_MEMO)!());
   validate(path, (ctx) => {
+    if (isEmpty(ctx.value())) {
+      return undefined;
+    }
     const max = ctx.state.property(MAX_MEMO)!();
     if (max === undefined || Number.isNaN(max)) {
       return undefined;

packages/forms/signals/src/api/validators/max_length.ts

@@ -11,7 +11,13 @@ import {aggregateProperty, property, validate} from '../logic';
 import {MAX_LENGTH} from '../property';
 import {FieldPath, LogicFn, PathKind} from '../types';
 import {maxLengthError} from '../validation_errors';
-import {BaseValidatorConfig, getLengthOrSize, getOption, ValueWithLengthOrSize} from './util';
+import {
+  BaseValidatorConfig,
+  getLengthOrSize,
+  getOption,
+  isEmpty,
+  ValueWithLengthOrSize,
+} from './util';
 
 /**
  * Binds a validator to the given path that requires the length of the value to be less than or
@@ -40,6 +46,9 @@ export function maxLength<
   );
   aggregateProperty(path, MAX_LENGTH, ({state}) => state.property(MAX_LENGTH_MEMO)!());
   validate(path, (ctx) => {
+    if (isEmpty(ctx.value())) {
+      return undefined;
+    }
     const maxLength = ctx.state.property(MAX_LENGTH_MEMO)!();
     if (maxLength === undefined) {
       return undefined;

packages/forms/signals/src/api/validators/min.ts

@@ -11,7 +11,7 @@ import {aggregateProperty, property, validate} from '../logic';
 import {MIN} from '../property';
 import {FieldPath, LogicFn, PathKind} from '../types';
 import {minError} from '../validation_errors';
-import {BaseValidatorConfig, getOption} from './util';
+import {BaseValidatorConfig, getOption, isEmpty} from './util';
 
 /**
  * Binds a validator to the given path that requires the value to be greater than or equal to
@@ -36,6 +36,9 @@ export function min<TPathKind extends PathKind = PathKind.Root>(
   );
   aggregateProperty(path, MIN, ({state}) => state.property(MIN_MEMO)!());
   validate(path, (ctx) => {
+    if (isEmpty(ctx.value())) {
+      return undefined;
+    }
     const min = ctx.state.property(MIN_MEMO)!();
     if (min === undefined || Number.isNaN(min)) {
       return undefined;

packages/forms/signals/src/api/validators/min_length.ts

@@ -11,7 +11,13 @@ import {aggregateProperty, property, validate} from '../logic';
 import {MIN_LENGTH} from '../property';
 import {FieldPath, LogicFn, PathKind} from '../types';
 import {minLengthError} from '../validation_errors';
-import {BaseValidatorConfig, getLengthOrSize, getOption, ValueWithLengthOrSize} from './util';
+import {
+  BaseValidatorConfig,
+  getLengthOrSize,
+  getOption,
+  isEmpty,
+  ValueWithLengthOrSize,
+} from './util';
 
 /**
  * Binds a validator to the given path that requires the length of the value to be greater than or
@@ -40,6 +46,9 @@ export function minLength<
   );
   aggregateProperty(path, MIN_LENGTH, ({state}) => state.property(MIN_LENGTH_MEMO)!());
   validate(path, (ctx) => {
+    if (isEmpty(ctx.value())) {
+      return undefined;
+    }
     const minLength = ctx.state.property(MIN_LENGTH_MEMO)!();
     if (minLength === undefined) {
       return undefined;

packages/forms/signals/src/api/validators/pattern.ts

@@ -11,7 +11,7 @@ import {aggregateProperty, property, validate} from '../logic';
 import {PATTERN} from '../property';
 import {FieldPath, LogicFn, PathKind} from '../types';
 import {patternError} from '../validation_errors';
-import {BaseValidatorConfig, getOption} from './util';
+import {BaseValidatorConfig, getOption, isEmpty} from './util';
 
 /**
  * Binds a validator to the given path that requires the value to match a specific regex pattern.
@@ -35,14 +35,13 @@ export function pattern<TPathKind extends PathKind = PathKind.Root>(
   );
   aggregateProperty(path, PATTERN, ({state}) => state.property(PATTERN_MEMO)!());
   validate(path, (ctx) => {
+    if (isEmpty(ctx.value())) {
+      return undefined;
+    }
     const pattern = ctx.state.property(PATTERN_MEMO)!();
-
-    // A pattern validator should not fail on an empty value. This matches the behavior of HTML's
-    // built in `pattern` attribute.
-    if (pattern === undefined || ctx.value() == null || ctx.value() === '') {
+    if (pattern === undefined) {
       return undefined;
     }
-
     if (!pattern.test(ctx.value())) {
       if (config?.error) {
         return getOption(config.error, ctx);

packages/forms/signals/src/api/validators/required.ts

@@ -11,7 +11,7 @@ import {aggregateProperty, property, validate} from '../logic';
 import {REQUIRED} from '../property';
 import {FieldPath, LogicFn, PathKind} from '../types';
 import {requiredError} from '../validation_errors';
-import {BaseValidatorConfig, getOption} from './util';
+import {BaseValidatorConfig, getOption, isEmpty} from './util';
 
 /**
  * Binds a validator to the given path that requires the value to be non-empty.
@@ -23,28 +23,22 @@ import {BaseValidatorConfig, getOption} from './util';
  *  - `message`: A user-facing message for the error.
  *  - `error`: Custom validation error(s) to be used instead of the default `ValidationError.required()`
  *    or a function that receives the `FieldContext` and returns custom validation error(s).
- *  - `emptyPredicate`: A function that receives the value, and returns `true` if it is considered empty.
- *    By default `false`, `''`, `null`, and `undefined` are considered empty
  *  - `when`: A function that receives the `FieldContext` and returns true if the field is required
  * @template TValue The type of value stored in the field the logic is bound to.
  * @template TPathKind The kind of path the logic is bound to (a root path, child path, or item of an array)
  */
 export function required<TValue, TPathKind extends PathKind = PathKind.Root>(
   path: FieldPath<TValue, TPathKind>,
   config?: BaseValidatorConfig<TValue, TPathKind> & {
-    emptyPredicate?: (value: TValue) => boolean;
     when?: NoInfer<LogicFn<TValue, boolean, TPathKind>>;
   },
 ): void {
-  const emptyPredicate =
-    config?.emptyPredicate ?? ((value) => value === false || value == null || value === '');
-
   const REQUIRED_MEMO = property(path, (ctx) =>
     computed(() => (config?.when ? config.when(ctx) : true)),
   );
   aggregateProperty(path, REQUIRED, ({state}) => state.property(REQUIRED_MEMO)!());
   validate(path, (ctx) => {
-    if (ctx.state.property(REQUIRED_MEMO)!() && emptyPredicate(ctx.value())) {
+    if (ctx.state.property(REQUIRED_MEMO)!() && isEmpty(ctx.value())) {
       if (config?.error) {
         return getOption(config.error, ctx);
       } else {

packages/forms/signals/src/api/validators/util.ts

@@ -50,3 +50,13 @@ export function getOption<TOption, TValue, TPathKind extends PathKind = PathKind
 ): TOption | undefined {
   return opt instanceof Function ? opt(ctx) : opt;
 }
+
+/**
+ * Checks if the given value is considered empty. Empty values are: null, undefined, '', false, NaN.
+ */
+export function isEmpty(value: unknown): boolean {
+  if (typeof value === 'number') {
+    return isNaN(value);
+  }
+  return value === '' || value === false || value == null;
+}

packages/forms/signals/test/node/api/validators/email.spec.ts

@@ -30,7 +30,7 @@ describe('email validator', () => {
   });
 
   it('supports custom errors', () => {
-    const cat = signal({name: 'pirojok-the-cat', email: ''});
+    const cat = signal({name: 'pirojok-the-cat', email: 'error'});
     const f = form(
       cat,
       (p) => {
@@ -52,7 +52,7 @@ describe('email validator', () => {
   });
 
   it('supports custom error message', () => {
-    const cat = signal({name: 'pirojok-the-cat', email: ''});
+    const cat = signal({name: 'pirojok-the-cat', email: 'error'});
     const f = form(
       cat,
       (p) => {
@@ -72,4 +72,19 @@ describe('email validator', () => {
       }),
     ]);
   });
+
+  it('should treat empty value as valid', () => {
+    const model = signal('');
+    const f = form(
+      model,
+      (p) => {
+        email(p);
+      },
+      {
+        injector: TestBed.inject(Injector),
+      },
+    );
+
+    expect(f().errors()).toEqual([]);
+  });
 });