prime-ui-kit 0.10.0 → 0.11.0

package/src/components/page-content/COMPONENT.md

@@ -3,18 +3,21 @@
 **Category:** page
 **Kind:** layout
 
-> Page structure inside the main column: title, description, page actions and content sections.
+> Page structure inside the main column: title, description, page actions and content sections; a page as high as the panel and the list + detail layout.
 
 ## When to use
 - Every route rendered inside `AppShell.Main`: a page heading (`<h1>`), an intro line, page-level actions and the page body.
 - A text page held to a reading measure (`PageContent.Root maxWidth="readable"`).
 - A wide dashboard page capped at the content width (`maxWidth="wide"`).
+- A page whose body takes the rest of the panel's height — a log table, a board, a chat (`fill`).
+- Mail, a messenger, a ticket queue: a list and the chosen record side by side, one at a time on a narrow panel (`PageContent.Split`).
 
 ## When not to use
 - The app frame (navigation rail, header, scrolling main column) → use [AppShell](../../layout/app-shell/COMPONENT.md).
 - A bounded block inside the page → use [Card](../card/COMPONENT.md).
 - An empty / error / not-found page → use [EmptyPage](../empty-page/COMPONENT.md).
 - Arbitrary headings inside content → use [Typography](../typography/COMPONENT.md).
+- Details that open over the list and close again (a record from a table) → use [Drawer](../drawer/COMPONENT.md); `Split` is for a list people work through record by record.
 
 ## Import
 ```tsx
@@ -23,12 +26,16 @@ import { PageContent } from "prime-ui-kit";
 
 ## Anatomy
 ```
-PageContent.Root | PageContent.Section     column; Root adds maxWidth, Section renders <section>
+PageContent.Root | PageContent.Section     column; Root adds maxWidth and fill, Section renders <section>
 ├─ PageContent.Header                      heading column + actions in one wrapping row
 │  ├─ PageContent.Title                    <h1>, heading-m
 │  ├─ PageContent.Description              <p>, secondary body-m
 │  └─ PageContent.Actions                  page buttons (moved to the end of the header row)
 └─ PageContent.Body                        page content, blocks 40 apart
+   └─ PageContent.Split                    list + detail; a container (prime-split)
+      ├─ PageContent.List                  list pane: 16–20rem column, or the whole split while closed
+      └─ PageContent.Detail                detail pane: the rest, or the whole split while open
+         └─ PageContent.BackButton         back to the list, only while one pane shows
 ```
 
 ## API
@@ -40,7 +47,8 @@ PageContent.Root | PageContent.Section     column; Root adds maxWidth, Section r
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `maxWidth` | `"full" \| "readable" \| "wide"` | `"full"` | Cap of the column: the whole main, `--prime-layout-content-max-width`, or a ~65ch reading measure. |
+| `maxWidth` | `"full" \| "readable" \| "wide"` | `"full"` | Cap of the column, centred: `full` — the whole main; `readable` — the reading measure `--prime-layout-reading-max-width` (42rem); `wide` — the content width `--prime-layout-content-max-width` (75rem). |
+| `fill` | `boolean` | `false` | The page takes the height of main (`AppShell.Root fillViewport`) and the body takes what the header leaves: for a full-height table, board, chat or `PageContent.Split`. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Header, Body), `className` and the other div attributes. |
 
 ### PageContent.Section
@@ -69,7 +77,7 @@ PageContent.Root | PageContent.Section     column; Root adds maxWidth, Section r
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `measure` | `"readable" \| "full"` | `"readable"` | `readable` — max ~65ch; `full` — the full width of the parent. |
+| `measure` | `"readable" \| "full"` | `"readable"` | `readable` — no wider than the reading measure `--prime-layout-reading-max-width` (42rem); `full` — the full width of the parent. |
 | `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `children`, `className` and the other paragraph attributes. |
 
 ### PageContent.Actions
