prime-ui-kit 0.3.2 → 0.4.1

package/src/components/data-table/examples/examples-demos.module.css

@@ -0,0 +1,78 @@
+/* Layout helpers for runnable examples (mirrors playground/snippets/data-table/*.module.css). */
+
+.demoLabel {
+  margin: var(--prime-sys-spacing-x4) 0 var(--prime-sys-spacing-x2);
+  font-size: var(--prime-sys-size-control-s-supportText);
+  font-weight: var(--prime-sys-typography-weight-medium);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.demoLabel:first-child {
+  margin-top: 0;
+}
+
+.demoTable {
+  margin-bottom: var(--prime-sys-spacing-x3);
+}
+
+.narrowCard {
+  box-sizing: border-box;
+  width: 100%;
+  max-width: 28rem;
+  padding: var(--prime-sys-spacing-x3);
+  border-radius: var(--prime-sys-shape-radius-m);
+  border: 1px dashed var(--prime-sys-color-border-subtle);
+}
+
+.lead {
+  margin: 0 0 var(--prime-sys-spacing-x3);
+  font-size: var(--prime-sys-size-control-s-supportText);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.leadTight {
+  margin: 0 0 var(--prime-sys-spacing-x2);
+  font-size: var(--prime-sys-size-control-s-supportText);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.statesStack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x6);
+  width: 100%;
+}
+
+.inlineIconRow {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--prime-sys-spacing-x2);
+}
+
+.inlineIconRowTight {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--prime-sys-spacing-x1);
+}
+
+.optionsFieldset {
+  margin: 0 0 var(--prime-sys-spacing-x4);
+  padding: var(--prime-sys-spacing-x3) var(--prime-sys-spacing-x4);
+  border: 1px solid var(--prime-sys-color-border-subtle);
+  border-radius: var(--prime-sys-shape-radius-m);
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-x4) var(--prime-sys-spacing-x6);
+}
+
+.optionsLegend {
+  padding: 0 var(--prime-sys-spacing-x2);
+  font-size: var(--prime-sys-typography-support-xs);
+}
+
+.optionLabel {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--prime-sys-spacing-x3);
+  cursor: pointer;
+}

package/src/components/data-table/examples/full-width.tsx

@@ -0,0 +1,39 @@
+import { DataTable, type DataTableColumn } from "prime-ui-kit";
+
+import styles from "./examples-demos.module.css";
+
+type Row = { id: string; task: string; hours: number };
+
+const rows: Row[] = [
+  { id: "T-12", task: "Сверстать отчёт по спринту", hours: 3 },
+  { id: "T-13", task: "Проверить миграции БД", hours: 1.5 },
+  { id: "T-14", task: "Обновить подсказки в форме входа", hours: 2 },
+];
+
+const columns: DataTableColumn<Row>[] = [
+  { id: "id", header: "Задача", accessor: "id", sortable: true, minWidth: "6rem" },
+  { id: "task", header: "Описание", accessor: "task", sortable: true, minWidth: "12rem" },
+  {
+    id: "hours",
+    header: "Часы",
+    accessor: "hours",
+    sortable: true,
+    align: "end",
+    minWidth: "5rem",
+    cell: (row) =>
+      row.hours.toLocaleString("ru-RU", { minimumFractionDigits: 0, maximumFractionDigits: 1 }),
+  },
+];
+
+/** Соответствует `playground/snippets/data-table/full-width.tsx`. */
+export default function DataTableFullWidthExample() {
+  return (
+    <div className={styles.narrowCard}>
+      <p className={styles.lead}>
+        Узкий контейнер: корень таблицы тянется на 100% ширины родителя (сетка карточки, колонка
+        формы).
+      </p>
+      <DataTable.Root columns={columns} rows={rows} showPagination={false} pageSize={10} />
+    </div>
+  );
+}

package/src/components/data-table/examples/highlight-and-striped.tsx

