@celke/kole-react 0.3.0 → 0.4.1

package/dist/components/Grafico/Cartesiano.d.ts

@@ -0,0 +1,23 @@
+import type { DadoGrafico, EixoGrafico, EixoXGrafico, FaixaGrafico, GraficoBaseProps, ReferenciaGrafico, SerieGrafico } from './tipos.js';
+export interface SerieCartesiana extends SerieGrafico {
+    tipo: 'linha' | 'barra';
+}
+export interface CartesianoProps extends GraficoBaseProps {
+    dados: DadoGrafico[];
+    eixoX: EixoXGrafico;
+    eixoY?: EixoGrafico;
+    eixoYDireito?: EixoGrafico;
+    series: SerieCartesiana[];
+    orientacao?: 'vertical' | 'horizontal';
+    pontos?: boolean;
+    area?: boolean;
+    referencias?: ReferenciaGrafico[];
+    faixas?: FaixaGrafico[];
+    divergente?: boolean;
+    rotulosNasBarras?: boolean;
+}
+/**
+ * Motor comum de `GraficoLinha`, `GraficoBarras` e `GraficoCombinado`: eixo X por
+ * categoria (faixas), data ou número, um ou dois eixos Y, barras agrupadas e linhas.
+ */
+export declare function Cartesiano(props: CartesianoProps): import("react").JSX.Element;

package/dist/components/Grafico/GraficoBarras.d.ts

@@ -0,0 +1,17 @@
+import type { DadoGrafico, EixoGrafico, EixoXGrafico, GraficoBaseProps, ReferenciaGrafico, SerieGrafico } from './tipos.js';
+export interface GraficoBarrasProps extends GraficoBaseProps {
+    dados: DadoGrafico[];
+    eixoX: EixoXGrafico;
+    eixoY?: EixoGrafico;
+    /** Mais de uma série = barras agrupadas lado a lado. */
+    series: SerieGrafico[];
+    /** `horizontal` serve para rankings: os rótulos longos ficam inteiros, sem girar. */
+    orientacao?: 'vertical' | 'horizontal';
+    /** `--graf-pos` acima de zero e `--graf-neg` abaixo, com a linha do zero destacada. */
+    divergente?: boolean;
+    /** Valor escrito na ponta de cada barra (some se não couber). */
+    rotulosNasBarras?: boolean;
+    referencias?: ReferenciaGrafico[];
+}
+/** Barras verticais ou horizontais, agrupadas ou divergentes. */
+export declare function GraficoBarras({ series, ...props }: GraficoBarrasProps): import("react").JSX.Element;

package/dist/components/Grafico/GraficoCombinado.d.ts

@@ -0,0 +1,20 @@
+import type { DadoGrafico, EixoGrafico, EixoXGrafico, GraficoBaseProps, ReferenciaGrafico, SerieGrafico } from './tipos.js';
+export interface GraficoCombinadoProps extends GraficoBaseProps {
+    dados: DadoGrafico[];
+    eixoX: EixoXGrafico;
+    /** Eixo esquerdo. */
+    eixoY?: EixoGrafico;
+    eixoYDireito?: EixoGrafico;
+    /** Padrão: eixo esquerdo. */
+    barras?: SerieGrafico[];
+    /** Padrão: eixo direito. */
+    linhas?: SerieGrafico[];
+    referencias?: ReferenciaGrafico[];
+    /** Marca os pontos das linhas. Padrão: sim até 60 pontos. */
+    pontos?: boolean;
+}
+/**
+ * Barras e linhas no mesmo eixo X, com dois eixos Y. A legenda diz o eixo de cada
+ * série ("Ticket médio (R$, eixo direito)"): sem isso, o gráfico de dois eixos engana.
+ */
+export declare function GraficoCombinado({ barras, linhas, eixoYDireito, ...props }: GraficoCombinadoProps): import("react").JSX.Element;

