ITP-GROWUP-LIB
Biblioteca JavaScript para criação de gráficos interativos, tabelas virtuais e widgets dinâmicos. Integra-se com Chart.js, jsPDF e html2canvas para fornecer funcionalidades completas de visualização, filtragem e exportação de relatórios em PDF.
---
$3
1.
Visão Geral
2.
Instalação
3.
API / Funcionalidades
-
filtrosAtuais
-
criarGrafico(ctx, tipoInicial, parametro_busca, backgroundColor, chave, obj, callback, porDuracao, parametro_busca_fim, aggregationType, valueField)
-
adicionarFiltrosDeMeses(dadosOriginais, parametro)
-
criarDataTable(containerEl, obj, colunas, options)
-
criarBotaoGerarRelatorio(dadosOriginais, containerEl)
-
criarGraficoBolha(ctx, dadosOriginais, eixoX, eixoY, raio, corField, aggregationType, valueField)
-
criarGraficoMisto(ctx, obj, titulo)
-
criarIcone(chartContainer)
4.
Exemplos de Uso
5.
Dependências Externas
6.
Licença
---
Visão Geral
A
ITP-GROWUP-LIB é voltada para desenvolvedores que desejam:
-
Gerar gráficos interativos (barra, linha, pizza, doughnut, radar, polarArea, bolha, misto)
-
Aplicar filtros globais (ano, mês, trimestre, valores de categoria, durações)
-
Exibir tabelas virtuais com paginação e possibilidade de filtrar diretamente pela célula clicada
-
Exportar relatórios em PDF contendo todos os gráficos renderizados e estatísticas por categoria
-
Criar um widget flutuante para carregar dados via endpoint ou arquivo JSON, selecionar propriedade, escolher tipo de gráfico e renderizar diretamente em um container
A biblioteca encapsula toda a lógica de filtragem, agregação e atualização automática de gráficos e tabelas, além de fornecer componentes prontos (botão de Relatório, spinner de carregamento) para facilitar integrações em aplicações web.
---
Instalação
1.
Via NPM
Caso a biblioteca esteja publicada no registro NPM (por exemplo
npm install itp-growup-lib), basta:
``
bash
Via CDN
`
html
`
API / Funcionalidades
$3
Descrição : Objeto global que armazena, em tempo real, todos os filtros aplicados a gráficos e tabelas.
Tipo : Object
Uso :
"data_inicio"
ou "prioridade"
).
`
js
`
Propósito :
getDadosAtuais
, processarDados
, processarDuracaoAtendimentos
).
filtrosAtuais
determina quais registros permanecem visíveis.
$3
ctx
CanvasRenderingContext2D
onde o gráfico será renderizado.
tipoInicial
string
'bar', 'line', 'pie', 'doughnut', 'radar', 'polarArea'
parametro_busca
string
obj) que será utilizado para agrupar ou filtrar por categoria/data (ex.: "data_inicio", "categoria", "status"). Se o campo contiver data (YYYY-MM-DD...), os controles de período (ano/mês/trimestre) serão gerados automaticamente.
backgroundColor
string ou Array
"rgba(0, 123, 255, 0.5)").
chave
string
"Total de Vendas", "Contagem de Categorias".
obj
Array
parametro_busca e, caso aggregationType seja 'sum' ou 'mean', deve conter também a propriedade valueField (campo numérico).
callback
function ou null
{ total, variacaoTexto }, onde:
total: número de registros após os filtros.
variacaoTexto: string com variação percentual em relação ao render anterior (ex.: "+10.50%").
porDuracao (opcional; padrão: true)
boolean
true: agrupa por parametro_busca normal (count).
false: cria um histograma de duração entre campo início e término (necessário passar parametro_busca_fim).
parametro_busca_fim (opcional; necessário se porDuracao === false)
string
"data_termino").
aggregationType (opcional; padrão: 'count')
string
'count', 'sum', 'mean', 'raw' (apenas para bubble).
'count': conta quantos itens existem em cada categoria.
'sum': soma os valores de valueField por categoria.
'mean': média de valueField por categoria.
valueField (opcional; necessário se aggregationType === 'sum' ou 'mean')
string
sum ou mean).
Detecção automática de campo de data :
obj) corresponder ao formato YYYY-MM-DD..., são gerados botões para filtrar por ano, dropdown para mês e dropdown para trimestre, todos respeitando filtros anteriores (ano ⇒ filtra meses/trimestres correspondentes).
Controles visuais :
tipoInicial).
e uma tabela HTML gerada a partir dos labels e valores calculados após aplicação de filtrosAtuais.
Atualização ao clicar na legenda :
todosOsGraficos, assim como tabelas e KPIs (caso seja implementado callback).
Registro em todosOsGraficos:
todosOsGraficos para permitir atualização global ao aplicar/remover filtros.
`js
Total após filtro: ${total}, Variação: ${variacaoTexto});
`
$3
dadosOriginais pelo campo parametro (por exemplo, se parametro === 'data_inicio', ao clicar em "Janeiro" o filtro global filtrosAtuais['data_inicio'] = ['Janeiro'] será aplicado).
dadosOriginais
Array
criarGrafico).
parametro
string
`js
`
$3
containerEl, com header fixo, corpo rolável (scroll vertical), paginação e suporte a filtrar clicando em qualquer célula. A filtragem também respeita filtrosAtuais, atualizando a visualização conforme filtros globais são aplicados.
containerEl
HTMLElement
obj
Array
criarGrafico).
colunas
Array
['nome', 'data_inicio', 'status']).
options (opcional)
Object
itemsPerPage (número; padrão 50): quantos registros exibir por página.
virtualRowHeight (número; em px; padrão 35): altura estimada de cada linha para cálculo de scroll virtual.
debounceTime (número; em ms; padrão 200): tempo para debounce de scroll/pesquisa.
Header Fixo + Corpo com Scroll
(conteúdo) fica dentro de uma rolável.
Paginação
itemsPerPage
, mostra botões de página (“1”, “2”, “3” …).
Filtragem ao Clicar na Célula
.celula-clicavel
.
coluna
, valor
) são extraídos de data-coluna
e data-valor
. Em seguida, chama toggleFiltro(coluna, valor)
, aplicando/removendo esse filtro global e atualizando todos os gráficos/tabelas.
Registro em todasAsTabelas
toggleFiltro
for chamado, atualizarTodasAsTabelas()
seja executada, redesenhando todas as tabelas com base no filtro global corrente.
no seu HTML:
`
js
`
$3
containerEl
, um botão estilizado (“Gerar Relatório”) que, ao ser clicado, gera um arquivo PDF contendo:
showLoadingSpinner
, updateLoadingSpinner
).
todosOsGraficos
) convertidos em imagens via grafico.toBase64Image()
.
calcularEstatisticasGrafico
(variações ano a ano, mês a mês).
"Relatorio_Visual_Completo.pdf"
(ou outros, conforme erros: "Relatorio_Visual_Sem_Graficos.pdf"
, etc).
dadosOriginais
Array
criarGrafico). Utilizado internamente para calcular estatísticas, caso necessário.
containerEl
HTMLElement
Gerar Relatório ” será inserido.
criado, caso seja necessário fazer referência a ele posteriormente.
`js
todosOsGraficos
...dados... / ];
`
$3
bolhas (bubble) usando Chart.js, agrupando dados conforme as dimensões passadas, agregando o campo raio (arraynumérico ou categórico) e colorindo bolhas de acordo com corField. O raio de cada bolha é normalizado entre 5px e 40px para melhor visualização.
ctx
CanvasRenderingContext2D
onde o gráfico de bolhas será renderizado.
dadosOriginais
Array
eixoX
string
convBuilder.
eixoY
string
eixoX).
raio
string
aggregationType === 'raw') ou somatório/média de valueField.
corField
string
corField terão cor igual.
aggregationType (opcional; padrão: 'raw')
string
'raw', 'count', 'sum', 'mean'
'raw': raio = valor numérico bruto (raio).
'count': raio proporcional à contagem de itens em cada grupo (eixoX, eixoY, corField).
'sum': somatório de valueField para cada grupo.
'mean': média de valueField em cada grupo.
valueField (opcional; necessário se aggregationType === 'sum' ou 'mean')
string
Agrupamento
${valorX}||${valorY}||${valorCor}.
count e sum de raio ou valueField para cada grupo.
Normalização do Raio
useSqrt = true, aplica raiz quadrada para compressão visual.
Geração de Cores
corField (após filtragem em filtrosAtuais) e gera tons HSL distribuídos uniformemente.
Atualização Dinâmica
grafico.data.datasets[0].data e grafico.data.datasets[0].backgroundColor, chamando grafico.update().
Chart(ctx, { type: 'bubble', ... }) e registra em todosOsGraficos com sua função renderizar.
`js
`
$3
gráfico misto (_mixed chart_) com barra + linha, reagindo a filtros globais (campo de data detectado automaticamente). A lógica interna foi exemplificada para um cenário de “atendimentos mensais”:
Barras : total de atendimentos por mês.
Linha : quantidade de atendimentos com nota “Excelente” por mês.
processar (o usuário pode customizar e estender o código-fonte conforme necessário).
ctx
CanvasRenderingContext2D
onde o gráfico será renderizado.
obj
Array
YYYY-MM-DD...) para extrair mês.
nota: 'Excelente' ou nota: 'Bom').
titulo (opcional; padrão: '')
string
title).
Agrupamento Mensal
dadosFiltrados, extrai mês de item.data_resolucao, incrementa contadores em dois objetos:
contagemAtendimentosMensal[nomeMes]
contagemExcelentesMensal[nomeMes] (somente se item.nota === 'Excelente').
Criação Chart.js
type: 'bar' como tipo base, com datasets: [ { type: 'bar', ... }, { type: 'line', ... } ].
y), barras em cores RGBA semitransparentes, linha sólida.
Atualização Global
filtrosAtuais muda, chama renderizar() definido internamente para recalcular e redesenhar o gráfico.
Registro em todosOsGraficos
toggleFiltro acionem atualização automática.
`js
`
$3
widget flutuante (ícone móvel) fixo na tela, que abre uma pequena janela de configuração. A janela permite:
Inserir endpoint (URL) para buscar dados JSON com fetch.
Fazer upload de arquivo JSON local.
) para gerar gráfico.
bar, line, pie, doughnut).
criarGrafico(ctx, ...) e renderizar no chartContainer.
chartContainer.
arrastado (drag and drop) e “encaixado” automaticamente nos cantos da tela (esquerda, direita, topo, base) quando solto, para manter uma boa experiência de UX.
chartContainer
HTMLElement
) onde os gráficos criados via widget serão inseridos.
Criação do ícone flutuante
ITP
position: fixed; bottom: 20px; right: 20px; width: 60px; height: 60px; ...
).
Janela de Configuração
fixo, inicialmente display: none
.
display: block/none
.
widgetWindow.style.top = rect.bottom + 'px'
, widgetWindow.style.left = rect.left + 'px'
).
Drag & Drop
mousedown
+ mousemove
+ mouseup
para arrastar o ícone.
DRAG_THRESHOLD
, define justDragged = true
para evitar que um clique acione a janela durante o arraste.
Processamento de Dados
handleFetch()
: faz fetch(endpoint)
, trata res.json()
, passa para processData(data)
.
handleFile(e)
: lê arquivo JSON local usando FileReader
, chama processData(jsonParsed)
.
processData(data)
:
data
é array não vazio.
Object.keys(data[0])
, exibe lista em