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

package/docs/textarea.json

@@ -0,0 +1,440 @@
+{
+  "family": "textarea",
+  "ui": "textarea",
+  "binding": "angular",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Multi-line text input."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "subtle",
+      "plain"
+    ],
+    "resize": [
+      "block",
+      "none",
+      "both"
+    ]
+  },
+  "members": {
+    "textarea": {
+      "nativeElement": "textarea",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "mono": false,
+        "resize": "block",
+        "autoSize": false,
+        "rows": 3,
+        "maxRows": 12,
+        "showCount": false
+      },
+      "capabilities": [
+        "value",
+        "appearance",
+        "size",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "focus-visible",
+        "disabled",
+        "invalid",
+        "readonly"
+      ],
+      "parts": [
+        "root"
+      ]
+    }
+  },
+  "docs": {
+    "textarea": {
+      "imports": {
+        "source": "import { provideTextareaDefaults, SlTextarea } from '@slotted/angular/textarea';",
+        "selector": "textarea[slTextarea]",
+        "exportAs": "slTextarea"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "textarea[slTextarea]",
+          "required": true,
+          "purpose": "The textarea element, which is both the control and its frame. It carries data-ui=\"textarea\", data-size, data-variant and data-resize, data-mono and data-auto-size when they are on, and data-disabled, data-invalid and data-readonly. It has no wrapper: the text field wraps its input so that buttons can sit inside one border, but no adornment sits inside a textarea, and its corner holds the resize handle. It is also the ControlValueAccessor, so the textarea binds to a reactive or template form as it stands."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slTextarea",
+          "description": "Makes the value controlled: it is written to the element whenever it changes, the way a form control’s value is. Without it the element keeps its own value."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slTextarea",
+          "description": "The value the textarea starts from when no value or form control writes one. It is read once the inputs are bound."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slTextarea, provideTextareaDefaults",
+          "description": "The step of the control scale. When unset, the textarea takes the size of its field, then of provideTextareaDefaults. The vertical padding is derived from the step, so a textarea of one row is as tall as a text field of the same step at every density."
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "slTextarea, provideTextareaDefaults",
+          "description": "How much frame the textarea draws: the three frames of the text field, read from the same tokens. When unset, the textarea takes the variant set by provideTextareaDefaults."
+        },
+        {
+          "name": "mono",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slTextarea, provideTextareaDefaults",
+          "description": "Sets the value in the monospaced font with tabular figures, for a payload, a template or a diff."
+        },
+        {
+          "name": "resize",
+          "type": "'block' | 'none' | 'both'",
+          "defaultValue": "block",
+          "appliesTo": "slTextarea, provideTextareaDefaults",
+          "description": "Which way the resize handle drags. The default is block rather than the platform’s both, because a textarea wider than its field breaks the field’s grid. While autoSize is on, the handle is removed."
+        },
+        {
+          "name": "autoSize",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slTextarea",
+          "description": "Grows the textarea with its content through CSS field-sizing, with no measurement in script, which cdkTextareaAutosize performs. rows becomes the floor and maxRows the ceiling."
+        },
+        {
+          "name": "rows",
+          "type": "number",
+          "defaultValue": "3",
+          "appliesTo": "slTextarea",
+          "description": "The starting height in lines, and the floor while autoSize is on. The default is 3 rather than the platform’s 2, because a box of two rows reads as a mistyped input."
+        },
+        {
+          "name": "maxRows",
+          "type": "number",
+          "defaultValue": "12",
+          "appliesTo": "slTextarea",
+          "description": "The ceiling autoSize grows to, in lines; past it the textarea scrolls. It cannot be removed, because a textarea that grows without limit pushes the page out from under the caret."
+        },
+        {
+          "name": "showCount",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slTextarea",
+          "description": "Publishes the length of the value to the field around it, which draws the count at the end of its label row."
+        },
+        {
+          "name": "countMax",
+          "type": "number",
+          "defaultValue": "maxlength",
+          "appliesTo": "slTextarea",
+          "description": "The limit the count is measured against; it defaults to maxlength. Without maxlength it is a soft limit: the value may pass it, and the count is then drawn as invalid."
+        },
+        {
+          "name": "maxLength",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "slTextarea",
+          "description": "The native limit, which refuses input past it. Bound as [maxLength] or written as a static maxlength attribute, it reaches the element as maxlength and the count is measured against it."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slTextarea",
+          "description": "Unset rather than false, so the textarea follows the field around it and a disabled form control. When set, it wins and writes the native disabled."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slTextarea",
+          "description": "Unset rather than false, so the textarea follows the field around it. Writes the native readonly: the textarea stays focusable, selectable and submitted, and keeps its resize handle. A static readonly attribute on the element counts as set."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slTextarea",
+          "description": "Unset rather than false, so the textarea follows the field around it. Writes aria-invalid and data-invalid."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "the textarea element",
+          "description": "The element’s own attribute; SlTextarea never writes it. Inside a required field, the textarea receives aria-required instead, because the native attribute turns on browser constraint validation."
+        }
+      ],
+      "composition": [
+        {
+          "name": "the directive itself",
+          "type": "slTextarea",
+          "defaultValue": "—",
+          "appliesTo": "the consumer’s own textarea",
+          "description": "slTextarea sits on your own textarea element, which is its only part. Every native attribute, listener and form binding you write stays on that element."
+        },
+        {
+          "name": "exportAs",
+          "type": "'slTextarea'",
+          "defaultValue": "—",
+          "appliesTo": "a template",
+          "description": "Reaches the directive instance. Its textareaElement is the native element, with focus(), select() and setSelectionRange()."
+        },
+        {
+          "name": "provideTextareaDefaults()",
+          "type": "{ size, variant, mono, resize }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "Sets size, variant, mono and resize once for every textarea under the injector. A textarea that states a value keeps it, and a textarea inside a field takes the field’s size over the token’s."
+        },
+        {
+          "name": "ControlValueAccessor",
+          "type": "formControl, formControlName, ngModel",
+          "defaultValue": "—",
+          "appliesTo": "slTextarea",
+          "description": "formControl, formControlName and ngModel bind the textarea directly. It registers no validator: SlTextarea owns no validity, and the form decides it."
+        }
+      ],
+      "events": [
+        {
+          "name": "(valueChange)",
+          "payload": "ChangeRequest<string>",
+          "when": "Before the value moves. request.value is the new value and request.previous the value it replaces. request.reason is always keyboard, because only an edit in the textarea moves the value, and request.source is the originating event. request.cancel() refuses the change: the form control and the count do not move, and the element keeps what was typed."
+        },
+        {
+          "name": "ControlValueAccessor",
+          "payload": "the form’s own value and touched state",
+          "when": "Whenever the value moves and the request was not cancelled, and on blur for touched. It is the two-way binding Angular forms expect, which is why there is no [(value)]: a two-way binding carries neither a reason nor cancel()."
+        }
+      ],
+      "accessibility": [
+        "The WAI-ARIA Authoring Practices define no pattern for a multi-line text control. Textarea follows the HTML specification for the element and the ARIA textbox role, whose aria-multiline the native element supplies.",
+        "Inside a field, the textarea takes its accessible name from the field’s label, whose for attribute points at the identifier the field generates. aria-describedby lists any value you write first, then the ones the field adds: help, description, count and error.",
+        "A required field sets aria-required, not the native required. Every value you write on the element (id, aria-describedby, aria-invalid, aria-required and readonly) is read before the host bindings compute and is never overwritten, although an Angular host binding otherwise wins over a static attribute.",
+        "Enter adds a line and never submits the form. WAI-ARIA describes this as the difference between a single-line and a multi-line text control, and a comment box that submitted on Enter would lose what was being written.",
+        "Tab moves focus out of the textarea. No key is bound, so no shortcut holds keyboard focus inside it.",
+        "Growth with the content is CSS, not script: the textarea takes its new height with no animation, so a screen reader announces nothing and a reader who asked for reduced motion sees no movement."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-radius",
+    "--slotted-control-shadow",
+    "--slotted-control-shadow-focus-geometry",
+    "--slotted-control-surface",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-family-mono",
+    "--slotted-line-height-md",
+    "--slotted-radius-none",
+    "--slotted-surface-sunken",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-textarea-background",
+    "--slotted-textarea-border-color",
+    "--slotted-textarea-color",
+    "--slotted-textarea-disabled-background",
+    "--slotted-textarea-disabled-border-color",
+    "--slotted-textarea-disabled-color",
+    "--slotted-textarea-hover-border-color",
+    "--slotted-textarea-invalid-border-color",
+    "--slotted-textarea-invalid-edge-width",
+    "--slotted-textarea-invalid-focus-ring-color",
+    "--slotted-textarea-line-height",
+    "--slotted-textarea-max-rows",
+    "--slotted-textarea-placeholder-color",
+    "--slotted-textarea-plain-hover-background",
+    "--slotted-textarea-radius",
+    "--slotted-textarea-readonly-background",
+    "--slotted-textarea-rows",
+    "--slotted-textarea-shadow",
+    "--slotted-textarea-subtle-background",
+    "--slotted-textarea-subtle-border-color",
+    "--slotted-textarea-subtle-hover-background",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slField>\n  <label slFieldLabel>Observações</label>\n  <textarea slTextarea [rows]=\"3\" placeholder=\"Descreva o que aconteceu\"></textarea>\n  <span slFieldDescription>Aparece no histórico do chamado.</span>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The step the control sits at",
+      "note": "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.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextarea } from '@slotted/angular/textarea';\n\n@Component({\n  selector: 'app-textarea-sizes',\n  imports: [SlField, SlFieldLabel, SlStack, SlTextarea],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField size=\"sm\">\n        <label slFieldLabel>Line item note</label>\n        <textarea\n          slTextarea\n          [rows]=\"2\"\n          defaultValue=\"Pack the glass bottles separately.\"\n        ></textarea>\n      </div>\n      <div slField size=\"md\">\n        <label slFieldLabel>Order note</label>\n        <textarea\n          slTextarea\n          [rows]=\"2\"\n          defaultValue=\"The customer asked for delivery before noon on Friday.\"\n        ></textarea>\n      </div>\n      <div slField size=\"lg\">\n        <label slFieldLabel>Message to the supplier</label>\n        <textarea\n          slTextarea\n          [rows]=\"2\"\n          defaultValue=\"Please confirm the revised quantities by Wednesday.\"\n        ></textarea>\n      </div>\n    </div>\n  `,\n})\nexport class TextareaSizes {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "variants",
+      "title": "How much frame the control shows",
+      "note": "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.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextarea } from '@slotted/angular/textarea';\n\n@Component({\n  selector: 'app-textarea-variants',\n  imports: [SlField, SlFieldLabel, SlStack, SlTextarea],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField>\n        <label slFieldLabel>Return reason</label>\n        <textarea\n          slTextarea\n          variant=\"outline\"\n          [rows]=\"2\"\n          defaultValue=\"Two jars arrived with broken seals.\"\n        ></textarea>\n      </div>\n      <div slField>\n        <label slFieldLabel>Warehouse note</label>\n        <textarea\n          slTextarea\n          variant=\"subtle\"\n          [rows]=\"2\"\n          defaultValue=\"Restock on shelf B4 after inspection.\"\n        ></textarea>\n      </div>\n      <div slField>\n        <label slFieldLabel>Picker comment</label>\n        <textarea\n          slTextarea\n          variant=\"plain\"\n          [rows]=\"2\"\n          defaultValue=\"Counted twice, 46 units on hand.\"\n        ></textarea>\n      </div>\n    </div>\n  `,\n})\nexport class TextareaVariants {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "auto-size",
+      "title": "Growing with the content",
+      "note": "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.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport { SlTextarea } from '@slotted/angular/textarea';\n\n@Component({\n  selector: 'app-textarea-auto-size',\n  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextarea],\n  template: `\n    <div slField>\n      <label slFieldLabel>Picking note</label>\n      <textarea\n        slTextarea\n        autoSize\n        [rows]=\"2\"\n        [maxRows]=\"6\"\n        defaultValue=\"Use the reinforced boxes for the olive oil.\"\n      ></textarea>\n      <span slFieldDescription>Shown to the picker on the warehouse screen.</span>\n    </div>\n  `,\n})\nexport class TextareaAutoSize {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "resize",
+      "title": "The handle in the corner",
+      "note": "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.",
+      "language": "html",
+      "source": "<textarea slTextarea resize=\"none\"></textarea>\n<textarea slTextarea resize=\"both\"></textarea>\n\n<!-- autoSize wins: the handle is withdrawn rather than left to fight. -->\n<textarea slTextarea autoSize resize=\"both\"></textarea>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "The four states the control paints",
+      "note": "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.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextarea } from '@slotted/angular/textarea';\n\n@Component({\n  selector: 'app-textarea-states',\n  imports: [SlField, SlFieldDescription, SlFieldError, SlFieldLabel, SlStack, SlTextarea],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField invalid required>\n        <label slFieldLabel>Damage report</label>\n        <textarea slTextarea [rows]=\"2\" defaultValue=\"Box dented.\"></textarea>\n        <span slFieldError>Describe the damage in at least 20 characters.</span>\n      </div>\n      <div slField readOnly>\n        <label slFieldLabel>Customer note</label>\n        <textarea\n          slTextarea\n          [rows]=\"2\"\n          defaultValue=\"Please ring the bell twice. The office is on the second floor.\"\n        ></textarea>\n        <span slFieldDescription>Written by the customer at checkout.</span>\n      </div>\n      <div slField disabled>\n        <label slFieldLabel>Carrier instructions</label>\n        <textarea slTextarea [rows]=\"2\" defaultValue=\"Leave with the building manager.\"></textarea>\n        <span slFieldDescription>Locked once the shipment is booked.</span>\n      </div>\n    </div>\n  `,\n})\nexport class TextareaStates {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "count",
+      "title": "Counting what has been typed",
+      "note": "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.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextarea } from '@slotted/angular/textarea';\n\n@Component({\n  selector: 'app-textarea-count',\n  imports: [SlField, SlFieldDescription, SlFieldLabel, SlStack, SlTextarea],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField>\n        <label slFieldLabel>Gift message</label>\n        <textarea\n          slTextarea\n          [rows]=\"2\"\n          maxlength=\"150\"\n          showCount\n          defaultValue=\"Happy anniversary to the whole team at Alfreds Futterkiste.\"\n        ></textarea>\n        <span slFieldDescription>Printed on a card inside the box.</span>\n      </div>\n      <div slField>\n        <label slFieldLabel>Product summary</label>\n        <textarea\n          slTextarea\n          [rows]=\"3\"\n          countMax=\"120\"\n          showCount\n          defaultValue=\"Hand-picked Darjeeling first flush, packed in resealable tins of 100 grams. Ships within two days.\"\n        ></textarea>\n        <span slFieldDescription>Search results cut summaries after 120 characters.</span>\n      </div>\n    </div>\n  `,\n})\nexport class TextareaCount {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "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.",
+      "language": "html",
+      "source": "<textarea slTextarea [rows]=\"3\">{{ jwt }}</textarea>\n\n<!-- overflow-wrap: anywhere in the stylesheet, so the whole string stays\n     selectable, copyable and reachable with the caret. -->\n<textarea slTextarea dir=\"rtl\" [rows]=\"3\">مرحبا بالعالم</textarea>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and reaching past it",
+      "note": "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.",
+      "language": "html",
+      "source": "<!-- ControlValueAccessor: the control belongs in a form as it stands. -->\n<textarea slTextarea [formControl]=\"notes\" autoSize></textarea>\n\n<!-- exportAs, for the element the template has to reach. -->\n<textarea slTextarea #campo=\"slTextarea\"></textarea>\n<button type=\"button\" (click)=\"campo.textareaElement.select()\">Selecionar</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the keyboard does, and what it deliberately does not",
+      "note": "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.",
+      "language": "html",
+      "source": "<form (ngSubmit)=\"enviar()\">\n  <textarea slTextarea [formControl]=\"notes\" [rows]=\"3\"></textarea>\n  <button slButton type=\"submit\">Enviar</button>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "basic",
+      "title": "basic.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport { SlTextarea } from '@slotted/angular/textarea';\n\n@Component({\n  selector: 'app-textarea-basic',\n  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextarea],\n  template: `\n    <div slField>\n      <label slFieldLabel>Delivery instructions</label>\n      <textarea slTextarea placeholder=\"Gate code, loading dock, opening hours\"></textarea>\n      <span slFieldDescription>Printed on the packing slip for the carrier.</span>\n    </div>\n  `,\n})\nexport class TextareaBasic {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "comment-composer",
+      "title": "comment-composer.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, signal } from '@angular/core';\nimport { SlButton } from '@slotted/angular/button';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlInline } from '@slotted/angular/inline';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextarea } from '@slotted/angular/textarea';\nimport { SlText } from '@slotted/angular/typography';\n\ninterface Comment {\n  id: number;\n  author: string;\n  time: string;\n  body: string;\n}\n\nconst THREAD: Comment[] = [\n  {\n    id: 1,\n    author: 'Maria Anders',\n    time: '09:12',\n    body: 'The customer called: the pallet has to arrive before the store opens at 8:00.',\n  },\n  {\n    id: 2,\n    author: 'Thomas Hardy',\n    time: '10:47',\n    body: 'Booked with the early carrier. Tracking follows once the truck is loaded.',\n  },\n];\n\n@Component({\n  selector: 'app-textarea-comment-composer',\n  imports: [SlButton, SlField, SlFieldLabel, SlInline, SlStack, SlTextarea, SlText],\n  template: `\n    <div slStack [gap]=\"6\">\n      <div slStack [gap]=\"4\">\n        @for (comment of comments(); track comment.id) {\n          <div slStack [gap]=\"1\">\n            <div slInline [gap]=\"2\" align=\"baseline\">\n              <span slText size=\"sm\" weight=\"semibold\">{{ comment.author }}</span>\n              <span slText size=\"sm\" tone=\"muted\">{{ comment.time }}</span>\n            </div>\n            <span slText size=\"sm\">{{ comment.body }}</span>\n          </div>\n        }\n      </div>\n      <form (submit)=\"submit($event)\">\n        <div slStack [gap]=\"3\">\n          <div slField>\n            <label slFieldLabel>Comment on order 10248</label>\n            <textarea\n              slTextarea\n              autoSize\n              [rows]=\"2\"\n              [maxRows]=\"8\"\n              placeholder=\"Write an update for the team\"\n              [value]=\"draft()\"\n              (valueChange)=\"draft.set($event.value)\"\n            ></textarea>\n          </div>\n          <div slInline justify=\"end\">\n            <button slButton type=\"submit\">Post comment</button>\n          </div>\n        </div>\n      </form>\n    </div>\n  `,\n})\nexport class TextareaCommentComposer {\n  readonly comments = signal(THREAD);\n  readonly draft = signal('');\n\n  submit(event: Event): void {\n    event.preventDefault();\n    const body = this.draft().trim();\n    if (body === '') return;\n    this.comments.update((current) => [\n      ...current,\n      { id: current.length + 1, author: 'You', time: 'Just now', body },\n    ]);\n    this.draft.set('');\n  }\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { provideTextareaDefaults, SlTextarea } from '@slotted/angular/textarea';\n\n@Component({\n  selector: 'app-textarea-defaults',\n  imports: [SlField, SlFieldLabel, SlStack, SlTextarea],\n  providers: [provideTextareaDefaults({ variant: 'subtle', resize: 'none' })],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField>\n        <label slFieldLabel>Reply to the customer</label>\n        <textarea slTextarea [rows]=\"2\" defaultValue=\"Your refund was issued today.\"></textarea>\n      </div>\n      <div slField>\n        <label slFieldLabel>Internal note</label>\n        <textarea slTextarea [rows]=\"2\" defaultValue=\"Refund approved by finance.\"></textarea>\n      </div>\n      <div slField>\n        <label slFieldLabel>Escalation summary</label>\n        <textarea\n          slTextarea\n          variant=\"outline\"\n          [rows]=\"2\"\n          defaultValue=\"Second refund request this quarter.\"\n        ></textarea>\n      </div>\n    </div>\n  `,\n})\nexport class TextareaDefaults {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "mono",
+      "title": "mono.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport { SlTextarea } from '@slotted/angular/textarea';\n\nconst PAYLOAD = `{\n  \"event\": \"order.shipped\",\n  \"orderId\": 10248,\n  \"carrier\": \"Federal Shipping\",\n  \"tracking\": \"FS-2026-0042-7731\"\n}`;\n\n@Component({\n  selector: 'app-textarea-mono',\n  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextarea],\n  template: `\n    <div slField>\n      <label slFieldLabel>Test payload</label>\n      <textarea\n        slTextarea\n        mono\n        variant=\"subtle\"\n        [rows]=\"7\"\n        spellcheck=\"false\"\n        [defaultValue]=\"payload\"\n      ></textarea>\n      <span slFieldDescription>Sent to your endpoint when you press Send test event.</span>\n    </div>\n  `,\n})\nexport class TextareaMono {\n  readonly payload = PAYLOAD;\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "read-only",
+      "title": "read-only.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport { SlTextarea } from '@slotted/angular/textarea';\n\nconst TERMS = `1. Payment. Invoices are payable within 30 days of the invoice date. Late payments carry interest of 1% per month.\n\n2. Delivery. The supplier ships within five business days of a confirmed purchase order. Partial shipments are invoiced separately.\n\n3. Returns. Goods damaged in transit are reported within 48 hours of receipt, with photographs of the packaging.\n\n4. Prices. Prices are fixed for the term of this agreement and reviewed every January.\n\n5. Termination. Either party may end this agreement with 60 days' written notice.`;\n\n@Component({\n  selector: 'app-textarea-read-only',\n  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextarea],\n  template: `\n    <div slField>\n      <label slFieldLabel>Supplier terms</label>\n      <textarea slTextarea readOnly [rows]=\"6\" [defaultValue]=\"terms\"></textarea>\n      <span slFieldDescription>Agreed with Exotic Liquids on 3 March 2026.</span>\n    </div>\n  `,\n})\nexport class TextareaReadOnly {\n  readonly terms = TERMS;\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "rows",
+      "title": "rows.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextarea } from '@slotted/angular/textarea';\n\n@Component({\n  selector: 'app-textarea-rows',\n  imports: [SlField, SlFieldLabel, SlStack, SlTextarea],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField>\n        <label slFieldLabel>Gift message</label>\n        <textarea\n          slTextarea\n          [rows]=\"2\"\n          resize=\"none\"\n          defaultValue=\"Happy birthday, Laura. Enjoy the tea.\"\n        ></textarea>\n      </div>\n      <div slField>\n        <label slFieldLabel>Incident report</label>\n        <textarea\n          slTextarea\n          [rows]=\"5\"\n          placeholder=\"What happened, when, and who was involved\"\n        ></textarea>\n      </div>\n      <div slField>\n        <label slFieldLabel>Reply draft</label>\n        <textarea\n          slTextarea\n          resize=\"both\"\n          placeholder=\"Drag the corner to resize in both directions\"\n        ></textarea>\n      </div>\n    </div>\n  `,\n})\nexport class TextareaRows {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, computed, signal } from '@angular/core';\nimport { toSignal } from '@angular/core/rxjs-interop';\nimport { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';\nimport { SlButton } from '@slotted/angular/button';\nimport { SlField, SlFieldError, SlFieldLabel } from '@slotted/angular/field';\nimport { SlInline } from '@slotted/angular/inline';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextarea } from '@slotted/angular/textarea';\n\nconst MIN_LENGTH = 20;\n\n@Component({\n  selector: 'app-textarea-validation',\n  imports: [\n    ReactiveFormsModule,\n    SlButton,\n    SlField,\n    SlFieldError,\n    SlFieldLabel,\n    SlInline,\n    SlStack,\n    SlTextarea,\n  ],\n  template: `\n    <form novalidate (submit)=\"submit($event)\">\n      <div slStack [gap]=\"4\">\n        <div slField required [invalid]=\"error() !== '' ? true : undefined\">\n          <label slFieldLabel>What is wrong with the item?</label>\n          <textarea slTextarea [formControl]=\"details\" (valueChange)=\"sent.set(false)\"></textarea>\n          <span slFieldError live=\"polite\" reserve>{{ error() }}</span>\n        </div>\n        <div slInline [gap]=\"3\" align=\"center\">\n          <button slButton type=\"submit\">Request a return</button>\n          @if (sent()) {\n            <span role=\"status\">Return requested.</span>\n          }\n        </div>\n      </div>\n    </form>\n  `,\n})\nexport class TextareaValidation {\n  readonly details = new FormControl('', {\n    nonNullable: true,\n    validators: [Validators.required, Validators.minLength(MIN_LENGTH)],\n  });\n  readonly value = toSignal(this.details.valueChanges, { initialValue: this.details.value });\n  readonly submitted = signal(false);\n  readonly sent = signal(false);\n  readonly error = computed(() => {\n    this.value();\n    if (!this.submitted()) return '';\n    if (this.details.hasError('required')) return 'Describe what is wrong with the item.';\n    if (this.details.hasError('minlength')) {\n      return `Add more detail: at least ${MIN_LENGTH} characters.`;\n    }\n    return '';\n  });\n\n  submit(event: Event): void {\n    event.preventDefault();\n    this.submitted.set(true);\n    this.sent.set(this.details.valid);\n  }\n}\n",
+      "verdict": "example"
+    }
+  ]
+}

