Ordo UI
PatternsData Display

StatsCard

@mox-hub/patterns 模式 · Data Display · canonical

stats-card@mox-hub/patternsData Displaycanonicalsrc/components/stats-card.tsx

变体轴

layout
compactfeatured
columns
23456
变体演示stats-card

任务

12

本周新增

执行

38

AI 执行中 3

成本

$0.42

本周累计

Props API

Prop类型默认值说明
items*StatsCardItem[]——
columns*2 | 3 | 4 | 5 | 64—
responsive*booleanfalse—
layout*StatsCardLayout"compact"—

源码

packages/patterns/src/components/stats-card.tsx
import type { KeyboardEvent, ReactNode } from 'react'

import type { IconComponent } from '../lib/types';
import { cn } from "@mox-hub/ui"
import { useMessages } from "@mox-hub/ui/i18n"

/**
 * StatsCard —— 统计卡(语义层唯一统计卡实现,2026-09-29 统计卡归一批)
 *
 * 收编谱系(七套归一,裁决 2026-09-29):
 * - compact(默认)= 原 ui/stats-card 横排瓦片(10 页消费的事实主力,形态 class 逐字沿袭);
 * - featured = 原 ui/stat-card 竖排摘要大卡(project-dashboard 摘要行)+
 *   dashboard-page / settings ai overview / analytics 三处本地 KPI/Stat 卡的公共形态,
 *   hint / onClick 槽位只有 featured 消费;trend/trendValue 槽位已消亡移除
 *   (2026-09-30 晨会裁决:归一批后业务零消费、仅画廊 demo 持有,且 up=绿/down=红
 *   的语义映射与「错误数上升」类指标天然反向,不再承载);
 * - 卡底(surface)与数值彩色(coloredValue)为可选项,分别收编 team-stats 灰底
 *   汇总瓦片与 acceptance KPIStats 数值着色先例。
 * 字号口径统一走 compact 基线:数值 text-xl font-mono tabular-nums,标签 text-xs。
 *
 * props 面封闭(semantic/README.md 裁决 G8):不接 className、不 extends
 * HTMLAttributes;形态轴全部是封闭枚举(layout/tone/surface),无样式透传口子。
 * columns 为固定列;responsive=true 开启窄屏降档(md 断点以下 3 列及以上降为
 * 2 列)——2026-09-30 晨会裁决的封闭响应式档,不开 className 口子。
 * 装饰色 tone 词表留在视觉层组件内(同 metric-row 口径;§19.5 状态 tone 链路
 * ui/tone.ts 管业务状态语义,不承接此处 accent 点缀色)。
 */

/** 装饰色档(accent 点缀,非状态语义) */
export type StatsTone = "default" | "green" | "blue" | "yellow" | "red" | "purple" | "orange" | "gray"

/** tone → 图标色 + 卡片描边点缀(取值逐字沿袭原 ui/stats-card STATS_THEMES;orange 沿 metric-row 词表) */
const TONE_CLASS: Record<StatsTone, { icon: string; card?: string }> = {
  default: { icon: "text-muted-foreground" },
  green: { icon: "text-accent-green", card: "hover:border-accent-green/40" },
  blue: { icon: "text-accent-blue", card: "hover:border-accent-blue/40" },
  yellow: { icon: "text-accent-yellow", card: "hover:border-accent-yellow/40" },
  red: { icon: "text-accent-red", card: "hover:border-accent-red/40" },
  purple: { icon: "text-accent-purple", card: "hover:border-accent-purple/40" },
  orange: { icon: "text-accent-orange", card: "hover:border-accent-orange/40" },
  gray: { icon: "text-muted-foreground", card: "border-border/40" },
}

/** 卡底档:card=白卡描边(默认)/ muted=灰底无描边(team-stats 项目汇总先例) */
export type StatsSurface = "card" | "muted"

/** 形态变种:compact 横排瓦片 / featured 竖排摘要大卡 */
export type StatsCardLayout = "compact" | "featured"

export interface StatsCardItem {
  /** 唯一标识 */
  key: string
  /** 数值(text-xl font-mono tabular-nums 基线;语义色走 coloredValue,不手工传 class) */
  value: ReactNode
  /** 标签(compact 在数值下、featured 在数值上,text-xs text-muted-foreground 基线) */
  label: ReactNode
  /** 图标组件(size-8 灰底微框架内以 size-16 渲染) */
  icon?: IconComponent
  /** 装饰色档(图标着色 + hover 描边点缀;default 不加点缀) */
  tone?: StatsTone
  /** 数值随 tone 着色(acceptance KPIStats 先例;default/gray 无色效不染) */
  coloredValue?: boolean
  /** 卡底档,默认 card */
  surface?: StatsSurface
  /** featured:数值下方补充说明 */
  hint?: ReactNode
  /** featured:整卡可点(下钻),hover 反馈由背景色承载(宪法 §3.6) */
  onClick?: () => void
}

