cleanplate 0.3.3 → 0.3.5

package/dist/utils/common.d.ts

@@ -1,5 +1,4 @@
 export function getInitials(name?: string): string;
-export function getAvatarBgColor(name?: string): string;
 export function getSpacingClass(marginConfig: any, styleObject: any, prefix: any): any;
 export function getUniqueId(): string;
 export function getVariantIcon(variant: any): string;

package/dist/utils/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/utils/common.js"],"names":[],"mappings":"AAEO,mDAIN;AAEM,wDASN;AAEM,uFAcN;AAEM,sCAON;AAEM,qDAgBN;AAEM,oDAEN;AAEM,mGAcN"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/utils/common.js"],"names":[],"mappings":"AAEO,mDAIN;AAEM,uFAcN;AAEM,sCAON;AAEM,qDAgBN;AAEM,oDAEN;AAEM,mGAcN"}

package/docs/AppShell.md

@@ -1,6 +1,6 @@
 # AppShell Component
 
-Purpose: Full-page layout that combines an optional Header (top), optional Footer (bottom), and an optional MenuList as a left sidebar, with main content in the center. Use for dashboard-style apps where the sidebar holds primary navigation and the header holds logo and utilities (e.g. user menu). Sidebar is hidden below 1024px; pass the same menu items to the header for the header’s mobile menu.
+Purpose: Full-page layout that combines an optional Header (top), optional Footer (bottom), and an optional MenuList as a left sidebar, with main content in the center. Use for dashboard-style apps where the sidebar holds primary navigation and the header holds logo and utilities (e.g. user menu). Sidebar is hidden below 1024px; pass the same menu items to the header for the header’s mobile menu. To avoid duplicating nav in the header center on desktop, set **`showCenterMenu: false`** on Header props (see `docs/Header.md`).
 
 ## Props / Inputs
 
