prime-ui-kit 0.9.1 → 0.9.2

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

@@ -0,0 +1,153 @@
+# BottomNav
+
+**Category:** navigation
+**Kind:** layout
+
+> Phone navigation: a bar of 3–5 main sections at the bottom of the screen.
+
+## 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).
+
+## 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 «Ещё».
+- 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.
+
+## Import
+```tsx
+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
+```
+
+## API
+
+<!-- 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.
+
+| 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`. |
+| `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. |
+
+### 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`. |
+| `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). |
+| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `aria-*`, `className` and the other attributes. |
+
+### BottomNav.ItemIcon
+`ref` → `HTMLSpanElement`. The item glyph (`aria-hidden`, 20) above the label.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon, e.g. `<Icon name="nav.home" />`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
+
+### BottomNav.ItemCount
+`ref` → `HTMLSpanElement` (the Badge). An `xs` Badge on the icon's top-end corner; read after the label («Заказы 12»).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The number (or a short status such as «99+»). |
+| `color` | `PaletteColor` | `"red"` | Badge hue: a count on a section asks for attention. |
+| `variant` | `"solid" \| "soft" \| "outline"` | `"solid"` | Badge treatment. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "color">` | — | `className` and the other span attributes. |
+
+## Variants
+
+Two item states only — current (primary color) and not (muted); no hover, no fill.
+
+### Flags (Root)
+| Flag | 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 | |
+
+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 |
+| `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 |
+| 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`) |
+| 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-bg-raised`), 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.
+
+## 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.
+- Surface fill with a faint top divider; inside `AppShell.Footer` the bar sticks to the bottom of the panel.
+
+## Accessibility
+
+### 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). |
+
+### 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 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`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `nav` | `"Основные разделы"` | `aria-label` of the `<nav>` landmark. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [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`. |
+| [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`. |
+
+## Mistakes
+- Six or more items → keep 3–5; 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.
+
+## Related
+- **Built from:** Badge, VisuallyHidden (internal)
+- **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

@@ -0,0 +1,39 @@
+/* Layout of the BottomNav scenarios: a phone-wide screen frame. 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));
+  height: calc(var(--prime-space-24) * 5);
+  margin-inline: auto;
+  overflow: hidden;
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-bg-surface);
+  box-shadow:
+    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
+    var(--prime-shadow-raised);
+}
+
+/* The page above the bar. */
+.screen {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  gap: var(--prime-space-2);
+  min-height: 0;
+  padding: var(--prime-space-6) var(--prime-layout-gutter-s);
+}
+
+/* in-app-shell.tsx: the shell fills the phone frame instead of the viewport. */
+.shell {
+  height: 100%;
+}
+
+/* floating.tsx: a client row — avatar and two lines of text. */
+.client {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-space-3);
+}

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

@@ -0,0 +1,89 @@
+/** A glass capsule over the page: the client list scrolls under its blur, with labels or icons alone — `floating`, `iconOnly`. */
+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" },
+  { id: "settings", label: "Настройки", icon: "action.settings" },
+] 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 BottomNavFloatingExample() {
+  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.Actions>
+            <Switch.Root checked={iconOnly} onCheckedChange={setIconOnly}>
+              <Switch.Label>Только иконки</Switch.Label>
+            </Switch.Root>
+          </AppHeader.Actions>
+        </AppHeader.Root>
+        <AppShell.Main>
+          <PageContent.Section>
+            <PageContent.Body>
+              {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.Root>
+        </AppShell.Footer>
+      </AppShell.Root>
+    </div>
+  );
+}

package/src/layout/bottom-nav/examples/icon-only.tsx

