@orbit-work/ui 0.1.0

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

@@ -0,0 +1,416 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+import { Copy, Doc, Download, Edit, Folder, Settings, Share, Sparkles, Sun, Trash } from "../../composite/Icons"
+import { Button } from "../Button"
+import { SegmentedControl } from "../SegmentedControl"
+import { Switch } from "../Switch"
+import { MENU_SEPARATOR, Menu, type MenuEntry, MenuSurface } from "./index"
+
+/**
+ * Menu — 下拉菜单（DS 2.0 patterns，合并 Dropdown / RowOverflowMenu / DetailOverflowMenu）。
+ *
+ * 两个入口：`MenuSurface` 是「面」（自己管开合时用），`Menu` 是「触发器 + 面」。
+ * 下面前半段展示面的全部形态与状态，后半段展示带触发器的完整菜单。
+ * 主题不写死：颜色全部走 token，用工具栏的 theme 切换看双主题。
+ */
+const meta = {
+  title: "Primitives/Menu",
+  component: MenuSurface,
+  parameters: { layout: "centered" },
+  tags: ["autodocs"],
+} satisfies Meta<typeof MenuSurface>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const basicItems: MenuEntry[] = [
+  { key: "edit", label: "重命名" },
+  { key: "duplicate", label: "创建副本" },
+  { key: "delete", label: "删除", danger: true },
+]
+
+const iconItems: MenuEntry[] = [
+  { key: "open", label: "打开", icon: <Doc /> },
+  { key: "copy", label: "复制链接", icon: <Copy /> },
+  { key: "share", label: "分享", icon: <Share /> },
+  { key: "delete", label: "删除", icon: <Trash />, danger: true },
+]
+
+/* ---------------------------------------------------------------- *
+ * MenuSurface — 面
+ * ---------------------------------------------------------------- */
+
+export const Default: Story = {
+  args: { items: basicItems },
+}
+
+export const WithIcons: Story = {
+  args: { items: iconItems },
+}
+
+export const WithShortcuts: Story = {
+  name: "带快捷键（Keycap 列）",
+  args: {
+    width: 240,
+    items: [
+      { key: "new", label: "新建", icon: <Doc />, shortcut: "Ctrl+N" },
+      { key: "open", label: "打开", icon: <Folder />, shortcut: "Ctrl+O" },
+      { key: "save", label: "保存", icon: <Download />, shortcut: ["Ctrl", "S"] },
+      MENU_SEPARATOR,
+      { key: "settings", label: "设置", icon: <Settings />, shortcut: "Ctrl+," },
+    ],
+  },
+}
+
+export const WithDescriptions: Story = {
+  name: "带说明行",
+  args: {
+    width: 260,
+    items: [
+      { key: "public", label: "公开", description: "任何拿到链接的人都能看" },
+      { key: "team", label: "团队内", description: "只有工作区成员能看" },
+      { key: "private", label: "仅自己", description: "别人看不到，也搜不到" },
+    ],
+  },
+}
+
+export const Checked: Story = {
+  name: "勾选态",
+  args: {
+    width: 220,
+    items: [
+      { key: "list", label: "列表视图", selected: true },
+      { key: "grid", label: "网格视图", selected: false },
+      { key: "board", label: "看板视图", selected: false },
+    ],
+  },
+}
+
+export const Grouped: Story = {
+  name: "分组 + 分隔线",
+  args: {
+    width: 240,
+    items: [
+      { type: "group", label: "文件" },
+      { key: "new", label: "新建", icon: <Doc />, shortcut: "Ctrl+N" },
+      { key: "open", label: "打开", icon: <Folder />, shortcut: "Ctrl+O" },
+      MENU_SEPARATOR,
+      { type: "group", label: "危险操作" },
+      { key: "delete", label: "删除工作区", icon: <Trash />, danger: true },
+    ],
+  },
+}
+
+export const LegacyDivider: Story = {
+  name: "兼容：旧 Dropdown 分隔项",
+  parameters: {
+    docs: { description: { story: '旧 items 数组里的 `{ key: "---" }` 仍被识别为分隔线，不用改数据。' } },
+  },
+  args: {
+    items: [
+      { key: "edit", label: "重命名" },
+      { key: "---", label: "" },
+      { key: "delete", label: "删除", danger: true },
+    ],
+  },
+}
+
+export const States: Story = {
+  name: "状态全档",
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "default / hover（-pop 档，鼠标划过看）/ press / focus-visible（Tab 或方向键）/ disabled / 选中 / 危险。",
+      },
+    },
+  },
+  args: {
+    width: 240,
+    items: [
+      { key: "default", label: "常态" },
+      { key: "selected", label: "选中（打勾）", selected: true },
+      { key: "active", label: "活动项（不打勾）" },
+      { key: "disabled", label: "禁用", disabled: true },
+      MENU_SEPARATOR,
+      { key: "danger", label: "危险动作", icon: <Trash />, danger: true },
+      { key: "danger-disabled", label: "危险且禁用", icon: <Trash />, danger: true, disabled: true },
+    ],
+    activeKey: "active",
+  },
+}
+
+export const Searchable: Story = {
+  name: "带搜索",
+  args: {
+    width: 260,
+    searchable: true,
+    searchPlaceholder: "搜索模型",
+    items: Array.from({ length: 12 }, (_, i) => ({
+      key: `model-${i + 1}`,
+      label: `Model ${i + 1}`,
+      selected: i === 2,
+    })),
+  },
+}
+
+export const EmptyResult: Story = {
+  name: "空结果",
+  parameters: {
+    docs: { description: { story: "过滤没命中时只给一句 text-3；带主按钮的空态母题走 EmptyState 原语。" } },
+  },
+  args: {
+    width: 240,
+    searchable: true,
+    searchValue: "找不到的东西",
+    items: basicItems,
+  },
+}
+
+export const HeaderAndFooter: Story = {
+  name: "眉标 + 页脚",
+  args: {
+    width: 260,
+    header: "当前项目",
+    items: [
+      { key: "a", label: "Orbitwork 桌面端", selected: true },
+      { key: "b", label: "设计系统 2.0" },
+    ],
+    footer: (
+      <Button variant="text" size="sm" className="w-full justify-start">
+        新建项目
+      </Button>
+    ),
+  },
+}
+
+export const LongList: Story = {
+  name: "长列表",
+  args: {
+    width: 220,
+    className: "max-h-72 overflow-y-auto",
+    items: Array.from({ length: 24 }, (_, i) => ({ key: `item-${i}`, label: `条目 ${i + 1}` })),
+  },
+}
+
+export const CustomContent: Story = {
+  name: "自定义内容（children）",
+  parameters: {
+    docs: { description: { story: "给了 children 时不加 menu 语义，条目的可读角色由调用方自己负责。" } },
+  },
+  args: {
+    width: 240,
+    children: (
+      <div className="px-2 py-3 text-ow-fs-ui text-[color:var(--ow-text-2)]">域内选择器自己渲染条目时走这条路。</div>
+    ),
+  },
+}
+
+/* ---------------------------------------------------------------- *
+ * Menu — 触发器 + 面
+ * ---------------------------------------------------------------- */
+
+export const WithTrigger: Story = {
+  name: "触发器 + 菜单",
+  parameters: { layout: "padded" },
+  render: () => (
+    <div className="flex min-h-64 items-start gap-4">
+      <Menu trigger={<Button variant="secondary">操作</Button>} items={iconItems} onSelect={() => {}} />
+    </div>
+  ),
+}
+
+export const TriggerRenderProp: Story = {
+  name: "触发器：渲染函数",
+  parameters: { layout: "padded" },
+  render: () => (
+    <div className="flex min-h-64 items-start gap-4">
+      <Menu
+        width={200}
+        items={iconItems}
+        onSelect={() => {}}
+        trigger={({ open, triggerProps }) => (
+          <Button variant="ghost" size="sm" {...triggerProps}>
+            {open ? "收起菜单" : "展开菜单"}
+          </Button>
+        )}
+      />
+    </div>
+  ),
+}
+
+export const AlignEnd: Story = {
+  name: "右缘对齐（行末「…」）",
+  parameters: { layout: "padded" },
+  render: () => (
+    <div className="flex min-h-64 w-96 justify-end">
+      <Menu
+        align="end"
+        width={180}
+        ariaLabel="更多操作"
+        items={[
+          { key: "edit", label: "编辑", icon: <Edit /> },
+          { key: "copy", label: "复制链接", icon: <Copy /> },
+          MENU_SEPARATOR,
+          { key: "delete", label: "删除", icon: <Trash />, danger: true },
+        ]}
+        onSelect={() => {}}
+        trigger={<Button variant="ghost" size="sm" aria-label="更多操作" icon={<Doc />} />}
+      />
+    </div>
+  ),
+}
+
+export const Controlled: Story = {
+  name: "受控开合",
+  parameters: { layout: "padded" },
+  render: function ControlledMenu() {
+    const [open, setOpen] = useState(false)
+    return (
+      <div className="flex min-h-64 items-start gap-3">
+        <Menu
+          open={open}
+          onOpenChange={setOpen}
+          items={basicItems}
+          onSelect={() => {}}
+          trigger={<Button variant="secondary">受控菜单</Button>}
+        />
+        <Button variant="text" size="sm" onClick={() => setOpen((value) => !value)}>
+          外部开关：{open ? "开" : "关"}
+        </Button>
+      </div>
+    )
+  },
+}
+
+export const StaysOpenOnSelect: Story = {
+  name: "选中不收起（多选）",
+  parameters: { layout: "padded" },
+  render: function MultiSelectMenu() {
+    const [picked, setPicked] = useState<string[]>(["md"])
+    const toggle = (key: string) =>
+      setPicked((current) => (current.includes(key) ? current.filter((k) => k !== key) : [...current, key]))
+    return (
+      <div className="flex min-h-64 items-start">
+        <Menu
+          closeOnSelect={false}
+          width={220}
+          items={[
+            { key: "md", label: "Markdown", selected: picked.includes("md") },
+            { key: "pdf", label: "PDF", selected: picked.includes("pdf") },
+            { key: "docx", label: "Word", selected: picked.includes("docx") },
+          ]}
+          onSelect={toggle}
+          trigger={<Button variant="secondary">导出格式</Button>}
+        />
+      </div>
+    )
+  },
+}
+
+/* ---------------------------------------------------------------- *
+ * R2 新槽：控件行 / banner 与 bare 眉标
+ * ---------------------------------------------------------------- */
+
+export const ControlRows: Story = {
+  name: "行尾控件 + mono 读数",
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`control` 给行尾放交互控件：该行渲染成 `<div role="menuitem">` 外壳（button 套 button 非法），' +
+          "控件自己吃掉点击，Tab 在「当前行 → 该行控件 → 下一行」间游走，走到末尾才交还焦点。" +
+          "`hint` 收 ReactNode，`hintMono` 让它走读数档（mono ＋ tabular-nums），版本号用。",
+      },
+    },
+  },
+  render: function ControlRowsMenu() {
+    const [pet, setPet] = useState(true)
+    const [theme, setTheme] = useState("light")
+    return (
+      <MenuSurface
+        width={280}
+        ariaLabel="控件行示例"
+        items={[
+          { key: "settings", label: "设置", icon: <Settings />, shortcut: "Ctrl+," },
+          {
+            key: "pet",
+            label: "桌面宠物",
+            icon: <Sparkles />,
+            control: <Switch checked={pet} onChange={setPet} aria-label="桌面宠物" />,
+          },
+          {
+            key: "theme",
+            label: "外观",
+            icon: <Sun />,
+            control: (
+              <SegmentedControl
+                size="sm"
+                variant="outline"
+                aria-label="外观"
+                value={theme}
+                onChange={setTheme}
+                options={[
+                  { value: "light", label: "浅色" },
+                  { value: "dark", label: "深色" },
+                  { value: "system", label: "自动" },
+                ]}
+              />
+            ),
+          },
+          MENU_SEPARATOR,
+          { key: "version", label: "检查更新", icon: <Download />, hint: "v1.4.2", hintMono: true },
+        ]}
+        onSelect={(key) => {
+          if (key === "pet") setPet((value) => !value)
+        }}
+      />
+    )
+  },
+}
+
+export const BannerAndBareHeader: Story = {
+  name: "banner 槽 + bare 眉标",
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`headerBare` 让 header 原样渲染（不套 CAPS 眉标排版）并标 `role="none"`；' +
+          '`banner` 是 header 与条目之间的整块自定义内容（套餐井这类），同样 `role="none"` 包裹 —— ' +
+          '`role="menu"` 的子代只认 menuitem / group / separator，不标 none 会被读屏整块跳过。',
+      },
+    },
+  },
+  args: {
+    width: 280,
+    ariaLabel: "账户菜单示例",
+    headerBare: true,
+    header: (
+      <div className="flex items-center gap-2.5 px-2 pt-2 pb-1.5">
+        <span className="w-8 h-8 shrink-0 [border-radius:var(--ow-radius-pill)] bg-[var(--ow-surface-2)] inline-flex items-center justify-center text-ow-fs-ui font-medium text-[color:var(--ow-text-2)]">
+          T
+        </span>
+        <span className="flex flex-col min-w-0 gap-0.5">
+          <span className="text-ow-fs-ui font-semibold text-[color:var(--ow-text)] truncate">Terry</span>
+          <span className="text-ow-fs-eyebrow font-normal text-[color:var(--ow-text-3)] truncate">
+            terry@orbitwork.ai
+          </span>
+        </span>
+      </div>
+    ),
+    banner: (
+      <div className="mx-2 mb-1.5 px-3 py-2.5 bg-[var(--ow-surface-2)] [border-radius:var(--ow-radius-md)] flex items-center justify-between gap-2">
+        <span className="text-ow-fs-ui font-medium text-[color:var(--ow-text)]">体验版</span>
+        <span className="text-ow-fs-eyebrow font-normal text-[color:var(--ow-text-2)] font-[family-name:var(--ow-font-mono)] tabular-nums">
+          1,240 / 2,000
+        </span>
+      </div>
+    ),
+    items: [
+      { key: "settings", label: "设置", icon: <Settings /> },
+      { key: "help", label: "帮助与反馈", icon: <Doc /> },
+      MENU_SEPARATOR,
+      { key: "logout", label: "退出登录", icon: <Trash />, danger: true },
+    ],
+  },
+}

