# Alert

Banner inline với title, body tùy chọn và action do người gọi cung cấp. Dùng info, success, warning hoặc danger để nói loại thông báo. Banner tĩnh là các section có tên; chọn status hoặc alert cho cập nhật động.

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

## Cách dùng

### Khi nào dùng

- Hiện thông báo thuộc trang hiện tại, chẳng hạn một cài đặt đã lưu hoặc một lần tải lên thất bại.
- Giải thích một tình trạng và đưa bước tiếp theo tùy chọn bên cạnh.

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

- Lựa chọn phá hủy cần xác nhận. Dùng AlertDialog.
- Thông báo ngắn biến mất sau một hành động. Dùng Toast.
- Kết quả thành công nhưng rỗng. Dùng EmptyState.

## Biến thể

### variant

Loại thông báo. Mỗi giá trị dùng cặp soft của status tương ứng: info, success, warning hoặc danger.

Giá trị: `info`, `success`, `warning`, `danger`. Mặc định: `info`.

## Ví dụ

### Hướng dẫn inline

```tsx
<Alert title="Không gian làm việc của bạn đã sẵn sàng">Mời một đồng đội để bắt đầu xem xét dự án cùng nhau.</Alert>
```

### Có action

```tsx
<Alert variant="warning" title="Dung lượng lưu trữ sắp đầy" action={<Link href="#storage">Quản lý lưu trữ</Link>}>Remove unused files before your next upload.</Alert>
```

### Cập nhật có thể bỏ qua

Phần tử cha gỡ banner khi onDismiss chạy. Cung cấp tên truy cập cụ thể cho button đóng.

```tsx
<Alert variant="success" title="Đã lưu thay đổi" role="status" dismissible dismissLabel="Dismiss saved changes message" onDismiss={dismissAlert}>Cài đặt dự án của bạn đã cập nhật.</Alert>
```

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

### Nên

- Viết title ngắn và giải thích bước tiếp theo trong body.
- Dùng action do người gọi cung cấp để giải quyết cảnh báo hoặc lỗi.
- Cung cấp dismissLabel và gỡ banner trong onDismiss khi cho phép bỏ qua.

### Không nên

- Đừng dùng Alert cho dialog xác nhận; dùng AlertDialog.
- Đừng thông báo mọi banner tĩnh như một alert.
- Đừng chỉ dựa vào icon hoặc màu để truyền thông báo.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `variant` | `enum` | `info`, `success`, `warning`, `danger` | `info` | Loại thông báo. Mỗi giá trị dùng cặp soft của status tương ứng: info, success, warning hoặc danger. |
| `title` (bắt buộc) | `node` |  |  | Heading ngắn đặt tên cho banner. |
| `icon` | `node` |  |  | Icon trang trí thay icon của variant. null ẩn icon. |
| `action` | `node` |  |  | Một action như Button hoặc Link, do người gọi cung cấp. |
| `dismissible` | `boolean` |  | `false` | Hiện button bỏ qua. true bắt buộc có dismissLabel và onDismiss. |
| `dismissLabel` | `string` |  |  | Tên truy cập của button bỏ qua, bắt buộc khi dismissible là true. |
| `onDismiss` | `function` |  |  | Được gọi khi button bỏ qua được kích hoạt. Phần tử cha gỡ banner. Bắt buộc khi dismissible là true. |

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `children` | không | Body của thông báo, tùy chọn. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Section có tên, với nền soft của status và viền, cùng chữ primary. |
| `icon` | Icon variant 16px để trang trí, theo màu status, trong hộp cao một dòng để thẳng hàng với dòng đầu của title. Được thay bằng icon hoặc ẩn bằng icon={null}. |
| `content` | Cột chứa title, body và các action tùy chọn. |
| `title` | Heading đặt tên cho section theo mặc định. |
| `body` | Body tùy chọn bằng chữ primary, giống title. |
| `actions` | Action do người gọi cung cấp, nằm dưới thông báo. |
| `close` | Button bỏ qua tùy chọn, được đặt tên bởi dismissLabel. |
| `hitArea` | Vùng chạm tối thiểu trong suốt quanh button bỏ qua. |

## Khả năng truy cập

Role: `region`

| Phím | Hành động |
| --- | --- |
| `Tab` | Focus action được cung cấp hoặc button bỏ qua. |
| `Enter / Space` | Kích hoạt button bỏ qua đang focus. |

- Title đặt tên cho section, trừ khi aria-label hoặc aria-labelledby cung cấp tên khác.
- Chỉ variant không tạo live region. Dùng role="status" cho cập nhật không khẩn hoặc role="alert" cho cập nhật khẩn.
- Icon chỉ để trang trí; title và body mang thông báo.
- Việc bỏ qua vẫn do phần tử cha điều khiển. Alert không tự ẩn.

## Cài đặt

```bash
npx werewolf-ui add alert
```

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.