# Progress

A bar that shows how much of a task is done when the amount is known: an upload, an import, steps of a setup. With no value it shows that work runs without saying how much is left. label names the task above the bar, and showValue adds the percentage.

## Cách dùng

### Khi nào dùng

- Show how much of a task is done when the amount is known: an upload, an import, the files of a sync.
- A task long enough for the user to wait on, named above the bar.

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

- Work whose amount is never known, such as checking a value. Use Spinner.
- Content whose layout you know while it loads, such as a list. Use Skeleton.
- The steps of a flow the user moves through, such as a setup wizard.

## Biến thể

### size

Thickness of the track: md on its own, sm inside a dense row or a card.

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

## Ví dụ

### Upload

```tsx
<Progress label="Uploading report.pdf" value={40} showValue />
```

### A count of files

max is the real count, so the bar and its percentage follow the files done.

```tsx
<Progress label="Importing files" value={3} max={12} showValue />
```

### Unknown amount

No value: the bar shows that work runs, not how much is left.

```tsx
<Progress label="Preparing your export" />
```

### Named elsewhere

A small bar in a card row whose name is already on screen.

```tsx
<Progress size="sm" aria-label="Storage sync" value={75} />
```

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

### Nên

- Name the task in the label, and use the real count as max (12 files) when there is one.
- Show the percentage when the task takes long enough for the user to wait on it.
- Say in text when a long task is done or has failed; the bar alone is not announced.

### Không nên

- Don't use it when the amount is never known. Use Spinner.
- Don't show one bar per step of a single task; one bar covers the whole task.
- Don't use it for the steps of a flow the user moves through.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `value` | `number` |  |  | How much is done, from 0 to max. Leave it out, or pass null, when the amount is unknown: the bar is indeterminate. |
| `max` | `number` |  | `100` | The value when the task is done. Use the real count (12 files) and pass the count done as value. |
| `size` | `enum` | `sm`, `md` | `md` | Thickness of the track: md on its own, sm inside a dense row or a card. |
| `label` | `node` |  |  | The visible name above the bar: what is in progress, Uploading report.pdf. Without it, set aria-label or aria-labelledby. |
| `showValue` | `boolean` |  | `false` | Shows the percentage at the end of the label row. Screen readers get it either way. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | The track: the soft gray fill, radius-full, the full width of its parent. 4px (sm) or 8px (md) thick. |
| `indicator` | The accent fill from the start, as long as the share of the work that is done. With no value, a third of the track in the middle (so it never reads as an amount) that pulses. |
| `wrapper` | With label or showValue: the column that holds the label row above the track, gap-xs. |
| `header` | The label row: the label, then the percentage at the end, gap-sm. |
| `label` | 13px medium primary text that names the task. |
| `value` | With showValue: 13px secondary text with tabular figures, at the end of the label row. |

## Khả năng truy cập

Role: `progressbar`

- Always named: the label prop (linked with aria-labelledby), or aria-label or aria-labelledby when the name is shown elsewhere. The type requires one.
- aria-valuenow, aria-valuemin and aria-valuemax follow value and max; aria-valuetext reads the percentage (40%). With no value, the bar is indeterminate and has neither.
- The visible percentage (showValue) is hidden from screen readers, since they read aria-valuetext on the bar.
- The fill grows only when the user allows motion, and the indeterminate pulse stops under prefers-reduced-motion.
- A progress bar is not a live region. For a long task, also say in text when it is done.

## Cài đặt

```bash
npx shadcn add https://werewolf-ui.vercel.app/r/progress.json
```

Lệnh này thêm luôn `styles/werewolf.css`, bộ token mà mọi component dùng, và các component khác mà nó cần. Import file đó một lần trong CSS gốc, ngay sau `@import "tailwindcss"`, với đường dẫn tính từ file CSS đó (từ `app/globals.css` là `@import "../styles/werewolf.css"`).