prime-ui-kit 0.18.0 → 0.20.0

package/dist/skill/reference/components/drawer/examples/loading.tsx

@@ -0,0 +1,58 @@
+/** A record card that opens before its data arrives: the title comes from the list row, the line under it and the body hold their place in skeletons, then the data fades in — `Drawer.Description`, `loading`. */
+import { Button, Crossfade, DescriptionList, Drawer, Skeleton } from "prime-ui-kit";
+import * as React from "react";
+
+const BIKE = {
+  title: "Велосипед №214",
+  summary: "Тур 2 · на линии с 6 октября",
+  facts: [
+    ["Модель", "Tour 2, рама M"],
+    ["Пробег", "1 840 км"],
+    ["Последнее ТО", "28 сентября"],
+    ["Арендатор", "Илья Морозов"],
+  ],
+};
+
+export default function DrawerLoadingExample() {
+  const [loading, setLoading] = React.useState(true);
+
+  const openChange = (open: boolean) => {
+    if (!open) return;
+    setLoading(true);
+    window.setTimeout(() => setLoading(false), 1200);
+  };
+
+  return (
+    <Drawer.Root onOpenChange={openChange}>
+      <Drawer.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Открыть велосипед
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Content>
+        <Drawer.Header>
+          <Drawer.Title>{BIKE.title}</Drawer.Title>
+          <Drawer.Description loading={loading}>{BIKE.summary}</Drawer.Description>
+        </Drawer.Header>
+        <Drawer.Body>
+          <Crossfade state={loading ? "loading" : "data"} aria-busy={loading}>
+            <DescriptionList.Root>
+              {BIKE.facts.map(([term, value]) => (
+                <DescriptionList.Item key={term} label={term}>
+                  {loading ? <Skeleton /> : value}
+                </DescriptionList.Item>
+              ))}
+            </DescriptionList.Root>
+          </Crossfade>
+        </Drawer.Body>
+        <Drawer.Footer>
+          <Drawer.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Закрыть
+            </Button.Root>
+          </Drawer.Close>
+        </Drawer.Footer>
+      </Drawer.Content>
+    </Drawer.Root>
+  );
+}

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

@@ -3,12 +3,13 @@
 **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.
+> An editable list of records of one shape — invoice lines, specs, contacts, prices by period: one row per record on one grid, the column headings once above the rows, the row's actions at its end 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`.
+- A list of short texts in the order a person sets (selling points, checklist items): one column, `reorderable`; each row ends with its remove button and its handle.
+- Dense rows (three or more columns), a touch-heavy screen, or rows that need more than remove and move → `rowActions="menu"`: one «⋯» per row.
 - 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
@@ -26,36 +27,39 @@ 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
-├─ totals row                `renderTotals`: a group «Итого», a total per column on the same tracks
+├─ sheet                     the rows on one grid (`variant="surface"`: a fill one step up the ladder)
+│  ├─ heading row            the column headings, once (aria-hidden; each field carries its heading as its label)
+│  ├─ <ol>                   the rows (Dnd.Sortable with `reorderable` and the buttons)
+│  │  └─ <li> row            [a cell per column] [end: × | ⋯] [grip: handle | lock]
+│  │     └─ cell             one kit field without `label`, named by its column heading
+│  └─ totals row             `renderTotals`: a group «Итого», a total per column on the same tracks
 └─ 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.
+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. Every row, a one-column row too, ends with the same slots: the remove «×» (or the «⋯» menu) and, with `reorderable` buttons, the grip after it — never a segment inside a field, where a «×» would read as «clear the text».
 
 ## 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 in a container under 30rem.
+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>`) on one grid, the row's actions at its end, add under the rows; rows stack in a container under 30rem.
 
 | 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` \| `xs` \| `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()`. |
