cleanplate 0.3.22 → 0.3.24

package/docs/FeedbackState.md

@@ -0,0 +1,179 @@
+# FeedbackState Component
+
+Purpose: Unified empty and error **region** for cards, panels, tables, and main content areas — when a section has no data or failed to load. Use `Alert` for short inline banners and `Toast` for transient messages. **Margin** uses the **framework-wide spacing suffix rule** (same for all components); see `llms.txt`.
+
+**Illustrations:** CleanPlate does not host artwork. Pass your own image URL (`png`, `jpg`, `svg`) or a custom `ReactNode`, or use the `icon` prop with a Material icon name when no image is needed.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| variant | `"empty" \| "error"` | yes | — | Drives default ARIA role and error tone |
+| title | string | yes | — | Primary headline |
+| titleTag | `"h1"` … `"h6" \| "p"` | no | `"h2"` | Semantic element for the title |
+| description | string \| ReactNode | no | — | Supporting copy |
+| illustration | string \| ReactNode | no | — | Image URL or custom media node |
+| illustrationAlt | string | no | `""` | `alt` for URL images; empty = decorative |
+| icon | MaterialIconName | no | — | Material icon when `illustration` is omitted |
+| size | `"small" \| "medium" \| "large"` | no | `"medium"` | Overall scale (spacing, media box, icon size) |
+| primaryAction | ActionConfig | no | — | Solid primary button |
+| secondaryAction | ActionConfig | no | — | Ghost secondary button |
+| onRetry | `() => void` | no | — | Shorthand primary “Try again” when `primaryAction` is absent |
+| retryLabel | string | no | `"Try again"` | Label when `onRetry` is used |
+| errorCode | string \| number | no | — | Visual error code (not the sole indicator) |
+| errorDetails | string | no | — | Technical detail in a `<details>` disclosure |
+| role | `"alert" \| "status" \| "none"` | no | `status` (empty) / `alert` (error) | Root ARIA role |
+| margin | string \| SpacingOption[] | no | `"0"` | Spacing **suffix**; component adds `m-` prefix |
+| className | string | no | `""` | Extra class on root for consumer CSS overrides |
+| dataTestId | string | no | — | `data-testid` on root |
+
+### ActionConfig
+
+```typescript
+type ActionConfig = {
+  label: string;
+  onClick: () => void;
+};
+```
+
+Actions use `Button` only — there is no `href`. Use `onClick` for navigation (e.g. router).
+
+## Types
+
+### FeedbackStateVariant
+```typescript
+type FeedbackStateVariant = "empty" | "error";
+```
+
+### FeedbackStateSize
+```typescript
+type FeedbackStateSize = "small" | "medium" | "large";
+```
+
+### FeedbackStateTitleTag
+```typescript
+type FeedbackStateTitleTag = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p";
+```
+
+### FeedbackStateRole
+```typescript
+type FeedbackStateRole = "alert" | "status" | "none";
+```
+
+### FeedbackStateProps
+```typescript
+interface FeedbackStateProps {
+  variant: FeedbackStateVariant;
+  title: string;
+  titleTag?: FeedbackStateTitleTag;
+  description?: string | React.ReactNode;
+  illustration?: string | React.ReactNode;
+  illustrationAlt?: string;
+  icon?: MaterialIconName;
+  size?: FeedbackStateSize;
+  primaryAction?: ActionConfig;
+  secondaryAction?: ActionConfig;
+  onRetry?: () => void;
+  retryLabel?: string;
+  errorCode?: string | number;
+  errorDetails?: string;
+  role?: FeedbackStateRole;
+  margin?: string | SpacingOption[];
+  className?: string;
+  dataTestId?: string;
+}
+```
+
+## Usage Examples
+
+### Empty state with icon
+
+```jsx
+import { FeedbackState } from "cleanplate";
+
+export const ProjectsEmpty = ({ onCreate }) => (
+  <FeedbackState
+    variant="empty"
+    title="No projects yet"
+    description="Create your first project to get started."
+    icon="folder_open"
+    primaryAction={{ label: "New project", onClick: onCreate }}
+  />
+);
+```
+
+### Empty state with module illustration
+
+```jsx
+<FeedbackState
+  variant="empty"
+  title="No search results"
+  description="Try adjusting your filters."
+  illustration="/assets/modules/search-empty.png"
+  illustrationAlt=""
+  primaryAction={{ label: "Clear filters", onClick: clearFilters }}
+/>
+```
+
+### Error with retry
+
+```jsx
+<FeedbackState
+  variant="error"
+  title="Could not load projects"
+  description="Check your connection and try again."
+  icon="cloud_off"
+  errorCode={503}
+  onRetry={refetch}
+/>
+```
+
+### Error with technical details
+
+```jsx
+<FeedbackState
+  variant="error"
+  title="Request failed"
+  errorDetails={error.message}
+  dataTestId="projects-error"
+/>
+```
+
+### Custom styles via className
+
+```jsx
+<FeedbackState
+  variant="empty"
+  title="No items"
+  className="my-module-empty"
+  icon="inbox"
+/>
+```
+
+```css
+.my-module-empty.cp-feedback-state {
+  min-height: 280px;
+}
+```
+
+## Behavior Notes
+
+- **Media precedence:** `illustration` → `icon` → no media. If both `illustration` and `icon` are set, illustration wins.
+- **Action precedence:** `primaryAction` overrides `onRetry`.
+- **Layout:** Stacked only (media above text, centered actions).
+- **Accessibility:** Root `aria-labelledby` points at the title; decorative media uses `aria-hidden` when `illustrationAlt` is empty and a title is present.
+- **Motion:** Subtle mount fade; disabled when `prefers-reduced-motion: reduce`.
+
+### Stable slot classes (for CSS overrides)
+
+- `cp-feedback-state` — root
+- `cp-feedback-state__media`, `cp-feedback-state__media-img`
+- `cp-feedback-state__content`, `cp-feedback-state__title`, `cp-feedback-state__description`
+- `cp-feedback-state__error-code`, `cp-feedback-state__actions`, `cp-feedback-state__details`
+
+## Related Components / Links
+
+- Alert (inline feedback)
+- Toast (transient messages)
+- Button, Icon, Typography (composed internally)
+- Container (wrap for layout in stories and apps)

