@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/button/index.tsx

@@ -0,0 +1,202 @@
+/**
+ * 按钮 Button
+ *
+ * 触发一个操作或事件，如提交表单、打开对话框、取消操作或执行删除。
+ *
+ * @when
+ * - 需要触发一个即时操作时
+ * - 需要在操作流中引导用户到下一步时
+ * - 需要为危险操作提供确认入口时
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Slot } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { Spinner } from '@/components/spinner';
+
+// ─── Button cva ─────────────────────────────────────────────────────────────
+//
+// 视觉由 token 驱动，组件只用语义 utility：
+// - 圆角 `rounded-md`：opentrek=8px / uni-manager=2px
+// - focus ring `ring-ring`：opentrek=品牌色 halo / uni-manager=transparent
+// - shadow：组件不写，uni-manager 通过 theme.css scoped CSS [data-slot='button'] 注入
+
+const buttonVariants = cva(
+  'inline-flex shrink-0 cursor-pointer items-center justify-center rounded-md font-normal whitespace-nowrap transition-colors select-none focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4',
+  {
+    variants: {
+      variant: {
+        default:
+          'bg-primary text-primary-foreground hover:bg-primary/90 aria-expanded:bg-primary/90',
+        secondary:
+          'bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary',
+        destructive:
+          'bg-destructive text-destructive-foreground hover:bg-destructive/90 aria-expanded:bg-destructive/90',
+        outline:
+          'border border-input bg-card hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground',
+        dashed:
+          'border border-dashed border-input bg-card hover:bg-muted hover:text-foreground aria-expanded:bg-muted',
+        ghost:
+          'hover:bg-accent hover:text-accent-foreground aria-expanded:bg-accent aria-expanded:text-accent-foreground',
+        link: 'text-primary hover:text-primary-hover',
+      },
+      // 语义色 — 与 variant 双 prop 组合
+      color: {
+        default: '',
+        primary: '',
+        destructive: '',
+      },
+      size: {
+        sm: 'h-6 gap-1 px-2 text-xs has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*=size-])]:size-3',
+        default:
+          'h-8 gap-1.5 px-2.5 text-xs has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2',
+        lg: 'h-9 gap-1.5 px-3 text-sm has-data-[icon=inline-end]:pr-2.5 has-data-[icon=inline-start]:pl-2.5',
+        icon: 'size-8 p-0',
+        'icon-sm': 'size-6 p-0 [&_svg:not([class*=size-])]:size-3',
+        'icon-lg': 'size-9 p-0',
+      },
+      shape: {
+        default: '',
+        round: 'rounded-full',
+        circle: 'rounded-full aspect-square p-0',
+        square: 'aspect-square p-0',
+      },
+      block: {
+        true: 'w-full',
+        false: '',
+      },
+    },
+    compoundVariants: [
+      // ─── color × variant ─────────────────────────────────────────────
+      {
+        variant: 'outline',
+        color: 'destructive',
+        className:
+          'border-destructive text-destructive hover:bg-destructive/10 hover:text-destructive',
+      },
+      {
+        variant: 'ghost',
+        color: 'destructive',
+        className:
+          'text-destructive hover:bg-destructive/10 hover:text-destructive',
+      },
+      {
+        variant: 'link',
+        color: 'destructive',
+        className: 'text-destructive hover:text-destructive-hover',
+      },
+      // ─── ghost / link padding 收紧 ─────────────────────────────────────
+      { variant: 'ghost', size: 'sm', className: 'px-1' },
+      { variant: 'ghost', size: 'default', className: 'px-1' },
+      { variant: 'ghost', size: 'lg', className: 'px-1' },
+      { variant: 'link', size: 'sm', className: 'h-auto px-0' },
+      { variant: 'link', size: 'default', className: 'h-auto px-0' },
+      { variant: 'link', size: 'lg', className: 'h-auto px-0' },
+    ],
+    defaultVariants: {
+      variant: 'default',
+      color: 'default',
+      size: 'default',
+      shape: 'default',
+      block: false,
+    },
+  },
+);
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type ButtonVariant =
+  | 'default'
+  | 'secondary'
+  | 'destructive'
+  | 'outline'
+  | 'dashed'
+  | 'ghost'
+  | 'link';
+export type ButtonColor = 'default' | 'primary' | 'destructive';
+export type ButtonSize =
+  | 'sm'
+  | 'default'
+  | 'lg'
+  | 'icon'
+  | 'icon-sm'
+  | 'icon-lg';
+export type ButtonShape = 'default' | 'round' | 'circle' | 'square';
+
+// ─── Button ─────────────────────────────────────────────────────────────────
+
+export interface ButtonProps
+  extends React.ComponentProps<'button'>,
+    VariantProps<typeof buttonVariants> {
+  /** 视觉风格。 @default default */
+  variant?: ButtonVariant;
+  /** 语义色，与 variant 双 prop 组合。 @default default */
+  color?: ButtonColor;
+  /** 尺寸。 @default default */
+  size?: ButtonSize;
+  /** 形状。circle/square 为等宽等高，适合纯图标。 @default default */
+  shape?: ButtonShape;
+  /** true 时撑满父容器宽度。 @default false */
+  block?: boolean;
+  /** Slot 模式，渲染为子元素。 @default false */
+  asChild?: boolean;
+  /** 设置按钮的载入状态。 @default false */
+  loading?: boolean;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  (
+    {
+      className,
+      variant,
+      color,
+      size,
+      shape,
+      block,
+      asChild = false,
+      loading = false,
+      disabled,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const Comp = asChild ? Slot.Root : 'button';
+
+    return (
+      <Comp
+        ref={ref as React.Ref<HTMLButtonElement>}
+        data-slot="button"
+        data-variant={variant}
+        data-size={size}
+        disabled={disabled || loading}
+        aria-busy={loading || undefined}
+        className={cn(
+          buttonVariants({
+            variant,
+            color,
+            size,
+            shape,
+            block,
+            className,
+          }),
+        )}
+        {...props}
+      >
+        {loading ? (
+          <>
+            <Spinner data-icon="loading" />
+            {children}
+          </>
+        ) : (
+          children
+        )}
+      </Comp>
+    );
+  },
+);
+Button.displayName = 'Button';
+
+export { Button, buttonVariants };

