prime-ui-kit 0.21.2 → 0.21.3

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";
@@ -462,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";
@@ -503,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";
@@ -514,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/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.2",
+  "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.

package/src/components/card/examples/screen.tsx

@@ -1,4 +1,4 @@
-/** 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`. */
+/** 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`. */
 import {
   Badge,
   Button,
@@ -157,10 +157,14 @@ export default function CardScreenExample() {
 
   return (
     <Page.Root>
-      {/* An overview: the large title in the flow; the bar keeps the period and the report in
-          reach and repeats the title once it scrolls away. */}
-      <Page.TopBar collapse>
-        <Page.Tools>
+      {/* An overview titles itself in its bar like any work screen: the title with its line of
+          data, the period that drives the tiles, the report. */}
+      <Page.TopBar>
+        <Page.Heading>
+          <Page.Title>Обзор</Page.Title>
+          <Page.Description>Продажи и оплаты · на 8 октября, 9:40</Page.Description>
+        </Page.Heading>
+        <Page.Tools aria-label="Обзор">
           <SegmentedControl.Root
             aria-label="Период"
             value={period}
@@ -180,12 +184,6 @@ export default function CardScreenExample() {
           </Button.Root>
         </Page.Actions>
       </Page.TopBar>
-      <Page.Header>
-        <Page.Heading>
-          <Page.Title>Обзор</Page.Title>
-          <Page.Description>Продажи и оплаты · на 8 октября, 9:40</Page.Description>
-        </Page.Heading>
-      </Page.Header>
       <Page.Body>
         {/* One board: every tile of the screen in one grid, 16 apart on both axes. */}
         <Page.Grid>

package/src/components/chat-list/COMPONENT.md

@@ -29,7 +29,7 @@ ChatList.Root                 <div> column filling its host (container `chat-lis
 │  └─ Crossfade               loading (placeholder List rows) ⇄ empty (EmptyPage compact) ⇄ the list
 │     └─ List.Root <ul>       aria-label «Диалоги»; spacer <li aria-hidden> stand for rows out of view
 │        └─ ChatList.Item     List.Item <li> + <button> | <a href> | your element (asChild); current from value; one Tab stop
-│           ├─ ChatList.ItemIcon         before the name: avatar slot (aria-hidden); after it: a glyph
+│           ├─ ChatList.ItemIcon         before the name: avatar slot (aria-hidden); after it: a glyph (role="img" with aria-label)
 │           ├─ ChatList.ItemText         the name; muted glyph after it
 │           ├─ ChatList.ItemDescription  author · media word · text — cross-fades with draft and «печатает…»
 │           ├─ (meta)                    delivery ticks · time
@@ -89,12 +89,12 @@ ChatList.Root                 <div> column filling its host (container `chat-lis
 | `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `className` and the native attributes of the row element. |
 
 ### ChatList.ItemIcon
-`ref` → `HTMLSpanElement`. Before the name: the avatar slot (`aria-hidden`), an `Avatar.Root` sized by the row. After the name: a glyph beside it (verified, bot, group).
+`ref` → `HTMLSpanElement`. Before the name: the avatar slot (`aria-hidden`), an `Avatar.Root` sized by the row. After the name: a glyph beside it (verified, bot, channel type), any kit icon sized by the row; with `aria-label` it is `role="img"` of that name.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | An `Avatar.Root` (with `Avatar.Status`), or after the name an `Icon` with a `label`. |
-| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other `span` attributes. |
+| `children` | `ReactNode` | — (required) | An `Avatar.Root` (with `Avatar.Status`), or after the name an icon: `<Icon name>` or a glyph of `prime-ui-kit/icons` (`<SendIcon />`), as is. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className`, `aria-label` (names a glyph after the name: its channel, «Официальный аккаунт») and the other `span` attributes. |
 
 ### ChatList.ItemText
 `ref` → `HTMLSpanElement`. The name of the dialog: one line, truncated, the glyphs after it kept whole; the search query is marked.
@@ -200,7 +200,7 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 
 - The list is a `<ul>` named «Диалоги» (`labels.list`); each row an `<li>` with a button, a link with `href`, or your link with `asChild`.
 - The open dialog is `aria-current="true"` on a button, `"page"` on a link. Selection does not follow the focus: arrows only move it (a dialog may load a conversation); Enter, Space and a click open.
-- The row is named by its content: the name, glyphs with a `label` («Без звука», a verified mark), the preview, the delivery mark («Прочитано»), the time, then «упоминание» and «непрочитанных: 3» instead of the bare badges; the avatar is `aria-hidden`.
+- The row is named by its content: the name, the glyphs (`ChatList.ItemIcon` `aria-label`, «Без звука»), the preview, the delivery mark («Прочитано»), the time, then «упоминание» and «непрочитанных: 3» instead of the bare badges; the avatar is `aria-hidden`.
 - While the other side types, the preview is `aria-hidden` and «печатает…» is read; a draft reads «Черновик: …».
 - A row with a menu has `aria-keyshortcuts="Shift+F10"`; the menu is a `Dropdown` (`menu` / `menuitem`).
 - The search field is `type="search"` named «Поиск по диалогам»; after a search a polite status says «Найдено: 4» or «Ничего не найдено».
@@ -257,6 +257,7 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 - Filtering inside `renderItem` (returning `null`) → filter `items`: the list counts, announces and glides by `items`.
 - Pinned dialogs mixed into the time order → put them first in `items`; `pinned` only draws the pin.
 - `onValueChange` used to mark a dialog read on focus → arrows only move the focus; mark read when the conversation shows it (`Chat.Messages onRead`) or on open.
+- A glyph after the name cloned with `label` and `size` → put the icon in `ChatList.ItemIcon` as is and name the part with `aria-label`: the row sizes it.
 - An `Avatar.Root size="s"` to fit the row → leave `size` out; the slot sizes the avatar to the tier.
 - A «⋯» button nested inside the row for the menu → `ChatList.ItemMenu`: it opens on right click, a long press and Shift+F10.
 - Deleting from the menu without a question → open a `ConfirmDialog` from the menu item.

package/src/components/chat-list/examples/structure.tsx

@@ -111,13 +111,13 @@ export default function ChatListStructureExample() {
             </ChatList.ItemIcon>
             <ChatList.ItemText>{item.name}</ChatList.ItemText>
             {item.verified ? (
-              <ChatList.ItemIcon>
-                <Icon name="status.success" tone="accent" label="Официальный аккаунт" />
+              <ChatList.ItemIcon aria-label="Официальный аккаунт">
+                <Icon name="status.success" tone="accent" />
               </ChatList.ItemIcon>
             ) : null}
             {item.group ? (
-              <ChatList.ItemIcon>
-                <Icon name="object.users" label="Группа" />
+              <ChatList.ItemIcon aria-label="Группа">
+                <Icon name="object.users" />
               </ChatList.ItemIcon>
             ) : null}
             <ChatList.ItemDescription

package/src/components/command-menu/COMPONENT.md

@@ -136,7 +136,7 @@ CommandMenu.Root                 Modal + top-aligned palette panel, query and lo
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the title), `className` and the other span attributes. |
 
 ### CommandMenu.Empty
-`ref` → `HTMLDivElement`. A compact EmptyPage (`role="status"`) shown while nothing matches and nothing loads: `labels.empty` and `labels.emptyHint`, text only. An action for the query is a `persistent` `CommandMenu.Item` at the end of the list.
+`ref` → `HTMLDivElement`. A compact EmptyPage (`role="status"`) shown while nothing matches and nothing loads: `labels.empty`, text only. An action for the query is a `persistent` `CommandMenu.Item` at the end of the list.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -236,7 +236,6 @@ One look: the floating layer of the ladder (it is a Modal), `--prime-modal-radiu
 |---|---|---|
 | `search` | `"Поиск"` | Default placeholder and accessible name of `CommandMenu.Input`. |
 | `empty` | `"Ничего не найдено"` | `CommandMenu.Empty`: nothing matches the query. |
-| `emptyHint` | `"Попробуйте изменить запрос"` | Second line of `CommandMenu.Empty`; `""` hides it. |
 | `loading` | `"Загрузка…"` | Announced while `loading` or `loadingMore`. |
 | `retry` | `"Повторить"` | The retry button under `loadError` (`onRetry`). |
 

package/src/components/command-menu/examples/states.tsx

@@ -46,7 +46,7 @@ export default function CommandMenuStatesExample() {
         onSearchChange={setSearch}
         loading={state === "loading"}
         aria-label="Выбор склада"
-        labels={{ empty: "Склад не найден", emptyHint: "В этом городе склада пока нет" }}
+        labels={{ empty: "В этом городе склада пока нет" }}
       >
         <CommandMenu.Input placeholder="Город склада" />
         <CommandMenu.List>