prime-ui-kit 0.18.0 → 0.20.0

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

@@ -0,0 +1,71 @@
+/** 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`. */
+import { FieldList, type FieldListColumn, Input } from "prime-ui-kit";
+import * as React from "react";
+
+type Stage = { id: string; name: string; days: string; percent: string; pinned?: boolean };
+
+const COLUMNS: FieldListColumn[] = [
+  { label: "Этап" },
+  { label: "Срок", width: "s" },
+  { label: "Доля", width: "xs" },
+];
+
+const STAGES: Stage[] = [
+  { id: "advance", name: "Аванс", days: "0", percent: "30", pinned: true },
+  { id: "design", name: "Приёмка дизайна", days: "21", percent: "20" },
+  { id: "beta", name: "Запуск бета-версии", days: "45", percent: "30" },
+  { id: "release", name: "Подписание акта", days: "60", percent: "20" },
+];
+
+export default function FieldListRowMenuExample() {
+  const [stages, setStages] = React.useState(STAGES);
+
+  return (
+    <FieldList
+      label="Этапы оплаты"
+      columns={COLUMNS}
+      rowActions="menu"
+      reorderable
+      value={stages}
+      onValueChange={setStages}
+      getId={(stage) => stage.id}
+      getLabel={(stage) => stage.name}
+      getLocked={(stage) => stage.pinned ?? false}
+      labels={{ lockedReason: "Аванс всегда первый" }}
+      createItem={() => ({ id: crypto.randomUUID(), name: "", days: "", percent: "" })}
+      addLabel="Добавить этап"
+      renderItem={(stage, row) => (
+        <>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Field
+                value={stage.name}
+                onChange={(event) => row.update({ name: event.target.value })}
+              />
+            </Input.Wrapper>
+          </Input.Root>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Field
+                value={stage.days}
+                inputMode="numeric"
+                onChange={(event) => row.update({ days: event.target.value })}
+              />
+              <Input.InlineAffix side="end">дн.</Input.InlineAffix>
+            </Input.Wrapper>
+          </Input.Root>
+          <Input.Root>
+            <Input.Wrapper>
+              <Input.Field
+                value={stage.percent}
+                inputMode="decimal"
+                onChange={(event) => row.update({ percent: event.target.value })}
+              />
+              <Input.InlineAffix side="end">%</Input.InlineAffix>
+            </Input.Wrapper>
+          </Input.Root>
+        </>
+      )}
+    />
+  );
+}

package/dist/skill/reference/components/field-list/examples/screen.module.css

