prime-ui-kit 0.7.13 → 0.9.1

package/src/components/tabs/examples/overflow.tsx

@@ -0,0 +1,60 @@
+/** Drag the frame narrower: icons go first, then labels, and icons with tooltips stay; then the list scrolls — `Tabs.Icon`. */
+import { Icon, Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  {
+    value: "overview",
+    label: "Обзор",
+    icon: "nav.home",
+    count: 0,
+    text: "Выручка за октябрь — 4 812 300 ₽.",
+  },
+  {
+    value: "orders",
+    label: "Заказы",
+    icon: "object.package",
+    count: 24,
+    text: "24 заказа ждут отгрузки.",
+  },
+  {
+    value: "invoices",
+    label: "Счета",
+    icon: "object.receipt",
+    count: 3,
+    text: "3 счёта просрочены.",
+  },
+  {
+    value: "clients",
+    label: "Клиенты",
+    icon: "object.users",
+    count: 0,
+    text: "312 активных компаний.",
+  },
+] as const;
+
+export default function TabsOverflowExample() {
+  return (
+    <Tabs.Root defaultValue="orders" className={styles.resizable}>
+      <Tabs.List aria-label="Магазин">
+        {SECTIONS.map((section) => (
+          <Tabs.Item key={section.value} value={section.value}>
+            <Tabs.Icon>
+              <Icon name={section.icon} />
+            </Tabs.Icon>
+            <Tabs.Label>{section.label}</Tabs.Label>
+            {section.count > 0 ? <Tabs.Count>{section.count}</Tabs.Count> : null}
+          </Tabs.Item>
+        ))}
+      </Tabs.List>
+      {SECTIONS.map((section) => (
+        <Tabs.Panel key={section.value} value={section.value}>
+          <Typography variant="body-m" tone="secondary">
+            {section.text}
+          </Typography>
+        </Tabs.Panel>
+      ))}
+    </Tabs.Root>
+  );
+}

package/src/components/tabs/examples/overview.tsx

@@ -0,0 +1,30 @@
+/** Sections of one screen; the active tab rises into the panel and glides to the next one — `defaultValue`. */
+import { Tabs, Typography } from "prime-ui-kit";
+
+const SECTIONS = [
+  { value: "overview", label: "Обзор", text: "Сводка по магазину за выбранный период." },
+  { value: "orders", label: "Заказы", text: "Последние заказы и их статусы." },
+  { value: "reviews", label: "Отзывы", text: "Новые отзывы покупателей." },
+  { value: "settings", label: "Настройки", text: "Название, валюта и способы доставки." },
+];
+
+export default function TabsOverviewExample() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List aria-label="Магазин">
+        {SECTIONS.map((section) => (
+          <Tabs.Item key={section.value} value={section.value}>
+            {section.label}
+          </Tabs.Item>
+        ))}
+      </Tabs.List>
+      {SECTIONS.map((section) => (
+        <Tabs.Panel key={section.value} value={section.value}>
+          <Typography variant="body-m" tone="secondary">
+            {section.text}
+          </Typography>
+        </Tabs.Panel>
+      ))}
+    </Tabs.Root>
+  );
+}

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

@@ -0,0 +1,30 @@
+/** Every size tier: text, icon, folder radius and spacing grow together — `size`. */
+import { Tabs, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function TabsSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+          <Tabs.Root size={size} defaultValue="all" fullWidth={false}>
+            <Tabs.List aria-label="Заявки">
+              <Tabs.Item value="all">Все</Tabs.Item>
+              <Tabs.Item value="active">Активные</Tabs.Item>
+              <Tabs.Item value="archive">Архив</Tabs.Item>
+            </Tabs.List>
+            <Tabs.Panel value="all">
+              <Typography variant="body-m" tone="secondary">
+                12 заявок за неделю.
+              </Typography>
+            </Tabs.Panel>
+          </Tabs.Root>
+        </div>
+      ))}
+    </>
+  );
+}

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

