prime-ui-kit 0.14.0 → 0.16.0

package/dist/skill/reference/components/tabs/COMPONENT.md

@@ -27,8 +27,8 @@ import { Tabs } from "prime-ui-kit";
 
 ## Anatomy
 ```
-Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItemWidth; no surface
-├─ Tabs.List              role="tablist" on a ScrollContainer, sliding folder; collapses, then scrolls
+Tabs.Root                 value, size (else the host tier), orientation, tone, fullWidth, min/maxItemWidth
+├─ Tabs.List              role="tablist" on the switcher row, sliding folder; collapses, then scrolls
 │  ├─ Tabs.Item           one tab (role="tab") in an item wrapper; onRemove adds a close button; parts:
 │  │  ├─ Tabs.Icon        decorative icon; hidden first, kept last
 │  │  ├─ Tabs.Label       title; keeps its width when it turns medium weight
@@ -51,17 +51,17 @@ Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItem
 | `defaultValue` | `string` | `""` | Initial active tab (uncontrolled). With `""` no tab is selected. |
 | `onValueChange` | `(value: string) => void` | — | Called with the new active value. |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | List direction and arrow keys. Vertical: a column of sections beside the panel, which becomes a horizontal strip in a container below 600px. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier: text, icon, spacing, folder radius and the gap between the strip and the panel; a tab is at least the control height. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Control tier: text, icon, spacing, folder radius and the gap between the strip and the panel; a tab is at least the control height. Without it the tier of the host. |
 | `fullWidth` | `boolean` | `true` | Horizontal tabs fill the list and tend to equal widths within `minItemWidth` … `maxItemWidth`; `false` sizes each tab to its content within the same bounds. |
 | `tone` | `"neutral" \| "accent"` | `"neutral"` | Colour of the active tab: `neutral` is primary text with an accent icon, `accent` puts text and icon in accent. |
-| `minItemWidth` | `number \| string` | `2.5 × control height` | Narrowest a horizontal tab with a label gets, px or a CSS length; a tab is also never narrower than its content (up to `maxItemWidth`). |
-| `maxItemWidth` | `number \| string` | `7 × control height` | Widest a horizontal tab gets, px or a CSS length (`"none"` lifts the cap); a longer label ends with an ellipsis. |
+| `minItemWidth` | `number \| string` | 2.5 × control height | Narrowest a horizontal tab with a label gets, px or a CSS length; a tab is also never narrower than its content (up to `maxItemWidth`). |
+| `maxItemWidth` | `number \| string` | 7 × control height | Widest a horizontal tab gets, px or a CSS length (`"none"` lifts the cap); a longer label ends with an ellipsis. |
 | `labels` | `Partial<TabsLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | `Tabs.List` and `Tabs.Panel`s. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">` | — | `className` and the other div attributes. |
 
 ### Tabs.List
-`ref` → `HTMLDivElement`. `role="tablist"` on a `ScrollContainer` with the sliding folder. When tabs do not fit it hides icons and descriptions, then labels (only when every tab has an icon), then scrolls; the active tab stays in view.
+`ref` → `HTMLDivElement`. `role="tablist"` on the switcher row (a sideways `ScrollContainer`) with the sliding folder. When tabs do not fit it hides icons and descriptions, then labels (only when every tab has an icon), then scrolls; the active tab stays in view.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -173,7 +173,7 @@ A tab is at least the control height of the tier, so a one-line list lines up wi
 | `Tabs.Icon` + `Tabs.Label` | muted icon before the label; the active tab's leading icon turns accent | sections with recognizable icons | |
 | `Tabs.Count` | soft badge after the label, tabular numbers | showing how many items a section has | |
 | `Tabs.Description` (two-line) | label (+ count) on line 1, `body-s` muted text on line 2; `<strong>` is primary / medium | dashboards with a summary per section | |
-| `onRemove` on Item | a ghost close button (`action.close`, two tiers below) at the end of the tab: on the active tab, on hover and focus, always on touch screens; the tab also closes by `Delete` / `Backspace` and a middle click, and closing the active tab selects its neighbour | open documents the user closes, like browser tabs | |
+| `onRemove` on Item | a ghost close button (`action.close`, `xs`; `s` in `l` and `xl` tabs) at the end of the tab: on the active tab, on hover and focus, always on touch screens; the tab also closes by `Delete` / `Backspace` and a middle click, and closing the active tab selects its neighbour | open documents the user closes, like browser tabs | |
 
 Avoid icons or descriptions on only some tabs (uneven rows; without an icon on every tab the list cannot collapse to icons) and Tabs used as a filter — use SegmentedControl.
 