package/src/components/button/meta.md

@@ -0,0 +1,209 @@
+# Button
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+按钮 Button
+触发一个操作或事件，如提交表单、打开对话框、取消操作或执行删除。
+
+## 使用场景
+
+- 需要触发一个即时操作时
+- 需要在操作流中引导用户到下一步时
+- 需要为危险操作提供确认入口时
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `ButtonVariant` | `default` | – | 视觉风格。 |
+| `color` | `ButtonColor` | `default` | – | 语义色，与 variant 双 prop 组合。 |
+| `size` | `ButtonSize` | `default` | – | 尺寸。 |
+| `shape` | `ButtonShape` | `default` | – | 形状。circle/square 为等宽等高，适合纯图标。 |
+| `block` | `boolean` | `false` | – | true 时撑满父容器宽度。 |
+| `asChild` | `boolean` | `false` | – | Slot 模式，渲染为子元素。 |
+| `loading` | `boolean` | `false` | – | 设置按钮的载入状态。 |
+
+## 示例
+
+### Variants
+
+按钮有多种视觉层次：主按钮、次按钮、描边按钮、虚线按钮、幽灵按钮、文字按钮。不同的类型可以用来区别按钮的重要程度。
+
+```tsx
+<div className="flex flex-wrap items-center gap-2">
+  <Button variant="default">Primary</Button>
+  <Button variant="secondary">Secondary</Button>
+  <Button variant="outline">Outline</Button>
+  <Button variant="dashed">Dashed</Button>
+  <Button variant="ghost">Ghost</Button>
+  <Button variant="destructive">Destructive</Button>
+  <Button variant="link">Link</Button>
+</div>
+```
+
+### Sizes
+
+可以通过设置 `size` 属性控制按钮的尺寸，可选值为 `lg` `default` `sm`，其中默认值为 `default`。
+
+```tsx
+<div className="flex items-center gap-2">
+  <Button size="sm">小 24px</Button>
+  <Button>中 32px</Button>
+  <Button size="lg">大 36px</Button>
+</div>
+```
+
+### WithIcon
+
+`Button` 可以嵌入 Icon，默认情况下 Icon 尺寸自动跟随 Button 的尺寸。
+
+```tsx
+<div className="flex gap-2">
+  <Button>
+    <MailIcon data-icon="inline-start" />
+    发送邮件
+  </Button>
+  <Button variant="outline">
+    <ArrowLeftIcon data-icon="inline-start" />
+    Backward
+  </Button>
+  <Button>
+    Forward
+    <ArrowRightIcon data-icon="inline-end" />
+  </Button>
+</div>
+```
+
+### IconOnly
+
+Button 只有图标时，应该显示为正方形。
+
+```tsx
+<div className="flex items-center gap-2">
+  <Button size="icon-sm" variant="ghost" aria-label="settings">
+    <SettingsIcon />
+  </Button>
+  <Button size="icon" variant="outline" aria-label="clock">
+    <ClockIcon />
+  </Button>
+  <Button size="icon-lg" aria-label="bell">
+    <BellIcon />
+  </Button>
+</div>
+```
+
+### Disabled
+
+添加 `disabled` 属性即可让按钮处于不可用状态，同时按钮样式也会改变。
+
+```tsx
+<div className="flex gap-2">
+  <Button disabled>Primary</Button>
+  <Button disabled variant="secondary">
+    Secondary
+  </Button>
+  <Button disabled variant="outline">
+    Outline
+  </Button>
+</div>
+```
+
+### Warning
+
+警告按钮用于危险操作的确认入口，可与 variant 组合使用。
+
+```tsx
+<div className="flex gap-2">
+  <Button variant="destructive">Destructive</Button>
+  <Button variant="outline" color="destructive">
+    Outline
+  </Button>
+  <Button variant="ghost" color="destructive">
+    Ghost
+  </Button>
+  <Button variant="link" color="destructive">
+    Link
+  </Button>
+</div>
+```
+
+### Group
+
+`ButtonGroup` 子组件用于将多个按钮组合在一个容器中。
+
+```tsx
+<div className="flex flex-col gap-4">
+  <ButtonGroup>
+    <Button>OK</Button>
+    <Button variant="secondary">Cancel</Button>
+  </ButtonGroup>
+
+  <ButtonGroup>
+    <Button size="lg" variant="outline">
+      Button
+    </Button>
+    <Button size="lg" variant="outline">
+      Button
+    </Button>
+    <Button size="lg" variant="outline">
+      Button
+    </Button>
+  </ButtonGroup>
+
+  <ButtonGroup>
+    <Button disabled variant="outline">
+      Left
+    </Button>
+    <Button disabled variant="outline">
+      Middle
+    </Button>
+    <Button disabled variant="outline">
+      Right
+    </Button>
+  </ButtonGroup>
+</div>
+```
+
+### AsChild
+
+默认情况下 Button 组件使用 `<button>` 标签来渲染按钮，通过 `asChild` 属性可以自定义 Button 的标签类型。
+
+```tsx
+<div className="flex gap-2">
+  <Button asChild>
+    <a href="https://example.com" target="_blank">
+      example.com
+    </a>
+  </Button>
+  <Button asChild variant="secondary">
+    <a href="https://example.com" target="_blank">
+      example.com
+    </a>
+  </Button>
+  <Button asChild variant="outline">
+    <a href="https://example.com" target="_blank">
+      example.com
+    </a>
+  </Button>
+</div>
+```
+
+### Accessibility
+
+在使用不包含文本的 icon Button 组件时，需要添加 `aria-label` 对其进行描述。
+
+```tsx
+<ButtonGroup>
+  <Button size="icon" aria-label="settings">
+    <SettingsIcon />
+  </Button>
+  <Button size="icon" aria-label="clock">
+    <ClockIcon />
+  </Button>
+  <Button size="icon" aria-label="notifications">
+    <BellIcon />
+  </Button>
+</ButtonGroup>
+```

