prime-ui-kit 0.14.0 → 0.16.0

package/src/components/select/COMPONENT.md

@@ -71,6 +71,8 @@ an icon) goes inside `Select.ItemMeta`.
 | `open` | `boolean` | — | Controlled open state of the list. |
 | `defaultOpen` | `boolean` | `false` | Initial open state, uncontrolled. |
 | `onOpenChange` | `(open: boolean) => void` | — | Called on every open and close: trigger, pick, Escape, an outside press. |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the list and returns focus to the trigger. |
+| `closeOnOutsideClick` | `boolean` | `true` | A press outside the list and its trigger closes it; focus follows the pointer. |
 | `label` | `ReactNode` | — | Field label above; names the trigger. |
 | `hint` | `ReactNode` | — | Support text under the field; linked by `aria-describedby`. |
 | `error` | `ReactNode` | — | Error message; replaces the hint and implies `invalid`. |
@@ -91,19 +93,21 @@ an icon) goes inside `Select.ItemMeta`.
 | `clearable` | `boolean` | `false` | A clear segment before the chevron while a value is set; `Delete` / `Backspace` on the trigger clear too. |
 | `name` | `string` | — | Form field name: hidden inputs submit the value (`""` while empty; one input per value with `multiple`). |
 | `placeholder` | `string` | — | Text in the trigger while nothing is picked. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Field tier: trigger height, padding, text; the list rows, the label and the hint follow it. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Field tier: trigger height, padding, text; the list rows, the label and the hint follow it. Without it the tier of its host (a form, a panel with a size), else `m`. |
 | `focusRing` | `boolean` | `true` | `false` hides the visual focus ring (`data-focus-ring="false"`), never focus or the error ring. |
 | `id` | `string` | — | Id of the trigger; generated when omitted. |
 | `labels` | `Partial<SelectLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — (required) | Trigger and Content. |
+| `className` | `string` | — | Class on the field frame `<div>`. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
 
 ### Select.Trigger
-`ref` → `HTMLButtonElement`. `<button role="combobox">` with the value, the clear segment and the chevron (a Spinner while `loading`). + native button props (`onFocus`, `onBlur`, `onKeyDown`… reach the button).
+`ref` → `HTMLButtonElement`. `<button role="combobox">` with the value, the clear segment and the chevron (a Spinner while `loading` or saving).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — | `Select.TriggerIcon`, `Select.Value`, optionally a Badge after it. A `Select.TriggerIcon` alone makes an icon-only trigger (the value read, not shown). |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "id" \| "type" \| "role">` | — | `onFocus`, `onBlur`, `onKeyDown`, `className` and the other button attributes reach the button. |
 
 ### Select.Value
 `ref` → `HTMLSpanElement`. The picked label (labels joined with `multiple`) with an ellipsis, or the placeholder.
@@ -114,10 +118,14 @@ an icon) goes inside `Select.ItemMeta`.
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other span attributes. |
 
 ### Select.TriggerIcon · Select.ItemIcon
-`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` with a leading glyph at the tier icon size: before the value / before the option label. + native `<span>` props.
+`ref` → `HTMLSpanElement`. An `aria-hidden` `<span>` with a leading glyph at the tier icon size: before the value / before the option label.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (the `Icon`), `className` and the other span attributes. |
 
 ### Select.Content
-`ref` → `HTMLDivElement` (the panel). Portal + the floating list panel with the search row, the `role="listbox"`, the empty and load states. Closed, the items render hidden so the trigger knows their labels. Below 640px it is a bottom sheet.
+`ref` → `HTMLDivElement` (the panel). Portal + the list panel: search row, `role="listbox"`, empty and load states; closed, the items render hidden so the trigger knows their labels. Below 640px a bottom sheet: scrim, handle, swipe down to close, page scroll locked.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -135,16 +143,23 @@ an icon) goes inside `Select.ItemMeta`.
 | `keywords` | `string` | — | Extra words for the search. |
 | `disabled` | `boolean` | `false` | Muted, skipped by the keyboard, not selectable. |
 | `children` | `ReactNode` | — (required) | Text, or `Select.ItemIcon`, `Avatar.Root`, `Thumbnail.Root`, `Select.ItemText`, `Select.ItemDescription`, `Select.ItemMeta`, `Badge.Root` as direct children. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role" \| "id" \| "children">` | — | `className`, `data-*`, `onClick` and the other attributes of the option row. |
 
 ### Select.ItemText · Select.ItemDescription · Select.ItemMeta
 `ref` → `HTMLSpanElement`. Rich option parts: the title (its text is the label) / a muted second line / a trailing muted value. Leading media is an `Avatar.Root` or `Thumbnail.Root` child, a trailing status a `Badge.Root`.
 
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The text. |
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `className` and the other span attributes. |
+
 ### Select.Group
