cleanplate 0.3.5 → 0.3.7

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. To avoid duplicating nav in the header center on desktop, set **`showCenterMenu: false`** on Header props (see `docs/Header.md`).
+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 account **Dropdown** with **Avatar** trigger). 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`). For **`headerRight`** user menus, follow the same **user meta + vertical MenuList** content structure as **`docs/Dropdown.md`** (*Recommended: account / user menu content*)—whether you render **`<Header />`** yourself or pass **`header={{ ... }}`** here.
 
 ## Props / Inputs
 
@@ -50,13 +50,54 @@ interface AppShellProps {
 
 ```jsx
 import { useState } from "react";
-import { AppShell, Container, Typography, Avatar } from "cleanplate";
+import { AppShell, Container, Typography, Avatar, Dropdown, MenuList } from "cleanplate";
 
 const MENU_ITEMS = [
   { label: "Dashboard", value: "/", icon: "speed" },
   { label: "Settings", value: "/settings", icon: "settings" },
 ];
 
+const ACCOUNT_MENU_ITEMS = [
+  { label: "Profile", value: "/profile", icon: "account_circle" },
+  { label: "Sign out", value: "/logout", icon: "logout" },
+];
+
+/** Same structure as `docs/Dropdown.md` — Recommended: account / user menu content */
+function AccountMenuContent({ onClose }) {
+  const handleMenuClick = () => {
+    onClose?.();
+  };
+  return (
+    <>
+      <div
+        style={{
+          padding: "var(--space-2) var(--space-4) var(--space-3) var(--space-4)",
+          marginBottom: "var(--space-2)",
+          borderBottom: "1px solid var(--gray-100)",
+        }}
+      >
+        <Typography variant="small" margin="0" style={{ color: "var(--text-muted)" }}>
+          Signed in as
+        </Typography>
+        <Typography variant="p" margin="t-2" isBold style={{ color: "var(--text-default)" }}>
+          Jordan Lee
+        </Typography>
+        <Typography variant="small" margin="t-2" wordBreak="wrap" style={{ color: "var(--text-subtle)" }}>
+          jordan@example.com
+        </Typography>
+      </div>
+      <MenuList
+        items={ACCOUNT_MENU_ITEMS}
+        direction="vertical"
+        variant="light"
+        size="small"
+        margin="0"
+        onMenuClick={handleMenuClick}
+      />
+    </>
+  );
+}
+
 const Dashboard = () => {
   const [active, setActive] = useState("/");
   const onMenuClick = (item) => setActive(item.value);
@@ -74,7 +115,16 @@ const Dashboard = () => {
         showCenterMenu: false,
         activeMenuItem: active,
         onMenuItemClick: onMenuClick,
-        headerRight: <Avatar name="User" />,
+        headerRight: (
+          <Dropdown
+            placement="bottom-end"
+            offset={8}
+            trigger={
+              <Avatar name="Jordan Lee" size="medium" margin="0" tabIndex={0} />
+            }
+            content={<AccountMenuContent />}
+          />
+        ),
       }}
       footer={{ brandName: "Acme Inc" }}
       sidebarWidth="260px"
