prime-ui-kit 0.18.0 → 0.19.0

package/src/components/field-list/examples/screen.tsx

@@ -1,4 +1,4 @@
-/** 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`. */
+/** 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, one value in three currencies in one row — `getLocked`, `compact`. */
 import {
   Button,
   Card,
@@ -29,9 +29,9 @@ type Period = { id: string; from: string; price: string; base?: boolean };
 
 const SPEC_COLUMNS: FieldListColumn[] = [
   { label: "Иконка", width: "compact" },
+  { label: "Цвет", width: "compact" },
   { label: "Параметр" },
   { label: "Значение" },
-  { label: "Цвет", width: "compact" },
 ];
 
 const SPEC_ICONS: { name: IconName; label: string }[] = [
@@ -97,6 +97,7 @@ const SAVED_MS = 2000;
 
 export default function FieldListScreenExample() {
   const formId = React.useId();
+  const specsTitleId = React.useId();
   const [specs, setSpecs] = React.useState(SPECS);
   const [periods, setPeriods] = React.useState(PERIODS);
   const [nameError, setNameError] = React.useState<string>();
@@ -134,182 +135,187 @@ export default function FieldListScreenExample() {
         </Page.Actions>
       </Page.Header>
       <Page.Body>
-        <Page.Section layout="aside" label="Основное">
-          <form id={formId} noValidate onSubmit={save}>
-            <Card.Root variant="panel">
-              <Card.Body>
-                <Fieldset disabled={saving} aria-label="Основное">
-                  <Input.Root label="Название" error={nameError}>
+        <form id={formId} noValidate onSubmit={save}>
+          <Card.Root variant="panel">
+            <Card.Header>
+              <Card.Title as="h2">Основное</Card.Title>
+            </Card.Header>
+            <Card.Body>
+              <Fieldset disabled={saving} aria-label="Основное">
+                <Input.Root label="Название" error={nameError}>
+                  <Input.Wrapper>
+                    <Input.Field name="name" defaultValue="Команда" />
+                  </Input.Wrapper>
+                </Input.Root>
+                <Textarea.Root
+                  name="summary"
+                  label="Описание"
+                  optional
+                  rows={2}
+                  defaultValue="Для отделов до 50 человек: задачи, документы и отчёты в одном месте."
+                />
+              </Fieldset>
+            </Card.Body>
+          </Card.Root>
+        </form>
+        <Card.Root variant="panel">
+          <Card.Header>
+            <Card.Title as="h2" id={specsTitleId}>
+              Характеристики
+            </Card.Title>
+            <Card.Description>Первые три закреплены: их видно в карточке тарифа.</Card.Description>
+          </Card.Header>
+          <Card.Body>
+            <FieldList
+              aria-labelledby={specsTitleId}
+              disabled={saving}
+              columns={SPEC_COLUMNS}
+              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>
+                      {SPEC_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 name="name" defaultValue="Команда" />
+                      <Input.Field
+                        value={spec.name}
+                        onChange={(event) => row.update({ name: event.target.value })}
+                      />
                     </Input.Wrapper>
                   </Input.Root>
-                  <Textarea.Root
-                    name="summary"
-                    label="Описание"
-                    optional
-                    rows={2}
-                    defaultValue="Для отделов до 50 человек: задачи, документы и отчёты в одном месте."
-                  />
-                </Fieldset>
-              </Card.Body>
-            </Card.Root>
-          </form>
-        </Page.Section>
-
-        <Page.Section layout="aside" label="Характеристики">
-          <Card.Root variant="panel">
-            <Card.Body>
+                  <Input.Root>
+                    <Input.Wrapper>
+                      <Input.Field
+                        value={spec.value}
+                        onChange={(event) => row.update({ value: event.target.value })}
+                      />
+                    </Input.Wrapper>
+                  </Input.Root>
+                </>
+              )}
+            />
+          </Card.Body>
+        </Card.Root>
+        <Card.Root variant="panel">
+          <Card.Header>
+            <Card.Title as="h2">Стоимость</Card.Title>
+          </Card.Header>
+          <Card.Body className={styles.groups}>
+            <Fieldset label="За месяц" disabled={saving}>
               <FieldList
-                aria-label="Характеристики"
-                disabled={saving}
-                columns={SPEC_COLUMNS}
-                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) => (
+                columns={PRICE_COLUMNS}
+                value={periods}
+                onValueChange={setPeriods}
+                getId={(period) => period.id}
+                getLocked={(period) => period.base ?? false}
+                labels={{ lockedReason: "Базовую цену нельзя удалить" }}
+                createItem={() => ({ id: crypto.randomUUID(), from: "", price: "" })}
+                addLabel="Добавить изменение цены"
+                renderItem={(period, 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>
-                        {SPEC_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>
-                    <Input.Root>
-                      <Input.Wrapper>
-                        <Input.Field
-                          value={spec.name}
-                          onChange={(event) => row.update({ name: event.target.value })}
-                        />
-                      </Input.Wrapper>
-                    </Input.Root>
-                    <Input.Root>
-                      <Input.Wrapper>
-                        <Input.Field
-                          value={spec.value}
-                          onChange={(event) => row.update({ value: event.target.value })}
-                        />
-                      </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>
-                  </>
-                )}
-              />
-            </Card.Body>
-          </Card.Root>
-        </Page.Section>
-
-        <Page.Section layout="aside" label="Стоимость">
-          <Card.Root variant="panel">
-            <Card.Body className={styles.groups}>
-              <Fieldset label="За месяц" disabled={saving}>
-                <FieldList
-                  columns={PRICE_COLUMNS}
-                  value={periods}
-                  onValueChange={setPeriods}
-                  getId={(period) => period.id}
-                  getLocked={(period) => period.base ?? false}
-                  createItem={() => ({ id: crypto.randomUUID(), from: "", price: "" })}
-                  addLabel="Добавить изменение цены"
-                  renderItem={(period, row) => (
-                    <>
-                      {period.base ? (
-                        <Input.Root>
-                          <Input.Wrapper>
-                            <Input.Field value="Всегда, если нет изменений" readOnly />
-                          </Input.Wrapper>
-                        </Input.Root>
-                      ) : (
-                        <Select.Root
-                          value={period.from}
-                          onValueChange={(from) => row.update({ from })}
-                          placeholder="Выберите месяц"
-                        >
-                          <Select.Trigger>
-                            <Select.Value />
-                          </Select.Trigger>
-                          <Select.Content>
-                            {MONTHS.map((month) => (
-                              <Select.Item key={month.value} value={month.value}>
-                                {month.label}
-                              </Select.Item>
-                            ))}
-                          </Select.Content>
-                        </Select.Root>
-                      )}
+                    {period.base ? (
                       <Input.Root>
                         <Input.Wrapper>
-                          <Input.Field
-                            value={period.price}
-                            inputMode="decimal"
-                            placeholder="0"
-                            onChange={(event) => row.update({ price: event.target.value })}
-                          />
-                          <Input.InlineAffix side="end">₽</Input.InlineAffix>
+                          <Input.Field value="Всегда, если нет изменений" readOnly />
                         </Input.Wrapper>
                       </Input.Root>
-                    </>
-                  )}
-                />
-              </Fieldset>
-              <Fieldset
-                label="Подключение"
-                description="Разовый платёж; пустая валюта не выставляется."
-                disabled={saving}
-              >
-                <div className={styles.currencies}>
-                  {SETUP_FEE.map((fee) => (
-                    <Input.Root key={fee.name}>
+                    ) : (
+                      <Select.Root
+                        value={period.from}
+                        onValueChange={(from) => row.update({ from })}
+                        placeholder="Выберите месяц"
+                      >
+                        <Select.Trigger>
+                          <Select.Value />
+                        </Select.Trigger>
+                        <Select.Content>
+                          {MONTHS.map((month) => (
+                            <Select.Item key={month.value} value={month.value}>
+                              {month.label}
+                            </Select.Item>
+                          ))}
+                        </Select.Content>
+                      </Select.Root>
+                    )}
+                    <Input.Root>
                       <Input.Wrapper>
                         <Input.Field
-                          name={fee.name}
-                          aria-label={fee.label}
+                          value={period.price}
                           inputMode="decimal"
                           placeholder="0"
-                          defaultValue={fee.value}
+                          onChange={(event) => row.update({ price: event.target.value })}
                         />
-                        <Input.InlineAffix side="end">{fee.currency}</Input.InlineAffix>
+                        <Input.InlineAffix side="end">₽</Input.InlineAffix>
                       </Input.Wrapper>
                     </Input.Root>
-                  ))}
-                </div>
-              </Fieldset>
-            </Card.Body>
-          </Card.Root>
-        </Page.Section>
+                  </>
+                )}
+              />
+            </Fieldset>
+            <Fieldset
+              label="Подключение"
+              description="Разовый платёж; пустая валюта не выставляется."
+              disabled={saving}
+            >
+              <div className={styles.currencies}>
+                {SETUP_FEE.map((fee) => (
+                  <Input.Root key={fee.name}>
+                    <Input.Wrapper>
+                      <Input.Field
+                        name={fee.name}
+                        aria-label={fee.label}
+                        inputMode="decimal"
+                        placeholder="0"
+                        defaultValue={fee.value}
+                      />
+                      <Input.InlineAffix side="end">{fee.currency}</Input.InlineAffix>
+                    </Input.Wrapper>
+                  </Input.Root>
+                ))}
+              </div>
+            </Fieldset>
+          </Card.Body>
+        </Card.Root>
       </Page.Body>
     </Page.Root>
   );

package/src/components/field-list/examples/totals.tsx

@@ -1,4 +1,4 @@
-/** 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`. */
+/** 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`. */
 import { FieldList, type FieldListColumn, Input } from "prime-ui-kit";
 import * as React from "react";
 
@@ -18,11 +18,7 @@ const SHARES: Share[] = [
   { id: "kotova", member: "Ирина Котова", percent: "20" },
 ];
 
-const RUB = new Intl.NumberFormat("ru-RU", {
-  style: "currency",
-  currency: "RUB",
-  maximumFractionDigits: 0,
-});
+const AMOUNT = new Intl.NumberFormat("ru-RU", { maximumFractionDigits: 0 });
 
 const percentOf = (share: Share) => Number(share.percent.replace(",", ".")) || 0;
 
@@ -62,7 +58,12 @@ export default function FieldListTotalsExample() {
           </Input.Root>
           <Input.Root>
             <Input.Wrapper>
-              <Input.Field value={RUB.format((BONUS * percentOf(share)) / 100)} readOnly />
+              <Input.Field
+                value={AMOUNT.format((BONUS * percentOf(share)) / 100)}
+                inputMode="decimal"
+                readOnly
+              />
+              <Input.InlineAffix side="end">₽</Input.InlineAffix>
             </Input.Wrapper>
           </Input.Root>
         </>
@@ -73,7 +74,7 @@ export default function FieldListTotalsExample() {
           <>
             {null}
             {`${percent} %`}
-            {RUB.format((BONUS * percent) / 100)}
+            {`${AMOUNT.format((BONUS * percent) / 100)} ₽`}
           </>
         );
       }}

