@ceed/ads 1.29.0 → 1.30.0-next.1

package/dist/components/navigation/MenuButton.md

@@ -1,8 +1,8 @@
 # MenuButton
 
-MenuButton is a high-level compound component that combines a labeled button trigger with a dropdown menu in a single, prop-driven API. Pass `buttonText` and an `items` array and the component handles the Dropdown, Menu, and MenuItem composition internally. It is the recommended choice when you need a simple text-triggered menu without custom content inside the menu panel.
+## Introduction
 
-MenuButton belongs to the **menu component family** alongside Dropdown, Menu, MenuItem, and IconMenuButton. For icon-only triggers, use IconMenuButton. For menus that need custom content (headers, dividers, mixed elements), use the lower-level Dropdown + Menu composition instead.
+MenuButton is a compound component that combines a button with a dropdown menu, allowing users to trigger a list of actions or navigation options from a single interactive element. It displays a button with text and an optional dropdown indicator icon that, when clicked, reveals a menu of selectable items. MenuButton is commonly used for action menus, navigation shortcuts, and grouped operations in toolbars and headers.
 
 ```tsx
 <MenuButton
@@ -34,6 +34,15 @@ MenuButton belongs to the **menu component family** alongside Dropdown, Menu, Me
 | color                | —           | "primary"                                                             |
 | size                 | —           | —                                                                     |
 
+> ⚠️ **Usage Warning** ⚠️
+>
+> Choose the right component for your use case:
+>
+> - **MenuButton**: For action menus triggered by a labeled button
+> - **IconMenuButton**: For action menus triggered by an icon-only button
+> - **Dropdown**: For more complex menu structures with custom triggers
+> - **Select**: For form inputs where user selects a value (not actions)
+
 ## Usage
 
 ```tsx
@@ -53,19 +62,31 @@ function UserMenu() {
 }
 ```
 
-## When to Use Which
+## Examples
 
-| Component           | Trigger     | Content          | Use when                                                     |
-| ------------------- | ----------- | ---------------- | ------------------------------------------------------------ |
-| **MenuButton**      | Text button | Simple item list | You need a labeled trigger with a flat list of text options  |
-| **IconMenuButton**  | Icon button | Simple item list | Space is limited (tables, cards, toolbars)                   |
-| **Dropdown + Menu** | Any element | Rich content     | You need dividers, headers, icons in items, or custom layout |
+### Playground
 
-## Features
+Interactive example with all controls.
 
-### Standalone (Without Dropdown Icon)
+```tsx
+<MenuButton
+  buttonText="Dashboard..."
+  items={[{
+  text: 'Profile'
+}, {
+  text: 'My account'
+}, {
+  text: 'Logout'
+}]}
+  showIcon
+  variant="solid"
+  color="primary"
+/>
+```
 
-Use `showIcon={false}` and a custom `buttonComponent` to render MenuButton as a standalone navigation link without the dropdown indicator.
+### Standalone (Without Icon)
+
+Use as a simple navigation link without the dropdown icon.
 
 ```tsx
 <MenuButton
@@ -89,7 +110,7 @@ Use `showIcon={false}` and a custom `buttonComponent` to render MenuButton as a
 
 ### With End Decorator
 
-Add badges, chips, or icons after the button text using `endDecorator`.
+Add badges, chips, or icons at the end of the button.
 
 ```tsx
 <MenuButton
@@ -110,7 +131,7 @@ Add badges, chips, or icons after the button text using `endDecorator`.
 
 ### Placement: Bottom Start
 
-Menu aligns to the left edge of the trigger button.
+Menu aligns to the left edge of the button.
 
 ```tsx
 <MenuButton
@@ -131,7 +152,7 @@ Menu aligns to the left edge of the trigger button.
 
 ### Placement: Bottom
 
-Menu centers below the trigger button.
+Menu centers below the button.
 
 ```tsx
 <MenuButton
@@ -152,7 +173,7 @@ Menu centers below the trigger button.
 
 ### Placement: Bottom End
 
-Menu aligns to the right edge of the trigger button.
+Menu aligns to the right edge of the button.
 
 ```tsx
 <MenuButton
