✨ feat(context-menu): add support for item descriptions and icon alignment

- Introduced a `desc` property for menu items to display secondary descriptions below the label.
- Added `iconAlign` option to control the vertical alignment of icons when descriptions are present, allowing for 'center' and 'start' alignment.
- Updated rendering logic in `ContextMenu` and `DropdownMenu` to accommodate new features.
- Enhanced documentation to reflect these changes and provide usage examples.

This enhancement improves the contextual information available in menus, enhancing user experience.

Signed-off-by: Innei <tukon479@gmail.com>

Author: Innei

package.json

@@ -106,7 +106,6 @@
   },
   "lint-staged": {
     "*.md": [
-      "remark --quiet --output --",
       "prettier --write --no-error-on-unmatched-pattern"
     ],
     "*.json": [

src/ContextMenu/ContextMenuHost.tsx

@@ -49,8 +49,12 @@ export const ContextMenuHost = memo(() => {
   }, []);
 
   const menuItems = useMemo(
-    () => renderContextMenuItems(state.items, [], { iconSpaceMode: state.iconSpaceMode }),
-    [state.items, state.iconSpaceMode],
+    () =>
+      renderContextMenuItems(state.items, [], {
+        iconAlign: state.iconAlign,
+        iconSpaceMode: state.iconSpaceMode,
+      }),
+    [state.items, state.iconAlign, state.iconSpaceMode],
   );
   const portalContainer = usePortalContainer(CONTEXT_MENU_CONTAINER_ATTR);
 

src/ContextMenu/demos/desc.tsx

@@ -0,0 +1,64 @@
+import {
+  Block,
+  ContextMenuTrigger,
+  type GenericItemType,
+  Icon,
+  showContextMenu,
+  Text,
+} from '@lobehub/ui';
+import { GithubIcon, GlobeIcon, PencilIcon, UploadIcon } from 'lucide-react';
+import { type MouseEvent } from 'react';
+import { useCallback, useMemo } from 'react';
+
+export default () => {
+  const items = useMemo<GenericItemType[]>(
+    () => [
+      {
+        desc: 'Import from a direct SKILL.md link',
+        icon: <Icon icon={GlobeIcon} />,
+        key: 'import-url',
+        label: 'Import from URL',
+      },
+      {
+        desc: 'Import from a public GitHub repository',
+        icon: <Icon icon={GithubIcon} />,
+        key: 'import-github',
+        label: 'Import from GitHub',
+      },
+      {
+        desc: 'Upload a local .zip or .skill file',
+        icon: <Icon icon={UploadIcon} />,
+        key: 'upload-zip',
+        label: 'Upload Zip',
+      },
+      {
+        desc: 'Manually configure a custom MCP server',
+        icon: <Icon icon={PencilIcon} />,
+        key: 'add-custom',
+        label: 'Add Custom MCP Skill',
+      },
+    ],
+    [],
+  );
+
+  const handleContextMenu = useCallback(
+    (event: MouseEvent<HTMLElement>) => {
+      event.preventDefault();
+      showContextMenu(items, { iconAlign: 'start' });
+    },
+    [items],
+  );
+
+  return (
+    <ContextMenuTrigger onContextMenu={handleContextMenu}>
+      <Block direction="vertical" gap={8} padding={16}>
+        <Text strong as={'p'}>
+          Right click this panel
+        </Text>
+        <Text as={'p'} type="secondary">
+          Each item has a description below the label
+        </Text>
+      </Block>
+    </ContextMenuTrigger>
+  );
+};

src/ContextMenu/index.md

@@ -21,6 +21,12 @@ description: ContextMenu provides an imperative API to open a menu at the last p
 
 <code src="./demos/switch.tsx" center></code>
 
+## Description
+
+Items can display a secondary description below the label using the `desc` property.
+
+<code src="./demos/desc.tsx" center></code>
+
 ## Empty Submenu
 
 <code src="./demos/emptySubmenu.tsx" center></code>
@@ -49,6 +55,7 @@ Control how icon spacing is reserved across menu items. In `global` mode (defaul
 
 | Property      | Description                                                                                    | Type                  | Default    |
 | ------------- | ---------------------------------------------------------------------------------------------- | --------------------- | ---------- |
+| iconAlign     | Icon vertical alignment when items have `desc`. Only effective with descriptions.              | `'center' \| 'start'` | `'center'` |
 | iconSpaceMode | Icon space reservation: `global` reserves for all items, `group` reserves per group with icons | `'global' \| 'group'` | `'global'` |
 
 ### ContextMenuHost

src/ContextMenu/renderItems.tsx

@@ -35,7 +35,7 @@ import {
   type ContextMenuSwitchItem,
 } from './type';
 
-export type { IconSpaceMode } from '@/Menu';
+export type { IconAlign, IconSpaceMode } from '@/Menu';
 
 const EmptyMenuItem = memo(() => {
   const { t } = useTranslation(common);
@@ -117,22 +117,36 @@ const renderItemContent = (
   iconNode?: ReactNode,
 ) => {
   const label = getItemLabel(item);
+  const desc = 'desc' in item ? item.desc : undefined;
   const extra = 'extra' in item ? item.extra : undefined;
   const indicatorOnRight = options?.indicatorOnRight;
+  const alignStart = Boolean(desc) && options?.iconAlign === 'start';
   const hasCustomIcon = iconNode !== undefined && !indicatorOnRight;
   const hasIcon = hasCustomIcon ? Boolean(iconNode) : Boolean(item.icon);
   const shouldRenderIcon = hasCustomIcon
     ? Boolean(options?.reserveIconSpace || iconNode)
     : Boolean(hasIcon || options?.reserveIconSpace);
 
+  const labelNode = desc ? (
+    <div className={styles.labelGroup}>
+      <span className={styles.label}>{label}</span>
+      <span className={styles.desc}>{desc}</span>
+    </div>
+  ) : (
+    <span className={styles.label}>{label}</span>
+  );
+
   return (
-    <div className={styles.itemContent}>
+    <div className={cx(styles.itemContent, alignStart && styles.itemContentAlignStart)}>
       {shouldRenderIcon ? (
-        <span aria-hidden={!hasIcon} className={styles.icon}>
+        <span
+          aria-hidden={!hasIcon}
+          className={cx(styles.icon, alignStart && styles.iconAlignStart)}
+        >
           {hasCustomIcon ? iconNode : hasIcon ? renderIcon(item.icon, 'small') : null}
         </span>
       ) : null}
-      <span className={styles.label}>{label}</span>
+      {labelNode}
       {extra ? <span className={styles.extra}>{extra}</span> : null}
       {indicatorOnRight && iconNode ? iconNode : null}
       {options?.submenu ? (
@@ -165,6 +179,7 @@ export const renderContextMenuItems = (
   keyPath: string[] = [],
   options?: RenderOptions,
 ): ReactNode[] => {
+  const iconAlign = options?.iconAlign;
   const iconSpaceMode = options?.iconSpaceMode ?? 'global';
   const reserveIconSpace =
     options?.reserveIconSpace ?? hasAnyIcon(items, iconSpaceMode === 'global');
@@ -199,7 +214,11 @@ export const renderContextMenuItems = (
           label={labelText}
           onCheckedChange={(checked) => checkboxItem.onCheckedChange?.(checked)}
         >
-          {renderItemContent(checkboxItem, { indicatorOnRight, reserveIconSpace }, indicator)}
+          {renderItemContent(
+            checkboxItem,
+            { iconAlign, indicatorOnRight, reserveIconSpace },
+            indicator,
+          )}
         </ContextMenu.CheckboxItem>
       );
     }
@@ -221,7 +240,7 @@ export const renderContextMenuItems = (
           label={labelText}
           onCheckedChange={switchItem.onCheckedChange}
         >
-          {renderItemContent(switchItem, { reserveIconSpace })}
+          {renderItemContent(switchItem, { iconAlign, reserveIconSpace })}
         </ContextMenuSwitchItemInternal>
       );
     }
@@ -248,6 +267,7 @@ export const renderContextMenuItems = (
           ) : null}
           {group.children
             ? renderContextMenuItems(group.children, nextKeyPath, {
+                iconAlign,
                 iconSpaceMode,
                 indicatorOnRight: groupIndicatorOnRight,
                 reserveIconSpace: groupReserveIconSpace,
@@ -274,6 +294,7 @@ export const renderContextMenuItems = (
             label={labelText}
           >
             {renderItemContent(submenu, {
+              iconAlign,
               reserveIconSpace,
               submenu: true,
             })}
@@ -288,7 +309,10 @@ export const renderContextMenuItems = (
             >
               <ContextMenu.Popup className={styles.popup}>
                 {submenu.children && submenu.children.length > 0 ? (
-                  renderContextMenuItems(submenu.children, nextKeyPath, { iconSpaceMode })
+                  renderContextMenuItems(submenu.children, nextKeyPath, {
+                    iconAlign,
+                    iconSpaceMode,
+                  })
                 ) : (
                   <EmptyMenuItem />
                 )}
@@ -313,7 +337,7 @@ export const renderContextMenuItems = (
         label={labelText}
         onClick={(event) => invokeItemClick(menuItem, nextKeyPath, event)}
       >
-        {renderItemContent(menuItem, { reserveIconSpace })}
+        {renderItemContent(menuItem, { iconAlign, reserveIconSpace })}
       </ContextMenu.Item>
     );
   });

src/ContextMenu/store.ts

@@ -1,10 +1,13 @@
 import type { VirtualElement } from '@floating-ui/react';
 
+import type { IconAlign } from '@/Menu';
+
 import type { IconSpaceMode } from './renderItems';
 import type { ContextMenuItem } from './type';
 
 export type ContextMenuState = {
   anchor: VirtualElement | null;
+  iconAlign?: IconAlign;
   iconSpaceMode: IconSpaceMode;
   items: ContextMenuItem[];
   open: boolean;
@@ -69,6 +72,7 @@ export const setContextMenuState = (next: Partial<ContextMenuState>) => {
 };
 
 export interface ShowContextMenuOptions {
+  iconAlign?: IconAlign;
   iconSpaceMode?: IconSpaceMode;
 }
 
@@ -80,6 +84,7 @@ export const showContextMenu = (items: ContextMenuItem[], options?: ShowContextM
 
   setContextMenuState({
     anchor: createVirtualElement(point),
+    iconAlign: options?.iconAlign,
     iconSpaceMode: options?.iconSpaceMode ?? 'global',
     items,
     open: true,

src/DropdownMenu/DropdownMenu.tsx

@@ -19,6 +19,7 @@ const DropdownMenu = memo<DropdownMenuProps>(
   ({
     children,
     defaultOpen,
+    iconAlign,
     iconSpaceMode,
     items,
     nativeButton,
@@ -57,12 +58,15 @@ const DropdownMenu = memo<DropdownMenuProps>(
     const menuItems = useMemo(() => {
       if (isOpen) {
         const resolvedItems = typeof items === 'function' ? items() : items;
-        const renderedItems = renderDropdownMenuItems(resolvedItems, [], { iconSpaceMode });
+        const renderedItems = renderDropdownMenuItems(resolvedItems, [], {
+          iconAlign,
+          iconSpaceMode,
+        });
         menuItemsRef.current = renderedItems;
         return renderedItems;
       }
       return menuItemsRef.current;
-    }, [isOpen, items, iconSpaceMode]);
+    }, [isOpen, items, iconAlign, iconSpaceMode]);
     const handleOpenChangeComplete = useCallback(
       (nextOpen: boolean) => {
         onOpenChangeComplete?.(nextOpen);

src/DropdownMenu/atoms.tsx

@@ -264,6 +264,17 @@ export const DropdownMenuItemIcon = ({ className, ...rest }: DropdownMenuItemIco
 
 DropdownMenuItemIcon.displayName = 'DropdownMenuItemIcon';
 
+export type DropdownMenuItemLabelGroupProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const DropdownMenuItemLabelGroup = ({
+  className,
+  ...rest
+}: DropdownMenuItemLabelGroupProps) => {
+  return <div {...rest} className={cx(styles.labelGroup, className)} />;
+};
+
+DropdownMenuItemLabelGroup.displayName = 'DropdownMenuItemLabelGroup';
+
 export type DropdownMenuItemLabelProps = React.HTMLAttributes<HTMLSpanElement>;
 
 export const DropdownMenuItemLabel = ({ className, ...rest }: DropdownMenuItemLabelProps) => {
@@ -272,6 +283,14 @@ export const DropdownMenuItemLabel = ({ className, ...rest }: DropdownMenuItemLa
 
 DropdownMenuItemLabel.displayName = 'DropdownMenuItemLabel';
 
+export type DropdownMenuItemDescProps = React.HTMLAttributes<HTMLSpanElement>;
+
+export const DropdownMenuItemDesc = ({ className, ...rest }: DropdownMenuItemDescProps) => {
+  return <span {...rest} className={cx(styles.desc, className)} />;
+};
+
+DropdownMenuItemDesc.displayName = 'DropdownMenuItemDesc';
+
 export type DropdownMenuItemExtraProps = React.HTMLAttributes<HTMLSpanElement>;
 
 export const DropdownMenuItemExtra = ({ className, ...rest }: DropdownMenuItemExtraProps) => {

src/DropdownMenu/demos/desc.tsx

@@ -0,0 +1,77 @@
+import { DropdownMenu, type DropdownMenuProps, Icon } from '@lobehub/ui';
+import { createStaticStyles } from 'antd-style';
+import { GithubIcon, GlobeIcon, MoreHorizontal, PencilIcon, UploadIcon } from 'lucide-react';
+
+const styles = createStaticStyles(({ css, cssVar }) => ({
+  trigger: css`
+    cursor: pointer;
+
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+
+    width: 44px;
+    height: 44px;
+    padding: 0;
+    border: 1px solid ${cssVar.colorBorderSecondary};
+    border-radius: 12px;
+
+    color: ${cssVar.colorTextSecondary};
+
+    background: ${cssVar.colorBgElevated};
+
+    transition: all 150ms ${cssVar.motionEaseOut};
+
+    &:hover {
+      color: ${cssVar.colorText};
+      background: ${cssVar.colorFillSecondary};
+    }
+
+    &:active {
+      transform: translateY(1px);
+    }
+
+    &[data-state='open'],
+    &[aria-expanded='true'] {
+      color: ${cssVar.colorText};
+      background: ${cssVar.colorFillTertiary};
+    }
+  `,
+}));
+
+const items: Exclude<DropdownMenuProps['items'], () => unknown> = [
+  {
+    desc: 'Import from a direct SKILL.md link',
+    icon: <Icon icon={GlobeIcon} />,
+    key: 'import-url',
+    label: 'Import from URL',
+  },
+  {
+    desc: 'Import from a public GitHub repository',
+    icon: <Icon icon={GithubIcon} />,
+    key: 'import-github',
+    label: 'Import from GitHub',
+  },
+  {
+    desc: 'Upload a local .zip or .skill file',
+    icon: <Icon icon={UploadIcon} />,
+    key: 'upload-zip',
+    label: 'Upload Zip',
+  },
+  {
+    desc: 'Manually configure a custom MCP server',
+    icon: <Icon icon={PencilIcon} />,
+    key: 'add-custom',
+    label: 'Add Custom MCP Skill',
+  },
+];
+
+export default () => {
+  return (
+    <DropdownMenu nativeButton iconAlign="start" items={items}>
+      <button aria-label="Open menu" className={styles.trigger} type="button">
+        <MoreHorizontal />
+      </button>
+    </DropdownMenu>
+  );
+};