# EmptyState

Section có tên cho một kết quả thành công nhưng trống. Nó hiện title cùng description tùy chọn, icon trang trí và hành động do bên gọi cung cấp. Ghép nó trong một vùng chứa sẵn có.

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

## Cách dùng

### Khi nào dùng

- Giải thích vì sao một màn hình thành công chưa có nội dung và đưa hành động đầu tiên của nó.
- Giải thích rằng bộ lọc không có kết quả khớp và đưa cách để chỉnh chúng.

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

- Nội dung vẫn đang tải. Dùng Skeleton hoặc Spinner.
- Một thao tác thất bại. Dùng Alert.
- Một bảng không có hàng. Dùng Table với nội dung trống của nó.

## Ví dụ

### Lần dùng đầu

```tsx
<EmptyState title="Chưa có dự án" description="Tạo một dự án để giữ ý tưởng và tệp của bạn cùng một chỗ." icon={<IconInbox size={20} />} action={<Button>Tạo dự án</Button>} />
```

### Kết quả đã lọc

```tsx
<EmptyState title="Không có dự án phù hợp" description="Thử tìm kiếm khác hoặc xóa bộ lọc để xem tất cả dự án." icon={<IconSearch size={20} />} action={<Link href="#all-projects">Xem tất cả dự án</Link>} />
```

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

### Nên

- Giải thích vì sao không có nội dung và đưa một bước tiếp theo hữu ích.
- Dùng thông báo lần dùng đầu khi chưa có nội dung nào, và thông báo khác khi bộ lọc che nội dung.
- Ghép bên trong một section của trang đã có, hoặc trong Card.

### Không nên

- Đừng dùng trạng thái trống cho lúc đang tải hoặc khi có lỗi.
- Đừng thêm viền card thứ hai quanh component.
- Đừng thông báo các section trống tĩnh như live region.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `title` (bắt buộc) | `node` |  |  | Tiêu đề ngắn, đặt tên cho kết quả trống. |
| `description` | `node` |  |  | Lời giải thích hoặc bước tiếp theo cho kết quả trống. |
| `icon` | `node` |  |  | Icon trang trí do bên gọi cung cấp. |
| `action` | `node` |  |  | Hành động do bên gọi cung cấp, giúp người dùng đi tiếp. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Section có tên, căn giữa, dùng khoảng cách của token, không có viền card. |
| `title` | Tiêu đề đặt tên cho section theo mặc định. |
| `description` | Chữ phụ tùy chọn, giải thích vì sao kết quả trống. |
| `icon` | Icon trang trí tùy chọn, bằng màu icon phụ. |
| `actions` | Hành động do bên gọi cung cấp, chẳng hạn Button hoặc Link. |

## Khả năng truy cập

Role: `region`

- title đặt tên cho section, trừ khi aria-label hoặc aria-labelledby đưa một tên khác.
- Không thêm live region theo mặc định. Bên gọi có thể đặt role="status" khi kết quả đổi.
- Icon là trang trí. Title và description giải thích kết quả trống.

## Cài đặt

```bash
npx werewolf-ui add empty-state
```

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.