prime-ui-kit 0.15.0 → 0.16.0

package/dist/skill/reference/layout/app-header/COMPONENT.md

@@ -8,7 +8,8 @@
 ## When to use
 - Every page of an app built on [AppShell](../app-shell/COMPONENT.md): the page titles itself here — `AppHeader.Title` (the page's `<h1>`) with an `AppHeader.Description` that carries data, the path up (`Breadcrumb`) on a nested record.
 - The page's tools — its own search and filter, sections, the view, the primary action — as a [PageToolbar](../../components/page-toolbar/COMPONENT.md) in `AppHeader.Tools`.
-- The phone header: the menu button that opens the off-canvas Sidebar, the title, the page's action as an icon.
+- The phone header: in an `AppShell` whose Sidebar is off-canvas the header leads with the menu button that opens it by itself; the title and the page's action as an icon follow.
+- A page that owns its header: render `AppHeader.Root` at the top of the page — inside the shell it renders in the shell's header row and replaces `AppShell.Template`'s `header` while the page is on screen.
 
 ## When not to use
 - A document page (settings, a long form, an article) → its title is `PageContent.Header` in main ([PageContent](../../components/page-content/COMPONENT.md)); the header then has no title.
@@ -22,9 +23,9 @@ import { AppHeader } from "prime-ui-kit";
 
 ## Anatomy
 ```
-AppHeader.Root               <header>, the page's sticky row as high as the Sidebar brand row
+AppHeader.Root               <header>, the page's sticky bar; in an AppShell it renders in the shell's header row
 ├─ AppHeader.Start           leading zone, takes the free width
-│  ├─ AppHeader.MenuButton   opens the off-canvas Sidebar (below 768px by default)
+│  ├─ (menu button)          drawn while the shell's Sidebar is off-canvas; AppHeader.MenuButton places it elsewhere
 │  ├─ Breadcrumb             the path up, only on a nested record
 │  ├─ AppHeader.Separator    short vertical line between the path and the title
 │  └─ AppHeader.Title        the page title, truncates
@@ -40,7 +41,7 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### AppHeader.Root
-`ref` → `HTMLElement`. The page's sticky `<header>` bar at the top of the content panel: only what the current page needs — its title, tools and own buttons. As high as the Sidebar brand row, lined up with the page. Icon buttons inside are `soft`, not `ghost`.
+`ref` → `HTMLElement`. The page's sticky `<header>`: its title, tools and own buttons. In an `AppShell` it renders in the shell's header row and, while the Sidebar is off-canvas, leads with the menu button. Icon buttons inside are `soft`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -76,14 +77,14 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 | `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
 ### AppHeader.Separator
-`ref` → `HTMLDivElement`. A short vertical `Divider` (20) between groups in a zone — the path and the title — with 16 of air on each side.
+`ref` → `HTMLDivElement`. The `inset` vertical `Divider` between groups in a zone — the path and the title: one text line tall, the tier gap on each side.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `…rest` | `Omit<DividerProps, "orientation" \| "children">` | — | `className` and the other div attributes. |
+| `…rest` | `Omit<DividerProps, "orientation" \| "children" \| "align" \| "size" \| "inset">` | — | `className` and the other div attributes. |
 
 ### AppHeader.Tools
-`ref` → `HTMLDivElement`. The page's tools in the header (a `PageToolbar.Root`): the header's second row, full width under the title row, wherever it is written.
+`ref` → `HTMLDivElement`. The page's tools in the header (a `PageToolbar.Root`): the header's second row, full width under the title row, wherever it is written in `AppHeader.Root` — directly, in a fragment or inside a component of the page.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -97,21 +98,14 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### AppHeader.MenuButton
-`ref` → `HTMLButtonElement`. A soft neutral icon `Button` named by `labels.menu` that opens the off-canvas Sidebar; wire `onClick` and `aria-expanded`.
+`ref` → `HTMLButtonElement`. The menu button the header draws by itself, placed elsewhere: a soft icon `Button` named by `labels.menu` that opens the shell's off-canvas Sidebar. Nothing while the Sidebar is a rail, or outside a shell.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `show` | `"narrow" \| "always"` | `"narrow"` | `narrow` — only below 768px, where a Sidebar with `offCanvas="auto"` leaves the layout; `always` — on every width (`offCanvas="always"`). |
-| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `aria-expanded`, `aria-label` (replaces `labels.menu`), `className` and the other button attributes. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children" \| "aria-expanded" \| "aria-controls">` | — | `onClick` (runs first; `preventDefault()` stops the toggle), `aria-label` (replaces `labels.menu`), `className` and the other button attributes. |
 
 ## Variants
 
-### show (MenuButton)
-| Value | Looks like | Use when | Default |
-|---|---|---|---|
-| `narrow` | The menu button shows only below 768px | Sidebar with `offCanvas="auto"` | yes |
-| `always` | The menu button on every width | Sidebar with `offCanvas="always"`, or you decide visibility yourself | |
-
 ### Structure
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -120,20 +114,22 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 | with `AppHeader.Actions` | A row of the page's buttons at the end of the title row | Export, a more menu of the page | |
 | with `AppHeader.Tools` | A second row under the title row with the page's PageToolbar | The page has search, filters, sections, a view or a primary action | |
 | no `AppHeader.Title` | Only the menu button and the page's buttons | A document page: its title is `PageContent.Header` in main | |
+| with `AppHeader.MenuButton` | The menu button at the place of the part instead of the start | The button belongs elsewhere in the bar (after a back button, in Actions) | |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| with page tools | an `AppHeader.Tools` child | Root renders it after the title row (DOM and Tab order follow the rows), full width, `--prime-space-3` under it |
+| in an app shell | `AppHeader.Root` anywhere inside `AppShell.Root` (a page's own one in main) | renders in the shell's header row at the top of the panel; the latest one on screen wins over `AppShell.Template`'s `header` |
+| with the menu button | the shell's Sidebar is off-canvas (`offCanvas="auto"` on a phone, `"always"`) | a soft icon Button leads `AppHeader.Start` (or the row) with `aria-expanded` and `aria-controls` from the shell; gone while the Sidebar is a rail on screen and outside a shell |
+| with page tools | an `AppHeader.Tools` anywhere in Root (directly, in a fragment, inside a component of the page) | rendered after the title row (DOM and Tab order follow the rows), full width, `--prime-space-3` under it |
 | narrow header | header width below 36rem (container `prime-app-header`) | the icon tile hides; the title and its line of data truncate |
-| menu button hidden | `show="narrow"` and viewport from 768px | `data-show="narrow"` on MenuButton |
 | short viewport | viewport below 480px high (a phone on its side) | Root stops sticking |
 
 ## Layout & spacing
 - Row min height = control m + `--prime-space-2` (44), padding-block `--prime-space-3` (the top grows to the safe-area inset): 68 in all, the height of the Sidebar header, so the brand and the title share one line.
-- Inline padding: the shell gutters (16 → 24 → 32, the same as `AppShell.Main`) in the shell's panel, so the header lines up with the page; `--prime-space-4` elsewhere. Main's top air (24, 32 from 1024px) stands between the header and the page's first block.
-- Icon buttons are `soft` neutral (MenuButton is), never `ghost`: every button on the bar has a shape.
-- Gaps: `--prime-space-3` between zones, `--prime-space-2` inside Start and Actions; `AppHeader.Separator` adds `--prime-space-2` on each side (16 in all) and is 20 high.
+- Inline padding: the page gutter `--prime-layout-gutter` (16 → 24 → 32, the same as `AppShell.Main`), so in the shell's header row the header lines up with the page; in a frame inside the page (a preview) the small gutter. Main's top air ([AppShell](../app-shell/COMPONENT.md)) stands between the header and the page's first block.
+- Icon buttons are `soft` neutral (the menu button is), never `ghost`: every button on the bar has a shape.
+- Gaps: `--prime-space-3` between zones, `--prime-space-2` inside Start and Actions; `AppHeader.Separator` is the `inset` vertical Divider: the tier gap on each side (8 at `m`) and one text line tall (20 at `m`).
 - `AppHeader.Icon` is a 36 tile with the radius and fill of a soft neutral button m, so it lines up with the buttons on the bar.
 - On the panel surface with no divider or shadow (depth from fill); `z-index: --prime-z-sticky`.
 - Sticky at `top: 0` of its scroller (static on a viewport below 480px high). The shared sticky surface paints its fill one border width past the top edge, so no sub-pixel seam of the scrolling rows shows above it.
@@ -143,14 +139,18 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves through the menu button, the path links and the page's buttons in reading order, then the page tools in the second row. |
 | `Enter` · `Space` | Presses the focused button: opens the menu or runs the action. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Root is a `<header>`: the banner landmark when it sits at the top level of the page.
-- MenuButton is named by `labels.menu`; pass `aria-expanded` (whether the Sidebar is open).
+- The menu button is named by `labels.menu`; `aria-expanded` (whether the Sidebar panel is open) and `aria-controls` (its `<nav>`) come from the shell.
 - The name of `AppHeader.Title` is the page heading `<h1>`; the description sits next to it, outside its accessible name. One `<h1>` per page: in the header on app pages, `PageContent.Title` on a document page (whose header has no title).
 - `AppHeader.Tools` follows the title row in the DOM, so Tab and screen readers meet the page tools after the header's own buttons.
 
@@ -159,7 +159,7 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 
 | Key | Default | Used for |
 |---|---|---|
-| `menu` | `"Открыть меню"` | Name of `AppHeader.MenuButton`. |
+| `menu` | `"Открыть меню"` | Name of the menu button (drawn by the header or `AppHeader.MenuButton`). |
 
 ## Examples
 | Example | Shows |
@@ -168,7 +168,7 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 | [breadcrumbs.tsx](examples/breadcrumbs.tsx) | A nested record: the path up, a separator and the record as the page title, the record's buttons at the end — `AppHeader.Separator`, `AppHeader.Actions`. |
 | [page-title.tsx](examples/page-title.tsx) | The header carries the page: the title is the page heading with a line of data, the page tools (sections, the period, the primary action) are its second row and lay themselves out from its width — `AppHeader.Title`, `AppHeader.Tools`. |
 | [in-app-shell.tsx](examples/in-app-shell.tsx) | The header in the app frame: one row with the Sidebar brand across the two planes, sticky over main — `AppShell`, `Sidebar.Brand`. |
-| [narrow.tsx](examples/narrow.tsx) | On a phone: the menu button opens the navigation, the title and its line of data truncate and the page's action keeps its icon — `AppHeader.MenuButton`, `show`. |
+| [narrow.tsx](examples/narrow.tsx) | On a phone the header leads with the menu button that opens the navigation by itself, the title and its line of data truncate and the page's action keeps its icon — `AppShell`, `offCanvas`. |
 
 ## Mistakes
 - A border or shadow under the header → it sits on the panel surface; the fill is the boundary.
@@ -178,9 +178,10 @@ The name of `AppHeader.Title` (not the icon or the description) is the page's `<
 - Page tools crammed into `AppHeader.Actions` → `AppHeader.Tools` with a PageToolbar: it wraps under the title instead of squeezing it.
 - A global search, notifications or app-wide buttons in the header → the row is per page; the app's own places live in the Sidebar.
 - A heading element of your own inside `AppHeader.Title` → the title's name is already the `<h1>`; a second heading nests inside it.
-- A hand-made menu button with a media query → `AppHeader.MenuButton` follows the Sidebar breakpoint.
+- A hand-made menu button with a media query or hand-wired `aria-expanded` → the header draws the menu button itself from the shell's Sidebar; `AppHeader.MenuButton` only moves it.
+- A page header that misses the phone menu → render the page's `AppHeader.Root` inside the `AppShell` (not in a frame of its own): it then joins the shell's header row and gets the menu button.
 - `ghost` icon buttons in the header → `variant="soft" tone="neutral"`: a light fill gives each button a shape on the bar.
 
 ## Related
-- **Built from:** [Button](../../components/button/COMPONENT.md), [Divider](../../components/divider/COMPONENT.md), Icon (`nav.menu`)
+- **Built from:** [Button](../../components/button/COMPONENT.md), [Divider](../../components/divider/COMPONENT.md), Icon (`nav.menu`), [AppShell](../app-shell/COMPONENT.md) (its header row and navigation)
 - **See also:** [AppShell](../app-shell/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [PageContent](../../components/page-content/COMPONENT.md), [PageToolbar](../../components/page-toolbar/COMPONENT.md) (inside `AppHeader.Tools`), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)

package/dist/skill/reference/layout/app-header/examples/examples.module.css

@@ -1,20 +1,15 @@
-/* Layout of the AppHeader scenarios: an app window and a phone-wide screen. Semantic tokens only. */
+/* Layout of the AppHeader scenarios: app windows and a phone-wide screen. The preview stage is the page; a window only sizes and clips. Semantic tokens only. */
 
-/* The top of an app window: the content panel (the page) with the header on it. */
+/* The top of an app window: the page with the header on it. */
 .window {
   box-sizing: border-box;
   width: 100%;
   overflow: hidden;
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-layer-current);
-  box-shadow:
-    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
-    var(--prime-shadow-raised);
 }
 
-/* narrow.tsx: the same window, phone-wide, so the title and its line of data truncate. */
+/* narrow.tsx: an app window, phone-wide, so the title and its line of data truncate. */
 .phone {
-  width: min(100%, var(--prime-drawer-width-s));
+  width: min(100%, var(--prime-layout-narrow-width));
   margin-inline: auto;
 }
 
@@ -25,23 +20,9 @@
   width: 100%;
   height: calc(var(--prime-space-24) * 4);
   overflow: hidden;
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-layer-current);
-  box-shadow:
-    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
-    var(--prime-shadow-raised);
 }
 
 /* The shell fills the window frame instead of the viewport. */
 .shell {
   height: 100%;
 }