package/docs/FormControls.md

@@ -10,8 +10,8 @@ FormControls is a set of form primitives exported as a namespace: `FormControls.
 | TextArea | Multi-line text | placeholder, value, onChange(e) |
 | Select | Floating UI combobox: desktop portalled list; **≤768px** bottom sheet; sync or async options, search, groups, multi chips + cap | `mode` / `isMulti`, `options`, `onSearch`, `searchable`, `groups`, `maxSelect`, `triggerMaxItems`, `panelMinWidth`, `name`, `placeholder`, `error` |
 | Date | Calendar date picker (`date-fns` + Floating UI); **Cancel** / **OK** staging; desktop **popover** (~**400px** max width, viewport-capped); **≤768px** **bottom sheet** + backdrop; **month** / **year** subviews with back + titled headers; trigger **`calendar_month`** icon | `value`/`defaultValue` (`Date \| null`), `onChange`, `minDate`/`maxDate`/`disabledDates`/`disabledDaysOfWeek`, `locale`, `weekStartsOn`, `dateFormat`, `clearable`, `readOnly`, `name` (hidden **yyyy-MM-dd**), `popoverPlacement`, `onOpen`/`onClose` |
-| Checkbox | Checkbox group (array-based, multi-select) | name, label, options, value (CheckboxValue[]), defaultValue, onChange(values, e), orientation, variant |
-| Radio | Radio group (array-based) | name, label, options, value, defaultValue, onChange(value, e), orientation, variant |
+| Checkbox | Checkbox group (array-based, multi-select) | name, label, options, value (CheckboxValue[]), defaultValue, onChange(values, e), orientation, variant, cardControlAlign |
+| Radio | Radio group (array-based) | name, label, options, value, defaultValue, onChange(value, e), orientation, variant, cardControlAlign |
 | File | File picker with `button` / `card` variants, drag-and-drop, and a removable file list | name, label, variant, multiple, accept, value (File[]), onChange(files, e), buttonLabel, dropZoneText |
 | Toggle | On/off switch | checked, defaultChecked, onChange(checked: boolean) |
 | Stepper | Numeric value with integrated − / + (integer text field + `min` / `max` / `step`) | placeholder, value, onChange(e), min, max, step, layout |
@@ -163,9 +163,9 @@ interface InputProps {
 - **TextAreaProps**: label, value/defaultValue, onChange, isDisabled, isRequired, isFluid, className, error, **`dataTestId`** (on `<textarea>`; `-error` — see overview).
 - **SelectProps**: … **`dataTestId`** (wrapper root; `-trigger`, `-panel`, `-option-{value}`, … — see **Select — E2E / test selectors**).
 - **FileProps**: `name`, `label`, `variant` (`"button" | "card"`, default `"button"`), `multiple`, `accept`, `value: File[]` (controlled), `defaultValue: File[]` (uncontrolled initial visual list), `onChange(files: File[], e?)`, `buttonLabel` (default `"Browse file"`), `dropZoneText` (default `"Drag files to upload"`, card variant only), plus the common `isDisabled`, `isRequired`, `isFluid`, `className`, `error`, **`dataTestId`** (on file input; `-trigger`, `-list`, `-item-{i}`, `-remove-{i}` — see **File — E2E / test selectors**). The card variant supports drag-and-drop. **FileVariant** = `"button" | "card"`.
-- **RadioProps**: `options` (non-empty `RadioOption[]`), `name`, `label` (group `<legend>`), optional `id`, `value`, `defaultValue`, `onChange(value, e)`, `orientation` (`"vertical" | "horizontal"`), `variant` (`"default" | "card"`), `isDisabled`, `isRequired`, `isFluid`, `className`, `error`, **`dataTestId`** (root on `<fieldset>`; suffixed ids on options container, rows, inputs, and labels — see **Checkbox and Radio — E2E / test selectors**).
+- **RadioProps**: `options` (non-empty `RadioOption[]`), `name`, `label` (group `<legend>`), optional `id`, `value`, `defaultValue`, `onChange(value, e)`, `orientation` (`"vertical" | "horizontal"`), `variant` (`"default" | "card"`), `cardControlAlign` (`"start" | "end"`, default `"end"` — card variant only; top-inline-start vs top-inline-end corner), `isDisabled`, `isRequired`, `isFluid`, `className`, `error`, **`dataTestId`** (root on `<fieldset>`; suffixed ids on options container, rows, inputs, and labels — see **Checkbox and Radio — E2E / test selectors**).
 - **RadioOption**: `{ label, value, isDisabled?, description?, icon?, dataTestId?, id? }`. `description` is rendered under the option label as muted secondary text and linked via `aria-describedby`. `icon` accepts any `ReactNode` (e.g. `<Icon />`, `<img />`, custom SVG) and renders to the left of the label/description. **`dataTestId`** on an option overrides the group-derived `-input-{value}` id for that option's native `<input>`.
-- **CheckboxProps**: `options` (non-empty `CheckboxOption[]`), `name`, `label` (group `<legend>`), optional `id`, `value` (`CheckboxValue[]`), `defaultValue` (`CheckboxValue[]`), `onChange(values, e)`, `orientation` (`"vertical" | "horizontal"`), `variant` (`"default" | "card"`), `isDisabled`, `isRequired`, `isFluid`, `className`, `error`, **`dataTestId`** (root on `<fieldset>`; suffixed ids on options container, rows, inputs, and labels — see **Checkbox and Radio — E2E / test selectors**).
+- **CheckboxProps**: `options` (non-empty `CheckboxOption[]`), `name`, `label` (group `<legend>`), optional `id`, `value` (`CheckboxValue[]`), `defaultValue` (`CheckboxValue[]`), `onChange(values, e)`, `orientation` (`"vertical" | "horizontal"`), `variant` (`"default" | "card"`), `cardControlAlign` (`"start" | "end"`, default `"end"` — card variant only; top-inline-start vs top-inline-end corner), `isDisabled`, `isRequired`, `isFluid`, `className`, `error`, **`dataTestId`** (root on `<fieldset>`; suffixed ids on options container, rows, inputs, and labels — see **Checkbox and Radio — E2E / test selectors**).
 - **CheckboxOption**: `{ label, value, isDisabled?, description?, icon?, dataTestId?, id? }`. `description` is rendered under the option label as muted secondary text and linked via `aria-describedby`. `icon` accepts any `ReactNode` (e.g. `<Icon />`, `<img />`, custom SVG) and renders to the left of the label/description. **`dataTestId`** on an option overrides the group-derived `-input-{value}` id for that option's native `<input>`. `CheckboxValue = string | number`.
 - **DateProps**: `value` / `defaultValue` (`Date | null`), `onChange(date: Date | null)`, `placeholder`, **`dateFormat`** (display string via `date-fns` + `locale`, default `MMM dd, yyyy`), **`name`** (renders a hidden `<input>` that submits **`yyyy-MM-dd`** for the committed calendar date), **`minDate`** / **`maxDate`** (inclusive navigation + selection bounds), **`disabledDates`** / **`disabledDaysOfWeek`** (greyed cells), **`locale`** (`date-fns` `Locale` — grid, subview copy, and field text), **`weekStartsOn`** (`0`–`6`, default `0` = Sunday), **`clearable`** (default `true`; shows clear control when a value exists), **`readOnly`** (no picker; value fixed), **`popoverPlacement`** (Floating UI placement for desktop; default `bottom-start`), **`onOpen`** / **`onClose`**, plus shared `label`, `isDisabled`, `isRequired`, `isFluid`, `className`, `error`, **`dataTestId`** (see **Date — E2E / test selectors**).
 - **ToggleProps**: checked, defaultChecked, onChange(checked: boolean), label, isDisabled, isRequired, isFluid, className, error, **`dataTestId`** (on switch input; `-label`, `-error`).
@@ -584,8 +584,8 @@ Pagination uses `FormControls.Select` for rows-per-page. Pills uses `FormControl
 - **File (`dataTestId`):** On file input plus `-trigger`, `-list`, `-item-{i}`, `-remove-{i}`. See **File — E2E / test selectors**.
 - **Select:** Built on **Floating UI** — desktop uses a **portalled** panel with flip/shift to stay in the viewport; panel **width** matches the trigger, with optional **`panelMinWidth`** when options need more horizontal space; **`searchable={false}`** hides the panel search field (full static list, or async `onSearch("")` on open); **≤768px** uses a **bottom sheet** (`role="dialog"`, `aria-modal`, `aria-labelledby` to the field label when the label exists). **Option** shape supports `group`, `icon`, `avatar`, `meta`, `disabled`. **`mode`** (`'single' | 'multi'`) replaces **`isMulti`** (still supported, deprecated). Single mode: **`onChange(Option | null)`** — `null` when cleared. Multi mode: **`onChange(Option[])`** — use **`[]`** for clear. **`name` + hidden `<input>`:** native form submit posts the selected **`value`**(s); **multi** joins with **commas** — avoid comma characters inside `value` if you rely on `FormData`, or parse manually. **`options={null}` + `onSearch`:** async loading; show loading/empty/error states in the panel. **`groups`:** sticky headings for shared `Option.group`. **`maxSelect`:** multi only; **`triggerMaxItems`:** chip overflow **`+N`**. **`aria-controls`** on the combobox trigger and panel search point at the listbox **only while open**. **`aria-invalid`** reflects **`error`** on trigger, search field, and listbox. Validation message uses **`role="alert"`** (via shared field error pattern).
 - **Date:** **`Date | null`** with **`onChange`**. Opens a **`role="dialog"`** calendar: **staging** applies on day tap; **Cancel** reverts to the last committed value; **OK** commits (and clears staging). **Desktop:** portalled Floating UI panel with flip/shift, fixed **max width ~400px** (capped by viewport). **≤768px:** bottom sheet fixed to the lower viewport + dimmed backdrop, `aria-modal`, body scroll lock while open (same breakpoint idea as Select). **Header:** month cluster + year cluster (44px arrow hits); tapping month/year opens **scrollable subviews** with **back (`arrow_back`)** and headings **“Select a month of {yyyy}”** / **“Select a year for {MMMM}”** (locale-aware via `locale`). **Trigger:** **`calendar_month`** trailing icon (not Select chevrons); optional **clear** when `clearable`. **`readOnly`** and **`isDisabled`** block interaction. Constraints: **`minDate`/`maxDate`** (inclusive), **`disabledDates`**, **`disabledDaysOfWeek`**. **`dateFormat`** + **`locale`** control the field string; grid labels follow **`locale`** and **`weekStartsOn`**. **`name`:** hidden input posts **`yyyy-MM-dd`** for the **committed** value only. **`onOpen`/`onClose`** fire when the panel opens/closes. **`popoverPlacement`** adjusts desktop anchor (default `bottom-start`). **`error`** / **`isRequired`** use the shared field error pattern (`aria-invalid`, message under the field).
