@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/navigation/ProfileMenu.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-ProfileMenu is a user account dropdown component that displays the current user's profile information and provides quick access to account-related actions. It combines an avatar trigger button with a dropdown menu containing the user's name, an optional badge (chip), caption text (such as email), and customizable menu items.
-
-ProfileMenu is typically placed in the application header or top navigation bar. It supports both controlled and uncontrolled open state, avatar image or auto-generated initials, multiple size variants, and flexible menu item configuration.
+ProfileMenu is a user account dropdown component that displays the current user's profile information and provides quick access to account-related actions. It combines an avatar button with a dropdown menu containing the user's name, optional badge (chip), caption (like email), and customizable menu items. ProfileMenu is typically placed in the header or navigation area of an application.
 
 ```tsx
 <ProfileMenu
@@ -54,11 +52,11 @@ function Header() {
 }
 ```
 
-## Profile Variations
+## Examples
 
 ### Default
 
-ProfileMenu with full profile information including name, chip badge, and caption.
+ProfileMenu with full profile information including name, chip, and caption.
 
 ```tsx
 <ProfileMenu
@@ -83,7 +81,7 @@ ProfileMenu with full profile information including name, chip badge, and captio
 
 ### Without Caption
 
-Profile showing only the name and chip badge, without a secondary caption line.
+Profile showing only the name and chip badge.
 
 ```tsx
 <ProfileMenu
@@ -107,7 +105,7 @@ Profile showing only the name and chip badge, without a secondary caption line.
 
 ### Without Chip
 
-Profile showing the name and caption, without a badge chip.
+Profile showing name and caption without a badge.
 
 ```tsx
 <ProfileMenu
@@ -131,7 +129,7 @@ Profile showing the name and caption, without a badge chip.
 
 ### Only Name
 
-Minimal profile display with just the user's name. Useful for compact layouts where additional context is not needed.
+Minimal profile with just the user's name.
 
 ```tsx
 <ProfileMenu
@@ -154,7 +152,7 @@ Minimal profile display with just the user's name. Useful for compact layouts wh
 
 ### Without Menu Items
 
-Profile card without any action menu items. The dropdown displays only the user information.
+Profile card without any menu actions.
 
 ```tsx
 <ProfileMenu
@@ -168,9 +166,9 @@ Profile card without any action menu items. The dropdown displays only the user
 />
 ```
 
-## Sizes
+### Sizes
 
-ProfileMenu supports `md` (default) and `sm` size variants for use in different layout densities.
+ProfileMenu supports different sizes for various layouts.
 
 ```tsx
 <Stack direction="row" gap="150px">
@@ -205,11 +203,9 @@ ProfileMenu supports `md` (default) and `sm` size variants for use in different
 </Stack>
 ```
 
-## Avatar
-
 ### With Profile Image
 
-When a user has a profile picture, pass the `image` property with `src` and `alt`. The image replaces the auto-generated initials.
+Display a custom avatar image instead of generated initials.
 
 ```tsx
 <ProfileMenu
@@ -237,7 +233,7 @@ When a user has a profile picture, pass the `image` property with `src` and `alt
 
 ### With Korean Name
 
-ProfileMenu automatically generates initials from various name formats, including Korean names.
+ProfileMenu automatically generates initials from various name formats.
 
 ```tsx
 <>
@@ -254,11 +250,9 @@ ProfileMenu automatically generates initials from various name formats, includin
 </>
 ```
 
-## Controlled vs Uncontrolled
-
 ### Controlled
 
-Use the `open` and `onOpenChange` props to control the menu's open state programmatically.
+Programmatically control the menu's open state.
 
 ```tsx
 <ProfileMenu {...args} open={open} onOpenChange={setOpen} />
@@ -266,7 +260,7 @@ Use the `open` and `onOpenChange` props to control the menu's open state program
 
 ### Uncontrolled
 
-Use `defaultOpen` to set the initial state, then let the component manage its own open/close behavior internally.
+Let the component manage its own open state internally.
 
 ```tsx
 <ProfileMenu
