prime-ui-kit 0.3.1 → 0.4.0

package/src/components/divider/examples/inset-stack.tsx

@@ -0,0 +1,33 @@
+import { Divider } from "prime-ui-kit";
+
+import s from "./divider-examples.module.css";
+
+/**
+ * Stack with a leading icon column: copy is inset in the text column while dividers span the full card width,
+ * matching common settings / list layouts.
+ */
+export default function DividerInsetStackExample() {
+  return (
+    <section className={s.card}>
+      <div className={s.stack}>
+        <div className={s.rowWithIcon}>
+          <span className={s.iconStub} aria-hidden />
+          <div className={s.rowMain}>
+            <p className={s.rowTitle}>Workspace</p>
+            <p className={s.rowDesc}>Renaming affects the sidebar and shared links.</p>
+          </div>
+        </div>
+
+        <Divider.Root size="m" />
+
+        <div className={s.rowWithIcon}>
+          <span className={s.iconStub} aria-hidden />
+          <div className={s.rowMain}>
+            <p className={s.rowTitle}>Billing</p>
+            <p className={s.insetBody}>Payment method and invoices (inset body copy).</p>
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}

package/src/components/divider/examples/line-spacing-column.tsx

@@ -0,0 +1,27 @@
+import { Divider } from "prime-ui-kit";
+
+import s from "./divider-examples.module.css";
+
+/**
+ * `variant="line-spacing"` between flex children: vertical rhythm comes from the parent `gap`, not from the
+ * divider stretching as a spacer.
+ */
+export default function DividerLineSpacingColumnExample() {
+  return (
+    <div className={`${s.shell} ${s.stack}`}>
+      <p className={s.body}>First block in a column with gap-driven spacing.</p>
+      <Divider.Root variant="line-spacing" size="m" />
+      <p className={s.body}>Second block — the divider is only a marker between siblings.</p>
+      <Divider.Root variant="line-spacing" size="m" />
+      <div className={s.toolbar}>
+        <button className={s.toolbarBtn} type="button">
+          One
+        </button>
+        <Divider.Root orientation="vertical" size="m" />
+        <button className={s.toolbarBtn} type="button">
+          Two
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/divider/examples/list-separators.tsx

@@ -0,0 +1,20 @@
+import { Divider } from "prime-ui-kit";
+
+import s from "./divider-examples.module.css";
+
+/** Full-width horizontal dividers between rows inside a bordered list shell. */
+export default function DividerListSeparatorsExample() {
+  return (
+    <ul className={s.list}>
+      <li className={s.listRow}>Inbox</li>
+      <li className={s.listSep} aria-hidden>
+        <Divider.Root size="s" role="presentation" />
+      </li>
+      <li className={s.listRow}>Sent</li>
+      <li className={s.listSep} aria-hidden>
+        <Divider.Root size="s" role="presentation" />
+      </li>
+      <li className={s.listRow}>Archive</li>
+    </ul>
+  );
+}

package/src/components/divider/examples/section-breaks.tsx

@@ -0,0 +1,27 @@
+import { Divider } from "prime-ui-kit";
+
+import s from "./divider-examples.module.css";
+
+/** Section rhythm: `variant="text"` labels blocks; pair with real headings where structure matters for a11y. */
+export default function DividerSectionBreaksExample() {
+  return (
+    <article className={s.card}>
+      <div className={s.stackLoose}>
+        <header>
+          <h2 className={s.heading}>Account</h2>
+          <p className={s.muted}>Profile and security</p>
+        </header>
+
+        <Divider.Root variant="text" size="m">
+          General
+        </Divider.Root>
+        <p className={s.body}>Name, email, and language preferences apply across all workspaces.</p>
+
+        <Divider.Root variant="text" size="m">
+          Notifications
+        </Divider.Root>
+        <p className={s.body}>Choose channels for product updates and billing alerts.</p>
+      </div>
+    </article>
+  );
+}

package/src/components/drawer/COMPONENT.md

@@ -6,21 +6,21 @@
 
 A slide-over panel rendered in a portal with a backdrop: page scroll is locked, focus stays inside the dialog until it closes, and siblings of the portal root on `document.body` are marked inert and `aria-hidden` while open.
 
-- **When to use** — secondary detail, filters, forms, or actions tied to a screen edge (left/right/top/bottom) without leaving the current view.
-- **When to use** — bottom or top sheets when the main canvas (e.g. a map) should stay partly visible.
-- **When to use** — the same modal-style contract as a dialog (focus trap, blocked background) but with an edge-attached panel instead of a centered box.
-- **When not to use** — short confirmations or compact prompts; prefer a centered [Modal](../modal/COMPONENT.md).
-- **When not to use** — inline expandable regions; use disclosure or a non-modal sidebar if you should not block the whole page.
-- **When not to use** — full page changes driven only by the URL; the kit does not wire routing—control `open` / `onOpenChange` from the app.
+- **Use** for secondary detail, filters, forms, or actions tied to a screen edge (left/right/top/bottom) without leaving the current view.
+- **Use** for bottom or top sheets when the main canvas (for example a map) should stay partly visible.
+- **Use** for the same modal-style contract as a dialog (focus trap, blocked background) but with an edge-attached panel instead of a centered box.
+- **Do not use** for short confirmations or compact prompts; prefer a centered [Modal](../modal/COMPONENT.md).
+- **Do not use** for inline expandable regions; use disclosure or a non-modal sidebar if you should not block the whole page.
+- **Do not use** for full page changes driven only by the URL; the kit does not wire routing—control `open` / `onOpenChange` from the app.
 
 ## Composition
 
 - **`Drawer.Root`** — holds open state, `closeOnEscape`, and `closeOnOverlayClick`; wraps everything else.
 - **`Drawer.Trigger`** (optional) — exactly one child element; opens on click unless the child’s `onClick` calls `preventDefault`.
 - **`Drawer.Portal`** — renders nothing when closed; when open, portals children (default container `document.body` via the internal `Portal`).
-- **`Drawer.Overlay`** and **`Drawer.Content`** should be **siblings** inside **`Drawer.Portal`** (backdrop is not a wrapper around the panel). List **`Drawer.Overlay`** before **`Drawer.Content`** so the panel paints above the backdrop when stacking order ties on `z-index`.
-- **`Drawer.Content`** — `role="dialog"`, `aria-modal="true"`, focus trap, and chrome size context for header/footer controls.
-- **`Drawer.Header`** → **`Drawer.Title`**, **`Drawer.Body`**, **`Drawer.Footer`** — all **must** be nested inside **`Drawer.Content`** (runtime error otherwise). **`Drawer.Close`** wraps a single control that should close the drawer (often a button in the footer or custom actions).
+- **`Drawer.Overlay`** and the panel surface should be **siblings** inside **`Drawer.Portal`** (backdrop is not a wrapper around the panel). List **`Drawer.Overlay`** before the panel so it stacks under the dialog when `z-index` ties.
+- **Panel surface:** at the portal root, **`Drawer.Content`** renders the full dialog shell (`role="dialog"`, focus trap, scroll lock, inert siblings, chrome size for header/footer). For a split where only the middle scrolls, use **`Drawer.Panel`** as the shell and nest **`Drawer.Content`** for the body region — see **`examples/explicit-panel.tsx`**.
+- **`Drawer.Header`** → **`Drawer.Title`**, **`Drawer.Body`**, **`Drawer.Footer`** — all **must** be nested inside the panel surface (**`Drawer.Content`** at root or **`Drawer.Panel`**). **`Drawer.Close`** wraps a single control that should close the drawer (often a button in the footer or custom actions).
 
 ### Minimal example
 
@@ -51,14 +51,42 @@ export function DrawerMinimal() {
 }
 ```
 
+### Playground snippets (source of truth)
+
+Runnable demos and copy-paste references: `playground/snippets/drawer/*.tsx` (Russian copy in UI; workspace imports use `@/`).
+
+| File | Intent |
+|------|--------|
+| `sizes.tsx` | Ladder **`size`** `s`–`xl` on **`Drawer.Content`**; padding, title tier, header close button, and footer controls share one control tier. |
+| `variants-sides.tsx` | **`side`** `right` (default), `left`, `bottom`, `top`; top/bottom sheets use capped height (~**`80vh`** in styles) and scroll in **`Drawer.Body`**. |
+| `states.tsx` | **`closeOnEscape={false}`** and **`closeOnOverlayClick={false}`** for dismiss only via actions; **`showCloseButton={false}`** on **`Drawer.Header`**. |
+| `controlled.tsx` | **`open`** / **`onOpenChange`** on **`Drawer.Root`** without **`Drawer.Trigger`**. |
+| `composition.tsx` | Header, **`Input`** in **`Drawer.Body`**, footer with **`Drawer.Close`** on cancel. |
+| `full-width.tsx` | Vertical stack in **`Drawer.Footer`** with **`Button.Root`** **`fullWidth`**. |
+| `responsive.tsx` | Side width cap **`min(28rem, 90vw)`**; long copy scrolls in **`Drawer.Body`**. |
+| `trigger-link.tsx` | **`Drawer.Trigger`** with a single **`LinkButton`** child; opening merges with existing **`onClick`** (e.g. **`preventDefault`** on **`href`**). |
+| `features.tsx` | **`Drawer.Portal`** **`container`**, **`aria-label`** on **`Drawer.Content`** without a visible title row, long list scroll inside **`Drawer.Body`**. |
+
+### Examples (`examples/`)
+
+English scenario starters next to this file (workspace **`@/`**; published **`prime-ui-kit`**):
+
+| File | Intent |
+|------|--------|
+| `examples/filters-panel.tsx` | Leading-edge filters; scroll criteria, **Apply** / **Reset** in footer. |
+| `examples/cart-preview.tsx` | Trailing-edge cart preview; line items scroll; checkout in footer. |
+| `examples/settings-side.tsx` | Trailing-edge settings; form fields share drawer **`size`** with chrome. |
+| `examples/mobile-nav-sheet.tsx` | Bottom sheet nav; rows wrapped in **`Drawer.Close`**. |
+| `examples/explicit-panel.tsx` | **`Drawer.Panel`** shell with inner **`Drawer.Content`** as scroll body only. |
+
 ## Rules
 
 - **Controlled vs uncontrolled:** pass `open` and `onOpenChange` for controlled mode; otherwise use `defaultOpen` on `Drawer.Root`. Omit `Drawer.Trigger` when you open/close from parent state only.
-- **Closing:** Escape and backdrop click call `onClose` by default; disable with `closeOnEscape={false}` and/or `closeOnOverlayClick={false}` on `Drawer.Root` for explicit-dismiss-only flows. Backdrop close runs only when the click target is the overlay element itself (not bubbled from children).
+- **Closing:** Escape and overlay click update open state by default (and invoke **`onOpenChange`** when controlled). Disable with `closeOnEscape={false}` and/or `closeOnOverlayClick={false}` on `Drawer.Root` for explicit-dismiss-only flows. Escape is handled while the panel is open (same layer as the dialog focus trap). Backdrop close runs only when the click target is the overlay element itself (not bubbled from children).
 - **`Drawer.Trigger` / `Drawer.Close`:** each expects **exactly one** React child that accepts an `onClick` handler; the kit merges its handler with yours and respects `preventDefault`.
-- **Accessible name:** set `aria-labelledby` on `Drawer.Content` to the `id` of `Drawer.Title`, or `aria-label` when there is no visible title.
+- **Accessible name:** set `aria-labelledby` on the panel to the `id` of `Drawer.Title`, or `aria-label` when there is no visible title.
 - **Header close control:** `showCloseButton={false}` on `Drawer.Header` removes the built-in ghost button (`aria-label` is `"Close drawer"` in code when shown).
-- **Sizing:** `size` on `Drawer.Content` is `s` | `m` | `l` | `xl` (default `m`); it drives padding, title scale, and control sizing in chrome via `ControlSizeProvider`. Panel width/height caps come from the component styles, not separate width/height props.
+- **Sizing:** `size` on the panel (`Drawer.Content` at root or `Drawer.Panel`) is `s` | `m` | `l` | `xl` (default `m`); it drives padding, title scale, and control sizing in chrome via `ControlSizeProvider`. Side panels cap width in CSS (**`min(28rem, 90vw)`**); top/bottom sheets cap height (~**`80vh`**), not separate width/height props.
 - **Portal:** `Drawer.Portal` renders `null` while closed, so portal subtree is unmounted when not open.
 
 ## API
@@ -69,8 +97,8 @@ export function DrawerMinimal() {
 |------|------|---------|----------|-------------|
 | `open` | `boolean` | — | No | Controlled open state. |
 | `defaultOpen` | `boolean` | `false` | No | Initial open state when uncontrolled. |
-| `onOpenChange` | `(open: boolean) => void` | — | No | Called when open state changes. |
-| `closeOnEscape` | `boolean` | `true` | No | Close when Escape is pressed while open. |
+| `onOpenChange` | `(open: boolean) => void` | — | No | Called when open state changes (trigger, dismiss, programmatic). |
+| `closeOnEscape` | `boolean` | `true` | No | Close on Escape while the panel is open. |
 | `closeOnOverlayClick` | `boolean` | `true` | No | Close when the overlay receives a direct click. |
 | `children` | `React.ReactNode` | — | Yes | Tree: trigger, portal, etc. |
 
@@ -84,39 +112,49 @@ export function DrawerMinimal() {
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `children` | `React.ReactElement<{ onClick?: React.MouseEventHandler; className?: string }>` | — | Yes | Single child; click closes unless default prevented. |
+| `children` | `React.ReactElement<{ onClick?: React.MouseEventHandler; className?: string }>` | — | Yes | Single child; click runs your `onClick` then closes unless default prevented. |
 
 ### Drawer.Portal
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `children` | `React.ReactNode` | — | Yes | Portaled subtree; not mounted when closed. |
+| `children` | `React.ReactNode` | — | No | Portaled subtree; not mounted when closed. |
 | `container` | `HTMLElement \| null` | `document.body` | No | DOM node for `createPortal` (falls back when `null`/omitted per `Portal` implementation). |
 
 ### Drawer.Overlay
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Spread onto the backdrop `div` (`role="presentation"` set in the component). |
+| `className` | `string` | — | No | Extra class on the backdrop. |
+| `onClick` | `React.MouseEventHandler<HTMLDivElement>` | — | No | Fires before overlay dismiss logic. |
+| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | `role="presentation"`; remaining attributes on the backdrop `div`. |
 
 ### Drawer.Content
 
+When used as the **direct** child of **`Drawer.Portal`** (after **`Drawer.Overlay`**), renders the dialog panel. When nested **inside** an existing panel, renders the scrollable body region only (see **`examples/explicit-panel.tsx`**).
+
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `side` | `"left" \| "right" \| "bottom" \| "top"` | `"right"` | No | Edge from which the panel enters. |
-| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Chrome and spacing tier for header/footer controls. |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Chrome and spacing tier for header/footer controls (`ControlSizeProvider`). |
 | `aria-label` | `string` | — | No | Accessible name when no visible title. |
 | `aria-labelledby` | `string` | — | No | `id` of the visible title element. |
 | `aria-describedby` | `string` | — | No | `id` of auxiliary description content. |
-| `className` | `string` | — | No | Class on the dialog root. |
-| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Additional attributes on the dialog `div` (`role="dialog"`, `aria-modal`, `tabIndex={-1}`, focus trap ref). |
+| `className` | `string` | — | No | Class on the panel or inner body root. |
+| `children` | `React.ReactNode` | — | No | Shell slots (header, body, footer) when panel root; scroll content when nested. |
+| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Panel: `role="dialog"`, `aria-modal`, `tabIndex={-1}`, focus trap, scroll lock, inert siblings. |
+
+### Drawer.Panel
+
+Same props as **`Drawer.Content`** when **`Drawer.Content`** is the portal-root panel. Use **`Drawer.Panel`** for explicit shell + inner **`Drawer.Content`** body scrolling — **`examples/explicit-panel.tsx`**.
 
 ### Drawer.Header
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `showCloseButton` | `boolean` | `true` | No | Renders the built-in icon close button. |
+| `showCloseButton` | `boolean` | `true` | No | Built-in ghost close control (neutral) on the right. |
 | `className` | `string` | — | No | Class on the `<header>`. |
+| `children` | `React.ReactNode` | — | No | Usually **`Drawer.Title`**; area left of the close control. |
 | … | `React.HTMLAttributes<HTMLElement>` | — | No | Native `<header>` attributes. |
 
 ### Drawer.Title
@@ -124,6 +162,7 @@ export function DrawerMinimal() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `className` | `string` | — | No | Class on the `<h2>`. |
+| `children` | `React.ReactNode` | — | No | Title text; set `id` for `aria-labelledby` on the panel. |
 | … | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | Renders `<h2>`. |
 
 ### Drawer.Body
@@ -131,6 +170,7 @@ export function DrawerMinimal() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `className` | `string` | — | No | Class on the scroll container root. |
+| `children` | `React.ReactNode` | — | No | Main content; vertical scroll when overflowing. |
 | … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Scrollable body via `ScrollContainer`. |
 
 ### Drawer.Footer
@@ -138,7 +178,8 @@ export function DrawerMinimal() {
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
 | `className` | `string` | — | No | Class on the `<footer>`. |
-| … | `React.HTMLAttributes<HTMLElement>` | — | No | Wraps actions; provides control size context. |
+| `children` | `React.ReactNode` | — | No | Action row; controls use **`ControlSizeProvider`** from panel **`size`**. |
+| … | `React.HTMLAttributes<HTMLElement>` | — | No | Renders `<footer>`. |
 
 ## Related
 

package/src/components/drawer/examples/cart-preview.tsx

@@ -0,0 +1,55 @@
+import { Button } from "@/components/button/Button";
+import { Drawer } from "@/components/drawer/Drawer";
+
+import styles from "./examples-scenarios.module.css";
+
+const lines = [
+  { title: "Canvas tote", meta: "Qty 1 · Navy", price: "$48.00" },
+  { title: "Studio mug", meta: "Qty 2 · Matte black", price: "$36.00" },
+] as const;
+
+/**
+ * Trailing-edge preview of the cart: scroll line items; primary checkout stays in the footer.
+ */
+export default function DrawerExampleCartPreview() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+          Cart (3)
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Portal>
+        <Drawer.Overlay />
+        <Drawer.Content side="right" size="m" aria-labelledby="drawer-cart-title">
+          <Drawer.Header>
+            <Drawer.Title id="drawer-cart-title">Your cart</Drawer.Title>
+          </Drawer.Header>
+          <Drawer.Body>
+            {lines.map((line) => (
+              <div key={line.title} className={styles.cartLine}>
+                <div className={styles.cartLineMain}>
+                  <p className={styles.cartTitle}>{line.title}</p>
+                  <p className={styles.cartPrice}>{line.price}</p>
+                </div>
+                <p className={styles.cartMeta}>{line.meta}</p>
+              </div>
+            ))}
+          </Drawer.Body>
+          <Drawer.Footer className={styles.footerActions}>
+            <Drawer.Close>
+              <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+                View cart
+              </Button.Root>
+            </Drawer.Close>
+            <Drawer.Close>
+              <Button.Root type="button" size="m" variant="primary">
+                Checkout
+              </Button.Root>
+            </Drawer.Close>
+          </Drawer.Footer>
+        </Drawer.Content>
+      </Drawer.Portal>
+    </Drawer.Root>
+  );
+}

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

@@ -0,0 +1,79 @@
+.intro {
+  margin: 0;
+  font-size: var(--prime-sys-typography-role-bodyDefault-fontSize);
+  line-height: var(--prime-sys-typography-role-bodyDefault-lineHeight);
+  color: var(--prime-sys-color-content-primary);
+}
+
+.nav {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x2);
+}
+
+.muted {
+  margin: 0;
+  color: var(--prime-sys-color-content-secondary);
+  font-size: var(--prime-sys-typography-role-bodyDefault-fontSize);
+  line-height: var(--prime-sys-typography-role-bodyDefault-lineHeight);
+}
+
+.filterStack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-l);
+}
+
+.cartLine {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x1);
+  padding-block: var(--prime-sys-spacing-m);
+  border-bottom: var(--prime-sys-unit-1px) solid var(--prime-sys-color-border-subtle);
+}
+
+.cartLine:last-child {
+  border-bottom: none;
+}
+
+.cartLineMain {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.cartTitle {
+  margin: 0;
+  font-size: var(--prime-sys-typography-role-bodyDefault-fontSize);
+  line-height: var(--prime-sys-typography-role-bodyDefault-lineHeight);
+  color: var(--prime-sys-color-content-primary);
+}
+
+.cartMeta {
+  margin: 0;
+  font-size: var(--prime-sys-typography-role-bodySmall-fontSize);
+  line-height: var(--prime-sys-typography-role-bodySmall-lineHeight);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.cartPrice {
+  margin: 0;
+  font-size: var(--prime-sys-typography-role-bodyDefault-fontSize);
+  line-height: var(--prime-sys-typography-role-bodyDefault-lineHeight);
+  color: var(--prime-sys-color-content-primary);
+  white-space: nowrap;
+}
+
+.footerActions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-m);
+  justify-content: flex-end;
+}
+
+.settingsStack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-l);
+}

