prime-ui-kit 0.16.0 → 0.18.0

package/dist/skill/foundations.md

@@ -35,12 +35,12 @@ Things that belong together sit closer than things that do not.
 | inline controls in a row (buttons, filters) | 8 | `--prime-space-2` |
 | switch → switch in a settings list | 20 | `--prime-space-5` |
 | group → group (fieldset, form section) | 32 | `--prime-space-8` |
-| tile → tile, both axes (KPI cards, charts, panels) | 16 | `--prime-space-4` — `PageContent.Grid` already does it |
-| block → block on a page (page header → body too) | 24 | `--prime-space-6` — `PageContent` already does it |
-| section → section on a page (a new topic with an `h2`) | 40 | `PageContent.Section` already does it |
+| tile → tile, both axes (KPI cards, charts, panels) | 16 | `--prime-space-4` — `Page.Grid` already does it |
+| block → block on a page (page header → body too) | 24 | `--prime-space-6` — `Page` already does it |
+| section → section on a page (a new topic with an `h2`) | 40 | `Page.Section` already does it |
 
-`PageContent.Body` already spaces its direct blocks 24 apart, a `PageContent.Section` 40 from its
-neighbours, `PageContent.Grid` its tiles 16 on both axes, and `AppShell.Main` already carries the page
+`Page.Body` already spaces its direct blocks 24 apart, a `Page.Section` 40 from its
+neighbours, `Page.Grid` its tiles 16 on both axes, and `AppShell.Main` already hands the page its
 gutters — do not add your own outer padding.
 
 ## 3. Size axis
@@ -143,10 +143,10 @@ A chart color does one job, and the job picks the colors:
 | `body-m` | 14/20 | default text |
 | `body-l` | 16/24 | reading text |
 | `title-s` | 14/20 600 | card title, group heading inside a card or form |
-| `title-m` | 16/24 600 | page section heading (`PageContent.Section` draws it), modal title |
+| `title-m` | 16/24 600 | page section heading (`Page.Section` draws it), modal title |
 | `title-l` | 18/24 600 | large block title |
 | `heading-s` | 20/28 600 | page sub-heading |
-| `heading-m` | 24/32 600 | the title of a document page (`PageContent.Title`); an app page titles itself in `AppHeader.Title` (`title-s`) |
+| `heading-m` | 24/32 600 | the page title in the flow (`Page.Title` of a document page or an overview); in `Page.TopBar` the same `Page.Title` is `title-m` |
 | `heading-l` | 30/36 600 | marketing / auth title |
 | `display-*` | 36–60 | hero numbers only |
 | `code` | 13/20 mono | identifiers, inline code |
@@ -154,7 +154,7 @@ A chart color does one job, and the job picks the colors:
 `variant` is required on `Typography`. Weights only 400/500/600. Numbers in tables, prices, dates:
 tabular (the kit does it in DataTable `numeric` columns and `Card.Value`; your own amounts take
 `font-variant-numeric: tabular-nums`). Reading text max width `--prime-layout-reading-max-width`
-(`PageContent.Root maxWidth="readable"`).
+(`Page.Root maxWidth="readable"`).
 
 ### Text colour
 