@@ -289,6 +283,24 @@ Use `defaultOpen` to set the initial state, then let the component manage its ow
 />
 ```
 
+## When to Use
+
+### ✅ Good Use Cases
+
+- **Application header**: Display current user and account actions
+- **Admin dashboards**: Quick access to user settings and logout
+- **Multi-user applications**: Show which account is active
+- **Settings access**: Provide shortcuts to profile and preferences
+- **Authentication flows**: Display logged-in user with sign-out option
+
+### ❌ When Not to Use
+
+- **Anonymous users**: Don't show ProfileMenu for non-authenticated users
+- **Simple navigation**: Use regular dropdown for non-profile menus
+- **Primary actions**: Critical actions belong in the main UI, not hidden in profile
+- **Complex forms**: Don't put forms or heavy content in the dropdown
+- **Mobile navigation**: Consider slide-out drawer or full-screen menu instead
+
 ## Common Use Cases
 
 ### Header Navigation
@@ -298,7 +310,7 @@ function AppHeader() {
   const { user, signOut } = useAuth();
 
   return (
-    <header style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+    <header>
       <Logo />
       <Navigation />
       <ProfileMenu
@@ -311,6 +323,7 @@ function AppHeader() {
         menuItems={[
           { label: 'My Profile', onClick: () => navigate('/profile') },
           { label: 'Account Settings', onClick: () => navigate('/settings') },
+          { label: 'Help & Support', onClick: () => window.open('/help') },
           { label: 'Sign Out', onClick: signOut },
         ]}
       />
@@ -322,19 +335,26 @@ function AppHeader() {
 ### Multi-Role User
 
 ```tsx
