@praxisui/charts 3.0.0-beta.0 → 3.0.0-beta.2

package/README.md

@@ -110,6 +110,124 @@ export class ChartDemoComponent {
 
 See the public exports in `projects/praxis-charts/src/public-api.ts`.
 
+## Runtime Model
+
+O runtime atual de `@praxisui/charts` opera em duas trilhas principais:
+
+- `dataSource.kind = "local"` para datasets entregues diretamente ao componente
+- `dataSource.kind = "remote"` para datasets remotos, com foco canônico em `praxis.stats`
+
+No modo remoto, o componente:
+
+- emite `queryRequest`
+- chama `PraxisChartStatsApiService`
+- transforma a resposta agregada em `PraxisChartDataRow[]`
+- renderiza o estado `loading`, `empty`, `error` ou `ready`
+
+### Versão Pedagógica de Alto Nível
+
+Esta é a leitura adequada para documentação pública e landing pages.
+
+```mermaid
+sequenceDiagram
+    participant Host as Host
+    participant Chart as praxis-chart
+    participant Stats as PraxisChartStatsApiService
+    participant Backend as API Praxis Stats
+
+    Host->>Chart: fornece config local ou remote
+    alt fonte local
+        Chart->>Chart: transforma dados locais e renderiza
+    else fonte remota
+        Chart-->>Host: emite queryRequest
+        Chart->>Stats: executa consulta praxis.stats
+        Stats->>Backend: POST /stats/*
+        Backend-->>Stats: retorna buckets/pontos agregados
+        Stats-->>Chart: entrega linhas canônicas
+        Chart->>Chart: renderiza loading, ready, empty ou error
+    end
+```
+
+Leitura pedagógica:
+
+1. **O host entrega um contrato declarativo**, não opções brutas do engine.
+2. **O componente resolve a fonte de dados**: local ou remota.
+3. **Quando a fonte é remota, a integração canônica é `praxis.stats`**.
+4. **O chart renderiza estados de UX e a visualização final a partir de linhas canônicas**.
+
+### Versão Detalhada e Fiel ao Runtime Atual
+
+```mermaid
+sequenceDiagram
+    participant Host as Host
+    participant Chart as PraxisChartComponent
+    participant Mapper as Canonical Mapper / config remoto
+    participant Stats as PraxisChartStatsApiService
+    participant Backend as API /stats
+    participant Engine as Chart Engine Adapter
+
+    Host->>Chart: [config] e opcionalmente [data]
+    alt data explicito fornecido
+        Chart->>Chart: resolvedData = data input
+    else fonte local
+        Chart->>Chart: resolvedData = dataSource.items
+    else fonte remote
+        Chart->>Chart: buildRemoteSignature(config)
+        Chart-->>Host: queryRequest({ chartId, dataSource, query })
+        Chart->>Stats: execute(event, config)
+        Stats->>Stats: valida statsPath + statsRequest
+        Stats->>Backend: POST {statsPath}
+        Backend-->>Stats: envelope com data agregada
+        Stats->>Stats: converte buckets/points em PraxisChartDataRow[]
+        Stats-->>Chart: rows remotas resolvidas
+    end
+
+    Chart->>Chart: resolve loadState (loading/empty/error/ready)
+    alt ready
+        Chart->>Engine: render(host, { config, data })
+    else not ready
+        Chart->>Engine: destroy()
+    end
+```
+
+### Limites Atuais do Contrato Canônico
+
+O mapper `x-ui.chart -> PraxisChartConfig` já impõe limites importantes que precisam aparecer na documentação pública:
+
+- `source.kind` suportado hoje: `praxis.stats` e `derived`
+- `source.kind = "praxis.stats"` exige `source.resource` e `source.operation`
+- agregações suportadas: `count`, `sum`, `avg`, `min`, `max`
+- `distinct-count` ainda não está implementado
+- charts `pie` e `donut` aceitam apenas uma métrica
+- charts cartesianos `praxis.stats` podem declarar múltiplas métricas apenas em `group-by` e `timeseries`
+- `distribution` continua single-métrica
+- `combo` exige pelo menos duas métricas e, no modo `praxis.stats`, suporta apenas `group-by` ou `timeseries`
+- `axis: "secondary"` é exclusivo de `combo`
+- `selectionChange` e `crossFilter` declarativos ainda não estão implementados
+- `theme.variant` e `theme.palette` por token ainda não estão implementados
+
+## Fluxo Canonico de `praxis.stats`
+
+Quando o contrato remoto vem do mapper canônico, o caminho gerado hoje segue a forma:
+
+- `{resourcePath}/stats/group-by`
+- `{resourcePath}/stats/timeseries`
+- `{resourcePath}/stats/distribution`
+
+O `PraxisChartStatsApiService`:
+
+- monta a URL final usando `API_URL`
+- normaliza o path remoto
+- envia `statsRequest` via `POST`
+- converte buckets/pontos em linhas canônicas para o runtime do chart
+
+Observação importante:
+
+- o runtime atual assume envelope com `data`
+- `queryRequest` é emitido para observabilidade do host antes da execução remota
+- a execução remota automática hoje está acoplada a `praxis.stats`; não existe ainda um hook público de override do request dentro do componente
+- a trilha canônica `x-ui.chart -> PraxisChartConfig -> praxis.stats` já promove múltiplas métricas para charts cartesianos suportados; para evitar semântica enganosa, `combo` segue sendo o único caso com eixo secundário e mistura heterogênea de séries
+
 ## Current Scope
 
 This first published version is focused on the core runtime:
@@ -118,6 +236,16 @@ This first published version is focused on the core runtime:
 - canonical chart contracts and runtime models
 - the initial ECharts-based engine adapter
 - metadata and mapping hooks for registry and dynamic widget composition
+- remote execution focused on canonical `praxis.stats`
+
+## Current Non-Goals
+
+The current runtime does not yet expose as stable public surface:
+
+- direct host control over raw ECharts options as the primary contract
+- declarative cross-filter orchestration
+- declarative selectionChange runtime actions
+- palette token indirection or theme variants from `x-ui.chart`
 
 ## Notes for Hosts