Ordo UI
PatternsSemantic

Chip

@mox-hub/patterns 模式 · Semantic · canonical

chip@mox-hub/patternsSemanticcanonicalsrc/components/chip.tsx

变体轴

tone
defaultdangerprimary
shape
pillsoft
变体演示chip
标签可关闭soft

Props API

Prop类型默认值说明
tone*ChipTone"default"—
shape*ChipShape"pill"—
variant*ChipVariant"outline"—
onClick*() => void——
onRemove*() => void——
disabled*boolean——
icon*ReactNode——
children*ReactNode——
labels*Partial<{ remove: string; }>——

源码

packages/patterns/src/components/chip.tsx
import { X } from "lucide-react"
import type * as React from "react"

import { RawButton } from "@mox-hub/ui/components/raw/raw-button"
import { TONE_CLASS as TONE_VISUALS } from "@mox-hub/ui/components/tone"
import { cn } from "@mox-hub/ui"
import { usePatternLabels } from "../lib/i18n"

const CHIP_DEFAULT_LABELS = { remove: "移除" }

type ChipTone = "default" | "danger" | "primary" | "info" | "warning" | "success"
type ChipShape = "pill" | "soft"
type ChipVariant = "outline" | "status"

const OUTLINE_TONE_CLASS: Record<ChipTone, { base: string; remove: string }> = {
  default: {
    base: "border-border text-content-text-secondary hover:bg-muted hover:text-foreground",
    remove: "hover:text-destructive",
  },
  danger: {
    base: "border-border text-content-text-secondary hover:border-accent-red/40 hover:bg-accent-red-light hover:text-accent-red",
    remove: "hover:text-destructive",
  },
  primary: {
    base: "border-dashed border-border text-muted-foreground hover:border-primary hover:text-primary",
    remove: "hover:text-destructive",
  },
  info: {
    base: "border-border text-content-text-secondary hover:border-accent-blue/40 hover:bg-accent-blue-light hover:text-accent-blue",
    remove: "hover:text-destructive",
  },
  warning: {
    base: "border-border text-content-text-secondary hover:border-accent-yellow/40 hover:bg-accent-yellow-light hover:text-accent-yellow",
    remove: "hover:text-destructive",
  },
  success: {
    base: "border-border text-content-text-secondary hover:border-accent-green/40 hover:bg-accent-green-light hover:text-accent-green",
    remove: "hover:text-destructive",
  },
}

/** status 变体:静态状态胶囊,复用 tone 唯一词表的浅底槽。 */
const STATUS_TONE_CLASS: Record<ChipTone, string> = {
  default: TONE_VISUALS.default.light,
  danger: TONE_VISUALS.danger.light,
  info: TONE_VISUALS.info.light,
  warning: TONE_VISUALS.warning.light,
  success: TONE_VISUALS.success.light,
  // primary 不在 Tone 五档词表内,沿用 accent-purple 浅底(与 AI 标识一致)
  primary: "bg-accent-purple-light text-accent-purple",
}

const SHAPE_CLASS: Record<ChipShape, string> = {
  pill: "rounded-full px-2.5 py-1",
  soft: "rounded-md px-2 py-0.5",
}

const CHIP_BASE =
  "inline-flex min-w-0 max-w-full shrink-0 items-center gap-1 truncate border bg-background text-xs whitespace-nowrap transition-colors"

