prime-ui-kit 0.9.3 → 0.11.0

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

@@ -8,10 +8,11 @@
 ## When to use
 - The top row of an app built on [AppShell](../app-shell/COMPONENT.md): the section title or the path, the ⌘K search entry, notifications, the account, one primary action.
 - The phone header: the menu button that opens the off-canvas Sidebar, the title, search as an icon.
+- A page without its own heading row in main (a board, a chat, a dense register): the header carries the page title (`AppHeader.Title as="h1"`) and the page tools (`AppHeader.Tools` with a PageToolbar).
 
 ## When not to use
-- The page heading, its description and page actions inside main → use [PageContent](../../components/page-content/COMPONENT.md) (`PageContent.Title` is the `<h1>`).
-- Tabs, filters and search for the data on the page → use [PageToolbar](../../components/page-toolbar/COMPONENT.md).
+- A page that has its heading, description and page actions in main → use [PageContent](../../components/page-content/COMPONENT.md) (`PageContent.Title` is the `<h1>`); then the header title stays a plain name.
+- Tabs, filters and search for the data on the page while the page has its own heading in main → put the [PageToolbar](../../components/page-toolbar/COMPONENT.md) in main, not in `AppHeader.Tools`.
 - App navigation → use [Sidebar](../sidebar/COMPONENT.md) and, on a phone, [BottomNav](../bottom-nav/COMPONENT.md); the header holds at most the menu button.
 - The search dialog itself → use [CommandMenu](../../components/command-menu/COMPONENT.md); `AppHeader.Search` only opens it.
 
@@ -30,20 +31,22 @@ AppHeader.Root               <header>, one sticky row as high as the Sidebar bra
 │     ├─ AppHeader.Icon      decorative glyph on a tile shaped like a soft button m
 │     └─ AppHeader.Description  muted caption under the name
 ├─ AppHeader.Search          field-looking button that opens the CommandMenu
-└─ AppHeader.Actions         trailing buttons: notifications, account, primary action
+├─ AppHeader.Actions         trailing buttons: notifications, account, primary action
+└─ AppHeader.Tools           second row, full width: the page tools (a PageToolbar.Root)
 ```
+`AppHeader.Title as="h1"` makes the name (not the description) the page heading.
 
 ## API
 
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### AppHeader.Root
-`ref` → `HTMLElement`. The `<header>` bar at the top of the content panel: one row as high as the Sidebar brand row, on the panel surface with no divider, sticky with the top safe-area inset (static below 480px of viewport height); inline padding is the shell gutter, so it lines up with the page in main (16 outside a shell). Its controls are size `m`; icon buttons inside are `soft` (a light fill), not `ghost`. A container (`prime-app-header`): below 36rem the icon tile and the description go and the search folds into an icon.
+`ref` → `HTMLElement`. The sticky `<header>` bar at the top of the content panel, one row as high as the Sidebar brand row and lined up with the page. Icon buttons inside are `soft`, not `ghost`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `labels` | `Partial<AppHeaderLabels>` | — | Built-in strings, see Labels. |
-| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (`AppHeader.Start`, `AppHeader.Search`, `AppHeader.Actions`), `className` and the other attributes. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (`AppHeader.Start`, `AppHeader.Search`, `AppHeader.Actions`, `AppHeader.Tools`), `className` and the other attributes. |
 
 ### AppHeader.Start
 `ref` → `HTMLDivElement`. The leading zone that takes the free width: the menu button, a back button, the title or a Breadcrumb.
@@ -53,10 +56,11 @@ AppHeader.Root               <header>, one sticky row as high as the Sidebar bra
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### AppHeader.Title
-`ref` → `HTMLDivElement`. Where you are: an optional `AppHeader.Icon`, the name (title-s, truncates) and an optional `AppHeader.Description` under it — the anatomy of the Sidebar brand. Not a heading: the page `<h1>` is PageContent.Title.
+`ref` → `HTMLDivElement`. Where you are: an optional `AppHeader.Icon`, the name (title-s, truncates) and an optional `AppHeader.Description` under it. Not a heading unless `as="h1"`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `as` | `"span" \| "h1"` | `"span"` | Tag of the name. `h1`: the header carries the page title — only the name is the heading, the description stays outside its accessible name; the look does not change. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the name, `AppHeader.Icon`, `AppHeader.Description` in any order), `className` and the other div attributes. |
 
 ### AppHeader.Icon
@@ -89,6 +93,13 @@ AppHeader.Root               <header>, one sticky row as high as the Sidebar bra
 | `shortcut` | `ReactNode` | `"⌘K"` | The key hint at the end (a `Kbd`, hidden from assistive tech); `null` hides it. Bind the key yourself. |
 | `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `className` and the other button 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.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (a `PageToolbar.Root`), `className` and the other div attributes. |
