Ordo UI
PatternsData Display

ChartCard

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

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

变体轴

height
smmdlg
变体演示chart-card
任务分布
近 7 天
图表内容区

Props API

Prop类型默认值说明
title*ReactNode——
hint*ReactNode——
action*ReactNode——
height*ChartCardHeight"md"—
footer*ReactNode——
children*ReactNode——

源码

packages/patterns/src/components/chart-card.tsx
import type * as React from "react"

import { SectionCard } from "./section-card"

type ChartCardHeight = "sm" | "md" | "lg"

/**
 * height 档位映射自现用图表容器高度实测(2026-09-29 grep ChartContainer/图卡容器):
 * - sm = h-30:project-overview-charts 任务分布 PieChart(唯一 h-30 实例)
 * - md = h-40(默认):project-overview-charts 燃尽 AreaChart + analytics 成本 BarChart(最高频档)
 * - lg = h-56:team-stats-section Token 折线(CardContent h-56 档)
 */
const HEIGHT_CLASS: Record<ChartCardHeight, string> = {
  sm: "h-30",
  md: "h-40",
  lg: "h-56",
}

/**
 * 把 SectionCard 卡头拉回本件旧基线(W3 组合化对齐,不改 SectionCard 本身):
 * - CardHeader 基类是 grid(SectionCard 的 `flex-row` 只改方向、不改 display),
 *   补 `flex` 让标题与 hint/action 回到同一行;
 * - 旧卡头是 p-4 单行、上下均 16px,SectionCard 默认只有水平内距 + pb-1;
 * - 旧卡头标题与右侧组间距 gap-2,SectionCard 默认 gap-1;
 * - 旧基线标题行 items-center,SectionCard 默认 items-start。
 * 后代变体落在 SectionCard 根 Card 上,特异性高于卡头自身的 grid/gap-1/pb-1,
 * 无需改 SectionCard 的公开面。
 */
const HEADER_ALIGN_CLASS =
  "[&>[data-slot=card-header]]:flex [&>[data-slot=card-header]]:items-center [&>[data-slot=card-header]]:gap-2 [&>[data-slot=card-header]]:p-4"

/**
 * ChartCard —— 图表卡壳(G 类 semantic 批二)
 *
 * 「标题 + 卡头右侧 hint/action + 固定高度图表容器」组合的唯一实现,
 * 抽象自 project-overview-charts / analytics-page / team-stats-section 等 8+ 处手写图表卡。
 *
 * W3 冗余收敛(2026-11-19):壳不再自持 ui/card 四件套,改为 SectionCard 组合——
 * 卡头/内容槽由 SectionCard 承担,本件只保留固定高度档(HEIGHT_CLASS)与来源行 footer。
 * 公开 props 面不变:显式声明 props,不接 `className`、不透传 variant、不 extends
 * HTMLAttributes。图表实现(ChartContainer + recharts 配置)留在 children 由调用方组装,
 * children 内图表用 `h-full w-full` 填充(ChartContainer 基类自带 aspect-video,
 * h-full 覆盖之),不再自带高度档。
 *
 * 视觉对齐(差异全部用 className 收口,不改 SectionCard):
 * - 根 Card 的 py-3.5/gap-3 是为裸卡设计的 → `py-0 gap-0` 归零,保持旧壳四边只有
 *   p-4 单一来源 = 16px;
 * - 卡头 → HEADER_ALIGN_CLASS(p-4 单行、标题左 / hint+action 右,text-sm font-medium);
 * - 内容槽 → SectionCard 默认 pt-0 保持,`px-4 pb-4` 对齐旧 CardContent。
 *
 * 组件协议:SectionCard 根槽位为 data-slot="card";图表容器与来源行仍分别标
 * data-slot="chart-card-plot" / "chart-card-footer"。
 */
function ChartCard({
  title,
  hint,
  action,
  height = "md",
  footer,
  children,
}: {
  /** 卡头左侧标题(text-sm font-medium 基线;lieflat 语法=标题写结论不写图型名) */
  title: React.ReactNode
  /** 卡头右侧说明文字(text-xs font-normal text-muted-foreground 基线;lieflat 语法=编码说明/图例放这里) */
  hint?: React.ReactNode
  /** 卡头右侧动作区(按钮等,排在 hint 之后) */
  action?: React.ReactNode
  /** 图表区定高档:sm=h-30 / md=h-40(默认)/ lg=h-56,映射现用值见 HEIGHT_CLASS */
  height?: ChartCardHeight
  /**
   * 卡底来源行(lieflat 四件套签名:`DELIVERY · LAST 7 DAYS` 式纯拉丁大写元数据,
   * text-3xs tracking-widest——宪法 §2.4 纯 Latin 元数据豁免档)。不传不渲染。
   */
  footer?: React.ReactNode
  children: React.ReactNode
}) {
  const hasAside = hint != null || action != null

  return (
    <SectionCard
      title={title}
      titleClassName="text-sm font-medium"
      actions={
        hasAside ? (
          <span className="flex shrink-0 items-center gap-2">
            {hint != null && (
              <span className="text-xs font-normal text-muted-foreground">{hint}</span>
            )}
            {action}
          </span>
        ) : undefined
      }
      className={`py-0 gap-0 ${HEADER_ALIGN_CLASS}`}
      contentClassName="px-4 pb-4"
    >
      <div data-slot="chart-card-plot" className={HEIGHT_CLASS[height]}>
        {children}
      </div>
      {footer != null && (
        <div
          data-slot="chart-card-footer"
          className="mt-3 pt-2.5 border-t border-border text-3xs font-medium tracking-widest text-muted-foreground"
        >
          {footer}
        </div>
      )}
    </SectionCard>
  )
}

export { ChartCard }
export type { ChartCardHeight }

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

用法说明

图表卡片壳:标题/描述/操作槽 + 固定高度档(sm/md/lg),内容区承载图表;不依赖 recharts。