@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/icon/icon.meta.md

@@ -0,0 +1,170 @@
+---
+id: icon
+name: Icon
+displayName: 图标
+type: component
+category: general
+since: 0.1.0
+package: '@teamix-evo/ui'
+---
+
+# Icon 图标
+
+图标容器 — 纯样式包裹层。**单一 children 通道**(对齐 Mantine ThemeIcon),不再提供 `icon` prop;**`variant`(形态) + `color`(颜色) 双 prop**(对齐 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md) 业界最大公约数),不再有 `withBackground/shape/bgTone` 三轨。**7 档 size**(xs/sm/md/lg/xl/2xl/3xl)依托 Tailwind v4 spacing scale,无需新增 design token。承接 cloud-design Icon 的"圆形/方形 + 彩色背景"为 `variant="circle"|"square"` + `color`。类名/样式 在所有分支均完整透传到外层根节点。
+
+## When to use
+
+- **状态指示** — `color="success / warning / destructive"` + 状态图标
+- **带背景容器的入口图标** — `variant="circle"|"square"` + `color`(PageHeader / 卡片头 / 数据概览)
+- **iconfont / 业务图集** — 通过 children 通道接 v0.2 `createIconfontIcon` 工厂返回的组件
+- **Slot 包装** — 给 `<a>` / `<button>` 一次性套上统一图标样式
+
+## When NOT to use
+
+- **常规 loading 全屏 / 局部** → 用 [`Spinner`](../spinner/spinner.meta.md),自带 `role="status"` + `sr-only` 文案
+- **纯 lucide 直用 + className 控样式即可** → 不需要包 `<Icon>`,shadcn 工程理念就是 `import { Smile } from 'lucide-react'` 直用
+- **用户头像 / 品牌 Logo** → 用 [`Avatar`](../avatar/avatar.meta.md)
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `children` | `React.ReactNode` | – | ✓ | 渲染目标 — 必填。lucide-react / 自定义 svg / iconfont 工厂返回的组件均可。 单一 children 通道,不再提供 `icon` prop(避免 `<Icon icon=...>` 组件名 + 同名 prop 的语义冗余)。 |
+| `variant` | `IconVariant` | `"plain"` | – | 形态 — 决定是否带背景容器。 - `plain`:无背景,size 直接控前景 svg(默认) - `circle` / `square`:带 `color` 配色的背景容器,inner svg 自动小一档 |
+| `color` | `IconColor` | `"default"` | – | 语义色 — 6 档枚举,字面与 OpenTrek tokens 对齐(见 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md))。 - `variant=plain` 时控前景色 - `variant=circle/square` 时同时控容器背景 + 前景(浅底深字) |
+| `size` | `IconSize` | `"md"` | – | 尺寸 — 7 档枚举 + inherit。`inherit` 走 `1em`,跟随父级字号(用于 Title / Button 内联场景)。 当 `variant!=plain` 时,该 size 指容器尺寸,inner svg 自动用对应小一档。 |
+| `spin` | `boolean` | `false` | – | 旋转动效 — 与 antd Icon `spin` 对齐,Tailwind `animate-spin` 实现。 |
+| `rotate` | `number` | – | – | 静态旋转角度(度数)— 与 antd Icon `rotate` 对齐,通过 inline transform 实现。 与 `spin` 同时使用语义模糊,不建议同用。 |
+| `asChild` | `boolean` | `false` | – | Slot 模式 — 把渲染目标交给消费方提供的子元素。开启时 `variant` 强制走 plain。 |
+| `decorative` | `boolean` | `true` | – | 装饰性图标(默认 true,自动 `aria-hidden="true"`)。 当图标承载语义信息时设为 false,**必须**同时提供 `aria-label` 或被 `<button aria-label>` 包裹。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add icon` 时,以下 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 -->
+
+## AI 生成纪律
+
+### 硬约束
+
+- **走 children 通道,不重发明 `icon` prop** — `<Icon><Smile /></Icon>`,不要再试图传 `<Icon icon={Smile} />`(该 prop 已下线)
+- **禁止内联 `<svg>`** — 用 lucide 现成图标,特殊场景才走 children 通道传自定义 svg
+- **禁止从 `@ant-design/icons` / `@alifd/next` Icon 引入** — 由 `@teamix-evo/eslint-config` 的 `teamix-evo/icon-from-lucide` 规则强制
+- **禁止给 Icon 加 arbitrary `size-[Xpx]`** — 用 7 档枚举 size,真有特殊像素诉求走 lint warn 路径用 `className`,且每处需 review
+- **禁止颜色字面量** — `style={{ color: '#1DC11D' }}` 是 cloud-design 老写法,现在走 `color` 枚举或父级 currentColor
+- **禁止给 Icon 加点击事件后忘记加 `decorative={false}` + `aria-label`** — 装饰性图标不应承担交互;要交互必须语义化(包 `<button>`)
+
+### 推荐范式
+
+- 基础用法:`<Icon><Smile /></Icon>`(默认装饰性,默认 md size,跟随父色)
+- 状态色:`<Icon color="success" size="lg"><CheckCircle2 /></Icon>`
+- 背景容器:`<Icon variant="circle" color="warning" size="lg"><AlertTriangle /></Icon>`
+- 加载:`<Icon spin color="muted"><Loader2 /></Icon>`(常规 loading 优先用 `<Spinner>`)
+- 可点击:`<button aria-label="删除"><Icon><Trash2 /></Icon></button>`(图标装饰性,语义靠 button)
+- Slot 包裹:`<Icon asChild size="lg" color="primary"><a href="..."><MyCustomLogo /></a></Icon>`
+
+### 反例
+
+- ❌ `<Icon icon={Smile} />` — `icon` prop 已下线,一律走 children
+- ❌ `<Icon><Smile /><Heart /></Icon>` — 只能传单一 children(svg/lucide 组件),多个子元素语义不明
+- ❌ `<Icon onClick={...}><Trash2 /></Icon>` — 装饰性图标不应承担交互;要交互包 `<button>`
+- ❌ `<Icon spin rotate={45}><Loader2 /></Icon>` — spin 与 rotate 同用语义模糊,选一个
+- ❌ 全屏 loading 用 `<Icon spin size="3xl"><Loader2 /></Icon>` — 用 `<Spinner size="xl" />`,后者带读屏文案
+
+## Examples
+
+```tsx
+import { Icon } from '@/components/icon';
+import {
+  AlertTriangle,
+  CheckCircle2,
+  Info,
+  Loader2,
+  Search,
+  Smile,
+  Trash2,
+} from 'lucide-react';
+
+// 基础(装饰性,跟随父色)
+<Icon><Smile /></Icon>
+
+// 状态色
+<Icon color="success" size="lg"><CheckCircle2 /></Icon>
+
+// 旋转动效
+<Icon spin color="muted"><Loader2 /></Icon>
+
+// 静态旋转
+<Icon rotate={90} size="lg"><AlertTriangle /></Icon>
+
+// 背景容器
+<Icon variant="circle" color="warning" size="lg"><AlertTriangle /></Icon>
+<Icon variant="square" color="primary" size="2xl"><Smile /></Icon>
+
+// 非装饰(承载语义,必须 aria-label)
+<Icon decorative={false} aria-label="提示信息"><Info /></Icon>
+
+// 装饰图标 + 交互按钮(语义靠 button)
+<button type="button" aria-label="删除">
+  <Icon><Trash2 /></Icon>
+</button>
+
+// Slot 包裹
+<Icon asChild size="lg" color="primary">
+  <a href="/search" aria-label="搜索">
+    <Search />
+  </a>
+</Icon>
+
+// 自定义 svg / iconfont 工厂
+<Icon size="lg" color="primary">
+  <svg viewBox="0 0 24 24" fill="currentColor">
+    <path d="M12 2 L22 22 L2 22 Z" />
+  </svg>
+</Icon>
+
+// className / style 透传(所有分支均合并到外层根节点)
+<Icon variant="circle" color="warning" size="lg"
+      className="ring-2 ring-warning ring-offset-2"
+      style={{ marginLeft: 8 }}>
+  <AlertTriangle />
+</Icon>
+```
+
+## 路线图
+
+| 阶段        | 能力                                                                     |
+| ----------- | ------------------------------------------------------------------------ |
+| v0.1 (本期) | children 通道 + variant + color + 7 档 size + spin/rotate/Slot/无障碍    |
+| v0.2        | iconfont 工厂 `createIconfontIcon({ scriptUrl })`,API 对 `<Icon>` 不破坏 |
+| v0.3+       | 多 icon set 工厂(heroicons / tabler 等),组件本身仍保持 lucide 默认源     |
+
+> **API 在 v0.1 就稳定** — 后续加源不破坏现有 prop。`icon` / `withBackground` / `shape` / `bgTone` 在 v0.1 进入 stable 前一次性由 `children` + `variant` + `color` 取代,后续不再变动。
+
+## 关联
+
+- 范本组件:[Spinner](../spinner/spinner.meta.md) — lucide 轻封装的最简范本
+- 关联组件:[PageHeader](../page-header/page-header.meta.md) — `withBackground` 能力的首个消费者
+- 关联 ADR:[ADR 0008](../../../../../docs/adr/0008-eslint-visual-rules-warn-baseline.md) — visual rules warn baseline(success / warning token 缺口处置)
+- 设计文档:[DEVELOPMENT.md](./DEVELOPMENT.md)

package/src/components/icon/icon.stories.tsx

@@ -0,0 +1,344 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  AlertTriangle,
+  Bell,
+  Check,
+  CheckCircle2,
+  Heart,
+  Info,
+  Loader2,
+  Search,
+  Server,
+  Settings,
+  Smile,
+  Trash2,
+  XCircle,
+} from 'lucide-react';
+
+import { Icon } from './icon';
+
+// 让 Storybook controls 能选 children 渲染哪个 lucide 组件。
+const iconMapping = {
+  Smile: <Smile />,
+  Check: <Check />,
+  CheckCircle2: <CheckCircle2 />,
+  AlertTriangle: <AlertTriangle />,
+  Loader2: <Loader2 />,
+  Search: <Search />,
+  Trash2: <Trash2 />,
+  Settings: <Settings />,
+  Info: <Info />,
+  Bell: <Bell />,
+  Heart: <Heart />,
+  Server: <Server />,
+  XCircle: <XCircle />,
+};
+
+const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
+const COLORS = [
+  'default',
+  'muted',
+  'primary',
+  'success',
+  'warning',
+  'destructive',
+] as const;
+
+const meta: Meta<typeof Icon> = {
+  title: '通用 · General/Icon',
+  component: Icon,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Icon 图标容器 —— 纯样式包裹层。**单一 children 通道**(对齐 Mantine ThemeIcon),没有 `icon` prop;**`variant` + `color` 双轴**(对齐 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md) 双 prop 治理),没有 `withBackground/shape/bgTone` 三轨。**7 档 size**(xs/sm/md/lg/xl/2xl/3xl) + `inherit`,Tailwind v4 spacing scale 直接覆盖,无需新增 design token。承接 cloud-design Icon 的"圆形/方形 + 彩色背景"能力为 `variant="circle"|"square"` + `color`;antd `@ant-design/icons` 的 `spin/rotate` 对齐保留;`asChild` 走 Slot 模式。className / style 在所有分支均完整透传到外层根节点。视觉走 OpenTrek semantic tokens。',
+      },
+    },
+  },
+  argTypes: {
+    children: {
+      control: 'select',
+      options: Object.keys(iconMapping),
+      mapping: iconMapping,
+    },
+    variant: {
+      control: 'inline-radio',
+      options: ['plain', 'circle', 'square'],
+    },
+    size: { control: 'select', options: [...SIZES, 'inherit'] },
+    color: { control: 'inline-radio', options: [...COLORS] },
+    spin: { control: 'boolean' },
+    rotate: { control: { type: 'number', min: 0, max: 360, step: 15 } },
+    decorative: { control: 'boolean' },
+    asChild: { control: 'boolean' },
+  },
+  args: {
+    children: <Smile />,
+    variant: 'plain',
+    color: 'default',
+    size: 'md',
+    spin: false,
+    decorative: true,
+    asChild: false,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ─── 1. Playground ──────────────────────────────────────────────────────────
+
+export const Playground: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '互动场:在右侧 Controls 切换 children / variant / color / size / spin / rotate,实时观察组合效果。',
+      },
+    },
+  },
+};
+
+// ─── 2. Sizes(7 档 + inherit)─────────────────────────────────────────────
+
+export const Sizes: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '7 档尺寸刻度:xs(12) / sm(16) / md(20,默认) / lg(24) / xl(28) / 2xl(36) / 3xl(48)。`inherit` 走 `1em` 跟随父字号,适合 Title / Button 内联。',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex items-end gap-6">
+      {SIZES.map((s) => (
+        <div key={s} className="flex flex-col items-center gap-2">
+          <Icon size={s}>
+            <Smile />
+          </Icon>
+          <span className="text-xs text-muted-foreground">{s}</span>
+        </div>
+      ))}
+      <div className="flex flex-col items-center gap-2 text-2xl">
+        <Icon size="inherit">
+          <Smile />
+        </Icon>
+        <span className="text-xs text-muted-foreground">inherit · 1em</span>
+      </div>
+    </div>
+  ),
+};
+
+// ─── 3. Colors(6 档语义色)───────────────────────────────────────────────
+
+export const Colors: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '6 档语义 color(对齐 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md)):default / muted / primary / success / warning / destructive。`default` 走 currentColor,跟随父级。',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex items-center gap-6">
+      {COLORS.map((c) => (
+        <div key={c} className="flex flex-col items-center gap-2">
+          <Icon color={c} size="lg">
+            <Heart />
+          </Icon>
+          <span className="text-xs text-muted-foreground">{c}</span>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+// ─── 4. Variants(plain / circle / square)─────────────────────────────────
+
+export const Variants: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '三种形态:`plain`(无背景,默认)、`circle`(圆形容器)、`square`(方形容器)。带背景容器时 `color` 同时驱动 bg(浅底)+ 前景(深字)。',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex items-center gap-8">
+      {(['plain', 'circle', 'square'] as const).map((v) => (
+        <div key={v} className="flex flex-col items-center gap-2">
+          <Icon variant={v} color="primary" size="lg">
+            <Server />
+          </Icon>
+          <span className="text-xs text-muted-foreground">{v}</span>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+// ─── 5. Variant × Color 矩阵 ──────────────────────────────────────────────────
+
+export const VariantColorMatrix: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '形态 × 语义色全矩阵 — 跨变体回归确认 token 与尺寸联动正确(success-subtle / warning-subtle / accent / destructive 透明度叠加)。',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex flex-col gap-6">
+      {(['circle', 'square'] as const).map((v) => (
+        <div key={v} className="flex flex-col gap-2">
+          <div className="text-xs font-medium text-muted-foreground">
+            variant = {v}
+          </div>
+          <div className="grid grid-cols-6 gap-4">
+            {COLORS.map((c) => (
+              <div key={c} className="flex flex-col items-center gap-2">
+                <Icon variant={v} color={c} size="lg">
+                  <Bell />
+                </Icon>
+                <span className="text-xs text-muted-foreground">{c}</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+// ─── 6. Spinning ────────────────────────────────────────────────────────────
+
+export const Spinning: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`spin` 启用 `animate-spin` 旋转动效,典型用于 Loader2。常规 loading 优先用 `<Spinner>`(自带 `role="status"` + 读屏文案)。',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex items-center gap-6">
+      <Icon spin color="muted" size="lg">
+        <Loader2 />
+      </Icon>
+      <Icon spin color="primary" size="xl">
+        <Loader2 />
+      </Icon>
+      <Icon spin variant="circle" color="primary" size="lg">
+        <Loader2 />
+      </Icon>
+    </div>
+  ),
+};
+
+// ─── 7. Rotated ─────────────────────────────────────────────────────────────
+
+export const Rotated: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`rotate` 静态旋转(度数)。inline transform 实现,与 `spin` 同时使用语义模糊。',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex items-center gap-6">
+      {[0, 45, 90, 135, 180].map((deg) => (
+        <div key={deg} className="flex flex-col items-center gap-2">
+          <Icon rotate={deg} size="lg">
+            <AlertTriangle />
+          </Icon>
+          <span className="text-xs text-muted-foreground">{deg}°</span>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+// ─── 8. AsChild(Slot 模式)───────────────────────────────────────────────
+
+export const AsChild: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Slot 模式 — 把 size / color / spin 类合并到 children 根节点,适合给 `<a>` / 自定义 logo 一次性套上统一 Icon 样式。开启 asChild 时强制走 plain。',
+      },
+    },
+  },
+  args: {
+    asChild: true,
+    size: 'lg',
+    color: 'primary',
+    children: (
+      <a href="#search" aria-label="搜索">
+        <Search />
+      </a>
+    ),
+  },
+};
+
+// ─── 9. WithAriaLabel(非装饰)──────────────────────────────────────────
+
+export const WithAriaLabel: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '非装饰图标 — `decorative={false}` 自动加 `role="img"`,**必须**同时提供 `aria-label`。读屏会把 label 当成内容朗读。',
+      },
+    },
+  },
+  args: {
+    decorative: false,
+    'aria-label': '提示信息',
+    color: 'primary',
+    size: 'lg',
+    children: <Info />,
+  },
+};
+
+// ─── 10. ClassName / Style 透传 ─────────────────────────────────────────────
+
+export const ClassNameAndStyle: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'className / style 在所有分支均合并到外层根节点。这里展示 plain / circle 两种形态下用 className 加 hover 缩放、用 style 加外边距,与组件内置样式正确叠加(tailwind-merge 处理冲突)。',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex items-center gap-6">
+      <Icon
+        size="lg"
+        color="primary"
+        className="transition-transform hover:scale-125"
+        style={{ marginRight: 8 }}
+      >
+        <Heart />
+      </Icon>
+      <Icon
+        variant="circle"
+        color="warning"
+        size="lg"
+        className="ring-2 ring-warning ring-offset-2"
+        style={{ marginLeft: 8 }}
+      >
+        <AlertTriangle />
+      </Icon>
+    </div>
+  ),
+};