prime-ui-kit 0.10.0 → 0.11.0

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>
+  );
+}

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

@@ -1,4 +1,4 @@
-/** A glass capsule over the page: the client list scrolls under its blur, with labels or icons alone — `floating`, `iconOnly`. */
+/** 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`. */
 import {
   AppHeader,
   AppShell,
@@ -42,15 +42,15 @@ export default function BottomNavFloatingExample() {
           <AppHeader.Start>
             <AppHeader.Title>Клиенты</AppHeader.Title>
           </AppHeader.Start>
-          <AppHeader.Actions>
-            <Switch.Root checked={iconOnly} onCheckedChange={setIconOnly}>
-              <Switch.Label>Только иконки</Switch.Label>
-            </Switch.Root>
-          </AppHeader.Actions>
         </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">

package/src/layout/bottom-nav/examples/in-app-shell.tsx

@@ -1,4 +1,4 @@
-/** 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`. */
+/** 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`. */
 import {
   AppHeader,
   AppShell,

package/src/layout/sidebar/COMPONENT.md

@@ -90,8 +90,8 @@ useSidebar()                       state hook for custom parts inside Root
 | `open` | `boolean` | — | Off-canvas panel on narrow viewports (controlled). |
 | `defaultOpen` | `boolean` | `false` | Initial off-canvas state (uncontrolled). |
 | `onOpenChange` | `(open: boolean) => void` | — | Off-canvas open / close: Toggle, scrim, Escape, navigation, leaving the narrow viewport. |
-| `offCanvas` | `"auto" \| "always" \| "never"` | `"auto"` | When the rail leaves the layout and becomes an off-canvas panel with a scrim and a focus trap, opened by `open`: `auto` — below 768px (viewport); `always` — at any width (navigation behind a menu button); `never` — always a rail. |
-| `persistKey` | `string` | — | Remembers the navigation across reloads in `localStorage` under this key: the mode and which collapsible groups and sub-lists are open, by their `id`, else their label text (give an `id` when labels are translated or change). The stored state wins over `defaultMode` / `defaultOpen`; controlled `mode` / `open` are not stored. Unavailable storage is ignored. |
+| `offCanvas` | `"auto" \| "always" \| "never"` | `"auto"` | When the rail becomes an off-canvas panel opened by `open`: `auto` — below 768px (viewport); `always` — at any width; `never` — always a rail. |
+| `persistKey` | `string` | — | `localStorage` key that keeps the mode and the open groups and sub-lists across reloads (keyed by `id`, else label text). Wins over `defaultMode` / `defaultOpen`. |
 | `labels` | `Partial<SidebarLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
@@ -103,7 +103,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### Sidebar.Brand
-`forwardRef` → the rendered element. Product block: `Sidebar.BrandLogo`, the name and a muted line; an `<a>` with `href`, the single child with `asChild`, else a `<div>`. In compact mode only the logo stays, without a tooltip (it would cover the edge toggle); the faded name still names the link.
+`forwardRef` → the rendered element. Product block: `Sidebar.BrandLogo`, the name and a muted line; an `<a>` with `href`, the single child with `asChild`, else a `<div>`. In compact mode only the logo stays.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -129,7 +129,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (Groups, Items, Subs), `className` and the other attributes. |
 
 ### Sidebar.Group
-`ref` → `HTMLDivElement`. `<div role="group">` named by its label. With `collapsible` the heading is a disclosure button (`aria-expanded`, `aria-controls`) with a chevron at its end; the items fold away (inert). On the compact rail the heading keeps its height and layout: its text slides toward the edge, scales down and is cut by the rail with a fade, so the first letters still name the section, and it still folds and unfolds the group. An open group keeps its items on the rail; a folded one stays folded and becomes one `…` row (named by the label, `aria-haspopup="dialog"`) whose items open in a flyout, like a sub-list. A folded group with a count that needs attention inside shows its dot (after the heading, or on the `…` row).
+`ref` → `HTMLDivElement`. `<div role="group">` named by its label. With `collapsible` the heading is a disclosure button that folds the items away; on the compact rail a folded group becomes one `…` row whose items open in a flyout.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -145,7 +145,7 @@ useSidebar()                       state hook for custom parts inside Root
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `current` | `boolean` | `false` | Current page: `aria-current="page"`, `data-state="active"`; surface fill and a raised shadow (a deeper wash in a flyout). |
+| `current` | `boolean` | `false` | Current page: `aria-current="page"`, `data-state="active"`; a muted fill and primary text and icon colour. |
 | `disabled` | `boolean` | `false` | Not interactive: `disabled` / `aria-disabled`, `data-disabled`; a link loses its `href`. |
 | `href` | `string` | — | Renders an `<a>` (with `target`, `rel`). |
 | `asChild` | `boolean` | `false` | Renders the single child (e.g. a router `NavLink`) as the item; its children are the label and parts. |
@@ -161,7 +161,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Sidebar.ItemCount
-`ref` → `HTMLSpanElement` (the number or the Badge). A count after the label: a plain muted number by default; a `Badge` (one tier down) when `color` or `variant` is set. In compact mode the number leaves the row (still read by screen readers) and a badge leaves a dot of its hue on the icon; a folded sub-list or group shows the dot of a badge inside it.
+`ref` → `HTMLSpanElement` (the number or the Badge). A count after the label: a plain muted number by default; a `Badge` (one tier down) when `color` or `variant` is set — on the compact rail it becomes a dot of its hue.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -179,7 +179,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Sidebar.ItemAction
-`ref` → `HTMLButtonElement`. A row action (create, add): a ghost icon `Button` one tier down with a tooltip, next to the item element — never inside it. It shows on hover and focus of the row, always on touch screens, while the trail (count, hint) steps aside; hidden on the compact rail.
+`ref` → `HTMLButtonElement`. A row action (create, add): a ghost icon `Button` one tier down with a tooltip, next to the item element — never inside it. Shows on hover and focus of the row (always on touch); hidden on the compact rail.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -190,7 +190,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" \| "onClick" \| "aria-label">` | — | `className` and the other attributes of the Button. |
 
 ### Sidebar.Sub
-`ref` → `HTMLDivElement`. A parent item with child items: `Sidebar.SubTrigger` + `Sidebar.SubContent` in a `<div>`. Expanded, the children unfold under the parent on a guide line; on the compact rail they open in a flyout (the kit Popover to the right, with the rows and spacing of a kit menu). A current child opens the sub-list and marks the parent as on the active path (`data-active-path`). While folded (and always on the rail) the parent shows the dot of a count inside that needs attention.
+`ref` → `HTMLDivElement`. A parent item with child items: `Sidebar.SubTrigger` + `Sidebar.SubContent` in a `<div>`. Children unfold on a guide line, or in a flyout on the compact rail. A current child opens the sub-list and marks the parent (`data-active-path`).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -200,7 +200,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
 
 ### Sidebar.SubTrigger
-`forwardRef` → `HTMLButtonElement`. The parent row: a disclosure `<button>` (`aria-expanded`, `aria-controls`) with a chevron at the end of the row. Expanded: click, `→` / `←` open and close. Compact: hover (after a short intent delay), click, `Enter` · `Space` · `→` open the flyout (`aria-haspopup="dialog"`); on the active path it takes the current lift.
+`forwardRef` → `HTMLButtonElement`. The parent row: a disclosure `<button>` (`aria-expanded`, `aria-controls`) with a chevron at the end of the row. On the compact rail it opens the flyout (`aria-haspopup="dialog"`).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -228,7 +228,7 @@ useSidebar()                       state hook for custom parts inside Root
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `variant` | `"item" \| "header"` | `"item"` | `item` — a row in the rail. `header` — an icon button «‹‹» at the end of `Sidebar.Header`; in compact mode the same button moves onto the rail's outer edge, shrinks and turns round, and its chevrons turn to point out. Off-canvas it stays in the header and closes the panel. |
+| `variant` | `"item" \| "header"` | `"item"` | `item` — a row in the rail. `header` — an icon button «‹‹» at the end of `Sidebar.Header` that moves onto the rail edge in compact mode. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" \| "aria-label" \| "aria-expanded" \| "aria-controls">` | — | `onClick` (runs first; `preventDefault()` stops the toggle), `className` and the other button attributes. |
 
 ### useSidebar()
@@ -287,7 +287,7 @@ The rail width does not depend on `size`.
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `collapsible` (Group) | the heading is a button with a chevron at its end; items fold away; folded on the rail, one `…` row opens them in a flyout | long navigation with sections | off |
-| `current` (Item) | surface fill + raised shadow, primary text and icon | the current page | off |
+| `current` (Item) | `fill-muted-hover` fill (a `fill-subtle-active` wash in a flyout), primary text and icon | the current page | off |
 | `disabled` (Item) | `text-disabled`, no hover, `cursor: not-allowed` | an unavailable section | off |
 
 Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header, or `Sidebar.Toggle` in the footer for a rail without a brand; on phones (`offCanvas="auto"`) or always (`offCanvas="always"`) pair it with `AppHeader.MenuButton` (`open` / `onOpenChange`). One current item at a time; give every top-level item an icon when the rail can go compact (child items need none).
@@ -306,6 +306,10 @@ Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header,
 | persisted | `persistKey` on Root | the mode and the open state of collapsible groups and sub-lists are read from and written to `localStorage` |
 | disabled | `disabled` | Item `disabled` / `aria-disabled`, `data-disabled` |
 
+`persistKey` stores collapsible groups and sub-lists by their `id`, else by their label text — give an `id` when labels are translated or change. The stored state wins over `defaultMode` / `defaultOpen`; controlled `mode` / `open` are not stored, and unavailable storage is ignored.
+
+On the active path a SubTrigger takes the current fill. On the compact rail a SubTrigger opens its flyout on hover after a short intent delay, as well as on click and from the keyboard.
+
 Leaving the narrow viewport closes the off-canvas panel; navigating from an `href` / `asChild` item (or the brand) closes it too. Navigating from a flyout closes the flyout.
 
 ## Layout & spacing
@@ -346,7 +350,8 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 - A collapsible group heading and a SubTrigger are buttons with `aria-expanded` and `aria-controls`; folded content is `inert`.
 - On the compact rail a SubTrigger and the `…` row of a folded group have `aria-haspopup="dialog"`; the flyout is a non-modal dialog named by the parent (the `…` row by the group label).
 - On the rail a collapsible group heading stays the same disclosure button (folding it there brings the `…` row); hovering it shows the whole name in a tooltip.
-- An attention dot is decorative: the count it stands for is read inside.
+- An attention dot is decorative: the count it stands for is read inside. On the compact rail a plain count leaves the row visually but stays readable by screen readers.
+- In compact mode the brand's name fades out but still names the link.
 - A row action is its own button next to the item (never nested), named by `label` with a tooltip.
 - The account avatar is hidden from screen readers; the name and the muted line name the button.
 - Off-canvas: scrim, focus trap and Escape; the scrim is a button labelled `labels.close`.
@@ -393,5 +398,5 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 - Your own `localStorage` code for the rail mode → `persistKey` keeps the mode and the folded groups.
 
 ## Related
-- **Built from:** [ScrollContainer](../../components/scroll-container/COMPONENT.md), [Badge](../../components/badge/COMPONENT.md), [Tooltip](../../components/tooltip/COMPONENT.md), [Popover](../../components/popover/COMPONENT.md) (compact flyout), [Button](../../components/button/COMPONENT.md) (header toggle, row action), [Avatar](../../components/avatar/COMPONENT.md) slot, Icon (`nav.sidebarCollapse`, `nav.sidebarExpand`, `nav.chevronsLeft`, `nav.chevronDown`, `nav.chevronsUpDown`, `action.add`)
+- **Built from:** [ScrollContainer](../../components/scroll-container/COMPONENT.md), [Badge](../../components/badge/COMPONENT.md), [Tooltip](../../components/tooltip/COMPONENT.md), [Popover](../../components/popover/COMPONENT.md) (compact flyout), [Button](../../components/button/COMPONENT.md) (header toggle, row action), [Avatar](../../components/avatar/COMPONENT.md) slot, Icon (`nav.sidebarCollapse`, `nav.sidebarExpand`, `nav.chevronsLeft`, `nav.chevronDown`, `nav.chevronsUpDown`, `action.add`, `action.more`)
 - **See also:** [AppShell](../app-shell/COMPONENT.md), [Dropdown](../../components/dropdown/COMPONENT.md) (account menu), [Drawer](../../components/drawer/COMPONENT.md), [Kbd](../../components/kbd/COMPONENT.md)

package/src/layout/sidebar/examples/account.tsx

@@ -63,7 +63,7 @@ export default function SidebarAccountExample() {
                 Анна Смирнова
               </Sidebar.Account>
             </Dropdown.Trigger>
-            <Dropdown.Content side="right" align="end">
+            <Dropdown.Content side="right">
               <Dropdown.Item>
                 <Dropdown.ItemIcon>
                   <Icon name="object.users" />

package/src/layout/sidebar/examples/overview.tsx

@@ -96,7 +96,7 @@ export default function SidebarOverviewExample() {
                 Анна Смирнова
               </Sidebar.Account>
             </Dropdown.Trigger>
-            <Dropdown.Content side="right" align="end">
+            <Dropdown.Content side="right">
               <Dropdown.Item>
                 <Dropdown.ItemIcon>
                   <Icon name="object.user" />

package/src/styles/controls.css

@@ -0,0 +1,138 @@
+/* Browser form-control styles switched off (part of `bundle.css`, always on). Every UA look —
+   native chrome, autofill paint, spin buttons, pickers, credential badges — is removed, so a
+   control is drawn only by its component and looks the same in every browser. Everything sits in
+   the `prime-reset` cascade layer: any unlayered rule wins over it whatever the specificity and the
+   file order — every component rule, the zero-specificity shared ones too (`:where(.trigger)`). */
+
+@layer prime-reset {
+  :where(html) {
+    -webkit-text-size-adjust: 100%;
+    text-size-adjust: 100%;
+  }
+
+  :where(button, input, select, textarea, optgroup) {
+    margin: 0;
+    font: inherit;
+    letter-spacing: inherit;
+    color: inherit;
+    -webkit-appearance: none;
+    appearance: none;
+  }
+
+  :where(button, input:not([type="checkbox"], [type="radio"]), select, textarea) {
+    border-radius: 0;
+  }
+
+  :where(button, [type="button"], [type="submit"], [type="reset"]) {
+    padding: 0;
+    border: 0;
+    background: none;
+    text-align: inherit;
+  }
+
+  :where(fieldset) {
+    min-width: 0;
+    margin: 0;
+    padding: 0;
+    border: 0;
+  }
+
+  :where(legend) {
+    padding: 0;
+  }
+
+  :where(progress, meter) {
+    -webkit-appearance: none;
+    appearance: none;
+  }
+
+  :where(select)::-ms-expand {
+    display: none;
+  }
+
+  /* Number: no spin buttons. */
+  :where(input[type="number"]) {
+    -moz-appearance: textfield;
+  }
+
+  input[type="number"]::-webkit-inner-spin-button,
+  input[type="number"]::-webkit-outer-spin-button {
+    -webkit-appearance: none;
+    margin: 0;
+  }
+
+  /* Search: no native clear / magnifier. */
+  input[type="search"]::-webkit-search-decoration,
+  input[type="search"]::-webkit-search-cancel-button,
+  input[type="search"]::-webkit-search-results-button,
+  input[type="search"]::-webkit-search-results-decoration {
+    -webkit-appearance: none;
+    display: none;
+  }
+
+  /* Date / time: no native picker glyph, no inner padding. */
+  input::-webkit-calendar-picker-indicator {
+    display: none;
+    -webkit-appearance: none;
+  }
+
+  input::-webkit-date-and-time-value {
+    min-height: 0;
+    text-align: inherit;
+  }
+
+  input::-webkit-datetime-edit,
+  input::-webkit-datetime-edit-fields-wrapper {
+    padding: 0;
+  }
+
+  /* File / color: no native button or swatch frame. */
+  input[type="file"]::file-selector-button,
+  input[type="file"]::-webkit-file-upload-button {
+    margin: 0;
+    padding: 0;
+    border: 0;
+    background: none;
+    color: inherit;
+    font: inherit;
+  }
+
+  input[type="color"]::-webkit-color-swatch-wrapper {
+    padding: 0;
+  }
+
+  input[type="color"]::-webkit-color-swatch {
+    border: 0;
+  }
+
+  input[type="color"]::-moz-color-swatch {
+    border: 0;
+  }
+
+  /* Safari's autofill / credentials / contacts badges. */
+  input::-webkit-contacts-auto-fill-button,
+  input::-webkit-credentials-auto-fill-button,
+  input::-webkit-strong-password-auto-fill-button {
+    /* biome-ignore lint/complexity/noImportantStyles: the UA badge is `!important` itself */
+    display: none !important;
+    visibility: hidden;
+    pointer-events: none;
+  }
+
+  /* Autofill paint (Chrome yellow / blue fill, forced text colour) never shows: the field keeps its
+     own surface and text. The background cannot be overridden directly, so its transition is pushed
+     out of reach; the text colour and caret are set explicitly. */
+  input:is(:-webkit-autofill, :autofill),
+  textarea:is(:-webkit-autofill, :autofill),
+  select:is(:-webkit-autofill, :autofill) {
+    -webkit-text-fill-color: var(--prime-color-text-primary);
+    caret-color: var(--prime-color-text-primary);
+    transition:
+      background-color 600000s 0s,
+      color 600000s 0s;
+  }
+
+  input:is(:-webkit-autofill, :autofill):disabled {
+    -webkit-text-fill-color: var(--prime-color-text-disabled);
+  }
+}