package/dist/components/Grafico/GraficoDispersao.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react';
+import type { DadoGrafico, EixoGrafico, GraficoBaseProps } from './tipos.js';
+export interface GraficoDispersaoProps extends GraficoBaseProps {
+    /** Cada item é um ponto. */
+    dados: DadoGrafico[];
+    /** Eixo horizontal (numérico). */
+    eixoX?: EixoGrafico;
+    eixoY?: EixoGrafico;
+    chaveX: string;
+    chaveY: string;
+    /** Campo mostrado como título da caixa de detalhes (ex.: o ano). */
+    chaveRotulo?: string;
+    /** Campo booleano: pontos destacados com `--graf-2`. */
+    chaveDestaque?: string;
+    /** Desenha a reta dos mínimos quadrados e mostra `r`, `r²` e `n` no canto. */
+    regressao?: boolean;
+    /** Texto abaixo do gráfico (ex.: p-valor calculado pelo app). */
+    nota?: ReactNode;
+    rotuloPontos?: string;
+    rotuloDestaque?: string;
+    rotuloRegressao?: string;
+}
+/** Cruzamento de duas medidas, um ponto por item, com reta de regressão opcional. */
+export declare function GraficoDispersao(props: GraficoDispersaoProps): import("react").JSX.Element;

package/dist/components/Grafico/GraficoLinha.d.ts

@@ -0,0 +1,18 @@
+import type { DadoGrafico, EixoGrafico, EixoXGrafico, FaixaGrafico, GraficoBaseProps, ReferenciaGrafico, SerieGrafico } from './tipos.js';
+export interface GraficoLinhaProps extends GraficoBaseProps {
+    /** Um objeto por ponto do eixo X. */
+    dados: DadoGrafico[];
+    eixoX: EixoXGrafico;
+    eixoY?: EixoGrafico;
+    series: SerieGrafico[];
+    /** Marca os pontos. Padrão: sim até 60 pontos. */
+    pontos?: boolean;
+    /** Preenche abaixo da primeira série. */
+    area?: boolean;
+    /** Linhas horizontais (ex.: média mensal). */
+    referencias?: ReferenciaGrafico[];
+    /** Intervalos sombreados no eixo X (ex.: novembro e dezembro). */
+    faixas?: FaixaGrafico[];
+}
+/** Séries ao longo do eixo X (tempo, categoria ou número). `null` deixa uma falha na linha. */
+export declare function GraficoLinha({ series, ...props }: GraficoLinhaProps): import("react").JSX.Element;

package/dist/components/Grafico/MapaCalor.d.ts

@@ -0,0 +1,25 @@
+import type { GraficoBaseProps, ValorGrafico } from './tipos.js';
+export interface CelulaMapaCalor {
+    linha: string | number;
+    coluna: string | number;
+    valor: ValorGrafico;
+}
+export interface MapaCalorProps extends Omit<GraficoBaseProps, 'legenda'> {
+    /** Rótulos das linhas, de cima para baixo (ex.: anos). */
+    linhas: Array<string | number>;
+    /** Rótulos das colunas, da esquerda para a direita (ex.: meses). */
+    colunas: Array<string | number>;
+    valores: CelulaMapaCalor[];
+    /** Padrão: o menor valor. */
+    minimo?: number;
+    /** Padrão: o maior valor. */
+    maximo?: number;
+    formatar?: (valor: number) => string;
+    unidade?: string;
+    /** Padrão `true`: barra com a escala de cores abaixo da grade. */
+    legendaEscala?: boolean;
+    /** Cabeçalho da coluna das linhas na tabela do "Ver dados". Padrão: "Linha". */
+    rotuloLinhas?: string;
+}
+/** Grade de células coloridas pela escala sequencial (`--graf-seq-1` a `--graf-seq-5`). */
+export declare function MapaCalor(props: MapaCalorProps): import("react").JSX.Element;

package/dist/components/Grafico/Minigrafico.d.ts

@@ -0,0 +1,11 @@
+export interface MinigraficoProps {
+    valores: number[];
+    /** A linha se desenha da esquerda para a direita ao aparecer (nunca com "reduzir movimento"). */
+    animacao?: boolean;
+    className?: string;
+}
+/**
+ * Linha pequena, sem eixos (sparkline), na cor `--ind-cor` do indicador ou `--graf-1`.
+ * Decorativa: o valor em texto fica com quem a usa.
+ */
+export declare function Minigrafico({ valores, animacao, className }: MinigraficoProps): import("react").JSX.Element | null;

package/dist/components/Grafico/MolduraGrafico.d.ts