package/src/components/kanban/COMPONENT.md

@@ -31,6 +31,7 @@ import {
 ## Anatomy
 ```
 Kanban.Root                          board: horizontal strip of columns, its own Dnd.Root if none above
+├─ placeholder columns               while `loading` and `columns` is empty: `loadingColumns` columns of Skeleton title and cards
 └─ <ul> (Dnd.Sortable, axis x)       the columns in `columnOrder`
    └─ <li> column (from `columns`)   no well with a header plate (`plain`) or a header line (`line`), or a `fill-muted` well (`well`)
       ├─ header                      title (`columnTitleAs`, h3) · count Badge (the stage color) · renderColumnActions(column) · [grip Dnd.Handle, a lock when `locked`]
@@ -76,6 +77,7 @@ Generic `Kanban.Root<T>`; `ref` → `HTMLDivElement`. The board: a strip of colu
 | `canDrop` | `(id: string, columnId: string) => boolean \| string` | — | A workflow rule: refuses card `id` in column `columnId` — `false`, or a string that says why (spoken and shown under the carried card). The column turns `danger` before the release. |
 | `variant` | `"plain" \| "line" \| "well"` | `"plain"` | No wells: `plain` — a filled header plate over the cards, `line` — a bare header over a faint line; cards stand on the host. `well`: every column is a filled well holding its cards (bounded queues). |
 | `loading` | `boolean` | `false` | Columns show skeleton cards in the card geometry; the cards cross-fade in when it turns off. |
+| `loadingColumns` | `number` | `3` | Placeholder columns a `loading` board draws while `columns` is empty (the stages are still loading); the columns fade in where they stood. |
 | `disabled` | `boolean` | `false` | Read-only board: no drag, no keyboard moves, no column grips; `onItemOpen` and `getItemHref` still open cards. |
 | `labels` | `Partial<KanbanLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "defaultValue">` | — | `className` (the board height), `aria-label` and the other div attributes. |
@@ -144,6 +146,7 @@ Do not wrap a `plain` board's columns in your own boxes, and do not put a `well`
 | `reorderableColumns` | a ghost grip at the end of every column header, after the actions; the column is carried by it | the user arranges the stages | `false` |
 | `canDrop` | the column turns `danger` under a refused card; a string reason is spoken and shown under the carried card; a keyboard move is announced as refused | workflow rules (a blocked ticket cannot be closed) | — |
 | `loading` | skeleton cards in the card geometry, no counts | the first load or a refresh | `false` |
+| `loadingColumns` | placeholder columns (a Skeleton title, Skeleton cards) while `loading` and `columns` is empty | the stages themselves come from the server | `3` |
 | `disabled` | cards do not drag, Alt + arrows do nothing | read-only boards, no permission | `false` |
 
 ## States
@@ -158,12 +161,13 @@ Do not wrap a `plain` board's columns in your own boxes, and do not put a `well`
 | full | count ≥ `limit` | `data-full` on the column, orange count `count / limit` |
 | empty | no cards | a compact `EmptyPage` in Dnd's dashed drop slot at the top (`fill-strong` dashed line, no fill): «Нет карточек» and the hint «Перетащите сюда карточку»; a `disabled` board shows the text alone; the whole column stays a drop area |
 | loading | `loading` | `aria-busy` and `data-loading` on the root; `Skeleton` cards; `Crossfade` swaps them for the cards |
+| loading, no columns yet | `loading` with empty `columns` | an `aria-hidden` row of `loadingColumns` placeholder columns; the columns fade in where they stood (`enterMotion`) |
 | disabled | `disabled` / `Kanban.Item disabled` | `data-disabled` on the root / card; no `aria-roledescription`, no shortcuts, no column grips |
 | saving | `onValueChange` / `onColumnOrderChange` returned a pending promise | the card (column) stays in its new place with `aria-busy` and `data-pending`; a card's content quiets to 0.6 under a centred `Spinner`, a column's heading quiets and its grip is busy (Dnd); it does not move again until the answer |
 | opens | `onItemOpen` / `getItemHref` | `data-clickable` (in place) or `data-link` (a link over the card, its focus ring drawn on the card); a card that opens lifts on hover on a read-only board too |
 | refused save | the promise rejected | the card glides back to its old column and place (every card it pushed aside glides too), a column glides back in the strip; `labels.moveFailed` / `labels.columnMoveFailed` is announced |
 
-Motion: the hover lift (shadow, the card rises above its neighbours) and the empty slot fade (`fast`, `standard`); a card dropped under the mouse lands straight into its hover lift (`data-dnd-hover`); the swap from skeletons is `Crossfade`; drag motion is Dnd's (lift, gap, glide, landing); a saving card or column quiets (`fast`, both ways) and its spinner fades in by itself; a refused save glides back (`base`, the list's FLIP glide), never jumps. Under `prefers-reduced-motion` all of it is off.
+Motion: the hover lift (shadow, the card rises above its neighbours) and the empty slot fade (`fast`, `standard`); a card dropped under the mouse lands straight into its hover lift (`data-dnd-hover`); the swap from skeletons is `Crossfade`, the columns that replace placeholder columns fade in; drag motion is Dnd's (lift, gap, glide, landing); a saving card or column quiets (`fast`, both ways) and its spinner fades in by itself; a refused save glides back (`base`, the list's FLIP glide), never jumps. Under `prefers-reduced-motion` all of it is off.
 
 A card's own `onKeyDown` runs before the board's: `preventDefault()` in it keeps the move from happening. A controlled owner applies the new `value` (or `columnOrder`) once the request succeeds — in the promise chain, before the returned promise resolves — never before the answer.
 
@@ -231,7 +235,7 @@ A card's own `onKeyDown` runs before the board's: `preventDefault()` in it keeps
 | [columns.tsx](examples/columns.tsx) | A sales pipeline whose stages move by the grip in their header while the first and the last stay locked; each stage carries its color on the count, a rule and its figures in two lines under the title, and is edited in a popover; the page keeps the order — `reorderableColumns`, `columnOrder`, `onColumnOrderChange`, `locked`, `color`, `description`, `renderColumnMeta`, `renderColumnActions`. |
 | [saving.tsx](examples/saving.tsx) | Every move is saved on the server: the card waits busy in its new place, and an invoice the server refuses to close glides back to its column — `onValueChange`. |
 | [item-link.tsx](examples/item-link.tsx) | Tickets that open: each card is a link to its page, so ⌘-click or a middle click opens a new tab, a plain click, Enter or Space opens it in place, and a drag only moves it — `getItemHref`, `onItemOpen`. |
-| [states.tsx](examples/states.tsx) | Loading draws skeleton cards in the card geometry; an empty column keeps its drop area and a closed order stays in place while the rest move; a read-only board drags nothing — `loading`, `disabled`. |
+| [states.tsx](examples/states.tsx) | Loading draws skeleton cards in the card geometry, and placeholder columns before the columns arrive; an empty column keeps its drop area and a closed order stays in place while the rest move; a read-only board drags nothing — `loading`, `loadingColumns`, `disabled`. |
 | [controlled.tsx](examples/controlled.tsx) | The placement lives in the parent: every move arrives with its source, target and position to save, and a button resets the board — `value`, `onValueChange`. |
 | [narrow.tsx](examples/narrow.tsx) | On a phone-width screen a column takes 85% of the board and snaps into place, so the next one peeks; the strip scrolls inside the board, never the page — `Kanban.Root`, `columns`. |
 | [screen.tsx](examples/screen.tsx) | A sales pipeline as a work screen: the title with the open deals and their sum, search, filter, the board / list switch and the one primary action in its top bar, a full-height Kanban of deals by stage with totals, moves saved on the server that can be refused, and the deal in a Drawer — `value`, `onValueChange`, `renderColumnMeta`, `onItemOpen`. |

package/src/components/kanban/examples/states.tsx

@@ -1,4 +1,4 @@
-/** Loading draws skeleton cards in the card geometry; an empty column keeps its drop area and a closed order stays in place while the rest move; a read-only board drags nothing — `loading`, `disabled`. */
+/** Loading draws skeleton cards in the card geometry, and placeholder columns before the columns arrive; an empty column keeps its drop area and a closed order stays in place while the rest move; a read-only board drags nothing — `loading`, `loadingColumns`, `disabled`. */
 import { Badge, Kanban, Typography } from "prime-ui-kit";
 
 type Order = { id: string; title: string; total: string; closed?: boolean };
@@ -24,9 +24,10 @@ const PLACEMENT = {
 };
 
 const STATES = [
-  { caption: "loading", loading: true, disabled: false },
-  { caption: "Kanban.Item disabled", loading: false, disabled: false },
-  { caption: "disabled", loading: false, disabled: true },
+  { caption: "loading · columns=[]", columns: [], loading: true, disabled: false },
+  { caption: "loading", columns: COLUMNS, loading: true, disabled: false },
+  { caption: "Kanban.Item disabled", columns: COLUMNS, loading: false, disabled: false },
+  { caption: "disabled", columns: COLUMNS, loading: false, disabled: true },
 ];
 
 export default function KanbanStatesExample() {
@@ -35,7 +36,8 @@ export default function KanbanStatesExample() {
       <div>
         <Kanban.Root
           aria-label={`Заказы склада: ${state.caption}`}
-          columns={COLUMNS}
+          columns={state.columns}
+          loadingColumns={COLUMNS.length}
           items={ORDERS}
           getId={(order) => order.id}
           getLabel={(order) => order.id}

package/src/components/list/COMPONENT.md

@@ -28,13 +28,14 @@ import { List } from "prime-ui-kit";
 ```
 List.Root                   <ul aria-label>; size (else the host tier) → row tier; onReorder → Dnd.Sortable <ul>
 └─ List.Item                <li> with a full-width <button> | <a href> | asChild element; current, disabled
-   │                         value; with onReorder: Dnd.Handle (busy while saving) before the row element
+   │                         value; with onReorder: Dnd.Handle (busy while saving) at the row's end, after its actions
    ├─ List.ItemIcon         leading Avatar.Root / Icon / Badge.Dot (aria-hidden); after the text — a trailing glyph
    ├─ List.ItemText         primary line, truncates
    ├─ List.ItemDescription  second line, muted, truncates
    ├─ List.ItemMeta         trailing small text (time, date, amount)
    ├─ List.ItemCount        trailing Badge, one tier down
-   └─ List.ItemActions      the row's own controls (Switch, Dropdown): beside the row element, one tier down
+   └─ List.ItemActions      the row's own controls (Switch, Dropdown): beside the row element, one tier down;
+                             side="end" after it, side="start" before it (a reorderable row's toggle)
 ```
 
 ## API
@@ -47,7 +48,7 @@ List.Root                   <ul aria-label>; size (else the host tier) → row t
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Row tier: height, text, icon and avatar size; counts take one tier down. Without it the tier of its host, else `m`. |
-| `onReorder` | `(id: string, beforeId: string \| null) => void \| Promise<void>` | — | Rows reorder by a leading handle (drag, touch hold, Alt + ↑ / ↓): item `value` `id` goes before `beforeId` (`null` = last). Apply with `moveBefore`; a returned promise keeps the row busy, a rejection moves it back. |
+| `onReorder` | `(id: string, beforeId: string \| null) => void \| Promise<void>` | — | Rows reorder by an end handle (drag, touch hold, Alt + ↑ / ↓): item `value` `id` goes before `beforeId` (`null` = last). Apply with `moveBefore`; a returned promise keeps the row busy, a rejection moves it back. |
 | `labels` | `Partial<ListLabels>` | — | Built-in strings, see Labels. |
 | `aria-label` | `string` | — | Name of the list for screen readers («Обращения»), when no visible heading names it. |
 | `children` | `ReactNode` | — | `List.Item`s. |
@@ -108,10 +109,11 @@ List.Root                   <ul aria-label>; size (else the host tier) → row t
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children" \| "color">` | — | `className` and the other `span` attributes. |
 
 ### List.ItemActions
-`ref` → `HTMLDivElement`. The row's own controls (a `Switch`, a `Dropdown` with its icon `Button`) at its end, beside the row element and never inside it, one tier below the row.
+`ref` → `HTMLDivElement`. The row's own controls (a `Switch`, a `Dropdown` with its icon `Button`) at its end or its start, beside the row element and never inside it, one tier below the row.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `side` | `"start" \| "end"` | `"end"` | `"end"` after the row element: a plain settings row, label first. `"start"` before it, in the DOM too: the on / off of a reorderable row reads first and the grip keeps the end. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the controls, each named on its own), `className` and the other `div` attributes. |
 
 ## Variants
@@ -137,6 +139,12 @@ A second line or an avatar makes a row taller than the one-line height; the vert
 ### List.ItemCount color
 `gray` (default) for a plain number; a hue for what needs attention (`blue` for unread). Any palette hue.
 
+### List.ItemActions side
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `end` | the controls after the row's text and trail | a plain row: the label first, the toggle or ⋯ menu at the end | yes |
+| `start` | the controls before the row's icon and text, first in the DOM and the Tab order | a reorderable row's on / off: the state reads first, the grip keeps the end edge | |
+
 ## States
 | State | Driven by | DOM |
 |---|---|---|
@@ -146,9 +154,9 @@ A second line or an avatar makes a row taller than the one-line height; the vert
 | current | `current` | `aria-current="true"` (button) or `"page"` (link); `fill-muted-hover` fill, primary text |
 | focus-visible | keyboard | the focus ring inside the row edge |
 | disabled | `disabled` | `disabled` on a button; `aria-disabled="true"`, no `href` on a link, `tabindex="-1"` on an `asChild` element; `data-disabled="true"`; disabled text; in a reorderable list the handle is disabled and the row holds its place |
-| reorderable | `onReorder` | `data-reorderable="true"` on the root (a `Dnd.Sortable` `<ul>`); each `<li>` is a sortable item (`data-dnd-item` = `value`) with a leading `Dnd.Handle`; drag by the handle (a touch hold on touch), Alt + ↑ / ↓ from the handle or the row; a lifted row leaves a dashed gap in the row's radius, its neighbours glide, the copy (handle and row, in the row's padding and radius) follows the pointer and sets down in its new place without a jump |
+| reorderable | `onReorder` | `data-reorderable="true"` on the root (a `Dnd.Sortable` `<ul>`); each `<li>` is a sortable item (`data-dnd-item` = `value`) with a `Dnd.Handle` at its end; drag by the handle (a touch hold on touch), Alt + ↑ / ↓ from the handle or the row; a lifted row leaves a dashed gap in the row's radius, its neighbours glide, the copy (handle and row, in the row's padding and radius) follows the pointer and sets down in its new place without a jump |
 | saving a move | `onReorder` returned a pending promise | the row stays in its new place, `aria-busy="true"`, the handle is busy (Dnd: a spinner in the disabled grip), the row content dims to 0.6 (`--prime-motion-fade-fast` both ways); a rejection glides the row back |