package/src/components/drawer/examples/explicit-panel.tsx

@@ -0,0 +1,40 @@
+import { Button } from "@/components/button/Button";
+import { Drawer } from "@/components/drawer/Drawer";
+
+import styles from "./examples-scenarios.module.css";
+
+/**
+ * Extended composition: `Drawer.Panel` exposes the shell explicitly; inner `Drawer.Content` is only the scroll region.
+ */
+export default function DrawerExampleExplicitPanel() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+          Open explicit panel
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Portal>
+        <Drawer.Overlay />
+        <Drawer.Panel side="right" size="m" aria-labelledby="drawer-explicit-title">
+          <Drawer.Header>
+            <Drawer.Title id="drawer-explicit-title">Details</Drawer.Title>
+          </Drawer.Header>
+          <Drawer.Content>
+            <p className={styles.intro}>
+              This body uses <code>Drawer.Content</code> inside <code>Drawer.Panel</code> so only
+              this region scrolls when content overflows.
+            </p>
+          </Drawer.Content>
+          <Drawer.Footer>
+            <Drawer.Close>
+              <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+                Close
+              </Button.Root>
+            </Drawer.Close>
+          </Drawer.Footer>
+        </Drawer.Panel>
+      </Drawer.Portal>
+    </Drawer.Root>
+  );
+}