-`ref` → `HTMLDivElement`. `<div role="group">` named by its `label`; hidden while the search leaves none of its options. + native `<div>` props.
+`ref` → `HTMLDivElement`. `<div role="group">` named by its `label`; hidden while the search leaves none of its options.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `label` | `ReactNode` | — | Heading of the group (caption, muted); also its accessible name. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `children` (the items), `className` and the other div attributes. |
 
 ### Select.Separator
 `ref` → `HTMLDivElement`. A full-bleed Divider between groups; hidden while searching.
@@ -154,7 +169,7 @@ an icon) goes inside `Select.ItemMeta`.
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the divider. |
 
 ### Select.Action
-`ref` → `HTMLDivElement`. A list-level action («Новый клиент»), a direct child of `Select.Content`: a `role="option"` row pinned under the list, never filtered, the last stop of the arrows; highlighted while the search finds nothing.
+`ref` → `HTMLDivElement`. A list-level action («Новый клиент»), a direct child of `Select.Content`: a `role="option"` row under the list (and the empty state), never filtered, the last stop of the arrows; when the search finds nothing it is highlighted and Enter runs it.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -182,7 +197,11 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | `clearable` | × segment before the chevron while a value is set (full height, one hover wash) | The field is optional and can be reset | `false` |
 | `loading` | spinner instead of the chevron; skeleton rows in the option geometry while no item is on screen | Options load asynchronously | `false` |
 | `loadingMore` | skeleton rows after the items | The next page is loading (`hasMore` + `onLoadMore`) | `false` |
-| `filter={false}` | every item shows whatever the query; the query is still marked in the labels | The owner searches on the server (`search`, `onSearchChange`) | `true` |
+| `filter` | items filter by the query; off, every item shows whatever the query and the query is still marked in the labels | Off when the owner searches on the server (`search`, `onSearchChange`) | `true` |
+| `required` / `optional` | red `*` / muted «необязательно» after the label | Mark the minority of the form | `false` / — |
+| `focusRing` | `false`: no focus ring; the trigger keeps its focus fill | Only where focus shows otherwise; never on a form field (WCAG 2.4.7) | `true` |
+| `closeOnOutsideClick` | `false`: the list stays open on a press beside it; Escape, the trigger, a single pick and Tab still close it | A filter list the person compares with the page | `true` |
+| `closeOnEscape` | `false`: Escape leaves the list open | The list must close only by a pick or the trigger | `true` |
 | `searchable` (Content) | search row with a faint hairline at the top of the list | More than ~10 options | `false` |
 | rich options | `Thumbnail.Root` or `Select.ItemDescription` in an item: a two-line row; `Avatar.Root` before the text and `Badge.Root` after it keep one line; the trigger the same with `renderValue` | Products, people, delivery tariffs | |
 | `Select.Action` | a row under the list behind a faint full-bleed hairline, with an optional leading icon; stays whatever the query | One list-level action: «Новый клиент», «Пригласить в команду» | |
@@ -194,7 +213,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | State | Driven by | DOM |
 |---|---|---|
 | empty | no value | `data-placeholder="true"` on Value, placeholder color |
-| open | `open` / click / arrows | trigger `data-state="open"`, `aria-expanded`; panel `data-state`, `data-side`; chevron turns 180° |
+| open | `open` / `defaultOpen` / click / arrows | trigger `data-state="open"`, `aria-expanded`; panel `data-state`, `data-side`; chevron turns 180° |
 | invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the trigger; error text below; the control shakes once when an error arrives (`data-shake` on the frame) |
 | disabled | `disabled` | native `disabled`, `data-disabled="true"` |
 | loading | `loading` | `data-loading="true"`, `aria-busy` on the trigger and the list; with no item on screen, `aria-hidden` skeleton rows (`data-skeleton`) in the list; `labels.loading` in a polite live region |