+
 ### AppHeader.Actions
 `ref` → `HTMLDivElement`. The trailing row of buttons: notifications, the account, one primary action. Never wraps.
 
@@ -119,10 +130,18 @@ AppHeader.Root               <header>, one sticky row as high as the Sidebar bra
 | Breadcrumb in Start | A soft back button, `AppHeader.Separator` and the path | A nested record page | |
 | with `AppHeader.Search` | A field-looking button with a key hint between Start and Actions | The app has a CommandMenu | |
 | with `AppHeader.Actions` | A row of buttons at the end | Notifications, account, one primary action | |
+| with `AppHeader.Tools` | A second row under the title row with the page's PageToolbar | The header carries the page: no heading row in main | |
+
+### as (Title)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `span` | the name, no heading | the page has `PageContent.Header` in main | yes |
+| `h1` | the same look; the name is the page `<h1>`, the description stays outside its name | the header carries the page title | |
 
 ## 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 |
 | narrow header | header width below 36rem (container `prime-app-header`) | the icon tile and the description hide; the search folds into a square button, its text stays as the name |
 | 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 |
@@ -134,21 +153,24 @@ AppHeader.Root               <header>, one sticky row as high as the Sidebar bra
 - 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.
 - `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.
 - Search: up to 288 wide, shrinks first; field tier m and the fill of the panel layer it sits on. Controls inside are size `m`.
+- `AppHeader.Tools` is the header's second row: the full width under the title row, 12 apart, sticky with it. The PageToolbar inside lays itself out from that width — one row from 56rem, two below — so on a phone the page tools wrap under the title, never squeeze it. The page's primary action goes into `PageToolbar.Actions` there, and `AppHeader.Actions` keeps notifications and the account.
 
 ## Accessibility
 
 ### Keyboard
 | Key | Action |
 |---|---|
-| `Tab` | Moves through the menu button, the path links, the search and the actions in reading order. |
+| `Tab` | Moves through the menu button, the path links, the search and the actions in reading order, then the page tools in the second row. |
 | `Enter` · `Space` | Presses the focused button: opens the menu, the search or runs the action. |
 
 ### ARIA
 - Root is a `<header>`: the banner landmark when it sits at the top level of the page.
 - Search is a button named by its text; the key hint is `aria-hidden`, and the app binds the shortcut.
 - MenuButton is named by `labels.menu`; pass `aria-expanded` (whether the Sidebar is open).
-- Title is not a heading: the page `<h1>` stays with PageContent.Title.
+- Title is not a heading by default: the page `<h1>` stays with PageContent.Title. With `as="h1"` the name is the page heading; the description sits next to it, outside its accessible name. One `<h1>` per page either way.
+- `AppHeader.Tools` follows the title row in the DOM, so Tab and screen readers meet the page tools after the header's own buttons.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -162,12 +184,15 @@ AppHeader.Root               <header>, one sticky row as high as the Sidebar bra
 |---|---|
 | [overview.tsx](examples/overview.tsx) | The top bar of a screen: where you are, global search, notifications and the primary action — `AppHeader.Title`, `AppHeader.Search`, `AppHeader.Actions`. |
 | [breadcrumbs.tsx](examples/breadcrumbs.tsx) | A nested page: a back button, a separator and the path instead of a title, actions on the record 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, the page tools (sections, the period, the primary action) are its second row and lay themselves out from its width — `AppHeader.Title`, `as`, `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 description goes and the search folds into an icon — `AppHeader.MenuButton`, `show`. |
 
 ## Mistakes
 - A border or shadow under the header → it sits on the panel surface; the fill is the boundary.
