@teamix-evo/ui 0.1.1

package/src/components/breadcrumb/breadcrumb.tsx

@@ -0,0 +1,122 @@
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { ChevronRight, MoreHorizontal } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+export interface BreadcrumbProps extends React.ComponentPropsWithoutRef<'nav'> {
+  /**
+   * 自定义分隔符(antd `separator` 并集)。每个 `<BreadcrumbSeparator />` 默认渲染 `<ChevronRight />`,
+   * 通过设置 children 可全局覆盖。
+   */
+  separator?: React.ReactNode;
+}
+
+const Breadcrumb = React.forwardRef<HTMLElement, BreadcrumbProps>(
+  ({ ...props }, ref) => <nav ref={ref} aria-label="breadcrumb" {...props} />,
+);
+Breadcrumb.displayName = 'Breadcrumb';
+
+const BreadcrumbList = React.forwardRef<
+  HTMLOListElement,
+  React.ComponentPropsWithoutRef<'ol'>
+>(({ className, ...props }, ref) => (
+  <ol
+    ref={ref}
+    className={cn(
+      'flex flex-wrap items-center gap-1.5 text-sm text-muted-foreground sm:gap-2.5',
+      className,
+    )}
+    {...props}
+  />
+));
+BreadcrumbList.displayName = 'BreadcrumbList';
+
+const BreadcrumbItem = React.forwardRef<
+  HTMLLIElement,
+  React.ComponentPropsWithoutRef<'li'>
+>(({ className, ...props }, ref) => (
+  <li
+    ref={ref}
+    className={cn('inline-flex items-center gap-1.5', className)}
+    {...props}
+  />
+));
+BreadcrumbItem.displayName = 'BreadcrumbItem';
+
+export interface BreadcrumbLinkProps
+  extends React.ComponentPropsWithoutRef<'a'> {
+  /** 用 Slot 渲染为子元素(常配合 React Router / Next.js Link)。 */
+  asChild?: boolean;
+}
+
+const BreadcrumbLink = React.forwardRef<HTMLAnchorElement, BreadcrumbLinkProps>(
+  ({ asChild, className, ...props }, ref) => {
+    const Comp = asChild ? Slot : 'a';
+    return (
+      <Comp
+        ref={ref}
+        className={cn('transition-colors hover:text-foreground', className)}
+        {...props}
+      />
+    );
+  },
+);
+BreadcrumbLink.displayName = 'BreadcrumbLink';
+
+const BreadcrumbPage = React.forwardRef<
+  HTMLSpanElement,
+  React.ComponentPropsWithoutRef<'span'>
+>(({ className, ...props }, ref) => (
+  <span
+    ref={ref}
+    role="link"
+    aria-disabled="true"
+    aria-current="page"
+    className={cn('font-normal text-foreground', className)}
+    {...props}
+  />
+));
+BreadcrumbPage.displayName = 'BreadcrumbPage';
+
+const BreadcrumbSeparator = ({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<'li'>) => (
+  <li
+    role="presentation"
+    aria-hidden="true"
+    className={cn('[&>svg]:size-3.5', className)}
+    {...props}
+  >
+    {children ?? <ChevronRight />}
+  </li>
+);
+BreadcrumbSeparator.displayName = 'BreadcrumbSeparator';
+
+const BreadcrumbEllipsis = ({
+  className,
+  ...props
+}: React.ComponentProps<'span'>) => (
+  <span
+    role="presentation"
+    aria-hidden="true"
+    className={cn('flex size-9 items-center justify-center', className)}
+    {...props}
+  >
+    <MoreHorizontal className="size-4" />
+    <span className="sr-only">More</span>
+  </span>
+);
+BreadcrumbEllipsis.displayName = 'BreadcrumbEllipsis';
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+};

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