@@ -209,7 +228,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 
 ## Layout & spacing
 - The trigger is 100% wide; set the width with the layout (grid column, max-width wrapper).
-- Label → field: tier `label-gap`; field → hint: tier `hint-gap`; field → field in a form: `--prime-space-5`.
+- Label → field: tier `label-gap`; field → hint: tier `hint-gap`; field → field in a form: the gap of a label-less `Fieldset`.
 - Panel: at least the trigger width and `--prime-panel-min-width`, at most twice that; max height `--prime-panel-max-height` (scrolls); flips near the viewport edge.
 - Long values truncate with an ellipsis in the trigger.
 - The clear segment's hit area grows to the 44 px touch target in height on a coarse pointer, like the clear segment of an Input.
@@ -254,6 +273,8 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Enter` · `Space` · `ArrowDown` · `ArrowUp` | On the trigger open the list; focus moves into the search or the list. |
@@ -266,6 +287,8 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | `Tab` | Returns focus to the trigger, closes the list and moves on from the trigger. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The trigger is `role="combobox"` with `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`; `label` names it.
 - The list is `role="listbox"` (`aria-multiselectable` with `multiple`); options are `role="option"` with `aria-selected`; the highlight goes through `aria-activedescendant`.
 - The hint and the error are linked by `aria-describedby`; the error sets `aria-invalid`; loading sets `aria-busy`.
@@ -295,7 +318,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A labelled field with a placeholder; picking an option closes the list and shows its label — `label`, `placeholder`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier; the label, the list rows and the hint take the tier of the field — `size`. |
-| [states.tsx](examples/states.tsx) | A default field next to a disabled, a loading, an invalid one and a list with nothing in it — `disabled`, `loading`, `invalid`, `labels`. |
+| [states.tsx](examples/states.tsx) | A default field next to a disabled, a loading, an invalid one, a list with nothing in it and a field whose focus shows without the ring — `disabled`, `loading`, `invalid`, `labels`, `focusRing`. |
 | [validation.tsx](examples/validation.tsx) | Live validation: unassigning the owner shakes the field and drops the error in, picking someone clears it; required and optional markers and a hint — `required`, `optional`, `hint`, `error`. |
 | [with-icon.tsx](examples/with-icon.tsx) | A leading icon in the trigger and an icon before every option label — `Select.TriggerIcon`, `Select.ItemIcon`. |
 | [multiple.tsx](examples/multiple.tsx) | Several values: checkboxes in the list, the list stays open on a pick, labels joined in the trigger — `multiple`. |
@@ -308,6 +331,7 @@ No `variant` or `tone`. The trigger is the field look (fill, inset control borde
 | [rich-options.tsx](examples/rich-options.tsx) | Options with a picture, a second line and a price; the trigger draws the picked option with the same parts — `renderValue`, `Select.ItemText`, `Select.ItemDescription`, `Select.ItemMeta`. |
 | [people.tsx](examples/people.tsx) | People in the rows and the trigger: an avatar sized to the tier before the name, a role badge after it — `Avatar.Root`, `Badge.Root`, `renderValue`. |
 | [icon-only.tsx](examples/icon-only.tsx) | An icon picker as wide as its glyph: the trigger holds only the picked icon and the chevron, the value is still read aloud — `Select.TriggerIcon`. |
+| [dismiss.tsx](examples/dismiss.tsx) | A filter list that stays open while the person looks beside it: only Escape, the trigger or Tab close it — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the value: the plan drives the price under the field and a button resets it — `value`, `onValueChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the list: a button opens it from code, a pick or Escape closes it — `open`, `onOpenChange`. |
 | [in-form.tsx](examples/in-form.tsx) | Regional settings form: the required country is checked on submit, the error shakes the field and leaves once a country is picked, a calm note confirms the save — `required`, `error`, `hint`. |

package/src/components/select/examples/dismiss.tsx

