@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/breadcrumb/breadcrumb.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Slash } from 'lucide-react';
 import {
   Breadcrumb,
@@ -9,11 +9,25 @@ import {
   BreadcrumbSeparator,
   BreadcrumbEllipsis,
 } from './breadcrumb';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/dropdown-menu/dropdown-menu';
 
 const meta: Meta<typeof Breadcrumb> = {
   title: '导航 · Navigation/Breadcrumb',
   component: Breadcrumb,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '面包屑 —— 在多层级页面中显示当前位置并提供回溯路径。shadcn 纯组合原子(`Breadcrumb` / `BreadcrumbList` / `BreadcrumbItem` / `BreadcrumbLink` / `BreadcrumbPage` / `BreadcrumbSeparator` / `BreadcrumbEllipsis`) + 对齐 antd `Breadcrumb` 的 `separator` 自定义并集,差异点是不收 antd `routes` / `itemRender` 数组式 API,改走 children 组合 + `asChild` 适配 React Router / Next.js `<Link>`:`asChild`、`separator`(默认 `ChevronRight`)、`BreadcrumbEllipsis` 折叠。视觉走 OpenTrek semantic tokens,字号 `text-sm`、普通项 `text-muted-foreground`、当前项 `text-foreground`、链接 hover 升至 `text-foreground`,所有样式来自 `@teamix-evo/tokens`,无 mock。',
+      },
+    },
+  },
 };
 
 export default meta;
@@ -40,7 +54,15 @@ export const Default: Story = {
 };
 
 export const CustomSeparator: Story = {
-  parameters: { controls: { disable: true } },
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '通过 `<BreadcrumbSeparator>` 的 children 覆盖默认 `ChevronRight`,可换为 `Slash` / 文字 / 任意 ReactNode。',
+      },
+    },
+  },
   render: () => (
     <Breadcrumb>
       <BreadcrumbList>
@@ -50,6 +72,12 @@ export const CustomSeparator: Story = {
         <BreadcrumbSeparator>
           <Slash />
         </BreadcrumbSeparator>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/projects">项目</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator>
+          <span>·</span>
+        </BreadcrumbSeparator>
         <BreadcrumbItem>
           <BreadcrumbPage>当前页</BreadcrumbPage>
         </BreadcrumbItem>
@@ -58,8 +86,16 @@ export const CustomSeparator: Story = {
   ),
 };
 
-export const Ellipsis: Story = {
-  parameters: { controls: { disable: true } },
+export const Collapsed: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '层级超过 4 级时使用 `<BreadcrumbEllipsis />` 折叠中间项,避免横向空间撑爆;可叠加 `DropdownMenu` 在悬停时展开完整路径。',
+      },
+    },
+  },
   render: () => (
     <Breadcrumb>
       <BreadcrumbList>
@@ -82,3 +118,90 @@ export const Ellipsis: Story = {
     </Breadcrumb>
   ),
 };
+
+export const MaxNodeCollapse: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '对齐旧库 `maxNode` 自动折叠能力 — 把 `<BreadcrumbEllipsis />` 包到 `<DropdownMenu>` 触发器里,点击 `…` 弹出被折叠层级列表(单击跳转)。组合优于专门 prop:可任意控制弹层位置 / 触发方式 / 自定义弹出 UI。',
+      },
+    },
+  },
+  render: () => {
+    const all = [
+      { label: '首页', href: '/' },
+      { label: 'Whatever', href: '/whatever' },
+      { label: 'All Categories', href: '/all' },
+      { label: "Women's Clothing", href: '/women' },
+      { label: 'Blouses & Shirts', href: '/blouses' },
+    ];
+    const head = all[0]!;
+    const middle = all.slice(1, -1);
+    return (
+      <Breadcrumb>
+        <BreadcrumbList>
+          <BreadcrumbItem>
+            <BreadcrumbLink href={head.href}>{head.label}</BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <DropdownMenu>
+              <DropdownMenuTrigger
+                aria-label="展开折叠层级"
+                className="rounded-sm focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+              >
+                <BreadcrumbEllipsis />
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="start">
+                {middle.map((it) => (
+                  <DropdownMenuItem key={it.href} asChild>
+                    <a href={it.href}>{it.label}</a>
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbPage>T-shirts</BreadcrumbPage>
+          </BreadcrumbItem>
+        </BreadcrumbList>
+      </Breadcrumb>
+    );
+  },
+};
+
+export const WithRouterLink: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '通过 `asChild` 把 `BreadcrumbLink` 替换为路由组件(此处用 `<a>` 演示),保持视觉与无障碍语义一致。',
+      },
+    },
+  },
+  render: () => (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink asChild>
+            <a href="/">首页</a>
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink asChild>
+            <a href="/orgs">组织</a>
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>成员管理</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  ),
+};

