prime-ui-kit 0.10.0 → 0.11.0

package/src/components/description-list/COMPONENT.md

@@ -0,0 +1,132 @@
+# DescriptionList
+
+**Category:** data-display
+**Kind:** composite
+
+> Read-only properties of a record: «label — value» pairs on a `<dl>` that stack by themselves where the room is narrow, with a muted dash for an empty value.
+
+## When to use
+- The details of a record in a card, a drawer or a page section: requisites, contacts, deal terms.
+- A summary before a confirm («Сумма», «Получатель», «Срок»).
+- Properties next to a value-specific action: copy an ИНН, call a number, write an email (`DescriptionList.ItemAction`).
+
+## When not to use
+- Values the user edits → fields ([Input](../input/COMPONENT.md), [Select](../select/COMPONENT.md)) in a form.
+- Many records with the same properties → [DataTable](../data-table/COMPONENT.md).
+- One headline number → [Card](../card/COMPONENT.md) `mini` / `stat-trend`.
+- A history of events → [Timeline](../timeline/COMPONENT.md).
+
+## Import
+```tsx
+import { DescriptionList } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+DescriptionList.Root                 <dl>; size (host tier), orientation; a size container
+└─ DescriptionList.Item              <div> per pair; label
+   ├─ <dt>                           the label
+   └─ <dd>                           the value (or labels.empty) · DescriptionList.ItemAction?
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### DescriptionList.Root
+`ref` → `HTMLDListElement`. A `<dl>` of «label — value» pairs and a size container: horizontal pairs stack once the list is narrower than 24rem. Gives its tier to the controls inside.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else `"m"`` | Label and value type and the gap between pairs; without it the list takes the tier of its host (a Card, a Drawer, a form). |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `horizontal` — the label in a column beside its value (one third of the width), stacking below 24rem of the list's own width; `vertical` — the label above its value at any width. |
+| `labels` | `Partial<DescriptionListLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLDListElement>` | — | `className`, `id`, `data-*` and the other attributes of the element. |
+
+### DescriptionList.Item
+`ref` → `HTMLDivElement`. One pair: a `<div>` holding the `<dt>` and the `<dd>`. The value wraps anywhere; no value (`null`, `""`, `false`) shows a muted `labels.empty` and speaks `labels.emptyText`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — (required) | The visible name of the value (`<dt>`). |
+| `children` | `ReactNode` | — | The value (`<dd>`): text, a Badge, a link; plus an optional `DescriptionList.ItemAction`, which goes to the end of the value. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `id`, `data-*` and the other attributes of the element. |
+
+### DescriptionList.ItemAction
+`ref` → `HTMLButtonElement`. A row action at the end of the value («Копировать», «Позвонить»): a ghost icon Button one tier below the list, with `label` as its name and tooltip.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — (required) | Accessible name and tooltip of the action. |
+| `children` | `ReactNode` | — (required) | The icon (`<Icon name="…" />`). |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children">` | — | `onClick`, `disabled`, `className` and the other button attributes. |
+
+## Variants
+
+### orientation
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `horizontal` | the label in a column (one third of the width) beside the value; stacked below 24rem of the list's width | record details in a card or a page | yes |
+| `vertical` | the label above its value at any width | a narrow side panel, a summary of a few long values | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` · `s` | label 12/16, value 12–13, pairs 8 apart | dense side panels, table expansions | |
+| `m` | label 13/20, value 14/20, pairs 12 apart | most cards and drawers | the host tier, else `m` |
+| `l` · `xl` | label 14/20, value 16/24, pairs 16 apart | a record page with room | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| size / orientation | props, the host tier | `data-size`, `data-orientation` on the `<dl>` |
+| narrow | the list narrower than 24rem (container query) | each pair stacks: the label above its value |
+| empty value | `children` is `null`, `""` or `false` | `data-empty` on the `<dd>`; muted `labels.empty`, spoken `labels.emptyText` |
+
+No motion: the list is static text; a row action has the Button's own press and hover.
+
+## Layout & spacing
+- The list fills its container; pairs are separated by air (8 · 12 · 16 by tier), not lines.
+- A horizontal pair: label column one third, value two thirds, 16 apart; values wrap anywhere, labels wrap too.
+- A row action sits at the end of the value, centred on its first line; it does not make the row taller.
+- Inside a `Card.Body` or a `Drawer` the list takes the host tier; do not pass `size` there.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves to the row actions (`DescriptionList.ItemAction`); the pairs themselves are not focusable. |
+| `Enter` · `Space` | Runs the row action. |
+
+### ARIA
+- The list is a `<dl>`: the label is a `<dt>`, the value a `<dd>`; screen readers read each pair as a term and its definition.
+- An empty value shows a muted `labels.empty` (hidden from assistive tech) and is read as `labels.emptyText`.
+- A row action is named by its `label`, which is also its tooltip; the icon is decorative.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `empty` | `"—"` | Visible mark of an empty value (muted, hidden from assistive tech). |
+| `emptyText` | `"Не указано"` | What assistive tech reads for an empty value. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A client's details in a card: labels beside values, a long address that wraps, an empty manager and a copy action — `DescriptionList.Item`, `label`, `DescriptionList.ItemAction`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier changes the label and value type and the gap between pairs — `size`. |
+| [structure.tsx](examples/structure.tsx) | Optional pieces of a pair: a Badge or a link as the value, a row action and an empty value with its own mark — `DescriptionList.ItemAction`, `labels`. |
+| [vertical.tsx](examples/vertical.tsx) | Labels above their values at any width, for a side panel of a record — `orientation`. |
+| [narrow.tsx](examples/narrow.tsx) | In a 320 px card the list is narrower than 24rem: each label moves above its value and long values wrap. |
+
+## Mistakes
+- A grid of `Typography` pairs or a two-column table for record details → `DescriptionList`: the `<dl>` semantics and the stacking come with it.
+- `""` or «—» typed by hand for a missing value → pass nothing; the list shows `labels.empty` and speaks `labels.emptyText`.
+- A copy button placed after the list or inside the label → `DescriptionList.ItemAction` inside the item, at the end of its value.
+- A viewport media query to stack the pairs → the list adapts to its own width already.
+
+## Related
+- **Built from:** [Button](../button/COMPONENT.md) (`ItemAction`), [Tooltip](../tooltip/COMPONENT.md) (the action's `label`)
+- **See also:** [Card](../card/COMPONENT.md) (the surface the list usually sits in), [Drawer](../drawer/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Timeline](../timeline/COMPONENT.md)

package/src/components/description-list/examples/examples.module.css

@@ -0,0 +1,41 @@
+/* Layout of the DescriptionList scenarios: semantic tokens only. */
+
+/* overview.tsx: a record card as wide as a dialog of size m. */
+.card {
+  width: min(100%, var(--prime-modal-width-m));
+}
+
+/* structure.tsx: a column as wide as a short form. */
+.column {
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+/* sizes.tsx: one tier per block, its caption right under it, blocks apart. */
+.sizes {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.size {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--prime-space-2);
+  min-width: 0;
+}
+
+.size > :first-child {
+  align-self: stretch;
+}
+
+/* vertical.tsx: a record side panel. */
+.side {
+  width: min(100%, var(--prime-drawer-width-s));
+}
+
+/* narrow.tsx: 320 px, the smallest supported viewport. */
+.narrow {
+  width: min(100%, calc(var(--prime-space-20) * 4));
+}

package/src/components/description-list/examples/narrow.tsx

@@ -0,0 +1,20 @@
+/** In a 320 px card the list is narrower than 24rem: each label moves above its value and long values wrap. */
+import { Card, DescriptionList } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DescriptionListNarrowExample() {
+  return (
+    <Card.Root className={styles.narrow}>
+      <Card.Body>
+        <DescriptionList.Root>
+          <DescriptionList.Item label="Компания">ООО «Северный ветер»</DescriptionList.Item>
+          <DescriptionList.Item label="Электронная почта">
+            finance.department@severny-veter-logistics.ru
+          </DescriptionList.Item>
+          <DescriptionList.Item label="Менеджер">{null}</DescriptionList.Item>
+        </DescriptionList.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/description-list/examples/overview.tsx

@@ -0,0 +1,35 @@
+/** A client's details in a card: labels beside values, a long address that wraps, an empty manager and a copy action — `DescriptionList.Item`, `label`, `DescriptionList.ItemAction`. */
+import { Card, DescriptionList, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const INN = "7704512398";
+
+export default function DescriptionListOverviewExample() {
+  return (
+    <Card.Root className={styles.card}>
+      <Card.Header>
+        <Card.Title>Реквизиты клиента</Card.Title>
+      </Card.Header>
+      <Card.Body>
+        <DescriptionList.Root>
+          <DescriptionList.Item label="Компания">ООО «Северный ветер»</DescriptionList.Item>
+          <DescriptionList.Item label="ИНН">
+            {INN}
+            <DescriptionList.ItemAction
+              label="Копировать ИНН"
+              onClick={() => navigator.clipboard?.writeText(INN)}
+            >
+              <Icon name="action.copy" />
+            </DescriptionList.ItemAction>
+          </DescriptionList.Item>
+          <DescriptionList.Item label="Телефон">+7 495 120-44-18</DescriptionList.Item>
+          <DescriptionList.Item label="Юридический адрес">
+            125167, г. Москва, Ленинградский проспект, д. 37, корп. 9, этаж 4, помещение XII
+          </DescriptionList.Item>
+          <DescriptionList.Item label="Менеджер">{null}</DescriptionList.Item>
+        </DescriptionList.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/description-list/examples/sizes.tsx

@@ -0,0 +1,24 @@
+/** Every tier changes the label and value type and the gap between pairs — `size`. */
+import { DescriptionList, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function DescriptionListSizesExample() {
+  return (
+    <div className={styles.sizes}>
+      {SIZES.map((size) => (
+        <div key={size} className={styles.size}>
+          <DescriptionList.Root size={size}>
+            <DescriptionList.Item label="Счёт">№ 4821 от 3 октября</DescriptionList.Item>
+            <DescriptionList.Item label="Сумма">94 750 ₽</DescriptionList.Item>
+          </DescriptionList.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/description-list/examples/structure.tsx

@@ -0,0 +1,29 @@
+/** Optional pieces of a pair: a Badge or a link as the value, a row action and an empty value with its own mark — `DescriptionList.ItemAction`, `labels`. */
+import { Badge, DescriptionList, Icon, LinkButton } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DescriptionListStructureExample() {
+  return (
+    <div className={styles.column}>
+      <DescriptionList.Root labels={{ empty: "Нет", emptyText: "Нет данных" }}>
+        <DescriptionList.Item label="Статус">
+          <Badge.Root color="green">Оплачен</Badge.Root>
+        </DescriptionList.Item>
+        <DescriptionList.Item label="Договор">
+          <LinkButton href="#contract-118">Договор № 118 от 12 марта</LinkButton>
+        </DescriptionList.Item>
+        <DescriptionList.Item label="Email">
+          finance@severny-veter.ru
+          <DescriptionList.ItemAction
+            label="Написать"
+            onClick={() => window.open("mailto:finance@severny-veter.ru")}
+          >
+            <Icon name="action.send" />
+          </DescriptionList.ItemAction>
+        </DescriptionList.Item>
+        <DescriptionList.Item label="Скидка">{null}</DescriptionList.Item>
+      </DescriptionList.Root>
+    </div>
+  );
+}

package/src/components/description-list/examples/vertical.tsx

@@ -0,0 +1,21 @@
+/** Labels above their values at any width, for a side panel of a record — `orientation`. */
+import { Card, DescriptionList } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DescriptionListVerticalExample() {
+  return (
+    <Card.Root className={styles.side}>
+      <Card.Body>
+        <DescriptionList.Root orientation="vertical">
+          <DescriptionList.Item label="Сделка">
+            Поставка оборудования, 2-й этап
+          </DescriptionList.Item>
+          <DescriptionList.Item label="Сумма">1 250 000 ₽</DescriptionList.Item>
+          <DescriptionList.Item label="Ответственный">Анна Ким</DescriptionList.Item>
+          <DescriptionList.Item label="Срок">15 ноября 2026</DescriptionList.Item>
+        </DescriptionList.Root>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/digit-input/COMPONENT.md

@@ -49,7 +49,7 @@ DigitInput            field frame: label row → cells → support row (hint | e
 | `value` | `string` | — | Controlled code; non-digits are dropped, extra digits cut to `length`. |
 | `defaultValue` | `string` | `""` | Initial code when uncontrolled. |
 | `onValueChange` | `(value: string) => void` | — | Called with the joined digits on every change. |
-| `onComplete` | `(value: string) => void` | — | Called once when the last empty cell is filled (typing, paste or autofill). |
+| `onComplete` | `(value: string) => void \| Promise<void>` | — | Called once when the last empty cell is filled (typing, paste or autofill). Return the check's promise: the cells wait read-only; resolve — the `success` look; reject — the code clears and the reason shows as the error. |
 | `fullWidth` | `boolean` | `false` | Cells share the container width up to 1.5 × their side (the row centres beyond that) and keep the tier height; otherwise square cells and the field hugs them. |
 | `groupSize` | `number` | — | Splits the cells into groups of this size with a wider gap (`3` → 123 456). |
 | `mask` | `boolean` | `false` | Hides the digits (PIN): cells are `type="password"`. |
@@ -85,7 +85,8 @@ No `variant` or `tone`.
 | `focusRing={false}` | no focus ring; the focus fill and the caret remain | a single code on a screen where focus is obvious | `true` |
 
 **Combinations**
-- Recommended: `error` set after a rejected code and cleared in `onValueChange`; `onComplete` to check the code as soon as it is filled.
+- Recommended: `onComplete` returning the check's promise — the field waits, shows success or clears and shows the reason; or, checking by hand, `error` set after a rejected code and cleared in `onValueChange`.
+- `error` and `success` you pass win over the `onComplete` check.
 - Pointless: `invalid` together with `error`; `length` larger than the real code.
 - Forbidden: `focusRing={false}` without another focus indicator (WCAG 2.4.7).
 
@@ -93,12 +94,14 @@ No `variant` or `tone`.
 | State | Driven by | DOM |
 |---|---|---|
 | hover | — | cell fill darkens (not on focused or disabled cells) |
-| focus | keyboard / click | focused cell: focus fill and its content selected so a new digit replaces it; one inset ring for the row appears on the cell and glides to the next one (`fast` · emphasized) instead of each cell drawing its own |
+| focus | keyboard / click | focused cell: focus fill and its content selected so a new digit replaces it; one inset ring for the row appears on the cell and glides to the next one (`fast` · emphasized) instead of each cell drawing its own; the code has no gaps, so focusing a cell past the first empty one moves focus to that entry cell |
 | filled cell | a digit in the cell | `data-filled="true"` on the cell; the digit fades in as it lands |
-| success | `success` (not while invalid) | `data-success="true"` on the fieldset; the cells turn `success-soft` one after another, half a stagger step apart |
+| checking | `onComplete` returned a pending promise | `aria-busy` and `data-pending="true"` on the fieldset, cells `readonly` and quiet to 0.6 (`fast`, both ways); typing waits for the answer |
+| refused | that promise rejected | the code clears and focus goes to the first cell; the reason (the rejection's message, else `labels.failed`) becomes the error (unless you pass `error`) and shakes in, a polite live region speaks it; typing again takes it away |
+| success | `success`, or a resolved `onComplete` promise (not while invalid) | `data-success="true"` on the fieldset (say it in words in `hint`); the cells turn `success-soft` one after another, half a stagger step apart |
 | full width | `fullWidth` | `data-full-width="true"` on the fieldset |
 | group start | `groupSize` | `data-group-start="true"` on the first cell of every group |
-| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the fieldset and the frame, `aria-invalid="true"` on cells; the control shakes once when an error arrives (`data-shake` on the frame) |
+| invalid | `invalid` or a non-empty `error` | `data-invalid="true"` on the fieldset and the frame, `aria-invalid="true"` on cells; the digits turn `danger-text` and the focus ring `danger-border`; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | `data-disabled="true"` and native `disabled` on the fieldset, every cell disabled, label and hint dimmed |
 | no focus ring | `focusRing={false}` | `data-focus-ring="false"` on the fieldset |
 
@@ -124,6 +127,7 @@ No `variant` or `tone`.
 - The cells sit in a `<fieldset>` (`role="group"`) named by the `label` (`aria-labelledby`) or `labels.group`; clicking the label focuses the first cell.
 - Each cell is named by `labels.cell` («Цифра 1 из 6») and has `autocomplete="one-time-code"` and `inputmode="numeric"`, so SMS codes are suggested on phones.
 - The hint or the error is linked to the group through `aria-describedby`; invalid cells carry `aria-invalid`.
+- While a code is checked the group has `aria-busy`; the reason of a refused code is spoken by a polite live region.
 - Paste and autofill of the whole code into any cell fill all cells.
 
 ### Labels
@@ -134,6 +138,7 @@ No `variant` or `tone`.
 | `group` | `"Код"` | Accessible name of the group when there is no visible `label`. |
 | `cell` | `"Цифра {index} из {length}"` | Accessible name of each cell; `{index}` (1-based) and `{length}` are replaced. |
 | `optional` | `"необязательно"` | Marker after the label when `optional`. |
+| `failed` | `"Неверный код"` | The error of a code whose `onComplete` promise rejected without a reason. |
 
 ## Examples
 | Example | Shows |
@@ -144,7 +149,7 @@ No `variant` or `tone`.
 | [validation.tsx](examples/validation.tsx) | A confirmation code checked once it is complete: a wrong code shakes in with one message and leaves as soon as you type again; a hint and an optional code — `required`, `optional`, `hint`, `error`. |
 | [grouped.tsx](examples/grouped.tsx) | A long code read in chunks with a wider gap between groups — `groupSize`. |
 | [full-width.tsx](examples/full-width.tsx) | Cells that share the container width and keep the tier height, above a full-width button — `fullWidth`. |
-| [on-complete.tsx](examples/on-complete.tsx) | The code is checked as soon as the last cell is filled: a right one turns the cells success, a wrong one turns the hint into an error — `onComplete`, `success`, `error`. |
+| [on-complete.tsx](examples/on-complete.tsx) | The code is checked on the server as soon as the last cell is filled: the cells wait, a right one turns them success, a wrong one clears them and shakes in the reason — `onComplete`, `hint`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the code and clears it with a button — `value`, `onValueChange`. |
 | [in-form.tsx](examples/in-form.tsx) | A masked card PIN submitted with a form; a short or wrong PIN shakes in an error that leaves when you type again — `name`, `mask`, `required`, `error`. |
 
@@ -153,6 +158,7 @@ No `variant` or `tone`.
 - A `Label` and a `Hint` placed next to the code by hand → pass `label`, `hint`, `error`.
 - Letters in the code → use `Input`; DigitInput accepts digits only.
 - Keeping `error` after the user edits the code → clear it in `onValueChange`.
+- A hand-made «checking…» state, a disabled field and a manual reset after a wrong code → return the check's promise from `onComplete`.
 
 ## Related
 - **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`)