@@ -0,0 +1,26 @@
+/** A filter list that stays open while the person looks beside it: only Escape, the trigger or Tab close it — `closeOnOutsideClick`, `closeOnEscape`. */
+import { Select } from "prime-ui-kit";
+
+export default function SelectDismissExample() {
+  return (
+    <Select.Root
+      label="Статусы заказов"
+      multiple
+      defaultValue={["new", "paid"]}
+      placeholder="Все статусы"
+      closeOnOutsideClick={false}
+      closeOnEscape
+    >
+      <Select.Trigger>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        <Select.Item value="new">Новый</Select.Item>
+        <Select.Item value="paid">Оплачен</Select.Item>
+        <Select.Item value="shipped">Отгружен</Select.Item>
+        <Select.Item value="delivered">Доставлен</Select.Item>
+        <Select.Item value="cancelled">Отменён</Select.Item>
+      </Select.Content>
+    </Select.Root>
+  );
+}

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

@@ -5,7 +5,7 @@
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-8);
-  width: min(100%, var(--prime-modal-width-m));
+  width: min(100%, var(--prime-layout-form-width-m));
 }
 
 .formHeader {
@@ -16,7 +16,8 @@
 
 .formFields {
   display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
+  /* Two columns while each keeps 12rem, one column in a narrower form — from its own width. */
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--prime-space-16) * 3)), 1fr));
   align-items: start;
   gap: var(--prime-space-5) var(--prime-space-4);
 }
@@ -27,9 +28,3 @@
   justify-content: flex-end;
   gap: var(--prime-space-2);
 }
-
-@media (max-width: 639px) {
-  .formFields {
-    grid-template-columns: minmax(0, 1fr);
-  }
-}

package/src/components/select/examples/server-search.tsx