-- **Radio:** Group-first API — pass `options: RadioOption[]`. Renders `<fieldset>` + `<legend>` with a single `value` and `onChange(value, e)`. `isRequired` puts `*` on the legend and adds `required`/`aria-required` to the first enabled option (HTML5 only requires one input in the group to carry it). Custom ring/dot follows the native `:checked` state so uncontrolled groups stay visually correct. Pass `variant="card"` for tile-style options (ring in top-right, optional `icon` on the left, primary-brand border + tint when selected). **`dataTestId`** on the group maps to the fieldset and emits suffixed ids (`-options`, `-option-{value}`, `-input-{value}`, `-label-{value}`); per-option `dataTestId` overrides the input suffix only.
-- **Checkbox:** Group-first API — pass `options: CheckboxOption[]`. Renders `<fieldset>` + `<legend>` with a `value: CheckboxValue[]` and `onChange(values, e)`. `isRequired` puts `*` on the legend and sets `aria-required` on the group; native HTML5 doesn't enforce "at least one" for checkbox groups, so add custom validation at the form layer. Custom box/tick follows the native `:checked` state. Pass `variant="card"` for tile-style options (box in top-right, optional `icon` on the left, primary-brand border + tint when checked). For a single checkbox, pass a one-element `options` array — `value=[]` is unchecked, `value=[opt.value]` is checked. **`dataTestId`** uses the same suffix scheme as Radio.
+- **Radio:** Group-first API — pass `options: RadioOption[]`. Renders `<fieldset>` + `<legend>` with a single `value` and `onChange(value, e)`. `isRequired` puts `*` on the legend and adds `required`/`aria-required` to the first enabled option (HTML5 only requires one input in the group to carry it). Custom ring/dot follows the native `:checked` state so uncontrolled groups stay visually correct. Pass `variant="card"` for tile-style options; `cardControlAlign` (`start` | `end`, default `end`) places the ring in the top-inline-start or top-inline-end corner (left / right in LTR). Optional `icon` beside label/description; primary-brand border + tint when selected. **`dataTestId`** on the group maps to the fieldset and emits suffixed ids (`-options`, `-option-{value}`, `-input-{value}`, `-label-{value}`); per-option `dataTestId` overrides the input suffix only.
+- **Checkbox:** Group-first API — pass `options: CheckboxOption[]`. Renders `<fieldset>` + `<legend>` with a `value: CheckboxValue[]` and `onChange(values, e)`. `isRequired` puts `*` on the legend and sets `aria-required` on the group; native HTML5 doesn't enforce "at least one" for checkbox groups, so add custom validation at the form layer. Custom box/tick follows the native `:checked` state. Pass `variant="card"` for tile-style options; `cardControlAlign` (`start` | `end`, default `end`) places the box in the top-inline-start or top-inline-end corner (left / right in LTR). For a single checkbox, pass a one-element `options` array — `value=[]` is unchecked, `value=[opt.value]` is checked. **`dataTestId`** uses the same suffix scheme as Radio.
 - **File:** Native `<input type="file">` is visually hidden but stays in the a11y tree. Manages a `File[]` selection internally; `onChange(files, e)` fires for picker selections, drops, and removals (the underlying event is `undefined` for non-picker triggers). With `multiple`, subsequent picks/drops append; without, the new selection replaces the old. The card variant supports drag-and-drop and tints primary-brand on hover. Removing a file resets the native input so re-selecting the same file still emits a change. `defaultValue` seeds the visual list only — browsers don't allow programmatic pre-population of file inputs.
 - **isFluid:** Full-width field wrapper.
 