@@ -69,8 +69,9 @@ const Dashboard = () => {
         variant: "light",
       }}
       header={{
-        logoUrl="/logo.svg",
+        logoUrl: "/logo.svg",
         menuItems: MENU_ITEMS,
+        showCenterMenu: false,
         activeMenuItem: active,
         onMenuItemClick: onMenuClick,
         headerRight: <Avatar name="User" />,
@@ -108,7 +109,7 @@ const Dashboard = () => {
 ```jsx
 <AppShell
   header={{
-    logoUrl="/logo.svg",
+    logoUrl: "/logo.svg",
     menuItems,
     activeMenuItem: active,
     onMenuItemClick: (item) => setActive(item.value),
@@ -137,12 +138,12 @@ const Dashboard = () => {
 - **Layout:** Root is a flex column with `min-height: 100vh`. Header and footer slots are full width; body is a flex row (sidebar + main). Main area is scrollable.
 - **Header / footer:** When `header` or `footer` is a plain object with Header/Footer props (e.g. `menuItems` for header), the component renders `<Header {...header} />` or `<Footer {...footer} />`. Otherwise it renders the ReactNode as-is.
 - **Sidebar:** Rendered in an `<aside aria-label="Main navigation">` with MenuList `direction="vertical"`. Width from `sidebarWidth` (inline style).
-- **Responsive:** At viewport width ≤ 1024px the sidebar column is hidden via CSS. When `header` is `HeaderProps`, the default is to rely on the header’s mobile menu for the same items. When there is no header (or `mobileSidebarDrawer` is `true`), AppShell renders a **Floating UI** mobile drawer: fixed menu trigger, `FloatingPortal` + `FloatingOverlay` (scroll lock) + `FloatingFocusManager` (modal focus), dismiss on overlay press and Escape, and the same `MenuList` as the sidebar.
+- **Responsive:** At viewport width ≤ 1024px the sidebar column is hidden via CSS. When `header` is `HeaderProps`, the default is to rely on the header’s mobile menu for the same items. When there is no header (or `mobileSidebarDrawer` is `true`), AppShell renders a **Floating UI** mobile drawer: fixed menu trigger, `FloatingPortal` + `FloatingOverlay` (scroll lock) + `FloatingFocusManager` (modal focus), dismiss on overlay press and Escape, and the same `MenuList` as the sidebar. On desktop, use Header’s **`showCenterMenu: false`** when the sidebar already shows the same items so the header center stays empty (or use **`headerCenter`** for a title or other content).
 - **No root spacing props:** AppShell does not expose margin/padding; use `className` or `contentClassName` for layout.
 
 ## Related Components / Links
 
-- Header (rendered in header slot when header is Header props; use same menu items for mobile)
+- Header (Header props or custom node; with sidebar + `HeaderProps`, pass **`showCenterMenu: false`** to hide duplicate center nav on desktop while keeping `menuItems` for the mobile menu)
 - Footer (rendered in footer slot when footer is Footer props)
 - MenuList (used in sidebar with direction="vertical")
 - Container (wrap page content inside children)

package/docs/Avatar.md

@@ -6,14 +6,14 @@ 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` and for generating background color when showing initials. |
+| name | string | no | "" | Display name; used for initials and `title` when no image/icon. Also used for image `alt`. |
 | 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. |
 | margin | string \| string[] | no | "m-0" | Spacing **suffix** for outer margin. The component adds the `m-` prefix (e.g. `"0"` → m-0, `"b-2"` → m-b-2). Use a single string or array: `"0"`, `["2", "b-3"]`. |
 | onClick | function | no | — | Click handler for the root div. |
-| className | string | no | "" | Additional class names for the root element. |
-| ...rest | React.HTMLAttributes<HTMLDivElement> | no | — | Any other div attributes (e.g. `id`, `data-*`, `aria-*`, `style`) are forwarded. |
+| className | string | no | "" | Additional class names for the root element; use to override backgrounds or other visuals (no inline `style` on Avatar). |
+| ...rest | `Omit<HTMLAttributes<HTMLDivElement>, "style">` | no | — | Other div attributes (`id`, `data-*`, `aria-*`, `ref`, etc.). The **`style`** prop is not supported; use **`className`** and CSS instead. |
 
 ## Types
 
@@ -34,7 +34,7 @@ type AvatarMargin = string | SpacingOption[];
 
 ### AvatarProps
 ```typescript
-interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
+interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "style"> {
   name?: string;
   image?: string;
   icon?: MaterialIconName;  // from "../icon/material-icon-names"
@@ -87,6 +87,14 @@ export const Example = () => (
 );
 ```
 
+### Custom appearance (`className`)
+
+Backgrounds come from CSS modules (`--primary-brand` for initials/icon, `--white` behind images). Override with your own class:
+
+```jsx
+<Avatar name="VIP" className="my-avatar--gold" />
+```
+
 ### Clickable avatar
 
 ```jsx
@@ -119,9 +127,9 @@ export const Example = () => (
 
 - **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.
 - **Initials:** Derived from the first letter of each word in `name` (up to 2 characters), e.g. "John Doe" → "JD".
-- **Background color:** When showing initials, background color is generated deterministically from `name` (hash-based).
+- **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`; all standard HTML div attributes and ref are supported via `...rest`.
+- **Root element:** A `div`; supports `ref` and other attributes except **`style`** (omitted from the public type so layout stays class-based).
 
 ## Related Components / Links
 

package/docs/Header.md

@@ -13,6 +13,7 @@ Purpose: Responsive navigation header with logo, menu items, and customizable le
 | headerLeft | ReactNode | no | — | Custom content for the left area (replaces logo when provided). |
 | headerRight | ReactNode | no | — | Custom content for the right area. |
 | headerCenter | ReactNode | no | — | Custom content for the center area (replaces MenuList when provided). |
+| showCenterMenu | boolean | no | true | When true, shows `menuItems` in the center on wide viewports. Set false when primary nav is only in a sidebar; `menuItems` is still used for the mobile menu. |
 | menuItems | MenuListItem[] | yes | — | Menu items for center nav and mobile menu; each has label, value, optional icon. |
 | size | "small" \| "medium" \| "large" | no | — | Size of the header. |
 | variant | "light" \| "dark" | no | — | Visual variant. |
@@ -45,6 +46,7 @@ interface HeaderProps {
   headerLeft?: React.ReactNode;
   headerRight?: React.ReactNode;
   headerCenter?: React.ReactNode;
+  showCenterMenu?: boolean;
   menuItems: MenuListItem[];
   size?: HeaderSize;
   variant?: HeaderVariant;
@@ -79,6 +81,21 @@ const AppHeader = () => {
 };
 ```
 
+### With AppShell (desktop nav in sidebar only)
+
+Use `showCenterMenu: false` so `menuItems` is only used for the header’s mobile menu while the sidebar shows the same links on desktop.
+
+```jsx
+<Header
+  logoUrl="/logo.svg"
+  menuItems={MENU_ITEMS}
+  showCenterMenu={false}
+  activeMenuItem={active}
+  onMenuItemClick={onMenuClick}
+  headerRight={<Avatar name="User" />}
+/>
+```
+
 ### With custom slots
 
 ```jsx
@@ -103,6 +120,7 @@ const AppHeader = () => {
 
 - **menuItems:** Required; each item has label, value, optional icon (Material icon name).
 - **headerLeft / headerCenter / headerRight:** When provided, replace the default logo, MenuList, or right slot.
+- **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).
 - **onMenuItemClick:** Called with the clicked item; mobile menu closes on click.
 - **Margin:** Uses the suffix API (e.g. `"0"` → m-0).

package/docs/MediaObject.md

@@ -9,7 +9,7 @@ Purpose: Combines fixed media (`Avatar`: icon, image, or initials) with a dense
 | title | string | yes | — | Primary line (e.g. name, sender). Rendered emphasized. |
 | 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 and avatar color generation (when image/icon not shown). |
+| mediaAvatar | string | no | "" | Display name used for initials when image/icon are not shown. |
 | 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. |

package/docs/MenuList.md

@@ -104,6 +104,7 @@ const Nav = () => {
 - **DOM:** A `div` wrapping a `ul` of `li` elements; each `li` contains an anchor.
 - **Animated:** Each item is wrapped in Animated with `fade-in-left` and staggered delay.
 - **Margin:** Uses the suffix API (e.g. `"0"` → m-0, `"b-2"` → m-b-2).
+- **Responsive (root):** At viewport width **≤1024px**, the root `.wrapper` gets extra padding, full viewport min-height, and constrained max-width so the list reads well in the header mobile sheet and similar narrow layouts (including AppShell’s mobile drawer).
 
 ## Related Components / Links
 

package/llms.txt

@@ -74,7 +74,7 @@ All component documentation is located in the `docs/` folder. The following docu
 ### Avatar Component
 - File: `docs/Avatar.md`
 - Purpose: Displays user initials, an image, or a Material icon in a consistent circle. Use for user identity in headers, lists, MediaObject, or anywhere you need a compact avatar.
-- Key Features: Display modes (initials, image, icon), sizes (small, medium), margin spacing (suffix API: e.g. "0" → m-0), optional onClick
+- Key Features: Display modes (initials, image, icon), sizes (small, medium), margin spacing (suffix API: e.g. "0" → m-0), optional onClick; backgrounds from CSS (className overrides), no inline style prop
 - Types: AvatarProps, AvatarSize, AvatarMargin, SpacingOption; icon prop uses MaterialIconName from Icon
 - Related Components: Used by MediaObject; often used with Container, Icon
 
@@ -194,14 +194,14 @@ All component documentation is located in the `docs/` folder. The following docu
 ### MenuList Component
 - File: `docs/MenuList.md`
 - Purpose: Renders a list of navigational items with optional icons, active state highlighting, and customizable layout.
-- Key Features: items (label, value, icon), activeItem, direction (horizontal, vertical), sizes (small, medium, large), variants (light, dark), margin (suffix API), onMenuClick(item), Animated entrance
+- Key Features: items (label, value, icon), activeItem, direction (horizontal, vertical), sizes (small, medium, large), variants (light, dark), margin (suffix API), onMenuClick(item), Animated entrance, responsive root layout at ≤1024px (padding, min-height) for mobile nav contexts
 - Types: MenuListProps, MenuListItem, MenuListSize, MenuListVariant, MenuListDirection, MenuListMargin
 - Related Components: Dropdown (content), Header (navigation), Container, Typography, Icon, Animated (used internally)
 
 ### Header Component
 - File: `docs/Header.md`
 - Purpose: Responsive navigation header with logo, menu items, and customizable left/center/right slots.
-- Key Features: logoUrl, menuItems, activeMenuItem, onMenuItemClick, headerLeft, headerCenter, headerRight, sizes (small, medium, large), variants (light, dark), margin (suffix API), responsive mobile menu
+- Key Features: logoUrl, menuItems, activeMenuItem, onMenuItemClick, headerLeft, headerCenter, headerRight, showCenterMenu, sizes (small, medium, large), variants (light, dark), margin (suffix API), responsive mobile menu
 - Types: HeaderProps, HeaderSize, HeaderVariant, HeaderMargin
 - Related Components: MenuList (center and mobile menu), Avatar (headerRight), Button, Icon, Animated (used internally)
 
@@ -229,7 +229,7 @@ All component documentation is located in the `docs/` folder. The following docu
 ### AppShell Component
 - File: `docs/AppShell.md`
 - Purpose: Full-page layout combining optional Header (top), Footer (bottom), and MenuList as left sidebar with main content. For dashboard-style apps.
-- Key Features: header (Header props or ReactNode), footer (Footer props or ReactNode), sidebar (AppShellSidebarConfig: items, activeItem, onMenuClick, size, variant), sidebarWidth, mobileSidebarDrawer / mobileSidebarDrawerLabel, responsive (sidebar column hidden ≤1024px; default Floating UI drawer when no HeaderProps header, else header mobile menu)
+- Key Features: header (Header props or ReactNode), footer (Footer props or ReactNode), sidebar (AppShellSidebarConfig: items, activeItem, onMenuClick, size, variant), sidebarWidth, mobileSidebarDrawer / mobileSidebarDrawerLabel, responsive (sidebar column hidden ≤1024px; default Floating UI drawer when no HeaderProps header, else header mobile menu); with Header + sidebar use Header `showCenterMenu: false` to avoid duplicate desktop nav
 - Types: AppShellProps, AppShellSidebarConfig
 - Related Components: Header, Footer, MenuList (sidebar), Container, Typography, Avatar
 

package/package.json

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