prime-ui-kit 0.9.0 → 0.9.2

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

@@ -1,31 +1,43 @@
-/** Off, on, disabled in both positions, read-only and invalid switches. Use it as a reference for every visual state. */
+/** Every state side by side, each labelled by its prop — `checked`, `readOnly`, `invalid`, `disabled`. */
 import { Switch } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 export default function SwitchStatesExample() {
   return (
-    <div className={styles.grid}>
-      <Switch.Root>
-        <Switch.Label>Выключен</Switch.Label>
-      </Switch.Root>
-      <Switch.Root defaultChecked>
-        <Switch.Label>Включён</Switch.Label>
-      </Switch.Root>
-      <Switch.Root disabled>
-        <Switch.Label>Отключён, выкл.</Switch.Label>
-      </Switch.Root>
-      <Switch.Root defaultChecked disabled>
-        <Switch.Label>Отключён, вкл.</Switch.Label>
-      </Switch.Root>
-      <Switch.Root defaultChecked readOnly>
-        <Switch.Label>Только чтение</Switch.Label>
-        <Switch.Hint>Меняет администратор.</Switch.Hint>
-      </Switch.Root>
-      <Switch.Root>
-        <Switch.Label>Ошибка</Switch.Label>
-        <Switch.Error>Включите, чтобы продолжить.</Switch.Error>
-      </Switch.Root>
-    </div>
+    <>
+      <div>
+        <div>
+          <Switch.Root>
+            <Switch.Label>unchecked</Switch.Label>
+          </Switch.Root>
+        </div>
+        <div>
+          <Switch.Root defaultChecked>
+            <Switch.Label>checked</Switch.Label>
+          </Switch.Root>
+        </div>
+        <div>
+          <Switch.Root defaultChecked readOnly>
+            <Switch.Label>readOnly</Switch.Label>
+          </Switch.Root>
+        </div>
+        <div>
+          <Switch.Root invalid>
+            <Switch.Label>invalid</Switch.Label>
+          </Switch.Root>
+        </div>
+      </div>
+      <div>
+        <div>
+          <Switch.Root disabled>
+            <Switch.Label>disabled</Switch.Label>
+          </Switch.Root>
+        </div>
+        <div>
+          <Switch.Root disabled defaultChecked>
+            <Switch.Label>disabled · checked</Switch.Label>
+          </Switch.Root>
+        </div>
+      </div>
+    </>
   );
 }

package/src/components/tabs/COMPONENT.md

@@ -1,13 +1,16 @@
 # Tabs
 
 **Category:** navigation
+**Kind:** navigation
 
-> Tabs for navigating between content panels of one screen.
+> Folder tabs for navigating between content panels of one screen: the active tab rises out of the panel.
 
 ## When to use
 - Splitting one screen into sections that are viewed one at a time (Overview / Orders / Reviews).
 - Settings pages with a side list of sections (`orientation="vertical"`).
 - Dashboard sections that need a counter or a one-line summary per tab (`Tabs.Count`, `Tabs.Description`).
+- Section bars that must survive narrow containers: with an icon on every tab they collapse to icons with tooltips.
+- Open documents or records the user switches between and closes, like browser tabs (`onRemove`, `minItemWidth`, `maxItemWidth`).
 
 ## When not to use
 - Choosing a value or a mode (period, list view, filter) → use [SegmentedControl](../segmented-control/COMPONENT.md).
