@teamix-evo/ui 0.2.0 → 0.3.0

package/src/components/tag/tag.stories.tsx

@@ -1,27 +1,68 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
-import { Tag } from './tag';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Hash, Star, Tag as TagIcon, Sparkles } from 'lucide-react';
+import { CheckableTagGroup, Tag } from './tag';
 
 const meta: Meta<typeof Tag> = {
-  title: '基础原语 · Foundation/Tag',
+  title: '数据展示 · Data Display/Tag',
   component: Tag,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '标签 — 用户可关闭的关键词 / 分类标签（分类、筛选条件、博客标签）。6 种语义色 + closable + onClose。等价 antd Tag（与 Badge 互补，Badge 偏状态徽标）。',
+          '标签 —— 用户可关闭的关键词标签 / 多彩分类 chip(博客标签、筛选条件、项目分类、单选/多选 chip)。基于原生 `<span>` + cva 形态轴,合并 antd Tag(`closable` / `icon` / `CheckableTag.Group`)与 cloud-design WindColorfulTag(`palette` 多彩分类) 的并集能力:形态 `variant`(`solid`/`outline`/`ghost`) × 语义 `color`(对齐 ADR 0021,5 档不收 `info`/`error`) × 装饰 `palette`(9 预设 + 任意 CSS 值) × `size`(`sm`/`md`) × `icon` × `closable`。视觉走 OpenTrek semantic tokens,圆角走 `--radius-tag`,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
   argTypes: {
+    variant: {
+      control: 'inline-radio',
+      options: ['solid', 'outline', 'ghost'],
+    },
     color: {
       control: 'select',
-      options: ['default', 'primary', 'success', 'warning', 'error', 'info'],
+      options: ['default', 'primary', 'success', 'warning', 'destructive'],
+    },
+    size: {
+      control: 'inline-radio',
+      options: ['sm', 'md'],
+    },
+    palette: {
+      control: 'select',
+      options: [
+        undefined,
+        'blue',
+        'cyan',
+        'green',
+        'orange',
+        'purple',
+        'red',
+        'magenta',
+        'lime',
+        'gold',
+      ],
+    },
+    icon: {
+      control: 'select',
+      options: ['none', 'hash', 'star', 'tag', 'sparkles'],
+      mapping: {
+        none: undefined,
+        hash: <Hash />,
+        star: <Star />,
+        tag: <TagIcon />,
+        sparkles: <Sparkles />,
+      },
     },
     closable: { control: 'boolean' },
   },
-  args: { color: 'default', children: '标签', closable: false },
+  args: {
+    variant: 'solid',
+    color: 'default',
+    size: 'md',
+    closable: false,
+    children: '标签',
+  },
 };
 
 export default meta;
@@ -29,21 +70,121 @@ type Story = StoryObj<typeof Tag>;
 
 export const Playground: Story = {};
 
