@teamix-evo/ui 0.3.0 → 0.5.0

package/README.md

@@ -10,7 +10,7 @@ Source-injected UI components for Teamix Evo. Based on shadcn/ui, extended with
 - **First consumer of `@teamix-evo/tokens`**: the dev server imports OpenTrek tokens directly from the tokens package (`dev/index.css`), so components are previewed against the SAME tokens that ship to consumers — no mock values, single source of truth.
 - **No variant**: brand differences are absorbed by `@teamix-evo/tokens` (CSS variables). One UI package serves all design variants.
 - **className contract**: components write `className="bg-primary"` (Tailwind v4 utility), which resolves to `var(--color-primary)` from the project's `tokens.theme.css`. Semantic token names (`primary`, `destructive`, `muted`, ...) align with shadcn — see `@teamix-evo/tokens` for the token layer.
-- **Imports**: source files use placeholder paths like `@/utils/cn`. The CLI rewrites these to user-configured aliases (e.g. `@/lib/utils`) at install time.
+- **Imports**: source files use real alias paths (e.g. `@/lib/utils`, `@/components/button`) that match the default user aliases. The CLI's `rewriteImports` keeps them aligned with `aliases` declared in `.teamix-evo/config.json` at install time.
 - **`updateStrategy: frozen`** is the default — once installed, the CLI never overwrites the file. Upgrades go through an AI + skill flow (v0.3, see PLAN §10.9).
 
 ## Package layout
@@ -34,8 +34,9 @@ packages/ui/
     │       ├── button.tsx
     │       ├── button.meta.md    # AI-readable component intro (Props auto-generated)
     │       └── button.stories.tsx (CSF 3.0)