@@ -171,6 +192,25 @@ Menu aligns to the right edge of the trigger button.
 />
 ```
 
+## When to Use
+
+### ✅ Good Use Cases
+
+- **User account menus**: Profile, settings, logout actions
+- **Action grouping**: Related actions in a toolbar
+- **Navigation shortcuts**: Quick access to related pages
+- **Overflow menus**: When space is limited
+- **Context actions**: Page or section-specific actions
+- **Export options**: Download, export, or share actions
+
+### ❌ When Not to Use
+
+- **Form value selection**: Use Select for picking values in forms
+- **Single action**: Use Button for single actions
+- **Icon-only trigger**: Use IconMenuButton for minimal space
+- **Complex menus**: Use Dropdown for nested menus or custom content
+- **Primary navigation**: Use Navigator or Tabs for main navigation
+
 ## Common Use Cases
 
 ### User Account Menu
@@ -186,6 +226,7 @@ function AccountMenu({ user, onLogout }) {
       items={[
         { text: 'Profile', onClick: () => navigate('/profile') },
         { text: 'Account Settings', onClick: () => navigate('/settings') },
+        { text: 'Billing', onClick: () => navigate('/billing') },
         { text: 'Logout', onClick: onLogout },
       ]}
     />
@@ -193,10 +234,10 @@ function AccountMenu({ user, onLogout }) {
 }
 ```
 
-### Export Options
+### Export Options Menu
 
 ```tsx
-function ExportMenu({ onExport }) {
+function ExportMenu({ data, onExport }) {
   return (
     <MenuButton
       buttonText="Export"
@@ -206,73 +247,425 @@ function ExportMenu({ onExport }) {
         { text: 'Export as CSV', onClick: () => onExport('csv') },
         { text: 'Export as Excel', onClick: () => onExport('xlsx') },
         { text: 'Export as PDF', onClick: () => onExport('pdf') },
+        { text: 'Print', onClick: () => window.print() },
       ]}
     />
   );
 }
 ```
 
-### Toolbar Actions
+### Actions Menu in Toolbar
 
 ```tsx
 function ToolbarActions({ selectedItems, onAction }) {
+  const hasSelection = selectedItems.length > 0;
+
+  return (
+    <Stack direction="row" gap={1}>
+      <Button onClick={() => onAction('create')}>Create New</Button>
+      <MenuButton
+        buttonText="Actions"
+        variant="outlined"
+        color="neutral"
+        disabled={!hasSelection}
+        items={[
+          { text: `Edit (${selectedItems.length})`, onClick: () => onAction('edit') },
+          { text: 'Duplicate', onClick: () => onAction('duplicate') },
+          { text: 'Move to Folder', onClick: () => onAction('move') },
+          { text: 'Archive', onClick: () => onAction('archive') },
+          { text: 'Delete', onClick: () => onAction('delete') },
+        ]}
+      />
+    </Stack>
+  );
+}
+```
+
+### Navigation with Dropdown
+
+```tsx
+function ProductsMenu() {
   return (
     <MenuButton
-      buttonText="Actions"
-      variant="outlined"
+      buttonText="Products"
+      variant="plain"
+      showIcon={true}
+      items={[
+        { text: 'All Products', onClick: () => navigate('/products') },
+        { text: 'Categories', onClick: () => navigate('/products/categories') },
+        { text: 'Inventory', onClick: () => navigate('/products/inventory') },
+        { text: 'Price Lists', onClick: () => navigate('/products/prices') },
+      ]}
+    />
+  );
+}
+```
+
+### Status Change Menu
+
+```tsx
+function StatusMenu({ currentStatus, onStatusChange }) {
+  const statuses = [
+    { value: 'draft', label: 'Draft', color: 'neutral' },
+    { value: 'pending', label: 'Pending Review', color: 'warning' },
+    { value: 'approved', label: 'Approved', color: 'success' },
+    { value: 'rejected', label: 'Rejected', color: 'danger' },
+  ];
+
+  const current = statuses.find((s) => s.value === currentStatus);
+
+  return (
+    <MenuButton
+      buttonText={current?.label || 'Set Status'}
+      variant="soft"
+      color={current?.color || 'neutral'}
+      items={statuses.map((status) => ({
+        text: status.label,
+        onClick: () => onStatusChange(status.value),
+      }))}
+    />
+  );
+}
+```
+
+### Menu with Decorators
+
+```tsx
+function NotificationsMenu({ notifications }) {
+  const unreadCount = notifications.filter((n) => !n.read).length;
+
+  return (
+    <MenuButton
+      buttonText="Notifications"
+      startDecorator={<NotificationsIcon />}
+      endDecorator={
+        unreadCount > 0 && (
+          <Chip size="sm" color="danger">
+            {unreadCount}
+          </Chip>
+        )
+      }
+      variant="soft"
+      items={notifications.slice(0, 5).map((n) => ({
+        text: n.title,
+        onClick: () => markAsRead(n.id),
+      }))}
+    />
+  );
+}
+```
+
+### Quick Settings Menu
+
+```tsx
+function QuickSettings({ settings, onSettingChange }) {
+  return (
+    <MenuButton
+      buttonText="Settings"
+      startDecorator={<SettingsIcon />}
+      variant="plain"
       color="neutral"
-      disabled={selectedItems.length === 0}
       items={[
-        { text: `Edit (${selectedItems.length})`, onClick: () => onAction('edit') },
-        { text: 'Duplicate', onClick: () => onAction('duplicate') },
-        { text: 'Archive', onClick: () => onAction('archive') },
-        { text: 'Delete', onClick: () => onAction('delete') },
+        {
+          text: settings.darkMode ? '☀️ Light Mode' : '🌙 Dark Mode',
+          onClick: () => onSettingChange('darkMode', !settings.darkMode),
+        },
+        {
+          text: settings.compactView ? '📐 Normal View' : '📏 Compact View',
+          onClick: () => onSettingChange('compactView', !settings.compactView),
+        },
+        {
+          text: 'Language: ' + settings.language.toUpperCase(),
+          onClick: () => openLanguageModal(),
+        },
       ]}
     />
   );
 }
 ```
 
