prime-ui-kit 0.13.0 → 0.14.0

package/dist/index.js

@@ -27,6 +27,7 @@ import {
   Drawer,
   Dropdown,
   ExampleFrame,
+  FieldList,
   Fieldset,
   FileUpload,
   Gallery,
@@ -85,7 +86,7 @@ import {
   useSidebar,
   useTokenValue,
   useUploadQueue
-} from "./chunks/chunk-Z3WKKAS6.js";
+} from "./chunks/chunk-SYEX7OVT.js";
 import {
   Avatar,
   Badge,
@@ -117,7 +118,7 @@ import {
   textTones,
   tones,
   variants
-} from "./chunks/chunk-E6SQBSDF.js";
+} from "./chunks/chunk-WXKRUVSE.js";
 import {
   ControlSizeProvider,
   useOptionalControlSize
@@ -158,6 +159,7 @@ export {
   Dropdown,
   EmptyPage,
   ExampleFrame,
+  FieldList,
   Fieldset,
   FileUpload,
   Gallery,

package/dist/internal/ChartTooltip.d.ts

@@ -0,0 +1,26 @@
+import * as React from "react";
+import type { AnchorPoint } from "../hooks/usePosition";
+export type { AnchorPoint };
+export type ChartTooltipProps = React.HTMLAttributes<HTMLDivElement> & {
+    /** The point the content belongs to («8 окт», «Неделя 41»), over the content. */
+    label?: React.ReactNode;
+    /**
+     * Floats the tooltip beside a point of `anchorRef` (px from its top-left corner) — the pointer
+     * over the plot, or the point the arrow keys reached; `null` hides it. Without `anchorRef` the
+     * body renders in place (a chart library positions it).
+     */
+    point?: AnchorPoint | null;
+    /** The plot the point lies in: its scroll and size changes move the tooltip with it. */
+    anchorRef?: React.RefObject<HTMLElement | null>;
+    /** Escape hid the floating tooltip (it stays hidden until the point moves). */
+    onDismiss?: () => void;
+    ref?: React.Ref<HTMLDivElement>;
+};
+/**
+ * The one chart tooltip of the kit (ChartFrame.Tooltip, Sparkline): its look, and — with
+ * `anchorRef` — its place. A floating tooltip is an anchored layer like every other
+ * (`useFloatingLayer` + `usePosition` with `anchorPoint`): right of the point, vertically centred,
+ * flipped to the left only where the right has no room, kept inside the viewport, passive (no
+ * focus, no presses) and aria-hidden — the chart speaks its points itself.
+ */
+export declare function ChartTooltip({ anchorRef, ...props }: ChartTooltipProps): import("react/jsx-runtime").JSX.Element;

package/dist/internal/FieldAction.d.ts

@@ -1,10 +1,4 @@
 import * as React from "react";
-/**
- * A button segment at a field's edge (Input, Textarea): full field height, the icon centred with the
- * field padding on both sides, a hover wash over the whole segment, the touch hit area. The field
- * hosts style it through `data-field-action`.
- */
-export declare const fieldActionClass: string;
 export type FieldActionButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" | "children"> & {
     /** Accessible name and tooltip («Позвонить», «Открыть профиль»). */
     label: string;
@@ -14,8 +8,13 @@ export type FieldActionButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonE
     children: React.ReactNode;
     ref?: React.Ref<HTMLButtonElement>;
 };
+/**
+ * A segment without a tooltip, for a kit control whose glyph says it all (Input's clear and
+ * reveal): the name stays accessible, nothing floats over the field.
+ */
+export declare function FieldActionSegment(props: FieldActionButtonProps): import("react/jsx-runtime").JSX.Element;
 /** A named icon action at the field's edge with a tooltip. */
-export declare function FieldActionButton({ label, asChild, className, disabled, type, children, ref, ...rest }: FieldActionButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function FieldActionButton(props: FieldActionButtonProps): import("react/jsx-runtime").JSX.Element;
 export type CopyState = "idle" | "copied" | "error";
 export type FieldCopyLabels = {
     /** Name and tooltip of the copy button. */

package/dist/internal/fieldCell.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+/**
+ * The contract between `FieldList` and the fields in its cells. A cell provides its column heading;
+ * a framed field without a `label` of its own takes it as its label (and keeps its own `label`, if
+ * any), so every field in a row has a name without a visible label per row. The column heading
+ * shows the name once above the rows; the field's label is read, not shown, until the list stacks
+ * its rows into blocks in a narrow container (`FIELD_LIST_CONTAINER`), where each field shows it.
+ */
+export type FieldCell = {
+    /** The column heading: the name of the field in this cell. */
+    label: string;
+    /**
+     * `wide` — hidden while the column heading is on screen, shown when the rows stack; `always` —
+     * a one-column list, named by the list's own label, shows none in either layout.
+     */
+    hidden: "wide" | "always";
+};
+export declare const FieldCellContext: React.Context<FieldCell | null>;
+/** Name of the size container `FieldList` sets; FieldFrame shows a cell label under its query. */
+export declare const FIELD_LIST_CONTAINER = "prime-field-list";
+export declare function useFieldCell(): FieldCell | null;

package/dist/internal/messageList.d.ts

@@ -43,8 +43,8 @@ export type MessageListContextValue = {
     /** A message was new at the end in this commit. */
     arrivedNow: () => boolean;
     /**
-     * Brings a message into view and points at it (unless `flash` is `false`: the others blink
-     * around it); `focus` moves the focus to it too.
+     * Brings a message into view and blinks it (unless `flash` is `false`); `focus`
+     * moves the focus to it too.
      */
     reveal: (value: string, focus?: boolean, flash?: boolean) => boolean;
     /** The selection; read it through `useMessageSelection` / `useListSelection`. */

package/dist/internal/palette.d.ts

@@ -1,4 +1,11 @@
 import { type PaletteColor } from "./states";
+/**
+ * A palette hue as a data mark: its step of the categorical chart palette, so a category has one
+ * color in charts and in shares. The one source of `--hue-chart` in `palette.module.css` (kept equal
+ * by `palette.test.ts`); as strings here, because a chart library takes its colors in JS. Gray is
+ * `chart-other`; sky has no chart step (it sits too close to blue) and keeps its solid.
+ */
+export declare const HUE_CHART: Record<PaletteColor, string>;
 /**
  * A palette hue for a person, stable per `id`: the same id always gets the same hue, on every
  * render and every device (a string hash, no state). For names in a group chat and initials of

package/dist/skill/SKILL.md

@@ -6,10 +6,12 @@ description: >
   navigation on prime-ui-kit; when
   choosing which kit component fits a task; when a needed component is missing and must be composed from
   the kit; when adding loading, empty and error states, feedback, motion or micro-animation to a screen;
-  and when reviewing a screen for design-system compliance (spacing rhythm, sizes, tokens, states,
-  motion, a11y, narrow screens). Triggers: build a screen, page, form, table, board, schedule, chat,
-  uploads, settings, dashboard, navigation; which component to use; animate, transition, loading state; prime-ui-kit; review a screen
-  against the design system — in any language.
+  when changing or redesigning a screen that exists; and when reviewing a screen for design-system and
+  UX compliance (data shape and layout, repeated or redundant labels, copy, friction, spacing rhythm,
+  sizes, tokens, states, motion, a11y, narrow screens). Triggers: build a screen, page, form, table,
+  board, schedule, chat, uploads, settings, dashboard, navigation; repeating fields, add another row;
+  which component to use; animate, transition, loading state; prime-ui-kit; improve, fix or review a
+  screen against the design system — in any language.
 ---
 
 # prime-ui-kit
@@ -24,25 +26,31 @@ region, `Skeleton` while it loads).
 
 0. **First** — [cheatsheet.md](cheatsheet.md): one page of the decisions agents most often get wrong,
    each as «do this, not that» with the exact API. Then follow the steps in order; each names its file.
-1. **The app frame, once per app** — [layouts.md](layouts.md): styles, theme, providers, `AppShell`
+   Changing a screen that exists: audit it first ([ux.md](ux.md#8-changing-a-screen-someone-built)),
+   then make the change.
+1. **Brief** — [ux.md](ux.md): five lines before any JSX (who and what for, the data and its shape,
+   the main action, the states, the narrow screen); the shape of the data decides the layout, every
+   label must carry something new, friction matches the cost of a mistake.
+2. **The app frame, once per app** — [layouts.md](layouts.md): styles, theme, providers, `AppShell`
    with `Sidebar` and `AppHeader`, page wrappers, auth screens. A screen you deliver renders only its page.
-2. **Choose** — [choosing.md](choosing.md): the category by task, then the component, then the pairs
+3. **Choose** — [choosing.md](choosing.md): the category by task, then the component, then the pairs
    that are easy to confuse.
-3. **Read the component** — [components.md](components.md) links each `COMPONENT.md` (API, variants,
+4. **Read the component** — [components.md](components.md) links each `COMPONENT.md` (API, variants,
    states, a11y, mistakes) and its `examples/`. Never guess a prop; copy structure from an example.
-4. **Compose the screen** — [composition.md](composition.md): start from the closest working screen in
+5. **Compose the screen** — [composition.md](composition.md): start from the closest working screen in
    [patterns/](patterns/) and keep its skeleton; rhythm, hierarchy, surfaces and type in
    [foundations.md](foundations.md).
-5. **Write the JSX** — [api-contract.md](api-contract.md): prop names, controlled state, events (async
+6. **Write the JSX** — [api-contract.md](api-contract.md): prop names, controlled state, events (async
    events return the request's Promise), forms and their submit flow (`Fieldset disabled`), uploads
    (`useUploadQueue`), destructive actions (`ConfirmDialog`), helpers (`groupMessages` for chat rows you build yourself),
    icon names.
-6. **States and motion** — [motion.md](motion.md): every region loads, empties and fails without
+7. **States and motion** — [motion.md](motion.md): every region loads, empties and fails without
    flipping; what the kit animates by itself and when to move your own elements.
-7. **Narrow screens** — [responsive.md](responsive.md): every screen works from 320px, the page panel is
+8. **Narrow screens** — [responsive.md](responsive.md): every screen works from 320px, the page panel is
    `PageToolbar`, nothing is hidden on phones, touch follows `(hover)` / `(pointer)`.
-8. **Check** — [checklist.md](checklist.md) and [anti-slop.md](anti-slop.md). Fix every «no», then hand
-   over.
+9. **Check** — [checklist.md](checklist.md) and [anti-slop.md](anti-slop.md), then look at the screen
+   in a browser: both themes, 1280 and 375 px ([ux.md](ux.md#9-look-at-it-before-handing-it-over)). Fix
+   every «no», then hand over.
 
 ## Where things are
 
@@ -63,6 +71,7 @@ project under `node_modules/prime-ui-kit/src/`.
 | File | Read when |
 |---|---|
 | [cheatsheet.md](cheatsheet.md) | first — the most frequent decisions and mistakes in one page |
+| [ux.md](ux.md) | before the layout of every screen and before changing one — the brief, data shape → layout, label economy, copy, friction, defaults, the visual check |
 | [layouts.md](layouts.md) | once per app — the app frame, page wrappers, auth screens |
 | [choosing.md](choosing.md) | unsure which component fits (Gantt / Timeline / Kanban / DataTable, Message / Composer, FileUpload list / grid / gallery / strip, ColorField / ColorPicker…); how to confirm a destructive action |
 | [components.md](components.md) | finding a component and its `COMPONENT.md` / `examples/` |
@@ -110,7 +119,8 @@ Take a semantic `<Icon name="…" />` first, else a glyph from the full animated
 5. Air is hierarchy: tighter inside a group, wider between groups, widest between sections — spacing via
    `gap` on the parent, never margins.
 6. One primary action per area. The rest are `soft`/`ghost`/`outline` with `tone="neutral"`.
-7. Labels above fields, always. Placeholder is an example value, never the label.
+7. Labels above fields, always — once per column for records in rows (`FieldList`), never numbered
+   («Пункт 1»), never repeating their heading. Placeholder is an example value, never the label.
 8. Text through `Typography` roles (`title-m` section, `title-s` group, `body-m` text, `caption` meta;
    the page title is `PageContent.Title`). No custom font sizes.
 9. Overlays (Modal, ConfirmDialog, Drawer, Sheet, Popover, Dropdown, Tooltip, CommandMenu, Select,

package/dist/skill/anti-slop.md

@@ -48,9 +48,10 @@ Text color goes through `Typography tone="secondary"`, not CSS.
 // bad — a card around a card around a table
 <Card.Root><Card.Root><DataTable columns={columns} rows={rows} /></Card.Root></Card.Root>
 
-// good — DataTable already is a filled block; a section heading is enough
-<Typography as="h2" variant="title-m">Последние оплаты</Typography>
-<DataTable columns={columns} rows={rows} />
+// good — DataTable already is a filled block; a titled section is enough
+<PageContent.Section label="Последние оплаты">
+  <DataTable columns={columns} rows={rows} />
+</PageContent.Section>
 ```
 
 ## 3a. Hover that merges with the neighbour
@@ -106,6 +107,78 @@ and inside a card, in both themes: rest, hover and the neighbour must be three d
 
 A search field in a toolbar may go without a visible label, but then it needs `aria-label`.
 
+## 5a. A label in every row, a record split over lines
+
+The most common shape bug of generated forms: rules for one field applied to a list of records.
+
+```tsx partial
+// bad — «Иконка · Параметр · Значение · Цвет» repeated in every record, a record on two lines,
+// numbered labels, a hint that explains the lock
+{specs.map((spec, index) => (
+  <div key={spec.id} className={styles.grid}>
+    <Select.Root label="Иконка">…</Select.Root>
+    <Input.Root label={`Параметр ${index + 1}`}>…</Input.Root>
+    <Input.Root label="Значение">…</Input.Root>
+    <ColorField label="Цвет иконки" />
+  </div>
+))}
+<Typography variant="body-s">Первые три всегда первыми. Остальные можно перетаскивать.</Typography>
+
+// good — one row per record, the headings once, compact columns for the small attributes
+<FieldList
+  label="Характеристики"
+  columns={[
+    { label: "Иконка", width: "compact" },
+    { label: "Параметр" },
+    { label: "Значение" },
+    { label: "Цвет", width: "compact" },
+  ]}
+  reorderable
+  getLocked={(spec) => spec.pinned}
+  value={specs}
+  onValueChange={setSpecs}
+  getId={(spec) => spec.id}
+  getLabel={(spec) => spec.name}
+  createItem={newSpec}
+  addLabel="Добавить характеристику"
+  renderItem={(spec, row) => (
+    <>
+      <Select.Root value={spec.icon} onValueChange={(icon) => row.update({ icon })}>
+        <Select.Trigger>
+          <Select.TriggerIcon><Icon name={spec.icon} /></Select.TriggerIcon>
+        </Select.Trigger>
+        <Select.Content>…</Select.Content>
+      </Select.Root>
+      <Input.Root>…</Input.Root>
+      <Input.Root>…</Input.Root>
+      <ColorPresets.Root value={spec.color} onValueChange={…}>…</ColorPresets.Root>
+    </>
+  )}
+/>
+```
+
+The same for one value in several units — one heading, the fields in a row, the unit inside:
+
+```tsx partial
+// bad — three labels, the currency in the label and again in the field, one field on a line of its own
+<Input.Root label="Депозит, $" optional>…<Input.InlineAffix side="end">$</Input.InlineAffix>…</Input.Root>
+<Input.Root label="Депозит, ฿" optional>…</Input.Root>
+<Input.Root label="Депозит, ₽" optional>…</Input.Root>
+
+// good — a group heading, three fields in one row, each named for assistive tech
+<Fieldset label="Депозит">
+  <div className={styles.row}>
+    <Input.Root>
+      <Input.Wrapper>
+        <Input.Field aria-label="Депозит в долларах" inputMode="decimal" />
+        <Input.InlineAffix side="end">$</Input.InlineAffix>
+      </Input.Wrapper>
+    </Input.Root>
+    {/* ฿ and ₽ the same */}
+  </div>
+</Fieldset>
+```
+
 ## 6. Everything on one level of air
 
 ```css
@@ -115,7 +188,7 @@ A search field in a toolbar may go without a visible label, but then it needs `a
 /* good — proximity scale */
 .form { display: grid; gap: var(--prime-space-8); }   /* group → group 32 */
 .group { display: grid; gap: var(--prime-space-5); }  /* field → field 20 */
-/* section → section 40 comes from PageContent.Body */
+/* block → block 24 and section → section 40 come from PageContent.Body / PageContent.Section */
 ```
 
 ## 7. `div` instead of a ready component

package/dist/skill/cheatsheet.md

@@ -39,6 +39,10 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - A record card that saves each field: `<Input.Root onCommit={save}>` (save returns a Promise) — not hand-written blur / Enter / Escape handlers or a field disabled while saving.
 - Markdown text outside a chat (an announcement, a task description) is `<Textarea.Root formatting>`: the Composer's toolbar, hotkeys and subset (`**`, `_`, `~~`, `` ` ``, `||spoiler||`, links, `> `) — not a hand-made toolbar over a textarea. Turn it on only where the text is shown with its Markdown.
 - Copy or call next to a value: `Input.CopyButton`, `Input.Action` inside `Input.Wrapper` — not a Button beside the field; a password: `Input.RevealButton`.
+- Records of one shape a person adds and removes (invoice lines, contacts, specs, prices by period): `<FieldList columns={[{ label: "Услуга" }, { label: "Цена", width: "m" }]} value onValueChange getId createItem addLabel renderItem={(item, row) => <>…fields without label…</>} />` — the headings stand once, every field takes its column heading as its label; not a `.map()` of fields with a `label` in every row, not «Позиция 1», «Позиция 2».
+- Small attributes in a row of fields: an icon-only `Select` (`<Select.Trigger><Select.TriggerIcon>…</Select.TriggerIcon></Select.Trigger>`, no `Select.Value`) and a `ColorPresets` swatch in `width: "compact"` columns — not a full-width Select and a ColorField on a line of their own.
+- A base value with overrides (a price and its changes by month): one `FieldList`, the base as the first row pinned by `getLocked` — not a separate field above a list in another geometry.
+- One value in several units (a deposit in ₽, $, ฿): the fields side by side in one row under one heading, each unit in `Input.InlineAffix` — not a label per field, not the unit in the label and in the field.
 
 ## State
 
@@ -76,7 +80,8 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 
 - `Card.Root` only for a bounded block with its own title: a KPI tile (`variant="stat-trend"`), a settings panel (`variant="panel"`), side facts — not around a whole section, a form field or a page.
 - Never a card in a card, and never a `DataTable` inside a Card — the table is already a filled block.
-- Section without a card: `<Typography as="h2" variant="title-m">` + the content.
+- Section without a card: `<PageContent.Section label="…">` + the content (a link or button beside the heading in `PageContent.Actions`) — not a hand-made `<section>` + `Typography as="h2"` + own gap.
+- The tiles of a screen (KPI cards, charts, panels): one `<PageContent.Grid>` with a `<PageContent.Cell span>` per tile — not an `auto-fit` grid per row (the rows would stand 24 apart instead of 16).
 - Depth from fill, not lines: no borders around blocks; `<Divider />` only inside a block.
 - Every scroll region is a `ScrollContainer` — never `overflow: auto` on a `div`: its hidden edges fade by themselves (`edges="shadow"` on a filled surface, `"none"` only for a page column), `scrollbar="hidden"` on strips, `snap` on strips of cards, `lock` to hold a list still, `anchor="end"` for a log. Kit components already scroll through it; do not wrap them again.
 - Tabs are a bar, not a container: `Tabs.Root` stands in the host's padding and the panel content goes straight into `Tabs.Panel` — never a Card or a padded `div` around the tabs or inside a panel. In a Modal / Drawer, `Tabs.Root` wraps `X.Header` + `X.Body` and `Tabs.List` goes last into the header — not a tab strip at the top of the body.
@@ -90,13 +95,14 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - Data the server sorts and pages (thousands of records): `source="server"` + `rowCount`, controlled `sort` / `page` as the request, `page` back to 1 on a new search or filter, old rows kept with `loading` while the next page loads — not a server page passed to the default client mode, and not `rows={[]}` between pages.
 - Categories (sources, platforms, regions) get `color` and the same order of `chartColors` in charts; statuses and meanings get `tone` — never paint categories with tones.
 - A chart with axes or several series: `<ChartFrame.Root series state>` around the library (or your SVG) with `ChartFrame.Plot renderPlot`, `Legend`, `Table` — not a hand-made Card with a grey box while loading and a legend of colored dots.
+- A tooltip on your own SVG chart: `<ChartFrame.Tooltip point={{ x, y }} items>` with the pointer in plot coordinates — not a `foreignObject` or a div placed and clamped by hand; it flips only when out of room.
 - Amounts, counts and dates are `numeric` columns; statuses are `Badge.Root color` from one status → color map.
 - Rows people order by hand: `onReorder(id, beforeId)` (apply it with `moveBefore`, return the save's Promise) — not a Dnd list rebuilt next to the table.
 - A short list of records people order by hand (stages, priorities) is `<List.Root onReorder>` with `List.Item value` — not up / down buttons or a hand-made `Dnd.Sortable`.
 - Groups that fold: pass `defaultCollapsedGroups={[]}` (or the controlled `collapsedGroups` + `onCollapsedGroupsChange`) — not your own button in `renderGroupHeader` or filtering `rows`. One heatmap over several columns: the same `scale: { min, max }` on each.
-- A trend in a table row is `<Sparkline layout="compact">` in the column's `cell` (a column `width`, series built once, not inline); the number itself goes in its own column.
+- A trend in a table row is `<Sparkline layout="compact">` in the column's `cell` (a column `width`, series built once, not inline, the same `min` / `max` on every row when rows compare by size); the number itself goes in its own column. A missing day is `value: null`, never `0`.
 - Properties of one record: `<DescriptionList.Root>` of `DescriptionList.Item` — not a hand-made grid of label / value text, not a one-row DataTable.
-- Who is busy when, a plan with dates: `Gantt` with `onBarChange` / `onBarCreate` — not bars drawn by hand or a DataTable of start and end dates. Statuses moved by hand: `Kanban`.
+- Who is busy when, a plan with dates: `Gantt` with `onBarChange` / `onBarCreate` — not bars drawn by hand or a DataTable of start and end dates. Statuses moved by hand: `Kanban` — `plain` (default, a header plate) or `line` (a header over a line) for a board that is the page's main region, `variant="well"` only when columns must read as bounded queues (WIP limits, sparse columns); never a Card or a filled box around a column.
 - Open a board card with `Kanban.Root onItemClick` (click, Enter, Space, never after a drag) or `getItemHref`; a Gantt row with `onRowClick` / `getRowHref` (the DataTable contract), a bar with `onSelect`; more facts in a bar tooltip with `renderBarTooltip` (it adds lines under the dates). A legend of hues is a row of `Badge.Root color` + `Badge.Dot` in the host's `toolbar`, the category also in text. Hour slots (bookings, appointments) are not Gantt — its unit is a calendar day.
 
 ## Chat
@@ -113,7 +119,7 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - «печатает…» on the other side: `Composer onActivityChange` (`typing` / `voice` / `video` / `null`, on a change only) → your socket; on the receiving side `<Chat.Root typing={activity === "typing"}>` (the header's status and the list's typing bubble together). Never send it from `onValueChange`.
 - Appearance: messages that are new at the end enter by themselves — mine and theirs float up a little from below and fade in; the first render, history loaded above and rows scrolled into view never animate. Do not add your own enter animation or `scrollTop = scrollHeight`.
 - `Chat.Messages` scrolls to my message, stays at the end for theirs while the reader is there, and otherwise shows the «N новых» button; `onNewMessage(value, { direction })` is for a sound or a counter, `onRead(values)` for read receipts (only what was really seen). The first unread is `unread={key}`; older history is `hasOlder` + `onLoadOlder`.
-- Jump to a message: `Message.Reply target={id}`, a press on `Chat.Pinned`, or `Chat.Root current={id}` (the chat scrolls to it and the other messages blink back around it); search: `Chat.SearchButton` + `Chat.Search` mark, count and step through the matches in texts and transcripts, keeping the others stepped back. Never an outline or a wash of your own on the target or on selected messages. Never `scrollIntoView` or your own transforms on rows.
+- Jump to a message: `Message.Reply target={id}`, a press on `Chat.Pinned`, or `Chat.Root current={id}` (the chat scrolls to it and the message blinks); search: `Chat.SearchButton` + `Chat.Search` mark, count and step through the matches in texts and transcripts, keeping the others stepped back. Never an outline or a wash of your own on the target or on selected messages. Never `scrollIntoView` or your own transforms on rows.
 - A long history (thousands of messages): nothing to switch on — `Chat.Messages` renders only the rows around the view and keeps the reader's place. With children, every top-level child is one row (a `Message.Root`, or a fragment / your own row component keyed by the message `value`); give pictures their `width` / `height` so a row's size is final before load; jumps, search, selection and the keyboard still reach every message. Not a hand-rolled window, `content-visibility` on rows or a measured bubble.
 - A message's layout is CSS: the bubble fits its content and the time sits at the end of the last line (or of the reactions row). Every size change of a message (reactions, a transcript, an edit, an upload) plays as one built-in stroke, width and height together; a reaction grows the message upward with the time still, the rows above gliding as one block. Never size, measure or animate a bubble yourself; an own content part declares itself with the kit's part contract instead of a wrapper.
 - One sound at a time is built in: a voice message, a video message and a chat video pause each other; `playing` / `onPlayingChange` on `VoicePlayer` or `VideoNote` when the app needs to know. A round video never plays or loops before a press. A recorded voice message without levels gets them from `getWaveform(blob)` once, stored with the message.
@@ -183,10 +189,23 @@ Full rules: [responsive.md](responsive.md).
 
 ## Spacing and values
 
-- Gaps are `gap` on the parent with `--prime-space-N` (N × 4px): 8 in a row of buttons, 20 field → field, 32 group → group; `PageContent.Body` already spaces blocks 40 — not margins, not outer padding.
+- Gaps are `gap` on the parent with `--prime-space-N` (N × 4px): 8 in a row of buttons, 16 tile → tile, 20 field → field, 32 group → group; `PageContent` already spaces blocks 24 and sections 40 — not margins, not outer padding.
 - Tokens only: `var(--prime-space-4)`, `var(--prime-color-text-secondary)`, `var(--prime-radius-m)` — never raw `px` / `rem` / hex, never `--prime-ref-*`, never inline `style`.
 - Text through `Typography` roles (`title-m`, `title-s`, `body-m`, `caption`) and `tone="secondary" | "muted"` — not `font-size` or `color` in CSS.
 
+## UX — what goes on the screen
+
+- Five lines of brief before the JSX: who and what for, the data and its shape, the main action, the states, the narrow screen ([ux.md](ux.md)) — not a layout picked by habit.
+- The shape of the data picks the layout: one record → a form or a `DescriptionList`; records a person edits → `FieldList`; records a person reads → `DataTable` ([the table](ux.md#2-the-shape-of-the-data-decides-the-layout)).
+- Every label carries something new: once per column, never numbered, never repeating its heading; no hint that explains what the layout shows (a lock already says «закреплено»).
+- Buttons say the verb and the object («Выставить счёт»), errors say how to fix it («Формат: +7 912 404-18-20»), empty states offer the next step — not «ОК», «Ошибка», «Нет данных».
+- Money, numbers and dates through `Intl` (`ru-RU`); «ёлочки», `…`, a non-breaking space before a unit — not `toFixed` and string glue.
+- Friction matches the cost: a reversible action at once with «Отменить» in a `Notification`; `ConfirmDialog` only for irreversible or weighty ones, naming the thing and the loss — not «Вы уверены?» on every delete.
+- A disabled control says why when the reason is not on screen; an action without permission is hidden.
+- Tabs, filters, search, page and the open record live in the URL.
+- Changing a screen that exists: audit it against [ux.md](ux.md), [checklist.md](checklist.md) and [anti-slop.md](anti-slop.md) first, fix the shape, then make the change.
+- Before handing over, look at it in a browser: both themes, 1280 and 375 px, every text read aloud.
+
 ## Anti-slop
 
 The whole list, bad → good: [anti-slop.md](anti-slop.md). Before handing over: [checklist.md](checklist.md).

package/dist/skill/checklist.md

@@ -8,10 +8,28 @@ Answer every item yes or no. Any «no» is fixed before handing over.
 - [ ] One `PageContent.Header` with title, one-line description and actions; blocks in `PageContent.Body`.
 - [ ] Cards only for standalone blocks; no card around a table, a single field or the whole page.
 
+## UX ([ux.md](ux.md))
+- [ ] I wrote the brief first: who and what for, the data and its shape, the main action, the states, the narrow screen.
+- [ ] Every entity is laid out by its shape: one record is one row or one block, never split over lines;
+      records a person edits are a `FieldList`, records a person reads a `DataTable`.
+- [ ] Labels on a form of rows ≤ columns + the list label: no label repeated per row, none numbered
+      («Пункт 1»), none repeating its heading; a unit in one place (the field's affix).
+- [ ] No text that explains the layout; every hint says what the person cannot see.
+- [ ] Buttons say the verb and the object; errors say how to fix it; empty states offer the next step.
+- [ ] Money, numbers and dates through `Intl` with `ru-RU`; «ёлочки», `…`, a non-breaking space before units.
+- [ ] Friction matches the cost: reversible → do it and offer «Отменить»; irreversible → `ConfirmDialog`
+      naming the thing and the loss; bulk → the count.
+- [ ] A disabled control says why when the reason is off screen; an action without permission is hidden.
+- [ ] Defaults prefill what the system knows; each field has the control and `inputMode` its data needs;
+      rare settings sit behind a disclosure.
+- [ ] Tabs, filters, search, page and the open record are in the URL.
+- [ ] I looked at the screen in a browser: both themes, 1280 and 375 px, the longest real values, an
+      empty list, an error on every field.
+
 ## Grid and spacing
 - [ ] Every spacing, size and gap in my CSS is a `--prime-space-*` (or another `--prime-*`) token on the 4px grid.
 - [ ] Spacing is `gap` on the parent; no margins on children; no outer padding duplicating `AppShell.Main` / `PageContent.Body`.
-- [ ] Proximity holds: field→field 20, inline controls 8, group→group 32, section→section 40.
+- [ ] Proximity holds: inline controls 8, tile→tile 16 (one `PageContent.Grid`), field→field 20, block→block 24, group→group 32, section→section 40 (`PageContent.Section`).
 - [ ] Inside a group things are visibly closer than between groups.
 
 ## Sizes and alignment

package/dist/skill/choosing.md

@@ -8,7 +8,7 @@ confuse. Links: [components.md](components.md). Whole screens: [composition.md](
 | The user needs to… | Category |
 |---|---|
 | trigger an action (save, delete, go on) | Actions — Button, ButtonGroup, LinkButton |
-| type a value (text, number, code, file, photos), group the fields of a form | Inputs — Input, Textarea, DigitInput, FileUpload, Label, Hint, Fieldset |
+| type a value (text, number, code, file, photos), group the fields of a form, edit a list of records of one shape | Inputs — Input, Textarea, DigitInput, FileUpload, Label, Hint, Fieldset, FieldList |
 | pick from options, toggle, set a range, filter, a date or a color | Selection — Checkbox, Radio, Switch, SegmentedControl, Slider, Select, NativeSelect, TagSelect, SmartFilter, Datepicker, ColorField, ColorPicker, ColorSwatches |
 | see data: status labels, people, objects, numbers and their trend, properties of a record, rows, a board, a schedule, events, code, disclosed sections | Data display — Badge, Avatar, Thumbnail, Kbd, Card, DescriptionList, DataTable, Kanban, Gantt, Timeline, CodeBlock, Accordion, Sparkline, ChartFrame |
 | hold a conversation: pick a dialog, read and send chat messages of every kind | Messages — Chat, ChatList, Message, Gallery, VoicePlayer, VideoNote, Composer |
@@ -33,7 +33,8 @@ Input with `Input.InlineAffix`. Search and filters above a list or table → Sma
 (`fields={[]}`); a lone search
 field outside a list (a picker, a settings section, a panel) → Input with `Input.Icon` + `type="search"`
 and `aria-label`. Several fields of a form under one heading → Fieldset (`label`, `disabled` while the
-form saves).
+form saves). Several records of the same fields that a person adds, edits and removes (invoice lines,
+contacts, specs, prices by period) → FieldList: one row per record, the headings once.
 
 **Selection.**
 
@@ -62,12 +63,15 @@ numbers/content → Card (pick the template; a whole tile that opens its details
 with a link). Read-only properties of one record («label — value») → DescriptionList, never a
 hand-made grid of text pairs. Rows with columns, sorting, selection → DataTable.
 Items that flow through statuses and are moved by hand → Kanban (a single list to reorder, or items
-dropped onto folders or assignees → Dnd directly).
+dropped onto folders or assignees → Dnd directly). Its look: `plain` (default; `line` for a quieter header over a line) when the board is
+the page's main region or sits in a Card / Drawer — headers and cards stand on the host, one level of
+nesting; `variant="well"` when columns must read as bounded queues (WIP limits, many sparse or empty
+columns, a dense board of narrow columns). Never your own box around a column.
 Records with a start and an end compared across time — who is busy when, a project plan with
 phases and milestones → Gantt (never a DataTable of dates or hand-drawn bars); moved and resized by
 hand through `onBarChange`.
 Chronological events → Timeline; a conversation between people (support, a team chat) → Message —
-never a Timeline or a list of Cards styled as bubbles. Code → CodeBlock. A number with its trend over days or weeks (revenue, orders, sign-ups) → Sparkline: the latest value, its change and a line you can scrub; values with a sign by period → Sparkline `variant="bars"`; a chart with axes or several series → ChartFrame around a chart library or your own SVG (the panel, legend, tooltip, states and the screen-reader table come from the kit, the colors from `series` / `chartColors` — never status tones); values to read, sort or compare row by row → DataTable, not a chart.
+never a Timeline or a list of Cards styled as bubbles. Code → CodeBlock. A number with its trend over days or weeks (revenue, orders, sign-ups) → Sparkline: the latest value, its change and a line you can scrub; values with a sign by period → Sparkline `variant="bars"`; against a plan → `reference`; missing days → `value: null`; a chart with axes or several series → ChartFrame around a chart library or your own SVG (the panel, legend, tooltip, states and the screen-reader table come from the kit, the colors from `series` / `chartColors` — never status tones); values to read, sort or compare row by row → DataTable, not a chart.
 
 **Messages.** A whole conversation → `Chat`: `Chat.Root` with `Chat.Header` (avatar, `Chat.Title`,
 `Chat.Description`, `Chat.Actions` with `Chat.SearchButton`), `Chat.Search`, `Chat.Pinned`,
@@ -138,6 +142,7 @@ collapsible`; a section with sub-pages → `Sidebar.Sub`; the signed-in user →
 | Pair | Rule |
 |---|---|
 | List / Sidebar / Tabs / Card list / DataTable | List: the records of a list + detail screen (dialogs, tickets, mail), one open at a time (`current`), each row a button or a link with a text line, a preview, meta and a count. Sidebar: the sections of the **app**. Tabs: panels of **one screen**. `Card.List` (`variant="list"`): static facts in a card, nothing opens. DataTable: many records compared by columns, sorted, filtered, selected in bulk. |
+| FieldList / DataTable / Fieldset / TagSelect | FieldList: records of one shape a person **edits** in a form, a row of fields each, added and removed by hand, up to four short fields per row. DataTable: records a person **reads**, sorts, filters and selects; edits open a Drawer. Fieldset: **one** record's fields under a heading. TagSelect: values **picked** from options, shown as tags. One value in several units is none of them — fields in one row under one heading. |
 | Tabs / SegmentedControl | Tabs switch **panels of content** (navigation inside a screen). SegmentedControl switches a **value or mode** of the same content (period, view mode, filter). |
 | Modal / Drawer / Sheet / Popover / Tooltip | Modal: blocking decision or a short form (≤ 4 fields) that needs full attention. Drawer: long form, filters, record details beside the page, while keeping page context. Sheet: a short task that ends by itself — a pick, an action, a short note — raised from the bottom edge. Popover: small non-modal panel anchored to a control (quick edit, explanation with a link). Tooltip: a few words naming or explaining a control, no interactive content. |
 | Select / NativeSelect | Select: the kit's floating list — icons, descriptions, groups, search, `multiple`, `clearable`. NativeSelect: a plain text list where the OS picker is better (phones) or the value must post with a form by `name`. |
@@ -151,7 +156,7 @@ collapsible`; a section with sub-pages → `Sidebar.Sub`; the signed-in user →
 | Gallery / MediaViewer / Thumbnail | Thumbnail: one picture or video of an object in a list, card or picker (selectable with `checked`). Gallery: an album of 1–10 photos and videos laid out by their ratios; it opens MediaViewer itself. MediaViewer: the full-screen viewer on its own, opened from your own thumbnails or a button (`getOrigin` for the zoom out of the tile). A grid of many images to browse → a CSS grid of Thumbnails, not a Gallery. |
 | Sparkline / ChartFrame | Sparkline: one series as a headline number with its change and a small line or bars you can scrub (`variant="bars"` for signed values). ChartFrame: a panel around a real chart (axes, several series, legend, tooltip, states) drawn by a library or your SVG. Rows to compare → DataTable. |
 | VoicePlayer / VideoNote | The same player props (`src`, `duration`, `playing`, transcript, `transfer`). VoicePlayer: audio, a waveform seek slider and a playback rate. VideoNote: a round face-to-camera video with a `poster`; alone in `Message.Root` it is the message. A video with controls → `Thumbnail.Video` / `Message.Media`. |
-| Card / plain section | Card for a bounded block of related content that stands out (metric, settings panel, side facts). A page section that is the only thing in its region needs no card: a `title-m` heading and the content. Never wrap a single field, a DataTable or a whole page in a Card. |
+| Card / plain section / Grid | Card for a bounded block of related content that stands out (metric, settings panel, side facts). A page section that is the only thing in its region needs no card: `PageContent.Section label` and the content. Several tiles of one screen → one `PageContent.Grid` with a `PageContent.Cell span` each; a grid inside one block (thumbnails, fields) is the block's own CSS. Never wrap a single field, a DataTable or a whole page in a Card. |
 | EmptyPage / empty DataTable | Empty table (no rows yet or nothing matches the filter): the DataTable `empty` prop — headers and toolbar stay. Whole page or region with no data at all (first run): EmptyPage with one action. |
 | Accordion / Tabs | Accordion when the user may need several sections open or reads them in order (FAQ, settings groups). Tabs when sections are alternatives viewed one at a time. |
 | Divider / gap | Divider inside a block between rows or a form and its footer. Between blocks and groups use air (`gap`), not lines. |

package/dist/skill/components.md

@@ -30,6 +30,7 @@ Type a value, and the field anatomy: label, hint, error.
 | Label | Field label (native `<label>`) with required and optional markers. | [COMPONENT.md](reference/components/label/COMPONENT.md) · [examples](reference/components/label/examples/) |
 | Hint | Help text or a validation error under a field. | [COMPONENT.md](reference/components/hint/COMPONENT.md) · [examples](reference/components/hint/examples/) |
 | Fieldset | A frameless group of form fields: a `title-s` legend, the form rhythm and one `disabled` for all of them. | [COMPONENT.md](reference/components/fieldset/COMPONENT.md) · [examples](reference/components/fieldset/examples/) |
+| FieldList | An editable list of records of one shape: one row of fields per record, the column headings once, add, remove, reorder, pinned rows. | [COMPONENT.md](reference/components/field-list/COMPONENT.md) · [examples](reference/components/field-list/examples/) |
 
 ## Selection (`selection`)
 
@@ -60,13 +61,13 @@ Show data: labels, people, objects, cards, tables, boards, feeds, code, disclose
 | Badge | The kit's one chip: a static label for a status, category or count, a removable value or applied filter, and a pressable toggle with a hover action — in a palette color. | [COMPONENT.md](reference/components/badge/COMPONENT.md) · [examples](reference/components/badge/examples/) |
 | Avatar | A round photo of a person or organization with an initials or icon fallback, a presence dot and overlapping groups. | [COMPONENT.md](reference/components/avatar/COMPONENT.md) · [examples](reference/components/avatar/examples/) |
 | Thumbnail | A preview of an object — product, vehicle, file, cover — at a fixed aspect ratio (`ratio`), an image or a video (`Thumbnail.Video`, first frame and length), a colored icon fallback, and a selectable tile (`checked`). | [COMPONENT.md](reference/components/thumbnail/COMPONENT.md) · [examples](reference/components/thumbnail/examples/) |
-| Sparkline | A small line or bar chart with its headline — the value at rest, its change against the point before and its date — where any point can be scrubbed; `layout="compact"` — just the plot, for a table cell. | [COMPONENT.md](reference/components/sparkline/COMPONENT.md) · [examples](reference/components/sparkline/examples/) |
+| Sparkline | A small chart — a smooth line over a fading area, a bare line or bars — with its headline: the value at rest, its change and its date; any point can be scrubbed; a tooltip beside the scrubbed point; `layout="compact"` — just the plot, for a table cell. | [COMPONENT.md](reference/components/sparkline/COMPONENT.md) · [examples](reference/components/sparkline/examples/) |
 | ChartFrame | A dashboard panel around any chart (Recharts, ECharts, visx, Chart.js or a hand-drawn SVG): title, headline value, a measured plot area, a series legend that hides series (`hiddenSeries`), loading / empty / error states (`state`, `onRetry`) that cross-fade, a tooltip body and a data table for screen readers. | [COMPONENT.md](reference/components/chart-frame/COMPONENT.md) · [examples](reference/components/chart-frame/examples/) |
 | Kbd | A key cap for a keyboard key or a shortcut, rendered as a native `<kbd>`. | [COMPONENT.md](reference/components/kbd/COMPONENT.md) · [examples](reference/components/kbd/examples/) |
 | Card | A filled surface block with structural templates for metrics, charts, lists, calls to action and covers. | [COMPONENT.md](reference/components/card/COMPONENT.md) · [examples](reference/components/card/examples/) |
 | DescriptionList | Read-only properties of a record: «label — value» pairs on a `<dl>` that stack by themselves where the room is narrow, with a muted dash for an empty value. | [COMPONENT.md](reference/components/description-list/COMPONENT.md) · [examples](reference/components/description-list/examples/) |
 | DataTable | A data table with sorting, pages or infinite scroll (on the client or by the server, `source="server"`), row selection, row groups, rows reordered by drag (`onReorder`), rows that open a record (link or in place), a column chooser (`DataTable.ColumnsMenu`), nested rows and loading / empty / error states. | [COMPONENT.md](reference/components/data-table/COMPONENT.md) · [examples](reference/components/data-table/examples/) |
-| Kanban | A board of status columns: cards move by drag, touch hold and Alt + arrows, columns reorder by a grip in their header (`reorderableColumns`, `columnOrder`), with column descriptions and colors, WIP limits, loading and empty columns. | [COMPONENT.md](reference/components/kanban/COMPONENT.md) · [examples](reference/components/kanban/examples/) |
+| Kanban | A board of status columns — without wells — cards on the page under a header plate (`plain`, default) or a header line (`line`) — or filled wells (`well`): cards move by drag, touch hold and Alt + arrows, columns reorder by a grip in their header (`reorderableColumns`, `columnOrder`), with column descriptions and colors, WIP limits, loading and empty columns. | [COMPONENT.md](reference/components/kanban/COMPONENT.md) · [examples](reference/components/kanban/examples/) |
 | Gantt | A resource or project schedule: rows with bars on a day / week / month axis, lanes for overlaps, milestones, a today line, a pinned first column, moves and resizes by pointer and keyboard through an async `onBarChange`, new bars drawn on empty space (`onBarCreate`), virtualized rows and days for thousands of rows. | [COMPONENT.md](reference/components/gantt/COMPONENT.md) · [examples](reference/components/gantt/examples/) |
 | Timeline | An event feed: dots on a thin line, event title and date, an optional amount on the right, grouped under labels. | [COMPONENT.md](reference/components/timeline/COMPONENT.md) · [examples](reference/components/timeline/examples/) |
 | CodeBlock | A static TypeScript / TSX snippet with syntax highlighting, on a filled panel or bare inside a host. | [COMPONENT.md](reference/components/code-block/COMPONENT.md) · [examples](reference/components/code-block/examples/) |
@@ -140,7 +141,7 @@ The frame and structure of a screen: app shell, app header, page column, page pa
 |---|---|---|
 | AppShell | The app frame: a content panel that is the page itself and a navigation rail one layer above it. | [COMPONENT.md](reference/layout/app-shell/COMPONENT.md) · [examples](reference/layout/app-shell/examples/) |
 | AppHeader | The bar at the top of the content panel: where you are, ⌘K search, a few actions, the phone menu button; as high as the Sidebar brand row. May carry the page title (`AppHeader.Title as="h1"`) and the page tools (`AppHeader.Tools`). | [COMPONENT.md](reference/layout/app-header/COMPONENT.md) · [examples](reference/layout/app-header/examples/) |
-| PageContent | Page structure inside the main column: title, description, page actions and content sections; a page as high as the panel (`fill`) and list + detail (`PageContent.Split`). | [COMPONENT.md](reference/components/page-content/COMPONENT.md) · [examples](reference/components/page-content/examples/) |
+| PageContent | Page structure inside the main column: title, page actions, titled sections (`PageContent.Section`) and the tile grid (`PageContent.Grid`); a page as high as the panel (`fill`) and list + detail (`PageContent.Split`). | [COMPONENT.md](reference/components/page-content/COMPONENT.md) · [examples](reference/components/page-content/examples/) |
 | PageToolbar | The panel at the top of a page — search and filter, sections, view options and the primary action — laid out from its own width: one row when wide, stacked rows when narrow, the active filters right under the search. | [COMPONENT.md](reference/components/page-toolbar/COMPONENT.md) · [examples](reference/components/page-toolbar/examples/) |
 | Divider | A hairline separator inside one surface, horizontal or vertical, with or without a label. | [COMPONENT.md](reference/components/divider/COMPONENT.md) · [examples](reference/components/divider/examples/) |
 | ScrollContainer | The kit's one scroll region: a thin scrollbar or none (`scrollbar="hidden"`), soft edges where content is hidden (`edges` fade / shadow), `snap`, `lock`, correct shrinking inside flex and grid parents; pinned to the end for chats (`anchor="end"`), edge events for loading more (`onReachStart` / `onReachEnd`). | [COMPONENT.md](reference/components/scroll-container/COMPONENT.md) · [examples](reference/components/scroll-container/examples/) |