# GroupAvatar

Một vòng tròn cỡ Avatar cho một nhóm, chia thành các ô thay vì chồng lên nhau: một thành viên lấp đầy, hai thành viên chia đôi, ba thành viên chiếm một nửa và hai phần tư, bốn trở lên chiếm bốn phần tư với +N cho phần còn lại. Dùng cho nhóm chat hoặc một đội.

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

## Cách dùng

### Khi nào dùng

- Đại diện cho nhóm chat hay một đội bằng một vòng tròn, như trong ConversationList.
- Hiện các thành viên của nhóm trong chỗ của một Avatar.

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

- Hiện nhiều người cạnh nhau. Dùng AvatarStack.
- Một người. Dùng Avatar.
- Một workspace hay thương hiệu có logo riêng. Dùng Avatar với src.

## Biến thể

### size

sm 24px, md 32px, lg 40px, như Avatar.

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

## Ví dụ

### Các cỡ nhóm

Hai, ba, bốn và nhiều thành viên hơn.

```tsx
<div className="flex items-center gap-md">
  <GroupAvatar alt="Linh và An" members={pairMembers} />
  <GroupAvatar alt="Nhóm ra mắt" members={trioMembers} />
  <GroupAvatar alt="Nhóm thiết kế" members={designTeam} />
  <GroupAvatar alt="Công ty" members={companyMembers} />
</div>
```

### Cạnh tên

Khi tên nhóm được viết cạnh nó, alt để trống.

```tsx
<div className="flex items-center gap-sm">
  <GroupAvatar alt="" size="lg" members={designTeam} />
  <span className="text-sm font-medium text-text-primary">Nhóm thiết kế</span>
</div>
```

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

### Nên

- Dùng lg cạnh hai dòng chữ, như trong ConversationList.
- Truyền ảnh khi có; chữ cái là dự phòng.
- Giữ thứ tự thành viên ổn định, để vòng tròn không đổi giữa các lần xem.

### Không nên

- Đừng dùng nó cho danh sách người cần phân biệt; dùng AvatarStack.
- Đừng dùng sm cho nhóm từ ba người trở lên khi chữ cái quan trọng; các ô quá nhỏ.
- Đừng đặt chấm trạng thái lên một ô; đặt nó lên vòng tròn.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `members` (bắt buộc) | `{ name: string; src?: string; initials?: string; color?: "gray" \| "red" \| "orange" \| "yellow" \| "green" \| "teal" \| "blue" \| "purple" \| "pink" }[]` |  |  | Các thành viên được hiện, theo thứ tự. Hiện tối đa bốn; quá bốn thì hiện ba và ô thứ tư đếm phần còn lại. color mặc định là blue, green, purple, orange. |
| `alt` (bắt buộc) | `string` |  |  | Tên của nhóm, như Nhóm thiết kế. Truyền chuỗi rỗng khi tên đã được viết cạnh nó. |
| `size` | `enum` | `sm`, `md`, `lg` | `md` | sm 24px, md 32px, lg 40px, như Avatar. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Vòng tròn: 24, 32 hoặc 40px, cắt tròn, chứa lưới các ô với khe 2px. |
| `tile` | Một thành viên: ảnh của họ, hoặc chữ cái đầu của tên viết tắt hay tên trên cặp màu dịu. Trong vòng 24px, một ô bị chia chỉ hiện màu. |
| `more` | Ô xám với +N (9+ khi trên 9) khi nhóm có hơn bốn thành viên. |

## Khả năng truy cập

Role: `img`

- alt đặt tên nhóm (EN `Design team`) trên vòng tròn, một hình ảnh cho trình đọc màn hình. Truyền alt="" khi tên đã được viết cạnh nó.
- Các ô, chữ cái và ảnh của chúng bị ẩn với trình đọc màn hình; tên nhóm mới là thứ được đọc.
- Màu chỉ để trang trí, như ở Avatar.

## Cài đặt

```bash
npx werewolf-ui add group-avatar
```

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.