prime-ui-kit 0.21.1 → 0.21.3

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

@@ -199,7 +199,7 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 
 ## 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`).
-- In a Modal or Drawer the tabs belong to the header: `Tabs.Root` wraps `X.Header` and `X.Body`, `Tabs.List` goes last into the header, the panels into the body. The header becomes the strip (painted like it, no hairline, edge to edge — the header hands the bar its side padding as `--prime-bleed-inline`), the active tab is the body rising into it, and the root renders no box (`display: contents`), so only the body scrolls and the tabs stay in view.
+- In a Modal or Drawer the tabs belong to the header: `Tabs.Root` wraps `X.Header` and `X.Body`, `Tabs.List` goes last into the header, the panels into the body. The header becomes the strip (painted like it, no hairline, edge to edge — the header hands the bar its side padding as `--prime-bleed-inline`), the active tab is the body rising into it, and the root renders no box (`display: contents`), so only the body scrolls and the tabs stay in view. A panel in the body stands its blocks 32 apart — the step between the body's sections — so a tab of self-titled blocks (charts, titled cards) or of `X.Section`s needs no spacing wrapper.
 
 ```tsx
 <Drawer.Content>
@@ -216,7 +216,7 @@ 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 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).
+- The list is a switcher (foundation §9): it never wraps — it collapses, then scrolls horizontally with faded edges (hidden scrollbar; at its sideways edge it stops, a vertical wheel goes on to the page). 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).

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

@@ -30,7 +30,6 @@ TagSelect                       field frame: label · control · hint/error (sin
 │   ├── 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
 ```
@@ -150,7 +149,6 @@ No `variant` or `tone`. The control is the field look; chips are the kit's soft
 
 | 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. |

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

@@ -15,7 +15,6 @@ export default function TagSelectOverviewExample() {
       options={OPTIONS}
       defaultValue={["design"]}
       placeholder="Добавить метку"
-      labels={{ panelHint: "Выберите метку" }}
     />
   );
 }

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

@@ -19,7 +19,6 @@ export default function TagSelectSizesExample() {
           label={size}
           options={OPTIONS}
           defaultValue={["design", "backend"]}
-          labels={{ panelHint: "Выберите метку" }}
         />
       ))}
     </div>

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

