cleanplate 0.3.28 → 0.3.30

package/dist/utils/use-media-query.d.ts

@@ -0,0 +1,2 @@
+export declare function useMediaQuery(matchesQuery: string): boolean;
+//# sourceMappingURL=use-media-query.d.ts.map

package/dist/utils/use-media-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-media-query.d.ts","sourceRoot":"","sources":["../../src/utils/use-media-query.ts"],"names":[],"mappings":"AAEA,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CA4B3D"}

package/docs/Drawer.md

@@ -0,0 +1,219 @@
+# Drawer Component
+
+Purpose: A slide-in overlay panel for navigation, filters, settings, or detail views. On desktop (≥768px), slides from a configurable edge (`left`, `right`, `top`, or `bottom`). Below 768px, always renders as a bottom sheet (max height 90dvh). Includes fade/slide transitions, focus management, and Modal-like optional chrome (title, close button, footer primary / secondary / tertiary actions).
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| children | React.ReactNode | yes | — | Drawer body content. |
+| isOpen | boolean | no | false | Whether the drawer is visible. |
+| onClose | () => void | no | — | Called when the drawer should close (close button, overlay, or Escape). |
+| placement | "left" \| "right" \| "top" \| "bottom" | no | "right" | Edge the drawer slides from on desktop; ignored on mobile (always bottom sheet). |
+| size | "small" \| "medium" \| "large" \| "full" | no | "medium" | Panel size preset (width for side drawers, height for top/bottom). |
+| title | string | no | "" | Title displayed in the drawer header. |
+| showCloseButton | boolean | no | true | Whether to show the X close button in the header. |
+| closeOnOverlayClick | boolean | no | true | Whether clicking the overlay closes the drawer. |
+| closeOnEscape | boolean | no | true | Whether pressing Escape closes the drawer. |
+| margin | string \| SpacingOption[] | no | "0" | Margin spacing (suffix or array of suffixes; component adds `m-` prefix). |
+| className | string | no | "" | Additional class names for the drawer panel. |
+| overlayClassName | string | no | "" | Additional class names for the overlay. |
+| contentClassName | string | no | "" | Additional class names for the content wrapper. |
+| headerClassName | string | no | "" | Additional class names for the header row. |
+| bodyClassName | string | no | "" | Additional class names for the body region. |
+| footerClassName | string | no | "" | Additional class names for the footer row. |
+| ariaLabel | string | no | — | Accessible name when no `title` is provided. Required for a11y when `title` is omitted. |
+| primaryButtonLabel | string | no | "" | Label for the primary footer button; empty hides it. |
+| onPrimaryButtonClick | () => void | no | — | Called when the primary footer button is clicked. |
+| secondaryButtonLabel | string | no | "" | Label for the secondary footer button; empty hides it. |
+| onSecondaryButtonClick | () => void | no | — | Called when the secondary footer button is clicked. |
+| tertiaryButtonLabel | string | no | "" | Label for the tertiary footer button (ghost variant); empty hides it. |
+| onTertiaryButtonClick | () => void | no | — | Called when the tertiary footer button is clicked. |
+| dataTestId | string | no | — | Root `data-testid` on the dialog panel; suffixed ids: `-overlay`, `-header`, `-title`, `-close`, `-body`, `-footer`, `-primary`, `-secondary`, `-tertiary` (see **E2E / test selectors**). |
+
+## Size presets
+
+| Size | Side drawer width (`left` / `right`) | Top / bottom drawer height |
+| --- | --- | --- |
+| `small` | `min(280px, 100vw − 56px)` | `30dvh` |
+| `medium` | `min(360px, 100vw − 56px)` | `50dvh` |
+| `large` | `min(480px, 100vw − 56px)` | `70dvh` |
+| `full` | `100vw` | `100dvh` |
+
+On mobile (≤768px), `size` height/width presets are overridden by the bottom sheet shell (`max-height: 90dvh`, full width).
+
+## Types
+
+### SpacingOption
+```typescript
+type SpacingOption = (typeof SPACING_OPTIONS)[number];
+```
+
+### DrawerPlacement
+```typescript
+type DrawerPlacement = "left" | "right" | "top" | "bottom";
+```
+
+### DrawerSize
+```typescript
+type DrawerSize = "small" | "medium" | "large" | "full";
+```
+
+### DrawerMargin
+```typescript
+type DrawerMargin = string | SpacingOption[];
+```
+
+### DrawerProps
+```typescript
+interface DrawerProps {
+  children: React.ReactNode;
+  isOpen?: boolean;
+  onClose?: () => void;
+  placement?: DrawerPlacement;
+  size?: DrawerSize;
+  title?: string;
+  showCloseButton?: boolean;
+  closeOnOverlayClick?: boolean;
+  closeOnEscape?: boolean;
+  margin?: DrawerMargin;
+  className?: string;
+  overlayClassName?: string;
+  contentClassName?: string;
+  headerClassName?: string;
+  bodyClassName?: string;
+  footerClassName?: string;
+  ariaLabel?: string;
+  primaryButtonLabel?: string;
+  onPrimaryButtonClick?: () => void;
+  secondaryButtonLabel?: string;
+  onSecondaryButtonClick?: () => void;
+  tertiaryButtonLabel?: string;
+  onTertiaryButtonClick?: () => void;
+  dataTestId?: string;
+}
+```
+
+## E2E / test selectors
+
+Pass `dataTestId="filters-drawer"` to get stable Playwright / Testing Library hooks:
+
+| Suffix | Element |
+| --- | --- |
+| *(root)* | Dialog panel (`role="dialog"`) |
+| `-overlay` | Backdrop overlay |
+| `-header` | Header row (title + close button) |
+| `-title` | Title text |
+| `-close` | Header close (X) button |
+| `-body` | Main content area |
+| `-footer` | Footer action row |
+| `-primary` | Primary footer button (solid) |
+| `-secondary` | Secondary footer button (outline) |
+| `-tertiary` | Tertiary footer button (ghost) |
+
+Header, title, close, footer, and button suffixes are omitted when those regions are not rendered.
+
+### Playwright example
+
+```ts
+await page.getByRole("button", { name: "Open filters" }).click();
+await expect(page.getByTestId("filters-drawer")).toBeVisible();
+await page.getByTestId("filters-drawer-body").getByLabel("Category").selectOption("books");
+await page.getByTestId("filters-drawer-primary").click();
+await expect(page.getByTestId("filters-drawer")).toBeHidden();
+```
+
+## Usage Examples
+
+### Basic
+
+```jsx
+import { Drawer, Button, Typography } from "cleanplate";
+import { useState } from "react";
+
+const App = () => {
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Open Drawer</Button>
+      <Drawer
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        title="Filters"
+        placement="right"
+      >
+        <Typography variant="p">Filter options go here.</Typography>
+      </Drawer>
+    </>
+  );
+};
+```
+
+### Placements (desktop)
+
+```jsx
+<Drawer placement="left" title="Navigation" isOpen={isOpen} onClose={onClose}>...</Drawer>
+<Drawer placement="right" title="Details" isOpen={isOpen} onClose={onClose}>...</Drawer>
+<Drawer placement="top" title="Announcements" isOpen={isOpen} onClose={onClose}>...</Drawer>
+<Drawer placement="bottom" title="Actions" isOpen={isOpen} onClose={onClose}>...</Drawer>
+```
+
+### With footer buttons
+
+Footer actions render in a row: **tertiary** (ghost, left), **secondary** (outline), **primary** (solid, right). Omit any label to hide that button.
+
+```jsx
+<Drawer
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="Apply Filters"
+  tertiaryButtonLabel="Learn more"
+  onTertiaryButtonClick={handleLearnMore}
+  secondaryButtonLabel="Reset"
+  onSecondaryButtonClick={handleReset}
+  primaryButtonLabel="Apply"
+  onPrimaryButtonClick={handleApply}
+>
+  <Typography variant="p">Choose filter criteria.</Typography>
+</Drawer>
+```
+
+### Custom class names
+
+```jsx
+<Drawer
+  isOpen={isOpen}
+  onClose={onClose}
+  title="Settings"
+  className="my-drawer-panel"
+  overlayClassName="my-drawer-overlay"
+  contentClassName="my-drawer-content"
+  headerClassName="my-drawer-header"
+  bodyClassName="my-drawer-body"
+  footerClassName="my-drawer-footer"
+  dataTestId="settings-drawer"
+>
+  ...
+</Drawer>
+```
+
+## Behavior Notes
+
+- **Desktop (≥768px):** Panel slides from the configured `placement` edge with subtle opacity fade. Side drawers use full viewport height; top/bottom drawers use full viewport width.
+- **Mobile (<768px):** Always renders as a bottom sheet regardless of `placement`. Max height is **90dvh** with rounded top corners and safe-area padding at the bottom.
+- **Rendering:** Mounts when `isOpen` is true and stays mounted briefly after close so the exit transition can finish.
+- **Close:** `onClose` is called when the user clicks the X button (if `showCloseButton`), the overlay (if `closeOnOverlayClick`), or Escape (if `closeOnEscape`). Footer buttons do not auto-close; call `onClose` in their handlers if desired.
+- **Footer buttons:** `primaryButtonLabel` (solid), `secondaryButtonLabel` (outline), and `tertiaryButtonLabel` (ghost). Tertiary aligns to the start of the footer row; secondary and primary align to the end.
+- **Body scroll:** Locked while open and restored on close.
+- **Focus:** Trapped while open; returned to the previously focused element on close.
+- **ARIA:** `role="dialog"`, `aria-modal="true"`, `aria-labelledby` when `title` is present, or `aria-label` via `ariaLabel`. Provide **`title` or `ariaLabel`** — a dev warning is logged when the drawer opens without either.
+- **Spacing:** `margin` uses the suffix API (e.g. `"0"`, `"b-2"`); component adds `m-` prefix.
+- **Reduced motion:** Respects `prefers-reduced-motion: reduce` (transitions minimized in CSS).
+
+## Related Components / Links
+
+- Modal (centered overlay dialog)
+- BottomSheet (drag gestures and snap points from bottom only)
+- ConfirmDialog (simple confirmation overlay)
+- Button (open trigger and footer actions)
+- Typography (title and body content)

