cleanplate 0.3.22 → 0.3.23

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/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.23",
   "description": "CleanPlate - A Headless React UI Framework",
   "files": [
     "dist",