-## Best Practices
+## Props and Customization
+
+### Key Props
+
+| Prop                   | Type                                                           | Default          | Description                       |
+| ---------------------- | -------------------------------------------------------------- | ---------------- | --------------------------------- |
+| `buttonText`           | `string`                                                       | -                | Text displayed on the button      |
+| `items`                | `Array<{ text: string; onClick?: () => void }>`                | -                | Menu items to display             |
+| `showIcon`             | `boolean`                                                      | `true`           | Show dropdown indicator icon      |
+| `variant`              | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'solid'`        | Button style variant              |
+| `color`                | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'primary'`      | Button color                      |
+| `size`                 | `'sm' \| 'md' \| 'lg'`                                         | `'md'`           | Button size                       |
+| `placement`            | `'bottom-start' \| 'bottom' \| 'bottom-end'`                   | `'bottom-start'` | Menu position                     |
+| `startDecorator`       | `ReactNode`                                                    | -                | Content before button text        |
+| `endDecorator`         | `ReactNode`                                                    | -                | Content after button text         |
+| `buttonComponent`      | `React.ElementType`                                            | `Button`         | Custom button component           |
+| `buttonComponentProps` | `object`                                                       | -                | Props for custom button component |
+
+### Menu Item Structure
+
+```tsx
+interface MenuItem {
+  text: string;          // Display text
+  onClick?: () => void;  // Click handler
+  // Additional props can be passed based on implementation
+}
+
+// Example items array
+const items = [
+  { text: 'Edit', onClick: handleEdit },
+  { text: 'Delete', onClick: handleDelete },
+];
+```
+
+### Variant and Color Options
+
+```tsx
+// Primary solid (default)
+<MenuButton buttonText="Actions" variant="solid" color="primary" />
+
+// Subtle outlined
+<MenuButton buttonText="Actions" variant="outlined" color="neutral" />
+
+// Soft background
+<MenuButton buttonText="Actions" variant="soft" color="primary" />
+
+// Plain/text only
+<MenuButton buttonText="Actions" variant="plain" color="neutral" />
+
+// Danger color
+<MenuButton buttonText="Delete" variant="soft" color="danger" />
+```
+
+### Size Options
 