package/src/components/primitives/Menu/MenuEmptySource.test.mjs

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const source = await readFile(new URL("./index.tsx", import.meta.url), "utf8")
+
+test("§6 / G5：弹层无结果走 EmptyState 的 text 档（原型 L923：一行灰字、无母题）", () => {
+  assert.ok(source.includes('import { EmptyState } from "../EmptyState"'))
+  // A5-B4：从 sm 紧凑档改到 text 档——弹层只有一两行高，塞 28px 母题会把面撑成两倍，
+  // 还让「没搜到」看着像一屏正经空态。度量/字阶/颜色仍由原语给，不是退回手写灰字。
+  assert.match(source, /<EmptyState message=\{empty\} variant="text" \/>/)
+  assert.doesNotMatch(source, /<EmptyState size="sm"/)
+  // 手搓的 text-3 居中小字块退役
+  assert.doesNotMatch(source, /data-ow-part="empty"\s*\n\s*className="py-4 px-2 text-\[color:var\(--ow-text-3\)\]/)
+})
+
+test('定位钩子 data-ow-part="empty" 保留，调用点与 e2e 不断链', () => {
+  assert.match(source, /<div data-ow-part="empty">/)
+})
+
+test("默认空态文案仍在（不改对外签名）", () => {
+  assert.match(source, /empty = "暂无结果"/)
+})

package/src/components/primitives/Menu/MenuSource.test.mjs

@@ -0,0 +1,207 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const source = await readFile(new URL("./index.tsx", import.meta.url), "utf8")
+
+// ---------------------------------------------------------------------------
+// 立面（COMPONENT-RULES §5 / §7）
+// ---------------------------------------------------------------------------
+
+test("menu surface keeps the DS 2.0 popover facade", () => {
+  assert.match(source, /bg-\[var\(--ow-popover-bg\)\]/, "面底走 --ow-popover-bg")
+  // 悬浮层永远保留 1px 边框，影子只属离地之物。
+  assert.match(source, /border border-\[color:var\(--ow-border\)\]/)
+  assert.match(source, /shadow-\[var\(--ow-shadow-pop\)\]/)
+  // 圆角 10 = 菜单档（§7 形状表）。
+  assert.match(source, /\[border-radius:var\(--ow-radius-menu\)\]/)
+  // z 一律走 token 梯度，禁裸数字。
+  assert.match(source, /zIndex: "var\(--ow-z-dropdown\)"/)
+  assert.doesNotMatch(source, /zIndex:\s*\d/, "z 不许写死数字")
+})
+
+test("rows sit on the popover surface, so they take the -pop interaction tier", () => {
+  // §5：坐在 --ow-popover-bg 上的行一律 hover-pop → press-pop，不是地面的 hover/press。
+  assert.match(
+    source,
+    /compoundVariants:[\s\S]*?hovered:\s*true[\s\S]*?bg-\[var\(--ow-hover-pop\)\][\s\S]*?active:bg-\[var\(--ow-press-pop\)\]/s,
+  )
+  assert.match(source, /bg-\[var\(--ow-error-tint\)\][\s\S]*?active:bg-\[var\(--ow-error-tint-hover\)\]/s)
+  assert.doesNotMatch(source, /hover:bg-\[var\(--ow-hover\)\]/, "弹层内不许用地面档 hover")
+  // 行高 32 是常态档（§7 高度表）。
+  assert.match(source, /hasDescription:\s*\{[\s\S]*?false:\s*"h-8"/s)
+})
+
+test("state completeness — focus-visible ring, per-token disabled, danger, selected", () => {
+  assert.match(source, /ow-focus-ring/, "§6 focus-visible 必做")
+  assert.match(source, /disabled:\s*\{\s*true:\s*"cursor-not-allowed text-\[color:var\(--ow-disabled-text\)\]"/s)
+  // 禁统一透明度禁用态（逐 token 给禁用色）。正则拼出来写，免得这行字面量本身
+  // 被 check-ds2 的 disabled 规则当成违规命中。
+  assert.doesNotMatch(source, new RegExp(`disabled:${"opacity"}-`), "禁统一透明度禁用态")
+  assert.match(source, /danger:\s*\{\s*true:\s*"text-\[color:var\(--ow-error\)\]"/s)
+  assert.match(source, /selected:\s*\{\s*true:\s*"bg-\[var\(--ow-selected-bg\)\]"/s)
+})
+
+test("motion is the single beacon easing at the 120ms hover tier", () => {
+  assert.match(source, /ease-\[var\(--ow-ease-beacon\)\]/)
+  assert.match(source, /duration-\[var\(--ow-dur-1\)\]/)
+  assert.doesNotMatch(source, /ease-\[var\(--ow-ease-out\)\]/)
+  // §9：禁缩放、禁位移式 hover 反馈。
+  assert.doesNotMatch(source, /hover:[a-z-]*(?:scale|translate)-/)
+})
+
+// ---------------------------------------------------------------------------
+// 条目形态
+// ---------------------------------------------------------------------------
+
+test("shortcut column renders keycaps, not plain text", () => {
+  // §7 读数（快捷键）一律 mono + tabular-nums —— Keycap 原语已经包好这两条。
+  assert.match(source, /import \{ KeycapCombo \} from "\.\.\/Keycap"/)
+  assert.match(source, /<KeycapCombo[^>]*keys=\{keys\}/)
+  assert.match(source, /shortcut\?: string \| string\[\]/)
+})
+
+test("selected rows are marked with a real check glyph", () => {
+  // 暗档 hover-pop 与 current-bg 同值属有意，所以选中项靠勾区分而不是靠底色；
+  // 勾是 Lucide 系图标，不是 "✓" 字符。
+  assert.match(source, /import \{ Check \} from "\.\.\/\.\.\/composite\/Icons"/)
+  assert.match(source, /\{item\.selected && \(\s*<Check/s)
+  assert.doesNotMatch(source, /✓/, "勾用图标件，不用字符")
+})
+
+test("entries cover separators, group labels and the legacy divider shape", () => {
+  assert.match(source, /export const MENU_SEPARATOR/)
+  assert.match(source, /type: "group"/)
+  // 旧 Dropdown 的 { key: "---" } 分隔项在兼容期必须继续识别，否则老 items 数组会
+  // 把分隔线渲染成一个空条目。
+  assert.match(source, /const LEGACY_DIVIDER_KEY = "---"/)
+  assert.match(source, /entry\.key === LEGACY_DIVIDER_KEY/)
+})
+
+test("menu semantics are on by default for item mode and off for custom children", () => {
+  assert.match(source, /const semantics = role \?\? \(children \? "none" : "menu"\)/)
+  assert.match(source, /role=\{semantics === "menu" \? "menu" : undefined\}/)
+  assert.match(source, /\? "menuitem"\s*:\s*"menuitemcheckbox"/s)
+})
+
+// ---------------------------------------------------------------------------
+// 键盘导航
+// ---------------------------------------------------------------------------
+
+test("keyboard navigation is complete", () => {
+  assert.match(source, /event\.key === "ArrowDown" \|\| event\.key === "ArrowUp"/)
+  assert.match(source, /event\.key === "Home" \|\| event\.key === "End"/)
+  assert.match(source, /event\.key === "Enter"/)
+  assert.match(source, /event\.key === "Escape"/)
+  assert.match(source, /aria-activedescendant/)
+  // 首字母跳转：搜索框、行尾控件在场时让位给它们，否则打字（含空格）会被当成跳转键吃掉。
+  // R2：判据从「只让搜索框」扩到「搜索框 + 控件区」，见文件末尾控件行一节。
+  assert.match(source, /if \(!inSearch && !inControl && event\.key\.length === 1/)
+})
+
+// ---------------------------------------------------------------------------
+// 弹层定位（这几条是组件存在的理由，改回去就等于把 bug 放回来）
+// ---------------------------------------------------------------------------
+
+test("the surface escapes clipping ancestors via a fixed-position portal", () => {
+  // 菜单常住在带 overflow 的滚动容器里（设置页 .settings__content 是 overflow-y: auto），
+  // absolute 定位的弹层会被祖先裁掉，而裁剪不是抬 z-index 能解决的。
+  assert.match(source, /createPortal\(menuContent, document\.body\)/)
+  assert.match(source, /position: "fixed"/)
+  // transform/filter 祖先会给 fixed 造出新的包含块，坐标要把那段偏移减回去。
+  assert.match(source, /findFixedOffsetAncestor/)
+  // 行末「…」贴右缘，不然长菜单会从行的左边探出去。
+  assert.match(source, /align === "end" \? anchorRect\.right - dropRect\.width : anchorRect\.left/)
+})
+
+test("outside-click ignores both the trigger and the portalled surface", () => {
+  // 菜单 portal 之后不在触发器子树里，只判断触发器会让「点菜单项」先关掉菜单，
+  // click 永远来不及触发 —— 那正是行菜单最初「点了没反应」的形态。
+  assert.match(source, /anchorRef\.current\?\.contains\(target\) \|\| surfaceRef\.current\?\.contains\(target\)/)
+  assert.match(source, /document\.addEventListener\("pointerdown", onPointerDown, true\)/)
+})
+
+test("escape returns focus to the trigger", () => {
+  assert.match(source, /const closeAndRestore = useCallback\(/)
+  assert.match(source, /focusTrigger\(\)/)
+})
+
+// ---------------------------------------------------------------------------
+// R3 中性件
+// ---------------------------------------------------------------------------
+
+test("menu is a neutral pattern — no beacon, no lime", () => {
+  assert.doesNotMatch(source, /--ow-yellow|--ow-beacon|--ow-accent-dot/)
+  assert.doesNotMatch(source, /BeaconIcons|BeaconSpinner/)
+})
+
+// ---------------------------------------------------------------------------
+// R2 基座：控件行 / hint 读数 / banner 与 bare 眉标（T4 账户菜单的前置）
+// ---------------------------------------------------------------------------
+
+test("行尾控件行是 div role=menuitem，不是 button 套 button", () => {
+  assert.match(source, /control\?: ReactNode/, "MenuItem 收 control 槽")
+  // button 里再嵌 button 是非法 HTML，浏览器会把内层拆出去，键盘与读屏一起错位。
+  assert.match(source, /if \(item\.control\) \{\s*return \(\s*<div/s)
+  assert.match(source, /\{\.\.\.rowProps\}\s*ref=\{\(node: HTMLDivElement \| null\)/s)
+  // 行本身不抢 Tab：靠方向键/面内 Tab 程序化聚焦。
+  assert.match(source, /tabIndex=\{-1\}\s*aria-disabled=\{item\.disabled \|\| undefined\}/s)
+  // 两种壳共用同一套行属性（立面/状态/事件逐字同构，只差标签）。
+  assert.match(source, /const rowProps = \{/)
+  assert.match(source, /const rowContent = \(/)
+  // 控件区自己吃掉点击，否则开关会被切两次；键盘事件必须继续冒泡（Esc 关面、Tab 游走）。
+  assert.match(source, /data-ow-part="item-control"[\s\S]*?onClick=\{\(event\) => event\.stopPropagation\(\)\}/s)
+  assert.doesNotMatch(source, /data-ow-part="item-control"[\s\S]{0,400}?onKeyDown=/s, "控件区不许拦键盘事件")
+})
+
+test("hint 收 ReactNode，hintMono 走读数档", () => {
+  assert.match(source, /hint\?: ReactNode/)
+  assert.match(source, /hintMono\?: boolean/)
+  // §7 读数：mono ＋ tabular-nums；不加 hintMono 的 hint 排版一字不变。
+  assert.match(source, /item\.hintMono && "font-\[family-name:var\(--ow-font-mono\)\] tabular-nums"/)
+})
+
+test("banner 槽与 bare 眉标都标 role=none", () => {
+  // role="menu" 的子代只认 menuitem / group / separator，非条目内容不标 none 会被整块跳过。
+  assert.match(source, /banner\?: ReactNode/)
+  assert.match(source, /headerBare\?: boolean/)
+  assert.match(source, /data-ow-part="banner" role="none"/)
+  assert.match(source, /data-ow-part="header" data-ow-variant="bare" role="none"/)
+  // bare 档不套眉标排版；眉标档原样保留（六个既有消费方零变化）。
+  assert.match(source, /headerBare \? \(/)
+  assert.match(
+    source,
+    /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\)\]"/,
+  )
+})
+
+test("Tab：有控件行时面内游走，无控件行仍是离面", () => {
+  // 旧行为（Tab 即 onClose）是全库其它菜单的现状，只有出现 control 行才改道。
+  assert.match(source, /if \(!rovingTab\) \{\s*onClose\?\.\(\)/s)
+  assert.match(source, /const hasControlRow = useMemo\(\(\) => navigable\.some\(\(item\) => !!item\.control\)/)
+  // 核对（Fable）：bare 头部 / banner / footer 里的按钮（复制 ID、升级）也是停靠点，否则键盘够不着；
+  // 有这三种槽或控件行才游走，都没有时照旧离面。
+  assert.match(source, /const rovingTab = hasControlRow \|\| \(!!header && headerBare\) \|\| !!banner/)
+  assert.match(source, /if \(headerBare\) stops\.push\(\.\.\.focusableStops\(slot\("header"\)\)\)/)
+  assert.match(source, /stops\.push\(\.\.\.focusableStops\(slot\("banner"\)\)\)/)
+  assert.match(source, /stops\.push\(\.\.\.focusableStops\(slot\("footer"\)\)\)/)
+  // 控件自己吃掉的键（分段器的 ←→ / Home / End）面不再接手，否则 Home/End 一边切段一边甩焦点。
+  assert.match(source, /if \(inControl && event\.isDefaultPrevented\(\)\) return/)
+  // 停靠点顺序：行 → 该行控件 → 下一行；两端才交还焦点。
+  assert.match(source, /const tabStops = useCallback\(/)
+  assert.match(source, /stops\.push\(row\)/)
+  assert.match(source, /if \(index < 0 \|\| next < 0 \|\| next >= stops\.length\) \{\s*onClose\?\.\(\)/s)
+  assert.match(source, /event\.shiftKey \? -1 : 1/, "Shift+Tab 反向游走")
+  // roving tabindex 的控件（分段器）内部只有一个 tabIndex=0 的段算停靠点。
+  assert.match(source, /node\.tabIndex < 0 \|\| node\.hasAttribute\("disabled"\)/)
+})
+
+test("焦点落在行尾控件里时，字符键 / Enter / 空格归控件", () => {
+  // 判据是「事件源在控件区内」，不是 tagName —— 否则开关上的空格会被首字母跳转吃掉。
+  assert.match(source, /const inControl = !!target\.closest\?\.\('\[data-ow-part="item-control"\]'\)/)
+  assert.match(source, /const inSearch = target\.tagName === "INPUT" && !inControl/)
+  assert.match(source, /event\.key === "Enter" && hoveredKey && !inSearch && !inControl/)
+  assert.match(source, /if \(!inSearch && !inControl && event\.key\.length === 1/)
+  // 控件行没有 button 的原生空格触发，补一条；普通行的空格仍走原生 click。
+  assert.match(source, /event\.key === " " && hoveredKey && !inSearch && !inControl[\s\S]*?row\?\.control/s)
+})