prime-ui-kit 0.13.0 → 0.14.0

package/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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/dist/skill/reference/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.

package/dist/skill/reference/components/field-list/COMPONENT.md

@@ -0,0 +1,164 @@
+# FieldList
+
+**Category:** inputs
+**Kind:** composite
+
+> An editable list of records of one shape — invoice lines, specs, contacts, prices by period: one row per record, the column headings once above the rows, a remove button per row and an add button under them.
+
+## When to use
+- A form part where a person adds, edits and removes several records of the same fields: invoice lines, contacts of a client, specs of a plan, recipients.
+- A base value with overrides (a price and its changes by month): the base is the first row, pinned with `getLocked`, each override is a row.
+- A list of short texts in the order a person sets (selling points, checklist items): one column, `reorderable`.
+- Small attributes of a record beside its text (an icon, a color): `width="compact"` columns with an icon-only `Select` (`Select.TriggerIcon` and no `Select.Value`) and a `ColorPresets` swatch.
+
+## When not to use
+- Records that are only read, sorted or filtered → [DataTable](../data-table/COMPONENT.md); its rows are data, not form fields.
+- One value in several units or currencies (a deposit in ₽, $, ฿) → fields side by side in one row of the form, each unit in `Input.InlineAffix`, under one heading; not a list a person grows.
+- A set of tags or values picked from options → [TagSelect](../tag-select/COMPONENT.md).
+- Reordering items that are not form rows (menu sections, cards) → [Dnd](../dnd/COMPONENT.md) or [List](../list/COMPONENT.md) `onReorder`.
+- A record with many fields or long texts per row → a list of records that opens each one in a [Drawer](../drawer/COMPONENT.md); a row holds up to four short fields.
+
+## Import
+```tsx
+import { FieldList, type FieldListColumn } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+FieldList                    field frame: label · the list · hint / error
+├─ heading row               the column headings, once (aria-hidden; each field carries its heading as its label)
+├─ <ol>                      the rows (Dnd.Sortable with `reorderable`)
+│  └─ <li> row               [lead: handle | lock] [a cell per column] [end: remove]
+│     └─ cell                one kit field without `label`, named by its column heading
+└─ add row                   Button «addLabel» (+ `labels.maxReached` at `max`)
+```
+A leaf: rows come from `value` through `renderItem`, which returns one element per column (a fragment). Every framed kit field (Input, Select, Datepicker, NativeSelect, ColorField…) in a cell takes its column heading as its label: read by screen readers, not shown while the heading row is on screen, shown above the field once the rows stack in a narrow container. `ColorPresets` takes it as the name of its trigger.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### FieldList
+Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editable list of records of one shape: column headings once, a row of fields per record (`<ol>`), remove per row, add under the rows; rows stack under 480 px.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `columns` | `readonly FieldListColumn[]` | — (required) | The columns in cell order: `label` (the heading; it names the field of the column in every row), `width` (`fill` \| `compact` \| `s` \| `m`), `required` (a `*` after the heading). |
+| `renderItem` | `(item: T, row: FieldListRow<T>) => ReactNode` | — (required) | The cells of a row, one element per column (a fragment): kit fields without `label`. `row` has `index`, `update(patch)` and `remove()`. |
+| `getId` | `(item: T) => string` | — (required) | Stable unique id of an item: the row key and the drag id. |
+| `value` | `readonly T[]` | — | The rows (controlled). |
+| `defaultValue` | `readonly T[]` | `[]` | The first rows (uncontrolled). |
+| `onValueChange` | `(value: T[]) => void` | — | The new list after an edit (`row.update`), an added, removed or moved row. |
+| `createItem` | `() => T` | — | A new empty item; with it the add button shows under the rows and focus goes to the new row's first field. |
+| `addLabel` | `string` | — | Text of the add button: what is added («Добавить позицию»). |
+| `getLabel` | `(item: T) => string` | — | The row's own text (its title field) for the remove button, the handle and drag announcements; else the row number. |
+| `getLocked` | `(item: T) => boolean` | — | Pinned rows: a lock in the lead column, no remove button, they hold their place while others move. |
+| `reorderable` | `boolean` | `false` | Rows move by a leading handle: drag, a touch hold, Alt + ↑ / ↓. |
+| `min` | `number` | `0` | The fewest rows: at this count the remove buttons are disabled. |
+| `max` | `number` | — | The most rows: at this count the add button is disabled with `labels.maxReached` beside it. |
+| `label` | `ReactNode` | — | Heading of the list; names the `<ol>`. Omit it inside a `Fieldset` whose legend names the list. |
+| `aria-label` | `string` | — | Name of the `<ol>` when no visible `label` names it (a section heading above the list). |
+| `hint` | `ReactNode` | — | Help text under the list; hidden while `error` shows. |
+| `error` | `ReactNode` | — | A problem of the list as a whole («Добавьте хотя бы одну позицию»); a field's own error goes on that field. |
+| `disabled` | `boolean` | `false` | Disables every field, handle and button; a disabled `Fieldset` around it sets it too. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the headings, buttons and the kit fields that read the host tier. Without it the host tier, else `m`. |
+| `labels` | `Partial<FieldListLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
+
+## Variants
+
+### width (column)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `fill` | shares the free width with the other `fill` columns | names, descriptions, any text | yes |
+| `compact` | two control heights wide | an icon-only `Select`, a `ColorPresets` swatch, a checkbox | |
+| `s` | 144 px | a quantity, a code, a number of days | |
+| `m` | 192 px | an amount with its unit, a date, a phone | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `reorderable` | a grip before every row; Alt + ↑ / ↓ on it | the order of the records matters (a pricing page, a checklist) | `false` |
+| `getLocked` | a lock where the grip is, no remove button; the row holds its place | a base value, system records a person cannot drop | — |
+| `createItem` | the add button under the rows, aligned with the first column | the person grows the list | — |
+| `min` · `max` | remove buttons off at `min`; the add button off with «Не больше {max}» at `max` | the record count is bounded | `0` · — |
+
+**Combinations**
+- Recommended: `label` on the list (or a `Fieldset` legend around it), one heading per column, a `getLabel` from the title field, an `addLabel` that says what is added.
+- Allowed but rare: one column — the heading row is not drawn, the list label names the rows.
+- Pointless: `getLocked` on every row with `createItem` — nothing can be removed or moved.
+- Forbidden: a `label` on every field of a row, a numbered label («Пункт 1», «Пункт 2»), a unit in a heading when the field shows it.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| empty | `value` with no items | no heading row; only the add button (with `createItem`) |
+| at min | `value.length <= min` | remove buttons `disabled` |
+| at max | `value.length >= max` | add button `disabled`, `labels.maxReached` beside it |
+| pinned row | `getLocked(item)` | `data-locked="true"` on the `<li>`; a lock, no remove button |
+| invalid | `error` (the list), a field's own `error` | the list's message under the add row; a field's under the field in its row |
+| disabled | `disabled` (or a disabled Fieldset) | `data-disabled="true"` on the frame; fields, handles and buttons disabled through the kit's disabled context |
+| stacked | container narrower than 480 px | heading row hidden, each row's fields in one column with their labels shown |
+
+## Layout & spacing
+- Rows 12 apart (`--prime-space-3`); columns 12 apart; the heading row sits at the tier's label gap above the first row.
+- Every row and the heading row share one track list: `[lead] [columns] [end]`; the lead fits the grip, the end fits a remove button of the tier.
+- The handle, the lock and the remove button stand on the middle of the first line of fields, so a field's error under it grows the row downwards only.
+- The add button lines up with the first column of fields, 12 under the last row.
+- Under 480 px of its own width (a container query): rows stack, fields 16 apart inside a row, rows 24 apart.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves through the fields of a row, then to its remove button and on. |
+| `Enter` · `Space` | On the add button adds a row and focuses its first field; on a remove button removes the row and focuses the next row's remove button. |
+| `Alt + ↑` · `Alt + ↓` | With `reorderable`, moves the row up or down (from its handle). |
+
+### ARIA
+- The rows are an `<ol>` named by the list `label` (`aria-labelledby`); the list gives each row its position.
+- The heading row is `aria-hidden`: each field in a cell carries its column heading as its own label, read but not shown on wide rows.
+- In a narrow container the heading row goes and each field's label shows above it.
+- The remove button is «Удалить {row}», the handle «Переместить {row}»: the row's name from `getLabel`, else its number.
+- A pinned row has a lock in place of the handle and no remove button; without `reorderable` the lock is an image named «Закреплена».
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `remove` | `"Удалить {row}"` | `aria-label` of a row's remove button; `{row}` is the row's name. |
+| `reorder` | `"Переместить {row}"` | `aria-label` of a row's handle (`reorderable`); `{row}` is the row's name. |
+| `row` | `"строку {index}"` | Name of a row without `getLabel` text; `{index}` counts from 1. |
+| `namedRow` | `"«{label}»"` | Name of a row with `getLabel` text; `{label}` is that text. |
+| `locked` | `"Закреплена"` | Spoken name of the lock of a pinned row in a list without `reorderable`. |
+| `maxReached` | `"Не больше {max}"` | Text beside the disabled add button once the list holds `max` rows. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Lines of an invoice: the column headings stand once above the rows, each row has a remove button and the add button sits under them — `columns`, `renderItem`, `createItem`, `addLabel`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier: the headings, the fields, the handle and the buttons follow the list's size — `size`. |
+| [reorder.tsx](examples/reorder.tsx) | Selling points of a plan in the order of the pricing page: a one-column list has no headings and no numbers, a point moves by its handle or Alt+arrows — `reorderable`, `getLabel`. |
+| [locked.tsx](examples/locked.tsx) | Specs of a plan on one line each: an icon picker and a color swatch take compact columns, the first three specs are pinned with a lock and the rest reorder below them — `getLocked`, `width`, `reorderable`. |
+| [base-row.tsx](examples/base-row.tsx) | A plan price and its changes by month in one table: the base price is the first, pinned row, each change is a row with its month and its price, and the unit sits in the field, not in a heading — `getLocked`, `width`. |
+| [limits.tsx](examples/limits.tsx) | Recipients of invoice reminders, from one to three: the last row cannot be removed and the add button says why it is off once the list is full — `min`, `max`, `hint`. |
+| [errors.tsx](examples/errors.tsx) | Contacts of a client checked on save: a field's problem shows under that field in its row, a problem of the whole list under the list, and focus goes to the first wrong field — `error`. |
+| [states.tsx](examples/states.tsx) | The same list editable and disabled while the request saves it: fields, handles and buttons turn off together — `disabled`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the lines: it sums them under the list and puts the saved lines back on reset — `value`, `onValueChange`. |
+| [narrow.tsx](examples/narrow.tsx) | The invoice lines in a 320 px column: the headings give way, each row stacks its fields with their own labels and rows stand a group apart — `columns`. |
+
+## Mistakes
+- A `label` above every field of every row («Иконка», «Параметр», «Значение» four times) → a FieldList: the headings stand once, the fields take them as hidden labels.
+- Numbered labels («Преимущество 1», «Преимущество 2») → none: the list label names the rows and the order is visible.
+- One record split over two lines of half-width fields → one row; small attributes go to `compact` columns (icon-only `Select`, `ColorPresets`).
+- A base value as a separate field above its overrides, in another geometry → the first row, pinned with `getLocked`.
+- The unit in every heading («Цена, ₽ / день») and again in the field → the unit once, in `Input.InlineAffix`.
+- A hint that explains what the lock already shows («Первые три всегда первыми») → no hint; the lock says it.
+- `aria-label` written on every field in a cell → none: the column heading names the field.
+- A grip, a remove button and an add button drawn by hand around a `.map()` of fields → FieldList.
+
+## Related
+- **Built from:** [Button](../button/COMPONENT.md) (add, remove), [Dnd](../dnd/COMPONENT.md) (`reorderable`: `Dnd.Sortable`, `Dnd.Handle`), [Label](../label/COMPONENT.md) (headings), `Icon` (lock), the field frame (label, hint, error)
+- **See also:** [Input](../input/COMPONENT.md), [Select](../select/COMPONENT.md) (icon-only trigger), [ColorPicker](../color-picker/COMPONENT.md) (`ColorPresets`), [Fieldset](../fieldset/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)

package/dist/skill/reference/components/field-list/examples/base-row.tsx

@@ -0,0 +1,76 @@
+/** A plan price and its changes by month in one table: the base price is the first, pinned row, each change is a row with its month and its price, and the unit sits in the field, not in a heading — `getLocked`, `width`. */
+import { FieldList, type FieldListColumn, Input, Select } from "prime-ui-kit";
+import * as React from "react";
+
+type Period = { id: string; from: string; price: string; base?: boolean };
+
+const COLUMNS: FieldListColumn[] = [{ label: "Действует" }, { label: "Цена за месяц", width: "m" }];
+
+const MONTHS = [
+  { value: "01", label: "С 1 января" },
+  { value: "04", label: "С 1 апреля" },
+  { value: "07", label: "С 1 июля" },
+  { value: "10", label: "С 1 октября" },
+];
+
+const PERIODS: Period[] = [
+  { id: "base", from: "", price: "4 900", base: true },
+  { id: "q3", from: "07", price: "5 400" },
+  { id: "q4", from: "10", price: "5 900" },
+];
+
+export default function FieldListBaseRowExample() {
+  const [periods, setPeriods] = React.useState(PERIODS);
+
+  return (
+    <FieldList
+      label="Цена тарифа"
+      columns={COLUMNS}
+      value={periods}
+      onValueChange={setPeriods}
+      getId={(period) => period.id}
+      getLocked={(period) => period.base ?? false}
+      createItem={() => ({ id: crypto.randomUUID(), from: "", price: "" })}
+      addLabel="Добавить изменение цены"
+      renderItem={(period, row) => (
+        <>
+          {period.base ? (
+            <Input.Root>
+              <Input.Wrapper>
+                <Input.Field value="Всегда, если нет изменений" readOnly />
+              </Input.Wrapper>
+            </Input.Root>
+          ) : (
+            <Select.Root
+              value={period.from}
+              onValueChange={(from) => row.update({ from })}
+              placeholder="Выберите месяц"
+            >
+              <Select.Trigger>
+                <Select.Value />
+              </Select.Trigger>
+              <Select.Content>
+                {MONTHS.map((month) => (
+                  <Select.Item key={month.value} value={month.value}>
+                    {month.label}
+                  </Select.Item>
+                ))}
+              </Select.Content>
+            </Select.Root>
+          )}
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Field
+                value={period.price}
+                inputMode="decimal"
+                placeholder="0"
+                onChange={(event) => row.update({ price: event.target.value })}
+              />
+              <Input.InlineAffix side="end">₽</Input.InlineAffix>
+            </Input.Wrapper>
+          </Input.Root>
+        </>
+      )}
+    />
+  );
+}