prime-ui-kit 0.16.0 → 0.18.0

package/src/components/slider/examples/controlled.tsx

@@ -24,7 +24,7 @@ export default function SliderControlledExample() {
             type="number"
             min={0}
             max={MAX_DISCOUNT}
-            aria-label="Скидка для клиента, %"
+            aria-label="Скидка для клиента"
             value={discount}
             onValueChange={(text) => {
               const next = Number(text);

package/src/components/slider/examples/states.tsx

@@ -3,19 +3,23 @@ import { Slider } from "prime-ui-kit";
 
 export default function SliderStatesExample() {
   return (
-    <div>
+    <>
       <div>
-        <Slider label="min" showValue defaultValue={0} />
+        <div>
+          <Slider label="min" showValue defaultValue={0} />
+        </div>
+        <div>
+          <Slider label="max" showValue defaultValue={100} />
+        </div>
       </div>
       <div>
-        <Slider label="max" showValue defaultValue={100} />
+        <div>
+          <Slider label="invalid" showValue defaultValue={90} invalid />
+        </div>
+        <div>
+          <Slider label="disabled" showValue defaultValue={35} disabled />
+        </div>
       </div>
-      <div>
-        <Slider label="invalid" showValue defaultValue={90} invalid />
-      </div>
-      <div>
-        <Slider label="disabled" showValue defaultValue={35} disabled />
-      </div>
-    </div>
+    </>
   );
 }

package/src/components/smart-filter/COMPONENT.md

@@ -13,10 +13,10 @@
 - An API that takes one value per field (`multiple: false`), a screen whose text search lives elsewhere (`searchable={false}`), values of different kinds in one field (`group`).
 
 ## When not to use
-- One field with a few options → use [SegmentedControl](../segmented-control/COMPONENT.md), [Select](../select/COMPONENT.md) or [TagSelect](../tag-select/COMPONENT.md) in the toolbar.
+- One field with a few options → use [SegmentedControl](../segmented-control/COMPONENT.md), [Select](../select/COMPONENT.md) or [TagSelect](../tag-select/COMPONENT.md) in the page's `Page.Tools`.
 - A search outside a table or list page (inside a picker, a settings section, a panel) → [Input](../input/COMPONENT.md) with a search icon. Over a table or list page the search is SmartFilter even with no fields yet (`fields={[]}`): it grows into filters without a rebuild.
 - Choosing values for a form field → use [TagSelect](../tag-select/COMPONENT.md).
-- One period that drives a whole dashboard → [Datepicker](../datepicker/COMPONENT.md) in the page toolbar; SmartFilter ranges filter rows of a list.
+- One period that drives a whole dashboard → [Datepicker](../datepicker/COMPONENT.md) in the page's `Page.Tools`; SmartFilter ranges filter rows of a list.
 
 ## Import
 ```tsx
@@ -30,7 +30,7 @@ import {
 
 ## Anatomy
 ```
-SmartFilter.Root                  state + context (flex column)
+SmartFilter.Root                  state + context, no DOM
 ├─ SmartFilter.Toolbar            [search Input (searchable)] [filter Button (count Badge)] — the anchor of the panel
 │  └─ panel                       flush Popover as wide as the toolbar; sections split by Dividers
 │     ├─ query row                ghost Button «Искать «text»» + Kbd ↵, while typing
@@ -41,14 +41,14 @@ SmartFilter.Root                  state + context (flex column)
 │     └─ footer                   hint · count · Reset Button
 └─ SmartFilter.Chips              applied filters as removable Badges · add / clear all Buttons
 ```
-The toolbar and the chips are separate parts so a page can put them in different places; both only need to be inside `Root`.
+The toolbar and the chips are separate parts so a page can put them in different places; both only need to be inside `Root`, which draws nothing of its own.
 
 ## API
 
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### SmartFilter.Root
-`ref` → `HTMLDivElement`. A `<div>` (flex column) with the state and the context; sets `data-size`.
+No DOM, no ref. The value, the search and the panel state shared by its parts; the host places the parts.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -62,11 +62,10 @@ The toolbar and the chips are separate parts so a page can put them in different
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the filter button, the search, the tags and the panel. Without it the tier of its host, else `m`. |
 | `collapsedLimit` | `number` | `12` | Values of one field shown before «Ещё N» (not while searching). |
 | `labels` | `Partial<SmartFilterLabels>` | — | Built-in strings, see Labels. |
-| `children` | `ReactNode` | — (required) | `SmartFilter.Toolbar` and `SmartFilter.Chips`, anywhere inside. |
-| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue" \| "onChange">` | — | `className` and the other div attributes. |
+| `children` | `ReactNode` | — (required) | `SmartFilter.Toolbar` and `SmartFilter.Chips`, anywhere inside — in a page bar the Root wraps `Page.Root`. |
 
 ### SmartFilter.Toolbar
-`ref` → `HTMLDivElement`. A `<div>`: the search Input first, then the filter Button (a count Badge while filters apply); the anchor of the panel, a flush Popover.
+`ref` → `HTMLDivElement`. A `<div>`: the search Input first, then the filter Button (a count Badge while filters apply), which shows only its icon and count when the search would get too little room; the anchor of the panel, a flush Popover.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -165,15 +164,16 @@ same height and type.
 | range inverted | `from` above `to` | both bound inputs `aria-invalid` with the danger ring; nothing matches |
 | single value | `multiple: false` | at most one value `aria-pressed`; no «−» |
 | no filters | empty value | no count on the button, no Chips |
+| compact button | the toolbar narrower than the search's 9rem plus the labelled button (search and fields both present) | the button shows its icon and the count Badge; its name stays «Фильтр» (`aria-label` without filters, a visually hidden label with them) |
 
 ## Layout & spacing
-- The panel is a flush Popover as wide as the toolbar; every section is a full-width row with its own padding (`--prime-space-3` × `--prime-space-4`, footer `--prime-space-2` × `--prime-space-4`), Dividers run edge to edge, the field label column is `--prime-space-24`; a row narrower than 24rem stacks the label over the values (an intrinsic wrap, no breakpoint).
-- The toolbar is one row of controls (`--prime-space-2` gap): the search first, growing from 9rem (`--prime-space-24` × 1.5), then the filter button at its own width. When less than 9rem is left beside the button, the button moves under the search; every row stays one control high. Search first, filter second — the active filters (`SmartFilter.Chips`) sit under them.
+- The panel is a flush Popover at least as wide as the toolbar (`width="min-trigger"`), by its content up to twice the panel minimum when the toolbar is narrow; every section is a full-width row with its own padding (`--prime-space-3` × `--prime-space-4`, footer `--prime-space-2` × `--prime-space-4`), Dividers run edge to edge, the field label column is at least `--prime-space-24` (a longer name takes its own width, never breaking inside a word); a row narrower than 24rem stacks the label over the values (an intrinsic wrap, no breakpoint).
+- The toolbar is one row of controls (`--prime-space-2` gap): the search first, growing from 9rem (`--prime-space-24` × 1.5), then the filter button at its own width. When less than 9rem is left beside the labelled button, the button shows only its icon and count and stays beside the search, which gives its width instead of wrapping. Every row stays one control high. The search and the button also stand alone: `searchable={false}` keeps the button, empty `fields` keep the search. Search first, filter second — the active filters (`SmartFilter.Chips`) sit under them.
 - Chips are Badges of the toolbar tier on the badge scale (`xs` → `s`), so a tag sits lower than the controls above it; «Добавить фильтр» is a tag of the same tier and «Сбросить все» a LinkButton with the tag's text size.
 - Values and chips wrap with `--prime-space-2` gaps; «Сбросить все» is pushed to the end. The chips row rises in with the first filter and closes up in place with the last (`partPresence`).
 - Option groups stack `--prime-space-3` apart, a caption `--prime-space-1` above each group's values. A range row holds two equal Inputs with a dash between them, centred on the field label.
 - While typing a search a range row stays only when its field name matches.
-- The root is a flex column (`--prime-space-3`): Toolbar, then Chips.
+- The root draws nothing: its host places Toolbar and Chips. In a page bar the Toolbar goes in `Page.Tools` and the Chips in `Page.Chips`, with `SmartFilter.Root` around `Page.Root`; outside a page a host stacks them (a `Card.Body`, a form column).
 
 ## Accessibility
 
@@ -244,7 +244,7 @@ same height and type.
 - A fixed field marked `finite: false` → the user can hide every value and get an empty list.
 - Filtering the list with `includes` → use `matchesSmartFilter` (empty `include` is "any", `exclude` rejects; range bounds are inclusive, dates by whole days; an item with no value passes only an empty filter).
 - Sending `include` to a server for a hidden value of a fixed field → use `resolveSmartFilterValues` («hide» becomes «all except», `[]` means no filter).
-- Putting `Chips` outside `SmartFilter.Root` → every part needs the root.
+- Putting `Chips` outside `SmartFilter.Root` → every part needs the root; when Toolbar and Chips stand in different groups of a page bar, wrap `Page.Root` in it.
 - A second row of filter buttons next to the toolbar → fields belong in `fields`.
 - An amount or a period in its own Popover beside the toolbar → a `range` / `date-range` field; it gets a chip and the count.
 - One field split in two because its values are of different kinds → one field with `group` on the options.
@@ -252,4 +252,4 @@ same height and type.
 
 ## Related
 - **Built from:** [Button](../button/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Input](../input/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Divider](../divider/COMPONENT.md), [Kbd](../kbd/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Typography](../typography/COMPONENT.md), Icon (`action.search`, `action.filter`, `action.add`, `nav.chevronDown`), [VisuallyHidden](../visually-hidden/COMPONENT.md)
-- **See also:** [PageToolbar](../page-toolbar/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)
+- **See also:** [Page](../../layout/page/COMPONENT.md) (`Page.Tools`, `Page.Chips`), [TagSelect](../tag-select/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)

package/src/components/smart-filter/examples/examples.module.css

@@ -30,6 +30,9 @@
 
 /* 320 px: the smallest supported viewport. */
 .narrow {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-3);
   width: min(100%, calc(var(--prime-space-20) * 4));
   min-width: 0;
 }

package/src/components/smart-filter/examples/many-values.tsx

@@ -1,6 +1,8 @@
 /** 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`. */
 import { Icon, SmartFilter, type SmartFilterField } from "prime-ui-kit";
 
+import styles from "./examples.module.css";
+
 const SERVICES = [
   "access-policy",
   "billing",
@@ -41,13 +43,15 @@ const FIELDS: SmartFilterField[] = [
 
 export default function SmartFilterManyValuesExample() {
   return (
-    <SmartFilter.Root
-      fields={FIELDS}
-      collapsedLimit={8}
-      defaultValue={{ service: { include: [], exclude: ["events"] } }}
-    >
-      <SmartFilter.Toolbar />
-      <SmartFilter.Chips />
-    </SmartFilter.Root>
+    <div className={styles.stack}>
+      <SmartFilter.Root
+        fields={FIELDS}
+        collapsedLimit={8}
+        defaultValue={{ service: { include: [], exclude: ["events"] } }}
+      >
+        <SmartFilter.Toolbar />
+        <SmartFilter.Chips />
+      </SmartFilter.Root>
+    </div>
   );
 }

package/src/components/smart-filter/examples/sizes.tsx

@@ -1,5 +1,5 @@
 /** Every size tier: the filter button, the search, the tags and the panel follow one tier — `size`. */
-import { SmartFilter, type SmartFilterField, Typography } from "prime-ui-kit";
+import { Card, SmartFilter, type SmartFilterField, Typography } from "prime-ui-kit";
 
 const FIELDS: SmartFilterField[] = [
   {
@@ -18,8 +18,12 @@ export default function SmartFilterSizesExample() {
       {SIZES.map((size) => (
         <div key={size}>
           <SmartFilter.Root fields={FIELDS} size={size} defaultValue={ONLY_GET}>
-            <SmartFilter.Toolbar />
-            <SmartFilter.Chips />
+            <Card.Root>
+              <Card.Body>
+                <SmartFilter.Toolbar />
+                <SmartFilter.Chips />
+              </Card.Body>
+            </Card.Root>
           </SmartFilter.Root>
           <Typography as="span" variant="caption" tone="muted">
             {size}

package/src/components/sparkline/COMPONENT.md

@@ -133,6 +133,7 @@ Put it in a `Card` for a dashboard tile.
 - Bars share the width equally, 4 px apart; the zero line sits where 0 falls on the scale (the bottom when every value is positive).
 - In a dashboard, wrap it in `Card.Root` + `Card.Body`; several cards go in a grid.
 - When the value row does not fit (a narrow card), the change badge wraps under the value.
+- On a head narrower than 20rem (a phone card) the date takes its own line under the title, which wraps instead of being cut; the break follows the width only, so a date that changes while scrubbing never moves it.
 - `layout="compact"` fits a DataTable row of any tier (plot and dot within an `xs` control height) and takes the cell width, at least `--prime-space-24`; give the column a `width` for an even plot per row. Put the number next to it in its own column: the compact plot shows a value only in its tooltip while scrubbed.
 - The tooltip is the kit's chart tooltip, placed like every anchored layer (`usePosition`): right of the pointer at its height, on the left only where the right has no room in the viewport — crossing the middle never moves it; from the keyboard right of the point at mid-height. Portaled, so a card or a table scroller never clips it.
 

package/src/components/sparkline/examples/curve.tsx

@@ -1,5 +1,7 @@
 /** The same month of active users as a smooth curve, straight segments and steps — `curve`. */
-import { Sparkline, type SparklinePoint, Typography } from "prime-ui-kit";
+import { Card, Sparkline, type SparklinePoint } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
 
 const USERS: SparklinePoint[] = [
   { label: "сен, 1 нед.", value: 1240 },
@@ -10,19 +12,22 @@ const USERS: SparklinePoint[] = [
   { label: "окт, 2 нед.", value: 1840 },
 ];
 
-const CURVES = ["smooth", "linear", "step"] as const;
+const CURVES = [
+  { curve: "smooth", title: "Плавная кривая" },
+  { curve: "linear", title: "Прямые отрезки" },
+  { curve: "step", title: "Ступени" },
+] as const;
 
 export default function SparklineCurveExample() {
   return (
-    <div>
-      {CURVES.map((curve) => (
-        <div key={curve}>
-          <Sparkline data={USERS} label="Активные пользователи" curve={curve} />
-          <Typography as="span" variant="caption" tone="muted">
-            {curve}
-          </Typography>
-        </div>
+    <>
+      {CURVES.map(({ curve, title }) => (
+        <Card.Root key={curve} className={styles.card}>
+          <Card.Body>
+            <Sparkline data={USERS} label={title} curve={curve} />
+          </Card.Body>
+        </Card.Root>
       ))}
-    </div>
+    </>
   );
 }

package/src/components/sparkline/examples/states.tsx

@@ -12,19 +12,23 @@ const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
 
 export default function SparklineStatesExample() {
   return (
-    <div>
+    <>
       <div>
-        <Sparkline data={REVENUE} label="Выручка" formatValue={formatRubles} />
-        <Typography as="span" variant="caption" tone="muted">
-          data
-        </Typography>
+        <div>
+          <Sparkline data={REVENUE} label="Выручка" formatValue={formatRubles} />
+          <Typography as="span" variant="caption" tone="muted">
+            data
+          </Typography>
+        </div>
       </div>
       <div>
-        <Sparkline data={[]} label="Выручка" loading />
-        <Typography as="span" variant="caption" tone="muted">
-          loading
-        </Typography>
+        <div>
+          <Sparkline data={[]} label="Выручка" loading />
+          <Typography as="span" variant="caption" tone="muted">
+            loading
+          </Typography>
+        </div>
       </div>
-    </div>
+    </>
   );
 }

package/src/components/switch/COMPONENT.md

@@ -46,6 +46,7 @@ Switch.Root          field grid; ref and input props go to the native input (rol
 | `optional` | `boolean` | `false` | Muted `labels.optional` after the label text; the field may stay off. |
 | `labels` | `Partial<SwitchLabels>` | — | Built-in strings, see Labels. |
 | `hint` | `ReactNode` | — | Help text under the label text. Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger ring on the off track and `aria-invalid`. A non-empty `error` implies it. |
 | `disabled` | `boolean` | `false` | No toggling; muted track (on = `accent-soft`), dimmed text and hint. |
@@ -97,7 +98,7 @@ No `variant` / `tone` / `color`.
 | off | `checked={false}` / default | `data-state="unchecked"`; track `fill-strong` (hover `fill-strong-hover`), thumb at the start |
 | on | `checked` / `defaultChecked` | `data-state="checked"`; accent track, the thumb glides to the end |
 | invalid | `invalid` or a non-empty `error` | `data-invalid="true"`, `aria-invalid`; danger ring on the off track and on focus; the row shakes once when an error arrives (`data-shake`) |
-| disabled | `disabled` | `data-disabled="true"`; off track `fill-muted`, on track `accent-soft`, `cursor: not-allowed` |
+| disabled | `disabled` | `data-disabled="true"`; off track `fill-muted`, on track `accent-soft`, thumb `control-thumb-disabled` without shadow, `cursor: not-allowed` |
 | read-only | `readOnly` | `aria-readonly="true"` on the input, `data-readonly="true"` on the field; no hover or press, default cursor |
 | saving | `loading`, or `onCheckedChange` returned a pending promise | the thumb stands in the new position with a `Spinner` inside (accent when on, muted when off; it fades in by itself), `aria-busy` on the input, `data-loading` on the track, presses ignored; a rejection glides the thumb back (`base`, emphasized) |
 | pressed | pointer press | the track scales to the compact press scale (not when disabled or read-only) |

package/src/components/tabs/COMPONENT.md

@@ -189,7 +189,7 @@ Avoid icons or descriptions on only some tabs (uneven rows; without an icon on e
 | 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 |
 | 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); 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 |
+| 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.
 

package/src/components/tag-select/COMPONENT.md

@@ -60,6 +60,7 @@ TagSelect                       field frame: label · control · hint/error (sin
 | `onOptionDelete` | `(value: string) => void \| Promise<void>` | — | Enables «Удалить» in the row menu; the value also leaves the selection. A returned Promise defers it: resolve deletes, reject keeps everything (e.g. after a confirmation). |
 | `label` | `ReactNode` | — | Field label above; names the input. |
 | `hint` | `ReactNode` | — | Support text under the field; linked by `aria-describedby`. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message; replaces the hint and implies `invalid`. |
 | `required` | `boolean` | `false` | Red `*` after the label and `aria-required` on the input. |
 | `optional` | `boolean` | — | Muted `labels.optional` after the label. |

package/src/components/textarea/COMPONENT.md

@@ -46,6 +46,7 @@ Unlike Input, Textarea has no Wrapper / Field parts: `Textarea.Root` renders the
 | `required` | `boolean` | — | Native `required` on the textarea and a red `*` after the label (`aria-hidden`). |
 | `optional` | `boolean` | `false` | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the field. Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger inset ring on the field box, `aria-invalid` on the textarea. A non-empty `error` implies it. |
 | `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring on the field box (`data-focus-ring="false"`); focus, keyboard, ARIA and the invalid ring stay. |

package/src/components/timeline/COMPONENT.md

@@ -27,7 +27,7 @@ Timeline.Root                    size container, sets the tier (size, else the h
 └─ Timeline.Group label          labelled <ol role="list">; the line runs from its first dot to its last
    ├─ Timeline.Item              <li> + row (div | button | a | asChild element) with the dot
    │  ├─ Timeline.ItemTitle      first line
-   │  ├─ Timeline.ItemMeta       second line (date); <strong> emphasizes a part
+   │  ├─ Timeline.ItemMeta       second line (date); <strong> emphasizes a part; repeats, lines stack
    │  └─ Timeline.ItemValue      trailing amount
    │     └─ Timeline.ItemMeta    second line under the amount
    └─ Timeline.Gap               <li>: interval between events (dashed segment, hollow dot)
@@ -73,7 +73,7 @@ Timeline.Root                    size container, sets the tier (size, else the h
 | `…rest` | `Omit<HTMLAttributes<HTMLElement>, "children" \| "color" \| "onClick">` | — | The other row attributes (`target`, `rel`, `download` with `href`). |
 
 ### Timeline.ItemTitle · Timeline.ItemMeta
-`ref` → `HTMLSpanElement`. `<span>` lines: the event (medium, accent on the highlighted row, wraps) and the muted secondary line with tabular numbers — under the title the date (emphasize a part with `<strong>`), inside `Timeline.ItemValue` the value's second line.
+`ref` → `HTMLSpanElement`. `<span>` lines: the event (medium, wraps) and the muted secondary line, tabular — under the title the date (`<strong>` emphasizes a part; several `Timeline.ItemMeta` stack), inside `Timeline.ItemValue` the value's second line.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -180,7 +180,7 @@ No `labels`.
 | [overview.tsx](examples/overview.tsx) | An operations feed: one labelled group, a line through the dots, the row under the pointer highlighted — `Timeline.Group`, `Timeline.ItemValue`. |
 | [variants.tsx](examples/variants.tsx) | Dot hues for categories at reduced emphasis, and status tones on items, values and gaps at full emphasis — `color`, `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier scales text, dot and row rhythm, rows 40 to 76 px — `size`. |
-| [structure.tsx](examples/structure.tsx) | A service history with intervals between events, a caption on the right of a gap and a second value line — `Timeline.Gap`, `Timeline.Description`, `Timeline.ItemMeta`. |
+| [structure.tsx](examples/structure.tsx) | A service history with intervals between events, a caption on the right of a gap, two meta lines under a repair and a second value line — `Timeline.Gap`, `Timeline.Description`, `Timeline.ItemMeta`. |
 | [links.tsx](examples/links.tsx) | Rows that open something: an operation page by a link or by your router link through the slot, a receipt in place by a button; one Tab stop each with a focus ring — `href`, `asChild`, `onClick`. |
 | [narrow.tsx](examples/narrow.tsx) | At 375 px the title wraps and the amount stays right; below 20rem of its own width the amount moves under the meta line — `Timeline.ItemValue`. |
 

package/src/components/timeline/examples/structure.tsx

@@ -1,4 +1,4 @@
-/** A service history with intervals between events, a caption on the right of a gap and a second value line — `Timeline.Gap`, `Timeline.Description`, `Timeline.ItemMeta`. */
+/** A service history with intervals between events, a caption on the right of a gap, two meta lines under a repair and a second value line — `Timeline.Gap`, `Timeline.Description`, `Timeline.ItemMeta`. */
 import { Timeline } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -36,6 +36,7 @@ export default function TimelineStructureExample() {
           <Timeline.ItemMeta>
             <strong>07.06.26</strong> · 12 100 км
           </Timeline.ItemMeta>
+          <Timeline.ItemMeta>Мастер Олег Смирнов · гарантия 6 месяцев</Timeline.ItemMeta>
           <Timeline.ItemValue>
             2 800 ₽<Timeline.ItemMeta>Ремонт</Timeline.ItemMeta>
           </Timeline.ItemValue>

package/src/components/typography/COMPONENT.md

@@ -94,7 +94,7 @@ Text has no interactive states.
 - No outer margins: spacing comes from the parent's `gap`.
 - Title, heading and display roles balance their lines (`text-wrap-style: balance`); body and caption avoid a lone last word (`pretty`). Long words break (`overflow-wrap: break-word`).
 - `code` uses the mono family (JetBrains Mono); every other role the sans family (Golos Text).
-- Reading text: cap the column at the reading measure (PageContent `maxWidth="readable"`, 60–75 characters).
+- Reading text: cap the column at the reading measure (`Page.Root maxWidth="readable"`, 60–75 characters).
 - `truncate` needs a block element and a shrinking parent (`min-width: 0` in flex rows).
 
 ## Accessibility
@@ -138,4 +138,4 @@ No `labels`.
 
 ## Related
 - **Built from:** —
-- **See also:** [LinkButton](../link-button/COMPONENT.md), [CodeBlock](../code-block/COMPONENT.md), [Label](../label/COMPONENT.md), [PageContent](../page-content/COMPONENT.md)
+- **See also:** [LinkButton](../link-button/COMPONENT.md), [CodeBlock](../code-block/COMPONENT.md), [Label](../label/COMPONENT.md), [Page](../../layout/page/COMPONENT.md)

package/src/layout/app-shell/COMPONENT.md

@@ -3,16 +3,16 @@
 **Category:** page
 **Kind:** layout
 
-> The app frame: a content panel that is the page itself and a navigation rail one layer above it.
+> The app frame — navigation and the page: a content panel that is the page itself and a navigation rail one layer above it.
 
 ## When to use
-- The root layout of an application: navigation column, an optional AppHeader, scrolling main column, a bottom bar for phone navigation.
+- The root layout of an application: navigation column, the scrolling main where the page renders, a bottom bar for phone navigation.
 - Any page that needs the kit's responsive gutters and the surface ladder for cards and fields.
 
 ## When not to use
 - The navigation itself → use [Sidebar](../sidebar/COMPONENT.md) inside `AppShell.Nav`, [BottomNav](../bottom-nav/COMPONENT.md) inside `AppShell.Footer`.
-- The page's top bar (the page title, its tools, the menu button) → use [AppHeader](../app-header/COMPONENT.md) anywhere in the shell: it renders in the shell's header row.
-- Page heading, actions and sections inside main → use [PageContent](../../components/page-content/COMPONENT.md).
+- Anything at the top of the page — the title, its actions and tools, the phone menu button → the page's own top bar, [Page](../page/COMPONENT.md) `Page.TopBar`; the shell has no header.
+- Page heading, actions and sections inside main → use [Page](../page/COMPONENT.md).
 - A temporary side panel over the page → use [Drawer](../../components/drawer/COMPONENT.md).
 - A scroll region inside a page → use [ScrollContainer](../../components/scroll-container/COMPONENT.md).
 
@@ -25,25 +25,24 @@ import { AppShell } from "prime-ui-kit";
 ```
 AppShell.Root                grid: nav column | content panel (the page, layer 0)
 ├─ AppShell.Nav              navigation column (usually Sidebar.Root, a surface one layer above the page)
-├─ (header row)              the panel's top: the latest AppHeader.Root in the shell renders here
-├─ AppShell.Main             <main>, scrolls, carries the gutters
+├─ AppShell.Main             <main>, scrolls; hands the page (Page.Root) its gutters and top air
 └─ AppShell.Footer           sticky bottom bar of the panel (usually BottomNav.Root)
-AppShell.Template            Root + Nav + the header + Main + Footer in one component
+AppShell.Template            Root + Nav + Main + Footer in one component
 useAppShellNav()             the navigation the Sidebar publishes, for triggers outside the rail
 ```
-Every child of Root that is not `AppShell.Nav` is placed into the content panel. An `AppHeader.Root` anywhere in the shell — a child of Root, `Template.header`, a page's own one in main — renders in the header row; the latest one on screen wins, so a page's header replaces the default while that page is shown.
+Every child of Root that is not `AppShell.Nav` is placed into the content panel. Everything at the top of the panel belongs to the page: its `Page.TopBar` sticks to the top of main.
 
 ## API
 
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### AppShell.Root
-`ref` → `HTMLDivElement`. Grid of the nav column and the content panel (the page itself); every child but `AppShell.Nav` goes into the panel. Owns the navigation its Sidebar publishes (`useAppShellNav`) and the header row an `AppHeader.Root` anywhere in it renders in.
+`ref` → `HTMLDivElement`. Grid of the nav column and the content panel (the page itself); every child but `AppShell.Nav` goes into the panel. Owns the navigation its Sidebar publishes (`useAppShellNav`).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `fillViewport` | `boolean` | `false` | The shell is exactly the viewport high and only `AppShell.Main` scrolls; otherwise the document scrolls and the nav is sticky. |
-| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Nav, `AppHeader.Root`, Main, Footer), `className` and the other div attributes. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Nav, Main, Footer), `className` and the other div attributes. |
 
 ### AppShell.Nav
 `ref` → `HTMLDivElement`. The navigation column slot (not a landmark: Sidebar renders the `<nav>`).
@@ -53,11 +52,10 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (usually `Sidebar.Root`), `className` and the other div attributes. |
 
 ### AppShell.Main
-`ref` → `HTMLElement`. The `<main>` with the canonical gutters: a vertical `ScrollContainer`.
+`ref` → `HTMLElement`. The `<main>` where the page renders: a vertical `ScrollContainer` that hands `Page.Root` the gutters and top air (`--page-gutter`, `--page-top`).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `contentWidth` | `"contained" \| "full"` | `"full"` | `full` — the whole panel with gutters; `contained` — a centred column up to `--prime-layout-content-max-width`. |
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes. |
 
 ### AppShell.Footer
@@ -68,17 +66,16 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (usually `BottomNav.Root`), `className` and the other div attributes. |
 
 ### AppShell.Template
-`ref` → the `<main>`. Root + Nav + the header + Main + Footer in one; main scrolls to the top when `scrollResetKey` changes.
+`ref` → the `<main>`. Root + Nav + Main + Footer in one; main scrolls to the top when `scrollResetKey` changes.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `fillViewport` | `boolean` | `false` | As on `AppShell.Root`: only `<main>` scrolls. |
 | `nav` | `ReactNode` | — | Navigation column content; without it the panel takes the full width. |
-| `header` | `ReactNode` | — | The default header row, an `AppHeader.Root`: a page that renders its own header replaces it while that page is on screen. |
 | `footer` | `ReactNode` | — | Footer content (`BottomNav`); no footer when omitted. |
-| `mainProps` | `Omit<AppShellMainProps, "children">` | — | Props for Main (e.g. `contentWidth`). |
+| `mainProps` | `Omit<AppShellMainProps, "children">` | — | Props for Main (`id`, `tabIndex` for a skip link). |
 | `scrollResetKey` | `unknown` | — | Main scrolls back to the top whenever this value changes; pass the router pathname. |
-| `children` | `ReactNode` | — | Page content inside Main. |
+| `children` | `ReactNode` | — | The page inside Main (`Page.Root`). |
 | `…rest` | `Omit<AppShellRootProps, "children">` | — | Root props: `fillViewport`, `className` and the div attributes. |
 
 ### Types
@@ -108,38 +105,29 @@ The navigation of the nearest `AppShell.Root` for a trigger outside the rail (a
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `false` | Shell at least viewport high; the document scrolls; nav sticks to the top | Content sites, simple apps | yes |
-| `true` | Shell exactly viewport high; only Main scrolls; header and nav stay put | Dense apps with a fixed frame | |
-
-### contentWidth (Main)
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `full` | Content spans the panel with responsive gutters | Tables, dashboards | yes |
-| `contained` | Centred column up to the content max width | Long-read pages | |
+| `true` | Shell exactly viewport high; only Main scrolls; nav and the page's sticky top bar stay put | Dense apps with a fixed frame | |
 
 ### Structure
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | with `AppShell.Nav` | Two columns: a rail one layer above the page + the panel that is the page | Apps with navigation | |
 | without Nav | Panel takes the full width | Single-page tools, auth screens | |
-| with `AppHeader.Root` | Sticky bar in the header row at the top of the panel, from anywhere in the shell | The page title (or the path and the record), the page's tools and buttons; on a phone it leads with the menu button | |
 | with `AppShell.Footer` | Sticky bar at the bottom of the panel, shown while no navigation column is on screen | BottomNav on a phone | |
 
-`AppShell.Template` with `nav={<Sidebar.Root …/>}` and `PageContent` inside is the standard app; `contentWidth="contained"` + `PageContent.Root maxWidth="readable"` for docs and articles.
+`AppShell.Template` with `nav={<Sidebar.Root …/>}` and a `Page.Root` inside is the standard app; `Page.Root maxWidth="readable"` for docs and articles.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | fixed frame | `fillViewport` | `data-fill-viewport="true"` on Root |
 | navigation column | an `AppShell.Nav` child | `data-nav="true"` on Root (two grid columns) |
-| content width | `contentWidth` | `data-content-width` on Main |
 | off-canvas navigation | the Sidebar publishes that it is an off-canvas panel (`offCanvas="auto"` on a phone, `"always"`) | `data-off-canvas="true"` on Root; `useAppShellNav()` reports `offCanvas`, `open`, `navId` |
 | footer bar | the navigation column: `AppShell.Nav` with a Sidebar that is not off-canvas | the footer is `display: none` while the rail is on screen; without Nav or with an off-canvas Sidebar it stays at any width |
-| header row | an `AppHeader.Root` in the shell | the latest one on screen renders at the top of the panel, before main |
 
 ## Layout & spacing
 - Two full-height planes edge to edge: no inset, radius, shadow or border — the boundary is the fill change (the Sidebar rail is layer 1, the panel the page: white rail beside a gray page in light, a rail one step lighter than the near-black page in dark).
-- Gutters in Main (and in the header row): the page gutter `--prime-layout-gutter` — `--prime-layout-gutter-s` (16) → `-m` (24) from 640px → `-l` (32) from 1024px. Main top padding `--prime-space-6` (24) → `--prime-space-8` (32) from 1024px; bottom `--prime-space-16`. Inside Main the page gutter is the small one again, so a frame nested in the page starts from its own gutter, not the shell's.
-- A page that fills the panel height (`PageContent.Root fill`): Main's bottom padding drops to the side gutter, so no long scroll tail stays under it.
+- Main hands the page its edge air: `--page-gutter` is the page gutter `--prime-layout-gutter` — `--prime-layout-gutter-s` (16) → `-m` (24) from 640px → `-l` (32) from 1024px; `--page-top` is `--prime-space-6` (24) → `--prime-space-8` (32) from 1024px. `Page.Root` pads itself with them (its top bar steps out to the panel's edges). Main itself pads only the bottom: `--prime-space-16`, the scroll tail of a long page. Inside Main the page gutter is the small one again, so a frame nested in the page starts from its own gutter, not the shell's.
+- A page that fills the panel height (`Page.Root fill`): Main's bottom padding drops to the side gutter, so no long scroll tail stays under it — beside the Sidebar rail too.
 - Main scrolls with `overscroll-behavior: contain`, so its scroll never chains to the document.
 - Nav column: sticky at the top, viewport high, `z-index: --prime-z-sticky` (above the panel, so the compact Sidebar toggle can ride the rail edge); with `fillViewport` it fills the shell height instead.
 - Footer: no padding of its own (BottomNav keeps the bottom safe-area inset), sticky at the bottom, `z-index: --prime-z-sticky`.
@@ -156,8 +144,8 @@ No keyboard interaction.
 ### ARIA
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-- Main is the `<main>` landmark; the banner comes from AppHeader (`<header>`), the navigation landmarks from Sidebar and BottomNav (`<nav>`).
-- One `<h1>` per page: `AppHeader.Title` on app pages, `PageContent.Title` on a document page (whose header then has no title).
+- Main is the `<main>` landmark; the navigation landmarks come from Sidebar and BottomNav (`<nav>`). The page's top bar is a `<header>` inside main, not a banner.
+- One `<h1>` per page: its `Page.Title`, in the top bar or in the flow.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -167,21 +155,20 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | The app frame: Sidebar in the nav column, the page title and its action in the AppHeader, the page in main; only main scrolls — `fillViewport`. |
-| [contained.tsx](examples/contained.tsx) | A shell without navigation whose main column is centred and capped for long reads — `contentWidth`. |
+| [overview.tsx](examples/overview.tsx) | The app frame: Sidebar in the nav column, the page in main with its title and action in its top bar; only main scrolls — `fillViewport`. |
 | [footer.tsx](examples/footer.tsx) | A phone app without a Sidebar: the bar in the footer stays at the bottom while main scrolls under it — `AppShell.Footer`. |
-| [template.tsx](examples/template.tsx) | Root, nav, header and main in one component; main scrolls back to the top whenever the page changes — `AppShell.Template`, `scrollResetKey`. |
-| [screen.tsx](examples/screen.tsx) | The app frame for desktop and phone: the Sidebar rail on a wide screen, the floating BottomNav in the footer on a phone whose More item opens the Sidebar, the AppHeader with the menu button it draws by itself, the page title with a line of data, and a simple home page that swaps with the current section — `fillViewport`, `scrollResetKey`, `useAppShellNav`. |
+| [template.tsx](examples/template.tsx) | Root, nav, main and footer in one component; main scrolls back to the top whenever the page changes — `AppShell.Template`, `scrollResetKey`. |
+| [screen.tsx](examples/screen.tsx) | The app frame for desktop and phone: the Sidebar rail on a wide screen, the floating BottomNav in the footer on a phone whose More item opens the Sidebar, the page top bar with the menu button it draws by itself, the page title with a line of data, and a simple home page that swaps with the current section — `fillViewport`, `scrollResetKey`, `useAppShellNav`. |
 
 ## Mistakes
-- Adding padding around the page content → Main already has the gutters.
+- Adding padding around the page content → `Page.Root` takes the gutters Main hands it.
 - Wrapping Main content in another scroll container → Main scrolls (with `fillViewport`) or the document does.
 - A border or shadow between nav and panel → the fill change is the boundary.
 - Putting the Sidebar directly in Root without `AppShell.Nav` → it lands inside the content panel.
 - BottomNav anywhere but `AppShell.Footer` → it stays next to the Sidebar rail on a desktop; the footer is what leaves while the rail is on screen.
 - `AppShell.Template` in a router app without `scrollResetKey` → a new page opens at the old scroll position; pass the pathname.
-- A hand-wired menu state shared by the Sidebar, a menu button and a BottomNav «Ещё» → the Sidebar publishes it to the shell: the AppHeader draws the menu button, other triggers read `useAppShellNav()`.
+- A hand-wired menu state shared by the Sidebar, a menu button and a BottomNav «Ещё» → the Sidebar publishes it to the shell: the page's `Page.TopBar` draws the menu button, other triggers read `useAppShellNav()`.
 
 ## Related
 - **Built from:** [ScrollContainer](../../components/scroll-container/COMPONENT.md)
-- **See also:** [AppHeader](../app-header/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [BottomNav](../bottom-nav/COMPONENT.md), [PageContent](../../components/page-content/COMPONENT.md), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)
+- **See also:** [Page](../page/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [BottomNav](../bottom-nav/COMPONENT.md), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)