prime-ui-kit 0.16.0 → 0.18.0

package/dist/layout/page/Page.d.ts

@@ -0,0 +1,302 @@
+import * as React from "react";
+export type PageLabels = {
+    /** Name of the menu button the top bar draws while the shell's Sidebar is off-canvas. */
+    menu: string;
+    /** Name of the «⋯» button the top bar's actions fold into when the row runs out of width. */
+    more: string;
+    /** Name of `Page.BackButton` (back from the detail to the list on a narrow split). */
+    back: string;
+    /** Title of the confirm `Page.Guard` opens when a person leaves a `dirty` page. */
+    leaveTitle: string;
+    /** Its description. */
+    leaveDescription: string;
+    /** Its confirm button: leave and lose the changes. */
+    leaveConfirm: string;
+    /** Its cancel button: stay on the page. */
+    leaveCancel: string;
+};
+export declare const PAGE_LABELS: PageLabels;
+type DivProps = React.HTMLAttributes<HTMLDivElement> & {
+    ref?: React.Ref<HTMLDivElement>;
+};
+/** Cap of the page column. */
+export type PageMaxWidth = "full" | "readable" | "wide";
+export type PageRootProps = DivProps & {
+    /**
+     * Cap of everything but the top bar, centred: `full` — the whole main; `readable` — 42rem (`--prime-layout-reading-max-width`); `wide` — 75rem (`--prime-layout-content-max-width`).
+     */
+    maxWidth?: PageMaxWidth;
+    /**
+     * The page takes the height of main (`AppShell.Root fillViewport`) and the body takes what the bar and the header leave: for a full-height table, board, chat or `Page.Split`.
+     */
+    fill?: boolean;
+    /**
+     * Built-in strings of every part, see Labels.
+     */
+    labels?: Partial<PageLabels>;
+};
+/**
+ * The page: the column inside `AppShell.Main` that holds the top bar, the header and the body. In
+ * the shell it takes the shell's gutters and top air (`--page-gutter`, `--page-top` from main);
+ * outside it brings none. `maxWidth` caps and centres everything but the top bar, which runs the
+ * width of the panel.
+ */
+declare function PageRoot({ maxWidth, fill, labels: labelsProp, className, ...rest }: PageRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageRoot {
+    var displayName: string;
+}
+export type PageTopBarProps = React.HTMLAttributes<HTMLElement> & {
+    /**
+     * Sticks to the top of the page's scroller (`AppShell.Main`); `false` — scrolls away with the page. On a screen lower than 480px it scrolls anyway.
+     */
+    sticky?: boolean;
+    /**
+     * Once the flow `Page.Title` scrolls out under the bar, the bar repeats it as the last level of its heading (of its `Breadcrumb` path, which folds for it), unless the path ends at it; it leaves when the title returns.
+     */
+    collapse?: boolean;
+    ref?: React.Ref<HTMLElement>;
+};
+/**
+ * The page's strip at its top edge, across the panel. Up to four groups in one grid —
+ * `Page.Heading`, `Page.Tools`, `Page.Actions` on the first line, `Page.Chips` under them — laid
+ * out by one plan chosen from their natural widths (`planBar`): one line while everything fits;
+ * then the tools take a line of their own; then the buttons give way to their icons, secondary
+ * first, and fold into «⋯»; only then does a heading with a path stack (path over title), and a
+ * heading without one truncate. Sticky inside the scroller of
+ * the page; while the shell's Sidebar is off-canvas it starts with the menu button. With
+ * `collapse` it repeats the flow `Page.Title` once that title scrolls out under the bar.
+ */
+declare function PageTopBar({ sticky, collapse, className, children, ref, ...rest }: PageTopBarProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageTopBar {
+    var displayName: string;
+}
+export type PageHeaderProps = DivProps;
+/**
+ * The document header in the page flow (settings, long forms, overviews): a `Page.Heading` and
+ * its `Page.Actions` in one row; the actions wrap under the heading on a narrow column. In a
+ * `Page.TopBar` the same parts stand directly in the bar.
+ */
+declare function PageHeader({ className, children, ...rest }: PageHeaderProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageHeader {
+    var displayName: string;
+}
+export type PageHeadingProps = DivProps;
+/**
+ * The title group: an optional `Breadcrumb` path, `Page.Title`, `Page.Description`. In the bar
+ * the title is the path's last level — the path, a chevron and the title on one line, the
+ * description under the whole line, both truncating; in the flow the path stands over a large
+ * title and the description wraps.
+ */
+declare function PageHeading({ className, children, ...rest }: PageHeadingProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageHeading {
+    var displayName: string;
+}
+export type PageTitleProps = React.HTMLAttributes<HTMLHeadingElement> & {
+    ref?: React.Ref<HTMLHeadingElement>;
+};
+/**
+ * The page's `<h1>`: the last level of the path in the top bar (it truncates), a large title in
+ * the flow. A flow title is what a `collapse` top bar repeats once it scrolls away.
+ */
+declare function PageTitle({ className, children, ref, ...rest }: PageTitleProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageTitle {
+    var displayName: string;
+}
+export type PageDescriptionProps = React.HTMLAttributes<HTMLParagraphElement> & {
+    /**
+     * Its data is loading: a Skeleton keeps the line's place, so the title never moves; the data then fades in. Sets `aria-busy`.
+     */
+    loading?: boolean;
+    ref?: React.Ref<HTMLParagraphElement>;
+};
+/** One line of context that carries data (a period, a count): truncates in the bar, wraps in the flow. */
+declare function PageDescription({ loading, className, children, ...rest }: PageDescriptionProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageDescription {
+    var displayName: string;
+}
+export type PageActionsProps = DivProps;
+/**
+ * The page's buttons: at the end of a `Page.Header` or a `Page.Section` heading in the flow (they
+ * wrap under it on a narrow column), on the first line of a `Page.TopBar` at every width. In the
+ * bar, when the line runs short, Buttons with an icon show only it — the secondary ones first,
+ * then the primary (the first solid Button) — with their label as name and tooltip; then the
+ * secondary Buttons fold into a «⋯» menu. Anything that is not a `Button.Root` stays as it is.
+ */
+declare function PageActions(props: PageActionsProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageActions {
+    var displayName: string;
+}
+export type PageToolsProps = DivProps;
+/**
+ * The page's tools — sections, search and filter, view — as kit controls in the order written.
+ * On the bar's first line each keeps its natural width; on a line of their own they fill it:
+ * a search (`SmartFilter.Toolbar`, `Input.Root`) takes the room first, switchers and fields share
+ * the rest (a `SegmentedControl.Root` and a `Datepicker.Root` are `fullWidth` unless set; a Select
+ * trigger fills by itself), and they wrap when one line is not enough. Named (`aria-label`), it is
+ * a `group`.
+ */
+declare function PageTools({ className, children, ref, ...rest }: PageToolsProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageTools {
+    var displayName: string;
+}
+export type PageChipsProps = DivProps;
+/** Active filters (`SmartFilter.Chips`) on a line of their own under the bar; gone while empty. */
+declare function PageChips({ className, ...rest }: PageChipsProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageChips {
+    var displayName: string;
+}
+export type PageBodyProps = DivProps;
+/** The page content: blocks of one screen 24 apart, a `Page.Section` 40 from its neighbours. */
+declare function PageBody({ className, ...rest }: PageBodyProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageBody {
+    var displayName: string;
+}
+/** Where the heading of a section stands: over its content or in a column beside it. */
+export type PageSectionLayout = "stack" | "aside";
+export type PageSectionProps = Omit<React.HTMLAttributes<HTMLElement>, "title"> & {
+    /**
+     * The visible heading (`h2`); it also names the section.
+     */
+    label: React.ReactNode;
+    /**
+     * One line of context under the heading, in secondary body-s.
+     */
+    description?: React.ReactNode;
+    /**
+     * `stack` — the heading over the content; `aside` — a ~16rem heading column beside it (a settings page), above it once the content would get narrower than 30rem.
+     */
+    layout?: PageSectionLayout;
+    ref?: React.Ref<HTMLElement>;
+};
+/**
+ * A titled section of the page: an `h2` heading (with an optional description and `Page.Actions`
+ * at its end) over its content. Sections stand further apart than the plain blocks of the body,
+ * so the air shows where a new topic starts.
+ */
+declare function PageSection({ label, description, layout, className, children, ...rest }: PageSectionProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageSection {
+    var displayName: string;
+}
+export type PageGridProps = DivProps;
+/**
+ * The grid of the page's tiles (KPI cards, charts, panels): 12 columns, one gap on both axes.
+ * Columns follow the grid's own width, so tiles fold on a narrow panel by themselves. A wide cell
+ * (span 7–11) written next to a narrow one (span 4–5) forms a pair that a mid-width grid lays out as
+ * 2/3 + 1/3, so the row keeps no hole.
+ */
+declare function PageGrid({ className, children, ...rest }: PageGridProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageGrid {
+    var displayName: string;
+}
+/** Columns of 12 a cell spans on a wide grid. */
+export type PageCellSpan = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/** Rows a cell spans. */
+export type PageCellRows = 1 | 2 | 3 | 4;
+export type PageCellProps = DivProps & {
+    /**
+     * Columns of 12 on a wide grid (64rem+). Narrower grids round it: see Grid columns in COMPONENT.md.
+     */
+    span?: PageCellSpan;
+    /**
+     * Rows the cell spans from 40rem: a chart beside two stacked tiles (`ChartFrame.Plot height="fill"` fills the height).
+     */
+    rows?: PageCellRows;
+};
+/**
+ * One tile place in `Page.Grid`; its child (a Card, a ChartFrame) fills it. A `Crossfade` child
+ * fills it too (`fill` unless set), so a tile that swaps its states keeps the row's height.
+ */
+declare function PageCell({ span, rows, className, children, ...rest }: PageCellProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageCell {
+    var displayName: string;
+}
+export type PageGuardProps = {
+    /**
+     * A request runs (a save): a press on those items does nothing until it ends; the browser asks before the tab closes.
+     */
+    busy?: boolean;
+    /**
+     * Changes are not saved: a press on those items asks «leave without saving?»; its confirm (`labels.leaveConfirm`) repeats the press, its cancel keeps the page. The browser asks before the tab closes.
+     */
+    dirty?: boolean;
+};
+/**
+ * Holds the page from where its form state lives: put it anywhere inside the page. While it holds,
+ * a press on a `Sidebar.Item`, a `BottomNav.Item` or a `Breadcrumb.Item` link stops before it
+ * navigates — `busy` holds it, `dirty` asks «leave without saving?» and replays the press once the
+ * person agrees — and the browser asks before the tab closes or reloads. Renders only the confirm.
+ */
+declare function PageGuard({ busy, dirty }: PageGuardProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageGuard {
+    var displayName: string;
+}
+export type PageSplitProps = DivProps & {
+    /**
+     * 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.
+     */
+    open?: boolean;
+    /**
+     * Initial open state, uncontrolled.
+     */
+    defaultOpen?: boolean;
+    /**
+     * `Page.BackButton` closes the detail (`false`); clear the chosen record there.
+     */
+    onOpenChange?: (open: boolean) => void;
+};
+/**
+ * List + detail (mail, a messenger, a ticket queue): two panes side by side from 48rem of its own
+ * width, one at a time below it — the list, or the open detail with a back button. Takes the free
+ * height of a filling page; each pane gives its last child the free height.
+ */
+declare function PageSplit({ open: openProp, defaultOpen, onOpenChange, className, children, ...rest }: PageSplitProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageSplit {
+    var displayName: string;
+}
+export type PageListProps = DivProps;
+/**
+ * The list pane of the split: a fixed column on a wide split, the whole split while the detail is
+ * closed. It remembers the control that had focus, so going back returns there.
+ */
+declare function PageList(props: PageListProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageList {
+    var displayName: string;
+}
+export type PageDetailProps = DivProps;
+/** The detail pane of the split: the rest of a wide split; on a narrow one it replaces the list while open. */
+declare function PageDetail(props: PageDetailProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageDetail {
+    var displayName: string;
+}
+export type PageBackButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> & {
+    ref?: React.Ref<HTMLButtonElement>;
+};
+/**
+ * Back from the detail to the list: a soft neutral icon Button named by `labels.back`, shown only
+ * while the split shows one pane. Put it at the start of the detail's header.
+ */
+declare function PageBackButton({ className, onClick, ...rest }: PageBackButtonProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageBackButton {
+    var displayName: string;
+}
+export declare const Page: {
+    Root: typeof PageRoot;
+    TopBar: typeof PageTopBar;
+    Header: typeof PageHeader;
+    Heading: typeof PageHeading;
+    Title: typeof PageTitle;
+    Description: typeof PageDescription;
+    Actions: typeof PageActions;
+    Tools: typeof PageTools;
+    Chips: typeof PageChips;
+    Body: typeof PageBody;
+    Section: typeof PageSection;
+    Grid: typeof PageGrid;
+    Cell: typeof PageCell;
+    Guard: typeof PageGuard;
+    Split: typeof PageSplit;
+    List: typeof PageList;
+    Detail: typeof PageDetail;
+    BackButton: typeof PageBackButton;
+};
+export {};

package/dist/layout/sidebar/Sidebar.d.ts

@@ -61,7 +61,7 @@ export type SidebarRootProps = React.ComponentPropsWithoutRef<"div"> & {
      */
     defaultOpen?: boolean;
     /**
-     * Off-canvas open / close: Toggle, the AppHeader menu button, scrim, Escape, an activated item, leaving the narrow viewport.
+     * Off-canvas open / close: Toggle, the menu button of `Page.TopBar`, scrim, Escape, an activated item, leaving the narrow viewport.
      */
     onOpenChange?: (open: boolean) => void;
     /**

package/dist/skill/SKILL.md

@@ -32,8 +32,8 @@ region, `Skeleton` while it loads).
    the main action, the states, the narrow screen); the shape of the data decides the layout, every
    label must carry something new, friction matches the cost of a mistake.
 2. **The app frame, once per app** — [layouts.md](layouts.md): styles, theme, providers, `AppShell`
-   with the `Sidebar`, page wrappers, auth screens. A screen you deliver renders its page: its
-   `AppHeader.Root` (title, a line of data, its tools) and its body.
+   with the `Sidebar`, page wrappers, auth screens. A screen you deliver renders its page: one
+   `Page.Root` with its top bar (title, a line of data, its tools) and its body.
 3. **Choose** — [choosing.md](choosing.md): the category by task, then the component, then the pairs
    that are easy to confuse.
 4. **Read the component** — [components.md](components.md) links each `COMPONENT.md` (API, variants,
@@ -48,8 +48,8 @@ region, `Skeleton` while it loads).
    icon names.
 7. **States and motion** — [motion.md](motion.md): every region loads, empties and fails without
    flipping; what the kit animates by itself and when to move your own elements.
-8. **Narrow screens** — [responsive.md](responsive.md): every screen works from 320px, the page panel is
-   `PageToolbar`, nothing is hidden on phones, touch follows `(hover)` / `(pointer)`.
+8. **Narrow screens** — [responsive.md](responsive.md): every screen works from 320px, the page's top bar
+   gives way by width itself, nothing is hidden on phones, touch follows `(hover)` / `(pointer)`.
 9. **Check** — [checklist.md](checklist.md) and [anti-slop.md](anti-slop.md), then look at the screen
    in a browser ([ux.md](ux.md#9-look-at-it-before-handing-it-over)). Fix every «no», then hand
    over.
@@ -65,7 +65,7 @@ project under `node_modules/prime-ui-kit/src/`.
 |---|---|---|
 | Component reference | `reference/components/<dir>/COMPONENT.md` | `node_modules/prime-ui-kit/src/components/<dir>/COMPONENT.md` |
 | Copyable scenarios | `reference/components/<dir>/examples/*.tsx` | `node_modules/prime-ui-kit/src/components/<dir>/examples/*.tsx` |
-| AppShell, Sidebar, AppHeader, BottomNav | `reference/layout/<dir>/…` | `node_modules/prime-ui-kit/src/layout/<dir>/…` |
+| AppShell, Sidebar, BottomNav, Page | `reference/layout/<dir>/…` | `node_modules/prime-ui-kit/src/layout/<dir>/…` |
 | Whole screens | `reference/<base>/<dir>/examples/screen.tsx` | `node_modules/prime-ui-kit/src/<base>/<dir>/examples/screen.tsx` |
 
 ## Files of this skill
@@ -81,7 +81,7 @@ project under `node_modules/prime-ui-kit/src/`.
 | [foundations.md](foundations.md) | grid, proximity scale, sizes, surfaces, type, tone and color |
 | [api-contract.md](api-contract.md) | writing JSX — prop names, sizes and host tiers, controlled state, forms, helpers, icons |
 | [motion.md](motion.md) | every screen — loading / empty / error that flow, what the kit animates, when to move, recipes |
-| [responsive.md](responsive.md) | every screen — 320px and up, the page panel (`PageToolbar`), touch |
+| [responsive.md](responsive.md) | every screen — 320px and up, the page's top bar (`Page.TopBar`), touch |
 | [anti-slop.md](anti-slop.md) | before and after writing — what makes a screen look generated |
 | [checklist.md](checklist.md) | before handing the screen over |
 
@@ -97,8 +97,8 @@ applyTheme("light"); // sets data-theme on <html>; "dark" for the dark theme
 ```
 
 Wrap the app in `NotificationProvider` if it shows toasts. Styles, `applyTheme`, `NotificationProvider`
-and `AppShell` belong to the app root, once. A screen component you deliver renders its page — its
-`AppHeader.Root` and its `PageContent` body — and assumes the root exists. If the project has no app
+and `AppShell` belong to the app root, once. A screen component you deliver renders its page — one
+`Page.Root` with its `Page.TopBar` and its `Page.Body` — and assumes the root exists. If the project has no app
 frame yet, also deliver it as a separate root layout from
 [layouts.md](layouts.md#app-frame-once-per-app) — never inline the frame into a page.
 
@@ -123,8 +123,8 @@ Take a semantic `<Icon name="…" />` first, else a glyph from the full animated
 7. Labels above fields, always — once per column for records in rows (`FieldList`), never numbered
    («Пункт 1»), never repeating their heading. Placeholder is an example value, never the label.
 8. Text through `Typography` roles (`title-m` section, `title-s` group, `body-m` text, `caption` meta;
-   the page title is `AppHeader.Title` in the page's header, `PageContent.Title` only on a
-   document page). No custom font sizes.
+   the page title is `Page.Title`, one per page: in the `Page.Heading` of `Page.TopBar` on a work screen, in the flow
+   on a document page or an overview). No custom font sizes.
 9. Overlays (Modal, ConfirmDialog, Drawer, Sheet, Popover, Dropdown, Tooltip, CommandMenu, Select,
    MediaViewer) come from the kit — never hand-made — and stay mounted: drive them with `open`,
    never `{open && …}`.

package/dist/skill/anti-slop.md

@@ -55,13 +55,13 @@ Text colour is not CSS: [foundations.md → Text colour](foundations.md#text-col
 ```tsx good
 // good — DataTable already is a filled block; a titled section is enough
 // declare: const payments: { id: string; client: string }[]
-<PageContent.Section label="Последние оплаты">
+<Page.Section label="Последние оплаты">
   <DataTable
     columns={[{ id: "client", header: "Клиент", accessor: "client" }]}
     rows={payments}
     getRowKey={(row) => row.id}
   />
-</PageContent.Section>
+</Page.Section>
 ```
 
 ## 3a. Hover that merges with the neighbour
@@ -225,7 +225,7 @@ The same for one value in several units — one heading, the fields in a row, th
 /* good — proximity scale */
 .form { display: grid; gap: var(--prime-space-8); }   /* group → group 32 */
 .group { display: grid; gap: var(--prime-space-5); }  /* field → field 20 */
-/* block → block 24 and section → section 40 come from PageContent.Body / PageContent.Section */
+/* block → block 24 and section → section 40 come from Page.Body / Page.Section */
 ```
 
 ## 7. `div` instead of a ready component
@@ -242,7 +242,7 @@ The same for one value in several units — one heading, the fields in a row, th
 | `<Button.Root onClick={() => location.assign(url)}>` | `<Button.Root asChild><a href={url}>…</a></Button.Root>` or `LinkButton` |
 | a hand-built spinner, shimmer, grey placeholder box or «Loading…» text | `loading` on Button / Select / DataTable; a region: `Skeleton` of its content inside `Crossfade`; no shape to hold: `Spinner` |
 | `{loading ? <Spinner /> : <List />}` — a state that flips | `<Crossfade state={status}>` around the region, `Skeleton` while loading |
-| a search Input + a row of filter Selects above a table | `SmartFilter` in the page's `PageToolbar` ([where the filters go](composition.md#where-the-filters-go)) |
+| a search Input + a row of filter Selects above a table | `SmartFilter` in the page's top bar: its toolbar in `Page.Tools`, its chips in `Page.Chips` ([where the filters go](composition.md#where-the-filters-go)) |
 | a grid of «label: value» text pairs for one record | `DescriptionList.Root` + `DescriptionList.Item` |
 | a Modal hand-built as «Удалить?» with your own pending flag | `ConfirmDialog.Root` with an async `onConfirm` |
 | a `<fieldset>` reset by hand, or `disabled` on every field while saving | `<Fieldset label disabled={saving}>` |
@@ -251,10 +251,15 @@ The same for one value in several units — one heading, the fields in a row, th
 | bars of dates drawn by hand, or a DataTable of start / end dates | `Gantt` |
 | a hand-made `<span>` hidden with CSS for screen readers | `<VisuallyHidden>` |
 | a `div` with `overflow: auto` | `ScrollContainer` (`edges`, `scrollbar="hidden"`, `snap`) |
+| `scroll-snap-type` on a strip of cards | `ScrollContainer snap` (`"mandatory"` only where each child fills most of the view) |
+| a flex row of Badges with its own gap | `Badge.Group` |
+| a Switch or a ⋯ button inside a list row, or the row rebuilt as a `div` to hold them | `List.ItemActions` beside the row's element |
+| a heading row (`Typography as="h3"` + buttons) over a group in a Drawer or a Modal | `Drawer.Section label` / `Modal.Section label` with `Drawer.Actions` / `Modal.Actions` |
+| Markdown turned into HTML (`dangerouslySetInnerHTML`, a Markdown library) | `RichText` |
 | an `<img>` with your own radius and loading box | `Thumbnail.Root` / `Avatar.Root` |
 | a lightbox, or a Modal with an `<img>` | `Gallery` (opens `MediaViewer` itself) or `MediaViewer` |
 | a `position: fixed` bottom tab bar | `BottomNav` in `AppShell.Footer` |
-| a menu state and a menu button wired by hand to open the phone Sidebar | nothing: the `AppHeader` draws the menu button; another trigger reads `useAppShellNav()` ([the app frame](layouts.md#app-frame-once-per-app)) |
+| a menu state and a menu button wired by hand to open the phone Sidebar | nothing: the page's `Page.TopBar` draws the menu button; another trigger reads `useAppShellNav()` ([the app frame](layouts.md#app-frame-once-per-app)) |
 | a bottom panel built from a Drawer or a `div` | `Sheet` |
 
 ## 7a. Fighting the table
@@ -287,6 +292,102 @@ The same for one value in several units — one heading, the fields in a row, th
 />
 ```
 
+## 7b. A top bar out of its groups
+
+The bar lays itself out only from its four groups ([the top bar](composition.md#the-top-bar)); a
+bar assembled any other way cannot give way on a narrow panel.
+
+The title as a row of its own under the path:
+
+```tsx partial
+// bad — the path, then the title on a second line; the path repeats the title
+<Page.Heading>
+  <Breadcrumb.Root>
+    <Breadcrumb.Item href="/invoices">Счета</Breadcrumb.Item>
+    <Breadcrumb.Item current>Счёт № 1042</Breadcrumb.Item>
+  </Breadcrumb.Root>
+</Page.Heading>
+<Typography as="h1" variant="heading-m">Счёт № 1042</Typography>
+```
+
+```tsx good
+// good — the path ends in the title: the levels above, then Page.Title, on one line
+<Page.TopBar>
+  <Page.Heading>
+    <Breadcrumb.Root>
+      <Breadcrumb.Item href="/invoices">Счета</Breadcrumb.Item>
+    </Breadcrumb.Root>
+    <Page.Title>Счёт № 1042</Page.Title>
+    <Page.Description>Отправлен · оплатить до 14 октября</Page.Description>
+  </Page.Heading>
+</Page.TopBar>
+```
+
+Buttons in two places, buttons with only text:
+
+```tsx partial
+// bad — export beside the title, the primary among the tools; no icons, so nothing can collapse
+<Page.Heading>
+  <Page.Title>Заказы</Page.Title>
+  <Button.Root variant="soft" tone="neutral">Экспорт</Button.Root>
+</Page.Heading>
+<Page.Tools aria-label="Заказы">
+  <SmartFilter.Toolbar />
+  <Button.Root>Новый заказ</Button.Root>
+</Page.Tools>
+```
+
+```tsx good
+// good — every button in one Page.Actions, each with an icon, the primary last
+<Page.Actions>
+  <Button.Root variant="soft" tone="neutral">
+    <Button.Icon>
+      <Icon name="action.download" />
+    </Button.Icon>
+    Экспорт
+  </Button.Root>
+  <Button.Root>
+    <Button.Icon>
+      <Icon name="action.add" />
+    </Button.Icon>
+    Новый заказ
+  </Button.Root>
+</Page.Actions>
+```
+
+`SmartFilter.Root` inside the bar:
+
+```tsx partial
+// bad — the filter's state wraps one group, its chips land outside it
+<Page.TopBar>
+  <SmartFilter.Root fields={FIELDS}>
+    <Page.Tools aria-label="Заказы">
+      <SmartFilter.Toolbar />
+    </Page.Tools>
+  </SmartFilter.Root>
+</Page.TopBar>
+```
+
+```tsx good
+// good — SmartFilter.Root draws nothing and wraps the page; toolbar and chips sit in their groups
+// declare: const FIELDS: Parameters<typeof SmartFilter.Root>[0]["fields"]
+<SmartFilter.Root fields={FIELDS}>
+  <Page.Root>
+    <Page.TopBar>
+      <Page.Heading>
+        <Page.Title>Заказы</Page.Title>
+      </Page.Heading>
+      <Page.Tools aria-label="Заказы">
+        <SmartFilter.Toolbar />
+      </Page.Tools>
+      <Page.Chips>
+        <SmartFilter.Chips />
+      </Page.Chips>
+    </Page.TopBar>
+  </Page.Root>
+</SmartFilter.Root>
+```
+
 ## 8. Decoration and filler
 
 - No emoji in UI. No icon next to every label — an icon earns its place when it speeds recognition

package/dist/skill/api-contract.md

@@ -25,14 +25,14 @@ import type { ControlSize, PaletteColor, TextTone, Tone, Variant } from "prime-u
 | Text value | native `value` / `onChange` + `onValueChange(string)` | Input (`Input.Field`), Textarea. |
 | Other state | `x` / `defaultX` / `onXChange(x)` | Badge `pressed`; Button `pressed`; ChartFrame `hiddenSeries`; Chat `selected`, `search`; ChatList `search`; ColorPicker `format`; CommandMenu `search`; Composer `recordMode`; DataTable `hiddenColumns`, `page`, `sort`, `selected`, `expanded`, `collapsedGroups`; ExampleFrame `viewport`, `colorScheme`; Gallery `index`; Gantt `scale`; Kanban `columnOrder`; MediaViewer `index`; Message.Media `index`; Select `search`; SmartFilter `search`; VideoNote `playing`, `transcriptExpanded`; VoicePlayer `rate`, `playing`, `transcriptExpanded`; Sidebar `mode`. |
 | Checked | `checked` / `defaultChecked` / `onCheckedChange(checked)` | Checkbox, Dropdown.CheckboxItem, Switch, Thumbnail. |
-| Open | `open` / `defaultOpen` / `onOpenChange(open)` | ColorPresets, CommandMenu, ConfirmDialog, Datepicker, Drawer, Dropdown, Gallery, MediaViewer, Message.Media, Modal, PageContent.Split, Popover, Select, Sheet, TagSelect, Tooltip, Sidebar, Sidebar.Group, Sidebar.Sub. |
-| Dismiss | `closeOnOutsideClick` (default `true`), `closeOnEscape` (default `true`) | Both on every overlay that opens a layer: the dialogs, the floating panels, the panels of Select, TagSelect, Datepicker and ColorPresets, the off-canvas Sidebar and the reaction bar of a message. `ConfirmDialog` takes both with `closeOnOutsideClick` default `false` (Escape is held while `onConfirm` runs). Tooltip and Notification take neither. A form holds closing with `Modal.Guard` / `Drawer.Guard` / `Sheet.Guard`. |
+| Open | `open` / `defaultOpen` / `onOpenChange(open)` | ColorPresets, CommandMenu, ConfirmDialog, Datepicker, Drawer, Dropdown, Gallery, MediaViewer, Message.Media, Modal, Popover, Select, Sheet, TagSelect, Tooltip, Page.Split, Sidebar, Sidebar.Group, Sidebar.Sub. |
+| Dismiss | `closeOnOutsideClick` (default `true`), `closeOnEscape` (default `true`) | Both on every overlay that opens a layer: the dialogs, the floating panels, the panels of Select, TagSelect, Datepicker and ColorPresets, the `suggestions` list of Input, the off-canvas Sidebar and the reaction bar of a message. `ConfirmDialog` takes both with `closeOnOutsideClick` default `false` (Escape is held while `onConfirm` runs). Tooltip and Notification take neither. A form holds closing with `Modal.Guard` / `Drawer.Guard` / `Sheet.Guard`. |
 | Selection mode | `multiple` | One vs many (Select, Accordion) — never `type`. `mode` only for structurally different values (Datepicker `single \| range`). |
 | Status words | `selected`, `current`, `pressed` | `current` marks a navigation location (`Sidebar.Item`, `Breadcrumb.Item`) and sets `aria-current`; `pressed` a toggle button. |
 | Flags | `disabled`, `readOnly`, `required`, `optional`, `loading`, `fullWidth` | Same names everywhere. |
 | Focus ring | `focusRing` (default `true`) | Fields only; `false` only where focus is obvious otherwise. |
 | System strings | `labels?: Partial<XLabels>` | aria labels, counters, default texts; Russian defaults; values as `{token}` templates. Visible content goes in children or props. |
-| Structure | `X.Root` + `X.Part` | Only for components with parts. Leaves are single exports: `Typography`, `Kbd`, `Divider`, `Spinner`, `Skeleton`, `Crossfade`, `LinkButton`, `NativeSelect`, `DigitInput`, `Slider`, `TagSelect`, `ColorSwatches`, `CodeBlock`, `ProgressBar`, `ProgressCircle`, `Sparkline`, `Pagination`, `DataTable`, `Gantt`, `Fieldset`, `VisuallyHidden`, `ColorField`, `ExampleFrame`, `VoicePlayer`, `VideoNote`, `ScrollContainer`, `Gallery`, `MediaViewer`. This is the one list; other files link here. A group of roots is `X.Group` (`Radio.Group`, `Avatar.Group`). |
+| Structure | `X.Root` + `X.Part` | Only for components with parts. Leaves are single exports: `Typography`, `Kbd`, `Divider`, `Spinner`, `Skeleton`, `Crossfade`, `LinkButton`, `NativeSelect`, `DigitInput`, `Slider`, `TagSelect`, `ColorSwatches`, `CodeBlock`, `ProgressBar`, `ProgressCircle`, `Sparkline`, `Pagination`, `DataTable`, `Gantt`, `Fieldset`, `VisuallyHidden`, `ColorField`, `ExampleFrame`, `VoicePlayer`, `VideoNote`, `ScrollContainer`, `Gallery`, `MediaViewer`, `RichText`. This is the one list; other files link here. A group of roots is `X.Group` (`Radio.Group`, `Avatar.Group`, `Badge.Group`). |
 | Slots | `X.Trigger`, `X.Close`, `X.Confirm`, `X.Anchor` | Your own button inside, exactly one element child; the slot renders no element and takes no `className` — style the child. A trigger the kit draws itself (`Select.Trigger`, `Accordion.Trigger`) is a real part with `className`. |
 | Icons in parts | `X.Icon`, `X.ItemIcon` | `Button.Icon`, `Input.Icon`, `Sidebar.ItemIcon`, `Dropdown.ItemIcon`… — never an `icon` prop on a component. Only data arrays (`notify()`, `options`) carry `icon: ReactNode`. |
 | DOM state | `data-size`, `data-variant`, `data-tone`, `data-color`, `data-invalid`, `data-disabled`, `data-loading`, `data-state` | Style your wrappers from these, not from class names of kit internals. |
@@ -85,7 +85,7 @@ export function PeriodFilter() {
   resolving. The async events: Input / Textarea `onCommit`, ConfirmDialog `onConfirm`,
   `EmptyPage.RetryButton` and CommandMenu `onRetry`, Button `onConfirm` (`holdToConfirm`), Slider
   `onCommit`, DigitInput `onComplete`, Tabs `onRemove`, Switch `onCheckedChange`, Badge `onRemove`,
-  FileUpload `onValueChange`, TagSelect `onCreate` / `onOptionUpdate` / `onOptionDelete`, DataTable
+  FileUpload and FieldList `onValueChange`, TagSelect `onCreate` / `onOptionUpdate` / `onOptionDelete`, DataTable
   and Dnd `onReorder`, Kanban `onValueChange` / `onColumnOrderChange`, Gantt `onBarChange` /
   `onBarCreate`, Composer `onSend` / `onSendVoice` / `onSendVideoNote`, `Message.Root`
   `onReactionToggle` and `onRetry`, the `onRetry` / `onCancel` of `Message.File`, the
@@ -118,8 +118,11 @@ export function PeriodFilter() {
 - Checkbox, Switch and Radio: [choice controls](#choice-controls) below.
 - `required` → red `*` after the label + native `required`. `optional` → muted «необязательно».
 - Placeholder is an example (`name@company.ru`), never the label.
-- Units and prefixes in affixes are hidden from screen readers — put the meaning into the label or hint
-  too («Бюджет, ₽», «Адрес: prime.app/p/…»).
+- `hintTone` (`success` · `warning` · `danger`) colors the `hint` of a field by the status of its
+  value («Осталось 12 дней» in `warning`); a lone `Hint.Root` takes `tone`. The words carry the
+  status and the color only repeats it; a validation problem is `error`, which replaces the hint.
+- `Input.Affix` and `Input.InlineAffix` describe the input for screen readers (`aria-describedby`),
+  so the label never repeats a unit or a prefix ([a unit lives in one place](ux.md#3-label-economy)).
 - Mark the minority: when most fields are required, mark only the optional ones (`optional`); when most
   are optional, mark the required ones; on a tie mark the required ones. Validate in code either way.
 - Show `error` after the user leaves the field or on submit, not while typing the first character.
@@ -249,7 +252,8 @@ place (a `Banner` for the page; for a region `EmptyPage tone="danger"` — it an
   фильтры»), and the same action keeps the same variant in the header, toolbars and menus. If «Отмена»
   would clash with the action itself («Отменить заказ»), use an unambiguous label («Не отменять»).
 - A control that navigates is a link: `LinkButton href`, `Button.Root asChild` with `<a>` / router
-  `Link`, `Sidebar.Item href` or `asChild`. Never `onClick={() => location.assign(…)}`.
+  `Link`, `Sidebar.Item` / `Breadcrumb.Item` / `List.Item` / `ChatList.Item` `href` or `asChild`. Never
+  `onClick={() => location.assign(…)}`.
 
 ## Destructive actions
 
@@ -291,7 +295,10 @@ export function DeleteProject({ onDelete }: { onDelete: () => Promise<void> }) {
 
 Leaving a form with unsaved changes is the same contract: `Modal.Guard` / `Drawer.Guard` inside the
 content with `dirty` (any dismiss asks «Не сохранять изменения?») and `busy` (nothing closes it while
-it saves).
+it saves). A form that is the whole page takes `Page.Guard` (`dirty`, `busy`) inside the page: it
+holds a press on `Sidebar.Item`, `BottomNav.Item` and `Breadcrumb.Item` links — router links
+included — and the browser's own close or reload; never a `beforeunload` or a ConfirmDialog on a
+crumb of your own.
 
 ## Providers and helpers