-function RoleBasedProfileMenu({ user, currentRole, switchRole, signOut }) {
+function RoleBasedProfileMenu({ user, currentRole, switchRole }) {
   const menuItems = [
     { label: 'My Profile', onClick: () => navigate('/profile') },
     { label: 'Settings', onClick: () => navigate('/settings') },
-    ...user.roles
-      .filter((role) => role !== currentRole)
-      .map((role) => ({
-        label: `Switch to ${role}`,
-        onClick: () => switchRole(role),
-      })),
-    { label: 'Sign Out', onClick: signOut },
   ];
 
+  // Add role switching if user has multiple roles
+  if (user.roles.length > 1) {
+    user.roles
+      .filter((role) => role !== currentRole)
+      .forEach((role) => {
+        menuItems.push({
+          label: `Switch to ${role}`,
+          onClick: () => switchRole(role),
+        });
+      });
+  }
+
+  menuItems.push({ label: 'Sign Out', onClick: () => signOut() });
+
   return (
     <ProfileMenu
       profile={{
@@ -371,46 +391,249 @@ function OrgProfileMenu({ user, organization }) {
 }
 ```
 
+### With Custom Initial Generation
+
+```tsx
+function CustomInitialsProfileMenu({ user }) {
+  // Custom function to generate initials
+  const getInitial = (name) => {
+    // For Korean names, use first character
+    if (/[\uAC00-\uD7AF]/.test(name)) {
+      return name.charAt(0);
+    }
+    // For English names, use first letters of first and last name
+    const parts = name.split(' ');
+    if (parts.length >= 2) {
+      return `${parts[0][0]}${parts[parts.length - 1][0]}`;
+    }
+    return name.substring(0, 2).toUpperCase();
+  };
+
+  return (
+    <ProfileMenu
+      profile={{
+        name: user.name,
+        caption: user.email,
+      }}
+      menuItems={[
+        { label: 'Profile', onClick: () => navigate('/profile') },
+        { label: 'Sign Out', onClick: () => signOut() },
+      ]}
+      getInitial={getInitial}
+    />
+  );
+}
+```
+
+## Props and Customization
+
+### Key Props
+
+| Prop           | Type                       | Default | Description                        |
+| -------------- | -------------------------- | ------- | ---------------------------------- |
+| `profile`      | `Profile`                  | -       | User profile information           |
+| `menuItems`    | `MenuItem[]`               | `[]`    | Array of menu actions              |
+| `open`         | `boolean`                  | -       | Controlled open state              |
+| `defaultOpen`  | `boolean`                  | `false` | Default open state (uncontrolled)  |
+| `onOpenChange` | `(open: boolean) => void`  | -       | Callback when open state changes   |
+| `size`         | `'sm' \| 'md'`             | `'md'`  | Size variant                       |
+| `getInitial`   | `(name: string) => string` | -       | Custom initial generation function |
+
+### Profile Type
+
+```tsx
+interface Profile {
+  name: string;              // User's display name (required)
+  caption?: string;          // Secondary text (email, role description)
+  chip?: string;             // Badge text (role, status)
+  image?: {
+    src: string;             // Avatar image URL
+    alt: string;             // Alt text for accessibility
+  };
+}
+```
+
+### MenuItem Type
+
+```tsx
+interface MenuItem {
+  label: string;             // Menu item text
+  onClick?: () => void;      // Click handler
+  // Plus any other MenuItem props from Joy UI
+}
+```
+
+### Controlled vs Uncontrolled
+
+```tsx
+// Uncontrolled - component manages state
+<ProfileMenu
+  defaultOpen={false}
+  profile={profile}
+  menuItems={menuItems}
+/>
+
+// Controlled - you manage state
+const [open, setOpen] = useState(false);
+<ProfileMenu
+  open={open}
+  onOpenChange={setOpen}
+  profile={profile}
+  menuItems={menuItems}
+/>
+```
+
+## Accessibility
+
+ProfileMenu includes built-in accessibility features:
+
+### ARIA Attributes
+
+- Button has proper `aria-haspopup` and `aria-expanded` attributes
+- Menu uses `role="menu"` with proper `role="menuitem"` for items
+- Focus management when opening and closing
+
+### Keyboard Navigation
+
+- **Tab**: Focus the profile button
+- **Enter/Space**: Open the menu
+- **Arrow Down**: Move to next menu item
+- **Arrow Up**: Move to previous menu item
+- **Enter**: Activate focused menu item
+- **Escape**: Close the menu
+
+### Screen Reader Support
+
+```tsx
+// Avatar announces the user name
+<ProfileMenu
+  profile={{
+    name: 'John Doe',  // Avatar reads "JD, John Doe"
+    image: { src: '...', alt: 'John Doe profile picture' },
+  }}
+/>
+```
+
+### Focus Management
+
+- Focus moves to first menu item when opened
+- Focus returns to button when menu closes
+- Click outside closes menu and returns focus
+
 ## Best Practices
 
-1. **Always include essential actions**: At minimum, provide access to profile viewing and sign-out.
+### ✅ Do
+
+1. **Include essential actions**: Always include profile and sign-out options
 
 ```tsx
-// ✅ Good: Essential menu items present
+// ✅ Good: Essential menu items
 <ProfileMenu
   menuItems={[
     { label: 'Profile', onClick: handleProfile },
+    { label: 'Settings', onClick: handleSettings },
     { label: 'Sign Out', onClick: handleSignOut },
   ]}
 />
-
-// ❌ Bad: Missing sign-out option
-<ProfileMenu menuItems={[{ label: 'Profile', onClick: handleProfile }]} />
 ```
 
-2. **Show user context**: Use the `chip` prop to display the user's current role or status so they know which account context they are operating in.
+2. **Show user context**: Display role or organization context in the chip
 
 ```tsx
 // ✅ Good: Clear user context
 <ProfileMenu
-  profile={{ name: 'Jane Smith', caption: 'jane@company.com', chip: 'Admin' }}
+  profile={{
+    name: 'Jane Smith',
+    caption: 'jane@company.com',
+    chip: 'Admin',  // Shows current role
+  }}
 />
 ```
 
-3. **Keep menu items concise**: Limit the number of menu items to 5-7 maximum. Move less common actions to a dedicated settings page.
+3. **Use descriptive labels**: Menu items should clearly describe actions
+
+4. **Provide avatar images**: When available, show actual profile photos
+
+### ❌ Don't
+
+1. **Don't overload with items**: Keep menu items to 5-7 maximum
 
 ```tsx
-// ❌ Bad: Too many items in the dropdown
-<ProfileMenu menuItems={[item1, item2, item3, item4, item5, item6, item7, item8, item9]} />
+// ❌ Bad: Too many items
+<ProfileMenu
+  menuItems={[
+    { label: 'Profile' },
+    { label: 'Settings' },
+    { label: 'Billing' },
+    { label: 'Team' },
+    { label: 'Integrations' },
+    { label: 'API Keys' },
+    { label: 'Audit Log' },
+    { label: 'Help' },
+    { label: 'Sign Out' },
+  ]}
+/>
 ```
 
-4. **Provide avatar images when available**: Real profile photos help users quickly identify the active account, especially in multi-user or shared environments.
+2. **Don't hide critical actions**: Important actions should be in main navigation
 
-5. **Do not use for non-user content**: ProfileMenu is specifically designed for user account contexts. For general navigation menus, use a regular Dropdown or Menu.
+3. **Don't use for non-user content**: ProfileMenu is specifically for user accounts
 
-## Accessibility
+4. **Don't leave profile empty**: Always provide at least the name
+
+## Performance Considerations
+
+### Lazy Load Menu Content
+
+For dynamic menu items, fetch data when needed:
+
+```tsx
+function ProfileMenuWithDynamicItems({ user }) {
+  const [menuItems, setMenuItems] = useState(baseMenuItems);
+
+  const handleOpenChange = async (isOpen) => {
+    if (isOpen && !menuItems.includes(dynamicItems)) {
+      const items = await fetchUserMenuItems(user.id);
+      setMenuItems([...baseMenuItems, ...items]);
+    }
+  };
+
+  return (
+    <ProfileMenu
+      profile={user}
+      menuItems={menuItems}
+      onOpenChange={handleOpenChange}
+    />
+  );
+}
+```
+
+### Memoize Menu Items
+
+When menu items are computed, memoize them:
+
+```tsx
+const menuItems = useMemo(() => [
+  { label: 'Profile', onClick: handleProfile },
+  { label: 'Settings', onClick: handleSettings },
+  ...(user.isAdmin ? [{ label: 'Admin', onClick: handleAdmin }] : []),
+  { label: 'Sign Out', onClick: handleSignOut },
+], [user.isAdmin, handleProfile, handleSettings, handleAdmin, handleSignOut]);
+```
+
+### Optimize Avatar Loading
+
+For profile images, ensure proper caching and loading:
+
+```tsx
+<ProfileMenu
+  profile={{
+    name: user.name,
+    image: user.avatarUrl
+      ? { src: `${user.avatarUrl}?size=64`, alt: user.name }
+      : undefined,
+  }}
+/>
+```
 
-- The avatar trigger button has `aria-haspopup` and `aria-expanded` attributes, informing assistive technology that it controls a menu.
-- The dropdown menu uses `role="menu"` with `role="menuitem"` for each action, following WAI-ARIA menu button pattern.
-- Keyboard navigation is fully supported: **Enter** or **Space** opens the menu, **Arrow Down/Up** navigates items, **Enter** activates a focused item, and **Escape** closes the menu.
-- Focus returns to the trigger button when the menu is closed, maintaining a predictable focus flow for keyboard and screen reader users.
+ProfileMenu provides a polished user account interface for admin applications. Place it in your header for easy access to user-related actions and account management.