@@ -22,166 +25,233 @@ import { Tabs } from "prime-ui-kit";
 ```
 
 ## Anatomy
-- `Tabs.Root` — state, size and orientation; lays out the list and the panel.
-  - `Tabs.List` — `role="tablist"` with the sliding indicator; scrolls instead of wrapping.
-    - `Tabs.Trigger` — one tab (`role="tab"`). Plain text, or parts:
-      - `Tabs.Icon` — decorative icon.
-      - `Tabs.Label` — title; truncates, keeps a stable width when it becomes medium weight.
-      - `Tabs.Count` — counter badge, one tier below the tabs size.
-      - `Tabs.Description` — muted second line; makes the trigger two-line.
-  - `Tabs.Panel` — `role="tabpanel"`, rendered only while its tab is active.
+```
+Tabs.Root                 value, size, orientation, tone, fullWidth, min/maxItemWidth; horizontal: the frame
+├─ Tabs.List              role="tablist" on a ScrollContainer, sliding folder / pill; 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
+│  │  ├─ Tabs.Count       counter Badge, one tier below the tabs size
+│  │  └─ Tabs.Description muted second line; makes the tab two-line
+│  └─ Tabs.Separator      Divider hairline between groups of tabs
+└─ Tabs.Panel             role="tabpanel", rendered only while its tab is active
+```
 
 ## API
-No part forwards a ref.
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Tabs.Root
-+ native `<div>` props (except `defaultValue`, `children`).
+`ref` → `HTMLDivElement`. `<div>` that owns the active value, size and orientation and lays out the list and the panel; horizontal, it is the frame: a sunken strip over the panel surface.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `string` | — | Active tab (controlled). |
 | `defaultValue` | `string` | `""` | Initial active tab (uncontrolled). With `""` no tab is selected. |
-| `onValueChange` | `(value: string) => void` | — | Called when the active tab changes. |
+| `onValueChange` | `(value: string) => void` | — | Called with the new active value. |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | List direction and arrow keys. A vertical list stacks above the panel when the container is narrower than 600px. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier: tab height, text, icon, radius, spacing. |
-| `children` | `ReactNode` | — (required) | `Tabs.List` and `Tabs.Panel`s. |
-| `className` | `string` | — | Extra class on the root. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Control tier: text, icon, spacing, folder radius and panel padding. A horizontal tab is the control height plus the folder rise on both sides; a vertical one is the control height. |
+| `fullWidth` | `boolean` | `true` | Horizontal tabs fill the list and tend to equal widths within `minItemWidth` … `maxItemWidth`, never narrower than their content: a long label keeps its width, short ones share the rest; when they do not fit, the list collapses, then scrolls. `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`). When tabs do not fit, the list collapses, then scrolls. Icon-only tabs are square. |
+| `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
-+ native `<div>` props (pass `aria-label`) except `role`, `aria-orientation`, `onKeyDown`, `onScroll` — they are set after the spread and override yours.
+`ref` → `HTMLDivElement`. `role="tablist"` on a `ScrollContainer` (horizontal, edge fade, hidden scrollbar) with the sliding folder (vertical: pill), which glides only into a choice by click or keys and is placed without motion on mount, resize and collapse. When tabs do not fit or a label would be cut, it hides icons and descriptions, then labels (icons with tooltips stay; only when every tab has an icon); then the list scrolls; a label is never cut to make room. The active tab is kept in view: only the list scrolls, never the page.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | `Tabs.Trigger`s. |
-| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | `Tabs.Item`s and `Tabs.Separator`s. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `aria-label` (name the list), `className` and the other div attributes; `role`, `aria-orientation` and `onKeyDown` are set by the list. |
 
-### Tabs.Trigger
-+ native `<button>` props except `value`, `children`, `type`, `role`, `onClick`.
+### Tabs.Item
+`ref` → `HTMLButtonElement`. One tab, a `<button role="tab">` in an item wrapper that also holds the close button of a removable tab; plain text children are wrapped in `Tabs.Label`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `string` | — (required) | Value that selects this tab and its panel. |
-| `disabled` | `boolean` | `false` | Disables the tab; arrow keys skip it. |
-| `children` | `ReactNode` | — (required) | Plain text (auto-wrapped in `Tabs.Label`) or `Tabs.Icon` / `Tabs.Label` / `Tabs.Count` / `Tabs.Description`. |
-| `className` | `string` | — | Extra class. |
+| `disabled` | `boolean` | `false` | Disables the tab; clicks and arrow keys skip it. |
+| `onRemove` | `() => void` | — | Makes the tab closable: a close button (shown on the active tab, on hover and focus, always on touch screens), `Delete` / `Backspace` and a middle click. Closing the active tab first selects its neighbour; remove the item from your list here. |
+| `children` | `ReactNode` | — (required) | Plain text, or `Tabs.Icon` / `Tabs.Label` / `Tabs.Count` / `Tabs.Description`. A description makes the tab two-line. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" \| "type" \| "role" \| "onClick">` | — | `className`, `aria-*` and the other button attributes; your `onKeyDown` / `onAuxClick` run first and `preventDefault()` keeps the tab open. |
 
