prime-ui-kit 0.17.0 → 0.19.0

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

@@ -177,7 +177,15 @@ const initials = (name: string) =>
     .toUpperCase();
 
 const COLUMNS: DataTableColumn<Invoice>[] = [
-  { id: "id", header: "Счёт", accessor: "id", sortable: true, numeric: true, align: "start" },
+  {
+    id: "id",
+    header: "Счёт",
+    accessor: "id",
+    sortable: true,
+    numeric: true,
+    align: "start",
+    hideable: false,
+  },
   {
     id: "client",
     header: "Клиент",
@@ -230,6 +238,7 @@ const COLUMNS: DataTableColumn<Invoice>[] = [
     id: "actions",
     header: "Действия",
     hideHeader: true,
+    hideable: false,
     width: "3.5rem",
     align: "end",
     cell: (row) => (
@@ -320,6 +329,8 @@ export default function DataTableScreenExample() {
             getRowLabel={(row) => `Счёт ${row.id}`}
             pageSize={6}
             stickyFirstColumn
+            stickyLastColumn
+            columnsMenu
             defaultSort={{ columnId: "due", order: "desc" }}
             empty={
               <EmptyPage.Root size="s" role="status" aria-labelledby="invoices-empty">

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

@@ -1,7 +1,6 @@
-/** A campaign list with search, a status filter and export above the table; the empty text when nothing matches — `toolbar`, `empty`. */
+/** A campaign table with its own search and status filter above it — two table-scoped controls; the empty text when nothing matches — `toolbar`, `empty`. */
 import {
   Badge,
-  Button,
   DataTable,
   type DataTableColumn,
   Icon,
@@ -87,36 +86,31 @@ export default function DataTableToolbarExample() {
       pageSize={5}
       empty="Ничего не найдено — измените запрос или фильтр"
       toolbar={
-        <div className={styles.toolbar}>
-          <div className={styles.filters}>
-            <Input.Root size="s" className={styles.search}>
-              <Input.Wrapper>
-                <Input.Icon side="start">
-                  <Icon name="action.search" />
-                </Input.Icon>
-                <Input.Field
-                  type="search"
-                  placeholder="Поиск кампаний"
-                  aria-label="Поиск кампаний"
-                  value={query}
-                  onValueChange={setQuery}
-                />
-              </Input.Wrapper>
-            </Input.Root>
-            <SegmentedControl.Root
-              size="s"
-              aria-label="Статус"
-              value={status}
-              onValueChange={setStatus}
-            >
-              <SegmentedControl.Item value="all">Все</SegmentedControl.Item>
-              <SegmentedControl.Item value="active">Активные</SegmentedControl.Item>
-              <SegmentedControl.Item value="paused">На паузе</SegmentedControl.Item>
-            </SegmentedControl.Root>
-          </div>
-          <Button.Root variant="outline" tone="neutral" size="s">
-            Экспорт
-          </Button.Root>
+        <div className={styles.filters}>
+          <Input.Root size="s" className={styles.search}>
+            <Input.Wrapper>
+              <Input.Icon side="start">
+                <Icon name="action.search" />
+              </Input.Icon>
+              <Input.Field
+                type="search"
+                placeholder="Поиск кампаний"
+                aria-label="Поиск кампаний"
+                value={query}
+                onValueChange={setQuery}
+              />
+            </Input.Wrapper>
+          </Input.Root>
+          <SegmentedControl.Root
+            size="s"
+            aria-label="Статус"
+            value={status}
+            onValueChange={setStatus}
+          >
+            <SegmentedControl.Item value="all">Все</SegmentedControl.Item>
+            <SegmentedControl.Item value="active">Активные</SegmentedControl.Item>
+            <SegmentedControl.Item value="paused">На паузе</SegmentedControl.Item>
+          </SegmentedControl.Root>
         </div>
       }
     />

package/src/components/datepicker/COMPONENT.md

@@ -12,7 +12,7 @@
 - An annual day and month without a year (`yearless`).
 
 ## When not to use
-- Time of day only → use [Input](../input/COMPONENT.md) with a time mask.
+- Time of day only → use [Input](../input/COMPONENT.md) with `Input.Field type="time"`: the time is typed in hour and minute segments, there is no day to pick (a date with a time is `withTime`).
 - A choice between a few fixed periods («7 дней», «30 дней») → use [SegmentedControl](../segmented-control/COMPONENT.md) or [Select](../select/COMPONENT.md).
 - A free-text date the user types → use [Input](../input/COMPONENT.md).
 
@@ -63,6 +63,7 @@ panel                       presets column (range) · 1–2 month grids · promp
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Field tier (height 28 · 32 · 36 · 40 · 48) and panel tier (day cell 24 · 28 · 32 · 36 · 40). Without it the tier of its host, else `m`. |
 | `label` | `ReactNode` | — | Field label; part of the button's accessible name together with the value. |
 | `hint` | `ReactNode` | — | Support text under the field (`aria-describedby`). |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in place of the hint; implies `invalid`. |
 | `required` | `boolean` | `false` | Red `*` after the label; the field button is described by `labels.required` (a button takes no `aria-required`). |
 | `optional` | `boolean` | — | Muted `labels.optional` after the label. |
@@ -241,6 +242,7 @@ Committing: without `footer` a picked day (or the second day of a range) applies
 | [inline-panel.tsx](examples/inline-panel.tsx) | A booking calendar embedded in a card: the card is its container, two months when the parent has room, the range applies at once — `Datepicker.Panel`, `months`, `prompt`. |
 | [yearless.tsx](examples/yearless.tsx) | An annual price change date: day and month without a year, a value prefix and taken days disabled — `yearless`, `valuePrefix`, `isDayDisabled`. |
 | [locale.tsx](examples/locale.tsx) | A delivery window on a partner portal in English: month and weekday names from the date-fns locale, the week from Sunday and the system texts translated — `locale`, `weekStartsOn`, `labels`. |
+| [deadline.tsx](examples/deadline.tsx) | A document's expiry date whose hint counts the days left and takes the status tone — `hint`, `hintTone`. |
 | [dismiss.tsx](examples/dismiss.tsx) | A shift period with a footer: the calendar keeps the draft on a press beside it and closes by Escape, Reset or Apply — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled.tsx](examples/controlled.tsx) | A report filter owns the period: quick buttons set it from outside, the field shows it — `value`, `onValueChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the panel: a reminder button opens the calendar from code, a picked day closes it — `open`, `onOpenChange`. |

package/src/components/datepicker/examples/deadline.tsx

@@ -0,0 +1,33 @@
+/** A document's expiry date whose hint counts the days left and takes the status tone — `hint`, `hintTone`. */
+import { differenceInCalendarDays } from "date-fns";
+import { Datepicker } from "prime-ui-kit";
+import * as React from "react";
+
+const TODAY = new Date(2026, 9, 15);
+const WARN_DAYS = 30;
+
+/** The hint and its tone: the words say the status, the tone repeats it. */
+function expiryHint(expires: Date | null) {
+  if (!expires) return { hint: "Дата из договора страхования", tone: "neutral" as const };
+  const days = differenceInCalendarDays(expires, TODAY);
+  if (days < 0) return { hint: `Срок истёк ${-days} дн. назад`, tone: "danger" as const };
+  if (days <= WARN_DAYS) return { hint: `Осталось ${days} дн.`, tone: "warning" as const };
+  return { hint: `Действует ещё ${days} дн.`, tone: "success" as const };
+}
+
+export default function DatepickerDeadlineExample() {
+  const [expires, setExpires] = React.useState<Date | null>(new Date(2026, 9, 27));
+  const { hint, tone } = expiryHint(expires);
+
+  return (
+    <Datepicker.Root
+      mode="single"
+      label="Страховка действует до"
+      value={expires}
+      onValueChange={setExpires}
+      hint={hint}
+      hintTone={tone}
+      fullWidth
+    />
+  );
+}

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

@@ -42,6 +42,7 @@ DigitInput            field frame: label row → cells → support row (hint | e
 | `required` | `boolean` | — | Red `*` after the label and native `required` on every cell. |
 | `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
 | `hint` | `ReactNode` | — | Help text under the cells. Hidden while `error` is shown. |
+| `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | — | Danger ring and danger digits on every cell, `aria-invalid`. A non-empty `error` implies it. |
 | `success` | `boolean` | `false` | The code was accepted (after the server checked it): the cells turn success one after another. Ignored while invalid. Say it in words too (`hint`). |

package/src/components/dnd/COMPONENT.md

@@ -30,7 +30,7 @@ Dnd.Root                         session owner: overlay (portal), live region, l
 ├─ Dnd.Sortable                  list container and drop target; renders items in the drawn order
 │  ├─ header                     optional content before the items that never moves (a group's heading row)
 │  ├─ Dnd.SortableItem           one item (li in ul/ol, div otherwise); the gap is drawn before it
-│  │  └─ Dnd.Handle              optional grip: a ghost icon-only Button (with `handle` on the list); a lock in a `locked` item; busy while the item's move is saved
+│  │  └─ Dnd.Handle              optional grip, last in the item: a ghost icon-only Button (with `handle` on the list); a lock in a `locked` item; busy while the item's move is saved
 │  ├─ empty                      the `empty` content while the list has no items
 │  └─ children                   optional content after the items that never moves (an add tile)
 ├─ Dnd.Draggable                 an item to carry elsewhere; stays in place, faded, until the drop
@@ -85,7 +85,7 @@ Generic `Dnd.Sortable<T>`; `ref` → `HTMLElement`. The list and its drop target
 | `…rest` | `Omit<HTMLAttributes<HTMLElement>, "id">` | — | `aria-labelledby` / `aria-describedby` (the visible title and description) and the other attributes. |
 
 ### Dnd.Handle
-`ref` → `HTMLButtonElement` (`HTMLSpanElement` in a `locked` item). The grip: a ghost icon-only `xs` Button that starts the drag and takes the item's keys; busy while the item's move is saved. In a `locked` item it is a lock.
+`ref` → `HTMLButtonElement` (`HTMLSpanElement` in a `locked` item). The grip: a ghost icon-only `xs` Button that starts the drag and takes the item's keys; busy while saving. In a `locked` item it is a lock. Place it last in the item, after its controls.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -201,6 +201,7 @@ An item's own `onPointerDown` / `onKeyDown` run before the kit's: `preventDefaul
 ## Layout & spacing
 - The distance between items is `--prime-space-2`; a host sets `--dnd-sortable-gap` on the list for another one.
 - A grid (`axis="grid"`) is `display: grid`: the host sets the tracks (`grid-template-columns`) and the cells' size; the gap takes a cell, and a carried item resizes to the cell it would land in.
+- A `Dnd.Handle` ends its item: the last child, after the item's own trailing controls (a remove button), at the inline end (on the left in RTL); a `locked` item's lock takes the same place, so the grips of every row stand on one line. In a table it is the last cell. An on / off switch leads the item (its first child), so its state reads first and nothing stands between the text and the grip.
 - The reason chip stands `--prime-tooltip-offset` under the carried copy, start-aligned, at most `--prime-tooltip-max-width` wide.
 - The look of a row is the consumer's: give `Dnd.SortableItem` / `Dnd.Draggable` a radius on its own class (the gap and the clone's fill take it) and keep the row's look within its ancestors up to the nearest surface (`data-depth`) — the clone flies inside empty copies (`display: contents`) of exactly those, so their variables and selectors still apply. A table row flies in a one-row copy of its table inside them.
 - A scrollable ancestor under the pointer auto-scrolls within 64 px of its edge (a `ScrollContainer` strip works).
@@ -251,7 +252,7 @@ An item's own `onPointerDown` / `onKeyDown` run before the kit's: `preventDefaul
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | Project tasks reordered by dragging the whole row; one root above, the move applied with a helper — `Dnd.Root`, `Dnd.Sortable`, `onReorder`, `moveBefore`. |
-| [handle.tsx](examples/handle.tsx) | Notification channels with switches: only the grip starts a drag, and the async save can roll the order back — `handle`, `Dnd.Handle`, `onReorder`. |
+| [handle.tsx](examples/handle.tsx) | Notification channels, each switch leading its row and the grip ending it: only the grip starts a drag, and the async save can roll the order back — `handle`, `Dnd.Handle`, `onReorder`. |
 | [grid.tsx](examples/grid.tsx) | Product photos in a wrapping grid: a photo carried across rows lands in reading order, the gap takes a cell, Alt + ← / → steps it one place — `axis`. |
 | [locked.tsx](examples/locked.tsx) | Sections of a workspace menu: the home section is pinned first with a lock in place of its grip, the rest reorder around nothing past it; each row is named by its visible title — `locked`, `handle`, `aria-labelledby`. |
 | [board.tsx](examples/board.tsx) | A ticket board: columns share one kind, so a ticket lands in another column at an exact position or moves there with Alt + ← / →, an empty column says so, and a full column refuses it before the release with the reason under the ticket — `kind`, `canDrop`, `empty`, `onReorder`. |

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

@@ -18,9 +18,9 @@
   box-shadow: var(--prime-shadow-raised);
 }
 
-/* The grip sits closer to the edge: it is a square button with its own inner room. */
+/* The grip ends the row and sits closer to the edge: a square button with its own inner room. */
 .handleRow {
-  padding-inline-start: var(--prime-space-2);
+  padding-inline-end: var(--prime-space-2);
 }
 
 .rowText {
@@ -134,9 +134,10 @@
   text-align: end;
 }
 
+/* The grip column ends the row. */
 .grip {
   inline-size: var(--prime-space-10);
-  padding-inline-end: 0;
+  padding-inline-start: 0;
 }
 
 /* A stage's heading row: a fill marks where a new stage starts. */

package/src/components/dnd/examples/handle.tsx

@@ -1,4 +1,4 @@
-/** Notification channels with switches: only the grip starts a drag, and the async save can roll the order back — `handle`, `Dnd.Handle`, `onReorder`. */
+/** Notification channels, each switch leading its row and the grip ending it: only the grip starts a drag, and the async save can roll the order back — `handle`, `Dnd.Handle`, `onReorder`. */
 import { Dnd, moveBefore, Switch, Typography } from "prime-ui-kit";
 import * as React from "react";
 
@@ -37,10 +37,6 @@ export default function DndHandleExample() {
         }}
         renderItem={(channel) => (
           <Dnd.SortableItem id={channel.id} className={styles.handleRow}>
-            <Dnd.Handle />
-            <Typography as="span" variant="body-m" className={styles.rowText}>
-              {channel.title}
-            </Typography>
             <Switch.Root
               aria-label={channel.title}
               checked={channel.enabled}
@@ -50,6 +46,10 @@ export default function DndHandleExample() {
                 )
               }
             />
+            <Typography as="span" variant="body-m" className={styles.rowText}>
+              {channel.title}
+            </Typography>
+            <Dnd.Handle />
           </Dnd.SortableItem>
         )}
       />

package/src/components/dnd/examples/locked.tsx

@@ -40,7 +40,6 @@ export default function DndLockedExample() {
             aria-labelledby={`${uid}-${section.id}`}
             aria-describedby={`${uid}-${section.id}-note`}
           >
-            <Dnd.Handle aria-label={`Переместить раздел «${section.title}»`} />
             <span className={styles.rowText}>
               <Typography as="span" variant="body-m" id={`${uid}-${section.id}`}>
                 {section.title}
@@ -49,6 +48,7 @@ export default function DndLockedExample() {
                 {section.description}
               </Typography>
             </span>
+            <Dnd.Handle aria-label={`Переместить раздел «${section.title}»`} />
           </Dnd.SortableItem>
         )}
       />

package/src/components/dnd/examples/table.tsx

@@ -51,9 +51,6 @@ export default function DndTableExample() {
         </caption>
         <thead>
           <tr>
-            <th scope="col" className={styles.grip}>
-              <VisuallyHidden>Порядок</VisuallyHidden>
-            </th>
             <th scope="col" className={styles.cell}>
               <Typography as="span" variant="caption" tone="muted">
                 Работа
@@ -64,6 +61,9 @@ export default function DndTableExample() {
                 Часы
               </Typography>
             </th>
+            <th scope="col" className={styles.grip}>
+              <VisuallyHidden>Порядок</VisuallyHidden>
+            </th>
           </tr>
         </thead>
         {stages.map((stage) => (
@@ -90,9 +90,6 @@ export default function DndTableExample() {
             }
             renderItem={(line) => (
               <Dnd.SortableItem id={line.id}>
-                <td className={styles.grip}>
-                  <Dnd.Handle />
-                </td>
                 <td className={styles.cell}>
                   <Typography as="span" variant="body-m">
                     {line.title}
@@ -103,6 +100,9 @@ export default function DndTableExample() {
                     {line.hours}
                   </Typography>
                 </td>
+                <td className={styles.grip}>
+                  <Dnd.Handle />
+                </td>
               </Dnd.SortableItem>
             )}
           />

package/src/components/drawer/COMPONENT.md

@@ -35,6 +35,7 @@ Drawer.Root                    state and dismiss policy (no DOM)
    │  ├─ Drawer.Description    <p>
    │  └─ Drawer.Actions        row of tier-s controls before the close button
    ├─ Drawer.Body              the only scrolling zone (ScrollContainer)
+   │  └─ Drawer.Section        <section>: <h3> label, description, Drawer.Actions at the heading's end
    └─ Drawer.Footer            always: Close or Cancel + the main action, primary last
       ├─ Drawer.Meta           <p>, muted status at the start
       └─ Drawer.Close          clones its child; closes on click
@@ -80,7 +81,7 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other attributes of the `<header>`. |
 
 ### Drawer.Actions
-`ref` → `HTMLDivElement`. A row of controls at the end of the header, before the close button: a status Badge, a ⋯ Dropdown, an icon button. Controls inside take tier `s`.
+`ref` → `HTMLDivElement`. A row of controls at the end of the header, before the close button: a status Badge, a ⋯ Dropdown; under the title when it would get less than 12rem; or at the end of a `Drawer.Section` heading. Controls inside take tier `s`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -95,12 +96,20 @@ No DOM, no ref. State and dismiss policy.
 | `children` | `ReactNode` | — (required) | An `Icon` (sized to the m icon), or the record's picture: an `Avatar.Root` (sized to the tile) or a `Thumbnail.Root`. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the tile. |
 
-### Drawer.Title · Drawer.Description
-`ref` → `HTMLHeadingElement` / `HTMLParagraphElement`. `<h2>` (title-m) / `<p>` (body-s, muted); their ids name and describe the dialog.
+### Drawer.Title
+`ref` → `HTMLHeadingElement`. `<h2>` (title-m); its id names the dialog.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `…rest` | `Omit<HTMLAttributes<HTMLHeadingElement \| HTMLParagraphElement>, "id">` | — | `className`, `children` and the other attributes except `id` (the dialog owns it). |
+| `…rest` | `Omit<HTMLAttributes<HTMLHeadingElement>, "id">` | — | `className`, `children` and the other attributes except `id` (the dialog owns it). |
+
+### Drawer.Description
+`ref` → `HTMLParagraphElement`. `<p>` (body-s, muted) under the title; its id describes the dialog.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `loading` | `boolean` | `false` | Its data loads: a `Skeleton` holds the line's place and `aria-busy` is set, so the header never moves; the data fades in. |
+| `…rest` | `Omit<HTMLAttributes<HTMLParagraphElement>, "id">` | — | `className`, `children` and the other attributes except `id` (the dialog owns it). |
 
 ### Drawer.Body
 `ref` → `HTMLDivElement`. The only scrolling zone (a ScrollContainer), 16 gap between blocks.
@@ -109,12 +118,21 @@ No DOM, no ref. State and dismiss policy.
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `children` and the other attributes of the zone. |
 
+### Drawer.Section
+`ref` → `HTMLElement`. A titled `<section>` of the body: an `<h3>` (title-s, under the `<h2>` title), an optional description, a `Drawer.Actions` at the end of the heading row; the content 16 below, sections 32 apart, in any wrapper. Fields group in a `Fieldset`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — (required) | The heading of the section; it names the `<section>`. |
+| `description` | `ReactNode` | — | One line of context under the heading (body-s). |
+| `…rest` | `Omit<HTMLAttributes<HTMLElement>, "title">` | — | `children` (the content and an optional `Drawer.Actions`), `className` and the other attributes of the `<section>`. |
+
 ### Drawer.Footer
 `ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last, and an optional `Meta` at the start.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `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. |
+| `layout` | `"fill" \| "end"` | `"end"` | `fill`: equal-width buttons in one row, wrapping rather than cutting a label; `end`: auto width, at the end. Stacked on phones (viewport below 640 px) and in a dialog narrower than 360 px. |
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className`, `children` and the other attributes of the `<footer>`. |
 
 ### Drawer.Meta
@@ -125,7 +143,7 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `className`, `children` and the other attributes of the `<p>`. |
 
 ### Drawer.Guard
-No DOM, no ref. Holds the dialog from anywhere inside Content, where the form state lives; renders only the built-in «discard changes?» confirm. Closing from code is never held.
+No DOM, no ref. Holds the dialog from anywhere inside Content, where the form state lives; renders only the built-in «discard changes?» confirm. While `busy` or `dirty` the browser also asks before the tab closes or reloads. Closing from code is never held.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -176,6 +194,9 @@ Below 640px of viewport every size is full width and loses its corners.
 | closing | `open` turns false | the panel keeps showing the children it had open while it slides out |
 | busy | `Drawer.Guard busy` | Escape, the scrim, the close button and `Drawer.Close` do nothing; the close button and the `Close` child are `disabled` in place |
 | dirty | `Drawer.Guard dirty` | a dismiss opens the «Не сохранять изменения?» ConfirmDialog (`labels.discard*`); its confirm closes the drawer |
+| leaving the tab | `Drawer.Guard busy` or `dirty` | the browser asks before the tab closes or reloads (`beforeunload`), as with `Page.Guard` |
+| description loading | `Drawer.Description loading` | a `Skeleton` holds the line, `aria-busy` on the `<p>`; the data fades in under the same element |
+| actions below | the title would get less than 12rem beside `Drawer.Actions` | `data-actions-below` on the header: the actions move under the title and the description |
 
 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. The drawer has no touch gestures: it is not dragged or swiped away — it closes by its buttons, Escape and the scrim, with the same slide-out.
 
@@ -189,6 +210,10 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 - Full viewport height; only the body scrolls, with its own side padding.
 - Tabs in the header: a `Tabs.List` inside `Drawer.Header` (with `Tabs.Root` around the header and the body) spans the header's last row. The header becomes the tab strip, edge to edge and without the hairline; the active tab is the body rising into it, the panels sit in the body.
 - Fields inside get the surface field fill.
+- Titled groups of the body (a record's contacts, its deals, its history): `Drawer.Section label` — an `<h3>` under the drawer's `<h2>` title, an optional `description`, a `Drawer.Actions` at the end of its heading row; content 16 below, sections 32 apart — directly in the body, in a `Tabs.Panel` or in a form, with no spacing wrapper of your own. A group of fields is a `Fieldset`; a page section is `Page.Section`.
+- With a `Drawer.Meta` the buttons stay one row: when the footer runs short the status goes above them first.
+- `Drawer.Actions` keep their place beside the title while it has 12rem; on a phone, where a status and a ⋯ beside the × would fold the title into letters, they move under it by themselves.
+- A record whose data is still loading: the title from the list row, `Drawer.Description loading` and a `Skeleton` body in the data's geometry under a `Crossfade` — not a skeleton of your own in the header.
 
 ## Accessibility
 
@@ -228,8 +253,9 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 | [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, rounded only on the edge facing the page — `side`. |
-| [header-actions.tsx](examples/header-actions.tsx) | A record card: its status and a ⋯ menu sit in the header before the close button, one tier smaller — `Drawer.Actions`. |
-| [client-card.tsx](examples/client-card.tsx) | A client card from the list: the contact's avatar heads the panel in place of an icon tile, then the details — `Drawer.Icon`, `Avatar.Root`. |
+| [header-actions.tsx](examples/header-actions.tsx) | A record card: its status and a ⋯ menu sit in the header before the close button, one tier smaller; on a phone, where the title has no room beside them, they move under it — `Drawer.Actions`. |
+| [client-card.tsx](examples/client-card.tsx) | A client card from the list: the contact's avatar heads the panel in place of an icon tile, then the details in titled sections, one with its own action — `Drawer.Icon`, `Avatar.Root`, `Drawer.Section`, `Drawer.Actions`. |
+| [loading.tsx](examples/loading.tsx) | A record card that opens before its data arrives: the title comes from the list row, the line under it and the body hold their place in skeletons, then the data fades in — `Drawer.Description`, `loading`. |
 | [guard.tsx](examples/guard.tsx) | A form that holds the drawer from inside: after an edit Escape, the scrim and Cancel ask before discarding, the footer says so, and saving locks every way out — `Drawer.Guard`, `Drawer.Meta`. |
 | [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`. |
@@ -241,6 +267,9 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 - A drawer without `Drawer.Footer` → add one: «Закрыть» for details, «Отмена» + the submit button for a form. The header × alone is not the end of the panel.
 - Save or Cancel buttons at the end of the body, or in the header → they go in `Drawer.Footer`, which stays in place while the body scrolls.
 - A delete confirmation in a Drawer → use ConfirmDialog.
+- A hand-made heading row (`Typography as="h3"` + buttons) over a group in the body → `Drawer.Section label` with `Drawer.Actions`.
+- A wrapper with its own gap around `Drawer.Section`s inside a `Tabs.Panel` or a form → not needed: sections keep 32 between them in any wrapper.
+- A `Skeleton` placed by hand in `Drawer.Description` while the record loads → `Drawer.Description loading`.
 - Busy or unsaved state lifted out of the form into Root props → put `Drawer.Guard` next to the form, inside Content.
 - Clearing the record together with `open` and rendering a skeleton for «no record» → not needed: the panel keeps its last content while it slides out.
 - A Badge or a menu as a custom child of the header text column → put them in `Drawer.Actions`.
@@ -250,5 +279,5 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 - Padding on a wrapper inside Body → Body already pads and scrolls.
 
 ## Related
-- **Built from:** the dialog shared with Modal and Sheet (`internal/overlay/DialogParts`), [Button](../button/COMPONENT.md) (close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Drawer.Body`), [Avatar](../avatar/COMPONENT.md) and [Thumbnail](../thumbnail/COMPONENT.md) (a record's picture in `Drawer.Icon`), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (the `Drawer.Guard` discard confirm), `Icon` (the close glyph)
+- **Built from:** the dialog shared with Modal and Sheet (`internal/overlay/DialogParts`), [Button](../button/COMPONENT.md) (close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Drawer.Body`), [Avatar](../avatar/COMPONENT.md) and [Thumbnail](../thumbnail/COMPONENT.md) (a record's picture in `Drawer.Icon`), [Skeleton](../skeleton/COMPONENT.md) (`Drawer.Description loading`), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (the `Drawer.Guard` discard confirm), `Icon` (the close glyph)
 - **See also:** [Modal](../modal/COMPONENT.md) (the same header, body, footer and `Guard` in the centre), [Sheet](../sheet/COMPONENT.md) (the same parts raised from the bottom edge for a short task), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (a destructive confirm), [Sidebar](../../layout/sidebar/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Avatar](../avatar/COMPONENT.md) (a person's picture in `Drawer.Icon`)

package/src/components/drawer/examples/client-card.tsx

@@ -1,5 +1,5 @@
-/** A client card from the list: the contact's avatar heads the panel in place of an icon tile, then the details — `Drawer.Icon`, `Avatar.Root`. */
-import { Avatar, Button, DescriptionList, Drawer } from "prime-ui-kit";
+/** A client card from the list: the contact's avatar heads the panel in place of an icon tile, then the details in titled sections, one with its own action — `Drawer.Icon`, `Avatar.Root`, `Drawer.Section`, `Drawer.Actions`. */
+import { Avatar, Button, DescriptionList, Drawer, Icon } from "prime-ui-kit";
 
 const CLIENT = {
   name: "Анна Соколова",
@@ -10,6 +10,11 @@ const CLIENT = {
   manager: "Игорь Лебедев",
 };
 
+const DEALS = [
+  { id: "D-2041", title: "Поставка серверов", amount: "1 240 000 ₽" },
+  { id: "D-2057", title: "Сервисный контракт на год", amount: "380 000 ₽" },
+];
+
 export default function DrawerClientCardExample() {
   return (
     <Drawer.Root>
@@ -29,12 +34,31 @@ export default function DrawerClientCardExample() {
           <Drawer.Description>{CLIENT.company}</Drawer.Description>
         </Drawer.Header>
         <Drawer.Body>
-          <DescriptionList.Root>
-            <DescriptionList.Item label="Должность">{CLIENT.role}</DescriptionList.Item>
-            <DescriptionList.Item label="Телефон">{CLIENT.phone}</DescriptionList.Item>
-            <DescriptionList.Item label="Почта">{CLIENT.email}</DescriptionList.Item>
-            <DescriptionList.Item label="Менеджер">{CLIENT.manager}</DescriptionList.Item>
-          </DescriptionList.Root>
+          <Drawer.Section label="Контакт">
+            <DescriptionList.Root>
+              <DescriptionList.Item label="Должность">{CLIENT.role}</DescriptionList.Item>
+              <DescriptionList.Item label="Телефон">{CLIENT.phone}</DescriptionList.Item>
+              <DescriptionList.Item label="Почта">{CLIENT.email}</DescriptionList.Item>
+              <DescriptionList.Item label="Менеджер">{CLIENT.manager}</DescriptionList.Item>
+            </DescriptionList.Root>
+          </Drawer.Section>
+          <Drawer.Section label="Открытые сделки" description="2 сделки на 1 620 000 ₽">
+            <Drawer.Actions>
+              <Button.Root variant="ghost" tone="neutral">
+                <Button.Icon>
+                  <Icon name="action.add" />
+                </Button.Icon>
+                Сделка
+              </Button.Root>
+            </Drawer.Actions>
+            <DescriptionList.Root>
+              {DEALS.map((deal) => (
+                <DescriptionList.Item key={deal.id} label={deal.title}>
+                  {deal.amount}
+                </DescriptionList.Item>
+              ))}
+            </DescriptionList.Root>
+          </Drawer.Section>
         </Drawer.Body>
         <Drawer.Footer>
           <Drawer.Close>

package/src/components/drawer/examples/header-actions.tsx

@@ -1,4 +1,4 @@
-/** A record card: its status and a ⋯ menu sit in the header before the close button, one tier smaller — `Drawer.Actions`. */
+/** A record card: its status and a ⋯ menu sit in the header before the close button, one tier smaller; on a phone, where the title has no room beside them, they move under it — `Drawer.Actions`. */
 import { Badge, Button, DescriptionList, Drawer, Dropdown, Icon } from "prime-ui-kit";
 
 const DEAL = {

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

@@ -0,0 +1,58 @@
+/** A record card that opens before its data arrives: the title comes from the list row, the line under it and the body hold their place in skeletons, then the data fades in — `Drawer.Description`, `loading`. */
+import { Button, Crossfade, DescriptionList, Drawer, Skeleton } from "prime-ui-kit";
+import * as React from "react";
+
+const BIKE = {
+  title: "Велосипед №214",
+  summary: "Тур 2 · на линии с 6 октября",
+  facts: [
+    ["Модель", "Tour 2, рама M"],
+    ["Пробег", "1 840 км"],
+    ["Последнее ТО", "28 сентября"],
+    ["Арендатор", "Илья Морозов"],
+  ],
+};
+
+export default function DrawerLoadingExample() {
+  const [loading, setLoading] = React.useState(true);
+
+  const openChange = (open: boolean) => {
+    if (!open) return;
+    setLoading(true);
+    window.setTimeout(() => setLoading(false), 1200);
+  };
+
+  return (
+    <Drawer.Root onOpenChange={openChange}>
+      <Drawer.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Открыть велосипед
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Content>
+        <Drawer.Header>
+          <Drawer.Title>{BIKE.title}</Drawer.Title>
+          <Drawer.Description loading={loading}>{BIKE.summary}</Drawer.Description>
+        </Drawer.Header>
+        <Drawer.Body>
+          <Crossfade state={loading ? "loading" : "data"} aria-busy={loading}>
+            <DescriptionList.Root>
+              {BIKE.facts.map(([term, value]) => (
+                <DescriptionList.Item key={term} label={term}>
+                  {loading ? <Skeleton /> : value}
+                </DescriptionList.Item>
+              ))}
+            </DescriptionList.Root>
+          </Crossfade>
+        </Drawer.Body>
+        <Drawer.Footer>
+          <Drawer.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Закрыть
+            </Button.Root>
+          </Drawer.Close>
+        </Drawer.Footer>
+      </Drawer.Content>
+    </Drawer.Root>
+  );
+}