@actionexec/dashboards 0.16.2 → 0.18.0

package/README.md

@@ -1,71 +1,90 @@
-# @actionexec/dashboards
-
-Biblioteca React para consumo de dashboards e demonstrativos servidos pela
-plataforma Action. Dedicada as APIs `/external/dashboards` e
-`/external/statements` — zero configuracao, so passe o token.
-
-## Instalacao
-
-```bash
-npm install @actionexec/dashboards
-```
-
-Peer deps: `react`, `react-dom`, `recharts`, `react-datepicker`.
-
-## Uso
-
-```tsx
-import { Dashboard, Statement } from '@actionexec/dashboards';
-import '@actionexec/dashboards/styles.css';
-
-export function App() {
-  return (
-    <>
-      <Dashboard token="token-do-dashboard" />
-      <Statement token="token-do-demonstrativo" />
-    </>
-  );
-}
-```
-
-Cada token responde por um recurso: o do dashboard nao abre um demonstrativo e
-vice-versa.
-
-## API publica
-
-### `<Dashboard>`
-
-Renderiza um dashboard completo com interatividade (filtros, variaveis, paleta).
-
-| Prop | Tipo | Default | Descricao |
-|---|---|---|---|
-| `token` | `string` | — | Token Bearer do dashboard (obrigatorio) |
-| `cellAspect` | `number` | `1` | Proporcao largura/altura da celula do grid |
-| `stackBelow` | `number \| 'auto'` | — | Largura (px) abaixo da qual os widgets empilham em coluna unica; `'auto'` usa o limiar natural do layout; ausente nunca empilha |
-| `onGeometryChange` | `(g: DashboardGeometry) => void` | — | Notificado a cada mudanca de medida — util para hosts de altura fixa |
-| `silenceWarnings` | `boolean` | `false` | Desliga o aviso de corte emitido no console |
-| `className` | `string` | — | Classe CSS adicional no container raiz |
-
-### `<Statement>`
-
-Renderiza um demonstrativo completo — linhas x colunas de periodo, com janela de
-datas ajustavel e download em PDF.
-
-| Prop | Tipo | Default | Descricao |
-|---|---|---|---|
-| `token` | `string` | — | Token Bearer do demonstrativo (obrigatorio) |
-| `palette` | `string[]` | paleta Action | Paleta de 15 cores, no formato do dashboard — para quem embute os dois lado a lado |
-| `showDownload` | `boolean` | `true` | Exibe o botao de download do PDF |
-| `className` | `string` | — | Classe CSS adicional no container raiz |
-
-Todos os valores sao computados no servidor: o componente nao agrega, nao
-formata numero e nao avalia formula. E o que garante que o documento exibido aqui
-seja identico ao do construtor da plataforma e ao PDF baixado.
-
-A altura do documento acompanha o numero de linhas; a largura rola na horizontal
-quando ha mais colunas de periodo do que cabem.
-
-### `ApiError`
-
-Erro lancado internamente quando a API retorna status != 2xx. Exposto para quem
-quiser fazer error boundary customizada em torno dos componentes.
+# @actionexec/dashboards
+
+Biblioteca React para consumo de dashboards e demonstrativos servidos pela
+plataforma Action. Dedicada as APIs `/external/dashboards` e
+`/external/statements` — zero configuracao, so passe o token.
+
+## Instalacao
+
+```bash
+npm install @actionexec/dashboards
+```
+
+Peer deps: `react`, `react-dom`, `recharts`, `react-datepicker`.
+
+## Uso
+
+```tsx
+import { Dashboard, Statement } from '@actionexec/dashboards';
+import '@actionexec/dashboards/styles.css';
+
+export function App() {
+  return (
+    <>
+      <Dashboard token="token-do-dashboard" />
+      <Statement token="token-do-demonstrativo" />
+    </>
+  );
+}
+```
+
+Cada token responde por um recurso: o do dashboard nao abre um demonstrativo e
+vice-versa.
+
+## API publica
+
+### `<Dashboard>`
+
+Renderiza um dashboard completo com interatividade (filtros, variaveis, paleta).
+
+| Prop | Tipo | Default | Descricao |
+|---|---|---|---|
+| `token` | `string` | — | Token Bearer do dashboard (obrigatorio) |
+| `cellAspect` | `number` | `1` | Proporcao largura/altura da celula do grid |
+| `stackBelow` | `number \| 'auto'` | — | Largura (px) abaixo da qual os widgets empilham em coluna unica; `'auto'` usa o limiar natural do layout; ausente nunca empilha |
+| `onGeometryChange` | `(g: DashboardGeometry) => void` | — | Notificado a cada mudanca de medida — util para hosts de altura fixa |
+| `silenceWarnings` | `boolean` | `false` | Desliga o aviso de corte emitido no console |
+| `className` | `string` | — | Classe CSS adicional no container raiz |
+
+### `<Statement>`
+
+Renderiza um demonstrativo completo — linhas x colunas de periodo, com janela de
+datas ajustavel e download em PDF.
+
+| Prop | Tipo | Default | Descricao |
+|---|---|---|---|
+| `token` | `string` | — | Token Bearer do demonstrativo (obrigatorio) |
+| `palette` | `string[]` | paleta Action | Paleta de 15 cores, no formato do dashboard — para quem embute os dois lado a lado |
+| `showDownload` | `boolean` | `true` | Exibe o botao de download do PDF |
+| `layout` | `'auto' \| 'table' \| 'periods'` | `'auto'` | Como o documento se desenha: a folha de colunas (`table`), um periodo por vez com seletor (`periods`), ou a escolha pela largura do container raiz (`auto`: `periods` abaixo de 600 px, `table` acima; sem `ResizeObserver` fica em `table`) |
+| `className` | `string` | — | Classe CSS adicional no container raiz |
+
+Todos os valores sao computados no servidor: o componente nao agrega, nao
+formata numero e nao avalia formula. E o que garante que o documento exibido aqui
+seja identico ao do construtor da plataforma e ao PDF baixado.
+
+A folha vive num viewport com scroll nos dois eixos (a barra horizontal fica na
+borda visivel, nao no fundo da tabela) e uma faixa de periodos no topo, que marca
+a coluna mais a vista. Secoes com recuo se recolhem na tela; o PDF continua com o
+documento inteiro.
+
+**Abaixo de 600 px** (`layout="auto"` num celular, ou `layout="periods"`) a folha
+da lugar a um periodo por vez: seletor com setas de 40 px e um `<select>` nativo
+com todas as colunas (a de total por ultimo, quando o documento a tem), e uma
+lista de duas colunas com o rotulo e o valor do periodo escolhido. Embaixo do
+valor vai a variacao contra o periodo anterior (o percentual da analise
+horizontal quando o documento a pede; senao, o valor anterior), que o toggle
+"Comparar com o anterior" liga e desliga. Recolher e expandir secoes e o mesmo
+estado nos dois modos: girar o celular nao desfaz o que o leitor abriu. O
+container raiz recebe `stmt--table` ou `stmt--periods` conforme o modo em vigor.
+O PDF nao muda com o modo.
+
+Na folha em pane estreito (`layout="table"` abaixo de 600 px), a barra de
+controles quebra linha, a legenda "Base" ganha uma linha propria e a coluna de
+rotulos se limita a 40% do viewport da folha, quebrando o nome da conta. Quem
+embute nao precisa mais de override proprio para isso.
+
+### `ApiError`
+
+Erro lancado internamente quando a API retorna status != 2xx. Exposto para quem
+quiser fazer error boundary customizada em torno dos componentes.