fix(forms): split the touched model into an input and touch output

leonsenft · thePunderWoman · commit fb166772d2e9 · 2026-02-19T09:07:03.000-08:00
The `touched` property was never meant to support two-way binding; a
control should not be able to dictate that a field is no longer touched.

* The `touched` input represents the touched state of the field.
* The `touch` output allows a control implementation to indicate when
  the bound field is touched.

Note the distinction is that the `touch` output indicates _when_ the
field is touched, and not _whether_ the field is touched.
diff --git a/goldens/public-api/forms/signals/index.api.md b/goldens/public-api/forms/signals/index.api.md
@@ -258,7 +258,8 @@ export interface FormUiControl {
     readonly pending?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
     readonly readonly?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
     readonly required?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
-    readonly touched?: ModelSignal<boolean> | InputSignal<boolean> | InputSignalWithTransform<boolean, unknown> | OutputRef<boolean>;
+    readonly touch?: OutputRef<void>;
+    readonly touched?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
 }
 
 // @public
diff --git a/packages/forms/signals/src/api/control.ts b/packages/forms/signals/src/api/control.ts
@@ -61,12 +61,7 @@ export interface FormUiControl {
    * An input to receive the touched status for the field. If implemented, the `Field` directive
    * will automatically bind the touched status from the bound field to this input.
    */
-  readonly touched?:
-    | ModelSignal<boolean>
-    | InputSignal<boolean>
-    | InputSignalWithTransform<boolean, unknown>
-    | OutputRef<boolean>;
-
+  readonly touched?: InputSignal<boolean> | InputSignalWithTransform<boolean, unknown>;
   /**
    * An input to receive the dirty status for the field. If implemented, the `Field` directive
    * will automatically bind the dirty status from the bound field to this input.
@@ -117,6 +112,10 @@ export interface FormUiControl {
   readonly pattern?:
     | InputSignal<readonly RegExp[]>
     | InputSignalWithTransform<readonly RegExp[], unknown>;
+  /**
+   * An output to emit when the control is touched.
+   */
+  readonly touch?: OutputRef<void>;
   /**
    * Focuses the UI control.
    *
diff --git a/packages/forms/signals/src/directive/control_custom.ts b/packages/forms/signals/src/directive/control_custom.ts
@@ -23,7 +23,7 @@ export function customControlCreate(
   parent: FormField<unknown>,
 ): () => void {
   host.listenToCustomControlModel((value) => parent.state().controlValue.set(value));
-  host.listenToCustomControlOutput('touchedChange', () => parent.state().markAsTouched());
+  host.listenToCustomControlOutput('touch', () => parent.state().markAsTouched());
 
   parent.registerAsBinding(host.customControl as FormUiControl);
 
diff --git a/packages/forms/signals/test/web/form_field_directive.spec.ts b/packages/forms/signals/test/web/form_field_directive.spec.ts
@@ -4099,11 +4099,12 @@ describe('field directive', () => {
       template: '<input #i [value]="value()" (input)="value.set(i.value)" />',
     })
     class CustomInput implements FormValueControl<string> {
-      value = model('');
-      touched = model(false);
+      readonly value = model('');
+      readonly touched = input(false);
+      readonly touch = output<void>();
 
       touchIt() {
-        this.touched.set(true);
+        this.touch.emit();
       }
     }
 

Original file line number	Diff line number	Diff line change
`@@ -258,7 +258,8 @@ export interface FormUiControl {`
`258`	`258`	`readonly pending?: InputSignal<boolean> \| InputSignalWithTransform<boolean, unknown>;`
`259`	`259`	`readonly readonly?: InputSignal<boolean> \| InputSignalWithTransform<boolean, unknown>;`
`260`	`260`	`readonly required?: InputSignal<boolean> \| InputSignalWithTransform<boolean, unknown>;`
`261`		`- readonly touched?: ModelSignal<boolean> \| InputSignal<boolean> \| InputSignalWithTransform<boolean, unknown> \| OutputRef<boolean>;`
	`261`	`+ readonly touch?: OutputRef<void>;`
	`262`	`+ readonly touched?: InputSignal<boolean> \| InputSignalWithTransform<boolean, unknown>;`
`262`	`263`	`}`
`263`	`264`
`264`	`265`	`// @public`
Original file line number	Diff line number	Diff line change
`@@ -4099,11 +4099,12 @@ describe('field directive', () => {`
`4099`	`4099`	`template: '<input #i [value]="value()" (input)="value.set(i.value)" />',`
`4100`	`4100`	`})`
`4101`	`4101`	`class CustomInput implements FormValueControl<string> {`
`4102`		`- value = model('');`
`4103`		`- touched = model(false);`
	`4102`	`+ readonly value = model('');`
	`4103`	`+ readonly touched = input(false);`
	`4104`	`+ readonly touch = output<void>();`
`4104`	`4105`
`4105`	`4106`	`touchIt() {`
`4106`		`- this.touched.set(true);`
	`4107`	`+ this.touch.emit();`
`4107`	`4108`	`}`
`4108`	`4109`	`}`
`4109`	`4110`