prime-ui-kit 0.17.0 → 0.19.0

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

@@ -1,4 +1,4 @@
-/** A settings page as a document: the path in the top bar that repeats the title once it scrolls away, the large title in the flow, sections with a heading column and a panel, a form saved by its own button, switches that apply at once and a danger zone with a confirm — `collapse`, `layout`, `maxWidth`. */
+/** A settings page as a document: the path in the top bar that repeats the title once it scrolls away, the large title in the flow, each section a card with its own heading, a form saved by its own button, switches that apply at once and a danger zone with a confirm — `collapse`, `maxWidth`, `Card.Header`. */
 import {
   Breadcrumb,
   Button,
@@ -88,118 +88,107 @@ export default function PageScreenExample() {
         </Page.Heading>
       </Page.Header>
       <Page.Body>
-        <Page.Section
-          layout="aside"
-          label="Компания"
-          description="Попадают в счета, акты и письма клиентам."
-        >
-          <form noValidate onSubmit={save} onReset={() => setInnError(undefined)}>
-            <Card.Root variant="panel">
-              <Card.Body>
-                <Fieldset disabled={saving}>
-                  <Input.Root label="Название">
+        <form noValidate onSubmit={save} onReset={() => setInnError(undefined)}>
+          <Card.Root variant="panel">
+            <Card.Header>
+              <Card.Title as="h2">Компания</Card.Title>
+              <Card.Description>Попадают в счета, акты и письма клиентам.</Card.Description>
+            </Card.Header>
+            <Card.Body>
+              <Fieldset disabled={saving}>
+                <Input.Root label="Название">
+                  <Input.Wrapper>
+                    <Input.Field name="name" defaultValue="ООО «Прайм Софт»" />
+                  </Input.Wrapper>
+                </Input.Root>
+                <div className={styles.pair}>
+                  <Input.Root label="ИНН" error={innError} hint="10 или 12 цифр" reserveSupportRow>
                     <Input.Wrapper>
-                      <Input.Field name="name" defaultValue="ООО «Прайм Софт»" />
+                      <Input.Field name="inn" inputMode="numeric" defaultValue="7704512908" />
                     </Input.Wrapper>
                   </Input.Root>
-                  <div className={styles.pair}>
-                    <Input.Root
-                      label="ИНН"
-                      error={innError}
-                      hint="10 или 12 цифр"
-                      reserveSupportRow
-                    >
-                      <Input.Wrapper>
-                        <Input.Field name="inn" inputMode="numeric" defaultValue="7704512908" />
-                      </Input.Wrapper>
-                    </Input.Root>
-                    <Select.Root label="Часовой пояс" defaultValue="Europe/Moscow">
-                      <Select.Trigger>
-                        <Select.Value />
-                      </Select.Trigger>
-                      <Select.Content searchable>
-                        {TIMEZONES.map((zone) => (
-                          <Select.Item key={zone.value} value={zone.value}>
-                            {zone.label}
-                          </Select.Item>
-                        ))}
-                      </Select.Content>
-                    </Select.Root>
-                  </div>
-                  <Textarea.Root
-                    name="address"
-                    label="Юридический адрес"
-                    optional
-                    rows={2}
-                    defaultValue="125009, Москва, ул. Тверская, д. 7, офис 412"
-                  />
-                </Fieldset>
-              </Card.Body>
-              <Card.Footer>
-                <Button.Root type="reset" variant="ghost" tone="neutral" disabled={saving}>
-                  Отменить изменения
-                </Button.Root>
-                <Button.Root type="submit" loading={saving}>
-                  {saved ? "Сохранено" : "Сохранить"}
-                </Button.Root>
-              </Card.Footer>
-            </Card.Root>
-          </form>
-        </Page.Section>
-
-        <Page.Section
-          layout="aside"
-          label="Уведомления"
-          description="Включаются сразу, без сохранения."
-        >
-          <Card.Root variant="panel">
-            <Card.Body>
-              <Fieldset aria-label="Уведомления">
-                {ALERTS.map((alert) => (
-                  <Switch.Root
-                    key={alert.name}
-                    name={alert.name}
-                    defaultChecked={alert.defaultChecked}
-                    hint={alert.hint}
-                  >
-                    <Switch.Label>{alert.label}</Switch.Label>
-                  </Switch.Root>
-                ))}
+                  <Select.Root label="Часовой пояс" defaultValue="Europe/Moscow">
+                    <Select.Trigger>
+                      <Select.Value />
+                    </Select.Trigger>
+                    <Select.Content searchable>
+                      {TIMEZONES.map((zone) => (
+                        <Select.Item key={zone.value} value={zone.value}>
+                          {zone.label}
+                        </Select.Item>
+                      ))}
+                    </Select.Content>
+                  </Select.Root>
+                </div>
+                <Textarea.Root
+                  name="address"
+                  label="Юридический адрес"
+                  optional
+                  rows={2}
+                  defaultValue="125009, Москва, ул. Тверская, д. 7, офис 412"
+                />
               </Fieldset>
             </Card.Body>
+            <Card.Footer>
+              <Button.Root type="reset" variant="ghost" tone="neutral" disabled={saving}>
+                Отменить изменения
+              </Button.Root>
+              <Button.Root type="submit" loading={saving}>
+                {saved ? "Сохранено" : "Сохранить"}
+              </Button.Root>
+            </Card.Footer>
           </Card.Root>
-        </Page.Section>
+        </form>
 
-        <Page.Section
-          layout="aside"
-          label="Рабочее пространство"
-          description="Действия, которые нельзя отменить."
-        >
-          <Card.Root variant="panel">
-            <Card.Body>
-              <div className={styles.danger}>
-                <div className={styles.dangerText}>
-                  <Typography variant="title-s">Удалить пространство</Typography>
-                  <Typography variant="body-s" tone="secondary">
-                    Счета, клиенты и история будут удалены для всех участников.
-                  </Typography>
-                </div>
-                <ConfirmDialog.Root
-                  title="Удалить «Прайм Софт»?"
-                  description="312 счетов, 48 клиентов и вся история удалятся без возможности восстановления."
-                  confirmLabel="Удалить пространство"
-                  onConfirm={removeWorkspace}
+        <Card.Root variant="panel">
+          <Card.Header>
+            <Card.Title as="h2">Уведомления</Card.Title>
+            <Card.Description>Включаются сразу, без сохранения.</Card.Description>
+          </Card.Header>
+          <Card.Body>
+            <Fieldset aria-label="Уведомления">
+              {ALERTS.map((alert) => (
+                <Switch.Root
+                  key={alert.name}
+                  name={alert.name}
+                  defaultChecked={alert.defaultChecked}
+                  hint={alert.hint}
                 >
-                  <ConfirmDialog.Trigger>
-                    <Button.Root variant="outline" tone="danger">
-                      Удалить
-                    </Button.Root>
-                  </ConfirmDialog.Trigger>
-                </ConfirmDialog.Root>
+                  <Switch.Label>{alert.label}</Switch.Label>
+                </Switch.Root>
+              ))}
+            </Fieldset>
+          </Card.Body>
+        </Card.Root>
+
+        <Card.Root variant="panel">
+          <Card.Header>
+            <Card.Title as="h2">Рабочее пространство</Card.Title>
+            <Card.Description>Действия, которые нельзя отменить.</Card.Description>
+          </Card.Header>
+          <Card.Body>
+            <div className={styles.danger}>
+              <div className={styles.dangerText}>
+                <Typography variant="title-s">Удалить пространство</Typography>
+                <Typography variant="body-s" tone="secondary">
+                  Счета, клиенты и история будут удалены для всех участников.
+                </Typography>
               </div>
-            </Card.Body>
-          </Card.Root>
-        </Page.Section>
+              <ConfirmDialog.Root
+                title="Удалить «Прайм Софт»?"
+                description="312 счетов, 48 клиентов и вся история удалятся без возможности восстановления."
+                confirmLabel="Удалить пространство"
+                onConfirm={removeWorkspace}
+              >
+                <ConfirmDialog.Trigger>
+                  <Button.Root variant="outline" tone="danger">
+                    Удалить
+                  </Button.Root>
+                </ConfirmDialog.Trigger>
+              </ConfirmDialog.Root>
+            </div>
+          </Card.Body>
+        </Card.Root>
       </Page.Body>
     </Page.Root>
   );

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

@@ -1,5 +1,5 @@
-/** 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, a heading column beside a panel — `Page.Section`, `label`, `description`, `Page.Actions`, `layout`. */
-import { Card, DataTable, type DataTableColumn, LinkButton, Page, Typography } from "prime-ui-kit";
+/** 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`. */
+import { Card, DataTable, type DataTableColumn, LinkButton, Page } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
@@ -55,19 +55,6 @@ export default function PageSectionsExample() {
           </Page.Actions>
           <DataTable columns={COLUMNS} rows={INVOICES} getRowKey={(row) => row.id} paging="none" />
         </Page.Section>
-        <Page.Section
-          layout="aside"
-          label="Реквизиты в счетах"
-          description="Попадают в каждый новый счёт."
-        >
-          <Card.Root variant="panel">
-            <Card.Body>
-              <Typography variant="body-m" tone="secondary">
-                ООО «Прайм Софт», ИНН 7701234567, р/с в Т-Банке.
-              </Typography>
-            </Card.Body>
-          </Card.Root>
-        </Page.Section>
       </Page.Body>
     </div>
   );

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

@@ -299,6 +299,7 @@ Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header,
 ## States
 | State | Driven by | DOM |
 |---|---|---|
+| held | a `Page.Guard` that is `busy` or `dirty` on the page | a press on `Sidebar.Item` or `Sidebar.Brand` stops before it navigates (a router link included) and the panel stays; `dirty` asks first, then repeats it |
 | mode | `mode` / `defaultMode` | Root `data-mode`, `data-panel-mode` (the last visible mode while hidden); `<nav inert>` while hidden |
 | off-canvas | `offCanvas="always"`, or `"auto"` + viewport < 768px | Root `data-off-canvas`, `data-state="open" \| "closed"`; `<nav inert>` while closed; the kit scrim (`role="presentation"`) while open; in an `AppShell` the shell Root `data-off-canvas` |
 | placing | the viewport crossed the off-canvas breakpoint (not a person's choice) | Root `data-placing` for one painted frame: the rail lands at its new width with no motion (no growing from 0, no folding rows, no sliding panel) |

package/dist/skill/responsive.md

@@ -48,7 +48,8 @@ A layout inside a page needs no breakpoint: it takes its columns from the room i
 
 - The tiles of a page (KPI cards, charts, panels) are one `Page.Grid` with a
   `Page.Cell span` per tile: it folds by its own width (below 30rem every tile takes the row,
-  then small tiles pair up, from 64rem each its span).
+  then small tiles pair up, from 64rem each its span). Write a wide tile (`span` 7–11) next to a
+  narrow one (4–5): between 40 and 64rem the two pair up as 2/3 + 1/3, so an 8 + 4 row keeps no hole.
 - A grid inside one block (thumbnails, short fields of one record) is the block's own
   `grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--prime-layout-tile-min-width)), 1fr))`
   — `auto-fill`, so a lone item keeps its column width instead of stretching across the row.
@@ -61,11 +62,11 @@ Use these as they are; never wrap them in your own breakpoints.
 
 | Need | Built in |
 |---|---|
-| app frame | `AppShell.Main` hands the page its gutters 16 → 24 → 32 and top air 24 → 32; `Page.TopBar` un-sticks on screens lower than 480px and respects the top safe area; in the bar the title and its line of data truncate |
+| app frame | `AppShell.Main` hands the page its gutters 16 → 24 → 32, top air 24 → 32 and bottom air 64 (the gutter under a `fill` page; above a floating BottomNav it keeps the capsule's room); `Page.TopBar` un-sticks on screens lower than 480px and respects the top safe area |
 | app navigation | Sidebar: on-canvas from 768px, an off-canvas panel below (`offCanvas="auto"`) opened by the menu button `Page.TopBar` draws by itself while the Sidebar is off-canvas; `BottomNav` in `AppShell.Footer` for 2–6 app sections on phones — flat or a floating glass capsule (`floating`) with an optional round `BottomNav.Action`, icons with or without labels (`iconOnly`); the shell hides it by itself while the Sidebar rail is on screen (from 768px with `offCanvas="auto"`) |
-| page top bar | `Page.TopBar` lays out its groups from their natural widths: one line while they fit, then the tools on a line of their own, then icon-only buttons, then «⋯», and the heading truncates last ([below](#the-pages-top-bar--pagetopbar)). `Page.Header` in the flow: actions wrap under the title |
+| page top bar | `Page.TopBar` lays out its groups from their natural widths: one line while they fit, then the tools on a line of their own, then icon-only buttons, then «⋯», and the heading gives last ([below](#the-pages-top-bar--pagetopbar)). `Page.Header` in the flow: actions wrap under the title |
 | switchers | [Switchers](#switchers) never wrap or truncate: they scroll inside themselves |
-| tables | DataTable scrolls inside itself, edge shadows show hidden columns, `stickyFirstColumn`, `DataTable.ColumnsMenu` for a column chooser, the toolbar stacks below a 30rem table, sticky head off on short screens |
+| tables | DataTable scrolls inside itself, edge shadows show hidden columns, `stickyFirstColumn` and `stickyLastColumn` (row actions), `columnsMenu` for a column chooser in the header row, the toolbar stacks below a 30rem table, sticky head off on short screens |
 | floating layers | Popover (opened from a Trigger), Dropdown, Select (and Datepicker, ColorPresets) never wider than the viewport − 16, 8 from the edges, flip when out of room; below 640 they open as a bottom sheet — scrim, grab handle, swipe down to close, page scroll locked; Tooltip and TagSelect stay anchored |
 | dialogs | Modal is a bottom sheet with a handle below 640 (swipe down closes it while `closeOnOutsideClick` allows); footer actions stack on phones and in a dialog narrower than 360px; `Sheet` is a bottom sheet for a short task at every width (centred at 560 on a tablet or desktop) and closes with a swipe down from its handle or header; a Drawer has no swipe — buttons, Escape and the scrim close it |
 | date picking | Datepicker shows two months and side presets only when they fit; otherwise one month and presets above |
@@ -85,12 +86,16 @@ in this order, and nothing ever overflows:
 
 1. **One line** — `Page.Heading`, `Page.Tools` and `Page.Actions` side by side while they fit.
 2. **Tools below** — the tools take a line of their own under the first one and fill its width: a
-   search (`SmartFilter.Toolbar`, `Input.Root`) grows first, the switchers share the rest and wrap
-   when one line is not enough. The actions stay on the first line beside the heading at every width.
+   search (`SmartFilter.Toolbar`, `Input.Root`) grows first, the switchers and a period
+   (`Datepicker.Root`) share the rest and wrap when one line is not enough. Beside a search that
+   would get too little room the SmartFilter button shows only its icon and count, on the same row.
+   The actions stay on the first line beside the heading at every width.
 3. **Icons** — every Button with an icon shows only the icon, the secondary ones first, then the
    primary; its label stays its accessible name and becomes its tooltip.
 4. **«⋯»** — the secondary Buttons fold into a menu (`labels.more`); the primary always stays.
-5. **The heading truncates** — only after every button step: the path levels first, then the title.
+5. **The heading gives** — only after every button step: the middle levels of the path fold into
+   «…»; a heading with a path that still does not fit stacks (the path on its own line over the
+   title, the title and its description wrapping), so no level is cut to a fragment; a heading without a path truncates.
 
 `Page.Chips` is always a line of its own under everything, gone while no filter is set. The heading
 keeps its natural width: the bar sizes the title, so there is nothing to tune.
@@ -182,7 +187,7 @@ export function OrdersPage() {
   inside takes that tier.
 - A Button without an icon keeps its label at every step and leaves the bar less room before it
   folds: give each one a `Button.Icon`.
-- A SegmentedControl in `Page.Tools` needs no `fullWidth`: the bar sets it.
+- A SegmentedControl or a Datepicker in `Page.Tools` needs no `fullWidth`: the bar sets it.
 - The primary action is on screen at every width — as its icon at the narrowest; it never folds and
   never disappears.
 - Section totals go into `SegmentedControl.Count`, not into stat cards above the table.
@@ -199,8 +204,10 @@ export function OrdersPage() {
 - Every switcher — Tabs, SegmentedControl, a horizontal ButtonGroup and BottomNav — scrolls inside
   itself when its items do not fit: never a second line, never a truncated item. Its hidden edges
   fade, a vertical mouse wheel scrolls it sideways, touch pans it, the current item is scrolled into
-  view, and the indicator moves only after a person's choice. A SegmentedControl whose items all have
-  icons collapses to icons (each named by its tooltip) before it scrolls.
+  view, and the indicator moves only after a person's choice. A SegmentedControl first tightens its
+  segments' padding, and one whose items all have icons then collapses to icons (each named by its
+  tooltip) before it scrolls. On a 320px phone two sections with counts fit a line of their own;
+  more, or long labels, scroll — keep the section a person needs first at the start.
 - Your duty as its host: give the switcher a bounded width. A flex or grid child that holds one sets
   `min-width: 0`, otherwise the switcher grows the row instead of scrolling
   ([foundation §9](reference/foundation.md#9-layout-and-responsiveness)).
@@ -218,8 +225,8 @@ export function OrdersPage() {
 
 ## Components on narrow widths — what you still decide
 
-**Tables.** Let DataTable scroll inside itself; offer a column chooser (`DataTable.ColumnsMenu` in
-`toolbar`; the key column `hideable: false`); `stickyFirstColumn` for the name. On phones a table / cards switch in `Page.Tools` is fine — silently dropping columns
+**Tables.** Let DataTable scroll inside itself; offer a column chooser (`columnsMenu`, in the header
+row; the key column `hideable: false`); `stickyFirstColumn` for the name. On phones a table / cards switch in `Page.Tools` is fine — silently dropping columns
 by breakpoint is not. Never ask to rotate the phone.
 
 **Card grids.** [Intrinsic grids](#intrinsic-grids), never a breakpoint. Tiles of a row share one

package/dist/skill/ux.md

@@ -55,8 +55,10 @@ 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 unit lives in one place.** In the field (`Input.InlineAffix`) or in the heading, never both.
-  Prefer the field: the unit stays beside the number when the row stacks.
+- **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
+  describes the input; `aria-label="рублей"` on it when the sign reads badly).
 - **No text that explains the layout.** «Двигатель, места и скорость всегда первыми» — the lock on
   those rows says it. A hint says what the person cannot see (a format, a consequence, a limit).
 - **One name per thing.** The same action, entity and status keep one word on the whole screen
@@ -97,7 +99,7 @@ Pick the lightest step that keeps the person safe ([choosing.md](choosing.md) ha
 | One standalone action that is easy to redo by hand | `Button.Root holdToConfirm` |
 | Irreversible loss of work, or an outward action that cannot be called back once it leaves the product (an invoice or a message sent to a client, a payment) | `ConfirmDialog` that names the thing and the consequence |
 | Bulk destructive | `ConfirmDialog` that names the count («Удалить 12 счетов?») |
-| Leaving a form with changes | `Modal.Guard` / `Drawer.Guard dirty` |
+| Leaving a form with changes | `Modal.Guard` / `Drawer.Guard dirty`; a form that is the page — `Page.Guard dirty` |
 
 A confirm on every action trains people to click through it; the one that mattered is then missed.
 Which button starts each step and how the confirm behaves:

package/dist/tokens/semantic.d.ts

@@ -22,7 +22,7 @@ export declare const semanticTokens: {
             readonly inverse: "{color.gray.925}";
             readonly scrim: "color-mix(in srgb, {color.gray.925} 44%, transparent)";
             /** Soft shade over an edge that hides scrolled content (DataTable columns). */
-            readonly edgeShadow: "color-mix(in srgb, {color.gray.925} 14%, transparent)";
+            readonly edgeShadow: "color-mix(in srgb, {color.gray.925} 8%, transparent)";
             /**
              * Translucent glass over content (floating BottomNav), always with a strong backdrop blur
              * (`--prime-glass-saturation` lifts the colors under it): dense, as the iOS tab bar — the
@@ -801,6 +801,8 @@ export declare const semanticTokens: {
         readonly videoNote: "14.5rem";
         /** The box of a sent round video message (`VideoNote`): its diameter, at most the row. */
         readonly videoNoteBox: "16.75rem";
+        /** The square box of a sticker (`Message.Sticker`), at most the row. */
+        readonly sticker: "10rem";
         /**
          * A message changing size (a reaction row, a transcript that opens): the bubble's box, its
          * parts and the messages around glide in one calm stroke, between `fast` and `base`; zeroed

package/dist/tokens/themes/dark.d.ts

@@ -11,7 +11,7 @@ export declare const darkThemeOverrides: {
             readonly inverse: "{color.gray.100}";
             readonly scrim: "color-mix(in srgb, {color.black} 60%, transparent)";
             /** Darker than the scrim's share: a shade on a 900 surface needs more ink to read. */
-            readonly edgeShadow: "color-mix(in srgb, {color.black} 50%, transparent)";
+            readonly edgeShadow: "color-mix(in srgb, {color.black} 28%, transparent)";
             readonly glass: "color-mix(in srgb, {color.gray.875} 76%, transparent)";
             readonly glassEdge: "color-mix(in srgb, {color.white} 28%, transparent)";
         };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "packageManager": "bun@1.3.13",
-  "description": "React 19 UI kit for product interfaces: 78 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.",
+  "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": {
     "prime-ui-kit": "bin/prime-ui-kit.js"
   },

package/src/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/src/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/src/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/src/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
 ```
 
@@ -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.
 
@@ -89,6 +91,7 @@ Use links for every ancestor and `current` on the last item; `s` above a `headin
 | 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"`), `data-collapsed` (`"true"` / `"deep"`).
 
@@ -133,12 +136,14 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`), `data-c
 | [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)

package/src/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>
+  );
+}

package/src/components/button/COMPONENT.md

@@ -66,7 +66,7 @@ Button.Root        <button> (or the single child with asChild); variant, tone, s
 | `labels` | `Partial<ButtonLabels>` | — | Built-in strings, see Labels. |
 | `asChild` | `boolean` | `false` | Merges Button props and styles onto the single child element (a link) instead of rendering `<button>`. `disabled`/`loading` become `aria-disabled`; `progress` and `holdToConfirm` need a `<button>`. |
 | `disabled` | `boolean` | — | Disabled state; `loading` also disables. With `asChild` the child leaves the Tab order and a link loses its `href`. |
-| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → a square icon-only button that needs `aria-label`. A changed label morphs letter by letter. With `asChild`, the one child element. |
+| `children` | `ReactNode` | — | Label and `Button.Icon`. Only `Button.Icon` children → a square icon-only button that needs `aria-label`. A changed label morphs letter by letter. With `asChild`, the one child element; its text is the label too. |
 | `aria-label` | `string` | — | The name of a button without a visible label; required with `shape="circle"`. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "size" \| "aria-pressed">` | — | `onClick`, `type` (`"button"` by default, not passed on with `asChild`), `className`, `aria-*`, `data-*` and the other button attributes. |
 

package/src/components/button-group/COMPONENT.md

@@ -47,6 +47,7 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the `group`. |
 | `optional` | `boolean` | `false` | Muted marker after the label (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the control (`aria-describedby`). Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger inset ring, `aria-invalid` and `data-invalid` on the `group`; the control shakes once when an error arrives. |
 | `reserveSupportRow` | `boolean` | `false` | Always render the support row, so an appearing error does not shift the layout. |