refactor(forms): convert FieldNode.controlValue to a WritableSignal

Remove `setControlValue()` from `Field` and convert `controlValue` to a
`WritableSignal` whose setter implements the debounced syncing behavior
of `setControlValue()`.

Also make sure that all signal reads during a sync are untracked.

Author: leonsenft

packages/core/src/render3/instructions/control.ts

@@ -346,7 +346,7 @@ function initializeCustomControl(
     directiveIndex,
     outputName,
     outputName,
-    wrapListener(tNode, lView, (value: unknown) => fieldDirective.state().setControlValue(value)),
+    wrapListener(tNode, lView, (value: unknown) => fieldDirective.state().controlValue.set(value)),
   );
 
   const directiveDef = tView.data[directiveIndex] as DirectiveDef<unknown>;
@@ -372,7 +372,7 @@ function initializeCustomControl(
 function initializeInteropControl(fieldDirective: ɵFormFieldDirective<unknown>): void {
   const interopControl = fieldDirective.ɵinteropControl!;
   interopControl.registerOnChange((value: unknown) =>
-    fieldDirective.state().setControlValue(value),
+    fieldDirective.state().controlValue.set(value),
   );
   interopControl.registerOnTouched(() => fieldDirective.state().markAsTouched());
 }
@@ -421,7 +421,7 @@ function initializeNativeControl(
 
   const inputListener = () => {
     const state = fieldDirective.state();
-    state.setControlValue(getNativeControlValue(element, state.value));
+    state.controlValue.set(getNativeControlValue(element, state.value));
   };
   listenToDomEvent(
     tNode,

packages/core/src/render3/interfaces/control.ts

@@ -190,7 +190,7 @@ export interface ɵFieldState<T> {
    * buffer debounced updates from the control to the field. This will also not take into account
    * the {@link controlValue} of children.
    */
-  readonly controlValue: Signal<T>;
+  readonly controlValue: WritableSignal<T>;
 
   /**
    * Sets the dirty status of the field to `true`.
@@ -201,9 +201,4 @@ export interface ɵFieldState<T> {
    * Sets the touched status of the field to `true`.
    */
   markAsTouched(): void;
-
-  /**
-   * Sets {@link controlValue} immediately and triggers synchronization to {@link value}.
-   */
-  setControlValue(value: T): void;
 }

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

@@ -7,6 +7,16 @@
  */
 
 import {computed, linkedSignal, type Signal, untracked, type WritableSignal} from '@angular/core';
+import {
+  createLinkedSignal,
+  LinkedSignalGetter,
+  LinkedSignalNode,
+  linkedSignalSetFn,
+  linkedSignalUpdateFn,
+  SIGNAL,
+  SignalGetter,
+  SignalNode,
+} from '@angular/core/primitives/signals';
 import type {FormField} from '../api/form_field_directive';
 import {
   MAX,
@@ -58,6 +68,7 @@ export class FieldNode implements FieldState<unknown> {
   readonly nodeState: FieldNodeState;
   readonly submitState: FieldSubmitState;
   readonly fieldAdapter: FieldAdapter;
+  readonly controlValue: WritableSignal<unknown>;
 
   private _context: FieldContext<unknown> | undefined = undefined;
   get context(): FieldContext<unknown> {
@@ -78,6 +89,7 @@ export class FieldNode implements FieldState<unknown> {
     this.nodeState = this.fieldAdapter.createNodeState(this, options);
     this.metadataState = new FieldMetadataState(this);
     this.submitState = new FieldSubmitState(this);
+    this.controlValue = this.controlValueSignal();
   }
 
   focusBoundControl(options?: FocusOptions): void {
@@ -136,11 +148,6 @@ export class FieldNode implements FieldState<unknown> {
     return this.structure.value;
   }
 
-  private _controlValue = linkedSignal(() => this.value());
-  get controlValue(): Signal<unknown> {
-    return this._controlValue.asReadonly();
-  }
-
   get keyInParent(): Signal<string | number> {
     return this.structure.keyInParent;
   }
@@ -279,15 +286,26 @@ export class FieldNode implements FieldState<unknown> {
   }
 
   /**
-   * Sets the control value of the field. This value may be debounced before it is synchronized with
-   * the field's {@link value} signal, depending on the debounce configuration.
+   * Creates a linked signal that initialiates a {@link debounceSync} when set.
    */
-  setControlValue(newValue: unknown): void {
-    untracked(() => {
-      this._controlValue.set(newValue);
+  private controlValueSignal(): WritableSignal<unknown> {
+    const signal = createLinkedSignal(this.value, identityFn);
+    const node = signal[SIGNAL] as LinkedSignalNode<unknown, unknown>;
+    const writableSignal = signal as LinkedSignalGetter<unknown, unknown> & WritableSignal<unknown>;
+
+    writableSignal.set = (newValue) => {
+      linkedSignalSetFn(node, newValue);
       this.markAsDirty();
       this.debounceSync();
-    });
+    };
+    writableSignal.update = (updateFn) => {
+      linkedSignalUpdateFn(node, updateFn);
+      this.markAsDirty();
+      this.debounceSync();
+    };
+    writableSignal.asReadonly = signalAsReadonlyFn.bind(signal);
+
+    return writableSignal;
   }
 
   /**
@@ -312,14 +330,16 @@ export class FieldNode implements FieldState<unknown> {
    * Initiates a debounced {@link sync}.
    *
    * If a debouncer is configured, the synchronization will occur after the debouncer resolves. If
-   * no debouncer is configured, the synchronization happens immediately. If {@link setControlValue}
-   * is called again while a debounce is pending, the previous debounce operation is aborted in
-   * favor of the new one.
+   * no debouncer is configured, the synchronization happens immediately. If {@link controlValue} is
+   * updated again while a debounce is pending, the previous debounce operation is aborted in favor
+   * of the new one.
    */
   private async debounceSync() {
-    this.pendingSync()?.abort();
+    const debouncer = untracked(() => {
+      this.pendingSync()?.abort();
+      return this.nodeState.debouncer();
+    });
 
-    const debouncer = this.nodeState.debouncer();
     if (debouncer) {
       const controller = new AbortController();
       const promise = debouncer(controller.signal);
@@ -415,3 +435,18 @@ function firstInDom<T extends FormField<unknown>>(
   const position = a.element.compareDocumentPosition(b.element);
   return position & Node.DOCUMENT_POSITION_PRECEDING ? b : a;
 }
+
+function identityFn<T>(v: T): T {
+  return v;
+}
+
+// TODO: Can we export/share this from @angular/core?
+function signalAsReadonlyFn<T>(this: SignalGetter<T>): Signal<T> {
+  const node = this[SIGNAL] as SignalNode<T> & {readonlyFn?: Signal<T>};
+  if (node.readonlyFn === undefined) {
+    const readonlyFn = () => this();
+    (readonlyFn as any)[SIGNAL] = node;
+    node.readonlyFn = readonlyFn as Signal<T>;
+  }
+  return node.readonlyFn;
+}

packages/forms/signals/test/node/api/debounce.spec.ts

@@ -23,7 +23,7 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('1600 Amphitheatre Pkwy');
     });
@@ -39,7 +39,7 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('');
 
@@ -58,7 +58,7 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('');
 
@@ -79,7 +79,7 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('1600 Amphitheatre Pkwy');
     });
@@ -95,7 +95,7 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('');
 
@@ -115,7 +115,7 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('');
 
@@ -142,10 +142,10 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('');
 
-      street.setControlValue('2000 N Shoreline Blvd');
+      street.controlValue.set('2000 N Shoreline Blvd');
       expect(street.value()).toBe('');
 
       first.resolve();
@@ -172,7 +172,7 @@ describe('debounce', () => {
       const street = addressForm.street();
 
       // Set `controlValue` which will trigger a debounce update.
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('');
 
@@ -204,10 +204,10 @@ describe('debounce', () => {
         );
         const street = addressForm.street();
 
-        street.setControlValue('1600 Amphitheatre Pkwy');
+        street.controlValue.set('1600 Amphitheatre Pkwy');
         expect(abortSpy).not.toHaveBeenCalled();
 
-        street.setControlValue('2000 N Shoreline Blvd');
+        street.controlValue.set('2000 N Shoreline Blvd');
         expect(abortSpy).toHaveBeenCalledTimes(1);
 
         resolve();
@@ -230,7 +230,7 @@ describe('debounce', () => {
         );
         const street = addressForm.street();
 
-        street.setControlValue('1600 Amphitheatre Pkwy');
+        street.controlValue.set('1600 Amphitheatre Pkwy');
         expect(abortSpy).not.toHaveBeenCalled();
 
         street.markAsTouched();
@@ -255,7 +255,7 @@ describe('debounce', () => {
         );
         const street = addressForm.street();
 
-        street.setControlValue('1600 Amphitheatre Pkwy');
+        street.controlValue.set('1600 Amphitheatre Pkwy');
         expect(addListenerSpy).toHaveBeenCalledOnceWith('abort', jasmine.any(Function), {
           once: true,
         });
@@ -280,7 +280,7 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('');
 
@@ -300,7 +300,7 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('1600 Amphitheatre Pkwy');
     });
@@ -316,7 +316,7 @@ describe('debounce', () => {
         options(),
       );
 
-      addressForm().setControlValue({street: '1600 Amphitheatre Pkwy'});
+      addressForm().controlValue.set({street: '1600 Amphitheatre Pkwy'});
       expect(addressForm().controlValue()).toEqual({street: '1600 Amphitheatre Pkwy'});
       expect(addressForm().value()).toEqual({street: ''});
 
@@ -334,10 +334,10 @@ describe('debounce', () => {
         options(),
       );
 
-      addressForm.street().setControlValue('1600 Amphitheatre Pkwy');
+      addressForm.street().controlValue.set('1600 Amphitheatre Pkwy');
       expect(addressForm().value()).toEqual({street: '', city: ''});
 
-      addressForm.city().setControlValue('Mountain View');
+      addressForm.city().controlValue.set('Mountain View');
       expect(addressForm().value()).toEqual({street: '', city: 'Mountain View'});
 
       await timeout(0);
@@ -361,7 +361,7 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('1600 Amphitheatre Pkwy');
     });
@@ -384,7 +384,7 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('');
 
@@ -417,12 +417,12 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('1600 Amphitheatre Pkwy');
 
       debounced.set(true);
-      street.setControlValue('2000 N Shoreline Blvd');
+      street.controlValue.set('2000 N Shoreline Blvd');
       expect(street.controlValue()).toBe('2000 N Shoreline Blvd');
       expect(street.value()).toBe('1600 Amphitheatre Pkwy');
 
@@ -448,15 +448,15 @@ describe('debounce', () => {
       );
       const street = addressForm.street();
 
-      street.setControlValue('1600 Amphitheatre Pkwy');
+      street.controlValue.set('1600 Amphitheatre Pkwy');
       expect(street.controlValue()).toBe('1600 Amphitheatre Pkwy');
       expect(street.value()).toBe('');
 
       await timeout(0);
       expect(street.value()).toBe('1600 Amphitheatre Pkwy');
 
       debounced.set(false);
-      street.setControlValue('2000 N Shoreline Blvd');
+      street.controlValue.set('2000 N Shoreline Blvd');
       expect(street.value()).toBe('2000 N Shoreline Blvd');
     });
   });

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

@@ -616,7 +616,7 @@ describe('FieldNode', () => {
       // Same object identity because there was no change to flush to the name.
       expect(myForm().value()).toBe(product);
 
-      myForm.name().setControlValue('b');
+      myForm.name().controlValue.set('b');
       // Same object identity because the name change is still pending.
       expect(myForm().value()).toBe(product);