prime-ui-kit 0.9.1 → 0.9.2

package/src/components/data-table/COMPONENT.md

@@ -10,6 +10,7 @@
 - Data that needs sorting, paging, bulk selection or a filter toolbar.
 - Hierarchical rows (`getRowChildren`) or rows with a detail panel (`renderExpanded`).
 - Wide numeric reports with a sticky head and first column.
+- Wide records on narrow screens: let people choose the columns (`hiddenColumns`) instead of dropping them.
 
 ## When not to use
 - One or two KPIs → use [Card](../card/COMPONENT.md).
@@ -28,7 +29,7 @@ Exported types: `DataTableColumn<Row>`, `DataTableProps<Row>`, `DataTableSortSta
 ```
 DataTable                           card-fill block, radius 12, clips its content
 ├── toolbar                         optional panel above the table (search, filters, bulk actions)
-├── scroll viewport                 ScrollContainer, both axes
+├── scroll viewport                 ScrollContainer, both axes, in a frame that holds the edge shadows
 │   └── table
 │       ├── thead                   [select all] [toggle] head cells; sortable heads hold a button
 │       └── tbody                   rows · sub-rows · detail rows · skeleton / empty / error row
@@ -46,6 +47,7 @@ Generic over `Row`; `ref` → `HTMLDivElement`. A card-fill block with an option
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `columns` | `DataTableColumn<Row>[]` | — (required) | Column definitions, see `DataTableColumn<Row>`. |
+| `hiddenColumns` | `string[]` | — | Ids of columns that are not rendered (head, body, skeleton and state rows); widths are measured again. A column with `hideable: false` stays. The list and the control that changes it (a column chooser in `toolbar`) belong to the consumer; sorting by a hidden column keeps the row order. |
 | `rows` | `Row[]` | — (required) | Data; sorted in memory when a sort is set. |
 | `getRowKey` | `(row: Row, index: number) => Key` | — | Stable row id (position by default); selection, expansion and the enter animation of new rows are keyed by it. Pass it whenever sorting, selection or expansion is used. |
 | `getRowLabel` | `(row: Row) => string` | — | Human row name for the checkbox and toggle names (`{label}` in `labels`). |
@@ -78,8 +80,8 @@ Generic over `Row`; `ref` → `HTMLDivElement`. A card-fill block with an option
 | `loadingMore` | `boolean` | `false` | A server batch is loading: footer status, `aria-busy`. |
 | `onLoadMore` | `() => void \| Promise<void>` | — | Called at the end when every loaded row is shown and `hasMore` is set. |
 | `scrollHeight` | `number \| string` | `360 with paging="infinite"` | Max height of the scroll viewport (number = px). |
-| `stickyHeader` | `boolean` | `false` | The head sticks while the body scrolls. |
-| `stickyFirstColumn` | `boolean` | `false` | The first column (with the selection and toggle columns) sticks while scrolling sideways. |
+| `stickyHeader` | `boolean` | `false` | The head sticks while the body scrolls (with `scrollHeight`); on screens lower than 480px it scrolls with the rows. |
+| `stickyFirstColumn` | `boolean` | `false` | The first visible column (with the selection and toggle columns) sticks while scrolling sideways; the start edge shadow falls from its end edge. |
 | `showHeader` | `boolean` | `true` | Render `<thead>`. |
 | `fullWidth` | `boolean` | `true` | The table spans its container; `false` sizes it by its content. |
 | `rowDividers` | `boolean` | `true` | Hairlines between rows. |
@@ -108,6 +110,7 @@ One column of `columns`: data, not a part.
 | `numeric` | `boolean` | — | Tabular figures, no wrapping, end alignment unless `align` is set. |
 | `truncate` | `boolean` | — | One line with an ellipsis; width from `maxWidth` (or `width`); string values get a `title`. |
 | `grow` | `boolean` | — | Takes the free width and wraps its text; the table then fills its container. With `minWidth` it never gets narrower: below that the table scrolls instead of cells overlapping. |
+| `hideable` | `boolean` | `true` | The column can be hidden through `hiddenColumns`; `false` for the key column that names the row. |
 | `width · minWidth · maxWidth` | `string` | — | CSS sizes of the column (`"14rem"`). |
 
 ## Variants
@@ -149,7 +152,8 @@ Heads keep `start` whatever the cell alignment, with the sort icon at the end ed
 | `striped` | every second row one opaque step off the fill | long numeric grids | `false` |
 | `highlightRowOnHover` | `fill-subtle` wash on the hovered row | interactive lists | `true` |
 | `highlightColumnOnHover` | `fill-subtle` wash on the hovered column | comparison tables | `false` |