-- `AppHeader.Title` as the page `<h1>` → the heading belongs to PageContent.Title in main.
+- `AppHeader.Title as="h1"` while main also has `PageContent.Title` → two `<h1>`; the header carries the title only when main has no heading row.
+- Page tools crammed into `AppHeader.Actions` → `AppHeader.Tools` with a PageToolbar: it wraps under the title instead of squeezing it.
+- A heading element of your own inside `AppHeader.Title` → `as="h1"`, so the description stays out of the heading.
 - A real text input for global search → `AppHeader.Search` opens the CommandMenu, where typing happens.
 - More than three actions → keep one primary action; the rest go into the page or a Dropdown.
 - A hand-made menu button with a media query → `AppHeader.MenuButton` follows the Sidebar breakpoint.
@@ -175,4 +200,4 @@ AppHeader.Root               <header>, one sticky row as high as the Sidebar bra
 
 ## Related
 - **Built from:** [Button](../../components/button/COMPONENT.md), [Kbd](../../components/kbd/COMPONENT.md), [Divider](../../components/divider/COMPONENT.md), Icon (`action.search`, `nav.menu`)
-- **See also:** [AppShell](../app-shell/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [PageContent](../../components/page-content/COMPONENT.md), [PageToolbar](../../components/page-toolbar/COMPONENT.md), [CommandMenu](../../components/command-menu/COMPONENT.md), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)
+- **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`), [CommandMenu](../../components/command-menu/COMPONENT.md), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)

package/src/layout/app-header/examples/page-title.tsx

@@ -0,0 +1,85 @@
+/** The header carries the page: the title is the page heading, the page tools (sections, the period, the primary action) are its second row and lay themselves out from its width — `AppHeader.Title`, `as`, `AppHeader.Tools`. */
+import { AppHeader, Button, Icon, PageToolbar, SegmentedControl, Select } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { value: "all", label: "Все" },
+  { value: "mine", label: "Мои" },
+  { value: "overdue", label: "Просроченные" },
+];
+
+const PERIODS = [
+  { value: "month", label: "Октябрь" },
+  { value: "quarter", label: "IV квартал" },
+  { value: "year", label: "2026 год" },
+];
+
+export default function AppHeaderPageTitleExample() {
+  const [section, setSection] = React.useState("all");
+  const [period, setPeriod] = React.useState("month");
+
+  return (
+    <div className={styles.window}>
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <AppHeader.Title as="h1">
+            Сделки
+            <AppHeader.Description>Отдел продаж</AppHeader.Description>
+          </AppHeader.Title>
+        </AppHeader.Start>
+        <AppHeader.Actions>
+          <Button.Root variant="soft" tone="neutral" aria-label="Уведомления">
+            <Button.Icon>
+              <Icon name="object.bell" />
+            </Button.Icon>
+          </Button.Root>
+        </AppHeader.Actions>
+        <AppHeader.Tools>
+          <PageToolbar.Root aria-label="Сделки">
+            <PageToolbar.Sections>
+              <SegmentedControl.Root
+                fullWidth
+                value={section}
+                onValueChange={setSection}
+                aria-label="Раздел"
+              >
+                {SECTIONS.map((item) => (
+                  <SegmentedControl.Item key={item.value} value={item.value}>
+                    {item.label}
+                  </SegmentedControl.Item>
+                ))}
+              </SegmentedControl.Root>
+            </PageToolbar.Sections>
+            <PageToolbar.View>
+              <Select.Root value={period} onValueChange={setPeriod}>
+                <Select.Trigger aria-label="Период">
+                  <Select.TriggerIcon>
+                    <Icon name="field.calendar" />
+                  </Select.TriggerIcon>
+                  <Select.Value />
+                </Select.Trigger>
+                <Select.Content>
+                  {PERIODS.map((item) => (
+                    <Select.Item key={item.value} value={item.value}>
+                      {item.label}
+                    </Select.Item>
+                  ))}
+                </Select.Content>
+              </Select.Root>
+            </PageToolbar.View>
+            <PageToolbar.Actions>
+              <Button.Root>
+                <Button.Icon>
+                  <Icon name="action.add" />
+                </Button.Icon>
+                Новая сделка
+              </Button.Root>
+            </PageToolbar.Actions>
+          </PageToolbar.Root>
+        </AppHeader.Tools>
+      </AppHeader.Root>
+    </div>
+  );
+}

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

@@ -60,7 +60,7 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes. |
 
 ### AppShell.Footer
-`ref` → `HTMLDivElement`. Sticky bottom bar of the panel for `BottomNav`; no padding of its own. A container (`prime-shell-footer`): BottomNav inside shows only while the panel is narrower than 640px.
+`ref` → `HTMLDivElement`. Sticky bottom bar of the panel for `BottomNav`; no padding of its own. Shows only while the shell has no navigation column on screen (no `AppShell.Nav`, or the Sidebar is off-canvas); with the rail on screen the footer leaves.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -99,7 +99,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 | Title or breadcrumbs, global search, actions, the mobile menu button | |
-| with `AppShell.Footer` | Sticky bar at the bottom of the panel, shown while it holds a visible bar | BottomNav on a phone | |
+| 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.
 
@@ -107,13 +107,18 @@ Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 | State | Driven by | DOM |
 |---|---|---|
 | fixed frame | `fillViewport` | `data-fill-viewport="true"` on Root |
+| navigation column | an `AppShell.Nav` child | `data-nav="true"` on Root (two grid columns) |
 | content width | `contentWidth` | `data-content-width` on Main |
-| footer bar | panel width (container `prime-shell-footer` on Footer) | BottomNav inside leaves from 640px of panel width; the empty footer takes no room |
+| 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 |
 
 ## 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: `--prime-layout-gutter-s` (16) → `-m` (24) from 640px → `-l` (32) from 1024px. Main top padding `--prime-space-6` (24) → `--prime-space-10` (40) from 1024px; bottom `--prime-space-16`.
+- 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-10` (40) from 1024px; bottom `--prime-space-16`. Children of Main start from their own gutters, 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.
 - Footer: no padding of its own (BottomNav keeps the bottom safe-area inset), sticky at the bottom, `z-index: --prime-z-sticky`.
