@bluemarble/bi 0.0.0-stage → 0.1.0

package/dist/client/index.d.ts

@@ -0,0 +1,410 @@
+import { F as ModelMeta, N as MeasureMeta, P as ModelDef, _ as ChartDef, a as DashboardResult, i as DashboardQueryDebug, l as FilterValue, n as DashboardFilters$1, o as DashboardRow, r as DashboardQuery, y as ChartsLayout } from "../types-CB4sK4jP.js";
+import { ComponentType, ReactNode } from "react";
+//#region src/client/BarChart.d.ts
+type BarChartProps = {
+  /** Dimensão das categorias. */
+  dimension: string;
+  /** Uma série por medida (cores fixas pela posição). */
+  measures: string[];
+  /** `horizontal` cabe nomes longos; com muitas categorias, rola dentro da altura. */
+  orientation?: 'vertical' | 'horizontal';
+  /** Empilha as séries (só faz sentido com partes de um total). */
+  stacked?: boolean;
+  /** `dimension` = ordem da consulta; `desc`/`asc` = pela primeira medida. */
+  sort?: 'dimension' | 'desc' | 'asc';
+  /** Só os N primeiros depois de ordenar. */
+  limit?: number;
+  formatDimension?: (value: FilterValue) => string;
+  /** Esconde categorias sem valor em nenhuma medida. */
+  hideEmpty?: boolean;
+  /** Valores nas pontas das barras (até 30 categorias; acima disso, só tooltip). */
+  showValues?: boolean;
+  clickToFilter?: boolean;
+  height?: number;
+  /** Nome da consulta no devtools. */
+  queryLabel?: string;
+};
+/**
+ * Barras de uma ou mais medidas por uma dimensão. Ex.:
+ * `<BarChart dimension="navio" measures={['custoTotal']} orientation="horizontal" sort="desc" limit={10} />`.
+ */
+declare function BarChart({ dimension, measures, orientation, stacked, sort, limit, formatDimension, hideEmpty, showValues, clickToFilter, height, queryLabel }: BarChartProps): import("react").JSX.Element;
+//#endregion
+//#region src/client/ComboChart.d.ts
+type ComboChartProps = {
+  /** Dimensão do eixo X. */
+  dimension: string;
+  /** Medida das barras. */
+  bar: string;
+  /** Medida da linha (eixo próprio, oculto; os valores aparecem nos pontos). */
+  line: string;
+  /** Medida extra mostrada como segunda linha do rótulo da barra (ex.: volume). */
+  detail?: string;
+  /** Rótulos e formatos: sem a prop, vale o dicionário do modelo (`label`, `format`). */
+  barLabel?: string;
+  lineLabel?: string;
+  detailLabel?: string;
+  formatDimension?: (value: FilterValue) => string;
+  formatBar?: (value: number) => string;
+  formatLine?: (value: number) => string;
+  formatDetail?: (value: number) => string;
+  /** Esconde grupos cuja medida da barra é vazia/zero (como o Power BI faz). */
+  hideEmpty?: boolean;
+  height?: number;
+  /** Rótulos de dados só até essa quantidade de barras (acima disso, só tooltip). */
+  maxLabels?: number;
+  barColor?: string;
+  lineColor?: string;
+  /**
+   * Clicar numa barra filtra o dashboard pelo valor dela (Ctrl/Cmd+clique acumula; clicar de novo
+   * no único selecionado ou fora das barras limpa). O próprio gráfico ignora esse filtro e só
+   * destaca a seleção, como o filtro cruzado do Power BI.
+   */
+  clickToFilter?: boolean;
+  /** Nome da consulta no devtools (padrão: `ComboChart · <dimensão>`). */
+  queryLabel?: string;
+};
+/**
+ * Barras + linha de uma dimensão, consultando o modelo do `DashboardProvider` (com os filtros dele).
+ * Ex.: `<ComboChart dimension="mes" bar="custoTotal" line="custoTon" detail="volTotal" />`.
+ */
+declare function ComboChart({ dimension, bar, line, detail, barLabel, lineLabel, detailLabel, formatDimension, formatBar, formatLine, formatDetail, hideEmpty, height, maxLabels, barColor, lineColor, clickToFilter, queryLabel }: ComboChartProps): import("react").JSX.Element;
+//#endregion
+//#region src/client/chartKit.d.ts
+/**
+ * Peças comuns dos gráficos ligados ao modelo: paleta, filtro por clique, legenda e os estados de
+ * carregando/erro/vazio.
+ */
+/**
+ * Paleta categórica, sempre nesta ordem (a série N tem sempre a mesma cor). Laranja Rocha primeiro;
+ * a ordem passa no validador de daltonismo (CVD ΔE ≥ 9 entre vizinhas) e de visão normal (≥ 19).
+ */
+declare const SERIES_COLORS: readonly ['#F58220', '#2a78d6', '#1baf7a', '#eda100', '#e87ba4', '#008300', '#6250d6', '#e34948'];
+/** "Outros" (fatias agrupadas) fica neutro, fora da paleta. */
+declare const OTHER_COLOR = "#9e9e9e";
+//#endregion
+//#region src/client/DashboardCanvas.d.ts
+type DashboardCanvasProps = {
+  /** O mesmo layout do `<DashboardCharts>` (`canvas` do JSON). */
+  layout: ChartsLayout;
+  children: ReactNode;
+};
+/**
+ * Tela de tamanho fixo (`layout.canvas`, ex.: 1920×1080): desenha os filhos nessa largura e escala
+ * tudo para caber na largura disponível, mantendo a proporção — numa tela menor o dashboard encolhe
+ * em vez de reorganizar os gráficos. Sem `canvas` no layout, só renderiza os filhos (responsivo).
+ *
+ * ```tsx
+ * <DashboardCanvas layout={layout}>
+ *   <DashboardFilters layout={layout} />
+ *   <DashboardCharts layout={layout} />
+ * </DashboardCanvas>
+ * ```
+ *
+ * A escala é um `transform`: os gráficos continuam medindo o tamanho de projeto (o Recharts compensa
+ * a escala no mouse) e os breakpoints do MUI, que olham a janela, ficam desligados no grid.
+ */
+declare function DashboardCanvas({ layout, children }: DashboardCanvasProps): import("react").JSX.Element;
+//#endregion
+//#region src/client/DashboardCharts.d.ts
+type ChartPanelProps = {
+  title: string;
+  chart: ChartDef;
+  children: ReactNode;
+};
+type DashboardChartsProps = {
+  /** Layout importado do JSON (`src/dashboard/layouts/<id>.json`). */
+  layout: ChartsLayout;
+  /** Formatters por nome, referenciados no JSON por `formatDimension`. */
+  formatters?: Record<string, (value: FilterValue) => string>;
+  /** Moldura de cada gráfico (título + conteúdo). */
+  panel?: ComponentType<ChartPanelProps>;
+  gap?: number;
+};
+/**
+ * Renderiza os gráficos de um layout declarativo num grid de 12 colunas (no celular, um por linha;
+ * dentro de um `<DashboardCanvas>` de tamanho fixo, sempre as 12). Em desenvolvimento, a aba
+ * Layout do devtools edita esse layout ao vivo (rascunho) e grava o JSON de volta.
+ *
+ * ```tsx
+ * import layout from '@/dashboard/layouts/analiseCusto.json'
+ * <DashboardCharts layout={layout as ChartsLayout} formatters={{ nomeMes }} panel={Panel} />
+ * ```
+ */
+declare function DashboardCharts({ layout, formatters, panel: Panel, gap }: DashboardChartsProps): import("react").JSX.Element;
+//#endregion
+//#region src/client/DashboardFilters.d.ts
+type DashboardFiltersProps = {
+  /** O mesmo layout do `<DashboardCharts>` (`filters` do JSON). */
+  layout: ChartsLayout;
+  /** Formatters por nome, referenciados no JSON por `formatLabel`. */
+  formatters?: Record<string, (value: FilterValue) => string>;
+  gap?: number;
+};
+/**
+ * Filtros (slicers) declarados em `layout.filters`, na ordem. Em desenvolvimento, a aba Layout do
+ * devtools adiciona, remove, reordena e edita os filtros ao vivo.
+ */
+declare function DashboardFilters({ layout, formatters, gap }: DashboardFiltersProps): import("react").JSX.Element;
+//#endregion
+//#region src/devtools/layoutStore.d.ts
+/**
+ * Layouts montados na página (`<DashboardCharts>` / `<DashboardFilters>`) e o rascunho de cada um,
+ * editado na aba Layout do devtools. Store externo como o de consultas: editar um gráfico
+ * re-renderiza só os componentes daquele layout e o painel.
+ */
+/** Parte do layout que um componente renderiza. */
+type LayoutPart = 'charts' | 'filters' | 'canvas';
+type LayoutEntry = {
+  /** O layout que veio do arquivo (o que a página passou ao `<DashboardCharts>`). */
+  registered: ChartsLayout;
+  /** Rascunho editado no devtools; `null` = página usando o registrado. */
+  draft: ChartsLayout | null;
+  /**
+   * Partes montadas na página e os formatters que cada uma recebeu (`formatDimension`,
+   * `formatLabel`). Parte ausente = a página não renderiza (ex.: sem `<DashboardFilters>`).
+   */
+  parts: Partial<Record<LayoutPart, string[]>>;
+};
+declare function createLayoutStore(): {
+  subscribe(listener: () => void): () => boolean;
+  getSnapshot: () => LayoutEntry[];
+  get: (id: string) => LayoutEntry | null;
+  /** Rascunho do layout, mesmo antes de registrar (evita renderizar o registrado e trocar). */
+  draftOf(layout: ChartsLayout): ChartsLayout | null;
+  /** Chamado pelo `<DashboardCharts>`/`<DashboardFilters>` ao montar e quando o arquivo muda (HMR). */
+  register(layout: ChartsLayout, part: LayoutPart, formatters: string[]): () => void;
+  setDraft: (id: string, next: ChartsLayout | null) => void;
+};
+type LayoutStore = ReturnType<typeof createLayoutStore>;
+//#endregion
+//#region src/devtools/store.d.ts
+/**
+ * Registro das consultas feitas pelos componentes (`useModelQuery`), lido pelo painel do devtools.
+ * É um store externo (`useSyncExternalStore`) para que registrar uma consulta não re-renderize a
+ * página inteira — só o painel.
+ */
+type RunStatus = 'loading' | 'success' | 'error' | 'cancelled';
+type QueryRun = {
+  runId: number;
+  instanceId: string;
+  label: string;
+  query: DashboardQuery;
+  status: RunStatus;
+  startedAt: number;
+  /** Ida e volta medida no browser. */
+  durationMs?: number;
+  rows?: DashboardRow[];
+  error?: string;
+  debug?: DashboardQueryDebug;
+};
+type TrackedInstance = {
+  instanceId: string;
+  label: string;
+  runs: number;
+  last: QueryRun;
+  /** Refeita muitas vezes em pouco tempo: sinal de re-render em loop (ex.: array novo a cada render). */
+  storm: boolean;
+};
+type DevtoolsSnapshot = {
+  instances: TrackedInstance[];
+  /** Execuções mais recentes primeiro. */
+  history: QueryRun[];
+};
+declare function createDevtoolsStore(): {
+  subscribe(listener: () => void): () => boolean;
+  getSnapshot: () => DevtoolsSnapshot;
+  start(instanceId: string, label: string, query: DashboardQuery): number;
+  succeed: (runId: number, rows: DashboardRow[], debug?: DashboardQueryDebug) => void;
+  fail: (runId: number, error: unknown) => void;
+  /** Consulta descartada antes de responder (filtro mudou, componente desmontou). */
+  cancel: (runId: number) => void;
+  remove(instanceId: string): void;
+  /** Avisa que todas as consultas vão refazer agora, de propósito. */
+  expectRefetch(): void;
+  /** Zera os alertas de loop (depois de corrigir o componente, sem recarregar a página). */
+  resetStorms(): void;
+  clearHistory(): void;
+};
+type DevtoolsStore = ReturnType<typeof createDevtoolsStore>;
+//#endregion
+//#region src/client/DashboardProvider.d.ts
+type DashboardFetcher = (query: DashboardQuery) => Promise<DashboardResult>;
+/** Só existe com o devtools ligado. */
+type DashboardDevtoolsContext = {
+  store: DevtoolsStore;
+  /** Layouts da página (`<DashboardCharts>`/`<DashboardFilters>`) e os rascunhos da aba Layout. */
+  layouts: LayoutStore;
+  /** Consulta o modelo registrado, ignorando o rascunho (comparações, snapshots). */
+  rawFetcher: DashboardFetcher;
+  /** Rascunho do modelo aplicado: todas as consultas da página passam a usá-lo. */
+  draft: ModelDef | null;
+  setDraft: (draft: ModelDef | null) => void;
+  /** Refaz todas as consultas da página. */
+  refresh: () => void;
+  defaultFilters: DashboardFilters$1;
+  setFilters: (filters: DashboardFilters$1) => void;
+};
+type DashboardContextValue = {
+  model: string;
+  filters: DashboardFilters$1;
+  setFilter: (dimension: string, values: FilterValue[]) => void;
+  fetcher: DashboardFetcher;
+  /** Dicionário do modelo (rótulos, descrições, formatos); `null` até carregar. */
+  meta: ModelMeta | null;
+  /** Muda quando o devtools pede para refazer as consultas. */
+  refreshKey: number;
+  devtools: DashboardDevtoolsContext | null;
+};
+type DashboardProviderProps = {
+  /** Nome do modelo no servidor (chave do registro de modelos do app). */
+  model: string;
+  /** Como chamar o endpoint do app (ex.: `(q) => api.post('/dashboard/query', q).then((r) => r.data)`). */
+  fetcher: DashboardFetcher;
+  defaultFilters?: DashboardFilters$1;
+  /**
+   * Painel de desenvolvimento (debug das consultas, edição do modelo). Padrão: ligado só com
+   * `NODE_ENV=development`. O endpoint também precisa de `runQuery(..., { devtools: true })`.
+   */
+  devtools?: boolean;
+  children: ReactNode;
+};
+/**
+ * Guarda os filtros do dashboard. Todo componente dentro dele (filtros, gráficos, tabelas) consulta o
+ * mesmo modelo com os mesmos filtros — é o que faz um slicer filtrar a página inteira, como no BI.
+ */
+declare function DashboardProvider({ model, fetcher, defaultFilters, devtools, children }: DashboardProviderProps): import("react").JSX.Element;
+declare function useDashboard(): DashboardContextValue;
+//#endregion
+//#region src/client/DataTable.d.ts
+type SortDirection = 'asc' | 'desc';
+type DataTableProps = {
+  /** Uma linha por combinação de dimensões (sem dimensões, uma linha só). */
+  dimensions?: string[];
+  /** Uma coluna por medida, formatada pelo dicionário do modelo. */
+  measures: string[];
+  /** Formatter por dimensão. */
+  formatDimensions?: Record<string, (value: FilterValue) => string>;
+  /**
+   * Linha de total, consultada sem as dimensões: razões (custo/t) saem do total, não da soma das
+   * linhas.
+   */
+  showTotal?: boolean;
+  /** Coluna da ordem inicial (dimensão ou medida); quem usa reordena clicando no cabeçalho. */
+  sortBy?: string;
+  sortDirection?: SortDirection;
+  /** Clicar numa linha filtra o dashboard pela primeira dimensão. */
+  clickToFilter?: boolean;
+  /** Altura máxima; a tabela rola com o cabeçalho fixo. */
+  height?: number;
+  /** Nome da consulta no devtools. */
+  queryLabel?: string;
+};
+/**
+ * Tabela de medidas por dimensões, com total e ordenação pelo cabeçalho. Ex.:
+ * `<DataTable dimensions={['navio']} measures={['volTotal', 'custoTotal', 'custoTon']} />`.
+ */
+declare function DataTable({ dimensions, measures, formatDimensions, showTotal, sortBy, sortDirection, clickToFilter, height, queryLabel }: DataTableProps): import("react").JSX.Element;
+//#endregion
+//#region src/client/DonutChart.d.ts
+type DonutChartProps = {
+  /** Dimensão das fatias. */
+  dimension: string;
+  /** Medida somável (partes de um total). Valores negativos ou zerados ficam de fora. */
+  measure: string;
+  /** Fatias além dessa quantidade viram "Outros" (no máximo 8, o tamanho da paleta). */
+  maxSlices?: number;
+  formatDimension?: (value: FilterValue) => string;
+  clickToFilter?: boolean;
+  height?: number;
+  /** Nome da consulta no devtools. */
+  queryLabel?: string;
+};
+/**
+ * Rosca de uma medida por uma dimensão, com o total no centro e a legenda ao lado (nome, % e valor).
+ * Ex.: `<DonutChart dimension="operacao_status" measure="custoTotal" />`.
+ */
+declare function DonutChart({ dimension, measure, maxSlices, formatDimension, clickToFilter, height, queryLabel }: DonutChartProps): import("react").JSX.Element;
+//#endregion
+//#region src/client/FilterSelect.d.ts
+type FilterSelectProps = {
+  dimension: string;
+  /** Padrão: `label` da dimensão no dicionário do modelo. */
+  label?: string;
+  formatLabel?: (value: FilterValue) => string;
+  width?: number;
+};
+/**
+ * Filtro de múltipla escolha de uma dimensão. As opções vêm do próprio modelo e respeitam os
+ * DEMAIS filtros (filtro cruzado): com Mês = Janeiro, o filtro de navio só lista quem atracou em
+ * janeiro. Nada selecionado = "Todos".
+ */
+declare function FilterSelect({ dimension, label, formatLabel, width }: FilterSelectProps): import("react").JSX.Element;
+//#endregion
+//#region src/client/format.d.ts
+declare function formatNumber(value: number | string | null | undefined, decimals?: number): string;
+declare const formatCurrency: (value: number | string | null | undefined, decimals?: number) => string;
+/**
+ * Formata pelo dicionário do modelo (`format`/`decimals` da medida). `fallbackDecimals` é o padrão
+ * do componente quando a medida não define `decimals`.
+ */
+declare function formatMeasure(value: number | string | null | undefined, meta: MeasureMeta | undefined, fallbackDecimals?: number): string;
+/** Formatter de uma medida pelo dicionário do modelo; sem `format`, número com `fallbackDecimals`. */
+declare function measureFormatter(meta: ModelMeta | null, measure: string, fallbackDecimals?: number): (value: number | string | null | undefined) => string;
+//#endregion
+//#region src/client/KpiCard.d.ts
+type KpiCardProps = {
+  /** Medida do número grande: o total com os filtros da página. */
+  measure: string;
+  /** Rótulo acima do número (no `<DashboardCharts>`, o título do painel faz esse papel). */
+  label?: string;
+  /** Medida extra numa linha menor embaixo (ex.: volume, custo/t). */
+  secondary?: string;
+  /** Padrão: `label` da medida secundária no dicionário. */
+  secondaryLabel?: string;
+  /** Nome da consulta no devtools. */
+  queryLabel?: string;
+};
+/**
+ * Card com o total de uma medida (e, opcionalmente, uma segunda medida embaixo). Uma consulta sem
+ * dimensões: razões (custo/t) saem do total, não de uma média. Ex.:
+ * `<KpiCard label="Custo total" measure="custoTotal" secondary="custoTon" />`.
+ */
+declare function KpiCard({ measure, label, secondary, secondaryLabel, queryLabel }: KpiCardProps): import("react").JSX.Element;
+//#endregion
+//#region src/client/ModelDictionary.d.ts
+/**
+ * Dicionário do modelo do `DashboardProvider`: o que cada filtro/eixo e cada número significa. É
+ * montado a partir de `label`/`description` das dimensões e medidas — documentação que não
+ * desatualiza, porque é a mesma definição que calcula os números.
+ */
+declare function ModelDictionary(): import("react").JSX.Element | null;
+//#endregion
+//#region src/client/useModelQuery.d.ts
+declare const INSPECT_ATTRIBUTE = "data-bm-dashboard-query";
+type UseModelQueryParams = {
+  dimensions?: string[];
+  measures?: string[];
+  /**
+   * Filtros do dashboard que esta consulta NÃO deve respeitar. Um filtro ignora a si mesmo para
+   * listar as opções (senão, ao escolher um navio, a lista mostraria só ele).
+   */
+  ignoreFilters?: string[];
+  /** Nome da consulta no devtools (padrão: dimensões × medidas). */
+  label?: string;
+  /** Não consulta (devolve `rows: []`); ex.: a linha de total de uma tabela que não mostra total. */
+  skip?: boolean;
+};
+declare function useModelQuery({ dimensions, measures, ignoreFilters, label, skip }: UseModelQueryParams): {
+  rows: DashboardRow[];
+  isLoading: boolean;
+  error: unknown;
+  inspectProps: {
+    "data-bm-dashboard-query": string;
+  } | {
+    "data-bm-dashboard-query"?: undefined;
+  };
+};
+//#endregion
+export { BarChart, type ChartPanelProps, ComboChart, DashboardCanvas, DashboardCharts, type DashboardFetcher, DashboardFilters, DashboardProvider, DataTable, DonutChart, FilterSelect, INSPECT_ATTRIBUTE, KpiCard, ModelDictionary, OTHER_COLOR, SERIES_COLORS, formatCurrency, formatMeasure, formatNumber, measureFormatter, useDashboard, useModelQuery };
+//# sourceMappingURL=index.d.ts.map