# ScrollProgress

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

Barra fina, de 4px, que se enche no vermelho de interface conforme a página rola — do topo ao fim. Só desenho, por contrato: `aria-hidden` na raiz (E62).

- Função: Estado e aviso
- Também chamado de: progresso de leitura, barra de rolagem, indicador de leitura
- Mora em: `app/components/atoms/ScrollProgress.tsx`
- Página: [https://phorte-design-system.vercel.app/styleguide/peca/ScrollProgress](https://phorte-design-system.vercel.app/styleguide/peca/ScrollProgress)
- Ficha no Storybook: [components-base-scrollprogress](https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-base-scrollprogress--docs)
- Prévia ao vivo, sozinha: [https://phorte-design-system.vercel.app/previa/ScrollProgress/0](https://phorte-design-system.vercel.app/previa/ScrollProgress/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 { ScrollProgress } from '@/app/components/atoms/ScrollProgress';

<ScrollProgress>…</ScrollProgress>
```

## Uso

### Variantes na ficha

1. [Padrão](https://phorte-design-system.vercel.app/previa/ScrollProgress/0)
2. [Sem trilha](https://phorte-design-system.vercel.app/previa/ScrollProgress/1)

No topo de artigos e páginas longas de leitura, fixada por quem usa, para mostrar quanto falta.

### Quando não usar

Para o progresso de uma tarefa (inscrição, carga horária), use o Progress. Em página curta, que cabe na tela, ela nem aparece.

### Faça

- Para acompanhar um painel que rola por dentro (uma gaveta, um artigo num quadro), passe o `alvo`: a ref da caixa (E124). Sem ele, a barra acompanha a janela.
- Com `trilha`, a barra aparece já em 0%, sobre `--muted`; sem ela, só aparece ao rolar — o jeito da Navbar.
- Posicione pelo consumidor (`fixed top-0`, por exemplo): a peça não se posiciona sozinha.
- Use uma por página.

### Evite

- Contar com ela para informar algo a quem usa leitor de tela: é só visual.

### Anatomia

1. **Trilha** — Largura total, 4px, transparente.
2. **Preenchimento** — No vermelho de interface, na largura toda, reduzido por `scaleX` à fração rolada.

### Estados

| Estado | O que muda |
| --- | --- |
| Topo | Preenchimento em 0%. |
| Rolando | O preenchimento acompanha a rolagem por `transform`, com transição de 150ms (`--duracao-rapida`) só com movimento liberado. |
| Fim | Preenchimento em 100%. |
| Página sem rolagem | Fica em 0%. |

### Comportamento

| Situação | O que acontece |
| --- | --- |
| Com `alvo` | Acompanha a rolagem da caixa: 0 no topo, metade no meio, cheia no fim — testado na ficha. A caixa que muda de altura refaz a conta. |
| Rolagem | Ouve o `scroll` da janela (passivo) e refaz a conta — rolado ÷ (altura do documento − altura da janela) — no máximo uma vez por quadro (`requestAnimationFrame`). |
| Janela ou documento mudam de tamanho | Refaz a conta no `resize` e quando o documento muda de altura (`ResizeObserver`) — uma imagem que carrega depois não deixa a barra errada. |
| Montagem | Calcula uma vez de saída, para abrir já na posição certa. |

### Relacionados

- [Progress](https://phorte-design-system.vercel.app/styleguide/md/Progress.md) — Progresso de uma tarefa, com nome e valor.
- [Navbar](https://phorte-design-system.vercel.app/styleguide/md/Navbar.md) — O topo fixo onde ela costuma ficar.

## Especificação

### Propriedades

| Prop | Tipo | Padrão | Obrigatória | Descrição |
| --- | --- | --- | --- | --- |
| `alvo` | `React.RefObject<HTMLElement \| null>` | — | não | A caixa cuja rolagem a barra acompanha (E124). Sem ele, a janela — o uso da Navbar. Com ele, um painel que rola por dentro: uma gaveta, um artigo num quadro, a prévia do styleguide. |
| `trilha` | `boolean` | `false` | não | Mostra a trilha em `--muted` (E124): a barra aparece já em 0%. Sem ela, a trilha é transparente, e nada se vê antes de rolar — o padrão da Navbar, que tem o próprio fundo. |

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

### Medidas

| Parte | Valor | Classe |
| --- | --- | --- |
| Altura | 4px | `h-1` |

### Tokens de cor

| Token | Valor | Usado como |
| --- | --- | --- |
| `--muted` | #F4F6F9 | `bg-muted` |
| `--primary` | #D42B2B | `bg-primary` |

## Acessibilidade

### Leitor de tela

- Não tem papel, nome nem valor, e a raiz é `aria-hidden` (E62): o leitor de tela não anuncia nada. A informação equivalente é a própria posição na página.
- Aceita `ref` e os atributos de `<div>`, como toda peça com raiz única (E62).

### 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/ScrollProgress.tsx` | Disponível |
| Ficha | https://main--69b4847d498a9bd8659db9ba.chromatic.com/?path=/docs/components-base-scrollprogress--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

- `6ecd5a3` 2026-09-29 — E130: MarketingHero — estrutura e layout refeitos
- Histórico completo no GitHub: https://github.com/srbunnie/Pos-Phorte-Design-System/commits/main/app/components/atoms/ScrollProgress.tsx