prime-ui-kit 0.15.0 → 0.16.0

package/src/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/src/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/src/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/src/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/src/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/src/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>

package/src/layout/app-shell/examples/screen.tsx

@@ -1,4 +1,4 @@
-/** 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`. */
+/** 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`. */
 import {
   AppHeader,
   AppShell,
@@ -11,6 +11,7 @@ import {
   PageContent,
   Sidebar,
   Typography,
+  useAppShellNav,
 } from "prime-ui-kit";
 import * as React from "react";
 
@@ -92,19 +93,33 @@ const PAGES: Record<Exclude<SectionId, "today">, { description: string; rows: Ro
 
 const isMore = (id: SectionId) => MORE.some((section) => section.id === id);
 
+/** «Ещё» opens the Sidebar as a panel: it reads the shell's navigation, so it renders inside the shell. */
+function MoreItem({ current }: { current: boolean }) {
+  const nav = useAppShellNav();
+  return (
+    <BottomNav.Item
+      current={current}
+      aria-expanded={nav?.open}
+      aria-controls={nav?.navId}
+      onClick={() => nav?.setOpen(true)}
+    >
+      <BottomNav.ItemIcon>
+        <Icon name="action.more" />
+      </BottomNav.ItemIcon>
+      Ещё
+    </BottomNav.Item>
+  );
+}
+
 export default function AppShellScreenExample() {
   const [current, setCurrent] = React.useState<SectionId>("today");
-  const [menuOpen, setMenuOpen] = React.useState(false);
   const [done, setDone] = React.useState<ReadonlySet<string>>(() => new Set(["t1"]));
 
   const openTasks = TASKS.length - done.size;
   const section = SECTIONS.find((item) => item.id === current) ?? SECTIONS[0];
 
-  // One handler for every way into a section: the Sidebar and the bar.
-  const go = (id: SectionId) => {
-    setCurrent(id);
-    setMenuOpen(false);
-  };
+  // One handler for every way into a section: the Sidebar (an item closes its panel) and the bar.
+  const go = (id: SectionId) => setCurrent(id);
 
   const toggleTask = (id: string, checked: boolean) =>
     setDone((prev) => {
@@ -137,7 +152,7 @@ export default function AppShellScreenExample() {
       fillViewport
       scrollResetKey={current}
       nav={
-        <Sidebar.Root open={menuOpen} onOpenChange={setMenuOpen}>
+        <Sidebar.Root>
           <Sidebar.Header>
             <Sidebar.Brand description="Отдел продаж">
               <Sidebar.BrandLogo>
@@ -155,8 +170,8 @@ export default function AppShellScreenExample() {
       }
       header={
         <AppHeader.Root>
+          {/* On a phone the header leads with the menu button that opens the Sidebar by itself. */}
           <AppHeader.Start>
-            <AppHeader.MenuButton aria-expanded={menuOpen} onClick={() => setMenuOpen(true)} />
             {/* Every page titles itself here: the only h1 and a line of data under it. */}
             <AppHeader.Title>
               {section.label}
@@ -183,22 +198,13 @@ export default function AppShellScreenExample() {
             </BottomNav.Item>
           ))}
           {/* The rest of the map lives in the Sidebar: «Ещё» opens it as a panel. */}
-          <BottomNav.Item
-            current={isMore(current)}
-            aria-expanded={menuOpen}
-            onClick={() => setMenuOpen(true)}
-          >
-            <BottomNav.ItemIcon>
-              <Icon name="action.more" />
-            </BottomNav.ItemIcon>
-            Ещё
-          </BottomNav.Item>
+          <MoreItem current={isMore(current)} />
         </BottomNav.Root>
       }
     >
       {/* Another section is another page: it cross-fades instead of flipping. */}
       <Crossfade state={current}>
-        <PageContent.Page>
+        <PageContent.Root as="section">
           <PageContent.Body>
             {current === "today" ? (
               <>
@@ -255,7 +261,7 @@ export default function AppShellScreenExample() {
               </Card.Root>
             )}
           </PageContent.Body>
-        </PageContent.Page>
+        </PageContent.Root>
       </Crossfade>
     </AppShell.Template>
   );

package/src/layout/app-shell/examples/template.tsx

@@ -1,4 +1,4 @@
-/** Root, nav, header and main in one component; main scrolls back to the top whenever the page changes — `AppShell.Template` with `scrollResetKey`. */
+/** Root, nav, header and main in one component; main scrolls back to the top whenever the page changes — `AppShell.Template`, `scrollResetKey`. */
 import { AppHeader, AppShell, Icon, PageContent, Sidebar, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -61,13 +61,13 @@ export default function AppShellTemplateExample() {
           </AppHeader.Root>
         }
       >
-        <PageContent.Page>
+        <PageContent.Root as="section">
           <PageContent.Body>
             <Typography variant="body-m" tone="secondary">
               {page.note}
             </Typography>
           </PageContent.Body>
-        </PageContent.Page>
+        </PageContent.Root>
       </AppShell.Template>
     </div>
   );

package/src/layout/bottom-nav/COMPONENT.md

@@ -21,7 +21,7 @@ import { BottomNav } from "prime-ui-kit";
 
 ## Anatomy
 ```
-BottomNav.Root                 <nav>, safe-area inset below
+BottomNav.Root                 <nav>, safe-area inset below; the bar is a switcher row
 ├─ BottomNav.Item              <button>, <a href> or the asChild element, in the bar
 │  ├─ BottomNav.ItemIcon       the glyph above the label (aria-hidden)
 │  ├─ BottomNav.ItemCount      Badge on the icon corner
@@ -34,7 +34,7 @@ BottomNav.Root                 <nav>, safe-area inset below
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### BottomNav.Root
-`ref` → `HTMLElement`. The `<nav>`: the bar of items in equal columns and the actions beside it. Inside `AppShell.Footer` it shows only while no Sidebar rail is on screen.
+`ref` → `HTMLElement`. The `<nav>`: the bar of items in equal columns — a switcher row that scrolls when they do not fit — and the actions beside it. Inside `AppShell.Footer` it shows only while no Sidebar rail is on screen.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -48,12 +48,14 @@ BottomNav.Root                 <nav>, safe-area inset below
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `current` | `boolean` | `false` | Current section: `aria-current="page"`; the icon and the label turn primary (the others are muted); floating, the item is in the accent on the selection capsule (the others in full ink). |
+| `current` | `boolean` | `false` | Current section: `aria-current="page"`; the icon and the label turn primary (the others are muted) and the glyph sits on a soft pill; floating, the item is in the accent on the selection capsule (the others in full ink). |
 | `disabled` | `boolean` | `false` | Not interactive: `disabled` / `aria-disabled`, `data-disabled`, out of the Tab order; an `href` link loses its `href`, an `asChild` child keeps its own and only its clicks are blocked. |
 | `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` | — | `BottomNav.ItemIcon`, an optional `BottomNav.ItemCount` and a short label (one word). |
-| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `aria-*`, `className` and the other attributes. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `onClick`, `aria-*`, `className` and the other attributes. |
 
 ### BottomNav.ItemIcon
 `ref` → `HTMLSpanElement`. The item glyph (`aria-hidden`, 20) above the label.
@@ -74,7 +76,7 @@ BottomNav.Root                 <nav>, safe-area inset below
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "color">` | — | `className` and the other span attributes. |
 
 ### BottomNav.Action
-`ref` → `HTMLButtonElement`. A Button `shape="circle"` (`l`, neutral solid) beside the bar for the screen's main action. Placed before the first item it stands at the start, otherwise at the end.
+`ref` → `HTMLButtonElement`. A Button `shape="circle"` (`l`, neutral; `solid` beside the flat bar, `glass` as tall as the floating capsule) for the screen's main action. Placed before the first item it stands at the start, otherwise at the end.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -84,12 +86,12 @@ BottomNav.Root                 <nav>, safe-area inset below
 
 ## Variants
 
-Two item states only — current and not; no hover fill. Flat: current in the primary color, the others muted. Floating (as iOS): current in the accent on the selection capsule, the others in full ink.
+Two item states only — current and not; no hover fill. Flat: current in the primary color with its glyph on a soft pill, the others muted. Floating (as iOS): current in the accent on the selection capsule, the others in full ink.
 
 ### Flags (Root)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `floating` | a glass capsule over the content across the width: translucent fill, backdrop blur, glass rim, a selection capsule under the current item; an action becomes a glass disk beside it | the app's look wants depth over the page, the iOS tab-bar feel | `false` |
+| `floating` | a glass capsule over the content across the width: translucent fill, backdrop blur, glass rim, a selection capsule under the current item; an action becomes a Button `glass` disk beside it | the app's look wants depth over the page, the iOS tab-bar feel | `false` |
 | `iconOnly` | icons alone; labels visually hidden, still the items' names | sections with unmistakable icons | `false` |
 
 Without flags the bar is flat at the screen edge on the surface, with a faint top divider.
@@ -97,41 +99,49 @@ Without flags the bar is flat at the screen edge on the surface, with a faint to
 ### Flags (Item)
 | Flag | Part | Effect |
 |---|---|---|
-| `current` | Item | `aria-current="page"`, icon and label in the primary color (floating: the accent, on the selection capsule) |
+| `current` | Item | `aria-current="page"`, icon and label in the primary color, the glyph on a soft pill (floating: the accent, on the selection capsule) |
 | `disabled` | Item | not interactive, disabled text color |
 | `asChild` | Item | the child element (router link) is the item |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| current | `current` or a router link setting `aria-current` | `aria-current="page"` on the item |
+| current | `current` or a router link setting `aria-current` | `aria-current="page"` on the item; flat, its glyph on a `fill-muted` pill |
+| pressed | pointer down | the glyph scales to `--prime-motion-press-scale-compact` (`internal/press`), flat and floating |
+| overflow | items wider than the bar | the items scroll inside the bar with faded edges; no label is cut |
 | focus | keyboard | focus ring inside the item edge |
 | disabled | `disabled` | `disabled` / `aria-disabled`, `data-disabled` |
 | hidden | inside `AppShell.Footer` while the Sidebar rail is on screen (`AppShell.Nav` without an off-canvas Sidebar) | `display: none` on the footer |
 | floating / icon only | `floating` / `iconOnly` | `data-floating="true"` / `data-icon-only="true"` on the `<nav>` |
 | selection | floating, an item with `aria-current` | the selection capsule `data-visible="true"`, `data-animate="true"` while it glides |
-| less transparency | `prefers-reduced-transparency: reduce` | a floating capsule and action turn opaque (`--prime-color-layer-floating-bg`), no blur |
+| less transparency | `prefers-reduced-transparency: reduce` | a floating capsule and action turn opaque (`--prime-color-bg-glass-solid`), no blur |
+| touch | a coarse pointer | floating items are rows at least the touch target high (`touchTargetRowClass`); the capsule and the action grow to hold them |
 
-Motion: the color of the icon and the label changes over `fast`. Floating, the selection capsule glides to the item that becomes current (`left` / `width` over `base`, emphasized easing — it follows `aria-current`, so a router link moves it too), snaps on a layout change (resize, fonts, new items) and fades when nothing is current; a pressed item's glyph and the action give under the finger (press scale). All instant under reduced motion.
+Motion: the color of the icon and the label and the flat pill change over `fast`. Floating, the selection capsule (the shared selection indicator) glides to the item that becomes current (`left` / `width` over `base`, emphasized easing — it follows `aria-current`, so a router link moves it too), snaps on a layout change (resize, fonts, new items) and fades when nothing is current; a pressed item's glyph and the action give under the finger (press scale). All instant under reduced motion.
 
 ## Layout & spacing
 - Bar `--prime-bottom-nav-height` (52) plus `env(safe-area-inset-bottom)`; side padding `--prime-bottom-nav-padding-x`. With `iconOnly` the bar is `--prime-bottom-nav-icon-only-height` (48).
-- Items share the width equally; the icon (`--prime-bottom-nav-icon-size`, 20 — a light glyph, so the bar stays quiet next to the page) sits in a `--prime-bottom-nav-glyph-width` × `--prime-bottom-nav-glyph-height` box (28 × 20) that anchors the count; the label is `--prime-bottom-nav-label-size` (10, medium, line 12 — the iOS tab-bar size) 4 below it and truncates.
-- Floating (the iOS 26 tab bar at three quarters its size): a full-radius capsule `--prime-bottom-nav-floating-height` (46; `--prime-bottom-nav-floating-icon-only-height`, 40, with `iconOnly`), items inset `--prime-bottom-nav-floating-padding` (4) with a `--prime-bottom-nav-floating-icon-size` (18) icon over a `--prime-bottom-nav-floating-label-size` (9, semibold) label, `--prime-bottom-nav-floating-item-gap` (2) apart. The capsule spans the width left beside its actions and the items share it equally. `--prime-bottom-nav-floating-inset` (12) from the sides and above `env(safe-area-inset-bottom)`. Glass: a dense `--prime-color-bg-glass` tint over a strong `blur(--prime-bottom-nav-blur)` (14) with `saturate(180%)`, so the page shows as soft shapes; the rim is a 1px ring of `--prime-color-bg-glass-edge` that catches at the top-start and bottom-end corners and fades along the sides (a masked gradient), with the overlay shadow. The selection capsule is ink at 12%, no rim. A `BottomNav.Action` is a glass disk as tall as the capsule with an 18 glyph, `--prime-bottom-nav-floating-gap` (8) beside it. The floating bar positions itself at the bottom of its positioned container; `AppShell.Footer` then takes no height, the page scrolls under the capsule and main gets extra bottom padding so the last line clears it.
+- Items share the width equally, each at least as wide as its label; the bar is a switcher (foundation §9), so items that do not fit scroll inside it — a label is never cut. The icon (`--prime-bottom-nav-icon-size`, 20 — a light glyph, so the bar stays quiet next to the page) sits in a `--prime-bottom-nav-glyph-width` × `--prime-bottom-nav-glyph-height` box (28 × 20) that anchors the count and is the current item's pill; the label is `--prime-bottom-nav-label-size` (10, medium, line 12 — the iOS tab-bar size) 4 below it.
+- Floating (the iOS 26 tab bar at three quarters its size): a full-radius capsule `--prime-bottom-nav-floating-height` (46; `--prime-bottom-nav-floating-icon-only-height`, 40, with `iconOnly`), items inset `--prime-bottom-nav-floating-padding` (4) with a `--prime-bottom-nav-floating-icon-size` (18) icon over a `--prime-bottom-nav-floating-label-size` (9, semibold) label, `--prime-bottom-nav-floating-item-gap` (2) apart. The capsule spans the width left beside its actions and the items share it equally. `--prime-bottom-nav-floating-inset` (12) from the sides and above `env(safe-area-inset-bottom)`. Glass: a dense `--prime-color-bg-glass` tint over a strong `blur(--prime-bottom-nav-blur)` (14) with `saturate(var(--prime-glass-saturation))`, so the page shows as soft shapes; the rim is a 1px ring of `--prime-color-bg-glass-edge` that catches at the top-start and bottom-end corners and fades along the sides (a masked gradient), with the overlay shadow. The selection capsule is ink at 12%, no rim. A `BottomNav.Action` is a Button `glass` disk as tall as the capsule (the root sets `--prime-control-height`) with an 18 glyph, `--prime-bottom-nav-floating-gap` (8) beside it. The floating bar positions itself at the bottom of its positioned container; `AppShell.Footer` then takes no height, the page scrolls under the capsule and main gets extra bottom padding so the last line clears it.
 - Flat: a `BottomNav.Action` is a muted disk (Button `shape="circle"`, neutral solid) of the `l` control height at the bar's edge.
 - Surface fill with a faint top divider; inside `AppShell.Footer` the bar sticks to the bottom of the panel.
+- An «Ещё» item that opens the shell's off-canvas navigation (the Sidebar) reads `useAppShellNav()` from inside `AppShell.Root`: `aria-expanded={nav?.open}`, `aria-controls={nav?.navId}`, `onClick={() => nav?.setOpen(true)}` — the AppShell screen example has it.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` · `Shift+Tab` | Moves focus through the sections and the action; a disabled one is skipped. |
 | `Enter` | Opens the section (a link or a button) or runs the action. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - A `<nav>` landmark named by `labels.nav` («Основные разделы») or its own `aria-label`.
-- The current section has `aria-current="page"`; visually it is the primary-color item among muted ones (a contrast step, not a hue); floating, it also sits on the selection capsule, so the accent is never the only cue.
+- The current section has `aria-current="page"`; visually it is the primary-color item among muted ones with its glyph on a pill, floating it sits on the selection capsule — colour is never the only cue.
 - The icon is hidden from assistive tech; the item is named by its label, the count is read after it («Заказы 12»).
 - `BottomNav.Action` is a button without text, named by its required `aria-label`; it sits inside the landmark, before or after the items (where it is placed).
 - A disabled item is a `disabled` button, an `aria-disabled` link without `href`, or an `aria-disabled` `asChild` child out of the Tab order (`tabIndex={-1}`).
@@ -151,12 +161,12 @@ Motion: the color of the icon and the label changes over `fast`. Floating, the s
 | [icon-only.tsx](examples/icon-only.tsx) | Icons alone: the labels are hidden but still name the sections for screen readers — `iconOnly`. |
 | [floating.tsx](examples/floating.tsx) | A glass capsule over the page across the width: the client list scrolls under its blur, the selection glides to a tapped section, with labels or icons alone — `floating`, `iconOnly`. |
 | [floating-action.tsx](examples/floating-action.tsx) | A round action beside the glass capsule for the screen's main action, with labels or icons alone — `BottomNav.Action`, `floating`. |
-| [router.tsx](examples/router.tsx) | A router link as the item: the router sets `aria-current` and the item shows as current; render it inside a router — `asChild`. |
+| [router.tsx](examples/router.tsx) | A router link as the item: the router marks the open section and the item shows it as current; render it inside a router — `asChild`. |
 | [in-app-shell.tsx](examples/in-app-shell.tsx) | The app frame on a phone: the AppHeader, the page and the bar in the footer, which gives way to the Sidebar rail once one is on screen — `AppShell.Footer`. |
 
 ## Mistakes
 - Seven or more items → keep 2–6; the rest goes to a «Ещё» section or Sidebar.
-- Long labels («Управление заказами») → one word; the label truncates.
+- Long labels («Управление заказами») → one word; a long label widens its column and the bar scrolls.
 - `iconOnly` with icons that need a caption to be understood → keep the labels.
 - A floating bar outside a positioned container → it sits at the bottom of the nearest positioned ancestor; put it in `AppShell.Footer`.
 - An action as an item («Создать» among the sections) → items navigate; put the screen's one main action in `BottomNav.Action` beside the bar, the rest in the page header.
@@ -165,5 +175,5 @@ Motion: the color of the icon and the label changes over `fast`. Floating, the s
 - Hiding the bar with your own media query → the shell already hides the footer while the Sidebar rail is on screen.
 
 ## Related
-- **Built from:** [Badge](../../components/badge/COMPONENT.md), VisuallyHidden (internal), [Button](../../components/button/COMPONENT.md) (`shape="circle"`, the action disk)
+- **Built from:** [ScrollContainer](../../components/scroll-container/COMPONENT.md) (`internal/SwitcherScroller`, the items), [Badge](../../components/badge/COMPONENT.md), [VisuallyHidden](../../components/visually-hidden/COMPONENT.md), [Button](../../components/button/COMPONENT.md) (`shape="circle"`, the action disk; `glass` when floating); `internal/selectionIndicator` (the selection capsule), `internal/press`, `internal/touchTarget`
 - **See also:** [AppShell](../app-shell/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [Tabs](../../components/tabs/COMPONENT.md)

package/src/layout/bottom-nav/examples/examples.module.css

@@ -1,19 +1,14 @@
-/* Layout of the BottomNav scenarios: a phone-wide screen frame. Semantic tokens only. */
+/* Layout of the BottomNav scenarios: a phone-wide screen. The preview stage is the page; the screen only sizes and clips. Semantic tokens only. */
 
 /* A phone screen: the content above, the bar pinned to the bottom edge. */
 .phone {
   box-sizing: border-box;
   display: flex;
   flex-direction: column;
-  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);
 }
 
 /* The page above the bar. */