# Metadata

Các cặp nhãn và giá trị chỉ đọc, mô tả một mục: trạng thái, người sở hữu, ngày, tag. Giá trị là một slot, nên nhận văn bản hoặc component bất kỳ (Badge, Avatar kèm tên, một link, một Button nhỏ). Horizontal đặt các nhãn trong một cột cạnh các giá trị; vertical đặt mỗi nhãn phía trên giá trị của nó.

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

- Hiện dữ kiện chỉ đọc về một mục, mỗi dữ kiện có tên: trạng thái, người sở hữu, ngày, tag, một ID.
- Một panel chi tiết cạnh nội dung chính, với tên ở một cột và các giá trị thẳng hàng bên cạnh.
- Một hàng dữ kiện chính, mỗi tên phía trên giá trị, chẳng hạn gói, số ghế và ngày gia hạn của một subscription.

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

- Giá trị người dùng sửa. Dùng Field, component này nối nhãn với control.
- Nhiều bản ghi dùng chung các tên, chẳng hạn danh sách dự án. Dùng Table, với các tên xuất hiện một lần ở header.
- Một trạng thái đứng một mình cạnh một mục, không có tên. Dùng Badge.

## Biến thể

### orientation

Trên Metadata, đặt cho mọi item. horizontal: các nhãn trong một cột cạnh các giá trị, cho một panel chi tiết. vertical: mỗi nhãn phía trên giá trị, cho một cột hẹp hoặc một hàng dữ kiện chính. Trên một MetadataItem, ghi đè cho item đó, chẳng hạn một mô tả dài dưới các hàng horizontal.

Giá trị: `horizontal`, `vertical`. Mặc định: `horizontal`.

## Ví dụ

### Mặc định

```tsx
<Metadata className="w-full max-w-sm">
  <MetadataItem label="Trạng thái">
    <Badge variant="success">Sẵn sàng</Badge>
  </MetadataItem>
  <MetadataItem label="Chủ sở hữu">
    <Avatar alt="" size="sm">AL</Avatar>
    Ada Lovelace
  </MetadataItem>
  <MetadataItem label="Đã tạo">6 thg 10, 2026</MetadataItem>
  <MetadataItem label="Thẻ">
    <Badge variant="blue">Thiết kế</Badge>
    <Badge variant="purple">Tokens</Badge>
  </MetadataItem>
</Metadata>
```

### Với icon

Icon không tự đặt tên gì, nên bị ẩn khỏi trình đọc màn hình. Mọi nhãn đều có một icon, hoặc không nhãn nào có.

```tsx
<Metadata className="w-full max-w-sm">
  <MetadataItem label="Trạng thái" leadingIcon={<IconCircleDashed size={16} />}>
    <Badge variant="warning">Đang xem xét</Badge>
  </MetadataItem>
  <MetadataItem label="Chủ sở hữu" leadingIcon={<IconUser size={16} />}>
    <Avatar alt="" size="sm">AL</Avatar>
    Ada Lovelace
  </MetadataItem>
  <MetadataItem label="Đến hạn" leadingIcon={<IconCalendar size={16} />}>Oct 20, 2026</MetadataItem>
  <MetadataItem label="Thẻ" leadingIcon={<IconTag size={16} />}>
    <Badge variant="blue">Thiết kế</Badge>
  </MetadataItem>
</Metadata>
```

### Dữ kiện chính trên một hàng

Các item vertical trên lưới ba cột: mỗi nhãn phía trên giá trị.

```tsx
<Metadata orientation="vertical" className="w-full max-w-lg grid-cols-3">
  <MetadataItem label="Gói">Pro</MetadataItem>
  <MetadataItem label="Chỗ">12 of 20</MetadataItem>
  <MetadataItem label="Gia hạn">1 thg 11, 2026</MetadataItem>
</Metadata>
```

### Một giá trị dài dưới các hàng

Một item vertical trong danh sách horizontal chiếm hết chiều rộng, cho giá trị cần chỗ.

```tsx
<Metadata className="w-full max-w-sm">
  <MetadataItem label="Trạng thái">
    <Badge variant="success">Sẵn sàng</Badge>
  </MetadataItem>
  <MetadataItem label="Khu vực">Châu Âu</MetadataItem>
  <MetadataItem label="Mô tả" orientation="vertical">Token thiết kế và thành phần cho các nhóm xây dựng giao diện của họ bằng agent.</MetadataItem>
</Metadata>
```

### Với một hành động

Một giá trị có thể chứa một control. Nhãn không đặt tên cho control, nên button tự mang chữ của nó.