-### Tabs.Icon, Tabs.Label, Tabs.Description
-+ native `<span>` props.
+### Tabs.Icon
+`ref` → `HTMLSpanElement`. Decorative icon (`aria-hidden`) before the label; muted, accent on the active tab. Hidden first when tabs do not fit; the last thing left when nothing else fits.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | Icon SVG / title text / second-line text (wrap a key value in `<strong>`). |
-| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="field.calendar" />`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+### Tabs.Label
+`ref` → `HTMLSpanElement`. Title; truncates and keeps a stable width when it turns medium weight.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Title text. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Tabs.Count
-No native props.
+`ref` → `HTMLSpanElement`. Counter `Badge` after the label, one tier below the tabs size.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Badge hue. |
 | `children` | `ReactNode` | — (required) | The number. |
-| `className` | `string` | — | Extra class. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+### Tabs.Description
+`ref` → `HTMLSpanElement`. Muted second line; becomes the tab's `aria-describedby`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Second-line text; wrap a key value in `<strong>`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+### Tabs.Separator
+`ref` → `HTMLDivElement`. A `Divider` hairline between groups of tabs, across the list direction; hidden from assistive tech.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other div attributes. |
 
 ### Tabs.Panel
-+ native `<div>` props.
+`ref` → `HTMLDivElement`. `<div role="tabpanel">`, focusable, rendered only while its tab is active; horizontal, the padded surface the folder rises from. Its content enters each time it opens.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `string` | — (required) | Tab value this panel belongs to. |
-| `children` | `ReactNode` | — (required) | Panel content. |
-| `className` | `string` | — | Extra class. |
+| `children` | `ReactNode` | — | Panel content. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
 
 ## Variants
-Tabs have no `variant`: navigation tabs are always underline (horizontal) or pill (vertical).
+Tabs have no `variant`: navigation tabs are always a folder (horizontal) or pills (vertical).
+
+### tone
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `neutral` | active tab in primary text, medium weight, its leading icon in `accent-text` | most screens | yes |
+| `accent` | active label and icon both in `accent-text` | the tabs are the main control of the screen and must read as selected at a glance | |
 
 ### orientation
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `horizontal` | regular-weight secondary text over a `border-subtle` hairline; the active tab is primary text, medium weight, with a 2px accent bar under its text that slides between tabs | switching sections above the content | yes |
+| `horizontal` | a `bg-sunken` strip over a padded `bg-surface` panel, tabs edge to edge; the active tab is the panel surface rising into the strip with concave flares, gliding between tabs; primary text, medium weight, accent icon; hover is the same shape in `fill-faint` | switching sections above the content | yes |
 | `vertical` | items padded like controls, no rail; active item is a `fill-muted` pill with a short accent mark at the start; hover `fill-subtle`; below a 600px container it becomes a scrolling row above the panel | settings pages with a side list of sections | |
 
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | 28px tabs, 12/16 text, gap between tabs 12 | dense panels | |
-| `s` | 32px, 13/20, gap 16 | compact cards | |
-| `m` | 36px, 14/20, gap 20 | default | yes |
-| `l` | 40px, 16/24, gap 24 | page-level sections | |
-| `xl` | 48px, 16/24, gap 32 | hero / landing sections | |
+| `xs` | 12/16 text, folder radius 8, rise 4, panel padding 16 | dense panels | |
+| `s` | 13/20, radius 8, rise 4, padding 20 | compact cards | |
+| `m` | 14/20, radius 12, rise 8, padding 24 | default | yes |
+| `l` | 16/24, radius 16, rise 12, padding 24 | page-level sections | |
+| `xl` | 16/24, radius 16, rise 12, padding 32 | hero / landing sections | |
 
-Tab height equals the control height: Tabs line up with Button, Input and SegmentedControl of the same `size`.
+A horizontal tab is the control height of the tier plus the rise above and below its content; a vertical tab is the control height, so a vertical list lines up with Button, Input and SegmentedControl of the same `size`.
 
-### Trigger content
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fullWidth` | horizontal tabs fill the list and tend to equal widths (`flex: 1 1 0`, up to `maxItemWidth`), content centred; a tab is never narrower than its content or `minItemWidth`, so a long label keeps its width and the short ones share the rest; `false` sizes each tab to its content, the strip still spans the frame | `false` for tabs of very different label lengths | `true` |
+
+### minItemWidth · maxItemWidth
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| defaults | a horizontal tab is 2.5 to 7 control heights wide (90 … 252 at `m`); tabs never stretch into wide bars | most screens | yes |
+| lengths (`128`, `"16rem"`) | browser tabs: grow up to `maxItemWidth` with the label cut by an ellipsis past it, never narrower than `minItemWidth` or their title up to the cap; in a crowded list the list scrolls | open documents, records, chats — many tabs with long titles | |
+| `maxItemWidth="none"` | tabs share the whole strip | a few sections that must fill a wide frame | |
+
+### Item content
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | text | label only | most tabs | yes |
 | `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, one badge tier below the tabs size, 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; tab height grows; `<strong>` is primary/medium | dashboards with a summary per section | |
+| `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 | open documents the user closes, like browser tabs | |
 
