Component / 046 / NEXOFRAME

AcknowledgeCheckbox

Mẫu chuẩn

Một ô checkbox kèm câu cam kết, dùng để chặn một hành động có hệ quả cho tới khi người dùng xác nhận đã đọc. Nó báo một giá trị checked qua một callback.

Composite tầng 2Dựng từ Checkbox + LabelVùng nhấn phủ cả câu1 giá trị điều khiển

Playground

Đổi brand, theme, câu cam kết và disabled để xem cùng một AcknowledgeCheckbox thích ứng.

Tôi đã kiểm tra nội dung và người nhận. Chỉ thực hiện đề xuất này.

Chưa chọn. Bấm vào bất kỳ đâu trên hàng, không chỉ ô vuông.

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

const [checked, setChecked] = useState(false);

<AcknowledgeCheckbox checked={checked} onCheckedChange={setChecked}>
  Tôi đã kiểm tra nội dung và người nhận. Chỉ thực hiện đề xuất này.
</AcknowledgeCheckbox>

Bài toán

Trước khi gửi một tin nhắn thay mặt cửa hàng hay đăng một bài viết, người quản lý phải chủ động xác nhận rằng họ đã đọc đúng nội dung và đúng người nhận. Checkbox cộng Label ghép tay thì làm được, nhưng mỗi màn hình sẽ ghép một kiểu: vùng nhấn chỉ ở ô vuông, câu cam kết không gắn với ô, khoảng cách tuỳ ý. Composite này cố định cách ghép đó để mọi chỗ "xác nhận trước khi làm" đọc giống nhau.

Khi nào sử dụng

Nên dùng

Mở khoá một nút hành động trong cùng một khối, sau khi người dùng xác nhận. Câu cam kết ngôi thứ nhất, một câu.

Khi nào không dùng

Tránh dùng

Không dùng cho	Dùng thay
Một tuỳ chọn cài đặt bật/tắt	Switch
Một lựa chọn trong danh sách	Checkbox cộng Label, hoặc CheckboxCardGroup
Chấp nhận điều khoản khi đăng ký	Checkbox trong Field. Đó là một trường của biểu mẫu, không phải khoá của một hành động
Xác nhận một hành động phá huỷ	AlertDialog

Dựng từ

Primitive tầng 1	Vai trong composite
Checkbox	Ô vuông; hành vi và `data-state` từ Radix Checkbox.
Label	Câu cam kết, gắn với ô qua `htmlFor` / `useId`.

AcknowledgeCheckbox thêm gì
Vùng nhấn phủ cả hàng, không chỉ ô vuông
Đường kẻ `border-divider` phía trên, tách khỏi nội dung được xác nhận
`id` tự sinh bằng `useId`, không bắt người gọi truyền

Anatomy

Một hàng gồm ô vuông đứng đầu, câu cam kết theo sau, ngăn khỏi nội dung phía trên bằng đường kẻ border-divider. Ô vuông căn theo dòng chữ đầu. Câu chữ dùng kiểu ui, màu text-primary.

States

Trạng thái	Biểu hiện
Chưa chọn	Mặc định
Đã chọn	`data-state="checked"` của Radix
Hover	Nền hàng `surface-hover`
Focus	Vòng focus trên ô vuông (từ `Checkbox`)
Disabled	Khi hành động bị chặn vì lý do khác, ví dụ nhân sự đang tạm dừng. Câu lý do do host hiện ở phía trên

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

Tab tới ô -- từ Checkbox.

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

Nhấn vào câu chữ -- từ Label + htmlFor. Hành vi của nền tảng, composite không thêm phím nào.

Seam — host sở hữu gì

Composite không biết hành động nào đang bị khoá, không tự bật nút, không reset khi nội dung đổi. Không fetch, không router, không next (ADR-UI-003 clause 2).

Host sở hữu	Cấp qua
Giá trị `checked`	`checked` / `onCheckedChange`
Việc bật/tắt nút hành động theo giá trị đó	Host tự render nút, đọc `checked`
Việc bỏ chọn khi nội dung được xác nhận thay đổi	Host tự gọi `onCheckedChange(false)`

API & triển khai

Prop	Mặc định	Quy ước
checked	—	Bắt buộc. Composite có điều khiển.
onCheckedChange	—	Bắt buộc. (checked: boolean) => void. Nhận boolean, không nhận "indeterminate".
children	—	Bắt buộc. Câu cam kết.
disabled	false	—

Design tokens

--nf-semantic-border-divider, --nf-semantic-surface-hover, --nf-semantic-text-primary, --nf-foundation-typography-ui-*, --nf-foundation-space-3 (khoảng ô–chữ; đệm trên), --nf-component-checkbox-radius (qua Checkbox).

Do / Don't

Nên dùng

Bỏ chọn khi nội dung được xác nhận thay đổi. Câu cam kết nói rõ cái gì đã được kiểm tra. Dùng cho một hành động của khối chứa nó.

Tránh dùng

Giữ ô đã chọn sau khi người dùng sửa bản nháp — lời xác nhận cũ không còn đúng. "Tôi đồng ý". Một ô xác nhận khoá nhiều hành động ở nhiều nơi.