prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/reference/components/tag-select/COMPONENT.md

@@ -0,0 +1,179 @@
+# TagSelect
+
+**Category:** selection
+**Kind:** field
+
+> A multi-value field that shows the picked values as coloured tags, filters as you type and can create new tags.
+
+## 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`; a Promise from `onOptionDelete` holds the deletion for a confirmation or a request).
+
+## 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 { TagSelect, type TagSelectOption } from "prime-ui-kit";
+```
+
+## 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">
+│   ├── input[type=hidden] × value   with `name`
+│   └── chevron
+└── list (portal)               role="listbox", multi-select
+    ├── 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
+
+<!-- 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: 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 \| 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 \| 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`. |
+| `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. |
+| `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. |
+| `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 (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. 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; 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 (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; 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 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
+<!-- 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. |
+| `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. |
+| `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) | 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 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, 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), [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/dist/skill/reference/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/dist/skill/reference/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>
+    </>
+  );
+}

package/dist/skill/reference/components/tag-select/examples/controlled.tsx

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

package/dist/skill/reference/components/tag-select/examples/creatable.tsx

@@ -0,0 +1,49 @@
+/** 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";
+
+const OPTIONS: TagSelectOption[] = [
+  { value: "bug", label: "Ошибка", color: "red" },
+  { 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 (
+    <>
+      <TagSelect
+        label="Метки"
+        options={OPTIONS}
+        creatable
+        defaultColor="purple"
+        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">
+        {created.length ? `Созданы: ${created.join(", ")}` : "Наберите новую метку и нажмите Enter"}
+      </Typography>
+    </>
+  );
+}

package/dist/skill/reference/components/tag-select/examples/examples.module.css

@@ -0,0 +1,16 @@
+/* Layout of the TagSelect scenarios: semantic tokens only. */
+
+/* in-form.tsx: field → field 20, actions at the end. */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+  width: min(100%, var(--prime-modal-width-m));
+}
+
+.actions {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
+}

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

@@ -0,0 +1,85 @@
+/** 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";
+
+import styles from "./examples.module.css";
+
+const LABELS: TagSelectOption[] = [
+  { value: "bug", label: "Ошибка", color: "red" },
+  { value: "feature", label: "Новая функция", color: "blue" },
+  { value: "ux", label: "UX", color: "purple" },
+];
+
+const PEOPLE: TagSelectOption[] = [
+  { value: "anna", label: "Анна Смирнова" },
+  { value: "igor", label: "Игорь Петров" },
+  { value: "olga", label: "Ольга Ким" },
+];
+
+export default function TagSelectInFormExample() {
+  const [labels, setLabels] = React.useState<string[]>([]);
+  const [error, setError] = React.useState<string>();
+  const [saved, setSaved] = React.useState(false);
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setError(labels.length ? undefined : "Добавьте хотя бы одну метку");
+    setSaved(labels.length > 0);
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Typography as="h3" variant="title-m">
+        Новая задача
+      </Typography>
+      <Input.Root label="Название" required>
+        <Input.Wrapper>
+          <Input.Field name="title" placeholder="Коротко о задаче" />
+        </Input.Wrapper>
+      </Input.Root>
+      <TagSelect
+        label="Метки"
+        name="labels"
+        required
+        hint="Помогают фильтровать задачи"
+        error={error}
+        options={LABELS}
+        value={labels}
+        onValueChange={(next) => {
+          setLabels(next);
+          setError(undefined);
+          setSaved(false);
+        }}
+        creatable
+        placeholder="Добавить метку"
+      />
+      <TagSelect
+        label="Наблюдатели"
+        name="watchers"
+        optional
+        options={PEOPLE}
+        placeholder="Добавить человека"
+      />
+      <div className={styles.actions}>
+        {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>
+      </div>
+    </form>
+  );
+}

package/dist/skill/reference/components/tag-select/examples/manage-tags.tsx

@@ -0,0 +1,38 @@
+/** 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: "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);
+
+  return (
+    <TagSelect
+      label="Каналы связи"
+      options={options}
+      defaultValue={["chat", "email"]}
+      creatable
+      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))
+      }
+      placeholder="Канал связи"
+    />
+  );
+}

package/dist/skill/reference/components/tag-select/examples/many-tags.tsx

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

package/dist/skill/reference/components/tag-select/examples/overview.tsx

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

package/dist/skill/reference/components/tag-select/examples/sizes.tsx

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

package/dist/skill/reference/components/tag-select/examples/states.tsx

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

package/dist/skill/reference/components/tag-select/examples/validation.tsx

@@ -0,0 +1,40 @@
+/** 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" },
+  { value: "spb", label: "Санкт-Петербург", color: "teal" },
+  { value: "kzn", label: "Казань", color: "green" },
+];
+
+const PEOPLE: TagSelectOption[] = [
+  { value: "anna", label: "Анна Смирнова" },
+  { value: "igor", label: "Игорь Петров" },
+];
+
+export default function TagSelectValidationExample() {
+  const [regions, setRegions] = React.useState(["msk"]);
+
+  return (
+    <>
+      <TagSelect
+        label="Города доставки"
+        required
+        hint="Склады, откуда отправляем заказы"
+        options={CITIES}
+        defaultValue={["msk"]}
+      />
+      <TagSelect
+        label="Регионы"
+        required
+        error={regions.length ? undefined : "Добавьте хотя бы один регион"}
+        options={CITIES}
+        value={regions}
+        onValueChange={setRegions}
+        placeholder="Добавить регион"
+      />
+      <TagSelect label="Наблюдатели" optional options={PEOPLE} placeholder="Добавить человека" />
+    </>
+  );
+}