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

mmalerba · mmalerba · commit 10ef96adb3d9 · 2025-08-29T14:43:03.000-07:00
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
diff --git a/goldens/public-api/forms/signals/index.api.md b/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;
 
diff --git a/packages/forms/signals/src/api/validators/email.ts b/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);
diff --git a/packages/forms/signals/src/api/validators/max.ts b/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;
diff --git a/packages/forms/signals/src/api/validators/max_length.ts b/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;
diff --git a/packages/forms/signals/src/api/validators/min.ts b/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;
diff --git a/packages/forms/signals/src/api/validators/min_length.ts b/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;
diff --git a/packages/forms/signals/src/api/validators/pattern.ts b/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);
diff --git a/packages/forms/signals/src/api/validators/required.ts b/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 {
diff --git a/packages/forms/signals/src/api/validators/util.ts b/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;
+}
diff --git a/packages/forms/signals/test/node/api/validators/email.spec.ts b/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([]);
+  });
 });
diff --git a/packages/forms/signals/test/node/api/validators/max.spec.ts b/packages/forms/signals/test/node/api/validators/max.spec.ts
@@ -107,6 +107,21 @@ describe('max validator', () => {
     expect(f.age().errors()).toEqual([]);
   });
 
+  it('should treat empty value as valid', () => {
+    const model = signal(NaN);
+    const f = form(
+      model,
+      (p) => {
+        max(p, -1);
+      },
+      {
+        injector: TestBed.inject(Injector),
+      },
+    );
+
+    expect(f().errors()).toEqual([]);
+  });
+
   describe('custom properties', () => {
     it('stores the MAX property on max', () => {
       const cat = signal({name: 'pirojok-the-cat', age: 6});
diff --git a/packages/forms/signals/test/node/api/validators/max_length.spec.ts b/packages/forms/signals/test/node/api/validators/max_length.spec.ts
@@ -123,6 +123,21 @@ describe('maxLength validator', () => {
     expect(f().errors()).toEqual([maxLengthError(3, {field: f})]);
   });
 
+  it('should treat empty value as valid', () => {
+    const model = signal('');
+    const f = form(
+      model,
+      (p) => {
+        maxLength(p, -1);
+      },
+      {
+        injector: TestBed.inject(Injector),
+      },
+    );
+
+    expect(f().errors()).toEqual([]);
+  });
+
   describe('custom properties', () => {
     it('stores the MAX_LENGTH property on maxLength', () => {
       const data = signal({text: 'abcdef'});
diff --git a/packages/forms/signals/test/node/api/validators/min.spec.ts b/packages/forms/signals/test/node/api/validators/min.spec.ts
@@ -107,6 +107,21 @@ describe('min validator', () => {
     expect(f.age().errors()).toEqual([]);
   });
 
+  it('should treat empty value as valid', () => {
+    const model = signal(NaN);
+    const f = form(
+      model,
+      (p) => {
+        min(p, 10);
+      },
+      {
+        injector: TestBed.inject(Injector),
+      },
+    );
+
+    expect(f().errors()).toEqual([]);
+  });
+
   describe('custom properties', () => {
     it('stores the MIN property on min', () => {
       const cat = signal({name: 'pirojok-the-cat', age: 3});
diff --git a/packages/forms/signals/test/node/api/validators/min_length.spec.ts b/packages/forms/signals/test/node/api/validators/min_length.spec.ts
@@ -123,6 +123,21 @@ describe('minLength validator', () => {
     expect(f().errors()).toEqual([minLengthError(5, {field: f})]);
   });
 
+  it('should treat empty value as valid', () => {
+    const model = signal('');
+    const f = form(
+      model,
+      (p) => {
+        minLength(p, 10);
+      },
+      {
+        injector: TestBed.inject(Injector),
+      },
+    );
+
+    expect(f().errors()).toEqual([]);
+  });
+
   describe('custom properties', () => {
     it('stores the MIN_LENGTH property on minLength', () => {
       const data = signal({text: 'ab'});
diff --git a/packages/forms/signals/test/node/api/validators/pattern.spec.ts b/packages/forms/signals/test/node/api/validators/pattern.spec.ts
@@ -53,6 +53,21 @@ describe('pattern validator', () => {
     ]);
   });
 
+  it('should treat empty value as valid', () => {
+    const model = signal('');
+    const f = form(
+      model,
+      (p) => {
+        pattern(p, /^hi$/);
+      },
+      {
+        injector: TestBed.inject(Injector),
+      },
+    );
+
+    expect(f().errors()).toEqual([]);
+  });
+
   describe('custom properties', () => {
     it('sets the PATTERN property', () => {
       const cat = signal({name: 'pelmeni-the-cat'});
diff --git a/packages/forms/signals/test/node/api/validators/required.spec.ts b/packages/forms/signals/test/node/api/validators/required.spec.ts
@@ -67,27 +67,6 @@ describe('required validator', () => {
     expect(f.name().errors()).toEqual([]);
   });
 
-  it('supports custom emptyPredicate', () => {
-    const cat = signal({name: ''});
-    const f = form(
-      cat,
-      (p) => {
-        required(p.name, {
-          emptyPredicate(value) {
-            return value === 'empty';
-          },
-        });
-      },
-      {
-        injector: TestBed.inject(Injector),
-      },
-    );
-
-    expect(f.name().errors()).toEqual([]);
-    f.name().value.set('empty');
-    expect(f.name().errors()).toEqual([requiredError({field: f.name})]);
-  });
-
   it('supports custom condition', () => {
     const cat = signal({name: '', age: 5});
     const f = form(
diff --git a/packages/forms/signals/test/node/api/validators/standard_schema.spec.ts b/packages/forms/signals/test/node/api/validators/standard_schema.spec.ts
@@ -180,4 +180,19 @@ describe('standard schema integration', () => {
     // Just expect schema to be defined, really just interested in testing the typing.
     expect(s).toBeDefined();
   });
+
+  it('should treat empty value as subject to the given standard schema', () => {
+    const model = signal('');
+    const f = form(
+      model,
+      (p) => {
+        validateStandardSchema(p, z.string().min(10));
+      },
+      {
+        injector: TestBed.inject(Injector),
+      },
+    );
+
+    expect(f().errors().length).toBe(1);
+  });
 });
diff --git a/packages/forms/signals/test/node/field_node.spec.ts b/packages/forms/signals/test/node/field_node.spec.ts
