Component / 062 / NEXOFRAME

GuardedStat

Mẫu chuẩn

Một thẻ chứa hai con số luôn đi cùng nhau: số cải thiện và số canh gác của nó. "Tự xử lý 82%" đứng cạnh "Vi phạm chính sách 0". Dựng trên Card, cùng kích thước với StatCard để xếp chung một dải.

Composite tầng 2Dựng từ Card, Separator3 guard stateunknown = "—"

Playground

Đổi guard state để xem màu giá trị canh gác và viền thẻ đổi khi breach; bật "Chưa đo" để xem trạng thái unknown.

Tự xử lý

82%

Vi phạm chính sách

7 ngày qua · kênh Facebook

Guard state: "ok".

import { GuardedStat } from "@nexobox/ui";

<GuardedStat
  primary={{ label: "Tự xử lý", value: "82%", metricId: "M-AUTO-01" }}
  guard={{ label: "Vi phạm chính sách", value: "0", metricId: "M-GUARD-07", state: "ok" }}
  caption="7 ngày qua · kênh Facebook"
  showIds={false}
  tone="brand"
/>

Bài toán

Một con số cải thiện đứng một mình luôn trông tốt. Chủ shop cần thấy cái giá của nó trong cùng một ánh nhìn, không phải ở thẻ thứ tư cuối hàng — luật trong outcome-map.md và operating-model.md §6.

Khi nào sử dụng

Nên dùng

Cột Đánh giá của Hồ sơ nhân viên; dải đầu trang Họp 1:1; Tổng quan khi hiển thị theo nhân viên.

Khi nào không dùng

Tránh dùng

Không dùng cho	Dùng thay
Một con số không có vế canh gác	StatCard
Biểu đồ theo thời gian	Không có trong corpus

Dựng từ

Primitive tầng 1	Vai trong composite
Card	Khung, viền, bán kính, đệm; viền đổi màu khi breach
Separator	Vạch dọc cao 70% thẻ, ngăn primary và guard
Badge	Nhãn metric id, chỉ hiện khi showIds

Anatomy

#	Phần	Ghi chú
1	Primary	Nhãn 12px muted, giá trị 28px semibold, màu text-primary
2	Divider	Separator dọc, cao 70% thẻ
3	Guard	Cùng cấu trúc, giá trị 20px; màu theo guard state
4	Caption	Một dòng dưới cả hai: phạm vi và kỳ
5	Unknown	Khi `value === null`, in "—" và caption đổi thành "Chưa đo", không bao giờ in 0 thay cho không biết

Variants

tone="ai" bọc cả thẻ trong data-nexi-v2, overlay Nexi Lens V2 như StatCard theo DS-002, cho metric do Nexi tạo ra.

States

State	Hành vi	Trợ năng
Measured	Như anatomy	`role="group"`, `aria-label` = "{primary.label} {value}, {guard.label} {value}"
Unknown	"—" và "Chưa đo"	`aria-label` nói "chưa đo"
Breach	Guard value danger, viền thẻ danger-border	`aria-live="polite"` khi state đổi sang breach

Bàn phím & trợ năng

Không tương tác, không nhận tiêu điểm.

Seam — host sở hữu gì

Composite không tính số, không quyết định ngưỡng guard state. Host truyền state đã tính từ ngưỡng nghiệp vụ của nó.

API & triển khai

Prop	Mặc định	Quy ước
primary	—	Bắt buộc. { label, value, metricId? }.
guard	—	Bắt buộc. primary + state: "ok" \| "watch" \| "breach".
caption	undefined	Bị thay bằng "Chưa đo" khi primary.value là null.
showIds	false	Hiện Badge metricId cạnh mỗi nhãn.
tone	"brand"	"brand" \| "ai".

Design tokens

--nf-semantic-text-primary (thay cho semantic-foreground), --nf-semantic-text-muted (thay cho foreground-muted), --nf-semantic-status-warning-foreground (thay cho semantic-warning), --nf-semantic-status-danger-foreground, --nf-semantic-status-danger-border (thay cho danger/danger-border), --nf-foundation-font-weight-semibold, --nf-foundation-space-3, --nf-foundation-space-4, --nf-foundation-typography-caption-*. Qua Card: --nf-component-card-*.

Do / Don't

Nên dùng

Luôn đặt cạnh guard cùng một chỉ số cải thiện. Giữ caption nói phạm vi và kỳ.

Tránh dùng

In 0 khi chưa đo được — phải in "—". Bỏ guard để chỉ còn một con số — đó là StatCard.