YMetrics

统一统计呈现入口。用于列表、工作区和概览页；统计请求、数据口径和点击后的业务动作由消费者负责。组件根据自身可用宽度呈现 Cards、Strip 或 Summary，不创建统计运行时。

Usage

Import / Basic

<script setup lang="ts">
import { YMetrics, type MetricGroup } from '@yoyoboot/ui-patterns/metrics'
const groups: MetricGroup[] = [{ key: 'users', label: '用户概览', items: [
  { key: 'total', label: '用户总数', value: 120, priority: 'primary', clickable: false },
  { key: 'active', label: '活跃用户', value: 84, priority: 'primary' },
  { key: 'pending', label: '待处理', value: 12, priority: 'secondary' }
] }]
function select(key: string) { /* 由业务应用筛选或打开详情 */ }
</script>
<template>
  <YMetrics :groups="groups" presentation="cards" compact-presentation="summary" @select="select" />
</template>

Presentations

形态	用途
cards	独立统计卡片，支持图标、说明与趋势
strip	按业务组排列的紧凑统计条
summary	最多四项的收起摘要，其余通过“更多统计”访问

presentation 必填，表示宽工作区形态；compactPresentation 默认 summary，也可显式选择其他形态。没有猜测业务用途的 auto 模式；业务不直接导入内部 Presenter。

Priority / emphasis

Summary 收起时按原始顺序优先选择 primary，再用未指定 priority 的项补足，最多四项。secondary 和超出预算的项进入更多统计。全部展开可以访问所有项；不能通过超过四个 primary 撑高默认首屏。

emphasis 只调整视觉强调，不改变顺序或可见性。各项 key 应在当前统计集合中唯一，与 select 事件中的业务 key 保持一致。

Busy / failure / stale / retry

<YMetrics :groups="groups" presentation="strip" :busy="updating"
  :state="failed ? 'stale-success' : updating ? 'updating' : 'ready'"
  @select="select" @retry="reloadMetrics" />

ready 不显示状态文案；updating 提供正在更新提示；failure / stale-success 使用错误色并显示重试。保留上次值与首次失败的占位值由消费者提供，不由组件伪造。clickable: false 是只读项；handoff 表示跳转而非筛选开关，因此不使用 aria-pressed。

API

Props

属性	合同
groups	MetricGroup[]，必填
presentation	cards / strip / summary，必填
compactPresentation	同上，默认 summary
busy	可选忙碌标识，影响 aria-busy
state	ready / updating / failure / stale-success，默认 ready
locale	可选数字格式化语言；省略使用应用 n
labels	可选 MetricLabels：more / less / help，及 updating / failure / stale / retry

MetricGroup 为 key、label、items。MetricItem 为 key、label、value，加可选 priority、emphasis、active、handoff、clickable、hint、icon、description、trend。trend 为 value 及 positive / negative / neutral tone。不存在设备专属的 mobilePrimary / mobileSecondary 字段。

Events / Slots

• select(key)：同一个业务指标 key；不提交查询或发起请求。
• retry()：由消费者恢复统计读取。
• presentation 插槽：得到 groups、presentation、select，可组合确有业务差异的展示；不提供内部 Presenter 的公开导入入口。

Responsive

依据组件自己的工作区测宽，而不是 viewport。大屏中的 420px Drawer 或分栏仍使用 compact fallback。测宽机制和内部阈值不属于公共配置 API。

compact expanded 切到 wide 后退出展开，再回 compact 从收起状态开始。切换不会初始化业务数据、请求或筛选。若焦点原本在组件内，通过 metric key 或展开意图恢复到等价目标；组件外的焦点不抢夺。

Theme / Visual

使用现有 Nuxt UI 与 management visual foundation 的背景、边框、主色和错误色，支持 light / dark、comfortable / compact 及 reduced-motion；不增加第二 Skin runtime。

Accessibility

可操作指标使用原生 button，支持键盘；筛选状态使用 aria-pressed，跳转指标不伪装为开关。帮助入口有独立 label，展开按钮提供 aria-expanded / aria-controls，更新提示使用 status 和 polite live region。reduced-motion 下取消统计项的视觉过渡。

Underlying implementation

YMetrics 调度包内 MetricCards / MetricStrip / MetricSummary；MetricItem 复用单项呈现。业务指标合同在 metrics/contracts.ts，统计事实不属于 List Workbench 或 Page Shell。

Source / Verification

公开入口 · 组件 · 数据合同

确定性检查：packages/ui-patterns/tests/metrics.spec.ts、tests/list-workbench/data-table.spec.ts。可运行容器与筛选任务示例：templates/admin-nuxtui-starter/tests-e2e/fixtures/responsive.html；浏览器用例为 tests-e2e/responsive-presentation.spec.ts。

本页是该组件的 canonical 文档；是否发布到站点由 docs/site.manifest.json 控制。具体工程证据与未完成项仍由 owning change 保存。