export interface StatsCardProps {
  /** 统计项列表 */
  items: StatsCardItem[]
  /** 网格列数(固定列,默认 4) */
  columns?: 2 | 3 | 4 | 5 | 6
  /** 窄屏降档:md 断点以下 3 列及以上降为 2 列(默认关,视觉零变化) */
  responsive?: boolean
  /** 形态变种,默认 compact */
  layout?: StatsCardLayout
}

/** 固定列档 */
const GRID_CLASS: Record<NonNullable<StatsCardProps["columns"]>, string> = {
  2: "grid-cols-2",
  3: "grid-cols-3",
  4: "grid-cols-4",
  5: "grid-cols-5",
  6: "grid-cols-6",
}

/** 窄屏降档(responsive=true):md 断点以下回 2 列 */
const GRID_RESPONSIVE_CLASS: Record<NonNullable<StatsCardProps["columns"]>, string> = {
  2: "grid-cols-2",
  3: "grid-cols-2 md:grid-cols-3",
  4: "grid-cols-2 md:grid-cols-4",
  5: "grid-cols-2 md:grid-cols-5",
  6: "grid-cols-2 md:grid-cols-6",
}

export function StatsCard({ items, columns = 4, responsive = false, layout = "compact" }: StatsCardProps) {
  const M = useMessages()
  // 审计 P2-24:空数组不再渲染空网格,给出本地化空态。
  if (items.length === 0) {
    return (
      <div data-slot="stats-card" className="text-sm text-muted-foreground">
        {M.common.empty}
      </div>
    )
  }
  return (
    <div
      data-slot="stats-card"
      className={cn("grid gap-3", (responsive ? GRID_RESPONSIVE_CLASS : GRID_CLASS)[columns])}
    >
      {items.map((item) => {
        const Icon = item.icon
        const tone = item.tone ?? "default"
        const toneClass = TONE_CLASS[tone]
        const valueTone =
          item.coloredValue && tone !== "default" && tone !== "gray" ? toneClass.icon : undefined
        const clickable = layout === "featured" && !!item.onClick
        const surfaceClass =
          item.surface === "muted"
            ? "bg-muted/50"
            : "border border-border/70 bg-card shadow-xs transition-colors hover:border-border"

        if (layout === "featured") {
          const onKeyDown = clickable
            ? (event: KeyboardEvent<HTMLDivElement>) => {
                if (event.key === 'Enter' || event.key === ' ') {
                  event.preventDefault()
                  item.onClick?.()
                }
              }
            : undefined
          return (
            <div
              key={item.key}
              data-slot="stats-card-item"
              className={cn(
                "rounded-lg p-4 text-card-foreground transition-colors",
                surfaceClass,
                // muted 底与 hover 同值时没有反馈(审计 P1-08):提高一档叠层。
                clickable &&
                  (item.surface === 'muted'
                    ? 'cursor-pointer hover:bg-muted'
                    : 'cursor-pointer hover:bg-muted'),
              )}
              onClick={item.onClick}
              onKeyDown={onKeyDown}
              role={clickable ? "button" : undefined}
              tabIndex={clickable ? 0 : undefined}
            >
              <div className="flex items-start justify-between gap-2">
                <p className="text-xs font-medium text-muted-foreground">{item.label}</p>
                {Icon && (
                  <div
                    className={cn(
                      "flex size-8 shrink-0 items-center justify-center rounded-md border border-border/40 bg-muted/40",
                      toneClass.icon,
                    )}
                  >
                    <Icon size={16} />
                  </div>
                )}
              </div>
              <p
                className={cn(
                  "mt-1 text-xl font-semibold font-mono tabular-nums leading-tight text-foreground",
                  valueTone,
                )}
              >
                {item.value}
              </p>
              {item.hint != null && (
                <p className="mt-1 text-xs text-muted-foreground">{item.hint}</p>
              )}
            </div>
          )
        }

        return (
          <div
            key={item.key}
            data-slot="stats-card-item"
            className={cn(
              "flex items-center gap-3 rounded-lg px-3.5 py-2.5",
              surfaceClass,
              toneClass.card,
            )}
          >
            {Icon && (
              <div
                className={cn(
                  "flex size-8 shrink-0 items-center justify-center rounded-md border border-border/40 bg-muted/40",
                  toneClass.icon,
                )}
              >
                <Icon size={16} />
              </div>
            )}
            <div className="flex min-w-0 flex-col">
              <span
                className={cn(
                  "truncate text-xl font-semibold font-mono tabular-nums leading-tight text-foreground",
                  valueTone,
                )}
              >
                {item.value}
              </span>
              <span className="mt-0.5 truncate text-xs text-muted-foreground">{item.label}</span>
            </div>
          </div>
        )
      })}
    </div>
  )
}

可访问性与 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。

用法说明

统计卡网格:items 驱动,columns 2-6,compact/featured 双形态;图标 tone 与可点击槽位由 items 声明。