@ceed/ads 1.29.0 → 1.30.0-next.1

package/dist/components/navigation/IconMenuButton.md

@@ -1,8 +1,8 @@
 # IconMenuButton
 
-IconMenuButton is a compact menu trigger that displays only an icon (typically a "more" or kebab icon) to reveal a dropdown list of actions. It shares the same prop-driven API as MenuButton -- pass an `items` array and the component handles the rest -- but it takes up minimal screen space by omitting visible text. This makes it ideal for table rows, card actions, list items, and toolbars where space is limited.
+## Introduction
 
-IconMenuButton is part of the **menu component family** alongside Dropdown, Menu, MenuItem, and MenuButton. When space allows, prefer MenuButton for its clearer labeling. When you need custom content inside the menu (dividers, headers, icons on items), use the lower-level Dropdown + Menu composition instead.
+IconMenuButton is a compact menu trigger component that displays an icon-only button to reveal a dropdown menu of actions. Unlike MenuButton which shows text, IconMenuButton uses minimal screen space by displaying only an icon (commonly a "more" or kebab icon). It's ideal for table row actions, card menus, and any context where space is limited but multiple actions need to be accessible.
 
 ```tsx
 <IconMenuButton
@@ -30,6 +30,15 @@ IconMenuButton is part of the **menu component family** alongside Dropdown, Menu
 | color                | —           | "primary"                                                             |
 | size                 | —           | —                                                                     |
 
+> ⚠️ **Usage Warning** ⚠️
+>
+> Accessibility consideration for icon-only buttons:
+>
+> - **Always provide `aria-label`**: Screen readers need text context
+> - **Use familiar icons**: MoreVert (⋮), MoreHoriz (⋯) are commonly recognized
+> - **Consider MenuButton**: When space allows, text labels improve clarity
+> - **Tooltip support**: Consider adding tooltips for sighted users
+
 ## Usage
 
 ```tsx
@@ -50,11 +59,30 @@ function RowActions({ onEdit, onDelete }) {
 }
 ```
 
-## Features
+## Examples
+
+### Playground
+
+Interactive example with all controls.
+
+```tsx
+<IconMenuButton
+  icon={<MoreVert />}
+  items={[{
+  text: 'Profile'
+}, {
+  text: 'My account'
+}, {
+  text: 'Logout'
+}]}
+  variant="solid"
+  color="primary"
+/>
+```
 
 ### Standalone
 
-Icon button rendered without dropdown menu functionality, useful as a custom link trigger.
+Icon button without dropdown functionality.
 
 ```tsx
 <IconMenuButton
@@ -77,7 +105,7 @@ Icon button rendered without dropdown menu functionality, useful as a custom lin
 
 ### Placement: Bottom Start
 
-Menu aligns to the left edge of the icon button.
+Menu aligns to the left edge of the button.
 
 ```tsx
 <IconMenuButton
@@ -100,7 +128,7 @@ Menu aligns to the left edge of the icon button.
 
 ### Placement: Bottom
 
-Menu centers below the icon button.
+Menu centers below the button.
 
 ```tsx
 <IconMenuButton
@@ -123,7 +151,7 @@ Menu centers below the icon button.
 
 ### Placement: Bottom End
 
-Menu aligns to the right edge of the icon button. Recommended when the button is positioned on the right side of a container to prevent the menu from overflowing the viewport.
+Menu aligns to the right edge of the button.
 
 ```tsx
 <IconMenuButton
@@ -144,6 +172,25 @@ Menu aligns to the right edge of the icon button. Recommended when the button is
 />
 ```
 