-| own controls | `List.ItemActions` in the item | the row element and the controls stand in one frame that takes the hover, press and current fills for both; the element itself stays clear |
+| own controls | `List.ItemActions` in the item | the row element and the controls stand in one frame that takes the hover, press and current fills for both; the element itself stays clear; `side="start"` controls come before the element in the frame, `data-side` on the actions |
 | rows come and go | the data adds or takes out a `List.Item` (`value`, else its key) | a new row rises in once (`enterMotion`), a removed one closes up in place (`listPresence`); the first render stays still |
 
 Root attributes: `data-size`, `role="list"` (the list style reset would drop the list semantics in WebKit). The fill changes on `background-color` with `--prime-motion-fade-xfast` both ways (a fade: reduced motion keeps it).
@@ -159,8 +167,9 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 - Row: leading icon · body (text over description) · trail. Beside two lines the trail stacks — meta on top, count below; beside one line they sit in a row.
 - Text and description truncate with an ellipsis; give a long `List.ItemText` a `title` with the full text.
 - On a coarse pointer a row is at least the touch target (44px).
-- Reorderable (`onReorder`): an `xs` handle box sits before each row, 4px from it; the row keeps its own padding and fill.
-- `List.ItemActions`: the controls one tier below the row, 4px apart, as far from the row's end as from its top and bottom.
+- Reorderable (`onReorder`): an `xs` handle box ends each row, 4px after the row element and its `List.ItemActions` (inline-end: on the left in RTL); the row keeps its own padding and fill, so every row's handle stands on one line.
+- `List.ItemActions`: the controls one tier below the row, 4px apart, as far from the row's edge as from its top and bottom — the end edge, or the start edge with `side="start"`, where the row's own padding then parts the controls from its icon or text.
+- One toggle place per row: a plain row ends with its toggle (label first); a reorderable row leads with it (`side="start"`) and ends with the grip — never a toggle between the label and the grip.
 - A colour dot in `List.ItemIcon` is the large `Badge.Dot` (8px) centred in an icon-wide box, so the text lines up with the rows that carry icons.
 
 ## Accessibility
