@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/button-group/index.tsx

@@ -0,0 +1,211 @@
+/**
+ * 按钮组 ButtonGroup
+ *
+ * 将多个按钮组合为一个视觉整体，支持水平和垂直排列。
+ *
+ * 组合结构：ButtonGroup > (Button | ButtonGroupText | ButtonGroupSeparator | ButtonGroupOverflow)
+ *
+ * @when
+ * - 需要将多个相关操作紧凑排列时（如工具栏）
+ * - 需要展示互斥选项组时（配合 Toggle 使用）
+ * - 需要将输入控件与按钮组合时（如搜索框 + 按钮）
+ * - 需要菜单按钮（MenuButton）时 — Button + DropdownMenu 组合
+ * - 需要分裂按钮（SplitButton）时 — ButtonGroup + Button + DropdownMenu 组合
+ * - 需要操作列折叠（DataTable 操作列等）时 — ButtonGroup + Button + ButtonGroupOverflow 组合
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Slot } from 'radix-ui';
+import { MoreHorizontalIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Button, type ButtonProps } from '@/components/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+  type DropdownMenuProps,
+} from '@/components/dropdown-menu';
+import { Separator } from '@/components/separator';
+
+// ─── ButtonGroup cva ────────────────────────────────────────────────────────
+//
+// 拼接策略使用 border-l-0 / border-t-0（shadcn v4 策略）取代旧版 -ml-px，
+// 兼容无 border 的 variant（ghost/link）不会出现重叠 1px 偏移。
+
+const buttonGroupVariants = cva(
+  'inline-flex w-fit items-stretch *:focus-visible:relative *:focus-visible:z-10 [&>input]:flex-1',
+  {
+    variants: {
+      orientation: {
+        horizontal:
+          '[&>*:not(:first-child)]:rounded-l-none [&>*:not(:first-child)]:border-l-0 [&>*:not(:last-child)]:rounded-r-none',
+        vertical:
+          'flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:first-child)]:border-t-0 [&>*:not(:last-child)]:rounded-b-none',
+      },
+      attached: {
+        true: '',
+        false: 'gap-2',
+      },
+    },
+    defaultVariants: { orientation: 'horizontal', attached: true },
+  },
+);
+
+// ─── ButtonGroup ────────────────────────────────────────────────────────────
+
+export interface ButtonGroupProps
+  extends React.ComponentProps<'div'>,
+    VariantProps<typeof buttonGroupVariants> {
+  /** 排列方向。 @default horizontal */
+  orientation?: 'horizontal' | 'vertical';
+  /** 按钮是否紧贴（false 时留 8px gap）。 @default true */
+  attached?: boolean;
+}
+
+function ButtonGroup({
+  orientation,
+  attached,
+  className,
+  children,
+  ...props
+}: ButtonGroupProps) {
+  return (
+    <div
+      role="group"
+      data-slot="button-group"
+      data-orientation={orientation}
+      className={cn(buttonGroupVariants({ orientation, attached }), className)}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+// ─── ButtonGroupText ────────────────────────────────────────────────────────
+
+export interface ButtonGroupTextProps extends React.ComponentProps<'div'> {
+  /** 使用 Slot 模式渲染子元素 */
+  asChild?: boolean;
+}
+
+function ButtonGroupText({
+  className,
+  asChild = false,
+  ...props
+}: ButtonGroupTextProps) {
+  const Comp = asChild ? Slot.Root : 'div';
+
+  return (
+    <Comp
+      className={cn(
+        'flex items-center gap-2 rounded-md border border-input bg-muted px-2.5 text-xs font-normal [&_svg]:pointer-events-none [&_svg:not([class*=size-])]:size-4',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── ButtonGroupSeparator ───────────────────────────────────────────────────
+
+function ButtonGroupSeparator({
+  className,
+  orientation = 'vertical',
+  ...props
+}: React.ComponentProps<typeof Separator>) {
+  return (
+    <Separator
+      data-slot="button-group-separator"
+      orientation={orientation}
+      className={cn(
+        'relative self-stretch bg-input',
+        // 水平分隔线（横线）左右各短 1px。垂直内缩交给底层 Separator。
+        orientation === 'horizontal' ? 'mx-px w-auto' : 'h-auto',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── ButtonGroupOverflow ────────────────────────────────────────────────────
+//
+// 把超出按钮折叠进 ⋯ 下拉触发器。内部封装 DropdownMenu + Trigger + Content，
+// 调用方在 children 中写 DropdownMenuItem 列表，自行控制哪些操作进折叠菜单。
+//
+// 默认非模态（modal=false），与 ButtonGroup 工具栏类场景下其他操作并存的常态一致。
+
+export interface ButtonGroupOverflowProps
+  extends Omit<DropdownMenuProps, 'children'> {
+  /** 触发按钮的可访问名（aria-label）。 @default '更多操作' */
+  triggerLabel?: string;
+  /** 触发按钮 variant，与 ButtonGroup 中相邻按钮风格保持一致。 @default 'ghost' */
+  variant?: ButtonProps['variant'];
+  /**
+   * 触发按钮 size。不传时根据 variant 自选：
+   * - `variant='link'` → `'default'`（命中 link×default 的 h-auto px-0，与相邻 link 文字按钮等高）
+   * - 其余 → `'icon'`（保持 32×32 方形热区）
+   */
+  size?: ButtonProps['size'];
+  /** 自定义触发器图标，传入即替换默认 ⋯。 */
+  icon?: React.ReactNode;
+  /** 下拉菜单对齐方式。 @default 'end' */
+  align?: 'start' | 'center' | 'end';
+  /** 下拉菜单与触发器的距离（像素）。 */
+  sideOffset?: number;
+  /** 下拉菜单内容自定义 className。 */
+  contentClassName?: string;
+  /** 下拉菜单内容，通常为一组 DropdownMenuItem。 */
+  children: React.ReactNode;
+}
+
+function ButtonGroupOverflow({
+  triggerLabel = '更多操作',
+  variant = 'ghost',
+  size,
+  icon,
+  align = 'end',
+  sideOffset,
+  contentClassName,
+  modal = false,
+  children,
+  ...rootProps
+}: ButtonGroupOverflowProps) {
+  // link 型触发器走 'default'（compoundVariants 会给到 h-auto px-0，随文字高度自适应）;
+  // 其他 variant 默认 'icon'（固定 32×32 方形热区）。
+  const resolvedSize = size ?? (variant === 'link' ? 'default' : 'icon');
+
+  return (
+    <DropdownMenu modal={modal} {...rootProps}>
+      <DropdownMenuTrigger asChild>
+        <Button
+          data-slot="button-group-overflow-trigger"
+          variant={variant}
+          size={resolvedSize}
+          aria-label={triggerLabel}
+        >
+          {icon ?? <MoreHorizontalIcon />}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent
+        data-slot="button-group-overflow-content"
+        align={align}
+        sideOffset={sideOffset}
+        className={contentClassName}
+      >
+        {children}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+export {
+  ButtonGroup,
+  ButtonGroupOverflow,
+  ButtonGroupSeparator,
+  ButtonGroupText,
+  buttonGroupVariants,
+};

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

@@ -0,0 +1,190 @@
+# ButtonGroup
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+按钮组 ButtonGroup
+将多个按钮组合为一个视觉整体，支持水平和垂直排列。
+组合结构：ButtonGroup > (Button | ButtonGroupText | ButtonGroupSeparator | ButtonGroupOverflow)
+
+## 使用场景
+
+- 需要将多个相关操作紧凑排列时（如工具栏）
+- 需要展示互斥选项组时（配合 Toggle 使用）
+- 需要将输入控件与按钮组合时（如搜索框 + 按钮）
+- 需要菜单按钮（MenuButton）时 — Button + DropdownMenu 组合
+- 需要分裂按钮（SplitButton）时 — ButtonGroup + Button + DropdownMenu 组合
+- 需要操作列折叠（DataTable 操作列等）时 — ButtonGroup + Button + ButtonGroupOverflow 组合
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | `horizontal` | – | 排列方向。 |
+| `attached` | `boolean` | `true` | – | 按钮是否紧贴（false 时留 8px gap）。 |
+| `asChild` | `boolean` | – | – | 使用 Slot 模式渲染子元素 |
+| `triggerLabel` | `string` | `'更多操作'` | – | 触发按钮的可访问名（aria-label）。 |
+| `variant` | `ButtonProps['variant']` | `'ghost'` | – | 触发按钮 variant，与 ButtonGroup 中相邻按钮风格保持一致。 |
+| `size` | `ButtonProps['size']` | `'icon'` | – | 触发按钮 size。 |
+| `icon` | `React.ReactNode` | – | – | 自定义触发器图标，传入即替换默认 ⋯。 |
+| `align` | `'start' \| 'center' \| 'end'` | `'end'` | – | 下拉菜单对齐方式。 |
+| `sideOffset` | `number` | – | – | 下拉菜单与触发器的距离（像素）。 |
+| `contentClassName` | `string` | – | – | 下拉菜单内容自定义 className。 |
+| `children` | `React.ReactNode` | – | ✓ | 下拉菜单内容，通常为一组 DropdownMenuItem。 |
+
+## 示例
+
+### Horizontal
+
+`ButtonGroup` 子组件用于将多个按钮组合在一个容器中。
+
+```tsx
+<ButtonGroup>
+  <Button variant="outline">取消</Button>
+  <Button>确定</Button>
+</ButtonGroup>
+```
+
+### Vertical
+
+通过 `orientation="vertical"` 设置垂直排列。
+
+```tsx
+<ButtonGroup orientation="vertical">
+  <Button variant="outline">选项一</Button>
+  <Button variant="outline">选项二</Button>
+  <Button variant="outline">选项三</Button>
+</ButtonGroup>
+```
+
+### WithSeparator
+
+工具栏场景，使用 `ButtonGroupSeparator` 分隔功能区块。
+
+```tsx
+<ButtonGroup>
+  <Button variant="outline" size="icon">
+    <BoldIcon />
+  </Button>
+  <ButtonGroupSeparator />
+  <Button variant="outline" size="icon">
+    <ItalicIcon />
+  </Button>
+  <ButtonGroupSeparator />
+  <Button variant="outline" size="icon">
+    <UnderlineIcon />
+  </Button>
+</ButtonGroup>
+```
+
+### WithText
+
+使用 `ButtonGroupText` 在按钮组中嵌入文本标签。
+
+```tsx
+<ButtonGroup>
+  <ButtonGroupText>格式</ButtonGroupText>
+  <Button variant="outline" size="icon">
+    <AlignLeftIcon />
+  </Button>
+  <Button variant="outline" size="icon">
+    <AlignCenterIcon />
+  </Button>
+  <Button variant="outline" size="icon">
+    <AlignRightIcon />
+  </Button>
+</ButtonGroup>
+```
+
+### MenuButton
+
+菜单按钮 — 点击按钮展开下拉菜单。使用 Button + DropdownMenu 组合实现。
+
+```tsx
+<DropdownMenu modal={false}>
+  <DropdownMenuTrigger asChild>
+    <Button variant="outline">
+      操作
+      <ChevronDownIcon data-icon="inline-end" />
+    </Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>
+      <CopyIcon />
+      复制
+    </DropdownMenuItem>
+    <DropdownMenuItem>
+      <PencilIcon />
+      编辑
+    </DropdownMenuItem>
+    <DropdownMenuItem>
+      <TrashIcon />
+      删除
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+### SplitButton
+
+分裂按钮 — 主操作 + 下拉更多。使用 ButtonGroup + Button + DropdownMenu 组合实现。
+
+```tsx
+<ButtonGroup>
+  <Button>
+    <PlusIcon data-icon="inline-start" />
+    新建实例
+  </Button>
+  <DropdownMenu modal={false}>
+    <DropdownMenuTrigger asChild>
+      <Button size="icon" aria-label="更多选项">
+        <ChevronDownIcon />
+      </Button>
+    </DropdownMenuTrigger>
+    <DropdownMenuContent>
+      <DropdownMenuItem>从模板创建</DropdownMenuItem>
+      <DropdownMenuItem>从快照创建</DropdownMenuItem>
+      <DropdownMenuItem>批量创建</DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</ButtonGroup>
+```
+
+### OverflowMenu
+
+溢出菜单 — 通过 `ButtonGroupOverflow` 把超出按钮折叠进 ⋯ 下拉菜单。
+
+```tsx
+<ButtonGroup>
+  <Button variant="outline">复制</Button>
+  <Button variant="outline">编辑</Button>
+  <ButtonGroupOverflow variant="outline">
+    <DropdownMenuItem>归档</DropdownMenuItem>
+    <DropdownMenuItem>导出</DropdownMenuItem>
+    <DropdownMenuItem variant="destructive">删除</DropdownMenuItem>
+  </ButtonGroupOverflow>
+</ButtonGroup>
+```
+
+### ActionColumn
+
+操作列 — DataTable 操作列经典模式：link 风格按钮 + Separator + ButtonGroupOverflow 折叠。
+
+```tsx
+<ButtonGroup>
+  <Button variant="link">管理</Button>
+  <ButtonGroupSeparator />
+  <Button variant="link" disabled>
+    编辑
+  </Button>
+  <ButtonGroupSeparator />
+  <Button variant="link">远程连接</Button>
+  <ButtonGroupSeparator />
+  <ButtonGroupOverflow variant="link">
+    <DropdownMenuItem disabled>释放</DropdownMenuItem>
+    <DropdownMenuItem>暂停</DropdownMenuItem>
+    <DropdownMenuItem>二次确认</DropdownMenuItem>
+  </ButtonGroupOverflow>
+</ButtonGroup>
+```

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

@@ -0,0 +1,182 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  BoldIcon,
+  ItalicIcon,
+  UnderlineIcon,
+  AlignLeftIcon,
+  AlignCenterIcon,
+  AlignRightIcon,
+  ChevronDownIcon,
+  PlusIcon,
+  CopyIcon,
+  TrashIcon,
+  PencilIcon,
+} from 'lucide-react';
+import {
+  ButtonGroup,
+  ButtonGroupOverflow,
+  ButtonGroupSeparator,
+  ButtonGroupText,
+} from './index';
+import { Button } from '@/components/button';
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+} from '@/components/dropdown-menu';
+
+const meta: Meta<typeof ButtonGroup> = {
+  title: '通用 · General/ButtonGroup 按钮组',
+  component: ButtonGroup,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** `ButtonGroup` 子组件用于将多个按钮组合在一个容器中。 */
+export const Horizontal: Story = {
+  render: () => (
+    <ButtonGroup>
+      <Button variant="outline">取消</Button>
+      <Button>确定</Button>
+    </ButtonGroup>
+  ),
+};
+
+/** 通过 `orientation="vertical"` 设置垂直排列。 */
+export const Vertical: Story = {
+  render: () => (
+    <ButtonGroup orientation="vertical">
+      <Button variant="outline">选项一</Button>
+      <Button variant="outline">选项二</Button>
+      <Button variant="outline">选项三</Button>
+    </ButtonGroup>
+  ),
+};
+
+/** 工具栏场景，使用 `ButtonGroupSeparator` 分隔功能区块。 */
+export const WithSeparator: Story = {
+  render: () => (
+    <ButtonGroup>
+      <Button variant="outline" size="icon">
+        <BoldIcon />
+      </Button>
+      <ButtonGroupSeparator />
+      <Button variant="outline" size="icon">
+        <ItalicIcon />
+      </Button>
+      <ButtonGroupSeparator />
+      <Button variant="outline" size="icon">
+        <UnderlineIcon />
+      </Button>
+    </ButtonGroup>
+  ),
+};
+
+/** 使用 `ButtonGroupText` 在按钮组中嵌入文本标签。 */
+export const WithText: Story = {
+  render: () => (
+    <ButtonGroup>
+      <ButtonGroupText>格式</ButtonGroupText>
+      <Button variant="outline" size="icon">
+        <AlignLeftIcon />
+      </Button>
+      <Button variant="outline" size="icon">
+        <AlignCenterIcon />
+      </Button>
+      <Button variant="outline" size="icon">
+        <AlignRightIcon />
+      </Button>
+    </ButtonGroup>
+  ),
+};
+
+/** 菜单按钮 — 点击按钮展开下拉菜单。使用 Button + DropdownMenu 组合实现。 */
+export const MenuButton: Story = {
+  render: () => (
+    <DropdownMenu modal={false}>
+      <DropdownMenuTrigger asChild>
+        <Button variant="outline">
+          操作
+          <ChevronDownIcon data-icon="inline-end" />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent>
+        <DropdownMenuItem>
+          <CopyIcon />
+          复制
+        </DropdownMenuItem>
+        <DropdownMenuItem>
+          <PencilIcon />
+          编辑
+        </DropdownMenuItem>
+        <DropdownMenuItem>
+          <TrashIcon />
+          删除
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  ),
+};
+
+/** 分裂按钮 — 主操作 + 下拉更多。使用 ButtonGroup + Button + DropdownMenu 组合实现。 */
+export const SplitButton: Story = {
+  render: () => (
+    <ButtonGroup>
+      <Button>
+        <PlusIcon data-icon="inline-start" />
+        新建实例
+      </Button>
+      <DropdownMenu modal={false}>
+        <DropdownMenuTrigger asChild>
+          <Button size="icon" aria-label="更多选项">
+            <ChevronDownIcon />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent>
+          <DropdownMenuItem>从模板创建</DropdownMenuItem>
+          <DropdownMenuItem>从快照创建</DropdownMenuItem>
+          <DropdownMenuItem>批量创建</DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </ButtonGroup>
+  ),
+};
+
+/** 溢出菜单 — 通过 `ButtonGroupOverflow` 把超出按钮折叠进 ⋯ 下拉菜单。 */
+export const OverflowMenu: Story = {
+  render: () => (
+    <ButtonGroup>
+      <Button variant="outline">复制</Button>
+      <Button variant="outline">编辑</Button>
+      <ButtonGroupOverflow variant="outline">
+        <DropdownMenuItem>归档</DropdownMenuItem>
+        <DropdownMenuItem>导出</DropdownMenuItem>
+        <DropdownMenuItem variant="destructive">删除</DropdownMenuItem>
+      </ButtonGroupOverflow>
+    </ButtonGroup>
+  ),
+};
+
+/** 操作列 — DataTable 操作列经典模式：h-4 锁高 + gap-3 间距 + ButtonGroupSeparator 分隔 + ButtonGroupOverflow 折叠。 */
+export const ActionColumn: Story = {
+  render: () => (
+    <ButtonGroup className="h-4 gap-3">
+      <Button variant="link">管理</Button>
+      <ButtonGroupSeparator />
+      <Button variant="link" disabled>
+        编辑
+      </Button>
+      <ButtonGroupSeparator />
+      <Button variant="link">远程连接</Button>
+      <ButtonGroupSeparator />
+      <ButtonGroupOverflow variant="link">
+        <DropdownMenuItem disabled>释放</DropdownMenuItem>
+        <DropdownMenuItem>暂停</DropdownMenuItem>
+        <DropdownMenuItem variant="destructive">删除</DropdownMenuItem>
+      </ButtonGroupOverflow>
+    </ButtonGroup>
+  ),
+};