prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/reference/components/textarea/COMPONENT.md

@@ -0,0 +1,206 @@
+# Textarea
+
+**Category:** inputs
+**Kind:** field
+
+> Multi-line text field with label, hint, error and a character counter; grows with its content by default.
+
+## When to use
+- Free-form text longer than one line: comments, descriptions, reviews, support requests, notes.
+- A plain growing input (`rows={1} maxRows={8}`) when a full chat composer with attachments, reply and voice is not needed.
+- 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).
+- A chat message input with send, attachments, reply / edit and voice → use [Composer](../composer/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.CopyButton   children: copies the text from the top end corner (kit-rendered)
+└─ Textarea.Action       children: the consumer's named icon action with a tooltip (button or asChild link)
+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. Its children are only the corner actions: they sit in the top end corner as full-height segments flush with the box edges, in JSX order, after the commit status of `onCommit`.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Textarea.Root
+`ref` → `HTMLTextAreaElement`. Renders the label row, the field box with the native `<textarea>` and the support row. Field-root rule for a leaf without a `Field` part: `className` goes to the field frame; `id`, `ref` and the native `<textarea>` props to the textarea.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier for text, padding, radius, label and hint. One line of text sits exactly like an Input of the same size. Without it the tier of its host (LoginForm, Popover, a panel with a size), else `m`. |
+| `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 (`aria-hidden`). |
+| `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`. |
+| `invalid` | `boolean` | `false` | Danger inset ring on the field box, `aria-invalid` on the textarea. 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. |
+| `counter` | `ReactNode` | — | Right side of the support row, usually `<Textarea.Counter />`. |
+| `reserveSupportRow` | `boolean` | `false` | Always render the support row (min height = hint line height), so an appearing error does not shift the layout. |
+| `autoResize` | `boolean` | `true` | Height follows the content (minimum `rows` lines, no resize handle; up to `maxRows` lines when set, then it scrolls inside). `false` → fixed height of `rows` lines with native vertical resize. |
+| `rows` | `number` | `3` | Minimum height in lines; with `autoResize={false}` the fixed height. `rows={1}` makes a field that starts as one line, like an Input. |
+| `maxRows` | `number` | — | With `autoResize`: the field grows up to this many lines, then scrolls inside (a chat composer: `rows={1} maxRows={8}`). Without it the field grows without a limit. |
+| `onValueChange` | `(value: string) => void` | — | Called with the new string; native `onChange` still fires first. |
+| `id` | `string` | — | Id of the `<textarea>` (auto-generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
+| `aria-describedby` | `string` | — | Merged before the hint/error ids. |
+| `onCommit` | `(value: string) => void \| Promise<void>` | — | Inline save: fires with a changed value on blur and Mod+Enter; Escape reverts. Return a Promise: the field shows a spinner and stays editable; a rejection restores the value — show why through `error`. |
+| `children` | `ReactNode` | — | Actions in the field's top end corner: `Textarea.CopyButton`, `Textarea.Action`. |
+| `labels` | `Partial<TextareaLabels>` | — | Built-in strings, see Labels. |
+| `className` | `string` | — | Class on the field frame `<div>` (label, field box, support row), as on every field root. |
+| `…rest` | `Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "size" \| "children">` | — | `value`, `defaultValue`, `onChange`, `placeholder`, `rows`, `maxLength`, `name`, `disabled`, `readOnly`, `aria-label`… |
+
+### Textarea.Counter
+`ref` → `HTMLSpanElement`. Character counter for the support row; shows `14/280` and announces `labels.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. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the `<span>`. |
+
+### Textarea.CopyButton
+`ref` → `HTMLButtonElement`. Copies the field's value from the field's top end corner (a read-only result): the copy glyph morphs into a check, the name and tooltip switch to `labels.copied` (`labels.copyError` when the clipboard refuses), a polite live region repeats it.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | `the field's value` | Text to copy instead of the field's current value. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children" \| "aria-label">` | — | `onClick`, `disabled` and the other button attributes. |
+
+### Textarea.Action
+`ref` → `HTMLButtonElement` (the child with `asChild`). The consumer's icon action in the field's top end corner: a full-height button segment named by `label`, with a tooltip and the touch hit area.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — (required) | Accessible name and tooltip («Позвонить», «Открыть профиль»). |
+| `asChild` | `boolean` | `false` | Renders the one child (an `<a href>`, a router link) with the segment's look; `disabled` becomes `aria-disabled`. |
+| `children` | `ReactNode` | — (required) | The glyph (`<Icon name>`), or with `asChild` the element that carries it. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" \| "children">` | — | `onClick`, `disabled` and the other button attributes. |
+
+## 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 (without `size`: the host's tier, else `m`) |
+| `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 from `rows` lines (three by default), no resize handle; with `maxRows` it stops there and scrolls inside | Comments, descriptions — most cases; `rows={1} maxRows={8}` for a chat input | yes |
+| `false` | Fixed height of `rows` lines, native vertical resize handle, scrolls inside | Very long text where the page must not grow, or a fixed layout | |
+
+### Flags
+| Value | 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; the control shakes once when an error arrives (`data-shake` on the frame) |
+| disabled | `disabled`, or a disabled `Fieldset` around it | `data-disabled="true"` on the field box, disabled fill and text; label and hint dimmed |
+| capped | `autoResize` with `maxRows` | `data-capped="true"` on the field box; the box grows line by line up to `maxRows` lines, then the textarea scrolls inside with the thin scrollbar |
+| 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` |
+| saving | `onCommit` returned a pending Promise | `aria-busy="true"` on the textarea, a `Spinner` in the top end corner (`data-commit="pending"`); the field stays editable; a live region says `labels.saving` |
+| saved | the Promise resolved (or `onCommit` returned nothing) | the spinner cross-fades into a success check (`data-commit="saved"`) that fades out; the live region says `labels.saved` |
+| save refused | the Promise rejected | the committed text is put back (unless the person typed on); the owner shows why through `error` |
+| copied | `Textarea.CopyButton` pressed | the copy glyph cross-fades into a check, the name becomes `labels.copied` (or `labels.copyError`) |
+
+Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+Enter (Ctrl or ⌘ with Enter — a plain Enter is a line break) commit a changed text, Escape puts the committed text back and is consumed. An unchanged text never fires. Return a Promise for a server save: pending shows a spinner while the field stays editable and Tab moves on, reject restores the text, resolve shows the check.
+
+`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: tier `hint-gap`.
+- 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
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Focuses the field, then the buttons in its corner; Enter inserts a line break instead of submitting the form. |
+| `Mod+Enter` | With `onCommit`: saves a changed text; focus stays in the field. |
+| `Escape` | With `onCommit`: puts the committed text back. |
+
+### ARIA
+- `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 and sets `aria-invalid="true"`.
+- The field box is a `<div>`, not a `<label>`, so counter and hint never leak into the accessible name; clicking its padding focuses the textarea.
+- `Textarea.Counter` shows `12/280` visually and announces `labels.counter` (`aria-live="polite"`).
+- `Textarea.Action` and `Textarea.CopyButton` are buttons (or a link with `asChild`) named by their label, with a tooltip; copying announces `labels.copied`. A press on them never moves focus into the textarea.
+- With `onCommit` the textarea carries `aria-busy="true"` while saving; a polite live region says `labels.saving`, then `labels.saved`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| 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. |
+| `copy` | `"Копировать"` | Name and tooltip of the copy button. |
+| `copied` | `"Скопировано"` | Name, tooltip and announcement once the value is copied. |
+| `copyError` | `"Не удалось скопировать"` | Name, tooltip and announcement when the clipboard refuses. |
+| `saving` | `"Сохранение"` | Announced while an `onCommit` save is pending. |
+| `saved` | `"Сохранено"` | Announced once an `onCommit` save succeeds. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A labelled multi-line field with a hint; the height follows the text — `label`, `hint`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier; text, padding, label and hint follow the tier — `size`. |
+| [states.tsx](examples/states.tsx) | A default field next to a read-only and a disabled one — `readOnly`, `disabled`. |
+| [validation.tsx](examples/validation.tsx) | Live validation: an error shakes the field as it arrives, drops in and leaves as soon as the text is fixed; required and optional markers, a hint and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. |
+| [auto-resize.tsx](examples/auto-resize.tsx) | A field that grows with its text, one that starts as a line and stops growing at five, and a fixed one with a resize handle — `autoResize`, `rows`, `maxRows`. |
+| [without-focus-ring.tsx](examples/without-focus-ring.tsx) | A single reply composer where the caret and the lighter fill show focus — `focusRing`. |
+| [edge-actions.tsx](examples/edge-actions.tsx) | A read-only generated reply with copying and a link to the template in the field's corner — `Textarea.CopyButton`, `Textarea.Action`. |
+| [inline-edit.tsx](examples/inline-edit.tsx) | A record card note that saves on blur and Mod+Enter, reverts on Escape and shows the server's refusal — `onCommit`, `error`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the text; the counter follows it and `maxLength` stops extra input — `value`, `onValueChange`, `Textarea.Counter`, `maxLength`. |
+| [in-form.tsx](examples/in-form.tsx) | Support request form: the description is checked on submit, its error leaves as soon as the text is long enough and does not shift the form, a sent request turns the button green — `required`, `error`, `reserveSupportRow`. |
+
+## 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 field box → it lands on the field frame (label, box, support row), as on every field root; size the box through the frame's layout.
+- Expecting a fixed height with the default `autoResize` → set `autoResize={false}` (and `rows`) for a fixed box with a resize handle.
+- A field that pushes the page down without end (a chat input, a note in a narrow panel) → cap it with `maxRows`; past it the field scrolls inside.
+- Only a placeholder, no label → add `label` or `aria-label`.
+- A copy `Button` under a read-only result → `Textarea.CopyButton` as a child of the root.
+- Other children than `Textarea.CopyButton` / `Textarea.Action` → the root renders the textarea itself; children are only the corner actions.
+
+## Related
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (corner actions), [Spinner](../spinner/COMPONENT.md) (`onCommit`)
+- **See also:** [Input](../input/COMPONENT.md) — the same field contract for one line; [Composer](../composer/COMPONENT.md) — a chat message input built on Textarea; [CodeBlock](../code-block/COMPONENT.md)

package/dist/skill/reference/components/textarea/examples/auto-resize.tsx

@@ -0,0 +1,28 @@
+/** A field that grows with its text, one that starts as a line and stops growing at five, and a fixed one with a resize handle — `autoResize`, `rows`, `maxRows`. */
+import { Textarea } from "prime-ui-kit";
+
+export default function TextareaAutoResizeExample() {
+  return (
+    <>
+      <Textarea.Root
+        label="Описание товара"
+        placeholder="Состав, размеры, уход"
+        hint="Высота растёт вместе с текстом, минимум три строки"
+      />
+      <Textarea.Root
+        label="Комментарий к заказу"
+        rows={1}
+        maxRows={5}
+        placeholder="Например, позвонить за час"
+        hint="Начинается с одной строки, после пяти строк прокручивается"
+      />
+      <Textarea.Root
+        label="Условия договора"
+        autoResize={false}
+        rows={5}
+        placeholder="Текст условий"
+        hint="Фиксированная высота, угол можно потянуть"
+      />
+    </>
+  );
+}

package/dist/skill/reference/components/textarea/examples/controlled.tsx

@@ -0,0 +1,21 @@
+/** The parent owns the text; the counter follows it and `maxLength` stops extra input — `value`, `onValueChange`, `Textarea.Counter`, `maxLength`. */
+import { Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+const LIMIT = 280;
+
+export default function TextareaControlledExample() {
+  const [review, setReview] = React.useState("Курьер приехал раньше срока, всё целое.");
+
+  return (
+    <Textarea.Root
+      label="Отзыв о доставке"
+      placeholder="Что понравилось, что нет"
+      hint="Отзыв появится после модерации"
+      value={review}
+      onValueChange={setReview}
+      maxLength={LIMIT}
+      counter={<Textarea.Counter current={review.length} max={LIMIT} />}
+    />
+  );
+}

package/dist/skill/reference/components/textarea/examples/edge-actions.tsx

@@ -0,0 +1,24 @@
+/** A read-only generated reply with copying and a link to the template in the field's corner — `Textarea.CopyButton`, `Textarea.Action`. */
+import { Icon, Textarea } from "prime-ui-kit";
+
+const REPLY = `Добрый день, Ирина!
+
+Счёт № 1042 на сумму 184 500 ₽ выставлен и отправлен на почту бухгалтерии. Оплатить его можно до 15 ноября.`;
+
+export default function TextareaEdgeActionsExample() {
+  return (
+    <Textarea.Root
+      label="Ответ клиенту"
+      hint="Собран из шаблона «Счёт выставлен»"
+      readOnly
+      value={REPLY}
+    >
+      <Textarea.Action label="Открыть шаблон" asChild>
+        <a href="#template-invoice-sent">
+          <Icon name="object.document" />
+        </a>
+      </Textarea.Action>
+      <Textarea.CopyButton />
+    </Textarea.Root>
+  );
+}

package/dist/skill/reference/components/textarea/examples/examples.module.css

@@ -0,0 +1,27 @@
+/* Layout of the Textarea scenarios: semantic tokens only. */
+
+/* in-form.tsx: field → field 20, group → actions 32 (foundation §1). */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-modal-width-m));
+}
+
+.formHeader {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-1);
+}
+
+.formFields {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+}
+
+.formActions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
+}

