@praxisui/charts 9.0.0-beta.1 → 9.0.0-beta.2

package/README.md

@@ -1,30 +1,8 @@
 # @praxisui/charts
 
-> Metadata-driven charting for Praxis UI Angular, with a stable public contract and an engine adapter boundary.
+Metadata-driven charting for Praxis UI Angular applications. Install `@praxisui/charts` when a host needs declarative analytics widgets aligned with the Praxis runtime instead of passing raw chart-engine options through the public API.
 
-## Documentation
-
-- Official documentation: https://praxisui.dev/components/charts
-- Quickstart reference app: https://github.com/codexrodrigues/praxis-ui-quickstart
-- Live Praxis UI demo: https://praxis-ui-4e602.web.app
-- Recommended for: Angular hosts that need declarative analytics widgets aligned with the `@praxisui/*` runtime
-
-## 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
-- mapping from canonical `x-ui.chart` contracts into Praxis widget/page structures
-- support services for backend payload adaptation, stats requests and chart option building
-
-## Why this package exists
-
-- keep the public API business-oriented instead of exposing raw engine options as the main contract
-- preserve the option to swap the rendering engine later without rewriting host integrations
-- align charts with the same metadata-driven model used by the rest of the Praxis UI platform
+The package renders `PraxisChartConfig` and canonical `x-ui.chart` documents through a Praxis engine boundary. Apache ECharts is the current adapter implementation, but host integrations should depend on Praxis contracts.
 
 ## Install
 
