@praxisui/charts 3.0.0-beta.1 → 3.0.0-beta.10

package/README.md

@@ -11,6 +11,8 @@
 ## What this package provides
 
 - `PraxisChartComponent` for standalone chart rendering
+- `PraxisChartConfigEditor` as the initial authoring shell for canonical `x-ui.chart` documents
+- optional runtime authoring bridge from `PraxisChartComponent` into the chart config editor when the host provides a settings-panel bridge
 - typed chart contracts for config, datasets, events and widget mapping
 - internal Apache ECharts adapter behind a Praxis engine interface
 - built-in `loading`, `empty` and `error` states
@@ -32,7 +34,7 @@ npm i @praxisui/charts
 Peer dependencies (Angular v20):
 - `@angular/core` `^20.0.0`
 - `@angular/common` `^20.0.0`
-- `@praxisui/core` `^1.0.0-beta.68`
+- `@praxisui/core` `^3.0.0-beta.2`
 
 Runtime dependency included by this package:
 - `echarts` `^6.0.0`
@@ -104,12 +106,153 @@ export class ChartDemoComponent {
 ## Public Surface Highlights
 
 - standalone components for charts, drilldown panel and runtime probe
+- the initial standalone chart config editor shell for `x-ui.chart`
 - chart contracts such as `PraxisChartConfig`, `PraxisChartDataSource` and `PraxisChartPointEvent`
 - providers and tokens for chart engine composition
 - services for canonical mapping, backend payload adaptation and option building
 
 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`
+
+## Declarative Query Contract
+
+For dynamic pages and widget orchestration, the primary public input for remote chart queries is `queryContext`.
+
+```html
+<praxis-chart
+  [config]="chartConfig"
+  [queryContext]="{
+    filters: { departmentId: 10, status: 'ACTIVE' },
+    sort: ['competencia,asc'],
+    limit: 12
+  }"
+></praxis-chart>
+```
+
+Current rules:
+
+- `queryContext.filters` is merged into remote datasource requests
+- `queryContext.sort` and `queryContext.limit` are also propagated when the datasource path supports them
+- `filterCriteria` is still accepted as a legacy compatibility bridge
+- for new authoring, `DynamicPage` connections and examples, prefer `queryContext`
+
+### 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 +261,18 @@ 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`
+- basic settings-panel-compatible authoring shell focused on canonical `x-ui.chart`
+- optional runtime edit affordance in `PraxisChartComponent` when `chartDocument` and a settings-panel bridge are available
+
+## 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