@@ -0,0 +1,77 @@
+import { type KeyboardEvent, type ReactNode } from 'react';
+import { type Coluna } from '../Tabela/Tabela.js';
+import type { DadoGrafico, GraficoBaseProps } from './tipos.js';
+export type FormaLegenda = 'linha' | 'barra' | 'ponto';
+export interface ItemLegenda {
+    chave: string;
+    rotulo: string;
+    cor: string;
+    forma: FormaLegenda;
+    tracejada?: boolean;
+    visivel: boolean;
+}
+export interface TabelaGrafico {
+    colunas: Coluna<DadoGrafico>[];
+    registros: DadoGrafico[];
+}
+interface MolduraGraficoProps extends GraficoBaseProps {
+    semDados: boolean;
+    itensLegenda?: ItemLegenda[];
+    aoAlternarSerie?: (chave: string) => void;
+    /** Montada só quando a pessoa pede a tabela. */
+    tabela: () => TabelaGrafico;
+    /** Texto abaixo do gráfico (ex.: estatística calculada pelo app). */
+    nota?: ReactNode;
+    /** O gráfico em si, desenhado na largura do container. */
+    children: (largura: number) => ReactNode;
+}
+/** Largura do elemento, acompanhando o container (o SVG é redesenhado, não esticado). */
+export declare function useLargura<T extends HTMLElement>(): readonly [import("react").RefObject<T | null>, number];
+/** Amostra da legenda e da caixa de detalhes: traço (linha), quadrado (barra) ou círculo (ponto). */
+export declare function Amostra({ cor, forma, tracejada }: {
+    cor: string;
+    forma: FormaLegenda;
+    tracejada?: boolean;
+}): import("react").JSX.Element;
+/** Esqueleto comum dos gráficos: título, legenda, ver dados, carregando e vazio. */
+export declare function MolduraGrafico({ titulo, altura, legenda, carregando, textoVazio, verDados, animacao, className, semDados, itensLegenda, aoAlternarSerie, tabela, nota, children, }: MolduraGraficoProps): import("react").JSX.Element;
+/** Legenda: esconde/mostra uma série, mas nunca a última visível (o gráfico ficaria em branco). */
+export declare function useSeriesOcultas(): readonly [ReadonlySet<string>, (chave: string, total: number) => void];
+/** Ponto ativo da caixa de detalhes: mouse, toque e setas do teclado andam pelos itens. */
+export declare function usePontoAtivo(total: number): {
+    ativo: number | null;
+    setAtivo: import("react").Dispatch<import("react").SetStateAction<number | null>>;
+    aoTeclar: (e: KeyboardEvent) => void;
+};
+export interface LinhaDetalhe {
+    chave: string;
+    rotulo: string;
+    cor: string;
+    forma: FormaLegenda;
+    valor: string;
+}
+/** Caixa de detalhes, ao lado da posição `x` (vira para a esquerda na metade direita). */
+export declare function CaixaDetalhes({ x, y, largura, titulo, linhas }: {
+    x: number;
+    y?: number;
+    largura: number;
+    titulo: string;
+    linhas: LinhaDetalhe[];
+}): import("react").JSX.Element;
+/** Texto da caixa de detalhes para o leitor de tela (a caixa visual fica escondida dele). */
+export declare function textoDetalhe(titulo: string, linhas: LinhaDetalhe[]): string;
+/**
+ * Recorte que revela o desenho da esquerda para a direita, na entrada animada
+ * (linhas, áreas e pontos). O retângulo cobre o SVG todo: no fim da animação,
+ * não corta nada.
+ */
+export declare function useRevelacao(animacao: boolean | undefined, largura: number, altura: number): {
+    recorte: undefined;
+    definicao: null;
+} | {
+    recorte: string;
+    definicao: import("react").JSX.Element;
+};
+/** Cor padrão da série pela posição: `--graf-1`, `--graf-2`… */
+export declare function corDaSerie(indice: number, cor?: string): string;
+export {};

package/dist/components/Grafico/escalas.d.ts

