prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/reference/components/select/examples/with-icon.tsx

@@ -0,0 +1,35 @@
+/** A leading icon in the trigger and an icon before every option label — `Select.TriggerIcon`, `Select.ItemIcon`. */
+import { Icon, Select } from "prime-ui-kit";
+import * as React from "react";
+
+const ACCESS = [
+  { value: "public", label: "Виден в поиске", icon: "action.search" },
+  { value: "invite", label: "Только по приглашению", icon: "field.email" },
+  { value: "private", label: "Только участники", icon: "status.locked" },
+] as const;
+
+export default function SelectWithIconExample() {
+  const [access, setAccess] = React.useState<string>("invite");
+  const selected = ACCESS.find((option) => option.value === access) ?? ACCESS[1];
+
+  return (
+    <Select.Root label="Доступ к проекту" value={access} onValueChange={setAccess}>
+      <Select.Trigger>
+        <Select.TriggerIcon>
+          <Icon name={selected.icon} />
+        </Select.TriggerIcon>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        {ACCESS.map((option) => (
+          <Select.Item key={option.value} value={option.value}>
+            <Select.ItemIcon>
+              <Icon name={option.icon} />
+            </Select.ItemIcon>
+            {option.label}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
+  );
+}

package/dist/skill/reference/components/sheet/COMPONENT.md

@@ -0,0 +1,216 @@
+# Sheet
+
+**Category:** overlays
+**Kind:** overlay
+
+> A panel raised from the bottom edge for a short task that ends by itself: pick a date, choose an action, leave a few words.
+
+## When to use
+- A pick that closes the sheet: a date, a status, a delivery slot (`Datepicker.Panel` straight in the body).
+- A short list of actions on one record («Повторить заказ», «Скачать счёт») — each closes the sheet.
+- A short note or a question the person answers in place, on a phone first: one or two fields with an explicit submit (`Sheet.Footer`).
+
+## When not to use
+- Record details, forms, filters that stay open while the person works → use [Drawer](../drawer/COMPONENT.md) (a side panel).
+- A decision or a short form in the centre of the screen → use [Modal](../modal/COMPONENT.md) (it becomes a bottom sheet on phones by itself).
+- A destructive confirm → use [ConfirmDialog](../confirm-dialog/COMPONENT.md).
+- Actions anchored to a button on a desktop → use [Dropdown](../dropdown/COMPONENT.md) (it becomes a sheet on phones by itself).
+
+## Import
+```tsx
+import { Sheet } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Sheet.Root                     state and dismiss policy (no DOM)
+├─ Sheet.Trigger               clones its child; opens on click
+└─ Sheet.Content               portal + scrim + role="dialog" panel at the bottom edge
+   ├─ (grab handle)            aria-hidden bar on top; a drag starts here
+   ├─ Sheet.Guard              no DOM: holds the sheet (busy / dirty) from inside
+   ├─ Sheet.Header             optional: [Icon] [Title + Description] [Actions] [close Button]
+   │  ├─ Sheet.Icon
+   │  ├─ Sheet.Title           <h2>
+   │  ├─ Sheet.Description     <p>
+   │  └─ Sheet.Actions         row of tier-s controls before the close button
+   ├─ Sheet.Body               the content; the only scrolling zone (ScrollContainer)
+   └─ Sheet.Footer             optional: only for a form with an explicit submit
+      ├─ Sheet.Meta            <p>, muted status at the start
+      └─ Sheet.Close           clones its child; closes on click
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Sheet.Root
+No DOM, no ref. State and dismiss policy.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean` | — | Controlled visibility; together with `onOpenChange`. |
+| `defaultOpen` | `boolean` | `false` | Initial visibility, uncontrolled. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, close button, `Close`, Escape, scrim click, code. A `Guard` holds the dismisses (not code). |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the dialog. |
+| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim (and a swipe down) closes the dialog; turn off for destructive confirms. |
+| `labels` | `Partial<SheetLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — | Trigger and Content. |
+
+### Sheet.Content
+`ref` → `HTMLDivElement` (the dialog panel). Portal + scrim + `role="dialog"` panel raised from the bottom edge, as tall as its content. Header and footer are optional: without a header name it with `aria-label`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `aria-label` | `string` | — | Dialog name when there is no Title. |
+| `aria-labelledby` | `string` | — | Overrides the Title id. |
+| `aria-describedby` | `string` | — | Overrides the Description id. |
+| `overlayClassName` | `string` | — | Class on the scrim. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className` and the other attributes of the `role="dialog"` element. |
+
+### Sheet.Header
+`ref` → `HTMLElement`. Renders `<header>`: [Icon] [Title + Description] [Actions] [close button]. + native `HTMLAttributes<HTMLElement>`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `showClose` | `boolean` | `true` | Built-in square ghost `s` close button named by `labels.close`; disabled in place while a `Guard` is `busy`. |
+| `children` | `ReactNode` | — | Icon, Title, Description, Actions in any order; each goes to its column. A `Tabs.List` (with `Tabs.Root` around header and body) turns the header into a tab strip. |
+
+### Sheet.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`. + native `<div>` props.
+
+### Sheet.Icon
+`ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Soft fill and icon color. |
+| `children` | `ReactNode` | — (required) | Icon glyph (sized to the m icon). |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the tile. |
+
+### Sheet.Title · Sheet.Description
+`ref` → `HTMLHeadingElement` / `HTMLParagraphElement`. `<h2>` (title-m) / `<p>` (body-s, muted); their ids name and describe the dialog. + native props except `id`.
+
+### Sheet.Body
+`ref` → `HTMLDivElement`. The only scrolling zone (a ScrollContainer), 16 gap between blocks. + native `<div>` props.
+
+### Sheet.Footer
+`ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last, and an optional `Meta` at the start. + native `HTMLAttributes<HTMLElement>`.
+
+| 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. |
+
+### Sheet.Meta
+`ref` → `HTMLParagraphElement`. A `<p>` at the start of the footer: short muted status text («Есть несохранённые изменения»); the buttons keep their width at the end. Not part of the dialog description. + native `<p>` props.
+
+### Sheet.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.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `busy` | `boolean` | `false` | A request runs: Escape, a press outside, a swipe, the close button and `Close` do nothing; the close button and the `Close` child stay in place, disabled. |
+| `dirty` | `boolean` | `false` | Unsaved changes: any of those dismisses first asks «Не сохранять изменения?» (a ConfirmDialog with `labels.discard*`); confirming closes the dialog. |
+
+### Sheet.Trigger · Sheet.Close
+No DOM: clone the single child and chain its `onClick` (unless the child's handler calls `preventDefault()`). `Close` goes through a `Guard` and makes its child `disabled` while the guard is busy.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactElement` | — (required) | One element, usually a Button. |
+
+## Variants
+Sheet has no `variant`, `side` or `size`: it always rises from the bottom edge, centred at `--prime-sheet-width` (560) on a tablet or desktop, full width on a phone, and as tall as its content.
+
+### Structure
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| content alone | the handle, then the body; named by `aria-label` | the content says what it is — a calendar under a «Дата отгрузки» button | |
+| header + body | a title (and description) above the content; the header keeps its × | the content needs a title to be understood — actions «Заказ № 1042» | |
+| header + body + footer | «Отмена» and the submit under the form | a short form that needs an explicit submit | |
+
+### layout (Footer)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `end` | auto-width buttons at the end | a short form | yes |
+| `fill` | equal-width buttons in one row | two equal answers | |
+
+### tone (Icon)
+`neutral` (default) · `accent` · `success` · `warning` · `danger` · `info` — soft tile fill and icon color, as in Modal.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| open / closed | `open` / `defaultOpen` / `onOpenChange` | `data-state` on the scrim and the panel; mounted until the slide-down ends |
+| swiping | a drag down from the handle or the header (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`; a sheet opened from another overlay stacks above it |
+| closing | `open` turns false | the panel keeps showing the children it had open while it slides down |
+| busy | `Sheet.Guard busy` | Escape, the scrim, a swipe, the close button and `Sheet.Close` do nothing; the close button and the `Close` child are `disabled` in place |
+| dirty | `Sheet.Guard dirty` | a dismiss opens the «Не сохранять изменения?» ConfirmDialog (`labels.discard*`); no swipe |
+
+Motion: the scrim fades, the sheet slides up over `slow` and down over `base` (`overlayMotion`); under `prefers-reduced-motion` it unmounts at once. A swipe down moves the sheet with the pointer; on release it closes past 30% of its height or on a quick flick and glides the rest of the way out, otherwise it glides back — both over `base` on the `emphasized` (iOS sheet) curve. A pull upward meets growing resistance and stops at 24; the sheet's fill continues that far below the screen edge. The scrim thins as the sheet goes down. The drag starts from the handle or the header, never from the body, so its content scrolls and its controls work as usual.
+
+## Layout & spacing
+- A sheet is a short task that ends by itself — a pick, a tap on an action, a swipe down. Its zones follow the task, not a template:
+  - **No footer by default.** A footer only for a form with an explicit submit: «Отмена» (`Sheet.Close`, outline neutral) and the submit (solid, last; `type="submit" form={formId}`).
+  - **The header is optional.** Keep it when the content needs a title to be understood (a list of actions on «Заказ № 1042»). Drop it — and with it the × and the hairline — when the content speaks for itself (a calendar opened from a «Дата отгрузки» button): name the sheet with `aria-label` on `Sheet.Content`.
+- The content is the sheet's own, across its width: `Datepicker.Panel` or a column of actions straight in `Sheet.Body` — never a Card or a padded box inside it.
+- Zone padding `--prime-sheet-padding`; height by content up to `100dvh − --prime-sheet-top-gap`, radius `--prime-sheet-radius` on top, a `--prime-sheet-handle-area` strip with the handle bar, the bottom safe-area inset below the content.
+- Only the body scrolls; header and footer stay in place.
+- Tabs in the header: a `Tabs.List` inside `Sheet.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.
+
+```tsx
+<Sheet.Content aria-label="Дата отгрузки">
+  <Sheet.Body>
+    <Datepicker.Panel mode="single" value={date} onValueChange={pick} />
+  </Sheet.Body>
+</Sheet.Content>
+```
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Escape` | Closes the sheet (`closeOnEscape`); focus returns to the trigger. |
+| `Tab` · `Shift+Tab` | Cycle focus inside the sheet. |
+
+### ARIA
+- `role="dialog"`, `aria-modal="true"`, named by Title — without a header by `aria-label` on `Sheet.Content`; described by Description.
+- Focus moves into the sheet 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 swipe down is an extra way out; Escape and the scrim stay. The grab handle is `aria-hidden`.
+- A busy `Guard` holds every dismiss, the swipe included; a dirty one opens a `role="alertdialog"` confirm with focus on «Продолжить».
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `close` | `"Закрыть"` | `aria-label` of the header close button. |
+| `discardTitle` | `"Не сохранять изменения?"` | Title of the confirm a dismiss opens while a `Guard` is `dirty`. |
+| `discardDescription` | `"Изменения в форме пропадут."` | Its description. |
+| `discardConfirm` | `"Не сохранять"` | Its confirm button: close and lose the changes. |
+| `discardCancel` | `"Продолжить"` | Its cancel button: back to the form. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | Actions with an order raised from the bottom edge: a header names the order, a column of actions follows, and each action closes the sheet — `Sheet.Trigger`, `Sheet.Header`, `Sheet.Close`. |
+| [structure.tsx](examples/structure.tsx) | The content alone: a date sheet with no header and no footer, the calendar across its width, named by `aria-label`; a pick or a swipe down closes it — `aria-label`, `Sheet.Body`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A handover the courier must answer: no swipe, scrim or Escape closes the sheet, only its two buttons — `closeOnOutsideClick`, `closeOnEscape`. |
+| [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the state and raises the sheet from a link in the text, without a trigger — `open`, `onOpenChange`. |
+| [in-form.tsx](examples/in-form.tsx) | A short form that needs an explicit submit: the one case for a footer, Cancel and Send under the field, an empty comment keeps the sheet open — `Sheet.Footer`, `error`. |
+
+## Mistakes
+- `<Drawer.Content side="bottom">` → there is no bottom Drawer; a panel from the bottom edge is `Sheet`.
+- «Отмена» / «Готово» buttons under a sheet that closes on a pick → drop the footer; the pick, the swipe, the scrim and Escape close it.
+- A header with only a title over a calendar or a list that already says what it is → drop the header and name the sheet with `aria-label`.
+- No header and no `aria-label` → the dialog has no name; give `Sheet.Content` an `aria-label`.
+- A Card or a padded `div` around the content → put it straight into `Sheet.Body`, across its width.
+- Record details or a long form in a sheet → use Drawer; a sheet is a short task.
+- `closeOnOutsideClick={false}` and `closeOnEscape={false}` with no header × and no `Sheet.Close` → nothing closes it; keep a button that answers.
+
+## Related
+- **Built from:** [Button](../button/COMPONENT.md) (close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Sheet.Body`), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (the `Sheet.Guard` discard confirm), `Icon` (the close glyph)
+- **See also:** [Drawer](../drawer/COMPONENT.md) (the same parts as a side panel), [Modal](../modal/COMPONENT.md) (the same parts in the centre), [Datepicker](../datepicker/COMPONENT.md) (`Datepicker.Panel` in a sheet), [Dropdown](../dropdown/COMPONENT.md)

package/dist/skill/reference/components/sheet/examples/controlled-open.tsx

@@ -0,0 +1,37 @@
+/** The parent owns the state and raises the sheet from a link in the text, without a trigger — `open`, `onOpenChange`. */
+import { LinkButton, Sheet, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+export default function SheetControlledOpenExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Typography variant="body-m" tone="secondary">
+        Доставка 5 октября.{" "}
+        <LinkButton
+          href="#delivery-cost"
+          onClick={(event) => {
+            event.preventDefault();
+            setOpen(true);
+          }}
+        >
+          Как считается стоимость?
+        </LinkButton>
+      </Typography>
+      <Sheet.Root open={open} onOpenChange={setOpen}>
+        <Sheet.Content>
+          <Sheet.Header>
+            <Sheet.Title>Стоимость доставки</Sheet.Title>
+          </Sheet.Header>
+          <Sheet.Body>
+            <Typography variant="body-m" tone="secondary">
+              Базовый тариф 390 ₽ до 5 кг, дальше 40 ₽ за каждый килограмм. От 5 000 ₽ в заказе
+              доставка бесплатная.
+            </Typography>
+          </Sheet.Body>
+        </Sheet.Content>
+      </Sheet.Root>
+    </>
+  );
+}

package/dist/skill/reference/components/sheet/examples/dismiss.tsx

@@ -0,0 +1,42 @@
+/** A handover the courier must answer: no swipe, scrim or Escape closes the sheet, only its two buttons — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Button, Sheet, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+export default function SheetDismissExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Sheet.Root
+      open={open}
+      onOpenChange={setOpen}
+      closeOnOutsideClick={false}
+      closeOnEscape={false}
+    >
+      <Sheet.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Передать заказ
+        </Button.Root>
+      </Sheet.Trigger>
+      <Sheet.Content>
+        <Sheet.Header showClose={false}>
+          <Sheet.Title>Заказ № 1042 передан клиенту?</Sheet.Title>
+        </Sheet.Header>
+        <Sheet.Body>
+          <Typography variant="body-m" tone="secondary">
+            Ответ попадёт в историю заказа и закроет доставку. Случайный свайп его не отменит.
+          </Typography>
+        </Sheet.Body>
+        <Sheet.Footer>
+          <Sheet.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Клиент не вышел
+            </Button.Root>
+          </Sheet.Close>
+          <Sheet.Close>
+            <Button.Root>Передан</Button.Root>
+          </Sheet.Close>
+        </Sheet.Footer>
+      </Sheet.Content>
+    </Sheet.Root>
+  );
+}

package/dist/skill/reference/components/sheet/examples/examples.module.css

@@ -0,0 +1,13 @@
+/* Layout of the Sheet scenarios: semantic tokens only. */
+
+/* overview.tsx: a column of actions, one per row. */
+.actions {
+  display: grid;
+  gap: var(--prime-space-1);
+}
+
+/* in-form.tsx: field groups get 20 between them. */
+.form {
+  display: grid;
+  gap: var(--prime-space-5);
+}

package/dist/skill/reference/components/sheet/examples/in-form.tsx

@@ -0,0 +1,65 @@
+/** A short form that needs an explicit submit: the one case for a footer, Cancel and Send under the field, an empty comment keeps the sheet open — `Sheet.Footer`, `error`. */
+import { Button, Sheet, Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function SheetInFormExample() {
+  const formId = React.useId();
+  const [open, setOpen] = React.useState(false);
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const comment = String(new FormData(event.currentTarget).get("comment") ?? "").trim();
+    if (!comment) {
+      setError("Напишите, что передать курьеру");
+      return;
+    }
+    setOpen(false);
+  };
+
+  return (
+    <Sheet.Root
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) setError(undefined);
+      }}
+    >
+      <Sheet.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Комментарий курьеру
+        </Button.Root>
+      </Sheet.Trigger>
+      <Sheet.Content>
+        <Sheet.Header>
+          <Sheet.Title>Комментарий курьеру</Sheet.Title>
+          <Sheet.Description>Заказ № 1042 · доставка 5 октября</Sheet.Description>
+        </Sheet.Header>
+        <Sheet.Body>
+          <form id={formId} className={styles.form} noValidate onSubmit={submit}>
+            <Textarea.Root
+              label="Комментарий"
+              name="comment"
+              placeholder="Позвонить за час, домофон не работает"
+              error={error}
+              reserveSupportRow
+              onValueChange={() => setError(undefined)}
+            />
+          </form>
+        </Sheet.Body>
+        <Sheet.Footer>
+          <Sheet.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Отмена
+            </Button.Root>
+          </Sheet.Close>
+          <Button.Root type="submit" form={formId}>
+            Отправить
+          </Button.Root>
+        </Sheet.Footer>
+      </Sheet.Content>
+    </Sheet.Root>
+  );
+}