package/src/components/button/stories.tsx

@@ -0,0 +1,215 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import {
+  MailIcon,
+  PlusIcon,
+  ArrowRightIcon,
+  ArrowLeftIcon,
+  SettingsIcon,
+  ClockIcon,
+  BellIcon,
+} from 'lucide-react';
+import { Button } from './index';
+import { ButtonGroup } from '@/components/button-group';
+
+const meta: Meta<typeof Button> = {
+  title: '通用 · General/Button 按钮',
+  component: Button,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { children: 'Button' },
+};
+
+/** 按钮有多种视觉层次：主按钮、次按钮、描边按钮、虚线按钮、幽灵按钮、文字按钮。不同的类型可以用来区别按钮的重要程度。 */
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <Button variant="default">Primary</Button>
+      <Button variant="secondary">Secondary</Button>
+      <Button variant="outline">Outline</Button>
+      <Button variant="dashed">Dashed</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="destructive">Destructive</Button>
+      <Button variant="link">Link</Button>
+    </div>
+  ),
+};
+
+/** 可以通过设置 `size` 属性控制按钮的尺寸，可选值为 `lg` `default` `sm`，其中默认值为 `default`。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Button size="sm">小 24px</Button>
+      <Button>中 32px</Button>
+      <Button size="lg">大 36px</Button>
+    </div>
+  ),
+};
+
+/** `Button` 可以嵌入 Icon，默认情况下 Icon 尺寸自动跟随 Button 的尺寸。 */
+export const WithIcon: Story = {
+  render: () => (
+    <div className="flex gap-2">
+      <Button>
+        <MailIcon data-icon="inline-start" />
+        发送邮件
+      </Button>
+      <Button variant="outline">
+        <ArrowLeftIcon data-icon="inline-start" />
+        Backward
+      </Button>
+      <Button>
+        Forward
+        <ArrowRightIcon data-icon="inline-end" />
+      </Button>
+    </div>
+  ),
+};
+
+/** Button 只有图标时，应该显示为正方形。 */
+export const IconOnly: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Button size="icon-sm" variant="ghost" aria-label="settings">
+        <SettingsIcon />
+      </Button>
+      <Button size="icon" variant="outline" aria-label="clock">
+        <ClockIcon />
+      </Button>
+      <Button size="icon-lg" aria-label="bell">
+        <BellIcon />
+      </Button>
+    </div>
+  ),
+};
+
+/** 通过设置 `loading` 属性即可以让按钮处于加载状态。 */
+export const Loading: Story = {
+  render: function LoadingDemo() {
+    const [loading, setLoading] = useState(false);
+    return (
+      <div className="flex gap-2">
+        <Button loading variant="secondary">
+          Loading
+        </Button>
+        <Button loading={loading} onClick={() => setLoading(true)}>
+          Click to loading
+        </Button>
+      </div>
+    );
+  },
+};
+
+/** 添加 `disabled` 属性即可让按钮处于不可用状态，同时按钮样式也会改变。 */
+export const Disabled: Story = {
+  render: () => (
+    <div className="flex gap-2">
+      <Button disabled>Primary</Button>
+      <Button disabled variant="secondary">
+        Secondary
+      </Button>
+      <Button disabled variant="outline">
+        Outline
+      </Button>
+    </div>
+  ),
+};
+
+/** 警告按钮用于危险操作的确认入口，可与 variant 组合使用。 */
+export const Warning: Story = {
+  render: () => (
+    <div className="flex gap-2">
+      <Button variant="destructive">Destructive</Button>
+      <Button variant="outline" color="destructive">
+        Outline
+      </Button>
+      <Button variant="ghost" color="destructive">
+        Ghost
+      </Button>
+      <Button variant="link" color="destructive">
+        Link
+      </Button>
+    </div>
+  ),
+};
+
+/** `ButtonGroup` 子组件用于将多个按钮组合在一个容器中。 */
+export const Group: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <ButtonGroup>
+        <Button>OK</Button>
+        <Button variant="secondary">Cancel</Button>
+      </ButtonGroup>
+
+      <ButtonGroup>
+        <Button size="lg" variant="outline">
+          Button
+        </Button>
+        <Button size="lg" variant="outline">
+          Button
+        </Button>
+        <Button size="lg" variant="outline">
+          Button
+        </Button>
+      </ButtonGroup>
+
+      <ButtonGroup>
+        <Button disabled variant="outline">
+          Left
+        </Button>
+        <Button disabled variant="outline">
+          Middle
+        </Button>
+        <Button disabled variant="outline">
+          Right
+        </Button>
+      </ButtonGroup>
+    </div>
+  ),
+};
+
+/** 默认情况下 Button 组件使用 `<button>` 标签来渲染按钮，通过 `asChild` 属性可以自定义 Button 的标签类型。 */
+export const AsChild: Story = {
+  render: () => (
+    <div className="flex gap-2">
+      <Button asChild>
+        <a href="https://example.com" target="_blank">
+          example.com
+        </a>
+      </Button>
+      <Button asChild variant="secondary">
+        <a href="https://example.com" target="_blank">
+          example.com
+        </a>
+      </Button>
+      <Button asChild variant="outline">
+        <a href="https://example.com" target="_blank">
+          example.com
+        </a>
+      </Button>
+    </div>
+  ),
+};
+
+/** 在使用不包含文本的 icon Button 组件时，需要添加 `aria-label` 对其进行描述。 */
+export const Accessibility: Story = {
+  render: () => (
+    <ButtonGroup>
+      <Button size="icon" aria-label="settings">
+        <SettingsIcon />
+      </Button>
+      <Button size="icon" aria-label="clock">
+        <ClockIcon />
+      </Button>
+      <Button size="icon" aria-label="notifications">
+        <BellIcon />
+      </Button>
+    </ButtonGroup>
+  ),
+};