@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/button/button.stories.tsx

@@ -1,31 +1,56 @@
 import type { ReactNode } from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
-import { ChevronRight, Download, Plus, Trash, X } from 'lucide-react';
-import { Button } from './button';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  ArrowRight,
+  ChevronDown,
+  ChevronRight,
+  Download,
+  Heart,
+  Plus,
+  Search,
+  Trash,
+  X,
+} from 'lucide-react';
+import { Button, ButtonGroup, ButtonGroupText } from './button';
+import { Input } from '@/components/input/input';
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuLabel,
+} from '@/components/dropdown-menu/dropdown-menu';
+import * as React from 'react';
 
 /**
- * Storybook Controls cannot edit React nodes directly, so we expose a string
- * key whose value is mapped to a real ReactNode via `mapping`. Editors see a
- * dropdown of icon names; the underlying prop receives the actual element.
+ * Storybook Controls 不能直接编辑 ReactNode,这里用字符串 key 通过 `mapping`
+ * 映射到真实 ReactNode — 编辑面板看到的是图标名下拉,实际 prop 收到 element。
  */
 const iconMap: Record<string, ReactNode> = {
   none: undefined,
+  arrowRight: <ArrowRight />,
   chevronRight: <ChevronRight />,
   download: <Download />,
+  heart: <Heart />,
   plus: <Plus />,
+  search: <Search />,
   trash: <Trash />,
   x: <X />,
 };
 
 const meta: Meta<typeof Button> = {
-  title: '基础原语 · Foundation/Button',
+  title: '通用 · General/Button',
   component: Button,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant)。className 走 OpenTrek semantic tokens,所有视觉来自 `@teamix-evo/design`,无 mock。',
+          'Button 按钮 —— 触发即时动作的最基础交互原子(提交、删除、跳转、加载)。shadcn 实现底座 + cloud-design 能力并集:`variant`(7 档形态)/ `color`(ADR 0021 语义色双 prop,与 variant 组合表达"语义×视觉")/ `size`(sm/md/lg/icon,可由 `<ButtonGroup size>` 注入)/ `shape`(default/round/circle/square)/ `loading`(自动 disabled+aria-busy+spinner)/ `icon` + `iconRight`(双 slot)/ `block`(撑满)/ `asChild`(Radix Slot 渲染为 `<a>` 等)/ `disabledTooltip`(禁用态解释文案,wrapper 拾取 hover)。组件合一:`ButtonGroup` + `ButtonGroupText` 同文件导出,等价 antd `Space.Compact`,支持 SplitButton、Toolbar、Input addon 等组合形态。视觉走 semantic tokens,圆角走 Tailwind 标准 `rounded-md`(消费 `--radius-md`),高度 24/32/36(`h-6/h-8/h-9`)、字重 `font-normal`、padding `px-3`、icon-text `gap-1` 全部直接走 Tailwind utility;uni-manager 主题下对齐 cloud-design hybridcloud 视觉(圆角 2px、字重 400、sm 24px)。',
       },
     },
   },
@@ -43,15 +68,21 @@ const meta: Meta<typeof Button> = {
         'link',
       ],
     },
