@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/tag/index.tsx

@@ -0,0 +1,774 @@
+/**
+ * 标签 Tag
+ *
+ * 用于分类标识、状态标记或可选择的筛选项。支持 4 种形态:
+ * 背景色块(`solid` / `outline` / `ghost`)与状态形态(`variant='status'`,
+ * 圆点默认、`showIcon` 切换为图标)。
+ *
+ * 关闭路径对齐 antd v6:`closable` 支持对象签名(自定义 closeIcon /
+ * closeArea / aria-label),`onClose(e)` 调用 `e.preventDefault()` 即可
+ * 阻止默认关闭;并提供 `visible` / `defaultVisible` 双形态可见性与
+ * `afterClose` 隐藏后回调。
+ *
+ * 组合结构:TagGroup > Tag * | CheckableTagGroup > CheckableTag *
+ *
+ * @when
+ * - 展示分类标签(项目类型、技术栈、博客标签)
+ * - 标记任务 / 资源状态(成功 / 运行中 / 失败 / 暂停 / 加载中 / 帮助 / 提示)
+ * - 可关闭的动态标签列表(支持外部受控可见性 / 阻止默认关闭)
+ * - 多选或单选筛选场景(CheckableTagGroup)
+ */
+import * as React from 'react';
+import { Slot } from 'radix-ui';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Loader2, X } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import {
+  DefaultFilledIcon,
+  ErrorFilledIcon,
+  HelpFilledIcon,
+  MentionFilledIcon,
+  PauseFilledIcon,
+  ProcessingFilledIcon,
+  SuccessFilledIcon,
+  WarningFilledIcon,
+} from '@/components/icon';
+
+// ─── Preset palette (categorical / decorative) ─────────────────────────────
+//
+// 与 ADR 0021 的 semantic `color` 正交:palette 是**装饰色**,用于纯类别区分
+// (博客标签 / 项目分类等),不承载状态语义。取色对齐 OpenTrek 视觉调性,
+// 以 HSL 形式声明便于派生 bg / border / text 三档(实色 + 透明度)。
+//
+// OpenTrek tokens 尚未提供多彩调色板;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. */
+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;
+  backgroundColorHover: string;
+  borderColor: string;
+  color: string;
+}
+
+function resolvePaletteStyle(palette: string): PaletteStyle {
+  const base =
+    (TAG_PALETTE_PRESETS as Record<string, string>)[palette] ?? palette;
+  return {
+    // solid 静态:base 12% 叠加;hover:同公式提到 20%("更浓")
+    backgroundColor: `color-mix(in srgb, ${base} 12%, transparent)`,
+    backgroundColorHover: `color-mix(in srgb, ${base} 20%, transparent)`,
+    borderColor: `color-mix(in srgb, ${base} 35%, transparent)`,
+    color: base,
+  };
+}
+
+// ─── Status 9 档(variant='status' 形态 + 非 status 变体自动派生色彩) ────
+//
+// 命名对齐 shadcn + 业界主流(antd v5 Badge status / 本仓历史):
+// success/processing/error/warning/pause/loading/help/mention;
+// 非 status 变体下传入 status 可自动派生色彩。
+export type TagStatus =
+  | 'default'
+  | 'success'
+  | 'processing'
+  | 'error'
+  | 'warning'
+  | 'pause'
+  | 'loading'
+  | 'help'
+  | 'mention';
+
+const STATUS_TOKEN_MAP: Record<TagStatus, string> = {
+  default: 'var(--color-muted-foreground)',
+  success: 'var(--color-success)',
+  processing: 'var(--color-primary)',
+  error: 'var(--color-destructive)',
+  warning: 'var(--color-warning)',
+  pause: 'var(--color-muted-foreground)',
+  loading: 'var(--color-muted-foreground)',
+  help: 'var(--color-help)',
+  mention: 'var(--color-primary)',
+};
+
+const STATUS_ICON_MAP: Record<
+  TagStatus,
+  React.ComponentType<{ className?: string }>
+> = {
+  default: DefaultFilledIcon,
+  success: SuccessFilledIcon,
+  processing: ProcessingFilledIcon,
+  error: ErrorFilledIcon,
+  warning: WarningFilledIcon,
+  pause: PauseFilledIcon,
+  loading: Loader2,
+  help: HelpFilledIcon,
+  mention: MentionFilledIcon,
+};
+
+// ── 5 语义色 solid 的 bg / hover-bg 映射 ──────────────────────
+//
+// hover 加深统一公式:
+// - default(不透明 muted):叠加 foreground 8%,近似 #f7f7f7 → ~#e5e5e5(对齐
+//   设计可选 fallback `--tag-bordered-bg-hover` 的观感)
+// - primary / destructive(透明 mix):/10 → /20,与 palette / status 派生同一公式
+// - success / warning(不透明 subtle):叠加 foreground 5% 维持柔和(subtle 本身已低饱和)
+const SOLID_BG_MAP: Record<
+  NonNullable<TagProps['color']>,
+  { bg: string; hover: string }
+> = {
+  default: {
+    bg: 'var(--color-muted)',
+    hover: 'color-mix(in srgb, var(--color-foreground) 8%, var(--color-muted))',
+  },
+  primary: {
+    bg: 'color-mix(in srgb, var(--color-primary) 10%, transparent)',
+    hover: 'color-mix(in srgb, var(--color-primary) 20%, transparent)',
+  },
+  success: {
+    bg: 'var(--color-success-subtle)',
+    hover:
+      'color-mix(in srgb, var(--color-foreground) 5%, var(--color-success-subtle))',
+  },
+  warning: {
+    bg: 'var(--color-warning-subtle)',
+    hover:
+      'color-mix(in srgb, var(--color-foreground) 5%, var(--color-warning-subtle))',
+  },
+  destructive: {
+    bg: 'color-mix(in srgb, var(--color-destructive) 10%, transparent)',
+    hover: 'color-mix(in srgb, var(--color-destructive) 20%, transparent)',
+  },
+};
+
+// ─── cva(仅覆盖 solid / outline / ghost 三种背景形态) ───────────────────
+const tagVariants = cva(
+  'inline-flex items-center gap-1 overflow-hidden whitespace-nowrap text-ellipsis border border-border font-normal transition-colors shrink-0 max-w-full',
+  {
+    variants: {
+      variant: {
+        solid: '',
+        outline: 'bg-transparent',
+        ghost: 'border-transparent bg-transparent',
+      },
+      color: {
+        default: '',
+        primary: '',
+        success: '',
+        warning: '',
+        destructive: '',
+      },
+      size: {
+        sm: 'h-5 px-3 text-xs',
+        md: 'h-6 px-3 text-xs',
+        lg: 'h-7 px-3 text-xs',
+      },
+    },
+    compoundVariants: [
+      // ── solid (filled background:边框透明,背景独捞视觉) ──
+      // 静态 bg 作为 fallback;hover 加深走 inline `--tag-bg` / `--tag-bg-hover`
+      // 变量 + className `bg-[var(...)] hover:bg-[var(...)]`完成(参见下方
+      // SOLID_BG_MAP 与 composedStyle 注入),使 palette / status 派生 / 5 语义色都在同一机制上 hover。
+      {
+        variant: 'solid',
+        color: 'default',
+        className: 'border-transparent bg-muted text-muted-foreground',
+      },
+      {
+        variant: 'solid',
+        color: 'primary',
+        className: 'border-transparent bg-primary/10 text-primary',
+      },
+      {
+        variant: 'solid',
+        color: 'success',
+        className: 'border-transparent bg-success-subtle text-success',
+      },
+      {
+        variant: 'solid',
+        color: 'warning',
+        className: 'border-transparent bg-warning-subtle text-warning',
+      },
+      {
+        variant: 'solid',
+        color: 'destructive',
+        className: 'border-transparent 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' },
+  },
+);
+
+// ─── closable 配置 ──────────────────────────────────────────────────────
+export interface TagClosableConfig {
+  /** 自定义关闭图标(默认 lucide `<X />`)。 */
+  closeIcon?: React.ReactNode;
+  /**
+   * 关闭响应区域:
+   * - `tail`(默认)只点击右侧关闭按钮触发
+   * - `tag` 整个标签可点击关闭,关闭按钮隐藏
+   */
+  closeArea?: 'tag' | 'tail';
+  /** 关闭按钮 aria-label(默认 `'Close'`)。 */
+  'aria-label'?: string;
+}
+
+export interface TagProps
+  extends Omit<React.ComponentProps<'span'>, 'color'>,
+    Omit<VariantProps<typeof tagVariants>, 'variant'> {
+  /** 形态轴:`solid` 实色背景(默认) / `outline` 仅描边 / `ghost` 仅文字 / `status` 状态形态(颜色由 `status` 决定,`variant='status'` 时 color/palette/icon 失效)。 */
+  variant?: 'solid' | 'outline' | 'ghost' | 'status';
+  /** 语义色 — 5 档(ADR 0021)。仅在 `variant !== 'status'` 时生效。装饰类别区分用 `palette`。 */
+  color?: 'default' | 'primary' | 'success' | 'warning' | 'destructive';
+  /** 尺寸:`sm` 高 20px / `md` 高 24px(默认) / `lg` 高 28px。 */
+  size?: 'sm' | 'md' | 'lg';
+  /** 状态语义 9 档:`success` / `processing` / `error` / `warning` / `pause` / `loading` / `help` / `mention` / `default`。`variant='status'` 渲染圆点/图标;其他 variant 自动派生彩色。 */
+  status?: TagStatus;
+  /** `variant='status'` 时是否渲染前缀图标(默认 `false`,渲染圆点)。 */
+  showIcon?: boolean;
+  /** 分类装饰色，与语义色正交。9 预设 + 任意 CSS 值。`variant='status'` 时失效。 */
+  palette?: TagPalettePreset | (string & {});
+  /** 标签文字左侧图标插槽。`variant='status'` 时失效(由内置图标接管)。 */
+  icon?: React.ReactNode;
+  /** 关闭按钮配置。`true` 启用默认关闭，对象签名可配 `closeIcon` / `closeArea` / `aria-label`。`onClose(e).preventDefault()` 可阻止。 */
+  closable?: boolean | TagClosableConfig;
+  /** 关闭回调。可调用 `e.preventDefault()` 阻止默认关闭(对齐 antd v6)。 */
+  onClose?: (
+    e: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>,
+  ) => void;
+  /** 关闭隐藏后回调(对齐 cloud-design `afterClose`)。 */
+  afterClose?: () => void;
+  /** 受控可见性。 */
+  visible?: boolean;
+  /** 非受控初始可见性,默认 `true`。 */
+  defaultVisible?: boolean;
+  /** 禁用态:灰显 + cursor-not-allowed,点击 / 关闭均无效。 */
+  disabled?: boolean;
+  /**
+   * 去除边框显示。在 OP 主题下，带 icon 的分类 Tag 使用此样式：
+   * 仅保留浅色背景 + 彩色文字 + 前缀图标，无边框线。
+   */
+  borderless?: boolean;
+  /** Slot 模式渲染为子元素(如 `<a>`);此模式下不内置渲染 icon 与关闭按钮。 */
+  asChild?: boolean;
+}
+
+function normalizeClosable(
+  closable: TagProps['closable'],
+): TagClosableConfig | null {
+  if (!closable) return null;
+  if (typeof closable === 'object') return closable;
+  return {};
+}
+
+function renderCloseIcon(node: React.ReactNode): React.ReactNode {
+  if (node === undefined) return <X className="size-3" />;
+  if (React.isValidElement<{ className?: string }>(node)) {
+    return React.cloneElement(node, {
+      className: cn('size-3', node.props?.className),
+    });
+  }
+  return node;
+}
+
+function Tag({
+  variant = 'solid',
+  color = 'default',
+  size = 'md',
+  status = 'default',
+  showIcon = false,
+  palette,
+  icon,
+  closable = false,
+  onClose,
+  afterClose,
+  visible,
+  defaultVisible = true,
+  disabled = false,
+  borderless = false,
+  asChild = false,
+  className,
+  style,
+  children,
+  onClick,
+  ...props
+}: TagProps) {
+  const isControlled = visible !== undefined;
+  const [internalOpen, setInternalOpen] = React.useState(defaultVisible);
+  const open = isControlled ? visible : internalOpen;
+
+  const closableConfig = asChild ? null : normalizeClosable(closable);
+  const closeArea = closableConfig?.closeArea ?? 'tail';
+  const closeAriaLabel = closableConfig?.['aria-label'] ?? 'Close';
+
+  const triggerClose = (
+    e: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>,
+  ) => {
+    if (disabled) return;
+    onClose?.(e);
+    if (e.defaultPrevented) return;
+    if (!isControlled) setInternalOpen(false);
+    if (typeof requestAnimationFrame !== 'undefined') {
+      requestAnimationFrame(() => afterClose?.());
+    } else {
+      afterClose?.();
+    }
+  };
+
+  const handleClick = (e: React.MouseEvent<HTMLSpanElement>) => {
+    onClick?.(e);
+    if (disabled) return;
+    if (closableConfig && closeArea === 'tag' && !e.defaultPrevented) {
+      triggerClose(e);
+    }
+  };
+
+  if (!open) return null;
+
+  const closeButton = closableConfig ? (
+    <button
+      type="button"
+      aria-label={closeAriaLabel}
+      disabled={disabled}
+      onClick={(e) => {
+        e.stopPropagation();
+        triggerClose(e);
+      }}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          e.stopPropagation();
+          triggerClose(e);
+        }
+      }}
+      className={cn(
+        '-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',
+        disabled && 'cursor-not-allowed opacity-30 hover:opacity-30',
+      )}
+    >
+      {renderCloseIcon(closableConfig.closeIcon)}
+    </button>
+  ) : null;
+
+  // ── variant='status':单独渲染路径,忽略 color / palette / icon ──
+  if (variant === 'status') {
+    const Icon = STATUS_ICON_MAP[status];
+    const tone = STATUS_TOKEN_MAP[status];
+    const Comp = asChild ? Slot.Root : 'span';
+    return (
+      <Comp
+        data-slot="tag"
+        data-variant="status"
+        data-status={status}
+        data-size={size}
+        data-disabled={disabled || undefined}
+        data-closable={closableConfig ? '' : undefined}
+        data-close-area={closableConfig ? closeArea : undefined}
+        aria-disabled={disabled || undefined}
+        className={cn(
+          'inline-flex h-6 max-w-full items-center gap-1.5 overflow-hidden whitespace-nowrap text-ellipsis text-xs font-normal shrink-0',
+          size === 'sm' && 'h-5',
+          size === 'lg' && 'h-7',
+          disabled && 'cursor-not-allowed opacity-50',
+          closableConfig &&
+            closeArea === 'tag' &&
+            !disabled &&
+            'cursor-pointer',
+          className,
+        )}
+        style={{ color: tone, ...style }}
+        onClick={handleClick}
+        {...props}
+      >
+        {asChild ? (
+          children
+        ) : (
+          <>
+            {showIcon ? (
+              <Icon
+                aria-hidden="true"
+                className={cn(
+                  'size-3.5 shrink-0',
+                  status === 'loading' && 'animate-spin',
+                )}
+              />
+            ) : (
+              <span
+                aria-hidden="true"
+                className={cn(
+                  'size-1.5 shrink-0 rounded-full',
+                  status === 'processing' && 'animate-pulse',
+                )}
+                style={{ backgroundColor: tone }}
+              />
+            )}
+            {children}
+            {closeArea === 'tail' ? closeButton : null}
+          </>
+        )}
+      </Comp>
+    );
+  }
+
+  // ── 普通 solid / outline / ghost 路径 ──
+  const composedStyle: React.CSSProperties = {
+    borderRadius: 'var(--radius-tag)',
+  };
+  // palette / status 派生 solid 路径需要 hover 加深 — 通过 CSS 变量驱动
+  // (inline backgroundColor 的 specificity 会压过 :hover className,
+  // 所以静态 bg 也走变量,className 用 `bg-[var(--tag-bg)]` 引用)
+  let hasInlineSolidHover = false;
+
+  if (palette) {
+    const ps = resolvePaletteStyle(palette);
+    composedStyle.color = ps.color;
+    if (variant === 'solid') {
+      (composedStyle as Record<string, string>)['--tag-bg'] =
+        ps.backgroundColor;
+      (composedStyle as Record<string, string>)['--tag-bg-hover'] =
+        ps.backgroundColorHover;
+      composedStyle.borderColor = ps.borderColor;
+      hasInlineSolidHover = true;
+    } else if (variant === 'outline') {
+      composedStyle.borderColor = ps.color;
+    }
+  } else if (status !== 'default' && color === 'default') {
+    // ── status 自动派生色彩(对齐 teamix-pro ProField tag column) ──
+    const statusColor = STATUS_TOKEN_MAP[status];
+    composedStyle.color = statusColor;
+    if (variant === 'solid') {
+      (composedStyle as Record<string, string>)[
+        '--tag-bg'
+      ] = `color-mix(in srgb, ${statusColor} 12%, transparent)`;
+      (composedStyle as Record<string, string>)[
+        '--tag-bg-hover'
+      ] = `color-mix(in srgb, ${statusColor} 20%, transparent)`;
+      composedStyle.borderColor = `color-mix(in srgb, ${statusColor} 25%, transparent)`;
+      hasInlineSolidHover = true;
+    } else if (variant === 'outline') {
+      composedStyle.borderColor = statusColor;
+    }
+  } else if (variant === 'solid') {
+    // ── 5 语义色 solid 默认路径:注入同一套 --tag-bg / --tag-bg-hover 变量 ──
+    const m = SOLID_BG_MAP[color];
+    (composedStyle as Record<string, string>)['--tag-bg'] = m.bg;
+    (composedStyle as Record<string, string>)['--tag-bg-hover'] = m.hover;
+    hasInlineSolidHover = true;
+  }
+
+  if (borderless) {
+    composedStyle.borderColor = 'transparent';
+  }
+
+  const Comp = asChild ? Slot.Root : 'span';
+  return (
+    <Comp
+      data-slot="tag"
+      data-variant={variant}
+      data-color={color}
+      data-size={size}
+      data-disabled={disabled || undefined}
+      data-closable={closableConfig ? '' : undefined}
+      data-close-area={closableConfig ? closeArea : undefined}
+      aria-disabled={disabled || undefined}
+      className={cn(
+        tagVariants({ variant, color, size }),
+        hasInlineSolidHover &&
+          'bg-[var(--tag-bg)] hover:bg-[var(--tag-bg-hover)]',
+        disabled && 'cursor-not-allowed opacity-50',
+        closableConfig && closeArea === 'tag' && !disabled && 'cursor-pointer',
+        className,
+      )}
+      style={{ ...composedStyle, ...style }}
+      onClick={handleClick}
+      {...props}
+    >
+      {asChild ? (
+        children
+      ) : (
+        <>
+          {icon ? (
+            <span
+              aria-hidden="true"
+              className="inline-flex shrink-0 items-center [&_svg]:size-3"
+            >
+              {icon}
+            </span>
+          ) : null}
+          {children}
+          {closeArea === 'tail' ? closeButton : null}
+        </>
+      )}
+    </Comp>
+  );
+}
+
+// ─── TagGroup（普通 Tag 横排容器,对齐 cloud-design Tag.Group） ────────────
+
+export interface TagGroupProps extends React.ComponentProps<'div'> {
+  /** 间距档位:`sm` 6px / `md` 8px(默认) / `lg` 12px。 */
+  gap?: 'sm' | 'md' | 'lg';
+}
+
+const TAG_GROUP_GAP_MAP: Record<NonNullable<TagGroupProps['gap']>, string> = {
+  sm: 'gap-1.5',
+  md: 'gap-2',
+  lg: 'gap-3',
+};
+
+function TagGroup({ gap = 'md', className, ...props }: TagGroupProps) {
+  return (
+    <div
+      data-slot="tag-group"
+      data-gap={gap}
+      role="group"
+      className={cn(
+        'flex flex-wrap items-center',
+        TAG_GROUP_GAP_MAP[gap],
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── CheckableTag(antd `Tag.CheckableTag` 并集) ─────────────────────────
+
+export interface CheckableTagProps
+  extends Omit<React.ComponentProps<'span'>, 'onChange'> {
+  /** 是否选中(受控)。 */
+  checked: boolean;
+  /** 选中态变化回调。 */
+  onChange?: (next: boolean) => void;
+  /** 形态:`solid`(默认) 选中填充 / `outline` 选中描边。 */
+  variant?: 'solid' | 'outline';
+  /** 禁用。 */
+  disabled?: boolean;
+}
+
+function CheckableTag({
+  checked,
+  onChange,
+  variant = 'solid',
+  disabled,
+  className,
+  style,
+  children,
+  ...props
+}: CheckableTagProps) {
+  return (
+    <span
+      data-slot="checkable-tag"
+      data-checked={checked}
+      data-variant={variant}
+      data-disabled={disabled || undefined}
+      role="checkbox"
+      aria-checked={checked}
+      aria-disabled={disabled}
+      tabIndex={disabled ? -1 : 0}
+      onClick={() => {
+        if (!disabled) onChange?.(!checked);
+      }}
+      onKeyDown={(e) => {
+        if (!disabled && (e.key === ' ' || e.key === 'Enter')) {
+          e.preventDefault();
+          onChange?.(!checked);
+        }
+      }}
+      style={{ borderRadius: 'var(--radius-tag)', ...style }}
+      className={cn(
+        'inline-flex h-6 max-w-full cursor-pointer items-center gap-1 overflow-hidden whitespace-nowrap text-ellipsis border border-border px-2 text-xs font-normal transition-colors shrink-0',
+        'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        variant === 'outline'
+          ? checked
+            ? 'border-primary text-primary bg-primary/10 hover:bg-primary/15'
+            : 'border-border text-foreground bg-transparent hover:bg-accent'
+          : checked
+          ? 'border-primary bg-primary text-primary-foreground hover:bg-primary/90'
+          : 'border-border bg-muted text-foreground hover:bg-accent',
+        disabled && 'cursor-not-allowed opacity-50',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </span>
+  );
+}
+
+// ─── CheckableTagGroup(antd v6 + cloud-design Tag.Selectable 并集) ──────
+
+export interface CheckableTagGroupOption {
+  /** 显示文本。 */
+  label: React.ReactNode;
+  /** 真实 value(受控集合的比对依据)。 */
+  value: string;
+  /** 禁用此项。 */
+  disabled?: boolean;
+}
+
+interface CheckableTagGroupBaseProps
+  extends Omit<
+    React.ComponentProps<'div'>,
+    'onChange' | 'defaultValue' | 'value'
+  > {
+  /** 候选项数组。 */
+  options: CheckableTagGroupOption[];
+  /** 可选标签形态:`solid`(默认) / `outline`。 */
+  variant?: 'solid' | 'outline';
+  /** 整组禁用。 */
+  disabled?: boolean;
+}
+
+export interface CheckableTagGroupMultipleProps
+  extends CheckableTagGroupBaseProps {
+  /** 多选模式(默认)。 */
+  multiple?: true;
+  /** 受控选中 value 集合。 */
+  value?: string[];
+  /** 非受控初值。 */
+  defaultValue?: string[];
+  /** 选中变化回调(多选)。 */
+  onChange?: (next: string[]) => void;
+}
+
+export interface CheckableTagGroupSingleProps
+  extends CheckableTagGroupBaseProps {
+  /** 单选模式。 */
+  multiple: false;
+  /** 受控选中 value(单选)。 */
+  value?: string | null;
+  /** 非受控初值(单选)。 */
+  defaultValue?: string | null;
+  /** 选中变化回调(单选,取消时回传 `null`)。 */
+  onChange?: (next: string | null) => void;
+}
+
+export type CheckableTagGroupProps =
+  | CheckableTagGroupMultipleProps
+  | CheckableTagGroupSingleProps;
+
+function CheckableTagGroup(props: CheckableTagGroupProps) {
+  const {
+    options,
+    variant,
+    disabled,
+    className,
+    multiple = true,
+    ...rest
+  } = props as CheckableTagGroupBaseProps & {
+    multiple?: boolean;
+    value?: string[] | string | null;
+    defaultValue?: string[] | string | null;
+    onChange?: (next: string[] | string | null) => void;
+  };
+  const isMultiple = multiple !== false;
+  const isControlled = rest.value !== undefined;
+
+  const [internal, setInternal] = React.useState<string[] | string | null>(
+    rest.defaultValue ?? (isMultiple ? [] : null),
+  );
+  const current = isControlled ? rest.value : internal;
+
+  const isChecked = (v: string) =>
+    isMultiple ? Array.isArray(current) && current.includes(v) : current === v;
+
+  const toggle = (v: string, next: boolean) => {
+    let nextValue: string[] | string | null;
+    if (isMultiple) {
+      const arr = Array.isArray(current) ? current : [];
+      nextValue = next ? [...arr, v] : arr.filter((x) => x !== v);
+    } else {
+      nextValue = next ? v : null;
+    }
+    if (!isControlled) setInternal(nextValue);
+    rest.onChange?.(nextValue as string[] & string & null);
+  };
+
+  // 把交互相关的 prop 抽出后剩余的 div props
+  const { value: _v, defaultValue: _dv, onChange: _oc, ...divProps } = rest;
+
+  return (
+    <div
+      data-slot="checkable-tag-group"
+      data-multiple={isMultiple || undefined}
+      role={isMultiple ? 'group' : 'radiogroup'}
+      className={cn('flex flex-wrap gap-2', className)}
+      {...divProps}
+    >
+      {options.map((opt) => (
+        <CheckableTag
+          key={opt.value}
+          checked={isChecked(opt.value)}
+          variant={variant}
+          disabled={disabled || opt.disabled}
+          onChange={(c) => toggle(opt.value, c)}
+        >
+          {opt.label}
+        </CheckableTag>
+      ))}
+    </div>
+  );
+}
+
+export {
+  Tag,
+  TagGroup,
+  CheckableTag,
+  CheckableTagGroup,
+  tagVariants,
+  TAG_PALETTE_PRESETS,
+};