prime-ui-kit 0.13.1 → 0.15.0

package/dist/skill/layouts.md

@@ -1,14 +1,15 @@
 # Layouts — app frame, page wrappers, auth
 
 Every screen sits in one frame: `AppShell.Root` with Nav / `AppHeader` / Main (the content panel is the page,
-the nav rail one layer above it) → `PageContent` (header + body). `AppShell.Main` carries the page gutters
-and `PageContent.Body` spaces its blocks 40 apart, so your code adds **no outer padding and no
-margins**. Your CSS only lays out the inside of a block (grids, rows) with `gap` on `--prime-space-*`.
-Main's top space under the header is part of the frame — 24, then 40 from 1024px: a page header starts
-there; never cancel it with a negative margin or a padding override.
+the nav rail one layer above it). The `AppHeader` belongs to the page — it carries the page title and
+the page's tools ([composition.md](composition.md#1-page-skeleton)); `PageContent` holds the body.
+`AppShell.Main` carries the page gutters and `PageContent` spaces the page — blocks 24, a titled
+`PageContent.Section` 40, tiles in a `PageContent.Grid` 16 on both axes — so your code adds **no outer padding and no margins**. Your CSS only lays out the inside of a block (grids, rows) with `gap` on `--prime-space-*`.
+Main's top air under the header is part of the frame — 24, then 32 from 1024px: the page's first block
+starts there; never cancel it with a negative margin or a padding override.
 