-- **Use descriptive button text.** The button label should clearly indicate what kind of options the menu contains. Avoid vague labels like "More" or "Options" -- prefer specific labels like "Export Options" or "User Actions".
+```tsx
+// Small
+<MenuButton buttonText="Small" size="sm" items={items} />
 
-  ```tsx
-  {/* ✅ Good: Clear purpose */}
-  <MenuButton buttonText="Export Options" items={exportItems} />
+// Medium (default)
+<MenuButton buttonText="Medium" size="md" items={items} />
 
-  {/* ❌ Avoid: Vague label */}
-  <MenuButton buttonText="More" items={items} />
-  ```
+// Large
+<MenuButton buttonText="Large" size="lg" items={items} />
+```
 
-- **Keep the items list short and focused.** Aim for 3-7 items that are logically related. If you need more items or mixed content, switch to the Dropdown + Menu composition pattern.
+### Custom Button Component
 
-- **Match variant to context.** Use `variant="solid"` for primary action menus, `variant="outlined"` or `variant="plain"` for secondary or navigation menus. Be consistent within the same toolbar or header.
+```tsx
+// Use with custom components like Link
+import { Link } from 'react-router-dom';
 
-  ```tsx
-  {/* ✅ Good: Appropriate variants */}
-  <MenuButton buttonText="Create" variant="solid" color="primary" items={createItems} />
-  <MenuButton buttonText="Settings" variant="plain" color="neutral" items={settingsItems} />
-  ```
+<MenuButton
+  buttonText="Dashboard"
+  buttonComponent={Link}
+  buttonComponentProps={{ to: '/dashboard' }}
+  showIcon={false}
+  items={items}
+/>
+```
 
-- **Do not use MenuButton for form value selection.** MenuButton triggers actions -- it is not a Select replacement. For form inputs where the user picks a value, use the Select component.
+### Decorators
 
-  ```tsx
-  {/* ❌ Bad: Form selection */}
-  <MenuButton buttonText={selectedValue} items={options} />
+```tsx
+// Start decorator (icon before text)
+<MenuButton
+  buttonText="Export"
+  startDecorator={<DownloadIcon />}
+  items={exportItems}
+/>
 
-  {/* ✅ Good: Use Select for forms */}
-  <Select value={selectedValue} onChange={handleChange}>
-    <Option value="a">Option A</Option>
-    <Option value="b">Option B</Option>
-  </Select>
-  ```
+// End decorator (badge after text)
+<MenuButton
+  buttonText="Inbox"
+  endDecorator={<Chip size="sm">5</Chip>}
+  items={inboxItems}
+/>
 
-- **Use `placement` to prevent overflow.** When the trigger is near the right edge of the viewport, use `placement="bottom-end"` so the menu does not extend beyond the screen.
+// Both decorators
+<MenuButton
+  buttonText="User"
+  startDecorator={<Avatar size="sm" />}
+  endDecorator={<ChevronDownIcon />}
+  showIcon={false}
+  items={userItems}
+/>
+```
 
 ## Accessibility
 