@@ -0,0 +1,85 @@
+import type { EixoGrafico, EixoXGrafico, ValorGrafico } from './tipos.js';
+/** Valor da caixa de detalhes e da tabela: `1.234,5 mm`. */
+export declare function formatarValor(valor: ValorGrafico | undefined, eixo?: EixoGrafico): string;
+/** Rótulo do eixo: compacto a partir de 10 mil (`12,4 mil`). */
+export declare function formatarPasso(valor: number, eixo?: EixoGrafico): string;
+/** Lê o campo como número; texto, `undefined` e `NaN` viram `null` (sem dado). */
+export declare function lerNumero(valor: unknown): ValorGrafico;
+/** Passo "redondo" de 1, 2 ou 5 × 10ⁿ, o mais próximo acima do passo bruto. */
+export declare function passoRedondo(bruto: number): number;
+export interface DominioRedondo {
+    de: number;
+    ate: number;
+    passos: number[];
+}
+/** Domínio ampliado até múltiplos do passo, com cerca de `alvo` divisões. */
+export declare function dominioRedondo(minimo: number, maximo: number, alvo?: number): DominioRedondo;
+export interface EscalaLinear {
+    (valor: number): number;
+    de: number;
+    ate: number;
+    passos: number[];
+}
+/** Escala linear de `[de, ate]` para `[p0, p1]` (em px), com os passos redondos do domínio. */
+export declare function escalaLinear(dominio: DominioRedondo, p0: number, p1: number): EscalaLinear;
+/** Domínio de um eixo Y a partir dos valores, respeitando `minimo`/`maximo` do eixo. */
+export declare function dominioDoEixo(valores: number[], eixo: EixoGrafico | undefined, alvo: number, comZero: boolean): DominioRedondo;
+export interface EscalaBanda {
+    /** Início da faixa do item `i` (px). */
+    inicio(i: number): number;
+    centro(i: number): number;
+    /** Largura útil da faixa (sem o espaço entre faixas). */
+    largura: number;
+    /** Largura de uma faixa inteira, com o espaço. */
+    passo: number;
+    /** Item sob a posição em px. */
+    indice(px: number): number;
+}
+/** Uma faixa por item, com `espaco` (0 a 1) de folga entre elas. */
+export declare function escalaBanda(n: number, p0: number, p1: number, espaco?: number): EscalaBanda;
+/** `Date`, timestamp ou texto (`aaaa-mm-dd`, `aaaa-mm`, ISO). Texto sem hora é lido no fuso local. */
+export declare function lerData(valor: unknown): Date | null;
+/** Formatadores curto (eixo: `jan/21`) e completo (caixa de detalhes: `jan/2021`) para estas datas. */
+export declare function formatadoresDeData(datas: Date[]): {
+    curto: (d: Date) => string;
+    completo: (d: Date) => string;
+};
+/** Rótulos do eixo X (curto) e da caixa de detalhes (completo), um por item. */
+export declare function rotulosDoEixoX(valores: unknown[], eixoX: EixoXGrafico): {
+    curtos: string[];
+    completos: string[];
+};
+/** Valor numérico do eixo X (`data` vira timestamp); `null` se não der para ler. */
+export declare function posicaoX(valor: unknown, tipo: EixoXGrafico['tipo']): number | null;
+/**
+ * Largura aproximada do texto em px (Inter a 12px, com folga). Estimativa fixa: o
+ * desenho não depende da fonte já ter carregado, e o teste visual sai sempre igual.
+ */
+export declare function larguraTexto(texto: string, tamanho?: number): number;
+/**
+ * Índices cujos rótulos cabem sem se sobrepor, andando da esquerda para a direita
+ * (o primeiro sempre entra). `posicoes` em px, na ordem dos itens.
+ */
+export declare function rotulosQueCabem(posicoes: number[], rotulos: string[], folga?: number): number[];
+/**
+ * Um rótulo a cada N itens, com N fixo (para faixas de mesmo tamanho): o mesmo
+ * espaçamento do começo ao fim do eixo.
+ */
+export declare function rotulosACadaN(passo: number, rotulos: string[], folga?: number): number[];
+export interface RegressaoLinear {
+    inclinacao: number;
+    intercepto: number;
+    /** Correlação de Pearson. */
+    r: number;
+    r2: number;
+    n: number;
+}
+/**
+ * Reta dos mínimos quadrados (`y = inclinacao × x + intercepto`) com `r`, `r²` e `n`.
+ * Pontos com `x` ou `y` não numérico ficam de fora. `null` com menos de 3 pontos ou
+ * variância zero em `x` ou em `y`.
+ */
+export declare function regressaoLinear(pontos: ReadonlyArray<{
+    x: number | null;
+    y: number | null;
+}>): RegressaoLinear | null;

package/dist/components/Grafico/tipos.d.ts

