# Navbar

Điều hướng trang ở đầu trang: thương hiệu, vài link và các hành động ở cuối hàng. Dưới md, các link chuyển vào một menu trượt vào từ cạnh bên. Chỉ có link: menu ứng dụng chứa lệnh là DropdownMenu, và ứng dụng có nhiều phần dùng Sidebar.

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

## Cách dùng

### Khi nào dùng

- Dẫn tới vài trang cấp cao nhất của một website hoặc ứng dụng nhỏ từ đầu mọi trang.
- Giữ thương hiệu, các link chính và một hành động đăng nhập hoặc đăng ký trong một hàng.

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

- Một ứng dụng có nhiều phần hoặc trang lồng nhau. Dùng Sidebar.
- Điều hướng cấp cao nhất trên ứng dụng ưu tiên điện thoại. Dùng BottomNav.
- Một menu các lệnh. Dùng DropdownMenu.

## Ví dụ

### Header của trang

```tsx
<Navbar label="Chính" className="w-full">
  <NavbarBrand href="#home">Acme</NavbarBrand>
  <NavbarLinks>
    <NavbarLink href="#overview" active>Tổng quan</NavbarLink>
    <NavbarLink href="#customers">Khách hàng</NavbarLink>
    <NavbarLink href="#reports">Báo cáo</NavbarLink>
  </NavbarLinks>
  <NavbarActions>
    <Button variant="ghost">Đăng nhập</Button>
    <Button>Bắt đầu</Button>
  </NavbarActions>
</Navbar>
```

### Link có icon

Icon đứng trước văn bản, 16px, và dùng màu accent ở trang hiện tại.

```tsx
<Navbar label="Chính" className="w-full">
  <NavbarBrand href="#home">Acme</NavbarBrand>
  <NavbarLinks>
    <NavbarLink href="#home" active>
      <IconHome size={16} />
      Trang chủ
    </NavbarLink>
    <NavbarLink href="#inbox">
      <IconInbox size={16} />
      Hộp thư đến
    </NavbarLink>
    <NavbarLink href="#settings">
      <IconSettings size={16} />
      Cài đặt
    </NavbarLink>
  </NavbarLinks>
</Navbar>
```

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

### Nên

- Giữ tối đa năm link, mỗi link một hoặc hai từ.
- Đánh dấu trang hiện tại bằng active, lấy từ router.
- Dùng sticky trên trang dài, để các link luôn trong tầm với.

### Không nên

- Đừng đặt lệnh (Lưu, Xóa) vào các link; link dẫn tới một nơi.
- Đừng dùng cả Navbar và Sidebar cho cùng các link.
- Đừng lồng menu trong các link; một trang có nhiều phần sâu cần Sidebar.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `label` (bắt buộc) | `string` |  |  | Đặt trên Navbar. Tên của landmark điều hướng, như Chính. |
| `menuLabel` | `string` |  | `Menu` | Đặt trên Navbar. Tên của button menu dưới md, và tiêu đề của menu nó mở. |
| `sticky` | `boolean` |  | `false` | Đặt trên Navbar. Dính ở đầu trang khi cuộn, trên một thanh kính mỏng, vẫn giữ đường kẻ bên dưới. |
| `active` | `boolean` |  | `false` | Đặt trên NavbarLink. Đánh dấu trang hiện tại: aria-current="page" và nền accent nhạt. |
| `asChild` | `boolean` |  | `false` | Đặt trên NavbarLink hoặc NavbarBrand. Áp dụng giao diện và hành vi link lên child duy nhất của nó, như một link của router. |
| `href` | `string` |  |  | Đặt trên NavbarLink hoặc NavbarBrand. Nơi link dẫn tới. |

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `brand` | không | Children của NavbarBrand: logo, tên hoặc cả hai. |
| `links` | không | Children của NavbarLinks: các item NavbarLink, viết một lần cho cả hàng và menu. |
| `actions` | không | Children của NavbarActions: một hoặc hai Button. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | nav: một hàng, có đường kẻ bên dưới. |
| `brand` | Link về trang chủ: logo, tên hoặc cả hai. |
| `list` | ul chứa các link. Từ md trở lên nằm sau thương hiệu; dưới md chuyển vào menu thành một cột. |
| `link` | Một link: văn bản và một icon 16px tùy chọn, trang hiện tại trên nền accent nhạt. |
| `icon` | Icon tùy chọn trong một link. |
| `menuButton` | Button icon ghost mở menu dưới md. |
| `actions` | Các button ở cuối hàng, như Đăng nhập. |

## Khả năng truy cập

Role: `navigation`

| Phím | Hành động |
| --- | --- |
| `Tab` | Chuyển qua thương hiệu, các link (hoặc button menu dưới md) và các hành động. |
| `Enter` | Đi theo link đang focus, hoặc mở menu từ button menu. |
| `Escape` | Đóng menu và trả focus về button menu. |

- Một landmark điều hướng được đặt tên bằng label, như EN `Main`. Đặt tên khác với mọi nav khác trên trang.
- Các link là một danh sách. Link của trang hiện tại có aria-current="page" và đặt data-current.
- Dưới md, button menu được đặt tên bằng menuLabel (EN `Menu`, VI `Trình đơn`). Menu là một dialog có tiêu đề bằng cùng văn bản, giữ focus bên trong khi mở.
- Đi theo một link từ menu sẽ đóng menu.

## Cài đặt

```bash
npx werewolf-ui add navbar
```

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.