-| `stickyHeader` · `stickyFirstColumn` | opaque sticky head / first column with a hairline edge | long / wide tables in a `scrollHeight` window | `false` |
+| `stickyHeader` · `stickyFirstColumn` | opaque sticky head / first column with a hairline edge; on screens lower than 480px the head scrolls with the rows | long / wide tables in a `scrollHeight` window | `false` |
+| column `hideable` | `false`: the column stays even when listed in `hiddenColumns` | the key column that names the row | `true` |
 | `showHeader` | head row shown | off only for self-explanatory key/value tables | `true` |
 | `fullWidth` | spans the container; `false` = content width | `false` for short lookup tables in wide layouts | `true` |
 | column `numeric` | tabular figures, end-aligned, no wrap | numbers, money | — |
@@ -166,15 +170,20 @@ Heads keep `start` whatever the cell alignment, with the sort icon at the end ed
 | selected | `selected` / `defaultSelected` | `aria-selected` rows with `accent-soft` fill; polite `labels.selectedCount` |
 | expanded | `expanded` / `defaultExpanded` | `data-expanded` on the parent row (one step darker); toggle `aria-expanded`, chevron turns 90° |
 | new rows | rows mounted by an expand or new in `rows` (by `getRowKey`) | `data-animate`: cells drop in from above (`enterMotion`); detail panels open and close through `grid-template-rows` (`data-state` on the detail row; it unmounts after the close) |
+| overflowing sideways | the table is wider than its viewport | `data-overflow-start` (scrolled from the start) and `data-overflow-end` (more to the end) on the root: a soft shadow over that edge, from the end edge of the sticky first column for the start; fades in and out over `fast` |
+| hidden columns | `hiddenColumns` | the listed columns (except `hideable: false`) are not rendered in the head, rows, skeleton or state rows; widths are measured again |
 | state swap | the body moves between loading, rows, empty and error | the body fades in over `base` (opacity only, the same swap motion as [Crossfade](../crossfade/COMPONENT.md)); the head stays still; nothing moves on the first render |
 
-Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data-sticky-header`, `data-sticky-first-column`, `data-table-width` (`fill` · `auto` · `grow`), `data-highlight-row`, `data-highlight-column`, `data-striped`, `data-loading`, `data-selectable`, `data-expandable`, `data-dragging` (while drag-selecting). Sorting and paging swap rows instantly; everything is still under `prefers-reduced-motion`.
+Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data-sticky-header`, `data-sticky-first-column`, `data-table-width` (`fill` · `auto` · `grow`), `data-highlight-row`, `data-highlight-column`, `data-striped`, `data-loading`, `data-selectable`, `data-expandable`, `data-dragging` (while drag-selecting), `data-overflow-start` · `data-overflow-end` (edges that hide columns). Sorting and paging swap rows instantly; everything is still under `prefers-reduced-motion`.
 
 ## Layout & spacing
 - The root fills its container on `--prime-color-card-bg`, radius 12, and clips full-bleed head and rows; on a card or a modal it becomes a sunken block — never wrap it in a Card.
 - Toolbar padding `--prime-space-3` × cell padding, items `gap: --prime-space-2`; below 30rem of table width toolbar and footer stack.
 - The footer has a hairline on top: range on the left, Pagination on the right. The range shows only with more than one page or with infinite scroll.
-- Columns scroll sideways inside the table; pin the identifying column with `stickyFirstColumn`. Works from 320 px.
+- Columns scroll sideways inside the table, never the page; pin the identifying column with `stickyFirstColumn`. Works from 320 px.
+- While columns are hidden past an edge, that edge shows a `--prime-space-4` shadow (the theme scrim at 40%) over the content; it takes no space and follows RTL. With `stickyFirstColumn` the start shadow falls from the pinned column's end edge.
+- Fewer columns, less scrolling: put a column chooser in `toolbar` (a Dropdown with a `Dropdown.CheckboxItem` per column, the key column `hideable: false` shown checked and disabled) and pass `hiddenColumns`. Never hide columns silently by width.
+- The sticky head stops sticking on screens lower than 480px (landscape phones), so it never takes a large share of the height.
 - Cell content: text, two-line text (title + `caption`), an Avatar with text, a Badge, or a control one tier down (`s` in an `m` table). Toolbar controls use `s` in an `m` table.
 - Column widths: `width` / `minWidth` / `maxWidth` strings; never size cells with custom CSS.
 - Sub-rows indent by `--dt-indent` per level (avatar of the tier + gap); override it on the root for other leading content.
