@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/drawer/drawer.tsx

@@ -1,114 +1,23 @@
-import * as React from 'react';
-import { Drawer as DrawerPrimitive } from 'vaul';
-
-import { cn } from '@/utils/cn';
-
-const Drawer = ({
-  shouldScaleBackground = true,
-  ...props
-}: React.ComponentProps<typeof DrawerPrimitive.Root>) => (
-  <DrawerPrimitive.Root
-    shouldScaleBackground={shouldScaleBackground}
-    {...props}
-  />
-);
-Drawer.displayName = 'Drawer';
-
-const DrawerTrigger = DrawerPrimitive.Trigger;
-const DrawerPortal = DrawerPrimitive.Portal;
-const DrawerClose = DrawerPrimitive.Close;
-
-const DrawerOverlay = React.forwardRef<
-  React.ElementRef<typeof DrawerPrimitive.Overlay>,
-  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Overlay>
->(({ className, ...props }, ref) => (
-  <DrawerPrimitive.Overlay
-    ref={ref}
-    className={cn('fixed inset-0 z-50 bg-black/80', className)}
-    {...props}
-  />
-));
-DrawerOverlay.displayName = DrawerPrimitive.Overlay.displayName;
-
-export interface DrawerContentProps
-  extends React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Content> {}
-
-const DrawerContent = React.forwardRef<
-  React.ElementRef<typeof DrawerPrimitive.Content>,
-  DrawerContentProps
->(({ className, children, ...props }, ref) => (
-  <DrawerPortal>
-    <DrawerOverlay />
-    <DrawerPrimitive.Content
-      ref={ref}
-      className={cn(
-        'fixed inset-x-0 bottom-0 z-50 mt-24 flex h-auto flex-col rounded-t-[10px] border bg-background',
-        className,
-      )}
-      {...props}
-    >
-      <div className="mx-auto mt-4 h-2 w-[100px] rounded-full bg-muted" />
-      {children}
-    </DrawerPrimitive.Content>
-  </DrawerPortal>
-));
-DrawerContent.displayName = 'DrawerContent';
-
-const DrawerHeader = ({
-  className,
-  ...props
-}: React.HTMLAttributes<HTMLDivElement>) => (
-  <div
-    className={cn('grid gap-1.5 p-4 text-center sm:text-left', className)}
-    {...props}
-  />
-);
-DrawerHeader.displayName = 'DrawerHeader';
-
-const DrawerFooter = ({
-  className,
-  ...props
-}: React.HTMLAttributes<HTMLDivElement>) => (
-  <div className={cn('mt-auto flex flex-col gap-2 p-4', className)} {...props} />
-);
-DrawerFooter.displayName = 'DrawerFooter';
-
-const DrawerTitle = React.forwardRef<
-  React.ElementRef<typeof DrawerPrimitive.Title>,
-  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Title>
->(({ className, ...props }, ref) => (
-  <DrawerPrimitive.Title
-    ref={ref}
-    className={cn(
-      'text-lg font-semibold leading-none tracking-tight',
-      className,
-    )}
-    {...props}
-  />
-));
-DrawerTitle.displayName = DrawerPrimitive.Title.displayName;
-
-const DrawerDescription = React.forwardRef<
-  React.ElementRef<typeof DrawerPrimitive.Description>,
-  React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Description>
->(({ className, ...props }, ref) => (
-  <DrawerPrimitive.Description
-    ref={ref}
-    className={cn('text-sm text-muted-foreground', className)}
-    {...props}
-  />
-));
-DrawerDescription.displayName = DrawerPrimitive.Description.displayName;
-
+/**
+ * Drawer — Sheet 的别名导出。
+ *
+ * 历史上 Drawer 基于 vaul(底部可拖拽抽屉),现在统一为 Sheet(Radix Dialog 底座)。
+ * 本文件通过 re-export 保持向后兼容:业务侧已有的 `import { Drawer, DrawerContent } from '...'` 不会断裂。
+ *
+ * @see sheet.tsx — 实际实现
+ */
 export {
-  Drawer,
-  DrawerPortal,
-  DrawerOverlay,
-  DrawerTrigger,
-  DrawerClose,
-  DrawerContent,
-  DrawerHeader,
-  DrawerFooter,
-  DrawerTitle,
-  DrawerDescription,
-};
+  Sheet as Drawer,
+  SheetPortal as DrawerPortal,
+  SheetOverlay as DrawerOverlay,
+  SheetTrigger as DrawerTrigger,
+  SheetClose as DrawerClose,
+  SheetContent as DrawerContent,
+  SheetHeader as DrawerHeader,
+  SheetBody as DrawerBody,
+  SheetFooter as DrawerFooter,
+  SheetTitle as DrawerTitle,
+  SheetDescription as DrawerDescription,
+} from '@/components/sheet/sheet';
+
+export type { SheetContentProps as DrawerContentProps, SheetSize as DrawerSize } from '@/components/sheet/sheet';