package/dist/skill/reference/components/textarea/examples/in-form.tsx

@@ -0,0 +1,76 @@
+/** Support request form: the description is checked on submit, its error leaves as soon as the text is long enough and does not shift the form, a sent request turns the button green — `required`, `error`, `reserveSupportRow`. */
+import { Button, Input, Textarea, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const LIMIT = 1000;
+const MIN_LENGTH = 20;
+
+export default function TextareaInFormExample() {
+  const [message, setMessage] = React.useState("");
+  const [checked, setChecked] = React.useState(false);
+  const [sent, setSent] = React.useState(false);
+  const tooShort = message.trim().length < MIN_LENGTH;
+  // After the first submit the check is live: the error leaves as soon as the text is long enough.
+  const error = checked && tooShort ? "Опишите проблему хотя бы в 20 символах" : undefined;
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setChecked(true);
+    setSent(!tooShort);
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <div className={styles.formHeader}>
+        <Typography as="h3" variant="title-m">
+          Обращение в поддержку
+        </Typography>
+        <Typography as="p" variant="body-s" tone="secondary">
+          Ответим в течение рабочего дня.
+        </Typography>
+      </div>
+      <div className={styles.formFields}>
+        <Input.Root label="Тема" required>
+          <Input.Wrapper>
+            <Input.Field name="subject" defaultValue="Не проходит оплата счёта" />
+          </Input.Wrapper>
+        </Input.Root>
+        <Textarea.Root
+          label="Опишите проблему"
+          name="message"
+          required
+          reserveSupportRow
+          placeholder="Что вы делали и что пошло не так"
+          hint="Не указывайте пароли и данные карты"
+          error={error}
+          value={message}
+          maxLength={LIMIT}
+          onValueChange={(value) => {
+            setMessage(value);
+            setSent(false);
+          }}
+          counter={<Textarea.Counter current={message.length} max={LIMIT} />}
+        />
+      </div>
+      <div className={styles.formActions}>
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          type="reset"
+          onClick={() => {
+            setMessage("");
+            setChecked(false);
+            setSent(false);
+          }}
+        >
+          Отменить
+        </Button.Root>
+        <Button.Root type="submit" tone={sent ? "success" : "accent"}>
+          {sent ? "Отправлено" : "Отправить"}
+        </Button.Root>
+      </div>
+    </form>
+  );
+}