+- A floating BottomNav (`floating`) in the footer: the footer takes no height, the capsule overlays the page, and Main keeps extra bottom room (the capsule height and the safe-area inset) so its last line never ends up under it.
 - The panel is the page (layer 0 of the surface ladder, gray in light): fields on it take the page fill, a Card inside is layer 1 — white in light with the raised whisper — and cards in cards go deeper.
 
 ## Accessibility
@@ -135,7 +140,7 @@ No `labels`.
 |---|---|
 | [overview.tsx](examples/overview.tsx) | The app frame: Sidebar in the nav column, breadcrumbs 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-wide app: the bar in the footer stays at the bottom while main scrolls under it, and leaves once the panel is 640px wide — `AppShell.Footer`. |
+| [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`. |
 
 ## Mistakes
@@ -143,6 +148,7 @@ No `labels`.
 - Wrapping Main content in another scroll container → Main scrolls (with `fillViewport`) or the document does.
 - A border or shadow between nav and panel → the fill change is the boundary.
 - Putting the Sidebar directly in Root without `AppShell.Nav` → it lands inside the content panel.
+- BottomNav anywhere but `AppShell.Footer` → it stays next to the Sidebar rail on a desktop; the footer is what leaves while the rail is on screen.
 - `AppShell.Template` in a router app without `scrollResetKey` → a new page opens at the old scroll position; pass the pathname.
 
 ## Related

package/src/layout/app-shell/examples/examples.module.css

@@ -28,7 +28,7 @@
   height: 100%;
 }
 
-/* footer.tsx: the same window, phone-wide, so the bar in the footer stays (it leaves from 640px). */
+/* footer.tsx: the same window, phone-wide; no Nav, so the bar in the footer stays. */
 .phone {
   box-sizing: border-box;
   display: flex;

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

@@ -1,4 +1,4 @@
-/** A phone-wide app: the bar in the footer stays at the bottom while main scrolls under it, and leaves once the panel is 640px wide — `AppShell.Footer`. */
+/** A phone app without a Sidebar: the bar in the footer stays at the bottom while main scrolls under it — `AppShell.Footer`. */
 import { AppHeader, AppShell, BottomNav, Icon, PageContent, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

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

@@ -3,16 +3,16 @@
 **Category:** navigation
 **Kind:** layout
 
-> Phone navigation: a bar of 3–5 main sections at the bottom of the screen.
+> Phone navigation: a bar of 2–6 main sections at the bottom of the screen, optionally with a round action beside it.
 
 ## When to use
 - The main sections of an app on a phone, one tap away (Главная, Заказы, Клиенты, Ещё).
-- Next to Sidebar in one app: Sidebar navigates on a wide screen, BottomNav on a phone (inside `AppShell.Footer` it leaves by itself once the panel is 640px wide).
+- Next to Sidebar in one app: Sidebar navigates on a wide screen, BottomNav on a phone (inside `AppShell.Footer` it leaves by itself while the Sidebar rail is on screen).
 
 ## When not to use
-- More than five destinations or nested sections → use [Sidebar](../sidebar/COMPONENT.md) (off-canvas on a phone), put the rest under «Ещё».
+- More than six destinations or nested sections → use [Sidebar](../sidebar/COMPONENT.md) (off-canvas on a phone), put the rest under «Ещё».
 - Switching views inside one page → use [Tabs](../../components/tabs/COMPONENT.md) or [SegmentedControl](../../components/segmented-control/COMPONENT.md).
-- Actions (create, filter) → use [Button](../../components/button/COMPONENT.md); the bar only navigates.
+- Several actions (create, filter, export) → use [Button](../../components/button/COMPONENT.md) in the page header; the bar holds at most one main action (`BottomNav.Action`).
 
 ## Import
 ```tsx
@@ -21,11 +21,12 @@ import { BottomNav } from "prime-ui-kit";
 
 ## Anatomy
 ```
-BottomNav.Root                 <nav> bar, equal columns, safe-area inset below
-└─ BottomNav.Item              <button>, <a href> or the asChild element
-   ├─ BottomNav.ItemIcon       the glyph above the label (aria-hidden)
-   ├─ BottomNav.ItemCount      Badge on the icon corner
-   └─ label                    one short word
+BottomNav.Root                 <nav>, safe-area inset below
+├─ 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
+│  └─ label                    one short word
+└─ BottomNav.Action            Button shape="circle" beside the bar (aria-label)
 ```
 
 ## API
@@ -33,22 +34,22 @@ BottomNav.Root                 <nav> bar, equal columns, 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>` bar: equal columns, surface fill with a faint top divider, the bottom safe-area inset below the items. Inside `AppShell.Footer` it shows only while the panel is narrower than 640px.
+`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.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `iconOnly` | `boolean` | `false` | Icons without visible labels; the labels stay in the DOM as visually hidden text and name the items. |
-| `floating` | `boolean` | `false` | A Liquid Glass capsule over the content (the iOS 26 tab bar): a clear `--prime-color-bg-glass` tint over a light backdrop blur, a specular top edge, a glass selection capsule under the current item, inset `--prime-bottom-nav-floating-inset` from the edges and above the home indicator. Positions itself at the bottom of its positioned container (`AppShell.Footer`, which then takes no height), so the page scrolls under it; with `iconOnly` the capsule hugs its square items, centred. Opaque under `prefers-reduced-transparency`. |
+| `floating` | `boolean` | `false` | A glass capsule floating over the content at the bottom of its positioned container (`AppShell.Footer`), with a selection capsule gliding under the current item; the page scrolls under it. |
 | `labels` | `Partial<BottomNavLabels>` | — | Built-in strings, see Labels. |
-| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (3–5 `BottomNav.Item`), `aria-label` (replaces `labels.nav`), `className` and the other attributes. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (2–6 `BottomNav.Item`, optional `BottomNav.Action` before or after them), `aria-label` (replaces `labels.nav`), `className` and the other attributes. |
 
 ### BottomNav.Item
 `ref` → the rendered element. `<button type="button">`, `<a>` with `href`, or the single child with `asChild`: the icon (20) above a short label (10).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `current` | `boolean` | `false` | Current section: `aria-current="page"`; the icon and the label turn primary (the others are muted). |
-| `disabled` | `boolean` | `false` | Not interactive: `disabled` / `aria-disabled`, `data-disabled`; a link loses its `href`. |
+| `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). |
+| `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`). |
 | `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). |