package/docs/textarea.md

@@ -0,0 +1,98 @@
+<!-- index: ./index.md -->
+# textarea
+
+`data-ui="textarea"` · Multi-line text input.
+
+## Import
+
+```ts
+import { provideTextareaDefaults, SlTextarea } from '@slotted/angular/textarea';
+```
+
+Selector: `textarea[slTextarea]` · exportAs: `slTextarea`
+
+## Minimal example
+
+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-basic',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextarea],
+  template: `
+    <div slField>
+      <label slFieldLabel>Delivery instructions</label>
+      <textarea slTextarea placeholder="Gate code, loading dock, opening hours"></textarea>
+      <span slFieldDescription>Printed on the packing slip for the carrier.</span>
+    </div>
+  `,
+})
+export class TextareaBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | textarea[slTextarea] | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | slTextarea | Makes the value controlled: it is written to the element whenever it changes, the way a form control’s value is. Without it the element keeps its own value. |
+| `defaultValue` | `string` | — | slTextarea | The value the textarea starts from when no value or form control writes one. It is read once the inputs are bound. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slTextarea, provideTextareaDefaults | The step of the control scale. When unset, the textarea takes the size of its field, then of provideTextareaDefaults. The vertical padding is derived from the step, so a textarea of one row is as tall as a text field of the same step at every density. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | slTextarea, provideTextareaDefaults | How much frame the textarea draws: the three frames of the text field, read from the same tokens. When unset, the textarea takes the variant set by provideTextareaDefaults. |
+| `mono` | `boolean` | false | slTextarea, provideTextareaDefaults | Sets the value in the monospaced font with tabular figures, for a payload, a template or a diff. |
+| `resize` | `'block' \| 'none' \| 'both'` | block | slTextarea, provideTextareaDefaults | Which way the resize handle drags. The default is block rather than the platform’s both, because a textarea wider than its field breaks the field’s grid. While autoSize is on, the handle is removed. |
+| `autoSize` | `boolean` | false | slTextarea | Grows the textarea with its content through CSS field-sizing, with no measurement in script, which cdkTextareaAutosize performs. rows becomes the floor and maxRows the ceiling. |
+| `rows` | `number` | 3 | slTextarea | The starting height in lines, and the floor while autoSize is on. The default is 3 rather than the platform’s 2, because a box of two rows reads as a mistyped input. |
+| `maxRows` | `number` | 12 | slTextarea | The ceiling autoSize grows to, in lines; past it the textarea scrolls. It cannot be removed, because a textarea that grows without limit pushes the page out from under the caret. |
+| `showCount` | `boolean` | false | slTextarea | Publishes the length of the value to the field around it, which draws the count at the end of its label row. |
+| `countMax` | `number` | maxlength | slTextarea | The limit the count is measured against; it defaults to maxlength. Without maxlength it is a soft limit: the value may pass it, and the count is then drawn as invalid. |
+| `maxLength` | `number` | — | slTextarea | The native limit, which refuses input past it. Bound as [maxLength] or written as a static maxlength attribute, it reaches the element as maxlength and the count is measured against it. |
+| `disabled` | `boolean` | from the field, or false | slTextarea | Unset rather than false, so the textarea follows the field around it and a disabled form control. When set, it wins and writes the native disabled. |
+| `readOnly` | `boolean` | from the field, or false | slTextarea | Unset rather than false, so the textarea follows the field around it. Writes the native readonly: the textarea stays focusable, selectable and submitted, and keeps its resize handle. A static readonly attribute on the element counts as set. |
+| `invalid` | `boolean` | from the field, or false | slTextarea | Unset rather than false, so the textarea follows the field around it. Writes aria-invalid and data-invalid. |
+| `required` | `boolean` | — | the textarea element | The element’s own attribute; SlTextarea never writes it. Inside a required field, the textarea receives aria-required instead, because the native attribute turns on browser constraint validation. |
+| `the directive itself` | `slTextarea` | — | the consumer’s own textarea | slTextarea sits on your own textarea element, which is its only part. Every native attribute, listener and form binding you write stays on that element. |
+| `exportAs` | `'slTextarea'` | — | a template | Reaches the directive instance. Its textareaElement is the native element, with focus(), select() and setSelectionRange(). |
+| `provideTextareaDefaults()` | `{ size, variant, mono, resize }` | — | an injector | Sets size, variant, mono and resize once for every textarea under the injector. A textarea that states a value keeps it, and a textarea inside a field takes the field’s size over the token’s. |
+| `ControlValueAccessor` | `formControl, formControlName, ngModel` | — | slTextarea | formControl, formControlName and ngModel bind the textarea directly. It registers no validator: SlTextarea owns no validity, and the form decides it. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(valueChange)` | `ChangeRequest<string>` | Before the value moves. request.value is the new value and request.previous the value it replaces. request.reason is always keyboard, because only an edit in the textarea moves the value, and request.source is the originating event. request.cancel() refuses the change: the form control and the count do not move, and the element keeps what was typed. |
+| `ControlValueAccessor` | `the form’s own value and touched state` | Whenever the value moves and the request was not cancelled, and on blur for touched. It is the two-way binding Angular forms expect, which is why there is no [(value)]: a two-way binding carries neither a reason nor cancel(). |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `resize` | `block`, `none`, `both` | `block` |
+
+## Rules
+
+- The WAI-ARIA Authoring Practices define no pattern for a multi-line text control. Textarea follows the HTML specification for the element and the ARIA textbox role, whose aria-multiline the native element supplies.
+- Inside a field, the textarea takes its accessible name from the field’s label, whose for attribute points at the identifier the field generates. aria-describedby lists any value you write first, then the ones the field adds: help, description, count and error.
+- A required field sets aria-required, not the native required. Every value you write on the element (id, aria-describedby, aria-invalid, aria-required and readonly) is read before the host bindings compute and is never overwritten, although an Angular host binding otherwise wins over a static attribute.
+- Enter adds a line and never submits the form. WAI-ARIA describes this as the difference between a single-line and a multi-line text control, and a comment box that submitted on Enter would lose what was being written.
+- Tab moves focus out of the textarea. No key is bound, so no shortcut holds keyboard focus inside it.
+- Growth with the content is CSS, not script: the textarea takes its new height with no animation, so a screen reader announces nothing and a reader who asked for reduced motion sees no movement.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-mono`, `--slotted-line-height-md`, `--slotted-radius-none`, `--slotted-surface-sunken`, `--slotted-text`, `--slotted-text-muted`, `--slotted-textarea-background`, `--slotted-textarea-border-color`, `--slotted-textarea-color`, `--slotted-textarea-disabled-background`, `--slotted-textarea-disabled-border-color`, `--slotted-textarea-disabled-color`, `--slotted-textarea-hover-border-color`, `--slotted-textarea-invalid-border-color`, `--slotted-textarea-invalid-edge-width`, `--slotted-textarea-invalid-focus-ring-color`, `--slotted-textarea-line-height`, `--slotted-textarea-max-rows`, `--slotted-textarea-placeholder-color`, `--slotted-textarea-plain-hover-background`, `--slotted-textarea-radius`, `--slotted-textarea-readonly-background`, `--slotted-textarea-rows`, `--slotted-textarea-shadow`, `--slotted-textarea-subtle-background`, `--slotted-textarea-subtle-border-color`, `--slotted-textarea-subtle-hover-background`, `--slotted-tone-accent-border`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+See [textarea.examples.md](./textarea.examples.md).