cleanplate 0.3.29 → 0.3.30

package/docs/Drawer.md

@@ -1,6 +1,6 @@
 # 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 actions).
+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
 
@@ -27,7 +27,20 @@ Purpose: A slide-in overlay panel for navigation, filters, settings, or detail v
 | 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. |
-| dataTestId | string | no | — | Root `data-testid` on the dialog panel; suffixed ids on overlay, header, title, close, body, footer, and action buttons (see **E2E / test selectors**). |
+| 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
 
@@ -75,6 +88,8 @@ interface DrawerProps {
   onPrimaryButtonClick?: () => void;
   secondaryButtonLabel?: string;
   onSecondaryButtonClick?: () => void;
+  tertiaryButtonLabel?: string;
+  onTertiaryButtonClick?: () => void;
   dataTestId?: string;
 }
 ```
@@ -92,8 +107,9 @@ Pass `dataTestId="filters-drawer"` to get stable Playwright / Testing Library ho
 | `-close` | Header close (X) button |
 | `-body` | Main content area |
 | `-footer` | Footer action row |
-| `-primary` | Primary footer button |
-| `-secondary` | Secondary footer button |
+| `-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.
 
@@ -144,15 +160,19 @@ const App = () => {
 
 ### 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"
-  primaryButtonLabel="Apply"
-  onPrimaryButtonClick={handleApply}
+  tertiaryButtonLabel="Learn more"
+  onTertiaryButtonClick={handleLearnMore}
   secondaryButtonLabel="Reset"
   onSecondaryButtonClick={handleReset}
+  primaryButtonLabel="Apply"
+  onPrimaryButtonClick={handleApply}
 >
   <Typography variant="p">Choose filter criteria.</Typography>
 </Drawer>
@@ -167,7 +187,10 @@ const App = () => {
   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"
 >
   ...
@@ -180,10 +203,12 @@ const App = () => {
 - **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
 

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

@@ -153,8 +153,8 @@ All component documentation is located in the `docs/` folder. The following docu
 
 ### 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 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, dataTestId with suffixed E2E hooks, ariaLabel
+- 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)
 
@@ -196,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

package/package.json

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