@@ -86,14 +94,46 @@ PageContent.Root | PageContent.Section     column; Root adds maxWidth, Section r
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
+### PageContent.Split
+`ref` → `HTMLDivElement`. List + detail (mail, a messenger, a ticket queue): side by side from 48rem of its own width, one pane at a time below it, focus following the pane that comes into view.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean` | — | The detail is open (a record is chosen), controlled. On a narrow split it takes the place of the list; on a wide one both panes stay. |
+| `defaultOpen` | `boolean` | `false` | Initial open state, uncontrolled. |
+| `onOpenChange` | `(open: boolean) => void` | — | `PageContent.BackButton` closes the detail (`false`); clear the chosen record there. |
+| `labels` | `Partial<PageContentLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (`PageContent.List`, `PageContent.Detail`), `className` and the other div attributes. |
+
+### PageContent.List
+`ref` → `HTMLDivElement`. The list pane: a column whose last child takes the free height (a Card with its own ScrollContainer). Focusable from code (`tabindex=-1`, no ring): going back lands on the control that had focus, else here.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `aria-label`, `className` and the other div attributes. |
+
+### PageContent.Detail
+`ref` → `HTMLDivElement`. The detail pane, built like the list pane; focus lands here when it opens on a narrow split. Show a hint («Выберите диалог») while nothing is chosen: a wide split always shows this pane.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `aria-label`, `className` and the other div attributes. |
+
+### PageContent.BackButton
+`ref` → `HTMLButtonElement`. Back from the detail to the list: a soft neutral icon Button (`nav.chevronLeft`) named by `labels.back`, shown only while the split shows one pane. Put it first in the detail's header; `event.preventDefault()` in `onClick` keeps the detail open.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children">` | — | `onClick`, `aria-label` (replaces `labels.back`), `className` and the other button attributes. |
+
 ## Variants
 
 ### maxWidth (Root)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `full` | Column fills the main area | App pages, tables, dashboards in a padded main | yes |
-| `readable` | Column capped at `--prime-layout-reading-max-width` (~65ch), centred | Terms, articles, help pages | |
-| `wide` | Column capped at `--prime-layout-content-max-width`, centred | Wide screens where content should not stretch edge to edge | |
+| `readable` | Column capped at `--prime-layout-reading-max-width` (42rem), centred | Terms, articles, help pages | |
+| `wide` | Column capped at `--prime-layout-content-max-width` (75rem), centred | Wide screens where content should not stretch edge to edge | |
 
 ### measure (Description)
 | Value | Looks like | Use when | Default |
@@ -103,38 +143,62 @@ PageContent.Root | PageContent.Section     column; Root adds maxWidth, Section r
 
 One `PageContent.Title` (`<h1>`) per page; sub-sections inside Body use `title-s` / `title-m` headings (`h2`). One primary button in Actions, the rest `soft` / `ghost` neutral.
 
