@slotted/react 0.1.0-beta.0 → 0.1.0-beta.10

package/dist/docs/tags-input.json

@@ -130,7 +130,9 @@
         "message",
         "counter",
         "clear",
-        "hint"
+        "hint",
+        "suggestions",
+        "suggestion"
       ]
     }
   },
@@ -193,6 +195,18 @@
           "element": "span, visually hidden",
           "required": true,
           "purpose": "What the row answers to, for a reader who cannot see the remove buttons: Delete removes a value, and — while editable — Enter edits it. The row names it as its description."
+        },
+        {
+          "part": "suggestions",
+          "element": "div[role=\"listbox\"]",
+          "required": false,
+          "purpose": "With suggestions, the list under the frame of the ones the typed text matches, minus the values already chosen. Rendered only while open; the input controls it and names its highlighted option by aria-activedescendant."
+        },
+        {
+          "part": "suggestion",
+          "element": "div[role=\"option\"]",
+          "required": false,
+          "purpose": "One suggestion. data-highlighted and aria-selected on the one Enter adds; a press adds it and keeps focus in the input."
         }
       ],
       "api": [
@@ -259,6 +273,13 @@
           "appliesTo": "TagsInput",
           "description": "How a paste is split. The default splits on the delimiters and on every line break."
         },
