@teamix-evo/ui 0.3.0 → 0.5.0

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

@@ -1,335 +0,0 @@
----
-id: button
-name: Button
-displayName: 按钮
-type: component
-category: general
-since: 0.1.0
-package: '@teamix-evo/ui'
----
-
-# Button 按钮
-
-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"` / `"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
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`button.tsx`](./button.tsx) 的 `ButtonProps` interface JSDoc。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `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` / `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 -->
-
-## 依赖
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
-
-<!-- auto:deps:begin -->
-### 同库依赖
-
-> `teamix-evo ui add button` 时,以下 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 依赖
-
-> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
-
-```bash
-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 -->
-
-> 除上述声明的 props 外,Button 同时透传所有原生 `<button>` 属性(`onClick` / `type` / `aria-*` / ...);`asChild=true` 时透传至 Radix Slot 的子元素。
-
-## 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 库。
-- **双 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"` 重复。
-- **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
-
-```tsx
-// 基本
-<Button>提交</Button>
-
-// 危险 + 加载
-<Button variant="destructive" loading>删除中</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