prime-ui-kit 0.9.0 → 0.9.2

package/src/components/digit-input/examples/controlled.tsx

@@ -1,27 +1,18 @@
-/** The parent owns the code (`value` + `onValueChange`), so a button can reset it. Use it when the code must be cleared or validated from outside. */
-import { Button, DigitInput, Typography } from "prime-ui-kit";
+/** The parent owns the code and clears it with a button — `value`, `onValueChange`. */
+import { Button, DigitInput } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 export default function DigitInputControlledExample() {
-  const [code, setCode] = React.useState("");
+  const [code, setCode] = React.useState("73");
 
   return (
-    <div className={styles.cell}>
-      <DigitInput.Root
-        length={4}
-        value={code}
-        onValueChange={setCode}
-        labels={{ group: "PIN-код" }}
-      />
-      <Typography.Root variant="caption" tone="muted">
-        Значение: {code.length > 0 ? code : "пусто"} ({code.length}/4)
-      </Typography.Root>
+    <div className={styles.row}>
+      <DigitInput label="PIN-код терминала" value={code} onValueChange={setCode} />
       <Button.Root
-        variant="ghost"
+        variant="soft"
         tone="neutral"
-        size="s"
         disabled={code.length === 0}
         onClick={() => setCode("")}
       >

package/src/components/digit-input/examples/examples.module.css

@@ -1,50 +1,25 @@
-/* Layout helpers for the DigitInput examples. Semantic tokens only. */
+/* Layout of the DigitInput scenarios: semantic tokens only. */
 
-.sizesRow {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: flex-end;
-  justify-content: center;
-  gap: var(--prime-space-6);
-}
-
-.cell {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: var(--prime-space-2);
-}
-
-.statesGrid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--prime-panel-min-width)), 1fr));
-  justify-items: center;
-  gap: var(--prime-space-6) var(--prime-space-5);
-  width: 100%;
-  max-width: var(--prime-modal-width-l);
-}
-
-.field {
+/* full-width.tsx, in-form.tsx: a phone-width column, code above the action (group → action 24). */
+.panel {
   display: flex;
   flex-direction: column;
-  align-items: flex-start;
-  gap: var(--prime-space-2);
-}
-
-.card {
-  width: 100%;
-  max-width: var(--prime-modal-width-s);
+  gap: var(--prime-space-6);
+  width: min(100%, var(--prime-modal-width-s));
 }
 
+/* in-form.tsx: the form hugs the cells; as a grid item the button stretches to the code's width. */
 .form {
   display: grid;
-  gap: var(--prime-space-5);
+  gap: var(--prime-space-6);
+  width: fit-content;
+  max-width: 100%;
 }
 
-.actions {
+/* controlled.tsx: the code and its action on one line, bottoms aligned. */
+.row {
   display: flex;
   flex-wrap: wrap;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--prime-space-2);
+  align-items: flex-end;
+  gap: var(--prime-space-3);
 }

package/src/components/digit-input/examples/full-width.tsx

@@ -0,0 +1,13 @@
+/** Cells that share the container width and keep the tier height, above a full-width button — `fullWidth`. */
+import { Button, DigitInput } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DigitInputFullWidthExample() {
+  return (
+    <div className={styles.panel}>
+      <DigitInput label="Код из SMS" length={6} fullWidth />
+      <Button.Root fullWidth>Подтвердить</Button.Root>
+    </div>
+  );
+}

package/src/components/digit-input/examples/grouped.tsx

@@ -0,0 +1,11 @@
+/** A long code read in chunks with a wider gap between groups — `groupSize`. */
+import { DigitInput } from "prime-ui-kit";
+
+export default function DigitInputGroupedExample() {
+  return (
+    <>
+      <DigitInput label="Код из приложения" length={6} groupSize={3} defaultValue="482915" />
+      <DigitInput label="Резервный код" length={8} groupSize={4} />
+    </>
+  );
+}

package/src/components/digit-input/examples/in-form.tsx

@@ -0,0 +1,32 @@
+/** A masked card PIN submitted with a form; a short PIN shows an error — `name`, `mask`, `required`, `error`. */
+import { Button, DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PIN_LENGTH = 4;
+
+export default function DigitInputInFormExample() {
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const pin = String(new FormData(event.currentTarget).get("pin") ?? "");
+    setError(pin.length === PIN_LENGTH ? undefined : "Введите все четыре цифры");
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <DigitInput
+        label="PIN-код карты"
+        name="pin"
+        length={PIN_LENGTH}
+        mask
+        required
+        error={error}
+        onValueChange={() => setError(undefined)}
+      />
+      <Button.Root type="submit">Привязать карту</Button.Root>
+    </form>
+  );
+}

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

@@ -0,0 +1,20 @@
+/** The code is checked as soon as the last cell is filled; a wrong code turns the hint into an error — `onComplete`, `error`. */
+import { DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+const VALID_CODE = "123456";
+
+export default function DigitInputOnCompleteExample() {
+  const [error, setError] = React.useState<string>();
+
+  return (
+    <DigitInput
+      label="Код подтверждения входа"
+      length={6}
+      hint={`Для проверки подходит ${VALID_CODE}`}
+      error={error}
+      onValueChange={() => setError(undefined)}
+      onComplete={(code) => setError(code === VALID_CODE ? undefined : "Неверный код")}
+    />
+  );
+}

package/src/components/digit-input/examples/overview.tsx

@@ -0,0 +1,6 @@
+/** A six-digit code from SMS with its label and a hint — `label`, `hint`, `length`. */
+import { DigitInput } from "prime-ui-kit";
+
+export default function DigitInputOverviewExample() {
+  return <DigitInput label="Код из SMS" hint="Код действует 5 минут" length={6} />;
+}

package/src/components/digit-input/examples/sizes.tsx

@@ -1,26 +1,14 @@
-/** Five tiers in a row: the cell is square with the side equal to the control height (28 · 32 · 36 · 40 · 48). Match the size of the surrounding buttons and inputs. */
-import { DigitInput, Typography } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** Every size; the cell is a square on its own scale, two steps above the control heights — `size`. */
+import { DigitInput } from "prime-ui-kit";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function DigitInputSizesExample() {
   return (
-    <div className={styles.sizesRow}>
+    <>
       {SIZES.map((size) => (
-        <div key={size} className={styles.cell}>
-          <DigitInput.Root
-            size={size}
-            length={4}
-            defaultValue="2048"
-            labels={{ group: `Код, ${size}` }}
-          />
-          <Typography.Root variant="caption" tone="muted">
-            {size}
-          </Typography.Root>
-        </div>
+        <DigitInput key={size} size={size} label={size} defaultValue="2048" />
       ))}
-    </div>
+    </>
   );
 }

package/src/components/digit-input/examples/states.tsx

@@ -1,55 +1,11 @@
-/** Empty, partly filled, filled, invalid and disabled codes. Use it to check every state of a code field. */
-import { DigitInput, Typography } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** A default code next to a disabled one — `disabled`. */
+import { DigitInput } from "prime-ui-kit";
 
 export default function DigitInputStatesExample() {
   return (
-    <div className={styles.statesGrid}>
-      <div className={styles.cell}>
-        <DigitInput.Root length={4} labels={{ group: "Пустой код" }} />
-        <Typography.Root variant="caption" tone="muted">
-          Пустое
-        </Typography.Root>
-      </div>
-      <div className={styles.cell}>
-        <DigitInput.Root
-          length={4}
-          defaultValue="42"
-          labels={{ group: "Частично введённый код" }}
-        />
-        <Typography.Root variant="caption" tone="muted">
-          Частично заполнено
-        </Typography.Root>
-      </div>
-      <div className={styles.cell}>
-        <DigitInput.Root length={4} defaultValue="4207" labels={{ group: "Введённый код" }} />
-        <Typography.Root variant="caption" tone="muted">
-          Заполнено
-        </Typography.Root>
-      </div>
-      <div className={styles.cell}>
-        <DigitInput.Root
-          invalid
-          length={4}
-          defaultValue="1111"
-          labels={{ group: "Неверный код" }}
-        />
-        <Typography.Root variant="caption" tone="muted">
-          invalid
-        </Typography.Root>
-      </div>
-      <div className={styles.cell}>
-        <DigitInput.Root
-          length={4}
-          defaultValue="99"
-          disabled
-          labels={{ group: "Код недоступен" }}
-        />
-        <Typography.Root variant="caption" tone="muted">
-          disabled
-        </Typography.Root>
-      </div>
-    </div>
+    <>
+      <DigitInput label="default" defaultValue="42" />
+      <DigitInput label="disabled" defaultValue="42" disabled />
+    </>
   );
 }

package/src/components/digit-input/examples/validation.tsx

@@ -0,0 +1,17 @@
+/** Required and optional markers, a hint and an error that replaces it — `required`, `optional`, `hint`, `error`. */
+import { DigitInput } from "prime-ui-kit";
+
+export default function DigitInputValidationExample() {
+  return (
+    <>
+      <DigitInput label="Код из письма" required hint="Проверьте папку «Спам»" length={6} />
+      <DigitInput
+        label="Код подтверждения"
+        required
+        defaultValue="1111"
+        error="Неверный код, осталось 2 попытки"
+      />
+      <DigitInput label="Код приглашения" optional />
+    </>
+  );
+}

package/src/components/divider/COMPONENT.md

@@ -1,8 +1,9 @@
 # Divider
 
-**Category:** layout
+**Category:** page
+**Kind:** primitive
 
-> A hairline separator, horizontal or vertical, with or without a label.
+> A hairline separator inside one surface, horizontal or vertical, with or without a label.
 
 ## When to use
 - Separate rows of a list or groups inside one panel, menu or card.
@@ -12,93 +13,101 @@
 
 ## When not to use
 - To separate cards or panels from each other → use fill and spacing ([Card](../card/COMPONENT.md), [PageContent](../page-content/COMPONENT.md) sections), never a line.
-- Separators inside a dropdown menu → use `Dropdown.Separator` ([Dropdown](../dropdown/COMPONENT.md)).
+- Separators inside a dropdown menu → `Dropdown.Separator` ([Dropdown](../dropdown/COMPONENT.md)).
 - Row lines of a table → [DataTable](../data-table/COMPONENT.md) draws them itself.
-- Collapsible sections → use [Accordion](../accordion/COMPONENT.md).
 
 ## Import
 ```tsx
 import { Divider } from "prime-ui-kit";
 ```
 
+## Anatomy
+```
+Divider          <div role="separator">; the line is drawn by ::before / ::after
+└─ label         children (text, Icon) between the two line halves
+```
+
 ## API
 
-### Divider.Root
-`forwardRef` to `<div>`. No `asChild`.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Divider
+`ref` → `HTMLDivElement`. A `role="separator"` hairline in `border-subtle`; children become its label.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Full-width line in a column, or a vertical line that stretches to the height of a flex row. |
-| `align` | `"start" \| "center" \| "end"` | `"center"` | Position of the label on the line. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the surrounding content: label type, gap and icon size. |
-| `children` | `ReactNode` | — | Label (text, or icon + text). Without children the divider is a plain line. An `Icon` inside is sized by the divider, not by its own `size`. |
-| `role` | `string` | `"separator"` | Use `"presentation"` for decorative lines between rows of an already structured list. |
-| `className` | `string` | — | Extra class on the root. |
-
-+ native `<div>` props (`HTMLAttributes<HTMLDivElement>`).
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` stretches to the height of its flex row and sets `aria-orientation`. |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | Position of the label on the line; `start` reads as a section heading. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the label: type, gap and icon size. Match the content around the divider. |
+| `children` | `ReactNode` | — | Label: text, an `Icon`, or both. Omit for a plain line. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `role` (`"presentation"` for a purely visual line), `aria-label` and the other div attributes. |
 
 ## Variants
+No `variant`, `tone` or `color`: one hairline in `border-subtle`, label in `text-muted`, weight 500.
 
-### orientation
+### align
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `horizontal` | 1px `border-subtle` line across the full row width | Between rows or groups stacked in a column | yes |
-| `vertical` | 1px line stretched to the row height (`align-self: stretch`) | Between groups of buttons in a toolbar | |
+| `start` | label flush left, line to the right | a section heading on a line | |
+| `center` | line — label — line | «или», a date in a feed | yes |
+| `end` | line to the left, label flush right | an end marker | |
 
-### align (only with children)
+### orientation
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `start` | Label flush with the start edge, line fills the rest | Section heading on a line («Безопасность») | |
-| `center` | Line – label – line | «или» between alternatives | yes |
-| `end` | Line fills the start, label flush with the end edge | Trailing meta label (rare) | |
+| `horizontal` | full-width line | between rows and blocks | yes |
+| `vertical` | line as tall as its flex row | between toolbar groups | |
 
-### Content
+### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| no children | One plain line, no gap | List rows, groups | yes |
-| text / icon + text | Muted medium-weight label between line segments, tier gap | Headings, «или» | |
-
-**Combinations**
-- Recommended: plain horizontal line in a `gap` column; `align="start"` + icon + text as a section heading; `align="center"` + «или».
-- Pointless: `orientation="vertical"` with a long label; `align` without children (has no effect).
-
-**Sizes** — label / gap / icon per tier: xs 12/16 · 4 · 14, s 12/16 · 8 · 16, **m 13/20 · 8 · 16**, l 14/20 · 8 · 20, xl 16/24 · 12 · 20. Match the tier of the controls or text around it.
-
-**Hierarchy** — lines are the only separators in the system and stay `border-subtle`; do not stack several labelled dividers in a row, use one heading per group.
+| `xs` · `s` | label 12/16, caption tracking | dense menus, `s` content | |
+| `m` | label 13/20, icon 16 | regular content | yes |
+| `l` · `xl` | label 14/20 · 16/24, icon 20 | large panels | |
 
 ## States
-Static component. DOM: `data-orientation`, `data-align`, `data-size` on the root; `aria-orientation="vertical"` only for vertical dividers.
+| State | Driven by | DOM |
+|---|---|---|
+| plain line | no children | `:empty`, one line |
+| labelled | children | two line halves, each at least `--prime-space-6` long |
+| orientation / align / size | props | `data-orientation`, `data-align`, `data-size`, `aria-orientation` when vertical |
 
 ## Layout & spacing
-- Has no margins: the spacing around a line comes from the parent `gap` (e.g. `--prime-space-3` in a list column, `--prime-space-2` in a toolbar).
-- A horizontal divider takes `width: 100%` of a flex column; a vertical one needs a flex row parent to get height.
-- A long label wraps (`overflow-wrap: anywhere`).
+- No margins: the parent's `gap` sets the rhythm around the line.
+- Horizontal: `width: 100%` in its flex column. Vertical: `align-self: stretch` in a flex row.
+- Label gap and icon size follow the tier (`--prime-control-<size>-gap`, `-icon`).
 
 ## Accessibility
-- `role="separator"` by default; vertical dividers add `aria-orientation="vertical"`.
-- Use `role="presentation"` when the line is purely decorative inside a structured list.
-- No keyboard interaction, no `labels`.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [variants.tsx](examples/variants.tsx) | Plain line, `align` start · center · end, line in a gap column, vertical in a toolbar | Picking the right shape |
-| [sizes.tsx](examples/sizes.tsx) | `size` xs → xl with a start label | Matching the label to the content tier |
-| [composition.tsx](examples/composition.tsx) | «или» between buttons, heading with icon, presentation lines in a settings list | Separators inside one surface |
+### Keyboard
+No keyboard interaction.
 
-```tsx
-import { Divider } from "prime-ui-kit";
+### ARIA
+- `role="separator"`; vertical sets `aria-orientation="vertical"`.
+- A purely visual line between rows that are separate anyway → `role="presentation"`.
+- The label is read as the separator's text; an icon-only divider needs `aria-label`.
 
-export function Example() {
-  return <Divider.Root>или</Divider.Root>;
-}
-```
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Hairlines between the rows of a settings list. |
+| [sizes.tsx](examples/sizes.tsx) | The label at every tier, matching the content around it — `size`. |
+| [with-icon.tsx](examples/with-icon.tsx) | An icon before the label and an icon alone on the line; the divider sizes it. |
+| [align.tsx](examples/align.tsx) | The label at the start, the center or the end of the line; `start` heads a section — `align`. |
+| [vertical.tsx](examples/vertical.tsx) | A vertical line between groups of toolbar buttons — `orientation`. |
+| [or-separator.tsx](examples/or-separator.tsx) | An "or" line between two ways to sign in. |
 
 ## Mistakes
 - Margins on the divider → spacing via the parent `gap`.
 - Lines between cards → separate cards by fill and spacing.
 - `<Icon size="l" />` inside the label → leave the size to the divider.
-- Vertical divider in a block container (no height) → place it in a flex row.
+- A vertical divider in a block container (no height) → place it in a flex row.
 
 ## Related
-[Dropdown](../dropdown/COMPONENT.md) · [Card](../card/COMPONENT.md) · [PageContent](../page-content/COMPONENT.md)
+- **Built from:** —
+- **See also:** [Dropdown](../dropdown/COMPONENT.md), [Card](../card/COMPONENT.md), [PageContent](../page-content/COMPONENT.md)

package/src/components/divider/examples/align.tsx

@@ -0,0 +1,14 @@
+/** The label at the start, the center or the end of the line; `start` heads a section — `align`. */
+import { Divider } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DividerAlignExample() {
+  return (
+    <div className={styles.column}>
+      <Divider align="start">Уведомления</Divider>
+      <Divider>Сегодня</Divider>
+      <Divider align="end">Конец истории</Divider>
+    </div>
+  );
+}

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

@@ -1,33 +1,24 @@
-/* Layout for the Divider examples: layout only, text goes through Typography. */
+/* Layout of the Divider scenarios: semantic tokens only. */
 
+/* A column as wide as a short form: the lines need room to read as lines. */
 .column {
   display: grid;
-  gap: var(--prime-space-6);
-  width: 100%;
-  max-width: var(--prime-modal-width-s);
-}
-
-.group {
-  display: grid;
-  gap: var(--prime-space-2);
-}
-
-.lineSpacingColumn {
-  display: flex;
-  flex-direction: column;
   gap: var(--prime-space-3);
+  width: min(100%, var(--prime-modal-width-s));
 }
 
+/* vertical.tsx: the row stretches the vertical line to the buttons' height. */
 .toolbar {
   display: flex;
   align-items: center;
   gap: var(--prime-space-2);
-  width: fit-content;
 }
 
+/* overview.tsx */
 .list {
   display: flex;
   flex-direction: column;
+  width: min(100%, var(--prime-modal-width-s));
 }
 
 .listRow {
@@ -37,8 +28,3 @@
   gap: var(--prime-space-4);
   padding-block: var(--prime-space-3);
 }
-
-.stack {
-  display: grid;
-  gap: var(--prime-space-3);
-}

package/src/components/divider/examples/or-separator.tsx

@@ -0,0 +1,19 @@
+/** An "or" line between two ways to sign in. */
+import { Button, Divider, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DividerOrSeparatorExample() {
+  return (
+    <div className={styles.column}>
+      <Button.Root fullWidth>Войти</Button.Root>
+      <Divider>или</Divider>
+      <Button.Root variant="outline" tone="neutral" fullWidth>
+        <Button.Icon>
+          <Icon name="field.email" />
+        </Button.Icon>
+        Получить ссылку на почту
+      </Button.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,30 @@
+/** Hairlines between the rows of a settings list. */
+import { Divider, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const ROWS = [
+  { label: "Пароль", value: "Изменён 12 дней назад" },
+  { label: "Двухфакторный вход", value: "Включён" },
+  { label: "Активные сессии", value: "3 устройства" },
+];
+
+export default function DividerOverviewExample() {
+  return (
+    <div className={styles.list}>
+      {ROWS.map((row, index) => (
+        <div key={row.label}>
+          {index > 0 ? <Divider /> : null}
+          <div className={styles.listRow}>
+            <Typography as="span" variant="body-m">
+              {row.label}
+            </Typography>
+            <Typography as="span" variant="body-m" tone="secondary">
+              {row.value}
+            </Typography>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/divider/examples/sizes.tsx

@@ -1,17 +1,18 @@
-/** Divider label at every size tier xs → xl. Match `size` to the tier of the surrounding content. */
-import { Divider } from "prime-ui-kit";
+/** The label at every tier, matching the content around it — `size`. */
+import { Divider, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
-const sizes = ["xs", "s", "m", "l", "xl"] as const;
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function DividerSizesExample() {
   return (
-    <div className={styles.column}>
-      {sizes.map((size) => (
-        <Divider.Root align="start" key={size} size={size}>
-          Раздел · {size}
-        </Divider.Root>
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Divider size={size}>Раздел</Divider>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
       ))}
     </div>
   );

package/src/components/divider/examples/vertical.tsx

@@ -0,0 +1,21 @@
+/** A vertical line between groups of toolbar buttons — `orientation`. */
+import { Button, Divider } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function DividerVerticalExample() {
+  return (
+    <div className={styles.toolbar}>
+      <Button.Root variant="ghost" tone="neutral">
+        Вырезать
+      </Button.Root>
+      <Button.Root variant="ghost" tone="neutral">
+        Копировать
+      </Button.Root>
+      <Divider orientation="vertical" />
+      <Button.Root variant="ghost" tone="danger">
+        Удалить
+      </Button.Root>
+    </div>
+  );
+}