-| `renderTotals` | `(items: readonly T[]) => ReactNode` | — | The totals row under the rows: one node per column (a fragment), `null` where a column has none. The first cell without a total reads `labels.totals`, the row's group name. |
+| `renderTotals` | `(items: readonly T[]) => ReactNode` | — | The totals row under the rows: one node per column (a fragment), `null` where none; each aligned as its column's field text. The first cell without a total reads `labels.totals`. |
 | `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 \| Promise<void>` | — | The new list after an edit (`row.update`), an add, a remove or a move. Return the save's promise: the new list shows while it is pending, the owner's again on a reject (say why with `error`). |
 | `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 + ↑ / ↓. |
+| `getLabel` | `(item: T) => string` | — | The row's own text (its title field) for the remove button, the handle, the menu button and move announcements; else the row number. |
+| `getLocked` | `(item: T) => boolean` | — | Pinned rows: the remove stays in its place, off, and says why (`labels.lockedReason`); with `reorderable` a lock takes the handle's place and the row holds it. In the menu every item is off. |
+| `reorderable` | `boolean` | `false` | Rows move: with `rowActions="buttons"` by a handle that ends the row, after the remove button (drag, a touch hold, Alt + ↑ / ↓); with `"menu"` by its items «Выше» and «Ниже» and Alt + ↑ / ↓ on the menu button. |
+| `rowActions` | `"buttons" \| "menu"` | `"buttons"` | How a row offers its actions: `buttons` — a remove button «×» and, with `reorderable`, the handle after it; `menu` — one «⋯» button whose menu moves the row up or down and removes it. |
+| `variant` | `"plain" \| "surface"` | `"plain"` | Look of the list: `plain` — the rows on the host surface; `surface` — the rows on a fill of their own, one step up the surface ladder, with side padding. |
 | `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. |
@@ -63,18 +67,30 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 | `hint` | `ReactNode` | — | Help text under the list; hidden while `error` shows. |
 | `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `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. |
+| `disabled` | `boolean` | `false` | Disables every field, handle, button and menu button; a disabled `Fieldset` around it sets it too. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"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
 
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `plain` | the rows on the host surface, no side padding, faint lines between rows | the list is the content of its card or section | yes |
+| `surface` | the rows on a fill one step up the surface ladder, radius `--prime-radius-l`, 12 of side padding and 12 of air under the last row | the list stands among other fields of a form or card and must read as one block | |
+
+### rowActions
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `buttons` | a ghost «×» at the row's end and, with `reorderable`, the grip after it; a pinned row: «×» off, then the lock | short lists edited often, a desktop screen, moving rows is a main task | yes |
+| `menu` | one ghost «⋯» per row; its Dropdown holds «Выше», «Ниже» (with `reorderable`), a separator and «Удалить» (danger) | dense rows (three or more columns), a touch-heavy screen, a row that needs more than remove and move | |
+
 ### 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 | |
+| `compact` | as wide as the widest of its controls, heading and total — the gap after it is the column gap like every other | an icon-only `Select`, a `ColorPresets` swatch, a checkbox | |
 | `xs` | 96 px | a number of a few digits: a share, a percent, a count | |
 | `s` | 144 px | a quantity, a code, a number of days | |
 | `m` | 192 px | an amount with its unit, a date, a phone | |
@@ -82,38 +98,41 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 ### 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 | — |
+| `reorderable` | buttons: a grip at the very end of every row, after the remove button, Alt + ↑ / ↓ on it; menu: «Выше» and «Ниже» in the menu, Alt + ↑ / ↓ on «⋯» | the order of the records matters (a pricing page, a checklist, payment stages) | `false` |
+| `getLocked` | the remove button in its place, off, with a tooltip saying why (`labels.lockedReason`); with `reorderable` a lock where the grip is and the row holds its place; in the menu every item off, «Удалить» says why | 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` · — |
-| `renderTotals` | a row of totals under the rows over a faint line, each on its column; «Итого» in the first cell without a total | the rows add up (shares, amounts, hours) | — |
+| `renderTotals` | a row of totals under the rows over a faint line, each on its column, aligned as the column's field text; «Итого» in the first cell without a total | the rows add up (shares, amounts, hours) | — |
 
 **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.
+- Pointless: `getLocked` on every row with `createItem` — nothing can be removed or moved; `variant="surface"` on a list that is alone in its card — a fill inside a fill.
 - 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 min | `value.length <= min` | remove buttons (or «Удалить» items) `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 |
