prime-ui-kit 0.7.13 → 0.9.1

package/src/components/tag-select/examples/controlled.tsx

@@ -0,0 +1,26 @@
+/** The parent owns the value: a preset button replaces the tags and the count follows them — `value`, `onValueChange`. */
+import { Button, TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const OPTIONS: TagSelectOption[] = [
+  { value: "anna", label: "Анна Смирнова", color: "blue" },
+  { value: "igor", label: "Игорь Петров", color: "green" },
+  { value: "olga", label: "Ольга Ким", color: "purple" },
+  { value: "pavel", label: "Павел Орлов", color: "orange" },
+];
+
+export default function TagSelectControlledExample() {
+  const [team, setTeam] = React.useState<string[]>(["anna"]);
+
+  return (
+    <>
+      <TagSelect label="Команда проекта" options={OPTIONS} value={team} onValueChange={setTeam} />
+      <Typography as="p" variant="body-s" tone="secondary">
+        В команде: {team.length}
+      </Typography>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setTeam(["anna", "igor", "olga"])}>
+        Добавить отдел дизайна
+      </Button.Root>
+    </>
+  );
+}

package/src/components/tag-select/examples/creatable.tsx

@@ -0,0 +1,28 @@
+/** A typed text that is not in the list becomes a new tag from the Create row or Enter — `creatable`, `onCreate`, `defaultColor`. */
+import { TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const OPTIONS: TagSelectOption[] = [
+  { value: "bug", label: "Ошибка", color: "red" },
+  { value: "feature", label: "Новая функция", color: "blue" },
+];
+
+export default function TagSelectCreatableExample() {
+  const [created, setCreated] = React.useState<string[]>([]);
+
+  return (
+    <>
+      <TagSelect
+        label="Метки"
+        options={OPTIONS}
+        creatable
+        defaultColor="purple"
+        onCreate={(value) => setCreated((prev) => [...prev, value])}
+        placeholder="Найдите или создайте метку"
+      />
+      <Typography as="p" variant="body-s" tone="secondary">
+        {created.length ? `Созданы: ${created.join(", ")}` : "Наберите новую метку и нажмите Enter"}
+      </Typography>
+    </>
+  );
+}

package/src/components/tag-select/examples/examples.module.css

@@ -1,14 +1,15 @@
-.stackNarrow {
-  width: 100%;
-  max-width: calc(var(--prime-sys-unit-1rem) * 22);
-}
+/* Layout of the TagSelect scenarios: semantic tokens only. */
 
-.stack {
+/* in-form.tsx: field → field 20, actions at the end. */
+.form {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-sys-spacing-s);
+  gap: var(--prime-space-5);
+  width: min(100%, var(--prime-modal-width-m));
 }
 
-.caption {
-  margin: 0;
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
 }

package/src/components/tag-select/examples/in-form.tsx

@@ -0,0 +1,61 @@
+/** A new task form: the required labels field is checked on submit and its error replaces the hint — `required`, `error`, `creatable`. */
+import { Button, Input, TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const LABELS: TagSelectOption[] = [
+  { value: "bug", label: "Ошибка", color: "red" },
+  { value: "feature", label: "Новая функция", color: "blue" },
+  { value: "ux", label: "UX", color: "purple" },
+];
+
+const PEOPLE: TagSelectOption[] = [
+  { value: "anna", label: "Анна Смирнова" },
+  { value: "igor", label: "Игорь Петров" },
+  { value: "olga", label: "Ольга Ким" },
+];
+
+export default function TagSelectInFormExample() {
+  const [labels, setLabels] = React.useState<string[]>([]);
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError(labels.length ? undefined : "Добавьте хотя бы одну метку");
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Typography as="h3" variant="title-m">
+        Новая задача
+      </Typography>
+      <Input.Root label="Название" required>
+        <Input.Wrapper>
+          <Input.Field name="title" placeholder="Коротко о задаче" />
+        </Input.Wrapper>
+      </Input.Root>
+      <TagSelect
+        label="Метки"
+        required
+        hint="Помогают фильтровать задачи"
+        error={error}
+        options={LABELS}
+        value={labels}
+        onValueChange={(next) => {
+          setLabels(next);
+          setError(undefined);
+        }}
+        creatable
+        placeholder="Добавить метку"
+      />
+      <TagSelect label="Наблюдатели" optional options={PEOPLE} placeholder="Добавить человека" />
+      <div className={styles.actions}>
+        <Button.Root variant="ghost" tone="neutral" type="reset">
+          Отмена
+        </Button.Root>
+        <Button.Root type="submit">Создать задачу</Button.Root>
+      </div>
+    </form>
+  );
+}

package/src/components/tag-select/examples/manage-tags.tsx

@@ -0,0 +1,34 @@
+/** Users keep their own tag dictionary: the row «⋯» menu renames, recolors or deletes an option — `onOptionUpdate`, `onOptionDelete`. */
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+import * as React from "react";
+
+const INITIAL_OPTIONS: TagSelectOption[] = [
+  { value: "telegram", label: "Telegram", color: "blue" },
+  { value: "whatsapp", label: "WhatsApp", color: "green" },
+  { value: "email", label: "Почта", color: "purple" },
+  { value: "phone", label: "Телефон", color: "orange" },
+];
+
+export default function TagSelectManageTagsExample() {
+  const [options, setOptions] = React.useState(INITIAL_OPTIONS);
+
+  return (
+    <TagSelect
+      label="Каналы связи"
+      options={options}
+      defaultValue={["telegram", "email"]}
+      creatable
+      onOptionUpdate={(value, updates) =>
+        setOptions((prev) =>
+          prev.some((option) => option.value === value)
+            ? prev.map((option) => (option.value === value ? { ...option, ...updates } : option))
+            : [...prev, { value, label: updates.label ?? value, color: updates.color }],
+        )
+      }
+      onOptionDelete={(value) =>
+        setOptions((prev) => prev.filter((option) => option.value !== value))
+      }
+      placeholder="Канал связи"
+    />
+  );
+}

package/src/components/tag-select/examples/many-tags.tsx

@@ -0,0 +1,20 @@
+/** More tags than fit: at rest one row with «+N», focused every tag on up to three wrapped rows that scroll — `defaultValue`. */
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+
+const CITIES: TagSelectOption[] = [
+  { value: "msk", label: "Москва", color: "blue" },
+  { value: "spb", label: "Санкт-Петербург", color: "teal" },
+  { value: "kzn", label: "Казань", color: "green" },
+  { value: "ekb", label: "Екатеринбург", color: "orange" },
+  { value: "nsk", label: "Новосибирск", color: "purple" },
+  { value: "sam", label: "Самара", color: "pink" },
+  { value: "ufa", label: "Уфа", color: "sky" },
+  { value: "krs", label: "Красноярск", color: "yellow" },
+  { value: "vvo", label: "Владивосток", color: "red" },
+];
+
+const PICKED = ["msk", "spb", "kzn", "ekb", "nsk", "sam", "ufa"];
+
+export default function TagSelectManyTagsExample() {
+  return <TagSelect label="Города доставки" options={CITIES} defaultValue={PICKED} />;
+}

package/src/components/tag-select/examples/overview.tsx

@@ -0,0 +1,21 @@
+/** A labelled tag field: focus opens the list, typing filters it, picked tags become chips — `label`, `options`. */
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+
+const OPTIONS: TagSelectOption[] = [
+  { value: "design", label: "Дизайн", color: "purple" },
+  { value: "backend", label: "Бэкенд", color: "blue" },
+  { value: "frontend", label: "Фронтенд", color: "sky" },
+  { value: "urgent", label: "Срочно", color: "red" },
+];
+
+export default function TagSelectOverviewExample() {
+  return (
+    <TagSelect
+      label="Метки задачи"
+      options={OPTIONS}
+      defaultValue={["design"]}
+      placeholder="Добавить метку"
+      labels={{ panelHint: "Выберите метку" }}
+    />
+  );
+}

package/src/components/tag-select/examples/sizes.tsx

@@ -0,0 +1,27 @@
+/** Every size tier with two picked tags; chips sit one tier below the field — `size`. */
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+const OPTIONS: TagSelectOption[] = [
+  { value: "design", label: "Дизайн", color: "purple" },
+  { value: "backend", label: "Бэкенд", color: "blue" },
+  { value: "urgent", label: "Срочно", color: "red" },
+];
+
+export default function TagSelectSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <TagSelect
+          key={size}
+          size={size}
+          label={size}
+          options={OPTIONS}
+          defaultValue={["design", "backend"]}
+          labels={{ panelHint: "Выберите метку" }}
+        />
+      ))}
+    </>
+  );
+}