@@ -181,8 +190,8 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 - The open record: `aria-current="true"` on a button (a selection inside the screen), `aria-current="page"` on a link (`href`, `asChild`) — the link points at the current URL. A router link may set it itself.
 - The row's name is its text, description, meta and count, in that order; the leading icon or avatar is `aria-hidden` — the text names the row.
 - Arrow keys do not move between rows: rows are ordinary Tab stops, as in the Sidebar.
-- `List.ItemActions` stand beside the row element, never inside it: the row's name stays its text, and Tab goes from the row to its controls.
-- With `onReorder` each row gets a handle named «Переместить {label}» (`labels.reorderItem`, `{label}` is the row's text line) and `aria-keyshortcuts`; the new place is announced politely («Новый лид: позиция 2 из 5»), a row being saved is `aria-busy`.
+- `List.ItemActions` stand beside the row element, never inside it: the row's name stays its text. Tab follows the row as it reads: the `side="start"` controls, the row, the `side="end"` controls.
+- With `onReorder` each row gets a handle named «Переместить {label}» (`labels.reorderItem`, `{label}` is the row's text line) and `aria-keyshortcuts`, last in the row: Tab reaches the row with its `List.ItemActions`, then the handle; the new place is announced politely («Новый лид: позиция 2 из 5»), a row being saved is `aria-busy`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -200,7 +209,7 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 | [with-icon.tsx](examples/with-icon.tsx) | Leading avatars of clients, icons of queues and colour dots of projects; an avatar takes the row tier, a dot stands in an icon-wide box — `List.ItemIcon`, `Badge.Dot`. |
 | [overflow.tsx](examples/overflow.tsx) | A long inbox in a pane of a fixed height: the list scrolls in a ScrollContainer and long names and previews truncate — `List.ItemText`, `List.ItemDescription`. |
 | [as-link.tsx](examples/as-link.tsx) | Rows as links to the invoice pages: a plain link, or your router link through the slot — `href`, `asChild`. |
-| [reorder.tsx](examples/reorder.tsx) | Funnel stages in the team's order: a stage moves by its handle or Alt+arrows and is saved on the server — `onReorder`, `value`. |
+| [reorder.tsx](examples/reorder.tsx) | Funnel stages in the team's order: a stage moves by its handle or Alt+arrows and is saved on the server; its switch leads the row, the grip ends it — `onReorder`, `value`, `side`. |
 | [row-controls.tsx](examples/row-controls.tsx) | Funnel stages with their own controls: a colour dot names the stage's hue, a switch shows it on the board and a menu edits it, all beside the row that opens the stage — `List.ItemActions`, `Badge.Dot`. |
 
 ## Mistakes
@@ -212,6 +221,7 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 - Up / down buttons on rows or a hand-made `Dnd.Sortable` of rows to order them → `List.Root onReorder` with a `value` on every item.
 - `onReorder` that rolls the order back itself on an error → return the promise; a rejection moves the row back.
 - A Switch or a menu button put inside a row, or a row rebuilt as a `div` to hold one → `List.ItemActions` beside the row element.
+- A Switch at the end of a reorderable row, between its label and the grip → `List.ItemActions side="start"`; the grip keeps the end.
 - A hollow `Icon` circle or a hand-drawn dot as a stage colour → `Badge.Dot color` in `List.ItemIcon`.
 
 ## Related