refactor(forms): make markAsTouched() touch all descendants by default

`markAsTouched()` now marks all descendants as touched. In general this
method is called when controls update the model. Most controls update
leaf nodes, in which case this change has no effect.

Marking all descendants allows triggering validation for subsections of
a form, independently from having to call `submit()` on the entire form.

`markAsTouched()` now accepts a `MarkAsTouchedOptions` parameter, which
includes a `self` property. This can be used mark only the receiving
field as touched: `node.markAsTouched({self: true})`.

Author: leonsenft

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

@@ -143,7 +143,7 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
     readonly invalid: Signal<boolean>;
     readonly keyInParent: Signal<TKey>;
     markAsDirty(): void;
-    markAsTouched(): void;
+    markAsTouched(options?: MarkAsTouchedOptions): void;
     readonly max?: Signal<number | undefined>;
     readonly maxLength?: Signal<number | undefined>;
     metadata<M>(key: MetadataKey<M, any, any>): M | undefined;
@@ -298,6 +298,11 @@ export type LogicFn<TValue, TReturn, TPathKind extends PathKind = PathKind.Root>
 // @public
 export type MapToErrorsFn<TValue, TResult, TPathKind extends PathKind = PathKind.Root> = (result: TResult, ctx: FieldContext<TValue, TPathKind>) => TreeValidationResult;
 
+// @public
+export interface MarkAsTouchedOptions {
+    self?: boolean;
+}
+
 // @public
 export const MAX: MetadataKey<Signal<number | undefined>, number | undefined, number | undefined>;
 

packages/forms/signals/compat/src/compat_field_adapter.ts

