# FilterBar

Một hàng bộ lọc phía trên bảng, danh sách hoặc chart: một ô tìm kiếm, các control lọc bạn đặt vào, một button xóa mọi bộ lọc và số kết quả. Hàng xuống dòng khi không đủ rộng.

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

## Cách dùng

### Khi nào dùng

- Thu hẹp một bảng, danh sách hoặc chart bằng một ô tìm kiếm và vài bộ lọc trong một hàng.
- Hiện số kết quả khớp và cho phép xóa mọi bộ lọc cùng lúc.

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

- Tìm trong toàn bộ ứng dụng hoặc chạy lệnh. Dùng Command.
- Điền một form để gửi. Dùng Field.
- Chuyển giữa các view của cùng nội dung. Dùng Tabs.

## Biến thể

### size

Chiều cao của ô tìm kiếm và button xóa. Cho mọi control lọc trong thanh cùng size: sm phía trên bảng dày, md theo mặc định.

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

## Ví dụ

### Đơn hàng

```tsx
<FilterBar label="Lọc đơn hàng" activeCount={1} onClear={clearFilters} resultText="24 đơn hàng" className="w-full">
  <FilterBarSearch label="Tìm kiếm đơn hàng" placeholder="Tìm kiếm đơn hàng" />
  <Select defaultValue="paid">
    <SelectTrigger aria-label="Trạng thái" className="w-36">
      <SelectValue />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="all">Mọi trạng thái</SelectItem>
      <SelectItem value="paid">Đã thanh toán</SelectItem>
      <SelectItem value="refunded">Đã hoàn tiền</SelectItem>
    </SelectContent>
  </Select>
</FilterBar>
```

### Nhỏ, phía trên bảng

Mọi control lấy size của thanh, sm phía trên bảng dày.

```tsx
<FilterBar label="Lọc thành viên" size="sm" resultText="8 thành viên" className="w-full">
  <FilterBarSearch label="Tìm kiếm thành viên" placeholder="Tên hoặc email" />
  <ToggleGroup type="single" size="sm" variant="outline" defaultValue="all" aria-label="Vai trò" className="min-w-0 max-w-full flex-wrap gap-y-[max(var(--spacing-xs),calc(var(--size-target-min)-var(--size-element-sm)))]">
    <ToggleGroupItem value="all">Tất cả</ToggleGroupItem>
    <ToggleGroupItem value="admin">Quản trị viên</ToggleGroupItem>
    <ToggleGroupItem value="member">Thành viên</ToggleGroupItem>
  </ToggleGroup>
</FilterBar>
```

### Chỉ tìm kiếm

```tsx
<FilterBar label="Lọc dự án" className="w-full">
  <FilterBarSearch label="Tìm kiếm dự án" placeholder="Tìm kiếm dự án" />
</FilterBar>
```

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

### Nên

- Đặt ô tìm kiếm trước, rồi tới các bộ lọc được dùng nhiều nhất.
- Cho mọi control trong thanh cùng một size.
- Giữ kết quả trên màn hình khi chúng cập nhật: đánh dấu bảng là pending thay vì xóa trống.

### Không nên

- Đừng đặt các hành động thay đổi dữ liệu (Xóa, Xuất) trong thanh; đặt chúng trong toolbar của bảng.
- Đừng hiện button xóa khi chưa đặt bộ lọc nào.
- Đừng chỉ đặt tên ô tìm kiếm trong placeholder.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `label` (bắt buộc) | `string` |  |  | Trên FilterBar: tên của landmark tìm kiếm, như Lọc đơn hàng. Trên FilterBarSearch: tên của ô tìm kiếm, như Tìm kiếm đơn hàng. |
| `size` | `enum` | `sm`, `md`, `lg` | `md` | Chiều cao của ô tìm kiếm và button xóa. Cho mọi control lọc trong thanh cùng size: sm phía trên bảng dày, md theo mặc định. |
| `activeCount` | `number` |  | `0` | Số bộ lọc đang đặt. Lớn hơn 0, và có onClear, thì button xóa hiện ra. |
| `onClear` | `() => void` |  |  | Được gọi bởi button xóa. Đặt lại mọi bộ lọc và văn bản tìm kiếm. |
| `clearLabel` | `string` |  | `Clear filters` | Văn bản của button xóa. Tiếng Việt: Xóa bộ lọc. |
| `resultText` | `string` |  |  | Số kết quả, như 24 đơn hàng. Được thông báo nhẹ nhàng khi thay đổi. |

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `filters` | không | Children của FilterBar: FilterBarSearch và các control lọc, theo thứ tự đọc. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Landmark tìm kiếm: một hàng có thể xuống dòng. |
| `search` | Ô tìm kiếm. Giãn ra lấp đầy hàng, tối đa 320px từ sm trở lên. |
| `filters` | Các control lọc bất kỳ giữa ô tìm kiếm và button xóa: Select, Combobox, DatePicker, ToggleGroup. |
| `clear` | Button ghost xóa mọi bộ lọc, hiện khi activeCount lớn hơn 0. |
| `result` | Số kết quả ở cuối hàng. |

## Khả năng truy cập

Role: `search`

| Phím | Hành động |
| --- | --- |
| `Tab` | Chuyển qua ô tìm kiếm, từng control lọc, rồi tới button xóa. |
| `Escape` | Trong ô tìm kiếm, xóa văn bản (hành vi có sẵn của ô tìm kiếm trong trình duyệt). |

- Một landmark tìm kiếm được đặt tên bằng label, như EN `Filter orders`.
- Ô tìm kiếm được đặt tên bằng label của nó, không phải placeholder, và có một icon tìm kiếm để trang trí.
- Văn bản kết quả là một status nhẹ nhàng, nên trình đọc màn hình đọc EN `24 orders` sau khi một bộ lọc thay đổi.
- Button xóa chỉ hiện khi có bộ lọc đang đặt; văn bản của nó nói việc nó làm (EN `Clear filters`, VI `Xóa bộ lọc`).

## Cài đặt

```bash
npx werewolf-ui add filter-bar
```

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.