docs: add signal form example + copy for matInput (#33779)

(cherry picked from commit cbc5e96)

Author: msmallest

src/components-examples/material/input/index.ts

@@ -1,6 +1,7 @@
 export {InputClearableExample} from './input-clearable/input-clearable-example';
 export {InputErrorStateMatcherExample} from './input-error-state-matcher/input-error-state-matcher-example';
 export {InputErrorsExample} from './input-errors/input-errors-example';
+export {InputErrorsSignalFormExample} from './input-errors-signal-form/input-errors-signal-form-example';
 export {InputFormExample} from './input-form/input-form-example';
 export {InputHintExample} from './input-hint/input-hint-example';
 export {InputOverviewExample} from './input-overview/input-overview-example';

src/components-examples/material/input/input-errors-signal-form/input-errors-signal-form-example.css

@@ -0,0 +1,9 @@
+.example-form {
+  min-width: 150px;
+  max-width: 500px;
+  width: 100%;
+}
+
+.example-full-width {
+  width: 100%;
+}

src/components-examples/material/input/input-errors-signal-form/input-errors-signal-form-example.html

@@ -0,0 +1,12 @@
+<form class="example-form">
+  <mat-form-field class="example-full-width">
+    <mat-label>Email</mat-label>
+    <input type="email" matInput [formField]="emailForm" placeholder="Ex. pat@example.com">
+    @if (emailForm().getError('email') && !emailForm().getError('required')) {
+      <mat-error>Please enter a valid email address</mat-error>
+    }
+    @if (emailForm().getError('required')) {
+      <mat-error>Email is <strong>required</strong></mat-error>
+    }
+  </mat-form-field>
+</form>

src/components-examples/material/input/input-errors-signal-form/input-errors-signal-form-example.ts

@@ -0,0 +1,21 @@
+import {Component, signal} from '@angular/core';
+import {MatInputModule} from '@angular/material/input';
+import {MatFormFieldModule} from '@angular/material/form-field';
+import {email, form, FormField, required} from '@angular/forms/signals';
+
+/**
+ * @title Input with error messages (signal form)
+ */
+@Component({
+  selector: 'input-errors-signal-form-example',
+  templateUrl: 'input-errors-signal-form-example.html',
+  styleUrl: 'input-errors-signal-form-example.css',
+  imports: [MatFormFieldModule, MatInputModule, FormField],
+})
+export class InputErrorsSignalFormExample {
+  private _emailModel = signal('');
+
+  protected emailForm = form(this._emailModel, schemaPath => {
+    (required(schemaPath), email(schemaPath));
+  });
+}

src/components-examples/material/input/input-errors/input-errors-example.ts

@@ -4,7 +4,7 @@ import {MatInputModule} from '@angular/material/input';
 import {MatFormFieldModule} from '@angular/material/form-field';
 
 /**
- * @title Input with error messages
+ * @title Input with error messages (reactive form)
  */
 @Component({
   selector: 'input-errors-example',

src/material/input/input.md

@@ -30,6 +30,10 @@ be used with `matNativeControl`:
 * url
 * week
 
+### Use with Angular Forms
+
+`matInput` is compatible with `@angular/forms` and supports `FormField`, `FormsModule`, and `ReactiveFormsModule`.
+
 ### Form field features
 
 There are a number of `<mat-form-field>` features that can be used with any `<input matNativeControl>` or
@@ -53,11 +57,20 @@ with your `matNativeControl`. By default, these error messages are shown when th
 the user has interacted with (touched) the element or the parent form has been submitted. If
 you wish to override this behavior (e.g. to show the error as soon as the invalid control is dirty
 or when a parent form group is invalid), you can use the `errorStateMatcher` property of the
-`matNativeControl`. The property takes an instance of an `ErrorStateMatcher` object. An `ErrorStateMatcher`
+`matNativeControl`. The property takes an instance of an `ErrorStateMatcher` object. 
+
+For reactive forms, an `ErrorStateMatcher`
 must implement a single method `isErrorState` which takes the `FormControl` for this `matNativeControl` as
 well as the parent form and returns a boolean indicating whether errors should be shown. (`true`
 indicating that they should be shown, and `false` indicating that they should not.)
 
+For signal forms, an `ErrorStateMatcher`
+must still implement the method `isErrorState` for backwards compatability with the reactive forms API, 
+but it can be fullfilled with `isErrorState() {return false}`. 
+Then the custom matcher can implement `isSignalErrorState`, which takes the `Field` for this 
+`matNativeControl` as well as the parent form and returns a boolean indicating whether errors 
+should be shown. (`true` indicating that they should be shown, and `false` indicating that they should not.)
+
 <!-- example(input-error-state-matcher) -->
 
 A global error state matcher can be specified by setting the `ErrorStateMatcher` provider. This