package/dist/skill/reference/components/textarea/examples/inline-edit.tsx

@@ -0,0 +1,42 @@
+/** A record card note that saves on blur and Mod+Enter, reverts on Escape and shows the server's refusal — `onCommit`, `error`. */
+import { Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+const SAVE_DELAY_MS = 900;
+const MAX_NOTE_LENGTH = 500;
+
+/** Stands in for the API call: a note over the limit is refused like a server validation error. */
+function saveNote(value: string) {
+  return new Promise<void>((resolve, reject) => {
+    window.setTimeout(() => {
+      if (value.length > MAX_NOTE_LENGTH) reject(new Error("Заметка длиннее 500 символов"));
+      else resolve();
+    }, SAVE_DELAY_MS);
+  });
+}
+
+export default function TextareaInlineEditExample() {
+  const [note, setNote] = React.useState(
+    "Перезвонить после согласования бюджета. Интересует годовой тариф на 40 мест.",
+  );
+  const [error, setError] = React.useState<string>();
+
+  return (
+    <Textarea.Root
+      label="Заметка по сделке"
+      hint="Сохраняется при выходе из поля и по Ctrl+Enter, Escape отменяет правку"
+      error={error}
+      value={note}
+      onValueChange={setNote}
+      onCommit={async (value) => {
+        setError(undefined);
+        try {
+          await saveNote(value);
+        } catch (reason) {
+          setError(reason instanceof Error ? reason.message : "Не удалось сохранить");
+          throw reason;
+        }
+      }}
+    />
+  );
+}

package/dist/skill/reference/components/textarea/examples/overview.tsx

@@ -0,0 +1,12 @@
+/** A labelled multi-line field with a hint; the height follows the text — `label`, `hint`. */
+import { Textarea } from "prime-ui-kit";
+
+export default function TextareaOverviewExample() {
+  return (
+    <Textarea.Root
+      label="Комментарий к заказу"
+      placeholder="Пожелания по доставке и упаковке"
+      hint="Курьер увидит этот текст"
+    />
+  );
+}

package/dist/skill/reference/components/textarea/examples/sizes.tsx

@@ -0,0 +1,20 @@
+/** Every size tier; text, padding, label and hint follow the tier — `size`. */
+import { Textarea } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function TextareaSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <Textarea.Root
+          key={size}
+          size={size}
+          label={size}
+          placeholder="Комментарий к заказу"
+          hint="Курьер увидит этот текст"
+        />
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/components/textarea/examples/states.tsx

@@ -0,0 +1,21 @@
+/** A default field next to a read-only and a disabled one — `readOnly`, `disabled`. */
+import { Textarea } from "prime-ui-kit";
+
+export default function TextareaStatesExample() {
+  return (
+    <>
+      <Textarea.Root label="default" placeholder="Причина возврата" />
+      <Textarea.Root
+        label="readOnly"
+        readOnly
+        defaultValue="Заявка закрыта 12 марта: товар принят на склад."
+      />
+      <Textarea.Root
+        label="disabled"
+        disabled
+        placeholder="Причина возврата"
+        hint="Станет доступно после выбора заказа"
+      />
+    </>
+  );
+}

package/dist/skill/reference/components/textarea/examples/validation.tsx

@@ -0,0 +1,50 @@
+/** Live validation: an error shakes the field as it arrives, drops in and leaves as soon as the text is fixed; required and optional markers, a hint and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. */
+import { Button, Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+const MIN_REASON = 20;
+
+export default function TextareaValidationExample() {
+  const [reason, setReason] = React.useState("Нет");
+  const [comment, setComment] = React.useState("Оплата частями");
+  const [commentError, setCommentError] = React.useState<string>();
+
+  const send = () => setCommentError(/\d{3,}/.test(comment) ? undefined : "Укажите номер договора");
+
+  return (
+    <>
+      <Textarea.Root
+        label="Описание задачи"
+        required
+        defaultValue="Подготовить акт сверки с поставщиком за третий квартал."
+        hint="Исполнитель увидит его в карточке задачи"
+      />
+      <Textarea.Root
+        label="Причина отказа"
+        required
+        value={reason}
+        onValueChange={setReason}
+        hint="Клиент получит её в письме"
+        error={
+          reason.trim().length < MIN_REASON
+            ? `Опишите причину хотя бы в ${MIN_REASON} символах`
+            : undefined
+        }
+      />
+      <Textarea.Root
+        label="Комментарий для бухгалтерии"
+        optional
+        reserveSupportRow
+        value={comment}
+        onValueChange={(value) => {
+          setComment(value);
+          setCommentError(undefined);
+        }}
+        error={commentError}
+      />
+      <Button.Root variant="soft" tone="neutral" onClick={send}>
+        Отправить в бухгалтерию
+      </Button.Root>
+    </>
+  );
+}

package/dist/skill/reference/components/textarea/examples/without-focus-ring.tsx

@@ -0,0 +1,12 @@
+/** A single reply composer where the caret and the lighter fill show focus — `focusRing`. */
+import { Textarea } from "prime-ui-kit";
+
+export default function TextareaWithoutFocusRingExample() {
+  return (
+    <Textarea.Root
+      focusRing={false}
+      aria-label="Ответ клиенту"
+      placeholder="Напишите ответ клиенту"
+    />
+  );
+}