package/dist/skill/reference/components/sheet/examples/overview.tsx

@@ -0,0 +1,50 @@
+/** Actions with an order raised from the bottom edge: a header names the order, a column of actions follows, and each action closes the sheet — `Sheet.Trigger`, `Sheet.Header`, `Sheet.Close`. */
+import { Button, Icon, Sheet } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const ACTIONS = [
+  { label: "Повторить заказ", icon: "action.refresh" },
+  { label: "Скачать счёт", icon: "action.download" },
+  { label: "Скопировать ссылку", icon: "action.copy" },
+] as const;
+
+export default function SheetOverviewExample() {
+  return (
+    <Sheet.Root>
+      <Sheet.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Действия с заказом
+        </Button.Root>
+      </Sheet.Trigger>
+      <Sheet.Content>
+        <Sheet.Header>
+          <Sheet.Title>Заказ № 1042</Sheet.Title>
+          <Sheet.Description>Анна Смирнова · 12 480 ₽</Sheet.Description>
+        </Sheet.Header>
+        <Sheet.Body>
+          <div className={styles.actions}>
+            {ACTIONS.map((action) => (
+              <Sheet.Close key={action.label}>
+                <Button.Root variant="ghost" tone="neutral" fullWidth>
+                  <Button.Icon>
+                    <Icon name={action.icon} />
+                  </Button.Icon>
+                  {action.label}
+                </Button.Root>
+              </Sheet.Close>
+            ))}
+            <Sheet.Close>
+              <Button.Root variant="ghost" tone="danger" fullWidth>
+                <Button.Icon>
+                  <Icon name="action.delete" />
+                </Button.Icon>
+                Отменить заказ
+              </Button.Root>
+            </Sheet.Close>
+          </div>
+        </Sheet.Body>
+      </Sheet.Content>
+    </Sheet.Root>
+  );
+}