@@ -106,6 +156,8 @@ const Dashboard = () => {
 
 ### Header and footer only (no sidebar)
 
+Use the same **`headerRight`** account menu pattern as in the full dashboard example (`Dropdown` + **`Avatar`** + **`AccountMenuContent`** from **`docs/Dropdown.md`**).
+
 ```jsx
 <AppShell
   header={{
@@ -113,7 +165,14 @@ const Dashboard = () => {
     menuItems,
     activeMenuItem: active,
     onMenuItemClick: (item) => setActive(item.value),
-    headerRight: <Avatar name="User" />,
+    headerRight: (
+      <Dropdown
+        placement="bottom-end"
+        offset={8}
+        trigger={<Avatar name="Jordan Lee" size="medium" margin="0" tabIndex={0} />}
+        content={<AccountMenuContent />}
+      />
+    ),
   }}
   footer={{ brandName: "My App" }}
 >
@@ -136,7 +195,7 @@ const Dashboard = () => {
 ## Behavior Notes
 
 - **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.
+- **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. **`header.headerRight`** should follow the same patterns as a standalone **`Header`** (see **`docs/Header.md`** and **`docs/Dropdown.md`** for the recommended account **`Dropdown`** content layout).
 - **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. 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.
@@ -144,6 +203,7 @@ const Dashboard = () => {
 ## Related Components / Links
 
 - 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)
+- Dropdown (see **`docs/Dropdown.md`** — recommended account menu **`content`** for **`headerRight`** with **`HeaderProps`**)
 - 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

@@ -10,10 +10,10 @@ Purpose: Displays user initials, an image, or a Material icon in a consistent ci
 | 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"]`. |
+| margin | string \| string[] | no | "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; 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. |
+| ...rest | `Omit<HTMLAttributes<HTMLDivElement>, "style">` | no | — | Other div attributes (`id`, `data-*`, `aria-*`, etc.). The **`style`** prop is not supported; use **`className`** and CSS instead. Use the **`ref`** from `React.forwardRef` for imperative access or parent-managed refs (e.g. **Dropdown** `trigger`). |
 
 ## Types
 
@@ -109,6 +109,24 @@ export const Example = () => (
 );
 ```
 
+### As Dropdown trigger (e.g. header user menu)
+
+[`Dropdown`](./Dropdown.md) clones the `trigger` element and injects **`ref`**, **`onClick`** (toggle), **`role="button"`**, **`aria-expanded`**, **`aria-haspopup`**, and a merged **`className`**. **`Avatar`** uses **`forwardRef`**, so pass it as the trigger and set identity props as usual. For account menus in **`Header`** or **`AppShell`** (`HeaderProps.headerRight`), use the **user meta + vertical `MenuList`** pattern in **`docs/Dropdown.md`** (*Recommended: account / user menu content*), not a bare `MenuList` only.
+
+```jsx
+import { Dropdown, Avatar, MenuList } from "cleanplate";
+
+<Dropdown
+  placement="bottom-end"
+  trigger={
+    <Avatar name="Jane Doe" image="/avatar.jpg" size="medium" margin="0" tabIndex={0} />
+  }
+  content={<AccountMenuContent />}
+/>
+```
+
+You do **not** pass `onClick` yourself when using `trigger`—Dropdown supplies it. Optional: add **`tabIndex={0}`** on Avatar (via spread / rest) if you need the trigger in tab order like a native button.
+
 ### With Container
 
 ```jsx

package/docs/Dropdown.md

@@ -160,6 +160,82 @@ export const Example = () => (
 />
 ```
 
+### Recommended: account / user menu content (Header & AppShell)
+
+When **`headerRight`** is a user menu, use **`Dropdown`** with an **`Avatar`** trigger (`placement="bottom-end"` and `offset={8}` are typical) and **`content`** built in **two parts**:
+
+1. **User meta** — Optional caption (“Signed in as”), **display name**, **email**. Use **`Typography`** with clear hierarchy: `variant="small"` + `var(--text-muted)` for the caption; `variant="p"` + `isBold` + `var(--text-default)` for the name; `variant="small"` + `wordBreak="wrap"` + `var(--text-subtle)` for the email. Space lines with the **`margin`** suffix API (e.g. `"0"`, `"t-2"`).
+2. **Actions** — A vertical **`MenuList`** (`direction="vertical"`, `size="small"`). In `onMenuClick`, run your handler then call **`onClose?.()`** so the panel closes (Dropdown injects **`onClose`** into `content` when cloning).
+
+**Whitespace:** Vertical **`MenuList`** items use **`padding: 8px 16px`** on each link (`--space-2` × `--space-4`). Wrap the meta block in a container using the same horizontal inset and similar vertical rhythm so copy lines up with menu rows:
+
+```jsx
+const accountMetaStyle = {
+  padding: "var(--space-2) var(--space-4) var(--space-3) var(--space-4)",
+  marginBottom: "var(--space-2)",
+  borderBottom: "1px solid var(--gray-100)",
+};
+```
+
+Use the same structure whether **`Header`** is used standalone or passed as **`header`** on **`AppShell`** (`HeaderProps`); only data and handlers change.
+
+```jsx
+import { Dropdown, Avatar, MenuList, Typography } from "cleanplate";
+
+const ACCOUNT_MENU_ITEMS = [
+  { label: "Profile", value: "/profile", icon: "account_circle" },
+  { label: "Settings", value: "/settings", icon: "settings" },
+  { label: "Sign out", value: "/logout", icon: "logout" },
+];
+
+function AccountMenuContent({ onClose, onItemSelect }) {
+  const handleMenuClick = (item) => {
+    onItemSelect?.(item);
+    onClose?.();
+  };
+  return (
+    <>
+      <div
+        style={{
+          padding: "var(--space-2) var(--space-4) var(--space-3) var(--space-4)",
+          marginBottom: "var(--space-2)",
+          borderBottom: "1px solid var(--gray-100)",
+        }}
+      >
+        <Typography variant="small" margin="0" style={{ color: "var(--text-muted)" }}>
+          Signed in as
+        </Typography>
+        <Typography variant="p" margin="t-2" isBold style={{ color: "var(--text-default)" }}>
+          Jordan Lee
+        </Typography>
+        <Typography variant="small" margin="t-2" wordBreak="wrap" style={{ color: "var(--text-subtle)" }}>
+          jordan@example.com
+        </Typography>
+      </div>
+      <MenuList
+        items={ACCOUNT_MENU_ITEMS}
+        direction="vertical"
+        variant="light"
+        size="small"
+        margin="0"
+        onMenuClick={handleMenuClick}
+      />
+    </>
+  );
+}
+
+<Dropdown
+  placement="bottom-end"
+  offset={8}
+  trigger={
+    <Avatar name="Jordan Lee" image="/avatar.jpg" size="medium" margin="0" tabIndex={0} />
+  }
+  content={<AccountMenuContent />}
+/>
+```
+
+Live reference: **molecules/Header/Playground** in Storybook uses this pattern for **`headerRight`**.
+
 ## Behavior Notes
 
 - **Trigger modes:** Exactly one of `trigger`, `renderTrigger`, or `triggerLabel` must be used; the component throws if none are provided.
@@ -171,5 +247,7 @@ export const Example = () => (
 ## Related Components / Links
 
 - Button (commonly used as trigger or inside renderTrigger)
+- Avatar (common trigger for account menus; see **Recommended: account / user menu content** above)
 - MenuList (often used inside dropdown content for menu items)
+- Header, AppShell (pass the same `headerRight` / account menu structure for standalone header or shell layout)
 - Icon (used in the default trigger when `triggerLabel` is set for arrow icons)

package/docs/Header.md

@@ -83,19 +83,33 @@ 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.
+Use `showCenterMenu: false` so `menuItems` is only used for the header’s mobile menu while the sidebar shows the same links on desktop. For **`headerRight`**, use the same **Dropdown + Avatar + user meta + vertical MenuList** pattern as in **`docs/Dropdown.md`** (*Recommended: account / user menu content*)—whether **`Header`** is rendered by you or by **`AppShell`** via **`header={{ ... }}`**.
 
 ```jsx
+import { Dropdown, Avatar } from "cleanplate";
+// AccountMenuContent: full structure in docs/Dropdown.md
+
 <Header
   logoUrl="/logo.svg"
   menuItems={MENU_ITEMS}
   showCenterMenu={false}
   activeMenuItem={active}
   onMenuItemClick={onMenuClick}
-  headerRight={<Avatar name="User" />}
+  headerRight={
+    <Dropdown
+      placement="bottom-end"
+      offset={8}
+      trigger={<Avatar name="Jordan Lee" size="medium" margin="0" tabIndex={0} />}
+      content={<AccountMenuContent />}
+    />
+  }
 />
 ```
 
+### User account menu (`headerRight`)
+
+Prefer **`Dropdown`** with **`Avatar`** as **`trigger`** and **`content`** that separates **identity** (caption, name, email with **`Typography`** + meta padding aligned to vertical **`MenuList`** rows) from **actions** (vertical **`MenuList`** calling **`onClose`** after each action). See **`docs/Dropdown.md`** — *Recommended: account / user menu content* — and Storybook **molecules/Header/Playground**.
+
 ### With custom slots
 
 ```jsx
@@ -120,6 +134,7 @@ Use `showCenterMenu: false` so `menuItems` is only used for the header’s mobil
 
 - **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.
+- **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).
 - **onMenuItemClick:** Called with the clicked item; mobile menu closes on click.
@@ -128,6 +143,7 @@ Use `showCenterMenu: false` so `menuItems` is only used for the header’s mobil
 ## Related Components / Links
 
 - MenuList (used in center and mobile menu)
-- Avatar (commonly in headerRight)
+- 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)