@@ -0,0 +1,71 @@
+import { DataTable, type DataTableColumn } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples-demos.module.css";
+
+type Row = { id: string; product: string; qty: number; price: number };
+
+const rows: Row[] = [
+  { id: "1", product: "Notebook", qty: 2, price: 1200 },
+  { id: "2", product: "Mouse", qty: 5, price: 45 },
+  { id: "3", product: "Keyboard", qty: 1, price: 180 },
+  { id: "4", product: "Display", qty: 1, price: 420 },
+];
+
+const columns: DataTableColumn<Row>[] = [
+  { id: "product", header: "Товар", accessor: "product", sortable: true, minWidth: "10rem" },
+  { id: "qty", header: "Кол-во", accessor: "qty", sortable: true, align: "end", minWidth: "6rem" },
+  {
+    id: "price",
+    header: "Цена",
+    accessor: "price",
+    sortable: true,
+    align: "end",
+    minWidth: "7rem",
+  },
+];
+
+/** Соответствует `playground/snippets/data-table/highlight-and-striped.tsx`. */
+export default function DataTableHighlightAndStripedExample() {
+  const [highlightRowOnHover, setHighlightRowOnHover] = React.useState(true);
+  const [highlightColumnOnHover, setHighlightColumnOnHover] = React.useState(false);
+  const [striped, setStriped] = React.useState(false);
+
+  return (
+    <div>
+      <fieldset className={styles.optionsFieldset}>
+        <legend className={styles.optionsLegend}>Опции таблицы</legend>
+        <label className={styles.optionLabel}>
+          <input
+            type="checkbox"
+            checked={highlightRowOnHover}
+            onChange={(e) => setHighlightRowOnHover(e.target.checked)}
+          />
+          Подсветка строки при наведении
+        </label>
+        <label className={styles.optionLabel}>
+          <input
+            type="checkbox"
+            checked={highlightColumnOnHover}
+            onChange={(e) => setHighlightColumnOnHover(e.target.checked)}
+          />
+          Подсветка колонки при наведении
+        </label>
+        <label className={styles.optionLabel}>
+          <input type="checkbox" checked={striped} onChange={(e) => setStriped(e.target.checked)} />
+          Чередование строк (зебра)
+        </label>
+      </fieldset>
+
+      <DataTable.Root
+        columns={columns}
+        rows={rows}
+        pageSize={10}
+        showPagination={false}
+        highlightRowOnHover={highlightRowOnHover}
+        highlightColumnOnHover={highlightColumnOnHover}
+        striped={striped}
+      />
+    </div>
+  );
+}

package/src/components/data-table/examples/sizes.tsx