@@ -43,9 +43,13 @@ export default function SelectServerSearchExample() {
   const [total, setTotal] = React.useState(0);
   const [loading, setLoading] = React.useState(true);
   const [loadingMore, setLoadingMore] = React.useState(false);
+  const pageTimer = React.useRef(0);
 
-  // A new query asks the server after a pause; the results on screen stay until the answer.
+  // A new query asks the server after a pause; the results on screen stay until the answer. A
+  // next page still on its way belongs to the old query: it is dropped.
   React.useEffect(() => {
+    window.clearTimeout(pageTimer.current);
+    setLoadingMore(false);
     setLoading(true);
     const timer = window.setTimeout(() => {
       const found = findClients(search);
@@ -58,7 +62,7 @@ export default function SelectServerSearchExample() {
 
   const loadMore = () => {
     setLoadingMore(true);
-    window.setTimeout(() => {
+    pageTimer.current = window.setTimeout(() => {
       setClients((shown) => findClients(search).slice(0, shown.length + PAGE_SIZE));
       setLoadingMore(false);
     }, LATENCY_MS);

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

@@ -5,7 +5,7 @@ const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function SelectSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
         <Select.Root key={size} size={size} label={size} defaultValue="week">
           <Select.Trigger>
@@ -18,6 +18,6 @@ export default function SelectSizesExample() {
           </Select.Content>
         </Select.Root>
       ))}
-    </>
+    </div>
   );
 }

package/src/components/select/examples/states.tsx

@@ -1,4 +1,4 @@
-/** A default field next to a disabled, a loading, an invalid one and a list with nothing in it — `disabled`, `loading`, `invalid`, `labels`. */
+/** A default field next to a disabled, a loading, an invalid one, a list with nothing in it and a field whose focus shows without the ring — `disabled`, `loading`, `invalid`, `labels`, `focusRing`. */
 import { Select } from "prime-ui-kit";
 
 const ROLES = [
@@ -9,7 +9,7 @@ const ROLES = [
 
 export default function SelectStatesExample() {
   return (
-    <>
+    <div>
       <Select.Root label="default" defaultValue="editor">
         <Select.Trigger>
           <Select.Value />
@@ -62,6 +62,18 @@ export default function SelectStatesExample() {
         </Select.Trigger>
         <Select.Content>{null}</Select.Content>
       </Select.Root>
-    </>
+      <Select.Root label="focusRing={false}" defaultValue="editor" focusRing={false}>
+        <Select.Trigger>
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          {ROLES.map((role) => (
+            <Select.Item key={role.value} value={role.value}>
+              {role.label}
+            </Select.Item>
+          ))}
+        </Select.Content>
+      </Select.Root>
+    </div>
   );
 }

package/src/components/select/examples/with-icon.tsx

@@ -13,23 +13,25 @@ export default function SelectWithIconExample() {
   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>
+    <div>
+      <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>
+    </div>
   );
 }

package/src/components/sheet/COMPONENT.md

@@ -26,7 +26,7 @@ import { Sheet } from "prime-ui-kit";
 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
+   ├─ (grab handle)            aria-hidden bar on top while the sheet swipes (`closeOnOutsideClick`); 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
@@ -52,12 +52,12 @@ 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. 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. |
+| `closeOnOutsideClick` | `boolean` | `true` | A click on the scrim (and a swipe down, which draws the grab handle) closes the dialog. A destructive action is confirmed in a ConfirmDialog; unsaved changes are held by `Guard`. |
 | `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`.
+`ref` → `HTMLDivElement` (the dialog panel). Portal + scrim + `role="dialog"` panel raised from the bottom edge, as tall as its content, with a grab handle while it swipes. Header and footer are optional: without a header name it with `aria-label`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -68,15 +68,20 @@ No DOM, no ref. State and dismiss policy.
 | `…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>`.
+`ref` → `HTMLElement`. Renders `<header>`: [Icon] [Title + Description] [Actions] [close button].
 
 | 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. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other attributes of the `<header>`. |
 
 ### 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.
+`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`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `children` and the other attributes of the row. |
 
 ### Sheet.Icon
 `ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill; around an `Avatar.Root` or a `Thumbnail.Root` (the record's picture) no tile — `data-media`, the avatar sized to 40 px.
@@ -84,35 +89,48 @@ No DOM, no ref. State and dismiss policy.
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Soft fill and icon color; not used around a picture. |
-| `children` | `ReactNode` | — (required) | An icon glyph (sized to the m icon), or the record's picture: an `Avatar.Root` (sized to the tile) or a `Thumbnail.Root`. |
+| `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. |
 
 ### 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`.
+`ref` → `HTMLHeadingElement` / `HTMLParagraphElement`. `<h2>` (title-m) / `<p>` (body-s, muted); their ids name and describe the dialog.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLHeadingElement \| HTMLParagraphElement>, "id">` | — | `className`, `children` and the other attributes except `id` (the dialog owns it). |
 
 ### Sheet.Body
-`ref` → `HTMLDivElement`. The only scrolling zone (a ScrollContainer), 16 gap between blocks. + native `<div>` props.
+`ref` → `HTMLDivElement`. The only scrolling zone (a ScrollContainer), 16 gap between blocks.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `children` and the other attributes of the zone. |
 
 ### Sheet.Footer
-`ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last, and an optional `Meta` at the start. + native `HTMLAttributes<HTMLElement>`.
+`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. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `className`, `children` and the other attributes of the `<footer>`. |
 
 ### 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.
+`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.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLParagraphElement>` | — | `className`, `children` and the other attributes of the `<p>`. |
 
 ### 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. |
+| `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. The grab handle stays and takes no drag. |
+| `dirty` | `boolean` | `false` | Unsaved changes: any of those dismisses (a swipe glides back 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.
+No DOM: each clones its child. `Trigger` and `Close` chain its `onClick` (skipped after `preventDefault()`): open; close through `Guard`, `disabled` while it is busy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -141,11 +159,12 @@ Sheet has no `variant`, `side` or `size`: it always rises from the bottom edge,
 | 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 |
+| dismiss | `closeOnEscape`, `closeOnOutsideClick` (both default `true`) | Escape, a scrim press and a swipe down ask the Root to close; `false` turns that way off (`closeOnOutsideClick={false}`: no handle, no swipe) |
+| swiping | a drag down from the handle or the header (with `closeOnOutsideClick`; without it there is no handle and no swipe) | `data-swiping` and `--swipe-offset` on the panel while the pointer drags it, `data-swipe-dismissed` while it glides out after a closing release — both mirrored on the scrim, which carries `--swipe-progress` (0…1) |
 | 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 |
+| 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; the handle stays, `data-swipe-disabled` on the panel (no grab cursor) |
+| dirty | `Sheet.Guard dirty` | a dismiss opens the «Не сохранять изменения?» ConfirmDialog (`labels.discard*`); a swipe past the threshold glides back and asks the same |
 
 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.
 
@@ -154,7 +173,7 @@ Motion: the scrim fades, the sheet slides up over `slow` and down over `base` (`
   - **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.
+- Zone padding `--prime-sheet-padding`, width `--prime-sheet-width`. The bottom-sheet surface (`src/internal/sheet.module.css`, shared with a Modal and the floating layers on a phone) gives the height by content up to the top gap, the rounded top, the handle strip and 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.
@@ -170,17 +189,21 @@ Motion: the scrim fades, the sheet slides up over `slow` and down over `base` (`
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | 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.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- `role="dialog"`, `aria-modal="true"`, named by `Sheet.Title` — without a header by `aria-label` on `Sheet.Content`; described by `Sheet.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 «Продолжить».
+- A swipe down from the grab handle or the header is an extra way out next to Escape and the scrim, following `closeOnOutsideClick`: with it off there is no swipe and no handle. The handle is `aria-hidden`.
+- A `Guard` that is `busy` holds every dismiss: the handle stays and takes no drag. A `dirty` one glides a swipe back and opens a `role="alertdialog"` confirm with focus on «Продолжить», as every other dismiss does.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -198,6 +221,8 @@ Motion: the scrim fades, the sheet slides up over `slow` and down over `base` (`
 |---|---|
 | [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`. |
+| [header-actions.tsx](examples/header-actions.tsx) | The courier is at the door: an icon tile heads the sheet, the payment status and a ⋯ menu sit before the close button, and two equal buttons fill the footer — `Sheet.Icon`, `Sheet.Actions`, `layout`. |
+| [guard.tsx](examples/guard.tsx) | A review form that holds the sheet: after an edit a swipe, the scrim, Escape and Cancel ask before discarding and the footer says so; sending locks every way out — `Sheet.Guard`, `Sheet.Meta`. |
 | [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`. |
@@ -212,5 +237,5 @@ Motion: the scrim fades, the sheet slides up over `slow` and down over `base` (`
 - `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)
+- **Built from:** the dialog shared with Modal and Drawer (`internal/overlay/DialogParts`), [Button](../button/COMPONENT.md) (close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Sheet.Body`), [Avatar](../avatar/COMPONENT.md) and [Thumbnail](../thumbnail/COMPONENT.md) (a record's picture in `Sheet.Icon`), [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/src/components/sheet/examples/guard.tsx

@@ -0,0 +1,72 @@
+/** A review form that holds the sheet: after an edit a swipe, the scrim, Escape and Cancel ask before discarding and the footer says so; sending locks every way out — `Sheet.Guard`, `Sheet.Meta`. */
+import { Button, Fieldset, Sheet, Textarea } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+/** Pretends to send the review. */
+function sendReview() {
+  return new Promise((resolve) => setTimeout(resolve, 1200));
+}
+
+export default function SheetGuardExample() {
+  const formId = React.useId();
+  const [open, setOpen] = React.useState(false);
+  const [dirty, setDirty] = React.useState(false);
+  const [sending, setSending] = React.useState(false);
+
+  const submit = async (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSending(true);
+    await sendReview();
+    setSending(false);
+    setDirty(false);
+    setOpen(false);
+  };
+
+  return (
+    <Sheet.Root
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next);
+        if (!next) setDirty(false);
+      }}
+    >
+      <Sheet.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Отзыв о доставке
+        </Button.Root>
+      </Sheet.Trigger>
+      <Sheet.Content>
+        <Sheet.Guard busy={sending} dirty={dirty} />
+        <Sheet.Header>
+          <Sheet.Title>Отзыв о доставке</Sheet.Title>
+          <Sheet.Description>Заказ № 1042 · курьер Олег Р.</Sheet.Description>
+        </Sheet.Header>
+        <Sheet.Body>
+          <form id={formId} className={styles.form} onSubmit={submit}>
+            <Fieldset disabled={sending}>
+              <Textarea.Root
+                label="Что понравилось или нет"
+                name="review"
+                placeholder="Привёз вовремя, помог занести коробки"
+                onValueChange={() => setDirty(true)}
+              />
+            </Fieldset>
+          </form>
+        </Sheet.Body>
+        <Sheet.Footer>
+          {dirty ? <Sheet.Meta>Есть несохранённые изменения</Sheet.Meta> : null}
+          <Sheet.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Отмена
+            </Button.Root>
+          </Sheet.Close>
+          <Button.Root type="submit" form={formId} loading={sending} disabled={!dirty}>
+            Отправить
+          </Button.Root>
+        </Sheet.Footer>
+      </Sheet.Content>
+    </Sheet.Root>
+  );
+}