# Kbd

Gợi ý phím tắt được render thành phần tử kbd gốc. KbdGroup xếp các phím riêng trong một chuỗi phím tắt. Các component này hiện phím tắt mà không đăng ký handler bàn phím.

**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 một phím tắt bên cạnh hành động mà phím đó kích hoạt.
- Mô tả một chuỗi phím trong hướng dẫn.

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

- Một phím hoặc hành động tương tác. Dùng Button.
- Đăng ký một phím tắt. Thêm handler trong ứng dụng của bạn.

## Biến thể

### size

Gợi ý phím tắt gọn: sm cao 16px và md cao 20px. Cả hai dùng chữ UI 12px.

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

## Ví dụ

### Chuỗi phím tắt

```tsx
<KbdGroup aria-label="Command K">
  <Kbd aria-label="Command">⌘</Kbd>
  <Kbd>K</Kbd>
</KbdGroup>
```

### Bên cạnh một hành động

```tsx
<Button variant="secondary">
  <span>Mở tìm kiếm</span>
  <KbdGroup aria-label="Control K">
    <Kbd size="sm" aria-label="Control">Ctrl</Kbd>
    <Kbd size="sm">K</Kbd>
  </KbdGroup>
</Button>
```

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

### Nên

- Render mỗi phím trong một Kbd riêng và ghép các phím bằng KbdGroup.
- Dùng tên đọc được cho ký hiệu mà công nghệ hỗ trợ có thể phát âm mơ hồ.

### Không nên

- Đừng làm Kbd click được hoặc focus được.
- Đừng hiện một phím tắt mà ứng dụng không hỗ trợ.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `size` | `enum` | `sm`, `md` | `md` | Gợi ý phím tắt gọn: sm cao 16px và md cao 20px. Cả hai dùng chữ UI 12px. |

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `children` | có | Nhãn phím hoặc ký hiệu phím tắt. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | kbd gốc, gọn, với chữ UI, nền surface, viền neutral và chữ secondary. Nhỏ cao 16px, vừa cao 20px; mỗi cái có cùng chiều rộng tối thiểu và nới ra cho tên phím dài hơn. |
| `group` | Wrapper KbdGroup inline, với khoảng cách theo token giữa các phím. |

## Khả năng truy cập

Role: `none`

- Kbd không focus được và không nhận nhập từ bàn phím.
- Đặt tên đọc được cho ký hiệu phím tắt, chẳng hạn aria-label="Command" cho ⌘.
- Phím tắt được hiện chỉ là gợi ý. Việc xử lý phím tắt thuộc về ứng dụng.

## Cài đặt

```bash
npx werewolf-ui add kbd
```

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.