+    color: {
+      description:
+        '语义色(ADR 0021),与 variant 双 prop 组合;outline+destructive 即旧库 warning+outline',
+      control: 'inline-radio',
+      options: ['default', 'primary', 'destructive'],
+    },
     size: {
-      description: '尺寸,`icon` 为正方形纯图标按钮',
+      description: '尺寸,`md` ≡ `default`,`icon` 为正方形纯图标按钮',
       control: 'select',
-      options: ['sm', 'default', 'lg', 'icon'],
+      options: ['sm', 'md', 'default', 'lg', 'icon'],
     },
     shape: {
-      description: '形状,`circle` 配 `size="icon"` 得圆形按钮',
+      description: '形状,`circle` / `square` 必须配 `size="icon"`',
       control: 'select',
-      options: ['default', 'round', 'circle'],
+      options: ['default', 'round', 'circle', 'square'],
     },
     block: {
       description: '`true` 时撑满父容器宽度',
@@ -62,35 +93,64 @@ const meta: Meta<typeof Button> = {
       control: 'boolean',
     },
     iconPosition: {
-      description: '图标 / spinner 相对文本的位置',
+      description: '兼容旧 API,新代码请用 `icon` / `iconRight` 双 slot',
       control: 'inline-radio',
       options: ['start', 'end'],
     },
     icon: {
-      description: '前置 / 后置图标(从 lucide-react 选择,演示用 mapping)',
+      description: '左侧图标(从 lucide-react 选择,演示用 mapping)',
+      options: Object.keys(iconMap),
+      mapping: iconMap,
+      control: {
+        type: 'select',
+        labels: {
+          none: '无',
+          arrowRight: '→ ArrowRight',
+          chevronRight: '→ ChevronRight',
+          download: '⬇ Download',
+          heart: '♥ Heart',
+          plus: '+ Plus',
+          search: '🔍 Search',
+          trash: '🗑 Trash',
+          x: '✕ X',
+        },
+      },
+    },
+    iconRight: {
+      description: '右侧图标(双 slot,可与 `icon` 共存)',
       options: Object.keys(iconMap),
       mapping: iconMap,
       control: {
         type: 'select',
         labels: {
           none: '无',
+          arrowRight: '→ ArrowRight',
           chevronRight: '→ ChevronRight',
           download: '⬇ Download',
+          heart: '♥ Heart',
           plus: '+ Plus',
+          search: '🔍 Search',
           trash: '🗑 Trash',
           x: '✕ X',
         },
       },
     },
     asChild: {
-      description: '用 Radix Slot 渲染为子元素(此时忽略 loading / icon)',
+      description:
+        '用 Radix Slot 渲染为子元素(忽略 loading / icon / iconRight)',
       control: 'boolean',
     },
     disabled: { control: 'boolean' },
+    disabledTooltip: {
+      description:
+        '禁用解释文案,仅在 `disabled` 同时存在时生效,内部用 cursor-not-allowed wrapper + Tooltip 拾取 hover',
+      control: 'text',
+    },
   },
   args: {
     children: 'Button',
     variant: 'default',
+    color: 'default',
     size: 'default',
     shape: 'default',
     block: false,
@@ -107,37 +167,38 @@ type Story = StoryObj<typeof Button>;
 // ─── Single-knob stories: editable via the Controls panel ─────────────────────
 
 /**
- * 默认按钮。可在 Controls 面板调 variant / size / shape / loading / icon 等
- * 全部 props,即时预览。这是最常用的演示形态。
+ * 默认按钮。Controls 面板可调全部 props,即时预览。
  */
 export const Playground: Story = {
-  args: { children: 'Submit' },
+  args: {
+    children: 'Submit',
+    block: false,
+  },
 };
 
 /**
- * 危险动作按钮。视觉用 `destructive` variant,语义来自 design token 的
- * destructive 配色;不要硬编码 `bg-red-600`。
+ * 危险动作按钮 — 视觉用 `destructive` variant,不要硬编码 `bg-red-600`。
  */
 export const Destructive: Story = {
   args: { children: 'Delete', variant: 'destructive' },
 };
 
 /**
- * Loading 态:自动 disabled + 替换 icon 为 spinner,视觉宽度保持一致以避免布局抖动。
+ * Loading 态 — 自动 `disabled` + `aria-busy=true` + spinner 替换左侧 icon,
+ * 视觉宽度保持以避免布局抖动。
  */
 export const Loading: Story = {
   args: { children: 'Saving', loading: true },
 };
 
 /**
- * 带图标的按钮。`icon` 接受 ReactNode,推荐 `lucide-react`;`iconPosition` 控制
- * 位于文本前(start)还是后(end)。
+ * 双 slot icon — `icon` 左、`iconRight` 右,可同时存在。
  */
-export const WithIcon: Story = {
+export const WithIcons: Story = {
   args: {
     children: 'Next step',
-    icon: <ChevronRight />,
-    iconPosition: 'end',
+    icon: <Search />,
+    iconRight: <ArrowRight />,
   },
 };
 
@@ -149,6 +210,34 @@ export const Block: Story = {
   decorators: [(Story) => <div style={{ width: 360 }}>{Story()}</div>],
 };
 
+/**
+ * Icon-only:无 children 仅传 `icon`,组件自动收紧 padding;
+ * 配合 `shape="circle"` / `"square"` + `size="icon"` 得到等宽等高图标按钮。
+ */
+export const IconOnly: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button size="icon" aria-label="Add" icon={<Plus />} />
+      <Button size="icon" shape="circle" aria-label="Like" icon={<Heart />} />
+      <Button
+        size="icon"
+        shape="square"
+        variant="outline"
+        aria-label="Search"
+        icon={<Search />}
+      />
+      <Button
+        size="icon"
+        shape="circle"
+        variant="ghost"
+        aria-label="Close"
+        icon={<X />}
+      />
+    </div>
+  ),
+};
+
 // ─── Visual reference stories: comparison tables, no Controls ─────────────────
 
 /**
@@ -171,24 +260,24 @@ export const VariantsMatrix: Story = {
 };
 
 /**
- * 四种 size(`sm / default / lg / icon`)。`icon` 尺寸用于纯图标按钮。
+ * 三档尺寸(`sm` 24px / `md`(`default`) 32px / `lg` 36px) + `icon`。
+ * cva 直接走 `h-6/h-8/h-9` Tailwind utility,与 Input / Select / DatePicker 同档。
  */
 export const SizesMatrix: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <div className="flex flex-wrap items-center gap-3">