@@ -0,0 +1,26 @@
+/** A disabled tab that clicks and arrow keys skip — `disabled`. */
+import { Tabs, Typography } from "prime-ui-kit";
+
+export default function TabsStatesExample() {
+  return (
+    <Tabs.Root defaultValue="profile">
+      <Tabs.List aria-label="Аккаунт">
+        <Tabs.Item value="profile">Профиль</Tabs.Item>
+        <Tabs.Item value="security">Безопасность</Tabs.Item>
+        <Tabs.Item value="billing" disabled>
+          Оплата
+        </Tabs.Item>
+      </Tabs.List>
+      <Tabs.Panel value="profile">
+        <Typography variant="body-m" tone="secondary">
+          Имя, должность и контакты.
+        </Typography>
+      </Tabs.Panel>
+      <Tabs.Panel value="security">
+        <Typography variant="body-m" tone="secondary">
+          Пароль и двухфакторная защита.
+        </Typography>
+      </Tabs.Panel>
+    </Tabs.Root>
+  );
+}

package/src/components/tabs/examples/two-line.tsx

@@ -0,0 +1,56 @@
+/** A label and a counter on the first line, a summary on the second — `Tabs.Count`, `Tabs.Description`. */
+import { type PaletteColor, Tabs, Typography } from "prime-ui-kit";
+
+const SECTIONS: {
+  value: string;
+  title: string;
+  count: number;
+  color: PaletteColor;
+  strong: string;
+  rest: string;
+}[] = [
+  { value: "new", title: "Новые", count: 12, color: "blue", strong: "3", rest: " срочных" },
+  {
+    value: "progress",
+    title: "В работе",
+    count: 5,
+    color: "orange",
+    strong: "2",
+    rest: " просрочены",
+  },
+  { value: "done", title: "Готово", count: 148, color: "green", strong: "31", rest: " за неделю" },
+  {
+    value: "returns",
+    title: "Возвраты",
+    count: 4,
+    color: "red",
+    strong: "1",
+    rest: " ждёт решения",
+  },
+];
+
+export default function TabsTwoLineExample() {
+  return (
+    <Tabs.Root defaultValue="new">
+      <Tabs.List aria-label="Заказы">
+        {SECTIONS.map((section) => (
+          <Tabs.Item key={section.value} value={section.value}>
+            <Tabs.Label>{section.title}</Tabs.Label>
+            <Tabs.Count color={section.color}>{section.count}</Tabs.Count>
+            <Tabs.Description>
+              <strong>{section.strong}</strong>
+              {section.rest}
+            </Tabs.Description>
+          </Tabs.Item>
+        ))}
+      </Tabs.List>
+      {SECTIONS.map((section) => (
+        <Tabs.Panel key={section.value} value={section.value}>
+          <Typography variant="body-m" tone="secondary">
+            {section.title}: {section.count} заказов.
+          </Typography>
+        </Tabs.Panel>
+      ))}
+    </Tabs.Root>
+  );
+}

package/src/components/tabs/examples/variants.tsx

@@ -0,0 +1,40 @@
+/** The active tab in primary text with an accent icon, or all in accent — `tone`. */
+import { Icon, Tabs, Typography } from "prime-ui-kit";
+
+const TONES = ["neutral", "accent"] as const;
+
+const SECTIONS = [
+  { value: "orders", label: "Заказы", icon: "object.package" },
+  { value: "invoices", label: "Счета", icon: "object.receipt" },
+  { value: "clients", label: "Клиенты", icon: "object.users" },
+] as const;
+
+export default function TabsVariantsExample() {
+  return (
+    <>
+      {TONES.map((tone) => (
+        <Tabs.Root key={tone} tone={tone} defaultValue="orders">
+          <Tabs.List aria-label="Продажи">
+            {SECTIONS.map((section) => (
+              <Tabs.Item key={section.value} value={section.value}>
+                <Tabs.Icon>
+                  <Icon name={section.icon} />
+                </Tabs.Icon>
+                <Tabs.Label>{section.label}</Tabs.Label>
+              </Tabs.Item>
+            ))}
+          </Tabs.List>
+          {SECTIONS.map((section) => (
+            <Tabs.Panel key={section.value} value={section.value}>
+              <Typography variant="body-m" tone="secondary">
+                {tone === "neutral"
+                  ? "Спокойный акцент: цвет только у иконки."
+                  : "Активная вкладка целиком в акцентном цвете."}
+              </Typography>
+            </Tabs.Panel>
+          ))}
+        </Tabs.Root>
+      ))}
+    </>
+  );
+}

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