```tsx
<Metadata className="w-full max-w-sm">
  <MetadataItem label="ID không gian làm việc">
    <span className="font-mono">ws_4f2a9c</span>
    <Button variant="secondary" size="sm">Copy ID</Button>
  </MetadataItem>
  <MetadataItem label="Đã tạo">6 thg 10, 2026</MetadataItem>
</Metadata>
```

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

### Nên

- Dùng Metadata cho dữ kiện chỉ đọc về một mục: trạng thái, người sở hữu, ngày, tag, ID.
- Giữ nhãn ngắn: một đến ba từ, sentence case, không có dấu hai chấm.
- Cho mọi item một giá trị. Khi không có, viết ra: None, Not set.
- Chọn horizontal cho panel chi tiết; vertical cho cột hẹp, hoặc cho một hàng dữ kiện chính với grid-cols-* trên Metadata.
- Bọc một câu có chứa link trong một span, để câu vẫn là một dòng văn liền thay vì các mảnh rời.

### Không nên

- Đừng đặt một control của form vào giá trị để sửa giá trị đó. Giá trị người dùng điền cần Field, với một nhãn nối tới control.
- Đừng dùng Metadata cho nhiều bản ghi dùng chung các nhãn; dùng Table.
- Đừng làm nhãn đậm hoặc có màu. Giá trị là thứ người dùng đọc; nhãn chỉ đặt tên cho giá trị.
- Đừng trộn item có icon và item không có icon trong cùng một danh sách.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `orientation` | `enum` | `horizontal`, `vertical` | `horizontal` | Trên Metadata, đặt cho mọi item. horizontal: các nhãn trong một cột cạnh các giá trị, cho một panel chi tiết. vertical: mỗi nhãn phía trên giá trị, cho một cột hẹp hoặc một hàng dữ kiện chính. Trên một MetadataItem, ghi đè cho item đó, chẳng hạn một mô tả dài dưới các hàng horizontal. |
| `label` (bắt buộc) | `node` |  |  | Đặt trên MetadataItem. Tên của giá trị: Status, Owner, Created. Một đến ba từ, sentence case, không có dấu hai chấm. |
| `leadingIcon` | `node` |  |  | Đặt trên MetadataItem. Icon Tabler trang trí trước nhãn: size={16}. Bỏ qua nếu không có icon. Mọi item trong danh sách đều có icon, hoặc không item nào có. |

### Slot

| Tên | Bắt buộc | Mô tả |
| --- | --- | --- |
| `items` | có | Một MetadataItem cho mỗi cặp. |
| `value` | có | Phần tử con của MetadataItem: văn bản, hoặc các component như Badge, Avatar với tên phía sau, một link hoặc một Button nhỏ. Nhiều component nằm trên một hàng và xuống dòng. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Metadata: phần tử dl. Horizontal: lưới hai cột, nhãn ở cột đầu rộng bằng nhãn dài nhất (tối đa 40% danh sách) và giá trị ở cột thứ hai. Vertical: lưới một cột, các item gap-lg; thêm grid-cols-* để xếp chúng thành một hàng. |
| `item` | MetadataItem: một cặp nhãn và giá trị, một div bọc dt và dd. Horizontal: một hàng trên hai cột của danh sách (subgrid). Vertical: nhãn phía trên giá trị, gap-xs. |
| `label` | dt: chữ secondary 14px, với icon tùy chọn phía trước (gap-xs). Horizontal: cao ít nhất bằng một control sm, chữ căn giữa. |
| `icon` | Icon phía trước tùy chọn trong nhãn: 16px, màu icon secondary, ngang với dòng đầu của nhãn, ẩn khỏi trình đọc màn hình. |
| `value` | dd: chữ primary 14px trên một hàng xuống dòng được (gap-sm), nên văn bản và các component thẳng hàng. Horizontal: cao ít nhất bằng một control sm, nội dung căn giữa, nên một dòng chữ và một button 28px đều ngang với nhãn. |

## Khả năng truy cập

Role: `term and definition (description list)`

- Metadata là một description list: mỗi nhãn là một dt và giá trị là một dd, gom trong một div, nên trình đọc màn hình đọc mỗi nhãn cùng giá trị và thông báo số lượng item.
- Icon phía trước mang tính trang trí và bị ẩn khỏi trình đọc màn hình; văn bản nhãn đặt tên cho giá trị.
- Để đặt tên cho cả danh sách, đặt một heading phía trên và trỏ aria-labelledby trên Metadata tới heading đó.
- Các control bên trong một giá trị (một link, một Button) giữ tên riêng và thứ tự focus. Một nhãn không phải tên của control: cho button chỉ có icon một aria-label riêng.

## Cài đặt

```bash
npx werewolf-ui add metadata
```

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.