prime-ui-kit 0.9.3 → 0.11.0

package/src/components/tag-select/COMPONENT.md

@@ -8,7 +8,7 @@
 ## When to use
 - Several values from a dictionary shown as removable chips: labels, cities, channels, watchers.
 - Users may add a value that is not in the list (`creatable`).
-- Users maintain the dictionary themselves: rename, recolor or delete options from the list (`onOptionUpdate`, `onOptionDelete`).
+- Users maintain the dictionary themselves: rename, recolor or delete options from the list (`onOptionUpdate`, `onOptionDelete`; a Promise from `onOptionDelete` holds the deletion for a confirmation or a request).
 
 ## When not to use
 - One value → use [Select](../select/COMPONENT.md).
@@ -27,11 +27,12 @@ TagSelect                       field frame: label · control · hint/error (sin
 ├── control                     field fill, one row at rest, wraps when focused
 │   ├── chip row                ScrollContainer: Badge chips (one tier down) · «+N» Badge · input
 │   │   └── <input role="combobox">
+│   ├── input[type=hidden] × value   with `name`
 │   └── chevron
 └── list (portal)               role="listbox", multi-select
-    ├── panel hint              labels.panelHint
-    ├── «Создать» row           with `creatable`
-    └── option row              Checkbox.Indicator · Badge [· «⋯» Button → Popover menu]
+    ├── panel hint              labels.panelHint (`""` hides it)
+    ├── «Создать» row           with `creatable`: plus icon · labels.create · preview Badge
+    └── option row              Checkbox.Indicator · Badge [· «⋯» Button → Popover menu]; picked options first
 ```
 
 ## API
@@ -49,12 +50,12 @@ TagSelect                       field frame: label · control · hint/error (sin
 | `onValueChange` | `(value: string[]) => void` | — | Called with the new list after a pick, a removal or a creation. |
 | `open` | `boolean` | — | Controlled open state of the list. |
 | `defaultOpen` | `boolean` | `false` | Initial open state, uncontrolled. |
-| `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: field click, Escape, an outside press. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: focus, a field click, typing, arrows, Escape, an outside press; typing closes it when nothing matches. |
 | `creatable` | `boolean` | `false` | A typed text that is not an option can be added (the Create row or Enter). |
-| `onCreate` | `(value: string) => void` | — | A new value was created, not picked from `options`. |
+| `onCreate` | `(value: string) => void \| Promise<void>` | — | A new value was created, not picked from `options`; it joins the selection at once. Return the save's promise: the chip waits busy; on reject it leaves again (say why with `error`). |
 | `defaultColor` | `PaletteColor` | `"gray"` | Chip color of values without an option color, created ones included. |
-| `onOptionUpdate` | `(value: string, updates: { label?: string; color?: PaletteColor }) => void` | — | Enables the row «⋯» menu with the tag name and color; `value` never changes. |
-| `onOptionDelete` | `(value: string) => void` | — | Enables «Удалить» in the row menu; the value also leaves the selection. |
+| `onOptionUpdate` | `(value: string, updates: { label?: string; color?: PaletteColor }) => void \| Promise<void>` | — | Enables the row «⋯» menu to rename and recolor a tag; `value` never changes. Return the save's promise and apply the change to `options` before it resolves; on reject the option goes back. |
+| `onOptionDelete` | `(value: string) => void \| Promise<void>` | — | Enables «Удалить» in the row menu; the value also leaves the selection. A returned Promise defers it: resolve deletes, reject keeps everything (e.g. after a confirmation). |
 | `label` | `ReactNode` | — | Field label above; names the input. |
 | `hint` | `ReactNode` | — | Support text under the field; linked by `aria-describedby`. |
 | `error` | `ReactNode` | — | Error message; replaces the hint and implies `invalid`. |
@@ -62,6 +63,7 @@ TagSelect                       field frame: label · control · hint/error (sin
 | `optional` | `boolean` | — | Muted `labels.optional` after the label. |
 | `invalid` | `boolean` | `false` | Danger inset ring and `aria-invalid`. |
 | `disabled` | `boolean` | `false` | Disabled field and chips; the list never opens. |
+| `name` | `string` | — | Form field name: one hidden input per selected value (read with `formData.getAll(name)`). |
 | `placeholder` | `string` | `""` | Text in the input while no tag is picked. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Field tier; the list uses the same tier, chips one tier down. |
 | `focusRing` | `boolean` | `true` | `false` hides the visual focus ring (`data-focus-ring="false"`), never focus or the error ring. |
@@ -86,42 +88,48 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `creatable` | a «Создать» row with the preview chip while the typed text is new | The dictionary is open | `false` |
-| `onOptionUpdate` / `onOptionDelete` | a «⋯» button on the highlighted row opening a rename / color / delete menu | Users keep their own tags | |
-| `disabled` | disabled fill, muted chips, no list | Not editable now | `false` |
+| `onOptionUpdate` / `onOptionDelete` | a «⋯» button on the highlighted row (always shown on touch screens) opening a rename / color / delete menu | Users keep their own tags | |
+| `disabled` | disabled fill, muted chips, no list | The value is read-only in this context | `false` |
 | `invalid` / `error` | danger inset ring (+ the message) | Validation failed | |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| collapsed / expanded | focus inside or the list open | `data-expanded="true"` on the control: every chip on up to three rows (then scroll with edge fades); the height animates |
+| collapsed / expanded | focus inside or the list open | `data-expanded="true"` on the control: every chip on up to three rows (then scroll with edge fades); the height animates. Focus leaving the field collapses it and clears the typed query |
 | open | focus, typing, arrows | `data-state="open"` on the control; list `data-state`, `data-side` |
 | overflow | more chips than fit at rest | a «+N» Badge button with `labels.more` and the hidden labels in `title` |
-| invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the input |
-| disabled | `disabled` | `data-disabled="true"`, native `disabled` on the input |
+| invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the input; the control shakes once when an error arrives (`data-shake` on the frame) |
+| disabled | `disabled` | `data-disabled="true"`, native `disabled` on the input and the hidden `name` inputs; never expands |
 | option highlighted / selected / disabled | keyboard and pointer / value / option `disabled` | `data-highlighted`, `aria-selected` + checked indicator, `data-disabled` |
+| option deletion pending | `onOptionDelete` returned a Promise that has not settled | `aria-busy` + `data-pending="true"` on the row, a spinner in place of «⋯», the row cannot be picked; value and options unchanged until it resolves, kept on reject |
+| option update pending | `onOptionUpdate` returned a Promise that has not settled | the new name or color shows at once (row, chip, menu); «⋯» is `loading` (`aria-busy`) while the menu stays open; on reject the option goes back and `labels.updateFailed` is announced |
+| creation pending | `onCreate` returned a Promise that has not settled | the new chip is in the selection with Badge `loading`: `aria-busy`, dimmed, a spinner in its remove segment; it cannot be removed (×, Delete, Backspace) until the answer; on reject it leaves the selection and the list and `labels.createFailed` is announced |
+| chip leaving | a chip removed by its × | the chip closes up in place (Badge's exit) and the chips after it glide in |
 
 ## Layout & spacing
 - The field is 100% wide; set the width with the layout.
 - Chips sit `--prime-space-1` apart; the chip row keeps `--prime-focus-space` so chip rings are never cut.
 - The list is at least the field width and `--prime-panel-min-width`; max height `--prime-panel-max-height`, flips near the viewport edge.
+- Pass every option: past 100 listed options the list renders only the options around the view; the highlighted option and the one whose «⋯» menu is open stay rendered, options carry `aria-posinset` / `aria-setsize`.
 
 ## Accessibility
 
 ### Keyboard
 | Key | Action |
 |---|---|
-| `ArrowDown` · `ArrowUp` | Open the list and move the highlight over the options. |
-| `Enter` | Tick or untick the highlighted option; on the Create row, create the tag. |
+| `ArrowDown` · `ArrowUp` | Open the list (when it has something to show) and move the highlight over the options. |
+| `Enter` | Tick or untick the highlighted option (the first one when nothing is highlighted); on the Create row, create the tag; in the row menu's name field, save the new name and close the menu. |
 | `Space` | Types a space: a tag may have several words. |
-| `Backspace` | In an empty input removes the last tag. |
+| `Backspace` | In an empty input removes the last tag; on a tag removes it and focuses the previous tag. |
 | `ArrowLeft` · `ArrowRight` | From the start of the input move focus over the tags and back to the input. |
-| `Delete` | On a tag removes it; focus moves to the neighbour tag. |
-| `Escape` | Closes the list. |
+| `Delete` | On a tag removes it; focus moves to the next tag, or to the input when none is left. |
+| `Escape` | Closes the row «⋯» menu if it is open, otherwise the list. |
 
 ### ARIA
 - The input is `role="combobox"` with `aria-expanded` and `aria-controls`; the list is `role="listbox"` with `aria-multiselectable`, options are `role="option"` with `aria-selected`.
 - The highlight goes through `aria-activedescendant`; the checkbox in a row is decorative.
 - A removal is announced with `labels.removed` in a live region; the remove button is named by `labels.remove`.
+- A tag being created has `aria-busy` on its chip, a row whose rename or recolor is saved has a busy «⋯»; a refused creation or change is announced with `labels.createFailed` / `labels.updateFailed`.
 - The hint and the error are linked by `aria-describedby`; the error sets `aria-invalid`.
 
 ### Labels
@@ -134,6 +142,8 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | `remove` | `"Удалить {label}"` | Accessible name of a chip's remove button; `{label}` is the tag text. |
 | `more` | `"Показать ещё {count}"` | Accessible name of the «+N» chip; `{count}` is the number of hidden tags. |
 | `removed` | `"Удалено: {label}"` | Screen-reader announcement after a tag is removed. |
+| `createFailed` | `"Не удалось создать тег «{label}»"` | Screen-reader announcement when the `onCreate` promise rejects and the new tag leaves. |
+| `updateFailed` | `"Не удалось изменить тег «{label}»"` | Screen-reader announcement when the `onOptionUpdate` promise rejects and the option goes back. |
 | `edit` | `"Изменить тег {label}"` | Accessible name of a row's «⋯» menu button. |
 | `name` | `"Название тега"` | Accessible name of the tag name field in the menu. |
 | `delete` | `"Удалить"` | Delete button in the menu. |
@@ -147,20 +157,23 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | [overview.tsx](examples/overview.tsx) | A labelled tag field: focus opens the list, typing filters it, picked tags become chips — `label`, `options`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier with two picked tags; chips sit one tier below the field — `size`. |
 | [states.tsx](examples/states.tsx) | A default field next to a disabled and an invalid one, with a disabled option in the list — `disabled`, `invalid`. |
-| [validation.tsx](examples/validation.tsx) | Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. |
-| [creatable.tsx](examples/creatable.tsx) | A typed text that is not in the list becomes a new tag from the Create row or Enter — `creatable`, `onCreate`, `defaultColor`. |
+| [validation.tsx](examples/validation.tsx) | Live validation: removing the last region shakes the field and drops the error in, adding one clears it; required and optional markers and a hint — `required`, `optional`, `hint`, `error`. |
+| [creatable.tsx](examples/creatable.tsx) | A typed text that is not in the list becomes a new tag from the Create row or Enter and is saved on the server: the chip waits busy, and a tag the server refuses leaves again — `creatable`, `onCreate`, `defaultColor`. |
 | [many-tags.tsx](examples/many-tags.tsx) | More tags than fit: at rest one row with «+N», focused every tag on up to three wrapped rows that scroll — `defaultValue`. |
-| [manage-tags.tsx](examples/manage-tags.tsx) | Users keep their own tag dictionary: the row «⋯» menu renames, recolors or deletes an option — `onOptionUpdate`, `onOptionDelete`. |
+| [manage-tags.tsx](examples/manage-tags.tsx) | Users keep their own tag dictionary on the server: the row «⋯» menu renames, recolors or deletes an option, and «⋯» spins while a change is saved — `onOptionUpdate`, `onOptionDelete`. |
+| [confirm-delete.tsx](examples/confirm-delete.tsx) | Deleting a shared tag asks first: the row waits with a spinner while the dialog is open, cancelling keeps the tag and the selection — `onOptionDelete`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the value: a preset button replaces the tags and the count follows them — `value`, `onValueChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the list: a button opens it from code, Escape or an outside press closes it — `open`, `onOpenChange`. |
-| [in-form.tsx](examples/in-form.tsx) | A new task form: the required labels field is checked on submit and its error replaces the hint — `required`, `error`, `creatable`. |
+| [in-form.tsx](examples/in-form.tsx) | A new task form: the required labels field is checked on submit, its error shakes the field and leaves once a label is added, a calm note confirms the task; the tags go with the form — `required`, `error`, `creatable`, `name`. |
 
 ## Mistakes
 - `TagSelect.Root` → TagSelect is a single export: `<TagSelect …/>`.
 - Options as JSX children → pass `options` data.
 - `onOptionUpdate` without updating your `options` → the rename disappears on the next render; keep `options` in state.
 - A TagSelect for one value → use Select.
+- Saving a created tag and taking it out of `value` yourself when the request fails → return the request's promise from `onCreate`; the chip waits and leaves on a rejection.
+- Deleting a shared tag without asking, or restoring the value by hand after a cancelled confirmation → return a Promise from `onOptionDelete` that resolves on confirm and rejects on cancel; nothing changes until it resolves.
 
 ## Related
-- **Built from:** [Badge](../badge/COMPONENT.md) (chips, «+N»), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator`), [ScrollContainer](../scroll-container/COMPONENT.md) (chip row, list), [Popover](../popover/COMPONENT.md), [Button](../button/COMPONENT.md), [Input](../input/COMPONENT.md) and [Divider](../divider/COMPONENT.md) (row menu), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (field frame)
+- **Built from:** [Badge](../badge/COMPONENT.md) (chips, «+N»), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator`), [ScrollContainer](../scroll-container/COMPONENT.md) (chip row, list), [Popover](../popover/COMPONENT.md), [Button](../button/COMPONENT.md), [Input](../input/COMPONENT.md) and [Divider](../divider/COMPONENT.md) (row menu), [VisuallyHidden](../visually-hidden/COMPONENT.md) («+N» name, removal announcement), `Icon` (chevron, plus, «⋯», delete), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (field frame); `useVirtualRows` (the window of a long list)
 - **See also:** [Select](../select/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md)

package/src/components/tag-select/examples/confirm-delete.tsx

@@ -0,0 +1,60 @@
+/** Deleting a shared tag asks first: the row waits with a spinner while the dialog is open, cancelling keeps the tag and the selection — `onOptionDelete`. */
+import { ConfirmDialog, TagSelect, type TagSelectOption } from "prime-ui-kit";
+import * as React from "react";
+
+const INITIAL_OPTIONS: TagSelectOption[] = [
+  { value: "vip", label: "VIP", color: "purple" },
+  { value: "wholesale", label: "Опт", color: "blue" },
+  { value: "overdue", label: "Просрочка", color: "red" },
+  { value: "new", label: "Новый клиент", color: "green" },
+];
+
+const CLIENTS_WITH_TAG: Record<string, number> = { vip: 12, wholesale: 48, overdue: 7, new: 31 };
+
+type Answer = { resolve: () => void; reject: () => void };
+
+export default function TagSelectConfirmDeleteExample() {
+  const [options, setOptions] = React.useState(INITIAL_OPTIONS);
+  const [open, setOpen] = React.useState(false);
+  const [target, setTarget] = React.useState<TagSelectOption>();
+  const answer = React.useRef<Answer>(null);
+
+  const askToDelete = (value: string) =>
+    new Promise<void>((resolve, reject) => {
+      answer.current = { resolve, reject };
+      setTarget(options.find((option) => option.value === value));
+      setOpen(true);
+    });
+
+  const confirm = () => {
+    setOptions((prev) => prev.filter((option) => option.value !== target?.value));
+    answer.current?.resolve();
+    answer.current = null;
+  };
+
+  return (
+    <>
+      <TagSelect
+        label="Метки клиента"
+        options={options}
+        defaultValue={["vip", "wholesale"]}
+        onOptionDelete={askToDelete}
+        placeholder="Добавить метку"
+      />
+      <ConfirmDialog.Root
+        open={open}
+        onOpenChange={(next) => {
+          setOpen(next);
+          if (next) return;
+          // Closed without the confirm: the tag stays.
+          answer.current?.reject();
+          answer.current = null;
+        }}
+        title={`Удалить метку «${target?.label ?? ""}»?`}
+        description={`Она снимется у всех клиентов с этой меткой: ${CLIENTS_WITH_TAG[target?.value ?? ""] ?? 0}.`}
+        confirmLabel="Удалить"
+        onConfirm={confirm}
+      />
+    </>
+  );
+}

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

@@ -1,4 +1,4 @@
-/** A typed text that is not in the list becomes a new tag from the Create row or Enter — `creatable`, `onCreate`, `defaultColor`. */
+/** A typed text that is not in the list becomes a new tag from the Create row or Enter and is saved on the server: the chip waits busy, and a tag the server refuses leaves again — `creatable`, `onCreate`, `defaultColor`. */
 import { TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -7,8 +7,19 @@ const OPTIONS: TagSelectOption[] = [
   { value: "feature", label: "Новая функция", color: "blue" },
 ];
 
+/** The server's answer a beat later: a label needs at least three letters. */
+function saveLabel(value: string) {
+  return new Promise<void>((resolve, reject) => {
+    setTimeout(() => {
+      if (value.length < 3) reject(new Error(`Метка «${value}» короче трёх букв`));
+      else resolve();
+    }, 900);
+  });
+}
+
 export default function TagSelectCreatableExample() {
   const [created, setCreated] = React.useState<string[]>([]);
+  const [failure, setFailure] = React.useState<string>();
 
   return (
     <>
@@ -17,7 +28,17 @@ export default function TagSelectCreatableExample() {
         options={OPTIONS}
         creatable
         defaultColor="purple"
-        onCreate={(value) => setCreated((prev) => [...prev, value])}
+        error={failure}
+        onCreate={async (value) => {
+          setFailure(undefined);
+          try {
+            await saveLabel(value);
+          } catch (error) {
+            setFailure(error instanceof Error ? error.message : String(error));
+            throw error;
+          }
+          setCreated((prev) => [...prev, value]);
+        }}
         placeholder="Найдите или создайте метку"
       />
       <Typography as="p" variant="body-s" tone="secondary">

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

@@ -10,6 +10,7 @@
 
 .actions {
   display: flex;
+  align-items: center;
   justify-content: flex-end;
   gap: var(--prime-space-2);
 }

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

@@ -1,4 +1,4 @@
-/** A new task form: the required labels field is checked on submit and its error replaces the hint — `required`, `error`, `creatable`. */
+/** A new task form: the required labels field is checked on submit, its error shakes the field and leaves once a label is added, a calm note confirms the task; the tags go with the form — `required`, `error`, `creatable`, `name`. */
 import { Button, Input, TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -19,10 +19,12 @@ const PEOPLE: TagSelectOption[] = [
 export default function TagSelectInFormExample() {
   const [labels, setLabels] = React.useState<string[]>([]);
   const [error, setError] = React.useState<string>();
+  const [saved, setSaved] = React.useState(false);
 
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
     setError(labels.length ? undefined : "Добавьте хотя бы одну метку");
+    setSaved(labels.length > 0);
   };
 
   return (
@@ -37,6 +39,7 @@ export default function TagSelectInFormExample() {
       </Input.Root>
       <TagSelect
         label="Метки"
+        name="labels"
         required
         hint="Помогают фильтровать задачи"
         error={error}
@@ -45,13 +48,34 @@ export default function TagSelectInFormExample() {
         onValueChange={(next) => {
           setLabels(next);
           setError(undefined);
+          setSaved(false);
         }}
         creatable
         placeholder="Добавить метку"
       />
-      <TagSelect label="Наблюдатели" optional options={PEOPLE} placeholder="Добавить человека" />
+      <TagSelect
+        label="Наблюдатели"
+        name="watchers"
+        optional
+        options={PEOPLE}
+        placeholder="Добавить человека"
+      />
       <div className={styles.actions}>
-        <Button.Root variant="ghost" tone="neutral" type="reset">
+        {saved ? (
+          <Typography as="p" variant="body-s" tone="secondary">
+            Задача создана
+          </Typography>
+        ) : null}
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          type="reset"
+          onClick={() => {
+            setLabels([]);
+            setError(undefined);
+            setSaved(false);
+          }}
+        >
           Отмена
         </Button.Root>
         <Button.Root type="submit">Создать задачу</Button.Root>

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

@@ -1,14 +1,17 @@
-/** Users keep their own tag dictionary: the row «⋯» menu renames, recolors or deletes an option — `onOptionUpdate`, `onOptionDelete`. */
+/** Users keep their own tag dictionary on the server: the row «⋯» menu renames, recolors or deletes an option, and «⋯» spins while a change is saved — `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: "chat", label: "Чат на сайте", color: "blue" },
   { value: "whatsapp", label: "WhatsApp", color: "green" },
   { value: "email", label: "Почта", color: "purple" },
   { value: "phone", label: "Телефон", color: "orange" },
 ];
 