package/{src/components/drawer/examples/date-sheet.tsx → dist/skill/reference/components/sheet/examples/structure.tsx}

@@ -1,41 +1,35 @@
-/** 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";
+/** The content alone: a date sheet with no header and no footer, the calendar across its width, named by `aria-label`; a pick or a swipe down closes it — `aria-label`, `Sheet.Body`. */
+import { Button, Datepicker, Icon, Sheet } 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() {
+export default function SheetStructureExample() {
   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>
+    <Sheet.Root open={open} onOpenChange={setOpen}>
+      <Sheet.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>
+      </Sheet.Trigger>
+      <Sheet.Content aria-label="Дата отгрузки">
+        <Sheet.Body>
           <Datepicker.Panel
             mode="single"
-            className={styles.calendar}
             value={date}
             onValueChange={(next) => {
               setDate(next);
               setOpen(false);
             }}
           />
-        </Drawer.Body>
-      </Drawer.Content>
-    </Drawer.Root>
+        </Sheet.Body>
+      </Sheet.Content>
+    </Sheet.Root>
   );
 }

package/dist/skill/reference/components/skeleton/COMPONENT.md

@@ -0,0 +1,104 @@
+# Skeleton
+
+**Category:** status
+**Kind:** primitive
+
+> A placeholder in the shape of the content that is loading — text lines, a control, an avatar, a block — so the layout is in place before the data arrives.
+
+## When to use
+- A region whose content has a known shape is loading: a list, a card, a profile, a form with saved values.
+- The loading state inside [Crossfade](../crossfade/COMPONENT.md): the skeleton holds the data's geometry and cross-fades into it.
+- First load of a page section, when the structure is known before the values.
+
+## When not to use
+- Loading with no shape to hold (a button waiting for its request, a status line) → [Spinner](../spinner/COMPONENT.md), or `loading` on [Button](../button/COMPONENT.md).
+- A known progress (upload, steps) → [ProgressBar](../progress-bar/COMPONENT.md) or [ProgressCircle](../progress-circle/COMPONENT.md).
+- A table loading its rows → `loading` on [DataTable](../data-table/COMPONENT.md); it renders skeleton rows of its columns itself.
+- Data already on screen being refreshed → keep it and set `aria-busy`; do not swap it back to a skeleton.
+
+## Import
+```tsx
+import { Skeleton } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Skeleton           <span aria-hidden="true">; data-shape, data-size
+└─ line × lines    shape="text" only: one line box per line, a rounded bar in its middle
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Skeleton
+`ref` → `HTMLSpanElement`. A pulsing placeholder in the shape of loading content; `aria-hidden="true"`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `shape` | `"text" \| "control" \| "circle" \| "block"` | `"text"` | `text` — lines of the tier's text; `control` — a field or button of the tier; `circle` — an avatar of the tier; `block` — a box that fills its container (image, chart, card). |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the text line (control text size and line height), the control height or the avatar size. |
+| `lines` | `number` | `1` | `text` only: number of lines; the last of several is 60% wide. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` (width, height of a `block`), `data-*` and the other span attributes. |
+
+## Variants
+
+### shape
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `text` | rounded bars on the tier's text line boxes; the last of several lines is 60% wide | titles, names, descriptions, cells | yes |
+| `control` | a block of the tier's control height and radius, full width | fields, buttons, selects of a form | |
+| `circle` | a circle of the tier's avatar size | avatars, round icons | |
+| `block` | a radius-l block that fills its container (at least 64px high) | images, covers, charts, whole cards | |
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` · `s` · `m` · `l` · `xl` | text: the control text size and line height of the tier; control: the control height; circle: the avatar size | the tier of the content it stands for | host tier, else `m` |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| pulsing | mounted | opacity eases 1 → 0.6 and back (`slow × 5`, `standard`, alternate) |
+| reduced motion | `prefers-reduced-motion: reduce` | no pulse: the placeholder stands still and stays visible |
+| shape / size | `shape`, `size` | `data-shape`, `data-size` |
+
+## Layout & spacing
+- Put skeletons in the real layout of the content: the same grid, gaps and paddings, so the swap to data moves nothing.
+- Width: a text line and a control fill their container; narrow them with a `className` (a label is shorter than its field, an amount shorter than a name). Shape defaults have zero specificity, so a `className` always wins.
+- Height: text and control come from the tier; a `block` fills its container or takes a height from `className`.
+- Inside a sized host (a DataTable, a Popover, a field tier) `size` follows the host tier.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Decorative: `aria-hidden="true"`, screen readers skip it.
+- The loading region announces itself: `aria-busy` on it (Crossfade, a card, a form) and, when the wait matters, a `role="status"` text.
+- Under `prefers-reduced-motion` the placeholder does not pulse.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A project card while it loads: the cover, the author and two lines of text take the room of the real content — `shape`, `lines`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier of a text line, a control and an avatar circle: the placeholder matches the content of that tier — `size`, `shape`. |
+| [form.tsx](examples/form.tsx) | A settings form while its values load: labels are short text lines, fields and the button are controls of the same tier — `shape`. |
+| [with-crossfade.tsx](examples/with-crossfade.tsx) | A list that reloads: placeholder rows of the same geometry cross-fade into the data, nothing jumps — `Crossfade`, `state`. |
+
+## Mistakes
+- A hand-drawn grey box with its own `@keyframes` → use `Skeleton`.
+- A spinner in the middle of an empty card while its list loads → skeleton rows of that list.
+- Skeletons of a different geometry than the data (one tall block for three rows) → the swap jumps; mirror the rows.
+- Swapping a skeleton for data without `Crossfade` → wrap the region: `Crossfade state={loading ? "loading" : "ready"}`.
+- Returning to a skeleton on every refresh of data already shown → keep the data, set `aria-busy`.
+
+## Related
+- **Built from:** —
+- **See also:** [Crossfade](../crossfade/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md)