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

package/README.md

@@ -115,7 +115,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`
@@ -127,6 +127,81 @@ No modo remoto, o componente:
 - 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 +255,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,21 +290,23 @@ 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`, `sum`, `avg`, `min`, `max`
+- `distinct-count` não é uma agregação aceita por `@praxisui/charts`
 - 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 não são ações aceitas por `@praxisui/charts`
+- `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`
 
@@ -248,9 +325,9 @@ 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
+- a execução remota automática é limitada a `praxis.stats`; o componente não expõe hook público de override do request
 - 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,6 +341,7 @@ 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`
 
 ## Current Non-Goals
 
@@ -272,7 +350,6 @@ 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