package/src/components/digit-input/examples/on-complete.tsx

@@ -1,21 +1,33 @@
-/** The code is checked as soon as the last cell is filled: a right one turns the cells success, a wrong one turns the hint into an error — `onComplete`, `success`, `error`. */
+/** The code is checked on the server as soon as the last cell is filled: the cells wait, a right one turns them success, a wrong one clears them and shakes in the reason — `onComplete`, `hint`. */
 import { DigitInput } from "prime-ui-kit";
 import * as React from "react";
 
 const VALID_CODE = "123456";
 
+/** The server checking the code a beat later. */
+function verifyCode(code: string) {
+  return new Promise<void>((resolve, reject) => {
+    setTimeout(() => {
+      if (code === VALID_CODE) resolve();
+      else reject(new Error("Неверный код — попробуйте ещё раз"));
+    }, 900);
+  });
+}
+
 export default function DigitInputOnCompleteExample() {
-  const [result, setResult] = React.useState<"accepted" | "rejected">();
+  const [verified, setVerified] = React.useState(false);
 
   return (
     <DigitInput
       label="Код подтверждения входа"
       length={6}
-      hint={result === "accepted" ? "Код подтверждён" : `Для проверки подходит ${VALID_CODE}`}
-      error={result === "rejected" ? "Неверный код" : undefined}
-      success={result === "accepted"}
-      onValueChange={() => setResult(undefined)}
-      onComplete={(code) => setResult(code === VALID_CODE ? "accepted" : "rejected")}
+      // The success look is color: the hint says it in words.
+      hint={verified ? "Код подтверждён" : `Для проверки подходит ${VALID_CODE}`}
+      onValueChange={() => setVerified(false)}
+      onComplete={async (code) => {
+        await verifyCode(code);
+        setVerified(true);
+      }}
     />
   );
 }

package/src/components/divider/COMPONENT.md

@@ -110,4 +110,4 @@ No `labels`.
 
 ## Related
 - **Built from:** —
-- **See also:** [Dropdown](../dropdown/COMPONENT.md), [Card](../card/COMPONENT.md), [PageContent](../page-content/COMPONENT.md)
+- **See also:** [Dropdown](../dropdown/COMPONENT.md) (`Dropdown.Separator`), [Select](../select/COMPONENT.md) (`Select.Separator`), [Accordion](../accordion/COMPONENT.md), [Card](../card/COMPONENT.md), [PageContent](../page-content/COMPONENT.md)