@@ -72,22 +73,31 @@ BottomNav.Root                 <nav> bar, equal columns, safe-area inset below
 | `variant` | `"solid" \| "soft" \| "outline"` | `"solid"` | Badge treatment. |
 | `…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.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `aria-label` | `string` | — (required) | The name of the action: the button has no visible text. |
+| `children` | `ReactNode` | — (required) | The glyph, e.g. `<Icon name="action.add" />`. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children">` | — | `onClick`, `disabled`, `className` and the other button attributes. |
+
 ## Variants
 
-Two item states only — current (primary color) and not (muted); no hover, no fill.
+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.
 
 ### Flags (Root)
-| Flag | Looks like | Use when | Default |
+| Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `floating` | a glass capsule over the content: translucent fill, backdrop blur, bright rim, inset from the edges | the app's look wants depth over the page, the iOS tab-bar feel | |
-| `iconOnly` | icons alone; labels visually hidden, still the items' names | 3–4 sections with unmistakable icons | |
+| `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` |
+| `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.
 
 ### Flags (Item)
 | Flag | Part | Effect |
 |---|---|---|
-| `current` | Item | `aria-current="page"`, icon and label in the primary color |
+| `current` | Item | `aria-current="page"`, icon and label in the primary color (floating: the accent, on the selection capsule) |
 | `disabled` | Item | not interactive, disabled text color |
 | `asChild` | Item | the child element (router link) is the item |
 
@@ -97,16 +107,18 @@ Without flags the bar is flat at the screen edge on the surface, with a faint to
 | current | `current` or a router link setting `aria-current` | `aria-current="page"` on the item |
 | focus | keyboard | focus ring inside the item edge |
 | disabled | `disabled` | `disabled` / `aria-disabled`, `data-disabled` |
-| hidden | inside `AppShell.Footer` 640px wide or more | `display: none` (container `prime-shell-footer`) |
+| 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>` |
-| less transparency | `prefers-reduced-transparency: reduce` | a floating capsule turns opaque (`--prime-color-layer-floating-bg`), no blur |
+| 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 |
 
