@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/textarea.examples.md

@@ -0,0 +1,612 @@
+<!-- index: ./index.md -->
+# textarea
+
+`data-ui="textarea"` · Multi-line text input.
+
+## Examples
+
+### Playground
+
+One control with every axis on it, driven by the controls below the canvas. Turn autoSize on and type: the box grows to the ceiling and then scrolls.
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Observações</label>
+  <textarea slTextarea [rows]="3" placeholder="Descreva o que aconteceu"></textarea>
+  <span slFieldDescription>Aparece no histórico do chamado.</span>
+</div>
+```
+
+### The step the control sits at
+
+The block padding is derived rather than chosen — half of what is left when one line box comes out of the control height — so a one-row textarea is exactly as tall as an input of the same step, at every density.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextarea } from '@slotted/angular/textarea';
+
+@Component({
+  selector: 'app-textarea-sizes',
+  imports: [SlField, SlFieldLabel, SlStack, SlTextarea],
+  template: `
+    <div slStack [gap]="5">
+      <div slField size="sm">
+        <label slFieldLabel>Line item note</label>
+        <textarea
+          slTextarea
+          [rows]="2"
+          defaultValue="Pack the glass bottles separately."
+        ></textarea>
+      </div>
+      <div slField size="md">
+        <label slFieldLabel>Order note</label>
+        <textarea
+          slTextarea
+          [rows]="2"
+          defaultValue="The customer asked for delivery before noon on Friday."
+        ></textarea>
+      </div>
+      <div slField size="lg">
+        <label slFieldLabel>Message to the supplier</label>
+        <textarea
+          slTextarea
+          [rows]="2"
+          defaultValue="Please confirm the revised quantities by Wednesday."
+        ></textarea>
+      </div>
+    </div>
+  `,
+})
+export class TextareaSizes {}
+```
+
+### How much frame the control shows
+
+The same three frames the single-line control paints, against the same tokens: one that takes the ground it is placed on, one that sinks into the page, and one that shows nothing until it is used.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextarea } from '@slotted/angular/textarea';
+
+@Component({
+  selector: 'app-textarea-variants',
+  imports: [SlField, SlFieldLabel, SlStack, SlTextarea],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Return reason</label>
+        <textarea
+          slTextarea
+          variant="outline"
+          [rows]="2"
+          defaultValue="Two jars arrived with broken seals."
+        ></textarea>
+      </div>
+      <div slField>
+        <label slFieldLabel>Warehouse note</label>
+        <textarea
+          slTextarea
+          variant="subtle"
+          [rows]="2"
+          defaultValue="Restock on shelf B4 after inspection."
+        ></textarea>
+      </div>
+      <div slField>
+        <label slFieldLabel>Picker comment</label>
+        <textarea
+          slTextarea
+          variant="plain"
+          [rows]="2"
+          defaultValue="Counted twice, 46 units on hand."
+        ></textarea>
+      </div>
+    </div>
+  `,
+})
+export class TextareaVariants {}
+```
+
+### Growing with the content
+
+Nothing is measured on the main thread: CSS field-sizing grows the box, rows is the floor and maxRows the ceiling. Type past four lines in the first example and the control scrolls rather than pushing the page.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlTextarea } from '@slotted/angular/textarea';
+
+@Component({
+  selector: 'app-textarea-auto-size',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextarea],
+  template: `
+    <div slField>
+      <label slFieldLabel>Picking note</label>
+      <textarea
+        slTextarea
+        autoSize
+        [rows]="2"
+        [maxRows]="6"
+        defaultValue="Use the reinforced boxes for the olive oil."
+      ></textarea>
+      <span slFieldDescription>Shown to the picker on the warehouse screen.</span>
+    </div>
+  `,
+})
+export class TextareaAutoSize {}
+```
+
+### The handle in the corner
+
+block is the default rather than the platform’s both, because a control wider than its field breaks the field’s own grid. The handle is withdrawn entirely while autoSize is on, since the two would disagree on the next keystroke.
+
+Excerpt — not a complete module
+
+```html
+<textarea slTextarea resize="none"></textarea>
+<textarea slTextarea resize="both"></textarea>
+
+<!-- autoSize wins: the handle is withdrawn rather than left to fight. -->
+<textarea slTextarea autoSize resize="both"></textarea>
+```
+
+### The four states the control paints
+
+Read-only keeps full-strength ink and its handle, because the commonest thing a read-only textarea holds is a value someone has to copy; disabled loses the handle as well, since a handle on a control nobody can type in is a handle that lies.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextarea } from '@slotted/angular/textarea';
+
+@Component({
+  selector: 'app-textarea-states',
+  imports: [SlField, SlFieldDescription, SlFieldError, SlFieldLabel, SlStack, SlTextarea],
+  template: `
+    <div slStack [gap]="5">
+      <div slField invalid required>
+        <label slFieldLabel>Damage report</label>
+        <textarea slTextarea [rows]="2" defaultValue="Box dented."></textarea>
+        <span slFieldError>Describe the damage in at least 20 characters.</span>
+      </div>
+      <div slField readOnly>
+        <label slFieldLabel>Customer note</label>
+        <textarea
+          slTextarea
+          [rows]="2"
+          defaultValue="Please ring the bell twice. The office is on the second floor."
+        ></textarea>
+        <span slFieldDescription>Written by the customer at checkout.</span>
+      </div>
+      <div slField disabled>
+        <label slFieldLabel>Carrier instructions</label>
+        <textarea slTextarea [rows]="2" defaultValue="Leave with the building manager."></textarea>
+        <span slFieldDescription>Locked once the shipment is booked.</span>
+      </div>
+    </div>
+  `,
+})
+export class TextareaStates {}
+```
+
+### Counting what has been typed
+
+The control counts and the field draws it in the spare column of the label row, so a count that appears on the first keystroke never shares a row with the error and pushes it — which is where Angular Material puts it.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextarea } from '@slotted/angular/textarea';
+
+@Component({
+  selector: 'app-textarea-count',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlStack, SlTextarea],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Gift message</label>
+        <textarea
+          slTextarea
+          [rows]="2"
+          maxlength="150"
+          showCount
+          defaultValue="Happy anniversary to the whole team at Alfreds Futterkiste."
+        ></textarea>
+        <span slFieldDescription>Printed on a card inside the box.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Product summary</label>
+        <textarea
+          slTextarea
+          [rows]="3"
+          countMax="120"
+          showCount
+          defaultValue="Hand-picked Darjeeling first flush, packed in resealable tins of 100 grams. Ships within two days."
+        ></textarea>
+        <span slFieldDescription>Search results cut summaries after 120 characters.</span>
+      </div>
+    </div>
+  `,
+})
+export class TextareaCount {}
+```
+
+### Content the family did not choose
+
+A pasted token with no break in it — a signed URL, a certificate, a container digest — wraps instead of taking the page’s horizontal scrollbar with it, and nothing is removed from the value.
+
+Excerpt — not a complete module
+
+```html
+<textarea slTextarea [rows]="3">{{ jwt }}</textarea>
+
+<!-- overflow-wrap: anywhere in the stylesheet, so the whole string stays
+     selectable, copyable and reachable with the caret. -->
+<textarea slTextarea dir="rtl" [rows]="3">مرحبا بالعالم</textarea>
+```
+
+### Setting it once, and reaching past it
+
+provideTextareaDefaults carries the four decisions an application takes once; exportAs reaches the instance, and textareaElement is the native element with focus, select and setSelectionRange already on it.
+
+Excerpt — not a complete module
+
+```html
+<!-- ControlValueAccessor: the control belongs in a form as it stands. -->
+<textarea slTextarea [formControl]="notes" autoSize></textarea>
+
+<!-- exportAs, for the element the template has to reach. -->
+<textarea slTextarea #campo="slTextarea"></textarea>
+<button type="button" (click)="campo.textareaElement.select()">Selecionar</button>
+```
+
+### What the keyboard does, and what it deliberately does not
+
+Enter makes a line and never submits — the difference WAI-ARIA notes between a single-line and a multi-line control — and Tab leaves the control rather than inserting a tab, so a keyboard user is never trapped in a comment box.
+
+Excerpt — not a complete module
+
+```html
+<form (ngSubmit)="enviar()">
+  <textarea slTextarea [formControl]="notes" [rows]="3"></textarea>
+  <button slButton type="submit">Enviar</button>
+</form>
+```
+
+### comment-composer.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextarea } from '@slotted/angular/textarea';
+import { SlText } from '@slotted/angular/typography';
+
+interface Comment {
+  id: number;
+  author: string;
+  time: string;
+  body: string;
+}
+
+const THREAD: Comment[] = [
+  {
+    id: 1,
+    author: 'Maria Anders',
+    time: '09:12',
+    body: 'The customer called: the pallet has to arrive before the store opens at 8:00.',
+  },
+  {
+    id: 2,
+    author: 'Thomas Hardy',
+    time: '10:47',
+    body: 'Booked with the early carrier. Tracking follows once the truck is loaded.',
+  },
+];
+
+@Component({
+  selector: 'app-textarea-comment-composer',
+  imports: [SlButton, SlField, SlFieldLabel, SlInline, SlStack, SlTextarea, SlText],
+  template: `
+    <div slStack [gap]="6">
+      <div slStack [gap]="4">
+        @for (comment of comments(); track comment.id) {
+          <div slStack [gap]="1">
+            <div slInline [gap]="2" align="baseline">
+              <span slText size="sm" weight="semibold">{{ comment.author }}</span>
+              <span slText size="sm" tone="muted">{{ comment.time }}</span>
+            </div>
+            <span slText size="sm">{{ comment.body }}</span>
+          </div>
+        }
+      </div>
+      <form (submit)="submit($event)">
+        <div slStack [gap]="3">
+          <div slField>
+            <label slFieldLabel>Comment on order 10248</label>
+            <textarea
+              slTextarea
+              autoSize
+              [rows]="2"
+              [maxRows]="8"
+              placeholder="Write an update for the team"
+              [value]="draft()"
+              (valueChange)="draft.set($event.value)"
+            ></textarea>
+          </div>
+          <div slInline justify="end">
+            <button slButton type="submit">Post comment</button>
+          </div>
+        </div>
+      </form>
+    </div>
+  `,
+})
+export class TextareaCommentComposer {
+  readonly comments = signal(THREAD);
+  readonly draft = signal('');
+
+  submit(event: Event): void {
+    event.preventDefault();
+    const body = this.draft().trim();
+    if (body === '') return;
+    this.comments.update((current) => [
+      ...current,
+      { id: current.length + 1, author: 'You', time: 'Just now', body },
+    ]);
+    this.draft.set('');
+  }
+}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { provideTextareaDefaults, SlTextarea } from '@slotted/angular/textarea';
+
+@Component({
+  selector: 'app-textarea-defaults',
+  imports: [SlField, SlFieldLabel, SlStack, SlTextarea],
+  providers: [provideTextareaDefaults({ variant: 'subtle', resize: 'none' })],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Reply to the customer</label>
+        <textarea slTextarea [rows]="2" defaultValue="Your refund was issued today."></textarea>
+      </div>
+      <div slField>
+        <label slFieldLabel>Internal note</label>
+        <textarea slTextarea [rows]="2" defaultValue="Refund approved by finance."></textarea>
+      </div>
+      <div slField>
+        <label slFieldLabel>Escalation summary</label>
+        <textarea
+          slTextarea
+          variant="outline"
+          [rows]="2"
+          defaultValue="Second refund request this quarter."
+        ></textarea>
+      </div>
+    </div>
+  `,
+})
+export class TextareaDefaults {}
+```
+
+### mono.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlTextarea } from '@slotted/angular/textarea';
+
+const PAYLOAD = `{
+  "event": "order.shipped",
+  "orderId": 10248,
+  "carrier": "Federal Shipping",
+  "tracking": "FS-2026-0042-7731"
+}`;
+
+@Component({
+  selector: 'app-textarea-mono',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextarea],
+  template: `
+    <div slField>
+      <label slFieldLabel>Test payload</label>
+      <textarea
+        slTextarea
+        mono
+        variant="subtle"
+        [rows]="7"
+        spellcheck="false"
+        [defaultValue]="payload"
+      ></textarea>
+      <span slFieldDescription>Sent to your endpoint when you press Send test event.</span>
+    </div>
+  `,
+})
+export class TextareaMono {
+  readonly payload = PAYLOAD;
+}
+```
+
+### read-only.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlTextarea } from '@slotted/angular/textarea';
+
+const TERMS = `1. Payment. Invoices are payable within 30 days of the invoice date. Late payments carry interest of 1% per month.
+
+2. Delivery. The supplier ships within five business days of a confirmed purchase order. Partial shipments are invoiced separately.
+
+3. Returns. Goods damaged in transit are reported within 48 hours of receipt, with photographs of the packaging.
+
+4. Prices. Prices are fixed for the term of this agreement and reviewed every January.
+
+5. Termination. Either party may end this agreement with 60 days' written notice.`;
+
+@Component({
+  selector: 'app-textarea-read-only',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextarea],
+  template: `
+    <div slField>
+      <label slFieldLabel>Supplier terms</label>
+      <textarea slTextarea readOnly [rows]="6" [defaultValue]="terms"></textarea>
+      <span slFieldDescription>Agreed with Exotic Liquids on 3 March 2026.</span>
+    </div>
+  `,
+})
+export class TextareaReadOnly {
+  readonly terms = TERMS;
+}
+```
+
+### rows.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextarea } from '@slotted/angular/textarea';
+
+@Component({
+  selector: 'app-textarea-rows',
+  imports: [SlField, SlFieldLabel, SlStack, SlTextarea],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Gift message</label>
+        <textarea
+          slTextarea
+          [rows]="2"
+          resize="none"
+          defaultValue="Happy birthday, Laura. Enjoy the tea."
+        ></textarea>
+      </div>
+      <div slField>
+        <label slFieldLabel>Incident report</label>
+        <textarea
+          slTextarea
+          [rows]="5"
+          placeholder="What happened, when, and who was involved"
+        ></textarea>
+      </div>
+      <div slField>
+        <label slFieldLabel>Reply draft</label>
+        <textarea
+          slTextarea
+          resize="both"
+          placeholder="Drag the corner to resize in both directions"
+        ></textarea>
+      </div>
+    </div>
+  `,
+})
+export class TextareaRows {}
+```
+
+### validation.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
+import { SlButton } from '@slotted/angular/button';
+import { SlField, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { SlTextarea } from '@slotted/angular/textarea';
+
+const MIN_LENGTH = 20;
+
+@Component({
+  selector: 'app-textarea-validation',
+  imports: [
+    ReactiveFormsModule,
+    SlButton,
+    SlField,
+    SlFieldError,
+    SlFieldLabel,
+    SlInline,
+    SlStack,
+    SlTextarea,
+  ],
+  template: `
+    <form novalidate (submit)="submit($event)">
+      <div slStack [gap]="4">
+        <div slField required [invalid]="error() !== '' ? true : undefined">
+          <label slFieldLabel>What is wrong with the item?</label>
+          <textarea slTextarea [formControl]="details" (valueChange)="sent.set(false)"></textarea>
+          <span slFieldError live="polite" reserve>{{ error() }}</span>
+        </div>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Request a return</button>
+          @if (sent()) {
+            <span role="status">Return requested.</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class TextareaValidation {
+  readonly details = new FormControl('', {
+    nonNullable: true,
+    validators: [Validators.required, Validators.minLength(MIN_LENGTH)],
+  });
+  readonly value = toSignal(this.details.valueChanges, { initialValue: this.details.value });
+  readonly submitted = signal(false);
+  readonly sent = signal(false);
+  readonly error = computed(() => {
+    this.value();
+    if (!this.submitted()) return '';
+    if (this.details.hasError('required')) return 'Describe what is wrong with the item.';
+    if (this.details.hasError('minlength')) {
+      return `Add more detail: at least ${MIN_LENGTH} characters.`;
+    }
+    return '';
+  });
+
+  submit(event: Event): void {
+    event.preventDefault();
+    this.submitted.set(true);
+    this.sent.set(this.details.valid);
+  }
+}
+```