@@ -0,0 +1,85 @@
+import { Badge, DataTable, type DataTableColumn, type DataTableSize, Tag } from "prime-ui-kit";
+
+import styles from "./examples-demos.module.css";
+
+type TeamRow = {
+  id: string;
+  member: string;
+  role: string;
+  team: string;
+  status: "Online" | "Offline" | "Busy" | "Away";
+};
+
+const rows: TeamRow[] = [
+  { id: "u1", member: "James Brown", role: "Product Manager", team: "Core", status: "Online" },
+  { id: "u2", member: "Sophia Williams", role: "Designer", team: "Growth", status: "Busy" },
+  { id: "u3", member: "Arthur Taylor", role: "Frontend Engineer", team: "Core", status: "Offline" },
+  { id: "u4", member: "Emma Wright", role: "QA Engineer", team: "Platform", status: "Away" },
+  {
+    id: "u5",
+    member: "Matthew Johnson",
+    role: "Data Engineer",
+    team: "Analytics",
+    status: "Online",
+  },
+];
+
+function mapStatusToBadge(status: TeamRow["status"]): "online" | "offline" | "busy" | "away" {
+  if (status === "Online") return "online";
+  if (status === "Offline") return "offline";
+  if (status === "Busy") return "busy";
+  return "away";
+}
+
+const columns: DataTableColumn<TeamRow>[] = [
+  { id: "member", header: "Member", accessor: "member", sortable: true, minWidth: "12rem" },
+  { id: "role", header: "Role", accessor: "role", sortable: true, minWidth: "12rem" },
+  {
+    id: "team",
+    header: "Team",
+    accessor: "team",
+    sortable: true,
+    minWidth: "9rem",
+    cell: (row) => <Tag.Root>{row.team}</Tag.Root>,
+  },
+  {
+    id: "status",
+    header: "Status",
+    accessor: "status",
+    sortable: true,
+    minWidth: "8rem",
+    cell: (row) => (
+      <Badge.Root variant="status" status={mapStatusToBadge(row.status)} label={row.status}>
+        {row.status}
+      </Badge.Root>
+    ),
+  },
+];
+
+function SizeRow({ size }: { size: DataTableSize }) {
+  return (
+    <>
+      <p className={styles.demoLabel}>size = {size}</p>
+      <DataTable.Root
+        className={styles.demoTable}
+        columns={columns}
+        rows={rows}
+        size={size}
+        pageSize={2}
+        paginationSize={size}
+      />
+    </>
+  );
+}
+
+/** Соответствует `playground/snippets/data-table/sizes.tsx`. */
+export default function DataTableSizesExample() {
+  return (
+    <>
+      <SizeRow size="s" />
+      <SizeRow size="m" />
+      <SizeRow size="l" />
+      <SizeRow size="xl" />
+    </>
+  );
+}

package/src/components/data-table/examples/sorting-pagination.tsx

@@ -0,0 +1,76 @@
+import { Badge, DataTable, type DataTableColumn, Tag } from "prime-ui-kit";
+
+type InvoiceRow = {
+  id: string;
+  customer: string;
+  amount: number;
+  country: string;
+  status: "Paid" | "Pending" | "Overdue";
+};
+
+const rows: InvoiceRow[] = [
+  { id: "INV-1001", customer: "Monday Inc.", amount: 1240, country: "USA", status: "Paid" },
+  { id: "INV-1002", customer: "Pixel Lab", amount: 860, country: "Germany", status: "Pending" },
+  { id: "INV-1003", customer: "Stella Team", amount: 2910, country: "Spain", status: "Paid" },
+  { id: "INV-1004", customer: "Nordic Grid", amount: 1490, country: "Sweden", status: "Pending" },
+  { id: "INV-1005", customer: "Onboardly", amount: 480, country: "France", status: "Overdue" },
+  { id: "INV-1006", customer: "Clever Peak", amount: 3010, country: "Canada", status: "Paid" },
+  { id: "INV-1007", customer: "Nimbus", amount: 1980, country: "UK", status: "Pending" },
+  { id: "INV-1008", customer: "Solar Crest", amount: 540, country: "Italy", status: "Overdue" },
+  { id: "INV-1009", customer: "Edge Point", amount: 2270, country: "USA", status: "Paid" },
+  { id: "INV-1010", customer: "Seven Loop", amount: 1750, country: "Poland", status: "Pending" },
+  { id: "INV-1011", customer: "Mint Dash", amount: 900, country: "Japan", status: "Paid" },
+  { id: "INV-1012", customer: "Blue Stone", amount: 1425, country: "Norway", status: "Overdue" },
+];
+
+function mapStatusToColor(status: InvoiceRow["status"]) {
+  if (status === "Paid") return "green";
+  if (status === "Overdue") return "red";
+  return "yellow";
+}
+
+const columns: DataTableColumn<InvoiceRow>[] = [
+  { id: "id", header: "Invoice", accessor: "id", sortable: true, minWidth: "8rem" },
+  { id: "customer", header: "Customer", accessor: "customer", sortable: true, minWidth: "12rem" },
+  {
+    id: "amount",
+    header: "Amount",
+    accessor: "amount",
+    sortable: true,
+    align: "end",
+    cell: (row) => `$${row.amount.toLocaleString()}`,
+    minWidth: "7rem",
+  },
+  {
+    id: "country",
+    header: "Country",
+    accessor: "country",
+    sortable: true,
+    minWidth: "8rem",
+    cell: (row) => <Tag.Root>{row.country}</Tag.Root>,
+  },
+  {
+    id: "status",
+    header: "Status",
+    accessor: "status",
+    sortable: true,
+    minWidth: "8rem",
+    cell: (row) => (
+      <Badge.Root color={mapStatusToColor(row.status)} variant="light">
+        {row.status}
+      </Badge.Root>
+    ),
+  },
+];
+
+/** Соответствует `playground/snippets/data-table/sorting-pagination.tsx`. */
+export default function DataTableSortingPaginationExample() {
+  return (
+    <DataTable.Root
+      columns={columns}
+      rows={rows}
+      defaultSort={{ columnId: "amount", order: "desc" }}
+      pageSize={5}
+    />
+  );
+}

