docs(cdk/coercion): add guidance on Angular built-in input transforms

src/cdk/coercion/coercion.md

@@ -1,49 +1,68 @@
 Utility functions for coercing `@Input`s into specific types.
 
-### Example
+### Relation to Angular's built-in input transforms
+
+Angular provides built-in equivalents for the most common coercion functions:
+
+| CDK coercion               | Angular built-in     |
+|----------------------------|----------------------|
+| `coerceBooleanProperty`    | `booleanAttribute`   |
+| `coerceNumberProperty`     | `numberAttribute`    |
+
+For new code, prefer Angular's built-in transforms with signal inputs:
 
 ```ts
-import {Directive, ElementRef} from '@angular/core';
-import {
-  coerceBooleanProperty,
-  BooleanInput,
-  NumberInput,
-  coerceNumberProperty,
-  coerceElement,
-} from '@angular/cdk/coercion';
-
-@Directive({
+import {Component, input} from '@angular/core';
+import {booleanAttribute, numberAttribute} from '@angular/core';
+
+@Component({
   selector: 'my-button',
   host: {
-    '[disabled]': 'disabled',
+    '[disabled]': 'disabled()',
     '(click)': 'greet()',
   }
 })
 class MyButton {
-  // Using `coerceBooleanProperty` allows for the disabled value of a button to be set as
-  // `<my-button disabled></my-button>` instead of `<my-button [disabled]="true"></my-button>`.
-  // It also allows for a string to be passed like `<my-button disabled="true"></my-button>`.
-  @Input()
-  get disabled() { return this._disabled; }
-  set disabled(value: BooleanInput) {
-    this._disabled = coerceBooleanProperty(value);
+  disabled = input(false, {transform: booleanAttribute});
+  greetDelay = input(0, {transform: numberAttribute});
+
+  greet() {
+    setTimeout(() => alert('Hello!'), this.greetDelay());
   }
-  private _disabled = false;
-
-  // `coerceNumberProperty` turns any value coming in from the view into a number, allowing the
-  // consumer to use a shorthand string while storing the parsed number in memory. E.g. the consumer can write:
-  // `<my-button greetDelay="500"></my-button>` instead of `<my-button [greetDelay]="500"></my-button>`.
-  // The second parameter specifies a fallback value to be used if the value can't be
-  // parsed to a number.
-  @Input()
-  get greetDelay() { return this._greetDelay; }
-  set greetDelay(value: NumberInput) {
-    this._greetDelay = coerceNumberProperty(value, 0);
+}
+```
+
+The CDK coercion functions remain useful when you need custom coercion
+logic that goes beyond simple boolean or number conversion, such as
+`coerceElement` or `coerceArray`.
+
+### Example
+
+```ts
+import {Component, ElementRef, input} from '@angular/core';
+import {coerceElement} from '@angular/cdk/coercion';
+import {booleanAttribute, numberAttribute} from '@angular/core';
+
+@Component({
+  selector: 'my-button',
+  host: {
+    '[disabled]': 'disabled()',
+    '(click)': 'greet()',
   }
-  private _greetDelay = 0;
+})
+class MyButton {
+  // Angular's `booleanAttribute` allows the disabled value of a button to be set as
+  // `<my-button disabled></my-button>` instead of `<my-button [disabled]="true"></my-button>`.
+  disabled = input(false, {transform: booleanAttribute});
+
+  // Angular's `numberAttribute` turns any value coming in from the view into a number, allowing the
+  // consumer to use a shorthand string while storing the parsed number in memory.
+  // E.g. `<my-button greetDelay="500"></my-button>` instead of
+  // `<my-button [greetDelay]="500"></my-button>`.
+  greetDelay = input(0, {transform: numberAttribute});
 
   greet() {
-    setTimeout(() => alert('Hello!'), this.greetDelay);
+    setTimeout(() => alert('Hello!'), this.greetDelay());
   }
 
   // `coerceElement` allows you to accept either an `ElementRef`