-The page recipes are whole, working screens in [patterns/](patterns/) — start from the closest one
-([the list](composition.md#patterns)) and keep its skeleton. The rules behind them are in [composition.md](composition.md).
+The page recipes are whole, working screens — the `screen.tsx` example of their main component
+([the list](composition.md#screens)): start from the closest one and keep its skeleton. The rules behind them are in [composition.md](composition.md).
 
 ## App frame (once per app)
 
@@ -16,18 +17,31 @@ Every `Sidebar.Item` gets a `Sidebar.ItemIcon` (in compact mode only icons remai
 `href`, or `asChild` with the router's `NavLink`; `current` marks the current page (`aria-current`), a
 router link sets it itself. Counters go in `Sidebar.ItemCount`. Below 768px the Sidebar becomes an
 off-canvas panel — the app must render a menu button that opens it, otherwise navigation is unreachable
-on phones. `AppHeader` is the top bar of the panel on every width: `AppHeader.MenuButton` shows itself
-below 768px (the Sidebar's own breakpoint), the title says where you are, `AppHeader.Search` opens the
-CommandMenu and folds into an icon on a narrow header. Its row is as high as the Sidebar brand row, so
-the brand and the title read as one line.
+on phones. `AppHeader` is the top bar of the panel on every width, and its row is the page's: the
+frame gives it the menu button (`AppHeader.MenuButton` shows itself below 768px, the Sidebar's own
+breakpoint); each page gives it its title, a line of data, its own buttons and its tools. The row is
+as high as the Sidebar brand row, so the brand and the title read as one line. Nothing app-wide goes
+into it — no global search, no notifications: the header row is per page.
 
 ```tsx
 import { AppHeader, AppShell, Icon, NotificationProvider, Sidebar } from "prime-ui-kit";
 import { type ReactNode, useState } from "react";
 
-type AppLayoutProps = { title: string; onSearch: () => void; children: ReactNode };
-
-export function AppLayout({ title, onSearch, children }: AppLayoutProps) {
+type AppLayoutProps = {
+  /** The page title — the page's h1; leave it out on a document page (its title is in main). */
+  title?: ReactNode;
+  /** One line of data under the title. */
+  description?: ReactNode;
+  /** The path up on a nested record: a `Breadcrumb.Root`. */
+  path?: ReactNode;
+  /** The page's own buttons in the title row. */
+  actions?: ReactNode;
+  /** The page's tools: a `PageToolbar.Root`. */
+  tools?: ReactNode;
+  children: ReactNode;
+};
+
+export function AppLayout({ title, description, path, actions, tools, children }: AppLayoutProps) {
   const [menuOpen, setMenuOpen] = useState(false);
   return (
     <NotificationProvider>
@@ -79,10 +93,21 @@ export function AppLayout({ title, onSearch, children }: AppLayoutProps) {
         <AppHeader.Root>
           <AppHeader.Start>
             <AppHeader.MenuButton aria-expanded={menuOpen} onClick={() => setMenuOpen(true)} />
-            <AppHeader.Title>{title}</AppHeader.Title>
+            {path ? (
+              <>
+                {path}
+                <AppHeader.Separator />
+              </>
+            ) : null}
+            {title ? (
+              <AppHeader.Title>
+                {title}
+                {description ? <AppHeader.Description>{description}</AppHeader.Description> : null}
+              </AppHeader.Title>
+            ) : null}
           </AppHeader.Start>
-          {/* Opens the app's CommandMenu; bind ⌘K to the same handler. */}
-          <AppHeader.Search onClick={onSearch}>Поиск заказов и клиентов</AppHeader.Search>
+          {actions ? <AppHeader.Actions>{actions}</AppHeader.Actions> : null}
+          {tools ? <AppHeader.Tools>{tools}</AppHeader.Tools> : null}
         </AppHeader.Root>
         <AppShell.Main>{children}</AppShell.Main>
       </AppShell.Root>
@@ -91,6 +116,11 @@ export function AppLayout({ title, onSearch, children }: AppLayoutProps) {
 }
 ```
 
+Each page renders `AppLayout` with its own header content:
+`<AppLayout title="Заказы" description="128 в работе · 6 ждут оплаты" tools={<OrdersToolbar />}>`.
+A document page (settings, a long form, help) passes no `title` and opens its body with
+`PageContent.Header`.
+
 Phone navigation for 2–6 main sections is a `BottomNav.Root` in `AppShell.Footer` (the last child of
 `AppShell.Root`, or the Template `footer` prop) — never in Main, never `position: fixed`, never behind
 your own media query. The shell hides the footer while the Sidebar rail is on screen and shows it
@@ -101,21 +131,19 @@ Next.js App Router: the package is marked `"use client"`, but a server component
 `"use client"` and render them from `app/layout.tsx` and the pages; import `bundle.css` in the root
 layout and put `data-theme` on `<html>` there.
 
-A nested record page keeps its `Breadcrumb` at the top of `PageContent.Header`, above the title
-([patterns/detail-page.tsx](patterns/detail-page.tsx)) — not in `AppHeader`. `AppHeader.Actions` holds at most notifications, the account and one primary action; page
-actions stay in `PageContent.Actions`. With `offCanvas="always"` pass `show="always"` to the menu button.
-
-### The page title in the header
+A nested record page puts the path up before its title in the header — `Breadcrumb` (the list it
+belongs to), `AppHeader.Separator`, `AppHeader.Title` with the record's name and its status as
+the description ([the detail page](reference/components/description-list/examples/screen.tsx)). With
+`offCanvas="always"` pass `show="always"` to the menu button.
 
-A page that wants all its height for the work (a board, a chat, a dense register) may drop the
-heading row in main and let the header carry the page — one or the other, never both:
+### The page's tools in the header
 
-- `AppHeader.Title as="h1"` is the page's only `<h1>` (the description stays outside its name);
-  main then has no `PageContent.Header`.
-- The page's tools — sections, the period, filters, the page's primary action — go into
-  `AppHeader.Tools` as a `PageToolbar.Root`: the header's second row, full width, sticky with it. The
-  toolbar lays itself out from that width (one row when wide, two on a phone), so the tools wrap
-  under the title instead of squeezing it. `AppHeader.Actions` keeps notifications and the account.
+The page's tools — its own search and filters, sections, the period or view, the primary action —
+go into `AppHeader.Tools` as a `PageToolbar.Root`: the header's second row, full width, sticky with
+it. The toolbar lays itself out from that width (one row when wide, stacked rows on a phone, the
+primary action on its own row when the search would be squeezed), so the tools wrap under the title
+instead of squeezing it. `AppHeader.Actions` keeps the page's other buttons (export, a more menu) in
+the title row.
 
 ```tsx
 import { AppHeader, Button, Icon, PageToolbar, SegmentedControl } from "prime-ui-kit";
@@ -126,7 +154,10 @@ export function DealsHeader({ view, onViewChange }: DealsHeaderProps) {
   return (
     <AppHeader.Root>
       <AppHeader.Start>
-        <AppHeader.Title as="h1">Сделки</AppHeader.Title>
+        <AppHeader.Title>
+          Сделки
+          <AppHeader.Description>7 сделок в работе · 6 461 750 ₽</AppHeader.Description>
+        </AppHeader.Title>
       </AppHeader.Start>
       <AppHeader.Tools>
         <PageToolbar.Root aria-label="Сделки">
@@ -181,11 +212,13 @@ from what people do, not from how the backend is split. The full guide with the
 
 ## Page wrapper
 
-- App pages with actions (dashboard, list, detail): `PageContent.Section` — the full width of the panel.
-- Settings and long forms: `PageContent.Root maxWidth="wide"` with a heading column + panel per section
-  ([patterns/settings-page.tsx](patterns/settings-page.tsx)), or `maxWidth="readable"` for a single
+- App pages (dashboard, list, detail, a board): `PageContent.Page` — the full width of the panel; the
+  page's title and tools are in its `AppHeader`, the body starts with its first block.
+- Document pages — settings and long forms: `PageContent.Root maxWidth="wide"` with `PageContent.Header`
+  (the page's h1) and a `PageContent.Section layout="aside"`
+  (heading column + panel) per section ([the settings page](reference/components/page-content/examples/screen.tsx)), or `maxWidth="readable"` for a single
   narrow column of fields.
-- Long reading text (terms, help): `PageContent.Root maxWidth="readable"`.
+- Long reading text (terms, help): `PageContent.Root maxWidth="readable"` with `PageContent.Header`.
 - A page as high as the panel (a log, a board, a chat): `AppShell.Root fillViewport` +
   `PageContent.Root fill`; the body passes its free height to a filling child — DataTable
   `scrollHeight="fill"`, Crossfade `fill`, `PageContent.Split`. Never compute heights from `100vh`.
@@ -196,9 +229,9 @@ from what people do, not from how the backend is split. The full guide with the
   (`anchor="end"` for a thread). The records in the list pane are a `List` (`current` on the open
   one). Details that open over a table and close again are a Drawer instead.
 
-## Which pattern to start from
+## Which screen to start from
 
-The table of screens and their patterns lives in [composition.md](composition.md#patterns).
+The table of screens lives in [composition.md](composition.md#screens).
 
 A short form (≤ 4 fields: rename, invite, confirm with a reason) belongs in a `Modal` with the same
 form rules: `Modal.Body` holds the `<form id>`, `Modal.Footer` holds Cancel + submit with `form={id}`

package/dist/skill/reference/components/avatar/COMPONENT.md

@@ -67,7 +67,7 @@ Avatar.Group           overlapping row, gives its size to members
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `status` | `"online" \| "offline" \| "away" \| "busy"` | — (required) | Presence state: green, gray, warning or danger dot. |
+| `status` | `"online" \| "offline" \| "away" \| "busy"` | — (required) | Presence state, told by shape and color: `online` a full green dot, `away` a warning crescent, `busy` a danger dot with a bar, `offline` a hollow gray ring. |
 | `labels` | `Partial<AvatarStatusLabels>` | — | Accessible names of the states, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
@@ -129,7 +129,7 @@ No keyboard interaction.
 
 ### ARIA
 - `Avatar.Image` `alt`: empty when the name is written next to it, otherwise the name. Without a photo and without a name nearby, put `aria-label` on `Avatar.Root`.
-- `Avatar.Status` is `role="img"` with `aria-label` from `labels`.
+- `Avatar.Status` is `role="img"` with `aria-label` from `labels`. Every state has its own shape (full dot, crescent, dot with a bar, hollow ring), so presence never rests on color alone.
 - `Avatar.Group` is `role="group"`; give it `aria-label`. Give `Avatar.Overflow` an `aria-label` («Ещё 3 участника»).
 
 ### Labels
@@ -148,8 +148,8 @@ No keyboard interaction.
 | [overview.tsx](examples/overview.tsx) | A photo with initials underneath while it loads, and initials alone — `Avatar.Image`, `Avatar.Fallback`. |
 | [variants.tsx](examples/variants.tsx) | Every palette hue of the fallback; derive it from a stable user id — `color`. |
 | [sizes.tsx](examples/sizes.tsx) | Every diameter, 20 to 64 px; initials take 40% of it — `size`. |
-| [states.tsx](examples/states.tsx) | A loaded photo, a broken URL that falls back to initials, and an icon fallback for a guest. |
-| [presence.tsx](examples/presence.tsx) | A presence dot on the avatar edge, announced by its state name — `Avatar.Status`, `labels`. |
+| [states.tsx](examples/states.tsx) | A loaded photo, a broken URL that falls back to initials, and an icon fallback for a guest — `Avatar.Image`, `Avatar.Fallback`. |
+| [presence.tsx](examples/presence.tsx) | A presence dot on the avatar edge: each state has its own shape and color and is announced by its name — `Avatar.Status`, `labels`. |
 | [team-group.tsx](examples/team-group.tsx) | Project members as an overlapping row with a «+N» cell; the group size goes to every member — `Avatar.Group`, `Avatar.Overflow`, `size`. |
 | [src-from-state.tsx](examples/src-from-state.tsx) | A new photo source restarts loading; initials show until the new photo arrives — `src`. |
 

package/dist/skill/reference/components/avatar/examples/presence.tsx

@@ -1,4 +1,4 @@
-/** A presence dot on the avatar edge, announced by its state name — `Avatar.Status`, `labels`. */
+/** A presence dot on the avatar edge: each state has its own shape and color and is announced by its name — `Avatar.Status`, `labels`. */
 import { Avatar, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/dist/skill/reference/components/avatar/examples/states.tsx

@@ -1,4 +1,4 @@
-/** A loaded photo, a broken URL that falls back to initials, and an icon fallback for a guest. */
+/** A loaded photo, a broken URL that falls back to initials, and an icon fallback for a guest — `Avatar.Image`, `Avatar.Fallback`. */
 import { Avatar, Icon, Typography } from "prime-ui-kit";
 
 const PHOTO = "https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=128&h=128&fit=crop";
@@ -7,7 +7,7 @@ export default function AvatarStatesExample() {
   return (
     <div>
       <div>
-        <Avatar.Root size="xl" color="green">
+        <Avatar.Root color="green">
           <Avatar.Image src={PHOTO} alt="Михаил Котов" />
           <Avatar.Fallback>МК</Avatar.Fallback>
         </Avatar.Root>
@@ -16,7 +16,7 @@ export default function AvatarStatesExample() {
         </Typography>
       </div>
       <div>
-        <Avatar.Root size="xl" color="orange">
+        <Avatar.Root color="orange">
           <Avatar.Image src="https://example.com/missing-avatar.png" alt="Сергей Лебедев" />
           <Avatar.Fallback>СЛ</Avatar.Fallback>
         </Avatar.Root>
@@ -25,9 +25,9 @@ export default function AvatarStatesExample() {
         </Typography>
       </div>
       <div>
-        <Avatar.Root size="xl" aria-label="Гость">
+        <Avatar.Root aria-label="Гость">
           <Avatar.Fallback>
-            <Icon name="field.email" />
+            <Icon name="object.user" />
           </Avatar.Fallback>
         </Avatar.Root>
         <Typography as="span" variant="caption" tone="muted">

package/dist/skill/reference/components/badge/examples/applied-filters.tsx

@@ -8,23 +8,9 @@ const INITIAL = ["Москва", "Санкт-Петербург", "Есть в
 
 export default function BadgeAppliedFiltersExample() {
   const [filters, setFilters] = React.useState(INITIAL);
-  const titleId = React.useId();
 
   return (
-    <section className={styles.filters} aria-labelledby={titleId}>
-      <div className={styles.filtersHeader}>
-        <Typography as="h3" variant="title-s" id={titleId}>
-          Фильтры
-        </Typography>
-        <Button.Root
-          variant="ghost"
-          tone="neutral"
-          size="s"
-          onClick={() => setFilters(filters.length > 0 ? [] : INITIAL)}
-        >
-          {filters.length > 0 ? "Сбросить все" : "Вернуть"}
-        </Button.Root>
-      </div>
+    <div className={styles.filters}>
       {filters.length > 0 ? (
         <div className={styles.badges}>
           {filters.map((label) => (
@@ -36,12 +22,20 @@ export default function BadgeAppliedFiltersExample() {
               {label}
             </Badge.Root>
           ))}
+          <Button.Root variant="ghost" tone="neutral" size="s" onClick={() => setFilters([])}>
+            Сбросить все
+          </Button.Root>
         </div>
       ) : (
-        <Typography variant="body-s" tone="muted">
-          Фильтры не выбраны — показаны все товары.
-        </Typography>
+        <div className={styles.badges}>
+          <Typography variant="body-s" tone="muted">
+            Фильтры не выбраны — показаны все товары.
+          </Typography>
+          <Button.Root variant="ghost" tone="neutral" size="s" onClick={() => setFilters(INITIAL)}>
+            Вернуть
+          </Button.Root>
+        </div>
       )}
-    </section>
+    </div>
   );
 }

package/dist/skill/reference/components/badge/examples/examples.module.css

@@ -10,20 +10,13 @@
   width: min(100%, var(--prime-modal-width-m));
 }
 
-/* applied-filters.tsx: a filter panel above a list. */
+/* applied-filters.tsx, server-tags.tsx: a row of badges above a list. */
 .filters {
   display: grid;
   gap: var(--prime-space-3);
   width: min(100%, var(--prime-modal-width-s));
 }
 
-.filtersHeader {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--prime-space-3);
-}
-
 .badges {
   display: flex;
   flex-wrap: wrap;

package/dist/skill/reference/components/badge/examples/server-tags.tsx

@@ -19,13 +19,9 @@ function deleteTag(tag: string) {
 export default function BadgeServerTagsExample() {
   const [tags, setTags] = React.useState(TAGS);
   const [failure, setFailure] = React.useState<string | null>(null);
-  const titleId = React.useId();
 
   return (
-    <section className={styles.filters} aria-labelledby={titleId}>
-      <Typography as="h3" variant="title-s" id={titleId}>
-        Теги заказа № 4821
-      </Typography>
+    <div className={styles.filters}>
       <div className={styles.badges}>
         {tags.map((tag) => (
           <Badge.Root
@@ -56,6 +52,6 @@ export default function BadgeServerTagsExample() {
           {failure}
         </Typography>
       ) : null}
-    </section>
+    </div>
   );
 }

package/dist/skill/reference/components/banner/COMPONENT.md

@@ -46,7 +46,7 @@ Banner.Root                 <div>; variant, tone, size, placement
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"info"` | Semantic color of the message. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Spacing, icon and title follow the control tier; the description is one step smaller. |
 | `placement` | `"inset" \| "page"` | `"inset"` | `inset` — rounded block in the flow or in a card; `page` — edge-to-edge strip above a page, content aligned to the page column. |
-| `onDismiss` | `() => void` | — | Renders a close button (top-right, or last in `Banner.Actions`) and calls this on click; the parent unmounts the banner. |
+| `onDismiss` | `() => void` | — | Renders a close button (top-right, or last in `Banner.Actions`) and calls this on click; the parent unmounts the banner, which closes up in place, and moves focus to a sensible place. |
 | `labels` | `Partial<BannerLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` (`alert`, `status`, `region`), `aria-label` and the other div attributes. |
 
@@ -117,7 +117,7 @@ Banner.Root                 <div>; variant, tone, size, placement
 | dismissible | `onDismiss` | corner ghost Button (`xs`, `s` on `l` / `xl`), or the last outline Button in `Banner.Actions` |
 | narrow | own width < 36rem (a banner with `Banner.Actions` is a size container) | actions move under the text |
 
-No `open` prop: the parent mounts and unmounts the banner.
+No `open` prop: the parent mounts and unmounts the banner. A mounted banner enters (a short fade and rise); an unmounted one closes up in place, so the content below glides up instead of jumping. To swap the banner for another block in the same spot (a «restore» button), wrap both in [Crossfade](../crossfade/COMPONENT.md).
 
 ## Layout & spacing
 - `width: 100%`; text column capped at `--prime-layout-reading-max-width`.
@@ -134,7 +134,7 @@ No `open` prop: the parent mounts and unmounts the banner.
 ### ARIA
 - The banner has no role of its own: give an error after an action `role="alert"`, a calm status `role="status"`, a page strip `role="region"` with `aria-label`.
 - The icon is `aria-hidden`: the title carries the meaning, not the color.
-- The close button is named by `labels.dismiss`; after dismissing, move focus somewhere sensible.
+- The close button is named by `labels.dismiss`. It leaves with the banner, so after dismissing the parent moves focus to a sensible place: the control that takes the banner's spot, or the next heading or action of the section (see `dismissible.tsx`).
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -150,9 +150,9 @@ No `open` prop: the parent mounts and unmounts the banner.
 | [variants.tsx](examples/variants.tsx) | Every treatment on every tone: soft by default, solid for urgent, outline for calm — `variant`, `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier: padding, icon and title follow the control tier, the description is one step smaller — `size`. |
 | [structure.tsx](examples/structure.tsx) | Optional parts: a one-line title, a title with a description, and actions where the close button joins the row — `Banner.Description`, `Banner.Actions`, `onDismiss`. |
-| [dismissible.tsx](examples/dismissible.tsx) | The parent owns visibility: the close button calls back and the parent unmounts the banner; the button name comes from labels — `onDismiss`, `labels`. |
+| [dismissible.tsx](examples/dismissible.tsx) | The parent owns visibility: the close button calls back, the banner closes up and focus moves to the restore button; the button name comes from labels — `onDismiss`, `labels`. |
 | [page-strip.tsx](examples/page-strip.tsx) | An edge-to-edge strip above a page and a rounded block inside a card — `placement`. |
-| [narrow.tsx](examples/narrow.tsx) | Below 36rem of its own width the banner moves the actions under the text. |
+| [narrow.tsx](examples/narrow.tsx) | Below 36rem of its own width the banner moves the actions under the text — `Banner.Actions`. |
 
 ## Mistakes
 - A hand-made × next to the banner → pass `onDismiss`.
@@ -162,4 +162,4 @@ No `open` prop: the parent mounts and unmounts the banner.
 
 ## Related
 - **Built from:** [Button](../button/COMPONENT.md) (close button), Icon (`action.close`)
-- **See also:** [Notification](../notification/COMPONENT.md), [Hint](../hint/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Badge](../badge/COMPONENT.md)
+- **See also:** [Crossfade](../crossfade/COMPONENT.md), [Notification](../notification/COMPONENT.md), [Hint](../hint/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Badge](../badge/COMPONENT.md)

package/dist/skill/reference/components/banner/examples/dismissible.tsx

@@ -1,18 +1,34 @@
-/** The parent owns visibility: the close button calls back and the parent unmounts the banner; the button name comes from labels — `onDismiss`, `labels`. */
-import { Banner, Button, Icon } from "prime-ui-kit";
+/** The parent owns visibility: the close button calls back, the banner closes up and focus moves to the restore button; the button name comes from labels — `onDismiss`, `labels`. */
+import { Banner, Button, Crossfade, Icon } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 export default function BannerDismissibleExample() {
   const [visible, setVisible] = React.useState(true);
+  const bannerRef = React.useRef<HTMLDivElement>(null);
+  const restoreRef = React.useRef<HTMLButtonElement>(null);
+  const toggled = React.useRef(false);
+
+  // The pressed button leaves with its block: focus goes to the control that takes its place.
+  React.useEffect(() => {
+    if (!toggled.current) return;
+    if (visible) bannerRef.current?.querySelector("button")?.focus();
+    else restoreRef.current?.focus();
+  }, [visible]);
+
+  const toggle = (next: boolean) => {
+    toggled.current = true;
+    setVisible(next);
+  };
 
   return (
-    <div className={styles.stack}>
+    <Crossfade state={visible ? "banner" : "restore"} className={styles.region}>
       {visible ? (
         <Banner.Root
+          ref={bannerRef}
           tone="accent"
-          onDismiss={() => setVisible(false)}
+          onDismiss={() => toggle(false)}
           labels={{ dismiss: "Скрыть объявление" }}
         >
           <Banner.Content>
@@ -24,15 +40,10 @@ export default function BannerDismissibleExample() {
           </Banner.Content>
         </Banner.Root>
       ) : (
-        <Button.Root
-          variant="outline"
-          tone="neutral"
-          className={styles.restore}
-          onClick={() => setVisible(true)}
-        >
+        <Button.Root ref={restoreRef} variant="outline" tone="neutral" onClick={() => toggle(true)}>
           Вернуть баннер
         </Button.Root>
       )}
-    </div>
+    </Crossfade>
   );
 }

package/dist/skill/reference/components/banner/examples/examples.module.css

@@ -8,7 +8,7 @@
   min-width: 0;
 }
 
-/* placement.tsx: a page frame above a card. */
+/* page-strip.tsx: the page strip above a card with an inset banner. */
 .sections {
   display: flex;
   flex-direction: column;
@@ -17,16 +17,12 @@
   min-width: 0;
 }
 
-.pageBody {
-  padding: var(--prime-space-5) var(--prime-space-4) var(--prime-space-8);
-}
-
 /* narrow.tsx: a 320px column; the banner's container query moves actions under the text. */
 .narrow {
   width: min(100%, calc(var(--prime-space-20) * 4));
 }
 
-/* dismiss.tsx */
-.restore {
-  align-self: flex-start;
+/* dismissible.tsx: the swapped region takes the row's width. */
+.region {
+  width: 100%;
 }

package/dist/skill/reference/components/banner/examples/narrow.tsx

@@ -1,4 +1,4 @@
-/** Below 36rem of its own width the banner moves the actions under the text. */
+/** Below 36rem of its own width the banner moves the actions under the text — `Banner.Actions`. */
 import { Banner, Button, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/dist/skill/reference/components/banner/examples/page-strip.tsx

@@ -1,32 +1,26 @@
 /** An edge-to-edge strip above a page and a rounded block inside a card — `placement`. */
-import { Banner, Button, Card, Icon, Typography } from "prime-ui-kit";
+import { Banner, Button, Card, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
 export default function BannerPageStripExample() {
   return (
     <div className={styles.sections}>
-      <Card.Root>
-        <Banner.Root
-          tone="warning"
-          placement="page"
-          role="region"
-          aria-label="Пробный период"
-          onDismiss={() => undefined}
-        >
-          <Banner.Content>
-            <Banner.Icon>
-              <Icon name="status.warning" />
-            </Banner.Icon>
-            <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
-          </Banner.Content>
-        </Banner.Root>
-        <div className={styles.pageBody}>
-          <Typography as="h3" variant="heading-s">
-            Отчёты
-          </Typography>
-        </div>
-      </Card.Root>
+      {/* In an app the strip stands first in the page, edge to edge above its content. */}
+      <Banner.Root
+        tone="warning"
+        placement="page"
+        role="region"
+        aria-label="Пробный период"
+        onDismiss={() => undefined}
+      >
+        <Banner.Content>
+          <Banner.Icon>
+            <Icon name="status.warning" />
+          </Banner.Icon>
+          <Banner.Title>Пробный период закончится 12 октября</Banner.Title>
+        </Banner.Content>
+      </Banner.Root>
       <Card.Root variant="panel">
         <Card.Header>
           <Card.Title>Оплата</Card.Title>

package/dist/skill/reference/components/breadcrumb/COMPONENT.md

@@ -85,13 +85,14 @@ Use links for every ancestor and `current` on the last item; `s` above a `headin
 |---|---|---|
 | current | `current` | `aria-current="page"` on the text span, or on the link when the item has `href` |
 | hover / focus-visible on links | pointer / keyboard | text → primary; focus ring from LinkButton |
-| truncation | width | each level truncates with an ellipsis, max width `2 × --prime-space-24` (192; `--prime-space-24 + --prime-space-6`, 120, in a container below 30rem); the last item shrinks last |
+| truncation | width | each level truncates with an ellipsis, max width `2 × --prime-space-24` (192; `--prime-space-24 + --prime-space-6`, 120, when its container is below 30rem — its own for 3+ levels, the nearest one above for 1–2); the last item shrinks last |
 | auto-collapse | 3+ levels and a container `< 30rem` | `data-collapsible="true"`; middle levels are `display: none` and replaced by «… ›», whose hidden text (`labels.ellipsis`) names them |
 
 Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 
 ## Layout & spacing
-- The root is a size container (`container-type: inline-size`, `inline-size: 100%`): inside a flex row give it `flex: 1 1 auto; min-width: 0`.
+- A path of 1–2 levels takes its content width (at most the row), so in a flex row — the `AppHeader` start, before `AppHeader.Separator` and the title — what follows stands right after it. A path of 3+ levels is a size container (`container-type: inline-size`, `inline-size: 100%`) that folds its middle levels by its own width: inside a flex row give it `flex: 1 1 auto; min-width: 0`.
+- In an `AppHeader` the path up holds the list a record belongs to (1–2 levels); the record itself is the `AppHeader.Title` after the separator, not the breadcrumb's `current` item.
 - Above a page title: `gap: var(--prime-space-2)` between the trail and the title row.
 - The list never wraps. Chevrons sit inside each level after the first, in the placeholder text color, at the tier icon size.
 
@@ -123,8 +124,8 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 | [overview.tsx](examples/overview.tsx) | The path to this page: links to the levels above and the current page last — `href`, `current`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier; text and chevrons follow the control tier — `size`. |
 | [with-icon.tsx](examples/with-icon.tsx) | The root level as a home icon; a link without text is named for screen readers — `aria-label`. |
-| [overflow.tsx](examples/overflow.tsx) | A long path: levels truncate, and in a 320px container the middle ones collapse into «…», which screen readers announce as hidden levels. |
-| [ellipsis.tsx](examples/ellipsis.tsx) | Levels skipped on purpose shown as «…» with hidden text for screen readers — `Breadcrumb.Ellipsis`. |
+| [overflow.tsx](examples/overflow.tsx) | A long path: levels truncate, and in a 320px container the middle ones collapse into «…», which screen readers announce as hidden levels — `Breadcrumb.Item`, `current`. |
+| [ellipsis.tsx](examples/ellipsis.tsx) | Levels skipped on purpose shown as «…» whose hidden text names them for screen readers — `Breadcrumb.Ellipsis`, `labels`. |
 
 ## Mistakes
 - Separators by hand between items → the root draws the chevrons.

package/dist/skill/reference/components/breadcrumb/examples/ellipsis.tsx

@@ -1,9 +1,9 @@
-/** Levels skipped on purpose shown as «…» with hidden text for screen readers — `Breadcrumb.Ellipsis`. */
+/** Levels skipped on purpose shown as «…» whose hidden text names them for screen readers — `Breadcrumb.Ellipsis`, `labels`. */
 import { Breadcrumb } from "prime-ui-kit";
 
 export default function BreadcrumbEllipsisExample() {
   return (
-    <Breadcrumb.Root>
+    <Breadcrumb.Root labels={{ ellipsis: "Скрытые разделы: Мебель, Офисные кресла" }}>
       <Breadcrumb.Item href="#catalog">Каталог</Breadcrumb.Item>
       <Breadcrumb.Ellipsis />
       <Breadcrumb.Item current>Кресло «Оптима»</Breadcrumb.Item>

package/dist/skill/reference/components/breadcrumb/examples/overflow.tsx

@@ -1,4 +1,4 @@
-/** A long path: levels truncate, and in a 320px container the middle ones collapse into «…», which screen readers announce as hidden levels. */
+/** A long path: levels truncate, and in a 320px container the middle ones collapse into «…», which screen readers announce as hidden levels — `Breadcrumb.Item`, `current`. */
 import { Breadcrumb } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/dist/skill/reference/components/button-group/COMPONENT.md

@@ -152,12 +152,12 @@ Group attributes: `data-size`, `data-orientation="vertical"` (only when vertical
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Related actions joined into one bar with a group name — `aria-label`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier, 28 to 48 px high, set once on the root — `size`. |
-| [states.tsx](examples/states.tsx) | A plain segment, a toggled one and a disabled one — `pressed`, `disabled`. |
+| [states.tsx](examples/states.tsx) | A plain segment, a toggled one, a disabled one and a group in error — `pressed`, `disabled`, `invalid`. |
 | [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and square icon-only segments — `ButtonGroup.Icon`, `aria-label`. |
 | [orientation.tsx](examples/orientation.tsx) | A row of segments and a column of related options — `orientation`. |
 | [full-width.tsx](examples/full-width.tsx) | The group fills its column and the segments share the width equally — `fullWidth`. |
 | [controlled.tsx](examples/controlled.tsx) | One of several: the active segment lives in parent state and gets `pressed`. |
-| [in-form.tsx](examples/in-form.tsx) | A task form: the priority toggles are a labelled field checked on submit, and native submit and reset segments sit in one group — `label`, `required`, `error`, `type`. |
+| [in-form.tsx](examples/in-form.tsx) | A task form: the priority toggles are a labelled field checked on submit, an optional reminder, and native submit and reset segments in one group — `label`, `required`, `hint`, `error`, `optional`, `type`. |
 
 ## Mistakes
 - `size` on each `ButtonGroup.Item` → set `size` once on `Root`.