+/** The server saving a change of the dictionary, a beat later. */
+const saveDictionary = () => new Promise<void>((resolve) => setTimeout(resolve, 600));
+
 export default function TagSelectManageTagsExample() {
   const [options, setOptions] = React.useState(INITIAL_OPTIONS);
 
@@ -16,15 +19,16 @@ export default function TagSelectManageTagsExample() {
     <TagSelect
       label="Каналы связи"
       options={options}
-      defaultValue={["telegram", "email"]}
+      defaultValue={["chat", "email"]}
       creatable
-      onOptionUpdate={(value, updates) =>
+      onOptionUpdate={async (value, updates) => {
+        await saveDictionary();
         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))
       }

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

@@ -1,5 +1,6 @@
-/** Required and optional markers, a hint, and an error that replaces the hint in the same row — `required`, `optional`, `hint`, `error`. */
+/** Live validation: removing the last region shakes the field and drops the error in, adding one clears it; required and optional markers and a hint — `required`, `optional`, `hint`, `error`. */
 import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+import * as React from "react";
 
 const CITIES: TagSelectOption[] = [
   { value: "msk", label: "Москва", color: "blue" },
@@ -13,6 +14,8 @@ const PEOPLE: TagSelectOption[] = [
 ];
 
 export default function TagSelectValidationExample() {
+  const [regions, setRegions] = React.useState(["msk"]);
+
   return (
     <>
       <TagSelect
@@ -25,8 +28,10 @@ export default function TagSelectValidationExample() {
       <TagSelect
         label="Регионы"
         required
-        error="Добавьте хотя бы один регион"
+        error={regions.length ? undefined : "Добавьте хотя бы один регион"}
         options={CITIES}
+        value={regions}
+        onValueChange={setRegions}
         placeholder="Добавить регион"
       />
       <TagSelect label="Наблюдатели" optional options={PEOPLE} placeholder="Добавить человека" />

package/src/components/textarea/COMPONENT.md

@@ -7,12 +7,14 @@
 
 ## 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
@@ -22,9 +24,11 @@ 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.
+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
 
@@ -45,10 +49,14 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 | `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. |
+| `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`… |
@@ -62,6 +70,24 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 | `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).
 
@@ -70,7 +96,7 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 |---|---|---|---|
 | `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 |
+| `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 | |
 
@@ -79,8 +105,8 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 ### 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 | |
+| `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 |
@@ -100,11 +126,18 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 | 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 |
+| 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`.
 
@@ -119,13 +152,17 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 ### Keyboard
 | Key | Action |
 |---|---|
-| `Tab` | Focuses the field; Enter inserts a line break instead of submitting the form. |
+| `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. -->
@@ -134,6 +171,11 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 |---|---|---|
 | `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 |
@@ -141,19 +183,24 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 | [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`. |
+| [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 and its error does not shift the form — `required`, `error`, `reserveSupportRow`. |
+| [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`)
-- **See also:** [Input](../input/COMPONENT.md) — the same field contract for one line; [CodeBlock](../code-block/COMPONENT.md)
+- **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/src/components/textarea/examples/auto-resize.tsx

@@ -1,4 +1,4 @@
-/** A field that grows with its text next to a fixed one with a resize handle — `autoResize`, `rows`. */
+/** 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() {
@@ -9,6 +9,13 @@ export default function TextareaAutoResizeExample() {
         placeholder="Состав, размеры, уход"
         hint="Высота растёт вместе с текстом, минимум три строки"
       />
+      <Textarea.Root
+        label="Комментарий к заказу"
+        rows={1}
+        maxRows={5}
+        placeholder="Например, позвонить за час"
+        hint="Начинается с одной строки, после пяти строк прокручивается"
+      />
       <Textarea.Root
         label="Условия договора"
         autoResize={false}

package/src/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>
+  );
+}