prime-ui-kit 0.15.0 → 0.17.0

package/dist/skill/reference/layout/page/examples/top-bar.tsx

@@ -0,0 +1,85 @@
+/** A nested record in the top bar: the path ending in the title, a line of data, the page's tools and its buttons — `Page.TopBar`, `Page.Heading`, `Page.Tools`, `Page.Actions`. */
+import { Breadcrumb, Button, Icon, Input, Page, SegmentedControl } from "prime-ui-kit";
+import * as React from "react";
+
+const SECTIONS = [
+  { value: "all", label: "Все" },
+  { value: "mine", label: "Мои" },
+  { value: "overdue", label: "Просрочены" },
+];
+
+const VIEWS = [
+  { value: "board", label: "Доска" },
+  { value: "list", label: "Список" },
+];
+
+export default function PageTopBarExample() {
+  const [section, setSection] = React.useState("all");
+  const [view, setView] = React.useState("board");
+  const [query, setQuery] = React.useState("");
+
+  return (
+    <Page.Root>
+      <Page.TopBar sticky={false}>
+        <Page.Heading>
+          <Breadcrumb.Root>
+            <Breadcrumb.Item href="#clients">Клиенты</Breadcrumb.Item>
+            <Breadcrumb.Item href="#north">ООО «Север»</Breadcrumb.Item>
+          </Breadcrumb.Root>
+          <Page.Title>Сделка № 2026-418</Page.Title>
+          <Page.Description>7 в работе · 6,5 млн ₽ · обновлено 9:40</Page.Description>
+        </Page.Heading>
+        <Page.Tools aria-label="Сделка № 2026-418">
+          <SegmentedControl.Root value={section} onValueChange={setSection} aria-label="Раздел">
+            {SECTIONS.map((item) => (
+              <SegmentedControl.Item key={item.value} value={item.value}>
+                {item.label}
+              </SegmentedControl.Item>
+            ))}
+          </SegmentedControl.Root>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Icon side="start">
+                <Icon name="action.search" tone="secondary" />
+              </Input.Icon>
+              <Input.Field
+                type="search"
+                aria-label="Поиск по задачам"
+                placeholder="Поиск"
+                value={query}
+                onValueChange={setQuery}
+              />
+            </Input.Wrapper>
+          </Input.Root>
+          <SegmentedControl.Root value={view} onValueChange={setView} aria-label="Вид">
+            {VIEWS.map((item) => (
+              <SegmentedControl.Item key={item.value} value={item.value}>
+                {item.label}
+              </SegmentedControl.Item>
+            ))}
+          </SegmentedControl.Root>
+        </Page.Tools>
+        <Page.Actions>
+          <Button.Root variant="soft" tone="neutral">
+            <Button.Icon>
+              <Icon name="action.forward" />
+            </Button.Icon>
+            Поделиться
+          </Button.Root>
+          <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>
+      </Page.TopBar>
+    </Page.Root>
+  );
+}

package/dist/skill/reference/{components/page-content → layout/page}/examples/variants.tsx