package/src/components/dropdown-menu/dropdown-menu.meta.md

@@ -4,10 +4,11 @@ name: DropdownMenu
 type: component
 category: navigation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 下拉菜单
 ---
 
-# DropdownMenu
+# DropdownMenu 下拉菜单
 
 下拉菜单 — Radix DropdownMenu 完整实现:Item / CheckboxItem / RadioItem / Label / Separator / Shortcut / Sub(子菜单)。
 对应 antd `Dropdown`,但本组件是**完整 menu primitives**(antd Dropdown 主要走 children 自由排版,本组件提供语义化每一种 item)。
@@ -56,8 +57,6 @@ pnpm add @radix-ui/react-dropdown-menu@^2.1.0 lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
-> 完整子组件:`DropdownMenu` / `DropdownMenuTrigger` / `DropdownMenuContent` / `DropdownMenuItem`(支持 `inset`)/ `DropdownMenuCheckboxItem` / `DropdownMenuRadioItem` / `DropdownMenuLabel` / `DropdownMenuSeparator` / `DropdownMenuShortcut` / `DropdownMenuGroup` / `DropdownMenuRadioGroup` / `DropdownMenuSub`(嵌套)/ `DropdownMenuSubTrigger` / `DropdownMenuSubContent`。
-
 ## AI 生成纪律
 
 - **Trigger 用 `asChild`**:wrap 已有 Button,而非新增 button 层
@@ -70,11 +69,20 @@ pnpm add @radix-ui/react-dropdown-menu@^2.1.0 lucide-react@^0.460.0
 
 ```tsx
 import {
-  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent,
-  DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem,
-  DropdownMenuRadioGroup, DropdownMenuLabel, DropdownMenuSeparator,
-  DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger,
-  DropdownMenuSubContent, DropdownMenuPortal,
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+  DropdownMenuPortal,
 } from '@/components/ui/dropdown-menu';
 import { Button } from '@/components/ui/button';
 import { User, Settings, LogOut } from 'lucide-react';
@@ -99,5 +107,65 @@ import { User, Settings, LogOut } from 'lucide-react';
       <LogOut /> 退出
     </DropdownMenuItem>
   </DropdownMenuContent>
-</DropdownMenu>
+</DropdownMenu>;
 ```