package/src/components/tag-select/examples/states.tsx

@@ -0,0 +1,24 @@
+/** A default field next to a disabled and an invalid one, with a disabled option in the list — `disabled`, `invalid`. */
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+
+const OPTIONS: TagSelectOption[] = [
+  { value: "msk", label: "Москва", color: "blue" },
+  { value: "spb", label: "Санкт-Петербург", color: "teal" },
+  { value: "kzn", label: "Казань", color: "green" },
+  { value: "kgd", label: "Калининград — склад закрыт", disabled: true },
+];
+
+export default function TagSelectStatesExample() {
+  return (
+    <>
+      <TagSelect
+        label="default"
+        options={OPTIONS}
+        defaultValue={["msk"]}
+        placeholder="Добавить город"
+      />
+      <TagSelect label="disabled" options={OPTIONS} defaultValue={["msk", "kzn"]} disabled />
+      <TagSelect label="invalid" options={OPTIONS} invalid placeholder="Добавить город" />
+    </>
+  );
+}

package/src/components/tag-select/examples/validation.tsx

@@ -0,0 +1,35 @@
+/** Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. */
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+
+const CITIES: TagSelectOption[] = [
+  { value: "msk", label: "Москва", color: "blue" },
+  { value: "spb", label: "Санкт-Петербург", color: "teal" },
+  { value: "kzn", label: "Казань", color: "green" },
+];
+
+const PEOPLE: TagSelectOption[] = [
+  { value: "anna", label: "Анна Смирнова" },
+  { value: "igor", label: "Игорь Петров" },
+];
+
+export default function TagSelectValidationExample() {
+  return (
+    <>
+      <TagSelect
+        label="Города доставки"
+        required
+        hint="Склады, откуда отправляем заказы"
+        options={CITIES}
+        defaultValue={["msk"]}
+      />
+      <TagSelect
+        label="Регионы"
+        required
+        error="Добавьте хотя бы один регион"
+        options={CITIES}
+        placeholder="Добавить регион"
+      />
+      <TagSelect label="Наблюдатели" optional options={PEOPLE} placeholder="Добавить человека" />
+    </>
+  );
+}

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
+**Kind:** field
 
