cleanplate 0.3.20 → 0.3.22

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

@@ -16,6 +16,26 @@ FormControls is a set of form primitives exported as a namespace: `FormControls.
 | 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 |
 
+## E2E / test selectors (overview)
+
+Pass **`dataTestId="my-field"`** on any control below. Patterns are consistent across the library so package consumers can write the same Playwright habits everywhere.
+
+| Control | Root id on | Primary interaction id | Common suffixes |
+| --- | --- | --- | --- |
+| **Input** | native `<input>` | same as root (`.fill()`) | `-clear`, `-prefix`, `-suffix`, `-error` |
+| **TextArea** | native `<textarea>` | same as root | `-error` |
+| **Select** | field wrapper | `-trigger` (open), `-option-{value}` (pick) | `-panel`, `-search`, `-search-clear`, `-listbox`, `-clear`, `-input`, `-error` |
+| **Date** | field wrapper | `-trigger`, `-day-YYYY-MM-DD` | `-panel`, `-grid`, `-done`, `-cancel`, `-clear`, `-input`, … |
+| **Checkbox** | `<fieldset>` | `-label-{value}` or `-input-{value}` | `-options`, `-option-{value}` |
+| **Radio** | `<fieldset>` | `-label-{value}` or `-input-{value}` | same as Checkbox |
+| **File** | hidden `<input type="file">` | same as root (`setInputFiles`) | `-trigger`, `-list`, `-item-{i}`, `-remove-{i}` |
+| **Toggle** | native switch `<input>` | `-label` (click) or root (`.check()`) | `-error` |
+| **Stepper** | numeric `<input>` | same as root | `-increment`, `-decrement`, `-error` |
+
+`{value}` keys sanitize option values: non-alphanumeric characters become `-` (e.g. `premium_plus` → `premium-plus`).
+
+Detail sections below expand each control. Component source files also document suffixes in **`dataTestId` JSDoc**.
+
 ## Types
 
 ### Option (and SelectOption)
@@ -112,6 +132,7 @@ interface InputProps {
   isFluid?: boolean;
   className?: string;
   error?: string;
+  /** On the native `<input>`; suffixed `-clear`, `-prefix`, `-suffix`, `-error` — see **Input — E2E / test selectors**. */
   dataTestId?: string;
   /** Native `autocomplete` attribute. */
   autoComplete?: string;
@@ -139,15 +160,16 @@ interface InputProps {
 ```
 
 ### Other control types
-- **TextAreaProps**: label, value/defaultValue, onChange, isDisabled, isRequired, isFluid, className, error, dataTestId.
-- **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`. The card variant supports drag-and-drop. **FileVariant** = `"button" | "card"`.
+- **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**).
 - **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>`.
-- **ToggleProps**: checked, defaultChecked, onChange(checked: boolean), label, isDisabled, isRequired, isFluid, className, error, dataTestId.
 - **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**).
 - **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`.
-- **FormControlsStepperProps**: label, placeholder, value/defaultValue, onChange(e), min, max, step, layout (`"default" | "split-controls" | "trailing-stacked-chevrons"`), isDisabled, isRequired, isFluid, className, error, dataTestId.
+- **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`).
+- **FormControlsStepperProps**: label, placeholder, value/defaultValue, onChange(e), min, max, step, layout (`"default" | "split-controls" | "trailing-stacked-chevrons"`), isDisabled, isRequired, isFluid, className, error, **`dataTestId`** (on input; `-increment`, `-decrement`, `-error`).
 
 ## Usage Examples
 
@@ -200,6 +222,82 @@ const [tags, setTags] = useState([{ label: "A", value: "a" }]);
 
 **Mobile:** At **viewport width ≤768px**, the panel opens as a **bottom sheet** (fixed to the lower viewport) with dialog semantics when a **label** is present, instead of a floating anchored list.
 
+### Input — E2E / test selectors
+
+Unlike grouped controls (Checkbox, Radio), **`dataTestId` is placed on the native `<input>`** so Playwright can target it directly for `.fill()` / `.type()` without an extra `-input` suffix.
+
+Pass **`dataTestId="email"`**:
+
+| Target | `data-testid` |
+| --- | --- |
+| Native `<input>` | `email` |
+| Search clear button | `email-clear` (only when `type="search"` and the field has a value) |
+| Prefix affix | `email-prefix` (when `prefix` is set) |
+| Suffix affix | `email-suffix` (when `suffix` is set) |
+| Error message | `email-error` (when `error` is set) |
+
+Affixes are ignored for `type="search"` (search uses icon + clear instead).
+
+#### Playwright examples
+
+```ts
+// Default / text / number / password
+await page.getByTestId("email").fill("user@example.com");
+
+// Search + clear
+await page.getByTestId("search-input").fill("query");
+await page.getByTestId("search-input-clear").click();
+
+// Amount with affixes
+await page.getByTestId("amount-input").fill("42");
+await expect(page.getByTestId("amount-input-error")).toHaveText("Required");
+```
+
+### TextArea, Toggle, and Stepper — E2E / test selectors
+
+**TextArea:** `dataTestId` on the `<textarea>`; `-error` when `error` is set.
+
+```ts
+await page.getByTestId("message-textarea").fill("Hello");
+```
+
+**Toggle:** `dataTestId` on the switch input; prefer `-label` for clicks.
+
+```ts
+await page.getByTestId("notifications-toggle-label").click();
+await expect(page.getByTestId("notifications-toggle")).toBeChecked();
+```
+
+**Stepper:** `dataTestId` on the numeric input; `-increment` / `-decrement` on step buttons.
+
+```ts
+await page.getByTestId("qty-stepper-increment").click();
+await expect(page.getByTestId("qty-stepper")).toHaveValue("2");
+```
+
+### Select — E2E / test selectors
+
+Pass **`dataTestId="fruit-select"`** on the field. The **root** id is on the field wrapper; open and pick via suffixed ids:
+
+| Suffix | Element |
+| --- | --- |
+| *(root)* | Field wrapper |
+| `-trigger` | Combobox (open panel) |
+| `-clear` | Clear selection (when `clearable`) |
+| `-panel` | Floating panel / mobile sheet |
+| `-search` | Panel search input (`searchable`) |
+| `-search-clear` | Clear panel search |
+| `-listbox` | Options list |
+| `-option-{value}` | Option row |
+| `-input` | Hidden `name` field (form submit) |
+| `-error` | Validation message |
+
+```ts
+await page.getByTestId("fruit-select-trigger").click();
+await page.getByTestId("fruit-select-option-mango").click();
+await expect(page.getByTestId("fruit-select-input")).toHaveValue("mango");
+```
+
 ### Input with prefix / suffix
 
 ```jsx
@@ -249,6 +347,27 @@ import { de } from "date-fns/locale/de";
 />
 ```
 
