# Toggle

Button bật hoặc tắt một lựa chọn định dạng hoặc chế độ view. Trạng thái được chọn dùng nền accent mềm.

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

## Cách dùng

### Khi nào dùng

- Bật hoặc tắt một lựa chọn, chẳng hạn ghim một mục hoặc áp dụng nhấn mạnh.
- Giữ một hành động toolbar ở trạng thái chọn cho đến khi người dùng tắt.

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

- Hành động không có trạng thái bật được giữ. Dùng Button.
- Cài đặt được submit trong form. Dùng Switch.
- Các lựa chọn liên quan. Dùng ToggleGroup.

## Biến thể

### variant

Trong suốt khi tắt, hoặc một surface có viền trung tính cho outline.

Giá trị: `default`, `outline`. Mặc định: `default`.

### size

Chiều cao control, cỡ chữ và icon, cùng các bước với Button: sm 28px, md 32px (mặc định), lg 36px, xl 44px với chuột; trên cảm ứng md là 36px, lg 44px và xl 48px. Control nhỏ vẫn giữ vùng nhấn tối thiểu.

Giá trị: `sm`, `md`, `lg`, `xl`. Mặc định: `md`.

## Ví dụ

### Định dạng

```tsx
<Toggle>Đậm</Toggle>
```

### Được chọn từ đầu

```tsx
<Toggle variant="outline" defaultPressed>Dạng xem lưới</Toggle>
```

### Chỉ icon

```tsx
<Toggle iconOnly aria-label="Đậm">
  <IconBold size={16} />
</Toggle>
```

### Lựa chọn vô hiệu

```tsx
<Toggle disabled defaultPressed>Định dạng đã khóa</Toggle>
```

### Icon kèm chữ

Icon và label ổn định ở cùng nhau khi lựa chọn đổi.

```tsx
<Toggle variant="outline" defaultPressed>
  <IconPin size={16} />
  Ghim mục
</Toggle>
```

### Trạng thái icon vô hiệu

```tsx
<Toggle iconOnly disabled aria-label="Đậm">
  <IconBold size={16} />
</Toggle>
<Toggle iconOnly disabled defaultPressed aria-label="In nghiêng">
  <IconItalic size={16} />
</Toggle>
```

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

### Nên

- Dùng label ổn định, đặt tên cho lựa chọn.
- Dùng iconOnly với aria-label cho control định dạng gọn.

### Không nên

- Đừng dùng Toggle cho hành động không có trạng thái được giữ.
- Đừng dùng cho cài đặt có hiệu lực ngay; dùng Switch.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `variant` | `enum` | `default`, `outline` | `default` | Trong suốt khi tắt, hoặc một surface có viền trung tính cho outline. |
| `size` | `enum` | `sm`, `md`, `lg`, `xl` | `md` | Chiều cao control, cỡ chữ và icon, cùng các bước với Button: sm 28px, md 32px (mặc định), lg 36px, xl 44px với chuột; trên cảm ứng md là 36px, lg 44px và xl 48px. Control nhỏ vẫn giữ vùng nhấn tối thiểu. |
| `disabled` | `boolean` |  | `false` | Chặn focus và lựa chọn, và dùng màu disabled. |
| `iconOnly` | `boolean` |  | `false` | Làm button vuông. Button chỉ có icon cần aria-label. |
| `pressed` | `boolean` |  |  | Trạng thái bật hoặc tắt controlled. Đi cùng onPressedChange. |
| `defaultPressed` | `boolean` |  | `false` | Trạng thái ban đầu khi uncontrolled. |
| `onPressedChange` | `function` |  |  | Nhận trạng thái boolean được yêu cầu sau khi kích hoạt. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Toggle button, trong suốt theo mặc định hoặc surface có viền ở outline. Khi bật dùng cặp accent mềm. |
| `icon` | Icon trang trí tùy chọn, 16px ở sm, md và lg và 20px ở xl. |
| `hitArea` | Pseudo-element trong suốt kéo đích của button tới size-target-min. |

## Khả năng truy cập

Role: `button`

| Phím | Hành động |
| --- | --- |
| `Space, Enter` | Toggle trạng thái pressed. |
| `Tab` | Chuyển focus tới control tiếp theo. |

- Children dạng chữ cung cấp tên truy cập. iconOnly cần aria-label.
- aria-pressed lộ trạng thái bật hoặc tắt. Giữ label ổn định khi trạng thái đổi.
- Button mặc định type="button" và không submit form của nó.
- Truyền size và weight cho mọi icon. Dùng regular khi tắt và có thể dùng fill khi bật.

## Cài đặt

```bash
npx werewolf-ui add toggle
```

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.