prime-ui-kit 0.20.1 → 0.21.1

package/dist/skill/reference/components/smart-filter/COMPONENT.md

@@ -93,6 +93,7 @@ One entry of `fields`: data, not a part. Selected values missing from `options`
 | `finite` | `boolean` | `true` | `options` fields: a fixed set — hiding every value is refused. `false` for an open set (services, users). |
 | `multiple` | `boolean` | `true` | `options` fields: many values at once. `false` — one value and no hiding: a press picks only that value, a second press clears it (an API that takes one value per field). |
 | `formatValue` | `(value: number) => string` | Russian digit groups | `range` fields: a bound in the chip («1 000 ₽»). |
+| `calendar` | `Pick<DatepickerPanelProps, "months" \| "presets" \| "prompt" \| "footer" \| "withTime" \| "isDayDisabled" \| "disableFuture" \| "today" \| "locale" \| "weekStartsOn" \| "labels">` | — | `date-range` fields: the calendar of the period, as on a report's own Datepicker — `presets`, `months`, `prompt`, `footer`, `withTime`; the chip names a matching preset («Период: Этот месяц»). Without it the panel opens one month with no presets. |
 
 ### Functions
 
@@ -233,7 +234,7 @@ same height and type.
 | [overview.tsx](examples/overview.tsx) | Filters above a request list: the filter button and the search, applied filters as tags, rows narrowed by the value and the text — `fields`, `value`, `search`, `matchesSmartFilter`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: the filter button, the search, the tags and the panel follow one tier — `size`. |
 | [many-values.tsx](examples/many-values.tsx) | An open set of twenty services, degraded ones marked with an icon, collapsed after eight; typing narrows the panel and marks the match in accent — `finite`, `icon`, `collapsedLimit`. |
-| [ranges.tsx](examples/ranges.tsx) | Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `matchesSmartFilter`, `isSmartFilterRange`. |
+| [ranges.tsx](examples/ranges.tsx) | Deals narrowed by an amount from–to and a period from a calendar with presets, two months and an Apply footer; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `calendar`, `matchesSmartFilter`, `isSmartFilterRange`. |
 | [single-value.tsx](examples/single-value.tsx) | For an API that takes one value per field: the filter button without a search, a press picks only that value and nothing can be hidden — `searchable`, `multiple`. |
 | [option-groups.tsx](examples/option-groups.tsx) | Values of different kinds in one field: owner types and people under their own headings — `options`, `group`. |
 | [controlled.tsx](examples/controlled.tsx) | A saved view sets the value from outside; the selection is read back as the list to ask the server for — `value`, `onValueChange`, `resolveSmartFilterValues`. |

package/dist/skill/reference/components/smart-filter/examples/ranges.tsx

