Widgets
Envoltório (shell) que renderiza qualquer chart ou analytics via type, com header, menu de ações e estados.
O Widget é a camada que envolve qualquer chart ou componente de analytics num Card, com título, descrição, menu de ações e estados (loading / empty / error). Ele roteia o conteúdo pela prop type — não precisa importar o chart manualmente.
Camada 3 da taxonomia: Charts → Analytics → Widgets → Dashboard.
Exemplos
Chart, KPI e pie como widgets, mais o estado de carregamento. Cada widget é um card com header (título + descrição), menu ⋮ e o desenho do gráfico abaixo.
Menu de ações (⋮)
O menu do widget reúne, em uma só lista: Editar, Tipo de gráfico ▸, Copiar para ▸, Fixar na sidebar, Redefinir resolução padrão, Visualizar expandido e Remover.
- Tipo de gráfico troca a visualização sem refazer o widget — Área, Barra, Coluna, Linha, Rosca, Pizza, Radar, Radial, Tag Cloud e KPI ficam num submenu. Trocar o tipo preserva os dados e a configuração de colunas.
- Copiar para envia uma cópia independente do widget para outra dashboard/área. As opções vêm das abas/áreas conhecidas pela tela; a cópia passa a ter vida própria.
- Modo compacto (widget fixado na sidebar): o menu substitui Fixar / Redefinir resolução / Visualizar expandido por Desafixar da sidebar e Mover para o body — as ações que só fazem sentido no corpo somem para reduzir ruído.
Composição
O Widget compõe o AnalyticsBlock (camada de contexto) e instancia o gráfico certo no slot — herdando bare/mode automaticamente, sem card-dentro-de-card. Por cima, ele adiciona a camada de personalização do usuário: tipo e colunas (via ChartWizard) e portabilidade (copiar/fixar).
Camadas: Chart (desenho) → AnalyticsBlock (contexto) → Widget (configuração do usuário) → Dashboard (layout).
Para dirigir o widget, prefira uma config persistível (tipo, colunas, título, período, fixado) sobre passar type + props soltos — a config é o que a tela salva e recarrega. O header pode exibir um badge de status (ok / warning / error) ou um selo custom (texto + cor); o selo tem prioridade. Um seletor de período no topo e um rodapé "Atualizado…" aparecem só quando alimentados.
Estados
Prioridade de renderização: error → loading → empty → conteúdo.
- Loading — esqueleto no lugar do desenho (
aria-busy). - Empty — deduzido de dados vazios, ou forçado; comunica "sem dados" sem parecer erro.
- Error — faixa de erro com mensagem opcional (
role="alert").
Modos
default— ocupa a proporção do grid no body/Dashboard.compact— altura máxima fixa, para fixar na Sidebar sem estourar. Esconde eixos, legenda e descrição: fica só o título + o desenho. Entra em compact automaticamente quando a largura do bloco fica< 240px(container, não viewport — ver Responsivo).- Mobile: full width.
Ciclo na tela (drag-and-drop)
Numa tela real (ex.: a Index de Transações), o Widget percorre um ciclo completo. O componente só emite eventos — quem orquestra layout e persistência é a tela/squad.
- Criar — pelo menu do cabeçalho de uma coluna da tabela (gera um chart/métrica daquela coluna). A edição abre o ChartWizard.
- Editar — ⋮ → Editar reabre o Wizard pré-preenchido.
- Fixar na sidebar — arrastar o card do corpo até a seção Gráficos da sidebar (ou ⋮ → Fixar). Vira uma cópia independente em modo compacto, agrupada pelo contexto de origem (Compras, Contratos…).
- Copiar para a dashboard — ⋮ → Copiar para, escolhendo a aba de destino.
- Persistir — a tela salva o layout (no demo,
localStorage; em produção, o endpoint do squad).
As áreas corpo e sidebar são simétricas: dá pra arrastar nos dois sentidos e reordenar dentro de cada uma. Cópias têm vidas apartadas (editar/remover uma não afeta a outra).
Quando não usar
- Para um único gráfico fixo, sem header, menu nem personalização do usuário, use o Chart direto (ou o AnalyticsBlock quando precisar só do contexto).
Acessibilidade
role="region"+aria-label(título + descrição).- Erro com
role="alert"; loading comaria-busy.