@@ -33,25 +11,37 @@ npm i @praxisui/charts@latest
 ```
 
 Peer dependencies:
-- `@angular/core` `^21.0.0`
-- `@angular/common` `^21.0.0`
-- `@angular/forms` `^21.0.0`
-- `@angular/material` `^21.0.0`
+
+- `@angular/common`, `@angular/core`, `@angular/forms`, `@angular/material` `^21.0.0`
 - `@praxisui/core` `^9.0.0-beta.1`
 - `@praxisui/table` `^9.0.0-beta.1`
 - `rxjs` `~7.8.0`
 
-Runtime dependency included by this package:
+Runtime dependency included by the package:
+
 - `echarts` `^6.0.0`
 
-## Quick Start
+## App Providers
+
+Register the chart engine and component metadata once in the host application.
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import { providePraxisCharts } from '@praxisui/charts';
+
+export const appConfig: ApplicationConfig = {
+  providers: [providePraxisCharts()],
+};
+```
+
+## Standalone Chart
 
 ```ts
 import { Component } from '@angular/core';
 import {
   PraxisChartComponent,
-  type PraxisChartPointEvent,
   type PraxisChartConfig,
+  type PraxisChartPointEvent,
 } from '@praxisui/charts';
 
 @Component({
@@ -62,14 +52,12 @@ import {
     <praxis-chart
       [config]="config"
       (pointClick)="onPointClick($event)"
-      (selectionChange)="onSelectionChange($event)"
-      (crossFilter)="onCrossFilter($event)"
-    ></praxis-chart>
+    />
   `,
 })
 export class ChartDemoComponent {
   readonly config: PraxisChartConfig = {
-    title: 'Employees by Department',
+    title: 'Employees by department',
     type: 'bar',
     dataSource: {
       kind: 'local',
@@ -80,365 +68,77 @@ export class ChartDemoComponent {
       ],
     },
     axes: {
-      x: {
-        field: 'department',
-        type: 'category',
-        label: 'Department',
-      },
-      y: {
-        field: 'total',
-        type: 'value',
-        label: 'Employees',
-      },
+      x: { field: 'department', type: 'category', label: 'Department' },
+      y: { field: 'total', type: 'value', label: 'Employees' },
     },
     series: [
       {
         id: 'employees',
         type: 'bar',
-        metric: {
-          field: 'total',
-          aggregation: 'sum',
-        },
+        metric: { field: 'total', aggregation: 'sum' },
         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) {
+  onPointClick(event: PraxisChartPointEvent): void {
     console.log('chart point', event);
   }
-
-  onSelectionChange(event: unknown) {
-    console.log('chart selection', event);
-  }
-
-  onCrossFilter(event: unknown) {
-    console.log('chart filters', event);
-  }
 }
 ```
 
-## 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`, `PraxisChartPointEvent`, `PraxisChartSelectionEvent` and `PraxisChartCrossFilterEvent`
-- 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 Contract
 
-## Runtime Model
+Use the component with either local data or governed remote execution:
 
-O runtime de `@praxisui/charts` opera em duas trilhas principais:
+- `dataSource.kind = 'local'`: the chart consumes rows supplied in `dataSource.items` or the `data` input.
+- `dataSource.kind = 'remote'`: the chart emits `queryRequest`, then uses a host `remoteDataResolver` or the default `PraxisChartStatsApiService` path for `praxis.stats`.
+- `queryContext`: primary input for dynamic-page orchestration; filters, sort and limit are merged into remote requests where supported.
+- `filterCriteria`: accepted as a compatibility bridge, but new integrations should use `queryContext`.
 
-- `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`
-- 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' }],
-};
+```html
+<praxis-chart
+  [config]="chartConfig"
+  [queryContext]="{
+    filters: { departmentId: 10, status: 'ACTIVE' },
+    sort: ['competencia,asc'],
+    limit: 12
+  }"
+/>
 ```
 
-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.
+The public contract is `PraxisChartConfig` or the canonical `PraxisXUiChartContract`; raw ECharts options are adapter detail, not the host-facing model.
 
-## Surface Modes
+## Canonical Chart Documents
 
-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.
+New `x-ui.chart` documents should describe sizing, surface mode, source, dimensions and metrics declaratively.
 
 ```ts
 const chartDocument: PraxisXUiChartContract = {
   version: '0.1.0',
   kind: 'bar',
   chartId: 'status-by-team',
-  sizing: {
-    mode: 'fill-container',
-    minHeight: 160,
-  },
-  theme: {
-    surface: {
-      mode: 'embedded',
-    },
-  },
+  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`.
-
-```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 do Fluxo Canônico
-
-```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
-```
-
-### Restrições do Contrato Canônico
-
-O mapper `x-ui.chart -> PraxisChartConfig` aplica as restrições públicas abaixo:
-
-- `source.kind` aceitos: `praxis.stats` e `derived`
-- `source.kind = "praxis.stats"` exige `source.resource` e `source.operation`
-- 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 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 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:
-
-- a integração remota usa envelope com `data`
-- `queryRequest` é emitido para observabilidade do host antes da execução remota
-- `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
-
-This first published version is focused on the core runtime:
-
-- the `praxis-chart` component
-- 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
-- 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 public chart contract keeps these concerns outside the stable surface:
-
-- direct host control over raw ECharts options as the primary contract
+Supported sizing modes are `fixed`, `fill-container` and `auto`. Prefer `fill-container` inside dashboard widget shells. Supported surface modes are `auto`, `embedded` and `contained`; prefer `embedded` when another shell owns the card, header or border.
 
-## Notes for Hosts
+## Authoring Surface
 
-- the package is designed for the Praxis platform model, where chart semantics live in canonical contracts and not in engine-specific payloads
-- if you are integrating charts into dynamic pages or widget shells, prefer the exported Praxis contracts and mappers over direct engine customization
-- if you need raw ECharts tuning, treat it as adapter-level implementation detail unless the contract is promoted to the public surface intentionally
+`PraxisChartConfigEditor` is the initial editor shell for canonical `x-ui.chart` documents. It expects governed resources, fields and targets from the host and emits structured apply/save/reset events. The authoring manifest is exported as `PRAXIS_CHARTS_AUTHORING_MANIFEST` for backend/tooling workflows that need executable chart-edit operations.
 
-## Reusable `x-ui.analytics` Runtime Pattern
+## Public API Snapshot
 
-When the backend publishes `x-ui.analytics.projections[]`, the reusable platform path is now:
+Main exports include `PraxisChartComponent`, `PraxisChartConfigEditor`, chart event/config models, `PraxisXUiChartContract`, engine adapter tokens, `providePraxisCharts`, canonical mapping/normalization/validation services, analytics chart services, chart metadata and `PRAXIS_CHARTS_AUTHORING_MANIFEST`.
 
-1. `@praxisui/core` resolves the contract with `AnalyticsSchemaContractService`
-2. `AnalyticsPresentationResolver` chooses the presentation family
-3. `AnalyticsChartContractService` in `@praxisui/charts` materializes the selected projection into `PraxisChartConfig`
+## Official Links
 
-This keeps chart hosts out of the business of:
-- calling `/schemas/filtered` manually
-- parsing `x-ui.analytics` by hand
-- selecting projections ad hoc
-- rebuilding the chart contract pipeline inside each app
+- Documentation: https://praxisui.dev/components/charts
+- Live demo: https://praxis-ui-4e602.web.app
+- Quickstart repository: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Source and issues: https://github.com/codexrodrigues/praxis-ui-angular

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@praxisui/charts",
-  "version": "9.0.0-beta.1",
+  "version": "9.0.0-beta.2",
   "description": "Metadata-driven charts library for Praxis UI Angular with engine adapters and Apache ECharts as the initial renderer.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
-    "@praxisui/core": "^9.0.0-beta.1",
+    "@praxisui/core": "^9.0.0-beta.2",
     "@angular/forms": "^21.0.0",
     "@angular/material": "^21.0.0",
-    "@praxisui/table": "^9.0.0-beta.1",
+    "@praxisui/table": "^9.0.0-beta.2",
     "rxjs": "~7.8.0"
   },
   "dependencies": {