+### Flags
+| Flag | Looks like when on | Use when | Default |
+|---|---|---|---|
+| `fill` (Root) | the page is as high as main; the body takes what the header leaves; main keeps gutter-high air under it | a full-height table, board, chat or `PageContent.Split` in an `AppShell.Root fillViewport` | `false` |
+
+### Split layout
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| wide (from 48rem of the split's width) | list in a 16–20rem column, detail beside it, 24 apart; no back button | desktops, tablets in landscape | — |
+| narrow (below 48rem) | one pane: the list, or the open detail with `PageContent.BackButton` | phones, a narrow panel next to an open Sidebar | — |
+
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | capped column | `maxWidth` | `data-max-width="readable" \| "wide"` on Root (absent for `full`) |
+| filling | `fill` | `data-fill="true"` on Root; `AppShell.Main` drops its long bottom air for it |
 | full-width intro | `measure="full"` | `data-measure="full"` on Description |
 | with actions | `PageContent.Actions` child | `data-has-actions="true"` on Header |
+| detail open | `open` / `defaultOpen` on Split | `data-open="true"` on Split; narrow: the list is `display: none`, else the detail is |
+| pane swap | `open` changes on a narrow split | the pane that comes into view enters once (`enterMotion.enterBase`: base, opacity + a 4 px rise); focus moves into the detail, or back to the list control; a wide split moves nothing |
 
 ## Layout & spacing
 - No outer padding: edge gutters come from `AppShell.Main`.
-- Header → Body `--prime-space-8` (32); blocks inside Body `--prime-space-10` (40); Title → Description `--prime-space-2` (8); buttons in Actions `--prime-space-2`.
+- Header → Body `--prime-space-8` (32); blocks inside Body `--prime-space-10` (40); Title → Description `--prime-space-2` (8); buttons in Actions `--prime-space-2`; heading → Actions `--prime-space-6` (24) side by side, `--prime-space-4` (16) once they wrap below.
 - Header is a wrapping row: actions stay to the right of the title while the heading keeps half a reading measure, otherwise they wrap below it — no breakpoint needed, works from 320px.
 - Title and Description wrap long words (`overflow-wrap: anywhere`).
+- `fill` needs a main with a height: `AppShell.Root fillViewport` (main scrolls inside the panel). The body passes its free height on to a filling child — DataTable `scrollHeight="fill"`, Crossfade `fill`, `PageContent.Split`.
+- Split takes the free height of a filling page and lays itself out from its own width (container `prime-split`), never from the window: a split beside an open Sidebar may be narrow on a wide screen. Each pane is a column whose last child takes the free height — put a Card with its own `ScrollContainer` there, so the list and the thread scroll separately.
+- The detail pane is on screen all the time on a wide split: while nothing is chosen it shows a short hint («Выберите диалог»), never an empty card.
 
 ## Accessibility
 
 ### Keyboard
-No keyboard interaction.
+| Key | Action |
+|---|---|
+| `Enter` · `Space` | On `PageContent.BackButton`: back from the detail to the list; focus returns to the list control that opened it. |
 
 ### ARIA
 - Title is an `<h1>`; use one per page.
 - Give `PageContent.Section` an `aria-labelledby` that points at the Title `id` to name the region.
+- Name `PageContent.List` and `PageContent.Detail` with `aria-label`. On a narrow split opening the detail moves focus into it and going back returns focus to the list control; the hidden pane is `display: none`, out of Tab and the accessibility tree. The panes take focus from code only (`tabindex="-1"`, no ring).
+- `PageContent.BackButton` is named by `labels.back` and is shown only while the split shows one pane.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-No `labels`.
+| Key | Default | Used for |
+|---|---|---|
+| `back` | `"Назад к списку"` | Name of `PageContent.BackButton` (on `PageContent.Split`). |
 
 ## Examples
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A page in the main column: title, description and page actions, then the body blocks — `PageContent.Actions`. |
 | [variants.tsx](examples/variants.tsx) | The same page column at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. |
+| [list-detail.tsx](examples/list-detail.tsx) | A support inbox as list + detail on a full-height page: side by side on a wide panel, one pane at a time with a back button on a narrow one — `PageContent.Split`, `PageContent.BackButton`, `fill`. |
 | [narrow.tsx](examples/narrow.tsx) | In a phone-width column the page actions wrap under the heading instead of squeezing it. |
 
 ## Mistakes
@@ -142,7 +206,10 @@ No `labels`.
 - Actions placed outside Header → put `PageContent.Actions` inside `PageContent.Header` so it aligns with the title and wraps.
 - Several `PageContent.Title` on one page → one `<h1>`, sub-headings via Typography.
 - Margins between blocks in Body → Body already sets the 40 gap.
+- Computing a height from `100vh` minus the header for a full-height table or chat → `PageContent.Root fill` and a filling child.
+- A list + detail built with window media queries → `PageContent.Split` follows its own width.
+- Unmounting the detail content the moment the narrow split goes back → keep the last record until another is chosen (the pane leaves with it on screen).
 
 ## Related
-- **Built from:** —
-- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Card](../card/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md)
+- **Built from:** [Button](../button/COMPONENT.md) (`PageContent.BackButton`), Icon (`nav.chevronLeft`)
+- **See also:** [AppShell](../../layout/app-shell/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Card](../card/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [Drawer](../drawer/COMPONENT.md)

package/src/components/page-content/examples/examples.module.css

@@ -16,6 +16,60 @@
   gap: var(--prime-space-10);
 }
 