package/src/components/breadcrumb/breadcrumb.tsx

@@ -6,14 +6,19 @@ import { cn } from '@/utils/cn';
 
 export interface BreadcrumbProps extends React.ComponentPropsWithoutRef<'nav'> {
   /**
-   * 自定义分隔符(antd `separator` 并集)。每个 `<BreadcrumbSeparator />` 默认渲染 `<ChevronRight />`,
-   * 通过设置 children 可全局覆盖。
+   * 自定义全局分隔符(antd `separator` 并集)。仅作类型层占位 —
+   * 实际渲染由 `<BreadcrumbSeparator>` 控制,默认 lucide `ChevronRight`,
+   * 通过 `<BreadcrumbSeparator>{节点}</BreadcrumbSeparator>` 覆盖单个分隔符。
+   * @default <ChevronRight />
    */
   separator?: React.ReactNode;
 }
 
 const Breadcrumb = React.forwardRef<HTMLElement, BreadcrumbProps>(
-  ({ ...props }, ref) => <nav ref={ref} aria-label="breadcrumb" {...props} />,
+  // separator 仅作 API 占位,不下传到 DOM,避免触发未知属性警告。
+  ({ separator: _separator, ...props }, ref) => (
+    <nav ref={ref} aria-label="breadcrumb" {...props} />
+  ),
 );
 Breadcrumb.displayName = 'Breadcrumb';
 
@@ -24,7 +29,7 @@ const BreadcrumbList = React.forwardRef<
   <ol
     ref={ref}
     className={cn(
-      'flex flex-wrap items-center gap-1.5 text-sm text-muted-foreground sm:gap-2.5',
+      'flex flex-wrap items-center gap-1.5 text-xs text-muted-foreground sm:gap-2.5',
       className,
     )}
     {...props}
@@ -46,7 +51,10 @@ BreadcrumbItem.displayName = 'BreadcrumbItem';
 
 export interface BreadcrumbLinkProps
   extends React.ComponentPropsWithoutRef<'a'> {
-  /** 用 Slot 渲染为子元素(常配合 React Router / Next.js Link)。 */
+  /**
+   * 用 Slot 渲染为子元素(常配合 React Router `<Link>` / Next.js `<Link>`)。
+   * @default false
+   */
   asChild?: boolean;
 }
 
@@ -56,7 +64,10 @@ const BreadcrumbLink = React.forwardRef<HTMLAnchorElement, BreadcrumbLinkProps>(
     return (
       <Comp
         ref={ref}
-        className={cn('transition-colors hover:text-foreground', className)}
+        className={cn(
+          'text-xs text-muted-foreground transition-colors hover:text-foreground',
+          className,
+        )}
         {...props}
       />
     );
@@ -73,7 +84,7 @@ const BreadcrumbPage = React.forwardRef<
     role="link"
     aria-disabled="true"
     aria-current="page"
-    className={cn('font-normal text-foreground', className)}
+    className={cn('text-xs font-normal text-foreground', className)}
     {...props}
   />
 ));