package/src/components/data-table/examples/states.tsx

@@ -0,0 +1,44 @@
+import { DataTable, type DataTableColumn } from "prime-ui-kit";
+
+import styles from "./examples-demos.module.css";
+
+type Row = { id: string; label: string };
+
+const columns: DataTableColumn<Row>[] = [
+  { id: "id", header: "Код", accessor: "id", minWidth: "6rem" },
+  { id: "label", header: "Название", accessor: "label", minWidth: "12rem" },
+];
+
+/** Соответствует `playground/snippets/data-table/states.tsx`. */
+export default function DataTableStatesExample() {
+  return (
+    <div className={styles.statesStack}>
+      <div>
+        <p className={styles.leadTight}>
+          <code>loading</code> при пустом наборе строк: одна строка с <code>loadingText</code>.
+        </p>
+        <DataTable.Root
+          columns={columns}
+          rows={[]}
+          loading
+          loadingText="Загружаем справочник…"
+          showPagination={false}
+          pageSize={10}
+        />
+      </div>
+      <div>
+        <p className={styles.leadTight}>
+          Пустой список: <code>emptyText</code> вместо строк данных.
+        </p>
+        <DataTable.Root
+          columns={columns}
+          rows={[]}
+          loading={false}
+          emptyText="Пока нет ни одной записи — добавьте первую через кнопку «Создать»."
+          showPagination={false}
+          pageSize={10}
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/data-table/examples/sticky-and-headers.tsx

@@ -0,0 +1,113 @@
+import { DataTable, type DataTableColumn } from "prime-ui-kit";
+
+import styles from "./examples-demos.module.css";
+
+type ForecastRow = {
+  id: string;
+  metric: string;
+  q1: number;
+  q2: number;
+  q3: number;
+  q4: number;
+  plan: number;
+  fact: number;
+};
+
+const rows: ForecastRow[] = [
+  { id: "r1", metric: "Revenue", q1: 1200, q2: 1280, q3: 1330, q4: 1410, plan: 5220, fact: 5105 },
+  { id: "r2", metric: "COGS", q1: 530, q2: 560, q3: 575, q4: 610, plan: 2275, fact: 2290 },
+  { id: "r3", metric: "Gross Profit", q1: 670, q2: 720, q3: 755, q4: 800, plan: 2945, fact: 2815 },
+  { id: "r4", metric: "Marketing", q1: 190, q2: 205, q3: 215, q4: 230, plan: 840, fact: 875 },
+  { id: "r5", metric: "R&D", q1: 160, q2: 170, q3: 180, q4: 190, plan: 700, fact: 710 },
+  { id: "r6", metric: "G&A", q1: 120, q2: 124, q3: 128, q4: 133, plan: 505, fact: 498 },
+  {
+    id: "r7",
+    metric: "Operating Profit",
+    q1: 200,
+    q2: 221,
+    q3: 232,
+    q4: 247,
+    plan: 900,
+    fact: 732,
+  },
+  { id: "r8", metric: "Tax", q1: 34, q2: 37, q3: 41, q4: 44, plan: 156, fact: 149 },
+  { id: "r9", metric: "Net Profit", q1: 166, q2: 184, q3: 191, q4: 203, plan: 744, fact: 583 },
+  {
+    id: "r10",
+    metric: "Customers",
+    q1: 1240,
+    q2: 1310,
+    q3: 1425,
+    q4: 1560,
+    plan: 5535,
+    fact: 5440,
+  },
+];
+
+const columns: DataTableColumn<ForecastRow>[] = [
+  { id: "metric", header: "Metric", accessor: "metric", sortable: true, minWidth: "13rem" },
+  { id: "q1", header: "Q1", accessor: "q1", sortable: true, align: "end", minWidth: "7rem" },
+  { id: "q2", header: "Q2", accessor: "q2", sortable: true, align: "end", minWidth: "7rem" },
+  { id: "q3", header: "Q3", accessor: "q3", sortable: true, align: "end", minWidth: "7rem" },
+  { id: "q4", header: "Q4", accessor: "q4", sortable: true, align: "end", minWidth: "7rem" },
+  { id: "plan", header: "Plan", accessor: "plan", sortable: true, align: "end", minWidth: "8rem" },
+  { id: "fact", header: "Fact", accessor: "fact", sortable: true, align: "end", minWidth: "8rem" },
+];
+
+function money(value: number): string {
+  return value.toLocaleString("en-US");
+}
+
+const formattedColumns: DataTableColumn<ForecastRow>[] = columns.map((column) => {
+  if (column.id === "metric") return column;
+  return {
+    ...column,
+    cell: (row) => money(row[column.id as keyof ForecastRow] as number),
+  };
+});
+
+function DemoBlock({
+  title,
+  showHeader,
+  stickyHeader,
+  stickyFirstColumn,
+}: {
+  title: string;
+  showHeader?: boolean;
+  stickyHeader?: boolean;
+  stickyFirstColumn?: boolean;
+}) {
+  return (
+    <>
+      <p className={styles.demoLabel}>{title}</p>
+      <DataTable.Root
+        className={styles.demoTable}
+        columns={formattedColumns}
+        rows={rows}
+        showHeader={showHeader}
+        stickyHeader={stickyHeader}
+        stickyFirstColumn={stickyFirstColumn}
+        showPagination={false}
+        scrollHeight={220}
+        infiniteScroll
+        initialVisibleRows={10}
+      />
+    </>
+  );
+}
+
+/** Соответствует `playground/snippets/data-table/sticky-and-headers.tsx`. */
+export default function DataTableStickyAndHeadersExample() {
+  return (
+    <>
+      <DemoBlock title="showHeader = false (верхняя шапка скрыта)" showHeader={false} />
+      <DemoBlock title="stickyHeader = true (липкая верхняя шапка)" stickyHeader />
+      <DemoBlock title="stickyFirstColumn = true (липкая первая колонка слева)" stickyFirstColumn />
+      <DemoBlock
+        title="stickyHeader + stickyFirstColumn (как в Excel)"
+        stickyHeader
+        stickyFirstColumn
+      />
+    </>
+  );
+}

package/src/components/datepicker/COMPONENT.md

@@ -26,15 +26,38 @@ Composite pieces for picking a calendar date or range: a size-aware shell, a day
 
 ## Extended
 
-- **Booking (stay + time)** — Use **`mode="range"`** on both `Calendar` and `Presets`, optional **`Datepicker.Time`** with **`mode="range"`** for check-in/check-out times. Presets can encode “tonight”, multi-night spans, or month windows. Reference implementation: **`examples/booking.tsx`** (`BookingDateRangeExample`).
-- **Birthdate** — **`mode="single"`**; disable future days with react-day-picker **`disabled`** (for example `date >= startOfTomorrow()` from date-fns). Show a human-readable line with **`Datepicker.Value`**. Open the month near a sensible default (for example year **2000**) when no value yet. Reference: **`examples/birthdate.tsx`** (`BirthdateSingleExample`).
-- **Range (reports / filters)** — **`mode="range"`** with **`numberOfMonths={2}`** or **`responsiveMonths`** for width-driven columns; presets for “this month / last month / last N days”. Reference: **`examples/range-report.tsx`** (`ReportRangeExample`).
-- **Full-width form field** — **`Button.Root fullWidth`** as **`Popover.Trigger`**; widen **`Popover.Content`** (for example `min-w-[min(100vw-2rem,36rem)]` when your app uses Tailwind) and **`Datepicker.Shell className="min-w-0"`** so **`responsiveMonths`** measures correctly. Reference: **`examples/full-width-form.tsx`** (`FullWidthFormDateExample`).
+### Playground snippets
 
-Repository **`.tsx` examples** under **`examples/`** are type-checked with the library build; copy them into your app and wire your own spacing/theme (see [Label](../label/COMPONENT.md) for the label primitive).
+Demos match **`playground/sections/DatepickerSection.tsx`** (order and intent). Sources use `@/` imports under **`playground/snippets/datepicker/`**:
+
+| Block | File | What it shows |
+|-------|------|----------------|
+| **Sizes** | [`sizes.tsx`](../../../playground/snippets/datepicker/sizes.tsx) (+ [`sizes.module.css`](../../../playground/snippets/datepicker/sizes.module.css)) | Four **`Datepicker.Shell`** / **`Calendar`** **`size`** values (**`s`**–**`xl`**), each in its own **`Popover`**. |
+| **Variants and modes** | [`variants-modes.tsx`](../../../playground/snippets/datepicker/variants-modes.tsx) (+ [`sizes.module.css`](../../../playground/snippets/datepicker/sizes.module.css)) | **`mode="single"`** vs **`mode="range"`** with separate triggers. |
+| **States** | [`states.tsx`](../../../playground/snippets/datepicker/states.tsx) | **`disabled`** by day of week; **`Calendar`** + **`Datepicker.Time`** (time inputs disabled until a date exists). |
+| **Responsive months** | [`responsive-months.tsx`](../../../playground/snippets/datepicker/responsive-months.tsx) | **`responsiveMonths`**, **`responsiveBreakpoints`**; preview uses **`examplePreviewBleed`** for container width. |
+| **Controlled value** | [`controlled-value.tsx`](../../../playground/snippets/datepicker/controlled-value.tsx) | Controlled **`selected`** / **`onSelect`**; **`Datepicker.Value`**; popover closes after a date is chosen. |
+| **Composition** | [`composition.tsx`](../../../playground/snippets/datepicker/composition.tsx) | **`Shell`** **`presets`**, **`Calendar`**, **`Time`**, **`Value`** in one panel; shared parent state. |
+| **Full width** | [`full-width.tsx`](../../../playground/snippets/datepicker/full-width.tsx) | Wide **`Popover.Content`** and **`Datepicker.Shell className="min-w-0"`** with **`responsiveMonths`**. |
+| **Trigger with icon** | [`popover.tsx`](../../../playground/snippets/datepicker/popover.tsx) | Calendar icon on **`Popover.Trigger`**; close after single-date select. |
+| **Range presets + time** | [`range-presets-time.tsx`](../../../playground/snippets/datepicker/range-presets-time.tsx) | **`mode="range"`** on **`Calendar`** and **`Presets`**; **`Datepicker.Time`** with **`mode="range"`**. |
+
+### Scenarios (recipes)
+
+Runnable **`prime-ui-kit`** examples under **`examples/`** (type-checked with the library build). Copy into your app and wire spacing/theme (see [Label](../label/COMPONENT.md) for the label primitive).
+
+| Scenario | File |
+|----------|------|
+| **Booking (stay + time)** — **`mode="range"`** on **`Calendar`** and **`Presets`**, **`Datepicker.Time`** **`mode="range"`**; presets for short stays and windows | [`booking.tsx`](./examples/booking.tsx) (`BookingDateRangeExample`) |
+| **Birthdate** — **`mode="single"`**, **`disabled`** for future days, **`Datepicker.Value`**, default month near a sensible year when empty | [`birthdate.tsx`](./examples/birthdate.tsx) (`BirthdateSingleExample`) |
+| **Range (reports / filters)** — **`numberOfMonths={2}`** or **`responsiveMonths`**; presets such as this month / last month / last N days | [`range-report.tsx`](./examples/range-report.tsx) (`ReportRangeExample`) |
+| **Full-width form field** — **`Button.Root fullWidth`** as **`Popover.Trigger`**; wide **`Popover.Content`** and **`Shell className="min-w-0"`** | [`full-width-form.tsx`](./examples/full-width-form.tsx) (`FullWidthFormDateExample`) |
+
+Snippet-level demos (internal **`@/`** imports) are listed in **Playground snippets** above.
 
 ## LLM note
 
+- Playground order and copy mirror **`playground/sections/DatepickerSection.tsx`**; runnable snippet sources live in **`playground/snippets/datepicker/`**.
 - Always compose **`Datepicker.Shell` → `Datepicker.Calendar`** at minimum; never use **`Calendar` without `Shell`** in real UIs if you rely on **`size`** context (default **`m`** on `Shell`).
 - For overlays, default to **[Popover](../popover/COMPONENT.md)** with **`insetPadding="none"`** on content unless the design system specifies otherwise.
 - **Controlled state:** bind **`selected`** and **`onSelect`** from react-day-picker; for range, state type is **`DateRange | undefined`**.

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

@@ -10,7 +10,8 @@
 - **Размер ячеек:** **`size`**: `"s"` \| `"m"` \| `"l"` \| `"xl"` (по умолчанию **`m`**).
 - **Режимы:** контролируемый (`value` + `onChange`) или неконтролируемый (`defaultValue`); опционально **`onComplete`**, **`disabled`**, **`hasError`**, **`className`**.
 - **Подписи и ошибки:** снаружи — [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md); встроенных слотов нет.
-- **Примеры в репозитории:** [`examples/`](./examples/) (OTP, PIN, шаг верификации, ошибка, сброс при повторной отправке).
+- **Playground:** секция **`playground/sections/DigitInputSection.tsx`**; исходники демо — **`playground/snippets/digit-input/*.tsx`** (импорты **`@/`**). Сниппеты **`playground/snippets/slider-digit/`** относятся к **Slider** с режимом «цифры», а не к **DigitInput**.
+- **Примеры для копирования:** [`examples/`](./examples/) — продуктовые сценарии и зеркала сниппетов с импортом **`prime-ui-kit`**.
 
 ## Extended
 
@@ -26,6 +27,18 @@
 - **Do not use** for free-form numbers (amounts, phone as one field); this component is fixed-length, one digit per slot.
 - **Do not expect** arrow keys to move between cells; only typing, Backspace on an empty cell, and pointer focus apply.
 
+### Playground snippets
+
+Демо совпадают по порядку и смыслу с **`playground/sections/DigitInputSection.tsx`**. В сниппетах — импорты **`@/`**; зеркальные рецепты с **`prime-ui-kit`** — в **`examples/`** (та же разметка и пропы, раскладка через простой column flex и токены отступов).
+
+| Блок | Сниппет | Зеркало в `examples/` |
+| ---- | ------- | ---------------------- |
+| **Размеры** | [`sizes.tsx`](../../../playground/snippets/digit-input/sizes.tsx) | [`sizes.tsx`](./examples/sizes.tsx) — **`size`** **`s`**, **`m`**, **`l`**, **`xl`** при **`length={4}`** и одинаковом **`defaultValue`** для сравнения масштаба. |
+| **Состояния** | [`states.tsx`](../../../playground/snippets/digit-input/states.tsx) | [`states.tsx`](./examples/states.tsx) — без флагов, **`hasError`**, **`disabled`**. |
+| **Контролируемый режим** | [`controlled.tsx`](../../../playground/snippets/digit-input/controlled.tsx) | [`controlled.tsx`](./examples/controlled.tsx) — **`value`** + **`onChange`**, подпись со строкой и счётчиком **`(n/4)`**. |
+| **Композиция** | [`composition.tsx`](../../../playground/snippets/digit-input/composition.tsx) | [`composition.tsx`](./examples/composition.tsx) — **[Label](../label/COMPONENT.md)** + **DigitInput** + **[Hint](../hint/COMPONENT.md)** без слотов на корне. |
+| **Специфичные фичи** | [`features.tsx`](../../../playground/snippets/digit-input/features.tsx) | [`features.tsx`](./examples/features.tsx) — разные **`length`** / **`defaultValue`**, демо **`onComplete`** после последней цифры. |
+
 ### Composition
 
 - Public API is **`DigitInput.Root` only** (`DigitInput = { Root }`). There are no inner slots (`Label`, `Icon`, etc.) on this component.
@@ -42,7 +55,9 @@ export function OneTimeCode() {
 }
 ```
 
-### Scenario-oriented examples
+### Scenarios (recipes)
+
+Продуктовые сценарии (импорт **`prime-ui-kit`**). Для построчного соответствия демо плейграунда см. **Playground snippets** выше.
 
 | Сценарий | Файл |
 | -------- | ---- |
@@ -66,6 +81,7 @@ export function OneTimeCode() {
 
 ## LLM note
 
+- Для разметки и комбинаций пропов сначала смотри **`playground/snippets/digit-input/*.tsx`** и зеркала **`examples/sizes.tsx`**, **`states.tsx`**, **`controlled.tsx`**, **`composition.tsx`**, **`features.tsx`**.
 - Нормализация: в **`value` / `onChange` / paste** нецифровые символы **удаляются**, строка **обрезается** до **`length`**. Алфавитно-цифровые коды **не поддерживаются**.
 - **`onComplete(value)`** вызывается **один раз**, когда длина строки **впервые** стала **`length`**, будучи до этого **меньше**; при редактировании уже полной строки без укорочения **не** вызывается снова.
 - **Backspace** на **пустой** ячейке только **переносит фокус** назад; **не** стирает предыдущую цифру автоматически.

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

@@ -0,0 +1,24 @@
+import { DigitInput, Hint, Label } from "prime-ui-kit";
+
+/**
+ * Подпись и подсказка рядом с группой ячеек — типичный блок ввода кода в форме.
+ * Паритет с `playground/snippets/digit-input/composition.tsx`.
+ */
+export default function DigitInputCompositionExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: "var(--prime-sys-spacing-m)",
+      }}
+    >
+      <Label.Root size="m">Код из сообщения</Label.Root>
+      <DigitInput.Root length={4} size="m" />
+      <Hint.Root size="m" variant="default">
+        Вставьте код из буфера: цифры распределятся по ячейкам с текущей позиции.
+      </Hint.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,26 @@
+import { DigitInput } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Значение держит родитель: `value` и `onChange`; подпись показывает прогресс заполнения.
+ * Паритет с `playground/snippets/digit-input/controlled.tsx`.
+ */
+export default function DigitInputControlledExample() {
+  const [code, setCode] = React.useState("");
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "var(--prime-sys-spacing-s)",
+        alignItems: "flex-start",
+      }}
+    >
+      <DigitInput.Root length={4} value={code} onChange={setCode} />
+      <p style={{ margin: 0 }}>
+        Собранная строка: {code.length > 0 ? code : "пусто"} ({code.length}/4)
+      </p>
+    </div>
+  );
+}