+
+## MenuButton 形态 — 旧库 API → 新组合映射
+
+新库 **不提供独立的 `MenuButton` 组件**。这是主动决策 — 旧库 cloud-design `MenuButton` / antd `Dropdown` 本质上就是 `DropdownMenu + Button trigger` 的组合,因此面向业务只暴露组合写法可以:
+
+- 与 `SplitButton` 形态(见 [`button.meta.md`](../button/button.meta.md))共享同一套 trigger 协议
+- 遵循 P1 "三层对齐"的原子/合成分层,不引入 wrapper 级套娃
+- 业务侧保留 trigger Button 类型全控(variant / size / icon / iconRight / loading 任意组合)
+
+### Props 映射表
+
+| 旧库 `MenuButton` API | 新库等价写法 | 备注 |
+| --- | --- | --- |
+| `label="X"` | `<DropdownMenuTrigger asChild><Button iconRight={<ChevronDown />}>X</Button></DropdownMenuTrigger>` | trigger Button 是 unstyled Slot,业务自由组合 variant/size/icon/iconRight |
+| `shape` / `type` / `size` / `component` / `ghost` 等 Button 属性透传 | 直接给 trigger Button 传同名 props | 新库 Button 见 [`button.meta.md`](../button/button.meta.md) |
+| `autoWidth`(默认 true,弹层宽度=按钮宽度) | `<DropdownMenuContent style={{ minWidth: 'var(--radix-dropdown-menu-trigger-width)' }}>` | 读 Radix 暴露的 CSS 变量;默认遵 shadcn `min-w-menu`(8rem)。主动选 `style` 而非 Tailwind arbitrary value(`min-w-[var(--...)]`),避免 `no-arbitrary-tw-value` lint 告警 |
+| `popupTriggerType="click"`(默认) | 默认即点击触发,无需配置 | — |
+| `popupTriggerType="hover"` | **不支持** — Radix 故意不暴露 hover(WCAG 可达性) | 替代:用 `HoverCard`(纯展示)或 `NavigationMenu`(导航) |
+| `popupContainer` | `<DropdownMenuPortal container={...}>` | 见 Radix 原生 Portal API |
+| `visible` / `defaultVisible` | `<DropdownMenu open={...}>` / `defaultOpen={...}` | — |
+| `onVisibleChange` | `<DropdownMenu onOpenChange={...}>` | — |
+| `popupStyle` / `popupClassName` | `<DropdownMenuContent style={...} className={...}>` | 直接传给 Content |
+| `popupProps` | `<DropdownMenuContent {...props}>` | 任意原生 prop 透传 |
+| `followTrigger`(滚动跟随) | **不支持** — Radix Portal 默认即 follow | — |
+| `defaultSelectedKeys` / `selectedKeys` + `selectMode="single"` | `<DropdownMenuRadioGroup defaultValue={...}>` / `value={...}` + `<DropdownMenuRadioItem value="...">` | 受控/非受控两套 |
+| `selectMode="multiple"` + `selectedKeys` | 多个独立 `<DropdownMenuCheckboxItem checked={...} onCheckedChange={...}>` | 业务侧自管 state(单选 vs 多选语义不同) |
+| `onItemClick` | 给每个 `<DropdownMenuItem onSelect={...}>` 单独绑 | shadcn/Radix 范式 — 每项独立处理器更类型安全 |
+| `onSelect` | `<DropdownMenuRadioGroup onValueChange={...}>` | 单选场景 |
+| `menuProps` | `<DropdownMenuContent {...}>` | 与 popupProps 等价 |
+| `MenuButton.Item` | `DropdownMenuItem` | — |
+| `MenuButton.Group` | `DropdownMenuGroup` + `DropdownMenuLabel` | — |
+| `MenuButton.Divider` | `DropdownMenuSeparator` | — |
+
+### 不修复清单(主动不补)
+
+| 旧 API | 决策原因 |
+| --- | --- |
+| `popupTriggerType="hover"` | Radix 故意不暴露(WCAG 可达性 — hover-only 触发对键盘/触屏不友好);替代用 `HoverCard` |
+| `delay`(hover 延时) | 无 hover 模式,故无需延时 |
+| `beforeOpen` / `afterClose` 等生命周期 | 已统一为 `onOpenChange(open)`,语义更窄/无歧义 |
+| `animation` 自定义参数 | 已固化为内置 CSS 动画(`animate-in/out fade+zoom+slide` 四向);业务覆盖 → `<DropdownMenuContent className="...">` |
+| 默认 ChevronDown 图标 | trigger Button 由业务组合,不在 Trigger 内塞默认 icon — 与 shadcn / Radix 的 unstyled trigger 语义一致 |
+| 独立 `MenuButton` 导出 | P1 三层对齐;`<DropdownMenu> + <Button>` 即原子合成,无需 wrapper |
+
+### 4 段标准形态 ↔ 现有 Story
+
+| 旧库 demo | 新库 Story | 文件 |
+| --- | --- | --- |
+| 基本(`label` + Button 属性透传) | `Default` | [`dropdown-menu.stories.tsx`](./dropdown-menu.stories.tsx) |
+| 复杂菜单(`Group` / `Item` / `Divider`) | `WithSubMenu`(包含 Group + Sub + Separator) | 同上 |
+| 多选菜单(`selectMode="multiple"`) | `CheckboxItems` | 同上 |
+| 单选菜单(`selectMode="single"`) | `RadioItems` | 同上 |
+| 尺寸(`size` 三档) | trigger Button 自传 `size` — 见 [`button.stories.tsx`](../button/button.stories.tsx) `GroupSplitButtonSizes` | — |
+
+### MenuButton 专项 AI 生成纪律(在通用纪律之上叠加)
+
+- **trigger Button 用 `iconRight={<ChevronDown />}`**(而非 `icon=`/`<ChevronDown />` 平铺到 children) — 让 "label + ▼" 顺序与旧库 MenuButton 一致,且自动适应 RTL
+- **ghost / 暗色容器内不要单独发明 prop** — 直接 `variant="ghost"`(浅色容器)或在暗色作用域内 `variant="ghost"` 让其继承 `--accent`(本仓库走 OpenTrek tokens 主题作用域,不需要 prop 级 light/dark 二态)
+- **autoWidth 不要写成 `min-w-[var(--radix-dropdown-menu-trigger-width)]`** — 会触发 `teamix-evo/no-arbitrary-tw-value` lint 告警;统一用 `style={{ minWidth: 'var(--radix-dropdown-menu-trigger-width)' }}` inline style
+- **不要手控 `open` state 实现 `onItemClick` 全局回调** — 每个 Item 用 `onSelect`,Radix 默认会自动关闭弹层