-
-/* 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);
-}

package/dist/skill/reference/layout/app-header/examples/in-app-shell.tsx

@@ -21,9 +21,7 @@ export default function AppHeaderInAppShellExample() {
             <Sidebar.Header>
               <Sidebar.Brand href="#home" description="Отдел продаж">
                 <Sidebar.BrandLogo>
-                  <span className={styles.logo}>
-                    <Icon name="nav.layoutGrid" />
-                  </span>
+                  <Icon name="nav.layoutGrid" />
                 </Sidebar.BrandLogo>
                 Acme CRM
               </Sidebar.Brand>
@@ -53,7 +51,7 @@ export default function AppHeaderInAppShellExample() {
           </AppHeader.Start>
         </AppHeader.Root>
         <AppShell.Main>
-          <PageContent.Page>
+          <PageContent.Root as="section">
             <PageContent.Body>
               {ORDERS.map((order) => (
                 <Typography key={order} variant="body-m">
@@ -61,7 +59,7 @@ export default function AppHeaderInAppShellExample() {
                 </Typography>
               ))}
             </PageContent.Body>
-          </PageContent.Page>
+          </PageContent.Root>
         </AppShell.Main>
       </AppShell.Root>
     </div>

package/dist/skill/reference/layout/app-header/examples/narrow.tsx

@@ -1,28 +1,66 @@
-/** On a phone: the menu button opens the navigation, the title and its line of data truncate and the page's action keeps its icon — `AppHeader.MenuButton`, `show`. */
-import { AppHeader, Button, Icon } from "prime-ui-kit";
+/** On a phone the header leads with the menu button that opens the navigation by itself, the title and its line of data truncate and the page's action keeps its icon — `AppShell`, `offCanvas`. */
+import { AppHeader, AppShell, Button, Icon, PageContent, Sidebar, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
+const ORDERS = [
+  "№ 4821 · ООО «Север» · 84 000 ₽",
+  "№ 4820 · ИП Котов · 12 500 ₽",
+  "№ 4819 · ООО «Вектор» · 230 000 ₽",
+];
+
 export default function AppHeaderNarrowExample() {
   return (
-    <div className={`${styles.window} ${styles.phone}`}>
-      <AppHeader.Root>
-        <AppHeader.Start>
-          {/* `always`: this frame is phone-wide on any screen; in an app keep the default `narrow`. */}
-          <AppHeader.MenuButton show="always" aria-expanded={false} />
-          <AppHeader.Title>
-            Заказы покупателей
-            <AppHeader.Description>128 в работе · 6 ждут оплаты · 2 возврата</AppHeader.Description>
-          </AppHeader.Title>
-        </AppHeader.Start>
-        <AppHeader.Actions>
-          <Button.Root aria-label="Новый заказ">
-            <Button.Icon>
-              <Icon name="action.add" />
-            </Button.Icon>
-          </Button.Root>
-        </AppHeader.Actions>
-      </AppHeader.Root>
+    <div className={`${styles.stage} ${styles.phone}`}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppShell.Nav>
+          {/* `always`: this window is phone-wide on any screen; in an app keep the default `auto`. */}
+          <Sidebar.Root offCanvas="always">
+            <Sidebar.Content>
+              <Sidebar.Item href="#overview">
+                <Sidebar.ItemIcon>
+                  <Icon name="nav.home" />
+                </Sidebar.ItemIcon>
+                Обзор
+              </Sidebar.Item>
+              <Sidebar.Item href="#orders" current>
+                <Sidebar.ItemIcon>
+                  <Icon name="object.package" />
+                </Sidebar.ItemIcon>
+                Заказы
+              </Sidebar.Item>
+            </Sidebar.Content>
+          </Sidebar.Root>
+        </AppShell.Nav>
+        <AppHeader.Root>
+          <AppHeader.Start>
+            <AppHeader.Title>
+              Заказы покупателей
+              <AppHeader.Description>
+                128 в работе · 6 ждут оплаты · 2 возврата
+              </AppHeader.Description>
+            </AppHeader.Title>
+          </AppHeader.Start>
+          <AppHeader.Actions>
+            <Button.Root aria-label="Новый заказ">
+              <Button.Icon>
+                <Icon name="action.add" />
+              </Button.Icon>
+            </Button.Root>
+          </AppHeader.Actions>
+        </AppHeader.Root>
+        <AppShell.Main>
+          <PageContent.Root as="section">
+            <PageContent.Body>
+              {ORDERS.map((order) => (
+                <Typography key={order} variant="body-m">
+                  {order}
+                </Typography>
+              ))}
+            </PageContent.Body>
+          </PageContent.Root>
+        </AppShell.Main>
+      </AppShell.Root>
     </div>
   );
 }

package/dist/skill/reference/layout/app-shell/COMPONENT.md

@@ -11,7 +11,7 @@
 
 ## 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) as a child of Root.
+- 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).
 - 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,19 +25,20 @@ 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)
