refactor(forms): extract common parser logic (#66917)

mmalerba · mattrbeck · commit a6a034799872 · 2026-02-13T12:11:06.000-08:00
native controls and custom controls (via transformedValue) use similar parsing logic but it needs to be hooked up differently. This commit extracts the common bits into a shared piece. PR Close #66917
diff --git a/goldens/public-api/forms/signals/index.api.md b/goldens/public-api/forms/signals/index.api.md
@@ -433,6 +433,12 @@ export type NgValidationError = RequiredValidationError | MinValidationError | M
 // @public
 export type OneOrMany<T> = T | readonly T[];
 
+// @public
+export interface ParseResult<TValue> {
+    readonly errors?: readonly ValidationError.WithoutFieldTree[];
+    readonly value?: TValue;
+}
+
 // @public
 export type PathKind = PathKind.Root | PathKind.Child | PathKind.Item;
 
@@ -595,10 +601,7 @@ export function transformedValue<TValue, TRaw>(value: ModelSignal<TValue>, optio
 // @public
 export interface TransformedValueOptions<TValue, TRaw> {
     format: (value: TValue) => TRaw;
-    parse: (rawValue: TRaw) => {
-        value?: TValue;
-        errors?: readonly ValidationError.WithoutFieldTree[];
-    };
+    parse: (rawValue: TRaw) => ParseResult<TValue>;
 }
 
 // @public
diff --git a/packages/forms/signals/src/api/transformed_value.ts b/packages/forms/signals/src/api/transformed_value.ts
@@ -14,8 +14,23 @@ import {
   type WritableSignal,
 } from '@angular/core';
 import {FORM_FIELD_PARSE_ERRORS} from '../directive/parse_errors';
+import {createParser} from '../util/parser';
 import type {ValidationError} from './rules';
 
+/**
+ * Result of parsing a raw value into a model value.
+ */
+export interface ParseResult<TValue> {
+  /**
+   * The parsed value, if parsing was successful.
+   */
+  readonly value?: TValue;
+  /**
+   * Errors encountered during parsing, if any.
+   */
+  readonly errors?: readonly ValidationError.WithoutFieldTree[];
+}
+
 /**
  * Options for `transformedValue`.
  *
@@ -29,7 +44,7 @@ export interface TransformedValueOptions<TValue, TRaw> {
    *   - `value`: The parsed model value. If `undefined`, the model will not be updated.
    *   - `errors`: Any parse errors encountered. If `undefined`, no errors are reported.
    */
-  parse: (rawValue: TRaw) => {value?: TValue; errors?: readonly ValidationError.WithoutFieldTree[]};
+  parse: (rawValue: TRaw) => ParseResult<TValue>;
 
   /**
    * Format the model value into the raw value.
@@ -92,38 +107,30 @@ export function transformedValue<TValue, TRaw>(
   options: TransformedValueOptions<TValue, TRaw>,
 ): TransformedValueSignal<TRaw> {
   const {parse, format} = options;
+  const parser = createParser(value, value.set, parse);
 
-  const parseErrors = linkedSignal({
-    source: value,
-    computation: () => [] as readonly ValidationError.WithoutFieldTree[],
-  });
-  const rawValue = linkedSignal(() => format(value()));
-
+  // Wire up the parse errors from the parser to the form field.
   const formFieldParseErrors = inject(FORM_FIELD_PARSE_ERRORS, {self: true, optional: true});
   if (formFieldParseErrors) {
-    formFieldParseErrors.set(parseErrors);
+    formFieldParseErrors.set(parser.errors);
   }
 
   // Create the result signal with overridden set/update and a `parseErrors` property.
+  const rawValue = linkedSignal(() => format(value()));
   const result = rawValue as WritableSignal<TRaw> & {
     parseErrors: Signal<readonly ValidationError.WithoutFieldTree[]>;
   };
+  result.parseErrors = parser.errors;
   const originalSet = result.set.bind(result);
 
+  // Notify the parser when `set` or `update` is called on the raw value
   result.set = (newRawValue: TRaw) => {
-    const result = parse(newRawValue);
-    parseErrors.set(result.errors ?? []);
-    if (result.value !== undefined) {
-      value.set(result.value);
-    }
+    parser.setRawValue(newRawValue);
     originalSet(newRawValue);
   };
-
   result.update = (updateFn: (value: TRaw) => TRaw) => {
     result.set(updateFn(rawValue()));
   };
 
-  result.parseErrors = parseErrors.asReadonly();
-
   return result;
 }
diff --git a/packages/forms/signals/src/directive/control_native.ts b/packages/forms/signals/src/directive/control_native.ts
@@ -6,12 +6,12 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 import {
-  linkedSignal,
   type ɵControlDirectiveHost as ControlDirectiveHost,
   type Signal,
   type WritableSignal,
 } from '@angular/core';
 import type {ValidationError} from '../api/rules';
+import {createParser} from '../util/parser';
 import {
   bindingUpdated,
   CONTROL_BINDING_NAMES,
@@ -32,22 +32,21 @@ export function nativeControlCreate(
 ): () => void {
   let updateMode = false;
   const input = parent.nativeFormElement;
-  // TODO: (perf) ok to always create this?
-  const parseErrors = linkedSignal({
-    source: () => parent.state().value(),
-    computation: () => [] as readonly ValidationError.WithoutFieldTree[],
-  });
-  parseErrorsSource.set(parseErrors);
 
-  host.listenToDom('input', () => {
-    const state = parent.state();
-    const {value, errors} = getNativeControlValue(input, state.value);
-    parseErrors.set(errors ?? []);
-    if (value !== undefined) {
-      state.controlValue.set(value);
-    }
-  });
+  // TODO: (perf) ok to always create this?
+  const parser = createParser(
+    // Read from the model value
+    () => parent.state().value(),
+    // Write to the buffered "control value"
+    (rawValue: unknown) => parent.state().controlValue.set(rawValue),
+    // Our parse function doesn't care about the raw value that gets passed in,
+    // It just reads the newly parsed value directly off the input element.
+    () => getNativeControlValue(input, parent.state().value),
+  );
 
+  parseErrorsSource.set(parser.errors);
+  // Pass undefined as the raw value since the parse function doesn't care about it.
+  host.listenToDom('input', () => parser.setRawValue(undefined));
   host.listenToDom('blur', () => parent.state().markAsTouched());
 
   parent.registerAsBinding();
diff --git a/packages/forms/signals/src/directive/native.ts b/packages/forms/signals/src/directive/native.ts
@@ -8,6 +8,7 @@
 
 import {type Renderer2, untracked} from '@angular/core';
 import {NativeInputParseError, WithoutFieldTree} from '../api/rules';
+import type {ParseResult} from '../api/transformed_value';
 
 /**
  * Supported native control element types.
@@ -49,11 +50,6 @@ export function isTextualFormElement(element: HTMLElement): boolean {
   return element.tagName === 'INPUT' || element.tagName === 'TEXTAREA';
 }
 
-export interface NativeControlValue {
-  value?: unknown;
-  errors?: readonly WithoutFieldTree<NativeInputParseError>[];
-}
-
 /**
  * Returns the value from a native control element.
  *
@@ -69,7 +65,7 @@ export interface NativeControlValue {
 export function getNativeControlValue(
   element: NativeFormControl,
   currentValue: () => unknown,
-): NativeControlValue {
+): ParseResult<unknown> {
   let modelValue: unknown;
 
   if (element.validity.badInput) {
diff --git a/packages/forms/signals/src/util/parser.ts b/packages/forms/signals/src/util/parser.ts
@@ -0,0 +1,54 @@
+/**
+ * @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.dev/license
+ */
+
+import {type Signal, linkedSignal} from '@angular/core';
+import type {ValidationError} from '../api/rules';
+import type {ParseResult} from '../api/transformed_value';
+
+/**
+ * An object that handles parsing raw UI values into model values.
+ */
+export interface Parser<TRaw> {
+  /**
+   * Errors encountered during the last parse attempt.
+   */
+  errors: Signal<readonly ValidationError.WithoutFieldTree[]>;
+  /**
+   * Parses the given raw value and updates the underlying model value if successful.
+   */
+  setRawValue: (rawValue: TRaw) => void;
+}
+
+/**
+ * Creates a {@link Parser} that synchronizes a raw value with an underlying model value.
+ *
+ * @param getValue Function to get the current model value.
+ * @param setValue Function to update the model value.
+ * @param parse Function to parse the raw value into a {@link ParseResult}.
+ * @returns A {@link Parser} instance.
+ */
+export function createParser<TValue, TRaw>(
+  getValue: () => TValue,
+  setValue: (value: TValue) => void,
+  parse: (raw: TRaw) => ParseResult<TValue>,
+): Parser<TRaw> {
+  const errors = linkedSignal({
+    source: getValue,
+    computation: () => [] as readonly ValidationError.WithoutFieldTree[],
+  });
+
+  const setRawValue = (rawValue: TRaw) => {
+    const result = parse(rawValue);
+    errors.set(result.errors ?? []);
+    if (result.value !== undefined) {
+      setValue(result.value);
+    }
+  };
+
+  return {errors: errors.asReadonly(), setRawValue};
+}
