docs(cdk): clarify textarea autosize examples

Keep the primary autosize example minimal and move the programmatic
resize scenario into a separate example so the extra logic is clearly
associated with style changes.

Author: hadt0786

src/cdk/text-field/text-field.md

@@ -5,14 +5,18 @@ The `text-field` package provides useful utilities for working with text input f
 
 The `cdkTextareaAutosize` directive can be applied to any `<textarea>` to make it automatically
 resize to fit its content. The minimum and maximum number of rows to expand to can be set via the
-`cdkAutosizeMinRows` and `cdkAutosizeMaxRows` properties respectively.
+`cdkAutosizeMinRows` and `cdkAutosizeMaxRows` properties respectively. No programmatic resize logic
+is required when the textarea only needs to react to content changes.
 
-The resize logic can be triggered programmatically by calling `resizeToFitContent`. This method
+<!-- example(text-field-autosize-textarea) -->
+
+The resize logic can also be triggered programmatically by calling `resizeToFitContent`. This method
 takes an optional boolean parameter `force` that defaults to `false`. Passing true will force the
-`<textarea>` to resize even if its text content has not changed, this can be useful if the styles
-affecting the `<textarea>` have changed.
+`<textarea>` to resize even if its text content has not changed, which is useful if styles affecting
+the `<textarea>` have changed. In the following example, changing the font size through the
+`mat-select` triggers a forced resize.
 
-<!-- example(text-field-autosize-textarea) -->
+<!-- example(text-field-autosize-textarea-programmatic) -->
 
 ### Monitoring the autofill state of an `<input>`
 

src/components-examples/cdk/text-field/index.ts

@@ -1,3 +1,4 @@
 export {TextFieldAutofillDirectiveExample} from './text-field-autofill-directive/text-field-autofill-directive-example';
 export {TextFieldAutofillMonitorExample} from './text-field-autofill-monitor/text-field-autofill-monitor-example';
+export {TextFieldAutosizeTextareaProgrammaticExample} from './text-field-autosize-textarea-programmatic/text-field-autosize-textarea-programmatic-example';
 export {TextFieldAutosizeTextareaExample} from './text-field-autosize-textarea/text-field-autosize-textarea-example';

…text-field-autosize-textarea-example.css …tosize-textarea-programmatic-example.csssrc/components-examples/cdk/text-field/text-field-autosize-textarea/text-field-autosize-textarea-example.css renamed to src/components-examples/cdk/text-field/text-field-autosize-textarea-programmatic/text-field-autosize-textarea-programmatic-example.css src/components-examples/cdk/text-field/text-field-autosize-textarea/text-field-autosize-textarea-example.css renamed to src/components-examples/cdk/text-field/text-field-autosize-textarea-programmatic/text-field-autosize-textarea-programmatic-example.css

@@ -0,0 +1,20 @@
+<mat-form-field>
+  <mat-label>Font size</mat-label>
+  <mat-select #fontSize value="16px" (selectionChange)="triggerResize()">
+    <mat-option value="10px">10px</mat-option>
+    <mat-option value="12px">12px</mat-option>
+    <mat-option value="14px">14px</mat-option>
+    <mat-option value="16px">16px</mat-option>
+    <mat-option value="18px">18px</mat-option>
+    <mat-option value="20px">20px</mat-option>
+  </mat-select>
+</mat-form-field>
+
+<mat-form-field [style.fontSize]="fontSize.value">
+  <mat-label>Autosize textarea</mat-label>
+  <textarea matInput
+            cdkTextareaAutosize
+            #autosize="cdkTextareaAutosize"
+            cdkAutosizeMinRows="1"
+            cdkAutosizeMaxRows="5"></textarea>
+</mat-form-field>

src/components-examples/cdk/text-field/text-field-autosize-textarea-programmatic/text-field-autosize-textarea-programmatic-example.html

@@ -0,0 +1,30 @@
+import {CdkTextareaAutosize, TextFieldModule} from '@angular/cdk/text-field';
+import {afterNextRender, Component, inject, Injector, ViewChild} from '@angular/core';
+import {MatFormFieldModule} from '@angular/material/form-field';
+import {MatInputModule} from '@angular/material/input';
+import {MatSelectModule} from '@angular/material/select';
+
+/** @title Programmatically resizing an autosize textarea */
+@Component({
+  selector: 'text-field-autosize-textarea-programmatic-example',
+  templateUrl: './text-field-autosize-textarea-programmatic-example.html',
+  styleUrl: './text-field-autosize-textarea-programmatic-example.css',
+  imports: [MatFormFieldModule, MatSelectModule, MatInputModule, TextFieldModule],
+})
+export class TextFieldAutosizeTextareaProgrammaticExample {
+  private _injector = inject(Injector);
+
+  @ViewChild('autosize') autosize!: CdkTextareaAutosize;
+
+  triggerResize() {
+    // Wait for content to render, then trigger textarea resize.
+    afterNextRender(
+      () => {
+        this.autosize.resizeToFitContent(true);
+      },
+      {
+        injector: this._injector,
+      },
+    );
+  }
+}

src/components-examples/cdk/text-field/text-field-autosize-textarea-programmatic/text-field-autosize-textarea-programmatic-example.ts

@@ -1,20 +1,7 @@
 <mat-form-field>
-  <mat-label>Font size</mat-label>
-  <mat-select #fontSize value="16px" (selectionChange)="triggerResize()">
-    <mat-option value="10px">10px</mat-option>
-    <mat-option value="12px">12px</mat-option>
-    <mat-option value="14px">14px</mat-option>
-    <mat-option value="16px">16px</mat-option>
-    <mat-option value="18px">18px</mat-option>
-    <mat-option value="20px">20px</mat-option>
-  </mat-select>
-</mat-form-field>
-
-<mat-form-field [style.fontSize]="fontSize.value">
   <mat-label>Autosize textarea</mat-label>
   <textarea matInput
             cdkTextareaAutosize
-            #autosize="cdkTextareaAutosize"
             cdkAutosizeMinRows="1"
             cdkAutosizeMaxRows="5"></textarea>
 </mat-form-field>

src/components-examples/cdk/text-field/text-field-autosize-textarea/text-field-autosize-textarea-example.html

@@ -1,30 +1,12 @@
-import {CdkTextareaAutosize, TextFieldModule} from '@angular/cdk/text-field';
-import {afterNextRender, Component, inject, Injector, ViewChild} from '@angular/core';
-import {MatInputModule} from '@angular/material/input';
-import {MatSelectModule} from '@angular/material/select';
+import {TextFieldModule} from '@angular/cdk/text-field';
+import {Component} from '@angular/core';
 import {MatFormFieldModule} from '@angular/material/form-field';
+import {MatInputModule} from '@angular/material/input';
 
 /** @title Auto-resizing textarea */
 @Component({
   selector: 'text-field-autosize-textarea-example',
   templateUrl: './text-field-autosize-textarea-example.html',
-  styleUrl: './text-field-autosize-textarea-example.css',
-  imports: [MatFormFieldModule, MatSelectModule, MatInputModule, TextFieldModule],
+  imports: [MatFormFieldModule, MatInputModule, TextFieldModule],
 })
-export class TextFieldAutosizeTextareaExample {
-  private _injector = inject(Injector);
-
-  @ViewChild('autosize') autosize!: CdkTextareaAutosize;
-
-  triggerResize() {
-    // Wait for content to render, then trigger textarea resize.
-    afterNextRender(
-      () => {
-        this.autosize.resizeToFitContent(true);
-      },
-      {
-        injector: this._injector,
-      },
-    );
-  }
-}
+export class TextFieldAutosizeTextareaExample {}