> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brainchat.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Widgets e gráficos

> Catálogo completo de widgets disponíveis no construtor de dashboards e como configurar cada um.

# Widgets e gráficos

Cada dashboard é composto por **widgets**. Existem dois grupos: **métricas** (visualizam dados) e **complementos** (decorativos).

***

## Métricas

### Gráficos

| Widget                 | Quando usar                                                             |
| ---------------------- | ----------------------------------------------------------------------- |
| **Barras verticais**   | Comparar valores entre categorias (vendas por mês, contatos por origem) |
| **Barras horizontais** | Quando há muitas categorias com nomes longos                            |
| **Linha**              | Evolução temporal de uma métrica (novos leads/dia)                      |
| **Área**               | Evolução temporal com ênfase em volume acumulado                        |
| **Pizza**              | Distribuição percentual entre poucas categorias (até 6)                 |
| **Rosca**              | Igual à pizza, mas com espaço central para um KPI                       |
| **Número (KPI)**       | Métrica única em destaque (Total de contatos: 1.247)                    |
| **Tabela**             | Lista detalhada de registros, com ordenação e busca                     |
| **Gantt**              | Cronograma de tarefas com fases, responsáveis e datas                   |

### Complementos decorativos

| Widget                  | Para quê                            |
| ----------------------- | ----------------------------------- |
| **Título**              | Cabeçalho de seção (H1, H2)         |
| **Texto**               | Bloco de texto explicativo          |
| **Separador**           | Linha horizontal divisória          |
| **Imagem**              | Logo, banner, ilustração            |
| **Formulário embutido** | Embed de um formulário do Brainchat |

***

## Configuração de uma métrica

Ao adicionar um widget de métrica, o editor abre 4 áreas:

### 1. Identificação

* **Título** — exibido acima do widget
* **Tabela de origem** — qual tabela alimenta o widget

### 2. Dados

| Configuração                         | Descrição                                                  |
| ------------------------------------ | ---------------------------------------------------------- |
| **Coluna de agrupamento** (dimensão) | Categoria no eixo X (ex: `mês`, `origem`, `status`)        |
| **Coluna de métrica**                | Valor agregado no eixo Y (ex: `valor_venda`, `quantidade`) |
| **Agregação**                        | Como combinar os valores                                   |

### Tipos de agregação

| Agregação      | O que faz                                  |
| -------------- | ------------------------------------------ |
| **Contagem**   | Conta quantos registros                    |
| **Soma**       | Soma os valores numéricos                  |
| **Média**      | Calcula a média                            |
| **Mínimo**     | Menor valor                                |
| **Máximo**     | Maior valor                                |
| **% do total** | Percentual de cada categoria sobre o total |

### Granularidade de data

Quando a coluna de agrupamento é uma data, escolha a granularidade:

`hora` · `dia` · `semana` · `quinzena` · `mês` · `bimestre` · `trimestre` · `semestre` · `ano`

### Fórmulas

Para combinar duas colunas em uma métrica, ative **Usar fórmula** e escolha:

* **Multiplicar** (ex: `quantidade × preço unitário`)
* **Dividir** (ex: `total ÷ contagem`)
* **Somar**
* **Subtrair**

### 3. Filtros do widget

Adicione filtros que afetam **apenas este widget** (independente dos filtros globais). Operadores disponíveis:

`igual` · `diferente` · `contém` · `não contém` · `começa com` · `termina com` · `maior que` · `menor que` · `entre` · `vazio` · `preenchido`

### 4. Aparência

| Configuração         | Efeito                                                            |
| -------------------- | ----------------------------------------------------------------- |
| **Formato do valor** | Moeda, número, percentual, data, duração, texto                   |
| **Casas decimais**   | Quantidade de decimais (0 a 4)                                    |
| **Separadores**      | Ponto/vírgula para milhar                                         |
| **Paleta de cores**  | Cores do gráfico (use a cor primária do dashboard ou personalize) |
| **Ordenação**        | ASC, DESC, por valor, por categoria                               |
| **Limite de itens**  | Top N (ex: top 10 produtos)                                       |

***

## Widget de Tabela — modos especiais

A tabela tem dois modos:

| Modo         | O que faz                                                  |
| ------------ | ---------------------------------------------------------- |
| **Lista**    | Mostra os registros como estão na tabela de origem         |
| **Agrupada** | Agrupa por uma ou mais colunas e mostra métricas agregadas |

Recursos extras:

* **Busca** integrada
* **Exportar** para CSV
* **Linhas por página** (paginação)
* **Truncar/quebrar** texto longo
* **Mostrar totais** no rodapé

***

## Widget de Gantt

O Gantt suporta hierarquia de até 3 níveis: **Projeto → Fase → Tarefa**.

Para cada nível você define:

* **Modo direto** — usa uma coluna da tabela base
* **Modo busca** — busca em outra tabela via FK

Colunas extras configuráveis na linha do tempo: duração, progresso, responsável, etiqueta, campos do registro.

***

## Widget de Número (KPI)

O KPI mostra **um único valor em destaque**. Pode ser configurado com:

* **Valor principal** — o número grande
* **Subtítulo** — descrição abaixo
* **Meta (opcional)** — valor ou fórmula de meta para comparar
* **Indicador de progresso** — barra ou círculo mostrando % atingido

***

## Próximo passo

<Card title="Filtros e páginas" icon="sliders" href="/dados/dashboards-filtros">
  Combine widgets com filtros globais e organize visões em abas.
</Card>