cleanplate 0.3.21 → 0.3.23

package/dist/stories/table/table-arg-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table-arg-types.d.ts","sourceRoot":"","sources":["../../../src/stories/table/table-arg-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAejD,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAWtD,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,QAE/B,CAAC"}
+{"version":3,"file":"table-arg-types.d.ts","sourceRoot":"","sources":["../../../src/stories/table/table-arg-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAgBjD,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAWtD,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,QAE/B,CAAC"}

package/docs/Avatar.md

@@ -7,6 +7,7 @@ Purpose: Displays user initials, an image, or a Material icon in a consistent ci
 | Prop | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
 | name | string | no | "" | Display name; used for initials and `title` when no image/icon. Also used for image `alt`. |
+| codeText | string | no | "" | Optional code-like text override for non-image/non-icon mode. Keeps only alphanumeric chars, then renders the last 4 characters (uppercased). |
 | image | string | no | "" | Image URL; when set, shows image instead of initials or icon. |
 | icon | MaterialIconName | no | — | Material icon name; when set (and no image), shows icon instead of initials. |
 | size | "small" \| "medium" | no | "medium" | Size of the avatar. |
@@ -36,6 +37,7 @@ type AvatarMargin = string | SpacingOption[];
 ```typescript
 interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "style"> {
   name?: string;
+  codeText?: string;
   image?: string;
   icon?: MaterialIconName;  // from "../icon/material-icon-names"
   size?: AvatarSize;
@@ -60,6 +62,20 @@ export const Example = () => (
 );
 ```
 
+### Code text (up to 4 chars)
+
+```jsx
+import { Avatar } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Avatar codeText="B101" size="medium" />
+    <Avatar codeText="F2" size="small" />
+    <Avatar codeText="order-AB#12-99" size="medium" />
+  </>
+);
+```
+
 ### Icon
 
 ```jsx
@@ -143,8 +159,10 @@ export const Example = () => (
 
 ## Behavior Notes
 
-- **Display priority:** If `image` is set, the image is shown. Else if `icon` is set, the Material icon is shown. Otherwise initials from `name` are shown.
+- **Display priority:** If `image` is set, the image is shown. Else if `icon` is set, the Material icon is shown. Else if `codeText` resolves to a valid value, that text is shown. Otherwise initials from `name` are shown.
+- **Code text sanitization:** `codeText` removes special characters, keeps only `[a-zA-Z0-9]`, then renders the **last 4** characters in uppercase. Examples: `"B101"` -> `"B101"`, `"F2"` -> `"F2"`, `"AB#12-99"` -> `"1299"`.
 - **Initials:** Derived from the first letter of each word in `name` (up to 2 characters), e.g. "John Doe" → "JD".
+- **Text fitting:** Avatar text auto-scales for 3-4 characters so code labels remain readable in both sizes.
 - **Backgrounds (CSS only):** **Initials** use `var(--primary-brand)` on the root. **Icon** mode uses `var(--primary-brand)` for the circle. **Image** mode uses `var(--white)` behind the photo so transparent PNGs do not show a hole. To change colors, add a **`className`** and target the root in your stylesheet.
 - **Spacing:** `margin` accepts the **spacing suffix**; the component adds the `m-` prefix via `getSpacingClass`. Use suffix form (e.g. `"0"`, `"2"`, `"b-3"`) when passing values explicitly.
 - **Root element:** A `div`; supports `ref` and other attributes except **`style`** (omitted from the public type so layout stays class-based).

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/Header.md

@@ -136,7 +136,9 @@ Prefer **`Dropdown`** with **`Avatar`** as **`trigger`** and **`content`** that
 - **headerLeft / headerCenter / headerRight:** When provided, replace the default logo, MenuList, or right slot.
 - **AppShell:** If you pass **`header`** as **`HeaderProps`** to **`AppShell`**, configure **`headerRight`** the same way as a standalone **`Header`** (recommended account dropdown structure does not change).
 - **showCenterMenu:** When `false`, the center column is empty on desktop (unless `headerCenter` is set). `menuItems` is still used for the mobile overlay.
-- **Mobile:** Below 1024px, center nav hides; hamburger shows. Click opens slide-in menu (Animated fade-in-left).
+- **Mobile:** Below 1024px, center nav hides; hamburger shows. Click opens a Floating UI drawer with backdrop fade and left slide animation.
+- **Backdrop + close:** Clicking the backdrop closes the drawer; close button and menu item clicks also close it.
+- **Scroll lock:** While the mobile drawer is open, background page scroll is locked.
 - **onMenuItemClick:** Called with the clicked item; mobile menu closes on click.
 - **Margin:** Uses the suffix API (e.g. `"0"` → m-0).
 
@@ -146,4 +148,4 @@ Prefer **`Dropdown`** with **`Avatar`** as **`trigger`** and **`content`** that
 - Dropdown, Avatar (account menu in **headerRight**; see `docs/Dropdown.md`)
 - AppShell (passes **`header`** as Header props; same **headerRight** recommendations apply)
 - Button, Icon (mobile menu trigger and close)
-- Animated (mobile menu slide-in)
+- Floating UI overlay/dialog primitives (mobile menu drawer)

package/docs/MediaObject.md

@@ -10,6 +10,7 @@ Purpose: Combines fixed media (`Avatar`: icon, image, or initials) with a dense
 | mediaIcon | `MaterialIconName` \| string | no | "" | Material Symbol name passed to `Avatar`. |
 | mediaImage | string | no | "" | Image URL for `Avatar`. |
 | mediaAvatar | string | no | "" | Display name used for initials when image/icon are not shown. |
+| mediaAvatarCodeText | string | no | "" | Optional avatar code override. Passed to `Avatar.codeText` (alphanumeric only, last 4 chars). |
 | subtitle | `React.ReactNode` | no | — | Optional middle line (e.g. subject). Omit for two-line layouts. |
 | description | `React.ReactNode` | no | — | Optional preview/snippet line(s); muted, multi-line ellipsis via `--cp-media-object-desc-lines`. |
 | descriptionLineClamp | number | no | 2 | Max lines for `description` before truncation. |
@@ -40,6 +41,7 @@ interface MediaObjectProps extends React.HTMLAttributes<HTMLDivElement> {
   mediaIcon?: MaterialIconName | string;
   mediaImage?: string;
   mediaAvatar?: string;
+  mediaAvatarCodeText?: string;
   title: string;
   subtitle?: React.ReactNode;
   description?: React.ReactNode;
@@ -184,6 +186,7 @@ import { MediaObject, Typography } from "cleanplate";
 - **Trailing rail**: If `meta` and/or `action` is passed, the body adds a second grid column: `meta` always occupies **column 2, row 1** aligned with `title`; `action` occupies **column 2, last text row**, aligned toward the snippet row. When **only one** logical text row remains and **both** `meta` and `action` exist, both stack in one compact trailing cell (`gap` 2px).
 - **`descriptionLineClamp`** sets the CSS custom property `--cp-media-object-desc-lines` on the snippet wrapper so consumers can clamp 1–N lines preview text.
 - **Media slot**: Implemented with `Avatar` (`name={mediaAvatar}`, `image`, `icon`). Combination rules when multiple props are set match `Avatar` (see `docs/Avatar.md`); typical usage passes one dominant source (photo URL vs icon vs name for initials).
+- **Code avatars**: Use `mediaAvatarCodeText` for code-like values (e.g. `B101`, `F2`). Avatar sanitizes to alphanumeric and renders the last 4 chars.
 - **`meta` primitives**: Strings and numbers render with component meta typography (muted `--text-muted`); pass React nodes when you control color/weight entirely.
 - **`title`** is always a string rendered as emphasized primary text (`--text-default`).
 - **`subtitle`** and **`description`** accept `React.ReactNode`; empty string / falsy hides the slot.

package/docs/Table.md

@@ -74,13 +74,14 @@ interface TableMobileColumns
   extends Omit<
     MediaObjectProps,
     | "title" | "subtitle" | "description" | "meta" | "action"
-    | "mediaAvatar" | "mediaIcon" | "mediaImage" | "onClick"
+    | "mediaAvatar" | "mediaAvatarCodeText" | "mediaIcon" | "mediaImage" | "onClick"
   > {
   title: TableMobileColumnKey;              // required row key
   subtitle?: TableMobileColumnField;
   description?: TableMobileColumnField;
   meta?: TableMobileColumnField;
   mediaAvatar?: TableMobileColumnKey;
+  mediaAvatarCodeText?: TableMobileColumnField<string>; // static code, row key, or resolver
   mediaIcon?: TableMobileColumnField<string>;  // static icon, row key, or resolver
   mediaImage?: TableMobileColumnField<string>; // static URL, row key, or resolver
   action?: (row: TableRow) => React.ReactNode;
@@ -180,6 +181,7 @@ const columns = [
     description: "email",
     meta: "status",
     mediaAvatar: "name",
+    mediaAvatarCodeText: "employeeCode",
     descriptionLineClamp: 2,
     action: (row) => <Badge label={String(row.status)} variant="success" />,
   }}
@@ -200,7 +202,7 @@ const columns = [
 
 - **Required:** `columns` and `data` are required. Each column must have `id` and `title`; row keys should match `id` for default cell display.
 - **Pagination:** Built-in Pagination is shown when `totalItems` > 0 and `hidePagination` is false. Pass `onPageChange` and optionally `onRowsPerPageChange`; keep `currentPage` and `rowsPerPage` in parent state.
-- **Mobile:** When viewport width < 768px and `mobileColumns` is set, each row renders as a `MediaObject`. Map row keys to `title`, `subtitle`, `description`, `meta`, and media fields, or use resolvers / `action` for custom per-row UI. Static MediaObject props (`descriptionLineClamp`, `margin`, `padding`, etc.) pass through unchanged.
+- **Mobile:** When viewport width < 768px and `mobileColumns` is set, each row renders as a `MediaObject`. Map row keys to `title`, `subtitle`, `description`, `meta`, and media fields (`mediaAvatar`, `mediaAvatarCodeText`, `mediaIcon`, `mediaImage`), or use resolvers / `action` for custom per-row UI. Static MediaObject props (`descriptionLineClamp`, `margin`, `padding`, etc.) pass through unchanged.
 - **customRender:** Receives `(rowData, column)` and returns a React node; use for badges, buttons, or any custom cell content.
 - **Spacing:** `margin` uses the suffix API; the component adds the `m-` prefix via `getSpacingClass`.
 

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.21",
+  "version": "0.3.23",
   "description": "CleanPlate - A Headless React UI Framework",
   "files": [
     "dist",