+        {
+          "name": "suggestions",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "Values the reader may choose instead of typing them whole. The input becomes a combobox: the typed text filters them by the locale’s collator, ArrowDown and ArrowUp move through them, Enter adds the highlighted one. A chosen suggestion is normalized, judged, deduplicated and capped like typed text, and typed text still commits."
+        },
         {
           "name": "formatLabel",
           "type": "(value: string) => string",
@@ -491,8 +512,10 @@
   },
   "tokens": [
     "--slotted-border-subtle",
+    "--slotted-border-width-thin",
     "--slotted-control-border-color",
     "--slotted-control-border-width",
+    "--slotted-control-focus-ring-offset",
     "--slotted-control-font-family",
     "--slotted-control-font-size-lg",
     "--slotted-control-font-size-md",
@@ -529,9 +552,12 @@
     "--slotted-font-size-xs",
     "--slotted-font-weight-medium",
     "--slotted-line-height-sm",
+    "--slotted-radius-lg",
     "--slotted-radius-none",
+    "--slotted-shadow-md",
     "--slotted-space-1",
     "--slotted-space-2",
+    "--slotted-surface-raised",
     "--slotted-surface-sunken",
     "--slotted-tags-input-action-active-background",
     "--slotted-tags-input-action-color",
@@ -571,7 +597,8 @@
     "--slotted-tone-accent-text",
     "--slotted-tone-danger-border",
     "--slotted-tone-secondary-subtle-active",
-    "--slotted-tone-secondary-subtle-hover"
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-z-index-popover"
   ],
   "examples": [
     {

package/dist/docs/tags-input.md

@@ -35,6 +35,8 @@ Excerpt — not a complete module
 | `counter` | span | no |
 | `clear` | button | no |
 | `hint` | span, visually hidden | yes |
+| `suggestions` | div[role="listbox"] | no |
+| `suggestion` | div[role="option"] | no |
 
 ## Props
 
@@ -49,6 +51,7 @@ Excerpt — not a complete module
 | `invalidValues` | `'keep' \| 'refuse'` | keep | TagsInput | What becomes of a value that fails: a chip in the danger tone with its reason, or a report through onValueRefuse. |
 | `normalize` | `(text: string) => string` | — | TagsInput | Runs before a value is judged. Trim by default; an email field lowercases here. |
 | `split` | `(text: string) => readonly string[]` | — | TagsInput | How a paste is split. The default splits on the delimiters and on every line break. |
+| `suggestions` | `readonly string[]` | — | TagsInput | Values the reader may choose instead of typing them whole. The input becomes a combobox: the typed text filters them by the locale’s collator, ArrowDown and ArrowUp move through them, Enter adds the highlighted one. A chosen suggestion is normalized, judged, deduplicated and capped like typed text, and typed text still commits. |
 | `formatLabel` | `(value: string) => string` | — | TagsInput | The chip’s text for a value, for a value that is an address and a label that is a name. |
 | `lockedValues` | `readonly string[]` | — | TagsInput | The values the reader may not remove. Their chips carry data-disabled and draw no remove control. |
 | `locale` | `string` | — | TagsInput | BCP 47, for the comparison the duplicate rule makes. The language in force when absent. |
@@ -117,7 +120,7 @@ Excerpt — not a complete module
 
 ## 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-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-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-size-xs`, `--slotted-font-weight-medium`, `--slotted-line-height-sm`, `--slotted-radius-none`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-surface-sunken`, `--slotted-tags-input-action-active-background`, `--slotted-tags-input-action-color`, `--slotted-tags-input-action-hover-background`, `--slotted-tags-input-action-size`, `--slotted-tags-input-autofill-background`, `--slotted-tags-input-background`, `--slotted-tags-input-border-color`, `--slotted-tags-input-color`, `--slotted-tags-input-counter-color`, `--slotted-tags-input-counter-complete-color`, `--slotted-tags-input-current-border-color`, `--slotted-tags-input-disabled-background`, `--slotted-tags-input-disabled-border-color`, `--slotted-tags-input-disabled-color`, `--slotted-tags-input-field-basis`, `--slotted-tags-input-field-min`, `--slotted-tags-input-hover-border-color`, `--slotted-tags-input-icon-size-min`, `--slotted-tags-input-invalid-border-color`, `--slotted-tags-input-invalid-edge-width`, `--slotted-tags-input-invalid-focus-ring-color`, `--slotted-tags-input-placeholder-color`, `--slotted-tags-input-plain-hover-background`, `--slotted-tags-input-radius`, `--slotted-tags-input-readonly-background`, `--slotted-tags-input-shadow`, `--slotted-tags-input-subtle-background`, `--slotted-tags-input-subtle-border-color`, `--slotted-tags-input-subtle-hover-background`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-focus-ring-offset`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-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-size-xs`, `--slotted-font-weight-medium`, `--slotted-line-height-sm`, `--slotted-radius-lg`, `--slotted-radius-none`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-tags-input-action-active-background`, `--slotted-tags-input-action-color`, `--slotted-tags-input-action-hover-background`, `--slotted-tags-input-action-size`, `--slotted-tags-input-autofill-background`, `--slotted-tags-input-background`, `--slotted-tags-input-border-color`, `--slotted-tags-input-color`, `--slotted-tags-input-counter-color`, `--slotted-tags-input-counter-complete-color`, `--slotted-tags-input-current-border-color`, `--slotted-tags-input-disabled-background`, `--slotted-tags-input-disabled-border-color`, `--slotted-tags-input-disabled-color`, `--slotted-tags-input-field-basis`, `--slotted-tags-input-field-min`, `--slotted-tags-input-hover-border-color`, `--slotted-tags-input-icon-size-min`, `--slotted-tags-input-invalid-border-color`, `--slotted-tags-input-invalid-edge-width`, `--slotted-tags-input-invalid-focus-ring-color`, `--slotted-tags-input-placeholder-color`, `--slotted-tags-input-plain-hover-background`, `--slotted-tags-input-radius`, `--slotted-tags-input-readonly-background`, `--slotted-tags-input-shadow`, `--slotted-tags-input-subtle-background`, `--slotted-tags-input-subtle-border-color`, `--slotted-tags-input-subtle-hover-background`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
 
 ## Examples
 

package/dist/docs/text-field.json

@@ -268,7 +268,7 @@
           "type": "'text' | 'search' | 'email' | 'url' | 'tel' | 'password'",
           "defaultValue": "text",
           "appliesTo": "TextField",
-          "description": "The input’s own type. Any other string an input accepts still reaches the element."
+          "description": "The input’s own type, one of the six listed. A date, a time, a month or a number is not a TextField: use date-picker (forms.md FM-16), time-picker or number-field. Other strings still reach the element for compatibility and are not supported."
         },
         {
           "name": "messages",
@@ -362,6 +362,7 @@
     "--slotted-border-subtle",
     "--slotted-control-border-color",
     "--slotted-control-border-width",
+    "--slotted-control-focus-ring-offset",
     "--slotted-control-font-family",
     "--slotted-control-font-size-lg",
     "--slotted-control-font-size-md",

package/dist/docs/text-field.md

@@ -65,7 +65,7 @@ export default function TextFieldBasic() {
 | `readOnly` | `boolean` | from the field, or false | TextField | Unset by default, so the text field takes the state of the field around it. It is the native readonly: the input stays focusable and selectable, and its value is submitted. |
 | `invalid` | `boolean` | from the field, or false | TextField | Unset by default, so the text field takes the state of the field around it. It sets aria-invalid on the input and data-invalid on the frame. |
 | `required` | `boolean` | — | TextField | The input’s own attribute, passed through unchanged; TextField never writes it. A field marks a required value with aria-required instead, because the native attribute turns on browser constraint validation. |
-| `type` | `'text' \| 'search' \| 'email' \| 'url' \| 'tel' \| 'password'` | text | TextField | The input’s own type. Any other string an input accepts still reaches the element. |
+| `type` | `'text' \| 'search' \| 'email' \| 'url' \| 'tel' \| 'password'` | text | TextField | The input’s own type, one of the six listed. A date, a time, a month or a number is not a TextField: use date-picker (forms.md FM-16), time-picker or number-field. Other strings still reach the element for compatibility and are not supported. |
 | `messages` | `Partial<TextFieldMessages>` | — | TextField | Replaces words of the active language, key by key. clear, reveal and copy name the buttons; reveal does not change with the state, because aria-pressed carries it. copied and copyFailed announce the outcome of a copy. capsLock is announced once when Caps Lock turns on in a focused password field. |
 | `render` | `(props: TextFieldRootProps) => ReactNode` | — | TextField | Renders the frame into another element and passes it every attribute. The props are typed against HTMLAttributes<HTMLElement>, so they can be spread onto a label or a fieldset. The input cannot be replaced, because it holds the value, the identifier and the wiring. |
 | `TextFieldAction` | `ComponentPropsWithRef<"button"> & { render? }` | type="button" | start, end | A button you place inside the frame. Every native prop reaches the button, and render replaces it. MenuTrigger, PopoverTrigger and TooltipTrigger pass their wiring to it through their own render. |
@@ -105,7 +105,7 @@ export default function TextFieldBasic() {
 
 ## 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-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-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-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-mono`, `--slotted-font-weight-medium`, `--slotted-radius-none`, `--slotted-radius-xs`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-field-action-active-background`, `--slotted-text-field-action-color`, `--slotted-text-field-action-hover-background`, `--slotted-text-field-action-label-color`, `--slotted-text-field-action-size`, `--slotted-text-field-adornment-color`, `--slotted-text-field-autofill-background`, `--slotted-text-field-background`, `--slotted-text-field-border-color`, `--slotted-text-field-caps-lock-color`, `--slotted-text-field-color`, `--slotted-text-field-copy-complete-color`, `--slotted-text-field-disabled-background`, `--slotted-text-field-disabled-border-color`, `--slotted-text-field-disabled-color`, `--slotted-text-field-hover-border-color`, `--slotted-text-field-icon-size-min`, `--slotted-text-field-invalid-border-color`, `--slotted-text-field-invalid-edge-width`, `--slotted-text-field-invalid-focus-ring-color`, `--slotted-text-field-placeholder-color`, `--slotted-text-field-plain-hover-background`, `--slotted-text-field-radius`, `--slotted-text-field-readonly-background`, `--slotted-text-field-shadow`, `--slotted-text-field-subtle-background`, `--slotted-text-field-subtle-border-color`, `--slotted-text-field-subtle-hover-background`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
+`--slotted-border-subtle`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-focus-ring-offset`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-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-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-mono`, `--slotted-font-weight-medium`, `--slotted-radius-none`, `--slotted-radius-xs`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-field-action-active-background`, `--slotted-text-field-action-color`, `--slotted-text-field-action-hover-background`, `--slotted-text-field-action-label-color`, `--slotted-text-field-action-size`, `--slotted-text-field-adornment-color`, `--slotted-text-field-autofill-background`, `--slotted-text-field-background`, `--slotted-text-field-border-color`, `--slotted-text-field-caps-lock-color`, `--slotted-text-field-color`, `--slotted-text-field-copy-complete-color`, `--slotted-text-field-disabled-background`, `--slotted-text-field-disabled-border-color`, `--slotted-text-field-disabled-color`, `--slotted-text-field-hover-border-color`, `--slotted-text-field-icon-size-min`, `--slotted-text-field-invalid-border-color`, `--slotted-text-field-invalid-edge-width`, `--slotted-text-field-invalid-focus-ring-color`, `--slotted-text-field-placeholder-color`, `--slotted-text-field-plain-hover-background`, `--slotted-text-field-radius`, `--slotted-text-field-readonly-background`, `--slotted-text-field-shadow`, `--slotted-text-field-subtle-background`, `--slotted-text-field-subtle-border-color`, `--slotted-text-field-subtle-hover-background`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
 
 ## Examples
 

package/dist/docs/textarea.examples.md

@@ -0,0 +1,504 @@
+<!-- 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
+
+```tsx
+<Field>
+  <FieldLabel>Observações</FieldLabel>
+  <Textarea rows={3} placeholder="Descreva o que aconteceu" />
+  <FieldDescription>Aparece no histórico do chamado.</FieldDescription>
+</Field>;
+```
+
+### 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
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaSizes() {
+  return (
+    <Stack gap={5}>
+      <Field size="sm">
+        <FieldLabel>Line item note</FieldLabel>
+        <Textarea rows={2} defaultValue="Pack the glass bottles separately." />
+      </Field>
+      <Field size="md">
+        <FieldLabel>Order note</FieldLabel>
+        <Textarea rows={2} defaultValue="The customer asked for delivery before noon on Friday." />
+      </Field>
+      <Field size="lg">
+        <FieldLabel>Message to the supplier</FieldLabel>
+        <Textarea rows={2} defaultValue="Please confirm the revised quantities by Wednesday." />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaVariants() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Return reason</FieldLabel>
+        <Textarea variant="outline" rows={2} defaultValue="Two jars arrived with broken seals." />
+      </Field>
+      <Field>
+        <FieldLabel>Warehouse note</FieldLabel>
+        <Textarea variant="subtle" rows={2} defaultValue="Restock on shelf B4 after inspection." />
+      </Field>
+      <Field>
+        <FieldLabel>Picker comment</FieldLabel>
+        <Textarea variant="plain" rows={2} defaultValue="Counted twice, 46 units on hand." />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaAutoSize() {
+  return (
+    <Field>
+      <FieldLabel>Picking note</FieldLabel>
+      <Textarea
+        autoSize
+        rows={2}
+        maxRows={6}
+        defaultValue="Use the reinforced boxes for the olive oil."
+      />
+      <FieldDescription>Shown to the picker on the warehouse screen.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### 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
+
+```tsx
+<Textarea resize="block" />;
+<Textarea resize="none" />;
+<Textarea resize="both" />;
+
+// autoSize wins: the handle is withdrawn rather than left to fight.
+<Textarea autoSize resize="both" />;
+```
+
+### 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
+
+```tsx
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaStates() {
+  return (
+    <Stack gap={5}>
+      <Field invalid required>
+        <FieldLabel>Damage report</FieldLabel>
+        <Textarea rows={2} defaultValue="Box dented." />
+        <FieldError>Describe the damage in at least 20 characters.</FieldError>
+      </Field>
+      <Field readOnly>
+        <FieldLabel>Customer note</FieldLabel>
+        <Textarea
+          rows={2}
+          defaultValue="Please ring the bell twice. The office is on the second floor."
+        />
+        <FieldDescription>Written by the customer at checkout.</FieldDescription>
+      </Field>
+      <Field disabled>
+        <FieldLabel>Carrier instructions</FieldLabel>
+        <Textarea rows={2} defaultValue="Leave with the building manager." />
+        <FieldDescription>Locked once the shipment is booked.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaCount() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Gift message</FieldLabel>
+        <Textarea
+          rows={2}
+          maxLength={150}
+          showCount
+          defaultValue="Happy anniversary to the whole team at Alfreds Futterkiste."
+        />
+        <FieldDescription>Printed on a card inside the box.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Product summary</FieldLabel>
+        <Textarea
+          rows={3}
+          countMax={120}
+          showCount
+          defaultValue="Hand-picked Darjeeling first flush, packed in resealable tins of 100 grams. Ships within two days."
+        />
+        <FieldDescription>Search results cut summaries after 120 characters.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+<Textarea defaultValue={jwt} rows={3} />;
+
+// overflow-wrap: anywhere in the stylesheet, so the whole string stays
+// selectable, copyable and reachable with the caret.
+<Textarea dir="rtl" defaultValue="مرحبا بالعالم" rows={3} />;
+```
+
+### Setting it once, and reaching past it
+
+The provider carries the four decisions an application takes once; render substitutes the element; ref reaches the textarea, which already has focus, select and setSelectionRange.
+
+Excerpt — not a complete module
+
+```tsx
+<TextareaDefaultsProvider resize="none" variant="subtle">
+  <Textarea autoSize />
+</TextareaDefaultsProvider>;
+
+const ref = useRef<HTMLTextAreaElement>(null);
+<Textarea ref={ref} name="notes" form="ticket" />;
+```
+
+### 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
+
+```tsx
+<form onSubmit={onSubmit}>
+  <Textarea name="notes" rows={3} />
+  <Button type="submit">Enviar</Button>
+</form>;
+```
+
+### comment-composer.tsx
+
+Example
+
+```tsx
+import { useState, type SubmitEvent } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+import { Text } from '@slotted/react/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.',
+  },
+];
+
+export default function TextareaCommentComposer() {
+  const [comments, setComments] = useState(THREAD);
+  const [draft, setDraft] = useState('');
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const body = draft.trim();
+    if (body === '') return;
+    setComments((current) => [
+      ...current,
+      { id: current.length + 1, author: 'You', time: 'Just now', body },
+    ]);
+    setDraft('');
+  };
+
+  return (
+    <Stack gap={6}>
+      <Stack gap={4}>
+        {comments.map((comment) => (
+          <Stack key={comment.id} gap={1}>
+            <Inline gap={2} align="baseline">
+              <Text size="sm" weight="semibold">
+                {comment.author}
+              </Text>
+              <Text size="sm" tone="muted">
+                {comment.time}
+              </Text>
+            </Inline>
+            <Text size="sm">{comment.body}</Text>
+          </Stack>
+        ))}
+      </Stack>
+      <form onSubmit={submit}>
+        <Stack gap={3}>
+          <Field>
+            <FieldLabel>Comment on order 10248</FieldLabel>
+            <Textarea
+              autoSize
+              rows={2}
+              maxRows={8}
+              placeholder="Write an update for the team"
+              value={draft}
+              onValueChange={setDraft}
+            />
+          </Field>
+          <Inline justify="end">
+            <Button type="submit">Post comment</Button>
+          </Inline>
+        </Stack>
+      </form>
+    </Stack>
+  );
+}
+```
+
+### defaults.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea, TextareaDefaultsProvider } from '@slotted/react/textarea';
+
+export default function TextareaDefaults() {
+  return (
+    <TextareaDefaultsProvider variant="subtle" resize="none">
+      <Stack gap={5}>
+        <Field>
+          <FieldLabel>Reply to the customer</FieldLabel>
+          <Textarea rows={2} defaultValue="Your refund was issued today." />
+        </Field>
+        <Field>
+          <FieldLabel>Internal note</FieldLabel>
+          <Textarea rows={2} defaultValue="Refund approved by finance." />
+        </Field>
+        <Field>
+          <FieldLabel>Escalation summary</FieldLabel>
+          <Textarea variant="outline" rows={2} defaultValue="Second refund request this quarter." />
+        </Field>
+      </Stack>
+    </TextareaDefaultsProvider>
+  );
+}
+```
+
+### mono.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Textarea } from '@slotted/react/textarea';
+
+const PAYLOAD = `{
+  "event": "order.shipped",
+  "orderId": 10248,
+  "carrier": "Federal Shipping",
+  "tracking": "FS-2026-0042-7731"
+}`;
+
+export default function TextareaMono() {
+  return (
+    <Field>
+      <FieldLabel>Test payload</FieldLabel>
+      <Textarea mono variant="subtle" rows={7} spellCheck={false} defaultValue={PAYLOAD} />
+      <FieldDescription>Sent to your endpoint when you press Send test event.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### read-only.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Textarea } from '@slotted/react/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.`;
+
+export default function TextareaReadOnly() {
+  return (
+    <Field>
+      <FieldLabel>Supplier terms</FieldLabel>
+      <Textarea readOnly rows={6} defaultValue={TERMS} />
+      <FieldDescription>Agreed with Exotic Liquids on 3 March 2026.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+### rows.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+export default function TextareaRows() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Gift message</FieldLabel>
+        <Textarea rows={2} resize="none" defaultValue="Happy birthday, Laura. Enjoy the tea." />
+      </Field>
+      <Field>
+        <FieldLabel>Incident report</FieldLabel>
+        <Textarea rows={5} placeholder="What happened, when, and who was involved" />
+      </Field>
+      <Field>
+        <FieldLabel>Reply draft</FieldLabel>
+        <Textarea resize="both" placeholder="Drag the corner to resize in both directions" />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### validation.tsx
+
+Example
+
+```tsx
+import { useState, type SubmitEvent } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldError, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { Stack } from '@slotted/react/stack';
+import { Textarea } from '@slotted/react/textarea';
+
+const MIN_LENGTH = 20;
+
+function detailsError(value: string): string {
+  if (value === '') return 'Describe what is wrong with the item.';
+  if (value.length < MIN_LENGTH) return `Add more detail: at least ${MIN_LENGTH} characters.`;
+  return '';
+}
+
+export default function TextareaValidation() {
+  const [details, setDetails] = useState('');
+  const [submitted, setSubmitted] = useState(false);
+  const [sent, setSent] = useState(false);
+  const error = submitted ? detailsError(details) : '';
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSubmitted(true);
+    setSent(detailsError(details) === '');
+  };
+
+  return (
+    <form noValidate onSubmit={submit}>
+      <Stack gap={4}>
+        <Field required invalid={error !== '' ? true : undefined}>
+          <FieldLabel>What is wrong with the item?</FieldLabel>
+          <Textarea
+            value={details}
+            onValueChange={(value) => {
+              setDetails(value);
+              setSent(false);
+            }}
+          />
+          <FieldError live="polite" reserve>
+            {error}
+          </FieldError>
+        </Field>
+        <Inline gap={3} align="center">
+          <Button type="submit">Request a return</Button>
+          {sent ? <span role="status">Return requested.</span> : null}
+        </Inline>
+      </Stack>
+    </form>
+  );
+}
+```

package/dist/docs/textarea.json

@@ -235,6 +235,7 @@
     "--slotted-border-subtle",
     "--slotted-control-border-color",
     "--slotted-control-border-width",
+    "--slotted-control-focus-ring-offset",
     "--slotted-control-font-family",
     "--slotted-control-font-size-lg",
     "--slotted-control-font-size-md",