+/* list-detail: main of a viewport-high shell — a column of a fixed height the page fills. */
+.fillMain {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: calc(var(--prime-space-24) * 5);
+  padding: var(--prime-layout-gutter-m);
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-layer-current);
+}
+
+/* A pane's card: an optional header row, then the scrolling region takes the rest. */
+.paneCard {
+  display: flex;
+  flex-direction: column;
+}
+
+.threadHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-2);
+  padding: var(--prime-space-3) var(--prime-space-4);
+}
+
+.pane {
+  flex: 1 1 auto;
+  min-height: 0;
+}
+
+.dialogs,
+.messages {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-1);
+  margin: 0;
+  padding: var(--prime-space-2);
+  list-style: none;
+}
+
+.messages {
+  gap: var(--prime-space-3);
+  padding: var(--prime-space-2) var(--prime-space-4) var(--prime-space-4);
+}
+
+/* A dialog row: the name at the start, the unread count at the end. */
+.dialog {
+  justify-content: space-between;
+}
+
+.hint {
+  padding: var(--prime-space-2) var(--prime-space-4);
+}
+
 /* A phone-width main column (360px). */
 .narrow {
   width: min(100%, calc(var(--prime-space-24) * 3.75));

package/src/components/page-content/examples/list-detail.tsx

@@ -0,0 +1,114 @@
+/** A support inbox as list + detail on a full-height page: side by side on a wide panel, one pane at a time with a back button on a narrow one — `PageContent.Split`, `PageContent.BackButton`, `fill`. */
+import { Badge, Button, Card, PageContent, ScrollContainer, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Dialog = { id: string; client: string; unread: number; messages: string[] };
+
+const DIALOGS: Dialog[] = [
+  {
+    id: "granit",
+    client: "ООО «Гранит»",
+    unread: 2,
+    messages: [
+      "Счёт № 4821 пришёл без НДС.",
+      "Проверю реквизиты и вернусь.",
+      "Нужно провести до пятницы.",
+      "Исправили ставку, новый счёт № 4830 на почте.",
+    ],
+  },
+  {
+    id: "leto",
+    client: "ООО «Лето»",
+    unread: 0,
+    messages: ["Можно перенести доставку на среду?", "Да, перенесли на 15 октября."],
+  },
+  {
+    id: "kozlov",
+    client: "ИП Козлов",
+    unread: 1,
+    messages: ["Подключите, пожалуйста, ЭДО.", "Пришлите идентификатор в Диадоке."],
+  },
+];
+
+export default function PageContentListDetailExample() {
+  const [dialogId, setDialogId] = React.useState<string | null>(null);
+  // The last opened dialog stays in the detail while the narrow split goes back to the list.
+  const [shown, setShown] = React.useState<Dialog | null>(null);
+
+  const open = (dialog: Dialog) => {
+    setDialogId(dialog.id);
+    setShown(dialog);
+  };
+
+  return (
+    <div className={styles.fillMain}>
+      <PageContent.Root fill>
+        <PageContent.Header>
+          <PageContent.Title>Обращения</PageContent.Title>
+        </PageContent.Header>
+        <PageContent.Body>
+          <PageContent.Split
+            open={dialogId !== null}
+            onOpenChange={(next) => {
+              if (!next) setDialogId(null);
+            }}
+          >
+            <PageContent.List aria-label="Диалоги">
+              <Card.Root className={styles.paneCard}>
+                <ScrollContainer className={styles.pane}>
+                  <ul className={styles.dialogs}>
+                    {DIALOGS.map((dialog) => (
+                      <li key={dialog.id}>
+                        <Button.Root
+                          variant={dialog.id === dialogId ? "soft" : "ghost"}
+                          tone="neutral"
+                          fullWidth
+                          aria-current={dialog.id === dialogId ? "true" : undefined}
+                          className={styles.dialog}
+                          onClick={() => open(dialog)}
+                        >
+                          {dialog.client}
+                          {dialog.unread > 0 ? (
+                            <Badge.Root color="blue">{dialog.unread}</Badge.Root>
+                          ) : null}
+                        </Button.Root>
+                      </li>
+                    ))}
+                  </ul>
+                </ScrollContainer>
+              </Card.Root>
+            </PageContent.List>
+
+            <PageContent.Detail aria-label="Переписка">
+              <Card.Root className={styles.paneCard}>
+                <div className={styles.threadHeader}>
+                  <PageContent.BackButton />
+                  <Typography as="h2" variant="title-s">
+                    {shown?.client ?? "Выберите диалог"}
+                  </Typography>
+                </div>
+                <ScrollContainer anchor="end" className={styles.pane}>
+                  {shown ? (
+                    <ul className={styles.messages}>
+                      {shown.messages.map((text) => (
+                        <li key={text}>
+                          <Typography variant="body-m">{text}</Typography>
+                        </li>
+                      ))}
+                    </ul>
+                  ) : (
+                    <Typography variant="body-m" tone="muted" className={styles.hint}>
+                      Переписка откроется здесь.
+                    </Typography>
+                  )}
+                </ScrollContainer>
+              </Card.Root>
+            </PageContent.Detail>
+          </PageContent.Split>
+        </PageContent.Body>
+      </PageContent.Root>
+    </div>
+  );
+}

package/src/components/page-content/examples/variants.tsx

@@ -9,7 +9,7 @@ const WIDTHS = [
   {
     value: "readable",
     title: "Условия использования",
-    text: "Около 65 знаков в строке, по центру.",
+    text: "Не шире колонки для чтения, по центру.",
   },
 ] as const;
 

package/src/components/page-toolbar/COMPONENT.md

@@ -3,7 +3,7 @@
 **Category:** page
 **Kind:** layout
 
-> The panel at the top of a page — sections, filter and search, view options and the primary action — laid out from its own width: one row when wide, exactly two rows when narrow, every slot in a fixed place.
+> The panel at the top of a page — sections, filter and search, view options and the primary action — laid out from its own width: one row when wide, stacked rows when narrow, search and filter always first with the active filters under them.
 
 ## When to use
 - A list, registry or dashboard page whose top holds several of: sections with counts, a filter and search, a period or view switch, the primary action.
@@ -24,12 +24,11 @@ import { PageToolbar } from "prime-ui-kit";
 ## Anatomy
 ```
 PageToolbar.Root                 container: its own width picks the layout
+├─ PageToolbar.Tools             search + filter button: SmartFilter.Toolbar — always first
 ├─ PageToolbar.Sections          sections of the page: a fullWidth SegmentedControl with counts
-├─ PageToolbar.Tools             filter button + search: SmartFilter.Toolbar
 ├─ PageToolbar.View              period, table / cards, columns
 ├─ PageToolbar.Actions           the primary action (and its secondary twin, e.g. «Отменить»)
-├─ PageToolbar.Chips             active filters: SmartFilter.Chips, a row under the panel
-└─ break                         hidden line break of the two-row layout (rendered by Root)
+└─ PageToolbar.Chips             active filters: SmartFilter.Chips, a row right under the search
 ```
 
 ## API
@@ -37,28 +36,28 @@ PageToolbar.Root                 container: its own width picks the layout
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### PageToolbar.Root
-`ref` → `HTMLDivElement`. The page panel: lays its slots out from its own width — one row from a 56rem container, exactly two rows below it. Parts may be left out; JSX order is the Tab order.
+`ref` → `HTMLDivElement`. The page panel: one row from 56rem of its own width, stacked rows below. Any slot may be left out; JSX order is the Tab order — write Tools, Sections, View, Actions, Chips.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### PageToolbar.Sections
-`ref` → `HTMLDivElement`. Sections of the page — a `fullWidth` SegmentedControl with counts. Top row; sized by content when wide, stretches when narrow and scrolls inside when it does not fit.
+`ref` → `HTMLDivElement`. Sections of the page — a `fullWidth` SegmentedControl with counts; scrolls inside when it does not fit.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### PageToolbar.Tools
-`ref` → `HTMLDivElement`. Filter button and search (`SmartFilter.Toolbar`): the stretchy item of its row; gives way down to 18rem (the button and a 9rem search on one line), then the View wraps instead.
+`ref` → `HTMLDivElement`. Search and filter button (`SmartFilter.Toolbar`): always the first slot and the stretchy one, the Chips right under it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### PageToolbar.View
-`ref` → `HTMLDivElement`. How the data is shown: period, table / cards, columns. Sized by content next to the Tools; alone in its row it stretches and its controls share the row equally.
+`ref` → `HTMLDivElement`. How the data is shown: period, table / cards, columns. Sized by content when wide; its own full row when narrow, its controls sharing it equally.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -72,7 +71,7 @@ PageToolbar.Root                 container: its own width picks the layout
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### PageToolbar.Chips
-`ref` → `HTMLDivElement`. Active filters (`SmartFilter.Chips`) in their own row under the panel; the row takes no space while it is empty.
+`ref` → `HTMLDivElement`. Active filters (`SmartFilter.Chips`) in their own row right under the search and filter; the row takes no space while it is empty.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -84,23 +83,23 @@ PageToolbar has no variants: the layout follows the toolbar's width.
 ### Layout by width
 | Toolbar width | Looks like | Default |
 |---|---|---|
-| `≥ 56rem` | one row that never wraps: Sections (content width) · Tools (stretch, at least 18rem) · View (content width) · Actions; short of room the Sections shrink and scroll inside | |
-| `< 56rem` | two rows: Sections (stretch) + Actions on top; Tools (stretch) + View below | yes (mobile first) |
-| any | Chips in their own row under the panel, only while there are chips | |
+| `≥ 56rem` | one row that never wraps: Tools (stretch, at least 18rem — a 9rem search and the filter button on one line) · Sections (content width) · View (content width) · Actions; Chips under it; short of room the Tools give way first, then the Sections shrink and scroll inside | |
+| `< 56rem` | rows: Tools (stretch) + Actions; Chips; Sections (full row); View (full row) | yes (mobile first) |
+| any | Chips right under the search and filter, only while there are chips | |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| wide | container ≥ 56rem | one row, no wrapping, break hidden; Chips rendered under the bar |
-| narrow | container < 56rem | `order` moves Actions to the top row, the break forces the second row |
-| one row empty | a row has no slot | break hidden, no empty gap |
-| alone in a row | Sections without Actions, Tools without View, View without Tools | that slot stretches to the full row; the View's controls share it equally |
-| tight row | Tools would go under 18rem (the filter button and a 9rem search) | the View wraps whole onto its own row and stretches there; the tools stay one line |
+| wide | container ≥ 56rem | one flex row, no wrapping; Chips rendered under the bar |
+| narrow | container < 56rem | a grid of real rows only (`order` + grid columns): a missing slot makes no row, every row is 12 from the next |
+| no Tools | Sections without Tools | the Sections take the Tools' place: first and stretchy, beside the action |
+| alone in a row | Tools or Sections without Actions; View when narrow | that slot stretches to the full row; the View's controls share it equally |
 | no chips | `PageToolbar.Chips` empty (`SmartFilter.Chips` renders nothing) | the chips row takes no space |
 
 ## Layout & spacing
-- 12 between slots and between rows, 8 inside a slot. No padding or fill of its own: it sits at the top of `PageContent.Body` (or replaces `PageContent.Header` on dense pages that keep their `h1` in the shell).
-- One stretchy item per row: Sections on top, Tools below. The primary action is at the end of the top row at every width and never wraps down; with no sections it is still pushed to the end.
+- 8 inside a slot. No padding or fill of its own: it sits at the top of `PageContent.Body` (or replaces `PageContent.Header` on dense pages that keep their `h1` in the shell).
+- The order is fixed: search and filter first, then the sections, the view and the primary action; the active filters always sit right under the search and filter, never under the sections. The primary action is at the end of the top row at every width and never wraps down.
+- Every gap is one step: 12 between slots and between every pair of rows, at any width — no row is ever further from the next.
 - Sections take a `fullWidth` SegmentedControl: the toolbar decides when it stretches (content width when wide, the full row when narrow), its items tend to equal width and it scrolls inside itself when they do not fit.
 - All controls share one tier, so they share one height and wrapped rows stay level: leave `size` off the controls (default `m`); for a denser page wrap the toolbar in `<ControlSizeProvider value="s">`.
 - On a phone the primary action may drop its text and keep the icon with `aria-label`; never remove it.
@@ -113,7 +112,7 @@ No keyboard interaction.
 
 ### ARIA
 - A plain `<div>`: name it with `aria-label` when a page has more than one panel.
-- Slots move only visually (`order`); the Tab order is the JSX order. Write the slots in the reading order of the wide layout — Sections, Tools, View, Actions, Chips. In the narrow layout the action is shown before the tools but reached after them.
+- Slots move only visually (`order`); the Tab order is the JSX order. Write the slots in the reading order of the wide layout — Tools, Sections, View, Actions, Chips. In the narrow layout the action is shown beside the tools but reached after the view.
 - An icon-only primary action on a narrow page carries `aria-label`.
 
 ### Labels
@@ -124,10 +123,10 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | The panel of an orders page: sections with counts, filter and search, the period and the primary action in one row; active filters in a row under it — `PageToolbar.Sections`, `PageToolbar.Tools`, `PageToolbar.View`, `PageToolbar.Actions`, `PageToolbar.Chips`. |
+| [overview.tsx](examples/overview.tsx) | The panel of an orders page: search and filter, sections with counts, the period and the primary action in one row; active filters right under the search — `PageToolbar.Tools`, `PageToolbar.Sections`, `PageToolbar.View`, `PageToolbar.Actions`, `PageToolbar.Chips`. |
 | [without-search.tsx](examples/without-search.tsx) | A dashboard panel without search on a tablet-width column: the sections fill the top row, the period selector alone in the bottom row stretches to the full width — `PageToolbar.Sections`, `PageToolbar.View`. |
 | [save-changes.tsx](examples/save-changes.tsx) | A settings page: sections of the form on the left, the save action with the number of changes at the end of the top row — never a sticky bar at the bottom of a phone screen — `PageToolbar.Actions`. |
-| [narrow.tsx](examples/narrow.tsx) | A phone-width column: exactly two rows — sections and the primary action on top, filter, search and the period below; each row has one stretchy item — `PageToolbar.Root`. |
+| [narrow.tsx](examples/narrow.tsx) | A phone-width column: search, filter and the primary action on top, the active filters under them, then the sections and the period, every row 12 apart — `PageToolbar.Root`. |
 
 ## Mistakes
 - A hand-built flex row of tabs, search and buttons with `flex-wrap` → rows wrap «as they come», the action drifts down; use `PageToolbar`.

package/src/components/page-toolbar/examples/narrow.tsx

@@ -1,4 +1,4 @@
-/** A phone-width column: exactly two rows — sections and the primary action on top, filter, search and the period below; each row has one stretchy item — `PageToolbar.Root`. */
+/** A phone-width column: search, filter and the primary action on top, the active filters under them, then the sections and the period, every row 12 apart — `PageToolbar.Root`. */
 import {
   Button,
   Icon,
@@ -51,6 +51,9 @@ export default function PageToolbarNarrowExample() {
         onSearchChange={setSearch}
       >
         <PageToolbar.Root aria-label="Заказы">
+          <PageToolbar.Tools>
+            <SmartFilter.Toolbar />
+          </PageToolbar.Tools>
           <PageToolbar.Sections>
             <SegmentedControl.Root
               fullWidth
@@ -66,9 +69,6 @@ export default function PageToolbarNarrowExample() {
               ))}
             </SegmentedControl.Root>
           </PageToolbar.Sections>
-          <PageToolbar.Tools>
-            <SmartFilter.Toolbar />
-          </PageToolbar.Tools>
           <PageToolbar.View>
             <Select.Root value={period} onValueChange={setPeriod}>
               <Select.Trigger aria-label="Период">

package/src/components/page-toolbar/examples/overview.tsx

@@ -1,4 +1,4 @@
-/** The panel of an orders page: sections with counts, filter and search, the period and the primary action in one row; active filters in a row under it — `PageToolbar.Sections`, `PageToolbar.Tools`, `PageToolbar.View`, `PageToolbar.Actions`, `PageToolbar.Chips`. */
+/** The panel of an orders page: search and filter, sections with counts, the period and the primary action in one row; active filters right under the search — `PageToolbar.Tools`, `PageToolbar.Sections`, `PageToolbar.View`, `PageToolbar.Actions`, `PageToolbar.Chips`. */
 import {
   Button,
   Icon,
@@ -61,6 +61,9 @@ export default function PageToolbarOverviewExample() {
       onSearchChange={setSearch}
     >
       <PageToolbar.Root aria-label="Заказы">
+        <PageToolbar.Tools>
+          <SmartFilter.Toolbar />
+        </PageToolbar.Tools>
         <PageToolbar.Sections>
           <SegmentedControl.Root
             fullWidth
@@ -76,9 +79,6 @@ export default function PageToolbarOverviewExample() {
             ))}
           </SegmentedControl.Root>
         </PageToolbar.Sections>
-        <PageToolbar.Tools>
-          <SmartFilter.Toolbar />
-        </PageToolbar.Tools>
         <PageToolbar.View>
           <Select.Root value={period} onValueChange={setPeriod}>
             <Select.Trigger aria-label="Период">

package/src/components/pagination/COMPONENT.md

@@ -128,5 +128,5 @@ Pagination              <nav aria-label={labels.nav}>; size and compact mode
 - A pager under a DataTable → the table renders its own.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md)
+- **Built from:** [Button](../button/COMPONENT.md), Icon (`nav.chevronLeft`, `nav.chevronRight`)
 - **See also:** [DataTable](../data-table/COMPONENT.md), [Select](../select/COMPONENT.md), [Stepper](../stepper/COMPONENT.md)