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

package/dist/docs/text-field.md

@@ -0,0 +1,112 @@
+<!-- index: ./index.md -->
+# text-field
+
+`data-ui="text-field"` · Single-line text input.
+
+## Import
+
+```tsx
+import { TextField, TextFieldAction, TextFieldDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { TextField } from '@slotted/react/text-field';
+
+export default function TextFieldBasic() {
+  return (
+    <Field required>
+      <FieldLabel>Company name</FieldLabel>
+      <TextField autoComplete="organization" clearable defaultValue="Northwind Traders" />
+      <FieldDescription>Printed on every invoice and packing slip.</FieldDescription>
+    </Field>
+  );
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `input` | input | yes |
+| `start` | span | no |
+| `end` | span | no |
+| `action` | button (TextFieldAction), inside start or end | no |
+| `busy` | span[data-ui="spinner"] | no |
+| `caps-lock` | span | no |
+| `clear` | button | no |
+| `copy` | button | no |
+| `reveal` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | TextField | Makes the value controlled for the life of the component. Without it the input keeps its own value, and a native form reset restores defaultValue. |
+| `defaultValue` | `string` | — | TextField | The value an uncontrolled text field starts from. It is read once and written to the input as the native attribute. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | TextField, TextFieldDefaultsProvider | The step of the control scale. Without it the text field takes the size of the field around it, then the provider’s. Height, padding, type and icon size come from the control scales, which the theme restates for each density. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | TextField, TextFieldDefaultsProvider | How much frame the control draws. plain draws no border at rest and keeps the same box, for a dense table cell. |
+| `mono` | `boolean` | false | TextField, TextFieldDefaultsProvider | Sets the value in the monospaced font with tabular figures, for identifiers, hashes and keys. |
+| `clearable` | `boolean` | false | TextField | Draws a button that empties the value with reason "clear" and returns focus to the input. The button is withdrawn while the value is empty, disabled or read-only. |
+| `revealable` | `boolean` | false | TextField | Draws a toggle that shows a password as characters. It appears only on type="password" and is withdrawn while the input is disabled. |
+| `copyable` | `boolean` | false | TextField | Draws a button that writes the value to the clipboard, shows a check for two seconds and announces the outcome. It is hidden while the value is empty or the input is disabled. |
+| `loading` | `boolean` | false | TextField | Draws the shared spinner before the buttons and sets aria-busy on the input; the value stays editable. Once loading is set, false included, the spinner keeps its place so it can leave with a transition. |
+| `revealed` | `boolean` | — | TextField | Makes the password toggle controlled. defaultRevealed sets the uncontrolled starting state. |
+| `showCount` | `boolean` | false | TextField | 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 | TextField | The limit the count is measured against. Without maxLength it is a soft limit: the value can pass it, and the count turns to the danger tone before validation runs. |
+| `start` | `ReactNode` | — | TextField | Content before the value in the reading direction. It is its own bidirectional run, and an icon inside it takes the control’s icon size. |
+| `end` | `ReactNode` | — | TextField | Content after the value in the reading direction. |
+| `disabled` | `boolean` | from the field, or false | TextField | Unset by default, so the text field takes the state of the field around it. When set, it wins, and it is the native attribute: the input leaves the tab order and form submission. |
+| `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. |
+| `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. |
+| `ref` | `Ref<HTMLInputElement>` | — | TextField | Reaches the input. focus(), select() and setSelectionRange() are the element’s own, so TextField adds no imperative handle. |
+| `className / style` | `string / CSSProperties` | — | TextField | Reach the frame, because the frame is what a reader sees. Every other native prop reaches the input. |
+| `TextFieldDefaultsProvider` | `{ size, variant, mono }` | — | a subtree | Sets size, variant and mono once for every text field under it. A field outranks it for size, so a text field inside a field takes the field’s size. |
+| `useField()` | `() => FieldContextValue \| undefined` | — | inside a Field | What TextField reads from the field around it: the identifier, the description, the disabled, read-only, invalid and required states, and the channel it publishes its count on. A text field inside a field needs no wiring of its own. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: string, request: ChangeRequest<string>)` | Before the value changes. The request carries the new value, the value it replaces, the reason ("keyboard" for an edit in the input, "clear" for the clear button), the originating event, and cancel(), which refuses the change before it commits. |
+| `onRevealedChange` | `(revealed: boolean, request: ChangeRequest<boolean>)` | Before the password toggle changes, with reason "pointer" or "keyboard" read from the click. A form that hides the password again on blur controls revealed and listens here. |
+| `onValueCopy` | `({ copied, reason, source, value }: TextFieldCopyDetail)` | After the copy button has asked the clipboard. copied is false when the clipboard refused the value, and reason is "pointer" or "keyboard". onCopy remains the input’s native clipboard event. |
+| `onChange, onInput, onFocus, onBlur, onKeyDown, onKeyUp` | `the element’s own events` | Whenever the input fires them. TextField composes your handler with its own instead of replacing it: yours runs first, and always runs. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+
+## Rules
+
+- There is no WAI-ARIA Authoring Practices pattern for a text field: the APG lists thirty patterns, and none of them is a single-line text input. The sources are the HTML specification for the input element, the APG practice Providing Accessible Names and Descriptions (w3.org/WAI/ARIA/apg/practices/names-and-descriptions/) for its name, and the ARIA textbox role for what may sit inside it.
+- The frame has no role. WAI-ARIA requires the children of a textbox to be non-interactive and presentational, so the clear and reveal buttons are siblings of the input inside a box that announces nothing.
+- The input takes its name from the field’s label, whose for attribute points at the identifier the field generates. The APG naming practice records that some combinations of browser and assistive technology compute no name from a label that wraps its control.
+- Inside a required field the input carries aria-required, never the native required, because the native attribute turns on browser constraint validation and changes how the form submits. Write required on the input to opt into the platform’s validation; TextField leaves it unchanged. disabled and readonly are the native attributes.
+- The clear and reveal buttons are native buttons with names you translate once through messages. Each is at least 24 CSS pixels wide at every size and density, which meets WCAG 2.2 success criterion 2.5.8. The reveal button keeps one name and carries its state in aria-pressed, which is the APG rule for a toggle button.
+- The copy button announces its outcome through the shared live announcer, Copied or Copy failed, because the check that replaces the copy mark is only visible. The Caps Lock mark is hidden from assistive technology; its message is announced once when Caps Lock turns on while the password field has focus.
+- loading sets aria-busy on the input and leaves it enabled, so the keyboard stays on the input while an asynchronous check runs. The spinner is hidden from assistive technology.
+- A menu inside the frame follows the APG menu button pattern (w3.org/WAI/ARIA/apg/patterns/menu-button/). The menu trigger on the action supplies aria-haspopup, aria-expanded, and Enter, Space and ArrowDown to open.
+- No key is bound to Escape. Some browsers clear a search input on Escape, and a text field that consumed the key inside a dialog would leave a keyboard user unable to close the dialog. WCAG success criterion 2.1.4 addresses the defects that single-key shortcuts cause.
+- The invalid state does not rely on colour alone: aria-invalid announces it, the field’s error states it in words, and the inline message writes a visually hidden “Error:” before the sentence. In the high-contrast scheme the border cannot carry the state, so nothing depends on it.
+
+## 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`
+
+## Examples
+
+See [text-field.examples.md](./text-field.examples.md).

