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

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
 
@@ -123,7 +153,8 @@ O runtime 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`
 
@@ -296,21 +327,22 @@ O mapper `x-ui.chart -> PraxisChartConfig` aplica as restrições públicas abai
 
 - `source.kind` aceitos: `praxis.stats` e `derived`
 - `source.kind = "praxis.stats"` exige `source.resource` e `source.operation`
-- agregações aceitas: `count`, `sum`, `avg`, `min`, `max`
-- `distinct-count` não é uma agregação aceita por `@praxisui/charts`
+- 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` 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 não são ações aceitas por `@praxisui/charts`
+- `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`
@@ -327,7 +359,8 @@ Observação importante:
 
 - 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 é limitada a `praxis.stats`; o componente não expõe hook público de override do request
+- `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
@@ -342,14 +375,48 @@ This first published version is focused on the core runtime:
 - 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`
+- executable agentic authoring manifest for `praxis-chart`, exported as `PRAXIS_CHARTS_AUTHORING_MANIFEST`
+
+## Agentic Authoring Contract
+
+`@praxisui/charts` publishes a component-level authoring manifest for `praxis-chart`.
+The manifest is an executable backend/tooling contract for canonical
+`PraxisXUiChartContract` documents, not prompt-routing documentation.
+
+The governed authoring targets are:
+
+- `chartType`
+- `series`
+- `axis`
+- `dataBinding`
+- `queryContext`
+- `crossFilter`
+- `drilldown`
+- `selection`
+- `legend`
+- `tooltip`
+
+Remote resource and field binding must come from governed API metadata,
+`availableResources` and `availableFields`. Cross-filter, drilldown and
+selection authoring persists structured `events.*` actions instead of command
+strings or raw prompt examples. The visual editor remains the canonical
+round-trip surface for this document: open, edit, apply/save, reset and reopen
+must preserve the same `x-ui.chart` shape consumed by the runtime.
+
+Each manifest operation declares its own editable target, resolver,
+ambiguity policy, preconditions, validators, affected paths, effects and
+`submissionImpact`. Chart document, type, series and axis changes are
+`config-only`; remote data binding, query context and event mappings
+`affect-remote-binding`; legend and tooltip changes are `visual-only`.
 
 ## 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
 
 ## Notes for Hosts