# Link

Link điều hướng luôn có gạch chân, với mức nhấn default hoặc subtle. Render một anchor trực tiếp, hoặc dùng asChild để style một router adapter mà vẫn giữ hành vi link.

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

- Điều hướng tới một trang, tài nguyên hoặc mục từ văn bản.
- Đặt một đích có gạch chân bên trong một câu.

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

- Một hành động thay đổi trang hiện tại mà không điều hướng. Dùng Button.
- Một đường đi qua các trang cha. Dùng Breadcrumb.

## Biến thể

### variant

default dùng chữ accent; subtle dùng chữ secondary.

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

## Ví dụ

### Điều hướng inline

```tsx
<p className="text-sm text-text-primary">
  <span>Đọc </span>
  <Link href="#installation">installation guide</Link>
  <span> before creating your first theme.</span>
</p>
```

### Đích external

```tsx
<Link external href="https://example.com/guide" target="_blank" rel="help">Mở hướng dẫn</Link>
```

### Link ghép

Một phần tử con duy nhất cung cấp đích. Dùng cùng cách ghép với router adapter của ứng dụng.

```tsx
<Link asChild variant="subtle">
  <a href="#project">Xem dự án</a>
</Link>
```

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

### Nên

- Dùng văn bản đích rõ nghĩa.
- Dùng asChild cho router adapter có prop đích riêng.
- Để việc mở tab mới là một lựa chọn rõ ràng bằng target="_blank".

### Không nên

- Đừng dùng Link cho hành động không điều hướng; dùng Button.
- Đừng dùng external thay cho target.
- Đừng lồng các anchor.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `variant` | `enum` | `default`, `subtle` | `default` | default dùng chữ accent; subtle dùng chữ secondary. |
| `external` | `boolean` |  | `false` | Thêm icon external-link trang trí. Không đổi target. |
| `asChild` | `boolean` |  | `false` | Style một link con duy nhất hoặc router adapter, không lồng anchor. |
| `href` | `string` |  |  | Đích cho anchor gốc. Router adapter con có thể tự cung cấp đích. |
| `target` | `string` |  |  | target điều hướng gốc. _blank gộp noopener và noreferrer vào rel. |
| `rel` | `string` |  |  | Các giá trị relationship. Giá trị hiện có được giữ khi thêm giá trị an toàn cho _blank. |

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `children` | có | Tên đích nhìn thấy, hoặc link con duy nhất khi asChild là true. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Anchor hoặc link do phía gọi cung cấp, có gạch chân và focus bàn phím nhìn thấy. |
| `icon` | Icon external-link trang trí, chỉ có khi external là true. |

## Khả năng truy cập

Role: `link`

| Phím | Hành động |
| --- | --- |
| `Tab` | Focus vào link. |
| `Enter` | Đi theo link đang focus. |

- Cả hai variant giữ gạch chân để link phân biệt được mà không chỉ dựa vào màu.
- Icon external mang tính trang trí và không đổi accessible name.
- external không buộc mở tab mới. target="_blank" rõ ràng thì thêm noopener noreferrer mà không bỏ các giá trị rel hiện có.
- asChild giữ đích của phần tử con, thuộc tính gốc, event handler và ref.

## Cài đặt

```bash
npx werewolf-ui add link
```

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.