@praxisui/charts 7.0.0-beta.0 → 8.0.0-beta.1

package/README.md

@@ -57,6 +57,8 @@ import {
     <praxis-chart
       [config]="config"
       (pointClick)="onPointClick($event)"
+      (selectionChange)="onSelectionChange($event)"
+      (crossFilter)="onCrossFilter($event)"
     ></praxis-chart>
   `,
 })
@@ -95,11 +97,39 @@ export class ChartDemoComponent {
         name: 'Employees',
       },
     ],
+    interactions: {
+      pointClick: true,
+      selection: true,
+      crossFilter: true,
+      eventActions: {
+        selectionChange: {
+          action: 'emit',
+          mapping: {
+            department: 'department',
+          },
+        },
+        crossFilter: {
+          action: 'filter-widget',
+          target: 'employeesTable',
+          mapping: {
+            department: 'department',
+          },
+        },
+      },
+    },
   };
 
   onPointClick(event: PraxisChartPointEvent) {
     console.log('chart point', event);
   }
+
+  onSelectionChange(event: unknown) {
+    console.log('chart selection', event);
+  }
+
+  onCrossFilter(event: unknown) {
+    console.log('chart filters', event);
+  }
 }
 ```
 
@@ -107,7 +137,7 @@ export class ChartDemoComponent {
 
 - 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`
+- chart contracts such as `PraxisChartConfig`, `PraxisChartDataSource`, `PraxisChartPointEvent`, `PraxisChartSelectionEvent` and `PraxisChartCrossFilterEvent`
 - providers and tokens for chart engine composition
 - services for canonical mapping, backend payload adaptation and option building
 
@@ -115,7 +145,7 @@ 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:
+O runtime 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`
@@ -123,10 +153,86 @@ O runtime atual de `@praxisui/charts` opera em duas trilhas principais:
 No modo remoto, o componente:
 
 - emite `queryRequest`
-- chama `PraxisChartStatsApiService`
+- usa `remoteDataResolver` quando o host fornece um resolvedor governado
+- usa `PraxisChartStatsApiService` como resolvedor padrão para `praxis.stats`
 - transforma a resposta agregada em `PraxisChartDataRow[]`
 - renderiza o estado `loading`, `empty`, `error` ou `ready`
 
+## Sizing Modes
+
+Charts expose sizing as canonical contract, not as host CSS. New chart documents
+should use `sizing` instead of the legacy top-level `height` property.
+
+```ts
+const chartDocument: PraxisXUiChartContract = {
+  version: '0.1.0',
+  kind: 'bar',
+  chartId: 'status-by-team',
+  sizing: {
+    mode: 'fill-container',
+    minHeight: 160,
+  },
+  source: { kind: 'derived' },
+  dimensions: [{ field: 'team' }],
+  metrics: [{ field: 'total', aggregation: 'count' }],
+};
+```
+
+Supported modes:
+
+- `fixed`: uses `sizing.height`; use it for standalone charts with deliberate fixed height.
+- `fill-container`: fills the usable body of a widget shell or another container with a defined height.
+- `auto`: lets the chart content define its natural height.
+
+Sizing values may be numbers or CSS lengths. Numeric editor input is normalized
+to pixels before the runtime applies styles, so `height: 320` and an editor
+value of `320` both resolve to `320px`. `minHeight` and `maxHeight` constrain
+the chart shell, and `aspectRatio` may be a positive number or CSS ratio such
+as `16 / 9`.
+
+For corporate dashboards and resizable widget canvases, prefer
+`sizing.mode = "fill-container"` plus a documented `minHeight`. The containing
+widget shell should provide a fill body layout, otherwise the chart cannot infer
+a stable vertical area from CSS alone. Legacy `height` is normalized as
+`sizing: { mode: "fixed", height }` in the canonical mapper only as a migration
+bridge for existing beta payloads.
+
+## Surface Modes
+
+Chart visual surface is also part of the canonical contract. Hosts should not
+override the internal chart shell with ad hoc CSS when the intent is business
+semantics such as embedded dashboard rendering versus standalone rendering.
+
+```ts
+const chartDocument: PraxisXUiChartContract = {
+  version: '0.1.0',
+  kind: 'bar',
+  chartId: 'status-by-team',
+  sizing: {
+    mode: 'fill-container',
+    minHeight: 160,
+  },
+  theme: {
+    surface: {
+      mode: 'embedded',
+    },
+  },
+  source: { kind: 'derived' },
+  dimensions: [{ field: 'team' }],
+  metrics: [{ field: 'total', aggregation: 'count' }],
+};
+```
+
+Supported surface modes:
+
+- `auto`: default; standalone charts use a contained neutral surface, while charts inside `WidgetShell` render embedded.
+- `embedded`: no internal card chrome; use it for corporate dashboards where `WidgetShell` owns the card, header, border and fullscreen behavior.
+- `contained`: the chart owns its visual surface; use it only for standalone chart placement outside a widget shell.
+
+For enterprise dashboards, prefer `theme.surface.mode = "embedded"` or the
+default `auto` inside `WidgetShell`. This avoids nested cards, duplicated
+rounded corners and decorative gradients competing with operational data.
+
 ## Declarative Query Contract
 
 For dynamic pages and widget orchestration, the primary public input for remote chart queries is `queryContext`.
@@ -180,7 +286,7 @@ Leitura pedagógica:
 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
+### Versão Detalhada do Fluxo Canônico
 
 ```mermaid
 sequenceDiagram
@@ -215,25 +321,28 @@ sequenceDiagram
     end
 ```
 
-### Limites Atuais do Contrato Canônico
+### Restrições do Contrato Canônico
 
-O mapper `x-ui.chart -> PraxisChartConfig` já impõe limites importantes que precisam aparecer na documentação pública:
+O mapper `x-ui.chart -> PraxisChartConfig` aplica as restrições públicas abaixo:
 
-- `source.kind` suportado hoje: `praxis.stats` e `derived`
+- `source.kind` aceitos: `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
+- agregações aceitas: `count`, `distinct-count`, `sum`, `avg`, `min`, `max`
+- `source.options.granularity` em `timeseries` aceita `day`, `week` e `month`
 - 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
+- `distribution` aceita apenas uma 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
+- `selectionChange` e `crossFilter` declarativos geram payloads canônicos derivados da seleção de ponto
+- `events.*.mapping` remapeia campos do ponto selecionado para os nomes de filtro esperados pelo host
+- `theme.variant` aceita `default`, `compact` e `executive`
+- `theme.palette` aceita array explícito de cores ou os tokens registrados `brand-primary`, `brand-balanced`, `status` e `executive`
+- campos explícitos de `theme.surface` têm precedência sobre os defaults aplicados por `theme.variant`
 
 ## Fluxo Canonico de `praxis.stats`
 
-Quando o contrato remoto vem do mapper canônico, o caminho gerado hoje segue a forma:
+Quando o contrato remoto vem do mapper canônico, o caminho gerado segue a forma:
 
 - `{resourcePath}/stats/group-by`
 - `{resourcePath}/stats/timeseries`
@@ -248,9 +357,10 @@ O `PraxisChartStatsApiService`:
 
 Observação importante:
 
-- o runtime atual assume envelope com `data`
+- a integração remota usa 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
+- `remoteDataResolver` permite que o host assuma a execução remota e entregue `PraxisChartDataRow[]`
+- sem `remoteDataResolver`, a execução remota padrão permanece limitada a `praxis.stats`
 - 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
@@ -264,15 +374,16 @@ This first published version is focused on the core runtime:
 - 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
+- canonical theme variants and registered palette tokens for `x-ui.chart`
+- declarative `selectionChange` and `crossFilter` actions emitted from selected chart points
+- `distinct-count` aggregation mapped to canonical `praxis.stats` `DISTINCT_COUNT`
+- host-owned remote data resolution through `remoteDataResolver`
 
 ## Current Non-Goals
 
-The current runtime does not yet expose as stable public surface:
+The public chart contract keeps these concerns outside the stable 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