+## When to Use
+
+### ✅ Good Use Cases
+
+- **Table row actions**: Edit, delete, view details actions for each row
+- **Card menus**: Action menus on cards or list items
+- **Toolbar overflow**: Secondary actions in space-constrained toolbars
+- **Mobile interfaces**: Compact action triggers on mobile screens
+- **Grid item actions**: Actions for items in a grid layout
+- **List item actions**: Contextual actions for list entries
+
+### ❌ When Not to Use
+
+- **Primary actions**: Important actions should be visible buttons
+- **When space allows text**: Use MenuButton for clearer labeling
+- **Form submissions**: Use standard buttons for form actions
+- **Navigation**: Use proper navigation components for routing
+- **Single action**: Use IconButton for single-action scenarios
+
 ## Common Use Cases
 
 ### Table Row Actions
@@ -154,12 +201,12 @@ function DataTableRow({ row, onEdit, onDelete, onDuplicate }) {
     <tr>
       <td>{row.name}</td>
       <td>{row.status}</td>
+      <td>{row.date}</td>
       <td>
         <IconMenuButton
           icon={<MoreVertIcon />}
           variant="plain"
           color="neutral"
-          size="sm"
           buttonComponentProps={{ 'aria-label': `Actions for ${row.name}` }}
           items={[
             { text: 'Edit', onClick: () => onEdit(row.id) },
@@ -173,12 +220,17 @@ function DataTableRow({ row, onEdit, onDelete, onDuplicate }) {
 }
 ```
 
-### Card Actions
+### Card Actions Menu
 
 ```tsx
 function ProductCard({ product, onAction }) {
   return (
     <Card>
+      <CardOverflow>
+        <AspectRatio>
+          <img src={product.image} alt={product.name} />
+        </AspectRatio>
+      </CardOverflow>
       <CardContent>
         <Box sx={{ display: 'flex', justifyContent: 'space-between' }}>
           <Typography level="title-md">{product.name}</Typography>
@@ -190,24 +242,159 @@ function ProductCard({ product, onAction }) {
             items={[
               { text: 'View Details', onClick: () => onAction('view', product.id) },
               { text: 'Edit', onClick: () => onAction('edit', product.id) },
-              { text: 'Delete', onClick: () => onAction('delete', product.id) },
+              { text: 'Add to Cart', onClick: () => onAction('cart', product.id) },
+              { text: 'Share', onClick: () => onAction('share', product.id) },
             ]}
           />
         </Box>
+        <Typography level="body-sm">${product.price}</Typography>
       </CardContent>
     </Card>
   );
 }
 ```
 
-### Toolbar Overflow
+### Comment Actions
+
+```tsx
+function Comment({ comment, currentUserId, onAction }) {
+  const isOwner = comment.authorId === currentUserId;
+
+  return (
+    <Box sx={{ display: 'flex', gap: 2 }}>
+      <Avatar src={comment.authorAvatar} />
+      <Box sx={{ flex: 1 }}>
+        <Stack direction="row" justifyContent="space-between" alignItems="flex-start">
+          <Box>
+            <Typography level="title-sm">{comment.authorName}</Typography>
+            <Typography level="body-xs" color="neutral">
+              {comment.timestamp}
+            </Typography>
+          </Box>
+          <IconMenuButton
+            icon={<MoreHorizIcon />}
+            variant="plain"
+            color="neutral"
+            size="sm"
+            buttonComponentProps={{ 'aria-label': 'Comment actions' }}
+            items={[
+              { text: 'Reply', onClick: () => onAction('reply', comment.id) },
+              ...(isOwner
+                ? [
+                    { text: 'Edit', onClick: () => onAction('edit', comment.id) },
+                    { text: 'Delete', onClick: () => onAction('delete', comment.id) },
+                  ]
+                : [{ text: 'Report', onClick: () => onAction('report', comment.id) }]),
+            ]}
+          />
+        </Stack>
+        <Typography level="body-sm" sx={{ mt: 1 }}>
+          {comment.content}
+        </Typography>
+      </Box>
+    </Box>
+  );
+}
+```
+
+### Notification Item Actions
+
+```tsx
+function NotificationItem({ notification, onAction }) {
+  return (
+    <ListItem
+      sx={{
+        bgcolor: notification.read ? 'transparent' : 'primary.softBg',
+      }}
+    >
+      <ListItemDecorator>
+        <Avatar src={notification.avatar} />
+      </ListItemDecorator>
+      <ListItemContent>
+        <Typography level="title-sm">{notification.title}</Typography>
+        <Typography level="body-xs">{notification.time}</Typography>
+      </ListItemContent>
+      <IconMenuButton
+        icon={<MoreVertIcon />}
+        variant="plain"
+        color="neutral"
+        size="sm"
+        buttonComponentProps={{ 'aria-label': 'Notification actions' }}
+        items={[
+          {
+            text: notification.read ? 'Mark as Unread' : 'Mark as Read',
+            onClick: () => onAction('toggleRead', notification.id),
+          },
+          { text: 'Dismiss', onClick: () => onAction('dismiss', notification.id) },
+          { text: 'Turn Off', onClick: () => onAction('turnOff', notification.type) },
+        ]}
+      />
+    </ListItem>
+  );
+}
+```
+
+### File Item Actions
+
+```tsx
+function FileItem({ file, onAction }) {
+  const getFileIcon = () => {
+    switch (file.type) {
+      case 'folder':
+        return <FolderIcon />;
+      case 'image':
+        return <ImageIcon />;
+      case 'document':
+        return <DescriptionIcon />;
+      default:
+        return <InsertDriveFileIcon />;
+    }
+  };
+
+  return (
+    <ListItem>
+      <ListItemDecorator>{getFileIcon()}</ListItemDecorator>
+      <ListItemContent>
+        <Typography level="title-sm">{file.name}</Typography>
+        <Typography level="body-xs" color="neutral">
+          {file.size} • Modified {file.modified}
+        </Typography>
+      </ListItemContent>
+      <IconMenuButton
+        icon={<MoreVertIcon />}
+        variant="plain"
+        color="neutral"
+        size="sm"
+        placement="bottom-end"
+        buttonComponentProps={{ 'aria-label': `Actions for ${file.name}` }}
+        items={[
+          { text: 'Download', onClick: () => onAction('download', file.id) },
+          { text: 'Share', onClick: () => onAction('share', file.id) },
+          { text: 'Rename', onClick: () => onAction('rename', file.id) },
+          { text: 'Move', onClick: () => onAction('move', file.id) },
+          { text: 'Delete', onClick: () => onAction('delete', file.id) },
+        ]}
+      />
+    </ListItem>
+  );
+}
+```
+
+### Toolbar Overflow Menu
 
 ```tsx
 function EditorToolbar({ onAction }) {
   return (
     <Stack direction="row" gap={1} alignItems="center">
-      <IconButton onClick={() => onAction('bold')}><FormatBoldIcon /></IconButton>
-      <IconButton onClick={() => onAction('italic')}><FormatItalicIcon /></IconButton>
+      <IconButton onClick={() => onAction('bold')}>
+        <FormatBoldIcon />
+      </IconButton>
+      <IconButton onClick={() => onAction('italic')}>
+        <FormatItalicIcon />
+      </IconButton>
+      <IconButton onClick={() => onAction('underline')}>
+        <FormatUnderlinedIcon />
+      </IconButton>
       <Divider orientation="vertical" />
       <IconMenuButton
         icon={<MoreHorizIcon />}
@@ -217,7 +404,9 @@ function EditorToolbar({ onAction }) {
         items={[
           { text: 'Strikethrough', onClick: () => onAction('strikethrough') },
           { text: 'Superscript', onClick: () => onAction('superscript') },
+          { text: 'Subscript', onClick: () => onAction('subscript') },
           { text: 'Code', onClick: () => onAction('code') },
+          { text: 'Clear Formatting', onClick: () => onAction('clear') },
         ]}
       />
     </Stack>
@@ -225,42 +414,315 @@ function EditorToolbar({ onAction }) {
 }
 ```
 
-## Best Practices
+### User List Item
+
+```tsx
+function UserListItem({ user, onAction }) {
+  return (
+    <ListItem>
+      <ListItemDecorator>
+        <Avatar src={user.avatar}>{user.initials}</Avatar>
+      </ListItemDecorator>
+      <ListItemContent>
+        <Typography level="title-sm">{user.name}</Typography>
+        <Typography level="body-xs">{user.email}</Typography>
+      </ListItemContent>
+      <Chip size="sm" color={user.active ? 'success' : 'neutral'}>
+        {user.active ? 'Active' : 'Inactive'}
+      </Chip>
+      <IconMenuButton
+        icon={<MoreVertIcon />}
+        variant="plain"
+        color="neutral"
+        size="sm"
+        buttonComponentProps={{ 'aria-label': `Actions for ${user.name}` }}
+        items={[
+          { text: 'View Profile', onClick: () => onAction('view', user.id) },
+          { text: 'Send Message', onClick: () => onAction('message', user.id) },
+          {
+            text: user.active ? 'Deactivate' : 'Activate',
+            onClick: () => onAction('toggleActive', user.id),
+          },
+          { text: 'Remove', onClick: () => onAction('remove', user.id) },
+        ]}
+      />
+    </ListItem>
+  );
+}
+```
+
+## Props and Customization
+
+### Key Props
+
+| Prop                   | Type                                                           | Default          | Description                                        |
+| ---------------------- | -------------------------------------------------------------- | ---------------- | -------------------------------------------------- |
+| `icon`                 | `ReactNode`                                                    | -                | Icon element to display (e.g., `<MoreVertIcon />`) |
+| `items`                | `Array<{ text: string; onClick?: () => void }>`                | -                | Menu items to display                              |
+| `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                                      |
+| `buttonComponent`      | `React.ElementType`                                            | `IconButton`     | Custom button component                            |
+| `buttonComponentProps` | `object`                                                       | -                | Props for button (include `aria-label`)            |
+
+### Common Icon Options
+
+```tsx
+import MoreVertIcon from '@mui/icons-material/MoreVert';     // Vertical dots (⋮)
+import MoreHorizIcon from '@mui/icons-material/MoreHoriz';   // Horizontal dots (⋯)
+import SettingsIcon from '@mui/icons-material/Settings';     // Gear icon
+import MenuIcon from '@mui/icons-material/Menu';             // Hamburger menu
+
+// Vertical dots (most common)
+<IconMenuButton icon={<MoreVertIcon />} items={items} />
+
+// Horizontal dots
+<IconMenuButton icon={<MoreHorizIcon />} items={items} />
 
-- **Always provide `aria-label`.** Since IconMenuButton has no visible text, screen readers rely entirely on the `aria-label` to announce the button's purpose. Include context when possible.
+// Custom icon
+<IconMenuButton icon={<SettingsIcon />} items={settingsItems} />
+```
+
+### Variant and Color Options
+
+```tsx
+// Solid (default) - high emphasis
+<IconMenuButton icon={<MoreVertIcon />} variant="solid" color="primary" />
+
+// Plain - minimal emphasis (recommended for tables/lists)
+<IconMenuButton icon={<MoreVertIcon />} variant="plain" color="neutral" />
 
-  ```tsx
-  {/* ✅ Good: Descriptive, contextual label */}
-  <IconMenuButton
-    icon={<MoreVertIcon />}
-    buttonComponentProps={{ 'aria-label': `Actions for ${item.name}` }}
-    items={items}
-  />
+// Soft - subtle background
+<IconMenuButton icon={<MoreVertIcon />} variant="soft" color="primary" />
 
-  {/* ❌ Bad: No accessible name */}
-  <IconMenuButton icon={<MoreVertIcon />} items={items} />
-  ```
+// Outlined - bordered
+<IconMenuButton icon={<MoreVertIcon />} variant="outlined" color="neutral" />
+```
 
-- **Use familiar icons.** Stick to universally recognized menu icons like MoreVert or MoreHoriz. Unfamiliar icons confuse users about what will happen when they click.
+### Size Options
 
-  ```tsx
-  {/* ✅ Good: Standard kebab/meatball icons */}
-  <IconMenuButton icon={<MoreVertIcon />} />
-  <IconMenuButton icon={<MoreHorizIcon />} />
+```tsx
+// Small - for compact lists
+<IconMenuButton icon={<MoreVertIcon />} size="sm" items={items} />
 
-  {/* ❌ Avoid: Non-standard icon for a menu trigger */}
-  <IconMenuButton icon={<StarIcon />} />
-  ```
+// Medium (default)
+<IconMenuButton icon={<MoreVertIcon />} size="md" items={items} />
 
-- **Prefer `variant="plain"` in data-dense contexts.** In tables, lists, and cards, a plain icon button reduces visual noise while remaining discoverable on hover.
+// Large - for prominent actions
+<IconMenuButton icon={<MoreVertIcon />} size="lg" items={items} />
+```
 
-- **Position menus to avoid overflow.** Use `placement="bottom-end"` for buttons near the right edge of a container, and `placement="bottom-start"` for buttons near the left edge.
+### Accessibility Props
 
-- **Do not hide primary actions.** Important actions like "Save" or "Submit" should always be visible as standalone buttons. Reserve IconMenuButton for secondary or contextual actions.
+```tsx
+// Always provide aria-label for accessibility
+<IconMenuButton
+  icon={<MoreVertIcon />}
+  buttonComponentProps={{
+    'aria-label': 'More actions for item',
+  }}
+  items={items}
+/>
+
+// Include context in aria-label
+<IconMenuButton
+  icon={<MoreVertIcon />}
+  buttonComponentProps={{
+    'aria-label': `Actions for ${item.name}`,
+  }}
+  items={items}
+/>
+```
 
 ## Accessibility
 
-- **ARIA requirements**: Always pass `'aria-label'` through `buttonComponentProps`. The button automatically receives `aria-haspopup="true"` and `aria-expanded` reflecting the menu state.
-- **Keyboard navigation**: Enter or Space opens the menu. Arrow Down/Up moves between items. Escape closes the menu and returns focus to the icon button. Tab closes the menu and advances focus.
-- **Focus visibility**: The icon button displays a visible focus ring when focused via keyboard, and menu items have clear focus indicators for keyboard navigation.
-- **Touch targets**: Ensure the button size is at least 44x44 CSS pixels for comfortable touch interaction. Avoid using `size="sm"` in mobile-primary interfaces unless the surrounding layout provides adequate spacing.
+IconMenuButton requires additional accessibility consideration since it lacks visible text:
+
+### ARIA Requirements
+
+```tsx
+// ✅ Required: Always provide aria-label
+<IconMenuButton
+  icon={<MoreVertIcon />}
+  buttonComponentProps={{ 'aria-label': 'More actions' }}
+  items={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 element
+
+### Screen Reader Announcements
+
+```tsx
+// Button announces: "More actions, menu button"
+<IconMenuButton
+  icon={<MoreVertIcon />}
+  buttonComponentProps={{ 'aria-label': 'More actions' }}
+/>
+
+// Contextual label: "Actions for Product XYZ, menu button"
+<IconMenuButton
+  icon={<MoreVertIcon />}
+  buttonComponentProps={{ 'aria-label': `Actions for ${product.name}` }}
+/>
+```
+
+### Focus Visibility
+
+- Clear focus ring on button when focused
+- Menu items have visible focus indicators
+- Focus is properly managed between button and menu
+
+## Best Practices
+
+### ✅ Do
+
+1. **Always include `aria-label`**: Essential for screen readers
+
+```tsx
+// ✅ Good: Descriptive aria-label
+<IconMenuButton
+  icon={<MoreVertIcon />}
+  buttonComponentProps={{ 'aria-label': 'File actions' }}
+  items={items}
+/>
+```
+
+2. **Use familiar icons**: Stick to recognizable patterns
+
+```tsx
+// ✅ Good: Widely recognized menu icons
+<IconMenuButton icon={<MoreVertIcon />} />  // Vertical dots
+<IconMenuButton icon={<MoreHorizIcon />} /> // Horizontal dots
+```
+
+3. **Use plain variant in lists/tables**: Reduces visual clutter
+
+```tsx
+// ✅ Good: Subtle appearance in data rows
+<IconMenuButton
+  icon={<MoreVertIcon />}
+  variant="plain"
+  color="neutral"
+  size="sm"
+/>
+```
+
+4. **Position menus appropriately**: Prevent overflow issues
+
+```tsx
+// ✅ Good: Right-aligned menu for right-side buttons
+<IconMenuButton
+  icon={<MoreVertIcon />}
+  placement="bottom-end"
+/>
+```
+
+### ❌ Don't
+
+1. **Don't skip aria-label**: Makes button inaccessible
+
+```tsx
+// ❌ Bad: No accessible name
+<IconMenuButton icon={<MoreVertIcon />} items={items} />
+
+// ✅ Good: Has aria-label
+<IconMenuButton
+  icon={<MoreVertIcon />}
+  buttonComponentProps={{ 'aria-label': 'Actions' }}
+  items={items}
+/>
+```
+
+2. **Don't use unfamiliar icons**: Users may not recognize them
+
+```tsx
+// ❌ Bad: Unclear what icon means
+<IconMenuButton icon={<StarIcon />} items={items} />
+
+// ✅ Good: Standard menu icon
+<IconMenuButton icon={<MoreVertIcon />} items={items} />
+```
+
+3. **Don't use for primary actions**: Important actions should be visible
+
+```tsx
+// ❌ Bad: Hiding primary action in icon menu
+<IconMenuButton
+  icon={<MoreVertIcon />}
+  items={[{ text: 'Submit Form', onClick: handleSubmit }]}
+/>
+
+// ✅ Good: Primary action is visible
+<Button onClick={handleSubmit}>Submit</Button>
+```
+
+4. **Don't use too-small sizes**: Must be easily clickable
+
+## Performance Considerations
+
+### Memoize Items Array
+
+```tsx
+const rowActions = useMemo(
+  () => [
+    { text: 'Edit', onClick: () => onEdit(row.id) },
+    { text: 'Delete', onClick: () => onDelete(row.id) },
+  ],
+  [row.id, onEdit, onDelete]
+);
+
+<IconMenuButton icon={<MoreVertIcon />} items={rowActions} />
+```
+
+### Memoize in List Renders
+
+When rendering many IconMenuButtons in lists/tables:
+
+```tsx
+const ActionMenu = memo(({ item, onAction }) => {
+  const items = useMemo(
+    () => [
+      { text: 'Edit', onClick: () => onAction('edit', item.id) },
+      { text: 'Delete', onClick: () => onAction('delete', item.id) },
+    ],
+    [item.id, onAction]
+  );
+
+  return (
+    <IconMenuButton
+      icon={<MoreVertIcon />}
+      variant="plain"
+      color="neutral"
+      size="sm"
+      buttonComponentProps={{ 'aria-label': `Actions for ${item.name}` }}
+      items={items}
+    />
+  );
+});
+```
+
+### Avoid Inline Object Creation
+
+```tsx
+// ❌ Bad: Creates new object every render
+<IconMenuButton
+  buttonComponentProps={{ 'aria-label': 'Actions' }}
+/>
+
+// ✅ Good: Stable props object
+const buttonProps = useMemo(
+  () => ({ 'aria-label': `Actions for ${item.name}` }),
+  [item.name]
+);
+<IconMenuButton buttonComponentProps={buttonProps} />
+```
+
+IconMenuButton provides a compact way to offer contextual actions in space-constrained interfaces. Always include proper accessibility attributes and use familiar icons to ensure all users can understand and interact with the menu trigger effectively.