@teamix-evo/ui 0.2.0 → 0.4.0

package/src/components/tabs/tabs.tsx

@@ -6,95 +6,159 @@ import { cn } from '@/utils/cn';
 
 const Tabs = TabsPrimitive.Root;
 
-const tabsListVariants = cva('inline-flex items-center justify-center', {
+/**
+ * TabsList 的视觉风格 + 尺寸由 cva 表达；
+ * 同时通过 `TabsListContext` 把 variant / size 透传到 TabsTrigger,
+ * 使得消费者只需在 List 上声明一次。
+ */
+const tabsListVariants = cva('inline-flex items-center', {
   variants: {
-    type: {
-      line: 'border-b border-border w-full justify-start gap-4',
-      card: 'h-9 rounded-md bg-muted p-1 text-muted-foreground',
+    variant: {
+      // 下划线风格(antd 默认):整行 baseline border + 选中项底部 primary 高亮线
+      line: 'w-full justify-start gap-4 border-b border-border bg-transparent text-muted-foreground',
+      // 胶囊风格(吸收 Segmented):圆角容器 + muted 底色 + 选中项 background 白底 shadow
+      capsule:
+        'justify-center gap-1 rounded-lg bg-muted p-1 text-muted-foreground',
+    },
+    size: {
+      sm: '',
+      md: '',
+      lg: '',
     },
   },
-  defaultVariants: { type: 'card' },
+  compoundVariants: [
+    { variant: 'capsule', size: 'sm', class: 'h-8' },
+    { variant: 'capsule', size: 'md', class: 'h-9' },
+    { variant: 'capsule', size: 'lg', class: 'h-10' },
+  ],
+  defaultVariants: { variant: 'line', size: 'md' },
 });
 
 const tabsTriggerVariants = cva(
-  'inline-flex items-center justify-center whitespace-nowrap text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  'inline-flex cursor-pointer items-center justify-center gap-1.5 whitespace-nowrap font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
   {
     variants: {
-      type: {
-        line: 'relative px-1 py-2 -mb-px border-b-2 border-transparent text-muted-foreground hover:text-foreground data-[state=active]:border-primary data-[state=active]:text-foreground',
-        card: 'rounded-sm px-3 py-1 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm',
+      variant: {
+        line: 'relative -mb-px border-b-2 border-transparent text-muted-foreground hover:text-foreground data-[state=active]:border-primary data-[state=active]:text-foreground',
+        capsule:
+          'rounded-md text-muted-foreground hover:text-foreground data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm',
+      },
+      size: {
+        sm: 'text-xs',
+        md: 'text-xs',
+        lg: 'text-sm',
       },
     },
-    defaultVariants: { type: 'card' },
+    compoundVariants: [
+      { variant: 'line', size: 'sm', class: 'px-1 py-1.5' },
+      { variant: 'line', size: 'md', class: 'px-1 py-2' },
+      { variant: 'line', size: 'lg', class: 'px-1 py-2.5' },
+      { variant: 'capsule', size: 'sm', class: 'px-2.5 py-1' },
+      { variant: 'capsule', size: 'md', class: 'px-3 py-1' },
+      { variant: 'capsule', size: 'lg', class: 'px-4 py-1.5' },
+    ],
+    defaultVariants: { variant: 'line', size: 'md' },
   },
 );
 
+type TabsVariant = NonNullable<
+  VariantProps<typeof tabsListVariants>['variant']
+>;
+type TabsSize = NonNullable<VariantProps<typeof tabsListVariants>['size']>;
+
+const TabsListContext = React.createContext<{
+  variant: TabsVariant;
+  size: TabsSize;
+}>({ variant: 'line', size: 'md' });
+
 export interface TabsListProps
   extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.List>,
     VariantProps<typeof tabsListVariants> {
   /**
-   * 视觉风格(antd `type` 并集)。`card` 是 shadcn 默认胶囊;`line` 是 antd 默认下划线。
-   * @default "card"
+   * 视觉风格(shadcn ∪ antd 并集 + 吸收 Segmented)。
+   * - `line`:下划线风格(antd 默认),适合页面级主导航 / 大区块切换。
+   * - `capsule`:胶囊风格(取代旧 `card`,吸收 Segmented),muted 底色 + 选中项白底 shadow,适合紧凑互斥单选(视图切换、时间区间)。
+   * @default "line"
    */
-  type?: 'line' | 'card';
+  variant?: TabsVariant;
   /**
-   * 右侧附加内容(antd `tabBarExtraContent` 并集);仅 `type="line"` 显式支持(布局灵活)。
+   * 尺寸(antd `size` 并集)。三档统一驱动 trigger 的字号与 padding。
+   * @default "md"
+   */
+  size?: TabsSize;
+  /**
+   * 右侧附加内容(antd `tabBarExtraContent` 并集);仅 `variant="line"` 显式支持(布局灵活)。
    * 用法:把节点放进来即可,组件用 `flex justify-between` 自动撑开。
    */
   extra?: React.ReactNode;
 }
 
-const TabsListContext = React.createContext<{ type: 'line' | 'card' }>({
-  type: 'card',
-});
-
 const TabsList = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.List>,
   TabsListProps
->(({ className, type = 'card', extra, children, ...props }, ref) => {
-  const list = (
-    <TabsPrimitive.List
-      ref={ref}
-      className={cn(tabsListVariants({ type }), className)}
-      {...props}
-    >
-      <TabsListContext.Provider value={{ type }}>
-        {children}
-      </TabsListContext.Provider>
-    </TabsPrimitive.List>
-  );
-  if (extra) {
-    return (
-      <div
-        className={cn(
-          'flex items-center justify-between',
-          type === 'line' && 'border-b border-border',
-        )}
+>(
+  (
+    { className, variant = 'line', size = 'md', extra, children, ...props },
+    ref,
+  ) => {
+    const list = (
+      <TabsPrimitive.List
+        ref={ref}
+        className={cn(tabsListVariants({ variant, size }), className)}
+        {...props}
       >
-        {React.cloneElement(list, {
-          className: cn(
-            tabsListVariants({ type }),
-            type === 'line' && 'border-b-0',
-            className,
-          ),
-        })}
-        <div className="shrink-0">{extra}</div>
-      </div>
+        <TabsListContext.Provider value={{ variant, size }}>
+          {children}
+        </TabsListContext.Provider>
+      </TabsPrimitive.List>
     );
-  }
-  return list;
-});
+    if (extra) {
+      return (
+        <div
+          className={cn(
+            'flex items-center justify-between',
+            variant === 'line' && 'border-b border-border',
+          )}
+        >
+          {React.cloneElement(list, {
+            className: cn(
+              tabsListVariants({ variant, size }),
+              variant === 'line' && 'border-b-0',
+              className,
+            ),
+          })}
+          <div className="shrink-0">{extra}</div>
+        </div>
+      );
+    }
+    return list;
+  },
+);
 TabsList.displayName = TabsPrimitive.List.displayName;
 
+/**
+ * `TabsTrigger` 也接受 `variant` / `size`,但仅用于显式覆盖来自 `TabsList`
+ * 的上下文(罕用)—— 通常在 `TabsList` 上声明一次即可。
+ * 类型用 inline 形式避免 gen:meta 候选优先匹配。
+ */
 const TabsTrigger = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.Trigger>,
-  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>
->(({ className, ...props }, ref) => {
-  const { type } = React.useContext(TabsListContext);
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger> & {
+    variant?: TabsVariant;
+    size?: TabsSize;
+  }
+>(({ className, variant, size, ...props }, ref) => {
+  const ctx = React.useContext(TabsListContext);
   return (
     <TabsPrimitive.Trigger
       ref={ref}
-      className={cn(tabsTriggerVariants({ type }), className)}
+      className={cn(
+        tabsTriggerVariants({
+          variant: variant ?? ctx.variant,
+          size: size ?? ctx.size,
+        }),
+        className,
+      )}
       {...props}
     />
   );
@@ -116,4 +180,11 @@ const TabsContent = React.forwardRef<
 ));
 TabsContent.displayName = TabsPrimitive.Content.displayName;
 
-export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants };
+export {
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+  tabsListVariants,
+  tabsTriggerVariants,
+};

package/src/components/tag/tag.meta.md

@@ -3,70 +3,52 @@ id: tag
 name: Tag
 displayName: 标签
 type: component
-category: foundation
+category: data-display
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
 
 # Tag 标签
 
-标签 — antd 独有补足。**与 Badge 区别**:Tag 偏向**用户可关闭的关键词标签**(分类 / 标签 / 筛选条件),支持 `closable` + 6 种语义色;Badge 偏向**状态徽标**(数字 / 红点 / 状态条)。
+标签 — antd 独有补足 + cloud-design 多彩并集。**与 Badge 区别**:Tag 偏向**用户可关闭的关键词标签**(分类 / 筛选条件 / 多彩分类),支持 `variant`(形态轴)× `color`(语义色轴,对齐 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md))× `palette`(装饰色轴,9 预设 + 任意 CSS 值)的三轴正交组合,以及 `icon` / `size` / `closable`;Badge 偏向**状态徽标**(数字 / 红点 / 状态条)。
 
 ## When to use
 
-- 关键词 / 标签 / 分类(博客标签、用户兴趣)
-- 当前筛选条件展示(可关闭以移除条件)
-- 列表项的次级标签(优先级 / 类型)
+- 关键词 / 标签 / 分类(博客标签、用户兴趣) — 多彩分类用 `palette`
+- 当前筛选条件展示(可关闭以移除条件) — 配 `closable + onClose`
+- 列表项的次级标签(优先级 / 类型) — 状态语义用 `color`
+- 单选 / 多选筛选 chip — 用 `CheckableTag` / `CheckableTagGroup`
 
 ## When NOT to use
 
-- 状态指示 → `Badge`
+- 状态指示(运行中 / 已停止 + 数字) → `Badge`
 - 切换按钮 → `Toggle` / `ToggleGroup`
 - 选择类输入 → `Combobox` / `Select`
 
 ## Props
 
 <!-- auto:props:begin -->
-
-#### Tag
-
-| 名称       | 类型                                                                    | 默认值      | 必填 | 说明                                                                                                         |
-| ---------- | ----------------------------------------------------------------------- | ----------- | ---- | ------------------------------------------------------------------------------------------------------------ |
-| `color`    | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `"default"` | –    | 语义颜色(antd `color` 并集) — 与 Badge 不同,Tag 偏向**用户可关闭的标签**(关键词 / 分类),Badge 偏向状态徽标。 |
-| `closable` | `boolean`                                                               | `false`     | –    | 显示关闭按钮(antd `closable` 并集)。                                                                         |
-| `onClose`  | `() => void`                                                            | –           | –    | 关闭回调。                                                                                                   |
-
-#### CheckableTag
-
-| 名称       | 类型                      | 默认值 | 必填 | 说明             |
-| ---------- | ------------------------- | ------ | ---- | ---------------- |
-| `checked`  | `boolean`                 | –      | ✓    | 是否选中(受控)。 |
-| `onChange` | `(next: boolean) => void` | –      | –    | 选中态变化回调。 |
-| `disabled` | `boolean`                 | –      | –    | 禁用。           |
-
-#### CheckableTagGroup
-
-| 名称           | 类型                        | 默认值 | 必填 | 说明                  |
-| -------------- | --------------------------- | ------ | ---- | --------------------- |
-| `options`      | `CheckableTagGroupOption[]` | –      | ✓    | 候选项数组。          |
-| `value`        | `string[]`                  | –      | –    | 受控选中 value 集合。 |
-| `defaultValue` | `string[]`                  | –      | –    | 非受控初值。          |
-| `onChange`     | `(next: string[]) => void`  | –      | –    | 选中变化回调。        |
-| `disabled`     | `boolean`                   | –      | –    | 整组禁用。            |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `'solid' \| 'outline' \| 'ghost'` | `"solid"` | – | 形态轴(对齐 [ADR 0021](../../../../docs/adr/0021-semantic-color-api-unification.md)): `solid` 实色背景 / `outline` 仅描边 / `ghost` 仅文字。 |
+| `color` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'destructive'` | `"default"` | – | 语义色 — 与组件状态绑定的调色板,5 档(填充背景类省略 `muted`,信息色用 `primary`, 不收 `info` — 见 ADR 0021)。装饰性类别区分请用 `palette`。 |
+| `size` | `'sm' \| 'md'` | `"md"` | – | 尺寸:`sm` 高 20px(更紧凑) / `md` 高 24px(默认)。 |
+| `palette` | `TagPalettePreset \| (string & {})` | – | – | **分类色 / 装饰色** — 与 `color`(语义色) 正交,用于纯装饰的类别区分(博客标签 / 项目分类 / ...)。 接受 9 种预设色 `'blue' \| 'cyan' \| 'green' \| 'orange' \| 'purple' \| 'red' \| 'magenta' \| 'lime' \| 'gold'` 或任意 CSS 颜色值(如 `'#FF5733'` / `'hsl(280 80% 60%)'` / `'var(--brand)'`)。 `palette` 存在时会**覆盖** `color` 的语义配色(派生 bg / border / text 三档), 但仍受 `variant` 控制形态:`solid` 12% bg + 35% border、`outline` 仅 solid 描边、`ghost` 仅文字。 装饰类别走 `palette`;状态语义走 `color`。两者同传时 `palette` 优先(因为它是显式装饰意图)。 |
+| `icon` | `React.ReactNode` | – | – | 标签文字左侧图标插槽(antd `icon` 并集)。推荐传 `lucide-react` icon。 与 `closable` 的关闭按钮不冲突 — icon 在左,X 在右。 |
+| `closable` | `boolean` | `false` | – | 显示关闭按钮(antd `closable` 并集)。 |
+| `onClose` | `() => void` | – | – | 关闭回调 — `closable` 触发时调用。建议父组件维护数组并在此回调中移除当前项。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add tag` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -75,49 +57,103 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add class-variance-authority@^0.7.0 lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
 
-- **`color` 反映语义**:不要随便选 — `error` 仅用于真错误,`success` 仅用于已通过
-- **`closable` 必配 `onClose`**:让父组件知道哪个 tag 被移除,业务侧维护数组
-- **文字 ≤ 4 个汉字 / 8 字符**:过长的标签视觉破碎
-- **不要嵌套交互**:Tag 内不要放 Button / Link
-- **筛选条件场景**:配 `closable` 让用户一键移除条件
+- **`color`(语义) vs `palette`(装饰) 选轴明确**:状态/反馈/校验类信号 → `color`;纯类别区分(标签云 / 分类) → `palette`。**不要混用**两轴去拼颜色
+- **`variant` 是形态不是颜色**(ADR 0021):`solid` / `outline` / `ghost`,**禁止**回写 `variant="primary"` 等旧风格
+- **`color` 不收 `info` / `error` / `danger`**:对齐 ADR 0021;信息色用 `color="primary"`,失败用 `destructive`
+- **`palette` 优先级高于 `color`**:同时传时 palette 覆盖配色(实现:inline style > utility class)
+- **palette 自定义值要可访问**:任意 CSS 颜色字符串都可传,但要保证 12% 透明度背景下对比度可读;**对纯白 / 极浅色慎用 solid 形态**(转为 `outline` 或 `ghost`)
+- **`closable` 必配 `onClose`**:父组件维护数组并在回调中移除
+- **icon 来源固定** `lucide-react`(ESLint `icon-from-lucide` 阻塞)。**不要**内联 SVG 或引入其它 icon 库
+- **文字 ≤ 4 个汉字 / 8 字符**:过长视觉破碎,考虑改用 Description / Field
+- **不要嵌套交互**:Tag 内不要放 Button / Link;`closable` X 已是组件唯一交互
+- **圆角走 token**:`--radius-tag`(4px) 由组件内 inline style 注入,**不要**覆盖为其他档位
+- **不要把语义色硬塞进 palette**:`palette="red"` 不等于 `color="destructive"` — 前者是装饰红,后者是危险信号语义
 
 ## Examples
 
 ```tsx
-import { Tag } from '@/components/ui/tag';
+import { Tag, CheckableTagGroup } from '@/components/ui/tag';
+import { Hash, Star } from 'lucide-react';
 import * as React from 'react';
 
-// 基础
-<Tag>React</Tag>
-<Tag color="primary">Vue</Tag>
-<Tag color="success">已通过</Tag>
-<Tag color="warning">待审核</Tag>
-<Tag color="error">失败</Tag>
-
-// 可关闭
-const [tags, setTags] = React.useState(['React', 'Vue', 'Angular']);
-<div className="flex gap-2">
-  {tags.map((t) => (
-    <Tag
-      key={t}
-      color="primary"
-      closable
-      onClose={() => setTags(tags.filter((x) => x !== t))}
-    >
-      {t}
-    </Tag>
-  ))}
+// 1. 形态 × 语义色(三种 variant × 五档 color)
+<div className="flex flex-wrap gap-2">
+  <Tag>Default</Tag>
+  <Tag variant="outline" color="primary">Primary outline</Tag>
+  <Tag variant="ghost" color="success">Ghost success</Tag>
+  <Tag color="warning">Warning</Tag>
+  <Tag color="destructive">Destructive</Tag>
 </div>
 
-// 筛选条件
+// 2. 多彩分类(9 预设 + 任意 CSS 值)
 <div className="flex flex-wrap gap-2">
-  <Tag closable>状态: 运行中</Tag>
-  <Tag closable>类型: 服务</Tag>
-  <Tag closable>地区: 杭州</Tag>
+  <Tag palette="blue">React</Tag>
+  <Tag palette="green">Vue</Tag>
+  <Tag palette="orange">Svelte</Tag>
+  <Tag palette="purple">Solid</Tag>
+  <Tag palette="#ff66cc">Custom Pink</Tag>
 </div>
+
+// 3. icon + closable + size
+<div className="flex flex-wrap items-center gap-2">
+  <Tag size="sm" icon={<Hash />}>small + icon</Tag>
+  <Tag icon={<Star />} closable onClose={() => alert('closed')}>
+    favorite
+  </Tag>
+</div>
+
+// 4. CheckableTagGroup(单/多选 chip)
+const [picked, setPicked] = React.useState<string[]>(['react']);
+<CheckableTagGroup
+  value={picked}
+  onChange={setPicked}
+  options={[
+    { label: 'React', value: 'react' },
+    { label: 'Vue', value: 'vue' },
+    { label: 'Angular', value: 'angular' },
+  ]}
+/>
 ```
+
+## Tag 形态 — 旧库 API → 新映射
+
+> 本节对齐 cloud-design (Teamix 1.0 hybridcloud) Tag / Tag.Closeable / Tag.Selectable / Tag.Group → 新库 Tag + CheckableTag + CheckableTagGroup 的迁移路径。
+
+### 组件拆合
+
+| 旧库             | 新库                                   | 说明                             |
+| ---------------- | -------------------------------------- | -------------------------------- |
+| `Tag`            | `Tag`                                  | 基础标签，直接对应               |
+| `Tag.Closeable`  | `Tag closable onClose={fn}`            | 合并为 `closable` prop           |
+| `Tag.Selectable` | `CheckableTag`                         | 重命名                           |
+| `Tag.Group`      | `div className="flex flex-wrap gap-2"` | 无需专用容器，flex gap 替代      |
+| —                | `CheckableTagGroup`                    | 新库独有，data-driven 多选标签组 |
+
+### Props / 值映射
+
+| 旧库                            | 新库                              | 备注                          |
+| ------------------------------- | --------------------------------- | ----------------------------- |
+| `type="normal"`                 | `variant="solid" color="default"` | 默认形态                      |
+| `type="primary"`                | `variant="solid" color="primary"` | 主色填充                      |
+| `color="blue"` (预设色)         | `palette="blue"`                  | 装饰色走 palette 轴           |
+| `color="red"` (预设色)          | `palette="red"`                   | 同上                          |
+| `size="small"`                  | `size="sm"`                       | 高 20px                       |
+| `size="medium"`                 | `size="md"`                       | 高 24px（默认）               |
+| `closable` (Tag.Closeable 专属) | `closable` (Tag prop)             | 统一到 Tag                    |
+| `onClose` 返回 false 阻止       | 外部受控(不渲染)                  | 父组件 state 管理             |
+| `closeArea="tag"`               | —                                 | 不迁移，固定 X 按钮区域       |
+| `animation` / `afterAppear`     | —                                 | 不迁移(CSS transition 已内置) |
+
+### 不迁移清单（保留新库优势）
+
+| 旧库能力                      | 理由                                  |
+| ----------------------------- | ------------------------------------- |
+| `closeArea="tag"` 整体可关闭  | 新库固定 X 按钮交互，语义更清晰       |
+| `onClose` 返回 false 阻止关闭 | 新库用外部受控模式替代                |
+| `animation` / `afterAppear`   | 过渡已由 CSS `transition-colors` 覆盖 |
+| `Tag.Group` 容器组件          | flex gap 布局更灵活，无需专用容器     |
+| `hoverUnchangable`            | 由 `variant` 形态决定 hover 行为      |