# Checklist

Danh sách việc có tiêu đề và thanh tiến độ, như các bước bắt đầu trên dashboard. Mỗi việc có một checkbox, hoặc một icon trạng thái khi ứng dụng quyết định việc nào đã xong. Dùng Stepper cho một luồng người dùng phải đi theo thứ tự.

**Phụ thuộc:** npm: 1 trực tiếp, 5 tổng; registry: 4 trực tiếp, 6 tổng.

## Cách dùng

### Khi nào dùng

- Hiện các việc cần làm để thiết lập workspace hoặc tài khoản, và số việc đã xong.
- Theo dõi một danh sách việc ngắn người dùng tự đánh dấu, như các bước kiểm tra trước khi ra mắt.

### Khi nào không dùng

- Dẫn qua các bước phải làm theo thứ tự. Dùng Stepper.
- Chọn nhiều lựa chọn trong một form. Dùng Checkbox.
- Hiện một thao tác đơn lẻ đã chạy được bao nhiêu. Dùng Progress.

## Biến thể

### headingLevel

Cấp heading của tiêu đề: thấp hơn một cấp so với heading chứa checklist.

Giá trị: `2`, `3`, `4`. Mặc định: `3`.

## Ví dụ

### Bắt đầu

```tsx
<Checklist title="Thiết lập không gian làm việc của bạn" description="Hoàn thành các việc này để tận dụng tối đa dashboard." items={setupTasks} defaultValue={setupDone} />
```

### Chỉ đọc, có action

Ứng dụng đánh dấu từng việc đã xong. Việc chưa xong hiện một action để bắt đầu.

```tsx
<Checklist readOnly title="Thiết lập không gian làm việc của bạn" items={setupTaskActions} value={setupDone} />
```

### Không có tiến độ

```tsx
<Checklist showProgress={false} title="Trước khi ra mắt" items={launchTasks} defaultValue={launchDone} />
```

## Nên và không nên

### Nên

- Giữ trong khoảng 3 đến 7 việc, mỗi việc là một cụm động từ ngắn.
- Dùng readOnly khi ứng dụng biết một việc đã xong, và cho mỗi việc chưa xong một action để bắt đầu.
- Ẩn checklist khi mọi việc đã xong, hoặc cho người dùng đóng nó.

### Không nên

- Đừng dùng cho các bước phải làm theo thứ tự. Dùng Stepper.
- Đừng dùng cho một tập lựa chọn. Dùng Checkbox trong Field.
- Đừng chuyển việc đã xong xuống cuối; danh sách giữ nguyên thứ tự.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `title` (bắt buộc) | `node` |  |  | Heading của checklist. |
| `description` | `string` |  |  | Văn bản tùy chọn dưới tiêu đề. |
| `items` (bắt buộc) | `{ id: string; label: string; description?: string; action?: React.ReactNode; disabled?: boolean }[]` |  |  | Các việc theo thứ tự. action hiện sau văn bản khi việc chưa xong. |
| `value` | `string[]` |  |  | Id của các việc đã xong, cho checklist được kiểm soát. |
| `defaultValue` | `string[]` |  |  | Id của các việc đã xong ở lần render đầu, cho checklist không kiểm soát. |
| `onValueChange` | `(value: string[]) => void` |  |  | Được gọi với các id đã xong, theo thứ tự item, khi một checkbox thay đổi. |
| `readOnly` | `boolean` |  | `false` | Ứng dụng quyết định khi nào một việc xong (đã có ảnh hồ sơ, một đồng đội đã tham gia). Các việc hiện icon trạng thái thay cho checkbox. |
| `showProgress` | `boolean` |  | `true` | Hiện văn bản tiến độ và thanh tiến độ trong header. |
| `progressText` | `(done: number, total: number) => string` |  |  | Văn bản trên thanh, cũng là tên của thanh. Mặc định EN `{done} of {total} done`, VI `Đã xong {done}/{total}`. |
| `headingLevel` | `enum` | `2`, `3`, `4` | `3` | Cấp heading của tiêu đề: thấp hơn một cấp so với heading chứa checklist. |
| `labels` | `{ done?: string; notDone?: string }` |  |  | Từ được đọc sau mỗi việc ở chế độ chỉ đọc. Mặc định: done, not done. Tiếng Việt: đã xong, chưa xong. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Section: header ở trên danh sách. |
| `header` | Tiêu đề, mô tả và thanh tiến độ. |
| `title` | Heading đặt tên cho checklist. |
| `description` | Văn bản tùy chọn dưới tiêu đề. |
| `list` | ul chứa các việc. |
| `item` | Một việc: control, label và mô tả, rồi một action tùy chọn ở cuối. Một đường kẻ tách nó khỏi việc phía trên. |
| `control` | Checkbox, hoặc icon trạng thái của việc chỉ đọc, trong một hộp cao một dòng. |
| `icon` | Icon trạng thái của việc chỉ đọc: vòng tròn nét đứt khi chưa xong, vòng tròn check đặc màu success khi đã xong. 16px. |
| `label` | Tên việc. Chuyển xuống màu chữ phụ khi đã xong. |
| `itemDescription` | Dòng phụ tùy chọn dưới tên việc. |
| `action` | Control tùy chọn sau văn bản, như một Button nhỏ. Chỉ hiện khi việc chưa xong. |

## Khả năng truy cập

Role: `region`

| Phím | Hành động |
| --- | --- |
| `Tab` | Chuyển tới checkbox của việc tiếp theo, rồi tới action của việc đó nếu có. |
| `Space` | Đánh dấu việc đang focus là đã xong hoặc chưa xong. |

- Một section được đặt tên bằng tiêu đề qua aria-labelledby, các việc nằm trong một danh sách.
- Mỗi checkbox được đặt tên bằng label của việc và được mô tả bằng mô tả của việc.
- Thanh tiến độ được đặt tên bằng văn bản tiến độ (EN `2 of 5 done`) và báo phần đã xong dưới dạng phần trăm.
- Việc chỉ đọc hiện một icon trạng thái bị ẩn với trình đọc màn hình; label kết thúc bằng từ trong labels (EN `done` hoặc `not done`, VI `đã xong` hoặc `chưa xong`).
- Việc đã xong giữ label và vị trí; chỉ màu chữ giảm xuống, nên danh sách không bị xê dịch.

## Cài đặt

```bash
npx werewolf-ui add checklist
```

Chạy `npx werewolf-ui init` một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem [Cài đặt](https://www.werewolf-ui.dev/vi/docs/installation.md) để biết yêu cầu và cách cài qua registry.