-Motion: the color of the icon and the label changes over `fast`; in the floating capsule the selection capsule grows in from 92% and fades in (`fast`, enter easing), instant under reduced motion. No hover or press feedback: an item is either current or not.
+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.
 
 ## 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-indicator-width` × `--prime-bottom-nav-indicator-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): items `--prime-bottom-nav-floating-item-size` (44) high inset `--prime-bottom-nav-floating-padding` (4) inside a full-radius capsule (52 in all); with `iconOnly` the items are 44 squares and the capsule hugs them. `--prime-bottom-nav-floating-inset` (12) from the sides and above `env(safe-area-inset-bottom)`. Liquid Glass: a clear `--prime-color-bg-glass` tint over a light `blur(--prime-bottom-nav-blur)` (8) with `saturate(180%)`, so the page reads through; a specular top edge in `--prime-color-bg-glass-edge`, a hairline of ink around it and the overlay shadow. The current item sits on a glass selection capsule (ink at 8% with its own top highlight). Inside `AppShell.Footer` main gets extra bottom padding so the last line clears the capsule.
+- 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.
+- 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.
 
 ## Accessibility
@@ -114,14 +126,15 @@ Motion: the color of the icon and the label changes over `fast`; in the floating
 ### Keyboard
 | Key | Action |
 |---|---|
-| `Tab` · `Shift+Tab` | Moves focus through the sections; a disabled one is skipped. |
-| `Enter` | Opens the section (a link or a button). |
+| `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
 - 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).
+- 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 icon is hidden from assistive tech; the item is named by its label, the count is read after it («Заказы 12»).
-- A disabled item is a `disabled` button or an `aria-disabled` link without `href`.
+- `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}`).
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -136,18 +149,21 @@ Motion: the color of the icon and the label changes over `fast`; in the floating
 | [overview.tsx](examples/overview.tsx) | Four sections of the app, the current one in the primary color and a tap moves it — `current`, `BottomNav.ItemIcon`. |
 | [structure.tsx](examples/structure.tsx) | Counts on the icons and a section that is not available yet — `BottomNav.ItemCount`, `disabled`. |
 | [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: the client list scrolls under its blur, with labels or icons alone — `floating`, `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`. |
-| [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 leaves once the panel is 640px wide — `AppShell.Footer`. |
+| [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
-- Six or more items → keep 3–5; the rest goes to a «Ещё» section or Sidebar.
+- Seven or more items → keep 2–6; the rest goes to a «Ещё» section or Sidebar.
 - Long labels («Управление заказами») → one word; the label truncates.
 - `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 item («Создать») in the bar → the bar navigates; put the action in the page header.
