@bluemarble/bi 0.7.0 → 0.8.1

package/README.md

@@ -1,77 +1,77 @@
-# bm-bi (`@bluemarble/bi`)
-
-Camada semântica para dashboards em React, no lugar do Power BI: o modelo (tabelas,
-relacionamentos, dimensões e medidas) é um objeto TS (`defineModel`), o servidor compila as
-consultas para SQL (MySQL/MariaDB) e os componentes de filtro e gráfico consultam o modelo pelo
-nome. Vem com um devtools (diagrama do modelo, editor de layout, playground, regressão).
-
-```ts
-import { defineModel, formula, sum } from '@bluemarble/bi/server'
-
-export const vendas = defineModel({
-  name: 'vendas',
-  tables: {
-    pedidos: { key: 'id', sql: 'SELECT id, loja, criado_em FROM pedidos' },
-    itens: { sql: 'SELECT pedido_id, valor FROM itens' }
-  },
-  relationships: [{ from: 'itens.pedido_id', to: 'pedidos.id' }],
-  dimensions: { loja: { sql: 'pedidos.loja', type: 'string' } },
-  measures: { valor: sum('itens.valor', { format: 'currency' }) }
-})
-```
-
-| Import                  | Onde roda      |
-| ----------------------- | -------------- |
-| `@bluemarble/bi/server` | só no servidor |
-| `@bluemarble/bi/client` | browser        |
-| `@bluemarble/bi/types`  | ambos          |
-
-```bash
-npm install @bluemarble/bi   # peer: react 19, @mui/material 7, recharts 3
-```
-
-Publicado no npm já compilado (`dist/`, ESM + `.d.ts`), sem precisar de `transpilePackages`.
-Conceitos, API, devtools e configuração do app estão em
-[`docs/dashboard-substituicao-powerbi.md`](docs/dashboard-substituicao-powerbi.md).
-
-## Desenvolvimento
-
-Projeto Vite+ com bun.
-
-```bash
-vp install        # dependências
-vp test           # testes (vitest, sem banco)
-vp run typecheck  # tsc
-vp check          # formatação (oxfmt) + lint (oxlint)
-vp run playground # dashboard + devtools em http://localhost:5180 (precisa do .env)
-```
-
-### Playground
-
-`playground/` é uma página Vite com o dashboard e o devtools ligados direto ao `src/` (sem passar
-pelo app). O endpoint `/api/dashboard/query` roda no próprio servidor do Vite e consulta o MySQL do
-`DATABASE_URL` do `.env` na raiz (modelo em `.env.example`; o `.env` não é versionado).
-
-- `playground/models/` — modelos (`defineModel`), registrados em `models/index.ts`;
-- `playground/layouts/` — layouts JSON dos gráficos/filtros;
-- `playground/dashboards.ts` — lista do seletor no topo (modelo + layout + filtros iniciais) e formatters.
-
-O "Salvar no arquivo" do devtools grava nessas pastas (formatando com `vp fmt`) e os snapshots vão
-para `playground/snapshots/`. Mudanças em modelos valem na consulta seguinte, sem reiniciar.
-
-### Testar no app antes de publicar
-
-Para usar a versão local num app (ex.: o `custo` do `rocha-pr`), aponte a dependência para esta
-pasta (`"@bluemarble/bi": "file:../../../bm-bi"` + `npm install`) e deixe `vp run dev` rodando
-(`vp pack --watch`): o app lê o `dist/`. Com o link, o Next precisa de `turbopack.root` e
-`turbopack.resolveAlias` — o `next.config.js` do `custo` liga isso sozinho quando detecta o link.
-
-## Publicar
-
-```bash
-vp run verify     # o mesmo que o CI roda: check, typecheck, testes e build
-vp run release    # bumpp: escolhe a versão, commita, cria a tag vX.Y.Z e faz push
-```
-
-A tag dispara `.github/workflows/publish.yml`, que confere tag x `package.json`, roda o `verify` e
-publica com `bun publish` (secret `NPM_TOKEN`). Depois, no app: `npm install @bluemarble/bi@X.Y.Z`.
+# bm-bi (`@bluemarble/bi`)
+
+Camada semântica para dashboards em React, no lugar do Power BI: o modelo (tabelas,
+relacionamentos, dimensões e medidas) é um objeto TS (`defineModel`), o servidor compila as
+consultas para SQL (MySQL/MariaDB) e os componentes de filtro e gráfico consultam o modelo pelo
+nome. Vem com um devtools (diagrama do modelo, editor de layout, playground, regressão).
+
+```ts
+import { defineModel, formula, sum } from '@bluemarble/bi/server'
+
+export const vendas = defineModel({
+  name: 'vendas',
+  tables: {
+    pedidos: { key: 'id', sql: 'SELECT id, loja, criado_em FROM pedidos' },
+    itens: { sql: 'SELECT pedido_id, valor FROM itens' }
+  },
+  relationships: [{ from: 'itens.pedido_id', to: 'pedidos.id' }],
+  dimensions: { loja: { sql: 'pedidos.loja', type: 'string' } },
+  measures: { valor: sum('itens.valor', { format: 'currency' }) }
+})
+```
+
+| Import                  | Onde roda      |
+| ----------------------- | -------------- |
+| `@bluemarble/bi/server` | só no servidor |
+| `@bluemarble/bi/client` | browser        |
+| `@bluemarble/bi/types`  | ambos          |
+
+```bash
+npm install @bluemarble/bi   # peer: react 19, @mui/material 7, recharts 3
+```
+
+Publicado no npm já compilado (`dist/`, ESM + `.d.ts`), sem precisar de `transpilePackages`.
+Conceitos, API, devtools e configuração do app estão em
+[`docs/dashboard-substituicao-powerbi.md`](docs/dashboard-substituicao-powerbi.md).
+
+## Desenvolvimento
+
+Projeto Vite+ com bun.
+
+```bash
+vp install        # dependências
+vp test           # testes (vitest, sem banco)
+vp run typecheck  # tsc
+vp check          # formatação (oxfmt) + lint (oxlint)
+vp run playground # dashboard + devtools em http://localhost:5180 (precisa do .env)
+```
+
+### Playground
+
+`playground/` é uma página Vite com o dashboard e o devtools ligados direto ao `src/` (sem passar
+pelo app). O endpoint `/api/dashboard/query` roda no próprio servidor do Vite e consulta o MySQL do
+`DATABASE_URL` do `.env` na raiz (modelo em `.env.example`; o `.env` não é versionado).
+
+- `playground/models/` — modelos (`defineModel`), registrados em `models/index.ts`;
+- `playground/layouts/` — layouts JSON dos gráficos/filtros;
+- `playground/dashboards.ts` — lista do seletor no topo (modelo + layout + filtros iniciais) e formatters.
+
+O "Salvar no arquivo" do devtools grava nessas pastas (formatando com `vp fmt`) e os snapshots vão
+para `playground/snapshots/`. Mudanças em modelos valem na consulta seguinte, sem reiniciar.
+
+### Testar no app antes de publicar
+
+Para usar a versão local num app (ex.: o `custo` do `rocha-pr`), aponte a dependência para esta
+pasta (`"@bluemarble/bi": "file:../../../bm-bi"` + `npm install`) e deixe `vp run dev` rodando
+(`vp pack --watch`): o app lê o `dist/`. Com o link, o Next precisa de `turbopack.root` e
+`turbopack.resolveAlias` — o `next.config.js` do `custo` liga isso sozinho quando detecta o link.
+
+## Publicar
+
+```bash
+vp run verify     # o mesmo que o CI roda: check, typecheck, testes e build
+vp run release    # bumpp: escolhe a versão, commita, cria a tag vX.Y.Z e faz push
+```
+
+A tag dispara `.github/workflows/publish.yml`, que confere tag x `package.json`, roda o `verify` e
+publica com `bun publish` (secret `NPM_TOKEN`). Depois, no app: `npm install @bluemarble/bi@X.Y.Z`.