@@ -59,7 +59,7 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 | `id` | `string` | — | Id of the `<textarea>` (auto-generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
 | `aria-describedby` | `string` | — | Merged before the hint/error ids. |
 | `onCommit` | `(value: string) => void \| Promise<void>` | — | Inline save: fires with a changed value on blur and Mod+Enter; Escape reverts. Return a Promise: the field shows a spinner and stays editable; a rejection restores the value — show why through `error`. |
-| `formatting` | `boolean` | `false` | Selecting text shows a floating toolbar of seven Markdown tools and enables their hotkeys; a tool wraps the selection, a second press unwraps it. Off: plain text. |
+| `formatting` | `boolean` | `false` | Selecting text shows a floating toolbar of eight Markdown tools and enables their hotkeys; a tool wraps the selection, a second press unwraps it. Off: plain text. |
 | `children` | `ReactNode` | — | Actions in the field's top end corner: `Textarea.CopyButton`, `Textarea.Action`. |
 | `labels` | `Partial<TextareaLabels>` | — | Built-in strings, see Labels. |
 | `className` | `string` | — | Class on the field frame `<div>` (label, field box, support row), as on every field root. |
@@ -116,7 +116,7 @@ Textarea has no `variant` or `tone`: one field treatment (fill, no visible borde
 | 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` |
-| `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` |
+| `formatting` | A floating toolbar over a selection (bold, italic, underline, 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` |
 
@@ -164,7 +164,7 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 | `Tab` | Focuses the field, then the buttons in its corner; Enter inserts a line break instead of submitting the form. |
 | `Mod+Enter` | With `onCommit`: saves a changed text; focus stays in the field. |
 | `Escape` | With `formatting`: first clears a selection with the toolbar. With `onCommit`: puts the committed text back. |
-| `Mod + B` · `Mod + I` · `Mod + Shift + X` · `Mod + E` · `Mod + Shift + H` · `Mod + K` · `Mod + Shift + 9` | With `formatting`: bold, italic, strikethrough, code, spoiler, link and quote for the selection; the physical key counts, so any layout works. |
+| `Mod + B` · `Mod + I` · `Mod + U` · `Mod + Shift + X` · `Mod + E` · `Mod + Shift + H` · `Mod + K` · `Mod + Shift + 9` | With `formatting`: bold, italic, underline, strikethrough, code, spoiler, link and quote for the selection; the physical key counts, so any layout works. |
 | `←` · `→` | Move between the formatting buttons. |
 | `Home` · `End` | Jump to the first / last formatting button. |
 
@@ -194,6 +194,7 @@ Inline save (`onCommit`): the text at focus is the committed one; blur and Mod+E
 | `formatting` | `"Форматирование"` | Accessible name of the formatting toolbar. |
 | `bold` | `"Жирный"` | Bold tool. |
 | `italic` | `"Курсив"` | Italic tool. |
+| `underline` | `"Подчёркнутый"` | Underline tool (`__…__`). |
 | `strikethrough` | `"Зачёркнутый"` | Strikethrough tool. |
 | `code` | `"Моноширинный"` | Code tool. |
 | `spoiler` | `"Скрытый текст"` | Spoiler tool (`\|\|…\|\|`). |

package/dist/skill/reference/icon-set.ts

@@ -1,6 +1,7 @@
 /**
  * `prime-ui-kit/icons` — the full animated glyph set as named components (`<BellIcon />`), each a
- * Lucide drawing with one gesture; import only what you use, the rest is never bundled. The
+ * Lucide drawing (or a Simple Icons brand mark: `<TelegramIcon />`) with one gesture; import only
+ * what you use, the rest is never bundled. The
  * semantic `<Icon name>` set lives in the main entry. Generated by `bun run icons:add`.
  */
 export type { DomainIconProps as GlyphIconProps, Glyph } from "./icons/glyph";
@@ -20,6 +21,7 @@ export { AlignVerticalSpaceAround as AlignVerticalSpaceAroundIcon } from "./icon
 export { Ambulance as AmbulanceIcon } from "./icons/glyphs/ambulance";
 export { Angry as AngryIcon } from "./icons/glyphs/angry";
 export { Annoyed as AnnoyedIcon } from "./icons/glyphs/annoyed";
+export { AppWindow as AppWindowIcon } from "./icons/glyphs/app-window";
 export { Archive as ArchiveIcon } from "./icons/glyphs/archive";
 export { ArrowBigDown as ArrowBigDownIcon } from "./icons/glyphs/arrow-big-down";
 export { ArrowBigDownDash as ArrowBigDownDashIcon } from "./icons/glyphs/arrow-big-down-dash";
@@ -461,6 +463,7 @@ export { SwissFranc as SwissFrancIcon } from "./icons/glyphs/swiss-franc";
 export { SwitchCamera as SwitchCameraIcon } from "./icons/glyphs/switch-camera";
 export { Syringe as SyringeIcon } from "./icons/glyphs/syringe";
 export { Tablet as TabletIcon } from "./icons/glyphs/tablet";
+export { Telegram as TelegramIcon } from "./icons/glyphs/telegram";
 export { Telescope as TelescopeIcon } from "./icons/glyphs/telescope";
 export { Terminal as TerminalIcon } from "./icons/glyphs/terminal";
 export { TextAlignCenter as TextAlignCenterIcon } from "./icons/glyphs/text-align-center";
@@ -502,6 +505,7 @@ export { Users as UsersIcon } from "./icons/glyphs/users";
 export { UsersRound as UsersRoundIcon } from "./icons/glyphs/users-round";
 export { Vibrate as VibrateIcon } from "./icons/glyphs/vibrate";
 export { Video as VideoIcon } from "./icons/glyphs/video";
+export { Vk as VkIcon } from "./icons/glyphs/vk";
 export { Volume as VolumeIcon } from "./icons/glyphs/volume";
 export { Volume2 as Volume2Icon } from "./icons/glyphs/volume-2";
 export { VolumeX as VolumeXIcon } from "./icons/glyphs/volume-x";
@@ -513,6 +517,7 @@ export { WavesArrowUp as WavesArrowUpIcon } from "./icons/glyphs/waves-arrow-up"
 export { WavesLadder as WavesLadderIcon } from "./icons/glyphs/waves-ladder";
 export { Waypoints as WaypointsIcon } from "./icons/glyphs/waypoints";
 export { Webhook as WebhookIcon } from "./icons/glyphs/webhook";
+export { Whatsapp as WhatsappIcon } from "./icons/glyphs/whatsapp";
 export { Wifi as WifiIcon } from "./icons/glyphs/wifi";
 export { WifiCog as WifiCogIcon } from "./icons/glyphs/wifi-cog";
 export { WifiLow as WifiLowIcon } from "./icons/glyphs/wifi-low";

package/dist/skill/reference/layout/app-shell/COMPONENT.md

@@ -128,7 +128,7 @@ The navigation of the nearest `AppShell.Root` for a trigger outside the rail (a
 - Two full-height planes edge to edge: no inset, radius, shadow or border — the boundary is the fill change (the Sidebar rail is layer 1, the panel the page: white rail beside a gray page in light, a rail one step lighter than the near-black page in dark).
 - Main hands the page its edge air: `--page-gutter` is the page gutter `--prime-layout-gutter` — `--prime-layout-gutter-s` (16) → `-m` (24) from 640px → `-l` (32) from 1024px; `--page-top` is `--prime-space-6` (24) → `--prime-space-8` (32) from 1024px. `Page.Root` pads itself with them (its top bar steps out to the panel's edges). Main itself pads only the bottom: `--prime-space-16`, the scroll tail of a long page. Inside Main the page gutter is the small one again, so a frame nested in the page starts from its own gutter, not the shell's.
 - A page that fills the panel height (`Page.Root fill`): Main's bottom padding drops to the side gutter, so no long scroll tail stays under it — beside the Sidebar rail too.
-- Main scrolls with `overscroll-behavior: contain`, so its scroll never chains to the document.
+- Main hands its scroll on at its end (ScrollContainer `overscrollBehavior="auto"`): without `fillViewport` it is not a scroller and the document scrolls under the pointer.
 - Nav column: sticky at the top, viewport high, `z-index: --prime-z-sticky` (above the panel, so the compact Sidebar toggle can ride the rail edge); with `fillViewport` it fills the shell height instead.
 - Footer: no padding of its own (BottomNav keeps the bottom safe-area inset), sticky at the bottom, `z-index: --prime-z-sticky`.
 - A floating BottomNav (`floating`) in the footer: the footer takes no height, the capsule overlays the page, and Main keeps extra bottom room (the capsule height and the safe-area inset) so its last line never ends up under it.

package/dist/skill/reference/layout/page/COMPONENT.md

@@ -9,8 +9,8 @@
 - Every route rendered inside `AppShell.Main`: the app is navigation and the page, and the page carries its own top (`Page.TopBar`), title (`Page.Title`, the `<h1>`) and body.
 - A work screen (a list, a board, a chat, a schedule): `Page.TopBar` with the title (`Page.Heading`), the page's tools (`Page.Tools`: sections, search and filter, view), all its buttons (`Page.Actions`) and the active filters (`Page.Chips`).
 - A filter stands next to what it filters. `Page.Tools` holds what acts on the whole page: sections, the view, a period that drives several blocks (the KPI cards and the table), and a search and filter only when it narrows several views of one set (a board and its list). A table's search, filter, chips, «Колонки» and selection menu always belong to its own tools row (DataTable `toolbar` + `toolbarChips`), on a page that is only the table too.
-- A section with sub-pages (the «Мессенджеры» item of the Sidebar with «Каналы» and «Статистика»): each sub-page is a route of its own, `Page.Title` stays the section's name, and the switch is a `SegmentedControl` of links (`SegmentedControl.Item asChild`) in `Page.Tools`; the body is the current sub-page. The Sidebar keeps the section's item current on every sub-route — a router `NavLink` to the section's path without `end`, or `current={pathname.startsWith("/messengers")}`.
-- A document page (settings, a long form, help) or an overview (a dashboard): `Page.Header` in the flow — the large title and its buttons — and `Page.TopBar collapse`, which repeats the title once it scrolls away and keeps the path and the buttons in reach.
+- A section with sub-pages (the «Мессенджеры» item of the Sidebar with «Каналы», «Шаблоны» and «Статистика»): each sub-page is a route of its own, `Page.Title` stays the section's name, and the switch is a `SegmentedControl` of links (`SegmentedControl.Item asChild`) in `Page.Tools`, on a line of its own under the title at the start (see Top bar plan), so it stays put while each sub-page brings its own `Page.Actions` or none; the body is the current sub-page. The Sidebar keeps the section's item current on every sub-route — a router `NavLink` to the section's path without `end`, or `current={pathname.startsWith("/messengers")}`.
+- A document page (settings, a long form, help) read top to bottom with no page tools: `Page.Header` in the flow — the large title and its buttons — and `Page.TopBar collapse` with the path in its `Page.Heading`, which repeats the title once it scrolls away. A dashboard or an analytics page titles itself in `Page.TopBar` like a list.
 - A nested record: a `Breadcrumb` path in `Page.Heading`; in the bar the title reads as its last level.
 - A text page held to a reading measure (`maxWidth="readable"`), a wide dashboard capped at the content width (`maxWidth="wide"`).
 - The tiles of a dashboard — KPI cards, charts, panels — as one board (`Page.Grid` + `Page.Cell`).
@@ -94,7 +94,7 @@ Page.Root                          the page column (<div>); maxWidth, fill, labe
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (`Page.Heading`, `Page.Tools`, `Page.Actions`, `Page.Chips` — direct children), `className` and the other attributes. |
 
 ### Page.Header
-`ref` → `HTMLDivElement`. The document header in the page flow (settings, long forms, overviews): a `Page.Heading` and its `Page.Actions` in one row; the actions wrap under it on a narrow column.
+`ref` → `HTMLDivElement`. The document header in the page flow (settings, long forms): a `Page.Heading` and its `Page.Actions` in one row; the actions wrap under it on a narrow column.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -123,7 +123,7 @@ Page.Root                          the page column (<div>); maxWidth, fill, labe
 | `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `children`, `className` and the other paragraph attributes. |
 
 ### Page.Tools
-`ref` → `HTMLDivElement`. What acts on the whole page: sections (route links of sub-pages), view, a shared period; a filter only over several views — a table's go in its `toolbar`. The DataTable tool row: a search takes the free room, the rest keep their width. Named, a `group`.
+`ref` → `HTMLDivElement`. What acts on the whole page: sub-page links, view, a shared period, a filter over several views (a table's tools go in its `toolbar`). Sub-page links take a line of their own at the start. Named, a `group`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -226,8 +226,8 @@ No DOM, no ref. Holds the page from anywhere inside it: a press on a `Sidebar.It
 ### Place of Page.Heading
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| in `Page.TopBar` | one line as high as the Sidebar brand row: path › title-m, the caption description under the whole line; both truncate | work screens: lists, boards, chats, records | |
-| in `Page.Header` in the flow | the large document header: path over a heading-m title, body-m description, the header's `Page.Actions` beside it, wrapping under it | document pages and overviews | |
+| in `Page.TopBar` | one line as high as the Sidebar brand row: path › title-m, the caption description under the whole line; both truncate | screens of data: lists, boards, chats, records, dashboards and analytics | |
+| in `Page.Header` in the flow | the large document header: path over a heading-m title, body-m description, the header's `Page.Actions` beside it, wrapping under it | document pages with no page tools: settings, long forms, help | |
 
 The size follows the place; the consumer passes nothing, and there are no title size props. One `Page.Title` (`<h1>`) per page, in one of the two places. A bar with no visible title still holds the `<h1>`: a `Page.Title` wrapped in `VisuallyHidden`, or a flow `Page.Title` (with `collapse` the bar repeats it).
 
@@ -236,7 +236,7 @@ The size follows the place; the consumer passes nothing, and there are no title
 |---|---|---|---|
 | `fill` (Root) | the page is as high as main; the body takes what the bar and the header leave; main keeps gutter-high air under it | a full-height table, board, chat or `Page.Split` in an `AppShell.Root fillViewport` | `false` |
 | `sticky` (TopBar) | the bar stays at the top of main while the page scrolls under it | every page; `false` for a bar that should scroll away | `true` |
-| `collapse` (TopBar) | the flow title rises into the bar's title row once it scrolls away | a document page or an overview with the title in the flow | `false` |
+| `collapse` (TopBar) | the flow title rises into the bar's title row once it scrolls away | a document page with the path in the bar and the title in the flow | `false` |
 | `dirty` (Guard) | nothing until a person leaves: a press on the navigation or the path asks «leave without saving?» | a form that is the page has unsaved changes | `false` |
 | `busy` (Guard) | nothing until a person leaves: a press on the navigation or the path does nothing | the page's save request runs | `false` |
 
@@ -245,13 +245,13 @@ One plan, chosen from the natural widths of the groups (`data-plan` on the bar's
 
 | Step | Looks like | Use when | Default |
 |---|---|---|---|
-| `one` | `[Heading 1fr][Tools][Actions]` on one line | everything fits | yes |
-| `below` | the tools on a line of their own under the heading and the actions — the one tool row, as the DataTable `toolbar`: a search (`SmartFilter.Toolbar`, `Input.Root`) takes the free room, switchers, pickers and buttons keep their width at the end; under 36rem the search takes a line of its own and a `SegmentedControl.Root` / `Datepicker.Root` / Select fills the line it stands on | heading + tools + actions do not fit | |
+| `one` | `[Heading 1fr][Tools][Actions]` on one line | everything fits, and the tools hold no navigation | yes |
+| `below` | the tools on a line of their own under the heading and the actions — the one tool row, as the DataTable `toolbar`: a search (`SmartFilter.Toolbar`, `Input.Root`) takes the free room, switchers, pickers and buttons keep their width at the end; under 36rem the search takes a line of its own and a `SegmentedControl.Root` / `Datepicker.Root` / Select fills the line it stands on | heading + tools + actions do not fit; always for a section's sub-pages (the tools hold a navigation — a `SegmentedControl` of links), gathered at the start | |
 | `icons-secondary` | as `below`; secondary Buttons with a `Button.Icon` show only the icon, the label is their name and their tooltip | heading + actions still do not fit | |
 | `icons` | the primary Button gives way to its icon too | still too wide | |
 | `fold` | the secondary Buttons fold into «⋯» (`labels.more`); the primary stays | still too wide, and «⋯» is narrower than their icons (a single secondary keeps its icon); past it a Breadcrumb path folds into «…»; if the path and the title still do not share the line, the heading stacks: the path on its own line over the title, the title and the description wrapping (`data-heading="stack"`); a heading without a path truncates | |
 
-The actions stay on the first line beside the heading at every step; `Page.Chips` is always a line under everything; nothing overflows. The primary is the first solid `Button.Root`; a Button without an icon keeps its label at every step; anything that is not a `Button.Root` stays as it is.
+A section's sub-pages never share the first line: there they would stand where each sub-page's own heading and actions leave room, and those differ («Подключить канал» on one, none on another), so the switch would move under the pointer. On a line of their own at the start they stand at one place on every sub-page and at every width. The actions stay on the first line beside the heading at every step; `Page.Chips` is always a line under everything; nothing overflows. The primary is the first solid `Button.Root`; a Button without an icon keeps its label at every step; anything that is not a `Button.Root` stays as it is.
 
 ### Grid columns
 | Grid width | Cell `span` 1–3 | `span` 4 | `span` 5–6 | `span` 7–12 | `rows` |
@@ -342,9 +342,9 @@ A wide cell (`span` 7–11) written next to a narrow one (`span` 4–5) is a pai
 | [structure.tsx](examples/structure.tsx) | A document page in the flow: the path over the large title, its line of data and the page's buttons beside them, then the body with a section — `Page.Header`, `Page.Heading`, `Page.Description`, `Page.Section`. |
 | [top-bar.tsx](examples/top-bar.tsx) | A nested record in the top bar: the path ending in the title, a line of data, the page's tools and its buttons — `Page.TopBar`, `Page.Heading`, `Page.Tools`, `Page.Actions`. |
 | [loading.tsx](examples/loading.tsx) | A page whose figures load after it opens: the line of data keeps its place under the title while it loads, so nothing in the bar moves — `loading`. |
-| [collapse.tsx](examples/collapse.tsx) | An overview whose large title scrolls away under the top bar: the bar repeats it with its line of data and keeps the period and the page's buttons in reach — `collapse`. |
+| [collapse.tsx](examples/collapse.tsx) | A document page whose large title scrolls away under the top bar: the bar holds the path and repeats the title after it once the title is out of view — `collapse`, `Page.Header`. |
 | [tools.tsx](examples/tools.tsx) | The orders page's tools in its top bar: sections with counts, the search and filter that narrow both views, the view, in the order written; the active filters on a line under everything — `Page.Tools`, `Page.Chips`. |
-| [router.tsx](examples/router.tsx) | A section with sub-pages: the title is the section, each sub-page is a route of its own, the switch in the bar is their links and the body cross-fades between them; render it inside a router — `Page.Tools`, `asChild`. |
+| [router.tsx](examples/router.tsx) | A section with sub-pages: the title is the section, each sub-page is a route of its own with its own actions, the switch in the bar is their links on a line of their own and the body cross-fades between them; render it inside a router — `Page.Tools`, `asChild`. |
 | [actions-collapse.tsx](examples/actions-collapse.tsx) | The buttons of an invoices page on a tablet-wide column: the line runs short, so the secondary buttons show only their icons with the label as the name and the tooltip, the primary keeps its label — `Page.Actions`, `Button.Icon`. |
 | [sections.tsx](examples/sections.tsx) | A page with titled sections: tiles of one screen close together, a new topic set off by air, a link at the end of the heading — `Page.Section`, `label`, `description`, `Page.Actions`. |
 | [grid.tsx](examples/grid.tsx) | A dashboard board: four KPI tiles, a chart two rows high beside two panels, one gap on both axes — `Page.Grid`, `Page.Cell`, `span`, `rows`. |
@@ -365,6 +365,7 @@ A wide cell (`span` 7–11) written next to a narrow one (`span` 4–5) is a pai
 - `SmartFilter.Root` inside the bar, around `Page.Tools` → it holds no DOM; wrap it around `Page.Root` so its Toolbar (in `Page.Tools`) and its Chips (in `Page.Chips`) share it.
 - A table's search, filter, chips or «Колонки» in `Page.Tools` / `Page.Chips` → they read as filters of the whole page and move when the page grows a block; they go in the table's `toolbar` / `toolbarChips` on every page, the one that is only the table too. The bar keeps the title, sections, the view, a period that drives every block and the page's buttons.
 - Sub-pages of a section as a second Sidebar level, a tab strip inside `Page.Body`, or a title that names the sub-page → the title stays the section, the sub-pages are route links in `Page.Tools` (`SegmentedControl.Item asChild`), and the section's Sidebar item stays current on every sub-route.
+- A dashboard or analytics page with a bar of tools only (`collapse`) over a large title in the flow → the title and its line of data go in the bar's `Page.Heading` beside the tools, as on a list; the flow header is for document pages.
 - `Page.Header` inside `Page.TopBar` → the bar takes `Page.Heading` and `Page.Actions` directly; `Page.Header` is the flow's document header.
 - A hand-made menu button for the phone Sidebar → the bar draws it while the Sidebar is off-canvas.
 - Hiding buttons with media queries on a phone → `Page.Actions` in the bar collapses and folds them by measured width.

package/dist/skill/reference/layout/page/examples/collapse.tsx

@@ -1,60 +1,74 @@
-/** An overview whose large title scrolls away under the top bar: the bar repeats it with its line of data and keeps the period and the page's buttons in reach — `collapse`. */
-import { AppShell, Button, Card, Icon, Page, SegmentedControl, Typography } from "prime-ui-kit";
-import * as React from "react";
+/** A document page whose large title scrolls away under the top bar: the bar holds the path and repeats the title after it once the title is out of view — `collapse`, `Page.Header`. */
+import { AppShell, Breadcrumb, Button, Card, Icon, Page, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const WEEKS = [
+const SECTIONS = [
   {
-    id: "w41",
-    title: "6–12 октября",
-    text: "Выручка 1,2 млн ₽, 312 заказов, средний чек 3 850 ₽.",
+    id: "terms",
+    title: "Сроки",
+    text: "Клиент может вернуть заказ в течение 14 дней после получения. Срок считается от даты в акте приёмки.",
+  },
+  {
+    id: "condition",
+    title: "Состояние товара",
+    text: "Товар принимается в заводской упаковке, без следов использования, с ярлыками и полным комплектом.",
+  },
+  {
+    id: "refund",
+    title: "Возврат денег",
+    text: "Деньги возвращаются тем же способом, которым был оплачен заказ, в течение 10 рабочих дней после проверки.",
+  },
+  {
+    id: "delivery",
+    title: "Доставка при возврате",
+    text: "Если товар с браком, доставку оплачивает магазин. В остальных случаях — клиент по тарифу службы доставки.",
+  },
+  {
+    id: "exceptions",
+    title: "Исключения",
+    text: "Не возвращаются товары, изготовленные по индивидуальному заказу, и цифровые лицензии после активации.",
   },
-  { id: "w40", title: "29 сентября – 5 октября", text: "Выручка 1,1 млн ₽, 298 заказов." },
-  { id: "w39", title: "22–28 сентября", text: "Выручка 0,9 млн ₽, 264 заказа." },
-  { id: "w38", title: "15–21 сентября", text: "Выручка 1,0 млн ₽, 281 заказ." },
-  { id: "w37", title: "8–14 сентября", text: "Выручка 0,8 млн ₽, 240 заказов." },
 ];
 
 export default function PageCollapseExample() {
-  const [period, setPeriod] = React.useState("week");
-
   return (
     <div className={`${styles.window} ${styles.tall}`}>
       <AppShell.Root fillViewport className={styles.shell}>
         <AppShell.Main>
-          <Page.Root>
+          <Page.Root maxWidth="readable">
             <Page.TopBar collapse>
-              <Page.Tools aria-label="Продажи">
-                <SegmentedControl.Root value={period} onValueChange={setPeriod} aria-label="Период">
-                  <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
-                  <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
-                </SegmentedControl.Root>
-              </Page.Tools>
+              <Page.Heading>
+                <Breadcrumb.Root>
+                  <Breadcrumb.Item href="#documents">Документы</Breadcrumb.Item>
+                </Breadcrumb.Root>
+              </Page.Heading>
+            </Page.TopBar>
+            <Page.Header>
+              <Page.Heading>
+                <Page.Title>Политика возвратов</Page.Title>
+                <Page.Description>
+                  Действует с 1 сентября для всех заказов магазина.
+                </Page.Description>
+              </Page.Heading>
               <Page.Actions>
                 <Button.Root variant="soft" tone="neutral">
                   <Button.Icon>
                     <Icon name="action.download" />
                   </Button.Icon>
-                  Отчёт
+                  Скачать PDF
                 </Button.Root>
               </Page.Actions>
-            </Page.TopBar>
-            <Page.Header>
-              <Page.Heading>
-                <Page.Title>Продажи</Page.Title>
-                <Page.Description>Интернет-магазин · на 14 октября, 9:40</Page.Description>
-              </Page.Heading>
             </Page.Header>
             <Page.Body>
-              {WEEKS.map((week) => (
-                <Card.Root key={week.id} variant="panel">
+              {SECTIONS.map((section) => (
+                <Card.Root key={section.id} variant="panel">
                   <Card.Header>
-                    <Card.Title as="h2">{week.title}</Card.Title>
+                    <Card.Title as="h2">{section.title}</Card.Title>
                   </Card.Header>
                   <Card.Body>
                     <Typography variant="body-m" tone="secondary">
-                      {week.text}
+                      {section.text}
                     </Typography>
                   </Card.Body>
                 </Card.Root>

package/dist/skill/reference/layout/page/examples/router.tsx

@@ -1,4 +1,4 @@
-/** A section with sub-pages: the title is the section, each sub-page is a route of its own, the switch in the bar is their links and the body cross-fades between them; render it inside a router — `Page.Tools`, `asChild`. */
+/** A section with sub-pages: the title is the section, each sub-page is a route of its own with its own actions, the switch in the bar is their links on a line of their own and the body cross-fades between them; render it inside a router — `Page.Tools`, `asChild`. */
 import {
   Button,
   Card,
@@ -12,10 +12,13 @@ import {
 import { Link, Route, Routes, useLocation } from "react-router-dom";
 
 type Channel = { id: string; name: string; dialogs: number; reply: string };
+type Template = { id: string; name: string; uses: number };
 
+// The action of each sub-page: its own label, none on the statistics.
 const SUB_PAGES = [
-  { to: "/messengers/channels", label: "Каналы" },
-  { to: "/messengers/stats", label: "Статистика" },
+  { to: "/messengers/channels", label: "Каналы", action: "Подключить канал" },
+  { to: "/messengers/templates", label: "Шаблоны", action: "Новый шаблон" },
+  { to: "/messengers/stats", label: "Статистика", action: null },
 ];
 
 const CHANNELS: Channel[] = [
@@ -25,6 +28,23 @@ const CHANNELS: Channel[] = [
   { id: "avito", name: "Авито · Склад на Южной", dialogs: 59, reply: "25 мин" },
 ];
 
+const TEMPLATES: Template[] = [
+  { id: "greeting", name: "Приветствие в рабочее время", uses: 812 },
+  { id: "night", name: "Ответ ночью", uses: 264 },
+  { id: "delivery", name: "Сроки доставки", uses: 151 },
+];
+
+const TEMPLATE_COLUMNS: DataTableColumn<Template>[] = [
+  { id: "name", header: "Шаблон", cell: (row) => row.name },
+  {
+    id: "uses",
+    header: "Отправок",
+    numeric: true,
+    headerAlign: "end",
+    cell: (row) => row.uses,
+  },
+];
+
 const COLUMNS: DataTableColumn<Channel>[] = [
   { id: "name", header: "Канал", cell: (row) => row.name },
   {
@@ -46,7 +66,7 @@ const COLUMNS: DataTableColumn<Channel>[] = [
 export default function PageRouterExample() {
   const location = useLocation();
   // The first sub-page answers every other path of the section (here the preview's «/»).
-  const current = SUB_PAGES.find((page) => page.to === location.pathname)?.to ?? SUB_PAGES[0].to;
+  const current = SUB_PAGES.find((page) => page.to === location.pathname) ?? SUB_PAGES[0];
 
   return (
     <Page.Root>
@@ -56,7 +76,7 @@ export default function PageRouterExample() {
           <Page.Description>4 канала · 1 280 диалогов за октябрь</Page.Description>
         </Page.Heading>
         <Page.Tools aria-label="Мессенджеры">
-          <SegmentedControl.Root value={current} aria-label="Подразделы">
+          <SegmentedControl.Root value={current.to} aria-label="Подразделы">
             {SUB_PAGES.map((page) => (
               <SegmentedControl.Item key={page.to} value={page.to} asChild>
                 <Link to={page.to}>{page.label}</Link>
@@ -64,18 +84,20 @@ export default function PageRouterExample() {
             ))}
           </SegmentedControl.Root>
         </Page.Tools>
-        <Page.Actions>
-          <Button.Root>
-            <Button.Icon>
-              <Icon name="action.add" />
-            </Button.Icon>
-            Подключить канал
-          </Button.Root>
-        </Page.Actions>
+        {current.action ? (
+          <Page.Actions>
+            <Button.Root>
+              <Button.Icon>
+                <Icon name="action.add" />
+              </Button.Icon>
+              {current.action}
+            </Button.Root>
+          </Page.Actions>
+        ) : null}
       </Page.TopBar>
       <Page.Body>
         {/* `location` keeps the leaving sub-page on its own route while it fades out. */}
-        <Crossfade state={current}>
+        <Crossfade state={current.to}>
           <Routes location={location}>
             <Route
               path="/messengers/stats"
@@ -105,6 +127,17 @@ export default function PageRouterExample() {
                 </Page.Grid>
               }
             />
+            <Route
+              path="/messengers/templates"
+              element={
+                <DataTable
+                  columns={TEMPLATE_COLUMNS}
+                  rows={TEMPLATES}
+                  getRowKey={(row) => row.id}
+                  paging="none"
+                />
+              }
+            />
             <Route
               path="*"
               element={

package/dist/skill/ux.md

@@ -34,6 +34,7 @@ adds text that explains what the layout failed to show.
 | A base value and its overrides (a price and its changes by month) | one list: the base is the first, pinned row | `FieldList` `getLocked` |
 | Small attributes of a record (an icon, a color, a flag) | compact controls in the record's row, not fields of their own | icon-only `Select`, `ColorPresets`, `Switch` |
 | Short texts in an order the person sets | one column, a handle per row | `FieldList` `reorderable` |
+| Records of one kind, some fixed by the system (funnel stages, default roles) | one list in their real order, the fixed rows pinned in place | `List` `locked`, `FieldList` `getLocked` |
 | Settings that most people never touch | behind a disclosure, after the common ones | `Accordion`, a «Дополнительно» section |
 | One of a few options, sent with a form | all visible | `Radio.Group` |
 | One of a few modes of what the screen shows | all visible | `SegmentedControl` |
@@ -81,6 +82,36 @@ records they cannot see. A set that can be empty shows its empty state, never a
 </Drawer.Section>
 ```
 
+**One kind, one list.** Records of one kind stay one list in the order they really have, whoever made
+them: the stages of a funnel, the team's and the system's alike, read top to bottom as the board shows
+them. What some rows cannot do (move, be removed) is a mark on those rows — the lock in the grip's
+place — never a second section. Two lists split one order in two, and their columns no longer line up.
+The test: does the board, the report or the process read these records as one sequence? Then they are
+one list.
+
+```tsx partial
+// bad — the system stages in a section of their own under the team's; one order, two lists
+<Drawer.Section label="Свои этапы">
+  <List.Root aria-label="Свои этапы" onReorder={reorder}>…</List.Root>
+</Drawer.Section>
+<Drawer.Section label="Системные этапы">
+  <List.Root aria-label="Системные этапы">…</List.Root>
+</Drawer.Section>
+```
+
+```tsx good
+// good — one list in board order; the system stages hold their places with a lock
+// declare: const stages: { id: string; name: string; system: boolean }[]
+// declare: const reorder: (id: string, beforeId: string | null) => void
+<List.Root aria-label="Этапы воронки" onReorder={reorder}>
+  {stages.map((stage) => (
+    <List.Item key={stage.id} value={stage.id} locked={stage.system}>
+      <List.ItemText>{stage.name}</List.ItemText>
+    </List.Item>
+  ))}
+</List.Root>
+```
+
 ## 3. Label economy
 
 Every word on screen must carry something the person does not see already.
@@ -91,6 +122,46 @@ Every word on screen must carry something the person does not see already.
   list already counts. The list label names the rows.
 - **No label that repeats its heading.** A field «Цена» inside the section «Цена» needs no label of
   its own beyond what the section says; a group of one field is the field.
+- **A heading only where it names what nothing else names.** A block that names itself — a chart or a
+  card with its own title, a table with its toolbar — gets no section heading over it, and the first
+  block of a tab never repeats the tab («Характеристики» under the tab «Характеристики»). A section
+  heading stands where several blocks share a topic that none of them names. The test: delete the
+  heading and read the screen; if nothing is lost, it goes. Blocks without a heading stand one under
+  another with the section step between them (a `Tabs.Panel` in a dialog body spaces them by itself;
+  no wrapper of your own).
+
+```tsx partial
+// bad — a section over a chart that has its own title, under a tab of the same name
+<Tabs.Panel value="analytics">
+  <Drawer.Section label="Аналитика" description="За 30 дней">
+    <ChartFrame.Root>
+      <ChartFrame.Header>
+        <ChartFrame.Title>Продажи</ChartFrame.Title>
+      </ChartFrame.Header>
+      …
+    </ChartFrame.Root>
+  </Drawer.Section>
+</Tabs.Panel>
+```
+
+```tsx good
+// good — the charts name themselves; the tab names the topic, the period is the tab's switcher
+// declare: const sales: Parameters<typeof ChartFrame.Root>[0]["rows"]
+// declare: const refunds: Parameters<typeof ChartFrame.Root>[0]["rows"]
+<Tabs.Panel value="analytics">
+  <ChartFrame.Root rows={sales}>
+    <ChartFrame.Header>
+      <ChartFrame.Title>Продажи</ChartFrame.Title>
+    </ChartFrame.Header>
+  </ChartFrame.Root>
+  <ChartFrame.Root rows={refunds}>
+    <ChartFrame.Header>
+      <ChartFrame.Title>Возвраты</ChartFrame.Title>
+    </ChartFrame.Header>
+  </ChartFrame.Root>
+</Tabs.Panel>
+```
+
 - **A unit lives in one place.** In the field (`Input.InlineAffix`) or in the heading, never both;
   never in the field's own label («Бюджет», not «Бюджет, ₽»). Prefer the field: the unit stays
   beside the number when the row stacks, and a screen reader hears it with the field (the affix
@@ -111,6 +182,11 @@ Every word on screen must carry something the person does not see already.
 | «Звук» (Switch) — «Применяется сразу, без сохранения» | no hint |
 | «Отключить доступ» — «Сотрудник не сможет войти, история его действий останется» | «Входы прекратятся» |
 | «Почта для входа» — «На эту почту придёт ссылка для входа в систему» | «Для входа и уведомлений» |
+- **Helper text is opt-in.** A hint, a limit, a counter, a range line («Показано 1–20 из 240») or a
+  description shows only where it tells this person something they need for this task; the kit
+  draws none of its own unless asked — DataTable shows its range with `showRange`, and FieldList and
+  FileUpload at `max` close up their add control without a word, so a limit worth knowing goes in
+  `hint` («До 10 фото»). Turn one on for a reason you can name, never because the prop exists.
 - **One name per thing.** The same action, entity and status keep one word on the whole screen
   (and across screens): «Счёт», not «Счёт» in the title and «Инвойс» in the button.
 - **Count the labels.** On a form of repeating rows, labels on screen ≤ number of columns + the
@@ -158,8 +234,9 @@ Which button starts each step and how the confirm behaves:
 ## 6. Nothing to guess
 
 - **A disabled control says why** when the reason is not on screen: a `hint` under the field, a
-  line beside the button («Не больше 3», as `FieldList` does at `max`), or the disabled control
-  itself in `Tooltip.Trigger`. An action a person may never take (no permission) is hidden, not
+  line beside the button, or the disabled control itself in `Tooltip.Trigger`. A control that
+  leaves at a limit (the add button of `FieldList` or `FileUpload` at `max`) says it ahead, in the
+  list's `hint`. An action a person may never take (no permission) is hidden, not
   disabled.
 - **The screen answers the latest question.** A request a value starts (a search, a filter, a page,
   a period) is cancelled when the value changes again — abort it (`AbortController`) or drop its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.21.1",
+  "version": "0.21.3",
   "packageManager": "bun@1.3.13",
   "description": "React 19 UI kit for product interfaces: 79 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y, Next.js App Router ready. Ships COMPONENT.md docs, copyable examples and an agent skill.",
   "bin": {

package/src/components/card/COMPONENT.md

@@ -220,7 +220,7 @@ No `labels`.
 | [flat.tsx](examples/flat.tsx) | A flat tile without the raised shadow next to the default one, for dense grids — `flat`. |
 | [states.tsx](examples/states.tsx) | A KPI tile while its report loads next to the loaded one, in the `stat-trend` and `mini` templates — `loading`. |
 | [narrow.tsx](examples/narrow.tsx) | The card is a size container: the split template stacks its cells below 22rem and the trend value shrinks below 20rem — `variant`. |
-| [screen.tsx](examples/screen.tsx) | A dashboard: the title and a line of data in the page flow, the period switch and the report in the top bar that keeps the title once it scrolls away; one grid of KPI tiles that cross-fade to the new period, a revenue trend, invoiced against paid beside two panels, and the latest payments with a link to the list — `collapse`, `Page.Grid`. |
+| [screen.tsx](examples/screen.tsx) | A dashboard: the title with a line of data, the period switch and the report in the page's top bar; one grid of KPI tiles that cross-fade to the new period, a revenue trend, invoiced against paid beside two panels, and the latest payments with a link to the list — `Page.TopBar`, `Page.Grid`. |
 
 ## Mistakes
 - A `<div>` with a border styled as a card → use `Card.Root`; depth comes from fill, not lines.