-      <Button size="sm">Small</Button>
-      <Button size="default">Default</Button>
-      <Button size="lg">Large</Button>
-      <Button size="icon" aria-label="Add">
-        <Plus />
-      </Button>
+      <Button size="sm">Small (24)</Button>
+      <Button size="md">Medium (32)</Button>
+      <Button size="lg">Large (36)</Button>
+      <Button size="icon" aria-label="Add" icon={<Plus />} />
     </div>
   ),
 };
 
 /**
- * 三种 shape(`default / round / circle`)。`circle` 必须配 `size="icon"`。
+ * 四种 shape(`default / round / circle / square`)。
+ * `circle` / `square` 必须配 `size="icon"`。
  */
 export const ShapesMatrix: Story = {
   parameters: { controls: { disable: true } },
@@ -196,16 +285,20 @@ export const ShapesMatrix: Story = {
     <div className="flex flex-wrap items-center gap-3">
       <Button shape="default">Default</Button>
       <Button shape="round">Round</Button>
-      <Button size="icon" shape="circle" aria-label="Close">
-        <X />
-      </Button>
+      <Button size="icon" shape="circle" aria-label="Like" icon={<Heart />} />
+      <Button
+        size="icon"
+        shape="square"
+        aria-label="Search"
+        icon={<Search />}
+      />
     </div>
   ),
 };
 
 /**
- * 状态对照:常态 / 禁用 / 加载。注意 loading 自动 disabled,不需要再传
- * `disabled`。
+ * 状态对照:常态 / 禁用 / 加载 / 加载替换 icon。
+ * loading 自动 disabled,不要再传 `disabled`。
  */
 export const StatesMatrix: Story = {
   parameters: { controls: { disable: true } },
@@ -215,15 +308,39 @@ export const StatesMatrix: Story = {
       <Button disabled>Disabled</Button>
       <Button loading>Loading</Button>
       <Button variant="outline" loading icon={<Download />}>
-        Loading replaces icon
+        Loading replaces left icon
       </Button>
     </div>
   ),
 };
 
