# Progress

> Componentes / Estado e aviso · Estado: **Em andamento** — Implementado e utilizável, mas ainda sem a validação completa de acessibilidade.

Barra de progresso de uma tarefa ou etapa — preenchida até o valor, com rótulo e porcentagem opcionais —, em três alturas e cinco cores. É um `role="progressbar"` com valor mínimo, máximo e atual; sem `value`, é indeterminada, para espera sem fim conhecido (E62).

- Função: Estado e aviso
- Também chamado de: barra de progresso, progresso, andamento
- Mora em: `app/components/atoms/Progress.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/Progress](https://phorte-design-system.vercel.app/styleguide/peca/Progress)
- Ficha no Storybook: [components-base-progress](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-base-progress--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/Progress/0](https://phorte-design-system.vercel.app/previa/Progress/0)
- Todas as peças: [https://phorte-design-system.vercel.app/llms.txt](https://phorte-design-system.vercel.app/llms.txt)

## Como usar no código

```tsx
import { Progress } from '@/app/components/atoms/Progress';

<Progress>…</Progress>
```

## Uso

### Variantes na ficha

1. [Interativo](https://phorte-design-system.vercel.app/previa/Progress/0)
2. [Variantes](https://phorte-design-system.vercel.app/previa/Progress/1)
3. [Indeterminado](https://phorte-design-system.vercel.app/previa/Progress/2)

Para mostrar quanto de uma coisa com fim conhecido já foi feito: etapas da inscrição, carga horária cumprida, vagas preenchidas.

### Quando não usar

Para quanto da página já foi lido, use o ScrollProgress. Para um valor que a pessoa escolhe, o Slider. Para a espera de um clique ("Enviando…" no próprio botão), o `isLoading` do Button.

### Faça

- Dê um `label`: é o nome da barra para o leitor ("Carga horária cumprida").
- Use `showValue` quando o número importa.
- Escolha a cor pelo significado: `warning` para prazo perto do fim, `success` para concluído.
- Diga **de quê** é o progresso: "Carga horária concluída", não "Progresso". Na determinada, a porcentagem; na indeterminada, o gerúndio com reticências: "Enviando o comprovante…" (E62).
- Use `min` quando a faixa não começa em zero: 70 de 20 a 120 é 50%.

### Evite

- Barra sem `label` nem `aria-label`: o leitor anuncia "barra de progresso" sem dizer do quê.
- Valor fora da faixa esperando que apareça: o componente prende entre 0 e `max`.

### Anatomia

1. **Rótulo** — O `label` à esquerda, em `text-sm`.
2. **Valor** — Porcentagem à direita, com `showValue`.
3. **Trilha** — Borda `--border-interactive` sobre `--card`, cantos redondos.
4. **Preenchimento** — Na cor da variante, até a porcentagem.

### Estados

| Estado | O que muda |
| --- | --- |
| Tamanho | `sm` 6px, `md` 10px (padrão), `lg` 16px de altura. |
| Cor | `primary` (padrão), `info`, `success`, `warning` ou `destructive` no preenchimento. |
| Mudança de valor | O preenchimento anima a largura em 500ms. |
| Indeterminado | Sem `value`: um trecho de 40% corre pela trilha em 1,4s, sem porcentagem. Com movimento reduzido, não corre — a trilha fica cheia e esmaecida, para não parecer parada em 40% (E62). |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Valor abaixo de `min` ou acima de `max` | É preso entre `min` (padrão 0) e `max`. |
| Sem `value` | Indeterminada: sem `aria-valuenow`, com `aria-busy="true"`, e o `showValue` não aparece — conferido no teste da ficha. |
| Porcentagem | Arredondada para inteiro (`Math.round`). |

### Relacionados

- [ScrollProgress](https://phorte-design-system.vercel.app/styleguide/md/ScrollProgress.md) — Quanto da página já foi lido.
- [Slider](https://phorte-design-system.vercel.app/styleguide/md/Slider.md) — Um valor que a pessoa escolhe.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | não | Variante do `cva`. |
| `variant` | `'primary' \| 'info' \| 'success' \| 'warning' \| 'destructive'` | `'primary'` | não | Variante do `cva`. |
| `value` | `number` | — | não | Sem `value`, a barra é **indeterminada** (E62): para espera sem fim conhecido — envio de arquivo, processamento da matrícula. Aí o rótulo diz o que acontece, no gerúndio: "Enviando o comprovante…". |
| `min` | `number` | `0` | não | Início da faixa (E62). Padrão 0. |
| `max` | `number` | `100` | não |  |
| `label` | `string` | — | não |  |
| `showValue` | `boolean` | — | não | A porcentagem ao lado do rótulo. Não aparece na indeterminada. |

Aceita também: `React.HTMLAttributes<HTMLDivElement>`.

### Medidas

| Parte | Valor | Classe |
| --- | --- | --- |
| Altura `sm` | 6px | `h-1.5` |
| Altura `md` | 10px | `h-2.5` |
| Altura `lg` | 16px | `h-4` |

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--border` | #E5E5E5 | `bg-border` |
| `--border-interactive` | #8C8C8C | `border-border-interactive` |
| `--card` | #FFFFFF | `bg-card` |
| `--destructive` | #BA0517 | `bg-destructive` |
| `--foreground` | #1A1A1A | `text-ink` |
| `--info` | #1D345E | `bg-info` |
| `--muted-foreground` | #595959 | `text-muted-foreground` |
| `--primary` | #D42B2B | `bg-primary` |
| `--success` | #2E844A | `bg-success` |
| `--warning` | #DD7A01 | `bg-warning` |

## Acessibilidade

### Leitor de tela

- `role="progressbar"` com `aria-valuenow`, `aria-valuemin` e `aria-valuemax`; o nome vem do `label` (por `aria-labelledby`) ou do `aria-label`/`aria-labelledby` passado, que vão só para a barra — nunca para o invólucro (E62).
- Indeterminada: nenhum valor e `aria-busy`. É assim que o leitor sabe que a espera não tem número.
- Não recebe foco: é informação, não controle.

### O que sustenta o estado

Usa os padrões: estatico. Falta ouvir com leitor de tela: estatico.

## Status e recursos

| Tipo | Recurso | Status |
| --- | --- | --- |
| Código | `app/components/atoms/Progress.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-base-progress--docs | Disponível |
| Teste de acessibilidade | axe em `npm run test` | No gate de todo commit |
| Leitor de tela | Passada da E33 | Falta ouvir |
| Design | Figma | Desativado até a Fase 2 |

### Histórico

- `fdd10ff` 2026-09-29 — ESTADO: E109 concluida, roteiro final fechado; proximo o merge na main
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/atoms/Progress.tsx