package/llms.txt

@@ -101,6 +101,13 @@ All component documentation is located in the `docs/` folder. The following docu
 - Types: AlertProps, AlertSize, AlertVariant, AlertMargin, SpacingOption
 - Related Components: Typography, Container, Button, Icon (used internally)
 
+### FeedbackState Component
+- File: `docs/FeedbackState.md`
+- Purpose: Unified empty and error region for cards, panels, tables, and content areas. Consumer-supplied illustration URL (png/jpg/svg) or Material `icon`; optional primary/secondary actions (`onClick` only).
+- Key Features: variant empty|error, sizes small|medium|large, stacked layout, errorCode/errorDetails, onRetry shorthand, className overrides, dataTestId, margin suffix API
+- Types: FeedbackStateProps, FeedbackStateVariant, FeedbackStateSize, FeedbackStateTitleTag, FeedbackStateRole, ActionConfig, FeedbackStateMargin, SpacingOption
+- Related Components: Typography, Button, Icon (used internally); Alert (inline); Toast (transient)
+
 ### Spinner Component
 - File: `docs/Spinner.md`
 - Purpose: Loading indicator that shows a rotating Material icon. Use for progress or activity states.
@@ -259,6 +266,7 @@ All documentation files follow a consistent format:
 | Container | `docs/Container.md` | Layout, spacing, and flex structure |
 | Dropdown | `docs/Dropdown.md` | Menus and floating panels |
 | Alert | `docs/Alert.md` | Inline feedback and notices |
+| FeedbackState | `docs/FeedbackState.md` | Empty/error content regions |
 | Spinner | `docs/Spinner.md` | Loading and activity indicator |
 | Stepper | `docs/Stepper.md` | Wizard / checkout **step progress** (not numeric +/−; that is **FormControls.Stepper** in FormControls) |
 | BreadCrumb | `docs/BreadCrumb.md` | Navigation trail and page hierarchy |
@@ -296,5 +304,5 @@ npm install cleanplate
 ## Usage
 
 ```jsx
-import { Button, Typography, Icon, MediaObject, Avatar, Container, Dropdown, Alert, 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, 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.22",
+  "version": "0.3.24",
   "description": "CleanPlate - A Headless React UI Framework",
   "files": [
     "dist",