-├─ AppHeader.Root            sticky top bar of the panel (a separate component)
+├─ (header row)              the panel's top: the latest AppHeader.Root in the shell renders here
 ├─ AppShell.Main             <main>, scrolls, carries the gutters
 └─ AppShell.Footer           sticky bottom bar of the panel (usually BottomNav.Root)
 AppShell.Template            Root + Nav + the header + 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.
+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.
 
 ## 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 (Sidebar, a surface one layer above the page) and the content panel (the page itself); every child that is not `AppShell.Nav` goes into the panel.
+`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.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -71,14 +72,36 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 
 | 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 top bar of the panel, an `AppHeader.Root`; no header when omitted. |
+| `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`). |
 | `scrollResetKey` | `unknown` | — | Main scrolls back to the top whenever this value changes; pass the router pathname. |
 | `children` | `ReactNode` | — | Page content inside Main. |
 | `…rest` | `Omit<AppShellRootProps, "children">` | — | Root props: `fillViewport`, `className` and the div attributes. |
 
+### Types
+
+#### `AppShellNavState`
+The navigation of the shell, as its Sidebar publishes it.
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `navId` | `string` | — | `id` of the navigation landmark, for `aria-controls`. |
+| `offCanvas` | `boolean` | — | The navigation is an off-canvas panel now (a phone, or `offCanvas="always"`). |
+| `open` | `boolean` | — | The off-canvas panel is open. |
+| `setOpen` | `(open: boolean) => void` | — | Opens or closes the off-canvas panel. |
+| `expanded` | `boolean` | — | The navigation is in view: the off-canvas panel open, or the rail expanded. |
+| `toggle` | `() => void` | — | Opens or closes the off-canvas panel; on screen, expands or folds the rail. |
+
+### Functions
+
+#### `useAppShellNav()`
+`() => AppShellNavState \| null`
+
+The navigation of the nearest `AppShell.Root` for a trigger outside the rail (a BottomNav «Ещё», an own menu button); `null` outside a shell or without a Sidebar in it.
+
 ## Variants
 
 ### fillViewport (Root)
@@ -98,7 +121,7 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 |---|---|---|---|
 | 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 at the top of the panel | The page title (or the path and the record), the page's tools and buttons, the mobile menu button | |
+| 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.
@@ -109,11 +132,13 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 | 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 an `AppHeader.Root` in the panel): `--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`. Children of Main start from their own gutters, not the shell's.
+- 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 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.
@@ -124,11 +149,15 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 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>`).
-- Give the page one `<h1>` (PageContent.Title).
+- One `<h1>` per page: `AppHeader.Title` on app pages, `PageContent.Title` on a document page (whose header then has no title).
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -141,8 +170,8 @@ No `labels`.
 | [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`. |
 | [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` with `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, the AppHeader with the menu button, the page title with a line of data, and a simple home page that swaps with the current section — `fillViewport`, `scrollResetKey`. |
+| [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`. |
 
 ## Mistakes
 - Adding padding around the page content → Main already has the gutters.
@@ -151,6 +180,7 @@ No `labels`.
 - 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()`.
 
 ## Related
 - **Built from:** [ScrollContainer](../../components/scroll-container/COMPONENT.md)

package/dist/skill/reference/layout/app-shell/examples/examples.module.css

@@ -1,4 +1,4 @@
-/* Layout for the AppShell examples: a small "app window" frame. Semantic tokens only. */
+/* Layout for the AppShell examples: a small app window. The preview stage is the page; the window only sizes and clips. Semantic tokens only. */
 
 .stage {
   box-sizing: border-box;
@@ -6,21 +6,6 @@
   width: 100%;
   height: calc(var(--prime-space-24) * 5);
   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);
-}
-
-/* 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);
 }
 
 /* The shell fills the window frame instead of the viewport. */
@@ -32,13 +17,8 @@
 .phone {
   box-sizing: border-box;
   display: flex;
-  width: min(100%, var(--prime-drawer-width-s));
+  width: min(100%, var(--prime-layout-narrow-width));
   height: calc(var(--prime-space-24) * 5);
   margin-inline: auto;
   overflow: hidden;
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-layer-current);
-  box-shadow:
-    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
-    var(--prime-shadow-raised);
 }

package/dist/skill/reference/layout/app-shell/examples/footer.tsx

@@ -31,7 +31,7 @@ export default function AppShellFooterExample() {
           </AppHeader.Start>
         </AppHeader.Root>
         <AppShell.Main>
-          <PageContent.Page>
+          <PageContent.Root as="section">
             <PageContent.Body>
               {INVOICES.map((invoice) => (
                 <Typography key={invoice} variant="body-m">
@@ -39,7 +39,7 @@ export default function AppShellFooterExample() {
                 </Typography>
               ))}
             </PageContent.Body>
-          </PageContent.Page>
+          </PageContent.Root>
         </AppShell.Main>
         <AppShell.Footer>
           <BottomNav.Root>

package/dist/skill/reference/layout/app-shell/examples/overview.tsx

@@ -13,9 +13,7 @@ export default function AppShellOverviewExample() {
             <Sidebar.Header>
               <Sidebar.Brand href="#home" description="Отдел продаж">
                 <Sidebar.BrandLogo>
-                  <span className={styles.logo}>
-                    <Icon name="nav.layoutGrid" />
-                  </span>
+                  <Icon name="nav.layoutGrid" />
                 </Sidebar.BrandLogo>
                 Acme CRM
               </Sidebar.Brand>
@@ -54,13 +52,13 @@ export default function AppShellOverviewExample() {
           </AppHeader.Actions>
         </AppHeader.Root>
         <AppShell.Main>
-          <PageContent.Page>
+          <PageContent.Root as="section">
             <PageContent.Body>
               <Typography variant="body-m" tone="secondary">
                 Выручка за месяц — 4,8 млн ₽, на 12% больше, чем в сентябре.
               </Typography>
             </PageContent.Body>
-          </PageContent.Page>
+          </PageContent.Root>
         </AppShell.Main>
       </AppShell.Root>
     </div>