Component / 056 / NEXOFRAME

CheckboxCardGroup

Mẫu chuẩn

Một nhóm lựa chọn không loại trừ nhau, mỗi lựa chọn là một thẻ có checkbox, tiêu đề và mô tả hoặc phần phụ tuỳ chọn. Nó báo một mảng các giá trị đã chọn qua một callback. Dựng trên Checkbox và Card. Là cặp song sinh của ChoiceCardGroup.

Composite tầng 2Dựng từ Checkbox + CardGiá trị là mảng2–8 lựa chọn

Playground

Chọn nhiều thẻ. Bật "Lỗi" rồi bỏ chọn hết để xem dòng lỗi của nhóm.

Nhiệm vụ

Soạn phản hồi khách hàng

Nháp trả lời cho tin nhắn đến.

Ghi nhận nhu cầu mua

Gắn thẻ hội thoại có ý định mua.

Định tuyến hội thoại

Chuyển cho đúng người phụ trách.

Đã chọn 1 nhiệm vụ.

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

const [value, setValue] = useState<string[]>(["reply"]);

<CheckboxCardGroup
  legend="Nhiệm vụ"
  options={[
    { value: "reply", title: "Soạn phản hồi khách hàng", description: "Nháp trả lời cho tin nhắn đến." },
    { value: "log-demand", title: "Ghi nhận nhu cầu mua", description: "Gắn thẻ hội thoại có ý định mua." },
  ]}
  value={value}
  onValueChange={setValue}
  layout="grid"
/>

Bài toán

Khi tuyển một Human AI, người quản lý chọn vài nhiệm vụ trong một danh sách, và vài kênh trong số kênh đã kết nối. Mỗi lựa chọn cần một dòng mô tả, hoặc dấu kênh. Một chuỗi Checkbox + Label không có chỗ cho mô tả, và vùng nhấn chỉ là ô vuông nhỏ.

Khi nào sử dụng

Nên dùng

Chọn một tập con trong 2–8 lựa chọn có mô tả. Khi cần một số tối thiểu (ví dụ "chọn ít nhất một nhiệm vụ"): host kiểm và hiện lỗi.

Khi nào không dùng

Tránh dùng

Không dùng cho	Dùng thay
Chọn một	ChoiceCardGroup
Một ô xác nhận khoá hành động	AcknowledgeCheckbox
Danh sách dài, nhãn ngắn	Checkbox + Label trong `fieldset`

Dựng từ

Primitive tầng 1	Vai trong composite
Checkbox	Ô chọn của mỗi thẻ (Radix)
Card	Khung của mỗi lựa chọn

CheckboxCardGroup thêm gì
`fieldset` + `legend`, giá trị là mảng
Cả thẻ là vùng nhấn; trạng thái chọn hiện trên viền và nền thẻ
Slot `adornment` cho mỗi lựa chọn, ví dụ `ChannelMark`
Chỗ hiện lỗi của nhóm, nối qua `aria-describedby`

Anatomy

#	Phần	Ghi chú
1	Legend	`fieldset` + `legend`, tên nhóm
2	Checkbox	Đầu mỗi thẻ
3	Tiêu đề / mô tả / adornment	Thân thẻ, adornment tuỳ chọn ở cuối
4	Lỗi nhóm	`error`, dưới lưới thẻ

States

Trạng thái	Biểu hiện
Chọn / không chọn	`data-state` của Checkbox; thẻ dùng viền `action-selected-foreground` và nền `action-selected-background` khi chọn
Hover, focus	Như ChoiceCardGroup
Disabled (một lựa chọn)	Thẻ mờ; ví dụ kênh chưa kết nối
Lỗi của nhóm	`error` có giá trị: dòng lỗi dưới nhóm, màu `status-danger-foreground`

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

Tab qua từng ô -- Checkbox.

Space bật/tắt -- Checkbox (Radix).

Nhấn vào thẻ -- composite: label bọc thẻ.

Seam — host sở hữu gì

Composite không kiểm số tối thiểu và không tự sinh câu lỗi. Host tính lỗi và truyền error.

API & triển khai

Prop	Mặc định	Quy ước
legend	—	Bắt buộc.
options	—	Bắt buộc.
value	—	Bắt buộc.
onValueChange	—	Bắt buộc. Giữ thứ tự của options.
error	undefined	—
layout	"grid"	"grid" \| "stack".

Design tokens

Như ChoiceCardGroup: Interaction Blue cho trạng thái chọn, border-control cho viền nghỉ và border-strong cho hover. Cộng --nf-semantic-status-danger-foreground cho dòng lỗi. Qua Card và Checkbox: token của hai primitive đó.

Do / Don't

Nên dùng

Vô hiệu kèm lý do: "Chưa kết nối". Lỗi nói cách sửa: "Hãy chọn ít nhất một nhiệm vụ." Trả mảng theo thứ tự options.

Tránh dùng

Ẩn lựa chọn không dùng được. Câu lỗi kiểu "Không hợp lệ". Trả mảng theo thứ tự người dùng bấm.