-**Combinations**
-- Recommended: `Tabs.Count color="blue"` on the active tab and `gray` on others (see `controlled.tsx`); per-section hues in two-line dashboards.
-- Avoid: icons on only some tabs; a `Tabs.Description` on only some tabs (rows of uneven height); Tabs used as a filter — use SegmentedControl.
+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.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| active | `value` / `defaultValue` | trigger `aria-selected="true"`, `data-state="active"`, `tabIndex=0`; others `data-state="inactive"`, `tabIndex=-1` |
-| hover | pointer | text → primary (vertical: `fill-subtle` background) |
-| focus-visible | keyboard | focus ring inside the tab (`--prime-focus-offset-inset`); panel shows the outer ring |
-| disabled | `disabled` on Trigger | native `disabled`, `data-disabled="true"`, `text-disabled` |
+| active | `value` / `defaultValue` | item `aria-selected="true"`, `data-state="active"`, `tabIndex=0`; others `data-state="inactive"`, `tabIndex=-1` |
+| hover | pointer | text → primary; horizontal: the folder shape in `fill-faint`, under the folder; vertical: `fill-subtle` background |
+| 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 (vertical: 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"` |
 | two-line | `Tabs.Description` child | `data-two-line="true"` |
-| overflow | list wider than its container | `data-overflow-start` / `data-overflow-end="true"` on the list, faded edges; the active tab scrolls into view |
+| 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; the active tab is kept in view on mount and on every value change — only the list scrolls, never the page |
 
-Other attributes: Root `data-orientation`, `data-size`; List `data-indicator="bar" | "pill"`; Trigger `data-value`; Label `data-text`. Controlled: `value` + `onValueChange`; uncontrolled: `defaultValue`. Inactive panels are unmounted.
+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" | "pill"`; 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.
 
 ## Layout & spacing
-- List → panel: `var(--prime-space-4)`; vertical list → panel: `var(--prime-space-6)`.
-- The list never wraps; it scrolls horizontally with faded edges. Give the list's container a width (`min-width: 0` on flex children).
+- Horizontal: the root is the frame (`radius-xl`, `bg-sunken`), the list sits flush on the panel and runs edge to edge; the panel pads its content by tier (`--prime-space-4` … `--prime-space-8`). Do not wrap Tabs in a Card — it already is one.
+- Vertical list → panel: `var(--prime-space-6)`.
+- 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).
+- 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).
 - In a vertical layout align the panel heading with the first tab by making the heading row one control tall (`min-height: var(--prime-control-m-height)`).
 
 ## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `ArrowLeft` · `ArrowRight` | Select the neighbouring tab, wrapping and skipping disabled ones; also work in a vertical list. |
