prime-ui-kit 0.14.0 → 0.16.0

package/src/components/confirm-dialog/examples/failure.tsx

@@ -1,31 +1,24 @@
-/** The server refuses: the dialog stays open with the owner's reason under the text and the confirm ready to try again — `error`, `onConfirm`. */
+/** The server refuses: the dialog stays open with the reason of the rejection under the text and the confirm ready to try again — `onConfirm`. */
 import { Button, ConfirmDialog } from "prime-ui-kit";
-import * as React from "react";
 
 /** Pretends the server refuses: the tag is still in use. */
 function deleteTag() {
-  return new Promise((_, reject) => setTimeout(() => reject(new Error("in use")), 900));
+  return new Promise((_, reject) =>
+    setTimeout(
+      () =>
+        reject(new Error("Тег используется в 12 активных сделках — сначала снимите его с них.")),
+      900,
+    ),
+  );
 }
 
 export default function ConfirmDialogFailureExample() {
-  const [error, setError] = React.useState<string>();
-
   return (
     <ConfirmDialog.Root
       title="Удалить тег «VIP»?"
       description="Тег снимется со всех клиентов."
       confirmLabel="Удалить тег"
-      error={error}
-      onOpenChange={() => setError(undefined)}
-      onConfirm={async () => {
-        setError(undefined);
-        try {
-          await deleteTag();
-        } catch (reason) {
-          setError("Тег используется в 12 активных сделках — сначала снимите его с них.");
-          throw reason;
-        }
-      }}
+      onConfirm={deleteTag}
     >
       <ConfirmDialog.Trigger>
         <Button.Root variant="soft" tone="danger">

package/src/components/crossfade/COMPONENT.md

@@ -40,7 +40,7 @@ Crossfade          <div>; holds the region's height while it changes
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### Crossfade
-`ref` → `HTMLDivElement`. A region that cross-fades its content when `state` changes and glides to the new height; still on the first render, instant under reduced motion.
+`ref` → `HTMLDivElement`. A region that cross-fades its content when `state` changes and glides to the new height; still on the first render. Under reduced motion the old content goes at once and the height jumps; the new content still fades in.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -69,12 +69,13 @@ Crossfade has no variants: one treatment, keyed by `state`.
 |---|---|---|
 | first render | mount | one layer, `data-state="open"`, no motion |
 | swapping | `state` changes | previous layer `data-state="closed"`, `aria-hidden`, `inert`, absolutely placed, fades out over `fast` with `exit` easing and unmounts on `animationend` (timeout fallback); the new layer fades in over `base` with `enter` easing |
-| resizing | the new state has another height | root `data-resizing="true"`: height glides from the old to the new value over `base` with `standard` easing, clipped with a `--prime-focus-space` margin, then returns to `auto` |
-| reduced motion | `prefers-reduced-motion: reduce` | instant swap: no leaving layer, no glide |
+| resizing | the new state has another height | root `data-resizing="true"`: height glides from the old to the new value over `base` with `standard` easing (a swap mid-glide starts from the height on screen), clipped with a `--prime-focus-space` margin, then returns to `auto` |
+| reduced motion | `prefers-reduced-motion: reduce` | the old layer goes before it is painted and the height does not glide; the new layer still fades in (the fade clock, foundation §7 rule 12) |
+| focus handoff | focus was in the old state when `state` changed | focus moves into the new layer: its first tab stop, else the layer itself (`tabindex="-1"`); focus elsewhere stays |
 | empty | the current state renders nothing (`null`, `false`, `""`) | no current layer; once nothing is leaving the root is `:empty` and `display: none` — no box and no gap in its grid or flex parent |
 | filling | `fill` | `data-fill="true"`; the root is a one-cell grid (`flex: 1`, `height: 100%`, `min-height: 0`), layers stretch to it |
 
-Motion is opacity only, so nothing shifts under the pointer; the leaving content keeps its instance (no remount, no repeated effects) until it is gone.
+Motion is opacity only, so nothing shifts under the pointer; the leaving content keeps its instance (no remount, no repeated effects) until it is gone. Each state is a block formatting context, so it measures the same in flow and laid over as it leaves.
 
 ## Layout & spacing
 - No padding, gap or fill of its own: it sits where the swapped content would sit (inside `Card.Body`, a page section, a panel).
@@ -85,12 +86,16 @@ Motion is opacity only, so nothing shifts under the pointer; the leaving content
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Renders a plain `<div>`; pass `aria-busy` while the region loads and `aria-live` or `role` when its changes must be announced.
 - The leaving layer is `aria-hidden` and `inert`: screen readers and Tab never reach content that is going away.
-- Move focus yourself when the focused control was in the old state (e.g. the retry button of an error).
+- Focus in the old state (the retry button of an error) moves into the new one: its first tab stop, or the new content itself; focus elsewhere on the page stays where it is.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -103,6 +108,7 @@ No `labels`.
 | [overview.tsx](examples/overview.tsx) | A card region that cross-fades between loading, data, empty and error and glides to the new height — `state`. |
 | [record-switch.tsx](examples/record-switch.tsx) | A detail panel keyed by the record id: picking another client cross-fades the details of a different height — `state`. |
 | [fill.tsx](examples/fill.tsx) | A deal board that fills its panel's height while it swaps between loading and data, and a notice slot above it that takes no room while empty — `fill`, `state`. |
+| [screen.tsx](examples/screen.tsx) | Screen states: the title and the date of the statement in the app header, a page-level error in a Banner with a retry, a region loading with a Skeleton of its rows and a table skeleton, the table error in place and a first-run EmptyPage; regions cross-fade between states — `state`. |
 
 ## Mistakes
 - A new `state` on every data refresh (`state={Date.now()}`) → key by what the region shows, not by when it was fetched.
@@ -110,6 +116,7 @@ No `labels`.
 - A spinner block for content of known shape → a `Skeleton` of that shape; a spinner is for loading with no shape to hold (a button, a status line).
 - Wrapping a DataTable to animate its loading / empty / error → the table body already cross-fades; use its props.
 - Hand-written `opacity` transitions or `height` animations for a state swap → Crossfade owns both, with tokens and reduced motion.
+- An effect that moves focus out of a state that is going away (the retry button of an error) → Crossfade hands focus to the new state itself.
 - `height: 100%` on the content of a full-height region → `fill` on the Crossfade; its layers stretch.
 - Rendering an optional block conditionally outside Crossfade (`{notice && <Banner />}`) → it pops in and out; keep the Crossfade and pass `null` when there is nothing to show.
 

package/src/components/crossfade/examples/examples.module.css

@@ -16,7 +16,7 @@
   max-width: 100%;
 }
 
-/* Placeholder rows share the data rows' geometry: the swap to data does not change the height. */
+/* Placeholder bars share the data's geometry: the swap to data does not change the height. */
 .payerBar {
   width: 55%;
 }
@@ -25,38 +25,6 @@
   width: 20%;
 }
 