@@ -182,18 +182,18 @@ Avoid icons or descriptions on only some tabs (uneven rows; without an icon on e
 |---|---|---|
 | active | `value` / `defaultValue` | item `aria-selected="true"`, `data-state="active"`, `tabIndex=0`; others `data-state="inactive"`, `tabIndex=-1` |
 | hover | pointer | text → primary; the folder shape in `fill-faint`, under the folder |
-| pressed | pointer down | the tab content scales to `--prime-motion-press-scale-compact` |
-| focus-visible | keyboard | focus ring inside the tab, above the folder; the panel shows an inset ring |
+| pressed | pointer down | the tab content scales to `--prime-motion-press-scale-compact` (`internal/press`) |
+| focus-visible | keyboard | the tab draws an inset ring in its own shape, above the folder; the focused panel draws the outer ring |
 | disabled | `disabled` on Item | native `disabled`, `data-disabled="true"`, `text-disabled`; a removable tab loses its close button |
 | removable | `onRemove` on Item | item wrapper `data-removable="true"`, close button, tab `aria-keyshortcuts="Delete"` |
 | closing, confirm pending | `onRemove` returned a promise that has not settled | the close button is `loading` (`aria-busy`); the tab, its selection and focus stay; resolved → the neighbour takes over, rejected → nothing changes |
 | two-line | `Tabs.Description` child | `data-two-line="true"` |
-| collapsed | tabs wider than the list, or a label that would be cut (horizontal) | list `data-collapse="full" \| "compact" \| "icon"`: `compact` hides icons and descriptions; `icon` hides labels (sr-only, shown in a `Tooltip`), counts and close buttons, only when every tab has an icon |
-| overflow | tabs at their narrowest (content width, `minItemWidth` or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (ScrollContainer), faded edges as deep as the hidden part at most (they grow and melt with the scroll, never switch); the active tab is kept in view and clear of the fades on mount and on every value change, the first and the last tab scroll all the way to the end — only the list scrolls, never the page |
+| collapsed | tabs wider than the list, or a label that would be cut (horizontal) | list `data-collapse="full" \| "compact" \| "icon"`: `compact` hides icons and descriptions; `icon` takes labels, counts and close buttons out of the row — a `VisuallyHidden` copy of the label names the tab and a `Tooltip` shows it — only when every tab has an icon |
+| overflow | tabs at their narrowest (content width, `minItemWidth` or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (the switcher row, a ScrollContainer), faded edges as deep as the hidden part at most (they grow and melt with the scroll, never switch); the active tab is kept in view and clear of the fades on mount and on every value change, the first and the last tab scroll all the way to the end — only the list scrolls, never the page. A column (a wide vertical list) has plain edges |
 
 The indicator glides (`emphasized` + `base`, `data-animate="true"`) only into a choice by click, arrow keys or closing the active tab; on mount, a value set from outside, a resize, font loading, tabs added or removed and collapse it is placed without motion, and it stays still under `prefers-reduced-motion`. The list scrolls smoothly to the active tab only after such a choice too.
 
-Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; List `data-indicator="folder"`, its indicator `data-axis="x" | "y"` (follows the list's direction, so a vertical list in a narrow container gets the top folder); Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted; a panel's content enters each time it opens.
+Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; the folder (the list's first child, `data-indicator`) `data-axis="x" | "y"` (follows the list's direction, so a vertical list in a narrow container gets the top folder); Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted, and a tab points at its panel (`aria-controls`) only while the panel is in the document; a panel's content enters each time it opens.
 
 ## Layout & spacing
 - Tabs are a bar, not a surface: the root has no fill, padding, radius or `data-depth`. On a page or in a `Card.Body`, put it straight into the host's padded region and the panel content straight into `Tabs.Panel`. The strip's edges and the panel content share the host's content edge; the panel stands one tier gap below the strip (`--prime-space-3` … `--prime-space-8`).
@@ -214,13 +214,16 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 ```
 - The folder paints the host's `layer-current`, so the active tab is always the colour of the surface it stands on; controls in a panel read the host's field and fill tokens.
 - Vertical: the column is as wide as its widest section (at least four control heights, at most 40% of the root) and as tall as its sections; the panel sits beside it, one gap away.
-- The list never wraps: it collapses, then scrolls horizontally with faded edges (hidden scrollbar, `overscroll-behavior: contain`). Give the list's container a width (`min-width: 0` on flex children).
+- The list is a switcher (foundation §9): it never wraps — it collapses, then scrolls horizontally with faded edges (hidden scrollbar, `overscroll-behavior: contain`). Give the list's container a width (`min-width: 0` on flex children).
+- Without `size` the tabs take the tier of their host (a Card, a Drawer, a form), else `m`.
 - A horizontal tab is never narrower than its content (`min-width: max-content`; the tab bounds that content between `minItemWidth` and `maxItemWidth`), so a label is never cut to make room. Full width, tabs tend to equal widths, not widths in proportion to their labels (`flex: 1 1 0`): a long label keeps its width, the short ones share the rest.
 - A vertical Tabs.Root is a size container: give it a width (it measures itself to switch to a row).
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `ArrowLeft` · `ArrowRight` | Select the neighbouring tab, wrapping and skipping disabled ones; also work in a vertical list. |
@@ -230,11 +233,13 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 | `Tab` | Enters the active tab (roving tabindex), then moves to the panel. |
 
 ### ARIA
-- WAI-ARIA tabs pattern: `tablist` / `tab` / `tabpanel` with `aria-controls` / `aria-labelledby` wired automatically; give `Tabs.List` an `aria-label`.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- WAI-ARIA tabs pattern: `tablist` / `tab` / `tabpanel` with `aria-controls` / `aria-labelledby` wired automatically; a tab names its panel in `aria-controls` only while the panel is in the document. Give `Tabs.List` an `aria-label`.
 - Selection follows focus; the panel is focusable (`tabIndex=0`).
 - In a two-line tab the accessible name is label (+ count); `Tabs.Description` becomes `aria-describedby`.
 - `Tabs.Icon` and `Tabs.Separator` are `aria-hidden`.
-- When only icons are left, the label stays for screen readers (sr-only) and shows in a `Tooltip` on hover and focus.
+- When only icons are left, a `VisuallyHidden` copy of the label names the tab and the label shows in a `Tooltip` on hover and focus.
 - The close button of a removable tab is named after it (`labels.remove`) and stays out of the Tab order; the tab announces `aria-keyshortcuts="Delete"`.
 
 ### Labels
@@ -249,7 +254,7 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Sections of one screen; the active tab rises into the strip and glides to the next one — `defaultValue`. |
 | [variants.tsx](examples/variants.tsx) | The active tab in primary text with an accent icon, or all in accent — `tone`. |
-| [sizes.tsx](examples/sizes.tsx) | Every size tier: text, icon, folder radius and spacing grow together — `size`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier: text, icon, folder radius and spacing grow together; tabs sized to their content — `size`, `fullWidth`. |
 | [states.tsx](examples/states.tsx) | A disabled tab that clicks and arrow keys skip — `disabled`. |
 | [with-icon.tsx](examples/with-icon.tsx) | A muted icon before the label and a hairline before the service section — `Tabs.Icon`, `Tabs.Label`, `Tabs.Separator`. |
 | [orientation.tsx](examples/orientation.tsx) | Account settings with a side list of sections: the active section reaches out of the panel, and below 600px the list moves above it — `orientation`. |
@@ -272,5 +277,5 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 - Tabs inside `Drawer.Body` / `Modal.Body` under the header → a floating strip under the header's hairline; wrap the header and the body in `Tabs.Root` and put `Tabs.List` into the header.
 
 ## Related
-- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Button](../button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), Icon (`action.close`)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (`internal/SwitcherScroller`, the list), [Badge](../badge/COMPONENT.md), [Button](../button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), [VisuallyHidden](../visually-hidden/COMPONENT.md) (the label of an icon-only tab), Icon (`action.close`); `internal/selectionIndicator` (the folder), `internal/press`
 - **See also:** [SegmentedControl](../segmented-control/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Accordion](../accordion/COMPONENT.md)

package/dist/skill/reference/components/tabs/examples/in-drawer.tsx

@@ -41,7 +41,7 @@ export default function TabsInDrawerExample() {
               <DescriptionList.Root>
                 <DescriptionList.Item label="Клиент">Анна Смирнова</DescriptionList.Item>
                 <DescriptionList.Item label="Статус">
-                  <Badge.Root color="orange">Собирается на складе</Badge.Root>
+                  <Badge.Root tone="info">Собирается на складе</Badge.Root>
                 </DescriptionList.Item>
                 <DescriptionList.Item label="Оплата">Картой, 3 октября</DescriptionList.Item>
                 <DescriptionList.Item label="Менеджер">Илья Соколов</DescriptionList.Item>

package/dist/skill/reference/components/tabs/examples/sizes.tsx

@@ -1,30 +1,25 @@
-/** Every size tier: text, icon, folder radius and spacing grow together — `size`. */
+/** Every size tier: text, icon, folder radius and spacing grow together; tabs sized to their content — `size`, `fullWidth`. */
 import { Tabs, Typography } from "prime-ui-kit";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function TabsSizesExample() {
   return (
-    <>
+    <div>
       {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>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
         </div>
       ))}
-    </>
+    </div>
   );
 }

package/dist/skill/reference/components/tabs/examples/variants.tsx

@@ -11,30 +11,26 @@ const SECTIONS = [
 
 export default function TabsVariantsExample() {
   return (
-    <>
+    <div>
       {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>
+        <div key={tone}>
+          <Tabs.Root 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>
+          </Tabs.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {tone}
+          </Typography>
+        </div>
       ))}
-    </>
+    </div>
   );
 }

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

@@ -51,9 +51,11 @@ TagSelect                       field frame: label · control · hint/error (sin
 | `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. |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the list; focus stays in the input. |
+| `closeOnOutsideClick` | `boolean` | `true` | A press outside the field and the list closes the list. |
 | `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. |
+| `fallbackColor` | `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. |
@@ -65,15 +67,16 @@ TagSelect                       field frame: label · control · hint/error (sin
 | `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. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Field tier; the list uses the same tier, chips one tier down. Without it the tier of its host (a form, a panel with a size), else `m`. |
 | `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`. |
+| `className` | `string` | — | Class on the field frame `<div>`. |
 | `…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.
+No `variant` or `tone`. The control is the field look; chips are the kit's soft Badges, the palette's soft steps that read on any field fill; the list is the shared floating panel.
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -90,13 +93,17 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | `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` |
+| `closeOnOutsideClick` | `false`: the list stays open on a press beside the field; Escape and Tab still close it | The person reads the page while tagging | `true` |
+| `closeOnEscape` | `false`: Escape leaves the list open | The list must close only by Tab or a press outside | `true` |
 | `invalid` / `error` | danger inset ring (+ the message) | Validation failed | |
+| `required` / `optional` | red `*` / muted «необязательно» after the label | Mark the minority of the form | `false` / — |
+| `focusRing` | `false`: no focus ring; the field keeps its focus fill | Only where focus shows otherwise; never on a form field (WCAG 2.4.7) | `true` |
 
 ## 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` |
+| open | `open` / `defaultOpen`, 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 |
@@ -115,6 +122,8 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `ArrowDown` · `ArrowUp` | Open the list (when it has something to show) and move the highlight over the options. |
@@ -123,9 +132,12 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | `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. |
+| `Shift+F10` · `ContextMenu` | With `onOptionUpdate` or `onOptionDelete`: opens the «⋯» menu of the highlighted row; Escape closes it. |
 | `Escape` | Closes the row «⋯» menu if it is open, otherwise the list. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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`.
@@ -148,7 +160,7 @@ No `variant` or `tone`. The control is the field look; chips are soft Badges on
 | `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. |
+| `colorNames` | `"По умолчанию · Красный · Оранжевый · Жёлтый · Зелёный · Синий · Фиолетовый · Розовый · Голубой · Бирюзовый"` | Names of the palette colors in the menu, by `PaletteColor` key. |
 | `optional` | `"необязательно"` | Muted marker after the label when `optional`. |
 
 ## Examples
@@ -156,12 +168,13 @@ 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`. |
+| [states.tsx](examples/states.tsx) | A default field next to a disabled and an invalid one and one whose focus shows without the ring, with a disabled option in the list — `disabled`, `invalid`, `focusRing`. |
 | [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`. |
+| [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`, `fallbackColor`. |
 | [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`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A tag list that stays open while the person reads the task beside it: Escape or Tab close it — `closeOnOutsideClick`, `closeOnEscape`. |
 | [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`. |

package/dist/skill/reference/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 and is saved on the server: the chip waits busy, and a tag the server refuses leaves again — `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`, `fallbackColor`. */
 import { TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -27,7 +27,7 @@ export default function TagSelectCreatableExample() {
         label="Метки"
         options={OPTIONS}
         creatable
-        defaultColor="purple"
+        fallbackColor="purple"
         error={failure}
         onCreate={async (value) => {
           setFailure(undefined);

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

@@ -0,0 +1,23 @@
+/** A tag list that stays open while the person reads the task beside it: Escape or Tab close it — `closeOnOutsideClick`, `closeOnEscape`. */
+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" },
+  { value: "blocked", label: "Заблокировано", color: "orange" },
+];
+
+export default function TagSelectDismissExample() {
+  return (
+    <TagSelect
+      label="Метки задачи"
+      options={OPTIONS}
+      defaultValue={["backend"]}
+      placeholder="Добавить метку"
+      closeOnOutsideClick={false}
+      closeOnEscape
+    />
+  );
+}

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

@@ -1,11 +1,11 @@
 /* Layout of the TagSelect scenarios: semantic tokens only. */
 
-/* in-form.tsx: field → field 20, actions at the end. */
+/* in-form.tsx: the fields (a Fieldset) → actions 32 (foundation §1). */
 .form {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-space-5);
-  width: min(100%, var(--prime-modal-width-m));
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-layout-form-width-m));
 }
 
 .actions {

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

@@ -1,5 +1,5 @@
 /** 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 { Button, Fieldset, Input, TagSelect, type TagSelectOption, Typography } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -29,37 +29,36 @@ export default function TagSelectInFormExample() {
 
   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="Добавить человека"
-      />
+      <Fieldset label="Новая задача">
+        <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="Добавить человека"
+        />
+      </Fieldset>
       <div className={styles.actions}>
         {saved ? (
           <Typography as="p" variant="body-s" tone="secondary">

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

@@ -11,7 +11,7 @@ const OPTIONS: TagSelectOption[] = [
 
 export default function TagSelectSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
         <TagSelect
           key={size}
@@ -22,6 +22,6 @@ export default function TagSelectSizesExample() {
           labels={{ panelHint: "Выберите метку" }}
         />
       ))}
-    </>
+    </div>
   );
 }

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

@@ -1,4 +1,4 @@
-/** A default field next to a disabled and an invalid one, with a disabled option in the list — `disabled`, `invalid`. */
+/** A default field next to a disabled and an invalid one and one whose focus shows without the ring, with a disabled option in the list — `disabled`, `invalid`, `focusRing`. */
 import { TagSelect, type TagSelectOption } from "prime-ui-kit";
 
 const OPTIONS: TagSelectOption[] = [
@@ -10,7 +10,7 @@ const OPTIONS: TagSelectOption[] = [
 
 export default function TagSelectStatesExample() {
   return (
-    <>
+    <div>
       <TagSelect
         label="default"
         options={OPTIONS}
@@ -19,6 +19,13 @@ export default function TagSelectStatesExample() {
       />
       <TagSelect label="disabled" options={OPTIONS} defaultValue={["msk", "kzn"]} disabled />
       <TagSelect label="invalid" options={OPTIONS} invalid placeholder="Добавить город" />
-    </>
+      <TagSelect
+        label="focusRing={false}"
+        options={OPTIONS}
+        defaultValue={["spb"]}
+        focusRing={false}
+        placeholder="Добавить город"
+      />
+    </div>
   );
 }

package/dist/skill/reference/components/textarea/COMPONENT.md

@@ -41,7 +41,7 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier for text, padding, radius, label and hint. One line of text sits exactly like an Input of the same size. Without it the tier of its host (LoginForm, Popover, a panel with a size), else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier for text, padding, radius, label and hint. One line of text sits exactly like an Input of the same size. Without it the tier of its host (LoginForm, Popover, a panel with a size), else `m`. |
 | `label` | `ReactNode` | — | Label above the field (`<label htmlFor>`). Without it, set `aria-label`. |
 | `required` | `boolean` | — | Native `required` on the textarea and a red `*` after the label (`aria-hidden`). |
 | `optional` | `boolean` | `false` | Muted marker right after the label text (`labels.optional`). |
@@ -49,7 +49,7 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger inset ring on the field box, `aria-invalid` on the textarea. A non-empty `error` implies it. |
 | `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring on the field box (`data-focus-ring="false"`); focus, keyboard, ARIA and the invalid ring stay. |
-| `counter` | `ReactNode` | — | Right side of the support row, usually `<Textarea.Counter />`. |
+| `counter` | `ReactNode` | — | Right side of the support row, usually `<Textarea.Counter current max />`. |
 | `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 `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. |
@@ -78,7 +78,7 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `string` | `the field's value` | Text to copy instead of the field's current value. |
+| `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
@@ -114,7 +114,7 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `focusRing={false}` | No focus ring; focus fill and caret remain | A single composer field where focus is obvious | `true` |
+| `focusRing` | `false`: no focus ring; focus fill and caret remain | A single composer field where focus is obvious | `true` |
 | `formatting` | A floating toolbar over a selection (bold, italic, strikethrough, code, spoiler, link, quote) and the Mod-hotkeys; each writes Markdown around the selection | The text is shown later with its Markdown (Message renders the same subset) | `false` |
 | `reserveSupportRow` | Empty support row of hint height | Live validation, fields side by side | `false` |
 | `required` / `optional` | Red `*` / muted «необязательно» after the label | Mark the minority of the form | — / `false` |
@@ -148,7 +148,7 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 
 ## Layout & spacing
 - Label → field: tier `label-gap` (`--prime-space-1` on xs/s, `--prime-space-2` on m–xl); field → support row: tier `hint-gap`.
-- Field → field in a form: `--prime-space-5`; group → actions: `--prime-space-8`.
+- Fields of a form stack in a label-less [Fieldset](../fieldset/COMPONENT.md) (20 apart); the form around the groups spaces them from its actions (32).
 - Width is always `100%` of the parent; set the width with the layout column.
 - Long words wrap (`overflow-wrap: anywhere`), so the field never overflows horizontally.
 - With `formatting` the toolbar floats `--prime-space-2` above the field box's start edge on the floating layer, over whatever is above the field; it takes no room in the layout.
@@ -156,6 +156,8 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Focuses the field, then the buttons in its corner; Enter inserts a line break instead of submitting the form. |
@@ -166,6 +168,8 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 | `Home` · `End` | Jump to the first / last formatting button. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `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.
@@ -200,7 +204,7 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 |---|---|
 | [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`. |
+| [states.tsx](examples/states.tsx) | A default field next to a read-only, a disabled and an invalid one with no message — `readOnly`, `disabled`, `invalid`. |
 | [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`. |
@@ -222,5 +226,5 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 - `formatting` on text that is shown as plain text → the reader sees `**` and `||`; turn it on only where the text is rendered with its Markdown.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (corner actions, formatting tools), [Spinner](../spinner/COMPONENT.md) (`onCommit`), [Button](../button/COMPONENT.md) and [Kbd](../kbd/COMPONENT.md) (formatting tools), Icon (`format.*`); `internal/textFormatting` + `internal/textFormattingToolbar` (the formatting shared with Composer)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (corner actions, formatting tools), [Spinner](../spinner/COMPONENT.md) (`onCommit`), [Button](../button/COMPONENT.md) and [Kbd](../kbd/COMPONENT.md) (formatting tools), Icon (`format.*`); `internal/textFormatting` + `internal/textFormattingToolbar` (the formatting shared with Composer), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **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/dist/skill/reference/components/textarea/examples/examples.module.css

@@ -1,23 +1,10 @@
 /* Layout of the Textarea scenarios: semantic tokens only. */
 
-/* in-form.tsx: field → field 20, group → actions 32 (foundation §1). */
+/* in-form.tsx, validation.tsx: the fields (a Fieldset), then the actions — group → actions 32. */
 .form {
-  display: flex;
-  flex-direction: column;
+  display: grid;
   gap: var(--prime-space-8);
-  width: min(100%, var(--prime-modal-width-m));
-}
-
-.formHeader {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-1);
-}
-
-.formFields {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-5);
+  width: min(100%, var(--prime-layout-form-width-m));
 }
 
 .formActions {