@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/avatar/meta.md

@@ -0,0 +1,242 @@
+# Avatar
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+头像 Avatar
+用来代表用户或事物，支持图片、图标或字符展示。图片加载失败时自动降级到 fallback。
+组合结构：Avatar > AvatarImage + AvatarFallback (+ AvatarBadge)；AvatarGroup > Avatar* (+ AvatarGroupCount)
+
+## 使用场景
+
+- 用户列表 / 评论区 / 卡片中展示用户形象
+- 配合用户名称、状态或徽标展示
+- 多个用户聚合展示时使用 AvatarGroup
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'default' \| 'lg'` | – | – | 头像尺寸 |
+| `shape` | `'circle' \| 'square'` | – | – | 头像形状 |
+
+## 示例
+
+### Type
+
+类型：支持图标、字符、图片，以及通过 className 覆盖底色。
+
+```tsx
+<div className="flex items-center gap-3">
+  <Avatar>
+    <AvatarFallback>
+      <UserIcon />
+    </AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback>
+      <SmileIcon />
+    </AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback>U</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+    <AvatarFallback>SC</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback className="bg-primary/10 text-primary">
+      U
+    </AvatarFallback>
+  </Avatar>
+</div>
+```
+
+### Sizes
+
+三种尺寸：sm / default / lg。
+
+```tsx
+<div className="flex items-center gap-3">
+  <Avatar size="sm">
+    <AvatarFallback>S</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback>M</AvatarFallback>
+  </Avatar>
+  <Avatar size="lg">
+    <AvatarFallback>L</AvatarFallback>
+  </Avatar>
+</div>
+```
+
+### Shape
+
+形状：默认 circle 圆形，square 方形使用 rounded-md。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <div className="flex items-center gap-3">
+    <Avatar shape="circle" size="sm">
+      <AvatarFallback>
+        <UserIcon />
+      </AvatarFallback>
+    </Avatar>
+    <Avatar shape="circle">
+      <AvatarFallback>
+        <UserIcon />
+      </AvatarFallback>
+    </Avatar>
+    <Avatar shape="circle" size="lg">
+      <AvatarFallback>
+        <UserIcon />
+      </AvatarFallback>
+    </Avatar>
+  </div>
+  <div className="flex items-center gap-3">
+    <Avatar shape="square" size="sm">
+      <AvatarFallback>
+        <UserIcon />
+      </AvatarFallback>
+    </Avatar>
+    <Avatar shape="square">
+      <AvatarFallback>
+        <UserIcon />
+      </AvatarFallback>
+    </Avatar>
+    <Avatar shape="square" size="lg">
+      <AvatarFallback>
+        <UserIcon />
+      </AvatarFallback>
+    </Avatar>
+  </div>
+</div>
+```
+
+### Fallback
+
+Fallback：图片加载失败时自动降级展示文字。
+
+```tsx
+<Avatar>
+  <AvatarImage src="https://invalid.example.com/avatar.png" alt="broken" />
+  <AvatarFallback>TM</AvatarFallback>
+</Avatar>
+```
+
+### Solid
+
+纯色：通过 className 给 fallback 配 chart 色板，适合用户名首字或类别标识。
+
+```tsx
+<div className="flex items-center gap-2">
+  <Avatar>
+    <AvatarFallback className="bg-chart-1 text-white">默认</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback className="bg-chart-6 text-white">张三</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback className="bg-chart-7 text-white">李四</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback className="bg-chart-3 text-white">赵二</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback className="bg-chart-2 text-white">B老</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback className="bg-chart-5 text-white">天罡</AvatarFallback>
+  </Avatar>
+  <Avatar>
+    <AvatarFallback className="bg-chart-10 text-white">地煞</AvatarFallback>
+  </Avatar>
+</div>
+```
+
+### WithIcon
+
+图标：children 直接放 lucide 图标，无需额外 prop。
+
+```tsx
+<div className="flex items-center gap-3">
+  <Avatar>
+    <AvatarFallback>
+      <UserIcon />
+    </AvatarFallback>
+  </Avatar>
+  <Avatar shape="square">
+    <AvatarFallback>
+      <SmileIcon />
+    </AvatarFallback>
+  </Avatar>
+</div>
+```
+
+### WithBadge
+
+徽标：① AvatarBadge 状态点；② Badge 嵌套数字徽标。
+
+```tsx
+<div className="flex items-center gap-6">
+  <Avatar>
+    <AvatarFallback>
+      <UserIcon />
+    </AvatarFallback>
+    <AvatarBadge className="bg-success" />
+  </Avatar>
+  <Avatar>
+    <AvatarFallback>
+      <UserIcon />
+    </AvatarFallback>
+    <AvatarBadge>
+      <CheckIcon />
+    </AvatarBadge>
+  </Avatar>
+  <div className="relative">
+    <Badge className="absolute -top-1 -right-1 z-10 h-4 min-w-4 px-1">
+      5
+    </Badge>
+    <Avatar shape="square">
+      <AvatarFallback>
+        <UserIcon />
+      </AvatarFallback>
+    </Avatar>
+  </div>
+</div>
+```
+
+### Group
+
+Group：多个头像叠加 + AvatarGroupCount 计数。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <AvatarGroup>
+    <Avatar>
+      <AvatarFallback>A</AvatarFallback>
+    </Avatar>
+    <Avatar>
+      <AvatarFallback>B</AvatarFallback>
+    </Avatar>
+    <Avatar>
+      <AvatarFallback>C</AvatarFallback>
+    </Avatar>
+    <AvatarGroupCount>+3</AvatarGroupCount>
+  </AvatarGroup>
+  <AvatarGroup>
+    <Avatar shape="square" size="lg">
+      <AvatarFallback>A</AvatarFallback>
+    </Avatar>
+    <Avatar shape="square" size="lg">
+      <AvatarFallback>B</AvatarFallback>
+    </Avatar>
+    <Avatar shape="square" size="lg">
+      <AvatarFallback>C</AvatarFallback>
+    </Avatar>
+    <AvatarGroupCount>+3</AvatarGroupCount>
+  </AvatarGroup>
+</div>
+```

package/src/components/avatar/stories.tsx

@@ -0,0 +1,241 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { CheckIcon, SmileIcon, UserIcon } from 'lucide-react';
+
+import { Badge } from '@/components/badge';
+import {
+  Avatar,
+  AvatarBadge,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+} from './index';
+
+const meta: Meta<typeof Avatar> = {
+  title: '数据展示 · Data Display/Avatar 头像',
+  component: Avatar,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 默认：图片头像，加载失败时回落到 fallback。 */
+export const Default: Story = {
+  render: () => (
+    <Avatar>
+      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+      <AvatarFallback>SC</AvatarFallback>
+    </Avatar>
+  ),
+};
+
+/** 类型：支持图标、字符、图片，以及通过 className 覆盖底色。 */
+export const Type: Story = {
+  render: () => (
+    <div className="flex items-center gap-3">
+      <Avatar>
+        <AvatarFallback>
+          <UserIcon />
+        </AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback>
+          <SmileIcon />
+        </AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback>U</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+        <AvatarFallback>SC</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback className="bg-primary/10 text-primary">
+          U
+        </AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+/** 三种尺寸：sm / default / lg。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-3">
+      <Avatar size="sm">
+        <AvatarFallback>S</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback>M</AvatarFallback>
+      </Avatar>
+      <Avatar size="lg">
+        <AvatarFallback>L</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+/** 形状：默认 circle 圆形，square 方形使用 rounded-md。 */
+export const Shape: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center gap-3">
+        <Avatar shape="circle" size="sm">
+          <AvatarFallback>
+            <UserIcon />
+          </AvatarFallback>
+        </Avatar>
+        <Avatar shape="circle">
+          <AvatarFallback>
+            <UserIcon />
+          </AvatarFallback>
+        </Avatar>
+        <Avatar shape="circle" size="lg">
+          <AvatarFallback>
+            <UserIcon />
+          </AvatarFallback>
+        </Avatar>
+      </div>
+      <div className="flex items-center gap-3">
+        <Avatar shape="square" size="sm">
+          <AvatarFallback>
+            <UserIcon />
+          </AvatarFallback>
+        </Avatar>
+        <Avatar shape="square">
+          <AvatarFallback>
+            <UserIcon />
+          </AvatarFallback>
+        </Avatar>
+        <Avatar shape="square" size="lg">
+          <AvatarFallback>
+            <UserIcon />
+          </AvatarFallback>
+        </Avatar>
+      </div>
+    </div>
+  ),
+};
+
+/** Fallback：图片加载失败时自动降级展示文字。 */
+export const Fallback: Story = {
+  render: () => (
+    <Avatar>
+      <AvatarImage src="https://invalid.example.com/avatar.png" alt="broken" />
+      <AvatarFallback>TM</AvatarFallback>
+    </Avatar>
+  ),
+};
+
+/** 纯色：通过 className 给 fallback 配 chart 色板，适合用户名首字或类别标识。 */
+export const Solid: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Avatar>
+        <AvatarFallback className="bg-chart-1 text-white">默认</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback className="bg-chart-6 text-white">张三</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback className="bg-chart-7 text-white">李四</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback className="bg-chart-3 text-white">赵二</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback className="bg-chart-2 text-white">B老</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback className="bg-chart-5 text-white">天罡</AvatarFallback>
+      </Avatar>
+      <Avatar>
+        <AvatarFallback className="bg-chart-10 text-white">地煞</AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+/** 图标：children 直接放 lucide 图标，无需额外 prop。 */
+export const WithIcon: Story = {
+  render: () => (
+    <div className="flex items-center gap-3">
+      <Avatar>
+        <AvatarFallback>
+          <UserIcon />
+        </AvatarFallback>
+      </Avatar>
+      <Avatar shape="square">
+        <AvatarFallback>
+          <SmileIcon />
+        </AvatarFallback>
+      </Avatar>
+    </div>
+  ),
+};
+
+/** 徽标：① AvatarBadge 状态点；② Badge 嵌套数字徽标。 */
+export const WithBadge: Story = {
+  render: () => (
+    <div className="flex items-center gap-6">
+      <Avatar>
+        <AvatarFallback>
+          <UserIcon />
+        </AvatarFallback>
+        <AvatarBadge className="bg-success" />
+      </Avatar>
+      <Avatar>
+        <AvatarFallback>
+          <UserIcon />
+        </AvatarFallback>
+        <AvatarBadge>
+          <CheckIcon />
+        </AvatarBadge>
+      </Avatar>
+      <div className="relative">
+        <Badge className="absolute -top-1 -right-1 z-10 h-4 min-w-4 px-1">
+          5
+        </Badge>
+        <Avatar shape="square">
+          <AvatarFallback>
+            <UserIcon />
+          </AvatarFallback>
+        </Avatar>
+      </div>
+    </div>
+  ),
+};
+
+/** Group：多个头像叠加 + AvatarGroupCount 计数。 */
+export const Group: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <AvatarGroup>
+        <Avatar>
+          <AvatarFallback>A</AvatarFallback>
+        </Avatar>
+        <Avatar>
+          <AvatarFallback>B</AvatarFallback>
+        </Avatar>
+        <Avatar>
+          <AvatarFallback>C</AvatarFallback>
+        </Avatar>
+        <AvatarGroupCount>+3</AvatarGroupCount>
+      </AvatarGroup>
+      <AvatarGroup>
+        <Avatar shape="square" size="lg">
+          <AvatarFallback>A</AvatarFallback>
+        </Avatar>
+        <Avatar shape="square" size="lg">
+          <AvatarFallback>B</AvatarFallback>
+        </Avatar>
+        <Avatar shape="square" size="lg">
+          <AvatarFallback>C</AvatarFallback>
+        </Avatar>
+        <AvatarGroupCount>+3</AvatarGroupCount>
+      </AvatarGroup>
+    </div>
+  ),
+};