@teamix-evo/ui 0.4.0 → 0.5.0

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

@@ -1,170 +0,0 @@
----
-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

@@ -1,344 +0,0 @@
-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>
-  ),
-};