# Progressbar

![Status](https://img.shields.io/badge/status-stable-brightgreen)

Componente de barra de progresso para representar visualmente o avanço de uma operação. Suporta modo determinado (valor percentual 0–100) e modo indeterminado (animação contínua quando a duração é desconhecida), além de um marcador de valor-alvo para comparação.

## Quando usar

- Processos com percentual de conclusão calculável — uploads, downloads, etapas de um fluxo, metas
- Operações de duração desconhecida — chamadas de API, processamentos em background (modo indeterminado)
- Dashboards de desempenho ou KPIs com comparação entre valor atual e meta

## Quando não usar

- Para indicar carregamento simples de página ou componente — use `Spinner` ou `Skeleton`
- Para representar sequências de etapas com navegação — use `Steps`
- Quando não há valor numérico mensurável e a duração é desconhecida sem necessidade de label — use `Spinner`

## Instalação

```typescript
import { ProgressBarModule } from '@seniorsistemas/angular-components/progressbar';

@NgModule({ imports: [ProgressBarModule] })
export class MeuModulo {}
```

## Uso básico

```html
<s-progressbar
  [value]="75"
  activeColor="blue"
  [showValue]="true"
/>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `activeColor` | `ProgressBarColors` | — | Sim | Cor da barra de progresso ativa |
| `value` | `number` | — | Não* | Valor atual (0–100). Obrigatório no modo `'determinate'`. Não usar em `'indeterminate'` |
| `mode` | `ProgressBarMode` | `'determinate'` | Não | Modo de operação da barra |
| `showValue` | `boolean` | `true` | Não | Exibe o valor percentual dentro da barra (apenas no modo determinado) |
| `targetValue` | `number` | `undefined` | Não | Valor-alvo (0–100) exibido como marcador de referência (modo determinado) |
| `label` | `string` | `undefined` | Não | Rótulo exibido abaixo da barra no modo indeterminado |
| `targetLabel` | `string` | `undefined` | Não | Rótulo do marcador de valor-alvo |
| `numberFormatOptions` | `Intl.NumberFormatOptions` | `{ style: 'decimal', minimumFractionDigits: 0, maximumFractionDigits: 2, roundingMode: 'trunc' }` | Não | Opções de formatação do valor percentual exibido |

### Tipos

```typescript
type ProgressBarColors = 'blue' | 'green' | 'red' | 'yellow';

type ProgressBarMode = 'determinate' | 'indeterminate';
```

### Guia de cores

| Cor | Uso sugerido |
|-----|-------------|
| `'blue'` | Progresso neutro ou informativo |
| `'green'` | Progresso positivo ou concluído com sucesso |
| `'red'` | Alertas críticos ou progresso negativo |
| `'yellow'` | Alertas ou progresso intermediário |

## Exemplos

### Modo determinado básico

```html
<s-progressbar
  [value]="65"
  activeColor="blue"
  [showValue]="true"
  mode="determinate"
></s-progressbar>
```

### Com marcador de meta

```html
<s-progressbar
  [value]="45"
  activeColor="green"
  [showValue]="true"
  mode="determinate"
  [targetValue]="70"
  targetLabel="Meta 70%"
></s-progressbar>
```

### Múltiplas cores

```html
<s-progressbar [value]="60" activeColor="blue" [showValue]="true" mode="determinate"></s-progressbar>
<s-progressbar [value]="80" activeColor="green" [showValue]="true" mode="determinate"></s-progressbar>
<s-progressbar [value]="35" activeColor="red" [showValue]="true" mode="determinate"></s-progressbar>
<s-progressbar [value]="55" activeColor="yellow" [showValue]="true" mode="determinate"></s-progressbar>
```

### Sem valor exibido

```html
<s-progressbar
  [value]="40"
  activeColor="blue"
  [showValue]="false"
  mode="determinate"
></s-progressbar>
```

### Modo indeterminado

```html
<s-progressbar
  activeColor="blue"
  mode="indeterminate"
  label="Processando dados..."
></s-progressbar>
```

## Acessibilidade

- O componente usa elementos semânticos de barra de progresso com valores calculados pelo CSS
- No modo determinado, o valor percentual é exibido visualmente dentro da barra
- No modo indeterminado, o `label` fornece contexto textual para leitores de tela sobre o que está sendo processado
- Erros são lançados em tempo de desenvolvimento se `value` estiver fora do intervalo 0–100 ou se `value`/`targetValue` forem usados em modo `'indeterminate'`

## Componentes relacionados

- [`Spinner`](../spinner/README.md) — indicador de carregamento circular
- [`Steps`](../steps/README.md) — sequência de etapas com navegação