@@ -1,5 +1,5 @@
-/** The same page column at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. */
-import { Card, PageContent, Typography } from "prime-ui-kit";
+/** The same page at three caps: the whole main, a wide dashboard column, a reading column — `maxWidth`. */
+import { Card, Page, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
@@ -9,13 +9,13 @@ const WIDTHS = [
   { value: "readable", text: "Условия использования: не шире колонки для чтения, по центру." },
 ] as const;
 
-export default function PageContentVariantsExample() {
+export default function PageVariantsExample() {
   return (
-    <div className={styles.main}>
-      <div className={styles.stack}>
-        {WIDTHS.map(({ value, text }) => (
-          <PageContent.Root key={value} maxWidth={value}>
-            <PageContent.Body>
+    <>
+      {WIDTHS.map(({ value, text }) => (
+        <div key={value} className={styles.main}>
+          <Page.Root maxWidth={value}>
+            <Page.Body>
               <Card.Root>
                 <Card.Body>
                   <Typography variant="body-s" tone="secondary">
@@ -23,10 +23,10 @@ export default function PageContentVariantsExample() {
                   </Typography>
                 </Card.Body>
               </Card.Root>
-            </PageContent.Body>
-          </PageContent.Root>
-        ))}
-      </div>
-    </div>
+            </Page.Body>
+          </Page.Root>
+        </div>
+      ))}
+    </>
   );
 }

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

@@ -54,7 +54,7 @@ import { Sidebar, useSidebar } from "prime-ui-kit";
 ```
 Sidebar.Root                       rail wrapper; renders <nav> inside; size tier for items
 ├─ Sidebar.Header                  one fixed-height row
-│  ├─ Sidebar.Brand                logo + name + muted line (link / div / asChild)
+│  ├─ Sidebar.Brand                logo + name + muted line (link / button / div / asChild)
 │  │  └─ Sidebar.BrandLogo         the mark, on the icon axis
 │  └─ Sidebar.Toggle variant="header"  «‹‹» at the header end → round button on the rail edge
 ├─ Sidebar.Content                 scrolling middle (ScrollContainer, edge fades, no scrollbar)
@@ -71,7 +71,7 @@ Sidebar.Root                       rail wrapper; renders <nav> inside; size tier
 │        └─ Sidebar.SubContent     child Items on a guide line (a flyout on the compact rail)
 └─ Sidebar.Footer                  bottom items, the item Toggle, the account
    └─ Sidebar.Account              avatar + name + muted line; a Dropdown.Trigger child
-useSidebar()                       state hook for custom parts inside Root
+useSidebar()                       state hook for custom parts inside Root (useAppShellNav outside it, in a shell)
 ```
 
 ## API
@@ -79,19 +79,21 @@ useSidebar()                       state hook for custom parts inside Root
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Sidebar.Root
-`forwardRef` → `HTMLDivElement`. The rail wrapper with the `<nav>` inside; owns the mode and the off-canvas panel and passes the tier to items.
+`ref` → `HTMLDivElement`. The rail wrapper with the `<nav>` inside; owns the mode and the off-canvas panel and passes the tier to items. In an `AppShell` it publishes its navigation to the shell (`useAppShellNav`).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Item tier: height 28 · 32 · 36 · 40 · 48, text, icon; counters and row actions one tier down. The rail width does not change. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Item tier: height 28 · 32 · 36 · 40 · 48, text, icon; coloured counts and row actions one tier down, plain counts keep the item size. The rail width does not change. Without it the tier of its host, else `m`. |
 | `mode` | `"expanded" \| "compact" \| "hidden"` | — | Desktop mode (controlled): full rail, icon rail with tooltips and flyouts, or hidden. |
 | `defaultMode` | `"expanded" \| "compact" \| "hidden"` | `"expanded"` | Initial mode (uncontrolled). |
 | `onModeChange` | `(mode: SidebarMode) => void` | — | Called with the new mode (Toggle, `useSidebar().setMode`). |
 | `open` | `boolean` | — | Off-canvas panel on narrow viewports (controlled). |
 | `defaultOpen` | `boolean` | `false` | Initial off-canvas state (uncontrolled). |
-| `onOpenChange` | `(open: boolean) => void` | — | Off-canvas open / close: Toggle, scrim, Escape, navigation, leaving the narrow viewport. |
+| `onOpenChange` | `(open: boolean) => void` | — | Off-canvas open / close: Toggle, the menu button of `Page.TopBar`, scrim, Escape, an activated item, leaving the narrow viewport. |
 | `offCanvas` | `"auto" \| "always" \| "never"` | `"auto"` | When the rail becomes an off-canvas panel opened by `open`: `auto` — below 768px (viewport); `always` — at any width; `never` — always a rail. |
-| `persistKey` | `string` | — | `localStorage` key that keeps the mode and the open groups and sub-lists across reloads (keyed by `id`, else label text). Wins over `defaultMode` / `defaultOpen`. |
+| `closeOnOutsideClick` | `boolean` | `true` | A press on the scrim (outside the off-canvas panel) closes the panel. |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the off-canvas panel. |
+| `persistKey` | `string` | — | `localStorage` key that keeps the mode (never `hidden`: the mode it left) and the open groups and sub-lists (by `id`, else label text) across reloads. Wins over `defaultMode` / `defaultOpen`. |
 | `labels` | `Partial<SidebarLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
@@ -103,7 +105,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### Sidebar.Brand
-`forwardRef` → the rendered element. Product block: `Sidebar.BrandLogo`, the name and a muted line; an `<a>` with `href`, the single child with `asChild`, else a `<div>`. In compact mode only the logo stays.
+`ref` → the rendered element. Product block: `Sidebar.BrandLogo`, the name and a muted line; an `<a>` with `href`, the single child with `asChild`, a `<button>` with only `onClick`, else a `<div>`. Activating it closes the off-canvas panel. In compact mode only the logo stays.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -111,7 +113,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `href` | `string` | — | Renders an `<a>` (usually home); navigating closes the off-canvas panel. |
 | `asChild` | `boolean` | `false` | Renders the single child (e.g. a router `Link`) as the brand; its children are the logo and the name. |
 | `children` | `ReactNode` | — | `Sidebar.BrandLogo` and the product name. |
-| `…rest` | `HTMLAttributes<HTMLElement>` | — | `onClick`, `aria-*`, `className` and the other attributes. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `onClick` (runs first; `preventDefault()` keeps the panel open; without `href` it makes the brand a button), `aria-*`, `className` and the other attributes. |
 
 ### Sidebar.BrandLogo
 `ref` → `HTMLSpanElement`. The product mark (`aria-hidden`): a square of the item height − 8 (at most 32) on the icon axis in every mode; its child fills it.
@@ -122,7 +124,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Sidebar.Content
-`forwardRef` → `HTMLElement`. The scrolling middle: a `ScrollContainer` with edge fades and no scrollbar; rows scrolled into view stop clear of the fades.
+`ref` → `HTMLElement`. The scrolling middle: a `ScrollContainer` with edge fades and no scrollbar; rows scrolled into view stop clear of the fades.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -141,16 +143,18 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `children` (Items, Subs), `className` and the other div attributes. |
 
 ### Sidebar.Item
-`forwardRef` → the rendered element. `<button type="button">`, `<a>` with `href`, or the single child with `asChild`; a tooltip with its label in compact mode. With `Sidebar.ItemAction` the element and the action sit side by side in a row `<div>`.
+`ref` → the rendered element. `<button type="button">`, `<a>` with `href`, or the single child with `asChild`; a tooltip with its label in compact mode; activating it closes the flyout and the off-canvas panel. With `Sidebar.ItemAction` both sit in a row `<div>`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `current` | `boolean` | `false` | Current page: `aria-current="page"`, `data-state="active"`; a muted fill and primary text and icon colour. |
 | `disabled` | `boolean` | `false` | Not interactive: `disabled` / `aria-disabled`, `data-disabled`; a link loses its `href`. |
 | `href` | `string` | — | Renders an `<a>` (with `target`, `rel`). |
+| `target` | `string` | — | Where the `<a>` opens (`href` only). |
+| `rel` | `string` | — | Relationship of the `<a>` (`href` only). |
 | `asChild` | `boolean` | `false` | Renders the single child (e.g. a router `NavLink`) as the item; its children are the label and parts. |
 | `children` | `ReactNode` | — | Label (also the compact tooltip) and parts: `Sidebar.ItemIcon` (before the label — leading, after it — trailing), `Sidebar.ItemCount`, `Sidebar.ItemShortcut`, `Sidebar.ItemAction`. |
-| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `aria-*`, `className` and the other attributes. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `onClick` (runs first; `preventDefault()` keeps the flyout and the panel open), `aria-*`, `className` and the other attributes. |
 
 ### Sidebar.ItemIcon
 `ref` → `HTMLSpanElement`. An icon (`aria-hidden`). Before the label it leads and stays on the icon axis in every mode; after the label it is a quiet trailing glyph (`data-edge="end"`, 14, muted), e.g. ↗ for an external link, hidden in compact mode.
@@ -179,14 +183,15 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Sidebar.ItemAction
-`ref` → `HTMLButtonElement`. A row action (create, add): a ghost icon `Button` one tier down with a tooltip, next to the item element — never inside it. Shows on hover and focus of the row (always on touch); hidden on the compact rail.
+`ref` → `HTMLButtonElement`. A row action (create, add): a ghost icon `Button` one tier down with a tooltip, next to the item element — never inside it; with `asChild` a link with the same look. Shows on hover and focus of the row (always on touch); hidden on the compact rail.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `label` | `string` | — (required) | Accessible name and tooltip («Создать задачу»). |
-| `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void` | — (required) | The action. |
+| `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void` | — | The action; required without `asChild`. |
+| `asChild` | `boolean` | `false` | Renders the single child (a link: another page, `mailto:`) as the action; its children are the glyph. |
 | `disabled` | `boolean` | — | Not available. |
-| `children` | `ReactNode` | — | The glyph; `<Icon name="action.add" />` by default. |
+| `children` | `ReactNode` | — | The glyph (`<Icon name="action.add" />` by default), or with `asChild` the link around it. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" \| "onClick" \| "aria-label">` | — | `className` and the other attributes of the Button. |
 
 ### Sidebar.Sub
@@ -200,7 +205,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### Sidebar.SubTrigger
-`forwardRef` → `HTMLButtonElement`. The parent row: a disclosure `<button>` (`aria-expanded`, `aria-controls`) with a chevron at the end of the row. On the compact rail it opens the flyout (`aria-haspopup="dialog"`).
+`ref` → `HTMLButtonElement`. The parent row: a disclosure `<button>` (`aria-expanded`, `aria-controls`) with a chevron at the end of the row. On the compact rail it opens the flyout (`aria-haspopup="dialog"`).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -215,7 +220,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `children` (Items), `className` (on the list) and the other div attributes. |
 
 ### Sidebar.Account
-`forwardRef` → `HTMLButtonElement`. The signed-in person at the bottom of `Sidebar.Footer`: avatar, name, a muted line and a ↕ chevron. A button, so it is a `Dropdown.Trigger` child; in compact mode only the avatar stays, with the name as a tooltip.
+`ref` → `HTMLButtonElement`. The signed-in person at the bottom of `Sidebar.Footer`: avatar, name, a muted line and a ↕ chevron. A button, so it is a `Dropdown.Trigger` child; in compact mode only the avatar stays, with the name as a tooltip.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -224,23 +229,19 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children">` | — | `onClick`, `aria-*`, `className` and the other button attributes. |
 
 ### Sidebar.Toggle
-`forwardRef` → `HTMLButtonElement`. Toggle: expanded ↔ compact on desktop (hidden → expanded), closes the off-canvas panel; label, icon, `aria-expanded` and `aria-controls` come from state and `labels`.
+`ref` → `HTMLButtonElement`. Expanded ↔ compact on desktop (hidden → expanded), open ↔ closed off-canvas; label, icon and ARIA from state and `labels`. Outside the rail, in an `AppShell`, a soft icon `Button` on the shell's navigation — the way back to a hidden rail.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `variant` | `"item" \| "header"` | `"item"` | `item` — a row in the rail. `header` — an icon button «‹‹» at the end of `Sidebar.Header` that moves onto the rail edge in compact mode. |
+| `variant` | `"item" \| "header"` | `"item"` | In the rail: `item` — a row; `header` — a round icon button «‹‹» at the end of `Sidebar.Header` that moves onto the rail edge in compact mode. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" \| "aria-label" \| "aria-expanded" \| "aria-controls">` | — | `onClick` (runs first; `preventDefault()` stops the toggle), `className` and the other button attributes. |
 
-### useSidebar()
-Hook for custom parts inside `Sidebar.Root` (throws outside). Returns the fields below.
+### Functions
 
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `mode · setMode` | `SidebarMode · (mode: SidebarMode) => void` | — | Desktop mode. |
-| `open · setOpen` | `boolean · (open: boolean) => void` | — | Off-canvas panel. |
-| `toggle` | `() => void` | — | The action of `Sidebar.Toggle`. |
-| `offCanvas` | `boolean` | — | The sidebar is an off-canvas panel now (`offCanvas="always"`, or `"auto"` under 768px). |
-| `size · navId · labels` | `ControlSize · string · SidebarLabels` | — | Tier, id of the `<nav>` (for `aria-controls` on your own menu button), resolved strings. |
+#### `useSidebar()`
+`() => { mode: SidebarMode; setMode: (mode: SidebarMode) => void; open: boolean; setOpen: (open: boolean) => void; toggle: () => void; offCanvas: boolean; size: ControlSize; navId: string; labels: SidebarLabels }`
+
+Hook for custom parts inside `Sidebar.Root` (throws outside): the desktop `mode`, the off-canvas `open` state, `toggle` (the action of `Sidebar.Toggle`), `offCanvas` (the sidebar is an off-canvas panel: `offCanvas="always"`, or `"auto"` under 768px), the tier, the `navId` of the `<nav>` (for `aria-controls` on your own menu button) and the resolved strings.
 
 ## Variants
 The rail is a surface beside the page, one layer above it on the surface ladder (`data-depth`): white on the light gray page, one step lighter than the near-black page in dark; no border or card. Items are transparent rows with `text-secondary`, `fill-subtle` on hover; the current item takes the rail's fill two ladder steps off it (`fill-muted-hover`) with primary text.
@@ -267,7 +268,7 @@ The rail width does not depend on `size`.
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `item` | an item row with a panel icon and the label | a toggle in `Sidebar.Footer` | yes |
-| `header` | a ghost «‹‹» icon button at the end of the header; on the compact rail a small round soft button across the outer edge, chevrons pointing out | a brand header (`Sidebar.Brand`) | |
+| `header` | a round ghost «‹‹» icon button (a disk of the compact tier) at the end of the header; on the compact rail a smaller soft disk across the outer edge, chevrons pointing out | a brand header (`Sidebar.Brand`) | |
 
 ### ItemCount
 | Value | Looks like | Use when | Default |
@@ -289,14 +290,19 @@ The rail width does not depend on `size`.
 | `collapsible` (Group) | the heading is a button with a chevron at its end; items fold away; folded on the rail, one `…` row opens them in a flyout | long navigation with sections | off |
 | `current` (Item) | `fill-muted-hover` fill (a `fill-subtle-active` wash in a flyout), primary text and icon | the current page | off |
 | `disabled` (Item) | `text-disabled`, no hover, `cursor: not-allowed` | an unavailable section | off |
+| `closeOnOutsideClick` (Root) | a press on the scrim closes the off-canvas panel | default; turn off when only the toggle or an item may close it | on |
+| `closeOnEscape` (Root) | Escape closes the off-canvas panel | default; turn off with `closeOnOutsideClick` for a panel only its toggle closes | on |
+| `asChild` (ItemAction) | the row action is the consumer's link with the button look | the action opens a page or `mailto:` | off |
 
-Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header, or `Sidebar.Toggle` in the footer for a rail without a brand; on phones (`offCanvas="auto"`) or always (`offCanvas="always"`) pair it with `AppHeader.MenuButton` (`open` / `onOpenChange`). One current item at a time; give every top-level item an icon when the rail can go compact (child items need none).
+Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header, or `Sidebar.Toggle` in the footer for a rail without a brand. Inside an `AppShell` the Sidebar publishes its navigation to the shell: on phones (`offCanvas="auto"`) or always (`offCanvas="always"`) the page's `Page.TopBar` draws the menu button that opens the panel by itself, a `Sidebar.Toggle` outside the rail brings back a hidden one, and other triggers (a BottomNav «Ещё») read `useAppShellNav()`. One current item at a time; give every top-level item an icon when the rail can go compact (child items need none).
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | mode | `mode` / `defaultMode` | Root `data-mode`, `data-panel-mode` (the last visible mode while hidden); `<nav inert>` while hidden |
-| off-canvas | `offCanvas="always"`, or `"auto"` + viewport < 768px | Root `data-off-canvas`, `data-state="open" \| "closed"`; `<nav inert>` while closed |
+| off-canvas | `offCanvas="always"`, or `"auto"` + viewport < 768px | Root `data-off-canvas`, `data-state="open" \| "closed"`; `<nav inert>` while closed; the kit scrim (`role="presentation"`) while open; in an `AppShell` the shell Root `data-off-canvas` |
+| placing | the viewport crossed the off-canvas breakpoint (not a person's choice) | Root `data-placing` for one painted frame: the rail lands at its new width with no motion (no growing from 0, no folding rows, no sliding panel) |
+| dismiss | `closeOnOutsideClick`, `closeOnEscape` | a press on the scrim / Escape closes the open panel, or not |
 | current | `current` or a router's `aria-current` | Item `aria-current="page"`, `data-state="active"` |
 | active path | a child of a Sub (or an item of a Group) is current | SubTrigger (or the `…` row of a folded Group) `data-active-path`; a closed Sub opens, a closed Group opens off the compact rail |
 | group open | Group `open` / `defaultOpen` (`collapsible`) | heading `aria-expanded`; region `data-state`, `inert` while closed |
@@ -306,16 +312,16 @@ Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header,
 | persisted | `persistKey` on Root | the mode and the open state of collapsible groups and sub-lists are read from and written to `localStorage` |
 | disabled | `disabled` | Item `disabled` / `aria-disabled`, `data-disabled` |
 
-`persistKey` stores collapsible groups and sub-lists by their `id`, else by their label text — give an `id` when labels are translated or change. The stored state wins over `defaultMode` / `defaultOpen`; controlled `mode` / `open` are not stored, and unavailable storage is ignored.
+`persistKey` stores collapsible groups and sub-lists by their `id`, else by their label text — give an `id` when labels are translated or change. The stored state wins over `defaultMode` / `defaultOpen`; controlled `mode` / `open` are not stored, and unavailable storage is ignored. A hidden rail is stored as the mode it left, so a reload never strands a person on a hidden rail.
 
 On the active path a SubTrigger takes the current fill. On the compact rail a SubTrigger opens its flyout on hover after a short intent delay, as well as on click and from the keyboard.
 
-Leaving the narrow viewport closes the off-canvas panel; navigating from an `href` / `asChild` item (or the brand) closes it too. Navigating from a flyout closes the flyout.
+Leaving the narrow viewport closes the off-canvas panel; activating an item (a link, a button or an `asChild` element) or the brand closes it too, unless its `onClick` prevents the default. Activating an item in a flyout closes the flyout.
 
 ## Layout & spacing
 - Panel padding: `--prime-space-3` block, `--prime-space-2` inline; regions 8 apart; groups 16 apart, items 4 apart.
 - Item horizontal padding is derived from the compact width so icons and the brand logo sit on one axis in every mode (the account avatar joins that axis on the rail).
-- Header is one row of the item height + 8. The header toggle (xs, 28) sits at its end, 8 from the rail edge; in compact mode it moves half past the edge, scales to 3/4, turns round and gets a ring in the rail color. The root clips with `clip-path`, reaching past the edge by the toggle's half-width and ring beside the header only; everywhere else the panel ends exactly at the spacer edge.
+- Header is one row of the item height + 8. The header toggle (a disk of the compact tier: 28, 32 at `l` and `xl`) sits at its end, 8 from the rail edge; in compact mode it moves half past the edge, scales to 3/4 and gets a ring in the rail color. The root clips with `clip-path`, reaching past the edge by the toggle's half-width and ring beside the header only; everywhere else the panel ends exactly at the spacer edge.
 - Collapsible group: heading 28 high with the chevron (14) at its end, aligned with the item trail; items start 4 below. A folded group's attention dot sits before the chevron.
 - On the rail a heading keeps its 28 and its layout: the text slides 8 toward the edge, scales to 0.85 and is cut at the rail box with a 12 fade into the rail. A folded group adds one `…` row under its heading. The items and the row share one place: folding or unfolding on the rail glides the group's height one way (list ↔ row) while the two cross-fade, so the rows below never move back.
 - Sub-list: a 1px `border-default` guide line on the parent icon's centre; every child branches off it with an 8 elbow and a 6 bend; child labels line up with the parent label.
@@ -326,7 +332,7 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
   so the row is the avatar + 2 × gap high (48 at m). On the compact rail the start inset becomes the
   one that centres the avatar on the icon axis, as part of the rail motion.
 - Compact flyout: the kit Popover (flush) to the right, aligned with the parent row, with the metrics of a kit menu — rows of the tier's menu item height (32 at m), the panel padding, no title (the row names it), no guide line; current child is a `fill-subtle-active` wash.
-- Motion: two layers on one clock. `Sidebar.Root` is the spacer: it reserves the rail width in the page, paints the rail and clips the panel to its own box; its width is the only layout that moves (the page column follows). The `<nav>` panel inside is positioned at the expanded width in every mode and never lays out again, so nothing re-wraps and nothing switches at the end. Every part is a plain CSS transition over `base` with the `standard` (ease-in-out) easing, started by the same mode change and ending with the rail: text fades through its fill colour (paint-only, no compositor layer per label), chevrons through their stroke, trailing boxes (a coloured count, a key hint) through `opacity`; coloured counts turn into dots; the account avatar slides onto the icon axis; the header toggle rides the edge by `translate` / `scale`. Rows stay full width: a row with a fill or a ring (current, on the active path, hovered, open, focused) draws them on a pseudo-element whose end edge travels to the icon box and clips its content there, so it always ends rail padding before the moving edge and is a rounded square around the icon at rest. Group headings keep their height and layout: their text slides toward the edge and scales down by transform while the moving cut ends it with a fade; the text box narrows only once the rail has closed (under the cut, never seen), so the dot and the chevron after it stay in place and fade. The `…` row of a folded group grows in and out on the same clock (grid track height), as do the attention dots (opacity and scale). Hidden keeps the look of the last visible mode and is clipped as one piece; the header toggle stays at its place and fades, and coming back from hidden it fades in at its final place. Collapsible groups that open for the rail and sub-lists that close for it move on the same clock (grid track height); chevrons rotate (base). All durations are tokens: under reduced motion every mode change is instant.
+- Motion: two layers on one clock. `Sidebar.Root` is the spacer: it reserves the rail width in the page, paints the rail and clips the panel to its own box; its width is the only layout that moves (the page column follows). The `<nav>` panel inside is positioned at the expanded width in every mode and never lays out again, so nothing re-wraps and nothing switches at the end. Every part is a plain CSS transition over `base` with the `standard` (ease-in-out) easing, started by the same mode change and ending with the rail: text fades through its fill colour (paint-only, no compositor layer per label), chevrons through their stroke, trailing boxes (a coloured count, a key hint) through `opacity`; coloured counts turn into dots; the account avatar slides onto the icon axis; the header toggle rides the edge by `translate` / `scale`. Rows stay full width: a row with a fill or a ring (current, on the active path, hovered, open, focused) draws them on a pseudo-element whose end edge travels to the icon box and clips its content there, so it always ends rail padding before the moving edge and is a rounded square around the icon at rest. Group headings keep their height and layout: their text slides toward the edge and scales down by transform while the moving cut ends it with a fade; the text box narrows only once the rail has closed (under the cut, never seen), so the dot and the chevron after it stay in place and fade. The `…` row of a folded group grows in and out on the same clock (the kit fold), as do the attention dots (opacity and scale). Hidden keeps the look of the last visible mode and is clipped as one piece; the header toggle stays at its place and fades, and coming back from hidden it fades in at its final place. Collapsible groups that open for the rail and sub-lists that close for it move on the same clock (the kit fold, `Disclosure`); chevrons rotate (base); a group or a sub-list that opens for the current page on mount stands open, without motion. All durations are tokens: under reduced motion every mode change is instant.
 - Layers of a row on the rail (compact tooltips, the sub-list flyout, a `Dropdown` around `Sidebar.Account`) anchor to the visible part of the row — the icon box — not to its full-width box. The brand has no compact tooltip: the logo speaks for itself and a tooltip would cover the edge toggle.
 - Off-canvas panel width: min(sidebar width, 100% − `--prime-space-12`).
 - Inside `AppShell.Nav` the rail takes the full height. The root is `height: 100%` and the panel is
@@ -336,6 +342,8 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus through the items; a disabled or folded one is skipped. |
@@ -345,6 +353,8 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 | `Escape` | Closes the flyout (focus returns to the parent) and the off-canvas panel on a narrow screen. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The panel is a `<nav>` named by `labels.navigation`; groups are `role="group"` named by their label.
 - The current item has `aria-current="page"`; in compact mode the label shows as a tooltip, so icon-only items keep a visible name.
 - A collapsible group heading and a SubTrigger are buttons with `aria-expanded` and `aria-controls`; folded content is `inert`.
@@ -354,8 +364,8 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 - In compact mode the brand's name fades out but still names the link.
 - A row action is its own button next to the item (never nested), named by `label` with a tooltip.
 - The account avatar is hidden from screen readers; the name and the muted line name the button.
-- Off-canvas: scrim, focus trap and Escape; the scrim is a button labelled `labels.close`.
-- Toggle: `aria-expanded`, `aria-controls` → nav, label from `labels`.
+- Off-canvas: a decorative scrim (a press on it is a press outside, `closeOnOutsideClick`), focus trap and Escape (`closeOnEscape`); focus returns to the opener.
+- Toggle, the menu button of `Page.TopBar` and `useAppShellNav` triggers: `aria-expanded`, `aria-controls` → the `<nav>`, label from `labels`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -365,7 +375,7 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 | `navigation` | `"Навигация"` | `aria-label` of the `<nav>`. |
 | `collapse` | `"Свернуть панель"` | Toggle label while expanded. |
 | `expand` | `"Развернуть панель"` | Toggle label while compact or hidden. |
-| `close` | `"Закрыть навигацию"` | Toggle label off-canvas and the scrim label. |
+| `close` | `"Закрыть навигацию"` | Toggle label while the off-canvas panel is open. |
 
 ## Examples
 | Example | Shows |
@@ -377,12 +387,13 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 | [collapsible-groups.tsx](examples/collapsible-groups.tsx) | Group headings that fold their items away, one group open at a time, with a chevron at the end of the heading; on the compact rail a folded group becomes one row whose items open in a flyout — `collapsible`, `open`, `onOpenChange`. |
 | [nested-items.tsx](examples/nested-items.tsx) | A parent item with child items on a guide line: a current child opens it and marks the parent; on the compact rail the children open in a flyout — `Sidebar.Sub`, `Sidebar.SubTrigger`, `Sidebar.SubContent`. |
 | [account.tsx](examples/account.tsx) | Footer items and the collapse row above the signed-in person: avatar, name and email open the account menu; collapse the rail from that row and only the avatar stays, on the icon axis — `Sidebar.Footer`, `Sidebar.Account`, `description`, `Sidebar.Toggle`. |
-| [router.tsx](examples/router.tsx) | Router links as the brand and the items: the router sets `aria-current` and the item shows as current; render it inside a router — `asChild`. |
+| [router.tsx](examples/router.tsx) | Router links as the brand and the items: the router marks the current link and the item shows it as current; render it inside a router — `asChild`. |
 | [persist.tsx](examples/persist.tsx) | The first visit opens on the icon rail; the mode and the folded groups are remembered and come back after a reload — `persistKey`, `defaultMode`. |
 | [custom-part.tsx](examples/custom-part.tsx) | A part of your own in the footer reads the rail state: the storage meter shows on the full rail and in the off-canvas panel and steps aside on the icon rail — `useSidebar`. |
+| [dismiss.tsx](examples/dismiss.tsx) | An off-canvas panel only its own toggle closes: a press on the scrim and Escape leave it open, a picked item still closes it — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the rail mode: expanded, an icon rail with tooltips, or hidden; every switch is one synchronous movement — `mode`, `onModeChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | Navigation behind a menu button at any width: the parent opens the off-canvas panel, the scrim, Escape, the header toggle or a navigation closes it — `offCanvas`, `open`, `onOpenChange`. |
-| [narrow.tsx](examples/narrow.tsx) | Below 768px the rail leaves the layout and slides in over the page from the menu button; from 768px it is the rail again, and the button leaves — `offCanvas`, `labels`. |
+| [narrow.tsx](examples/narrow.tsx) | Below 768px the rail leaves the layout and slides in over the page from the menu button the page top bar draws by itself; from 768px it is the rail again, and the button leaves — `AppShell`, `labels`. |
 
 ## Mistakes
 - `icon={…}` / `badge={…}` props → use the `Sidebar.ItemIcon` and `Sidebar.ItemCount` parts.
@@ -401,5 +412,5 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 - Your own `localStorage` code for the rail mode → `persistKey` keeps the mode and the folded groups.
 
 ## Related
-- **Built from:** [ScrollContainer](../../components/scroll-container/COMPONENT.md), [Badge](../../components/badge/COMPONENT.md), [Tooltip](../../components/tooltip/COMPONENT.md), [Popover](../../components/popover/COMPONENT.md) (compact flyout), [Button](../../components/button/COMPONENT.md) (header toggle, row action), [Avatar](../../components/avatar/COMPONENT.md) slot, Icon (`nav.sidebarCollapse`, `nav.sidebarExpand`, `nav.chevronsLeft`, `nav.chevronDown`, `nav.chevronsUpDown`, `action.add`, `action.more`)
+- **Built from:** [AppShell](../app-shell/COMPONENT.md) (publishes the navigation), [ScrollContainer](../../components/scroll-container/COMPONENT.md), [Badge](../../components/badge/COMPONENT.md), [Tooltip](../../components/tooltip/COMPONENT.md), [Popover](../../components/popover/COMPONENT.md) (compact flyout), [Button](../../components/button/COMPONENT.md) (header toggle, row action), [Avatar](../../components/avatar/COMPONENT.md) slot, Icon (`nav.sidebarCollapse`, `nav.sidebarExpand`, `nav.chevronsLeft`, `nav.chevronDown`, `nav.chevronsUpDown`, `action.add`, `action.more`)
 - **See also:** [AppShell](../app-shell/COMPONENT.md), [Dropdown](../../components/dropdown/COMPONENT.md) (account menu), [Drawer](../../components/drawer/COMPONENT.md), [Kbd](../../components/kbd/COMPONENT.md)

package/dist/skill/reference/layout/sidebar/examples/account.tsx

@@ -10,9 +10,7 @@ export default function SidebarAccountExample() {
         <Sidebar.Header>
           <Sidebar.Brand href="#home" description="Отдел продаж">
             <Sidebar.BrandLogo>
-              <span className={styles.logo}>
-                <Icon name="nav.layoutGrid" />
-              </span>
+              <Icon name="nav.layoutGrid" />
             </Sidebar.BrandLogo>
             Прайм CRM
           </Sidebar.Brand>

package/dist/skill/reference/layout/sidebar/examples/brand-header.tsx

@@ -10,9 +10,7 @@ export default function SidebarBrandHeaderExample() {
         <Sidebar.Header>
           <Sidebar.Brand href="#home" description="Отдел продаж">
             <Sidebar.BrandLogo>
-              <span className={styles.logo}>
-                <Icon name="nav.layoutGrid" />
-              </span>
+              <Icon name="nav.layoutGrid" />
             </Sidebar.BrandLogo>
             Прайм CRM
           </Sidebar.Brand>

package/dist/skill/reference/layout/sidebar/examples/collapsible-groups.tsx

@@ -18,9 +18,7 @@ export default function SidebarCollapsibleGroupsExample() {
         <Sidebar.Header>
           <Sidebar.Brand href="#home" description="Отдел продаж">
             <Sidebar.BrandLogo>
-              <span className={styles.logo}>
-                <Icon name="nav.layoutGrid" />
-              </span>
+              <Icon name="nav.layoutGrid" />
             </Sidebar.BrandLogo>
             Прайм CRM
           </Sidebar.Brand>

package/dist/skill/reference/layout/sidebar/examples/controlled-open.tsx

@@ -13,9 +13,7 @@ export default function SidebarControlledOpenExample() {
         <Sidebar.Header>
           <Sidebar.Brand href="#home" description="Отдел продаж">
             <Sidebar.BrandLogo>
-              <span className={styles.logo}>
-                <Icon name="nav.layoutGrid" />
-              </span>
+              <Icon name="nav.layoutGrid" />
             </Sidebar.BrandLogo>
             Прайм CRM
           </Sidebar.Brand>

package/dist/skill/reference/layout/sidebar/examples/controlled.tsx

@@ -31,9 +31,7 @@ export default function SidebarControlledExample() {
           <Sidebar.Header>
             <Sidebar.Brand href="#home" description="Отдел продаж">
               <Sidebar.BrandLogo>
-                <span className={styles.logo}>
-                  <Icon name="nav.layoutGrid" />
-                </span>
+                <Icon name="nav.layoutGrid" />
               </Sidebar.BrandLogo>
               Прайм CRM
             </Sidebar.Brand>

package/dist/skill/reference/layout/sidebar/examples/custom-part.tsx

@@ -21,9 +21,7 @@ export default function SidebarCustomPartExample() {
         <Sidebar.Header>
           <Sidebar.Brand href="#home" description="Отдел продаж">
             <Sidebar.BrandLogo>
-              <span className={styles.logo}>
-                <Icon name="nav.layoutGrid" />
-              </span>
+              <Icon name="nav.layoutGrid" />
             </Sidebar.BrandLogo>
             Прайм CRM
           </Sidebar.Brand>

package/dist/skill/reference/layout/sidebar/examples/dismiss.tsx

@@ -0,0 +1,50 @@
+/** An off-canvas panel only its own toggle closes: a press on the scrim and Escape leave it open, a picked item still closes it — `closeOnOutsideClick`, `closeOnEscape`. */
+import { AppShell, Icon, Page, Sidebar } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function SidebarDismissExample() {
+  return (
+    <div className={styles.stage}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppShell.Nav>
+          <Sidebar.Root offCanvas="always" closeOnOutsideClick={false} closeOnEscape={false}>
+            <Sidebar.Header>
+              <Sidebar.Brand href="#home" description="Склад · смена 2">
+                <Sidebar.BrandLogo>
+                  <Icon name="object.package" />
+                </Sidebar.BrandLogo>
+                Терминал сборки
+              </Sidebar.Brand>
+              <Sidebar.Toggle variant="header" />
+            </Sidebar.Header>
+            <Sidebar.Content>
+              <Sidebar.Item href="#picking" current>
+                <Sidebar.ItemIcon>
+                  <Icon name="object.tasks" />
+                </Sidebar.ItemIcon>
+                Сборка заказов
+                <Sidebar.ItemCount>14</Sidebar.ItemCount>
+              </Sidebar.Item>
+              <Sidebar.Item href="#returns">
+                <Sidebar.ItemIcon>
+                  <Icon name="object.package" />
+                </Sidebar.ItemIcon>
+                Возвраты
+              </Sidebar.Item>
+            </Sidebar.Content>
+          </Sidebar.Root>
+        </AppShell.Nav>
+        <AppShell.Main>
+          <Page.Root>
+            <Page.TopBar>
+              <Page.Heading>
+                <Page.Title>Сборка заказов</Page.Title>
+              </Page.Heading>
+            </Page.TopBar>
+          </Page.Root>
+        </AppShell.Main>
+      </AppShell.Root>
+    </div>
+  );
+}

package/dist/skill/reference/layout/sidebar/examples/examples.module.css

@@ -1,4 +1,4 @@
-/* Layout for the Sidebar examples: small "app windows" (the page with a rail one layer above it). Semantic tokens only. */
+/* Layout for the Sidebar examples: small app windows. The preview stage is the page, the rail one layer above it; a window only sizes and clips. Semantic tokens only. */
 
 .stage {
   box-sizing: border-box;
@@ -6,12 +6,6 @@
   width: 100%;
   height: calc(var(--prime-space-24) * 4);
   overflow: hidden;
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-layer-current);
-  /* The window is a page on the preview's page: a hairline keeps its edge visible. */
-  box-shadow:
-    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
-    var(--prime-shadow-raised);
 }
 
 /* A window tall enough for a full rail: header, groups, footer and the account. */
@@ -24,22 +18,17 @@
   height: calc(var(--prime-space-24) * 2);
 }
 
-/* Content plane next to the rail, like AppShell: the page itself, edge to edge. */
+/* narrow.tsx: the app shell fills the window frame instead of the viewport. */
+.shell {
+  height: 100%;
+}
+
+/* The page plane next to the rail, like AppShell.Main. */
 .content {
   box-sizing: border-box;
   flex: 1 1 auto;
   min-width: 0;
   padding: var(--prime-space-4);
-  background: var(--prime-color-layer-current);
-}
-
-/* The product mark inside `Sidebar.BrandLogo`: an accent tile with a glyph. */
-.logo {
-  display: grid;
-  place-items: center;
-  border-radius: var(--prime-radius-m);
-  background: var(--prime-color-accent-default);
-  color: var(--prime-color-accent-fg);
 }
 
 /* custom-part.tsx: an own block in the footer, inset like the item labels. */
@@ -47,20 +36,6 @@
   padding: var(--prime-space-2);
 }
 
-.sizes {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(calc(var(--prime-space-24) * 2.5), 1fr));
-  gap: var(--prime-space-4);
-  width: 100%;
-}
-
-.sizeColumn {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-2);
-  min-width: 0;
-}
-
 .column {
   display: flex;
   flex-direction: column;