/**
 * Chip —— 语义组件层首件(G 类批 G1;G5 裁决示范组件,自 stash 留档复活)
 *
 * 标签 / 胶囊 / 可关闭标签的唯一实现:可关闭标签、驳回原因 chips、过滤器 tag、
 * 计数胶囊等形态的唯一真相源,业务面不再为标签形态裸写 button。
 *
 * **raw vs ui 边界判例一(G8 落点,后续语义组件照此裁断)**:
 * - 「容器可点击」的展示件不是动作钮——可点击语义用 `RawButton` 承载(button 元素
 *   可达性 + `type="button"` 防表单误提交),**刻意不用 `<Button>`**:chip 不参与
 *   §4.5 动作钮形态收敛,换 Button 会把它卷进 variant/size 轴。
 * - 尾部 × 关闭钮同理走 `RawButton`(删除的是 chip 自身,非页面动作钮)。
 * - 纯展示态(无 onClick 且无 onRemove)用 `span`。
 *
 * **props 面封闭(G8 裁决口径,本组件即首例)**:显式声明 props,不接 `className`
 * (形态内聚,不留样式透传口子)、不透传 variant、不 extends HTMLAttributes。
 * 复核记录:stash 原实现曾接 className,批 G1 复核时按 G8 摘除。
 *
 * 形态:
 * - `shape="pill"`(默认)胶囊——动作 chips / 计数胶囊;`shape="soft"` 小圆角——标签 tag。
 * - `variant="outline"`(默认)悬停语义色:`danger` 悬停转红(驳回原因 chips)、
 *   `primary` 悬停转主色(Add tag,dashed 虚线框)。
 * - `variant="status"` 静态状态胶囊:复用 tone 五档浅底(default/info/warning/success/danger)
 *   + primary 的 AI 紫;用于替代已弃用的 `status-pill`。
 */
function Chip({
  tone = "default",
  shape = "pill",
  variant = "outline",
  onClick,
  onRemove,
  disabled,
  icon,
  children,
  labels,
}: {
  /** 语义色:outline 控制悬停色 / status 控制静态浅底色 */
  tone?: ChipTone
  /** pill 胶囊(动作 chips / 计数胶囊)| soft 小圆角(标签 tag) */
  shape?: ChipShape
  /** outline 可交互样式(默认)| status 静态状态胶囊 */
  variant?: ChipVariant
  /** 可点击语义(内部 RawButton 承载;不传且无 onRemove 时为 span 展示) */
  onClick?: () => void
  /** 传入则渲染尾部 × 关闭钮 */
  onRemove?: () => void
  disabled?: boolean
  icon?: React.ReactNode
  children?: React.ReactNode
  labels?: Partial<typeof CHIP_DEFAULT_LABELS>
}) {
  const D = usePatternLabels("chip", CHIP_DEFAULT_LABELS)
  const outline = OUTLINE_TONE_CLASS[tone]
  const toneClass =
    variant === "status" ? STATUS_TONE_CLASS[tone] : outline.base
  const interactive = Boolean(onClick)

  const removeButton = onRemove ? (
    <RawButton
      aria-label={labels?.remove ?? D.remove}
      disabled={disabled}
      onClick={
        interactive
          ? (e) => {
              e.stopPropagation()
              onRemove()
            }
          : onRemove
      }
      className={cn("ms-0.5 rounded-full transition-colors", outline.remove)}
    >
      <X className="size-2.5" />
    </RawButton>
  ) : null

  if (!interactive) {
    return (
      <span
        className={cn(
          CHIP_BASE,
          SHAPE_CLASS[shape],
          toneClass,
          variant === "status"
            ? "border-transparent font-semibold"
            : "font-normal",
          disabled && "pointer-events-none opacity-40",
        )}
      >
        {icon}
        {children}
        {removeButton}
      </span>
    )
  }

  return (
    <RawButton
      disabled={disabled}
      onClick={onClick}
      className={cn(
        CHIP_BASE,
        SHAPE_CLASS[shape],
        toneClass,
        variant === "status"
          ? "border-transparent font-semibold"
          : "font-normal",
        disabled && "pointer-events-none opacity-40",
      )}
    >
      {icon}
      {children}
      {removeButton}
    </RawButton>
  )
}

export { Chip }
export type { ChipTone, ChipShape, ChipVariant }

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

标签/胶囊/可关闭标签唯一实现:tone + shape 封闭轴;容器可点击语义用 RawButton,不用 Button。