+| pinned row | `getLocked(item)` | `data-locked="true"` on the `<li>`; the remove button stays in its slot, `disabled` behind a focusable Tooltip host, its tooltip `labels.lockedReason`; with `reorderable` Dnd's lock in the grip box; in the menu every item `disabled`, «Удалить» described by `labels.lockedReason` |
+| hover | the pointer over a row of a `surface` list (`(hover: hover)` only; a `plain` row has no fill of its own) | the whole row takes the field fill (`--prime-color-fill-muted`) and its fields the surface fill (`--prime-color-layer-current`) |
 | 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 30rem | heading row hidden, each row's fields in one column with their labels shown; each total on its own line after its column name |
+| disabled | `disabled` (or a disabled Fieldset) | `data-disabled="true"` on the frame; fields, handles, buttons and menu buttons disabled through the kit's disabled context |
+| stacked | container narrower than 30rem | heading row hidden; the compact columns, the first field and the actions on the first line, every other field on a line of its own with its label shown; `data-stack` on the body keeps the first field at least 160 wide: `actions` when it is too narrow beside the actions (they end the second line, after the next field), `main` when it is too narrow even without them (it takes the full width under the compact columns and the actions); each total on its own line after its column name |
 | saving | a promise from `onValueChange` | the rows show the new list, `aria-busy="true"` on the `<ol>`; a reject brings the owner's list back |
-| rows come and go | the add button, a remove button, a new `value` | a row the data adds rises in once (`enterMotion`), a removed one closes up in place and the rows below glide up (`listPresence`); the heading row rises in with the first row and closes up with the last (`partPresence`); the first render stays still |
+| rows come and go | the add button, a remove, a menu move, a new `value` | a row the data adds rises in once (`enterMotion`), a removed one closes up in place and the rows below glide up (`listPresence`); a row the menu moves glides to its place (`useFlipList`); the heading row rises in with the first row and closes up with the last (`partPresence`); the first render stays still |
 
 ## 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 is one `xs` control wide (the grip or the lock), 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 totals row stands 12 under the last row over a faint line, 12 more above its totals; a total's text starts where its column's field text does.
-- The add button lines up with the first column of fields, 12 under the last row.
-- Under 30rem of its own width (a container query): rows stack, fields 16 apart inside a row, rows 24 apart.
+- One grid for the list: every row, the heading row and the totals row share one track list `[columns] [end] [grip]`, so the columns line up like a table's; the end fits the row's «×» or «⋯» of the tier, the grip (with `reorderable` buttons) is one `xs` control wide (the handle or the lock) and ends the row on the inline-end side (on the left in RTL). Every row fills the same slots: a pinned row shows its remove off, never a hole.
+- Rows stand edge to edge, 8 of padding above and below their fields; a faint line between two rows (`hairline`), inset by the side padding, none above the first row. Columns 12 apart (`--prime-space-3`).
+- `plain`: side padding 0. `surface`: the sheet's fill (`--prime-color-layer-current` at its `data-depth`), radius `--prime-radius-l`, 12 of side padding on every row and 12 above the headings and under the last row.
+- A `compact` column is measured: its track is the widest of its controls, its heading and its total, so the gaps between columns are all 12.
+- The remove button, the menu button, the handle and the lock stand on the middle of the first line of fields, so a field's error under it grows the row downwards only.
+- The totals row stands under the last row over a faint line; a total's text sits where its column's field text does: at the start, or at the end for a field that ends its number there (an `Input` with `inputMode="decimal"` and an end `Input.InlineAffix`). Stacked, every total ends its line.
+- The add button lines up with the sheet's start, 12 under it.
+- Under 30rem of its own width (a container query): rows stack — the first line holds the compact columns, the first field and the actions; the other fields take the full width under it, 16 apart; rows 12 of padding above and below. The first field keeps at least 160 (measured, so a name such as «Вход через SSO» stays whole at 320 and 360): too narrow beside the actions, they end the second line after the next field; too narrow even without them (a narrow card), the field takes the full width under the compact columns and the actions.
 
 ## Accessibility
 