-    └── utils/
-        └── cn.ts
+    └── lib/
+        ├── utils.ts        ← cn() helper
+        └── color.ts       ← Color util
 ```
 
 ## Scripts
@@ -73,7 +74,7 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). MCP reads
 
 | id                                           | 中文名       | 英文        | 来源 | 关键能力 / antd 对应                                                            |
 | -------------------------------------------- | ------------ | ----------- | ---- | ------------------------------------------------------------------------------- |
-| [cn](src/utils/cn.ts)                        | 类名合并工具 | cn          | util | clsx + tailwind-merge,所有组件的 className 合并基础                             |
+| [cn](src/lib/utils.ts)                       | 类名合并工具 | cn          | util | clsx + tailwind-merge,所有组件的 className 合并基础                             |
 | [button](src/components/button/)             | 按钮         | Button      | 🅢🅐   | shadcn Button + antd `loading` / `icon` / `shape` / `block` / `dashed` variant  |
 | [label](src/components/label/)               | 表单标签     | Label       | 🅢    | Radix Label,补 `required` / `disabled` 显式视觉(对齐 antd Form.Item label 部分) |
 | [badge](src/components/badge/)               | 徽标         | Badge       | 🅢🅐   | 四种形态:文本徽标 / 数字气泡 / 红点 / 状态点(对齐 antd Badge)                   |
@@ -82,7 +83,6 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). MCP reads
 | [avatar](src/components/avatar/)             | 头像         | Avatar      | 🅢🅐   | Radix Avatar + antd `size` / `shape` / `Avatar.Group`                           |
 | [progress](src/components/progress/)         | 进度条       | Progress    | 🅢🅐   | 线形 + 配套 `ProgressCircle` 环形(对齐 antd Progress)                           |
 | [spinner](src/components/spinner/)           | 加载指示器   | Spinner     | 🅢🅐   | shadcn 2025-10 新增;4 档尺寸 + 4 档语义色(对齐 antd Spin 无遮罩版)              |
-| [kbd](src/components/kbd/)                   | 键位         | Kbd         | 🅢    | shadcn 2025-10 新增;`Kbd` + `KbdGroup` 标注快捷键(antd 体系无)                  |
 | [aspect-ratio](src/components/aspect-ratio/) | 等比容器     | AspectRatio | 🅢    | Radix AspectRatio,无 layout shift(antd 体系无)                                  |
 | [image](src/components/image/)               | 图片         | Image       | 🅐    | 自动加载占位 + 失败占位 + 点击预览(对齐 antd Image)                             |
 | [tag](src/components/tag/)                   | 标签         | Tag         | 🅐    | 关键词标签 + `closable` + 6 种语义色 + `CheckableTag(Group)`(对齐 antd Tag v6)  |
@@ -118,26 +118,24 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). MCP reads
 | [input](src/components/input/)               | 输入框     | Input       | 🅢🅐   | + `clearable` / `showCount` / `size` / `error` 四档内建(复合形态已拆出独立 `InputGroup`,对齐 antd Input 集合) |
 | [textarea](src/components/textarea/)         | 多行文本框 | Textarea    | 🅢🅐   | + `autoSize` / `showCount`(对齐 antd Input.TextArea)                                                          |
 | [input-number](src/components/input-number/) | 数字输入框 | InputNumber | 🅐    | 步进 + min/max 夹紧 + precision + 千分位 + null 空状态(对齐 antd InputNumber)                                 |
-| [input-otp](src/components/input-otp/)       | 验证码输入 | InputOTP    | 🅢🅐   | input-otp 库封装,登录 / 二步验证 / PIN(对齐 antd Input.OTP v5.21+)                                            |
 | [mentions](src/components/mentions/)         | @ 提及输入 | Mentions    | 🅐    | Textarea + @ 触发候选下拉,异步 onSearch(对齐 antd Mentions)                                                   |
 
 #### 3.3 选择类(下拉 / 单选 / 多选)
 
-| id                                             | 中文名       | 英文         | 来源 | 关键能力 / antd 对应                                                    |
-| ---------------------------------------------- | ------------ | ------------ | ---- | ----------------------------------------------------------------------- |
-| [select](src/components/select/)               | 选择器       | Select       | 🅢🅐   | Radix Select(对齐 antd Select 单选)                                     |
-| [native-select](src/components/native-select/) | 原生选择器   | NativeSelect | 🅢    | shadcn 2025-10 新增;原生 `<select>`,移动端 / SSR 友好(antd 体系无)      |
-| [combobox](src/components/combobox/)           | 可搜索选择器 | Combobox     | 🅢    | Command + Popover,必选(value ∈ options)(对齐 antd Select showSearch)    |
-| [auto-complete](src/components/auto-complete/) | 自动完成     | AutoComplete | 🅐    | 自由输入 + 候选建议(value 可任意 string)(对齐 antd AutoComplete)        |
-| [cascader](src/components/cascader/)           | 级联选择     | Cascader     | 🅐    | 多级联动,叶子触发 / 中途可选(对齐 antd Cascader)                        |
-| [tree-select](src/components/tree-select/)     | 树形选择     | TreeSelect   | 🅐    | Tree 嵌入 Popover,单选 / 多选(对齐 antd TreeSelect)                     |
-| [checkbox](src/components/checkbox/)           | 多选框       | Checkbox     | 🅢🅐   | Radix 原生 indeterminate + Checkbox.Group(对齐 antd Checkbox)           |
-| [radio-group](src/components/radio-group/)     | 单选组       | RadioGroup   | 🅢🅐   | + `variant=button` 按钮组形态(对齐 antd Radio + Radio.Button)           |
-| [switch](src/components/switch/)               | 开关         | Switch       | 🅢🅐   | + `loading` / `checkedChildren` / `unCheckedChildren`(对齐 antd Switch) |
-| [slider](src/components/slider/)               | 滑动输入     | Slider       | 🅢🅐   | 原生支持双滑块 + antd marks 刻度(对齐 antd Slider)                      |
-| [toggle](src/components/toggle/)               | 切换按钮     | Toggle       | 🅢    | Radix Toggle,工具栏图标级开关(antd 体系无)                              |
-| [toggle-group](src/components/toggle-group/)   | 切换按钮组   | ToggleGroup  | 🅢    | type=single \| multiple,与 RadioButton 互补(antd 体系无)                |
-| [segmented](src/components/segmented/)         | 分段控制     | Segmented    | 🅐    | iOS / macOS 风格紧凑互斥单选(对齐 antd Segmented v5.0+)                 |
+| id                                             | 中文名     | 英文         | 来源 | 关键能力 / antd 对应                                                    |
+| ---------------------------------------------- | ---------- | ------------ | ---- | ----------------------------------------------------------------------- |
+| [select](src/components/select/)               | 选择器     | Select       | 🅢🅐   | Radix Select(对齐 antd Select 单选)                                     |
+| [native-select](src/components/native-select/) | 原生选择器 | NativeSelect | 🅢    | shadcn 2025-10 新增;原生 `<select>`,移动端 / SSR 友好(antd 体系无)      |
+| [auto-complete](src/components/auto-complete/) | 自动完成   | AutoComplete | 🅐    | 自由输入 + 候选建议(value 可任意 string)(对齐 antd AutoComplete)        |
+| [cascader](src/components/cascader/)           | 级联选择   | Cascader     | 🅐    | 多级联动,叶子触发 / 中途可选(对齐 antd Cascader)                        |
+| [tree-select](src/components/tree-select/)     | 树形选择   | TreeSelect   | 🅐    | Tree 嵌入 Popover,单选 / 多选(对齐 antd TreeSelect)                     |
+| [checkbox](src/components/checkbox/)           | 多选框     | Checkbox     | 🅢🅐   | Radix 原生 indeterminate + Checkbox.Group(对齐 antd Checkbox)           |
+| [radio-group](src/components/radio-group/)     | 单选组     | RadioGroup   | 🅢🅐   | + `variant=button` 按钮组形态(对齐 antd Radio + Radio.Button)           |
+| [switch](src/components/switch/)               | 开关       | Switch       | 🅢🅐   | + `loading` / `checkedChildren` / `unCheckedChildren`(对齐 antd Switch) |
+| [slider](src/components/slider/)               | 滑动输入   | Slider       | 🅢🅐   | 原生支持双滑块 + antd marks 刻度(对齐 antd Slider)                      |
+| [toggle](src/components/toggle/)               | 切换按钮   | Toggle       | 🅢    | Radix Toggle,工具栏图标级开关(antd 体系无)                              |
+| [toggle-group](src/components/toggle-group/)   | 切换按钮组 | ToggleGroup  | 🅢    | type=single \| multiple,与 RadioButton 互补(antd 体系无)                |
+| [segmented](src/components/segmented/)         | 分段控制   | Segmented    | 🅐    | iOS / macOS 风格紧凑互斥单选(对齐 antd Segmented v5.0+)                 |
 
 #### 3.4 日期 / 时间 / 颜色 / 评分 / 文件
 
@@ -165,24 +163,24 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). MCP reads
 
 ### 5. 反馈与浮层 / Feedback & Overlay(16 件)
 
-| id                                           | 中文名     | 英文            | 来源 | 关键能力 / antd 对应                                                                                               |
-| -------------------------------------------- | ---------- | --------------- | ---- | ------------------------------------------------------------------------------------------------------------------ |
-| [alert](src/components/alert/)               | 警示条     | Alert           | 🅢🅐   | + `type` / `showIcon` / `closable` / `banner`(对齐 antd Alert)                                                     |
-| [dialog](src/components/dialog/)             | 对话框     | Dialog          | 🅢🅐   | Radix Dialog;Header / Footer / Title / Description(对齐 antd Modal)                                                |
-| [alert-dialog](src/components/alert-dialog/) | 确认对话框 | AlertDialog     | 🅢🅐   | Radix AlertDialog;阻塞式 Action + Cancel(对齐 antd Modal.confirm)                                                  |
-| [popconfirm](src/components/popconfirm/)     | 气泡确认   | Popconfirm      | 🅐    | 轻量确认,onConfirm Promise 自动 loading(对齐 antd Popconfirm)                                                      |
-| [popover](src/components/popover/)           | 浮层       | Popover         | 🅢🅐   | + antd `arrow`(对齐 antd Popover)                                                                                  |
-| [command](src/components/command/)           | 命令面板   | Command         | 🅢    | cmdk(Linear / Raycast 风格)过滤 + 键盘导航 + a11y;同时作为 Combobox / Select / AutoComplete 同源下拉内核(ADR 0029) |
-| [tooltip](src/components/tooltip/)           | 文字提示   | Tooltip         | 🅢🅐   | + `arrow` / `placement(side)` + 一行 wrapper API(对齐 antd Tooltip)                                                |
-| [hover-card](src/components/hover-card/)     | 悬浮卡片   | HoverCard       | 🅢    | hover 触发的富内容卡(@user 卡片 / 链接预览)(antd 体系无)                                                           |
-| [sheet](src/components/sheet/)               | 侧边面板   | Sheet           | 🅢🅐   | Radix Dialog + side(对齐 antd Drawer top/right/left)                                                               |
-| [drawer](src/components/drawer/)             | 抽屉       | Drawer          | 🅢    | vaul,iOS 风格底部可拖拽(对齐 antd Drawer placement=bottom 但加拖拽)                                                |
-| [sonner](src/components/sonner/)             | 消息提示   | Toaster + toast | 🅢🅐   | sonner 包装;短文字 toast(对齐 antd message)                                                                        |
-| [notification](src/components/notification/) | 通知卡片   | notification    | 🅐    | sonner toast.custom 二次封装;title + description 卡片(对齐 antd Notification)                                      |
-| [result](src/components/result/)             | 结果页     | Result          | 🅐    | 整页级反馈(成功 / 失败 / 404 / 403 / 500)(对齐 antd Result)                                                        |
-| [empty](src/components/empty/)               | 空状态     | Empty           | 🅐    | 列表 / 表格 / 搜索为空时占位 + extra 行动按钮(对齐 antd Empty)                                                     |
-| [tour](src/components/tour/)                 | 漫游引导   | Tour            | 🅐    | 多步骤 spotlight + 卡片 + 步进(对齐 antd Tour v5.0+)                                                               |
-| [watermark](src/components/watermark/)       | 水印       | Watermark       | 🅐    | SVG 平铺水印(前端视觉,不作安全防护)(对齐 antd Watermark v5.1+)                                                     |
+| id                                           | 中文名     | 英文            | 来源 | 关键能力 / antd 对应                                                                                    |
+| -------------------------------------------- | ---------- | --------------- | ---- | ------------------------------------------------------------------------------------------------------- |
+| [alert](src/components/alert/)               | 警示条     | Alert           | 🅢🅐   | + `type` / `showIcon` / `closable` / `banner`(对齐 antd Alert)                                          |
+| [dialog](src/components/dialog/)             | 对话框     | Dialog          | 🅢🅐   | Radix Dialog;Header / Footer / Title / Description(对齐 antd Modal)                                     |
+| [alert-dialog](src/components/alert-dialog/) | 确认对话框 | AlertDialog     | 🅢🅐   | Radix AlertDialog;阻塞式 Action + Cancel(对齐 antd Modal.confirm)                                       |
+| [popconfirm](src/components/popconfirm/)     | 气泡确认   | Popconfirm      | 🅐    | 轻量确认,onConfirm Promise 自动 loading(对齐 antd Popconfirm)                                           |
+| [popover](src/components/popover/)           | 浮层       | Popover         | 🅢🅐   | + antd `arrow`(对齐 antd Popover)                                                                       |
+| [command](src/components/command/)           | 命令面板   | Command         | 🅢    | cmdk(Linear / Raycast 风格)过滤 + 键盘导航 + a11y;同时作为 Select / AutoComplete 同源下拉内核(ADR 0029) |
+| [tooltip](src/components/tooltip/)           | 文字提示   | Tooltip         | 🅢🅐   | + `arrow` / `placement(side)` + 一行 wrapper API(对齐 antd Tooltip)                                     |
+| [hover-card](src/components/hover-card/)     | 悬浮卡片   | HoverCard       | 🅢    | hover 触发的富内容卡(@user 卡片 / 链接预览)(antd 体系无)                                                |
+| [sheet](src/components/sheet/)               | 侧边面板   | Sheet           | 🅢🅐   | Radix Dialog + side(对齐 antd Drawer top/right/left)                                                    |
+| [drawer](src/components/drawer/)             | 抽屉       | Drawer          | 🅢    | vaul,iOS 风格底部可拖拽(对齐 antd Drawer placement=bottom 但加拖拽)                                     |
+| [sonner](src/components/sonner/)             | 消息提示   | Toaster + toast | 🅢🅐   | sonner 包装;短文字 toast(对齐 antd message)                                                             |
+| [notification](src/components/notification/) | 通知卡片   | notification    | 🅐    | sonner toast.custom 二次封装;title + description 卡片(对齐 antd Notification)                           |
+| [result](src/components/result/)             | 结果页     | Result          | 🅐    | 整页级反馈(成功 / 失败 / 404 / 403 / 500)(对齐 antd Result)                                             |
+| [empty](src/components/empty/)               | 空状态     | Empty           | 🅐    | 列表 / 表格 / 搜索为空时占位 + extra 行动按钮(对齐 antd Empty)                                          |
+| [tour](src/components/tour/)                 | 漫游引导   | Tour            | 🅐    | 多步骤 spotlight + 卡片 + 步进(对齐 antd Tour v5.0+)                                                    |
+| [watermark](src/components/watermark/)       | 水印       | Watermark       | 🅐    | SVG 平铺水印(前端视觉,不作安全防护)(对齐 antd Watermark v5.1+)                                          |
 
 ### 6. 导航 / Navigation(14 件)
 
@@ -208,7 +206,7 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). MCP reads
 | id                                 | 中文名   | 英文    | 来源 | 关键能力 / antd 对应                                                |
 | ---------------------------------- | -------- | ------- | ---- | ------------------------------------------------------------------- |
 | [app](src/components/app/)         | 应用容器 | App     | 🅐    | 根容器,挂全局 Toaster + dir / lang(不接管主题)(对齐 antd App v5.1+) |
-| [command](src/components/command/) | 命令面板 | Command | 🅢    | cmdk(Linear / Raycast 风格),Combobox 的底座(antd 体系无)            |
+| [command](src/components/command/) | 命令面板 | Command | 🅢    | cmdk(Linear / Raycast 风格),下拉同源内核(antd 体系无)               |
 
 ---
 
@@ -258,19 +256,18 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). MCP reads
 
 **不可合并**:触发方式 × 交互性 = 4 个象限,3 件覆盖 3 象限(剩 click + 纯文本 = AlertDialog)。
 
-### 5. 选择类下拉(7 件)— Select / NativeSelect / Combobox / AutoComplete / TreeSelect / Cascader / Segmented
+### 5. 选择类下拉(6 件)— Select / NativeSelect / AutoComplete / TreeSelect / Cascader / Segmented
 
 | 组件         | value 域               | 候选呈现          | 互斥点                    |
 | ------------ | ---------------------- | ----------------- | ------------------------- |
 | Select       | options 之一           | Radix popup       | **必选**,无搜索           |
 | NativeSelect | options 之一           | 原生 picker       | **0 JS**,SSR / 移动端友好 |
-| Combobox     | options 之一           | Command + Popover | **必选 + 搜索**           |
 | AutoComplete | **任意字符串**         | 自渲下拉          | **可自由输入**,候选是建议 |
 | TreeSelect   | options 之一(支持多选) | Tree 嵌入 Popover | **层级结构**              |
 | Cascader     | 路径数组               | 多列面板          | **级联,每层下钻**         |
 | Segmented    | options 之一           | inline 按钮组     | **2~5 档紧凑互斥**        |
 
-**不可合并**:value 形态 × 候选呈现 = 7 个独立场景。
+**不可合并**:value 形态 × 候选呈现 = 6 个独立场景。
 
 ### 6. 互斥单选可视化(4 件)— RadioGroup / Segmented / ToggleGroup(single)/ Tabs
 
@@ -312,7 +309,7 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). MCP reads
 | **Sheet ↔ Drawer**                              | ❌ **保持分离**       | Sheet 走 Radix Dialog(轻、4 方向、桌面端);Drawer 走 vaul(重、仅底部、可拖拽手势、iOS 风格)。**两种不同的库 + 不同的 UX 范式**,业务侧按场景选 |
 | **Spinner ↔ Skeleton ↔ Progress**               | ❌ **保持分离**       | 三种 affordance 互斥(见 §1)                                                                                                                  |
 | **Tooltip ↔ Popover ↔ HoverCard**               | ❌ **保持分离**       | 触发 × 交互性 4 象限(见 §4)                                                                                                                  |
-| **Select ↔ Combobox ↔ AutoComplete**            | ❌ **保持分离**       | value 域(必选 / 自由) × 是否搜索 = 4 类(见 §5)                                                                                               |
+| **Select ↔ AutoComplete**                       | ❌ **保持分离**       | value 域(必选 / 自由) × 是否搜索 = 4 类(见 §5)                                                                                               |
 | **RadioGroup ↔ Segmented ↔ ToggleGroup ↔ Tabs** | ❌ **保持分离**       | 视觉语义不同(表单 / 视图切换 / 工具栏 / 页面切换)                                                                                            |
 | **Form ↔ Field**                                | ❌ **保持分离**       | 状态管理绑定差异(见 §8)                                                                                                                      |
 | **toast() ↔ notification**                      | ✅ **已合并 runtime** | 都基于 sonner;notification 是 sonner.toast.custom 的二次封装,**已是同源不同表层**                                                            |
@@ -328,9 +325,8 @@ Each component should ship a `<id>.meta.md` (frontmatter + Markdown). MCP reads
 
 ### 暂不实现(待用户需求触发)
 
-| 组件               | 来源                                          | 暂缓理由                              |
-| ------------------ | --------------------------------------------- | ------------------------------------- |
-| Chart              | 🅢🅐(shadcn 2026-03 升 Recharts v3 / antd Plot) | 用户指示暂跳过                        |
-| QRCode             | 🅐(antd v5.1+)                                 | 需引入 `qrcode.react` 依赖,用户暂跳过 |
-| Direction Provider | 🅢(shadcn 2026-01 新)                          | RTL provider,无业务需求暂缓           |
-| BorderBeam         | 🅐(antd v6.4 装饰类)                           | 装饰组件,优先级低                     |
+| 组件               | 来源                 | 暂缓理由                              |
+| ------------------ | -------------------- | ------------------------------------- |
+| QRCode             | 🅐(antd v5.1+)        | 需引入 `qrcode.react` 依赖,用户暂跳过 |
+| Direction Provider | 🅢(shadcn 2026-01 新) | RTL provider,无业务需求暂缓           |
+| BorderBeam         | 🅐(antd v6.4 装饰类)  | 装饰组件,优先级低                     |