@@ -0,0 +1,44 @@
+/** A muted icon before the label and a hairline before the service section — `Tabs.Icon`, `Tabs.Label`, `Tabs.Separator`. */
+import { Icon, Tabs, Typography } from "prime-ui-kit";
+
+const SECTIONS = [
+  { value: "overview", label: "Обзор", icon: "nav.home", text: "Выручка и заказы за неделю." },
+  { value: "orders", label: "Заказы", icon: "object.package", text: "24 заказа ждут отгрузки." },
+  { value: "invoices", label: "Счета", icon: "object.receipt", text: "3 счёта просрочены." },
+] as const;
+
+export default function TabsWithIconExample() {
+  return (
+    <Tabs.Root defaultValue="orders">
+      <Tabs.List aria-label="Магазин">
+        {SECTIONS.map((section) => (
+          <Tabs.Item key={section.value} value={section.value}>
+            <Tabs.Icon>
+              <Icon name={section.icon} />
+            </Tabs.Icon>
+            <Tabs.Label>{section.label}</Tabs.Label>
+          </Tabs.Item>
+        ))}
+        <Tabs.Separator />
+        <Tabs.Item value="settings">
+          <Tabs.Icon>
+            <Icon name="action.settings" />
+          </Tabs.Icon>
+          <Tabs.Label>Настройки</Tabs.Label>
+        </Tabs.Item>
+      </Tabs.List>
+      {SECTIONS.map((section) => (
+        <Tabs.Panel key={section.value} value={section.value}>
+          <Typography variant="body-m" tone="secondary">
+            {section.text}
+          </Typography>
+        </Tabs.Panel>
+      ))}
+      <Tabs.Panel value="settings">
+        <Typography variant="body-m" tone="secondary">
+          Реквизиты, уведомления и доступы сотрудников.
+        </Typography>
+      </Tabs.Panel>
+    </Tabs.Root>
+  );
+}

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

@@ -1,155 +1,166 @@
-# 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
+**Kind:** field
 
-## About
+> A multi-value field that shows the picked 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**
-
-- 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
-
-- **`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.
-
-### Canonical example
-
-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).
+## When not to use
+- One value → use [Select](../select/COMPONENT.md).
+- A few values from a short closed list where chips are not needed → use [Select](../select/COMPONENT.md) with `multiple`.
+- 2–6 independent options that should all be visible → use [Checkbox](../checkbox/COMPONENT.md).
+- Values shown outside a field → use [Badge](../badge/COMPONENT.md) (`onRemove` for removable ones).
 
+## Import
 ```tsx