@@ -225,6 +234,7 @@ Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data
 | [nested-rows.tsx](examples/nested-rows.tsx) | Partners with their expense lines: sub-rows indented under the parent's name, a chevron toggle, together with selection and sorting — `getRowChildren`, `expanded`, `onExpandedChange`. |
 | [detail-panel.tsx](examples/detail-panel.tsx) | Order details in a full-width row under an expanded order, aligned with the first content column — `renderExpanded`, `defaultExpanded`. |
 | [sticky.tsx](examples/sticky.tsx) | Monthly sales by region in a 280 px window: the head and the region column stay while scrolling both ways — `stickyHeader`, `stickyFirstColumn`, `scrollHeight`. |
+| [columns-visibility.tsx](examples/columns-visibility.tsx) | Orders with a column chooser in the toolbar: fewer columns, less sideways scrolling; the order number always stays — `hiddenColumns`, `hideable`, `toolbar`. |
 | [infinite-scroll.tsx](examples/infinite-scroll.tsx) | An audit log that reveals loaded rows in batches and then asks the server for more — `paging`, `infiniteBatchSize`, `hasMore`, `loadingMore`, `onLoadMore`. |
 | [states.tsx](examples/states.tsx) | Loading skeleton, an empty period and a load error with a retry: the head stays, only the body changes — `loading`, `loadingRows`, `empty`, `error`. |
 | [controlled.tsx](examples/controlled.tsx) | Sort and page owned by the parent (a URL or a store): a header click goes asc → desc → none, a new sort returns to page 1 — `sort`, `onSortChange`, `page`, `onPageChange`. |
