@ceed/ads 1.23.3 → 1.23.5

package/dist/components/navigation/MenuButton.md

@@ -1,8 +1,8 @@
 # MenuButton
 
-## Introduction
+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.
 
-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.
+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.
 
 ```tsx
 <MenuButton
@@ -34,15 +34,6 @@ MenuButton is a compound component that combines a button with a dropdown menu,
 | 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
@@ -62,31 +53,19 @@ function UserMenu() {
 }
 ```
 
-## Examples
+## When to Use Which
 
-### Playground
+| 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 |
 
-Interactive example with all controls.
+## Features
 
-```tsx
-<MenuButton
-  buttonText="Dashboard..."
-  items={[{
-  text: 'Profile'
-}, {
-  text: 'My account'
-}, {
-  text: 'Logout'
-}]}
-  showIcon
-  variant="solid"
-  color="primary"
-/>
-```
+### Standalone (Without Dropdown Icon)
 
-### Standalone (Without Icon)
-
-Use as a simple navigation link without the dropdown icon.
+Use `showIcon={false}` and a custom `buttonComponent` to render MenuButton as a standalone navigation link without the dropdown indicator.
 
 ```tsx
 <MenuButton
@@ -110,7 +89,7 @@ Use as a simple navigation link without the dropdown icon.
 
 ### With End Decorator
 
-Add badges, chips, or icons at the end of the button.
+Add badges, chips, or icons after the button text using `endDecorator`.
 
 ```tsx
 <MenuButton
@@ -131,7 +110,7 @@ Add badges, chips, or icons at the end of the button.
 
 ### Placement: Bottom Start
 
-Menu aligns to the left edge of the button.
+Menu aligns to the left edge of the trigger button.
 
 ```tsx
 <MenuButton
@@ -152,7 +131,7 @@ Menu aligns to the left edge of the button.
 
 ### Placement: Bottom
 
-Menu centers below the button.
+Menu centers below the trigger button.
 
 ```tsx
 <MenuButton
@@ -173,7 +152,7 @@ Menu centers below the button.
 
 ### Placement: Bottom End
 
-Menu aligns to the right edge of the button.
+Menu aligns to the right edge of the trigger button.
 
 ```tsx
 <MenuButton
@@ -192,25 +171,6 @@ Menu aligns to the right edge of the 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
@@ -226,7 +186,6 @@ 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 },
       ]}
     />
@@ -234,10 +193,10 @@ function AccountMenu({ user, onLogout }) {
 }
 ```
 
-### Export Options Menu
+### Export Options
 
 ```tsx
-function ExportMenu({ data, onExport }) {
+function ExportMenu({ onExport }) {
   return (
     <MenuButton
       buttonText="Export"
@@ -247,425 +206,73 @@ function ExportMenu({ data, 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() },
       ]}
     />
   );
 }
 ```
 
-### Actions Menu in Toolbar
+### Toolbar Actions
 
 ```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="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"
+      buttonText="Actions"
+      variant="outlined"
       color="neutral"
+      disabled={selectedItems.length === 0}
       items={[
-        {
-          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(),
-        },
+        { text: `Edit (${selectedItems.length})`, onClick: () => onAction('edit') },
+        { text: 'Duplicate', onClick: () => onAction('duplicate') },
+        { text: 'Archive', onClick: () => onAction('archive') },
+        { text: 'Delete', onClick: () => onAction('delete') },
       ]}
     />
   );
 }
 ```
 
-## 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
-
-```tsx
-// Small
-<MenuButton buttonText="Small" size="sm" items={items} />
-
-// Medium (default)
-<MenuButton buttonText="Medium" size="md" items={items} />
-
-// Large
-<MenuButton buttonText="Large" size="lg" items={items} />
-```
-
-### Custom Button Component
-
-```tsx
-// Use with custom components like Link
-import { Link } from 'react-router-dom';
-
-<MenuButton
-  buttonText="Dashboard"
-  buttonComponent={Link}
-  buttonComponentProps={{ to: '/dashboard' }}
-  showIcon={false}
-  items={items}
-/>
-```
-
-### Decorators
-
-```tsx
-// Start decorator (icon before text)
-<MenuButton
-  buttonText="Export"
-  startDecorator={<DownloadIcon />}
-  items={exportItems}
-/>
-
-// End decorator (badge after text)
-<MenuButton
-  buttonText="Inbox"
-  endDecorator={<Chip size="sm">5</Chip>}
-  items={inboxItems}
-/>
-
-// Both decorators
-<MenuButton
-  buttonText="User"
-  startDecorator={<Avatar size="sm" />}
-  endDecorator={<ChevronDownIcon />}
-  showIcon={false}
-  items={userItems}
-/>
-```
-
-## Accessibility
-
-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
+- **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".
 
-1. **Use clear, action-oriented labels**: Button text should indicate what the menu contains
+  ```tsx
+  {/* ✅ Good: Clear purpose */}
+  <MenuButton buttonText="Export Options" items={exportItems} />
 
-```tsx
-// ✅ Good: Clear menu purpose
-<MenuButton buttonText="Export Options" items={exportItems} />
-<MenuButton buttonText="User Actions" items={userItems} />
-```
+  {/* ❌ Avoid: Vague label */}
+  <MenuButton buttonText="More" items={items} />
+  ```
 
-2. **Group related actions**: Keep menu items logically related
+- **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.
 
-```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 },
-  ]}
-/>
-```
+- **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.
 
-3. **Use appropriate variants**: Match the button style to its context
+  ```tsx
+  {/* ✅ Good: Appropriate variants */}
+  <MenuButton buttonText="Create" variant="solid" color="primary" items={createItems} />
+  <MenuButton buttonText="Settings" variant="plain" color="neutral" items={settingsItems} />
+  ```
 
-```tsx
-// ✅ Good: Primary for main actions, plain for navigation
-<MenuButton buttonText="Create" variant="solid" color="primary" />
-<MenuButton buttonText="Settings" variant="plain" color="neutral" />
-```
+- **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.
 
-4. **Limit menu items**: Keep menus scannable (5-7 items max)
+  ```tsx
+  {/* ❌ Bad: Form selection */}
+  <MenuButton buttonText={selectedValue} items={options} />
 
-### ❌ Don't
+  {/* ✅ Good: Use Select for forms */}
+  <Select value={selectedValue} onChange={handleChange}>
+    <Option value="a">Option A</Option>
+    <Option value="b">Option B</Option>
+  </Select>
+  ```
 
-1. **Don't use for form inputs**: Use Select for value selection
+- **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.
 
-```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);
-      },
-    },
-  ],
-  []
-);
-```
+## Accessibility
 
-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.
+- **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.