@orbit-work/ui 0.1.0

package/src/components/composite/NavMenu/NavMenu.stories.tsx

@@ -0,0 +1,383 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { AlertCircle, Doc as File, Folder as Home, Mail, Search, Server, Settings as User } from "../Icons"
+import { NAV_MENU_DIVIDER, NavMenu } from "./index"
+
+const meta = {
+  title: "Composite/NavMenu",
+  component: NavMenu,
+  parameters: {
+    layout: "padded",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof NavMenu>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    items: [
+      { key: "home", label: "Home", icon: <Home />, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, onClick: () => console.log("profile") },
+      { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+    ],
+  },
+}
+
+export const WithActiveItem: Story = {
+  args: {
+    items: [
+      { key: "home", label: "Home", icon: <Home />, active: true, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, onClick: () => console.log("profile") },
+      { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+    ],
+  },
+}
+
+export const WithDisabledItem: Story = {
+  args: {
+    items: [
+      { key: "home", label: "Home", icon: <Home />, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, disabled: true, onClick: () => console.log("profile") },
+      { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+    ],
+  },
+}
+
+export const WithDangerItem: Story = {
+  args: {
+    items: [
+      { key: "home", label: "Home", icon: <Home />, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, onClick: () => console.log("profile") },
+      {
+        key: "delete",
+        label: "Delete Account",
+        icon: <User />,
+        danger: true,
+        onClick: () => console.log("delete"),
+      },
+    ],
+  },
+}
+
+export const WithDividers: Story = {
+  args: {
+    items: [
+      { key: "home", label: "Home", icon: <Home />, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, onClick: () => console.log("profile") },
+      NAV_MENU_DIVIDER,
+      { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+      { key: "logout", label: "Logout", danger: true, onClick: () => console.log("logout") },
+    ],
+  },
+}
+
+export const WithDescriptions: Story = {
+  args: {
+    items: [
+      {
+        key: "home",
+        label: "Home",
+        description: "Dashboard overview",
+        icon: <Home />,
+        onClick: () => console.log("home"),
+      },
+      {
+        key: "profile",
+        label: "Profile",
+        description: "Manage your account",
+        icon: <User />,
+        onClick: () => console.log("profile"),
+      },
+      {
+        key: "settings",
+        label: "Settings",
+        description: "Configure preferences",
+        icon: <User />,
+        onClick: () => console.log("settings"),
+      },
+    ],
+  },
+}
+
+export const WithSuffixes: Story = {
+  args: {
+    items: [
+      { key: "home", label: "Home", icon: <Home />, suffix: <span>⌘H</span>, onClick: () => console.log("home") },
+      {
+        key: "profile",
+        label: "Profile",
+        icon: <User />,
+        suffix: <span>⌘P</span>,
+        onClick: () => console.log("profile"),
+      },
+      {
+        key: "notifications",
+        label: "Notifications",
+        icon: <AlertCircle />,
+        suffix: (
+          <span
+            style={{
+              background: "var(--ow-error)",
+              color: "white",
+              padding: "2px 6px",
+              borderRadius: 10,
+              fontSize: 11,
+            }}
+          >
+            3
+          </span>
+        ),
+        onClick: () => console.log("notifications"),
+      },
+    ],
+  },
+}
+
+export const SmallSize: Story = {
+  args: {
+    size: "sm",
+    items: [
+      { key: "home", label: "Home", icon: <Home />, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, active: true, onClick: () => console.log("profile") },
+      { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+    ],
+  },
+}
+
+export const MediumSize: Story = {
+  args: {
+    size: "md",
+    items: [
+      { key: "home", label: "Home", icon: <Home />, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, active: true, onClick: () => console.log("profile") },
+      { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+    ],
+  },
+}
+
+export const Collapsed: Story = {
+  args: {
+    collapsed: true,
+    items: [
+      { key: "home", label: "Home", icon: <Home />, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, active: true, onClick: () => console.log("profile") },
+      { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+    ],
+  },
+}
+
+export const CollapsedWithDividers: Story = {
+  args: {
+    collapsed: true,
+    items: [
+      { key: "home", label: "Home", icon: <Home />, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, active: true, onClick: () => console.log("profile") },
+      NAV_MENU_DIVIDER,
+      { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+    ],
+  },
+}
+
+export const NoIcons: Story = {
+  args: {
+    items: [
+      { key: "home", label: "Home", onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", active: true, onClick: () => console.log("profile") },
+      { key: "settings", label: "Settings", onClick: () => console.log("settings") },
+    ],
+  },
+}
+
+export const WithCustomClassName: Story = {
+  args: {
+    className: "custom-menu-class",
+    items: [
+      { key: "home", label: "Home", icon: <Home />, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, onClick: () => console.log("profile") },
+    ],
+  },
+}
+
+export const WithCustomAriaLabel: Story = {
+  args: {
+    ariaLabel: "Main navigation",
+    items: [
+      { key: "home", label: "Home", icon: <Home />, onClick: () => console.log("home") },
+      { key: "profile", label: "Profile", icon: <User />, onClick: () => console.log("profile") },
+    ],
+  },
+}
+
+export const NoHandlers: Story = {
+  args: {
+    items: [
+      { key: "home", label: "Home", icon: <Home /> },
+      { key: "profile", label: "Profile", icon: <User />, active: true },
+      { key: "settings", label: "Settings", icon: <User /> },
+    ],
+  },
+}
+
+export const MixedStates: Story = {
+  args: {
+    items: [
+      { key: "home", label: "Home", icon: <Home />, active: true, onClick: () => console.log("home") },
+      {
+        key: "mail",
+        label: "Mail",
+        icon: <Mail />,
+        suffix: (
+          <span
+            style={{
+              background: "var(--ow-info-tint)",
+              color: "var(--ow-info-on-tint)",
+              padding: "2px 6px",
+              borderRadius: 10,
+              fontSize: 11,
+            }}
+          >
+            12
+          </span>
+        ),
+        onClick: () => console.log("mail"),
+      },
+      { key: "search", label: "Search", icon: <Search />, onClick: () => console.log("search") },
+      NAV_MENU_DIVIDER,
+      { key: "profile", label: "Profile", icon: <User />, disabled: true, onClick: () => console.log("profile") },
+      { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+      NAV_MENU_DIVIDER,
+      { key: "delete", label: "Delete", danger: true, onClick: () => console.log("delete") },
+    ],
+  },
+}
+
+export const FileExplorer: Story = {
+  args: {
+    items: [
+      { key: "all", label: "All Files", icon: <Home />, active: true, onClick: () => console.log("all") },
+      { key: "recent", label: "Recent", icon: <File />, onClick: () => console.log("recent") },
+      {
+        key: "starred",
+        label: "Starred",
+        icon: <File />,
+        suffix: <span>★</span>,
+        onClick: () => console.log("starred"),
+      },
+      NAV_MENU_DIVIDER,
+      { key: "code", label: "Code", icon: <File />, onClick: () => console.log("code") },
+      { key: "database", label: "Database", icon: <Server />, onClick: () => console.log("database") },
+    ],
+  },
+}
+
+export const InSidebar: Story = {
+  render: () => (
+    <div
+      style={{
+        width: 240,
+        background: "var(--ow-surface)",
+        padding: 12,
+        borderRadius: 8,
+        border: "1px solid var(--ow-border-strong)",
+      }}
+    >
+      <NavMenu
+        items={[
+          {
+            key: "home",
+            label: "Home",
+            description: "Dashboard",
+            icon: <Home />,
+            active: true,
+            onClick: () => console.log("home"),
+          },
+          {
+            key: "profile",
+            label: "Profile",
+            description: "Your account",
+            icon: <User />,
+            onClick: () => console.log("profile"),
+          },
+          {
+            key: "notifications",
+            label: "Notifications",
+            description: "Activity feed",
+            icon: <AlertCircle />,
+            suffix: (
+              <span
+                style={{
+                  background: "var(--ow-error)",
+                  color: "white",
+                  padding: "2px 6px",
+                  borderRadius: 10,
+                  fontSize: 11,
+                }}
+              >
+                5
+              </span>
+            ),
+            onClick: () => console.log("notifications"),
+          },
+          NAV_MENU_DIVIDER,
+          {
+            key: "settings",
+            label: "Settings",
+            description: "Preferences",
+            icon: <User />,
+            onClick: () => console.log("settings"),
+          },
+        ]}
+      />
+    </div>
+  ),
+}
+
+export const CollapsibleSidebar: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 16 }}>
+      <div
+        style={{
+          width: 240,
+          background: "var(--ow-surface)",
+          padding: 12,
+          borderRadius: 8,
+          border: "1px solid var(--ow-border-strong)",
+        }}
+      >
+        <div style={{ fontSize: 12, fontWeight: 600, color: "var(--ow-text-3)", marginBottom: 8, paddingLeft: 8 }}>
+          Expanded
+        </div>
+        <NavMenu
+          collapsed={false}
+          items={[
+            { key: "home", label: "Home", icon: <Home />, active: true, onClick: () => console.log("home") },
+            { key: "profile", label: "Profile", icon: <User />, onClick: () => console.log("profile") },
+            { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+          ]}
+        />
+      </div>
+      <div
+        style={{
+          width: 56,
+          background: "var(--ow-surface)",
+          padding: 12,
+          borderRadius: 8,
+          border: "1px solid var(--ow-border-strong)",
+        }}
+      >
+        <div style={{ fontSize: 12, fontWeight: 600, color: "var(--ow-text-3)", marginBottom: 8, textAlign: "center" }}>
+          •••
+        </div>
+        <NavMenu
+          collapsed={true}
+          items={[
+            { key: "home", label: "Home", icon: <Home />, active: true, onClick: () => console.log("home") },
+            { key: "profile", label: "Profile", icon: <User />, onClick: () => console.log("profile") },
+            { key: "settings", label: "Settings", icon: <User />, onClick: () => console.log("settings") },
+          ]}
+        />
+      </div>
+    </div>
+  ),
+}

package/src/components/composite/NavMenu/NavMenuSource.test.mjs

@@ -0,0 +1,56 @@
+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")
+const menuSource = await readFile(new URL("../../primitives/Menu/index.tsx", import.meta.url), "utf8")
+const compositeBarrel = await readFile(new URL("../index.ts", import.meta.url), "utf8")
+
+// DS 2.0 蓝图批次②：`Menu` 这个名字归下拉菜单（合并 Dropdown/RowOverflowMenu/
+// DetailOverflowMenu），语义相反的导航列让位改名 NavMenu。两边同名会在包级 barrel
+// 上直接撞车，所以这条边界要锁住。
+
+test("the nav column renders a nav landmark and keeps the ground-tier interaction colors", () => {
+  assert.match(source, /export function NavMenu\(/)
+  assert.match(source, /<nav\b/)
+  assert.match(source, /data-slot="nav-menu"/)
+  // §5：坐在地面/面板上的行走 hover/press，不是弹层的 -pop 档。
+  assert.match(source, /hover:bg-\[var\(--ow-hover\)\] active:bg-\[var\(--ow-press\)\]/)
+  assert.doesNotMatch(source, /--ow-hover-pop/)
+  // §9 唯一缓动。
+  assert.match(source, /ease-\[var\(--ow-ease-beacon\)\]/)
+})
+
+test("the Menu name belongs to the dropdown pattern, not to this file", () => {
+  assert.doesNotMatch(source, /export function Menu\b/)
+  assert.doesNotMatch(source, /export type MenuProps\b/)
+  assert.doesNotMatch(source, /export type MenuEntry\b/)
+  assert.match(menuSource, /export function Menu\(/)
+  assert.match(compositeBarrel, /export \* from "\.\/NavMenu"/)
+  assert.doesNotMatch(compositeBarrel, /export \* from "\.\/Menu"/)
+})
+
+test("non-colliding legacy names stay exported so out-of-package code still compiles", () => {
+  assert.match(source, /@deprecated[\s\S]*?export type MenuItemType = NavMenuItemType/)
+  assert.match(source, /export type MenuDividerType = NavMenuDividerType/)
+  // 值要与旧版逐字同构，否则老 items 数组里的分隔线会渲染成一个空条目。
+  assert.match(source, /export const NAV_MENU_DIVIDER: NavMenuDividerType = \{ type: "divider" \}/)
+  assert.match(source, /export const MENU_DIVIDER: NavMenuDividerType = NAV_MENU_DIVIDER/)
+})
+
+// ── W5 终扫：位置极归属写进契约（§4 让形规则）─────────────────────────────
+test("当前项＝current-bg ＋ 500 字重；图标内信标点归调用方，组件本身不造荧黄", () => {
+  assert.match(source, /bg-\[var\(--ow-current-bg\)\][^"]*font-medium/)
+  assert.match(source, /位置极（§4）/)
+  assert.match(source, /BeaconIcons/)
+  assert.doesNotMatch(source, /--ow-beacon|--ow-accent-dot|--ow-yellow/)
+})
+
+test("§7 行高/字号：40—32 两档 ＋ fs-ui/fs-body-sm，不留 48 与裸 text-sm/text-xs", () => {
+  // 注释里留着旧口径的记述，判定只看去注释后的代码
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\{\/\*[\s\S]*?\*\/\}/g, "")
+  assert.match(code, /size === "sm" \? "min-h-8 gap-2 py-1" : "min-h-10 gap-3 py-2"/)
+  assert.doesNotMatch(code, /48 : 40/)
+  assert.doesNotMatch(code, /\btext-sm\b/)
+  assert.doesNotMatch(code, /\btext-xs\b/)
+})

package/src/components/composite/NavMenu/index.tsx

@@ -0,0 +1,142 @@
+import type { ReactNode } from "react"
+import { cn } from "../../../lib/utils"
+import { Button } from "../../primitives"
+
+export type NavMenuItemType = {
+  key: string
+  label: string
+  description?: string
+  icon?: ReactNode
+  suffix?: ReactNode
+  active?: boolean
+  disabled?: boolean
+  danger?: boolean
+  onClick?: () => void
+}
+
+export type NavMenuDividerType = { type: "divider"; key?: string }
+export type NavMenuEntry = NavMenuItemType | NavMenuDividerType
+export const NAV_MENU_DIVIDER: NavMenuDividerType = { type: "divider" }
+
+export type NavMenuProps = {
+  items: NavMenuEntry[]
+  className?: string
+  size?: "sm" | "md"
+  collapsed?: boolean
+  ariaLabel?: string
+}
+
+/**
+ * NavMenu — 垂直导航列（DS 2.0 更名件）。
+ *
+ * 渲染 `<nav>`：图标 + 名称 + 可选描述/后缀，当前项走 `--ow-current-bg` 位置底。
+ * 坐在地面/面板上，所以交互底色是 `--ow-hover` / `--ow-press`（不是弹层的 -pop 档）。
+ *
+ * 度量按 composite/ListRow 的密度档对齐（§7 行高 40／密 32）：
+ * `size="md"` = `min-h-10 gap-3 px-3 py-2`，`size="sm"` = `min-h-8 gap-2 px-2.5 py-1`。
+ * W3 验收修：原来行高写死在 inline style 上——`item.description ? 48 : 40`，48 不在
+ * §7 高度表；字号是裸 `text-sm`(14) 而非 UI 密度档。现改成 min-height ＋ 上下内距，
+ * 带描述的两行行由内容撑高（同 ListRow 的做法），单行行正好落 40／32；字号落
+ * `--ow-fs-ui`(13)，后缀槽的裸 `text-xs` 一并换成 `--ow-fs-body-sm`(12) token。
+ *
+ * 位置极（§4）：当前项底＝`--ow-current-bg` ＋ 500 字重由本件保证；判断表要求的
+ * 「图标内信标点」由**调用方传入的图标**承担——导航位请传 BeaconIcons 族（九枚语义位
+ * 的 `.dot` 零件可经 `.ow-dot-lit` 点亮），本件不替普通 Lucide 图标补点，也不自造
+ * 荧黄元素（R2/R3）。位置极占了「图标内信标点」形之后，同屏状态极须改用行尾点＋
+ * mono 计数（§4 让形规则）。
+ *
+ * 2.0 更名说明：本组件原名 `Menu`，但蓝图 02 patterns 的 `Menu` 指「下拉菜单」
+ * （合并 Dropdown/RowOverflowMenu/DetailOverflowMenu）。语义相反，故导航件让出
+ * `Menu` 名字改称 NavMenu；下拉菜单见 `primitives/Menu`。
+ */
+export function NavMenu({ items, className = "", size = "md", collapsed = false, ariaLabel = "菜单" }: NavMenuProps) {
+  return (
+    <nav
+      data-slot="nav-menu"
+      data-ow-size={size}
+      data-ow-state={collapsed ? "collapsed" : undefined}
+      className={cn("flex flex-col gap-0.5 data-[ow-state=collapsed]:w-10", className)}
+      aria-label={ariaLabel}
+    >
+      {items.map((item, index) => {
+        if ("type" in item)
+          return (
+            <div
+              key={item.key ?? `divider-${index}`}
+              data-ow-part="divider"
+              className="h-px my-1.5 mx-2.5 bg-ow-border"
+              role="separator"
+            />
+          )
+        return (
+          <Button
+            key={item.key}
+            type="button"
+            data-ow-part="item"
+            data-ow-state={[item.active && "active", item.danger && "danger"].filter(Boolean).join(" ") || undefined}
+            variant="unstyled"
+            className={cn(
+              /* 圆角走控件档 --ow-radius-control(8)：与 ListRow 的 pop 档、ModelPickerList
+                 的 .modelopt 同值。原取 --ow-radius-tag(6)——6 在形状表内，但那是**分类标**
+                 档，行是控件位，同一「行」角色不留 0/6/8 三个值（W-R2）。
+                 transition 收窄到 background-color：原写 background 简写，连
+                 background-image/position/size/attachment 一起过渡（同 Button 从
+                 transition-all 收窄的那类残留）。 */
+              "flex items-center [border-radius:var(--ow-radius-control)] border-0 font-normal text-ow-fs-ui leading-none font-[family-name:var(--ow-font-sans)] text-left w-full transition-[background-color,color] duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)] ow-focus-ring",
+              "hover:bg-[var(--ow-hover)] active:bg-[var(--ow-press)]",
+              "disabled:cursor-not-allowed disabled:text-[color:var(--ow-disabled-text)]",
+              /* ListRow 密度档：default=min-h-10(40) · compact=min-h-8(32)。
+                 h-auto 是把 Button 基座 size=md 自带的 h-8 摘掉（tw-merge 同组后写覆盖），
+                 让 min-height ＋ 内距说了算，带描述的两行行才能自然撑高。 */
+              "h-auto",
+              size === "sm" ? "min-h-8 gap-2 py-1" : "min-h-10 gap-3 py-2",
+              collapsed ? "px-0 justify-center" : size === "sm" ? "px-2.5" : "px-3",
+              item.active && "bg-[var(--ow-current-bg)] text-[color:var(--ow-text)] font-medium",
+              item.danger &&
+                "text-[color:var(--ow-error)] hover:bg-[var(--ow-error-tint)] hover:text-[color:var(--ow-error-hover)]",
+            )}
+            disabled={item.disabled}
+            aria-current={item.active ? "page" : undefined}
+            aria-label={collapsed ? item.label : undefined}
+            title={collapsed ? item.label : undefined}
+            onClick={item.onClick}
+          >
+            {item.icon && <span className="w-4 h-4 inline-flex flex-shrink-0">{item.icon}</span>}
+            {!collapsed && (
+              <span className="flex flex-1 min-w-0 flex-col gap-1">
+                <span>{item.label}</span>
+                {item.description && (
+                  <span className="font-normal text-ow-fs-eyebrow leading-snug font-[family-name:var(--ow-font-sans)] text-ow-text-3 overflow-hidden text-ellipsis whitespace-nowrap">
+                    {item.description}
+                  </span>
+                )}
+              </span>
+            )}
+            {!collapsed && item.suffix && (
+              <span className="ml-auto text-ow-text-3 font-normal text-ow-fs-body-sm leading-none font-[family-name:var(--ow-font-sans)] flex-shrink-0">
+                {item.suffix}
+              </span>
+            )}
+          </Button>
+        )
+      })}
+    </nav>
+  )
+}
+
+/* ------------------------------------------------------------------ *
+ * 兼容层（@deprecated · DS 2.0 更名残留）
+ *
+ * 旧名 `Menu` / `MenuProps` / `MenuEntry` 已让给 patterns 的下拉菜单
+ * （`primitives/Menu`），同名再导出会在包级 barrel 上直接撞车，所以这里只保留
+ * 不冲突的类型与常量别名 —— 值与旧版逐字同构，包外老代码的 `MenuItemType` /
+ * `MENU_DIVIDER` 继续可编译。组件本体与条目联合类型请改用 `NavMenu` /
+ * `NavMenuEntry`。
+ * ------------------------------------------------------------------ */
+
+/** @deprecated 改用 `NavMenuItemType`（组件已更名 NavMenu）。 */
+export type MenuItemType = NavMenuItemType
+/** @deprecated 改用 `NavMenuDividerType`。 */
+export type MenuDividerType = NavMenuDividerType
+/** @deprecated 改用 `NAV_MENU_DIVIDER`；下拉菜单的分隔项是 `MENU_SEPARATOR`。 */
+export const MENU_DIVIDER: NavMenuDividerType = NAV_MENU_DIVIDER