# 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            |
| `infoSignTooltip`  | `string`  | `undefined`          |     Não     | Texto do tooltip exibido ao passar o mouse sobre o ícone de informação (ⓘ) ao lado do label |
| `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>
```

### Com ícone de informação no label

O `infoSignTooltip` exibe um ícone de informação (ⓘ) ao lado do label. Útil para métricas com definição técnica ou critérios de cálculo que o usuário pode não conhecer.

```html
<s-stats-card
    label="Taxa de conversão"
    value="12,5%"
    iconClass="fa fa-line-chart"
    color="#4A90E2"
    infoSignTooltip="Percentual de visitantes que realizaram uma compra no período selecionado"
/>
```

### 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