@orbit-work/ui 0.1.2-preview.0 → 0.1.2

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

@@ -1,923 +0,0 @@
-"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。
- * （Select 的 portal 菜单量位也复用这个。）
- */
-export 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
-}