package/src/components/drawer/examples/filters-panel.tsx

@@ -0,0 +1,53 @@
+import { Button } from "@/components/button/Button";
+import { Checkbox } from "@/components/checkbox/Checkbox";
+import { Drawer } from "@/components/drawer/Drawer";
+
+import styles from "./examples-scenarios.module.css";
+
+/**
+ * Filter drawer from the leading edge; footer keeps Apply / Reset visible while criteria scroll.
+ */
+export default function DrawerExampleFiltersPanel() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+          Filters
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Portal>
+        <Drawer.Overlay />
+        <Drawer.Content side="left" size="m" aria-labelledby="drawer-filters-title">
+          <Drawer.Header>
+            <Drawer.Title id="drawer-filters-title">Filters</Drawer.Title>
+          </Drawer.Header>
+          <Drawer.Body>
+            <div className={styles.filterStack}>
+              <Checkbox.Root size="m" defaultChecked>
+                <Checkbox.Label>In stock only</Checkbox.Label>
+              </Checkbox.Root>
+              <Checkbox.Root size="m">
+                <Checkbox.Label>On sale</Checkbox.Label>
+              </Checkbox.Root>
+              <Checkbox.Root size="m">
+                <Checkbox.Label>Ships today</Checkbox.Label>
+              </Checkbox.Root>
+            </div>
+          </Drawer.Body>
+          <Drawer.Footer className={styles.footerActions}>
+            <Drawer.Close>
+              <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+                Reset
+              </Button.Root>
+            </Drawer.Close>
+            <Drawer.Close>
+              <Button.Root type="button" size="m" variant="primary">
+                Apply
+              </Button.Root>
+            </Drawer.Close>
+          </Drawer.Footer>
+        </Drawer.Content>
+      </Drawer.Portal>
+    </Drawer.Root>
+  );
+}

