prime-ui-kit 0.7.13 → 0.9.0

package/src/components/textarea/COMPONENT.md

@@ -1,133 +1,159 @@
 # Textarea
 
-**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
+**Category:** inputs
 
-## Canonical
+> Multi-line text field with label, hint, error and a character counter; grows with its content by default.
 
-- **Purpose:** multiline text with optional in-control **character counter**, and optional **hint** or **error** below, wired through **`aria-describedby`** on the native **`textarea`**.
-- **Skeleton vs Input:** unlike [Input](../input/COMPONENT.md) (`Root` → `Wrapper` → **`Field`**), **Textarea** uses a single **`Textarea.Root`**: an outer **`.field`** stack wraps a bordered **`label`** (the field chrome) that owns the native **`<textarea>`**—there is **no** separate `Textarea.Field` export; pass standard textarea attributes on **`Root`**.
-- **Children:** **`Textarea.CharCounter`** only as a **direct** child of **`Root`** (footer inside the chrome). **`Textarea.Hint`** / **`Textarea.Error`** as direct children **after** that chrome (siblings of the inner `label`, not wrapped around `CharCounter`).
-- **Size:** `size` ∈ `s | m | l | xl` only on **`Textarea.Root`**; the HTML **`size`** attribute is omitted from the public typing (reserved).
-- **Scenario grid:** see [**Scenarios (playground + `examples/`)**](#scenarios-playground--examples) below — order matches **`playground/sections/TextareaSection.tsx`** and **`playground/snippets/textarea/*.tsx`**.
+## When to use
+- Free-form text longer than one line: comments, descriptions, reviews, support requests, notes.
+- Text with a length limit shown to the user (`Textarea.Counter`).
 
+## When not to use
+- A single-line value (name, e-mail, search) → use [Input](../input/COMPONENT.md).
+- A one-time code split into cells → use [DigitInput](../digit-input/COMPONENT.md).
+- Read-only code or logs → use [CodeBlock](../code-block/COMPONENT.md).
+
+## Import
 ```tsx
 import { Textarea } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Textarea.Root       label row → field box with the native <textarea> → support row (hint | error · counter)
+Textarea.Counter    goes into Textarea.Root `counter` (right side of the support row)
+```
+Unlike Input, Textarea has no Wrapper/Field parts: `Textarea.Root` renders the whole field and takes native `<textarea>` props directly.
+
+## API
+
+### Textarea.Root
+`forwardRef` to `HTMLTextAreaElement`. + native `<textarea>` props except `size` and `children` (`value`, `defaultValue`, `onChange`, `placeholder`, `rows`, `maxLength`, `name`, `disabled`, `readOnly`, `required`, `aria-label`, …); they go to the `<textarea>`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier for text, padding, radius, label and hint. One line of text sits exactly like an Input of the same size. |
+| `invalid` | `boolean` | `false` | Danger inset ring, `aria-invalid`. A non-empty `error` implies it. |
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring on the field box (`data-focus-ring="false"`); focus, keyboard, ARIA and the invalid ring stay. |
+| `label` | `ReactNode` | — | Label above the field (`<label htmlFor>`). Without it, set `aria-label`. |
+| `required` | `boolean` | — | Native `required` on the textarea and a red `*` after the label. |
+| `optional` | `boolean` | `false` | Muted marker right after the label text (`labels.optional`). |
+| `hint` | `ReactNode` | — | Help text under the field; hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `counter` | `ReactNode` | — | Right side of the support row, usually `<Textarea.Counter />`. |
+| `reserveSupportRow` | `boolean` | `false` | Always render the support row, so an appearing error does not shift the layout. |
+| `autoResize` | `boolean` | `true` | Height follows the content (minimum three lines, no scrollbar, no resize handle). `false` → fixed height (minimum three lines or `rows`) with native vertical resize. |
+| `onValueChange` | `(value: string) => void` | — | Called with the new string; native `onChange` still fires first. |
+| `labels` | `Partial<TextareaLabels>` | see Accessibility | Built-in strings. |
+| `id` | `string` | auto (`useId`) | Id of the textarea; hint id `${id}-hint`, error id `${id}-error`. |
+| `aria-describedby` | `string` | — | Merged before the hint/error ids. |
+| `className` | `string` | — | Class on the visible field box (not on the outer wrapper). |
+
+### Textarea.Counter
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `current` | `number` | — (required) | Current length. |
+| `max` | `number` | — (required) | Limit; `current > max` turns the counter danger (`data-invalid="true"`). Add `maxLength` on the root for a hard limit. |
+| `className` | `string` | — | Class on the `<span>`. |
+
+## Variants
+Textarea has no `variant` or `tone`: one field treatment (fill, no visible border).
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | Text 12/16, padX 8, radius 6, label 12/16, hint 12/16 | Dense panels next to `xs` controls | |
+| `s` | Text 13/20, padX 8, radius 8, label 12/16, hint 12/16 | Compact side panels, comments in lists | |
+| `m` | Text 14/20, padX 12, radius 8, label 13/20, hint 12/16 | Regular forms | yes |
+| `l` | Text 16/24, padX 12, radius 10, label 14/20, hint 13/20 | Spacious forms, long reading text | |
+| `xl` | Text 16/24, padX 16, radius 12, label 14/20, hint 13/20 | Hero forms next to `xl` inputs | |
+
+**Sizes:** vertical padding = (control height − line height) / 2, so the first line aligns with an [Input](../input/COMPONENT.md) of the same size in the next column. Use the same size as the other fields of the form.
+
+### autoResize
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `true` | Box grows line by line with the text, minimum three lines, no resize handle | Comments, descriptions — most cases | yes |
+| `false` | Fixed height (`rows` or three lines), native vertical resize handle, scrolls inside | Very long text where the page must not grow, or a fixed layout | |
+
+### Visual flags
+| Flag | Looks like | Use when | Default |
+|---|---|---|---|
+| `focusRing={false}` | No focus ring; focus fill and caret remain | A single composer field where focus is obvious | `true` |
+| `reserveSupportRow` | Empty support row of hint height | Live validation, fields side by side | `false` |
+| `required` / `optional` | Red `*` / muted «необязательно» after the label | Mark the minority of the form | — / `false` |
+
+**Combinations**
+- Recommended: `counter` + `maxLength` for a hard limit; `counter` without `maxLength` for a soft limit that shows overflow; `reserveSupportRow` + `error` for validation on submit.
+- Pointless: `hint` and `error` at once (error replaces hint); `required` with `optional`.
+- Forbidden: `focusRing={false}` on regular form fields (WCAG 2.4.7).
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| hover | — | fill darkens (not when focused, disabled or read-only) |
+| focus | keyboard focus | focus fill and inset focus ring on the field box; clicking the box padding focuses the textarea |
+| no focus ring | `focusRing={false}` | `data-focus-ring="false"` on the field box |
+| invalid | `invalid` or non-empty `error` | `data-invalid="true"` on the outer wrapper and the field box, `aria-invalid="true"`, danger ring |
+| disabled | `disabled` | `data-disabled="true"` on the field box, disabled fill and text; label and hint dimmed |
+| read-only | `readOnly` | `data-readonly="true"` on the field box, no hover, default cursor |
+| reserved support row | `reserveSupportRow` | `data-reserve="true"` on the support row |
+| counter over limit | `current > max` | `data-invalid="true"` on `Textarea.Counter` |
+
+`data-size` is set on the outer wrapper and the field box. Controlled: `value` + `onValueChange` (or `onChange`). Uncontrolled: `defaultValue`.
+
+## Layout & spacing
+- Label → field: tier `label-gap` (`--prime-space-1` on xs/s, `--prime-space-2` on m–xl); field → support row: `--prime-space-1`.
+- Field → field in a form: `--prime-space-5`; group → actions: `--prime-space-8`.
+- Width is always `100%` of the parent; set the width with the layout column.
+- Long words wrap (`overflow-wrap: anywhere`), so the field never overflows horizontally.
+
+## Accessibility
+- `label` renders `<label htmlFor>` bound to the textarea; without it set `aria-label`. A placeholder never replaces the label.
+- Hint and error are linked via `aria-describedby`; the error replaces the hint.
+- The field box is a `<div>`, not a `<label>`, so counter and hint never leak into the accessible name.
+- `Textarea.Counter` shows `12/280` visually and announces `labels.counter` (`aria-live="polite"`).
+
+| `labels` key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the label when `optional` |
+| `counter` | `"{current} из {max} символов"` | Screen-reader text of `Textarea.Counter`; `{current}` and `{max}` are replaced |
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [sizes.tsx](examples/sizes.tsx) | `xs`…`xl` with label and hint | Picking a size |
+| [with-label.tsx](examples/with-label.tsx) | `required`, `optional`, custom `labels.optional`, `aria-label` without a visible label | Marking fields |
+| [hint-and-error.tsx](examples/hint-and-error.tsx) | Hint vs error replacing it | Validation messages |
+| [states.tsx](examples/states.tsx) | Empty, filled, error, read-only, disabled | Checking all states |
+| [surfaces.tsx](examples/surfaces.tsx) | Fill following the surface | Fields on canvas vs in cards/overlays |
+| [controlled.tsx](examples/controlled.tsx) | `value` + `onValueChange` with `Textarea.Counter` | Length-limited text |
+| [reserved-support-row.tsx](examples/reserved-support-row.tsx) | With and without `reserveSupportRow` while toggling an error | Validation without layout shift |
+| [height-and-limits.tsx](examples/height-and-limits.tsx) | `autoResize` vs `autoResize={false}`, soft vs hard limit | Choosing height and limit behaviour |
+| [in-form.tsx](examples/in-form.tsx) | Support request form in a card with Input, Textarea and actions | Form reference |
 
-export function Example() {
+```tsx
+import { Textarea } from "prime-ui-kit";
+
+export function CommentField() {
   return (
-    <Textarea.Root placeholder="Notes" name="notes">
-      <Textarea.Hint>Optional hint below the field.</Textarea.Hint>
-    </Textarea.Root>
+    <Textarea.Root
+      label="Комментарий"
+      optional
+      placeholder="Пожелания к заказу"
+      hint="Курьер увидит этот текст."
+    />
   );
 }
 ```
 
-## Extended
-
-### About
-
-A composite multiline field: native `textarea` inside bordered field chrome, optional footer for a character counter, and optional hint or error lines below wired through `aria-describedby`.
-
-**When to use**
-
-- Long or growing text in forms, feedback, notes, descriptions, and comments where a single line is not enough.
-- Flows that need a built-in counter, hint, or error message aligned with the same sizing scale as other controls.
-- Layouts where auto-growing height (`autoResize`) should track content without manual `rows` tuning.
-
-**When not to use**
-
-- Single-line values — use [Input](../input/COMPONENT.md).
-- Rich text or embedded formatting — use a dedicated editor component.
-- When the visible label must sit only above the chrome — pair [Label](../label/COMPONENT.md) with a stable **`id`** on **`Textarea.Root`** (see [`./examples/02-comment.tsx`](./examples/02-comment.tsx)); do not nest a second `label` around the control.
-
-### Composition
-
-- **`Textarea.Root`** — outer `div` (`.field`) with `data-size`, `TextareaProvider`, and `ControlSizeProvider`. The native `textarea` sits inside a `label` (`htmlFor` → input id) with bordered `.control` styling; when `autoResize` is true, the textarea is wrapped so `data-value` can drive height.
-- **`Textarea.CharCounter`** — must be a **direct** child of `Root`; implementation partitions children by reference equality to `Textarea.CharCounter` and renders matching nodes in the control footer.
-- **`Textarea.Hint`** / **`Textarea.Error`** — direct children of `Root`, **not** passed as `CharCounter`; they render after the `label` and register ids merged into the textarea’s `aria-describedby`.
-
-### Scenarios (playground + `examples/`)
-
-Live demos use **`playground/snippets/textarea/*.tsx`** (see **`playground/sections/TextareaSection.tsx`**). The table lists the same scenarios with package-oriented copies under **`examples/`** (aligned with those snippets; order matches the playground section).
-
-| Scenario | What it shows | `examples/` |
-|----------|---------------|-------------|
-| Sizes | Four **`size`** values (`s`–`xl`), each field with a **`Textarea.Hint`** naming the tier. | [`examples/sizes.tsx`](examples/sizes.tsx) |
-| Variants | **`variant="default"`** vs **`variant="error"`** with **`Textarea.Error`** (`aria-describedby`, invalid styling). | [`examples/variants.tsx`](examples/variants.tsx) |
-| States | Hint, **`disabled`**, **`readOnly`**, and native **`required`** on the textarea. | [`examples/states.tsx`](examples/states.tsx) |
-| Controlled | Parent **`value`** / **`onChange`**; live length in **`Textarea.Hint`**. | [`examples/controlled.tsx`](examples/controlled.tsx) |
-| Composition | **`Typography`** section title, counter + hint, second root with **`Textarea.Error`**. | [`examples/composition.tsx`](examples/composition.tsx) |
-| Full width | Narrow card-style parent; root spans the track (**`width: 100%`**, **`min-width: 0`** on `.field`). | [`examples/full-width.tsx`](examples/full-width.tsx) |
-| Features | Default **`autoResize`**, **`autoResize={false}`**, **`CharCounter`**, **`data-overflow`**, **`maxLength`** + counter. | [`examples/features.tsx`](examples/features.tsx) |
-
-### Additional narrative examples
-
-- [`./examples/01-support-ticket.tsx`](./examples/01-support-ticket.tsx) — Support form: long description with counter, hint, and **`maxLength`** cap.
-- [`./examples/02-comment.tsx`](./examples/02-comment.tsx) — Order comment: **Label** + **`Textarea.Root`** with shared **`id`**, counter, and logistics hint.
-
-**LLM note:** Prefer reading the runnable files under `./examples/*.tsx` for full scenarios, prop combinations, and composition patterns; this page keeps the contract (rules + API tables) authoritative.
-
-### Rules
-
-- **Controlled vs uncontrolled:** pass **`value`** with **`onChange`** / **`onInput`** as needed for controlled text; omit **`value`** and optionally set **`defaultValue`** for uncontrolled usage.
-- **`autoResize`** defaults to **`true`**: input events update a wrapper `data-value` mirror; set **`autoResize={false}`** to rely on fixed height / native resize behavior.
-- **Min height:** design tokens define the **minimum inner** height (`token − 2×padding` on the `::after` mirror); the bordered shell height follows padding + that inner block. The mirror uses the **same** `font-size` / `line-height` as the native `textarea` so row height matches wrapped text (no growing empty band below the last line). The shell does **not** duplicate `min-height` with `flex-grow` on inner stacks — that used to stretch the field below the mirrored content.
-- **`variant="error"`** or mounting **`Textarea.Error`** sets invalid styling; **`aria-invalid`** defaults from that unless overridden.
-- **`aria-describedby`** you pass is **merged** with auto-added hint and error ids (your ids first, then hint and error when those parts mount).
-- **`disabled`** / **`readOnly`** on `Root` flow to the native textarea; **`Textarea.Hint`** switches to a disabled visual variant when either is true.
-- Do not pass **`size`** as a DOM attribute on the textarea — it is omitted from the element API and reserved for **`Textarea.Root`** (`"s"` \| `"m"` \| `"l"` \| `"xl"`).
-- **`Textarea.CharCounter`** is only recognized as an immediate child of **`Root`**; arbitrary wrappers around it will not land in the footer.
-- Counter overflow (**`current` > `max`**) sets **`data-overflow="true"`** on the counter for styling; it does not block typing by itself (pair with **`maxLength`** if you need a hard cap).
-- The counter uses **`aria-live="polite"`** so count updates do not interrupt typing.
-- **Full width:** the `.field` root uses **`width: 100%`** and **`min-width: 0`** (same idea as Input). Place **`Textarea.Root`** inside a parent that spans the desired column or card width.
-- There is no **`asChild`** or polymorphic root — structure is fixed.
-
-### API
-
-#### Textarea.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| variant | `"default" \| "error"` | `"default"` | no | Visual invalid emphasis; combines with `aria-invalid` and `Textarea.Error` registration. |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Control scale (padding, type, min height). |
-| autoResize | `boolean` | `true` | no | When true, height follows content via wrapper `data-value`; when false, no auto-grow wrapper. |
-| id | `string` | `useId()` | no | Stable id for the textarea; outer `label` uses `htmlFor` pointing here. |
-| className | `string` | — | no | Extra class on the visible field shell: bordered **`label`** (`.control`) with state **`data-*`** attributes. |
-| disabled | `boolean` | — | no | Native disabled state. |
-| readOnly | `boolean` | — | no | Native read-only state. |
-| value | `string` | — | no | Controlled value. |
-| defaultValue | `string` | — | no | Uncontrolled initial value. |
-| onInput | `React.FormEventHandler<HTMLTextAreaElement>` | — | no | Fires after internal `data-value` sync when `autoResize` is on. |
-| aria-describedby | `string` | — | no | Merged with hint/error ids when those parts mount. |
-| aria-invalid | `Booleanish` | from variant / error | no | Explicit invalidity over heuristics. |
-| children | `React.ReactNode` | — | no | `CharCounter` in the footer; `Hint` / `Error` after the `label`. |
-| …rest | `Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "size">` | — | no | Standard textarea attributes (`placeholder`, `rows`, `maxLength`, `required`, `onChange`, `onInput`, `name`, `autoComplete`, etc.). |
-
-#### Textarea.CharCounter
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| current | `number` | — | yes | Current character count. |
-| max | `number` | — | yes | Displayed limit; overflow when `current > max` sets `data-overflow="true"`. |
-
-#### Textarea.Hint
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Hint copy. |
-| className | `string` | — | no | Extra class on the underlying `Hint.Root`. |
-| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` comes from context. |
-
-#### Textarea.Error
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Error copy. |
-| className | `string` | — | no | Extra class on the underlying `Hint.Root`. |
-| …rest | `Omit<React.HTMLAttributes<HTMLParagraphElement>, "id">` | — | no | Paragraph attributes; `id` comes from context. |
+## Mistakes
+- `<Textarea.Root><textarea /></Textarea.Root>` → Textarea.Root renders the textarea itself; pass native props to the root.
+- Counter without `maxLength` when the limit is hard → add `maxLength` so extra input is blocked.
+- `className` expected on the outer wrapper → it lands on the field box; wrap the root in your own element for layout.
+- Expecting a fixed height with the default `autoResize` → set `autoResize={false}` (and `rows`) for a fixed box with a resize handle.
+- Only a placeholder, no label → add `label` or `aria-label`.
 
 ## Related
-
-- [Input](../input/COMPONENT.md)
-- [Label](../label/COMPONENT.md)
-- [Hint](../hint/COMPONENT.md)
+- [Input](../input/COMPONENT.md) — same field contract for one line.
+- [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — rendered by `label`, `hint`, `error`.

package/src/components/textarea/examples/controlled.tsx

@@ -1,17 +1,25 @@
+/** Controlled `value` + `onValueChange` with the text length passed to `Textarea.Counter`. Use it for length-limited text such as reviews. */
 import { Textarea } from "prime-ui-kit";
 import * as React from "react";
 
-/** Parent-owned `value` / `onChange`; character count in `Textarea.Hint`. */
+import styles from "./examples.module.css";
+
+const MAX = 280;
+
 export default function TextareaControlledExample() {
-  const [notes, setNotes] = React.useState("Draft text is stored in parent state.");
+  const [text, setText] = React.useState("Курьер приехал раньше срока, всё целое.");
 
   return (
-    <Textarea.Root
-      value={notes}
-      onChange={(e) => setNotes(e.target.value)}
-      placeholder="Type here…"
-    >
-      <Textarea.Hint>Characters: {notes.length}</Textarea.Hint>
-    </Textarea.Root>
+    <div className={styles.column}>
+      <Textarea.Root
+        label="Отзыв о доставке"
+        value={text}
+        onValueChange={setText}
+        maxLength={MAX}
+        placeholder="Что понравилось, что нет"
+        hint="Отзыв появится после модерации."
+        counter={<Textarea.Counter current={text.length} max={MAX} />}
+      />
+    </div>
   );
 }

package/src/components/textarea/examples/examples.module.css

@@ -1,33 +1,60 @@
-.stack {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-m);
+/* Layout helpers for the Textarea examples. Semantic tokens only. */
+
+.sizesGrid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--prime-space-16) * 2)), 1fr));
+  align-items: start;
+  gap: var(--prime-space-5);
+  width: 100%;
 }
 
-.compositionStack {
+.column {
   display: grid;
-  gap: var(--prime-sys-spacing-x3);
-  max-width: min(100%, 28rem);
+  gap: var(--prime-space-5);
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
 }
 
-.blockSpacer {
-  margin-top: var(--prime-sys-spacing-l);
+.pair {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--prime-panel-min-width)), 1fr));
+  align-items: start;
+  gap: var(--prime-space-5);
   width: 100%;
+  max-width: var(--prime-modal-width-m);
+}
+
+.cell {
+  display: grid;
+  gap: var(--prime-space-2);
   min-width: 0;
 }
 
-.labelBlock {
+/* Demo block below the field that shows whether the layout shifts. */
+.marker {
+  padding: var(--prime-space-2) var(--prime-space-3);
+  border-radius: var(--prime-radius-s);
+  background: var(--prime-color-fill-subtle);
+}
+
+.card {
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
+}
+
+.form {
+  display: grid;
+  gap: var(--prime-space-5);
+}
+
+.actions {
   display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-s);
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
 }
 
-.fullWidthCard {
-  box-sizing: border-box;
+/* Fills its surface tile like Input does, so no stray gap remains on the right. */
+.surfaceField {
   width: 100%;
-  max-width: min(100%, 22rem);
-  padding: var(--prime-sys-spacing-x3);
-  border-radius: var(--prime-sys-radius-m);
-  border: 1px dashed var(--prime-sys-color-border-subtle);
-  background: var(--prime-sys-color-surface-raised);
 }

package/src/components/textarea/examples/height-and-limits.tsx

@@ -0,0 +1,45 @@
+/** `autoResize` (default) vs fixed height with native resize; a soft limit (counter only) vs a hard limit (`maxLength`). Use it to choose height and limit behaviour. */
+import { Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const LONG_TEXT = "Текст длиннее лимита в 30 символов — счётчик краснеет.";
+
+export default function TextareaHeightAndLimitsExample() {
+  const [soft, setSoft] = React.useState(LONG_TEXT);
+  const [hard, setHard] = React.useState("");
+
+  return (
+    <div className={styles.pair}>
+      <Textarea.Root
+        label="autoResize"
+        placeholder="Пишите несколько строк — поле растёт"
+        hint="Высота следует за текстом, минимум три строки."
+      />
+      <Textarea.Root
+        label="autoResize={false}"
+        autoResize={false}
+        rows={4}
+        placeholder="Тяните угол"
+        hint="Фиксированная высота и нативный resize."
+      />
+      <Textarea.Root
+        label="Мягкий лимит"
+        value={soft}
+        onValueChange={setSoft}
+        hint="Ввод не блокируется, счётчик показывает переполнение."
+        counter={<Textarea.Counter current={soft.length} max={30} />}
+      />
+      <Textarea.Root
+        label="Жёсткий лимит"
+        value={hard}
+        maxLength={80}
+        onValueChange={setHard}
+        placeholder="Не больше 80 символов"
+        hint="maxLength не даёт ввести лишнее."
+        counter={<Textarea.Counter current={hard.length} max={80} />}
+      />
+    </div>
+  );
+}

package/src/components/textarea/examples/hint-and-error.tsx

@@ -0,0 +1,21 @@
+/** Hint under the field and an error that replaces it; a non-empty `error` implies `invalid`. Use it for validation messages. */
+import { Textarea } from "prime-ui-kit";
+import styles from "./examples.module.css";
+
+export default function TextareaHintAndErrorExample() {
+  return (
+    <div className={styles.pair}>
+      <Textarea.Root
+        label="Описание"
+        placeholder="Расскажите о товаре"
+        hint="Покупатели видят первые две строки."
+      />
+      <Textarea.Root
+        label="Описание"
+        defaultValue="Ок"
+        hint="Покупатели видят первые две строки."
+        error="Добавьте хотя бы 20 символов."
+      />
+    </div>
+  );
+}

package/src/components/textarea/examples/in-form.tsx

@@ -0,0 +1,60 @@
+/** A support request form in a card: Input and Textarea of size `m`, required and optional fields, counter and an error after submit. Use it as a form reference. */
+import { Button, Card, Input, Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const MAX = 1000;
+
+export default function TextareaInFormExample() {
+  const [message, setMessage] = React.useState("");
+  const [sent, setSent] = React.useState(false);
+  const tooShort = sent && message.trim().length < 20;
+
+  return (
+    <Card.Root variant="panel" className={styles.card}>
+      <Card.SectionHeader>
+        <Card.SectionTitle>Обращение в поддержку</Card.SectionTitle>
+      </Card.SectionHeader>
+      <Card.Body>
+        <form
+          className={styles.form}
+          onSubmit={(e) => {
+            e.preventDefault();
+            setSent(true);
+          }}
+        >
+          <Input.Root label="Тема" required>
+            <Input.Wrapper>
+              <Input.Field placeholder="Не проходит оплата" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Textarea.Root
+            label="Опишите проблему"
+            required
+            reserveSupportRow
+            value={message}
+            maxLength={MAX}
+            onValueChange={setMessage}
+            placeholder="Что вы делали и что пошло не так"
+            hint="Не указывайте пароли и данные карты."
+            error={tooShort ? "Нужно хотя бы 20 символов." : undefined}
+            counter={<Textarea.Counter current={message.length} max={MAX} />}
+          />
+          <Textarea.Root label="Шаги воспроизведения" optional placeholder="1. Открыть корзину…" />
+          <div className={styles.actions}>
+            <Button.Root
+              variant="outline"
+              tone="neutral"
+              type="button"
+              onClick={() => setSent(false)}
+            >
+              Отмена
+            </Button.Root>
+            <Button.Root type="submit">Отправить</Button.Root>
+          </div>
+        </form>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/textarea/examples/reserved-support-row.tsx

@@ -0,0 +1,37 @@
+/** `reserveSupportRow` keeps space for the error, so the block below does not jump. Use it for fields validated on the fly. */
+import { Switch, Textarea, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function TextareaReservedSupportRowExample() {
+  const [showError, setShowError] = React.useState(false);
+  const error = showError ? "Слишком коротко." : undefined;
+
+  return (
+    <div className={styles.column}>
+      <Switch.Root checked={showError} onCheckedChange={setShowError}>
+        <Switch.Label>Показать ошибку</Switch.Label>
+      </Switch.Root>
+      <div className={styles.pair}>
+        <div className={styles.cell}>
+          <Textarea.Root label="Без резерва" placeholder="Комментарий" error={error} />
+          <Typography.Root variant="caption" tone="secondary" className={styles.marker}>
+            Этот блок сдвигается
+          </Typography.Root>
+        </div>
+        <div className={styles.cell}>
+          <Textarea.Root
+            label="reserveSupportRow"
+            reserveSupportRow
+            placeholder="Комментарий"
+            error={error}
+          />
+          <Typography.Root variant="caption" tone="secondary" className={styles.marker}>
+            Этот блок на месте
+          </Typography.Root>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/textarea/examples/sizes.tsx

@@ -1,21 +1,21 @@
+/** Five tiers side by side: text, padding, label and hint come from the size. Pick the size that matches the neighbouring fields. */
 import { Textarea } from "prime-ui-kit";
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
-/** Four `size` tiers — one field per size with a matching `Textarea.Hint` label. */
 export default function TextareaSizesExample() {
   return (
-    <>
-      <Textarea.Root size="s" placeholder="Size s">
-        <Textarea.Hint>size=&quot;s&quot;</Textarea.Hint>
-      </Textarea.Root>
-      <Textarea.Root size="m" placeholder="Size m">
-        <Textarea.Hint>size=&quot;m&quot;</Textarea.Hint>
-      </Textarea.Root>
-      <Textarea.Root size="l" placeholder="Size l">
-        <Textarea.Hint>size=&quot;l&quot;</Textarea.Hint>
-      </Textarea.Root>
-      <Textarea.Root size="xl" placeholder="Size xl">
-        <Textarea.Hint>size=&quot;xl&quot;</Textarea.Hint>
-      </Textarea.Root>
-    </>
+    <div className={styles.sizesGrid}>
+      {SIZES.map((size) => (
+        <Textarea.Root
+          key={size}
+          size={size}
+          label={`Размер ${size}`}
+          placeholder="Комментарий"
+          hint={`Подсказка яруса ${size}`}
+        />
+      ))}
+    </div>
   );
 }

package/src/components/textarea/examples/states.tsx

@@ -1,19 +1,25 @@
+/** Empty, filled, error, read-only and disabled fields. Use it to check every state of a multi-line field. */
 import { Textarea } from "prime-ui-kit";
+import styles from "./examples.module.css";
 
-/** Default with hint, `disabled`, `readOnly`, and native `required` on the textarea. */
 export default function TextareaStatesExample() {
   return (
-    <>
-      <Textarea.Root placeholder="With hint">
-        <Textarea.Hint>Default state</Textarea.Hint>
-      </Textarea.Root>
-      <Textarea.Root placeholder="Not editable" disabled>
-        <Textarea.Hint>disabled</Textarea.Hint>
-      </Textarea.Root>
-      <Textarea.Root defaultValue="Read only copy" readOnly>
-        <Textarea.Hint>readOnly</Textarea.Hint>
-      </Textarea.Root>
-      <Textarea.Root required placeholder="Required field" />
-    </>
+    <div className={styles.pair}>
+      <Textarea.Root label="Пустое" placeholder="Начните печатать" />
+      <Textarea.Root label="Заполненное" defaultValue="Позвоните за час до доставки." />
+      <Textarea.Root label="Ошибка" defaultValue="—" error="Опишите причину возврата." />
+      <Textarea.Root
+        label="Только чтение"
+        readOnly
+        defaultValue="Заявка закрыта 12 марта."
+        hint="Текст можно выделить и скопировать."
+      />
+      <Textarea.Root
+        label="Отключено"
+        disabled
+        placeholder="Недоступно"
+        hint="Поле станет доступно после выбора заказа."
+      />
+    </div>
   );
 }