package/llms.txt

@@ -87,9 +87,9 @@ All component documentation is located in the `docs/` folder. The following docu
 ### Dropdown Component
 - File: `docs/Dropdown.md`
 - Purpose: Floating panel that shows content relative to a trigger. Use for menus, option lists, or any content that opens on click.
-- Key Features: 12 placements, flip/shift to stay in viewport, three trigger modes (trigger element, renderTrigger, triggerLabel), close on outside click or Escape
+- Key Features: 12 placements, flip/shift to stay in viewport, three trigger modes (trigger element, renderTrigger, triggerLabel), close on outside click or Escape; **recommended account menu content** (user meta Typography + padding aligned to vertical MenuList + divider + MenuList; same for Header and AppShell `headerRight`)
 - Types: DropdownProps, DropdownPlacement, DropdownTriggerProps, DropdownRenderTriggerParams
-- Related Components: Button (trigger), MenuList (content)
+- Related Components: Button (trigger), Avatar (account trigger), MenuList (content), Header, AppShell
 
 ### Alert Component
 - File: `docs/Alert.md`
@@ -194,16 +194,16 @@ 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, responsive root layout at ≤1024px (padding, min-height) for mobile nav contexts
+- Key Features: items (label, value, icon), activeItem, direction (horizontal, vertical), sizes (small, medium, large), variants (light, dark), margin (suffix API), onMenuClick(item), Animated entrance
 - 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, showCenterMenu, 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; **headerRight** account menus: Dropdown + Avatar + user meta + vertical MenuList (see `docs/Dropdown.md`)
 - Types: HeaderProps, HeaderSize, HeaderVariant, HeaderMargin
-- Related Components: MenuList (center and mobile menu), Avatar (headerRight), Button, Icon, Animated (used internally)
+- Related Components: MenuList (center and mobile menu), Dropdown, Avatar (headerRight), AppShell, Button, Icon, Animated (used internally)
 
 ### PageHeader Component
 - File: `docs/PageHeader.md`
@@ -229,9 +229,9 @@ 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); with Header + sidebar use Header `showCenterMenu: false` to avoid duplicate desktop nav
+- 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; **headerRight** uses same account Dropdown pattern as standalone Header (`docs/Dropdown.md`)
 - Types: AppShellProps, AppShellSidebarConfig
-- Related Components: Header, Footer, MenuList (sidebar), Container, Typography, Avatar
+- Related Components: Header, Footer, MenuList (sidebar), Dropdown, Container, Typography, Avatar
 
 ## Documentation Format
 

package/package.json

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