@@ -122,9 +141,9 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 
 | 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). |
+| `Tab` | Moves through the fields of a row, then to its remove button and its handle (or its menu button) and on; a pinned row's remove takes focus to show why it is off. |
+| `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; on a menu button opens the row's menu. |
+| `Alt + ↑` · `Alt + ↓` | With `reorderable`, moves the row up or down (from its handle, or from its menu button with `rowActions="menu"`); focus stays on it. |
 
 ### ARIA
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -133,20 +152,26 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 - 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.
 - The `<ol>` is described by the list's `hint` and `error` (`aria-describedby`), which speak for every row.
 - In a narrow container the heading row goes and each field's label shows above it.
+- With `rowActions="menu"` the row's «⋯» button opens a `role="menu"` (Dropdown) named «Действия: {row}»; it lists Alt + ↑ / ↓ in `aria-keyshortcuts`, and a move says the row's new place in a polite live region.
 - The totals row (`renderTotals`) is a `group` named by `labels.totals`; each total is read after its column heading.
-- 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 Dnd's lock (an image named «Закреплена»).
+- The remove button is «Удалить: {row}», the handle «Переместить: {row}»: the row's name from `getLabel`, else its number.
+- A pinned row keeps its remove button: `aria-disabled`, described by `labels.lockedReason` (a tooltip on hover and focus); with `reorderable` Dnd's lock stands in place of the handle. In the menu its items are `disabled` and the remove item is described by `labels.lockedReason`.
 
 ### 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. |
+| `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. |
+| `actions` | `"Действия: {row}"` | `aria-label` of a row's menu button (`rowActions="menu"`); `{row}` is the row's name. |
+| `moveUp` | `"Выше"` | Menu item that moves the row one place up. |
+| `moveDown` | `"Ниже"` | Menu item that moves the row one place down. |
+| `removeItem` | `"Удалить"` | Menu item that removes the row. |
+| `moved` | `"{row}: позиция {position} из {total}"` | Announced after a move from the menu or its keys; `{row}` is the row's name, `{position}` its new place, `{total}` the row count. |
+| `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`. |
+| `lockedReason` | `"Закреплённую строку нельзя удалить"` | Why a pinned row (`getLocked`) cannot be removed: the tooltip of its remove button, the description of its menu's remove item. |
 | `maxReached` | `"Не больше {max}"` | Text beside the disabled add button once the list holds `max` rows. |
 | `totals` | `"Итого"` | Name of the totals row (`renderTotals`), shown in its first cell when that has no total. |
 
@@ -154,18 +179,20 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 | 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`. |
+| [variants.tsx](examples/variants.tsx) | The two looks of the same list: the rows on the host surface, or on a fill of their own with side padding — `variant`. |
 | [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`. |