-import * as React from "react";
-import type { TagSelectOption } from "prime-ui-kit";
-import { TagSelect } from "prime-ui-kit";
-
-const initialOptions: TagSelectOption[] = [
-  { value: "telegram", label: "Telegram", color: "blue" },
-  { value: "whatsapp", label: "WhatsApp", color: "green" },
-];
-
-export function Example() {
-  const [value, setValue] = React.useState<string[]>([]);
-  const [options, setOptions] = React.useState<TagSelectOption[]>(initialOptions);
-
-  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"
-    />
-  );
-}
+import { TagSelect, type TagSelectOption } from "prime-ui-kit";
 ```
 
-### 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).
+## Anatomy
+```
+TagSelect                       field frame: label · control · hint/error (single export)
+├── control                     field fill, one row at rest, wraps when focused
+│   ├── chip row                ScrollContainer: Badge chips (one tier down) · «+N» Badge · input
+│   │   └── <input role="combobox">
+│   └── chevron
+└── list (portal)               role="listbox", multi-select
+    ├── panel hint              labels.panelHint
+    ├── «Создать» row           with `creatable`
+    └── option row              Checkbox.Indicator · Badge [· «⋯» Button → Popover menu]
+```
 
 ## 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») |
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### TagSelect
+`ref` → `HTMLDivElement` (the field frame). The field frame with a chip row and an `<input role="combobox">`, and a portaled multi-select list; options come as data.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `options` | `TagSelectOption[]` | — (required) | Available tags: `{ value, label, color?, disabled? }`. |
+| `value` | `string[]` | — | Controlled picked values. |
+| `defaultValue` | `string[]` | `[]` | Initial picked values, uncontrolled. |
+| `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. |
+| `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`. |
+| `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. |
+| `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`. |
+| `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the input. |
+| `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. |
+| `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. |
+| `id` | `string` | — | Id of the input; generated when omitted. |
+| `labels` | `Partial<TagSelectLabels>` | — | Built-in strings, see Labels (`colorNames` merges by key). |
+| `aria-label · aria-labelledby` | `string` | — | Name of the input and the list when there is no `label`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
+
+## Variants
+No `variant` or `tone`. The control is the field look; chips are soft Badges on the field's wash (neutral chips a stronger wash, hue chips a wash of their hue); the list is the shared floating panel.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28 field, xs chips | Dense filters | |
+| `s` | 32 field, xs chips | Compact panels | |
+| `m` | 36 field, s chips | Regular forms | yes |
+| `l` | 40 field, m chips | Spacious forms | |
+| `xl` | 48 field, l chips | Touch-first screens | |
+
+### Flags
+| 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` |
+| `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 |
+| 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 |
+| option highlighted / selected / disabled | keyboard and pointer / value / option `disabled` | `data-highlighted`, `aria-selected` + checked indicator, `data-disabled` |
+
+## 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.
+
+## 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. |
+| `Space` | Types a space: a tag may have several words. |
+| `Backspace` | In an empty input removes the last 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. |
+
+### 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`.
+- The hint and the error are linked by `aria-describedby`; the error sets `aria-invalid`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `panelHint` | `"Выберите вариант или создайте новый"` | Line above the list; `""` hides it. |
+| `create` | `"Создать"` | Action text before the preview of a new tag. |
+| `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. |
+| `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. |
+| `colors` | `"Цвета"` | Heading of the color list in the menu. |
+| `colorNames` | `"По умолчанию · Красный · Оранжевый · …"` | Names of the palette colors in the menu, by `PaletteColor` key. |
+| `optional` | `"необязательно"` | Muted marker after the label when `optional`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [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`. |
+| [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`. |
+| [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`. |
+
+## 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.
 
 ## Related
-
-- [Select](../select/COMPONENT.md)
-- [Tag](../tag/COMPONENT.md)
-- [Badge](../badge/COMPONENT.md)
-- [ScrollContainer](../scroll-container/ScrollContainer.tsx) (internal list)
+- **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)
+- **See also:** [Select](../select/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md)

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

@@ -0,0 +1,29 @@
+/** The parent owns the list: a button opens it from code, Escape or an outside press closes it — `open`, `onOpenChange`. */
+import { Button, TagSelect, type TagSelectOption } 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 TagSelectControlledOpenExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <TagSelect
+        label="Исполнители задачи"
+        options={OPTIONS}
+        placeholder="Никто не назначен"
+        open={open}
+        onOpenChange={setOpen}
+      />
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+        Назначить исполнителей
+      </Button.Root>
+    </>
+  );
+}