prime-ui-kit 0.14.0 → 0.15.0

package/dist/skill/reference/layout/sidebar/examples/router.tsx

@@ -1,6 +1,6 @@
-/** A router link as the item: the router sets `aria-current` and the item shows as current; render it inside a router — `asChild`. */
+/** Router links as the brand and the items: the router sets `aria-current` and the item shows as current; render it inside a router — `asChild`. */
 import { Icon, Sidebar } from "prime-ui-kit";
-import { NavLink } from "react-router-dom";
+import { Link, NavLink } from "react-router-dom";
 
 import styles from "./examples.module.css";
 
@@ -14,6 +14,18 @@ export default function SidebarRouterExample() {
   return (
     <div className={styles.stage}>
       <Sidebar.Root offCanvas="never">
+        <Sidebar.Header>
+          <Sidebar.Brand asChild description="Документация">
+            <Link to="/">
+              <Sidebar.BrandLogo>
+                <span className={styles.logo}>
+                  <Icon name="object.book" />
+                </span>
+              </Sidebar.BrandLogo>
+              Prime UI
+            </Link>
+          </Sidebar.Brand>
+        </Sidebar.Header>
         <Sidebar.Content>
           {LINKS.map((link) => (
             <Sidebar.Item key={link.to} asChild>

package/dist/skill/reference/layout/sidebar/examples/structure.tsx

@@ -1,4 +1,4 @@
-/** Labelled groups and the optional item parts: a plain count, a coloured badge, a key hint, a trailing icon, a row action and a disabled section — `Sidebar.Group`, `Sidebar.ItemCount`, `color`, `Sidebar.ItemShortcut`, `Sidebar.ItemAction`, `disabled`. */
+/** Labelled groups and the optional item parts: a plain count, coloured and solid badges, a key hint, a trailing icon, row actions with the default and an own glyph and a disabled section — `Sidebar.Group`, `Sidebar.ItemCount`, `color`, `variant`, `Sidebar.ItemShortcut`, `Sidebar.ItemAction`, `disabled`. */
 import { Icon, Kbd, Sidebar } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -29,7 +29,9 @@ export default function SidebarStructureExample() {
                 <Icon name="object.bell" />
               </Sidebar.ItemIcon>
               Уведомления
-              <Sidebar.ItemCount color="red">7</Sidebar.ItemCount>
+              <Sidebar.ItemCount color="red" variant="solid">
+                7
+              </Sidebar.ItemCount>
             </Sidebar.Item>
           </Sidebar.Group>
           <Sidebar.Group label="Работа">
@@ -54,6 +56,9 @@ export default function SidebarStructureExample() {
               </Sidebar.ItemIcon>
               Интеграции
               <Sidebar.ItemCount color="orange">!</Sidebar.ItemCount>
+              <Sidebar.ItemAction label="Синхронизировать интеграции" onClick={() => {}}>
+                <Icon name="action.refresh" />
+              </Sidebar.ItemAction>
             </Sidebar.Item>
           </Sidebar.Group>
           <Sidebar.Group label="Администрирование">

package/dist/skill/responsive.md

@@ -47,10 +47,10 @@ Use these as they are; never wrap them in your own breakpoints.
 
 | Need | Built in |
 |---|---|
-| app frame | AppShell gutters 16 → 24 → 32; `AppHeader` un-sticks on screens lower than 480px, respects safe areas and, below 36rem of its width, drops the description and folds the search into an icon |
+| app frame | AppShell gutters 16 → 24 → 32; `AppHeader` un-sticks on screens lower than 480px, respects safe areas and, below 36rem of its width, drops the title icon, the title and its line of data truncate |
 | app navigation | Sidebar: on-canvas from 768px, an off-canvas panel below (`offCanvas="auto"`) opened by `AppHeader.MenuButton`, which shows itself below 768px; `BottomNav` in `AppShell.Footer` for 2–6 app sections on phones — flat or a floating glass capsule (`floating`) with an optional round `BottomNav.Action`, icons with or without labels (`iconOnly`); the shell hides it by itself while the Sidebar rail is on screen (from 768px with `offCanvas="auto"`) |
 | page panel | `PageToolbar` — search and filter first, one row when wide, stacked rows when narrow (below) |
-| page header | `PageContent.Header`: actions wrap under the title |
+| page header | `AppHeader`: the page's tools wrap under the title (`AppHeader.Tools`), the primary action takes its own row when the search would be squeezed; a document page's `PageContent.Header`: actions wrap under the title |
 | switchers | SegmentedControl and Tabs never wrap: they scroll inside themselves (hidden scrollbar, faded edges, a vertical wheel scrolls them sideways), the active item is scrolled into view, stretched items tend to equal width, the indicator moves only after a person's choice; Tabs collapse icons and descriptions first |
 | tables | DataTable scrolls inside itself, edge shadows show hidden columns, `stickyFirstColumn`, `DataTable.ColumnsMenu` for a column chooser, the toolbar stacks below a 30rem table, sticky head off on short screens |
 | floating layers | Popover (opened from a Trigger), Dropdown, Select (and Datepicker, ColorPresets) never wider than the viewport − 16, 8 from the edges, flip when out of room; below 640 they open as a bottom sheet — scrim, grab handle, swipe down to close, page scroll locked; Tooltip and TagSelect stay anchored |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "packageManager": "bun@1.3.13",
   "description": "React 19 UI kit for product interfaces: 79 composable components on one design contract — forms, selects, tables, overlays, navigation, app shell. CSS Modules, --prime-* tokens, light and dark themes, TypeScript, a11y, Next.js App Router ready. Ships COMPONENT.md docs, copyable examples and an agent skill.",
   "bin": {

package/src/components/avatar/examples/states.tsx

@@ -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/src/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/src/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/src/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/src/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,10 +17,6 @@
   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));

package/src/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/src/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.
 
@@ -124,7 +125,7 @@ Root attributes: `data-size`, `data-collapsible` (`"true"` / `"false"`).
 | [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 — `Breadcrumb.Item`, `current`. |
-| [ellipsis.tsx](examples/ellipsis.tsx) | Levels skipped on purpose shown as «…» with hidden text for screen readers — `Breadcrumb.Ellipsis`. |
+| [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/src/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/src/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`.

package/src/components/button-group/examples/in-form.tsx

@@ -1,4 +1,4 @@
-/** 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`. */
+/** 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`. */
 import { ButtonGroup, Input } from "prime-ui-kit";
 import * as React from "react";
 
@@ -10,8 +10,11 @@ const PRIORITIES = [
   { value: "high", label: "Высокий" },
 ];
 
+const REMINDERS = ["За час", "За день"];
+
 export default function ButtonGroupInFormExample() {
   const [priority, setPriority] = React.useState("");
+  const [reminder, setReminder] = React.useState("");
   const [error, setError] = React.useState<string>();
 
   return (
@@ -24,6 +27,7 @@ export default function ButtonGroupInFormExample() {
       }}
       onReset={() => {
         setPriority("");
+        setReminder("");
         setError(undefined);
       }}
     >
@@ -32,7 +36,12 @@ export default function ButtonGroupInFormExample() {
           <Input.Field name="title" defaultValue="Подготовить акт сверки для «Северного ветра»" />
         </Input.Wrapper>
       </Input.Root>
-      <ButtonGroup.Root label="Приоритет" required error={error}>
+      <ButtonGroup.Root
+        label="Приоритет"
+        required
+        hint="Высокий поднимает задачу в начало списка"
+        error={error}
+      >
         {PRIORITIES.map((option) => (
           <ButtonGroup.Item
             key={option.value}
@@ -46,6 +55,17 @@ export default function ButtonGroupInFormExample() {
           </ButtonGroup.Item>
         ))}
       </ButtonGroup.Root>
+      <ButtonGroup.Root label="Напомнить" optional>
+        {REMINDERS.map((option) => (
+          <ButtonGroup.Item
+            key={option}
+            pressed={reminder === option}
+            onClick={() => setReminder(reminder === option ? "" : option)}
+          >
+            {option}
+          </ButtonGroup.Item>
+        ))}
+      </ButtonGroup.Root>
       <ButtonGroup.Root aria-label="Создать задачу или очистить форму">
         <ButtonGroup.Item type="submit">Создать</ButtonGroup.Item>
         <ButtonGroup.Item type="reset">Очистить</ButtonGroup.Item>

package/src/components/button-group/examples/states.tsx

@@ -1,4 +1,4 @@
-/** A plain segment, a toggled one and a disabled one — `pressed`, `disabled`. */
+/** A plain segment, a toggled one, a disabled one and a group in error — `pressed`, `disabled`, `invalid`. */
 import { ButtonGroup, Typography } from "prime-ui-kit";
 
 export default function ButtonGroupStatesExample() {
@@ -28,6 +28,15 @@ export default function ButtonGroupStatesExample() {
           disabled
         </Typography>
       </div>
+      <div>
+        <ButtonGroup.Root aria-label="Статус задачи" invalid>
+          <ButtonGroup.Item>Открыта</ButtonGroup.Item>
+          <ButtonGroup.Item>В работе</ButtonGroup.Item>
+        </ButtonGroup.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          invalid
+        </Typography>
+      </div>
     </div>
   );
 }

package/src/components/card/COMPONENT.md

@@ -194,13 +194,14 @@ No `labels`.
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A company settings panel: a header, fields on the surface fill and buttons in the footer — `Card.Header`, `Card.Body`, `Card.Footer`. |
-| [variants.tsx](examples/variants.tsx) | KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change and a reference line — `variant`, `Card.Delta`, `Card.Meta`. |
+| [variants.tsx](examples/variants.tsx) | KPI templates: an icon tile with a value, a badge with a value in the header row, and a large value with its change in every tone and a reference line — `variant`, `Card.Delta`, `tone`, `Card.Meta`. |
 | [kpi-media.tsx](examples/kpi-media.tsx) | A KPI with a sparkline or a fill level in the bottom slot of `mini` — `Card.Media`. |
 | [panel-chart.tsx](examples/panel-chart.tsx) | A chart widget: a header with a short description and a period switch, and a Sparkline with the period total over its chart — `Card.Header`, `Card.Description`, `Card.Body`. |
 | [interactive.tsx](examples/interactive.tsx) | Whole cards as links to their reports: one tab stop each, a lift on hover, a press and the focus ring — `asChild`. |
 | [content-templates.tsx](examples/content-templates.tsx) | Content templates: a call to action, an events list and a campaign tile with a cover — `Card.Footer`, `Card.List`, `Card.Media`. |
 | [flat.tsx](examples/flat.tsx) | A flat tile without the raised shadow next to the default one, for dense grids — `flat`. |
 | [narrow.tsx](examples/narrow.tsx) | The card is a size container: the split template stacks its cells below 22rem and the trend value shrinks below 20rem — `variant`. |
+| [screen.tsx](examples/screen.tsx) | A dashboard: the title, a line of data, the period switch and the report in the app header; one grid of KPI tiles that cross-fade to the new period, a revenue trend, invoiced against paid beside two panels, and the latest payments with a link to the list — `AppHeader.Tools`, `PageContent.Grid`. |
 
 ## Mistakes
 - A `<div>` with a border styled as a card → use `Card.Root`; depth comes from fill, not lines.

package/src/components/card/examples/screen.module.css

@@ -0,0 +1,14 @@
+/* Dashboard: the board of tiles is PageContent.Grid; here only the inside of the tiles. */
+
+/* Bars inside a panel: 20 apart, like fields. */
+.bars {
+  display: grid;
+  gap: var(--prime-space-5);
+}
+
+.client {
+  display: inline-flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-2);
+}