# Tooltip

Gợi ý chữ ngắn cho phần tử nó bọc, hiện khi hover và khi focus bằng bàn phím. Surface inverse, ngược với mode hiện tại (light trong dark mode, dark trong light mode), với bóng medium và chữ 14px. Chỉ chữ: mọi thứ người dùng tác động thuộc về popover hoặc dialog.

**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

- Nêu icon button làm gì cho người dùng nhìn được, cùng từ với aria-label của nó.
- Hiện một chi tiết một số người dùng muốn nhưng không ai cần, chẳng hạn ngày đầy đủ sau 2 giờ trước.

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

- Mọi thứ người dùng phải đọc để xong một việc. Viết trên trang, hoặc trong description của một Field.
- Link, button hoặc control khác bên trong gợi ý. Dùng Dialog cho mọi thứ người dùng tác động.
- Tên duy nhất của icon button. Cũng đặt aria-label cho button.

## Biến thể

### side

Phía của trigger mà tooltip mở. Nó lật khi không đủ chỗ.

Giá trị: `top`, `right`, `bottom`, `left`. Mặc định: `top`.

### align

Căn dọc theo mép của trigger.

Giá trị: `start`, `center`, `end`. Mặc định: `center`.

## Ví dụ

### Mặc định

```tsx
<Tooltip content="Copy liên kết">
  <Button variant="secondary" iconOnly aria-label="Copy liên kết">
    <IconLink size={16} />
  </Button>
</Tooltip>
```

### Chi tiết thêm

Ngày đầy đủ sau một ngày tương đối, cho số ít người dùng muốn xem.

```tsx
<Tooltip content="6 tháng 10 năm 2026, 14:32" side="bottom">
  <Button variant="ghost" size="sm">Đã sửa 2 giờ trước</Button>
</Tooltip>
```

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

### Nên

- Nêu icon button làm gì, cùng từ với aria-label của nó.
- Thêm một thông tin người dùng có thể muốn nhưng không cần: ngày đầy đủ sau một ngày tương đối, một phím tắt.
- Giữ trong vài từ trên một dòng.
- Bọc các tooltip nằm cạnh nhau, chẳng hạn các button của một toolbar, trong TooltipGroup: khi một tooltip đã hiện, tooltip tiếp theo mở ngay, không delay và không fade.

### Không nên

- Đừng đặt link, button hoặc control khác trong tooltip.
- Đừng dùng tooltip làm tên duy nhất của icon button.
- Đừng đặt thứ người dùng cần để xong một việc chỉ trong tooltip.
- Đừng bọc phần tử không nhận focus, chẳng hạn chữ thuần hoặc button disabled.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `content` (bắt buộc) | `node` |  |  | Gợi ý: vài từ chữ thuần, sentence case, không dấu chấm khi là cụm. Sao chép liên kết, Đã lưu trữ 3 ngày trước. |
| `side` | `enum` | `top`, `right`, `bottom`, `left` | `top` | Phía của trigger mà tooltip mở. Nó lật khi không đủ chỗ. |
| `align` | `enum` | `start`, `center`, `end` | `center` | Căn dọc theo mép của trigger. |
| `sideOffset` | `number` |  | `4` | Khoảng cách giữa trigger và tooltip, tính bằng px; 4 khớp spacing-xs. |
| `delayDuration` | `number` |  | `200` | Thời gian chờ, tính bằng ms, trước khi hover mở tooltip. Focus mở ngay. Trong TooltipGroup, delay của nhóm được dùng trừ khi prop này được đặt. |
| `disabled` | `boolean` |  | `false` | Render trigger mà không có tooltip. |
| `open` | `boolean` |  |  | Trạng thái mở controlled, cho một tour hoặc một test. Đi cùng onOpenChange. |
| `defaultOpen` | `boolean` |  |  | Mở ở lần render đầu, khi bạn không control nó. |
| `onOpenChange` | `function` |  |  | Được gọi với true hoặc false khi hover, focus hoặc Escape mở hoặc đóng tooltip. |

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `trigger` | có | Một phần tử nhận focus: một Button, một link. Tooltip mô tả phần tử đó. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Tooltip: nền inverse (light trên trang dark, dark trên trang light) với chữ inverse, viền trong suốt (viền hiện ở mode forced-colors, mode này bỏ nền), radius-element, shadow-med, chữ 14px, rộng tối đa 320px. |
| `trigger` | Phần tử con mà tooltip mô tả. Nhận aria-describedby khi tooltip đang mở. |

## Khả năng truy cập

Role: `tooltip`

| Phím | Hành động |
| --- | --- |
| `Tab` | Focus trên trigger mở tooltip ngay. |
| `Escape` | Đóng tooltip; focus ở lại trên trigger. |

- Trigger phải nhận focus (button hoặc link), để người dùng bàn phím cũng nhận gợi ý. Chữ tooltip được đọc như mô tả của trigger.
- Tooltip không bao giờ tự đặt tên icon button: button vẫn cần aria-label.
- Hover không có trên màn hình cảm ứng. Đừng đặt thứ người dùng cần chỉ trong tooltip.
- Tooltip giữ mở khi con trỏ di lên nó, để đọc được ở mọi mức zoom.

## Cài đặt

```bash
npx werewolf-ui add tooltip
```

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.