+| [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, each row ends with its remove button and then its handle, a point moves by the handle or Alt+arrows — `reorderable`, `getLabel`. |
+| [row-menu.tsx](examples/row-menu.tsx) | Payment stages of a project in dense rows: one more-button per row holds move up, move down and remove, the moves are off at the ends and next to the pinned advance, and Alt+arrows on the button move the row too — `rowActions`, `reorderable`, `getLocked`. |
+| [locked.tsx](examples/locked.tsx) | Specs of a plan on one line each: an icon picker and its color side by side in compact columns, the first three specs are pinned with a lock in the handle's place and a remove button that is off and says why, 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 whose remove button is off and says why, each change is a row with its month and its price, and the unit sits in the field, not in a heading — `getLocked`, `labels`, `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; a `*` after a heading marks a required column — `error`, `required`. |
-| [totals.tsx](examples/totals.tsx) | A deal bonus split between the team: the share takes a narrow column, and the totals row under the lines sums the shares and the amounts — `renderTotals`, `width`. |
+| [totals.tsx](examples/totals.tsx) | A deal bonus split between the team: the share takes a narrow column, and the totals row under the lines sums the shares and the amounts, each ending where its fields end their numbers — `renderTotals`, `width`. |
 | [saving.tsx](examples/saving.tsx) | Removing a recipient is saved on the server: the row leaves at once and comes back with the reason if the server refuses — `onValueChange`, `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`. |
-| [screen.tsx](examples/screen.tsx) | A record editor as a document page, a long form whose title, description and save stand in the content header: a plan's name, its specs and prices in one form; repeating records as FieldList rows with the headings once, a base price pinned above its changes, one value in three currencies in one row — `getLocked`, `compact`. |
+| [narrow.tsx](examples/narrow.tsx) | Specs of a plan in a 320 px column: the headings give way, the icon, its color and the name keep the first line, and the value takes the line under it with the remove button and the handle, each field with its own label — `columns`, `width`. |
+| [screen.tsx](examples/screen.tsx) | A record editor as a document page, a long form whose title, description and save stand in the content header and whose blocks are titled cards one under another: a plan's name, its specs and prices; repeating records as FieldList rows with the headings once, an icon and its color side by side, a base price pinned above its changes, the price list on its own fill among the fields of its card, one value in three currencies in one row — `getLocked`, `compact`, `variant`. |
 
 ## Mistakes
 - A `label` above every field of every row («Иконка», «Параметр», «Значение» four times) → a FieldList: the headings stand once, the fields take them as hidden labels.
@@ -173,11 +200,15 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 - 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.
+- A hint that explains what the lock already shows («Первые три всегда первыми») → no hint; the lock and the remove button's reason say it.
+- A pinned row with an empty place where the others have a remove button → none to fix by hand: FieldList draws it off with `labels.lockedReason`; say the domain reason there («Базовую цену нельзя удалить»).
+- A remove «×» as an `Input.Action` inside a one-field row → none: a «×» in a field reads as «clear the text»; FieldList ends every row with its own remove.
+- A «⋯» menu or a «−» drawn by hand next to the rows → `rowActions`; a Card drawn around the list to set it apart from the form → `variant="surface"`.
+- `rowActions="menu"` on a two-column list a person reorders all day → the buttons: the handle and «×» in sight are one gesture, the menu is three.
 - `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.
 - A total under the list typed by hand in a line of text, or a DataTable of fields to get a totals row → `renderTotals`.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md) (add, remove), [Dnd](../dnd/COMPONENT.md) (`reorderable`: `Dnd.Sortable`, `Dnd.Handle`; the lock of a pinned row), [Label](../label/COMPONENT.md) (headings), the field frame (label, [Hint](../hint/COMPONENT.md) for the hint and error), [VisuallyHidden](../visually-hidden/COMPONENT.md)
+- **Built from:** [Button](../button/COMPONENT.md) (add, remove, the menu button), [Dnd](../dnd/COMPONENT.md) (`reorderable`: `Dnd.Sortable`, `Dnd.Handle`; the lock of a pinned row), [Dropdown](../dropdown/COMPONENT.md) (`rowActions="menu"`), [Label](../label/COMPONENT.md) (headings), [Tooltip](../tooltip/COMPONENT.md) (why a pinned row's remove is off), the field frame (label, [Hint](../hint/COMPONENT.md) for the hint and error), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **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

@@ -1,4 +1,4 @@
-/** 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`. */
+/** A plan price and its changes by month in one table: the base price is the first, pinned row whose remove button is off and says why, each change is a row with its month and its price, and the unit sits in the field, not in a heading — `getLocked`, `labels`, `width`. */
 import { FieldList, type FieldListColumn, Input, Select } from "prime-ui-kit";
 import * as React from "react";
 
@@ -30,6 +30,7 @@ export default function FieldListBaseRowExample() {
       onValueChange={setPeriods}
       getId={(period) => period.id}
       getLocked={(period) => period.base ?? false}
+      labels={{ lockedReason: "Базовую цену нельзя удалить" }}
       createItem={() => ({ id: crypto.randomUUID(), from: "", price: "" })}
       addLabel="Добавить изменение цены"
       renderItem={(period, row) => (

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

@@ -1,4 +1,4 @@
-/** 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`. */
+/** Specs of a plan on one line each: an icon picker and its color side by side in compact columns, the first three specs are pinned with a lock in the handle's place and a remove button that is off and says why, the rest reorder below them — `getLocked`, `width`, `reorderable`. */
 import {
   ColorPresets,
   FieldList,
@@ -21,9 +21,9 @@ type Spec = {
 
 const COLUMNS: FieldListColumn[] = [
   { label: "Иконка", width: "compact" },
+  { label: "Цвет", width: "compact" },
   { label: "Параметр" },
   { label: "Значение" },
-  { label: "Цвет", width: "compact" },
 ];
 
 const ICONS: { name: IconName; label: string }[] = [
@@ -107,6 +107,15 @@ export default function FieldListLockedExample() {
               ))}
             </Select.Content>
           </Select.Root>
+          <ColorPresets.Root
+            value={spec.color}
+            onValueChange={(color) => row.update({ color: color ?? spec.color })}
+          >
+            <ColorPresets.Trigger>
+              <ColorPresets.SwatchButton />
+            </ColorPresets.Trigger>
+            <ColorPresets.Content />
+          </ColorPresets.Root>
           <Input.Root>
             <Input.Wrapper>
               <Input.Field
@@ -123,15 +132,6 @@ export default function FieldListLockedExample() {
               />
             </Input.Wrapper>
           </Input.Root>
-          <ColorPresets.Root
-            value={spec.color}
-            onValueChange={(color) => row.update({ color: color ?? spec.color })}
-          >
-            <ColorPresets.Trigger>
-              <ColorPresets.SwatchButton />
-            </ColorPresets.Trigger>
-            <ColorPresets.Content />
-          </ColorPresets.Root>
         </>
       )}
     />

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

@@ -1,63 +1,138 @@
-/** 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`. */
-import { FieldList, type FieldListColumn, Input } from "prime-ui-kit";
+/** Specs of a plan in a 320 px column: the headings give way, the icon, its color and the name keep the first line, and the value takes the line under it with the remove button and the handle, each field with its own label — `columns`, `width`. */
+import {
+  ColorPresets,
+  FieldList,
+  type FieldListColumn,
+  Icon,
+  type IconName,
+  Input,
+  Select,
+} from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
-type Line = { id: string; service: string; quantity: string; price: string };
+type Spec = {
+  id: string;
+  icon: IconName;
+  name: string;
+  value: string;
+  color: string;
+  pinned?: boolean;
+};
 
 const COLUMNS: FieldListColumn[] = [
-  { label: "Услуга" },
-  { label: "Кол-во", width: "s" },
-  { label: "Цена", width: "m" },
+  { label: "Иконка", width: "compact" },
+  { label: "Цвет", width: "compact" },
+  { label: "Параметр" },
+  { label: "Значение" },
 ];
 
-const LINES: Line[] = [
-  { id: "setup", service: "Внедрение CRM", quantity: "1", price: "180 000" },
-  { id: "training", service: "Обучение менеджеров", quantity: "3", price: "15 000" },
+const ICONS: { name: IconName; label: string }[] = [
+  { name: "object.users", label: "Пользователи" },
+  { name: "object.storage", label: "Хранилище" },
+  { name: "object.headset", label: "Поддержка" },
+  { name: "object.chart", label: "Отчёты" },
+  { name: "object.key", label: "Доступ" },
+  { name: "object.globe", label: "Интеграции" },
+];
+
+const SPECS: Spec[] = [
+  {
+    id: "seats",
+    icon: "object.users",
+    name: "Сотрудники",
+    value: "до 50",
+    color: "#5068f5",
+    pinned: true,
+  },
+  {
+    id: "storage",
+    icon: "object.storage",
+    name: "Хранилище",
+    value: "200 ГБ",
+    color: "#22c55e",
+    pinned: true,
+  },
+  {
+    id: "support",
+    icon: "object.headset",
+    name: "Поддержка",
+    value: "8/5",
+    color: "#f97316",
+    pinned: true,
+  },
+  { id: "reports", icon: "object.chart", name: "Отчёты", value: "12 шаблонов", color: "#a855f7" },
+  { id: "sso", icon: "object.key", name: "Вход через SSO", value: "SAML, OIDC", color: "#14b8a6" },
 ];
 
 export default function FieldListNarrowExample() {
-  const [lines, setLines] = React.useState(LINES);
+  const [specs, setSpecs] = React.useState(SPECS);
 
   return (
     <div className={styles.narrow}>
       <FieldList
-        label="Позиции счёта"
+        label="Характеристики тарифа"
         columns={COLUMNS}
-        value={lines}
-        onValueChange={setLines}
-        getId={(line) => line.id}
-        getLabel={(line) => line.service}
-        createItem={() => ({ id: crypto.randomUUID(), service: "", quantity: "1", price: "" })}
-        addLabel="Добавить позицию"
-        renderItem={(line, row) => (
+        reorderable
+        value={specs}
+        onValueChange={setSpecs}
+        getId={(spec) => spec.id}
+        getLabel={(spec) => spec.name}
+        getLocked={(spec) => spec.pinned ?? false}
+        createItem={(): Spec => ({
+          id: crypto.randomUUID(),
+          icon: "object.globe",
+          name: "",
+          value: "",
+          color: "#14b8a6",
+        })}
+        addLabel="Добавить характеристику"
+        renderItem={(spec, row) => (
           <>
+            <Select.Root
+              value={spec.icon}
+              onValueChange={(icon) => row.update({ icon: icon as IconName })}
+            >
+              <Select.Trigger>
+                <Select.TriggerIcon>
+                  <Icon name={spec.icon} />
+                </Select.TriggerIcon>
+              </Select.Trigger>
+              <Select.Content>
+                {ICONS.map((icon) => (
+                  <Select.Item key={icon.name} value={icon.name}>
+                    <Select.ItemIcon>
+                      <Icon name={icon.name} />
+                    </Select.ItemIcon>
+                    {icon.label}
+                  </Select.Item>
+                ))}
+              </Select.Content>
+            </Select.Root>
+            <ColorPresets.Root
+              value={spec.color}
+              onValueChange={(color) => row.update({ color: color ?? spec.color })}
+            >
+              <ColorPresets.Trigger>
+                <ColorPresets.SwatchButton />
+              </ColorPresets.Trigger>
+              <ColorPresets.Content />
+            </ColorPresets.Root>
             <Input.Root>
               <Input.Wrapper>
                 <Input.Field
-                  value={line.service}
-                  onChange={(event) => row.update({ service: event.target.value })}
-                />
-              </Input.Wrapper>
-            </Input.Root>
-            <Input.Root>
-              <Input.Wrapper>
-                <Input.Field
-                  value={line.quantity}
-                  inputMode="numeric"
-                  onChange={(event) => row.update({ quantity: event.target.value })}
+                  value={spec.name}
+                  onChange={(event) => row.update({ name: event.target.value })}
                 />
               </Input.Wrapper>
             </Input.Root>
             <Input.Root>
               <Input.Wrapper>
                 <Input.Field
-                  value={line.price}
-                  inputMode="decimal"
-                  onChange={(event) => row.update({ price: event.target.value })}
+                  value={spec.value}
+                  onChange={(event) => row.update({ value: event.target.value })}
                 />
-                <Input.InlineAffix side="end">₽</Input.InlineAffix>
               </Input.Wrapper>
             </Input.Root>
           </>

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

@@ -1,4 +1,4 @@
-/** 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`. */
+/** Selling points of a plan in the order of the pricing page: a one-column list has no headings and no numbers, each row ends with its remove button and then its handle, a point moves by the handle or Alt+arrows — `reorderable`, `getLabel`. */
 import { FieldList, type FieldListColumn, Input } from "prime-ui-kit";
 import * as React from "react";