@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/avatar/avatar.meta.md

@@ -1,93 +0,0 @@
----
-id: avatar
-name: Avatar
-displayName: 头像
-type: component
-category: data-display
-since: 0.1.0
-package: '@teamix-evo/ui'
----
-
-# Avatar 头像
-
-头像 — Radix Avatar(图片加载失败自动回退到 Fallback)+ antd Avatar 的 `size / shape / Avatar.Group` 并集。
-
-## When to use
-
-- 用户身份标识(列表 / 评论 / 顶部导航)
-- 多人协作场景的成员展示(`AvatarGroup max`)
-- 资源所有者标记
-
-## When NOT to use
-
-- 装饰性图标 → 用 `lucide-react` 图标
-- 大尺寸内容头图 → 用 `AspectRatio` + `<img>` 自由布局
-
-## Props
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `size` | `'sm' \| 'md' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 尺寸(antd 并集:sm 32 / default 40 / lg 48 / xl 64)。 |
-| `shape` | `'circle' \| 'square'` | `"circle"` | – | 形状(antd 并集)。 |
-<!-- auto:props:end -->
-
-## 依赖
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
-
-<!-- auto:deps:begin -->
-### 同库依赖
-
-> `teamix-evo ui add avatar` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-
-### npm 依赖
-
-> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
-
-```bash
-pnpm add @radix-ui/react-avatar@^1.1.0 class-variance-authority@^0.7.0 lucide-react@^0.460.0
-```
-<!-- auto:deps:end -->
-
-## AI 生成纪律
-
-- **必须配 Fallback**:`AvatarImage` 加载失败时无 Fallback 会渲染空白;**永远**写 `<AvatarImage /> + <AvatarFallback>{initials}</AvatarFallback>` 的对子
-- **Fallback 内容用首字母**:取 name 首字母 1~2 个,**不要**塞图标(图标用 `<img>` 直接渲染更准确)
-- **Group 内尺寸统一**:`AvatarGroup` 的 `size` 会覆盖子项 — 不要在 Group 内混用不同尺寸的 Avatar
-- **shape="square" 用于品牌 / 产品 Logo**:用户头像保持 `circle` 默认
-
-## Examples
-
-```tsx
-import {
-  Avatar, AvatarImage, AvatarFallback, AvatarGroup,
-} from '@/components/ui/avatar';
-
-// 基础
-<Avatar>
-  <AvatarImage src="/u/lyca.jpg" alt="lyca" />
-  <AvatarFallback>LY</AvatarFallback>
-</Avatar>
-
-// 尺寸 + 形状
-<Avatar size="lg" shape="square">
-  <AvatarImage src="/p/teamix.svg" alt="Teamix" />
-  <AvatarFallback>TE</AvatarFallback>
-</Avatar>
-
-// 协作组(超出 3 收起)
-<AvatarGroup max={3} size="sm">
-  <Avatar><AvatarImage src="/u/a.jpg" /><AvatarFallback>A</AvatarFallback></Avatar>
-  <Avatar><AvatarImage src="/u/b.jpg" /><AvatarFallback>B</AvatarFallback></Avatar>
-  <Avatar><AvatarImage src="/u/c.jpg" /><AvatarFallback>C</AvatarFallback></Avatar>
-  <Avatar><AvatarImage src="/u/d.jpg" /><AvatarFallback>D</AvatarFallback></Avatar>
-  <Avatar><AvatarImage src="/u/e.jpg" /><AvatarFallback>E</AvatarFallback></Avatar>
-</AvatarGroup>
-```

package/src/components/avatar/avatar.stories.tsx

@@ -1,98 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from './avatar';
-
-const meta: Meta<typeof Avatar> = {
-  title: '数据展示 · Data Display/Avatar',
-  component: Avatar,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '头像 — 表示用户或对象，支持图片 / 文字 / 图标三种回退源。基于 Radix Avatar（图片加载失败自动回退到 fallback）+ antd 增强：尺寸 sm/default/lg/xl、形状 circle/square、`AvatarGroup` 堆叠。未传 children 时 fallback 默认渲染 lucide `User` 占位图标。',
-      },
-    },
-  },
-  argTypes: {
-    size: { control: 'select', options: ['sm', 'default', 'lg', 'xl'] },
-    shape: { control: 'inline-radio', options: ['circle', 'square'] },
-  },
-  args: { size: 'default', shape: 'circle' },
-};
-
-export default meta;
-type Story = StoryObj<typeof Avatar>;
-
-export const Playground: Story = {
-  render: (args) => (
-    <Avatar {...args}>
-      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-      <AvatarFallback>SH</AvatarFallback>
-    </Avatar>
-  ),
-};
-
-export const SizesAndShapes: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex items-end gap-3">
-      {(['sm', 'default', 'lg', 'xl'] as const).map((s) => (
-        <Avatar key={s} size={s}>
-          <AvatarImage src="https://github.com/shadcn.png" />
-          <AvatarFallback>SH</AvatarFallback>
-        </Avatar>
-      ))}
-      <Avatar shape="square">
-        <AvatarFallback>TE</AvatarFallback>
-      </Avatar>
-    </div>
-  ),
-};
-
-export const FallbackOnly: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex items-center gap-3">
-      <Avatar>
-        <AvatarFallback>JD</AvatarFallback>
-      </Avatar>
-      <Avatar>
-        <AvatarFallback>李</AvatarFallback>
-      </Avatar>
-      <Avatar>
-        <AvatarFallback>?</AvatarFallback>
-      </Avatar>
-    </div>
-  ),
-};
-
-export const DefaultIconFallback: Story = {
-  name: '默认图标回退',
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex items-end gap-3">
-      {(['sm', 'default', 'lg', 'xl'] as const).map((s) => (
-        <Avatar key={s} size={s}>
-          {/* 未传图片与文字 children, fallback 自动渲染 lucide User 占位 */}
-          <AvatarFallback />
-        </Avatar>
-      ))}
-      <Avatar shape="square">
-        <AvatarFallback />
-      </Avatar>
-    </div>
-  ),
-};
-
-export const Group: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <AvatarGroup max={3}>
-      {['A', 'B', 'C', 'D', 'E'].map((c) => (
-        <Avatar key={c}>
-          <AvatarFallback>{c}</AvatarFallback>
-        </Avatar>
-      ))}
-    </AvatarGroup>
-  ),
-};

package/src/components/avatar/avatar.tsx

@@ -1,127 +0,0 @@
-import * as React from 'react';
-import * as AvatarPrimitive from '@radix-ui/react-avatar';
-import { cva, type VariantProps } from 'class-variance-authority';
-import { User } from 'lucide-react';
-
-import { cn } from '@/utils/cn';
-
-const avatarVariants = cva('relative flex shrink-0 overflow-hidden bg-muted', {
-  variants: {
-    size: {
-      sm: 'size-8 text-xs',
-      md: 'size-10 text-xs',
-      default: 'size-10 text-xs',
-      lg: 'size-12 text-sm',
-      xl: 'size-16 text-base',
-    },
-    shape: {
-      circle: 'rounded-full',
-      square: 'rounded-md',
-    },
-  },
-  defaultVariants: { size: 'md', shape: 'circle' },
-});
-
-export interface AvatarProps
-  extends React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>,
-    VariantProps<typeof avatarVariants> {
-  /**
-   * 尺寸(antd 并集:sm 32 / default 40 / lg 48 / xl 64)。
-   * @default "default"
-   */
-  size?: 'sm' | 'md' | 'default' | 'lg' | 'xl';
-  /**
-   * 形状(antd 并集)。
-   * @default "circle"
-   */
-  shape?: 'circle' | 'square';
-}
-
-const Avatar = React.forwardRef<
-  React.ElementRef<typeof AvatarPrimitive.Root>,
-  AvatarProps
->(({ className, size, shape, ...props }, ref) => (
-  <AvatarPrimitive.Root
-    ref={ref}
-    className={cn(avatarVariants({ size, shape }), className)}
-    {...props}
-  />
-));
-Avatar.displayName = AvatarPrimitive.Root.displayName;
-
-const AvatarImage = React.forwardRef<
-  React.ElementRef<typeof AvatarPrimitive.Image>,
-  React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Image>
->(({ className, ...props }, ref) => (
-  <AvatarPrimitive.Image
-    ref={ref}
-    className={cn('aspect-square size-full object-cover', className)}
-    {...props}
-  />
-));
-AvatarImage.displayName = AvatarPrimitive.Image.displayName;
-
-const AvatarFallback = React.forwardRef<
-  React.ElementRef<typeof AvatarPrimitive.Fallback>,
-  React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Fallback>
->(({ className, children, ...props }, ref) => (
-  <AvatarPrimitive.Fallback
-    ref={ref}
-    className={cn(
-      'flex size-full items-center justify-center font-medium text-muted-foreground',
-      className,
-    )}
-    {...props}
-  >
-    {children ?? <User className="h-3/5 w-3/5" aria-hidden="true" />}
-  </AvatarPrimitive.Fallback>
-));
-AvatarFallback.displayName = AvatarPrimitive.Fallback.displayName;
-
-// ─── AvatarGroup(antd 并集)────────────────────────────────────────────────
-
-export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
-  /**
-   * 显示前 N 个 Avatar,其余收为 `+N` 折叠气泡。
-   * @default 3
-   */
-  max?: number;
-  /** Group 内所有 Avatar 共享的尺寸,会覆盖单个 Avatar 的 size。 */
-  size?: AvatarProps['size'];
-}
-
-const AvatarGroup = React.forwardRef<HTMLDivElement, AvatarGroupProps>(
-  ({ className, max = 3, size, children, ...props }, ref) => {
-    const items = React.Children.toArray(children);
-    const visible = items.slice(0, max);
-    const overflow = items.length - max;
-
-    return (
-      <div
-        ref={ref}
-        className={cn(
-          'flex items-center -space-x-2 [&>*]:ring-2 [&>*]:ring-background',
-          className,
-        )}
-        {...props}
-      >
-        {visible.map((child, i) =>
-          React.isValidElement(child) && size
-            ? React.cloneElement(child as React.ReactElement<AvatarProps>, {
-                size,
-                key: i,
-              })
-            : child,
-        )}
-        {overflow > 0 ? (
-          <Avatar size={size}>
-            <AvatarFallback>+{overflow}</AvatarFallback>
-          </Avatar>
-        ) : null}
-      </div>
-    );
-  },
-);
-AvatarGroup.displayName = 'AvatarGroup';
-
-export { Avatar, AvatarImage, AvatarFallback, AvatarGroup, avatarVariants };

package/src/components/badge/badge.meta.md

@@ -1,120 +0,0 @@
----
-id: badge
-name: Badge
-displayName: 徽标
-type: component
-category: data-display
-since: 0.1.0
-package: '@teamix-evo/ui'
----
-
-# Badge 徽标
-
-徽标 — shadcn 文本标签风格 + antd 数字徽标 / 红点 / 状态点的合集。
-**单组件四种形态**,根据 props 自动切换:
-
-| 形态             | 触发条件                                | 示例                                       |
-| ---------------- | --------------------------------------- | ------------------------------------------ |
-| 文本徽标(shadcn) | 无 `count / dot / status`,仅 `children` | `<Badge>New</Badge>`                       |
-| 包裹徽标(antd)   | 有 `children` + `count` 或 `dot`        | `<Badge count={5}><Avatar /></Badge>`      |
-| 独立数字气泡     | 仅 `count`,无 `children`                | `<Badge count={3} />`                      |
-| 状态点 + 文字    | 有 `status`                             | `<Badge status="success" text="运行中" />` |
-
-## When to use
-
-- **文本徽标**:版本号 / 标签 / 状态短文(`Beta` / `New` / `Pro`)
-- **数字气泡**:消息未读数、购物车数量等数字提示(浮在 Avatar / 按钮右上角)
-- **红点**:有未读但不需要数字时
-- **状态点**:列表 / 详情页的资源状态(运行中 / 已停止 / 错误等)
-
-## When NOT to use
-
-- 需要可关闭、可定制颜色的标签 → 用 `Tag`(v0.7 提供)
-- 角标(置于 Card 或图片右上角的丝带)→ 用 `Badge.Ribbon`(v0.x 提供)
-- 大段说明文字 → 用 `Alert` 或 `Tooltip`
-
-## Props
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`badge.tsx`](./badge.tsx) 的 `BadgeProps` interface JSDoc。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'warning'` | `"default"` | – | 视觉风格;`default / secondary / destructive / outline` 来自 shadcn, `success / warning` 来自 antd 状态色补足。 |
-| `count` | `number` | – | – | 数字徽标内容。配合 `children` 时,数字气泡浮在右上角(包裹模式); 无 `children` 时,渲染为独立小气泡(standalone 模式)。 `0` 默认不显示,需配 `showZero`。 |
-| `overflowCount` | `number` | `99` | – | 数字超过此值时显示 `${overflowCount}+`。仅在有 `count` 时生效。 |
-| `showZero` | `boolean` | `false` | – | `true` 时即使 `count === 0` 也显示气泡。 |
-| `dot` | `boolean` | `false` | – | `true` 时渲染为纯红点(无文字)。配合 `children` 时浮在右上角。 `dot` 与 `count` 同时存在,`dot` 优先。 |
-| `status` | `BadgeStatus` | – | – | 状态点 + 文字(`<dot> <text>` 行内组合),用于"运行中 / 已停止"等状态描述。 必须与 `children` 互斥使用 — 这是 standalone 状态条形态。 |
-| `text` | `React.ReactNode` | – | – | 配合 `status` 使用,渲染在状态点右侧。无 `status` 时忽略。 |
-| `children` | `React.ReactNode` | – | – | 被包裹的元素(包裹模式)或徽标文本内容(standalone 文本模式)。 |
-<!-- auto:props:end -->
-
-## 依赖
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
-
-<!-- auto:deps:begin -->
-### 同库依赖
-
-> `teamix-evo ui add badge` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-
-### npm 依赖
-
-> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
-
-```bash
-pnpm add class-variance-authority@^0.7.0
-```
-<!-- auto:deps:end -->
-
-> 除上述 props 外,Badge 透传所有 `<span>` 原生属性(`onClick` / `aria-*` / `id` / ...)。
-
-## AI 生成纪律
-
-- **形态自动判断**:不要同时传 `count + dot`(`dot` 优先)、`status + children`(语义冲突),组件会按优先级降级,但人写代码时应明确单一形态。
-- **status 颜色不要硬编码**:`success / warning / error` 等颜色已在 design `foundations/color/semantic.md` 锁定;**不要**绕过 `status` prop 直接写 `bg-green-500` 等。
-- **count 必须为非负整数**:负数会渲染但语义错乱;0 默认不显示,需要显示 0 时显式传 `showZero`。
-- **包裹模式的 ring**:气泡有 `ring-2 ring-background` 模拟"挖空"边框,**不要**改这里的 ring 颜色 — 切换 dark mode 时会自动适配。
-- **状态条文案**:`text` 用现在分词或简短状态语(`运行中` / `已停止` / `异常`),不超过 6 个汉字。
-- **不要堆叠**:同一容器内不要并排出现多种 Badge 形态(数字 + 状态条),信息过载;改用一张分组的状态卡片。
-
-## Examples
-
-```tsx
-import { Badge } from '@/components/ui/badge';
-import { Bell } from 'lucide-react';
-
-// 文本徽标(shadcn)
-<Badge>New</Badge>
-<Badge variant="secondary">Beta</Badge>
-<Badge variant="destructive">Critical</Badge>
-<Badge variant="success">Verified</Badge>
-<Badge variant="warning">Pending</Badge>
-
-// 数字徽标(antd 风格 — 包裹模式)
-<Badge count={5}>
-  <Bell className="size-6" />
-</Badge>
-
-<Badge count={120} overflowCount={99}>
-  <Bell className="size-6" />
-</Badge>
-
-// 红点
-<Badge dot>
-  <Bell className="size-6" />
-</Badge>
-
-// 独立数字气泡
-<Badge count={3} />
-
-// 状态点 + 文字
-<Badge status="success" text="运行中" />
-<Badge status="processing" text="部署中" />
-<Badge status="error" text="异常" />
-```