package/src/components/dropdown-menu/dropdown-menu.stories.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
-import { LogOut, Settings, User, Cloud, Github } from 'lucide-react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ChevronDown, LogOut, Settings, User, Cloud, Github } from 'lucide-react';
 import {
   DropdownMenu,
   DropdownMenuTrigger,
@@ -12,6 +12,10 @@ import {
   DropdownMenuLabel,
   DropdownMenuSeparator,
   DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+  DropdownMenuGroup,
 } from './dropdown-menu';
 import { Button } from '@/components/button/button';
 
@@ -19,6 +23,14 @@ const meta: Meta<typeof DropdownMenuContent> = {
   title: '导航 · Navigation/DropdownMenu',
   component: DropdownMenuContent,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'DropdownMenu 下拉菜单 —— 按钮 / 头像 / 溢出按钮触发一组能被选择、勾选或切换的动作。Radix `DropdownMenu` 内核 + shadcn 原子，**对齐 antd `Dropdown`** 为动作菜单提供完整语义化原语，对齐 shadcn 的 `DropdownMenuItem` / `DropdownMenuCheckboxItem` / `DropdownMenuRadioItem` / `DropdownMenuSub` / `DropdownMenuShortcut`，并补足 `disabled` / `inset` / 嵌套子菜单。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/tokens`，无 mock。',
+      },
+    },
+  },
 };
 
 export default meta;
@@ -110,3 +122,77 @@ export const RadioItems: Story = {
     );
   },
 };