@@ -239,6 +249,9 @@ Root attributes: `data-size`, `data-row-dividers`, `data-column-dividers`, `data
 - A custom checkbox column → use `selectable` (range, drag and announcements built in).
 - A long table in a `scrollHeight` window without `stickyHeader` → the head scrolls away.
 - `paging="none"` for hundreds of rows → use `pages` or `infinite`.
+- Dropping columns below a breakpoint → people lose data without knowing it; offer a column chooser with `hiddenColumns`.
+- Letting the key column be hidden → set `hideable: false` on it, so every row keeps its name.
+- Wrapping the table in an `overflow-x` box of your own → it already scrolls inside and shows the edge shadows.
 
 ## Related
 - **Built from:** [Checkbox](../checkbox/COMPONENT.md), [Button](../button/COMPONENT.md), [Pagination](../pagination/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md) (loading rows, in the table tier)

package/src/components/data-table/examples/columns-visibility.tsx

@@ -0,0 +1,167 @@
+/** Orders with a column chooser in the toolbar: fewer columns, less sideways scrolling; the order number always stays — `hiddenColumns`, `hideable`, `toolbar`. */
+import {
+  Badge,
+  Button,
+  DataTable,
+  type DataTableColumn,
+  Dropdown,
+  Icon,
+  Typography,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Status = "paid" | "shipped" | "waiting";
+type Order = {
+  id: string;
+  client: string;
+  manager: string;
+  city: string;
+  status: Status;
+  date: string;
+  items: number;
+  total: number;
+};
+
+const STATUS: Record<Status, { label: string; color: "green" | "blue" | "orange" }> = {
+  paid: { label: "Оплачен", color: "green" },
+  shipped: { label: "Отгружен", color: "blue" },
+  waiting: { label: "Ждёт оплаты", color: "orange" },
+};
+
+const ORDERS: Order[] = [
+  {
+    id: "№ 1040",
+    client: "ООО «Северный ветер»",
+    manager: "Ольга Смирнова",
+    city: "Москва",
+    status: "paid",
+    date: "02.10.2026",
+    items: 12,
+    total: 184_500,
+  },
+  {
+    id: "№ 1041",
+    client: "ИП Козлов",
+    manager: "Игорь Волков",
+    city: "Казань",
+    status: "waiting",
+    date: "03.10.2026",
+    items: 3,
+    total: 27_900,
+  },
+  {
+    id: "№ 1042",
+    client: "АО «Технопарк»",
+    manager: "Ольга Смирнова",
+    city: "Санкт-Петербург",
+    status: "shipped",
+    date: "04.10.2026",
+    items: 40,
+    total: 612_000,
+  },
+  {
+    id: "№ 1043",
+    client: "ООО «Лето»",
+    manager: "Мария Орлова",
+    city: "Екатеринбург",
+    status: "paid",
+    date: "05.10.2026",
+    items: 7,
+    total: 58_350,
+  },
+  {
+    id: "№ 1044",
+    client: "ООО «Гранит»",
+    manager: "Игорь Волков",
+    city: "Новосибирск",
+    status: "shipped",
+    date: "06.10.2026",
+    items: 18,
+    total: 241_800,
+  },
+];
+
+const RUB = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+
+const COLUMNS: DataTableColumn<Order>[] = [
+  { id: "id", header: "Заказ", accessor: "id", hideable: false },
+  { id: "client", header: "Клиент", accessor: "client" },
+  { id: "manager", header: "Менеджер", accessor: "manager" },
+  { id: "city", header: "Город", accessor: "city" },
+  {
+    id: "status",
+    header: "Статус",
+    cell: (row) => (
+      <Badge.Root color={STATUS[row.status].color}>{STATUS[row.status].label}</Badge.Root>
+    ),
+  },
+  { id: "date", header: "Дата", accessor: "date", numeric: true },
+  { id: "items", header: "Позиций", accessor: "items", numeric: true },
+  {
+    id: "total",
+    header: "Сумма",
+    accessor: "total",
+    sortable: true,
+    numeric: true,
+    cell: (row) => RUB.format(row.total),
+  },
+];
+
+export default function DataTableColumnsVisibilityExample() {
+  const [hidden, setHidden] = React.useState<string[]>(["city", "items"]);
+  const shown = COLUMNS.length - hidden.length;
+
+  const toggle = (id: string, visible: boolean) =>
+    setHidden((current) => (visible ? current.filter((c) => c !== id) : [...current, id]));
+
+  return (
+    <DataTable
+      columns={COLUMNS}
+      hiddenColumns={hidden}
+      rows={ORDERS}
+      getRowKey={(row) => row.id}
+      stickyFirstColumn
+      toolbar={
+        <div className={styles.toolbar}>
+          <Typography as="span" variant="body-s" tone="secondary">
+            Заказы за неделю: {ORDERS.length}
+          </Typography>
+          <Dropdown.Root>
+            <Dropdown.Trigger>
+              <Button.Root variant="outline" tone="neutral" size="s">
+                <Button.Icon>
+                  <Icon name="view.preview" />
+                </Button.Icon>
+                Колонки: {shown} из {COLUMNS.length}
+              </Button.Root>
+            </Dropdown.Trigger>
+            <Dropdown.Content align="end" size="s">
+              <Dropdown.Group label="Колонки таблицы">
+                {COLUMNS.map((column) => (
+                  <Dropdown.CheckboxItem
+                    key={column.id}
+                    checked={!hidden.includes(column.id)}
+                    disabled={column.hideable === false}
+                    onCheckedChange={(visible) => toggle(column.id, visible)}
+                  >
+                    {column.header}
+                  </Dropdown.CheckboxItem>
+                ))}
+              </Dropdown.Group>
+              <Dropdown.Separator />
+              <Dropdown.Item disabled={hidden.length === 0} onSelect={() => setHidden([])}>
+                Показать все
+              </Dropdown.Item>
+            </Dropdown.Content>
+          </Dropdown.Root>
+        </div>
+      }
+    />
+  );
+}

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

@@ -37,7 +37,7 @@ DigitInput            field frame: label row → cells → support row (hint | e
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `length` | `number` | `4` | Number of cells. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier: the cell is a square with the side of the control height (28 · 32 · 36 · 40 · 48); label and hint follow it. Without it the tier of its host (LoginForm, a panel), else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier: the cell is a square on its own scale, two steps above the control heights (36 · 40 · 48 · 56 · 64); label and hint follow the field tier. Without it the tier of its host (LoginForm, a panel), else `m`. |
 | `label` | `ReactNode` | — | Label above the cells; names the group (`aria-labelledby`) and focuses the first cell on click. Without it the group is named by `labels.group`. |
 | `required` | `boolean` | — | Red `*` after the label and native `required` on every cell. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
@@ -49,7 +49,7 @@ DigitInput            field frame: label row → cells → support row (hint | e
 | `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). |
-| `fullWidth` | `boolean` | `false` | Cells share the container width and keep the tier height; otherwise square cells and the field hugs them. |
+| `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"`. |
 | `name` | `string` | — | Name of a hidden input that carries the joined code in a native form submit. |