package/src/components/drawer/examples/mobile-nav-sheet.tsx

@@ -0,0 +1,43 @@
+import { Button } from "@/components/button/Button";
+import { Drawer } from "@/components/drawer/Drawer";
+
+import styles from "./examples-scenarios.module.css";
+
+const items = ["Home", "Catalog", "Orders", "Account"] as const;
+
+/**
+ * Bottom sheet pattern for small-viewport primary navigation. Wrap rows in `Drawer.Close` so choosing a section dismisses the sheet.
+ */
+export default function DrawerExampleMobileNavSheet() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+          Menu
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Portal>
+        <Drawer.Overlay />
+        <Drawer.Content side="bottom" size="m" aria-labelledby="drawer-nav-title">
+          <Drawer.Header>
+            <Drawer.Title id="drawer-nav-title">Navigate</Drawer.Title>
+          </Drawer.Header>
+          <Drawer.Body>
+            <nav className={styles.nav} aria-label="Primary">
+              {items.map((label) => (
+                <Drawer.Close key={label}>
+                  <Button.Root type="button" size="m" variant="neutral" mode="ghost" fullWidth>
+                    {label}
+                  </Button.Root>
+                </Drawer.Close>
+              ))}
+            </nav>
+            <p className={styles.muted}>
+              In a real app, wire each action to routing and close from `onOpenChange` if needed.
+            </p>
+          </Drawer.Body>
+        </Drawer.Content>
+      </Drawer.Portal>
+    </Drawer.Root>
+  );
+}

