Component / 051 / NEXOFRAME

ActivityList

Mẫu chuẩn

Một danh sách có thứ tự gồm các hoạt động: ai (avatar và tên), làm gì (một câu), khi nào, và trạng thái. Người dùng có thể chọn một mục; composite báo mục đó qua một callback onItemSelect.

Composite tầng 2Dựng từ Avatar + StatusDotNgữ nghĩa <ol>1 callback onItemSelect

Playground

Bật hoặc tắt onItemSelect, và cắt danh sách bằng limit, để xem dòng đổi từ tĩnh sang một nút phủ cả dòng.

Chưa chọn mục nào. Bấm một dòng. Đang hiện 3/3 mục.

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

<ActivityList
  aria-label="Công việc đang diễn ra"
  items={items}
  onItemSelect={(id) => takeover(id)}
/>

Bài toán

"Từ bản nháp đến kết quả: luôn biết ai đang phụ trách và bước tiếp theo." Người quản lý cần quét nhanh hàng chục hoạt động, mỗi dòng trả lời ai, việc gì, lúc nào, tới đâu rồi. Avatar và StatusDot là hai mảnh, nhưng thứ tự đọc của một dòng, cách nhấn vào một dòng và ngữ nghĩa danh sách có thứ tự không thuộc primitive nào.

Khi nào sử dụng

Nên dùng

Dòng thời gian các việc do người hoặc Human AI làm. Khi mỗi mục có một người phụ trách và một trạng thái.

Khi nào không dùng

Tránh dùng

Không dùng cho	Dùng thay
Dữ liệu cần sắp xếp theo cột	Table
Tin nhắn hội thoại	MessageBubble
Danh sách lựa chọn	RadioGroup, CheckboxCardGroup

Dựng từ

Primitive tầng 1	Vai trong composite
Avatar (`size="sm"`), AvatarFallback	Người phụ trách.
StatusDot	Trạng thái của mục, có nhãn chữ.

ActivityList thêm gì
Ngữ nghĩa `<ol>`: thứ tự thời gian là thông tin
Một dòng nhấn được (nút phủ cả dòng) khi có `onItemSelect`
Kẻ `border-divider` giữa các dòng
`limit`: cắt danh sách, host tự quyết lối "xem tất cả"

Anatomy

#	Phần	Ghi chú
1	Avatar	`size="sm"`, bên trái. Chữ viết tắt khi không có ảnh.
2	Tên và giờ	Tên `text-primary`, giờ `text-muted` căn phải cùng hàng.
3	Câu tóm tắt	`text-secondary`, một câu nói việc gì.
4	StatusDot	`status` và `statusLabel`. Màu không thay nhãn chữ.
5	Kẻ phân dòng	`border-divider` dưới mỗi dòng, trừ dòng cuối.

Variants

Không có prop variant. Trạng thái của từng mục do StatusDot mang, qua status và statusLabel của mỗi phần tử items.

States

Trạng thái	Biểu hiện
Có mục	Danh sách
Rỗng	Host render Empty. Composite không tự vẽ trạng thái rỗng
Dòng hover, focus	Khi có `onItemSelect`: nền `surface-hover`, vòng focus trên nút của dòng

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

Tab qua từng dòng, Enter / Space chọn -- mỗi dòng là một <button> khi có onItemSelect, không có thì dòng không nhận tiêu điểm.

Seam — host sở hữu gì

Composite không lọc, không sắp xếp, không định dạng thời gian, không điều hướng.

Host sở hữu	Cấp qua
Các mục đã lọc, đã định dạng	`items`
Chọn một mục dẫn tới đâu	`onItemSelect`

API & triển khai

Prop	Mặc định	Quy ước
items	—	Bắt buộc. ReadonlyArray<{ id; actor: { name; initials; imageSrc? }; summary; time; status: StatusDotVariant; statusLabel }>.
limit	undefined	Cắt danh sách.
onItemSelect	undefined	(id: string) => void. Có thì mỗi dòng nhấn được.
aria-label	—	Bắt buộc.

Design tokens

--nf-semantic-border-divider, --nf-semantic-surface-hover, --nf-semantic-text-primary, --nf-semantic-text-secondary, --nf-semantic-text-muted, --nf-foundation-typography-ui-*, --nf-foundation-typography-caption-*, --nf-foundation-space-2, --nf-foundation-space-3, --nf-component-focus-*. Qua Avatar và StatusDot: token của hai primitive đó.

Do / Don't

Nên dùng

Câu tóm tắt nói việc: "Soạn phản hồi cho chị Lan". Thời gian tương đối do host định dạng. statusLabel bằng chữ.

Tránh dùng

"Hoạt động số 482". Để composite gọi new Date(). Chỉ màu chấm.