@ceed/ads 1.23.3 → 1.23.5

package/dist/components/navigation/ProfileMenu.md

@@ -2,7 +2,9 @@
 
 ## 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 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.
+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.
 
 ```tsx
 <ProfileMenu
@@ -52,11 +54,11 @@ function Header() {
 }
 ```
 
-## Examples
+## Profile Variations
 
 ### Default
 
-ProfileMenu with full profile information including name, chip, and caption.
+ProfileMenu with full profile information including name, chip badge, and caption.
 
 ```tsx
 <ProfileMenu
@@ -81,7 +83,7 @@ ProfileMenu with full profile information including name, chip, and caption.
 
 ### Without Caption
 
-Profile showing only the name and chip badge.
+Profile showing only the name and chip badge, without a secondary caption line.
 
 ```tsx
 <ProfileMenu
@@ -105,7 +107,7 @@ Profile showing only the name and chip badge.
 
 ### Without Chip
 
-Profile showing name and caption without a badge.
+Profile showing the name and caption, without a badge chip.
 
 ```tsx
 <ProfileMenu
@@ -129,7 +131,7 @@ Profile showing name and caption without a badge.
 
 ### Only Name
 
-Minimal profile with just the user's name.
+Minimal profile display with just the user's name. Useful for compact layouts where additional context is not needed.
 
 ```tsx
 <ProfileMenu
@@ -152,7 +154,7 @@ Minimal profile with just the user's name.
 
 ### Without Menu Items
 
-Profile card without any menu actions.
+Profile card without any action menu items. The dropdown displays only the user information.
 
 ```tsx
 <ProfileMenu
@@ -166,9 +168,9 @@ Profile card without any menu actions.
 />
 ```
 
-### Sizes
+## Sizes
 
-ProfileMenu supports different sizes for various layouts.
+ProfileMenu supports `md` (default) and `sm` size variants for use in different layout densities.
 
 ```tsx
 <Stack direction="row" gap="150px">
@@ -203,9 +205,11 @@ ProfileMenu supports different sizes for various layouts.
 </Stack>
 ```
 
+## Avatar
+
 ### With Profile Image
 
-Display a custom avatar image instead of generated initials.
+When a user has a profile picture, pass the `image` property with `src` and `alt`. The image replaces the auto-generated initials.
 
 ```tsx
 <ProfileMenu
@@ -233,7 +237,7 @@ Display a custom avatar image instead of generated initials.
 
 ### With Korean Name
 
-ProfileMenu automatically generates initials from various name formats.
+ProfileMenu automatically generates initials from various name formats, including Korean names.
 
 ```tsx
 <>
@@ -250,9 +254,11 @@ ProfileMenu automatically generates initials from various name formats.
 </>
 ```
 
+## Controlled vs Uncontrolled
+
 ### Controlled
 
-Programmatically control the menu's open state.
+Use the `open` and `onOpenChange` props to control the menu's open state programmatically.
 
 ```tsx
 <ProfileMenu {...args} open={open} onOpenChange={setOpen} />
@@ -260,7 +266,7 @@ Programmatically control the menu's open state.
 
 ### Uncontrolled
 
-Let the component manage its own open state internally.
+Use `defaultOpen` to set the initial state, then let the component manage its own open/close behavior internally.
 
 ```tsx
 <ProfileMenu
@@ -283,24 +289,6 @@ Let the component manage its own open state internally.
 />
 ```
 
-## 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
@@ -310,7 +298,7 @@ function AppHeader() {
   const { user, signOut } = useAuth();
 
   return (
-    <header>
+    <header style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
       <Logo />
       <Navigation />
       <ProfileMenu
@@ -323,7 +311,6 @@ 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 },
         ]}
       />
@@ -335,25 +322,18 @@ function AppHeader() {
 ### Multi-Role User
 
 ```tsx
-function RoleBasedProfileMenu({ user, currentRole, switchRole }) {
+function RoleBasedProfileMenu({ user, currentRole, switchRole, signOut }) {
   const menuItems = [
     { label: 'My Profile', onClick: () => navigate('/profile') },
     { label: 'Settings', onClick: () => navigate('/settings') },
-  ];
-
-  // Add role switching if user has multiple roles
-  if (user.roles.length > 1) {
-    user.roles
+    ...user.roles
       .filter((role) => role !== currentRole)
-      .forEach((role) => {
-        menuItems.push({
-          label: `Switch to ${role}`,
-          onClick: () => switchRole(role),
-        });
-      });
-  }
-
-  menuItems.push({ label: 'Sign Out', onClick: () => signOut() });
+      .map((role) => ({
+        label: `Switch to ${role}`,
+        onClick: () => switchRole(role),
+      })),
+    { label: 'Sign Out', onClick: signOut },
+  ];
 
   return (
     <ProfileMenu
@@ -391,249 +371,46 @@ 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
 
-### ✅ Do
-
-1. **Include essential actions**: Always include profile and sign-out options
+1. **Always include essential actions**: At minimum, provide access to profile viewing and sign-out.
 
 ```tsx
-// ✅ Good: Essential menu items
+// ✅ Good: Essential menu items present
 <ProfileMenu
   menuItems={[
     { label: 'Profile', onClick: handleProfile },
-    { label: 'Settings', onClick: handleSettings },
     { label: 'Sign Out', onClick: handleSignOut },
   ]}
 />
-```
 
-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',  // Shows current role
-  }}
-/>
+// ❌ Bad: Missing sign-out option
+<ProfileMenu menuItems={[{ label: 'Profile', onClick: handleProfile }]} />
 ```
 
-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
+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.
 
 ```tsx
-// ❌ Bad: Too many items
+// ✅ Good: Clear user context
 <ProfileMenu
-  menuItems={[
-    { label: 'Profile' },
-    { label: 'Settings' },
-    { label: 'Billing' },
-    { label: 'Team' },
-    { label: 'Integrations' },
-    { label: 'API Keys' },
-    { label: 'Audit Log' },
-    { label: 'Help' },
-    { label: 'Sign Out' },
-  ]}
+  profile={{ name: 'Jane Smith', caption: 'jane@company.com', chip: 'Admin' }}
 />
 ```
 
-2. **Don't hide critical actions**: Important actions should be in main navigation
-
-3. **Don't use for non-user content**: ProfileMenu is specifically for user accounts
-
-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:
+3. **Keep menu items concise**: Limit the number of menu items to 5-7 maximum. Move less common actions to a dedicated settings page.
 
 ```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]);
+// ❌ Bad: Too many items in the dropdown
+<ProfileMenu menuItems={[item1, item2, item3, item4, item5, item6, item7, item8, item9]} />
 ```
 
-### Optimize Avatar Loading
+4. **Provide avatar images when available**: Real profile photos help users quickly identify the active account, especially in multi-user or shared environments.
 
-For profile images, ensure proper caching and loading:
+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.
 
-```tsx
-<ProfileMenu
-  profile={{
-    name: user.name,
-    image: user.avatarUrl
-      ? { src: `${user.avatarUrl}?size=64`, alt: user.name }
-      : undefined,
-  }}
-/>
-```
+## Accessibility
 
-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.
+- 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.