@@ -0,0 +1,41 @@
+/** Icons alone: the labels are hidden but still name the sections for screen readers — `iconOnly`. */
+import { BottomNav, Icon, 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: "orders", label: "Заказы", icon: "object.package" },
+  { id: "inbox", label: "Входящие", icon: "object.inbox" },
+  { id: "profile", label: "Профиль", icon: "object.user" },
+] as const;
+
+export default function BottomNavIconOnlyExample() {
+  const [section, setSection] = React.useState<string>("home");
+  const current = SECTIONS.find((item) => item.id === section) ?? SECTIONS[0];
+
+  return (
+    <div className={styles.phone}>
+      <div className={styles.screen}>
+        <Typography as="h2" variant="title-m">
+          {current.label}
+        </Typography>
+      </div>
+      <BottomNav.Root 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.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,64 @@
+/** 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`. */
+import {
+  AppHeader,
+  AppShell,
+  BottomNav,
+  Button,
+  Icon,
+  PageContent,
+  Typography,
+} from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { label: "Главная", icon: "nav.home" },
+  { label: "Заказы", icon: "object.package" },
+  { label: "Клиенты", icon: "object.users" },
+  { label: "Ещё", icon: "action.more" },
+] as const;
+
+const ORDERS = ["№ 4821 · ООО «Север»", "№ 4820 · ИП Котов", "№ 4819 · ООО «Вектор»"];
+
+export default function BottomNavInAppShellExample() {
+  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>
+              {ORDERS.map((order) => (
+                <Typography key={order} variant="body-m">
+                  {order}
+                </Typography>
+              ))}
+              <Button.Root variant="soft" tone="neutral">
+                <Button.Icon>
+                  <Icon name="action.add" />
+                </Button.Icon>
+                Новый заказ
+              </Button.Root>
+            </PageContent.Body>
+          </PageContent.Section>
+        </AppShell.Main>
+        <AppShell.Footer>
+          <BottomNav.Root>
+            {SECTIONS.map((item, index) => (
+              <BottomNav.Item key={item.label} current={index === 1}>
+                <BottomNav.ItemIcon>
+                  <Icon name={item.icon} />
+                </BottomNav.ItemIcon>
+                {item.label}
+              </BottomNav.Item>
+            ))}
+          </BottomNav.Root>
+        </AppShell.Footer>
+      </AppShell.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,44 @@
+/** Four sections of the app, the current one in the primary color and a tap moves it — `current`, `BottomNav.ItemIcon`. */
+import { BottomNav, Icon, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SECTIONS = [
+  { id: "home", label: "Главная", icon: "nav.home", summary: "Выручка за неделю — 1,2 млн ₽" },
+  { id: "orders", label: "Заказы", icon: "object.package", summary: "37 заказов ждут отгрузки" },
+  { id: "clients", label: "Клиенты", icon: "object.users", summary: "214 активных клиентов" },
+  { id: "settings", label: "Настройки", icon: "action.settings", summary: "Профиль и уведомления" },
+] as const;
+
+export default function BottomNavOverviewExample() {
+  const [section, setSection] = React.useState<string>("orders");
+  const current = SECTIONS.find((item) => item.id === section) ?? SECTIONS[0];
+
+  return (
+    <div className={styles.phone}>
+      <div className={styles.screen}>
+        <Typography as="h2" variant="title-m">
+          {current.label}
+        </Typography>
+        <Typography variant="body-m" tone="secondary">
+          {current.summary}
+        </Typography>
+      </div>
+      <BottomNav.Root>
+        {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.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,31 @@
+/** A router link as the item: the router sets `aria-current` and the item shows as current; render it inside a router — `asChild`. */
+import { BottomNav, Icon } from "prime-ui-kit";
+import { NavLink } from "react-router-dom";
+
+import styles from "./examples.module.css";
+
+const LINKS = [
+  { to: "/app-shell", label: "Каркас", icon: "nav.layoutGrid" },
+  { to: "/bottom-nav", label: "Навигация", icon: "nav.menu" },
+  { to: "/sidebar", label: "Сайдбар", icon: "nav.sidebarExpand" },
+] as const;
+
+export default function BottomNavRouterExample() {
+  return (
+    <div className={styles.phone}>
+      <div className={styles.screen} />
+      <BottomNav.Root>
+        {LINKS.map((link) => (
+          <BottomNav.Item key={link.to} asChild>
+            <NavLink to={link.to}>
+              <BottomNav.ItemIcon>
+                <Icon name={link.icon} />
+              </BottomNav.ItemIcon>
+              {link.label}
+            </NavLink>
+          </BottomNav.Item>
+        ))}
+      </BottomNav.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,47 @@
+/** Counts on the icons and a section that is not available yet — `BottomNav.ItemCount`, `disabled`. */
+import { BottomNav, Icon, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function BottomNavStructureExample() {
+  return (
+    <div className={styles.phone}>
+      <div className={styles.screen}>
+        <Typography as="h2" variant="title-m">
+          Главная
+        </Typography>
+        <Typography variant="body-m" tone="secondary">
+          12 новых заказов и 3 сообщения от клиентов.
+        </Typography>
+      </div>
+      <BottomNav.Root>
+        <BottomNav.Item current>
+          <BottomNav.ItemIcon>
+            <Icon name="nav.home" />
+          </BottomNav.ItemIcon>
+          Главная
+        </BottomNav.Item>
+        <BottomNav.Item>
+          <BottomNav.ItemIcon>
+            <Icon name="object.package" />
+          </BottomNav.ItemIcon>
+          <BottomNav.ItemCount>12</BottomNav.ItemCount>
+          Заказы
+        </BottomNav.Item>
+        <BottomNav.Item>
+          <BottomNav.ItemIcon>
+            <Icon name="object.message" />
+          </BottomNav.ItemIcon>
+          <BottomNav.ItemCount color="blue">3</BottomNav.ItemCount>
+          Сообщения
+        </BottomNav.Item>
+        <BottomNav.Item disabled>
+          <BottomNav.ItemIcon>
+            <Icon name="object.chart" />
+          </BottomNav.ItemIcon>
+          Отчёты
+        </BottomNav.Item>
+      </BottomNav.Root>
+    </div>
+  );
+}

package/src/layout/sidebar/COMPONENT.md

@@ -1,6 +1,6 @@
 # Sidebar
 
-**Category:** layout
+**Category:** navigation
 **Kind:** layout
 
 > App side navigation in three modes — expanded, compact, hidden — and an off-canvas panel on narrow screens.
@@ -22,7 +22,8 @@ same place. Structure it by what people do, not by how the backend is split.
   tooltip), so start sibling labels differently («Продажи» and «Проекты» both read «Про»).
 - **Fold only what is secondary.** Make a group `collapsible` when the list is long (about 12+
   items) or the group is used rarely; keep the main group open and fixed. `defaultOpen={false}`
-  only for rarely used groups — a group with the current page opens by itself.
+  only for rarely used groups — a group with the current page opens by itself (on the compact rail
+  it stays folded; its `…` row marks the page).
 - **One level of nesting.** `Sidebar.Sub` is one section with 2–6 views of the same objects
   (Сделки → Новые · В работе · Закрытые). The parent only discloses; an overview page is the first
   child («Все сделки»). Never a sub-list inside a sub-list — split the section or use page tabs.
@@ -128,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. 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 (`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).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -136,7 +137,7 @@ useSidebar()                       state hook for custom parts inside Root
 | `collapsible` | `boolean` | `false` | The heading shows and hides the items. Needs `label`. |
 | `open` | `boolean` | — | Items shown (controlled). |
 | `onOpenChange` | `(open: boolean) => void` | — | Called with the new open state (click, keyboard, a current page moving inside). |
-| `defaultOpen` | `boolean` | `true` | Initial state (uncontrolled). A closed group opens by itself when the current page moves into it. |
+| `defaultOpen` | `boolean` | `true` | Initial state (uncontrolled). Off the compact rail a closed group opens by itself when the current page moves into it; on the rail it stays folded and its `…` row marks the page. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `children` (Items, Subs), `className` and the other div attributes. |
 
 ### Sidebar.Item
@@ -178,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 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. 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.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -289,7 +290,7 @@ The rail width does not depend on `size`.
 | `current` (Item) | surface fill + raised shadow, 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 a menu button in `AppShell.Header` (`open` / `onOpenChange`). One current item at a time; give every top-level item an icon when the rail can go compact (child items need none).
+Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header, or `Sidebar.Toggle` in the footer for a rail without a brand; 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).
 
 ## States
 | State | Driven by | DOM |
@@ -297,7 +298,7 @@ Put `<Sidebar.Toggle variant="header" />` next to `Sidebar.Brand` in the header,
 | mode | `mode` / `defaultMode` | Root `data-mode`, `data-panel-mode` (the last visible mode while hidden); `<nav inert>` while hidden |
 | off-canvas | `offCanvas="always"`, or `"auto"` + viewport < 768px | Root `data-off-canvas`, `data-state="open" \| "closed"`; `<nav inert>` while closed |
 | current | `current` or a router's `aria-current` | Item `aria-current="page"`, `data-state="active"` |
-| active path | a child of a Sub (or an item of a Group) is current | SubTrigger `data-active-path`; a closed Sub / Group opens |
+| active path | a child of a Sub (or an item of a Group) is current | SubTrigger (or the `…` row of a folded Group) `data-active-path`; a closed Sub opens, a closed Group opens off the compact rail |
 | group open | Group `open` / `defaultOpen` (`collapsible`) | heading `aria-expanded`; region `data-state`, `inert` while closed |
 | sub open | Sub `open` / `defaultOpen` | SubTrigger `aria-expanded`; SubContent `data-state`, `inert` while closed |
 | flyout | hover / click / keyboard on a SubTrigger, or on the `…` row of a folded group, in compact mode | the row `aria-haspopup="dialog"`, `aria-expanded`; a Popover `role="dialog"` |
@@ -312,9 +313,9 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 - Item horizontal padding is derived from the compact width so icons and the brand logo sit on one axis in every mode (the account avatar joins that axis on the rail).
 - Header is one row of the item height + 8. The header toggle (xs, 28) sits at its end, 8 from the rail edge; in compact mode it moves half past the edge, scales to 3/4, turns round and gets a canvas ring. The root clips with `clip-path`, reaching past the edge by the toggle's half-width and ring beside the header only; everywhere else the panel ends exactly at the spacer edge.
 - Collapsible group: heading 28 high with the chevron (14) at its end, aligned with the item trail; items start 4 below. A folded group's attention dot sits before the chevron.
-- On the rail a heading keeps its 28 and its layout: the text slides 8 toward the edge, scales to 0.85 and is cut at the rail box with a 12 fade into the canvas. A folded group adds one `…` row under its heading.
+- On the rail a heading keeps its 28 and its layout: the text slides 8 toward the edge, scales to 0.85 and is cut at the rail box with a 12 fade into the canvas. A folded group adds one `…` row under its heading. The items and the row share one place: folding or unfolding on the rail glides the group's height one way (list ↔ row) while the two cross-fade, so the rows below never move back.
 - Sub-list: a 1px `border-default` guide line on the parent icon's centre; every child branches off it with an 8 elbow and a 6 bend; child labels line up with the parent label.
-- Trail (count, key hint, trailing icon) sits at the row end; a row action (one tier down) appears there on hover / focus and the trail moves aside.
+- Trail (count, key hint, trailing icon) sits at the row end; a row action (one tier down) appears there on hover / focus (always on touch screens) and the trail moves aside.
 - Footer: items 4 apart; the account is set 8 apart below them. It is its own card-like row: the
   avatar of the tier (xs 20, s 24, m·l 32, xl 40) sits in an even frame — the inset before it, the
   gap to the text and the air above and below are one value, the tier gap (xs 4, s·m·l 8, xl 12),
@@ -344,7 +345,7 @@ Leaving the narrow viewport closes the off-canvas panel; navigating from an `hre
 - The current item has `aria-current="page"`; in compact mode the label shows as a tooltip, so icon-only items keep a visible name.
 - A collapsible group heading and a SubTrigger are buttons with `aria-expanded` and `aria-controls`; folded content is `inert`.
 - 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 group heading is out of the tab order and hidden from screen readers (the group keeps its name); hovering it shows the whole name in a tooltip.
+- 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.
 - 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.

package/src/styles/theme-dark.css

@@ -7,6 +7,9 @@
   --prime-color-accent-soft-hover: color-mix(in srgb, var(--prime-ref-color-cobalt-500) 28%, transparent);
   --prime-color-accent-text: var(--prime-ref-color-cobalt-400);
   --prime-color-bg-canvas: var(--prime-ref-color-gray-950);
+  --prime-color-bg-edge-shadow: rgba(0, 0, 0, 0.5);
+  --prime-color-bg-glass: color-mix(in srgb, var(--prime-ref-color-gray-875) 56%, transparent);
+  --prime-color-bg-glass-edge: rgba(255, 255, 255, 0.16);
   --prime-color-bg-inverse: var(--prime-ref-color-gray-100);
   --prime-color-bg-raised: var(--prime-ref-color-gray-875);
   --prime-color-bg-scrim: rgba(0, 0, 0, 0.6);