-## 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";
-
-export function Example() {
-  return (
-    <Textarea.Root placeholder="Notes" name="notes">
-      <Textarea.Hint>Optional hint below the field.</Textarea.Hint>
-    </Textarea.Root>
-  );
-}
 ```
 
-## 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. |
+## 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
+
+<!-- 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 three lines, no scrollbar, no resize handle). `false` → fixed height (three lines or `rows`) with native vertical resize. |
+| `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. |
+| `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>`. |
+
+## 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 | |
+
+### 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 |
+| 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: 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; Enter inserts a line break instead of submitting the form. |
+
+### 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"`).
+
+### 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. |
+
+## 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) | Required and optional markers, a hint, an error 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 next to a fixed one with a resize handle — `autoResize`, `rows`. |
+| [without-focus-ring.tsx](examples/without-focus-ring.tsx) | A single reply composer where the caret and the lighter fill show focus — `focusRing`. |
+| [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 and its error does not shift the form — `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.
+- Only a placeholder, no label → add `label` or `aria-label`.
 
 ## Related
-
-- [Input](../input/COMPONENT.md)
-- [Label](../label/COMPONENT.md)
-- [Hint](../hint/COMPONENT.md)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
+- **See also:** [Input](../input/COMPONENT.md) — the same field contract for one line; [CodeBlock](../code-block/COMPONENT.md)