-- **ARIA attributes**: The trigger button automatically receives `aria-haspopup="true"` and `aria-expanded` that reflects the open/closed state. The menu panel has `role="menu"` and each item has `role="menuitem"`.
-- **Keyboard navigation**: Enter or Space opens the menu. Arrow Down/Up moves between items. Escape closes the menu and returns focus to the button. Tab closes the menu and moves focus to the next element.
-- **Screen reader support**: The button is announced as "\[buttonText], menu button, expanded/collapsed". Menu items are announced with their position (e.g., "Profile, menu item, 1 of 3").
-- **Focus management**: Focus moves to the first menu item when the menu opens and returns to the trigger button when the menu closes.
+MenuButton includes built-in accessibility features:
+
+### ARIA Attributes
+
+- Button has `aria-haspopup="true"` indicating it opens a menu
+- Button has `aria-expanded` reflecting menu open state
+- Menu has proper `role="menu"` and `role="menuitem"` structure
+- Focus is managed between button and menu items
+
+### Keyboard Navigation
+
+- **Enter/Space**: Open menu when button is focused
+- **Arrow Down**: Move to next menu item
+- **Arrow Up**: Move to previous menu item
+- **Escape**: Close menu and return focus to button
+- **Tab**: Close menu and move to next focusable element
+- **Enter**: Select focused menu item
+
+### Screen Reader Support
+
+```tsx
+// Button announces: "Account, menu button, expanded/collapsed"
+<MenuButton
+  buttonText="Account"
+  items={[...]}
+/>
+
+// Menu items are announced as: "Profile, menu item, 1 of 3"
+```
+
+### Focus Management
+
+- Focus moves to first menu item when menu opens
+- Focus returns to button when menu closes
+- Menu items are focusable with arrow keys
+
+## Best Practices
+
+### ✅ Do
+
+1. **Use clear, action-oriented labels**: Button text should indicate what the menu contains
+
+```tsx
+// ✅ Good: Clear menu purpose
+<MenuButton buttonText="Export Options" items={exportItems} />
+<MenuButton buttonText="User Actions" items={userItems} />
+```
+
+2. **Group related actions**: Keep menu items logically related
+
+```tsx
+// ✅ Good: Related file actions
+<MenuButton
+  buttonText="File"
+  items={[
+    { text: 'New', onClick: handleNew },
+    { text: 'Open', onClick: handleOpen },
+    { text: 'Save', onClick: handleSave },
+    { text: 'Save As...', onClick: handleSaveAs },
+  ]}
+/>
+```
+
+3. **Use appropriate variants**: Match the button style to its context
+
+```tsx
+// ✅ Good: Primary for main actions, plain for navigation
+<MenuButton buttonText="Create" variant="solid" color="primary" />
+<MenuButton buttonText="Settings" variant="plain" color="neutral" />
+```
+
+4. **Limit menu items**: Keep menus scannable (5-7 items max)
+
+### ❌ Don't
+
+1. **Don't use for form inputs**: Use Select for value selection
+
+```tsx
+// ❌ Bad: Using MenuButton for form selection
+<MenuButton buttonText={selectedOption} items={options} />
+
+// ✅ Good: Use Select for forms
+<Select value={selectedOption} onChange={handleChange}>
+  {options.map((opt) => <Option key={opt.value} value={opt.value}>{opt.label}</Option>)}
+</Select>
+```
+
+2. **Don't use vague labels**: Be specific about menu contents
+
+```tsx
+// ❌ Bad: Unclear what "More" contains
+<MenuButton buttonText="More" items={items} />
+
+// ✅ Good: Clear menu purpose
+<MenuButton buttonText="More Actions" items={actionItems} />
+```
+
+3. **Don't overload menus**: Split large menus into categories
+
+```tsx
+// ❌ Bad: Too many unrelated items
+<MenuButton
+  buttonText="Options"
+  items={[
+    { text: 'Edit' },
+    { text: 'Delete' },
+    { text: 'Share' },
+    { text: 'Settings' },
+    { text: 'Help' },
+    { text: 'About' },
+    // ... many more items
+  ]}
+/>
+```
+
+4. **Don't hide primary actions**: Important actions should be visible
+
+## Performance Considerations
+
+### Memoize Items Array
+
+Prevent unnecessary re-renders by memoizing the items array:
+
+```tsx
+const menuItems = useMemo(
+  () => [
+    { text: 'Edit', onClick: handleEdit },
+    { text: 'Delete', onClick: handleDelete },
+  ],
+  [handleEdit, handleDelete]
+);
+
+<MenuButton buttonText="Actions" items={menuItems} />
+```
+
+### Memoize Click Handlers
+
+```tsx
+const handleExport = useCallback(
+  (format: string) => {
+    exportData(data, format);
+  },
+  [data]
+);
+
+const exportItems = useMemo(
+  () => [
+    { text: 'CSV', onClick: () => handleExport('csv') },
+    { text: 'Excel', onClick: () => handleExport('xlsx') },
+  ],
+  [handleExport]
+);
+```
+
+### Lazy Load Heavy Actions
+
+For actions that trigger heavy operations:
+
+```tsx
+const items = useMemo(
+  () => [
+    {
+      text: 'Generate Report',
+      onClick: async () => {
+        setLoading(true);
+        await generateReport();
+        setLoading(false);
+      },
+    },
+  ],
+  []
+);
+```
+
+MenuButton provides a convenient way to group related actions behind a single button trigger. Use it for account menus, action groups, and navigation shortcuts while keeping the menu contents focused and scannable. For icon-only triggers in space-constrained areas, consider IconMenuButton instead.