@@ -1,6 +1,7 @@
-/** Deals narrowed by an amount from–to and a period from the calendar; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `matchesSmartFilter`, `isSmartFilterRange`. */
+/** Deals narrowed by an amount from–to and a period from a calendar with presets, two months and an Apply footer; each range is one readable chip, and the bounds go to the server as from / to parameters — `kind`, `formatValue`, `calendar`, `matchesSmartFilter`, `isSmartFilterRange`. */
 import {
   Card,
+  DEFAULT_DATEPICKER_PRESETS,
   formatDateValue,
   isSmartFilterRange,
   matchesSmartFilter,
@@ -17,7 +18,12 @@ const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
 
 const FIELDS: SmartFilterField[] = [
   { key: "amount", label: "Сумма", kind: "range", formatValue: formatRubles },
-  { key: "closed", label: "Период", kind: "date-range" },
+  {
+    key: "closed",
+    label: "Период",
+    kind: "date-range",
+    calendar: { presets: DEFAULT_DATEPICKER_PRESETS, months: 2, prompt: true, footer: true },
+  },
   {
     key: "stage",
     label: "Этап",

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

@@ -68,7 +68,7 @@ Spinner          <span role="status">; size and tone
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| appearing | mounted | fades in over `fast` (`internal/enterMotion`), so a spinner that comes and goes never blinks |
+| appearing | mounted into a host already shown | fades in over `fast` (`internal/enterMotion`), so a spinner that comes and goes never blinks; one that mounts with its page stands still |
 | spinning | mounted | the ring turns at a constant speed (`--prime-motion-loop × 3` per turn, linear) |
 | reduced motion | `prefers-reduced-motion` | the ring keeps turning, twice as slow (`--prime-motion-loop × 6` per turn) and linear: a loading cue is information, so the token is not zeroed |
 | size / tone | `size`, `tone` | `data-size` (the explicit size, else the host control tier, else `m`), `data-tone` (only for a non-default tone) |

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

@@ -35,7 +35,7 @@ Tabs.Root                 value, size (else the host tier), orientation, tone, f
 │  │  ├─ Tabs.Count       counter Badge, one tier below the tabs size
 │  │  └─ Tabs.Description muted second line; makes the tab two-line
 │  └─ Tabs.Separator      Divider hairline between groups of tabs
-└─ Tabs.Panel             role="tabpanel", rendered only while its tab is active; no fill, no padding
+└─ Tabs.Panel             role="tabpanel", rendered only while its tab is active (keepMounted: kept hidden once opened); no fill, no padding
 ```
 
 ## API
@@ -120,11 +120,12 @@ Tabs.Root                 value, size (else the host tier), orientation, tone, f
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other div attributes. |
 
 ### Tabs.Panel
-`ref` → `HTMLDivElement`. `<div role="tabpanel">`, focusable, rendered only while its tab is active. No fill and no padding: its content is the host's content, aligned with the strip's edges. Its content enters each time it opens.
+`ref` → `HTMLDivElement`. `<div role="tabpanel">`, focusable, rendered only while its tab is active (with `keepMounted`, kept hidden once opened). No fill and no padding: its content is the host's content, aligned with the strip's edges. Content opened after mount enters.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `string` | — (required) | Tab value this panel belongs to. |
+| `keepMounted` | `boolean` | `false` | Once opened, the panel stays mounted and `hidden` while another tab is active: its data, form draft and scroll survive a switch. A panel never opened is not mounted. |
 | `children` | `ReactNode` | — | Panel content. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
 
@@ -187,13 +188,14 @@ Avoid icons or descriptions on only some tabs (uneven rows; without an icon on e
 | disabled | `disabled` on Item | native `disabled`, `data-disabled="true"`, `text-disabled`; a removable tab loses its close button |
 | removable | `onRemove` on Item | item wrapper `data-removable="true"`, close button, tab `aria-keyshortcuts="Delete"` |
 | closing, confirm pending | `onRemove` returned a promise that has not settled | the close button is `loading` (`aria-busy`); the tab, its selection and focus stay; resolved → the neighbour takes over, rejected → nothing changes |
+| kept | `keepMounted` on Panel, its tab once opened and now inactive | the panel stays mounted with `hidden` (out of the layout, the tab order and the accessibility tree); its tab keeps `aria-controls`; shown again, its content enters as on a first open |
 | two-line | `Tabs.Description` child | `data-two-line="true"` |
 | collapsed | tabs wider than the list, or a label that would be cut (horizontal) | list `data-collapse="full" \| "compact" \| "icon"`: `compact` hides icons and descriptions; `icon` takes labels, counts and close buttons out of the row — a `VisuallyHidden` copy of the label names the tab and a `Tooltip` shows it — only when every tab has an icon |
 | overflow | tabs at their narrowest (content width, `minItemWidth` or icon squares) still wider than the list | `data-overflow-start` / `data-overflow-end` on the list (the switcher row, a ScrollContainer), faded edges as deep as the hidden part at most (they grow and melt with the scroll, never switch); when the end edge would cut only a tab's empty side, the tabs at `minItemWidth` widen a little (`--tabs-peek`, up to 30%) so a label fades out at the edge and shows that more tabs follow; the active tab is kept in view and clear of the fades on mount and on every value change, the first and the last tab scroll all the way to the end — only the list scrolls, never the page. A column (a wide vertical list) has plain edges |
 
 The indicator glides (`emphasized` + `base`, `data-animate="true"`) only into a choice by click, arrow keys or closing the active tab; on mount, a value set from outside, a resize, font loading, tabs added or removed and collapse it is placed without motion, and it stays still under `prefers-reduced-motion`. The list scrolls smoothly to the active tab only after such a choice too.
 
-Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; the folder (the list's first child, `data-indicator`) `data-axis="x" | "y"` (follows the list's direction, so a vertical list in a narrow container gets the top folder); Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted, and a tab points at its panel (`aria-controls`) only while the panel is in the document; a panel's content enters each time it opens.
+Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-width`, inline `--tabs-item-min` / `--tabs-item-max` when set; the folder (the list's first child, `data-indicator`) `data-axis="x" | "y"` (follows the list's direction, so a vertical list in a narrow container gets the top folder); Item `data-value` on the tab, `data-state` / `data-disabled` on its wrapper too; Label `data-text`. Inactive panels are unmounted (unless `keepMounted`), and a tab points at its panel (`aria-controls`) only while the panel is in the document; a panel's content enters each time it opens after mount (the panel shown on mount stands still).
 
 ## Layout & spacing
 - Tabs are a bar, not a surface: the root has no fill, padding, radius or `data-depth`. On a page or in a `Card.Body`, put it straight into the host's padded region and the panel content straight into `Tabs.Panel`. The strip's edges and the panel content share the host's content edge; the panel stands one tier gap below the strip (`--prime-space-3` … `--prime-space-8`).
@@ -261,7 +263,7 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 | [overflow.tsx](examples/overflow.tsx) | Drag the frame narrower: icons go first, then labels, and icons with tooltips stay; then the list scrolls — `Tabs.Icon`. |
 | [closable.tsx](examples/closable.tsx) | Open order cards as browser tabs: each closes by its button, Delete or a middle click; tabs stay between two widths, and the list scrolls when they do not fit — `onRemove`, `minItemWidth`, `maxItemWidth`. |
 | [two-line.tsx](examples/two-line.tsx) | A label and a counter on the first line, a summary on the second — `Tabs.Count`, `Tabs.Description`. |
-| [in-drawer.tsx](examples/in-drawer.tsx) | Order details in a Drawer: the tab bar runs along the bottom of the header, the active tab is the body rising into it, and every panel is the body's own content — `Tabs.Root`, `Tabs.List`, `Tabs.Panel`. |
+| [in-drawer.tsx](examples/in-drawer.tsx) | Order details in a Drawer: the tab bar runs along the bottom of the header and scrolls sideways when the tabs outgrow the drawer, the active tab is the body rising into it, every panel is the body's own content, and the delivery form keeps its edits across tabs — `Tabs.Root`, `Tabs.List`, `Tabs.Panel`, `keepMounted`. |
 | [controlled.tsx](examples/controlled.tsx) | The active tab lives in parent state, e.g. synced with the URL — `value`, `onValueChange`. |
 
 ## Mistakes
@@ -274,6 +276,7 @@ Other attributes: Root `data-orientation`, `data-size`, `data-tone`, `data-full-
 - A hand-made × inside `Tabs.Item` → a button inside a tab button; pass `onRemove` instead.
 - `onRemove` that does not drop the tab from your list → the tab stays; the kit only moves the selection.
 - `Tabs.List` without `aria-label` → add one.
+- Lifting a panel's data or form draft to the parent only so it survives a tab switch → `keepMounted` on that `Tabs.Panel`.
 - Tabs inside `Drawer.Body` / `Modal.Body` under the header → a floating strip under the header's hairline; wrap the header and the body in `Tabs.Root` and put `Tabs.List` into the header.
 
 ## Related

package/dist/skill/reference/components/tabs/examples/in-drawer.tsx

@@ -1,4 +1,4 @@
-/** Order details in a Drawer: the tab bar runs along the bottom of the header, the active tab is the body rising into it, and every panel is the body's own content — `Tabs.Root`, `Tabs.List`, `Tabs.Panel`. */
+/** Order details in a Drawer: the tab bar runs along the bottom of the header and scrolls sideways when the tabs outgrow the drawer, the active tab is the body rising into it, every panel is the body's own content, and the delivery form keeps its edits across tabs — `Tabs.Root`, `Tabs.List`, `Tabs.Panel`, `keepMounted`. */
 import { Badge, Button, DescriptionList, Drawer, Fieldset, Input, Tabs } from "prime-ui-kit";
 
 const ITEMS = [
@@ -7,6 +7,11 @@ const ITEMS = [
   { name: "Сборка и подъём на этаж", amount: "1 × 3 200 ₽" },
 ];
 
+const DOCUMENTS = [
+  { name: "Счёт № 1042-С", date: "3 октября" },
+  { name: "Накладная № 1042-Н", date: "4 октября" },
+];
+
 const HISTORY = [
   { time: "3 октября, 10:14", event: "Заказ оформлен" },
   { time: "3 октября, 10:20", event: "Оплата прошла" },
@@ -33,6 +38,7 @@ export default function TabsInDrawerExample() {
                 <Tabs.Count>{ITEMS.length}</Tabs.Count>
               </Tabs.Item>
               <Tabs.Item value="delivery">Доставка</Tabs.Item>
+              <Tabs.Item value="documents">Документы</Tabs.Item>
               <Tabs.Item value="history">История</Tabs.Item>
             </Tabs.List>
           </Drawer.Header>
@@ -58,7 +64,7 @@ export default function TabsInDrawerExample() {
               </DescriptionList.Root>
             </Tabs.Panel>
 
-            <Tabs.Panel value="delivery">
+            <Tabs.Panel value="delivery" keepMounted>
               <Fieldset aria-label="Доставка">
                 <Input.Root label="Адрес">
                   <Input.Wrapper>
@@ -73,6 +79,16 @@ export default function TabsInDrawerExample() {
               </Fieldset>
             </Tabs.Panel>
 
+            <Tabs.Panel value="documents">
+              <DescriptionList.Root>
+                {DOCUMENTS.map((document) => (
+                  <DescriptionList.Item key={document.name} label={document.name}>
+                    {document.date}
+                  </DescriptionList.Item>
+                ))}
+              </DescriptionList.Root>
+            </Tabs.Panel>
+
             <Tabs.Panel value="history">
               <DescriptionList.Root>
                 {HISTORY.map((entry) => (

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

@@ -142,6 +142,7 @@ Thumbnail.Root          frame (a <div>; the child with asChild; a <button role="
 - In a table the row grows to the thumbnail; never shrink the thumbnail to the row.
 - Card covers: `fullWidth` inside the card body, the body's gap to the title.
 - No outline by default: the fill separates the preview.
+- In a leading media slot (`Drawer.Icon`, `Modal.Icon`, `Sheet.Icon`, `Card.Icon`) the thumbnail takes the slot's size (`m`, 40px) whatever `size` it was given, also through a wrapper component of yours; the slot then draws no tile.
 
 ## Accessibility
 

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

@@ -110,7 +110,7 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| open / closed | hover (mouse, pen) or focus after `delayDuration`; `open` / `defaultOpen` / `onOpenChange` | `data-state="open" \| "closed"` on the chip (closed during the exit) and on the trigger |
+| open / closed | hover (mouse, pen) or keyboard focus after `delayDuration` (not the focus a click causes or a dialog moves in after a click); `open` / `defaultOpen` / `onOpenChange` | `data-state="open" \| "closed"` on the chip (closed during the exit) and on the trigger |
 | closing | blur, a press on the trigger, Escape, pointer leaving (unless it moves onto the chip) | — |
 | warm group | another tooltip of the Provider was just shown | `data-instant="true"`: opens and leaves without motion |
 | side | `side` and the room around the trigger | `data-side` (resolved), `data-align` |
@@ -128,7 +128,7 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 
 | Key | Action |
 |---|---|
-| `Tab` | Focus on the trigger opens the tooltip after the delay. |
+| `Tab` | Keyboard focus on the trigger opens the tooltip after the delay; focus a click causes, or a layer moves in after a click, does not. |
 | `Escape` | Hides the tooltip; focus stays on the trigger. |
 
 ### ARIA
@@ -137,7 +137,7 @@ A chip of tier T is as tall as a menu item of tier T; text, padding and radius s
 - The chip is `role="tooltip"`; while open the trigger points at it with `aria-describedby` (appended to the child's own).
 - `Tooltip.Trigger` composes the child's `ref`, sets `data-state` and chains the child's `onPointerEnter`, `onPointerLeave`, `onPointerDown`, `onFocus` and `onBlur`.
 - The tooltip is a description, not the name: an icon-only button needs its own `aria-label`.
-- The pointer may move onto the chip without closing it (WCAG 1.4.13); a touch does not open it, focus does.
+- The pointer may move onto the chip without closing it (WCAG 1.4.13); a touch does not open it, keyboard focus does.
 - Tooltip has no `closeOnEscape` / `closeOnOutsideClick` (foundation §8): it closes on pointer-leave, blur, a press on the trigger and Escape, and Escape cannot be turned off — WCAG 1.4.13 requires the chip to be dismissable without moving the pointer or focus.
 - A `disabled` control (its own prop or a disabled `Fieldset`) is wrapped by the kit in a focusable `<span>`: the host takes hover and Tab, the focus ring is drawn on the control. Around a button the host is that button for assistive tech — `role="button"`, `aria-disabled`, named by the control through `aria-labelledby` — and the control itself leaves the tree.
 - A trigger that is no tab stop (Badge, Avatar, ProgressCircle, `Icon` with `label`) gets `tabIndex={0}` and the focus ring; its name comes from `aria-label` or the icon `label`.

package/dist/skill/reference/foundation.md

@@ -51,11 +51,14 @@ The design contract for every component. Tokens live in `tokens/` and are genera
    perfectly in a row (Button, Input, Select, Datepicker trigger, SegmentedControl, Tabs).
 5. **Nested radius = outer radius − padding.** Panel 12 with padding 4 → items 8.
 6. **Air is hierarchy.** Important content gets more space; secondary content is grouped tighter.
-7. **State changes are continuous.** Nothing on screen flips from one state to another. Controls move
-   into their new state (§7 Motion, rule 8); a region that changes what it shows — loading → data →
+7. **State changes are continuous; loading never unfolds.** Nothing on screen flips from one state to
+   another. Controls move into their new state (§7 Motion, rule 8). Whatever loads is a `Skeleton` in
+   the data's geometry from the first paint — never nothing, never a region that grows from zero —
+   and the data then replaces it in place: no height glide, no reveal, no slide, at most a short
+   cross-fade, the layout settled in one frame. A region swapping between settled states — data →
    empty → error, one record → another — cross-fades and glides to its new height (`Crossfade`). A
-   loading region holds the shape of what is coming (`Skeleton` with the data's geometry), so the
-   swap moves nothing. This holds for every region of every screen, not only for prominent ones.
+   region that mounts in its state shows it still. This holds for every region of every screen, not
+   only for prominent ones.
 
 ## 2. Token layers and naming
 
@@ -339,8 +342,8 @@ Every component is designed with its micro-animations, not only its static state
    `padding`, `top/left`; never `transition: all` — list the properties. Where size must animate, prefer
    `transform` / `scale` (progress fills). The exceptions are a closed list, each with one engine,
    and `src/styles/motion-perf.test.ts` allows nothing else:
-   - **height glide** — a region that swaps its content glides to the new height (`Crossfade`, the
-     Notification stack);
+   - **height glide** — a region that swaps its content between settled states glides to the new
+     height (`Crossfade`, the Notification stack); a swap into or out of loading never glides;
    - **row fold** — a part that folds open or closed animates `grid-template-rows` 0fr ↔ 1fr
      (`Disclosure`: Accordion, DataTable expanded rows);
    - **text width** — a label that morphs into another text glides its `width` (`MorphText`).
@@ -353,8 +356,11 @@ Every component is designed with its micro-animations, not only its static state
 8. **State moves, it does not swap.** Checkmark draws/scales in, switch thumb slides, selection indicator
    (tabs, segmented control) glides to the new item, chevrons rotate, progress fills, counters and fills
    ease. Two states cross-fade rather than flip when they replace each other in place: a region
-   swapping its content uses `Crossfade` (inside a component: `RegionSwap`), and its
-   loading state is a `Skeleton` of the coming content (principle 7).
+   swapping its content uses `Crossfade` (inside a component: `RegionSwap`). Its loading state is
+   the state `"loading"`: a `Skeleton` of the coming content, drawn from the first paint, which the
+   data replaces in place — the height settles in one frame and the fade takes `fast`; only a swap
+   between settled states fades on `base` and glides its height (principle 7). Nothing moves on the
+   first render of a region.
 9. **Interruptible.** Toggled state uses CSS transitions (retarget mid-flight), not keyframes. Keyframes only
    for one-shot enter/exit (overlay presence, spinner, skeleton) and one-shot gestures (icons, rule 13;
    a field's error shake, rule 14).
@@ -394,7 +400,7 @@ should stay still, and say so in a CSS comment only when the omission is non-obv
 | selected | `accent-soft` bg + `accent-text`, or check icon in `accent-text` |
 | disabled | `fill-muted`/`field-bg-disabled` bg, `text-disabled` color, no shadow, `cursor: not-allowed` |
 | loading (control) | spinner replaces leading icon, label stays, width does not change, `aria-busy` |
-| loading (region) | `Skeleton` in the data's geometry inside `Crossfade`, `aria-busy` on the region; data already shown stays during a refresh |
+| loading (region) | `Skeleton` in the data's geometry from the first paint, as the `"loading"` state of `Crossfade` (the data replaces it in place, no height glide), `aria-busy` on the region; data already shown stays during a refresh |
 | error | `danger-border` inset ring + `danger-text` message; layout does not shift (support row reserves height when the component asks for it) |
 | empty | centered muted text in `body-s`, optional action; reached through `Crossfade` like every region state |
 

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

@@ -8,7 +8,8 @@
 ## When to use
 - 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). The search, filter, chips and column chooser of a page that is one list stay there too — the list is the page. On a page that holds more than its table (KPI cards, a chart), they belong to the table's own tools row (DataTable `toolbar` + `toolbarChips`), not the bar.
+- 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 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"`).
@@ -44,8 +45,8 @@ Page.Root                          the page column (<div>); maxWidth, fill, labe
 │  │  ├─ Page.Title                <h1>, title-m, the path's last level, truncates
 │  │  └─ Page.Description          <p>, muted caption under the whole line, truncates
 │  ├─ Page.Tools                   what acts on the whole page, in the order written: the one tool row (as the DataTable toolbar)
-│  │  ├─ SegmentedControl.Root     sections, view (fullWidth unless set)
-│  │  ├─ SmartFilter.Toolbar       search and filter: grows first on a line of its own
+│  │  ├─ SegmentedControl.Root     sections (route links of sub-pages), view (fullWidth unless set)
+│  │  ├─ SmartFilter.Toolbar       a search and filter over several views: grows first on a line of its own
 │  │  ├─ Datepicker.Root           a period (fullWidth unless set)
 │  │  └─ Select.Root …             a period, columns; the trigger fills its place
 │  ├─ Page.Actions                 every button of the page; icons, then «⋯» when short
@@ -122,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, a shared period, view; the search of a one-list page. The tool row of the DataTable `toolbar`: a search takes the free room, the rest keep their width at the end. Named, a `group`.
+`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`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -292,6 +293,7 @@ A wide cell (`span` 7–11) written next to a narrow one (`span` 4–5) is a pai
 - The edge air comes from the host: `AppShell.Main` sets `--page-gutter` (the page gutter, 16 → 24 → 32) and `--page-top` (24 → 32 from 1024px); `Page.Root` pads itself with them. Outside a host the page brings no air. The page resets both for what it holds, so a page nested in it starts clean.
 - `Page.TopBar` steps out of the gutter to the panel's edges and keeps the gutter inside; padding 12 above (or the top safe-area inset) and below; what follows starts 24 under its controls (header → body; the bar's own 12 counts in). The first line is as high as the Sidebar brand row (control m + 8), so the two read as one line. Groups 16 apart on a line, lines 12 apart; tools 8 apart; buttons 8 apart.
 - `Page.Tools` and `Page.Chips` are the kit's one tool row and chips line (`ToolRow`), the same as the DataTable `toolbar` and `toolbarChips`: the bar only places them. On the first line every tool keeps its natural width; on a line of their own they take the line and lay out from its width (container `prime-tool-row`), never from the window.
+- The tool row lays out the elements it is given, each in a cell: pass the tools as direct children of `Page.Tools` or a fragment. A wrapper component that returns several controls is one cell — no gaps between them, no growing search.
 - In the bar only the heading's column gives (`minmax(0, 1fr)`): the tools and the actions keep their width. The heading keeps its natural width until every button step is taken; then a heading with a path stacks (the path over the title, the title and the description wrapping), so no level is cut to a fragment; a heading without a path truncates its title.
 - The plan is measured, never chosen by breakpoints: the bar lays itself out from its own width.
 - Header (flow) → Body 24; blocks inside Body 24; a `Page.Section` 40 from its neighbours (the body's 24 + 16); tile → tile in a Grid 16 on both axes; section heading → content 16, heading → description 4; flow Title → Description 8; heading → Actions 24 side by side, 16 once they wrap below.
@@ -341,7 +343,8 @@ A wide cell (`span` 7–11) written next to a narrow one (`span` 4–5) is a pai
 | [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`. |
-| [tools.tsx](examples/tools.tsx) | The orders page's tools in its top bar: sections with counts, search and filter, the period, in the order written; the active filters on a line under everything — `Page.Tools`, `Page.Chips`. |
+| [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`. |
 | [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`. |
@@ -360,7 +363,8 @@ A wide cell (`span` 7–11) written next to a narrow one (`span` 4–5) is a pai
 - Buttons without an icon in a crowded bar → they cannot give way to an icon; give each `Button.Root` a `Button.Icon` beside its label.
 - Two places for buttons (some beside the title, the primary among the tools) → every button of the page goes into the one `Page.Actions`, the primary last.
 - `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` above KPI cards or a chart they do not filter → they read as filters of the whole page; move them into the table's `toolbar` / `toolbarChips`. The bar keeps the title, a period that drives every block, sections and the primary action.
+- 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.
 - `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/router.tsx

@@ -0,0 +1,124 @@
+/** 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`. */
+import {
+  Button,
+  Card,
+  Crossfade,
+  DataTable,
+  type DataTableColumn,
+  Icon,
+  Page,
+  SegmentedControl,
+} from "prime-ui-kit";
+import { Link, Route, Routes, useLocation } from "react-router-dom";
+
+type Channel = { id: string; name: string; dialogs: number; reply: string };
+
+const SUB_PAGES = [
+  { to: "/messengers/channels", label: "Каналы" },
+  { to: "/messengers/stats", label: "Статистика" },
+];
+
+const CHANNELS: Channel[] = [
+  { id: "tg", name: "Telegram · @prime_support", dialogs: 642, reply: "4 мин" },
+  { id: "wa", name: "WhatsApp · +7 495 120-44-10", dialogs: 391, reply: "7 мин" },
+  { id: "vk", name: "ВКонтакте · Прайм CRM", dialogs: 188, reply: "12 мин" },
+  { id: "avito", name: "Авито · Склад на Южной", dialogs: 59, reply: "25 мин" },
+];
+
+const COLUMNS: DataTableColumn<Channel>[] = [
+  { id: "name", header: "Канал", cell: (row) => row.name },
+  {
+    id: "dialogs",
+    header: "Диалогов",
+    numeric: true,
+    headerAlign: "end",
+    cell: (row) => row.dialogs,
+  },
+  {
+    id: "reply",
+    header: "Первый ответ",
+    numeric: true,
+    headerAlign: "end",
+    cell: (row) => row.reply,
+  },
+];
+
+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;
+
+  return (
+    <Page.Root>
+      <Page.TopBar sticky={false}>
+        <Page.Heading>
+          <Page.Title>Мессенджеры</Page.Title>
+          <Page.Description>4 канала · 1 280 диалогов за октябрь</Page.Description>
+        </Page.Heading>
+        <Page.Tools aria-label="Мессенджеры">
+          <SegmentedControl.Root value={current} aria-label="Подразделы">
+            {SUB_PAGES.map((page) => (
+              <SegmentedControl.Item key={page.to} value={page.to} asChild>
+                <Link to={page.to}>{page.label}</Link>
+              </SegmentedControl.Item>
+            ))}
+          </SegmentedControl.Root>
+        </Page.Tools>
+        <Page.Actions>
+          <Button.Root>
+            <Button.Icon>
+              <Icon name="action.add" />
+            </Button.Icon>
+            Подключить канал
+          </Button.Root>
+        </Page.Actions>
+      </Page.TopBar>
+      <Page.Body>
+        {/* `location` keeps the leaving sub-page on its own route while it fades out. */}
+        <Crossfade state={current}>
+          <Routes location={location}>
+            <Route
+              path="/messengers/stats"
+              element={
+                <Page.Grid>
+                  <Page.Cell span={4}>
+                    <Card.Root variant="stat-trend">
+                      <Card.Label>Диалогов</Card.Label>
+                      <Card.Value>1 280</Card.Value>
+                      <Card.Delta tone="success">+14% к сентябрю</Card.Delta>
+                    </Card.Root>
+                  </Page.Cell>
+                  <Page.Cell span={4}>
+                    <Card.Root variant="stat-trend">
+                      <Card.Label>Первый ответ</Card.Label>
+                      <Card.Value>6 мин</Card.Value>
+                      <Card.Delta tone="success">на 2 мин быстрее</Card.Delta>
+                    </Card.Root>
+                  </Page.Cell>
+                  <Page.Cell span={4}>
+                    <Card.Root variant="stat-trend">
+                      <Card.Label>Без ответа</Card.Label>
+                      <Card.Value>23</Card.Value>
+                      <Card.Delta tone="danger">+5 за сутки</Card.Delta>
+                    </Card.Root>
+                  </Page.Cell>
+                </Page.Grid>
+              }
+            />
+            <Route
+              path="*"
+              element={
+                <DataTable
+                  columns={COLUMNS}
+                  rows={CHANNELS}
+                  getRowKey={(row) => row.id}
+                  paging="none"
+                />
+              }
+            />
+          </Routes>
+        </Crossfade>
+      </Page.Body>
+    </Page.Root>
+  );
+}

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

@@ -1,10 +1,9 @@
-/** The orders page's tools in its top bar: sections with counts, search and filter, the period, in the order written; the active filters on a line under everything — `Page.Tools`, `Page.Chips`. */
+/** 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`. */
 import {
   Button,
   Icon,
   Page,
   SegmentedControl,
-  Select,
   SmartFilter,
   type SmartFilterField,
   type SmartFilterValue,
@@ -18,10 +17,9 @@ const SECTIONS = [
   { value: "cancelled", label: "Отменены", count: 20 },
 ];
 
-const PERIODS = [
-  { value: "7d", label: "7 дней" },
-  { value: "30d", label: "30 дней" },
-  { value: "quarter", label: "Квартал" },
+const VIEWS = [
+  { value: "list", label: "Список" },
+  { value: "board", label: "Доска" },
 ];
 
 const FIELDS: SmartFilterField[] = [
@@ -46,7 +44,7 @@ const FIELDS: SmartFilterField[] = [
 
 export default function PageToolsExample() {
   const [section, setSection] = React.useState("all");
-  const [period, setPeriod] = React.useState("30d");
+  const [view, setView] = React.useState("list");
   const [filter, setFilter] = React.useState<SmartFilterValue>({
     city: { include: ["msk"], exclude: [] },
   });
@@ -75,21 +73,13 @@ export default function PageToolsExample() {
               ))}
             </SegmentedControl.Root>
             <SmartFilter.Toolbar />
-            <Select.Root value={period} onValueChange={setPeriod}>
-              <Select.Trigger aria-label="Период">
-                <Select.TriggerIcon>
-                  <Icon name="field.calendar" />
-                </Select.TriggerIcon>
-                <Select.Value />
-              </Select.Trigger>
-              <Select.Content>
-                {PERIODS.map((item) => (
-                  <Select.Item key={item.value} value={item.value}>
-                    {item.label}
-                  </Select.Item>
-                ))}
-              </Select.Content>
-            </Select.Root>
+            <SegmentedControl.Root value={view} onValueChange={setView} aria-label="Вид">
+              {VIEWS.map((item) => (
+                <SegmentedControl.Item key={item.value} value={item.value}>
+                  {item.label}
+                </SegmentedControl.Item>
+              ))}
+            </SegmentedControl.Root>
           </Page.Tools>
           <Page.Actions>
             <Button.Root>

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

@@ -26,7 +26,10 @@ same place. Structure it by what people do, not by how the backend is split.
   it stays folded; its `…` row marks the page).
 - **One level of nesting.** `Sidebar.Sub` is one section with 2–6 views of the same objects
   (Сделки → Новые · В работе · Закрытые). The parent only discloses; an overview page is the first
-  child («Все сделки»). Never a sub-list inside a sub-list — split the section or use page tabs.
+  child («Все сделки»). Never a sub-list inside a sub-list — split the section. Facets of one section
+  («Мессенджеры» → «Каналы» · «Статистика») are no sub-list: they are route links in the page's
+  `Page.Tools`, and the section's item stays `current` on every sub-route (a `NavLink` without `end`,
+  or `current={pathname.startsWith("/messengers")}`).
 - **Icons.** Every top-level item and every sub-list parent has a distinct icon (on the rail the
   icon is all that is left); children of a sub-list have none.
 - **Numbers and dots.** A plain `Sidebar.ItemCount` is information (12 new deals): it leaves the
@@ -70,7 +73,7 @@ Sidebar.Root                       rail wrapper; renders <nav> inside; size tier
 │        ├─ Sidebar.SubTrigger     disclosure row, chevron at the end
 │        └─ Sidebar.SubContent     child Items on a guide line (a flyout on the compact rail)
 └─ Sidebar.Footer                  bottom items, the item Toggle, the account
-   └─ Sidebar.Account              avatar + name + muted line; a Dropdown.Trigger child
+   └─ Sidebar.Account              avatar + name + muted line; a ↕ chevron as a Dropdown.Trigger child
 useSidebar()                       state hook for custom parts inside Root (useAppShellNav outside it, in a shell)
 ```
 
@@ -220,7 +223,7 @@ useSidebar()                       state hook for custom parts inside Root (useA
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `children` (Items), `className` (on the list) and the other div attributes. |
 
 ### Sidebar.Account
-`ref` → `HTMLButtonElement`. The signed-in person at the bottom of `Sidebar.Footer`: avatar, name, a muted line and a ↕ chevron. A button, so it is a `Dropdown.Trigger` child; in compact mode only the avatar stays, with the name as a tooltip.
+`ref` → `HTMLButtonElement`. The signed-in person at the bottom of `Sidebar.Footer`: avatar, name, a muted line; a ↕ chevron only as a `Dropdown.Trigger` child. In compact mode only the avatar stays, with the name as a tooltip.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -311,6 +314,7 @@ Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header,
 | flyout | hover / click / keyboard on a SubTrigger, or on the `…` row of a folded group, in compact mode | the row `aria-haspopup="dialog"`, `aria-expanded`; a Popover `role="dialog"` |
 | attention dot | a coloured `Sidebar.ItemCount` inside a folded Sub (always on the rail) or a folded Group | `Badge.Dot` with `data-attention="shown" \| "hidden"` on the parent row / heading / `…` row |
 | persisted | `persistKey` on Root | the mode and the open state of collapsible groups and sub-lists are read from and written to `localStorage` |
+| account menu | `Sidebar.Account` inside a `Dropdown.Trigger` (`aria-haspopup="menu"`) | the ↕ chevron at the end of the row; without a menu (a plain `onClick`, a `Drawer.Trigger`) no chevron |
 | disabled | `disabled` | Item `disabled` / `aria-disabled`, `data-disabled` |
 
 `persistKey` stores collapsible groups and sub-lists by their `id`, else by their label text — give an `id` when labels are translated or change. The stored state wins over `defaultMode` / `defaultOpen`; controlled `mode` / `open` are not stored, and unavailable storage is ignored. A hidden rail is stored as the mode it left, so a reload never strands a person on a hidden rail.
@@ -388,6 +392,7 @@ Leaving the narrow viewport closes the off-canvas panel; activating an item (a l
 | [collapsible-groups.tsx](examples/collapsible-groups.tsx) | Group headings that fold their items away, one group open at a time, with a chevron at the end of the heading; on the compact rail a folded group becomes one row whose items open in a flyout — `collapsible`, `open`, `onOpenChange`. |
 | [nested-items.tsx](examples/nested-items.tsx) | A parent item with child items on a guide line: a current child opens it and marks the parent; on the compact rail the children open in a flyout — `Sidebar.Sub`, `Sidebar.SubTrigger`, `Sidebar.SubContent`. |
 | [account.tsx](examples/account.tsx) | Footer items and the collapse row above the signed-in person: avatar, name and email open the account menu; collapse the rail from that row and only the avatar stays, on the icon axis — `Sidebar.Footer`, `Sidebar.Account`, `description`, `Sidebar.Toggle`. |
+| [account-profile.tsx](examples/account-profile.tsx) | The signed-in person opens a profile panel, not a menu, so the row draws no chevron — `Sidebar.Account`, `description`. |
 | [router.tsx](examples/router.tsx) | Router links as the brand and the items: the router marks the current link and the item shows it as current; render it inside a router — `asChild`. |
 | [persist.tsx](examples/persist.tsx) | The first visit opens on the icon rail; the mode and the folded groups are remembered and come back after a reload — `persistKey`, `defaultMode`. |
 | [custom-part.tsx](examples/custom-part.tsx) | A part of your own in the footer reads the rail state: the storage meter shows on the full rail and in the off-canvas panel and steps aside on the icon rail — `useSidebar`. |