@@ -0,0 +1,68 @@
+/** `null` = sem dado: a linha fica com uma falha, a barra some, a célula fica sem cor. Nunca vira zero. */
+export type ValorGrafico = number | null;
+export interface SerieGrafico {
+    /** Campo de cada item de `dados`. */
+    chave: string;
+    /** Legenda e caixa de detalhes. */
+    rotulo: string;
+    /** Padrão: `--graf-1`, `--graf-2`… na ordem das séries. */
+    cor?: string;
+    /** Ex.: linha de tendência. */
+    tracejada?: boolean;
+    /** Só no `GraficoCombinado`. Padrão: barras no esquerdo, linhas no direito. */
+    eixo?: 'esquerdo' | 'direito';
+}
+export interface EixoGrafico {
+    /** Ex.: "Vendas". */
+    rotulo?: string;
+    /** Ex.: "mil R$"; aparece no eixo e na caixa de detalhes. */
+    unidade?: string;
+    formatar?: (valor: number) => string;
+    minimo?: number;
+    maximo?: number;
+}
+export interface EixoXGrafico {
+    chave: string;
+    /** `data` aceita `Date`, timestamp ou texto `aaaa-mm-dd` / `aaaa-mm`. */
+    tipo: 'categoria' | 'data' | 'numero';
+    /** Cabeçalho da coluna na tabela do "Ver dados" (padrão: Categoria, Data ou Valor). */
+    rotulo?: string;
+    formatar?: (valor: string | number | Date) => string;
+}
+/** Linha horizontal de referência (ex.: média mensal). */
+export interface ReferenciaGrafico {
+    valor: number;
+    rotulo: string;
+    eixo?: 'esquerdo' | 'direito';
+}
+/** Intervalo sombreado no eixo X (ex.: novembro e dezembro). `de` e `ate` são valores do eixo X. */
+export interface FaixaGrafico {
+    de: string | number;
+    ate: string | number;
+    rotulo?: string;
+}
+/** Item de `dados`: um objeto por ponto do eixo X. */
+export type DadoGrafico = Record<string, unknown>;
+/** Props comuns a todos os gráficos. */
+export interface GraficoBaseProps {
+    /** Nome acessível do gráfico (aparece acima dele). */
+    titulo: string;
+    /** Resumo em texto para leitor de tela (ex.: "Faturamento mensal de 2025, máximo em dezembro"). */
+    descricao?: string;
+    /** Altura da área do gráfico em px. Padrão `280`; a largura acompanha o container. */
+    altura?: number;
+    /** Padrão `true`. Clicar num item esconde ou mostra a série. */
+    legenda?: boolean;
+    carregando?: boolean;
+    /** Sem dados, mostra o `Vazio` com este texto. */
+    textoVazio?: string;
+    /**
+     * Anima a entrada do gráfico (linhas se desenham, barras crescem a partir do zero).
+     * Só na primeira vez que aparece, não a cada atualização dos dados, e nunca com
+     * "reduzir movimento" ligado no sistema. Padrão `false`.
+     */
+    animacao?: boolean;
+    /** Padrão `true`. Botão que alterna entre o gráfico e uma `Tabela` com os mesmos valores. */
+    verDados?: boolean;
+    className?: string;
+}

package/dist/components/Indicador/Indicador.d.ts

@@ -14,6 +14,10 @@ export interface IndicadorProps {
     variacao?: number;
     /** Qual direção é boa (verde). Padrão: `alta`; use `baixa` para despesas, rejeições… */
     variacaoBoa?: 'alta' | 'baixa';
+    /** Série para um minigráfico abaixo do valor, na cor de `cor` (ou `--graf-1`). Sem eixos: só a forma da tendência. */
+    tendencia?: number[];
+    /** Anima o minigráfico da `tendencia` ao aparecer (nunca com "reduzir movimento"). Padrão `false`. */
+    animacao?: boolean;
     /** Linha miúda abaixo do valor (ex.: "há 6 min"). */
     descricao?: ReactNode;
     /** Rodapé (variação, comparação…). */
@@ -21,7 +25,7 @@ export interface IndicadorProps {
     className?: string;
 }
 /** Card de KPI para dashboards. */
-export declare function Indicador({ rotulo, valor, icone, cor, href, aoClicar, carregando, variacao, variacaoBoa, descricao, children, className }: IndicadorProps): import("react").JSX.Element;
+export declare function Indicador({ rotulo, valor, icone, cor, href, aoClicar, carregando, variacao, variacaoBoa, tendencia, animacao, descricao, children, className }: IndicadorProps): import("react").JSX.Element;
 /** Grade responsiva de indicadores. */
 export declare function Indicadores({ children, className }: {
     children: ReactNode;