@@ -66,18 +66,18 @@ No `variant` or `tone`.
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | 28 × 28 cells, radius 6, digits 12/16, gap 4 | Inline confirmation inside dense tables or popovers | |
-| `s` | 32 × 32 cells, radius 8, digits 14/20, gap 8 | Compact dialogs | |
-| `m` | 36 × 36 cells, radius 8, digits 16/24, gap 8 | Regular forms and modals | yes |
-| `l` | 40 × 40 cells, radius 10, digits 18/24, gap 8 | Standalone verification screens | |
-| `xl` | 48 × 48 cells, radius 12, digits 20/28, gap 12 | Full-page sign-in, mobile-first screens | |
+| `xs` | 36 × 36 cells, radius 8, digits 16/24, gap 8 | A code inside a popover or a dense panel | |
+| `s` | 40 × 40 cells, radius 10, digits 18/24, gap 8 | Compact dialogs | |
+| `m` | 48 × 48 cells, radius 12, digits 20/28, gap 12 | Regular forms, modals, LoginForm | yes |
+| `l` | 56 × 56 cells, radius 12, digits 24/32, gap 12 | Standalone verification screens | |
+| `xl` | 64 × 64 cells, radius 16, digits 30/36, gap 16 | Full-page sign-in, mobile-first screens | |
 
-**Sizes:** digits are semibold and tabular, one type step larger than the tier text (`xs` uses the tier text). A cell of size T is as high as Input and Button of size T; the label and the hint take the same tier.
+**Sizes:** cells have their own scale, two steps above the control heights: a code is the one thing on its screen and a small cell is hard to hit and to read (cell `xs` = control `m`, `s` = control `l`, `m` = control `xl`). Digits are semibold and tabular and grow with the cell; the label and the hint keep the field tier.
 
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `fullWidth` | one row, cells share the width, tier height | cards, forms and narrow phone columns where a full-width button follows | `false` |
+| `fullWidth` | one row, cells share the width up to 1.5 × their side, then the row centres; tier height | narrow phone columns where a full-width button follows | `false` |
 | `groupSize` | an extra gap before every group (`3` → 123 456) | codes of six digits and longer | — |
 | `mask` | dots instead of digits | PIN codes | `false` |
 | `required` / `optional` | red `*` / muted «необязательно» after the label | mark the minority of the form | — |
@@ -137,7 +137,7 @@ No `variant` or `tone`.
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A six-digit code from SMS with its label and a hint — `label`, `hint`, `length`. |
-| [sizes.tsx](examples/sizes.tsx) | Every size; the cell is a square with the side of the control height — `size`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size; the cell is a square on its own scale, two steps above the control heights — `size`. |
 | [states.tsx](examples/states.tsx) | A default code next to a disabled one — `disabled`. |
 | [validation.tsx](examples/validation.tsx) | Required and optional markers, a hint and an error that replaces it — `required`, `optional`, `hint`, `error`. |
 | [grouped.tsx](examples/grouped.tsx) | A long code read in chunks with a wider gap between groups — `groupSize`. |

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

@@ -8,6 +8,14 @@
   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-6);
+  width: fit-content;
+  max-width: 100%;
+}
+
 /* controlled.tsx: the code and its action on one line, bottoms aligned. */
 .row {
   display: flex;

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

@@ -16,20 +16,17 @@ export default function DigitInputInFormExample() {
   };
 
   return (
-    <form className={styles.panel} noValidate onSubmit={submit}>
+    <form className={styles.form} noValidate onSubmit={submit}>
       <DigitInput
         label="PIN-код карты"
         name="pin"
         length={PIN_LENGTH}
         mask
         required
-        fullWidth
         error={error}
         onValueChange={() => setError(undefined)}
       />
-      <Button.Root type="submit" fullWidth>
-        Привязать карту
-      </Button.Root>
+      <Button.Root type="submit">Привязать карту</Button.Root>
     </form>
   );
 }

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