package/src/components/badge/badge.stories.tsx

@@ -1,153 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Bell, MessageSquare, ShoppingCart } from 'lucide-react';
-import { Badge } from './badge';
-
-const meta: Meta<typeof Badge> = {
-  title: '数据展示 · Data Display/Badge',
-  component: Badge,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '徽标 — shadcn 文本徽标 + antd 数字 / 红点 / 状态点的合集,单组件四种形态。',
-      },
-    },
-  },
-  argTypes: {
-    variant: {
-      description: '视觉风格(仅文本徽标形态生效)',
-      control: 'select',
-      options: [
-        'default',
-        'secondary',
-        'destructive',
-        'outline',
-        'success',
-        'warning',
-      ],
-    },
-    count: {
-      description: '数字徽标(配 children 时浮在右上角,否则独立气泡)',
-      control: { type: 'number', min: 0 },
-    },
-    overflowCount: {
-      description: 'count 溢出阈值',
-      control: { type: 'number', min: 1 },
-    },
-    showZero: {
-      description: 'count 为 0 时是否显示',
-      control: 'boolean',
-    },
-    dot: {
-      description: '渲染为纯红点(配 children 时浮在右上角)',
-      control: 'boolean',
-    },
-    status: {
-      description: '状态点 + 文字(与 children 互斥)',
-      control: 'select',
-      options: [
-        undefined,
-        'default',
-        'success',
-        'processing',
-        'error',
-        'warning',
-      ],
-    },
-    text: {
-      description: '配合 status 渲染的文字',
-      control: 'text',
-    },
-    children: {
-      description: '徽标内容(文本模式)或被包裹元素',
-      control: 'text',
-    },
-  },
-  args: {
-    children: 'New',
-    variant: 'default',
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof Badge>;
-
-/** 文本徽标(默认形态)。在 Controls 调 variant / 文字 / 切换形态。 */
-export const Playground: Story = {};
-
-/** 六种 variant 文本徽标对照。 */
-export const VariantsMatrix: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex flex-wrap items-center gap-3">
-      <Badge>Default</Badge>
-      <Badge variant="secondary">Secondary</Badge>
-      <Badge variant="destructive">Destructive</Badge>
-      <Badge variant="outline">Outline</Badge>
-      <Badge variant="success">Success</Badge>
-      <Badge variant="warning">Warning</Badge>
-    </div>
-  ),
-};
-
-/** 数字徽标 — 包裹模式(浮在 children 右上角)。 */
-export const NumericWrapped: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex items-center gap-8">
-      <Badge count={5}>
-        <Bell className="size-6 text-muted-foreground" />
-      </Badge>
-      <Badge count={32}>
-        <MessageSquare className="size-6 text-muted-foreground" />
-      </Badge>
-      <Badge count={120} overflowCount={99}>
-        <ShoppingCart className="size-6 text-muted-foreground" />
-      </Badge>
-    </div>
-  ),
-};
-
-/** 红点 — 无文字提示有未读。 */
-export const Dot: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex items-center gap-8">
-      <Badge dot>
-        <Bell className="size-6 text-muted-foreground" />
-      </Badge>
-      <Badge dot>
-        <MessageSquare className="size-6 text-muted-foreground" />
-      </Badge>
-    </div>
-  ),
-};
-
-/** 独立数字气泡(无 children)。常用于内联标记。 */
-export const StandaloneCount: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex items-center gap-3">
-      <Badge count={1} />
-      <Badge count={9} />
-      <Badge count={99} />
-      <Badge count={150} overflowCount={99} />
-      <Badge count={0} showZero />
-    </div>
-  ),
-};
-
-/** 状态点 + 文字(列表 / 详情页资源状态)。 */
-export const StatusMatrix: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex flex-col items-start gap-2">
-      <Badge status="success" text="运行中" />
-      <Badge status="processing" text="部署中" />
-      <Badge status="warning" text="降级运行" />
-      <Badge status="error" text="异常" />
-      <Badge status="default" text="已停止" />
-    </div>
-  ),
-};