+### Date — E2E / test selectors
+
+Pass **`dataTestId="dob"`** on the field:
+
+| Suffix | Element |
+| --- | --- |
+| *(root)* | Field wrapper |
+| `-trigger` | Open picker |
+| `-clear` | Clear committed value (`clearable`) |
+| `-panel` | Calendar dialog |
+| `-grid` | Day grid |
+| `-day-YYYY-MM-DD` | Day button |
+| `-cancel` / `-done` | Footer actions |
+| `-input` | Hidden `name` field (`yyyy-MM-dd`) |
+
+```ts
+await page.getByTestId("dob-trigger").click();
+await page.getByTestId("dob-day-2026-05-18").click();
+await page.getByTestId("dob-done").click();
+```
+
 ### Checkbox group
 
 Pass an `options` array. The component renders the entire group inside a `<fieldset>` + `<legend>` and emits `onChange(values, event)` with the next array of selected values. The required `*` is rendered on the group label, not on individual options.
@@ -397,6 +516,24 @@ await expect(page.getByTestId("shipping-input-std")).not.toBeChecked();
 await page.getByTestId("shipping-input-std").check();
 ```
 
+### File — E2E / test selectors
+
+Pass **`dataTestId="upload"`**. The **root** id is on the hidden file input (use `setInputFiles`); related UI uses suffixes:
+
+| Suffix | Element |
+| --- | --- |
+| *(root)* | Hidden `<input type="file">` |
+| `-trigger` | Browse / drop-zone label |
+| `-list` | Selected files list |
+| `-item-{i}` | File row |
+| `-remove-{i}` | Remove button |
+
+```ts
+await page.getByTestId("upload").setInputFiles("fixtures/doc.pdf");
+await expect(page.getByTestId("upload-item-0")).toContainText("doc.pdf");
+await page.getByTestId("upload-remove-0").click();
+```
+
 ### File (button variant)
 
 Compact trigger that looks like a primary button. Selected files render below the trigger as small cards with a type-specific thumbnail icon, name, size, and a remove button.
@@ -440,6 +577,11 @@ Pagination uses `FormControls.Select` for rows-per-page. Pills uses `FormControl
 - **Input (`prefix` / `suffix`):** Inline leading/trailing text affix for currency (`$`), country code (`+91`), unit (`kg`, `%`), TLD (`.com`), etc. Soft-capped at 4 characters so the layout stays predictable; longer strings are truncated. When set, the field's outer wrapper takes over the visible border / padding / focus ring so the affixes read as part of the same input. Affixes are linked to the input via `aria-describedby`, so screen readers announce e.g. "Amount, dollars, $500" when the visible affix is `$`. For symbols/abbreviations that don't read well, pass `prefixA11yLabel` / `suffixA11yLabel` (e.g. `prefix="$"`, `prefixA11yLabel="dollars"`). Ignored when `type="search"` (search already uses both edges) — for any other `type`, including `number`, affixes work as expected.
 - **Input (validation / constraints):** `maxLength` is passed straight to the native attribute (works for any `type`). `min` / `max` are passed to the native attribute (HTML5 form-validation hints) and, for `type="number"` only, also clamped on `blur` — the user can finish typing freely and the value snaps to the bound when they leave the field.
 - **Input (`autoComplete` / `onBlur`):** `autoComplete` maps to the native attribute (`"email"`, `"current-password"`, `"off"`, …). `onBlur` runs after any internal numeric clamp so consumers see the final value.
+- **Input (`dataTestId`):** Applied on the native `<input>` for direct E2E fill/type. Optional suffixed ids: `-clear` (search), `-prefix`, `-suffix` (affix layout), `-error` (validation message). See **Input — E2E / test selectors**.
+- **TextArea / Toggle / Stepper (`dataTestId`):** On the native control; see **TextArea, Toggle, and Stepper — E2E / test selectors**.
+- **Select (`dataTestId`):** Wrapper root plus `-trigger`, `-panel`, `-option-{value}`, etc. See **Select — E2E / test selectors**.
+- **Date (`dataTestId`):** Wrapper root plus calendar suffixes. See **Date — E2E / test selectors**.
+- **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.

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/package.json

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