+| `ArrowUp` · `ArrowDown` | The same in a vertical list. |
+| `Home` · `End` | First and last enabled tab. |
+| `Delete` · `Backspace` | Close a tab with `onRemove`; closing the active tab selects and focuses its neighbour. |
+| `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`.
-- Keyboard: horizontal ← →, vertical ↑ ↓ (← → also work), Home / End; selection follows focus and wraps; disabled tabs are skipped. Roving tabindex — Tab enters the active tab, then moves to the panel (`tabIndex=0`).
+- 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` is `aria-hidden`. No `labels` keys.
+- `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.
+- 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"`.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [horizontal.tsx](examples/horizontal.tsx) | Underline tabs with panels | switching panels of one screen |
-| [sizes.tsx](examples/sizes.tsx) | Every size next to a Button of the same size | aligning tabs with controls |
-| [states.tsx](examples/states.tsx) | Icons, disabled tab, overflow at phone width | icons, unavailable sections, narrow screens |
-| [controlled.tsx](examples/controlled.tsx) | `value` + `onValueChange` with `Tabs.Count` | tab in app state / URL |
-| [two-line.tsx](examples/two-line.tsx) | Label + Count + Description | dashboards with per-section summary |
-| [vertical.tsx](examples/vertical.tsx) | Vertical settings tabs in a card | settings pages |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-```tsx
-import { Tabs } from "prime-ui-kit";
+| Key | Default | Used for |
+|---|---|---|
+| `remove` | `"Закрыть вкладку «{label}»"` | Accessible name of the close button of a removable tab; `{label}` is the tab title (its value when the title is not text). |
 
-export function ShopTabs() {
-  return (
-    <Tabs.Root defaultValue="overview">
-      <Tabs.List aria-label="Магазин">
-        <Tabs.Trigger value="overview">Обзор</Tabs.Trigger>
-        <Tabs.Trigger value="orders">Заказы</Tabs.Trigger>
-      </Tabs.List>
-      <Tabs.Panel value="overview">Сводка по магазину.</Tabs.Panel>
-      <Tabs.Panel value="orders">Последние заказы.</Tabs.Panel>
-    </Tabs.Root>
-  );
-}
-```
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Sections of one screen; the active tab rises into the panel 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`. |
+| [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) | Tabs over the panel and a side list of sections that stacks on top below 600px — `orientation`. |
+| [overflow.tsx](examples/overflow.tsx) | Drag the frame narrower: icons go first, then labels, and icons with tooltips stay; then the list scrolls — `Tabs.Icon`. |
+| [closable.tsx](examples/closable.tsx) | Open order cards as browser tabs: each closes by its button, Delete or a middle click; tabs stay between two widths, and the list scrolls when they do not fit — `onRemove`, `minItemWidth`, `maxItemWidth`. |
+| [two-line.tsx](examples/two-line.tsx) | A label and a counter on the first line, a summary on the second — `Tabs.Count`, `Tabs.Description`. |
+| [controlled.tsx](examples/controlled.tsx) | The active tab lives in parent state, e.g. synced with the URL — `value`, `onValueChange`. |
 
 ## Mistakes
-- `<Tabs.Root>` without `defaultValue`/`value` → no tab is active; pass the first tab's value.
+- `<Tabs.Root>` without `defaultValue` / `value` → no tab is active; pass the first tab's value.
 - `variant="pills"` / `variant="underline"` → Tabs have no variant; use `orientation`, or SegmentedControl for a pill switch.
+- An icon on only some tabs → the list cannot collapse to icons and scrolls instead; give every tab an icon or none.
+- Tabs inside a `Card.Root` → a frame in a frame; the horizontal root is the surface.
 - Using Tabs to filter a list → use SegmentedControl.
-- `onClick` on `Tabs.Trigger` → use `onValueChange` on Root.
+- `onClick` on `Tabs.Item` → use `onValueChange` on Root.
+- A hand-made × inside `Tabs.Item` → a button inside a tab button; pass `onRemove` instead.
+- `onRemove` that does not drop the tab from your list → the tab stays; the kit only moves the selection.
 - `Tabs.List` without `aria-label` → add one.
 
 ## Related
-- [SegmentedControl](../segmented-control/COMPONENT.md)
-- [ButtonGroup](../button-group/COMPONENT.md)
-- [Accordion](../accordion/COMPONENT.md)
-- [Badge](../badge/COMPONENT.md)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Button](../button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md)
+- **See also:** [SegmentedControl](../segmented-control/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Accordion](../accordion/COMPONENT.md)

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

@@ -0,0 +1,48 @@
+/** Open order cards as browser tabs: each closes by its button, Delete or a middle click; tabs stay between two widths, and the list scrolls when they do not fit — `onRemove`, `minItemWidth`, `maxItemWidth`. */
+import { Button, Tabs, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const ORDERS = [
+  { id: "10482", client: "Северный ветер", total: "184 200 ₽" },
+  { id: "10479", client: "ИП Корнеева", total: "36 900 ₽" },
+  { id: "10471", client: "Техноплан", total: "512 040 ₽" },
+  { id: "10466", client: "Балтийская логистическая компания", total: "97 300 ₽" },
+  { id: "10458", client: "ИП Гусев", total: "12 400 ₽" },
+];
+
+export default function TabsClosableExample() {
+  const [openOrders, setOpenOrders] = React.useState(ORDERS);
+
+  if (openOrders.length === 0) {
+    return (
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpenOrders(ORDERS)}>
+        Открыть заказы снова
+      </Button.Root>
+    );
+  }
+
+  return (
+    <Tabs.Root defaultValue="10479" minItemWidth={160} maxItemWidth={224}>
+      <Tabs.List aria-label="Открытые заказы">
+        {openOrders.map((order) => (
+          <Tabs.Item
+            key={order.id}
+            value={order.id}
+            onRemove={() =>
+              setOpenOrders((orders) => orders.filter((item) => item.id !== order.id))
+            }
+          >
+            {order.client}
+          </Tabs.Item>
+        ))}
+      </Tabs.List>
+      {openOrders.map((order) => (
+        <Tabs.Panel key={order.id} value={order.id}>
+          <Typography variant="body-m" tone="secondary">
+            Заказ № {order.id}, {order.client}, сумма {order.total}.
+          </Typography>
+        </Tabs.Panel>
+      ))}
+    </Tabs.Root>
+  );
+}

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

@@ -1,37 +1,31 @@
-/** Controlled tabs (`value` + `onValueChange`) with `Tabs.Count` counters. Use when the active tab lives in app state or the URL. */
+/** The active tab lives in parent state, e.g. synced with the URL — `value`, `onValueChange`. */
 import { Tabs, Typography } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./examples.module.css";
-
-const tabs = [
+const QUEUES = [
   { value: "new", label: "Новые", count: 12 },
   { value: "progress", label: "В работе", count: 5 },
   { value: "done", label: "Готово", count: 148 },
 ];
 
 export default function TabsControlledExample() {
-  const [value, setValue] = React.useState("new");
-  const current = tabs.find((t) => t.value === value);
+  const [queue, setQueue] = React.useState("new");
 
   return (
-    <Tabs.Root value={value} onValueChange={setValue}>
+    <Tabs.Root value={queue} onValueChange={setQueue}>
       <Tabs.List aria-label="Заявки">
-        {tabs.map((t) => (
-          <Tabs.Trigger key={t.value} value={t.value}>
-            <Tabs.Label>{t.label}</Tabs.Label>
-            <Tabs.Count color={t.value === value ? "blue" : "gray"}>{t.count}</Tabs.Count>
-          </Tabs.Trigger>
+        {QUEUES.map((item) => (
+          <Tabs.Item key={item.value} value={item.value}>
+            <Tabs.Label>{item.label}</Tabs.Label>
+            <Tabs.Count color={item.value === queue ? "blue" : "gray"}>{item.count}</Tabs.Count>
+          </Tabs.Item>
         ))}
       </Tabs.List>
-      {tabs.map((t) => (
-        <Tabs.Panel key={t.value} value={t.value}>
-          <Typography.Root variant="body-m" tone="secondary">
-            Заявок в разделе «{current?.label}»:{" "}
-            <Typography.Root as="span" variant="body-m" tone="muted" className={styles.count}>
-              {current?.count}
-            </Typography.Root>
-          </Typography.Root>
+      {QUEUES.map((item) => (
+        <Tabs.Panel key={item.value} value={item.value}>
+          <Typography variant="body-m" tone="secondary">
+            Заявок в разделе «{item.label}»: {item.count}.
+          </Typography>
         </Tabs.Panel>
       ))}
     </Tabs.Root>

package/src/components/tabs/examples/examples.module.css

@@ -1,98 +1,18 @@
-/* Layout for the Tabs examples: semantic tokens only. */
+/* Layout of the Tabs scenarios: semantic tokens only. */
 
-.stack {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-8);
-  width: 100%;
-  min-width: 0;
-}
-
-.group {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-2);
-  width: 100%;
-  min-width: 0;
-}
-
-.sizes {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-4);
-  width: 100%;
-  min-width: 0;
-}
-
-/* label · tabs · button of the same tier on one baseline row */
-.sizeRow {
-  display: flex;
-  align-items: center;
-  gap: var(--prime-space-4);
-  min-width: 0;
-}
-
-.sizeRow > :nth-child(2) {
-  flex: 0 1 auto;
-  min-width: 0;
-}
-
-.caption {
-  flex: none;
-  width: var(--prime-space-8);
-}
-
-/* ≈375px — a phone-width container. */
-.narrow {
-  width: min(100%, calc(var(--prime-drawer-width-s) + var(--prime-space-4)));
-}
-
-.card {
+/* A column for Tabs that fill their frame (a vertical root measures its own width, so it needs
+   one): wide enough to show the strip, narrower than the preview. */
+.frame {
   box-sizing: border-box;
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-4);
-  width: min(100%, calc(var(--prime-modal-width-l) - var(--prime-space-4)));
-  padding: var(--prime-card-padding-m);
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-card-bg);
-  box-shadow: var(--prime-card-shadow);
-  --prime-color-field-bg: var(--prime-color-field-bg-surface);
-}
-
-.form {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-5);
-  max-width: calc(var(--prime-drawer-width-s) + var(--prime-space-6));
-}
-
-/* Settings panel: the heading row is one control tall, so it lines up with the first tab. */
-.section {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-4);
-  min-width: 0;
-}
-
-.sectionHead {
-  display: flex;
-  align-items: center;
-  min-height: var(--prime-control-m-height);
-}
-
-.rows {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-5);
-}
-
-/* Fleet dashboard: two-line underline tabs across the frame. */
-.fleet {
-  width: 100%;
-  min-width: 0;
+  width: min(100%, calc(16 * var(--prime-control-m-height)));
+  margin-inline: auto;
 }
 
-.count {
-  font-variant-numeric: tabular-nums;
+/* The same column, which the reader can drag narrower to watch the tabs collapse and scroll. */
+.resizable {
+  composes: frame;
+  min-width: calc(3 * var(--prime-control-m-height));
+  max-width: 100%;
+  overflow: hidden;
+  resize: horizontal;
 }