@@ -87,7 +98,10 @@ const BreadcrumbSeparator = ({
   <li
     role="presentation"
     aria-hidden="true"
-    className={cn('[&>svg]:size-3.5', className)}
+    className={cn(
+      'inline-flex items-center text-muted-foreground [&>svg]:size-3.5',
+      className,
+    )}
     {...props}
   >
     {children ?? <ChevronRight />}

package/src/components/button/button.meta.md

@@ -1,28 +1,34 @@
 ---
 id: button
 name: Button
+displayName: 按钮
 type: component
-category: foundation
+category: general
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Button
+# Button 按钮
 
-通用按钮 — 基于 shadcn/ui Button 二次封装,补齐 antd 的 `loading / icon / shape / block` 等开箱即用能力。
-按钮文本、aria 状态由消费方提供;视觉与可访问性由组件保障。
+Button 按钮 —— 触发即时动作的最基础交互原子(提交、删除、跳转、加载)。基于 shadcn/ui 实现 + cloud-design 能力并集:`variant`(7 档形态)、`color`(ADR 0021 语义色双 prop)、`size`(sm/md/lg/icon,可由 `<ButtonGroup size>` 注入)、`shape`(default/round/circle/square)、`loading`(spinner + 自动 disabled + aria-busy)、`icon` + `iconRight`(双 slot)、`block`(撑满)、`asChild`(渲染为任意元素)、`disabledTooltip`(禁用解释)。**组件合一**:`ButtonGroup` + `ButtonGroupText` 同文件导出,等价 antd `Space.Compact`,支持 SplitButton、Toolbar、Input addon 等组合形态,通过 `<ButtonGroup size>` + React.Context 自顶向下注入子 Button 尺寸。
 
 ## When to use
 
 - 表单提交、对话框确认、列表行操作等触发性交互
-- 需要明确反馈"按下→处理中→完成"过程的场景(用 `loading`)
-- 需要纯图标按钮时(用 `size="icon"` + `shape="circle"` 组合)
+- 需要明确反馈"按下 → 处理中 → 完成"过程的场景(用 `loading`)
+- 需要纯图标按钮时(用 `size="icon"` + `shape="circle"` / `"square"` 组合)
+- 需要 prefix + suffix 双图标时(用 `icon` + `iconRight` 双 slot)
+- 需要 warning + outline 等"语义 × 视觉"双维度表达 → 用 `variant="outline" color="destructive"`(ADR 0021)
+- 禁用按钮需要解释原因 → 用 `disabled` + `disabledTooltip`
+- **SplitButton / Toolbar / Input addon 等组合** → 用 `ButtonGroup` 包裹
 
 ## When NOT to use
 
 - 仅做导航而无副作用 → 用 `<a>` 或路由 `Link`(必要时配 `variant="link"` 视觉)
 - 切换布尔状态 → 用 `Switch` / `Toggle`,不要用按钮模拟
 - 需要承载多行说明文字 → 用 `Card` 等容器组件
+- 需要全屏阻塞加载 → 用 `Spinner` + 遮罩,不要用 `loading` 撑大按钮
+- 互斥单选切换 → `ToggleGroup`(语义更强),不要用 `ButtonGroup` 模拟
 
 ## Props
 
@@ -31,14 +37,17 @@ package: "@teamix-evo/ui"
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'dashed' \| 'ghost' \| 'link'` | `"default"` | – | 视觉风格,语义按 design token 走。 |
-| `size` | `'sm' \| 'default' \| 'lg' \| 'icon'` | `"default"` | – | 尺寸,`icon` 为正方形纯图标按钮。 |
-| `shape` | `'default' \| 'round' \| 'circle'` | `"default"` | – | 形状,`circle` 配 `size="icon"` 得圆形按钮。 |
+| `variant` | `ButtonVariant` | `"default"` | – | 视觉风格,语义按 design token 走。 |
+| `color` | `ButtonColor` | `"default"` | – | 语义色(ADR 0021)。与 `variant` 双 prop 组合表达"语义 × 视觉"两个维度, 例:`variant="outline" color="destructive"` 实现旧库 warning+outline 形态; `variant="ghost" color="destructive"` 实现轻量危险删除按钮。 |
+| `size` | `ButtonSize` | `"default"` | – | 尺寸。`md` 与 `default` 等价,`icon` 为正方形纯图标按钮。 若包在 `<ButtonGroup size="..">` 中且本地未显式传值,自动继承 group 的 size。 |
+| `shape` | `ButtonShape` | `"default"` | – | 形状。`circle` / `square` 必须配 `size="icon"`。 |
 | `block` | `boolean` | `false` | – | `true` 时撑满父容器宽度。 |
-| `asChild` | `boolean` | `false` | – | 用 Radix Slot 模式渲染为子元素;此时 `loading` / `icon` 被忽略。 |
-| `loading` | `boolean` | `false` | – | 显示自旋 spinner,自动 disabled,保留视觉宽度。 |
-| `icon` | `React.ReactNode` | – | – | 前置 / 后置图标(来自 `lucide-react`)。loading 时被 spinner 替换。 |
-| `iconPosition` | `'start' \| 'end'` | `"start"` | – | 图标 / spinner 相对文本的位置。 |
+| `asChild` | `boolean` | `false` | – | 用 Radix Slot 模式渲染为子元素;此时 `loading` / `icon` / `iconRight` 被忽略。 |
+| `loading` | `boolean` | `false` | – | 显示自旋 spinner,自动 `disabled` + `aria-busy=true`,保留视觉宽度。 |
+| `icon` | `React.ReactNode` | – | – | 文本左侧图标。推荐 `lucide-react`。loading 时被 spinner 替换。 |
+| `iconRight` | `React.ReactNode` | – | – | 文本右侧图标。推荐 `lucide-react`。 |
+| `iconPosition` | `'start' \| 'end'` | `"start"` | – | 兼容旧 API:`icon` 相对文本的位置;新代码请直接使用 `icon` / `iconRight` 双 slot。 |
+| `disabledTooltip` | `React.ReactNode` | – | – | `disabled=true` 时的禁用解释文本。仅在 `disabled` 同时存在时生效: 内部包一层 `cursor-not-allowed` wrapper + Tooltip,把 button pointer-events 关闭后由 wrapper 拾取 hover。 不传则保持原生 disabled 行为。 |
 | `children` | `React.ReactNode` | – | – | 按钮文本 / 内容。 |
 <!-- auto:props:end -->
 
@@ -54,13 +63,14 @@ package: "@teamix-evo/ui"
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `tooltip` | component | 文字提示气泡 — Radix Tooltip + antd arrow/placement(side) 并集 + cloud-design Balloon 双变体(default 深底 / light 白底) + 一行 wrapper API |
 
 ### npm 依赖
 
 > 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
 
 ```bash
-pnpm add @radix-ui/react-slot@^1.1.0 class-variance-authority@^0.7.0 lucide-react@^0.460.0
+pnpm add @radix-ui/react-slot@^1.1.0 @radix-ui/react-tooltip@^1.1.0 class-variance-authority@^0.7.0 lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
@@ -69,11 +79,17 @@ pnpm add @radix-ui/react-slot@^1.1.0 class-variance-authority@^0.7.0 lucide-reac
 ## AI 生成纪律
 
 - **variant 语义**:危险动作(删除/重置)用 `destructive`;次要动作(取消)用 `secondary` 或 `ghost`;表单主操作用 `default`;**不要**用 inline 任意值(如 `bg-[#ff0000]`)。
+- **color 双 prop(ADR 0021)**:语义色与视觉风格正交 —— 旧库 `warning + outline` 用 `variant="outline" color="destructive"` 表达,**不要**新增 `warning` variant;同理 `variant="ghost" color="destructive"` = 轻量删除按钮。
 - **icon 来源**:固定从 `lucide-react` import,**不要**内联 SVG,不要混用其他 icon 库。
-- **loading + disabled**:写 `loading` 即可,**不要**额外手动加 `disabled`,组件已自动处理。
-- **shape="circle"**:必须配 `size="icon"` 一起使用,否则视觉会变形(扁圆)。
+- **双 slot 优于 iconPosition**:新代码用 `icon` + `iconRight` 双 slot;`iconPosition` 仅为兼容旧调用保留,**不要**在新代码中使用。
+- **loading + disabled**:写 `loading` 即可,**不要**额外手动加 `disabled`,组件已自动处理 `aria-busy`。
+- **disabledTooltip 必须配 disabled**:仅在 `disabled=true` 时生效,不要单独使用;**不要**用 `title` 原生 attr 模拟,会失去样式与 a11y。
+- **shape="circle" / "square"**：独立图标按钮必须配 `size="icon"`；SplitButton trigger 可仅用 `shape="square"` 不传 size，从 ButtonGroup 继承尺寸。
+- **icon-only 必带 `aria-label`**:无 children 仅图标的按钮必须传 `aria-label` 给读屏。
 - **block**:`true` 时按钮撑满,**不要**再用 `className="w-full"` 重复。
-- **asChild**:仅当需要渲染为 `<a>` / `<Link>` 等其他元素时启用,且**不要**与 `loading` / `icon` 同时使用,会被忽略。
+- **size 别用任意值**:用枚举档位(`sm`/`md`/`lg`/`icon`),**不要**写 `className="h-[30px]"`,会破坏 24/32/36 三档体系的视觉一致性(同行 Input/Select 等表单原子混排时高度对不齐)。
+- **圆角靠 cva**:不要在外部传 `className="rounded-xl"` 覆盖默认圆角,默认 `rounded-md`(Tailwind v4 标准 namespace,uni-manager 下 = 2px / opentrek 下 = 6px) 已对齐主题语义。不使用自定义 `--radius-button` 组件级别名 token。
+- **asChild 互斥**:仅当渲染为 `<a>` / `<Link>` 等其他元素时启用,且**不要**与 `loading` / `icon` / `iconRight` 同时使用,会被忽略。
 
 ## Examples
 
@@ -84,15 +100,236 @@ pnpm add @radix-ui/react-slot@^1.1.0 class-variance-authority@^0.7.0 lucide-reac
 // 危险 + 加载
 <Button variant="destructive" loading>删除中</Button>
 
-// 图标 + 后置
-<Button icon={<ChevronRight />} iconPosition="end">下一步</Button>
+// ADR 0021 双 prop —— warning + outline 形态
+<Button variant="outline" color="destructive" icon={<Trash />}>删除</Button>
 
-// 圆形图标按钮
+// 禁用 + 解释文案
+<Button disabled disabledTooltip="无权限操作,请联系管理员">发布</Button>
+
+// 双 slot 图标
+<Button icon={<Search />} iconRight={<ArrowRight />}>搜索文档</Button>
+
+// 圆形 / 方形图标按钮
 <Button size="icon" shape="circle" variant="ghost" icon={<X />} aria-label="关闭" />
+<Button size="icon" shape="square" variant="outline" icon={<Search />} aria-label="搜索" />
 
 // 块级
 <Button block>登录</Button>
 
+// 三档尺寸(uni-manager: 24/32/36)
+<Button size="sm">紧凑</Button>
+<Button size="md">默认</Button>
+<Button size="lg">强调</Button>
+
 // 作为链接
 <Button asChild variant="link"><a href="/docs">查看文档</a></Button>
 ```
+
+---
+
+## ButtonGroup 按钮组
+
+按钮组 — **等价 antd `Space.Compact`**(v6 替代旧 `Button.Group`)+ **cloud-design `SplitButton` 形态并集**。把多个按钮 / 输入框"粘"在一起共享边线,典型场景:**SplitButton**(主按钮 + 右侧 ChevronDown 下拉箭头按钮 + DropdownMenu 触发)、Toolbar、Input + Button 拼装。配 `ButtonGroupText` 渲染只读 addon 文本。通过 `size` prop + React.Context 把尺寸下发给未显式传 size 的子 Button。
+
+### When to use
+
+- **SplitButton**(主操作 + 右侧下拉箭头)— 默认主动作 + 备选动作集合(发布/保存/编辑等)
+- Toolbar(同语义按钮集合,如 "上一页 / 下一页 / 跳转")
+- Input + 按钮拼装(搜索框、单位选择)
+- 多档切换显示(配 `Toggle` 也可,但 ToggleGroup 更专精)
+
+### When NOT to use
+
+- 互斥单选切换 → `ToggleGroup`(语义更强)
+- 不相干的按钮 → 普通 `Button` + flex gap
+
+### Props
+
+| 名称          | 类型                         | 默认值         | 必填 | 说明                                                                                                                                        |
+| ------------- | ---------------------------- | -------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `"horizontal"` | –    | 排列方向。                                                                                                                                  |
+| `attached`    | `boolean`                    | `true`         | –    | 是否把按钮"粘"在一起去除边距(antd `Space.Compact` 等价行为)— `false` 时按钮间留 8px gap。                                                   |
+| `size`        | `ButtonSize`                 | –              | –    | 统一下发给子 Button 的尺寸;子 Button 若显式传了 `size` 则以子值优先。通过 React.Context 注入,跨 Slot 透传无效(asChild 自定义渲染不会拿到)。 |
+
+### AI 生成纪律
+
+- **`attached=true`(默认)子项之间边线共享**:第一项 / 最后一项保留外侧圆角,中间项去除圆角;**不要**在内部再设 `rounded`
+- **混用 Input + Button**:把 Input 直接放进 ButtonGroup,它的 `rounded-md` 也会被组件圈圆角(无需特殊处理)
+- **`ButtonGroupText`** 用于只读 addon(`https://` 前缀、`/月` 后缀);**不要**把它当按钮点击
+- **vertical 模式** 适合工具栏侧边小集合,horizontal 是默认推荐
+- **size 下发优先级**:`<ButtonGroup size="sm">` 注入 sm,子 Button 显式传 `size` 时以子值优先,Context 不强制覆盖
+- **不要**在 ButtonGroup 内放 spinner / icon-only 与文字按钮混排时,高度需要靠 button `size` 对齐 — 子项尺寸应一致;**推荐**用 `<ButtonGroup size>` 统一注入而不是逐个传
+
+### Examples
+
+```tsx
+import { Button, ButtonGroup, ButtonGroupText } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import {
+  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem,
+} from '@/components/ui/dropdown-menu';
+import { ChevronDown } from 'lucide-react';
+
+// Split button (纯形态 - 仅 icon 占位)
+<ButtonGroup>
+  <Button>保存</Button>
+  <Button shape="square" icon={<ChevronDown />} aria-label="更多" />
+</ButtonGroup>
+
+// Split button + DropdownMenu 完整形态
+<ButtonGroup>
+  <Button>发布</Button>
+  <DropdownMenu>
+    <DropdownMenuTrigger asChild>
+      <Button shape="square" icon={<ChevronDown />} aria-label="更多发布选项" />
+    </DropdownMenuTrigger>
+    <DropdownMenuContent align="end">
+      <DropdownMenuItem>保存为草稿</DropdownMenuItem>
+      <DropdownMenuItem>定时发布</DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</ButtonGroup>
+
+// 通过 size 注入,子 Button 自动继承
+<ButtonGroup size="sm">
+  <Button variant="outline">继承 sm</Button>
+  <Button variant="outline">继承 sm</Button>
+  <Button variant="outline" size="lg">显式 lg(覆盖 Context)</Button>
+</ButtonGroup>
+
+// Toolbar
+<ButtonGroup>
+  <Button variant="outline">上一页</Button>
+  <Button variant="outline">1 / 10</Button>
+  <Button variant="outline">下一页</Button>
+</ButtonGroup>
+
+// 带 addon 文本
+<ButtonGroup>
+  <ButtonGroupText>https://</ButtonGroupText>
+  <Input defaultValue="example.com" className="rounded-l-none" />
+  <Button>访问</Button>
+</ButtonGroup>
+
+// 不粘连(留间距)
+<ButtonGroup attached={false}>
+  <Button variant="outline">取消</Button>
+  <Button>确定</Button>
+</ButtonGroup>
+```
+
+---
+
+## SplitButton 形态 — 旧库 API → 新组合映射
+
+新库 **不提供独立的 `SplitButton` 组件**。这是主动决策 — 旧库 cloud-design / antd `Dropdown.Button` 本质上是 `ButtonGroup attached + Button + DropdownMenu` 的组合,因此面向业务只暴露组合写法可以:
+
+- 统一与其他 SplitButton-like 组合(Input + Button addon 、Toolbar)的结构语法
+- 遵循 P1 “三层对齐”的原子/合成分层,不增加 wrapper 级套娃
+- 业务侧保留 DropdownMenu 子项类型全控(Item / CheckboxItem / RadioItem / Label / Separator 任意组装)
+
+以下是旧库 `SplitButton` 全 API 到新组合的逐项映射(拷贝可用):
+
+| 旧库 API · cloud-design SplitButton          | 新库组合写法                                                                                                                                                                                                                                |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `size: 'small' \| 'medium' \| 'large'`       | `<ButtonGroup size="sm" \| "md" \| "lg">` — 注入子 Button                                                                                                                                                                                   |
+| `type: 'normal' \| 'primary' \| 'secondary'` | `<Button variant="default" \| "secondary">`(primary == default,遵循 shadcn 语义)                                                                                                                                                            |
+| `label`                                      | `<Button>{label}</Button>` 的 children                                                                                                                                                                                                      |
+| `component: 'button' \| 'a'`                 | `<Button asChild>` + `<a href />`                                                                                                                                                                                                           |
+| `leftButtonProps`                            | 主 `<Button {...leftButtonProps}>` 直接 spread                                                                                                                                                                                              |
+| `triggerProps`                               | `<DropdownMenuTrigger asChild><Button {...triggerProps} /></DropdownMenuTrigger>`                                                                                                                                                           |
+| `defaultSelectedKeys`                        | `<DropdownMenuCheckboxItem defaultChecked>` / `<DropdownMenuRadioGroup defaultValue>`                                                                                                                                                       |
+| `selectedKeys`(受控)                         | `<DropdownMenuCheckboxItem checked onCheckedChange>` / `<DropdownMenuRadioGroup value onValueChange>`                                                                                                                                       |
+| `selectMode: 'single' \| 'multiple'`         | `single` → `RadioGroup` + `RadioItem`;`multiple` → `CheckboxItem`                                                                                                                                                                           |
+| `onSelect` / `onItemClick`                   | `<DropdownMenuItem onSelect>`(Radix 在 keyboard / click 都触发)                                                                                                                                                                             |
+| `visible` / `defaultVisible`                 | `<DropdownMenu open \| defaultOpen>`                                                                                                                                                                                                        |
+| `onVisibleChange`                            | `<DropdownMenu onOpenChange>`                                                                                                                                                                                                               |
+| `popupAlign`                                 | `<DropdownMenuContent align="start" \| "center" \| "end">`                                                                                                                                                                                  |
+| `popupStyle` / `popupClassName`              | `<DropdownMenuContent style className>`                                                                                                                                                                                                     |
+| `popupProps`                                 | `<DropdownMenuContent {...popupProps}>` 直接 spread                                                                                                                                                                                         |
+| `menuProps`                                  | 以各 `<DropdownMenu*>` 子项的 props 明确表达(避免黑盒透传)                                                                                                                                                                                  |
+| `autoWidth`(默认 true)                       | `<DropdownMenuContent style={{ minWidth: 'var(--radix-dropdown-menu-trigger-width)' }}>` — 读 Radix 暴露的 CSS 变量,只在需要时显式指定,默认遵 shadcn `min-w-[8rem]`(主动选 style 而非 Tailwind arbitrary,避免 `no-arbitrary-tw-value` 告警) |
+
+### 不修复清单(旧库能力不迁移的决策)
+
+| 旧库能力                    | 决策          | 理由                                                                                                                            |
+| --------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `popupTriggerType: 'hover'` | **不补**      | Radix DropdownMenu 不原生支持 hover 触发(设计上不符合无障碍/移动端语义)。业务需 hover 菜单请改用 `NavigationMenu` / `HoverCard` |
+| `ghost: 'light' \| 'dark'`  | **不补 prop** | ghost variant 靠主题作用域适配 — 黑底区域套 `[data-theme='dark']`,亮底不动。旧库双 prop 是主题能力不足时代的补丁                |
+| `followTrigger`(随滚动)     | **不补**      | Radix Portal 默认随触发路径滚动定位(`Floating UI` 多策略),无需额外 prop                                                         |
+| 独立 `<SplitButton>` 导出名 | **不加**      | 保留组合式 — 低抽象、高透明、与 Toolbar / Input addon 保持同一结构语法                                                          |
+
+### Examples
+
+```tsx
+import { Button, ButtonGroup } from '@/components/ui/button';
+import {
+  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent,
+  DropdownMenuItem, DropdownMenuSeparator,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel,
+} from '@/components/ui/dropdown-menu';
+import { ChevronDown } from 'lucide-react';
+
+// 完整形态(默认 click)
+<ButtonGroup>
+  <Button>发布</Button>
+  <DropdownMenu>
+    <DropdownMenuTrigger asChild>
+      <Button shape="square" icon={<ChevronDown />} aria-label="更多发布选项" />
+    </DropdownMenuTrigger>
+    <DropdownMenuContent align="end">
+      <DropdownMenuItem>保存为草稿</DropdownMenuItem>
+      <DropdownMenuItem>定时发布</DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <DropdownMenuItem>发布到多个渠道…</DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</ButtonGroup>
+
+// 多选形态(旧库 selectMode="multiple" 等价)
+<ButtonGroup>
+  <Button>发布到 N 个渠道</Button>
+  <DropdownMenu>
+    <DropdownMenuTrigger asChild>
+      <Button shape="square" icon={<ChevronDown />} aria-label="选择发布渠道" />
+    </DropdownMenuTrigger>
+    <DropdownMenuContent align="end">
+      <DropdownMenuLabel>发布渠道</DropdownMenuLabel>
+      <DropdownMenuSeparator />
+      <DropdownMenuCheckboxItem checked={web} onCheckedChange={setWeb}>Web 站点</DropdownMenuCheckboxItem>
+      <DropdownMenuCheckboxItem checked={mobile} onCheckedChange={setMobile}>移动端</DropdownMenuCheckboxItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</ButtonGroup>
+
+// 单选形态(旧库 selectMode="single" 等价)
+<ButtonGroup>
+  <Button>部署到 {envLabel}</Button>
+  <DropdownMenu>
+    <DropdownMenuTrigger asChild>
+      <Button shape="square" icon={<ChevronDown />} aria-label="切换环境" />
+    </DropdownMenuTrigger>
+    <DropdownMenuContent align="end">
+      <DropdownMenuRadioGroup value={env} onValueChange={setEnv}>
+        <DropdownMenuRadioItem value="dev">开发</DropdownMenuRadioItem>
+        <DropdownMenuRadioItem value="staging">预发</DropdownMenuRadioItem>
+        <DropdownMenuRadioItem value="prod">生产</DropdownMenuRadioItem>
+      </DropdownMenuRadioGroup>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</ButtonGroup>
+
+// autoWidth(弹层宽度跟随触发按钮)—默认不启,需要时读 Radix CSS 变量(主动选 style 避免 Tailwind arbitrary value 告警):
+<DropdownMenuContent style={{ minWidth: 'var(--radix-dropdown-menu-trigger-width)' }}>
+  ...
+</DropdownMenuContent>
+```
+
+### AI 生成纪律补充(SplitButton 专项)
+
+- **主按钮与下拉 trigger 的 `variant` 必须一致**(同为 `default` 或同为 `outline`),否则 attached 粘连后边线/背景错位,反衬能力下降
+- **下拉箭头 trigger 必须传 `aria-label`**(例 `"更多发布选项"`)— icon-only 读屏友好
+- **取消 trigger 残留 focus ring** 已在 [`dropdown-menu.tsx`](../dropdown-menu/dropdown-menu.tsx) 默认处理(`onCloseAutoFocus` 默认 preventDefault),业务侧不需手动覆盖
+- **不要用 `<Button onClick>` 手控打开下拉** — 用 `<DropdownMenuTrigger asChild>` 包裹让 Radix 接管键盘/aria 状态
+- **不要提取 `<SplitButton>` wrapper** — 违背该决策(本章开头说明),需复用请抽成业务项目内部的联合 hook 而非 UI 库 entry