package/dist/docs/textarea.json

@@ -0,0 +1,431 @@
+{
+  "family": "textarea",
+  "ui": "textarea",
+  "binding": "react",
+  "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 { Textarea, TextareaDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "textarea, or the element render returns",
+          "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."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Textarea",
+          "description": "Makes the value controlled for the life of the component. Without it the element keeps its own value, and a native form reset restores defaultValue."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Textarea",
+          "description": "The value an uncontrolled textarea starts from. It is read once and written to the element, which is what a form reset returns to."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "Textarea, TextareaDefaultsProvider",
+          "description": "The step of the control scale. When unset, the textarea takes the size of its field, then of the provider. 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": "Textarea, TextareaDefaultsProvider",
+          "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 of the provider."
+        },
+        {
+          "name": "mono",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Textarea, TextareaDefaultsProvider",
+          "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": "Textarea, TextareaDefaultsProvider",
+          "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": "Textarea",
+          "description": "Grows the textarea with its content through CSS field-sizing, with no measurement in script. rows becomes the floor and maxRows the ceiling."
+        },
+        {
+          "name": "rows",
+          "type": "number",
+          "defaultValue": "3",
+          "appliesTo": "Textarea",
+          "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": "Textarea",
+          "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": "Textarea",
+          "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": "Textarea",
+          "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": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "Textarea",
+          "description": "Unset rather than false, so the textarea follows the field around it. When set, it wins over the field and writes the native disabled."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "Textarea",
+          "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."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "Textarea",
+          "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": "Textarea",
+          "description": "The element’s own attribute, passed through unchanged; Textarea never writes it. Inside a required field, the textarea receives aria-required instead."
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: TextareaRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Textarea",
+          "description": "Renders another element in place of the textarea and passes it every attribute, including the two custom properties that carry rows and maxRows. The props are typed as HTMLAttributes<HTMLElement>, so they spread onto any element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTextAreaElement>",
+          "defaultValue": "—",
+          "appliesTo": "Textarea",
+          "description": "Reaches the textarea element. focus(), select() and setSelectionRange() are the element’s own, so Textarea adds no imperative handle."
+        },
+        {
+          "name": "TextareaDefaultsProvider",
+          "type": "{ size, variant, mono, resize }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets size, variant, mono and resize once for every textarea under it. A textarea that states a value keeps it, and a textarea inside a field takes the field’s size over the provider’s."
+        },
+        {
+          "name": "useField()",
+          "type": "() => FieldContextValue | undefined",
+          "defaultValue": "—",
+          "appliesTo": "inside a Field",
+          "description": "What Textarea reads inside a Field to wire itself: the identifier, the description, the disabled, read-only, invalid and required states, and the channel it publishes its count on."
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: string, request: 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 count does not move, and an uncontrolled element keeps what was typed."
+        },
+        {
+          "name": "onChange, onInput, onFocus, onBlur",
+          "payload": "the element’s own events",
+          "when": "Whenever the textarea fires them. Textarea composes your handler with its own instead of replacing it: yours runs first, and always runs."
+        }
+      ],
+      "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. The native attribute turns on browser constraint validation and changes how the form submits; write required on the textarea to opt in, and it is kept. disabled and readonly are the native attributes.",
+        "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": "tsx",
+      "source": "<Field>\n  <FieldLabel>Observações</FieldLabel>\n  <Textarea rows={3} placeholder=\"Descreva o que aconteceu\" />\n  <FieldDescription>Aparece no histórico do chamado.</FieldDescription>\n</Field>;\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": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { Textarea } from '@slotted/react/textarea';\n\nexport default function TextareaSizes() {\n  return (\n    <Stack gap={5}>\n      <Field size=\"sm\">\n        <FieldLabel>Line item note</FieldLabel>\n        <Textarea rows={2} defaultValue=\"Pack the glass bottles separately.\" />\n      </Field>\n      <Field size=\"md\">\n        <FieldLabel>Order note</FieldLabel>\n        <Textarea rows={2} defaultValue=\"The customer asked for delivery before noon on Friday.\" />\n      </Field>\n      <Field size=\"lg\">\n        <FieldLabel>Message to the supplier</FieldLabel>\n        <Textarea rows={2} defaultValue=\"Please confirm the revised quantities by Wednesday.\" />\n      </Field>\n    </Stack>\n  );\n}\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": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { Textarea } from '@slotted/react/textarea';\n\nexport default function TextareaVariants() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Return reason</FieldLabel>\n        <Textarea variant=\"outline\" rows={2} defaultValue=\"Two jars arrived with broken seals.\" />\n      </Field>\n      <Field>\n        <FieldLabel>Warehouse note</FieldLabel>\n        <Textarea variant=\"subtle\" rows={2} defaultValue=\"Restock on shelf B4 after inspection.\" />\n      </Field>\n      <Field>\n        <FieldLabel>Picker comment</FieldLabel>\n        <Textarea variant=\"plain\" rows={2} defaultValue=\"Counted twice, 46 units on hand.\" />\n      </Field>\n    </Stack>\n  );\n}\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": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Textarea } from '@slotted/react/textarea';\n\nexport default function TextareaAutoSize() {\n  return (\n    <Field>\n      <FieldLabel>Picking note</FieldLabel>\n      <Textarea\n        autoSize\n        rows={2}\n        maxRows={6}\n        defaultValue=\"Use the reinforced boxes for the olive oil.\"\n      />\n      <FieldDescription>Shown to the picker on the warehouse screen.</FieldDescription>\n    </Field>\n  );\n}\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": "tsx",
+      "source": "<Textarea resize=\"block\" />;\n<Textarea resize=\"none\" />;\n<Textarea resize=\"both\" />;\n\n// autoSize wins: the handle is withdrawn rather than left to fight.\n<Textarea autoSize resize=\"both\" />;\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": "tsx",
+      "source": "import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { Textarea } from '@slotted/react/textarea';\n\nexport default function TextareaStates() {\n  return (\n    <Stack gap={5}>\n      <Field invalid required>\n        <FieldLabel>Damage report</FieldLabel>\n        <Textarea rows={2} defaultValue=\"Box dented.\" />\n        <FieldError>Describe the damage in at least 20 characters.</FieldError>\n      </Field>\n      <Field readOnly>\n        <FieldLabel>Customer note</FieldLabel>\n        <Textarea\n          rows={2}\n          defaultValue=\"Please ring the bell twice. The office is on the second floor.\"\n        />\n        <FieldDescription>Written by the customer at checkout.</FieldDescription>\n      </Field>\n      <Field disabled>\n        <FieldLabel>Carrier instructions</FieldLabel>\n        <Textarea rows={2} defaultValue=\"Leave with the building manager.\" />\n        <FieldDescription>Locked once the shipment is booked.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\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": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { Textarea } from '@slotted/react/textarea';\n\nexport default function TextareaCount() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Gift message</FieldLabel>\n        <Textarea\n          rows={2}\n          maxLength={150}\n          showCount\n          defaultValue=\"Happy anniversary to the whole team at Alfreds Futterkiste.\"\n        />\n        <FieldDescription>Printed on a card inside the box.</FieldDescription>\n      </Field>\n      <Field>\n        <FieldLabel>Product summary</FieldLabel>\n        <Textarea\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        />\n        <FieldDescription>Search results cut summaries after 120 characters.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\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": "tsx",
+      "source": "<Textarea defaultValue={jwt} rows={3} />;\n\n// overflow-wrap: anywhere in the stylesheet, so the whole string stays\n// selectable, copyable and reachable with the caret.\n<Textarea dir=\"rtl\" defaultValue=\"مرحبا بالعالم\" rows={3} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and reaching past it",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<TextareaDefaultsProvider resize=\"none\" variant=\"subtle\">\n  <Textarea autoSize />\n</TextareaDefaultsProvider>;\n\nconst ref = useRef<HTMLTextAreaElement>(null);\n<Textarea ref={ref} name=\"notes\" form=\"ticket\" />;\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": "tsx",
+      "source": "<form onSubmit={onSubmit}>\n  <Textarea name=\"notes\" rows={3} />\n  <Button type=\"submit\">Enviar</Button>\n</form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "basic",
+      "title": "basic.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Textarea } from '@slotted/react/textarea';\n\nexport default function TextareaBasic() {\n  return (\n    <Field>\n      <FieldLabel>Delivery instructions</FieldLabel>\n      <Textarea placeholder=\"Gate code, loading dock, opening hours\" />\n      <FieldDescription>Printed on the packing slip for the carrier.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "comment-composer",
+      "title": "comment-composer.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState, type SubmitEvent } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport { Textarea } from '@slotted/react/textarea';\nimport { Text } from '@slotted/react/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\nexport default function TextareaCommentComposer() {\n  const [comments, setComments] = useState(THREAD);\n  const [draft, setDraft] = useState('');\n\n  const submit = (event: SubmitEvent<HTMLFormElement>) => {\n    event.preventDefault();\n    const body = draft.trim();\n    if (body === '') return;\n    setComments((current) => [\n      ...current,\n      { id: current.length + 1, author: 'You', time: 'Just now', body },\n    ]);\n    setDraft('');\n  };\n\n  return (\n    <Stack gap={6}>\n      <Stack gap={4}>\n        {comments.map((comment) => (\n          <Stack key={comment.id} gap={1}>\n            <Inline gap={2} align=\"baseline\">\n              <Text size=\"sm\" weight=\"semibold\">\n                {comment.author}\n              </Text>\n              <Text size=\"sm\" tone=\"muted\">\n                {comment.time}\n              </Text>\n            </Inline>\n            <Text size=\"sm\">{comment.body}</Text>\n          </Stack>\n        ))}\n      </Stack>\n      <form onSubmit={submit}>\n        <Stack gap={3}>\n          <Field>\n            <FieldLabel>Comment on order 10248</FieldLabel>\n            <Textarea\n              autoSize\n              rows={2}\n              maxRows={8}\n              placeholder=\"Write an update for the team\"\n              value={draft}\n              onValueChange={setDraft}\n            />\n          </Field>\n          <Inline justify=\"end\">\n            <Button type=\"submit\">Post comment</Button>\n          </Inline>\n        </Stack>\n      </form>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { Textarea, TextareaDefaultsProvider } from '@slotted/react/textarea';\n\nexport default function TextareaDefaults() {\n  return (\n    <TextareaDefaultsProvider variant=\"subtle\" resize=\"none\">\n      <Stack gap={5}>\n        <Field>\n          <FieldLabel>Reply to the customer</FieldLabel>\n          <Textarea rows={2} defaultValue=\"Your refund was issued today.\" />\n        </Field>\n        <Field>\n          <FieldLabel>Internal note</FieldLabel>\n          <Textarea rows={2} defaultValue=\"Refund approved by finance.\" />\n        </Field>\n        <Field>\n          <FieldLabel>Escalation summary</FieldLabel>\n          <Textarea variant=\"outline\" rows={2} defaultValue=\"Second refund request this quarter.\" />\n        </Field>\n      </Stack>\n    </TextareaDefaultsProvider>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "mono",
+      "title": "mono.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Textarea } from '@slotted/react/textarea';\n\nconst PAYLOAD = `{\n  \"event\": \"order.shipped\",\n  \"orderId\": 10248,\n  \"carrier\": \"Federal Shipping\",\n  \"tracking\": \"FS-2026-0042-7731\"\n}`;\n\nexport default function TextareaMono() {\n  return (\n    <Field>\n      <FieldLabel>Test payload</FieldLabel>\n      <Textarea mono variant=\"subtle\" rows={7} spellCheck={false} defaultValue={PAYLOAD} />\n      <FieldDescription>Sent to your endpoint when you press Send test event.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "read-only",
+      "title": "read-only.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Textarea } from '@slotted/react/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\nexport default function TextareaReadOnly() {\n  return (\n    <Field>\n      <FieldLabel>Supplier terms</FieldLabel>\n      <Textarea readOnly rows={6} defaultValue={TERMS} />\n      <FieldDescription>Agreed with Exotic Liquids on 3 March 2026.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "rows",
+      "title": "rows.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { Textarea } from '@slotted/react/textarea';\n\nexport default function TextareaRows() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Gift message</FieldLabel>\n        <Textarea rows={2} resize=\"none\" defaultValue=\"Happy birthday, Laura. Enjoy the tea.\" />\n      </Field>\n      <Field>\n        <FieldLabel>Incident report</FieldLabel>\n        <Textarea rows={5} placeholder=\"What happened, when, and who was involved\" />\n      </Field>\n      <Field>\n        <FieldLabel>Reply draft</FieldLabel>\n        <Textarea resize=\"both\" placeholder=\"Drag the corner to resize in both directions\" />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState, type SubmitEvent } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { Field, FieldError, FieldLabel } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport { Textarea } from '@slotted/react/textarea';\n\nconst MIN_LENGTH = 20;\n\nfunction detailsError(value: string): string {\n  if (value === '') return 'Describe what is wrong with the item.';\n  if (value.length < MIN_LENGTH) return `Add more detail: at least ${MIN_LENGTH} characters.`;\n  return '';\n}\n\nexport default function TextareaValidation() {\n  const [details, setDetails] = useState('');\n  const [submitted, setSubmitted] = useState(false);\n  const [sent, setSent] = useState(false);\n  const error = submitted ? detailsError(details) : '';\n\n  const submit = (event: SubmitEvent<HTMLFormElement>) => {\n    event.preventDefault();\n    setSubmitted(true);\n    setSent(detailsError(details) === '');\n  };\n\n  return (\n    <form noValidate onSubmit={submit}>\n      <Stack gap={4}>\n        <Field required invalid={error !== '' ? true : undefined}>\n          <FieldLabel>What is wrong with the item?</FieldLabel>\n          <Textarea\n            value={details}\n            onValueChange={(value) => {\n              setDetails(value);\n              setSent(false);\n            }}\n          />\n          <FieldError live=\"polite\" reserve>\n            {error}\n          </FieldError>\n        </Field>\n        <Inline gap={3} align=\"center\">\n          <Button type=\"submit\">Request a return</Button>\n          {sent ? <span role=\"status\">Return requested.</span> : null}\n        </Inline>\n      </Stack>\n    </form>\n  );\n}\n",
+      "verdict": "example"
+    }
+  ]
+}