@@ -0,0 +1,98 @@
+---
+id: button
+name: Button
+type: component
+category: foundation
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Button
+
+通用按钮 — 基于 shadcn/ui Button 二次封装,补齐 antd 的 `loading / icon / shape / block` 等开箱即用能力。
+按钮文本、aria 状态由消费方提供;视觉与可访问性由组件保障。
+
+## When to use
+
+- 表单提交、对话框确认、列表行操作等触发性交互
+- 需要明确反馈"按下→处理中→完成"过程的场景(用 `loading`)
+- 需要纯图标按钮时(用 `size="icon"` + `shape="circle"` 组合)
+
+## When NOT to use
+
+- 仅做导航而无副作用 → 用 `<a>` 或路由 `Link`(必要时配 `variant="link"` 视觉)
+- 切换布尔状态 → 用 `Switch` / `Toggle`,不要用按钮模拟
+- 需要承载多行说明文字 → 用 `Card` 等容器组件
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`button.tsx`](./button.tsx) 的 `ButtonProps` interface JSDoc。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- 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"` 得圆形按钮。 |
+| `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 相对文本的位置。 |
+| `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) |
+
+### 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
+```
+<!-- auto:deps:end -->
+
+> 除上述声明的 props 外,Button 同时透传所有原生 `<button>` 属性(`onClick` / `type` / `aria-*` / ...);`asChild=true` 时透传至 Radix Slot 的子元素。
+
+## AI 生成纪律
+
+- **variant 语义**:危险动作(删除/重置)用 `destructive`;次要动作(取消)用 `secondary` 或 `ghost`;表单主操作用 `default`;**不要**用 inline 任意值(如 `bg-[#ff0000]`)。
+- **icon 来源**:固定从 `lucide-react` import,**不要**内联 SVG,不要混用其他 icon 库。
+- **loading + disabled**:写 `loading` 即可,**不要**额外手动加 `disabled`,组件已自动处理。
+- **shape="circle"**:必须配 `size="icon"` 一起使用,否则视觉会变形(扁圆)。
+- **block**:`true` 时按钮撑满,**不要**再用 `className="w-full"` 重复。
+- **asChild**:仅当需要渲染为 `<a>` / `<Link>` 等其他元素时启用,且**不要**与 `loading` / `icon` 同时使用,会被忽略。
+
+## Examples
+
+```tsx
+// 基本
+<Button>提交</Button>
+
+// 危险 + 加载
+<Button variant="destructive" loading>删除中</Button>
+
+// 图标 + 后置
+<Button icon={<ChevronRight />} iconPosition="end">下一步</Button>
+
+// 圆形图标按钮
+<Button size="icon" shape="circle" variant="ghost" icon={<X />} aria-label="关闭" />
+
+// 块级
+<Button block>登录</Button>
+
+// 作为链接
+<Button asChild variant="link"><a href="/docs">查看文档</a></Button>
+```

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

@@ -0,0 +1,235 @@
+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';
+
+/**
+ * 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.
+ */
+const iconMap: Record<string, ReactNode> = {
+  none: undefined,
+  chevronRight: <ChevronRight />,
+  download: <Download />,
+  plus: <Plus />,
+  trash: <Trash />,
+  x: <X />,
+};
+
+const meta: Meta<typeof Button> = {
+  title: '基础原语 · Foundation/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。',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      description: '视觉风格,语义按 design token 走',
+      control: 'select',
+      options: [
+        'default',
+        'secondary',
+        'destructive',
+        'outline',
+        'dashed',
+        'ghost',
+        'link',
+      ],
+    },
+    size: {
+      description: '尺寸,`icon` 为正方形纯图标按钮',
+      control: 'select',
+      options: ['sm', 'default', 'lg', 'icon'],
+    },
+    shape: {
+      description: '形状,`circle` 配 `size="icon"` 得圆形按钮',
+      control: 'select',
+      options: ['default', 'round', 'circle'],
+    },
+    block: {
+      description: '`true` 时撑满父容器宽度',
+      control: 'boolean',
+    },
+    loading: {
+      description: '显示自旋 spinner,自动 disabled,保留视觉宽度',
+      control: 'boolean',
+    },
+    iconPosition: {
+      description: '图标 / spinner 相对文本的位置',
+      control: 'inline-radio',
+      options: ['start', 'end'],
+    },
+    icon: {
+      description: '前置 / 后置图标(从 lucide-react 选择,演示用 mapping)',
+      options: Object.keys(iconMap),
+      mapping: iconMap,
+      control: {
+        type: 'select',
+        labels: {
+          none: '无',
+          chevronRight: '→ ChevronRight',
+          download: '⬇ Download',
+          plus: '+ Plus',
+          trash: '🗑 Trash',
+          x: '✕ X',
+        },
+      },
+    },
+    asChild: {
+      description: '用 Radix Slot 渲染为子元素(此时忽略 loading / icon)',
+      control: 'boolean',
+    },
+    disabled: { control: 'boolean' },
+  },
+  args: {
+    children: 'Button',
+    variant: 'default',
+    size: 'default',
+    shape: 'default',
+    block: false,
+    loading: false,
+    iconPosition: 'start',
+    asChild: false,
+    disabled: false,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+// ─── Single-knob stories: editable via the Controls panel ─────────────────────
+
+/**
+ * 默认按钮。可在 Controls 面板调 variant / size / shape / loading / icon 等
+ * 全部 props,即时预览。这是最常用的演示形态。
+ */
+export const Playground: Story = {
+  args: { children: 'Submit' },
+};
+
+/**
+ * 危险动作按钮。视觉用 `destructive` variant,语义来自 design token 的
+ * destructive 配色;不要硬编码 `bg-red-600`。
+ */
+export const Destructive: Story = {
+  args: { children: 'Delete', variant: 'destructive' },
+};
+
+/**
+ * Loading 态:自动 disabled + 替换 icon 为 spinner,视觉宽度保持一致以避免布局抖动。
+ */
+export const Loading: Story = {
+  args: { children: 'Saving', loading: true },
+};
+
+/**
+ * 带图标的按钮。`icon` 接受 ReactNode,推荐 `lucide-react`;`iconPosition` 控制
+ * 位于文本前(start)还是后(end)。
+ */
+export const WithIcon: Story = {
+  args: {
+    children: 'Next step',
+    icon: <ChevronRight />,
+    iconPosition: 'end',
+  },
+};
+
+/**
+ * 块级按钮:`block=true` 撑满父容器宽度。常用于表单主操作 / 移动端。
+ */
+export const Block: Story = {
+  args: { children: 'Sign in', block: true },
+  decorators: [(Story) => <div style={{ width: 360 }}>{Story()}</div>],
+};
+
+// ─── Visual reference stories: comparison tables, no Controls ─────────────────
+
+/**
+ * 七种 variant 横向对照(`default / secondary / destructive / outline /
+ * dashed / ghost / link`)。视觉锚点 — 调 design token 时这条故事最直观。
+ */
+export const VariantsMatrix: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button>Default</Button>
+      <Button variant="secondary">Secondary</Button>
+      <Button variant="destructive">Destructive</Button>
+      <Button variant="outline">Outline</Button>
+      <Button variant="dashed">Dashed</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="link">Link</Button>
+    </div>
+  ),
+};
+
+/**
+ * 四种 size(`sm / default / lg / icon`)。`icon` 尺寸用于纯图标按钮。
+ */
+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>
+    </div>
+  ),
+};
+
+/**
+ * 三种 shape(`default / round / circle`)。`circle` 必须配 `size="icon"`。
+ */
+export const ShapesMatrix: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <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>
+    </div>
+  ),
+};
+
+/**
+ * 状态对照:常态 / 禁用 / 加载。注意 loading 自动 disabled,不需要再传
+ * `disabled`。
+ */
+export const StatesMatrix: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button>Default</Button>
+      <Button disabled>Disabled</Button>
+      <Button loading>Loading</Button>
+      <Button variant="outline" loading icon={<Download />}>
+        Loading replaces icon
+      </Button>
+    </div>
+  ),
+};
+
+/**
+ * `asChild` 模式:把按钮视觉应用到子元素,常见用法是渲染为 `<a>` 链接。
+ * 注意此模式下 `loading` 和 `icon` 会被忽略。
+ */
+export const AsChild: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Button asChild variant="link">
+      <a href="https://teamix-evo.dev">Open docs</a>
+    </Button>
+  ),
+};