@@ -1,4 +1,4 @@
-/** Every size; the cell is a square with the side of the control height — `size`. */
+/** 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;

package/src/components/divider/COMPONENT.md

@@ -1,6 +1,6 @@
 # Divider
 
-**Category:** layout
+**Category:** page
 **Kind:** primitive
 
 > A hairline separator inside one surface, horizontal or vertical, with or without a label.

package/src/components/dnd/COMPONENT.md

@@ -1,6 +1,6 @@
 # Dnd
 
-**Category:** layout
+**Category:** interaction
 **Kind:** composite
 
 > Pointer-driven drag and drop: reorderable lists, draggable items and drop zones on one shared session, with a lifted clone, a gap where the item lands, auto-scroll, touch support and a keyboard path.
@@ -131,10 +131,10 @@ Generic `Dnd.DropZone<TData>`; `ref` → `HTMLElement`. Renders the `as` element
 | State | Driven by | DOM |
 |---|---|---|
 | idle | — | items show `cursor: grab` |
-| carried | a drag | the clone follows the pointer, lifted on `--prime-shadow-modal`, scale 1.02; a sortable source leaves the layout (`data-lifted`) and a dashed accent gap of its size and radius fades in; neighbours glide aside; a `Dnd.Draggable` stays at 0.4 opacity (`data-dragging`) |
+| carried | a drag | the clone follows the pointer, lifted on `--prime-shadow-modal`, scale 1.02; a sortable source leaves the layout (`data-lifted`) and a dashed accent gap of its size and radius fades in and glides with the items as the landing spot moves; entering a connected list, it fades out in the list it left and in where it opens; crossing empty space (the gutter between lists) leaves the gap in the last list that takes the item; neighbours glide aside; a `Dnd.Draggable` stays at 0.4 opacity (`data-dragging`) |
 | over a zone | pointer over an accepting zone | `data-dnd-over`: `accent-soft` fill, dashed accent outline |
 | refused | `canDrop` returns `false` | `data-dnd-reject`: `danger-soft` fill; the clone gets a dashed `danger` outline |
-| dropped | release | the clone glides to the item's new place and is swapped for the real element; `data-dnd-flash` with `flashOnDrop` |
+| dropped | release over a target, or over empty space while a list holds the gap | the clone glides to the item's new place and is swapped for the real element; `data-dnd-flash` with `flashOnDrop` |
 | cancelled | Escape, a system-cancelled pointer | the clone flies back, nothing changes |
 | disabled | `disabled` | `data-disabled`, no `aria-roledescription` |
 

package/src/components/drawer/COMPONENT.md

@@ -3,13 +3,14 @@
 **Category:** overlays
 **Kind:** overlay
 
-> A modal side panel that slides in from the edge: filters, forms and record details.
+> A modal panel that slides in from the edge: filters, forms and record details at the side, a bottom sheet on a phone.
 
 ## When to use
 - Editing settings or a record without leaving the page.
 - Filters or navigation on narrow screens (`side="left"`).
 - Read-only details of a list row (order, user, event).
 - Long content (history, logs) that needs a tall scrolling area.
+- A short task on a phone — pick a date, choose an action, fill two fields — in a bottom sheet (`side="bottom"`).
 
 ## When not to use
 - Confirmations and short decisions → use [Modal](../modal/COMPONENT.md).
@@ -27,6 +28,7 @@ import { Drawer } from "prime-ui-kit";
 Drawer.Root                    state and dismiss policy (no DOM)
 ├─ Drawer.Trigger              clones its child; opens on click
 └─ Drawer.Content              portal + scrim + role="dialog" panel at the edge
+   ├─ (grab handle)            side="bottom" only: aria-hidden bar, a drag starts here
    ├─ Drawer.Header            grid: [Icon] [Title + Description] [close Button]
    │  ├─ Drawer.Icon
    │  ├─ Drawer.Title          <h2>
@@ -49,7 +51,7 @@ No DOM, no ref. State and dismiss policy.
 | `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
 | `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, close button, `Close`, Escape, scrim click, code. |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the dialog. |
-| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim closes the dialog; turn off for destructive confirms. |
+| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim (and a swipe on a bottom sheet) closes the dialog; turn off for destructive confirms. |
 | `labels` | `Partial<DrawerLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — | Trigger and Content. |
 
@@ -58,8 +60,8 @@ No DOM, no ref. State and dismiss policy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `side` | `"left" \| "right"` | `"right"` | Edge the panel slides from; rounded only on the edge facing the page. |
-| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Width: 360 · 480 · 640 · 800. Below 640 px of viewport — full width, square corners. |
+| `side` | `"left" \| "right" \| "bottom"` | `"right"` | Edge the panel slides from; rounded only on the edge facing the page. `bottom` is a sheet: a grab handle on top, height by content. A swipe toward the edge closes the panel (with `closeOnOutsideClick`): a bottom sheet from its handle or header, a side drawer by touch anywhere (by mouse from the header). |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | Width: 360 · 480 · 640 · 800; a bottom sheet is centred and at least 560 (`--prime-sheet-min-width`). Below 640 px of viewport — full width; side drawers lose their corners. |
 | `aria-label` | `string` | — | Dialog name when there is no Title. |
 | `aria-labelledby` | `string` | — | Overrides the Title id. |
 | `aria-describedby` | `string` | — | Overrides the Description id. |
@@ -94,7 +96,7 @@ No DOM, no ref. State and dismiss policy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `layout` | `"fill" \| "end"` | `"end"` | `fill`: equal-width buttons in one row; `end`: auto width, at the end. Narrower than 360 px — stacked. |
+| `layout` | `"fill" \| "end"` | `"end"` | `fill`: equal-width buttons in one row; `end`: auto width, at the end. Stacked on phones (viewport below 640 px) and in a dialog narrower than 360 px. |
 
 ### Drawer.Trigger · Drawer.Close
 No DOM: clone the single child and chain its `onClick` (unless the child's handler calls `preventDefault()`).
@@ -110,6 +112,7 @@ No DOM: clone the single child and chain its `onClick` (unless the child's handl
 |---|---|---|---|
 | `right` | slides from the right, rounded on its left edge | details and forms | yes |
 | `left` | slides from the left, rounded on its right edge | filters, mobile navigation | |
+| `bottom` | rises from the bottom, rounded on top, grab handle, height by content | a short task on a phone | |
 
 ### size (Content)
 | Value | Looks like | Use when | Default |
@@ -119,7 +122,7 @@ No DOM: clone the single child and chain its `onClick` (unless the child's handl
 | `l` | 640 wide | wide forms | |
 | `xl` | 800 wide | tables, previews | |
 
-Below 640px of viewport every size is full width with square corners.
+A bottom sheet is centred at its width, never narrower than 560 (`--prime-sheet-min-width`), so a tablet gets a real sheet. Below 640px of viewport every size is full width; side drawers lose their corners, the sheet keeps its top radius.
 
 ### layout (Footer)
 | Value | Looks like | Use when | Default |
@@ -135,13 +138,15 @@ Below 640px of viewport every size is full width with square corners.
 |---|---|---|
 | open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state` on the scrim and the panel; mounted until the slide-out ends |
 | side / size | Content props | `data-side`, `data-size` on the panel |
+| swiping | a drag toward the edge (with `closeOnOutsideClick`) | `data-swiping` and `--swipe-offset` on the panel while the pointer drags it; `data-swipe-dismissed` while it glides out after a closing release; `--swipe-progress` (0…1) on the scrim |
 | open: trapped | while open | focus trapped, page scroll locked, siblings of the portal `inert` (the toast region stays usable); a drawer opened from a Modal or another drawer stacks above it |
 
-Motion: the scrim fades, the panel slides from its side over `slow` and leaves over `base` (`overlayMotion`); under `prefers-reduced-motion` it unmounts at once.
+Motion: the scrim fades, the panel slides from its side over `slow` and leaves over `base` (`overlayMotion`); under `prefers-reduced-motion` it unmounts at once. A swipe moves the panel with the pointer; on release it closes past 30% of its size or on a quick flick and glides the rest of the way out from where it was let go, otherwise it glides back — both over `base` on the `emphasized` (iOS sheet) curve. A pull the other way meets growing resistance and stops at 24; the panel's fill continues that far past the screen edge, so it never comes away from it. The scrim follows the panel: its fill thins in proportion to how far out the panel is, tracks the finger while dragging and glides with the panel on release. A bottom sheet drags from its handle or header; a side drawer by touch anywhere (not on text fields, sliders or sideways scrollers), by mouse from the header.
 
 ## Layout & spacing
 - Zone padding `--prime-drawer-padding`; hairlines between header, body and footer.
 - Full viewport height; only the body scrolls, with its own side padding.
+- Bottom sheet: width by `size`, at least `--prime-sheet-min-width` (560); height by content up to `100dvh − --prime-sheet-top-gap`, radius `--prime-sheet-radius`, a `--prime-sheet-handle-area` strip with the handle bar, the bottom safe-area inset below the content.
 - Fields inside get the surface field fill.
 
 ## Accessibility
@@ -157,6 +162,7 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 - Focus moves into the panel on open and returns to the opener on close, including after a scrim click.
 - The page behind is `inert`, scroll is locked; only the topmost layer reacts.
 - A drawer opened from a Modal stacks above it.
+- A swipe toward the edge is an extra way out; the close button and Escape stay. The grab handle is `aria-hidden`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -171,7 +177,8 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 | [overview.tsx](examples/overview.tsx) | Order details next to the list: a trigger, a header with a close button and a read-only body — `Drawer.Trigger`, `Drawer.Body`. |
 | [structure.tsx](examples/structure.tsx) | Optional parts: an icon tile in the header and one full-width action in the footer — `Drawer.Icon`, `Drawer.Footer`, `layout`. |
 | [sizes.tsx](examples/sizes.tsx) | Every panel width, 360 to 800 px; below 640 px of viewport the panel takes the full width — `size`. |
-| [placement.tsx](examples/placement.tsx) | The panel slides from the right for details and from the left for filters — `side`. |
+| [placement.tsx](examples/placement.tsx) | The panel slides from the right for details, from the left for filters and up from the bottom as a sheet — `side`. |
+| [date-sheet.tsx](examples/date-sheet.tsx) | A date picked in a bottom sheet: a grab handle on top, a swipe down or a pick closes it — `side`, `Drawer.Body`. |
 | [long-content.tsx](examples/long-content.tsx) | A long body scrolls on its own while the header and the footer stay in place — `Drawer.Body`. |
 | [dismiss.tsx](examples/dismiss.tsx) | An import closes only from its buttons, and not at all while it runs — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the state and opens the drawer from a link, without a trigger — `open`, `onOpenChange`. |
@@ -180,7 +187,8 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 ## Mistakes
 - A delete confirmation in a Drawer → use Modal.
 - Expecting Enter to submit via `Drawer.Confirm` → Drawer has no Confirm; use a `<form>` with a submit button.
-- `side="top"` / `"bottom"` → only `left` and `right`.
+- `side="top"` → only `left`, `right` and `bottom`.
+- Swipe as the only way to close → keep `Drawer.Header` with its close button (or `Drawer.Close`); a swipe is an extra gesture.
 - Padding on a wrapper inside Body → Body already pads and scrolls.
 
 ## Related

package/src/components/drawer/examples/date-sheet.tsx

@@ -0,0 +1,41 @@
+/** A date picked in a bottom sheet: a grab handle on top, a swipe down or a pick closes it — `side`, `Drawer.Body`. */
+import { Button, Datepicker, Drawer, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const FORMAT = new Intl.DateTimeFormat("ru-RU", { day: "numeric", month: "long", year: "numeric" });
+
+export default function DrawerDateSheetExample() {
+  const [open, setOpen] = React.useState(false);
+  const [date, setDate] = React.useState<Date | null>(new Date(2026, 2, 8));
+
+  return (
+    <Drawer.Root open={open} onOpenChange={setOpen}>
+      <Drawer.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          <Button.Icon>
+            <Icon name="field.calendar" />
+          </Button.Icon>
+          {date ? `Отгрузка ${FORMAT.format(date)}` : "Дата отгрузки"}
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Content side="bottom">
+        <Drawer.Header>
+          <Drawer.Title>Дата отгрузки</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Body>
+          <Datepicker.Panel
+            mode="single"
+            className={styles.calendar}
+            value={date}
+            onValueChange={(next) => {
+              setDate(next);
+              setOpen(false);
+            }}
+          />
+        </Drawer.Body>
+      </Drawer.Content>
+    </Drawer.Root>
+  );
+}

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

@@ -19,3 +19,8 @@
   margin: 0;
   font-variant-numeric: tabular-nums;
 }
+
+/* date-sheet.tsx: the calendar keeps its own width, centred in the sheet. */
+.calendar {
+  align-self: center;
+}

package/src/components/drawer/examples/placement.tsx

@@ -1,9 +1,10 @@
-/** The panel slides from the right for details and from the left for filters — `side`. */
+/** The panel slides from the right for details, from the left for filters and up from the bottom as a sheet — `side`. */
 import { Button, Drawer, Typography } from "prime-ui-kit";
 
 const SIDES = [
   { side: "left", title: "Фильтры" },
   { side: "right", title: "Детали заказа" },
+  { side: "bottom", title: "Действия с заказом" },
 ] as const;
 
 export default function DrawerPlacementExample() {
@@ -22,7 +23,8 @@ export default function DrawerPlacementExample() {
             </Drawer.Header>
             <Drawer.Body>
               <Typography variant="body-m" tone="secondary">
-                Скругление только со стороны страницы, подложка затемняет остальное.
+                Скругление только со стороны страницы, подложка затемняет остальное. Свайп к краю
+                закрывает панель.
               </Typography>
             </Drawer.Body>
           </Drawer.Content>