prime-ui-kit 0.13.1 → 0.14.0

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.
@@ -196,11 +196,11 @@ No `labels`.
 | [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`. |
 | [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`. |
 
 ## Mistakes
 - A `<div>` with a border styled as a card → use `Card.Root`; depth comes from fill, not lines.
@@ -209,10 +209,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/chart-frame/COMPONENT.md

@@ -33,7 +33,7 @@ ChartFrame.Root              <figure>; surface of the depth ladder; state, serie
 ├─ ChartFrame.Plot           <div>; fixed height, measured; Crossfade of plot / Skeleton / empty / error
 ├─ ChartFrame.Legend         <ul>; a toggle button per series: swatch · name · value
 ├─ ChartFrame.Table          <table>; visually hidden data, ready state only
-└─ ChartFrame.Tooltip        <div>; rendered by the chart library's tooltip hook, inside the Root
+└─ ChartFrame.Tooltip        <div>; with `point` portaled beside that point of the plot, else in place for a library's tooltip hook
 ```
 
 ## API
@@ -104,7 +104,7 @@ ChartFrame.Root              <figure>; surface of the depth ladder; state, serie
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `height` | `number` | `240, 160 under 30rem` | Height of the plot area in px. |
+| `height` | `number \| "fill"` | `240, 160 under 30rem` | Height of the plot area in px. `fill` takes the free height of a stretched panel (a `PageContent.Cell` with `rows`), the default height at least. |
 | `renderPlot` | `(area: ChartFramePlotArea) => ReactNode` | — | Renders the chart at the measured `{ width, height }` with every series `{ id, label, color, hidden }` — for libraries that need explicit sizes (Chart.js, visx). |
 | `children` | `ReactNode` | — | A chart that sizes itself to its container (an SVG with a `viewBox`, `ResponsiveContainer`); it fills the area. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
@@ -118,12 +118,13 @@ ChartFrame.Root              <figure>; surface of the depth ladder; state, serie
 | `…rest` | `HTMLAttributes<HTMLUListElement>` | — | `className` and the other ul attributes. |
 
 ### ChartFrame.Tooltip
-`ref` → `HTMLDivElement`. The kit's tooltip body for a chart library's custom tooltip (Recharts `content`, visx `TooltipWithBounds`). The library positions it; render it inside `ChartFrame.Root`.
+`ref` → `HTMLDivElement`. The kit's chart tooltip: with `point` it floats beside that point of the plot; without it it is the body for a library's tooltip hook (Recharts `content`). Inside `ChartFrame.Root`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `label` | `string` | — | The point the rows belong to («Неделя 41»). |
 | `items` | `ChartFrameTooltipItem[]` | — (required) | `{ id, value }` per series at that point; name and color come from the root's series, rows of hidden series are left out, values go through `formatValue`. |
+| `point` | `{ x: number; y: number } \| null` | — | A point in `renderPlot` coordinates (the pointer, or the point the arrows reached): the tooltip floats right of it, left only without room; `null` hides it. Floating, it is `aria-hidden`. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other div attributes. |
 
 ### ChartFrame.Table
@@ -177,7 +178,7 @@ ChartFrame.Root              <figure>; surface of the depth ladder; state, serie
 - The header puts the title and the description in the first column and the actions at the end; under 24rem of panel width the actions drop under the description.
 - The plot is 240 px high (160 px under 30rem of panel width) unless `height` is set; it never changes height between states.
 - Legend entries wrap onto more lines; each has a 44 px touch hit area on coarse pointers.
-- `ChartFrame.Tooltip` is a floating panel with the point's label over rows of swatch · series name · value; the chart library positions it (Recharts `content`, visx `TooltipWithBounds`, a hand-drawn overlay).
+- `ChartFrame.Tooltip` is the floating layer of the ladder with the point's label over rows of swatch · series name · value. With `point` the kit places it like every anchored layer (`usePosition`): right of the point at its height, on the left only where the right has no room in the viewport, inside the viewport, following the plot on scroll. Without `point` the chart library positions it (Recharts `content`).
 - SVG `<text>` in the plot takes the caption type in `--prime-color-text-muted`; a class of your own still wins.
 - Works from 320 px; the container queries are on the panel's own width, so it adapts in a grid cell as on a phone.
 
@@ -195,6 +196,7 @@ ChartFrame.Root              <figure>; surface of the depth ladder; state, serie
 - The root is a `<figure>` named by `ChartFrame.Title` and described by `ChartFrame.Description`; `aria-busy` while loading.
 - A legend entry is a button with `aria-pressed` — pressed while its series is shown; the legend list is named by `labels.legend`. A hidden series differs by the swatch's shape (a ring) and a quiet name, never by color alone.
 - `ChartFrame.Table` is a visually hidden table with the chart's data, named by the title: a row header per point, a column per shown series, values through `formatValue`.
+- A `ChartFrame.Tooltip` with `point` is `aria-hidden` and passive (no focus, no presses; `Escape` hides it until the point moves): it repeats what the plot speaks — give a focusable plot an `aria-valuetext`, like the slider in the tooltip example.
 - The empty state is `role="status"`, the error `role="alert"` with the retry button.
 - The drawing is the library's: hide a decorative SVG (`aria-hidden`) when `ChartFrame.Table` carries the data; marks you make focusable need their own `aria-label`.
 
@@ -213,7 +215,7 @@ ChartFrame.Root              <figure>; surface of the depth ladder; state, serie
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Revenue by month as a hand-drawn SVG line chart in a dashboard panel: the headline with its change, a period switch, a legend that turns series off and a table for screen readers — `series`, `formatValue`, `renderPlot`. |
-| [tooltip.tsx](examples/tooltip.tsx) | Invoices by week as grouped bars: pointing at a week or stepping with the arrows shows the kit tooltip body with a row per series — `ChartFrame.Tooltip`, `items`. |
+| [tooltip.tsx](examples/tooltip.tsx) | Invoices by week as grouped bars: the kit tooltip follows the pointer with a row per series, the arrows step through the weeks — `ChartFrame.Tooltip`, `items`, `point`. |
 | [states.tsx](examples/states.tsx) | Loading, empty, error and data swap in the plot's place without moving the panel; the error retries — `state`, `onRetry`. |
 | [controlled.tsx](examples/controlled.tsx) | Lead sources with totals in the legend; the hidden series live in the page state and one button shows them all again — `hiddenSeries`, `onHiddenSeriesChange`. |
 | [narrow.tsx](examples/narrow.tsx) | A 320px column: the actions drop under the title, the plot gets lower and a self-sizing SVG stretches to it — `children`, `height`. |
@@ -249,7 +251,7 @@ ChartFrame.Root              <figure>; surface of the depth ladder; state, serie
   <ChartFrame.Table rows={tableRows} />
 </ChartFrame.Root>
 ```
-ECharts and Chart.js take the same `width`, `height` and `series[i].color`; their HTML tooltips are strings, so use their own tooltip there or a React overlay with `ChartFrame.Tooltip`.
+ECharts and Chart.js take the same `width`, `height` and `series[i].color`; their HTML tooltips are strings, so use their own tooltip there or `ChartFrame.Tooltip` with `point` from their hover event.
 
 ## Mistakes
 - Colors picked per chart (`#3b82f6`) → `series[i].color` from `renderPlot`, or `chartColors`; status tones (`success`, `danger`) never paint categories.
@@ -259,7 +261,8 @@ ECharts and Chart.js take the same `width`, `height` and `series[i].color`; thei
 - A legend for a single series → the title already names it; leave `ChartFrame.Legend` out.
 - Two y-axes of different measures in one frame → two ChartFrames side by side.
 - The data only in the drawing → add `ChartFrame.Table`; screen readers cannot read a plot.
+- A hand-drawn chart with its tooltip placed by hand (a `foreignObject`, clamped coordinates) → `ChartFrame.Tooltip` with `point`: it flips only when out of room and never jumps at the middle.
 
 ## Related
-- **Built from:** [Crossfade](../crossfade/COMPONENT.md) (state swap), [Skeleton](../skeleton/COMPONENT.md) (loading), [EmptyPage](../empty-page/COMPONENT.md) (empty, error, retry), `Icon`, `chartColors`
+- **Built from:** [Crossfade](../crossfade/COMPONENT.md) (state swap), [Skeleton](../skeleton/COMPONENT.md) (loading), [EmptyPage](../empty-page/COMPONENT.md) (empty, error, retry), `Icon`, `chartColors`, `ChartTooltip` (the chart tooltip shared with Sparkline)
 - **See also:** [Sparkline](../sparkline/COMPONENT.md), [Card](../card/COMPONENT.md), [ProgressBar](../progress-bar/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)

package/src/components/chart-frame/examples/tooltip.tsx

@@ -1,4 +1,4 @@
-/** Invoices by week as grouped bars: pointing at a week or stepping with the arrows shows the kit tooltip body with a row per series — `ChartFrame.Tooltip`, `items`. */
+/** Invoices by week as grouped bars: the kit tooltip follows the pointer with a row per series, the arrows step through the weeks — `ChartFrame.Tooltip`, `items`, `point`. */
 import { ChartFrame, type ChartFrameSeries, chartColors } from "prime-ui-kit";
 import * as React from "react";
 
@@ -18,12 +18,13 @@ const WEEKS = [
 
 const MARGIN = { top: 8, right: 0, bottom: 24, left: 32 };
 const TICKS = [0, 20, 40, 60];
-const TOOLTIP = { width: 176, height: 88 };
 
 const formatCount = (value: number) => `${value} шт.`;
 
 export default function ChartFrameTooltipExample() {
   const [active, setActive] = React.useState<number | null>(null);
+  // The pointer in plot coordinates; `null` while the arrow keys step through the weeks.
+  const [pointer, setPointer] = React.useState<{ x: number; y: number } | null>(null);
 
   return (
     <ChartFrame.Root series={SERIES} formatValue={formatCount}>
@@ -39,13 +40,11 @@ export default function ChartFrameTooltipExample() {
           const bar = Math.min(24, (band - 16) / series.length);
           const y = (v: number) => MARGIN.top + innerH * (1 - v / TICKS[TICKS.length - 1]);
           const point = active === null ? null : WEEKS[active];
-          const tooltipX =
+          // Beside the pointer; from the keyboard beside the middle of the active week.
+          const tooltipAt =
             active === null
-              ? 0
-              : Math.min(
-                  Math.max(MARGIN.left + band * active + band / 2 - TOOLTIP.width / 2, 0),
-                  width - TOOLTIP.width,
-                );
+              ? null
+              : (pointer ?? { x: MARGIN.left + band * active + band / 2, y: height / 2 });
           return (
             <div
               role="slider"
@@ -58,6 +57,7 @@ export default function ChartFrameTooltipExample() {
               onPointerMove={(event) => {
                 const rect = event.currentTarget.getBoundingClientRect();
                 const index = Math.floor((event.clientX - rect.left - MARGIN.left) / band);
+                setPointer({ x: event.clientX - rect.left, y: event.clientY - rect.top });
                 setActive(index >= 0 && index < WEEKS.length ? index : null);
               }}
               onPointerLeave={() => setActive(null)}
@@ -67,6 +67,7 @@ export default function ChartFrameTooltipExample() {
                 const step = event.key === "ArrowRight" ? 1 : event.key === "ArrowLeft" ? -1 : 0;
                 if (!step) return;
                 event.preventDefault();
+                setPointer(null);
                 setActive((current) =>
                   Math.min(Math.max((current ?? 0) + step, 0), WEEKS.length - 1),
                 );
@@ -124,24 +125,19 @@ export default function ChartFrameTooltipExample() {
                     </g>
                   );
                 })}
-                {point ? (
-                  <foreignObject
-                    x={tooltipX}
-                    y={0}
-                    width={TOOLTIP.width}
-                    height={TOOLTIP.height}
-                    overflow="visible"
-                  >
-                    <ChartFrame.Tooltip
-                      label={point.label}
-                      items={[
+              </svg>
+              <ChartFrame.Tooltip
+                point={tooltipAt}
+                label={point?.label}
+                items={
+                  point
+                    ? [
                         { id: "paid", value: point.paid },
                         { id: "pending", value: point.pending },
-                      ]}
-                    />
-                  </foreignObject>
-                ) : null}
-              </svg>
+                      ]
+                    : []
+                }
+              />
             </div>
           );
         }}

package/src/components/chat/COMPONENT.md

@@ -97,7 +97,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | `search` | `string \| null` | — | The search query (controlled); `null` — the search bar is closed. Matches in the messages' text and transcripts are marked; the newest is current. |
 | `defaultSearch` | `string \| null` | `null` | The initial search (uncontrolled). |
 | `onSearchChange` | `(search: string \| null) => void` | — | The search opened (`""`), changed its query or closed (`null`). |
-| `current` | `string \| null` | `null` | A message to bring into view (a link, a notification): on change the chat brings it to the middle and the other messages blink back. The focus stays where it is. |
+| `current` | `string \| null` | `null` | A message to bring into view (a link, a notification): on change the chat brings it to the middle and the message itself blinks. The focus stays where it is. |
 | `typing` | `boolean` | `false` | The other side is typing: `Chat.Description` cross-fades into «печатает…» and the list ends with the typing bubble (`Message.Typing`), which gives way at once to the reply that ends it. |
 | `labels` | `Partial<ChatLabels>` | — | System strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "defaultValue">` | — | `className` and the other attributes of the frame. |
@@ -248,7 +248,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | away from the end | the reader scrolled up | a round soft «к последним» button at the bottom-end, rising in (`fast`); a `Badge` counts incoming messages that came meanwhile; a press glides to the end — from far away it lands one view before the end first — and stops when the reader scrolls; at the end it leaves and the count resets |
 | first load | `Chat.Messages loading` | the messages' region is `aria-busy`: six `Skeleton` bubbles in the message geometry (the bubble's radius, one or two lines of body text in its padding, widths within its cap), on alternating sides at the end of the list, a group chat's incoming ones beside a circle in the avatar's gutter; `labels.loading` is announced politely. When it ends they cross-fade into the list (`Crossfade`: the new state in `base`, the placeholders out in `fast`); the list mounts then, so what it shows is its first render — nothing enters, nothing is reported new |
 | older history | `hasOlder` | a bubble-shaped `Skeleton` above the first message; reaching it calls `onLoadOlder`; the rows that arrive above keep the reader's place |
-| jumped to | `Message.Reply target`, `Chat.Pinned`, `current` | the list brings the message to the middle (a near one glides, a far one lands at once — rendering it first — and settles once its neighbours have laid out); nothing is drawn on it: every other message steps back and comes forward three times (opacity 1 → `--prime-message-dim-opacity` → 1, `base` each) — `data-pointing="a"` / `"b"` on the list, flipped on every jump so a repeated jump restarts it, and `data-pointed` on the message; a reply's target also takes the focus, a `current` change leaves it where it is. While the search is open its current match takes the place of `current`. Reduced motion: the others stand back for a moment, no blink |
+| jumped to | `Message.Reply target`, `Chat.Pinned`, `current` | the list brings the message to the middle (a near one glides, a far one lands at once — rendering it first — and settles once its neighbours have laid out); the message itself steps back and comes forward three times, the others stay still (opacity 1 → `--prime-message-dim-opacity` → 1, `base` each) — `data-pointing="a"` / `"b"` on the list, flipped on every jump so a repeated jump restarts it, and `data-pointed` on the message; a reply's target also takes the focus, a `current` change leaves it where it is. While the search is open its current match takes the place of `current`. Reduced motion: no blink, the others stand back for a moment |
 | search | `search` (the bar open) | every case-insensitive match in the messages' text and transcripts under a soft accent wash (`<mark>`); the newest match is current: brought into view while the others stay back (`data-pointing="current"`); Enter and the older / newer buttons move the full strength to the older or newer match in one step; «2 из 5» or «Нет совпадений» beside the field |
 | typing | `typing` | the description cross-fades into «печатает…» in the accent (`Crossfade`); the typing bubble enters at the end of the list like an incoming message and leaves closing its height |
 | pinned | `Chat.Pinned items` | the rail's current segment in the accent; a press jumps to the message and steps the bar to the older one (the oldest wraps to the newest), its line entering; without items the bar renders nothing |
@@ -320,7 +320,7 @@ Chat.Root                         <div> column, fills its host; owns selection,
 | [structure.tsx](examples/structure.tsx) | The list alone, written as parts: `Chat.Root` with only `Chat.Messages`, a date that stays on top while its day scrolls, an event of the chat and the unread band — `Chat.Messages`, `Chat.Separator`, `Chat.Service`, `Chat.Unread`. |
 | [group-chat.tsx](examples/group-chat.tsx) | A team chat from data: the first message of an author's run opens with the name in the author's hue, a crown for the owner and the member's tag; the avatar — a photo, or initials — closes the run; a direct chat shows neither — `type`, `items`, `renderMessage`, `Message.Author`, `tag`, `Message.AuthorIcon`, `hueOf`. |
 | [live.tsx](examples/live.tsx) | A live support chat: the client types — the header and the end of the list say so — then answers; new messages enter at the end, read receipts come from what is on screen, and scrolled up the round button counts what arrived — `typing`, `onNewMessage`, `onRead`. |
-| [search.tsx](examples/search.tsx) | Search and pinned messages: the search bar marks every match in the texts and transcripts, counts them and steps between them while the others step back; a pinned message's press jumps to it and blinks the others — `Chat.SearchButton`, `Chat.Search`, `defaultSearch`, `Chat.Pinned`. |
+| [search.tsx](examples/search.tsx) | Search and pinned messages: the search bar marks every match in the texts and transcripts, counts them and steps between them while the others step back; a pinned message's press jumps to it and blinks it — `Chat.SearchButton`, `Chat.Search`, `defaultSearch`, `Chat.Pinned`. |
 | [states.tsx](examples/states.tsx) | The first load of a conversation: bubble-shaped placeholders on both sides stand in the list's place, then cross-fade into the messages — `loading`. |
 | [controlled.tsx](examples/controlled.tsx) | Selection mode owned by the screen: the Select item of a message's menu starts it, a check stands beside every message, a press toggles one while the others step back, the bar counts and acts, Escape leaves — `selected`, `onSelectedChange`, `Chat.SelectionBar`. |
 | [narrow.tsx](examples/narrow.tsx) | At phone width the header keeps its actions and lets the title ellipsize, bubbles take up to 85% of the chat, long links wrap and an album keeps its layout — `Chat.Root`, `Chat.Header`, `Chat.Messages`, `Chat.Footer`. |

package/src/components/chat/examples/search.tsx

@@ -1,4 +1,4 @@
-/** Search and pinned messages: the search bar marks every match in the texts and transcripts, counts them and steps between them while the others step back; a pinned message's press jumps to it and blinks the others — `Chat.SearchButton`, `Chat.Search`, `defaultSearch`, `Chat.Pinned`. */
+/** Search and pinned messages: the search bar marks every match in the texts and transcripts, counts them and steps between them while the others step back; a pinned message's press jumps to it and blinks it — `Chat.SearchButton`, `Chat.Search`, `defaultSearch`, `Chat.Pinned`. */
 import { Card, Chat, Message, VoicePlayer } from "prime-ui-kit";
 
 import styles from "./examples.module.css";

package/src/components/chat-list/COMPONENT.md

@@ -170,7 +170,7 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 
 ## Layout & spacing
 - The root is a flex column that fills its host's height: put it straight into a `Card.Root` or a `PageContent.List` pane with a height; the scroller takes the rest under the search field.
-- The search field stands on 8px sides; the rows on 8px sides and 4px between them (a margin inside each `<li>`, so the virtual window measures rows with their space).
+- One inset all round, the panel's 4px: the search field and the rows stand 4px from every edge of the host, so in a card (radius 12) their 8px corners follow the card's (nested radius = outer − padding). Rows stand 4px apart (a margin inside each `<li>`, so the virtual window measures rows with their space); the last row's margin is the inset below it.
 - A row: avatar · name and preview · time over the counts. The name and the preview truncate; glyphs, the time and the counts never do.
 - From 100 dialogs only the rows around the view render; spacers hold the rest of the height. The row with the Tab stop and the row with an open menu stay rendered.
 - The root is the `chat-list` container: below 240px the preview line and the time step out, the names and counts stay. At 320px (a phone) everything shows.

package/src/components/checkbox/examples/indicator.tsx

@@ -10,8 +10,19 @@ const CITIES = [
   { value: "kzn", label: "Казань" },
 ];
 
+/** One tab stop: arrows move the focused row (wrapping), Home / End jump to the ends. */
+function nextIndex(key: string, index: number, count: number): number | null {
+  if (key === "ArrowDown") return (index + 1) % count;
+  if (key === "ArrowUp") return (index - 1 + count) % count;
+  if (key === "Home") return 0;
+  if (key === "End") return count - 1;
+  return null;
+}
+
 export default function CheckboxIndicatorExample() {
   const [selected, setSelected] = React.useState<string[]>(["msk"]);
+  const [active, setActive] = React.useState(0);
+  const optionRefs = React.useRef<(HTMLDivElement | null)[]>([]);
 
   const toggle = (value: string) =>
     setSelected((current) =>
@@ -24,16 +35,27 @@ export default function CheckboxIndicatorExample() {
       aria-label="Города доставки"
       aria-multiselectable
       className={styles.optionList}
+      onKeyDown={(event) => {
+        const next = nextIndex(event.key, active, CITIES.length);
+        if (next === null) return;
+        event.preventDefault();
+        setActive(next);
+        optionRefs.current[next]?.focus();
+      }}
     >
-      {CITIES.map((city) => {
+      {CITIES.map((city, index) => {
         const isSelected = selected.includes(city.value);
         return (
           <div
             key={city.value}
+            ref={(node) => {
+              optionRefs.current[index] = node;
+            }}
             role="option"
             aria-selected={isSelected}
-            tabIndex={0}
+            tabIndex={index === active ? 0 : -1}
             className={styles.option}
+            onFocus={() => setActive(index)}
             onClick={() => toggle(city.value)}
             onKeyDown={(event) => {
               if (event.key === " " || event.key === "Enter") {

package/src/components/color-picker/COMPONENT.md

@@ -270,7 +270,7 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 - Field + trigger row: gap `--prime-space-2`, `align-items: flex-end` so the trigger aligns with the field box under a label.
 - Panel parts gap: 12px (`--prime-space-3`) from `ColorPicker.Panel`.
 - ColorPresets.Content `align="auto"`: a trigger near the end of the screen lines up the panel's end edge and the panel grows toward the start, and the other way near the start; a fixed `align` still flips at the screen edge.
-- ColorPresets grid: one row for up to 8 presets (+ «no color»), else rows of 8 (`columns` overrides); below 480px viewport width the `l` / `xl` grids wrap to half the columns.
+- ColorPresets grid: one row for up to 8 presets (+ «no color»), else rows of 8 (`columns` overrides); below 480px viewport width the `l` / `xl` grids wrap to half the columns. On a coarse pointer every swatch grows to the 44 px touch target and the grid takes at most 5 columns, so it still fits a 320px panel; the arrow keys walk the same columns.
 
 ## Accessibility
 
@@ -306,7 +306,7 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 | `red` | `"Красный, 0–255"` | Red channel field. |
 | `green` | `"Зелёный, 0–255"` | Green channel field. |
 | `blue` | `"Синий, 0–255"` | Blue channel field. |
-| `trigger` | `"Цвет"` | ColorPresets trigger name prefix: «<trigger>: <color name>». |
+| `trigger` | `"Цвет"` | ColorPresets trigger name prefix: «<trigger>: <color name>»; in a FieldList cell the column heading. |
 | `list` | `"Цвета"` | ColorPresets swatch list name when `Content` has no `label`. |
 | `empty` | `"Без цвета"` | ColorPresets «no color» swatch and the trigger name for an empty value. |
 

package/src/components/color-swatches/COMPONENT.md

@@ -97,6 +97,7 @@ Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
 
 ## Layout & spacing
 - The swatches take the container width in equal columns: each one stretches across its column (the height stays the tier's). A row wraps only when they no longer fit, and then the swatches split evenly over the rows (16 → 8 + 8, never 14 + 2); no column count to set. In a content-sized container they stand in one row at the tier size.
+- On a coarse pointer the swatches grow to the 44 px touch target (a dense grid cannot grow an invisible hit area past its neighbours) and wrap into more rows.
 - The keyboard focus ring sits outside the swatches; kit hosts (Modal / Drawer body, panels, cards) already keep `--prime-focus-space` padding, so the ring is never clipped. In your own `overflow` container, keep that padding.
 - Label → swatches and swatches → hint use the tier `label-gap` / `hint-gap`; field → field 20.
 

package/src/components/datepicker/COMPONENT.md

@@ -156,6 +156,7 @@ Committing: without `footer` a picked day (or the second day of a range) applies
 - Label → field: the tier `label-gap`; field → field in a form: `--prime-space-5`.
 - `align="auto"`: a field near the end of the screen lines up the popover's end edge and the panel grows toward the start, and the other way near the start; a fixed `align` still flips at the screen edge.
 - Months gap `--prime-space-6`. `Datepicker.Panel` has no fill, padding or radius — the host is its container; it shows 1–2 months by the host's width with day columns spread across it. An embedded panel measures its parent; narrower than one month → compact cells and footer fields above the buttons. Works from 320 px.
+- On a coarse pointer the day cells grow to the 44 px touch target (a dense grid cannot grow an invisible hit area past its neighbours); narrower than seven of them, the columns shrink.
 - Values are wall-clock local dates; convert time zones in the app.
 
 ## Accessibility

package/src/components/dnd/COMPONENT.md

@@ -36,7 +36,7 @@ Dnd.Root                         session owner: overlay (portal), live region, l
 ├─ Dnd.Draggable                 an item to carry elsewhere; stays in place, faded, until the drop
 └─ Dnd.DropZone                  a box that takes dropped items
 ```
-A drag in flight is drawn by `Dnd.Root` as a clone of the lifted element above every layer, following the pointer; an item without a fill of its own flies on the fill of the surface it was lifted from (`--prime-color-layer-current`). A refusal with a reason shows the reason in a chip under the clone. The page gets `data-dnd-active="mouse | touch | pen"` on `<html>` for the length of the gesture.
+A drag in flight is drawn by `Dnd.Root` as a clone of the lifted element above every layer, following the pointer. The clone flies inside empty copies (`display: contents`) of its ancestors up to the nearest surface (`data-depth`) and that surface's `data-theme`, so the host's variables and selectors (a List row's tier padding and radius) dress it exactly as the item in place, and it sets down without a jump; an item without a fill of its own flies on the fill of the surface it was lifted from (`--prime-color-layer-current`). A refusal with a reason shows the reason in a chip under the clone. The page gets `data-dnd-active="mouse | touch | pen"` on `<html>` for the length of the gesture.
 
 ## API
 
@@ -190,7 +190,7 @@ An item's own `onPointerDown` / `onKeyDown` run before the kit's: `preventDefaul
 - The list gap is `--prime-space-2`; override it with `className` (widen the rule with `[data-axis]` so it wins: `.gallery[data-axis] { gap: … }`).
 - A grid (`axis="grid"`) is `display: grid`: the host sets the tracks (`grid-template-columns`) and the cells' size; the gap takes a cell, and a carried item resizes to the cell it would land in.
 - The reason chip stands `--prime-tooltip-offset` under the carried copy, start-aligned, at most `--prime-tooltip-max-width` wide.
-- The look of a row is the consumer's: give `Dnd.SortableItem` / `Dnd.Draggable` a fill, a radius and padding on its own class — the clone is portalled to `<body>`, ancestor selectors do not reach it. A table row is the exception: it flies inside empty copies (`display: contents`) of its ancestors up to the nearest surface (`data-depth`), so the table's own cell styles still apply.
+- The look of a row is the consumer's: give `Dnd.SortableItem` / `Dnd.Draggable` a radius on its own class (the gap and the clone's fill take it) and keep the row's look within its ancestors up to the nearest surface (`data-depth`) — the clone flies inside empty copies (`display: contents`) of exactly those, so their variables and selectors still apply. A table row flies in a one-row copy of its table inside them.
 - A scrollable ancestor under the pointer auto-scrolls within 64 px of its edge (a `ScrollContainer` strip works).
 - Keep a zone's height stable between states; it only changes fill and outline.
 
@@ -246,7 +246,7 @@ An item's own `onPointerDown` / `onKeyDown` run before the kit's: `preventDefaul
 - A `Dnd.SortableItem` `id` that differs from `getId(item)` → the item never moves.
 - Rendering items yourself instead of through `renderItem` → the list cannot draw the gap or the optimistic order.
 - Using `index` as the id → ids must survive a reorder.
-- Styling a row from an ancestor selector (`.list .row`) → the flying clone loses it.
+- Styling a row from an ancestor above the nearest surface (`data-depth`) → the flying clone loses it; keep the row's look on the row and its hosts inside the surface.
 - Starting a drag from a button inside a row without `handle` → presses on controls are theirs; use `Dnd.Handle`.
 - A drag-only move with no alternative → add a button or a menu for the same action.
 - `aria-label` on an item that shows a title and a description → it hides them; point `aria-labelledby` / `aria-describedby` at them.