{
  "id": "menu",
  "type": "components",
  "status": "published",
  "name": {
    "zh": "菜单",
    "en": "Menu"
  },
  "aliases": [
    "菜单",
    "下拉菜单",
    "右键菜单",
    "上下文菜单",
    "操作菜单",
    "更多操作",
    "三个点点出来的菜单"
  ],
  "category": [
    "Navigation",
    "Overlay"
  ],
  "description": {
    "zh": "点击或右键触发的临时操作列表浮层：平铺或分组的命令项，选中即执行并关闭。 用于收纳非高频操作（更多、设置、删除），通常以「⋯」按钮或右键唤起。",
    "en": "A temporary overlay listing actions, opened by click or right-click: flat or grouped command items that execute and close on selection. It houses infrequent actions (more, settings, delete), usually behind a \"⋯\" button or a context click."
  },
  "use_when": [
    {
      "zh": "收纳低频操作，避免界面堆满按钮",
      "en": "Stash infrequent actions instead of crowding buttons"
    },
    {
      "zh": "右键唤起的上下文操作（文件、画布元素）",
      "en": "Context actions on right-click (files, canvas items)"
    },
    {
      "zh": "顶部导航的站点栏目入口",
      "en": "Site section entry points in a top nav"
    }
  ],
  "avoid_when": [
    {
      "zh": "高频主操作（直接露出按钮）",
      "en": "Frequent primary actions — expose real buttons"
    },
    {
      "zh": "层级很深的树（改用侧边栏或命令面板）",
      "en": "Very deep trees — use a sidebar or command palette"
    },
    {
      "zh": "破坏性操作需二次确认，不能一触即发",
      "en": "Destructive items need confirmation, not one-click firing"
    }
  ],
  "tags": [
    "navigation",
    "overlay",
    "actions",
    "context"
  ],
  "api": [
    "role=\"menu\"",
    "role=\"menuitem\""
  ],
  "disambiguation": {
    "zh": "菜单（Menu）是命令列表，点选即执行；导航（Navbar/Sidebar）是页面目的地；下拉（Dropdown）是「按钮 + 菜单」的组合控件。",
    "en": "A menu lists commands that run on click. Navigation (Navbar/Sidebar) lists destinations. A dropdown is the combined control — a button plus a menu."
  },
  "confusable": [
    {
      "id": "dropdown",
      "note": {
        "zh": "Dropdown 是按钮+菜单的完整控件，Menu 只是弹出的命令列表部分。",
        "en": "Dropdown is the full button+menu control; Menu is only the popup command list."
      }
    },
    {
      "id": "navbar",
      "note": {
        "zh": "Navbar 跳转页面目的地，Menu 执行即时命令。",
        "en": "Navbar jumps to destinations; Menu runs immediate commands."
      }
    },
    {
      "id": "select",
      "note": {
        "zh": "Select 选中一个值回填表单，Menu 触发一个动作。",
        "en": "Select picks a value for a form; Menu triggers an action."
      }
    }
  ],
  "variants": [
    {
      "id": "dropdown",
      "name": {
        "zh": "下拉",
        "en": "Dropdown"
      },
      "note": {
        "zh": "点击按钮在下方弹出",
        "en": "Opens below its trigger button"
      }
    },
    {
      "id": "context",
      "name": {
        "zh": "上下文",
        "en": "Context"
      },
      "note": {
        "zh": "右键在指针位置弹出",
        "en": "Opens at the pointer on right-click"
      }
    },
    {
      "id": "grouped",
      "name": {
        "zh": "分组",
        "en": "Grouped"
      },
      "note": {
        "zh": "带分组标题与分隔线",
        "en": "Group labels with separators"
      }
    }
  ],
  "anatomy": [
    "触发器（Trigger）",
    "菜单面板（Panel）",
    "菜单项（Items）",
    "分隔线（Separator）"
  ],
  "applicable_styles": [
    "bento-grid",
    "cyberpunk",
    "organic",
    "minimalism",
    "flat-design",
    "swiss-style",
    "neobrutalism",
    "editorial"
  ],
  "related": [
    {
      "id": "dropdown",
      "relation": "similar_to"
    },
    {
      "id": "navbar",
      "relation": "alternative_to"
    },
    {
      "id": "command-palette",
      "relation": "similar_to"
    },
    {
      "id": "popover",
      "relation": "similar_to"
    }
  ],
  "demo": {
    "component": "menu",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "compare": {
    "group": "primary-navigation",
    "dimensions": {
      "空间占用": {
        "zh": "低，隐藏直至唤起",
        "en": "Low — hidden until invoked"
      },
      "层级容量": {
        "zh": "中，两级以内为宜",
        "en": "Medium — two levels at most"
      },
      "移动端友好": {
        "zh": "中，需加大触达面积",
        "en": "Medium — needs larger touch targets"
      }
    }
  },
  "implementation": {
    "css": [
      "position: absolute",
      "z-index",
      "box-shadow",
      "min-width"
    ],
    "notes": {
      "zh": "以触发器为锚 absolute 定位，默认下方展开，贴近屏幕边缘时翻转。菜单项用 button （role=\"menuitem\"），↑↓ 循环、Enter 执行、Esc 关闭；危险项用红色文字并与常规项分隔。 点击外部关闭：document 监听 pointerdown 判断 target。",
      "en": "Anchor to the trigger with absolute positioning, opening below by default and flipping near screen edges. Items are buttons with role=\"menuitem\"; ↑↓ cycles, Enter executes, Esc closes; destructive items get red text and a separator before them. Close on outside click: listen for pointerdown on document and check the target."
    }
  },
  "sources": [
    {
      "name": "WAI-ARIA Authoring Practices — Menu Button",
      "url": "https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/"
    },
    {
      "name": "Apple HIG — Menus",
      "url": "https://developer.apple.com/design/human-interface-guidelines/menus"
    }
  ],
  "prompts": {
    "basic": {
      "zh": "创建一个菜单（Menu）组件：点击「⋯」按钮弹出操作列表（重命名、复制链接、删除）， 点击项执行并关闭菜单。",
      "en": "Create a Menu component: a \"⋯\" button opens an action list (rename, copy link, delete); selecting an item executes it and closes the menu."
    },
    "design": {
      "zh": "创建 Menu 组件。要求：浮层 min-w 160px、圆角、边框、大阴影；菜单项行高一致、hover 浅色高亮； 分组标题小写灰字；危险项红色文字并用分隔线隔开；展开时触发器保持强调态； 深浅色主题一致。",
      "en": "Create a Menu. Requirements: overlay min-w 160px, rounded, bordered, heavily shadowed; consistent item rows with light hover highlight; small grey group labels; destructive items in red separated by a divider; the trigger keeps an accent state while open; consistent light/dark themes."
    },
    "implementation": {
      "zh": "用 React + Tailwind 实现 Menu：open 受控；容器 relative，面板 absolute top-full mt-1； document pointerdown 监听外部关闭，Esc 关闭；焦点移入面板， ArrowUp/ArrowDown 在 item 间循环（role=\"menuitem\"），Enter 执行并回调 onSelect； 项目数据驱动 {label, danger?, separator?}；入场 scale + fade（时长乘 var(--demo-speed, 1)）。",
      "en": "React + Tailwind Menu: controlled open state; relative wrapper with an absolute top-full mt-1 panel; document pointerdown listener closes on outside click, Esc closes; focus moves into the panel and ArrowUp/ArrowDown cycles items (role=\"menuitem\"), Enter executes via onSelect; items are data-driven {label, danger?, separator?}; enter animation scale + fade (duration scaled by var(--demo-speed, 1))."
    },
    "agent": {
      "zh": "在当前项目中实现菜单（Menu）组件。\n\n先检查现有组件体系与 Design Token，优先复用现有的表面色与阴影变量。\n用途：列表行的「更多」操作与右键上下文。\n要求：\n- 锚定触发器弹出，贴近边缘自动翻转\n- 键盘可用：↑↓ 循环、Enter 执行、Esc 关闭\n- 危险项红色 + 分隔线，触发二次确认的钩子\n- 点击外部关闭，深浅色主题一致\n- 不新增依赖\n完成后运行现有检查，说明修改文件。",
      "en": "Implement a Menu component in the current project.\n\nInspect the existing component system and design tokens first; reuse existing\nsurface and shadow variables.\nUsage: row \"more\" actions and right-click context.\nRequirements:\n- Anchored to the trigger, flips near screen edges\n- Keyboard: ↑↓ cycling, Enter to execute, Esc to close\n- Destructive items in red with a divider and a confirm hook\n- Closes on outside click; consistent light/dark themes\n- No new dependencies\nRun existing checks when done and list modified files."
    }
  },
  "playground": {
    "task": {
      "zh": "用鼠标与键盘选择动作，体验重命名、删除确认与撤销。",
      "en": "Try pointer and keyboard actions, rename, confirm deletion and undo."
    },
    "checks": [
      {
        "zh": "所有菜单项包括危险项都应可用键盘到达。",
        "en": "Every action, including destructive ones, must be keyboard reachable."
      },
      {
        "zh": "点外部与 Esc 都能关闭，焦点不应丢失。",
        "en": "Outside click and Escape should dismiss without losing focus."
      }
    ]
  }
}