# StatsCard

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

Card de estatística que exibe um valor numérico com ícone, rótulo e animação de contagem. Suporta diferentes estilos visuais (modo claro, modo escuro, versão leve) e pode emitir evento ao ser clicado.

## Quando usar

- Dashboards com métricas e indicadores de performance
- Painéis de resumo com dados numéricos relevantes (totais, contagens, KPIs)
- Indicadores visuais que precisam destacar variações de valor com animação

## Quando não usar

- Exibição de dados textuais complexos — prefira `Card` ou um componente de lista
- Navegação para outra seção — prefira `Tile`
- Indicadores sem valor numérico central

## Instalação

```typescript
import { StatsCardModule } from '@seniorsistemas/angular-components/stats-card';

@NgModule({ imports: [StatsCardModule] })
export class MeuModule {}
```

## Uso básico

```html
<s-stats-card
  label="Vendas"
  value="1.234"
  iconClass="fas fa-shopping-cart"
  color="#3399ff"
/>
```

## API

### Inputs

| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
|-------------|------|--------|:-----------:|-----------|
| `label` | `string` | — | Sim | Rótulo descritivo da estatística exibida |
| `value` | `string` | `'0'` | Não | Valor numérico exibido. Quando `animateNumbers` está ativo, a contagem é animada |
| `iconClass` | `string` | `'fa fa-bar-chart'` | Não | Classe CSS do ícone (Font Awesome) |
| `color` | `string` | `'#339966'` | Não | Cor de destaque do card em formato CSS |
| `lightMode` | `boolean` | `true` | Não | Ativa o modo de cores claras (ícone com fundo colorido) |
| `lightVersion` | `boolean` | `false` | Não | Ativa a versão visual leve (sem sombra e com fundo claro) |
| `alwaysWithBorder` | `boolean` | `false` | Não | Exibe borda mesmo quando o card não está em destaque |
| `animateNumbers` | `boolean` | `true` | Não | Habilita a animação de contagem ao atualizar o valor |
| `clickable` | `boolean` | `false` | Não | Habilita o cursor de ponteiro e o evento de clique |
| `tooltip` | `string` | `''` | Não | Texto do tooltip exibido ao passar o mouse sobre o card |
| `id` | `string` | `'s-stats-card-{n}'` | Não | Identificador único do card no DOM |

### Outputs

| Evento | Tipo | Descrição |
|--------|------|-----------|
| `clicked` | `EventEmitter<MouseEvent>` | Emitido quando o usuário clica no card (requer `clickable = true`) |

## Exemplos

### Card padrão (modo claro)

```html
<s-stats-card
  label="População"
  value="214000000"
  iconClass="fa fa-users"
  color="#339966"
  [lightMode]="true"
></s-stats-card>
```

### Card modo escuro

```html
<s-stats-card
  label="Área territorial"
  value="8515767 km²"
  iconClass="fa fa-map"
  color="#F45B5B"
  [lightMode]="false"
></s-stats-card>
```

### Card clicável

```html
<s-stats-card
  label="Estados"
  value="27"
  iconClass="fa fa-flag"
  color="#4A90E2"
  [clickable]="true"
  [alwaysWithBorder]="true"
  tooltip="Clique para ver detalhes"
  (clicked)="onVerDetalhes($event)"
></s-stats-card>
```

### Grid de múltiplos cards

```html
<div style="display: grid; grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)); gap: 1rem;">
  <s-stats-card label="Total de pedidos" value="1.234" iconClass="fa fa-shopping-cart" color="#339966" [lightMode]="true"></s-stats-card>
  <s-stats-card label="Receita" value="R$ 45.200" iconClass="fa fa-dollar" color="#4A90E2" [lightMode]="false"></s-stats-card>
  <s-stats-card label="Usuários ativos" value="892" iconClass="fa fa-users" color="#9B59B6" [lightMode]="true" [lightVersion]="true"></s-stats-card>
</div>
```

### Com valor dinâmico e animação

```html
<s-stats-card
  label="Visitantes hoje"
  [value]="visitantesHoje.toString()"
  iconClass="fa fa-eye"
  color="#339966"
  [animateNumbers]="true"
></s-stats-card>
```

## Acessibilidade

- Quando `clickable = true`, o card recebe cursor pointer; recomenda-se fornecer `tooltip` descritivo para leitores de tela
- A animação de contagem tem duração de 200ms com steps de 20ms; não é disparada quando `animateNumbers = false`
- O atributo `id` permite associar o card a outros elementos acessíveis na página

## Componentes relacionados

- [`Tile`](../tile/README.md) — card clicável para navegação
- [`Card`](../card/README.md) — container genérico de conteúdo