-export const Colors: Story = {
+export const SemanticColors: Story = {
+  name: '语义色 (color × variant)',
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="flex flex-wrap gap-2">
-      <Tag>Default</Tag>
-      <Tag color="primary">Primary</Tag>
-      <Tag color="success">Success</Tag>
-      <Tag color="warning">Warning</Tag>
-      <Tag color="error">Error</Tag>
-      <Tag color="info">Info</Tag>
+    <div className="flex flex-col gap-3">
+      {(['solid', 'outline', 'ghost'] as const).map((v) => (
+        <div key={v} className="flex flex-wrap items-center gap-2">
+          <span className="w-16 text-xs text-muted-foreground">{v}</span>
+          <Tag variant={v}>Default</Tag>
+          <Tag variant={v} color="primary">
+            Primary
+          </Tag>
+          <Tag variant={v} color="success">
+            Success
+          </Tag>
+          <Tag variant={v} color="warning">
+            Warning
+          </Tag>
+          <Tag variant={v} color="destructive">
+            Destructive
+          </Tag>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const Palette: Story = {
+  name: '多彩分类 (palette × variant)',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const presets = [
+      'blue',
+      'cyan',
+      'green',
+      'lime',
+      'gold',
+      'orange',
+      'red',
+      'magenta',
+      'purple',
+    ] as const;
+    return (
+      <div className="flex flex-col gap-3">
+        {(['solid', 'outline', 'ghost'] as const).map((v) => (
+          <div key={v} className="flex flex-wrap items-center gap-2">
+            <span className="w-16 text-xs text-muted-foreground">{v}</span>
+            {presets.map((p) => (
+              <Tag key={p} variant={v} palette={p}>
+                {p}
+              </Tag>
+            ))}
+          </div>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const PaletteCustom: Story = {
+  name: '多彩分类 · 自定义 CSS 颜色',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      {/* eslint-disable teamix-evo/no-color-literal -- demo of custom palette accepting any CSS color string (hex / hsl / named); these are literals **as user input**, not styling decisions. */}
+      <Tag palette="#ff66cc">#ff66cc</Tag>
+      <Tag palette="hsl(280 80% 60%)">hsl(280 80% 60%)</Tag>
+      <Tag palette="teal">teal</Tag>
+      <Tag palette="var(--color-primary)">var(--color-primary)</Tag>
+      <Tag variant="outline" palette="rebeccapurple">
+        rebeccapurple
+      </Tag>
+      {/* eslint-enable teamix-evo/no-color-literal */}
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  name: '尺寸',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Tag size="sm">Small</Tag>
+      <Tag size="md">Medium</Tag>
+      <Tag size="sm" color="primary">
+        sm primary
+      </Tag>
+      <Tag size="md" color="success">
+        md success
+      </Tag>
+    </div>
+  ),
+};
+
+export const WithIcon: Story = {
+  name: 'icon 插槽',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <Tag icon={<Hash />}>topic</Tag>
+      <Tag icon={<Star />} color="warning">
+        featured
+      </Tag>
+      <Tag variant="outline" icon={<Sparkles />} palette="purple">
+        new
+      </Tag>
+      <Tag icon={<TagIcon />} closable onClose={() => undefined}>
+        with icon + closable
+      </Tag>
     </div>
   ),
 };
 
 export const Closable: Story = {
+  name: 'closable + 受控移除',
   parameters: { controls: { disable: true } },
   render: () => {
     const [tags, setTags] = React.useState([
@@ -70,9 +211,10 @@ export const Closable: Story = {
 };
 
 export const Filters: Story = {
+  name: '场景:筛选条件',
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="flex flex-wrap gap-2">
+    <div className="flex flex-wrap items-center gap-2">
       <span className="text-sm text-muted-foreground">已选筛选:</span>
       <Tag closable>状态: 运行中</Tag>
       <Tag closable>类型: 服务</Tag>
@@ -80,3 +222,29 @@ export const Filters: Story = {
     </div>
   ),
 };
+
+export const Checkable: Story = {
+  name: 'CheckableTagGroup',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [picked, setPicked] = React.useState<string[]>(['react']);
+    return (
+      <div className="flex flex-col gap-2">
+        <CheckableTagGroup
+          value={picked}
+          onChange={setPicked}
+          options={[
+            { label: 'React', value: 'react' },
+            { label: 'Vue', value: 'vue' },
+            { label: 'Angular', value: 'angular' },
+            { label: 'Svelte', value: 'svelte' },
+            { label: 'Solid', value: 'solid', disabled: true },
+          ]}
+        />
+        <span className="text-xs text-muted-foreground">
+          已选: {picked.join(', ') || '(空)'}
+        </span>
+      </div>
+    );
+  },
+};

package/src/components/tag/tag.tsx

@@ -4,20 +4,136 @@ import { X } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
 
+// ─── Preset palette (categorical / decorative) ─────────────────────────────
+//
+// 与 ADR 0021 的 semantic `color` 正交：palette 是**装饰色**，用于纯类别区分
+// （博客标签 / 项目分类等），不承载状态语义。取色对齐 OpenTrek 视觉调性，
+// 以 HSL 形式声明便于派生 bg / border / text 三档（实色 + 透明度）。
+//
+// OpenTrek tokens 尚未提供多彩调色板（v0.6 前的已知缺口，见 packages/ui/AGENTS.md §B）；
+// palette 通过 inline style 注入而非 className，custom 任意 CSS 值同路径。
+// 待 tokens 包补 `--palette-blue` 等令牌后，本块替换为 `var(--palette-X)` 即可。
+/* eslint-disable teamix-evo/no-color-literal -- multi-color palette is the v0.6 token gap; constants here are the bridge until OpenTrek ships --palette-* tokens. Same precedent as color-picker default / watermark canvas fallback. */
+const TAG_PALETTE_PRESETS = {
+  blue: 'hsl(217 91% 60%)',
+  cyan: 'hsl(187 85% 43%)',
+  green: 'hsl(142 71% 45%)',
+  orange: 'hsl(25 95% 53%)',
+  purple: 'hsl(271 76% 53%)',
+  red: 'hsl(0 84% 60%)',
+  magenta: 'hsl(322 81% 53%)',
+  lime: 'hsl(78 76% 38%)',
+  gold: 'hsl(45 93% 47%)',
+} as const;
+/* eslint-enable teamix-evo/no-color-literal */
+
+export type TagPalettePreset = keyof typeof TAG_PALETTE_PRESETS;
+
+interface PaletteStyle {
+  backgroundColor: string;
+  borderColor: string;
+  color: string;
+}
+
+function resolvePaletteStyle(palette: string): PaletteStyle {
+  const base =
+    (TAG_PALETTE_PRESETS as Record<string, string>)[palette] ?? palette;
+  return {
+    backgroundColor: `color-mix(in srgb, ${base} 12%, transparent)`,
+    borderColor: `color-mix(in srgb, ${base} 35%, transparent)`,
+    color: base,
+  };
+}
+
 const tagVariants = cva(
-  'inline-flex items-center gap-1 rounded-md border px-2 py-0.5 text-xs font-medium transition-colors',
+  'inline-flex items-center gap-1 border border-border font-medium transition-colors',
   {
     variants: {
+      variant: {
+        solid: '',
+        outline: 'bg-transparent',
+        ghost: 'border-transparent bg-transparent',
+      },
       color: {
-        default: 'border-border bg-muted text-foreground',
-        primary: 'border-primary/30 bg-primary/10 text-primary',
-        success: 'border-success-border/30 bg-success-subtle text-success',
-        warning: 'border-warning-border/30 bg-warning-subtle text-warning',
-        error: 'border-destructive/30 bg-destructive/10 text-destructive',
-        info: 'border-info-border/30 bg-info-subtle text-info',
+        default: '',
+        primary: '',
+        success: '',
+        warning: '',
+        destructive: '',
+      },
+      size: {
+        sm: 'h-5 px-1.5 text-xs',
+        md: 'h-6 px-2 text-xs',
       },
     },
-    defaultVariants: { color: 'default' },
+    compoundVariants: [
+      // ── solid (filled background) ──
+      {
+        variant: 'solid',
+        color: 'default',
+        className: 'border-border bg-muted text-foreground',
+      },
+      {
+        variant: 'solid',
+        color: 'primary',
+        className: 'border-primary/30 bg-primary/10 text-primary',
+      },
+      {
+        variant: 'solid',
+        color: 'success',
+        className:
+          'border-success-border/30 bg-success-subtle text-success',
+      },
+      {
+        variant: 'solid',
+        color: 'warning',
+        className:
+          'border-warning-border/30 bg-warning-subtle text-warning',
+      },
+      {
+        variant: 'solid',
+        color: 'destructive',
+        className:
+          'border-destructive/30 bg-destructive/10 text-destructive',
+      },
+      // ── outline (border + text) ──
+      {
+        variant: 'outline',
+        color: 'default',
+        className: 'border-border text-foreground',
+      },
+      {
+        variant: 'outline',
+        color: 'primary',
+        className: 'border-primary text-primary',
+      },
+      {
+        variant: 'outline',
+        color: 'success',
+        className: 'border-success text-success',
+      },
+      {
+        variant: 'outline',
+        color: 'warning',
+        className: 'border-warning text-warning',
+      },
+      {
+        variant: 'outline',
+        color: 'destructive',
+        className: 'border-destructive text-destructive',
+      },
+      // ── ghost (text only) ──
+      { variant: 'ghost', color: 'default', className: 'text-foreground' },
+      { variant: 'ghost', color: 'primary', className: 'text-primary' },
+      { variant: 'ghost', color: 'success', className: 'text-success' },
+      { variant: 'ghost', color: 'warning', className: 'text-warning' },
+      {
+        variant: 'ghost',
+        color: 'destructive',
+        className: 'text-destructive',
+      },
+    ],
+    defaultVariants: { variant: 'solid', color: 'default', size: 'md' },
   },
 );
 
@@ -25,34 +141,104 @@ export interface TagProps
   extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'color'>,
     VariantProps<typeof tagVariants> {
   /**
-   * 语义颜色(antd `color` 并集) — 与 Badge 不同,Tag 偏向**用户可关闭的标签**(关键词 / 分类),Badge 偏向状态徽标。
+   * 形态轴(对齐 [ADR 0021](../../../../docs/adr/0021-semantic-color-api-unification.md)):
+   * `solid` 实色背景 / `outline` 仅描边 / `ghost` 仅文字。
+   * @default "solid"
+   */
+  variant?: 'solid' | 'outline' | 'ghost';
+  /**
+   * 语义色 — 与组件状态绑定的调色板,5 档(填充背景类省略 `muted`,信息色用 `primary`,
+   * 不收 `info` — 见 ADR 0021)。装饰性类别区分请用 `palette`。
    * @default "default"
    */
-  color?: 'default' | 'primary' | 'success' | 'warning' | 'error' | 'info';
+  color?: 'default' | 'primary' | 'success' | 'warning' | 'destructive';
+  /**
+   * 尺寸:`sm` 高 20px(更紧凑) / `md` 高 24px(默认)。
+   * @default "md"
+   */
+  size?: 'sm' | 'md';
+  /**
+   * **分类色 / 装饰色** — 与 `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` 优先(因为它是显式装饰意图)。
+   */
+  palette?: TagPalettePreset | (string & {});
+  /**
+   * 标签文字左侧图标插槽(antd `icon` 并集)。推荐传 `lucide-react` icon。
+   * 与 `closable` 的关闭按钮不冲突 — icon 在左,X 在右。
+   */
+  icon?: React.ReactNode;
   /**
    * 显示关闭按钮(antd `closable` 并集)。
    * @default false
    */
   closable?: boolean;
   /**
-   * 关闭回调。
+   * 关闭回调 — `closable` 触发时调用。建议父组件维护数组并在此回调中移除当前项。
    */
   onClose?: () => void;
 }
 
 const Tag = React.forwardRef<HTMLSpanElement, TagProps>(
   (
-    { color, closable = false, onClose, className, children, ...props },
+    {
+      variant,
+      color,
+      size,
+      palette,
+      icon,
+      closable = false,
+      onClose,
+      className,
+      style,
+      children,
+      ...props
+    },
     ref,
   ) => {
     const [open, setOpen] = React.useState(true);
     if (!open) return null;
+
+    // 始终用 token --radius-tag 注入 borderRadius(OpenTrek 组件级圆角)
+    const composedStyle: React.CSSProperties = {
+      borderRadius: 'var(--radius-tag)',
+    };
+
+    // palette 路径:覆盖 cva 的颜色 className(inline style 优先级 > utility class)
+    if (palette) {
+      const ps = resolvePaletteStyle(palette);
+      composedStyle.color = ps.color;
+      if (variant === undefined || variant === 'solid') {
+        composedStyle.backgroundColor = ps.backgroundColor;
+        composedStyle.borderColor = ps.borderColor;
+      } else if (variant === 'outline') {
+        // outline 用实色描边,识别度更高(palette 装饰场景下更直观)
+        composedStyle.borderColor = ps.color;
+      }
+      // ghost: cva 已 transparent,只覆盖 text color
+    }
+
     return (
       <span
         ref={ref}
-        className={cn(tagVariants({ color }), className)}
+        className={cn(tagVariants({ variant, color, size }), className)}
+        style={{ ...composedStyle, ...style }}
         {...props}
       >
+        {icon ? (
+          <span
+            aria-hidden="true"
+            className="inline-flex shrink-0 items-center [&_svg]:size-3"
+          >
+            {icon}
+          </span>
+        ) : null}
         {children}
         {closable ? (
           <button
@@ -62,7 +248,7 @@ const Tag = React.forwardRef<HTMLSpanElement, TagProps>(
               setOpen(false);
               onClose?.();
             }}
-            className="rounded-sm opacity-60 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+            className="-mr-0.5 inline-flex shrink-0 cursor-pointer rounded-sm opacity-60 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
           >
             <X className="size-3" />
           </button>
@@ -86,7 +272,7 @@ export interface CheckableTagProps
 }
 
 const CheckableTag = React.forwardRef<HTMLSpanElement, CheckableTagProps>(
-  ({ checked, onChange, disabled, className, children, ...props }, ref) => (
+  ({ checked, onChange, disabled, className, style, children, ...props }, ref) => (
     <span
       ref={ref}
       role="checkbox"
@@ -102,12 +288,13 @@ const CheckableTag = React.forwardRef<HTMLSpanElement, CheckableTagProps>(
           onChange?.(!checked);
         }
       }}
+      style={{ borderRadius: 'var(--radius-tag)', ...style }}
       className={cn(
-        'inline-flex cursor-pointer items-center gap-1 rounded-md border px-2 py-0.5 text-xs font-medium transition-colors',
+        'inline-flex h-6 cursor-pointer items-center gap-1 border border-border px-2 text-xs font-medium transition-colors',
         'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
         checked
           ? 'border-primary bg-primary text-primary-foreground hover:bg-primary/90'
-          : 'border-border bg-muted text-foreground hover:bg-accent',
+          : 'bg-muted text-foreground hover:bg-accent',
         disabled && 'cursor-not-allowed opacity-50',
         className,
       )}
@@ -131,7 +318,10 @@ export interface CheckableTagGroupOption {
 }
 
 export interface CheckableTagGroupProps
-  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+  extends Omit<
+    React.HTMLAttributes<HTMLDivElement>,
+    'onChange' | 'defaultValue'
+  > {
   /** 候选项数组。 */
   options: CheckableTagGroupOption[];
   /** 受控选中 value 集合。 */
@@ -144,13 +334,18 @@ export interface CheckableTagGroupProps
   disabled?: boolean;
 }
 
-const CheckableTagGroup = React.forwardRef<HTMLDivElement, CheckableTagGroupProps>(
+const CheckableTagGroup = React.forwardRef<
+  HTMLDivElement,
+  CheckableTagGroupProps
+>(
   (
     { options, value, defaultValue, onChange, disabled, className, ...props },
     ref,
   ) => {
     const isControlled = value !== undefined;
-    const [internal, setInternal] = React.useState<string[]>(defaultValue ?? []);
+    const [internal, setInternal] = React.useState<string[]>(
+      defaultValue ?? [],
+    );
     const current = isControlled ? value! : internal;
 
     const toggle = (v: string, next: boolean) => {
@@ -182,4 +377,10 @@ const CheckableTagGroup = React.forwardRef<HTMLDivElement, CheckableTagGroupProp
 );
 CheckableTagGroup.displayName = 'CheckableTagGroup';
 
-export { Tag, CheckableTag, CheckableTagGroup, tagVariants };
+export {
+  Tag,
+  CheckableTag,
+  CheckableTagGroup,
+  tagVariants,
+  TAG_PALETTE_PRESETS,
+};