prime-ui-kit 0.7.13 → 0.9.0

package/src/components/tag/examples/with-icon.tsx

@@ -1,22 +1,28 @@
+/** `Tag.Icon` puts a leading icon in the tag text color, sized to the tag tier. Use when the icon tells the value type (email, privacy, page). */
 import { Icon, Tag } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-/** Two tags with leading icons and text. */
-export default function TagExampleWithIcon() {
+export default function TagWithIconExample() {
   return (
-    <div className={styles.chipRow}>
+    <div className={styles.tags}>
       <Tag.Root>
+        <Tag.Icon>
+          <Icon name="field.email" />
+        </Tag.Icon>
+        anna@example.ru
+      </Tag.Root>
+      <Tag.Root labels={{ remove: "Убрать «Приватные»" }} onRemove={() => undefined}>
         <Tag.Icon>
           <Icon name="status.locked" />
         </Tag.Icon>
-        <span>Secured</span>
+        Приватные
       </Tag.Root>
-      <Tag.Root>
+      <Tag.Root size="s">
         <Tag.Icon>
-          <Icon name="field.email" />
+          <Icon name="nav.home" />
         </Tag.Icon>
-        <span>Newsletter</span>
+        Главная
       </Tag.Root>
     </div>
   );

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

@@ -1,155 +1,169 @@
-# Tag select
+# TagSelect
 
-**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:** selection
 
-## About
+> A multi-select field that shows the chosen values as coloured tags, filters as you type and can create new tags.
 
-A multi-select field: selected values appear as removable chips (styled like [Tag](../tag/COMPONENT.md)); typing in the embedded input filters the dropdown list. Options are passed as **`options`** (value, label, optional **`Badge`** **`filled`** color). With **`creatable`**, the user can add a string that is not in the list; **`onCreated`** fires only when a new value is committed via Create / Enter (not when picking from **`options`**).
+## 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`).
 
-**When to use**
+## When not to use
+- One value → use [Select](../select/COMPONENT.md) instead.
+- A few values from a short closed list where chips are not needed → use [Select](../select/COMPONENT.md) with `multiple` instead.
+- 2–6 independent options that should all be visible → use [Checkbox](../checkbox/COMPONENT.md) instead.
+- Static tags shown outside a field → use [Tag](../tag/COMPONENT.md) or [Badge](../badge/COMPONENT.md) instead.
 
-- Forms and filters where several labels from a known set are needed (channels, skills, topics) with optional ad-hoc values.
-- Flows that combine chip display, inline filtering, and keyboard navigation in one control.
-
-**When not to use**
-
-- Exactly one choice from a closed set — prefer [Select](../select/COMPONENT.md).
-- Free text without structured chips — prefer [Input](../input/COMPONENT.md) or [Textarea](../textarea/COMPONENT.md).
-- Read-only tags without editing — prefer [Tag](../tag/COMPONENT.md) alone.
-
-## Composition
+## Import
+```tsx
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+```
 
-- **`TagSelect.Root`** — owns **`options`**, **`value`** / **`defaultValue`**, **`onValueChange`**, **`creatable`**, **`onCreated`**, **`optionManagement`** (опционально: меню «⋯» у строки — переименование, палитра цветов, удаление из справочника), **`placeholder`**, **`hint`**, **`size`** (same [`Select`](../select) size axis as **`Select.Root`**), **`disabled`**, **`hasError`**, **`aria-label`** / **`aria-labelledby`**. Renders the chip row + input, a portaled listbox when open, and optional **`ScrollContainer`** for the option list.
+## Anatomy
+Single part `TagSelect.Root`. It renders:
+```
+field frame: label · control · hint/error
+└─ control (field fill)
+   ├─ chips (Tag, one tier below the field) · «+N» chip button when collapsed
+   ├─ text input (role="combobox")
+   └─ chevron
+portal panel (role="listbox"): panel hint · «Создать» row · option rows (checkbox + tag [+ «⋯» menu])
+```
 
-### Canonical example
+## API
 
-Controlled **`options`**, **`creatable`**, and **`optionManagement`**: keep **`options`** in React state; in **`onUpdate`**, append a row when **`tagValue`** is not found (covers tags created in-session before the parent list includes them).
+### TagSelect.Root
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `options` | `TagSelectOption[]` | — (required) | Dictionary: `{ value: string; label: string; color?: PaletteColor; disabled?: boolean }`. |
+| `value` | `string[]` | — | Controlled selection in the order it was added; use with `onValueChange`. |
+| `defaultValue` | `string[]` | `[]` | Initial selection in uncontrolled mode. |
+| `onValueChange` | `(value: string[]) => void` | — | Called after adding, removing or creating a tag. |
+| `open` | `boolean` | — | Controlled panel state. |
+| `defaultOpen` | `boolean` | `false` | Initial panel state. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when the panel opens or closes. |
+| `creatable` | `boolean` | `false` | Typing a value that is not in `options` shows a «Создать» row; Enter adds it. |
+| `onCreate` | `(value: string) => void` | — | Called only for a created value (not for picks from `options`). |
+| `defaultColor` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Chip colour for values without an option colour, including created ones. |
+| `onOptionUpdate` | `(value: string, updates: { label?: string; color?: PaletteColor }) => void` | — | Enables the row «⋯» menu with name field and colour list. `value` never changes. |
+| `onOptionDelete` | `(value: string) => void` | — | Enables «Удалить» in the row menu; the value is also removed from the selection. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Field tier; the list uses the same tier, chips one tier down (`xs` chips at both `xs` and `s`). |
+| `label` | `ReactNode` | — | Label above the field. |
+| `required` | `boolean` | `false` | Red `*` after the label, `aria-required`. |
+| `optional` | `boolean` | — | Muted `labels.optional` marker. |
+| `hint` | `ReactNode` | — | Hint under the field. |
+| `error` | `ReactNode` | — | Error message in the hint slot; non-empty implies `invalid`. |
+| `invalid` | `boolean` | — | Danger ring and `aria-invalid` without a message. |
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring. |
+| `disabled` | `boolean` | `false` | Disables the field, chips and the panel. |
+| `placeholder` | `string` | `""` | Input placeholder while nothing is selected. |
+| `id` | `string` | auto (`useId`) | Id of the text input. |
+| `labels` | `Partial<TagSelectLabels>` | Russian defaults | System strings, see Accessibility. |
+| `aria-label` | `string` | — | Name of the input and listbox without a visible `label`. |
+| `aria-labelledby` | `string` | — | Id of the element that names the field. |
+| `className` | `string` | — | Class on the field frame `div`. |
+
+No other native props, no ref, no hidden form input (submit `value` from state).
+
+## Variants
+No `variant`/`tone`. Axes: `size`, chip `color` (per option / `defaultColor`), behaviour flags (`creatable`, manageable rows).
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28px field, `xs` chips (no smaller tier), 24px list rows | dense filters | |
+| `s` | 32px field, `xs` chips, 28px rows | compact panels | |
+| `m` | 36px field, `s` chips, 32px rows | regular forms | yes |
+| `l` | 40px field, `m` chips, 36px rows | spacious forms | |
+| `xl` | 48px field, `l` chips, 40px rows | touch-first screens | |
+
+### color (option `color` / `defaultColor`)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `gray` | neutral soft tag | people, plain values | `defaultColor` |
+| `blue` · `green` · `orange` · `red` · `yellow` · `purple` · `sky` · `pink` · `teal` | soft tag of the hue | categories that users recognise by colour | |
+
+### Behaviour flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `creatable` | «+ Создать [preview tag]» row while the query has no exact match | open vocabularies (labels) | `false` |
+| `onOptionUpdate` / `onOptionDelete` set | each enabled row gets a «⋯» button opening a Popover: name field, «Удалить», colour list | user-managed dictionaries | off |
+
+**Combinations**
+- `creatable` + `onOptionUpdate` → created tags can be renamed/recoloured at once; keep `options` in state and merge updates (see [manage-tags.tsx](examples/manage-tags.tsx)).
+- `onOptionDelete` without keeping `options` in state → the option comes back on the next render; always remove it from your `options`.
+- `labels={{ panelHint: "" }}` hides the line above the list — use it for plain dictionaries (people).
+
+**Sizes** — single-row field height equals `--prime-control-<tier>-height`, aligned with Input and Select of the same tier.
+
+**Hierarchy** — inside a Card the field fill switches to the surface variant like Input next to it.
+
+## States
+| State | Driven by | DOM | Looks like |
+|---|---|---|---|
+| collapsed | no focus inside, panel closed | control without `data-expanded` | one row; chips that do not fit go into a «+N» chip (`title` lists them) |
+| expanded | focus inside or panel open | `data-expanded="true"` | all chips on several rows (up to three, then the field scrolls) |
+| open | typing / click / ↑ ↓ | `data-state="open"`, `aria-expanded` on input; panel `data-state`, `data-side` | panel under the field; selected options first with a check, then the rest |
+| invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` | inset `danger-border` ring, error text |
+| disabled | `disabled` | `data-disabled="true"`, native `disabled` | disabled field fill, dimmed chips |
+| option disabled | `options[i].disabled` | row `data-disabled`, native `disabled` | dimmed tag, not selectable, excluded from search |
+| focus-visible | keyboard | `data-focus-ring="false"` when `focusRing={false}` | inset focus ring on the control |
+
+The panel opens only when it has rows (matches or a create row) and closes when it has none. It follows the overlay contract: outside press and Escape close it; the manage Popover is a separate topmost layer.
+Controlled: `value` + `onValueChange`, `open` + `onOpenChange`. Uncontrolled: `defaultValue`, `defaultOpen`.
+
+## Layout & spacing
+- Field is 100% wide; set width with the layout.
+- Label → field: tier `label-gap`; field → field in a form: `--prime-space-5`.
+- Chips are one tier below the field and never change the single-row height in the collapsed state.
+
+## Accessibility
+- The only tab stop is the text input (`role="combobox"`, `aria-autocomplete="list"`, `aria-controls`, `aria-activedescendant`, `aria-describedby`, `aria-required`, `aria-invalid`).
+- Listbox `role="listbox"` `aria-multiselectable`, rows `role="option"` with `aria-selected`.
+- Keyboard: ↑ / ↓ open and move, Enter / Space toggle the highlighted row (or create), Escape closes, Backspace in an empty input removes the last chip, ← from the start of the input moves to chips, ← / → between chips, Delete / Backspace on a chip remove it (focus moves to a neighbour). Removal is announced in a polite live region.
+- `labels` keys (defaults):
+  - `panelHint` — «Выберите вариант или создайте новый» (`""` hides it)
+  - `create` — «Создать»
+  - `remove` — «Удалить {label}» (chip remove button)
+  - `more` — «Показать ещё {count}» («+N» button)
+  - `removed` — «Удалено: {label}» (live announcement)
+  - `edit` — «Изменить тег {label}» («⋯» button)
+  - `name` — «Название тега» (name field in the menu)
+  - `delete` — «Удалить»
+  - `colors` — «Цвета» (colour list heading)
+  - `colorNames` — gray «По умолчанию», red «Красный», orange «Оранжевый», yellow «Жёлтый», green «Зелёный», blue «Синий», purple «Фиолетовый», pink «Розовый», sky «Голубой», teal «Бирюзовый»
+  - `optional` — «необязательно»
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [sizes.tsx](examples/sizes.tsx) | All size tiers with chips | Matching other controls |
+| [states.tsx](examples/states.tsx) | Empty, «+N» overflow, error, disabled, disabled option | Reference for every state |
+| [manage-tags.tsx](examples/manage-tags.tsx) | Controlled, `creatable`, `onOptionUpdate`, `onOptionDelete`, custom `labels` | User-managed tag dictionary |
+| [in-form.tsx](examples/in-form.tsx) | Card form with `creatable` labels and `optional` watchers next to Input | Tag fields in forms |
 
 ```tsx
-import * as React from "react";
-import type { TagSelectOption } from "prime-ui-kit";
-import { TagSelect } from "prime-ui-kit";
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
 
-const initialOptions: TagSelectOption[] = [
-  { value: "telegram", label: "Telegram", color: "blue" },
-  { value: "whatsapp", label: "WhatsApp", color: "green" },
+const options: TagSelectOption[] = [
+  { value: "bug", label: "Ошибка", color: "red" },
+  { value: "feature", label: "Новая функция", color: "blue" },
 ];
 
-export function Example() {
-  const [value, setValue] = React.useState<string[]>([]);
-  const [options, setOptions] = React.useState<TagSelectOption[]>(initialOptions);
-
+export function LabelsField() {
   return (
-    <TagSelect.Root
-      options={options}
-      value={value}
-      onValueChange={setValue}
-      creatable
-      optionManagement={{
-        onUpdate: (tagValue, updates) => {
-          setOptions((prev) => {
-            const i = prev.findIndex((o) => o.value === tagValue);
-            if (i === -1) {
-              return [
-                ...prev,
-                {
-                  value: tagValue,
-                  label: updates.label ?? tagValue,
-                  color: updates.color ?? "gray",
-                },
-              ];
-            }
-            return prev.map((o) =>
-              o.value === tagValue
-                ? {
-                    ...o,
-                    ...(updates.label !== undefined ? { label: updates.label } : {}),
-                    ...(updates.color !== undefined ? { color: updates.color } : {}),
-                  }
-                : o,
-            );
-          });
-        },
-        onDelete: (tagValue) => {
-          setOptions((prev) => prev.filter((o) => o.value !== tagValue));
-        },
-      }}
-      placeholder="Channel…"
-      aria-label="Contact channels"
-    />
+    <TagSelect.Root label="Метки" options={options} defaultValue={["bug"]} creatable />
   );
 }
 ```
 
-### Scenarios (`examples/`)
-
-| File | Intent |
-|------|--------|
-| [`examples/pattern-canonical.tsx`](./examples/pattern-canonical.tsx) | Full stack: **`creatable`**, **`optionManagement`** (⋯), controlled **`options`**; **`prime-ui-kit`** import. |
-| [`examples/pattern-features.tsx`](./examples/pattern-features.tsx) | Same as canonical with **`@/`** imports; mirrors [`playground/snippets/tag-select/features.tsx`](../../../playground/snippets/tag-select/features.tsx). |
-
-### Playground
-
-Live demo: **`playground/sections/TagSelectSection.tsx`** — snippet **`playground/snippets/tag-select/features.tsx`** (same behavior as the canonical example).
-
-**LLM note:** Prefer runnable files under **`./examples/*.tsx`** for prop combinations; this page keeps the contract (rules + API) authoritative.
-
-## Rules
-
-- **`size`** follows the same **`Select`** control tier as **`Select.Root`**; nested **`Badge`** chips inherit size via **`ControlSizeProvider`**.
-- **`onCreated`** is only invoked when a **new** value is added through creatable flow (Create row or Enter), not when selecting an existing **`options`** row.
-- **`hasPanelContent`** gates the dropdown: if there are no list rows and no create row, the panel closes.
-- **List rows vs chips:** options already in **`value`** are omitted from the listbox (add-to-selection rows only). If nothing is left to add and there is no creatable row, the panel does **not** open on focus (e.g. all catalog tags already on the record) — open again after typing (filter / create) or removing a chip so at least one option can be added again. **`optionManagement`** ⋯ is available on rows **when** those options appear in the list (not while the panel is forced empty).
-- Removing the last chip with empty input: **Backspace** removes the last selected value.
-- Name the control with **`aria-label`** or **`aria-labelledby`** when there is no visible [Label](../label/COMPONENT.md).
-
-## API
-
-### TagSelect.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| options | `TagSelectOption[]` | — | Yes | Options: **`value`**, **`label`**, optional **`color`**, **`disabled`** |
-| value | `string[]` | — | No | Controlled selected values |
-| defaultValue | `string[]` | `[]` | No | Uncontrolled initial selected values |
-| onValueChange | `(next: string[]) => void` | — | No | Called when selection changes |
-| creatable | `boolean` | `false` | No | Allow creating a value not in **`options`** |
-| onCreated | `(value: string) => void` | — | No | When **`creatable`**: fired for newly created values only |
-| defaultTagColor | `BadgeColor` | `"gray"` | No | Chip color for values not in **`options`** |
-| hint | `React.ReactNode` | `"Select an option or create one"` | No | Text above the list |
-| createActionLabel | `string` | `"Create"` | No | Label for the create row |
-| disabled | `boolean` | `false` | No | Disables the field |
-| placeholder | `string` | `""` | No | Input placeholder |
-| hasError | `boolean` | `false` | No | Error styling |
-| size | `SelectSize` | `"m"` | No | Same size axis as **`Select.Root`** |
-| optionManagement | `TagSelectOptionManagement` | — | No | Меню редактирования опции в списке (⋯): **`onUpdate`**, **`onDelete`**, опционально подписи |
-| id | `string` | — | No | Root id (listbox and input ids are derived) |
-| className | `string` | — | No | Extra class on the root |
-| aria-label | `string` | — | No | Accessible name |
-| aria-labelledby | `string` | — | No | References label ids |
-
-### TagSelectOption
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| value | `string` | Yes | Stored in **`value[]`** |
-| label | `string` | Yes | Chip and list row text |
-| color | `BadgeColor` | No | **`Badge`** **`filled`** color in the list |
-| disabled | `boolean` | No | Option not selectable |
-
-### TagSelectOptionManagement
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| onUpdate | `(value: string, updates: { label?: string; color?: BadgeColor }) => void` | Yes | Обновить подпись и/или цвет; **`value`** опции не меняется |
-| onDelete | `(value: string) => void` | Yes | Удалить опцию из справочника; выбранные значения с этим **`value`** снимаются |
-| colorsSectionLabel | `string` | No | Заголовок блока цветов (по умолчанию «Colors») |
-| deleteLabel | `string` | No | Подпись кнопки удаления (по умолчанию «Delete») |
-| editMenuAriaLabelPrefix | `string` | No | Префикс **`aria-label`** кнопки ⋯ (по умолчанию «Edit tag») |
+## Mistakes
+- Children like `<TagSelect.Item>` → there are none; pass `options`.
+- `onChange` → use `onValueChange` (`string[]`).
+- `onOptionDelete` / `onOptionUpdate` without updating your `options` state → changes are lost.
+- Using it for a single value → use `Select`.
+- Expecting `name` / form submission → there is no hidden input; submit `value` from state.
 
 ## Related
-
-- [Select](../select/COMPONENT.md)
-- [Tag](../tag/COMPONENT.md)
-- [Badge](../badge/COMPONENT.md)
-- [ScrollContainer](../scroll-container/ScrollContainer.tsx) (internal list)
+[Select](../select/COMPONENT.md) · [Tag](../tag/COMPONENT.md) · [Input](../input/COMPONENT.md) · [Popover](../popover/COMPONENT.md)

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

@@ -1,14 +1,34 @@
-.stackNarrow {
+/* Example layout: semantic tokens only. */
+
+.column {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
+  width: 100%;
+  max-width: calc(var(--prime-space-24) * 3.5);
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(calc(var(--prime-space-24) * 2.75), 1fr));
+  gap: var(--prime-space-5) var(--prime-space-4);
   width: 100%;
-  max-width: calc(var(--prime-sys-unit-1rem) * 22);
 }
 
-.stack {
+.form {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-sys-spacing-s);
+  gap: var(--prime-space-5);
 }
 
-.caption {
-  margin: 0;
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
+}
+
+.card {
+  width: 100%;
+  max-width: calc(var(--prime-space-24) * 5);
 }

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

@@ -0,0 +1,58 @@
+/** A task form in a card with a creatable labels field and an optional watchers field next to an Input. Use it for tag fields inside forms. */
+import { Button, Card, Input, TagSelect, type TagSelectOption } from "prime-ui-kit";
+
+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" },
+  { value: "docs", label: "Документация", color: "gray" },
+];
+
+const people: TagSelectOption[] = [
+  { value: "anna", label: "Анна Смирнова" },
+  { value: "igor", label: "Игорь Петров" },
+  { value: "olga", label: "Ольга Ким" },
+];
+
+export default function TagSelectInFormExample() {
+  return (
+    <Card.Root variant="panel" className={styles.card}>
+      <Card.SectionHeader>
+        <Card.SectionTitle>Новая задача</Card.SectionTitle>
+      </Card.SectionHeader>
+      <Card.Body>
+        <form className={styles.form} onSubmit={(event) => event.preventDefault()}>
+          <Input.Root label="Название" required>
+            <Input.Wrapper>
+              <Input.Field placeholder="Коротко о задаче" />
+            </Input.Wrapper>
+          </Input.Root>
+          <TagSelect.Root
+            label="Метки"
+            options={labels}
+            defaultValue={["bug"]}
+            creatable
+            labels={{ panelHint: "Выберите метку или создайте новую" }}
+            placeholder="Добавить метку"
+          />
+          <TagSelect.Root
+            label="Наблюдатели"
+            optional
+            hint="Получат уведомления об изменениях"
+            options={people}
+            labels={{ panelHint: "" }}
+            placeholder="Добавить человека"
+          />
+          <div className={styles.actions}>
+            <Button.Root variant="ghost" tone="neutral">
+              Отмена
+            </Button.Root>
+            <Button.Root type="submit">Создать задачу</Button.Root>
+          </div>
+        </form>
+      </Card.Body>
+    </Card.Root>
+  );
+}

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

@@ -0,0 +1,53 @@
+/** A controlled field with creatable tags and the row «⋯» menu to rename, recolor or delete options. Use it when users maintain their own tag dictionary. */
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const initialOptions: TagSelectOption[] = [
+  { value: "telegram", label: "Telegram", color: "blue" },
+  { value: "whatsapp", label: "WhatsApp", color: "green" },
+  { value: "email", label: "Почта", color: "purple" },
+  { value: "phone", label: "Телефон", color: "orange" },
+  { value: "viber", label: "Viber", color: "pink" },
+  { value: "sms", label: "SMS", color: "teal" },
+];
+
+export default function TagSelectManageTagsExample() {
+  const [value, setValue] = React.useState<string[]>([
+    "telegram",
+    "whatsapp",
+    "email",
+    "phone",
+    "viber",
+  ]);
+  const [options, setOptions] = React.useState<TagSelectOption[]>(initialOptions);
+
+  return (
+    <div className={styles.column}>
+      <TagSelect.Root
+        options={options}
+        value={value}
+        onValueChange={setValue}
+        creatable
+        labels={{ panelHint: "Выберите канал или создайте новый", edit: "Изменить метку {label}" }}
+        onOptionUpdate={(tagValue, updates) => {
+          setOptions((prev) =>
+            prev.some((o) => o.value === tagValue)
+              ? prev.map((o) => (o.value === tagValue ? { ...o, ...updates } : o))
+              : [
+                  ...prev,
+                  { value: tagValue, label: updates.label ?? tagValue, color: updates.color },
+                ],
+          );
+        }}
+        onOptionDelete={(tagValue) => {
+          setOptions((prev) => prev.filter((o) => o.value !== tagValue));
+        }}
+        label="Каналы связи"
+        hint="Фокус раскрывает все теги; ⋯ у строки — переименовать, сменить цвет или удалить"
+        placeholder="Канал связи"
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,30 @@
+/** All five size tiers with two selected tags; chips are one tier below the field. Use it to match the field to the other controls of a form. */
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+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 (
+    <div className={styles.column}>
+      {SIZES.map((size) => (
+        <TagSelect.Root
+          key={size}
+          size={size}
+          options={options}
+          defaultValue={["design", "backend"]}
+          label={`Метки, ${size}`}
+          labels={{ panelHint: "Выберите метку" }}
+          placeholder="Добавить метку"
+        />
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,49 @@
+/** Empty, overflowing into «+N», error and disabled fields, with a disabled option in the list. Use it as a reference for every field state. */
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const options: 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" },
+  { value: "kgd", label: "Калининград", disabled: true },
+];
+
+const LABELS = { panelHint: "Выберите город" };
+
+export default function TagSelectStatesExample() {
+  return (
+    <div className={styles.grid}>
+      <TagSelect.Root
+        label="Пусто"
+        hint="Длинный список прокручивается, «Калининград» недоступен"
+        options={options}
+        labels={LABELS}
+        placeholder="Добавить город"
+      />
+      <TagSelect.Root
+        label="Переполнение"
+        hint="В покое — одна строка и «+N»; в фокусе видны все"
+        options={options}
+        labels={LABELS}
+        defaultValue={["msk", "spb", "kzn", "ekb", "nsk"]}
+      />
+      <TagSelect.Root
+        label="Ошибка"
+        required
+        error="Добавьте хотя бы один город"
+        options={options}
+        labels={LABELS}
+        placeholder="Добавить город"
+      />
+      <TagSelect.Root label="Отключено" options={options} defaultValue={["msk", "kzn"]} disabled />
+    </div>
+  );
+}