package/docs/FormControls.md

@@ -83,8 +83,10 @@ interface SelectProps {
   searchable?: boolean;
   /** Panel search field placeholder. @default "Search" */
   searchPlaceholder?: string;
-  /** When search text matches nothing, optional “add” callback receives trimmed string. */
+  /** Persistent footer “add” action; callback receives trimmed search text or `""`. */
   onAddOption?: (value: string) => void;
+  /** Footer button label. @default "Add option" */
+  addOptionLabel?: string;
   /** @default true */
   closeOnAddOption?: boolean;
   placeholder?: string;
@@ -289,6 +291,7 @@ Pass **`dataTestId="fruit-select"`** on the field. The **root** id is on the fie
 | `-search-clear` | Clear panel search |
 | `-listbox` | Options list |
 | `-option-{value}` | Option row |
+| `-add-option` | Footer add action (`onAddOption`) |
 | `-input` | Hidden `name` field (form submit) |
 | `-error` | Validation message |
 

package/llms.txt

@@ -151,6 +151,13 @@ All component documentation is located in the `docs/` folder. The following docu
 - Types: ModalProps, ModalSize, ModalMargin, SpacingOption
 - Related Components: ConfirmDialog (simpler confirm-only), Button, Typography, Icon (used internally)
 
+### Drawer Component
+- File: `docs/Drawer.md`
+- Purpose: Slide-in overlay panel from a configurable edge (left, right, top, bottom) on desktop; below 768px always renders as a bottom sheet (max 90dvh). Optional title, close button, footer primary/secondary/tertiary actions; fade/slide transitions, focus trap, scroll lock.
+- Key Features: placement (left, right, top, bottom), size (small, medium, large, full), showCloseButton, closeOnOverlayClick, closeOnEscape, margin (suffix API), className/overlayClassName/contentClassName/headerClassName/bodyClassName/footerClassName, footer buttons (primary solid, secondary outline, tertiary ghost), dataTestId with suffixed E2E hooks (`-primary`, `-secondary`, `-tertiary`), ariaLabel (dev warning when title and ariaLabel both omitted), mobile safe-area padding
+- Types: DrawerProps, DrawerPlacement, DrawerSize, DrawerMargin, SpacingOption
+- Related Components: Modal (centered dialog), BottomSheet (drag/snap from bottom), Button, Typography, Icon (used internally)
+
 ### Pagination Component
 - File: `docs/Pagination.md`
 - Purpose: Navigate large content sets by pages. Shows total count, prev/next and page-number buttons with ellipsis, and optional rows-per-page select. Controlled via currentPage and rowsPerPage.
@@ -189,7 +196,7 @@ All component documentation is located in the `docs/` folder. The following docu
 ### FormControls
 - File: `docs/FormControls.md`
 - Purpose: Set of form primitives: Input, TextArea, Select, Date, Checkbox, Radio, File, Toggle, **FormControls.Stepper** (numeric +/− only; wizard step UI is the separate **`Stepper`** export — `docs/Stepper.md`). Access via `FormControls.Input`, `FormControls.Select`, etc.
-- Key Features: Input (supports text/search/number + prefix/suffix; number maps to numeric text input, strips non-digits on change, optional `phoneDigits` trims autofill to last N digits for phone fields, clamps via `min`/`max` on blur; search adds icon + clear button), TextArea, **Select** (Floating UI: portalled combobox on desktop with flip/shift positioning; **viewport ≤768px** uses a **bottom sheet** shell with `role="dialog"` / `aria-modal` when a label exists; **sync** `options` with in-panel **search filter**, or **async** via `options={null}` + `onSearch` (debounced); **groups** (`Option.group` sticky headers); **multi** chips with `triggerMaxItems` **+N** overflow, **Select all / Clear all**, **`maxSelect`** cap; optional **`onAddOption`**; combobox + listbox ARIA, **`aria-invalid`** on error, **`aria-controls`** on trigger/search only while open; `name` + hidden input for forms — multi posts comma-joined **`value`s**), **Date** (calendar **`Date | null`** + **Cancel/OK** staging; `date-fns` **Locale** + **`dateFormat`**; **Floating UI** desktop popover **~max 400px** wide (viewport-capped) with **`popoverPlacement`**; **≤768px** **bottom sheet** + backdrop/body lock like Select; **month/year subviews** with back + **“Select a month of {yyyy}”** / **“Select a year for {MMMM}”** titles; trigger **`calendar_month`** icon + optional clear; **`minDate`/`maxDate`/`disabledDates`/`disabledDaysOfWeek`**, **`weekStartsOn`**, **`readOnly`**, **`clearable`**, **`name`** → hidden **`yyyy-MM-dd`**, **`onOpen`/`onClose`**), Checkbox (group-first: options[], CheckboxValue[] for multi-select, onChange(values, e); each option supports `description` and `icon`; `variant="card"` for tile-style options), Radio (group-first: options[], single value, onChange(value, e); each option supports `description` and `icon`; `variant="card"` for tile-style options), File (`variant="button" | "card"`; card variant has dashed drop zone with drag-and-drop; `value: File[]` + `onChange(files, e)`; renders a removable file list with type-aware thumbnail, name, and size), Toggle (switch semantics via checkbox + role="switch"), **FormControls.Stepper** (numeric integer only: inner field is `type="text"` + `inputMode="numeric"` with − / +; `min`, `max`, `step`; **`layout`**: `"default"` | `"split-controls"` | `"trailing-stacked-chevrons"`; no **`type`** prop — use **Input** for other field kinds; − / + clicks do not move focus into the field, avoiding unwanted mobile keyboard); common props label, isRequired, isFluid, error
+- Key Features: Input (supports text/search/number + prefix/suffix; number maps to numeric text input, strips non-digits on change, optional `phoneDigits` trims autofill to last N digits for phone fields, clamps via `min`/`max` on blur; search adds icon + clear button), TextArea, **Select** (Floating UI: portalled combobox on desktop with flip/shift positioning; **viewport ≤768px** uses a **bottom sheet** shell with `role="dialog"` / `aria-modal` when a label exists; **sync** `options` with in-panel **search filter**, or **async** via `options={null}` + `onSearch` (debounced); **groups** (`Option.group` sticky headers); **multi** chips with `triggerMaxItems` **+N** overflow, **Select all / Clear all**, **`maxSelect`** cap; optional **`onAddOption`** + **`addOptionLabel`** (persistent footer below scrollable list); combobox + listbox ARIA, **`aria-invalid`** on error, **`aria-controls`** on trigger/search only while open; `name` + hidden input for forms — multi posts comma-joined **`value`s**), **Date** (calendar **`Date | null`** + **Cancel/OK** staging; `date-fns` **Locale** + **`dateFormat`**; **Floating UI** desktop popover **~max 400px** wide (viewport-capped) with **`popoverPlacement`**; **≤768px** **bottom sheet** + backdrop/body lock like Select; **month/year subviews** with back + **“Select a month of {yyyy}”** / **“Select a year for {MMMM}”** titles; trigger **`calendar_month`** icon + optional clear; **`minDate`/`maxDate`/`disabledDates`/`disabledDaysOfWeek`**, **`weekStartsOn`**, **`readOnly`**, **`clearable`**, **`name`** → hidden **`yyyy-MM-dd`**, **`onOpen`/`onClose`**), Checkbox (group-first: options[], CheckboxValue[] for multi-select, onChange(values, e); each option supports `description` and `icon`; `variant="card"` for tile-style options), Radio (group-first: options[], single value, onChange(value, e); each option supports `description` and `icon`; `variant="card"` for tile-style options), File (`variant="button" | "card"`; card variant has dashed drop zone with drag-and-drop; `value: File[]` + `onChange(files, e)`; renders a removable file list with type-aware thumbnail, name, and size), Toggle (switch semantics via checkbox + role="switch"), **FormControls.Stepper** (numeric integer only: inner field is `type="text"` + `inputMode="numeric"` with − / +; `min`, `max`, `step`; **`layout`**: `"default"` | `"split-controls"` | `"trailing-stacked-chevrons"`; no **`type`** prop — use **Input** for other field kinds; − / + clicks do not move focus into the field, avoiding unwanted mobile keyboard); common props label, isRequired, isFluid, error
 - Types: InputProps, **Option** (preferred), **SelectOption** (deprecated alias of Option), **SelectValue**, SelectProps, TextAreaProps, CheckboxProps, CheckboxOption, CheckboxValue, FileProps, FileVariant, RadioProps, RadioOption, RadioValue, ToggleProps, DateProps, FormControlsStepperProps, **FormControlsStepperLayout**
 - Theming: Public CSS custom property `--cp-form-control-radius` (default `var(--radius-large)` = 12px) controls corner radius for Input, TextArea, **FormControls.Stepper** shell, Select trigger + open dropdown corners, Date trigger + calendar panel shell, File (outline trigger, drop zone, in-card CTA span, file list rows), and Radio/Checkbox `variant="card"` tiles. Override on `:root` (or any wrapper / inline `style`) after importing `cleanplate/dist/index.css` to retheme just form fields. Prefer this over overriding the underlying `--radius-large` design token, which affects every "large radius" surface in the framework.
 - Related Components: Pills (Input), Pagination (Select), Container, Button
@@ -273,6 +280,7 @@ All documentation files follow a consistent format:
 | Accordion | `docs/Accordion.md` | Collapsible panels and FAQ sections |
 | ConfirmDialog | `docs/ConfirmDialog.md` | Confirmation modals and destructive actions |
 | Modal | `docs/Modal.md` | Forms, long content, and custom dialogs |
+| Drawer | `docs/Drawer.md` | Edge slide-in panel; bottom sheet on mobile |
 | Pagination | `docs/Pagination.md` | Page navigation for tables and lists |
 | Table | `docs/Table.md` | Structured tabular data with optional pagination and mobile view |
 | Badge | `docs/Badge.md` | Status labels, tags, and counts with colored variants |
@@ -304,5 +312,5 @@ npm install cleanplate
 ## Usage
 
 ```jsx
-import { Button, Typography, Icon, MediaObject, Avatar, Container, Dropdown, Alert, FeedbackState, Spinner, Stepper, BreadCrumb, Accordion, ConfirmDialog, Modal, Pagination, Table, Badge, Pills, Animated, FormControls, Toast, MenuList, Header, PageHeader, BottomSheet, Footer, AppShell } from "cleanplate";
+import { Button, Typography, Icon, MediaObject, Avatar, Container, Dropdown, Alert, FeedbackState, Spinner, Stepper, BreadCrumb, Accordion, ConfirmDialog, Modal, Drawer, Pagination, Table, Badge, Pills, Animated, FormControls, Toast, MenuList, Header, PageHeader, BottomSheet, Footer, AppShell } from "cleanplate";
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cleanplate",
-  "version": "0.3.28",
+  "version": "0.3.30",
   "description": "CleanPlate - A Headless React UI Framework",
   "files": [
     "dist",