@@ -1,4 +1,4 @@
-/* Record editor: the sections are Page.Section layout="aside"; here only the panels' insides. */
+/* Record editor: the blocks are titled cards in the page flow; here only the cards' insides. */
 
 /* Two groups in one panel, a group apart. */
 .groups {

package/dist/skill/reference/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, the price list on its own fill among the fields of its card, one value in three currencies in one row — `getLocked`, `compact`, `variant`. */
 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,188 @@ 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) => (
+                variant="surface"
+                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/dist/skill/reference/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/dist/skill/reference/components/field-list/examples/variants.tsx

@@ -0,0 +1,51 @@
+/** The two looks of the same list: the rows on the host surface, or on a fill of their own with side padding — `variant`. */
+import { FieldList, type FieldListColumn, Input, Typography } from "prime-ui-kit";
+
+type Contact = { id: string; name: string; phone: string };
+
+const VARIANTS = ["plain", "surface"] as const;
+
+const COLUMNS: FieldListColumn[] = [{ label: "Контакт" }, { label: "Телефон", width: "m" }];
+
+const CONTACTS: Contact[] = [
+  { id: "buyer", name: "Анна Лебедева", phone: "+7 912 404-18-20" },
+  { id: "accountant", name: "Олег Демин", phone: "+7 903 118-42-07" },
+];
+
+export default function FieldListVariantsExample() {
+  return (
+    <div>
+      {VARIANTS.map((variant) => (
+        <div key={variant}>
+          <div>
+            <FieldList
+              variant={variant}
+              label="Контакты покупателя"
+              columns={COLUMNS}
+              defaultValue={CONTACTS}
+              getId={(contact) => contact.id}
+              getLabel={(contact) => contact.name}
+              renderItem={(contact) => (
+                <>
+                  <Input.Root>
+                    <Input.Wrapper>
+                      <Input.Field defaultValue={contact.name} />
+                    </Input.Wrapper>
+                  </Input.Root>
+                  <Input.Root>
+                    <Input.Wrapper>
+                      <Input.Field type="tel" defaultValue={contact.phone} />
+                    </Input.Wrapper>
+                  </Input.Root>
+                </>
+              )}
+            />
+            <Typography as="span" variant="caption" tone="muted">
+              {variant}
+            </Typography>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/gantt/COMPONENT.md

@@ -25,7 +25,7 @@ import { Gantt, type GanttBar, type GanttDates, type GanttScale } from "prime-ui
 ## Anatomy
 ```
 Gantt                          surface (layer of the ladder), size container
-├─ toolbar                     your `toolbar` content · «Сегодня» · zoom (SegmentedControl)
+├─ toolbar                     the kit's tool row: your `toolbar` content (the free room) · «Сегодня» · zoom (SegmentedControl)
 └─ viewport                    ScrollContainer, both axes, own scroll only
    └─ role="grid"
       ├─ head row (sticky)     corner (sticky) · axis: top tier (months / years) over bottom tier (days / weeks / months), today chip
@@ -62,7 +62,7 @@ Gantt                          surface (layer of the ladder), size container
 | `readOnly` | `boolean` | `false` | No moving, resizing or creating; bars still select and show their dates. |
 | `loading` | `boolean` | `false` | Without rows — skeleton rows in the chart's geometry and a status for screen readers; with rows they stay and the grid is `aria-busy`. |
 | `empty` | `ReactNode` | — | Empty-state content when `rows` is empty; a string goes into a compact `EmptyPage`. Defaults to `labels.empty`. |
-| `toolbar` | `ReactNode` | — | Content at the start of the toolbar (title, filters, a primary action); the zoom and «Сегодня» sit at its end. |
+| `toolbar` | `ReactNode` | — | Content at the start of the toolbar (title, a legend, filters), kept together in the free room; «Сегодня» and the zoom keep their width at its end, and on a narrow chart they take the next line, the zoom filling it. |
 | `scrollHeight` | `number \| "fill"` | — | Max height of the viewport in px, so the header sticks while rows scroll; `"fill"` — the chart takes its flex / grid parent's height. |
 | `onItemOpen` | `(bar: Bar, row: Row) => void` | — | A bar was activated (click, Enter, Space): open its record. A drag never opens it. |
 | `onBarChange` | `(dates: GanttDates, bar: Bar, row: Row) => void \| Promise<void>` | — | New dates of a bar after a drag or an editing key — update your data. A returned Promise keeps the bar busy at the new dates; a rejection glides it back. Without it bars cannot be edited. |
@@ -151,7 +151,7 @@ A `tone` wins over `color`. Say the status in the label too, never only by color
 - Editing precision: a move, a resize and a drawing snap to whole days at every zoom (at the month zoom a day is 4 px, so the snap holds a day until the pointer clearly leaves it); hold Alt to snap to the zoom's week or month. A bar is at least one day long: a resize past the opposite edge stops there and never flips. On touch a finger held on a bar picks it up, then it drags like a pointer.
 - Creating: on empty space the cursor is a crosshair and, on pointer devices, the cell under it is washed with a «+». Drag across a row to draw a range in days, double-click (or long-press on touch) for one unit of the zoom; a drag after the long press draws days. While drawing, a ghost with a dates and duration tooltip follows the pointer. Without `onBarCreate` (or with `readOnly`) nothing can be created and empty space shows no create cursor. Near the edges of the axis a drag, a resize and a drawing scroll the chart.
 - Tooltip: the bar's title, then its dates · duration · progress; `renderBarTooltip` adds lines under them (a client, planned hours) and never replaces them — the dates are what the bar means on the axis, and the same tooltip shows the new dates while dragging.
-- A legend of bar colours goes in `toolbar`: a row of `Badge.Root color` + `Badge.Dot` with the category name, one per hue the bars use; the toolbar wraps it. Say the category in the bar label or the tooltip too, never only by colour.
+- A legend of bar colours goes in `toolbar`: a row of `Badge.Root color` + `Badge.Dot` with the category name, one per hue the bars use; the toolbar keeps it together in the free room and wraps it, «Сегодня» and the zoom at the end (on a narrow chart on the next line, the zoom filling it). Say the category in the bar label or the tooltip too, never only by colour.
 - The default axis covers every bar and today with a unit of room on both sides; pass `range` for a fixed period.
 - The chart opens with today a third into the view; «Сегодня» and the arrow keys scroll only the chart's scroller, never the page.
 - A row grows by a lane for every overlapping bar: lanes are packed greedily by start date.
@@ -237,5 +237,5 @@ A `tone` wins over `color`. Say the status in the label too, never only by color
 - Expecting the page to scroll to today → «Сегодня» scrolls only the chart.
 
 ## Related
-- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Button](../button/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), Icon (`action.add` in the create cue), [VisuallyHidden](../visually-hidden/COMPONENT.md)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), [Button](../button/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), Icon (`action.add` in the create cue), [VisuallyHidden](../visually-hidden/COMPONENT.md); `ToolRow` (the toolbar, as the DataTable `toolbar`) with [SmartFilter](../smart-filter/COMPONENT.md), [Input](../input/COMPONENT.md) and [Typography](../typography/COMPONENT.md) (what grows in the tool row), [SegmentedControl](../segmented-control/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md) and [Select](../select/COMPONENT.md) (what fills a short line; the first two get `fullWidth`)
 - **See also:** [Timeline](../timeline/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Kanban](../kanban/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [Avatar](../avatar/COMPONENT.md)

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