+
+export const WithSubMenu: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="outline">更多动作</Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent className="w-56">
+        <DropdownMenuLabel>项目</DropdownMenuLabel>
+        <DropdownMenuSeparator />
+        <DropdownMenuGroup>
+          <DropdownMenuItem>新建</DropdownMenuItem>
+          <DropdownMenuItem>复制</DropdownMenuItem>
+          <DropdownMenuItem>重命名…</DropdownMenuItem>
+        </DropdownMenuGroup>
+        <DropdownMenuSeparator />
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger>分享到</DropdownMenuSubTrigger>
+          <DropdownMenuSubContent>
+            <DropdownMenuItem>邮件</DropdownMenuItem>
+            <DropdownMenuItem>消息</DropdownMenuItem>
+            <DropdownMenuItem>复制链接</DropdownMenuItem>
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger>导出为</DropdownMenuSubTrigger>
+          <DropdownMenuSubContent>
+            <DropdownMenuItem>PDF</DropdownMenuItem>
+            <DropdownMenuItem>Markdown</DropdownMenuItem>
+            <DropdownMenuItem disabled>HTML（即将支持）</DropdownMenuItem>
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  ),
+};
+
+export const DisabledItems: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="outline">查看禁用项</Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent className="w-56">
+        <DropdownMenuItem>可点击</DropdownMenuItem>
+        <DropdownMenuItem disabled>不可点击（disabled）</DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem>另一个可点击项</DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  ),
+};
+
+export const SplitButtonTrigger: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="inline-flex isolate [&>*:not(:first-child)]:rounded-l-none [&>*:not(:last-child)]:rounded-r-none [&>*:not(:first-child)]:-ml-px hover:[&>*]:z-10 focus-visible:[&>*]:z-10">
+      <Button>保存</Button>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button size="icon" icon={<ChevronDown />} aria-label="更多保存选项" />
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem>保存为草稿</DropdownMenuItem>
+          <DropdownMenuItem>保存并发布</DropdownMenuItem>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem>另存为…</DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  ),
+};

package/src/components/dropdown-menu/dropdown-menu.tsx