package/src/components/button/button.tsx

@@ -0,0 +1,160 @@
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Loader2 } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center gap-2 whitespace-nowrap text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+  {
+    variants: {
+      variant: {
+        default:
+          'bg-primary text-primary-foreground shadow hover:bg-primary/90',
+        secondary:
+          'bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80',
+        destructive:
+          'bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90',
+        outline:
+          'border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground',
+        dashed:
+          'border border-dashed border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        sm: 'h-8 px-3 text-xs',
+        default: 'h-9 px-4 py-2',
+        lg: 'h-10 px-8',
+        icon: 'h-9 w-9',
+      },
+      shape: {
+        default: 'rounded-md',
+        round: 'rounded-full',
+        circle: 'rounded-full aspect-square p-0',
+      },
+      block: {
+        true: 'w-full',
+        false: '',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+      shape: 'default',
+      block: false,
+    },
+  },
+);
+
+export interface ButtonProps
+  extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'>,
+    VariantProps<typeof buttonVariants> {
+  /**
+   * 视觉风格,语义按 design token 走。
+   * @default "default"
+   */
+  variant?:
+    | 'default'
+    | 'secondary'
+    | 'destructive'
+    | 'outline'
+    | 'dashed'
+    | 'ghost'
+    | 'link';
+  /**
+   * 尺寸,`icon` 为正方形纯图标按钮。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg' | 'icon';
+  /**
+   * 形状,`circle` 配 `size="icon"` 得圆形按钮。
+   * @default "default"
+   */
+  shape?: 'default' | 'round' | 'circle';
+  /**
+   * `true` 时撑满父容器宽度。
+   * @default false
+   */
+  block?: boolean;
+  /**
+   * 用 Radix Slot 模式渲染为子元素;此时 `loading` / `icon` 被忽略。
+   * @default false
+   */
+  asChild?: boolean;
+  /**
+   * 显示自旋 spinner,自动 disabled,保留视觉宽度。
+   * @default false
+   */
+  loading?: boolean;
+  /**
+   * 前置 / 后置图标(来自 `lucide-react`)。loading 时被 spinner 替换。
+   */
+  icon?: React.ReactNode;
+  /**
+   * 图标 / spinner 相对文本的位置。
+   * @default "start"
+   */
+  iconPosition?: 'start' | 'end';
+  /** 按钮文本 / 内容。 */
+  children?: React.ReactNode;
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  (
+    {
+      className,
+      variant,
+      size,
+      shape,
+      block,
+      asChild = false,
+      loading = false,
+      icon,
+      iconPosition = 'start',
+      disabled,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const composedClassName = cn(
+      buttonVariants({ variant, size, shape, block, className }),
+    );
+
+    if (asChild) {
+      return (
+        <Slot ref={ref} className={composedClassName} {...props}>
+          {children}
+        </Slot>
+      );
+    }
+
+    const leading = loading ? (
+      <Loader2
+        className="animate-spin motion-reduce:animate-none"
+        aria-hidden="true"
+      />
+    ) : (
+      icon
+    );
+
+    return (
+      <button
+        ref={ref}
+        className={composedClassName}
+        disabled={disabled || loading}
+        aria-busy={loading || undefined}
+        {...props}
+      >
+        {iconPosition === 'start' && leading}
+        {children}
+        {iconPosition === 'end' && leading}
+      </button>
+    );
+  },
+);
+Button.displayName = 'Button';
+
+export { Button, buttonVariants };