package/src/components/drawer/examples/settings-side.tsx

@@ -0,0 +1,54 @@
+import { Button } from "@/components/button/Button";
+import { Drawer } from "@/components/drawer/Drawer";
+import { Input } from "@/components/input/Input";
+
+import styles from "./examples-scenarios.module.css";
+
+/**
+ * Settings on the trailing edge: form fields share the drawer `size` tier with header and footer controls.
+ */
+export default function DrawerExampleSettingsSide() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+          Workspace settings
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Portal>
+        <Drawer.Overlay />
+        <Drawer.Content side="right" size="m" aria-labelledby="drawer-settings-title">
+          <Drawer.Header>
+            <Drawer.Title id="drawer-settings-title">Workspace</Drawer.Title>
+          </Drawer.Header>
+          <Drawer.Body>
+            <div className={styles.settingsStack}>
+              <Input.Root label="Workspace name" size="m">
+                <Input.Wrapper>
+                  <Input.Field defaultValue="Acme Design" />
+                </Input.Wrapper>
+              </Input.Root>
+              <Input.Root label="Default timezone" size="m" hint="Used for scheduled reports.">
+                <Input.Wrapper>
+                  <Input.Field defaultValue="Europe/Berlin" />
+                </Input.Wrapper>
+              </Input.Root>
+            </div>
+          </Drawer.Body>
+          <Drawer.Footer className={styles.footerActions}>
+            <Drawer.Close>
+              <Button.Root type="button" size="m" variant="neutral" mode="stroke">
+                Cancel
+              </Button.Root>
+            </Drawer.Close>
+            <Drawer.Close>
+              <Button.Root type="button" size="m" variant="primary">
+                Save changes
+              </Button.Root>
+            </Drawer.Close>
+          </Drawer.Footer>
+        </Drawer.Content>
+      </Drawer.Portal>
+    </Drawer.Root>
+  );
+}