+/**
+ * 双 slot 组合演示:同一按钮同时挂左右图标,适合 prefix + suffix 类操作
+ * (例如「下载」+「外部链接」)。
+ */
+export const DualSlots: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button icon={<Download />} iconRight={<ArrowRight />}>
+        Download &amp; continue
+      </Button>
+      <Button variant="outline" icon={<Search />} iconRight={<ChevronRight />}>
+        Search docs
+      </Button>
+      <Button
+        variant="ghost"
+        icon={<Heart />}
+        iconRight={<Plus />}
+        aria-label="Like and add"
+      />
+    </div>
+  ),
+};
+
 /**
  * `asChild` 模式:把按钮视觉应用到子元素,常见用法是渲染为 `<a>` 链接。
- * 注意此模式下 `loading` 和 `icon` 会被忽略。
+ * 注意此模式下 `loading` / `icon` / `iconRight` 会被忽略。
  */
 export const AsChild: Story = {
   parameters: { controls: { disable: true } },
@@ -233,3 +350,394 @@ export const AsChild: Story = {
     </Button>
   ),
 };
+
+// ─── New stories added during Button MVP 优化对齐 ─────────────────────────────
+
+/**
+ * ADR 0021 双 prop 组合 — 用 `variant="outline" color="destructive"` 表达
+ * 旧库 cloud-design `type="normal" warning` 的语义,而不是新增 variant。
+ * 同样支持 `variant="ghost" color="destructive"`(轻量删除)等组合。
+ */
+export const WarningOutline: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button variant="outline" color="destructive" icon={<Trash />}>
+        删除
+      </Button>
+      <Button variant="ghost" color="destructive">
+        移除关联
+      </Button>
+      <Button variant="link" color="destructive">
+        解除绑定
+      </Button>
+    </div>
+  ),
+};
+
+/**
+ * 禁用 + 解释文案 — `disabled` + `disabledTooltip` 触发 cursor-not-allowed
+ * wrapper + Tooltip;wrapper 拾取 hover,button 自身 pointer-events 关闭。
+ * 不传 `disabledTooltip` 时保持原生 disabled 行为不变。
+ */
+export const DisabledWithTooltip: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button disabled disabledTooltip="无权限操作,请联系管理员">
+        发布
+      </Button>
+      <Button
+        variant="outline"
+        disabled
+        disabledTooltip="尚未选中任何条目"
+        icon={<Trash />}
+      >
+        批量删除
+      </Button>
+    </div>
+  ),
+};
+
+/**
+ * ghost / link text 按钮 — 高度跟随主 size 档(24/32/36),与其他 variant 一致;
+ * 区别在于去除背景/边框与收紧水平 padding(ghost px-1 / link px-0)。
+ * (早期版本曾使用 18/20px 独立紧凑高度,D1 决策后取消)
+ */
+export const TextCompactSizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col items-start gap-4">
+      <div className="flex flex-wrap items-center gap-3">
+        <Button variant="ghost" size="sm">
+          Ghost sm (24)
+        </Button>
+        <Button variant="ghost" size="md">
+          Ghost md (32)
+        </Button>
+        <Button variant="ghost" size="lg">
+          Ghost lg (36)
+        </Button>
+      </div>
+      <div className="flex flex-wrap items-center gap-3">
+        <Button variant="link" size="sm">
+          Link sm
+        </Button>
+        <Button variant="link" size="md">
+          Link md
+        </Button>
+        <Button variant="link" size="lg">
+          Link lg
+        </Button>
+      </div>
+    </div>
+  ),
+};
+
+// ─── ButtonGroup stories (合并自 button-group.stories.tsx) ────────────────────
+
+/**
+ * ButtonGroup 基础形态 — 把多个 `Button` / `Input` 包在一起共享边线,
+ * `attached`(默认 true)等价 antd `Space.Compact`,`false` 时按钮间留 8px。
+ */
+export const GroupPlayground: StoryObj<typeof ButtonGroup> = {
+  args: { orientation: 'horizontal', attached: true },
+  argTypes: {
+    orientation: {
+      control: 'inline-radio',
+      options: ['horizontal', 'vertical'],
+    },
+    attached: { control: 'boolean' },
+  },
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">左</Button>
+      <Button variant="outline">中</Button>
+      <Button variant="outline">右</Button>
+    </ButtonGroup>
+  ),
+};
+
+/**
+ * SplitButton 简化形态 — 左主操作 + 右下拉箭头(独立 Button)。
+ */
+export const GroupSplitButton: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ButtonGroup>
+      <Button>保存</Button>
+      <Button shape="square" icon={<ChevronDown />} aria-label="更多保存选项" />
+    </ButtonGroup>
+  ),
+};
+
+/**
+ * SplitButton 完整形态 — 右侧 ChevronDown 接 DropdownMenu。主按钮与
+ * 下拉触发使用同一 `variant` 保证视觉一致;对齐 cloud-design `SplitButton`
+ * 与 antd `Dropdown.Button` 的主场景。
+ */
+export const GroupSplitButtonWithDropdown: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col items-start gap-3">
+      <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>
+      <ButtonGroup>
+        <Button variant="outline">编辑</Button>
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              variant="outline"
+              shape="square"
+              icon={<ChevronDown />}
+              aria-label="更多编辑选项"
+            />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem>复制</DropdownMenuItem>
+            <DropdownMenuItem>重命名</DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem className="text-destructive focus:text-destructive">
+              删除
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </ButtonGroup>
+    </div>
+  ),
+};
+
+/**
+ * SplitButton 多选形态 — 对应 cloud-design SplitButton 的 `selectMode="multiple"` +
+ * `selectedKeys`。新组合用 `DropdownMenuCheckboxItem` 表达,checked 受控,主按钮
+ * 文案随选择动态变化。
+ */
+export const GroupSplitButtonWithCheckbox: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const ChannelsSplit = () => {
+      const [channels, setChannels] = React.useState<Record<string, boolean>>({
+        web: true,
+        mobile: true,
+        email: false,
+      });
+      const toggle = (k: string) => (v: boolean) =>
+        setChannels((s) => ({ ...s, [k]: v }));
+      const count = Object.values(channels).filter(Boolean).length;
+      return (
+        <ButtonGroup>
+          <Button>{`发布到 ${count} 个渠道`}</Button>
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                shape="square"
+                icon={<ChevronDown />}
+                aria-label="选择发布渠道"
+              />
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end">
+              <DropdownMenuLabel>发布渠道</DropdownMenuLabel>
+              <DropdownMenuSeparator />
+              <DropdownMenuCheckboxItem
+                checked={channels.web}
+                onCheckedChange={toggle('web')}
+              >
+                Web 站点
+              </DropdownMenuCheckboxItem>
+              <DropdownMenuCheckboxItem
+                checked={channels.mobile}
+                onCheckedChange={toggle('mobile')}
+              >
+                移动端
+              </DropdownMenuCheckboxItem>
+              <DropdownMenuCheckboxItem
+                checked={channels.email}
+                onCheckedChange={toggle('email')}
+              >
+                邮件订阅
+              </DropdownMenuCheckboxItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </ButtonGroup>
+      );
+    };
+    return <ChannelsSplit />;
+  },
+};
+
+/**
+ * SplitButton 单选形态 — 对应 cloud-design SplitButton 的 `selectMode="single"`。
+ * 新组合用 `DropdownMenuRadioGroup` + `DropdownMenuRadioItem` 表达,value 受控,
+ * 选中项 ✓ 反馈。
+ */
+export const GroupSplitButtonWithRadio: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const EnvSplit = () => {
+      const [env, setEnv] = React.useState('staging');
+      const envLabel = { dev: '开发', staging: '预发', prod: '生产' }[env];
+      return (
+        <ButtonGroup>
+          <Button>{`部署到 ${envLabel}`}</Button>
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                shape="square"
+                icon={<ChevronDown />}
+                aria-label="切换部署环境"
+              />
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end">
+              <DropdownMenuLabel>部署环境</DropdownMenuLabel>
+              <DropdownMenuSeparator />
+              <DropdownMenuRadioGroup value={env} onValueChange={setEnv}>
+                <DropdownMenuRadioItem value="dev">开发</DropdownMenuRadioItem>
+                <DropdownMenuRadioItem value="staging">
+                  预发
+                </DropdownMenuRadioItem>
+                <DropdownMenuRadioItem value="prod">生产</DropdownMenuRadioItem>
+              </DropdownMenuRadioGroup>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </ButtonGroup>
+      );
+    };
+    return <EnvSplit />;
+  },
+};
+
+/**
+ * SplitButton 三档尺寸 — 对应 cloud-design SplitButton 的 `size="small/medium/large"`。
+ * 通过 `<ButtonGroup size>` 注入,子 Button 同步继承;同时演示对齐旧库 `autoWidth=true`
+ * 的写法 — 用 `style.minWidth` 读 Radix 暴露的 `--radix-dropdown-menu-trigger-width`
+ * CSS 变量(避免 Tailwind arbitrary value 规则告警),让弹层最小宽度追平触发按钮宽度。
+ */
+export const GroupSplitButtonSizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const Demo = ({ size }: { size: 'sm' | 'md' | 'lg' }) => (
+      <ButtonGroup size={size}>
+        <Button>新建数据库</Button>
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              shape="square"
+              icon={<ChevronDown />}
+              aria-label="更多新建选项"
+            />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent
+            align="end"
+            style={{ minWidth: 'var(--radix-dropdown-menu-trigger-width)' }}
+          >
+            <DropdownMenuItem>MySQL 实例</DropdownMenuItem>
+            <DropdownMenuItem>PostgreSQL 实例</DropdownMenuItem>
+            <DropdownMenuItem>Redis 实例</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </ButtonGroup>
+    );
+    return (
+      <div className="flex flex-col items-start gap-3">
+        <Demo size="sm" />
+        <Demo size="md" />
+        <Demo size="lg" />
+      </div>
+    );
+  },
+};
+
+/**
+ * `<ButtonGroup size="sm">` 自动通过 Context 把 sm 注入未显式传 size 的子 Button。
+ * 显式传 `size` 的子 Button 以子值优先,Context 不覆盖。
+ */
+export const GroupSizeInherit: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col items-start gap-3">
+      <ButtonGroup size="sm">
+        <Button variant="outline">继承 sm</Button>
+        <Button variant="outline">继承 sm</Button>
+        <Button variant="outline" size="lg">
+          显式 lg(不继承)
+        </Button>
+      </ButtonGroup>
+      <ButtonGroup size="lg">
+        <Button>继承 lg</Button>
+        <Button variant="outline">继承 lg</Button>
+        <Button variant="outline">继承 lg</Button>
+      </ButtonGroup>
+    </div>
+  ),
+};
+
+/**
+ * 分页器形态。
+ */
+export const GroupPager: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ButtonGroup>
+      <Button variant="outline">上一页</Button>
+      <Button variant="outline">1 / 10</Button>
+      <Button variant="outline">下一页</Button>
+    </ButtonGroup>
+  ),
+};
+
+/**
+ * Input + addon 拼装。`ButtonGroupText` 提供 antd-style addon 文字。
+ */
+export const GroupInputAddon: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ButtonGroup>
+      <ButtonGroupText>https://</ButtonGroupText>
+      <Input defaultValue="example.com" className="rounded-l-none" />
+      <Button>访问</Button>
+    </ButtonGroup>
+  ),
+};
+
+/**
+ * 垂直方向按钮组。
+ */
+export const GroupVertical: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ButtonGroup orientation="vertical">
+      <Button variant="outline">编辑</Button>
+      <Button variant="outline">复制</Button>
+      <Button variant="outline">删除</Button>
+    </ButtonGroup>
+  ),
+};
+
+/**
+ * `attached={false}` — 按钮间保留 8px gap,圆角不被去除。
+ */
+export const GroupNotAttached: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ButtonGroup attached={false}>
+      <Button variant="outline">取消</Button>
+      <Button>确定</Button>
+    </ButtonGroup>
+  ),
+};