@@ -20,7 +20,7 @@ const DropdownMenuSubTrigger = React.forwardRef<
   <DropdownMenuPrimitive.SubTrigger
     ref={ref}
     className={cn(
-      'flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-accent data-[state=open]:bg-accent [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+      'flex cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-xs outline-none focus:bg-accent data-[state=open]:bg-accent [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
       inset && 'pl-8',
       className,
     )}
@@ -40,7 +40,7 @@ const DropdownMenuSubContent = React.forwardRef<
   <DropdownMenuPrimitive.SubContent
     ref={ref}
     className={cn(
-      'z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
+      'z-50 min-w-menu overflow-hidden rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
       className,
     )}
     {...props}
@@ -49,16 +49,31 @@ const DropdownMenuSubContent = React.forwardRef<
 DropdownMenuSubContent.displayName =
   DropdownMenuPrimitive.SubContent.displayName;
 
+/**
+ * `onCloseAutoFocus` 默认 `preventDefault` — 阻止 Radix 关闭时把焦点程序化
+ * restore 回 trigger。
+ *
+ * 原因:Chromium/Safari 把"程序化 restore 的 focus"判定为非鼠标焦点 → 触发
+ * `:focus-visible` → trigger(尤其是 SplitButton 右侧 ChevronDown 这类只有
+ * 下拉箭头的 Button)在关闭后残留蓝色 ring,与用户"鼠标点完已经失焦了"的
+ * 视觉预期冲突。对齐 antd `Dropdown.Button` / cloud-design `SplitButton` 的
+ * 鼠标体感:关闭后无残留 ring。
+ *
+ * 取舍:键盘 Esc 关闭后焦点也不会 restore 回 trigger,而是落到 body(下一次
+ * Tab 从文档头开始)。这是为视觉体感做的可达性轻微降级 — 业务侧需要保留
+ * restore 行为时,显式传 `onCloseAutoFocus` 即可完全覆盖默认。
+ */
 const DropdownMenuContent = React.forwardRef<
   React.ElementRef<typeof DropdownMenuPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
->(({ className, sideOffset = 4, ...props }, ref) => (
+>(({ className, sideOffset = 4, onCloseAutoFocus, ...props }, ref) => (
   <DropdownMenuPrimitive.Portal>
     <DropdownMenuPrimitive.Content
       ref={ref}
       sideOffset={sideOffset}
+      onCloseAutoFocus={onCloseAutoFocus ?? ((event) => event.preventDefault())}
       className={cn(
-        'z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+        'z-50 min-w-menu overflow-hidden rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
         className,
       )}
       {...props}
@@ -76,7 +91,7 @@ const DropdownMenuItem = React.forwardRef<
   <DropdownMenuPrimitive.Item
     ref={ref}
     className={cn(
-      'relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+      'relative flex cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-xs outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
       inset && 'pl-8',
       className,
     )}
@@ -92,7 +107,7 @@ const DropdownMenuCheckboxItem = React.forwardRef<
   <DropdownMenuPrimitive.CheckboxItem
     ref={ref}
     className={cn(
-      'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      'relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-xs outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
       className,
     )}
     checked={checked}
@@ -116,7 +131,7 @@ const DropdownMenuRadioItem = React.forwardRef<
   <DropdownMenuPrimitive.RadioItem
     ref={ref}
     className={cn(
-      'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      'relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-xs outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
       className,
     )}
     {...props}
@@ -140,7 +155,7 @@ const DropdownMenuLabel = React.forwardRef<
   <DropdownMenuPrimitive.Label
     ref={ref}
     className={cn(
-      'px-2 py-1.5 text-sm font-semibold',
+      'px-2 py-1.5 text-xs font-semibold',
       inset && 'pl-8',
       className,
     )}
@@ -159,8 +174,7 @@ const DropdownMenuSeparator = React.forwardRef<
     {...props}
   />
 ));
-DropdownMenuSeparator.displayName =
-  DropdownMenuPrimitive.Separator.displayName;
+DropdownMenuSeparator.displayName = DropdownMenuPrimitive.Separator.displayName;
 
 const DropdownMenuShortcut = ({
   className,

package/src/components/ellipsis/ellipsis.meta.md

@@ -0,0 +1,87 @@
+---
+id: ellipsis
+name: Ellipsis
+displayName: 截断文本
+type: component
+category: data-display
+since: 0.2.0
+package: '@teamix-evo/ui'
+---
+
+# Ellipsis 截断文本
+
+单行 / 多行文本截断 + 渐变遮罩 + 溢出时自动 hover tooltip。对齐《Teamix UI 表单设计规范》§八 "内容显示不完全 — 截断 + 渐变遮罩 + hover tooltip 三件套"。
+
+## When to use
+
+- 表格单元格、Field 详情值、Tag、面包屑等横向宽度受限场景
+- Label / Description 长文案需要在固定宽度下完整可读(hover 看全)
+- 任何"窄列展示长字符串"的位置(对齐规范第八节示例)
+
+## When NOT to use
+
+- 容器永远不会溢出 → 直接 `<span>` / `<p>`,不引入额外组件
+- 需要"逐字符显示且可换行" → 用普通段落
+- 富文本(含 button / link 等交互) → Tooltip 与子级事件可能冲突,自行组合 Tooltip + truncate
+
+## Props
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `tooltip` | `React.ReactNode` | – | – | 超长时显示的 tooltip 文本 — 不传时自动用 children 的纯文本(优先)或 `title` 属性。 显示规则:仅当实际渲染时检测到溢出(scrollWidth > clientWidth 或 scrollHeight > clientHeight)才挂载 Tooltip。 |
+| `lines` | `number` | `1` | – | 多行截断行数。传入数字 >1 时走 `-webkit-line-clamp` 多行模式;否则单行 truncate。 |
+| `fade` | `boolean` | `true` | – | 是否在文本右侧叠加渐变遮罩(对齐《Teamix UI 表单设计规范》§八 "截断 + 渐变遮罩 + hover tooltip 三件套")。 默认开启;在容器无溢出时 mask 自动隐藏(scrollWidth ≤ clientWidth)。 |
+| `tooltipSide` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | – | Tooltip 弹出方向。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add ellipsis` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `tooltip` | component | 文字提示气泡 — Radix Tooltip + antd arrow/placement(side) 并集 + cloud-design Balloon 双变体(default 深底 / light 白底) + 一行 wrapper API |
+
+### npm 依赖
+
+_无 — 本组件不依赖任何 npm 包。_
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **不要手写 `truncate` + `<Tooltip>`**:直接用 `<Ellipsis>`,组件内置 ResizeObserver 检测溢出,仅溢出时挂 Tooltip(避免短文本也弹)
+- **多行截断走 `lines` prop**:`<Ellipsis lines={2}>`,不要手写 `-webkit-line-clamp` className
+- **`fade` 默认开启**:渐变遮罩仅在溢出时显示;关掉只走纯 ellipsis 可设 `fade={false}`
+- **tooltip 内容兜底**:不传 `tooltip` 时自动用 children 作为 tooltip 文本(适合纯文本场景);若 children 含 JSX,显式传 `tooltip="..."`
+
+## Examples
+
+```tsx
+import { Ellipsis } from '@/components/ui/ellipsis';
+
+// 单行 + 渐变遮罩 + 自动 tooltip
+<div className="w-32">
+  <Ellipsis>这一段超长文本会自动截断、右侧带渐变遮罩,hover 弹 tooltip 看全文</Ellipsis>
+</div>
+
+// 多行
+<div className="w-48">
+  <Ellipsis lines={2}>段落多行截断的示例文本,超过两行后剩余内容会被裁剪。</Ellipsis>
+</div>
+
+// 显式 tooltip 内容(child 含 JSX 时常用)
+<Ellipsis tooltip="完整路径:zhao.yu > 公共部门 > 财务部">
+  zhao.yu &gt; 公共部门 &gt; 财务部
+</Ellipsis>
+
+// 详情表格场景
+<Field orientation="horizontal" inputWidth="m">
+  <FieldLabel className="min-w-24 shrink-0 text-muted-foreground">备注</FieldLabel>
+  <Ellipsis className="flex-1 text-xs">{remark}</Ellipsis>
+</Field>
+```

package/src/components/ellipsis/ellipsis.stories.tsx

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Ellipsis } from './ellipsis';
+
+const meta = {
+  title: 'Data Display / Ellipsis',
+  component: Ellipsis,
+  parameters: { layout: 'centered' },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Ellipsis>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** 单行截断 + 渐变遮罩 + 自动 tooltip(对齐规范 §八)。 */
+export const Default: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-48 rounded-md border border-border bg-card p-3">
+      <Ellipsis>
+        这是一段超长文本,容器宽度有限自动截断并右侧加渐变遮罩,hover 弹 tooltip 看全文
+      </Ellipsis>
+    </div>
+  ),
+};
+
+/** 不会溢出时,不挂 tooltip 也不显示渐变。 */
+export const NoOverflow: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-64 rounded-md border border-border bg-card p-3">
+      <Ellipsis>短文本不溢出</Ellipsis>
+    </div>
+  ),
+};
+
+/** 多行截断(`lines={2}`)。 */
+export const MultiLine: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-72 rounded-md border border-border bg-card p-3">
+      <Ellipsis lines={2}>
+        段落多行截断的示例文本。当容器宽度受限且文本超过指定行数时,剩余内容会被裁剪,
+        鼠标 hover 弹出完整内容。这是规范 §八 "内容显示不完全" 的标准做法之一。
+      </Ellipsis>
+    </div>
+  ),
+};
+
+/** 关闭渐变遮罩,仅保留 ellipsis。 */
+export const NoFade: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-48 rounded-md border border-border bg-card p-3">
+      <Ellipsis fade={false}>
+        这是一段超长文本,关闭渐变遮罩,仅保留省略号
+      </Ellipsis>
+    </div>
+  ),
+};
+
+/** 显式 tooltip 内容(JSX children 场景)。 */
+export const CustomTooltip: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-48 rounded-md border border-border bg-card p-3">
+      <Ellipsis tooltip="完整路径:zhao.yu > 公共部门 > 财务部">
+        zhao.yu &gt; 公共部门 &gt; 财务部
+      </Ellipsis>
+    </div>
+  ),
+};