@@ -94,7 +94,7 @@ export class CompatFieldAdapter implements FieldAdapter {
     if (!options.control) {
       return this.basicAdapter.createValidationState(node);
     }
-    return new CompatValidationState(options);
+    return new CompatValidationState(node, options);
   }
 
   /**

packages/forms/signals/compat/src/compat_validation_state.ts

@@ -16,10 +16,10 @@ import {
 } from '../../src/compat/validation_errors';
 import {getControlStatusSignal} from './compat_field_node';
 import {CompatFieldNodeOptions} from './compat_structure';
+import {CompatFieldNode} from './compat_field_node';
 
 // Readonly signal containing an empty array, used for optimization.
 const EMPTY_ARRAY_SIGNAL = computed(() => []);
-const TRUE_SIGNAL = computed(() => true);
 
 /**
  * Compat version of a validation state that wraps a FormControl, and proxies it's validation state.
@@ -36,7 +36,10 @@ export class CompatValidationState implements ValidationState {
 
   readonly parseErrors: Signal<ValidationError.WithFormField[]> = computed(() => []);
 
-  constructor(options: CompatFieldNodeOptions) {
+  constructor(
+    private readonly node: CompatFieldNode,
+    options: CompatFieldNodeOptions,
+  ) {
     this.syncValid = getControlStatusSignal(options, (c: AbstractControl) => c.status === 'VALID');
     this.errors = getControlStatusSignal(options, extractNestedReactiveErrors);
     this.pending = getControlStatusSignal(options, (c) => c.pending);
@@ -57,7 +60,12 @@ export class CompatValidationState implements ValidationState {
   rawSyncTreeErrors = EMPTY_ARRAY_SIGNAL;
   syncErrors = EMPTY_ARRAY_SIGNAL;
   rawAsyncErrors = EMPTY_ARRAY_SIGNAL;
-  shouldSkipValidation = TRUE_SIGNAL;
+
+  // Compat fields can't have validation rules applied to them; however, there are other
+  // features that depend on this property, such as `markAsTouched()`.
+  readonly shouldSkipValidation = computed(
+    () => this.node.hidden() || this.node.disabled() || this.node.readonly(),
+  );
 
   /**
    * Computes status based on whether the field is valid/invalid/pending.

packages/forms/signals/src/api/structure.ts

@@ -408,24 +408,14 @@ export async function submit<TModel>(
     );
   }
 
-  const onInvalid = options?.onInvalid as FormSubmitOptions<unknown, unknown>['onInvalid'];
-  const ignoreValidators = options?.ignoreValidators ?? 'pending';
-
-  // Determine whether or not to run the action based on the current validity.
-  let shouldRunAction = true;
-  untracked(() => {
-    markAllAsTouched(node);
+  node.markAsTouched();
 
-    if (ignoreValidators === 'none') {
-      shouldRunAction = node.valid();
-    } else if (ignoreValidators === 'pending') {
-      shouldRunAction = !node.invalid();
-    }
-  });
+  const onInvalid = options?.onInvalid as FormSubmitOptions<unknown, unknown>['onInvalid'];
+  const shouldRun = shouldRunAction(node, options?.ignoreValidators);
 
   // Run the action (or alternatively the `onInvalid` callback)
   try {
-    if (shouldRunAction) {
+    if (shouldRun) {
       node.submitState.selfSubmitting.set(true);
       const errors = await untracked(() => action?.(field, detail));
       errors && setSubmissionErrors(node, errors);
@@ -452,17 +442,17 @@ export function schema<TValue>(fn: SchemaFn<TValue>): Schema<TValue> {
   return SchemaImpl.create(fn) as unknown as Schema<TValue>;
 }
 
-/** Marks a {@link node} and its descendants as touched. */
-function markAllAsTouched(node: FieldNode) {
-  // Don't mark hidden, disabled, or readonly fields as touched since they don't contribute to the
-  // form's validity. This also prevents errors from appearing immediately if they're later made
-  // interactive.
-  if (node.validationState.shouldSkipValidation()) {
-    return;
-  }
-  node.markAsTouched();
-  for (const child of node.structure.children()) {
-    markAllAsTouched(child);
+function shouldRunAction(
+  node: FieldNode,
+  ignoreValidators?: FormSubmitOptions<unknown, unknown>['ignoreValidators'],
+) {
+  switch (ignoreValidators) {
+    case 'all':
+      return true;
+    case 'none':
+      return untracked(node.valid);
+    default: // Ignore pending validators by default (or specified 'pending').
+      return !untracked(node.invalid);
   }
 }
 

packages/forms/signals/src/api/types.ts

@@ -57,6 +57,19 @@ export interface FormSubmitOptions<TRootModel, TSubmittedModel> {
   ignoreValidators?: 'pending' | 'none' | 'all';
 }
 
+/**
+ * Options for the `markAsTouched` method.
+ *
+ * @experimental 21.2.2
+ */
+export interface MarkAsTouchedOptions {
+  /**
+   * If `true`, only marks the current field as touched.
+   * If `false` or not provided, marks the field and all its descendants as touched.
+   */
+  self?: boolean;
+}
+
 /**
  * A type that represents either a single value of type `T` or a readonly array of `T`.
  * @template T The type of the value(s).
@@ -430,9 +443,11 @@ export interface FieldState<TValue, TKey extends string | number = string | numb
   markAsDirty(): void;
 
   /**
-   * Sets the touched status of the field to `true`.
+   * Sets the touched status of the field and its descendants to `true`.
+   *
+   * @param options Options for marking the field as touched.
    */
-  markAsTouched(): void;
+  markAsTouched(options?: MarkAsTouchedOptions): void;
 
   /**
    * Reads a metadata value from the field.

packages/forms/signals/src/field/node.ts

@@ -17,7 +17,13 @@ import {
   REQUIRED,
 } from '../api/rules/metadata';
 import type {ValidationError} from '../api/rules/validation/validation_errors';
-import type {DisabledReason, FieldContext, FieldState, FieldTree} from '../api/types';
+import type {
+  DisabledReason,
+  FieldContext,
+  FieldState,
+  FieldTree,
+  MarkAsTouchedOptions,
+} from '../api/types';
 import type {FormField} from '../directive/form_field_directive';
 import {DYNAMIC} from '../schema/logic';
 import {LogicNode} from '../schema/logic_node';
@@ -238,16 +244,26 @@ export class FieldNode implements FieldState<unknown> {
     return this.metadataState.has(key);
   }
 
-  /**
-   * Marks this specific field as touched.
-   */
-  markAsTouched(): void {
+  markAsTouched(options?: MarkAsTouchedOptions): void {
     untracked(() => {
-      this.nodeState.markAsTouched();
+      this.markAsTouchedInternal(options);
       this.flushSync();
     });
   }
 
+  markAsTouchedInternal(options?: MarkAsTouchedOptions): void {
+    if (this.validationState.shouldSkipValidation()) {
+      return;
+    }
+    this.nodeState.markAsTouched();
+    if (options?.self) {
+      return;
+    }
+    for (const child of this.structure.children()) {
+      child.markAsTouchedInternal();
+    }
+  }
+
   /**
    * Marks this specific field as dirty.
    */

packages/forms/signals/test/node/field_node.spec.ts

@@ -417,7 +417,7 @@ describe('FieldNode', () => {
       expect(f().touched()).toBe(true);
     });
 
-    it('does not propagate down', () => {
+    it('propagates down by default', () => {
       const f = form(
         signal({
           a: 1,
@@ -426,8 +426,28 @@ describe('FieldNode', () => {
         {injector: TestBed.inject(Injector)},
       );
 
+      expect(f().touched()).toBe(false);
       expect(f.a().touched()).toBe(false);
+      expect(f.b().touched()).toBe(false);
       f().markAsTouched();
+      expect(f().touched()).toBe(true);
+      expect(f.a().touched()).toBe(true);
+      expect(f.b().touched()).toBe(true);
+    });
+
+    it('does not propagate down when self is true', () => {
+      const f = form(
+        signal({
+          a: 1,
+          b: 2,
+        }),
+        {injector: TestBed.inject(Injector)},
+      );
+
+      expect(f().touched()).toBe(false);
+      expect(f.a().touched()).toBe(false);
+      f().markAsTouched({self: true});
+      expect(f().touched()).toBe(true);
       expect(f.a().touched()).toBe(false);
     });