@@ -174,7 +174,7 @@ level of air: a page with uniform 16px gaps everywhere reads as a list of unrela
   the [breakpoints and their scope](responsive.md#breakpoints), the
   [intrinsic grids](responsive.md#intrinsic-grids), what the kit adapts by itself and touch.
 - Flex children with text: `min-width: 0` + ellipsis or `overflow-wrap: anywhere`.
-- Sticky parts come from the kit: `AppHeader` (with the `PageToolbar` in `AppHeader.Tools`), the
+- Sticky parts come from the kit: `Page.TopBar` (with all its groups), the
   DataTable head and `stickyFirstColumn`, the Gantt header and first column — each sticks inside its
   own scroller, and the top ones let go on screens lower than 480px. Never a `position: sticky` bar of your own.
 

package/dist/skill/layouts.md

@@ -1,14 +1,16 @@
 # Layouts — app frame, page wrappers, auth
 
-Every screen sits in one frame: `AppShell.Root` with the Sidebar in `AppShell.Nav`, a header row and
+The app is navigation and the page: `AppShell.Root` with the Sidebar in `AppShell.Nav` and
 `AppShell.Main` (the content panel is the page, the nav rail one layer above it). The frame is the
-app's; the header row and the body are the page's — a screen renders its own `AppHeader.Root` (the
-page title and the page's tools, [composition.md](composition.md#1-page-skeleton)) and its body in
-`PageContent`.
-`AppShell.Main` carries the page gutters and `PageContent` spaces the page — blocks 24, a titled
-`PageContent.Section` 40, tiles in a `PageContent.Grid` 16 on both axes — so your code adds **no outer padding and no margins**. Your CSS only lays out the inside of a block (grids, rows) with `gap` on `--prime-space-*`.
-Main's top air under the header is part of the frame — 24, then 32 from 1024px: the page's first block
-starts there; never cancel it with a negative margin or a padding override.
+app's; everything inside Main is the page's — a screen renders one `Page.Root` with its own top
+(`Page.TopBar`: the page title and the page's tools, [composition.md](composition.md#1-page-skeleton))
+and its body in `Page.Body`.
+`AppShell.Main` hands the page its gutters and its edge air and `Page` spaces it — blocks 24, a titled
+`Page.Section` 40, tiles in a `Page.Grid` 16 on both axes — so your code adds **no outer padding and no margins**. Your CSS only lays out the inside of a block (grids, rows) with `gap` on `--prime-space-*`.
+The edge air is part of the frame. On top: 24, then 32 from 1024px, where a page without a bar
+starts; under a `Page.TopBar` the body starts 24 below the bar's controls. At the bottom: a long
+page keeps a 64 scroll tail, a `Page.Root fill` page only the side gutter, beside the Sidebar rail
+as well. Never cancel it with a negative margin or a padding override.
 
 The page recipes are whole, working screens — the `screen.tsx` example of their main component
 ([the list](composition.md#screens)): start from the closest one and keep its skeleton. The rules behind them are in [composition.md](composition.md).
@@ -16,14 +18,13 @@ The page recipes are whole, working screens — the `screen.tsx` example of thei
 ## App frame (once per app)
 
 The frame is the root layout and nothing else: the providers, `AppShell.Root`, the Sidebar in
-`AppShell.Nav` and `AppShell.Main` around the page. It holds no header content and no menu state:
+`AppShell.Nav` and `AppShell.Main` around the page. It holds no header and no menu state:
 
-- **The header row belongs to the page.** An `AppHeader.Root` anywhere inside the shell — the page's
-  own one, rendered at the top of its body — shows in the shell's header row; the latest one on
-  screen wins, so every page brings its own. Its row is as high as the Sidebar brand row, so the brand
-  and the title read as one line. Nothing app-wide goes into it — no global search, no notifications.
+- **Everything at the top belongs to the page.** There is no app-wide header and no global search:
+  every page renders its own `Page.TopBar` with only what it needs. Its title row is as high as the
+  Sidebar brand row, so the brand and the title read as one line.
 - **The phone menu comes with the frame.** Below 768px the Sidebar becomes an off-canvas panel
-  (`offCanvas="auto"`) and the AppHeader leads with the menu button that opens it by itself — never a
+  (`offCanvas="auto"`) and `Page.TopBar` leads with the menu button that opens it by itself — never a
   menu state or a menu button wired by hand. A trigger outside the rail (a BottomNav «Ещё», your own
   button) reads the shell's navigation with `useAppShellNav()` (`open`, `setOpen`, `navId`; see
   [the app frame screen](reference/layout/app-shell/examples/screen.tsx)).
@@ -90,37 +91,33 @@ export function AppFrame({ children }: { children: ReactNode }) {
 }
 ```
 
-Every page renders its header and its body; the header shows in the frame's header row:
+Every page renders its top and its body in one `Page.Root`:
 
 ```tsx
-import { AppHeader, PageContent } from "prime-ui-kit";
+import { Page } from "prime-ui-kit";
 
 export function OrdersPage() {
   return (
-    <>
-      <AppHeader.Root>
-        <AppHeader.Start>
-          <AppHeader.Title>
-            Заказы
-            <AppHeader.Description>128 в работе · 6 ждут оплаты</AppHeader.Description>
-          </AppHeader.Title>
-        </AppHeader.Start>
-      </AppHeader.Root>
-      <PageContent.Root as="section">
-        <PageContent.Body>{/* the page's blocks */}</PageContent.Body>
-      </PageContent.Root>
-    </>
+    <Page.Root>
+      <Page.TopBar>
+        <Page.Heading>
+          <Page.Title>Заказы</Page.Title>
+          <Page.Description>128 в работе · 6 ждут оплаты</Page.Description>
+        </Page.Heading>
+      </Page.TopBar>
+      <Page.Body>{/* the page's blocks */}</Page.Body>
+    </Page.Root>
   );
 }
 ```
 
-A document page (settings, a long form, help) renders an `AppHeader.Root` without a title — only
-its own buttons, and on a phone the menu button the header draws — and opens its body with
-`PageContent.Header`.
+What stands in the bar — the path ending in the title, the tools, every button, the active filters —
+is [the top bar](composition.md#the-top-bar); where the title stands on a document page or an
+overview is [the page skeleton](composition.md#1-page-skeleton).
 
 With React Router the frame's `children` is `<Outlet />` and every item is `Sidebar.Item asChild`
 around a `NavLink` ([the router example](reference/layout/sidebar/examples/router.tsx)). The same frame
-as one component is `AppShell.Template` (`nav`, `footer`, the page as children); give it the
+as one component is `AppShell.Template` (`nav`, `footer`, `mainProps`, the page as children); give it the
 pathname as `scrollResetKey`, so a new page opens at the top.
 
 Phone navigation for 2–6 main sections is a `BottomNav.Root` in `AppShell.Footer` (the last child of
@@ -133,60 +130,6 @@ Next.js App Router: the package is marked `"use client"`, but a server component
 `"use client"` and render them from `app/layout.tsx` and the pages; import `bundle.css` in the root
 layout and put `data-theme` on `<html>` there.
 
-A nested record page puts the path up before its title in the header — `Breadcrumb` (the list it
-belongs to), `AppHeader.Separator`, `AppHeader.Title` with the record's name and its status as
-the description ([the detail page](reference/components/description-list/examples/screen.tsx)).
-
-### The page's tools in the header
-
-The page's tools — its own search and filters, sections, the period or view, the primary action —
-go into `AppHeader.Tools` as a `PageToolbar.Root`: the header's second row, full width, sticky with
-it. The toolbar lays itself out from that width ([the page panel](responsive.md#page-panel--pagetoolbar)),
-so the tools wrap under the title instead of squeezing it. `AppHeader.Actions` keeps the page's
-other buttons (export, a more menu) in the title row.
-
-```tsx
-import { AppHeader, Button, Icon, PageToolbar, SegmentedControl } from "prime-ui-kit";
-
-type DealsHeaderProps = { view: string; onViewChange: (view: string) => void };
-
-export function DealsHeader({ view, onViewChange }: DealsHeaderProps) {
-  return (
-    <AppHeader.Root>
-      <AppHeader.Start>
-        <AppHeader.Title>
-          Сделки
-          <AppHeader.Description>7 сделок в работе · 6 461 750 ₽</AppHeader.Description>
-        </AppHeader.Title>
-      </AppHeader.Start>
-      <AppHeader.Tools>
-        <PageToolbar.Root aria-label="Сделки">
-          <PageToolbar.Sections>
-            <SegmentedControl.Root
-              fullWidth
-              value={view}
-              onValueChange={onViewChange}
-              aria-label="Вид"
-            >
-              <SegmentedControl.Item value="board">Доска</SegmentedControl.Item>
-              <SegmentedControl.Item value="list">Список</SegmentedControl.Item>
-            </SegmentedControl.Root>
-          </PageToolbar.Sections>
-          <PageToolbar.Actions>
-            <Button.Root>
-              <Button.Icon>
-                <Icon name="action.add" />
-              </Button.Icon>
-              Новая сделка
-            </Button.Root>
-          </PageToolbar.Actions>
-        </PageToolbar.Root>
-      </AppHeader.Tools>
-    </AppHeader.Root>
-  );
-}
-```
-
 ## Navigation structure (the sidebar's content)
 
 The sidebar is the product's map: people scan it, remember where things are and come back. Build it
@@ -208,20 +151,20 @@ shows only icons); none on the children of a sub-list.
 
 ## Page wrapper
 
-- App pages (dashboard, list, detail, a board): `PageContent.Root as="section"` — the full width of
-  the panel; the page's title and tools are in its `AppHeader`, its blocks go into
-  `PageContent.Body` ([the page skeleton](composition.md#1-page-skeleton)).
-- Document pages — settings and long forms: `PageContent.Root maxWidth="wide"` with `PageContent.Header`
-  (the page's h1) and a `PageContent.Section layout="aside"`
-  (heading column + panel) per section ([the settings page](reference/components/page-content/examples/screen.tsx)), or `maxWidth="readable"` for a single
+- App pages (dashboard, list, detail, a board): `Page.Root` — the full width of the panel; the
+  page's title and tools are in its `Page.TopBar`, its blocks go into `Page.Body`
+  ([the page skeleton](composition.md#1-page-skeleton)).
+- Document pages — settings and long forms: `Page.Root maxWidth="wide"` with `Page.Header` in the
+  flow (the page's h1) and a `Page.Section layout="aside"` (heading column + panel) per section
+  ([the settings page](reference/layout/page/examples/screen.tsx)), or `maxWidth="readable"` for a single
   narrow column of fields.
-- Long reading text (terms, help): `PageContent.Root maxWidth="readable"` with `PageContent.Header`.
+- Long reading text (terms, help): `Page.Root maxWidth="readable"` with `Page.Header` in the flow.
 - A page as high as the panel (a log, a board, a chat): `AppShell.Root fillViewport` +
-  `PageContent.Root fill`; the body passes its free height to a filling child — DataTable
-  `scrollHeight="fill"`, Crossfade `fill`, `PageContent.Split`. Never compute heights from `100vh`.
-- List + detail (mail, a messenger, a ticket queue): `PageContent.Split` with `PageContent.Panel kind="list"` and
-  `PageContent.Panel kind="detail"` in a filling page. Side by side from 48rem of the split's own width, one pane
-  at a time below it with `PageContent.BackButton` first in the detail's header; `open` is «a record
+  `Page.Root fill`; the body passes its free height to a filling child — DataTable
+  `scrollHeight="fill"`, Crossfade `fill`, `Page.Split`. Never compute heights from `100vh`.
+- List + detail (mail, a messenger, a ticket queue): `Page.Split` with `Page.List` and
+  `Page.Detail` in a filling page. Side by side from 48rem of the split's own width, one pane
+  at a time below it with `Page.BackButton` first in the detail's header; `open` is «a record
   is chosen». Each pane gives its last child the free height: a Card with its own `ScrollContainer`
   (`anchor="end"` for a thread). The records in the list pane are a `List` (`current` on the open
   one), the conversations of a messenger a `ChatList`. Details that open over a table and close

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

@@ -72,7 +72,7 @@ Avatar.Group           overlapping row, gives its size to members
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Avatar.Group
-`ref` → `HTMLDivElement`. An overlapping row (`role="group"`); members overlap by 25% with a ring in `--avatar-ring`.
+`ref` → `HTMLDivElement`. An overlapping row (`role="group"`); members overlap by an eighth of the diameter with a ring in `--avatar-ring`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -119,7 +119,7 @@ The soft fill is opaque: the soft hue is composited over the ground the avatar s
 ## Layout & spacing
 - Inline-flex, never shrinks, `vertical-align: middle`.
 - Avatar → name: space step 3 (12px) in lists and cards, step 2 (8px) in table cells.
-- Group: members overlap by 25% of the diameter with a 2px ring in the ground they stand on: the current layer of the surface around them (no surface sets anything), or `--avatar-ring` from a host whose ground is not a layer (a reaction chip sets its own fill); the fills of initials and «+N» are composited over the same ground.
+- Group: members overlap by an eighth of the diameter (initials are never cut) with a 2px ring in the ground they stand on: the current layer of the surface around them (no surface sets anything), or `--avatar-ring` from a host whose ground is not a layer (a reaction chip sets its own fill); the fills of initials and «+N» are composited over the same ground.
 - An icon fallback is half the diameter: a kit `Icon` reads `--prime-icon-size`, a raw svg too.
 
 ## Accessibility

package/dist/skill/reference/components/avatar/examples/team-group.tsx

@@ -28,7 +28,7 @@ const MEMBERS: { name: string; initials: string; color: PaletteColor; src?: stri
 
 export default function AvatarTeamGroupExample() {
   return (
-    <Avatar.Group size="s" aria-label="Участники проекта: 7">
+    <Avatar.Group size="l" aria-label="Участники проекта: 7">
       {MEMBERS.map((member) => (
         <Avatar.Root key={member.initials} color={member.color} aria-label={member.name}>
           {member.src ? <Avatar.Image src={member.src} /> : null}

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

@@ -12,6 +12,7 @@
 - A selected value, keyword or applied filter the user can remove (`onRemove`).
 - Values in a filter panel that toggle on press and hide with a hover action (the `pressed` triad, `Badge.Action`).
 - A short code as a square tile (a file format «PDF») — `shape="square"`.
+- Several badges as one value (the tags of a client, a record's labels) — `Badge.Group`: it wraps and keeps one gap.
 
 ## When not to use
 - A multi-select field with chips → use [TagSelect](../tag-select/COMPONENT.md) (it renders badges itself).
@@ -33,6 +34,8 @@ Badge.Root          <span>: fill, tier dimensions
 │                   (a toggle <button> with the pressed triad; a <span> with a trailing segment; none when read-only)
 ├─ Badge.Action     optional end segment revealed on hover / focus (always shown on touch screens)
 └─ remove segment   with onRemove: full height, the whole end is the hit area (Icon action.close)
+
+Badge.Group         <div>: a wrapping row of Badge.Root, one value; `size` sets every badge's tier
 ```
 
 ## API
@@ -60,6 +63,14 @@ Badge.Root          <span>: fill, tier dimensions
 | `children` | `ReactNode` | — | Text, `Badge.Dot`, `Badge.Icon`, one `Badge.Action`. Only `Badge.Icon` children (no remove or action) make a square icon-only badge. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "onClick" \| "color">` | — | `aria-label` (an icon-only badge named by it is an image) and the other span attributes; no `onClick` — a pressable chip is the toggle. |
 
+### Badge.Group
+`ref` → `HTMLDivElement`. A row of badges as one value (the tags of a record): it wraps onto more lines, the badges a chip gap apart.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | the host tier, one step down | Tier of every badge in the group; a badge's own `size` wins. Small tiers stand closer. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the `Badge.Root`s), `className`, `aria-label` (a named group is `role="group"`) and the other div attributes. |
+
 ### Badge.Icon
 `ref` → `HTMLSpanElement`. A `<span>` holding one icon at the tier icon size. At the first or last position it becomes a full-height edge segment.
 
@@ -163,7 +174,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - `Badge.Dot` is 6px, 8px from `l`; alone it takes the tier of the surrounding control; `color` paints it in the solid step of that hue.
 - The root never clips: the text ellipsizes in its own box, so the segments' touch areas reach past the chip.
 - `Badge.Action` room is reserved, so revealing it never changes the badge width.
-- Several badges in a row: `gap: var(--prime-space-2)`.
+- Several badges in a row: `Badge.Group` — it wraps, badges 8 apart (4 at the `xs` and `s` tiers).
 - In a list row the badge is the trailing column; the title column gets `min-width: 0` and an ellipsis.
 
 ## Accessibility
@@ -206,6 +217,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 | [server-tags.tsx](examples/server-tags.tsx) | Order tags removed on the server: a badge waits dimmed with a spinner, leaves once the server agrees and stays with an announcement when it refuses — `onRemove`, `labels`. |
 | [filter-values.tsx](examples/filter-values.tsx) | Filter values as toggles with a hide action that slides in without changing the width — `pressed`, `onPressedChange`, `Badge.Action`, `persistent`. |
 | [square.tsx](examples/square.tsx) | File formats as square tiles of text, large enough for three letters; the hue sorts them by kind — `shape`, `size`, `color`. |
+| [tag-row.tsx](examples/tag-row.tsx) | The tags of a client as one value: the row wraps in a narrow column and keeps one gap between badges — `Badge.Group`, `size`. |
 | [controlled.tsx](examples/controlled.tsx) | Delivery cities as toggle chips whose state the screen owns: the summary counts the chosen ones — `pressed`, `onPressedChange`. |
 
 ## Mistakes
@@ -217,6 +229,7 @@ A status takes `tone`; a category takes `color`. The two never go together (the
 - Several removable badges with the default «Удалить» → pass `labels.remove` with the badge text.
 - A colored badge with no text → keep a word; color alone is not a signal.
 - An explicit `size` inside a control → drop it; the badge takes the tier one step down.
+- A row of badges in a hand-made flex wrapper with its own gap → `Badge.Group`.
 - `onRemove` together with `Badge.Action` → one end segment per badge.
 - Removing the badge from your list first and putting it back when the request fails → return the request's promise and remove it after it succeeds; the badge waits meanwhile.
 

package/dist/skill/reference/components/badge/examples/examples.module.css

@@ -23,3 +23,10 @@
   align-items: center;
   gap: var(--prime-space-2);
 }
+
+/* tag-row.tsx: a 320 px column, narrow enough for the row of badges to wrap. */
+.column {
+  display: grid;
+  gap: var(--prime-space-6);
+  inline-size: min(100%, calc(var(--prime-space-20) * 4));
+}

package/dist/skill/reference/components/badge/examples/tag-row.tsx

@@ -0,0 +1,34 @@
+/** The tags of a client as one value: the row wraps in a narrow column and keeps one gap between badges — `Badge.Group`, `size`. */
+import { Badge } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const TAGS = [
+  { label: "Ключевой клиент", color: "purple" },
+  { label: "Оптовые закупки", color: "blue" },
+  { label: "Отсрочка 30 дней", color: "orange" },
+  { label: "ЭДО", color: "teal" },
+  { label: "Москва", color: "gray" },
+  { label: "Новый договор", color: "green" },
+] as const;
+
+export default function BadgeTagRowExample() {
+  return (
+    <div className={styles.column}>
+      <Badge.Group aria-label="Теги клиента">
+        {TAGS.map((tag) => (
+          <Badge.Root key={tag.label} color={tag.color}>
+            {tag.label}
+          </Badge.Root>
+        ))}
+      </Badge.Group>
+      <Badge.Group size="s" aria-label="Теги заказа">
+        {TAGS.slice(0, 4).map((tag) => (
+          <Badge.Root key={tag.label} color={tag.color}>
+            {tag.label}
+          </Badge.Root>
+        ))}
+      </Badge.Group>
+    </div>
+  );
+}

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

@@ -29,8 +29,8 @@ Banner.Root                 <div>; variant, tone, size, placement
 │  ├─ Banner.Icon           one Icon on the first line (aria-hidden)
 │  ├─ Banner.Title
 │  ├─ Banner.Description
-│  └─ Banner.Actions        buttons; with onDismiss the close button is last here
-└─ close button             with onDismiss and no Actions: ghost icon Button (tone="inherit"), top-right
+│  └─ Banner.Actions        buttons; with onDismiss the close button is last here (wide banner)
+└─ close button             with onDismiss and no Actions, or Actions under the text: ghost icon Button (tone="inherit"), top-right
 ```
 
 ## API
@@ -72,7 +72,7 @@ Banner.Root                 <div>; variant, tone, size, placement
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
 ### Banner.Actions
-`ref` → `HTMLDivElement`. A `<div>` row of buttons; with `onDismiss` the close button becomes its last square button.
+`ref` → `HTMLDivElement`. A `<div>` row of buttons; with `onDismiss` the close button becomes its last square button (in the corner below 36rem).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -115,7 +115,7 @@ Banner.Root                 <div>; variant, tone, size, placement
 |---|---|---|
 | look | `variant`, `tone`, `size`, `placement` | `data-variant`, `data-tone`, `data-size`, `data-placement` |
 | dismissible | `onDismiss` | corner ghost Button (`xs`, `s` on `l` / `xl`), or the last outline Button in `Banner.Actions` |
-| narrow | own width < 36rem (a banner with `Banner.Actions` is a size container) | actions move under the text |
+| narrow | own width < 36rem (a banner with `Banner.Actions` is a size container) | actions move under the text; the close button returns to the corner |
 
 No `open` prop: the parent mounts and unmounts the banner. A mounted banner enters (a short fade and rise); an unmounted one closes up in place, so the content below glides up instead of jumping. To swap the banner for another block in the same spot (a «restore» button), wrap both in [Crossfade](../crossfade/COMPONENT.md).
 

package/dist/skill/reference/components/banner/examples/examples.module.css

@@ -8,7 +8,8 @@
   min-width: 0;
 }
 
-/* page-strip.tsx: the page strip above a card with an inset banner. */
+/* page-strip.tsx: a page — the strip spans its whole width, the content below keeps the page's
+   side padding, so the strip reads wider than the card with the inset banner. */
 .sections {
   display: flex;
   flex-direction: column;
@@ -17,6 +18,10 @@
   min-width: 0;
 }
 
+.pageBody {
+  padding-inline: var(--prime-layout-gutter);
+}
+
 /* narrow.tsx: a 320px column; the banner's container query moves actions under the text. */
 .narrow {
   width: min(100%, calc(var(--prime-space-20) * 4));

package/dist/skill/reference/components/banner/examples/page-strip.tsx

@@ -6,7 +6,7 @@ import styles from "./examples.module.css";
 export default function BannerPageStripExample() {
   return (
     <div className={styles.sections}>
-      {/* In an app the strip stands first in the page, edge to edge above its content. */}
+      {/* In an app the strip stands first in the page, edge to edge above its padded content. */}
       <Banner.Root
         tone="warning"
         placement="page"
@@ -21,27 +21,29 @@ export default function BannerPageStripExample() {
           <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
         </Banner.Content>
       </Banner.Root>
-      <Card.Root variant="panel">
-        <Card.Header>
-          <Card.Title>Оплата</Card.Title>
-        </Card.Header>
-        <Card.Body>
-          <Banner.Root tone="danger">
-            <Banner.Content>
-              <Banner.Icon>
-                <Icon name="status.danger" />
-              </Banner.Icon>
-              <Banner.Title>Не удалось списать оплату</Banner.Title>
-              <Banner.Description>
-                Карта •••• 4242 отклонена банком. Обновите способ оплаты до 15 октября.
-              </Banner.Description>
-              <Banner.Actions>
-                <Button.Root tone="danger">Обновить карту</Button.Root>
-              </Banner.Actions>
-            </Banner.Content>
-          </Banner.Root>
-        </Card.Body>
-      </Card.Root>
+      <div className={styles.pageBody}>
+        <Card.Root variant="panel">
+          <Card.Header>
+            <Card.Title>Оплата</Card.Title>
+          </Card.Header>
+          <Card.Body>
+            <Banner.Root tone="danger">
+              <Banner.Content>
+                <Banner.Icon>
+                  <Icon name="status.danger" />
+                </Banner.Icon>
+                <Banner.Title>Не удалось списать оплату</Banner.Title>
+                <Banner.Description>
+                  Карта •••• 4242 отклонена банком. Обновите способ оплаты до 15 октября.
+                </Banner.Description>
+                <Banner.Actions>
+                  <Button.Root tone="danger">Обновить карту</Button.Root>
+                </Banner.Actions>
+              </Banner.Content>
+            </Banner.Root>
+          </Card.Body>
+        </Card.Root>
+      </div>
     </div>
   );
 }

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

@@ -23,7 +23,7 @@ import { Breadcrumb } from "prime-ui-kit";
 ## Anatomy
 ```
 Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels; auto-collapse into a «…» menu
-├─ Breadcrumb.Item        <li>: a link (href → LinkButton), text, or the current page (current)
+├─ Breadcrumb.Item        <li>: a link (href → LinkButton, or a router link with asChild), text, or the current page (current)
 └─ Breadcrumb.Ellipsis    <li> with «…» for levels skipped on purpose
 ```
 
@@ -32,7 +32,7 @@ Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Breadcrumb.Root
-`ref` → `HTMLElement` (the `<nav>`). `<nav aria-label>` with an `<ol>`; draws the chevrons between levels, sets the size and, on narrow containers, collapses the middle levels into a «…» menu button that lists them.
+`ref` → `HTMLElement` (the `<nav>`). `<nav aria-label>` with an `<ol>`; draws the chevrons between levels, sets the size and folds levels that do not fit into a «…» menu button that lists them: the middle ones, then the first one too.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -42,14 +42,15 @@ Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other `nav` attributes; an `aria-label` here overrides `labels.nav`. |
 
 ### Breadcrumb.Item
-`ref` → `HTMLLIElement`. `<li>`: a muted `LinkButton` (`href`), plain text, or the current page (`current`).
+`ref` → `HTMLLIElement`. `<li>`: a muted `LinkButton` (`href`, or the consumer's router link with `asChild`), plain text, or the current page (`current`). A press on the link goes through `Page.Guard`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `href` | `string` | — | Renders a link; without it the item is text. |
+| `href` | `string` | — | Renders a link; without it (and without `asChild`) the item is text. |
+| `asChild` | `boolean` | `false` | The single child (a router `Link`) is the level's link with the same look; its own text is the level. In the «…» menu of a folded path it is the menu item. |
 | `current` | `boolean` | — | Current page: `aria-current="page"` (on the link when `href` is set), primary text, medium weight. Usually the last item, without `href`. |
 | `aria-label` | `string` | — | Name of a link without visible text (e.g. a home icon); set on the link, not the `li`. |
-| `children` | `ReactNode` | — | Text or an `Icon`. A string also becomes the `title` of a text item (full text when truncated). |
+| `children` | `ReactNode` | — | Text or an `Icon`; with `asChild` one element. A string also becomes the `title` of a text item (full text when truncated). |
 | `…rest` | `Omit<LiHTMLAttributes<HTMLLIElement>, "aria-label">` | — | `className` and the other `li` attributes. |
 
 ### Breadcrumb.Ellipsis
@@ -77,6 +78,7 @@ Breadcrumb.Root           <nav aria-label> + <ol>; size; chevrons between levels
 | text (no `href`, no `current`) | muted text | a level without its own page | yes |
 | current (`current`) | primary text, medium weight | the last item — this page | |
 | icon link (`href` + `aria-label`, `Icon` child) | icon at the tier icon size | a «home» root | |
+| router link (`asChild`, one `Link` child) | the same muted link, the consumer's element | an app with a client router: the path moves without a reload | |
 
 Use links for every ancestor and `current` on the last item; `s` above a `heading-m` page title. Avoid `href` on the current item and two `current` items.
 
@@ -85,15 +87,17 @@ Use links for every ancestor and `current` on the last item; `s` above a `headin
 |---|---|---|
 | current | `current` | `aria-current="page"` on the text span, or on the link when the item has `href` |
 | hover / focus-visible on links | pointer / keyboard | text → primary; focus ring from LinkButton |
-| truncation | width | each level truncates with an ellipsis, max width `2 × --prime-space-24` (192; `--prime-space-24 + --prime-space-6`, 120, when its container is below 30rem — its own for 3+ levels, the nearest one above for 1–2); the last item shrinks last |
-| auto-collapse | 3+ levels and a container `< 30rem` | `data-collapsible="true"`; middle levels are `display: none` and replaced by «… ›»: a ghost menu button (`Dropdown.Trigger`, named by `labels.ellipsis`) whose menu lists them — links stay links, a level without `href` is a disabled row |
+| truncation | width | each level truncates with an ellipsis, max width `2 × --prime-space-24` (192); the current page shrinks at half the rate of the others |
+| auto-collapse | 2+ levels whose whole path does not fit the width uncut (measured on every resize) | `data-collapsible="true"`, `data-collapsed="true"`; middle levels are `display: none` and replaced by «… ›»: a ghost menu button (`Dropdown.Trigger`, named by `labels.ellipsis`) whose menu lists them — links stay links, a level without `href` is a disabled row |
+| deep collapse | the path folded as above still does not fit | `data-collapsed="deep"`; the first level folds too: «…» › current page, the menu lists every level before it |
 | collapse menu open | a press, `Enter` or `ArrowDown` on the «…» | `aria-expanded="true"` on the button; a `role="menu"` panel at the tier size |
+| held | a `Page.Guard` that is `busy` or `dirty` on the page | a press on a level's link (in the path or the «…» menu) stops before it navigates; `dirty` asks first, then repeats it |
 
-Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
+Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`), `data-collapsed` (`"true"` / `"deep"`).
 
 ## Layout & spacing
-- A path of 1–2 levels takes its content width (at most the row), so in a flex row — the `AppHeader` start, before `AppHeader.Separator` and the title — what follows stands right after it. A path of 3+ levels is a size container (`container-type: inline-size`, `inline-size: 100%`) that folds its middle levels by its own width: inside a flex row give it `flex: 1 1 auto; min-width: 0`.
-- In an `AppHeader` the path up holds the list a record belongs to (1–2 levels); the record itself is the `AppHeader.Title` after the separator, not the breadcrumb's `current` item.
+- A single level takes its content width (at most the row). A path of 2+ levels fills the row (`inline-size: 100%`) and folds by that width, so a wider row unfolds it again; its intrinsic width stays the whole path, so a host that measures natural widths (the `Page.TopBar` plan) reads it uncut. Inside a flex row give it a box that takes the room it may use (`flex: 1 1 auto; min-width: 0`).
+- In a `Page.Heading` the path up holds the list a record belongs to (1–2 levels); the record itself is the `Page.Title` (in a top bar the path's last level, after the chevron), not the breadcrumb's `current` item.
 - Above a page title: `gap: var(--prime-space-2)` between the trail and the title row.
 - The list never wraps. Chevrons sit inside each level after the first, in the placeholder text color, at the tier icon size.
 
@@ -113,7 +117,7 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 
 - `nav` landmark with `aria-label` from `labels.nav`; an ordered list.
 - The current page has `aria-current="page"`; the chevrons are `aria-hidden` spans inside the levels, so every list item is a level.
-- Collapsed middle levels leave the layout and the tab order (no invisible focus stops); the automatic «…» is a menu button (`aria-haspopup="menu"`) named by `labels.ellipsis`, and its menu lists them as links.
+- Collapsed levels leave the layout and the tab order (no invisible focus stops); the automatic «…» is a menu button (`aria-haspopup="menu"`) named by `labels.ellipsis`, and its menu lists them as links.
 - Icon-only links need `aria-label` on the Item.
 
 ### Labels
@@ -132,13 +136,15 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 | [with-icon.tsx](examples/with-icon.tsx) | The root level as a home icon; a link without text is named for screen readers — `aria-label`. |
 | [overflow.tsx](examples/overflow.tsx) | A long path: levels truncate, and in a 320px container the middle ones collapse into a «…» menu that lists them — `Breadcrumb.Item`, `current`. |
 | [ellipsis.tsx](examples/ellipsis.tsx) | Levels skipped on purpose shown as «…» whose hidden text names them for screen readers — `Breadcrumb.Ellipsis`, `labels`. |
+| [router.tsx](examples/router.tsx) | Router links as the levels above: the path moves without a reload; render it inside a router — `asChild`, `current`. |
 
 ## Mistakes
 - Separators by hand between items → the root draws the chevrons.
 - `<Breadcrumb.Item href="…" current>` → the current page has no `href`.
 - Breadcrumb inside a flex row collapsing to zero width → give it `flex: 1 1 auto; min-width: 0`.
 - Home icon link without `aria-label` → add `aria-label="Главная"`.
+- `href` + `onClick` with `preventDefault()` and `navigate()` for a router → `asChild` with the router's `Link`.
 
 ## Related
 - **Built from:** [LinkButton](../link-button/COMPONENT.md) (`tone="muted"`), [Button](../button/COMPONENT.md) and [Dropdown](../dropdown/COMPONENT.md) (the collapse menu), Icon (`nav.chevronRight`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
-- **See also:** [Tabs](../tabs/COMPONENT.md), [PageContent](../page-content/COMPONENT.md), [Stepper](../stepper/COMPONENT.md)
+- **See also:** [Tabs](../tabs/COMPONENT.md), [Page](../../layout/page/COMPONENT.md), [Stepper](../stepper/COMPONENT.md)

package/dist/skill/reference/components/breadcrumb/examples/router.tsx

@@ -0,0 +1,17 @@
+/** Router links as the levels above: the path moves without a reload; render it inside a router — `asChild`, `current`. */
+import { Breadcrumb } from "prime-ui-kit";
+import { Link } from "react-router-dom";
+
+export default function BreadcrumbRouterExample() {
+  return (
+    <Breadcrumb.Root>
+      <Breadcrumb.Item asChild>
+        <Link to="/crm">CRM</Link>
+      </Breadcrumb.Item>
+      <Breadcrumb.Item asChild>
+        <Link to="/crm/clients">Клиенты</Link>
+      </Breadcrumb.Item>
+      <Breadcrumb.Item current>ООО «Северный ветер»</Breadcrumb.Item>
+    </Breadcrumb.Root>
+  );
+}