@orbit-work/ui 0.1.0

package/src/components/primitives/Menu/index.tsx

@@ -0,0 +1,922 @@
+"use client"
+
+import { type VariantProps, cva } from "class-variance-authority"
+import {
+  type ReactElement,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactNode,
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react"
+import { createPortal } from "react-dom" // ui-imports-guard-disable-line
+import { cn } from "../../../lib/utils"
+import { Check } from "../../composite/Icons"
+import { Button } from "../Button"
+import { EmptyState } from "../EmptyState"
+import { Field } from "../Field"
+import { KeycapCombo } from "../Keycap"
+
+/* ------------------------------------------------------------------ *
+ * 条目模型
+ * ------------------------------------------------------------------ */
+
+export type MenuItem = {
+  key: string
+  label: ReactNode
+  icon?: ReactNode
+  /** 快捷键列：mono 键帽（读数规范）。字符串按 `+` 拆成组合键。 */
+  shortcut?: string | string[]
+  /** 行尾次要文字（非快捷键）。同时给了 shortcut 时以 shortcut 为准。 */
+  hint?: ReactNode
+  /** hint 走读数档：mono ＋ tabular-nums（§7 读数口径，版本号/计数这类数字用）。 */
+  hintMono?: boolean
+  /**
+   * 行尾交互控件（开关、分段器…）。给了 control 的行渲染成 `<div role="menuitem">` 外壳
+   * ＋ 标签区，控件本身可聚焦 —— 不再是 button 套 button（HTML 不允许，浏览器会把内层
+   * 拆出去，键盘与读屏都会错位）。控件区自己吃掉点击，不会顺带触发整行的 onSelect。
+   * 行 `disabled` 只禁行本身（aria-disabled、不进方向键/Tab 序列），控件要禁用得自己传 disabled。
+   */
+  control?: ReactNode
+  /** 名称下方的说明行（行高自适应，不再是 32 定高）。 */
+  description?: string
+  /** 勾选态：行尾打勾（暗档 hover-pop 与 current-bg 同值，选中靠勾区分）。 */
+  selected?: boolean
+  /** 危险动作：error 色 + error-tint hover。 */
+  danger?: boolean
+  disabled?: boolean
+  /** searchable 过滤用文本，label 非字符串时必填。 */
+  searchText?: string
+}
+
+/** 分隔线。旧 Dropdown 的 `{ key: "---" }` 形态同样识别。 */
+export type MenuSeparatorEntry = { type: "separator"; key?: string }
+/** 分组标题（眉标档：CAPS + tracking，不可聚焦）。 */
+export type MenuGroupEntry = { type: "group"; key?: string; label: ReactNode }
+
+export type MenuEntry = MenuItem | MenuSeparatorEntry | MenuGroupEntry
+
+/** 分隔项常量。导航列的分隔项是 `NAV_MENU_DIVIDER`（composite/NavMenu）。 */
+export const MENU_SEPARATOR: MenuSeparatorEntry = { type: "separator" }
+
+/** 旧 Dropdown 分隔项的 key 约定，兼容期继续识别。 */
+const LEGACY_DIVIDER_KEY = "---"
+
+function isSeparator(entry: MenuEntry): entry is MenuSeparatorEntry {
+  return ("type" in entry && entry.type === "separator") || (!("type" in entry) && entry.key === LEGACY_DIVIDER_KEY)
+}
+function isGroup(entry: MenuEntry): entry is MenuGroupEntry {
+  return "type" in entry && entry.type === "group"
+}
+function isItem(entry: MenuEntry): entry is MenuItem {
+  return !isSeparator(entry) && !isGroup(entry)
+}
+function itemText(item: MenuItem): string {
+  return item.searchText ?? (typeof item.label === "string" ? item.label : "")
+}
+function shortcutKeys(shortcut: string | string[]): string[] {
+  return (Array.isArray(shortcut) ? shortcut : shortcut.split("+")).map((key) => key.trim()).filter(Boolean)
+}
+
+/** 槽内可聚焦件（Tab 停靠点）：行尾控件区、bare 头部、banner、footer 里的按钮/输入等。行本身 tabIndex=-1，不会被这条选中。 */
+const FOCUSABLE = ["button", "[href]", "input", "select", "textarea", '[tabindex]:not([tabindex="-1"])'].join(", ")
+/** 取一个槽里的 Tab 停靠点（DOM 顺序）。roving tabindex 的控件（分段器）内部只有一个 tabIndex=0 的段，其余 -1 不算。 */
+function focusableStops(root: Element | null | undefined): HTMLElement[] {
+  if (!root) return []
+  return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE)).filter(
+    (node) => !(node.tabIndex < 0 || node.hasAttribute("disabled") || node.getAttribute("aria-hidden") === "true"),
+  )
+}
+
+/* ------------------------------------------------------------------ *
+ * 行样式
+ * ------------------------------------------------------------------ */
+
+const menuItemVariants = cva(
+  [
+    "flex items-center gap-2 w-full px-2 text-left text-ow-fs-ui font-normal",
+    "transition-[background-color,color] duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)]",
+    "[border-radius:var(--ow-radius-control)] ow-focus-ring",
+  ].join(" "),
+  {
+    variants: {
+      danger: {
+        true: "text-[color:var(--ow-error)]",
+        false: "text-[color:var(--ow-text)]",
+      },
+      selected: {
+        true: "bg-[var(--ow-selected-bg)]",
+        false: "",
+      },
+      hovered: {
+        true: "",
+        false: "",
+      },
+      disabled: {
+        true: "cursor-not-allowed text-[color:var(--ow-disabled-text)]",
+        false: "cursor-pointer",
+      },
+      hasDescription: {
+        // 行高 32 是常态；带说明行时放开为自适应两行。
+        true: "h-auto py-2 items-start",
+        false: "h-8",
+      },
+    },
+    compoundVariants: [
+      // 坐在 --ow-popover-bg 上的行一律 -pop 档（§5 交互底色相对所在表面递进）。
+      {
+        hovered: true,
+        selected: false,
+        disabled: false,
+        danger: false,
+        className: "bg-[var(--ow-hover-pop)] active:bg-[var(--ow-press-pop)]",
+      },
+      {
+        hovered: true,
+        selected: false,
+        disabled: false,
+        danger: true,
+        className: "bg-[var(--ow-error-tint)] active:bg-[var(--ow-error-tint-hover)]",
+      },
+    ],
+    defaultVariants: {
+      danger: false,
+      selected: false,
+      hovered: false,
+      disabled: false,
+      hasDescription: false,
+    },
+  },
+)
+
+export type MenuItemVariants = VariantProps<typeof menuItemVariants>
+
+/* ------------------------------------------------------------------ *
+ * MenuSurface — 菜单面
+ * ------------------------------------------------------------------ */
+
+export type MenuSurfaceProps = {
+  items?: MenuEntry[]
+  /** 自定义内容（域内选择器自渲染条目时用）。给了 children 时默认不加 menu 语义。 */
+  children?: ReactNode
+  /** 自定义内容尺寸可能变化时改变它，触发 portal 重新测量。 */
+  contentKey?: string | number
+  onSelect?: (key: string) => void
+  /** 高亮某项但不画勾（区别于 selected）。 */
+  activeKey?: string | null
+  /** 鼠标划过非分隔、非禁用条目时回调。 */
+  onItemHover?: (key: string) => void
+  /** 面宽 px（默认 200）。 */
+  width?: number
+  /** 条目上方的眉标行。 */
+  header?: ReactNode
+  /**
+   * header 原样渲染：不套眉标排版（CAPS / tracking / --ow-eyebrow），并以 `role="none"`
+   * 包裹，让读屏把里面的非条目内容（头像块、账号名）当普通内容读，而不是当菜单项跳过。
+   * 里面的按钮（复制 ID 这类）是面内 Tab 停靠点，排在条目之前。
+   */
+  headerBare?: boolean
+  /**
+   * header 与条目之间的整块自定义内容（套餐井这类）。`role="none"` 包裹，同上；
+   * 里面的按钮（升级 / 充值）是面内 Tab 停靠点，排在 header 之后、条目之前。
+   */
+  banner?: ReactNode
+  /** 条目下方的固定区（上分隔线）。 */
+  footer?: ReactNode
+  /** 内嵌搜索字段。 */
+  searchable?: boolean
+  searchPlaceholder?: string
+  searchValue?: string
+  onSearchChange?: (value: string) => void
+  /** 过滤无结果时的一句话（渲染进 `EmptyState` 紧凑档：信标母题 ＋ 一句 text-2）。 */
+  empty?: ReactNode
+  /**
+   * Portal 模式 —— 渲染进 document.body 并 fixed 定位，自动避开视口边界。
+   * 传锚点 ref，或 `true` 表示以父元素为锚。滚动容器会裁掉 absolute 弹层，
+   * 而裁剪不是抬 z-index 能解决的，所以行内菜单一律走这条路。
+   */
+  portal?: boolean | React.RefObject<HTMLElement | null>
+  /** 非 portal 模式下溢出视口时自动微调位移（默认关）。 */
+  autoAdjust?: boolean
+  /** portal 模式的横向对齐：`start` 贴锚点左缘（默认）· `end` 贴右缘（行末「…」用）。 */
+  align?: "start" | "end"
+  /**
+   * 语义档：`menu` 给容器 role="menu"、条目 role="menuitem(checkbox)"；
+   * `none` 只当装饰容器。默认 items 模式为 menu，children 模式为 none。
+   */
+  role?: "menu" | "none"
+  /**
+   * 打开后把焦点收进面：`true`＝搜索框优先，否则第一条可用项（键盘打开时用，行上立刻有
+   * focus-visible 环可循）；`"surface"`＝只把焦点落在面本体（tabIndex=-1 的容器）——
+   * 指针打开时用：方向键/Esc 照常可用，但第一行不画键盘环（R3 · 2026-09-04，Terry
+   * 意见 1「选中状态的焦点环」：指针开面时首行那圈环是 Storybook 里最扎眼的一处）。
+   */
+  autoFocus?: boolean | "surface"
+  /** Esc / Tab 离开时回调，触发器模式据此关闭。 */
+  onClose?: () => void
+  /** 容器可读名（role="menu" 时用）。 */
+  ariaLabel?: string
+  /** 拿到面本体（portal 出去后不在触发器子树里，外点判断要它）。 */
+  surfaceRef?: React.RefObject<HTMLDivElement | null>
+  className?: string
+}
+
+/**
+ * MenuSurface — 下拉菜单的「面」（DS 2.0 patterns · Menu 簇）。
+ *
+ * 立面按 §5：`--ow-popover-bg` 底 + 1px `--ow-border` + `--ow-shadow-pop` +
+ * `var(--ow-z-dropdown)`，圆角 10（`--ow-radius-menu`，§7）；行高 32、行 hover
+ * 走 `-pop` 档；快捷键列 Keycap（mono + tabular-nums）；勾选态打勾；危险项 error 色。
+ * 键盘：↑↓ / Home / End / 首字母跳转 / Enter 选中 / Esc 关闭。
+ *
+ * 这是旧 `primitives/Dropdown` 的规范化继任者，属性向后兼容（Dropdown 现为
+ * @deprecated 别名）。带触发器的完整菜单见同目录 `Menu`。
+ */
+export function MenuSurface({
+  items = [],
+  children,
+  contentKey,
+  onSelect,
+  activeKey,
+  onItemHover,
+  width = 200,
+  header,
+  headerBare = false,
+  banner,
+  footer,
+  searchable = false,
+  searchPlaceholder = "搜索",
+  searchValue,
+  onSearchChange,
+  empty = "暂无结果",
+  portal = false,
+  autoAdjust = false,
+  align = "start",
+  role,
+  autoFocus = false,
+  onClose,
+  ariaLabel,
+  surfaceRef,
+  className = "",
+}: MenuSurfaceProps) {
+  const [hoveredKey, setHoveredKey] = useState<string | null>(null)
+  const [internalSearch, setInternalSearch] = useState("")
+  const ref = useRef<HTMLDivElement | null>(null)
+  const setSurfaceNode = useCallback(
+    (node: HTMLDivElement | null) => {
+      ref.current = node
+      // RefObject.current 在旧版 @types/react 里是 readonly，这里是合法的回写场景。
+      if (surfaceRef) (surfaceRef as React.MutableRefObject<HTMLDivElement | null>).current = node
+    },
+    [surfaceRef],
+  )
+  // 控件行是 div、普通行是 button，两种都要能被程序化聚焦，所以放宽到 HTMLElement。
+  const itemRefs = useRef(new Map<string, HTMLElement>())
+  const typeahead = useRef<{ buffer: string; at: number }>({ buffer: "", at: 0 })
+  const [portalPos, setPortalPos] = useState<{ top: number; left: number } | null>(null)
+  const [adjust, setAdjust] = useState<{ x: number; y: number }>({ x: 0, y: 0 })
+  const adjustRef = useRef(adjust)
+  const baseId = useId()
+  const semantics = role ?? (children ? "none" : "menu")
+  const query = searchValue ?? internalSearch
+  const visibleItems = useMemo(() => {
+    if (!searchable || !query.trim()) return items
+    const needle = query.trim().toLowerCase()
+    return items.filter((entry) => !isItem(entry) || itemText(entry).toLowerCase().includes(needle))
+  }, [items, query, searchable])
+  const navigable = useMemo(
+    () => visibleItems.filter((entry): entry is MenuItem => isItem(entry) && !entry.disabled),
+    [visibleItems],
+  )
+  // 面内是否有带控件的行。
+  const hasControlRow = useMemo(() => navigable.some((item) => !!item.control), [navigable])
+  // Tab 是「面内游走」还是「离面」：有控件行、bare 头部或 banner 时游走（这三种槽里会放复制 ID /
+  // 升级这类按钮，不游走键盘就够不着）；都没有时照旧离面，全库既有消费方零变化。
+  const rovingTab = hasControlRow || (!!header && headerBare) || !!banner
+  // Tab 停靠点（DOM 顺序）：bare 头部里的可聚焦件 → banner 里的 → 行 → 该行控件 → 下一行 → … → footer 里的。
+  const tabStops = useCallback(() => {
+    const surface = ref.current
+    const slot = (part: string) => surface?.querySelector(`:scope > [data-ow-part="${part}"]`)
+    const stops: HTMLElement[] = []
+    if (headerBare) stops.push(...focusableStops(slot("header")))
+    stops.push(...focusableStops(slot("banner")))
+    for (const item of navigable) {
+      const row = itemRefs.current.get(item.key)
+      if (!row) continue
+      stops.push(row)
+      if (item.control) stops.push(...focusableStops(row.querySelector('[data-ow-part="item-control"]')))
+    }
+    stops.push(...focusableStops(slot("footer")))
+    return stops
+  }, [navigable, headerBare])
+
+  const setSearch = (value: string) => {
+    if (searchValue === undefined) setInternalSearch(value)
+    onSearchChange?.(value)
+  }
+
+  const focusItem = useCallback((key: string | null, moveFocus: boolean) => {
+    setHoveredKey(key)
+    if (key && moveFocus) itemRefs.current.get(key)?.focus()
+  }, [])
+
+  // 打开时把焦点收进面：有搜索框先给搜索框，否则给第一条可用项。
+  useEffect(() => {
+    if (!autoFocus) return
+    const frame = requestAnimationFrame(() => {
+      if (autoFocus === "surface") {
+        ref.current?.focus()
+        return
+      }
+      if (searchable) {
+        ref.current?.querySelector<HTMLInputElement>("input")?.focus()
+        setHoveredKey(navigable[0]?.key ?? null)
+        return
+      }
+      const first = navigable[0]?.key
+      if (first) focusItem(first, true)
+      else ref.current?.focus()
+    })
+    return () => cancelAnimationFrame(frame)
+    // 只在打开那一刻收一次焦点，条目变化不该把焦点抢回去。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoFocus])
+
+  const onKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+    const target = event.target as HTMLElement
+    // 焦点落在行尾控件里时，字符键/Enter/空格归控件自己 —— 否则开关上的空格会被菜单
+    // 的首字母跳转吃掉（判据是「事件源在控件区内」，不是 tagName）。
+    const inControl = !!target.closest?.('[data-ow-part="item-control"]')
+    const inSearch = target.tagName === "INPUT" && !inControl
+    if (event.key === "Escape") {
+      event.stopPropagation()
+      onClose?.()
+      return
+    }
+    if (event.key === "Tab") {
+      // 无控件行、无 bare 头部 / banner：Tab 即离面（历史行为，全库其它菜单零变化）。
+      if (!rovingTab) {
+        onClose?.()
+        return
+      }
+      // 否则 Tab 在「头部/banner 按钮 → 行 → 该行控件 → 下一行 → footer」间游走，走到两端才交还焦点。
+      const stops = tabStops()
+      const active = typeof document === "undefined" ? null : (document.activeElement as HTMLElement | null)
+      let index = active ? stops.indexOf(active) : -1
+      if (index < 0 && active) {
+        // 焦点在控件内部更深一层时，取最靠后的包含它的停靠点（控件排在自己行之后）。
+        for (let i = stops.length - 1; i >= 0; i -= 1) {
+          if (stops[i]?.contains(active)) {
+            index = i
+            break
+          }
+        }
+      }
+      const next = index + (event.shiftKey ? -1 : 1)
+      if (index < 0 || next < 0 || next >= stops.length) {
+        onClose?.()
+        return
+      }
+      event.preventDefault()
+      stops[next]?.focus()
+      return
+    }
+    // 控件自己已处理的键（分段器的 ←→ / Home / End 会 preventDefault）面不再接手，
+    // 否则 Home/End 会一边切段、一边把焦点甩到首/末行。
+    if (inControl && event.isDefaultPrevented()) return
+    if (navigable.length === 0) return
+    const current = navigable.findIndex((item) => item.key === hoveredKey)
+    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+      event.preventDefault()
+      const step = event.key === "ArrowDown" ? 1 : -1
+      const next =
+        current < 0 ? (step > 0 ? 0 : navigable.length - 1) : (current + step + navigable.length) % navigable.length
+      const target = navigable[next]
+      if (target) focusItem(target.key, !inSearch)
+      return
+    }
+    if (event.key === "Home" || event.key === "End") {
+      event.preventDefault()
+      const target = navigable[event.key === "Home" ? 0 : navigable.length - 1]
+      if (target) focusItem(target.key, !inSearch)
+      return
+    }
+    if (event.key === "Enter" && hoveredKey && !inSearch && !inControl) {
+      event.preventDefault()
+      onSelect?.(hoveredKey)
+      return
+    }
+    // 控件行是 <div role="menuitem">，没有 button 的原生空格触发，这里补上。只补控件行：
+    // 普通行的空格仍走原生 click，行为不变。
+    if (event.key === " " && hoveredKey && !inSearch && !inControl) {
+      const row = navigable.find((item) => item.key === hoveredKey)
+      if (row?.control) {
+        event.preventDefault()
+        onSelect?.(hoveredKey)
+        return
+      }
+    }
+    // 首字母跳转：搜索框、行尾控件在场时让位给它们。
+    if (!inSearch && !inControl && event.key.length === 1 && !event.metaKey && !event.ctrlKey && !event.altKey) {
+      const now = Date.now()
+      typeahead.current = {
+        buffer: now - typeahead.current.at > 800 ? event.key : typeahead.current.buffer + event.key,
+        at: now,
+      }
+      const needle = typeahead.current.buffer.toLowerCase()
+      const hit = navigable.find((item) => itemText(item).toLowerCase().startsWith(needle))
+      if (hit) {
+        event.preventDefault()
+        focusItem(hit.key, true)
+      }
+    }
+  }
+
+  // 非 portal 模式：溢出视口时整体位移（autoAdjust 显式开启）。
+  useLayoutEffect(() => {
+    if (!autoAdjust || portal) {
+      adjustRef.current = { x: 0, y: 0 }
+      setAdjust((current) => (current.x || current.y ? { x: 0, y: 0 } : current))
+      return
+    }
+    const el = ref.current
+    if (!el) return
+    let raf = 0
+    const measure = () => {
+      cancelAnimationFrame(raf)
+      raf = requestAnimationFrame(() => {
+        const rect = el.getBoundingClientRect()
+        const current = adjustRef.current
+        const base = {
+          left: rect.left - current.x,
+          right: rect.right - current.x,
+          top: rect.top - current.y,
+          bottom: rect.bottom - current.y,
+        }
+        let x = 0
+        let y = 0
+        if (base.right > window.innerWidth - 8) x = window.innerWidth - 8 - base.right
+        if (base.left + x < 8) x = 8 - base.left
+        if (base.bottom > window.innerHeight - 8) y = window.innerHeight - 8 - base.bottom
+        if (base.top + y < 8) y = 8 - base.top
+        if (x !== current.x || y !== current.y) {
+          adjustRef.current = { x, y }
+          setAdjust({ x, y })
+        }
+      })
+    }
+    measure()
+    const resizeObserver = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(measure)
+    resizeObserver?.observe(el)
+    window.addEventListener("resize", measure)
+    window.addEventListener("scroll", measure, true)
+    return () => {
+      cancelAnimationFrame(raf)
+      resizeObserver?.disconnect()
+      window.removeEventListener("resize", measure)
+      window.removeEventListener("scroll", measure, true)
+    }
+  }, [autoAdjust, portal])
+
+  // Portal 模式：量锚点后在视口内定位。transform 祖先会改写 fixed 的包含块，
+  // 所以要把那段偏移减回去。
+  useLayoutEffect(() => {
+    if (!portal) return
+    const el = ref.current
+    if (!el) return
+    const measure = () => {
+      const anchor = typeof portal === "object" && portal.current ? portal.current : el.parentElement
+      if (!anchor) return
+      const anchorRect = anchor.getBoundingClientRect()
+      const dropRect = el.getBoundingClientRect()
+
+      const offsetParent = findFixedOffsetAncestor(el)
+      const offsetX = offsetParent ? offsetParent.getBoundingClientRect().left : 0
+      const offsetY = offsetParent ? offsetParent.getBoundingClientRect().top : 0
+
+      let top = anchorRect.bottom + 4 - offsetY
+      let left = (align === "end" ? anchorRect.right - dropRect.width : anchorRect.left) - offsetX
+
+      if (anchorRect.bottom + 4 + dropRect.height > window.innerHeight - 8) {
+        top = anchorRect.top - dropRect.height - 4 - offsetY
+      }
+      if (top + offsetY < 8) top = 8 - offsetY
+      if (left + offsetX + dropRect.width > window.innerWidth - 8) {
+        left = window.innerWidth - dropRect.width - 8 - offsetX
+      }
+      if (left + offsetX < 8) left = 8 - offsetX
+
+      // 捕获阶段的 scroll 每帧能来好几发；位置没变就别造新对象，否则整棵菜单
+      // 跟着滚动重渲染。
+      setPortalPos((current) => (current && current.top === top && current.left === left ? current : { top, left }))
+    }
+    // 等菜单渲染完再量，否则拿不到高度。
+    const raf = requestAnimationFrame(measure)
+    window.addEventListener("resize", measure)
+    window.addEventListener("scroll", measure, true)
+    return () => {
+      cancelAnimationFrame(raf)
+      window.removeEventListener("resize", measure)
+      window.removeEventListener("scroll", measure, true)
+    }
+  }, [portal, align, items.length, contentKey])
+
+  const menuContent = (
+    <div
+      ref={setSurfaceNode}
+      data-slot="menu-surface"
+      data-ow-part="surface"
+      tabIndex={-1}
+      role={semantics === "menu" ? "menu" : undefined}
+      aria-label={semantics === "menu" ? ariaLabel : undefined}
+      aria-activedescendant={semantics === "menu" && hoveredKey ? `${baseId}-${hoveredKey}` : undefined}
+      onKeyDown={onKeyDown}
+      className={cn(
+        // 弹层立面：贴地之物才 0 影，离地之物给 pop 影，且永远保留 1px 边。
+        "bg-[var(--ow-popover-bg)] border border-[color:var(--ow-border)] shadow-[var(--ow-shadow-pop)] p-1.5 box-border outline-none",
+        "[border-radius:var(--ow-radius-menu)]",
+        className,
+      )}
+      style={{
+        width,
+        ...(portal
+          ? {
+              position: "fixed",
+              zIndex: "var(--ow-z-dropdown)",
+              top: portalPos?.top ?? -9999,
+              left: portalPos?.left ?? -9999,
+              visibility: portalPos ? "visible" : "hidden",
+            }
+          : { transform: adjust.x || adjust.y ? `translate(${adjust.x}px, ${adjust.y}px)` : undefined }),
+      }}
+    >
+      {header &&
+        (headerBare ? (
+          // 头像块这类非眉标内容：原样渲染，且 role="none" —— role="menu" 的子代只认
+          // menuitem/group/separator，不标 none 的话读屏会整块跳过。
+          <div data-ow-part="header" data-ow-variant="bare" role="none">
+            {header}
+          </div>
+        ) : (
+          <div
+            data-ow-part="header"
+            // R2：header 与 group 同是眉标角色，字号/字重/tracking 全同，色也归一到 --ow-eyebrow
+            // （原 header 走 --ow-text-3，同角色两值）。
+            className="font-medium text-ow-fs-eyebrow leading-none text-[color:var(--ow-eyebrow)] px-2 pt-2 pb-1.5 uppercase tracking-[var(--ow-ls-eyebrow)]"
+          >
+            {header}
+          </div>
+        ))}
+      {banner && (
+        <div data-ow-part="banner" role="none">
+          {banner}
+        </div>
+      )}
+      {searchable && (
+        <Field
+          value={query}
+          onChange={setSearch}
+          placeholder={searchPlaceholder}
+          aria-label={searchPlaceholder}
+          // §5：搜索框坐在弹层面上，走 Field 的弹层档（底/边各升一档），
+          // 否则暗档 surface-2 与 popover-bg 同色，井整个消失。
+          tier="pop"
+          className="mb-1.5"
+        />
+      )}
+      <div data-ow-part="list" className="min-h-0">
+        {children ??
+          (visibleItems.length === 0 ? (
+            // §6 / G5：弹层无结果走 EmptyState 原语的 `variant="text"` 档——原型里弹层
+            // 空态**不带母题**（@ 菜单 template.dc.html L923、命令面板 L3018 都只有一行
+            // --ow-fs-ui text-2 灰字，左对齐）。这不是「退回手写灰字」：度量、字阶、颜色
+            // 仍由原语给，只是这一档本来就没有图形位——菜单只有一两行高，塞一枚 28px 母题
+            // 会把弹层撑成两倍，还让「没搜到」看着像一屏正经空态。
+            <div data-ow-part="empty">
+              <EmptyState message={empty} variant="text" />
+            </div>
+          ) : (
+            visibleItems.map((entry, index) => {
+              if (isSeparator(entry))
+                return (
+                  <div
+                    key={entry.key ?? `separator-${index}`}
+                    data-ow-part="separator"
+                    role={semantics === "menu" ? "separator" : undefined}
+                    className="h-px bg-[var(--ow-border)] mx-1.5 my-1.5"
+                  />
+                )
+              if (isGroup(entry))
+                return (
+                  <div
+                    key={entry.key ?? `group-${index}`}
+                    data-ow-part="group"
+                    className="font-medium text-ow-fs-eyebrow leading-none text-[color:var(--ow-eyebrow)] px-2 pt-2 pb-1.5 uppercase tracking-[var(--ow-ls-eyebrow)]"
+                  >
+                    {entry.label}
+                  </div>
+                )
+              const item = entry
+              const active = activeKey === item.key
+              const isHovered = hoveredKey === item.key && !item.disabled
+              const keys = item.shortcut ? shortcutKeys(item.shortcut) : null
+              // 行的公共属性：两种壳（button / 控件行的 div）逐字同构，只差标签与可聚焦方式。
+              const rowProps = {
+                id: `${baseId}-${item.key}`,
+                "data-ow-part": "item",
+                "data-ow-role": item.danger ? "danger" : item.selected || active ? "selected" : "default",
+                "data-ow-state": isHovered ? "highlighted" : undefined,
+                role:
+                  semantics === "menu" ? (item.selected === undefined ? "menuitem" : "menuitemcheckbox") : undefined,
+                "aria-checked": semantics === "menu" && item.selected !== undefined ? item.selected : undefined,
+                className: menuItemVariants({
+                  danger: item.danger,
+                  selected: item.selected || active,
+                  hovered: isHovered,
+                  disabled: item.disabled,
+                  hasDescription: !!item.description,
+                }),
+                onMouseEnter: () => {
+                  setHoveredKey(item.key)
+                  if (!item.disabled) onItemHover?.(item.key)
+                },
+                onMouseLeave: () => setHoveredKey(null),
+                onFocus: () => setHoveredKey(item.key),
+                onClick: () => {
+                  if (!item.disabled) onSelect?.(item.key)
+                },
+              }
+              const rowContent = (
+                <>
+                  {item.icon && (
+                    <span
+                      data-ow-part="item-icon"
+                      className="w-4 h-4 shrink-0 inline-flex items-center justify-center text-[color:var(--ow-text-3)]"
+                    >
+                      {item.icon}
+                    </span>
+                  )}
+                  <span className="flex-1 flex flex-col gap-0.5 min-w-0">
+                    <span className="flex-1">{item.label}</span>
+                    {item.description && (
+                      <span className="text-ow-fs-eyebrow font-normal leading-snug text-[color:var(--ow-text-3)]">
+                        {item.description}
+                      </span>
+                    )}
+                  </span>
+                  {keys && keys.length > 0 ? (
+                    <KeycapCombo data-ow-part="shortcut" className="shrink-0" keys={keys} />
+                  ) : (
+                    item.hint && (
+                      <span
+                        data-ow-part="hint"
+                        className={cn(
+                          "text-ow-fs-eyebrow leading-snug font-normal text-[color:var(--ow-text-3)]",
+                          // §7 读数：版本号、计数这类数字走 mono ＋ tabular-nums，别的 hint 不动。
+                          item.hintMono && "font-[family-name:var(--ow-font-mono)] tabular-nums",
+                        )}
+                      >
+                        {item.hint}
+                      </span>
+                    )
+                  )}
+                  {item.control && (
+                    <span
+                      data-ow-part="item-control"
+                      className="shrink-0 inline-flex items-center"
+                      // 控件自理点击，别让它顺带触发整行的 onSelect（否则开关会被切两次）。
+                      // 键盘事件照旧冒泡到面上：Esc 关面、Tab 游走都要靠它。
+                      onClick={(event) => event.stopPropagation()}
+                    >
+                      {item.control}
+                    </span>
+                  )}
+                  {item.selected && (
+                    <Check
+                      data-ow-part="check"
+                      aria-hidden="true"
+                      className="w-4 h-4 shrink-0 text-[color:var(--ow-text)]"
+                    />
+                  )}
+                </>
+              )
+              // 行尾有交互控件时行不能是 <button>（button 套 button 非法）：改 div 外壳，
+              // 行自身 tabIndex=-1 靠方向键/Tab 程序化聚焦，控件是面内的下一个 Tab 停靠点。
+              if (item.control) {
+                return (
+                  <div
+                    key={item.key}
+                    {...rowProps}
+                    ref={(node: HTMLDivElement | null) => {
+                      if (node) itemRefs.current.set(item.key, node)
+                      else itemRefs.current.delete(item.key)
+                    }}
+                    tabIndex={-1}
+                    aria-disabled={item.disabled || undefined}
+                  >
+                    {rowContent}
+                  </div>
+                )
+              }
+              return (
+                <Button
+                  key={item.key}
+                  {...rowProps}
+                  ref={(node: HTMLButtonElement | null) => {
+                    if (node) itemRefs.current.set(item.key, node)
+                    else itemRefs.current.delete(item.key)
+                  }}
+                  variant="unstyled"
+                  disabled={item.disabled}
+                >
+                  {rowContent}
+                </Button>
+              )
+            })
+          ))}
+      </div>
+      {footer && (
+        <div data-ow-part="footer" className="border-t border-[color:var(--ow-border)] mt-1 pt-1">
+          {footer}
+        </div>
+      )}
+    </div>
+  )
+
+  if (portal && typeof document !== "undefined") {
+    return createPortal(menuContent, document.body)
+  }
+  return menuContent
+}
+
+/* ------------------------------------------------------------------ *
+ * Menu — 触发器 + 菜单面
+ * ------------------------------------------------------------------ */
+
+export type MenuTriggerState = {
+  open: boolean
+  toggle: () => void
+  close: () => void
+  /** 摊到触发器上的无障碍属性与开合处理。 */
+  triggerProps: {
+    "aria-haspopup": "menu"
+    "aria-expanded": boolean
+    onClick: (event: React.MouseEvent) => void
+    onKeyDown: (event: ReactKeyboardEvent) => void
+  }
+}
+
+export type MenuProps = Omit<MenuSurfaceProps, "portal" | "autoFocus" | "onClose" | "surfaceRef"> & {
+  /** 触发器：元素（自动注入 aria/onClick）或渲染函数（自己摊 triggerProps）。 */
+  trigger: ReactElement | ((state: MenuTriggerState) => ReactNode)
+  /** 受控开合。 */
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** 选中后是否自动收起（默认 true）。 */
+  closeOnSelect?: boolean
+  /** 触发器外层容器类名。 */
+  triggerClassName?: string
+}
+
+/**
+ * Menu — 下拉菜单（DS 2.0 patterns · 合并 Dropdown / RowOverflowMenu / DetailOverflowMenu）。
+ *
+ * 触发器 + `MenuSurface`：开合、外点关闭、Esc 关闭并把焦点还给触发器、打开即收焦点，
+ * 面本身负责立面与键盘导航。菜单一律 portal 到 body 后 fixed 定位 —— 行菜单常住在带
+ * overflow 的滚动容器里，absolute 弹层会被祖先裁掉，而裁剪不是抬 z-index 能解决的。
+ *
+ * R3 中性件：不带信标、不带荧黄；空态母题走 `EmptyState` 原语的 `size="sm"` 紧凑档。
+ */
+export function Menu({
+  trigger,
+  open: openProp,
+  onOpenChange,
+  closeOnSelect = true,
+  triggerClassName = "",
+  onSelect,
+  ...surfaceProps
+}: MenuProps) {
+  const [internalOpen, setInternalOpen] = useState(false)
+  const open = openProp ?? internalOpen
+  const anchorRef = useRef<HTMLSpanElement>(null)
+  const surfaceRef = useRef<HTMLDivElement>(null)
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (openProp === undefined) setInternalOpen(next)
+      onOpenChange?.(next)
+    },
+    [openProp, onOpenChange],
+  )
+
+  const focusTrigger = useCallback(() => {
+    anchorRef.current?.querySelector<HTMLElement>("button, [href], [tabindex]:not([tabindex='-1'])")?.focus()
+  }, [])
+
+  const close = useCallback(() => setOpen(false), [setOpen])
+  const closeAndRestore = useCallback(() => {
+    setOpen(false)
+    focusTrigger()
+  }, [setOpen, focusTrigger])
+  const toggle = useCallback(() => setOpen(!open), [open, setOpen])
+
+  // 菜单已经 portal 到 body，不在触发器子树里，所以两棵子树都要放过 —— 只判断
+  // 触发器会让「点菜单项」先关掉菜单，click 永远来不及触发。
+  useEffect(() => {
+    if (!open) return
+    const onPointerDown = (event: PointerEvent) => {
+      const target = event.target as Node | null
+      if (!target) return
+      if (anchorRef.current?.contains(target) || surfaceRef.current?.contains(target)) return
+      setOpen(false)
+    }
+    document.addEventListener("pointerdown", onPointerDown, true)
+    return () => document.removeEventListener("pointerdown", onPointerDown, true)
+  }, [open, setOpen])
+
+  // 记下「这次是键盘还是指针打开的」：键盘（Enter/Space 的 click detail=0，或方向键）
+  // → 焦点进第一行；指针 → 焦点只落面本体，首行不画环（R3，见 MenuSurface.autoFocus）。
+  const openedByKeyboard = useRef(false)
+  const triggerProps: MenuTriggerState["triggerProps"] = {
+    "aria-haspopup": "menu",
+    "aria-expanded": open,
+    onClick: (event) => {
+      openedByKeyboard.current = event.detail === 0
+      toggle()
+    },
+    onKeyDown: (event) => {
+      if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+        event.preventDefault()
+        openedByKeyboard.current = true
+        setOpen(true)
+      }
+    },
+  }
+
+  return (
+    <span data-slot="menu" className={cn("inline-flex", triggerClassName)} ref={anchorRef}>
+      {typeof trigger === "function"
+        ? trigger({ open, toggle, close, triggerProps })
+        : isValidElement(trigger)
+          ? cloneElement(trigger as ReactElement<Record<string, unknown>>, {
+              ...triggerProps,
+              // 触发器自带的 onClick/onKeyDown 不能被开合逻辑吞掉，两个都要跑。
+              onClick: (event: React.MouseEvent) => {
+                ;(trigger.props as { onClick?: (e: React.MouseEvent) => void }).onClick?.(event)
+                if (!event.defaultPrevented) {
+                  openedByKeyboard.current = event.detail === 0
+                  toggle()
+                }
+              },
+              onKeyDown: (event: ReactKeyboardEvent) => {
+                ;(trigger.props as { onKeyDown?: (e: ReactKeyboardEvent) => void }).onKeyDown?.(event)
+                triggerProps.onKeyDown(event)
+              },
+            })
+          : trigger}
+      {open && (
+        <MenuSurface
+          {...surfaceProps}
+          surfaceRef={surfaceRef}
+          portal={anchorRef}
+          autoFocus={openedByKeyboard.current ? true : "surface"}
+          onClose={closeAndRestore}
+          onSelect={(key) => {
+            if (closeOnSelect) setOpen(false)
+            onSelect?.(key)
+          }}
+        />
+      )}
+    </span>
+  )
+}
+
+/**
+ * 向上找最近的带 transform/perspective/filter/will-change 的祖先 —— 它会给
+ * fixed 元素造出新的包含块，让坐标不再相对视口。没有就返回 null。
+ */
+function findFixedOffsetAncestor(el: HTMLElement): HTMLElement | null {
+  let parent = el.parentElement
+  while (parent && parent !== document.body && parent !== document.documentElement) {
+    const style = getComputedStyle(parent)
+    const transform = style.transform || style.webkitTransform
+    if (
+      (transform && transform !== "none") ||
+      (style.filter && style.filter !== "none") ||
+      (style.perspective && style.perspective !== "none") ||
+      style.willChange === "transform" ||
+      style.willChange === "filter" ||
+      style.willChange === "perspective"
+    ) {
+      return parent
+    }
+    parent = parent.parentElement
+  }
+  return null
+}