prime-ui-kit 0.13.1 → 0.15.0

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.
 
@@ -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/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/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/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

@@ -163,7 +163,7 @@ Card.Root asChild                <a> or <button> (the only child) holding the pa
 Without `asChild` a card is static: no hover, focus or press of its own. With it: `data-interactive` on the element.
 
 ## Layout & spacing
-- Grid of cards: `repeat(auto-fit, minmax(min(100%, 14rem), 1fr))`, gap `--prime-space-4`.
+- Cards on a page: one `PageContent.Grid` with a `PageContent.Cell span` per card (16 on both axes, the cards of a row share one height); a grid inside one block is the block's own `repeat(auto-fit, minmax(min(100%, 14rem), 1fr))`, gap `--prime-space-4`.
 - Radius `--prime-card-radius`, no border. In `panel` and `list` the `Header` is a padded zone with a faint inset hairline below; in `stat-trend` it can pair a leading Badge or icon with a compact `Card.Value`.
 - Padding `--prime-card-padding-m` (20); `Body` gap `--prime-card-gap` (16); fields inside `Body` 20 apart, one ladder step off the card.
 - Depth comes from nesting (foundation §4): on the page — the AppShell panel is the page — a card is layer 1 (white in light) with the raised whisper; inside another card it is the next layer, a flat tile. The ladder stops at layer 4.
@@ -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, a summary line and an edge-to-edge chart — `Card.Header`, `Card.Description`, `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. |
+| [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.
@@ -209,10 +210,11 @@ No `labels`.
 - Custom padding on a `panel` root → padding belongs to `Header` / `Body` / `Footer`.
 - A wrapper `<div>` around the label and the value of `mini` → put `Icon`, `Label`, `Value` straight into the root (or into a `split` cell); the template lays them out.
 - A chart SVG with only a `viewBox` → give it a CSS height.
+- A hand-drawn trend SVG in a chart widget → `Sparkline` in the `Body` (or `Media`); a chart with a legend and states → `ChartFrame`.
 - A clickable `<div>` card with `onClick` → `asChild` with a real `<a href>` (Cmd-click, a new tab) or a `<button>`.
 - Buttons or links inside an `asChild` card → nested interactive elements; move them out of the card.
 - The reference figures written into `Card.Delta` or `Card.Label` → `Card.Meta`.
 
 ## Related
 - **Built from:** —
-- **See also:** [PageContent](../page-content/COMPONENT.md), [DescriptionList](../description-list/COMPONENT.md) (record details inside a `Card.Body`), [Fieldset](../fieldset/COMPONENT.md) (groups of fields inside a settings card), [DataTable](../data-table/COMPONENT.md), [Badge](../badge/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)
+- **See also:** [PageContent](../page-content/COMPONENT.md), [DescriptionList](../description-list/COMPONENT.md) (record details inside a `Card.Body`), [Fieldset](../fieldset/COMPONENT.md) (groups of fields inside a settings card), [DataTable](../data-table/COMPONENT.md), [Badge](../badge/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Sparkline](../sparkline/COMPONENT.md) (a trend with its total inside a `panel`), [ChartFrame](../chart-frame/COMPONENT.md) (a full chart with legend and states)

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

@@ -28,34 +28,6 @@
   width: min(100%, calc(var(--prime-space-24) * 6));
 }
 
-/* Sparkline: fixed height from tokens, stretches to the card width. */
-.spark {
-  display: block;
-  width: 100%;
-  height: var(--prime-space-10);
-  color: var(--prime-color-accent-default);
-  overflow: visible;
-}
-
-.chart {
-  display: block;
-  width: 100%;
-  /* Fixed height: a viewBox-only SVG would otherwise scale to a square of the card width. */
-  height: calc(var(--prime-space-24) * 2);
-  color: var(--prime-color-accent-default);
-}
-
-.chartFill {
-  fill: var(--prime-color-accent-soft);
-}
-
-.chartLine {
-  fill: none;
-  stroke: currentColor;
-  stroke-width: calc(2 * var(--prime-border-width));
-  vector-effect: non-scaling-stroke;
-}
-
 .cover {
   background: linear-gradient(
     135deg,

package/src/components/card/examples/kpi-media.tsx

@@ -1,9 +1,19 @@
 /** A KPI with a sparkline or a fill level in the bottom slot of `mini` — `Card.Media`. */
-import { Card, Icon, ProgressBar } from "prime-ui-kit";
+import { Card, Icon, ProgressBar, Sparkline, type SparklinePoint } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-const SPARKLINE = "M0 32 L15 28 L30 30 L45 18 L60 22 L75 12 L90 16 L105 8 L120 4";
+const REQUESTS: SparklinePoint[] = [
+  { label: "12:00", value: 9_120 },
+  { label: "12:10", value: 9_640 },
+  { label: "12:20", value: 9_380 },
+  { label: "12:30", value: 10_910 },
+  { label: "12:40", value: 10_470 },
+  { label: "12:50", value: 11_760 },
+  { label: "13:00", value: 11_290 },
+  { label: "13:10", value: 12_310 },
+  { label: "13:20", value: 12_840 },
+];
 
 export default function CardKpiMediaExample() {
   return (
@@ -15,15 +25,7 @@ export default function CardKpiMediaExample() {
         <Card.Label>Запросы в минуту</Card.Label>
         <Card.Value>12 840</Card.Value>
         <Card.Media>
-          {/* The SVG stretches to the card width; CSS sets its height, not the viewBox. */}
-          <svg
-            className={styles.spark}
-            viewBox="0 0 120 40"
-            preserveAspectRatio="none"
-            aria-hidden="true"
-          >
-            <path d={SPARKLINE} className={styles.chartLine} />
-          </svg>
+          <Sparkline layout="compact" data={REQUESTS} label="Запросы в минуту за час" />
         </Card.Media>
       </Card.Root>
 

package/src/components/card/examples/narrow.tsx

@@ -1,4 +1,4 @@
-/** The card is a size container: the split template stacks its cells below 22rem and the trend value shrinks below 20rem. */
+/** The card is a size container: the split template stacks its cells below 22rem and the trend value shrinks below 20rem — `variant`. */
 import { Card, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/src/components/card/examples/panel-chart.tsx

@@ -1,43 +1,66 @@
-/** A chart widget: a header with a short description and a period switch, a summary line and an edge-to-edge chart — `Card.Header`, `Card.Description`, `Card.Media`. */
-import { Card, SegmentedControl, Typography } from "prime-ui-kit";
+/** 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`. */
+import { Card, SegmentedControl, Sparkline, type SparklinePoint } from "prime-ui-kit";
+import * as React from "react";
 
 import styles from "./examples.module.css";
 