-.list {
-  display: grid;
-  margin: 0;
-  padding: 0;
-  list-style: none;
-}
-
-.listRow {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--prime-space-4);
-  padding-block: var(--prime-space-3);
-  border-bottom: var(--prime-border-width) solid var(--prime-color-border-subtle);
-}
-
-.listRow:last-child {
-  border-bottom: 0;
-}
-
-.amount {
-  font-variant-numeric: tabular-nums;
-}
-
-.facts {
-  display: grid;
-  gap: var(--prime-space-3);
-  margin: 0;
-  padding: 0;
-  list-style: none;
-}
-
 /* fill.tsx: a page panel of a fixed height; the board region takes what the rows above leave. */
 .fillPage {
   display: flex;
@@ -84,10 +52,3 @@
 .column {
   align-self: stretch;
 }
-
-.fact {
-  display: grid;
-  grid-template-columns: calc(var(--prime-space-24) + var(--prime-space-4)) minmax(0, 1fr);
-  align-items: baseline;
-  gap: var(--prime-space-4);
-}

package/src/components/crossfade/examples/fill.tsx

@@ -1,13 +1,5 @@
 /** A deal board that fills its panel's height while it swaps between loading and data, and a notice slot above it that takes no room while empty — `fill`, `state`. */
-import {
-  Banner,
-  Button,
-  Card,
-  Crossfade,
-  ScrollContainer,
-  Skeleton,
-  Typography,
-} from "prime-ui-kit";
+import { Banner, Button, Card, Crossfade, List, ScrollContainer, Skeleton } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -21,6 +13,7 @@ const STAGES = [
 export default function CrossfadeFillExample() {
   const [status, setStatus] = React.useState<"loading" | "ready">("ready");
   const [notice, setNotice] = React.useState<string | null>(null);
+  const [dealId, setDealId] = React.useState<string | null>(null);
 
   const refresh = () => {
     setNotice(null);
@@ -55,19 +48,23 @@ export default function CrossfadeFillExample() {
           <ScrollContainer className={styles.board}>
             {STAGES.map((stage) => (
               <Card.Root key={stage.id} className={styles.column}>
-                <Card.Body>
-                  <Typography as="h3" variant="title-s">
+                <Card.Header>
+                  <Card.Title as="h3">
                     {stage.title} · {stage.deals.length}
-                  </Typography>
-                  <ul className={styles.facts}>
+                  </Card.Title>
+                </Card.Header>
+                <Card.Body>
+                  <List.Root aria-label={stage.title}>
                     {stage.deals.map((deal) => (
-                      <li key={deal}>
-                        <Typography as="span" variant="body-m">
-                          {deal}
-                        </Typography>
-                      </li>
+                      <List.Item
+                        key={deal}
+                        current={deal === dealId}
+                        onClick={() => setDealId(deal)}
+                      >
+                        <List.ItemText>{deal}</List.ItemText>
+                      </List.Item>
                     ))}
-                  </ul>
+                  </List.Root>
                 </Card.Body>
               </Card.Root>
             ))}

package/src/components/crossfade/examples/overview.tsx

@@ -3,11 +3,11 @@ import {
   Button,
   Card,
   Crossfade,
+  DescriptionList,
   EmptyPage,
   Icon,
   SegmentedControl,
   Skeleton,
-  Typography,
 } from "prime-ui-kit";
 import * as React from "react";
 
@@ -43,29 +43,27 @@ export default function CrossfadeOverviewExample() {
         </Card.Header>
         <Card.Body>
           <Crossfade state={status} aria-busy={status === "loading"}>
+            {/* The placeholder is the same list with bars for the text: the swap keeps the height. */}
             {status === "loading" ? (
-              <ul className={styles.list}>
+              <DescriptionList.Root>
                 {PAYMENTS.map((payment) => (
-                  <li key={payment.id} className={styles.listRow}>
-                    <Skeleton className={styles.payerBar} />
+                  <DescriptionList.Item
+                    key={payment.id}
+                    label={<Skeleton className={styles.payerBar} />}
+                  >
                     <Skeleton className={styles.amountBar} />
-                  </li>
+                  </DescriptionList.Item>
                 ))}
-              </ul>
+              </DescriptionList.Root>
             ) : null}
             {status === "ready" ? (
-              <ul className={styles.list}>
+              <DescriptionList.Root>
                 {PAYMENTS.map((payment) => (
-                  <li key={payment.id} className={styles.listRow}>
-                    <Typography as="span" variant="body-m">
-                      {payment.payer}
-                    </Typography>
-                    <Typography as="span" variant="body-m" className={styles.amount}>
-                      {payment.amount}
-                    </Typography>
-                  </li>
+                  <DescriptionList.Item key={payment.id} label={payment.payer}>
+                    {payment.amount}
+                  </DescriptionList.Item>
                 ))}
-              </ul>
+              </DescriptionList.Root>
             ) : null}
             {status === "empty" ? (
               <EmptyPage.Root size="s" aria-labelledby="payments-empty">

package/src/components/crossfade/examples/record-switch.tsx

@@ -1,5 +1,5 @@
 /** A detail panel keyed by the record id: picking another client cross-fades the details of a different height — `state`. */
-import { Card, Crossfade, SegmentedControl, Typography } from "prime-ui-kit";
+import { Card, Crossfade, DescriptionList, SegmentedControl } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -47,18 +47,13 @@ export default function CrossfadeRecordSwitchExample() {
       <Card.Root variant="panel">
         <Card.Body>
           <Crossfade state={client.id}>
-            <ul className={styles.facts} aria-label={client.name}>
+            <DescriptionList.Root aria-label={client.name}>
               {client.facts.map(([term, value]) => (
-                <li key={term} className={styles.fact}>
-                  <Typography as="span" variant="body-s" tone="secondary">
-                    {term}
-                  </Typography>
-                  <Typography as="span" variant="body-m">
-                    {value}
-                  </Typography>
-                </li>
+                <DescriptionList.Item key={term} label={term}>
+                  {value}
+                </DescriptionList.Item>
               ))}
-            </ul>
+            </DescriptionList.Root>
           </Crossfade>
         </Card.Body>
       </Card.Root>

package/src/components/crossfade/examples/screen.module.css

@@ -0,0 +1,17 @@
+/* Screen states: the layout keeps its shape in every state, only the content of a region changes. */
+
+/* The banner and the panels as one block with no gap of its own: the 24 under the banner (the body's
+   block gap) lives in its slot inside the Crossfade, so it arrives and leaves with the banner. */
+.lead {
+  display: grid;
+  min-width: 0;
+}
+
+.bannerSlot {
+  padding-block-end: var(--prime-space-6);
+}
+
+/* A balance placeholder as wide as a balance, so the value column keeps its shape. */
+.balanceBar {
+  width: 35%;
+}

package/src/components/crossfade/examples/screen.tsx

@@ -0,0 +1,186 @@
+/** Screen states: the title and the date of the statement in the app header, a page-level error in a Banner with a retry, a region loading with a Skeleton of its rows and a table skeleton, the table error in place and a first-run EmptyPage; regions cross-fade between states — `state`. */
+import {
+  AppHeader,
+  Banner,
+  Button,
+  Card,
+  Crossfade,
+  DataTable,
+  type DataTableColumn,
+  DescriptionList,
+  EmptyPage,
+  Icon,
+  PageContent,
+  Skeleton,
+  Typography,
+  useNotifications,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./screen.module.css";
+
+type Status = "error" | "loading" | "ready";
+type Payment = { id: string; payer: string; purpose: string; amount: number };
+
+const PAYMENTS: Payment[] = [
+  { id: "b1", payer: "ООО «Гранит»", purpose: "Оплата по сч. 2026-0414", amount: 94_750 },
+  { id: "b2", payer: "ИП Орлов Д. С.", purpose: "Предоплата за обучение", amount: 18_000 },
+  { id: "b3", payer: "АО «Альфа Медиа»", purpose: "Без указания счёта", amount: 380_000 },
+];
+
+const ACCOUNTS = [
+  { name: "Т-Банк, расчётный", balance: "4 812 300 ₽" },
+  { name: "Сбербанк, расчётный", balance: "1 207 950 ₽" },
+];
+
+const MONEY = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+
+const COLUMNS: DataTableColumn<Payment>[] = [
+  { id: "payer", header: "Плательщик", accessor: "payer" },
+  { id: "purpose", header: "Назначение", accessor: "purpose" },
+  {
+    id: "amount",
+    header: "Сумма",
+    numeric: true,
+    headerAlign: "end",
+    cell: (row) => MONEY.format(row.amount),
+  },
+];
+
+export default function CrossfadeScreenExample() {
+  const { notify } = useNotifications();
+  const [status, setStatus] = React.useState<Status>("error");
+
+  const retry = () => {
+    setStatus("loading");
+    window.setTimeout(() => {
+      setStatus("ready");
+      notify({
+        tone: "success",
+        title: "Выписка получена",
+        description: "3 платежа ждут разнесения",
+      });
+    }, 1500);
+  };
+
+  return (
+    <>
+      {/* The header carries the page: the only h1 and a line of data, here the date of the last
+          statement — it moves on once the statement arrives. Main has no PageContent.Header. */}
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <AppHeader.Title>
+            Сверка с банком
+            <AppHeader.Description>
+              2 счёта · выписка на {status === "ready" ? "7" : "6"} октября
+            </AppHeader.Description>
+          </AppHeader.Title>
+        </AppHeader.Start>
+      </AppHeader.Root>
+
+      <PageContent.Root>
+        <PageContent.Body>
+          {/* The page banner and the panels are one block: the banner, with the 40 below it, comes and
+            goes inside a Crossfade, so the panels glide instead of jumping. */}
+          <div className={styles.lead}>
+            <Crossfade state={status === "error" ? "error" : "ok"}>
+              {status === "error" ? (
+                <div className={styles.bannerSlot}>
+                  <Banner.Root tone="danger">
+                    <Banner.Content>
+                      <Banner.Icon>
+                        <Icon name="status.danger" />
+                      </Banner.Icon>
+                      <Banner.Title>Выписка за 7 октября не получена</Banner.Title>
+                      <Banner.Description>
+                        Т-Банк не ответил на запрос. Остатки показаны на 6 октября.
+                      </Banner.Description>
+                      <Banner.Actions>
+                        <Button.Root tone="danger" onClick={retry}>
+                          Повторить
+                        </Button.Root>
+                      </Banner.Actions>
+                    </Banner.Content>
+                  </Banner.Root>
+                </div>
+              ) : null}
+            </Crossfade>
+
+            <PageContent.Grid>
+              <PageContent.Cell span={6}>
+                <Card.Root variant="panel" aria-busy={status === "loading"}>
+                  <Card.Header>
+                    <Card.Title as="h2">Остатки</Card.Title>
+                    <Typography as="span" variant="caption" tone="muted">
+                      {status === "ready" ? "на 7 октября" : "на 6 октября"}
+                    </Typography>
+                  </Card.Header>
+                  <Card.Body>
+                    {/* Loading ↔ data cross-fade in place; the table below swaps its body the same way. */}
+                    <Crossfade state={status === "loading" ? "loading" : "ready"}>
+                      {/* The accounts are known: only their balances wait, as bars of the value. */}
+                      <DescriptionList.Root>
+                        {ACCOUNTS.map((account) => (
+                          <DescriptionList.Item key={account.name} label={account.name}>
+                            {status === "loading" ? (
+                              <Skeleton className={styles.balanceBar} />
+                            ) : (
+                              account.balance
+                            )}
+                          </DescriptionList.Item>
+                        ))}
+                      </DescriptionList.Root>
+                    </Crossfade>
+                  </Card.Body>
+                </Card.Root>
+              </PageContent.Cell>
+
+              <PageContent.Cell span={6}>
+                <Card.Root variant="panel">
+                  <Card.Header>
+                    <Card.Title as="h2">Правила разнесения</Card.Title>
+                  </Card.Header>
+                  <Card.Body>
+                    <EmptyPage.Root size="s" aria-labelledby="rules-empty">
+                      <EmptyPage.Icon tone="accent">
+                        <Icon name="action.filter" />
+                      </EmptyPage.Icon>
+                      <EmptyPage.Title as="h3" id="rules-empty">
+                        Правил пока нет
+                      </EmptyPage.Title>
+                      <EmptyPage.Description>
+                        Правило свяжет платёж со счётом по ИНН или назначению.
+                      </EmptyPage.Description>
+                      <EmptyPage.Actions>
+                        <Button.Root variant="soft" tone="neutral">
+                          Создать правило
+                        </Button.Root>
+                      </EmptyPage.Actions>
+                    </EmptyPage.Root>
+                  </Card.Body>
+                </Card.Root>
+              </PageContent.Cell>
+            </PageContent.Grid>
+          </div>
+
+          <PageContent.Section label="Неразнесённые платежи">
+            <DataTable
+              columns={COLUMNS}
+              rows={status === "ready" ? PAYMENTS : []}
+              getRowKey={(row) => row.id}
+              paging="none"
+              loading={status === "loading"}
+              loadingRows={3}
+              loadError={status === "error" ? "Платежи появятся после загрузки выписки" : undefined}
+              empty="Все платежи разнесены"
+            />
+          </PageContent.Section>
+        </PageContent.Body>
+      </PageContent.Root>
+    </>
+  );
+}