-- Hiding the bar with your own media query inside `AppShell.Footer` → the footer already hides it from 640px of panel width.
+- 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.
+- `BottomNav.Action` without `aria-label` → the button has no name; it is required.
+- The bar outside `AppShell.Footer` (in Main, Root or `position: fixed` on the page) → it never leaves and shows next to the Sidebar on a desktop; put it in `AppShell.Footer` (or the Template `footer` prop).
+- 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, VisuallyHidden (internal)
+- **Built from:** [Badge](../../components/badge/COMPONENT.md), VisuallyHidden (internal), [Button](../../components/button/COMPONENT.md) (`shape="circle"`, the action disk)
 - **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

@@ -31,9 +31,16 @@
   height: 100%;
 }
 
-/* floating.tsx: a client row — avatar and two lines of text. */
+/* floating*.tsx: a client row — avatar and two lines of text. */
 .client {
   display: flex;
   align-items: center;
   gap: var(--prime-space-3);
 }
+
+/* floating*.tsx: the look switch above the list. */
+.options {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-space-2) var(--prime-space-6);
+}

package/src/layout/bottom-nav/examples/floating-action.tsx

@@ -0,0 +1,91 @@
+/** A round action beside the glass capsule for the screen's main action, with labels or icons alone — `BottomNav.Action`, `floating`. */
+import {
+  AppHeader,
+  AppShell,
+  Avatar,
+  BottomNav,
+  Icon,
+  PageContent,
+  Switch,
+  Typography,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { id: "home", label: "Главная", icon: "nav.home" },
+  { id: "clients", label: "Клиенты", icon: "object.users" },
+  { id: "inbox", label: "Входящие", icon: "object.inbox" },
+] as const;
+
+const CLIENTS = [
+  { name: "ООО «Север»", initials: "СЕ", color: "blue", deals: "4 сделки" },
+  { name: "ИП Котов", initials: "КО", color: "green", deals: "1 сделка" },
+  { name: "ООО «Вектор»", initials: "ВЕ", color: "orange", deals: "7 сделок" },
+  { name: "АО «Меридиан»", initials: "МЕ", color: "purple", deals: "2 сделки" },
+  { name: "ООО «Полюс»", initials: "ПО", color: "red", deals: "5 сделок" },
+  { name: "ИП Белова", initials: "БЕ", color: "teal", deals: "3 сделки" },
+  { name: "ООО «Гранит»", initials: "ГР", color: "yellow", deals: "6 сделок" },
+  { name: "АО «Ладога»", initials: "ЛА", color: "sky", deals: "2 сделки" },
+] as const;
+
+export default function BottomNavFloatingActionExample() {
+  const [section, setSection] = React.useState<string>("clients");
+  const [iconOnly, setIconOnly] = React.useState(false);
+
+  return (
+    <div className={styles.phone}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppHeader.Root>
+          <AppHeader.Start>
+            <AppHeader.Title>Клиенты</AppHeader.Title>
+          </AppHeader.Start>
+        </AppHeader.Root>
+        <AppShell.Main>
+          <PageContent.Section>
+            <PageContent.Body>
+              <div className={styles.options}>
+                <Switch.Root checked={iconOnly} onCheckedChange={setIconOnly}>
+                  <Switch.Label>Только иконки</Switch.Label>
+                </Switch.Root>
+              </div>
+              {CLIENTS.map((client) => (
+                <div key={client.name} className={styles.client}>
+                  <Avatar.Root color={client.color} aria-hidden="true">
+                    <Avatar.Fallback>{client.initials}</Avatar.Fallback>
+                  </Avatar.Root>
+                  <div>
+                    <Typography variant="body-m">{client.name}</Typography>
+                    <Typography variant="body-s" tone="muted">
+                      {client.deals}
+                    </Typography>
+                  </div>
+                </div>
+              ))}
+            </PageContent.Body>
+          </PageContent.Section>
+        </AppShell.Main>
+        <AppShell.Footer>
+          <BottomNav.Root floating iconOnly={iconOnly}>
+            {SECTIONS.map((item) => (
+              <BottomNav.Item
+                key={item.id}
+                current={item.id === section}
+                onClick={() => setSection(item.id)}
+              >
+                <BottomNav.ItemIcon>
+                  <Icon name={item.icon} />
+                </BottomNav.ItemIcon>
+                {item.label}
+              </BottomNav.Item>
+            ))}
+            <BottomNav.Action aria-label="Новый клиент">
+              <Icon name="action.add" />
+            </BottomNav.Action>
+          </BottomNav.Root>
+        </AppShell.Footer>
+      </AppShell.Root>
+    </div>
+  );
+}