-const POINTS = [42, 48, 45, 60, 58, 72, 66, 80, 76, 88, 84, 96];
+type Period = "week" | "month";
 
-/** An area chart path in a 100 × 100 box; the SVG stretches over the whole `Card.Media`. */
-const LINE = POINTS.map(
-  (value, i) => `${i === 0 ? "M" : "L"}${(i * 100) / (POINTS.length - 1)} ${100 - value}`,
-).join(" ");
+const REVENUE: Record<Period, SparklinePoint[]> = {
+  week: [
+    { label: "6 окт", value: 412_000 },
+    { label: "7 окт", value: 468_000 },
+    { label: "8 окт", value: 445_000 },
+    { label: "9 окт", value: 603_000 },
+    { label: "10 окт", value: 581_000 },
+    { label: "11 окт", value: 214_000 },
+    { label: "12 окт", value: 187_000 },
+  ],
+  month: [
+    { label: "сен, 1 нед.", value: 2_480_000 },
+    { label: "сен, 2 нед.", value: 2_760_000 },
+    { label: "сен, 3 нед.", value: 2_610_000 },
+    { label: "сен, 4 нед.", value: 3_140_000 },
+    { label: "окт, 1 нед.", value: 2_910_000 },
+  ],
+};
+
+/** The same total for the period before: the badge at rest compares the headline with it. */
+const PREVIOUS: Record<Period, number> = {
+  week: 2_640_000,
+  month: 12_900_000,
+};
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
 
 export default function CardPanelChartExample() {
+  const [period, setPeriod] = React.useState<Period>("month");
+
   return (
     <div className={styles.panel}>
       <Card.Root variant="panel">
         <Card.Header>
           <Card.Title>Выручка</Card.Title>
           <Card.Description>Оплаченные счета, без возвратов</Card.Description>
-          <SegmentedControl.Root size="xs" defaultValue="month" aria-label="Период">
+          <SegmentedControl.Root
+            size="xs"
+            value={period}
+            onValueChange={(value) => setPeriod(value as Period)}
+            aria-label="Период"
+          >
             <SegmentedControl.Item value="week">Неделя</SegmentedControl.Item>
             <SegmentedControl.Item value="month">Месяц</SegmentedControl.Item>
           </SegmentedControl.Root>
         </Card.Header>
         <Card.Body>
-          <Typography variant="body-s" tone="secondary">
-            С начала квартала: 12,6 млн ₽, план выполнен на 84%.
-          </Typography>
+          <Sparkline
+            data={REVENUE[period]}
+            label="Оплачено за период"
+            summary="sum"
+            compareTo={PREVIOUS[period]}
+            formatValue={formatRubles}
+          />
         </Card.Body>
-        <Card.Media>
-          <svg
-            className={styles.chart}
-            viewBox="0 0 100 100"
-            preserveAspectRatio="none"
-            aria-hidden="true"
-          >
-            <path className={styles.chartFill} d={`${LINE} L100 100 L0 100 Z`} />
-            <path className={styles.chartLine} d={LINE} />
-          </svg>
-        </Card.Media>
       </Card.Root>
     </div>
   );

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