@praxisui/charts 9.0.0-beta.9 → 9.0.0-beta.90

package/README.md

@@ -19,8 +19,8 @@ npm i @praxisui/charts@latest
 Peer dependencies:
 
 - `@angular/common`, `@angular/core`, `@angular/forms`, `@angular/material` `^21.0.0`
-- `@praxisui/core` `^9.0.0-beta.4`
-- `@praxisui/table` `^9.0.0-beta.4`
+- `@praxisui/core` `^9.0.0-beta.12`
+- `@praxisui/table` `^9.0.0-beta.12`
 - `rxjs` `~7.8.0`
 
 Runtime dependency included by the package:
@@ -40,6 +40,26 @@ export const appConfig: ApplicationConfig = {
 };
 ```
 
+`providePraxisCharts()` installs Apache ECharts as the default renderer through the Praxis engine factory boundary. Each
+`<praxis-chart>` receives its own stateful engine instance. Hosts that need a custom renderer can keep the same public
+registration path and replace only the factory:
+
+```ts
+import { ApplicationConfig } from '@angular/core';
+import {
+  providePraxisCharts,
+  type PraxisChartEngineAdapter,
+} from '@praxisui/charts';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    providePraxisCharts({
+      engineFactory: (): PraxisChartEngineAdapter => new CustomChartEngineAdapter(),
+    }),
+  ],
+};
+```
+
 ## Standalone Chart
 
 ```ts
@@ -99,8 +119,15 @@ Use the component with either local data or governed remote execution:
 
 - `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`.
+- `praxis.stats/comparison`: analytics projections materialize one `Current` and one `Previous` series per governed metric. The starter remains responsible for period resolution, bucket union, delta and baseline semantics; charts only render the returned period values.
 - `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`.
+- `pointClick`: raw renderer-neutral point evidence. Configured click actions are emitted separately through `pointAction`.
+- For categorical `praxis.stats` points, `data.key` remains the canonical bucket identity while `label` and the category field remain presentation evidence, including when distinct buckets share the same display label.
+- For time-series `praxis.stats` points, `data.start` (falling back to a valid temporal `data.key`) drives the time coordinate, `data.end` preserves the inclusive bucket boundary, and `data.label` remains presentation evidence. After the target is grounded from the governed filter schema, Page Builder composition can materialize a range input as `[data.start, data.end]`, guarded on both boundaries. Repeated labels therefore do not collapse distinct periods.
+- `selectionChange`: single-point selection evidence with canonical filters. Toggle, replacement and multi-select are not advertised by this runtime contract.
+- `drillDown` and `crossFilter`: structured action/filter payloads intended for Page Builder composition links and governed host orchestration.
+- Analytics projections with `crossFilter=true` must publish `bindings.primaryDimension.keyFilterField`. The analytics adapter maps the preserved raw row `key` to that public request field and fails closed when the binding is absent; labels and dimension naming conventions are never used as filter identity.
 
 ```html
 <praxis-chart
@@ -132,15 +159,81 @@ const chartDocument: PraxisXUiChartContract = {
 };
 ```
 
+Governed period comparisons use the same document and the canonical `comparison` stats operation. The resource must publish `canonicalOperations.statsComparison=true`; the dimension must be group-by eligible, the period field time-series eligible, and metrics are limited to `count`, `distinct-count`, or `sum` as declared by capabilities.
+
+```ts
+const comparisonDocument: PraxisXUiChartContract = {
+  version: '0.1.0',
+  kind: 'bar',
+  chartId: 'employees-by-department-comparison',
+  source: {
+    kind: 'praxis.stats',
+    resource: '/api/human-resources/employees',
+    operation: 'comparison',
+    options: {
+      comparisonPeriod: {
+        field: 'admissionDate',
+        timezone: 'America/Sao_Paulo',
+        preset: 'LAST_30_DAYS',
+        mode: 'PREVIOUS_ALIGNED',
+      },
+    },
+  },
+  dimensions: [{ field: 'department' }],
+  metrics: [
+    { field: 'employeeId', aggregation: 'distinct-count', label: 'Employees' },
+    { field: 'absenceDays', aggregation: 'sum', label: 'Absence days' },
+  ],
+};
+```
+
+The mapper emits one `POST /stats/comparison` request with canonical `metrics[]`; it never downgrades the document into independent period requests or a singular `metric`. Each governed metric is materialized as current and previous display series.
+
 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.
 
+## Micro Visualizations
+
+`PraxisMicroVisualizationComponent` renders the first renderer-neutral presentation visualizations from `@praxisui/core`.
+It is intended for compact presentation surfaces, especially table cells, list items and read-only form summaries.
+
+The table-safe kinds currently aligned with `PraxisPresentationVisualizationKind` are:
+
+- `line`
+- `area`
+- `column`
+- `comparison`
+- `stackedBar`
+- `radial`
+- `harveyBall`
+- `bullet`
+- `delta`
+- `processFlow`
+
+The component does not instantiate ECharts. It renders lightweight HTML/CSS from `PraxisPresentationVisualizationConfig`
+and falls back to `fallbackText` when the visualization kind cannot be rendered for the current compact surface.
+Use `points` as the canonical numeric series for `line`, `area`, `column`, and `comparison`;
+use `segments` for `stackedBar`, `thresholds` for `bullet`, and `items` for item/step-oriented visualizations such as `processFlow`.
+Rich charts still use the canonical `x-ui.chart` document flow above; micro visualizations are the lightweight presentation contract for dense cells, list items, object headers, card summaries and form presentation surfaces.
+
 ## Authoring Surface
 
-`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.
+`PraxisChartConfigEditor` is the initial editor shell for canonical `x-ui.chart` documents. It consumes governed resources, fields and targets 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.
+
+`ChartResourceCapabilityCatalogAdapter` derives resource operations and eligible dimension, time and metric options directly from `ResourceCapabilitySnapshot`, including fail-closed comparison eligibility.
+
+Applications should install `providePraxisCharts()` once. The registered `ComponentDocMeta.configEditor.contextResolver` materializes the editor context without making Page Builder own Chart semantics. Initial resolution groups `/schemas/catalog` endpoints by the stable `resourceKey`, exposes that value as `availableResources[].id`, and keeps the catalog's governed root-relative resource path as `availableResources[].path`. A selected `praxis.stats` source is normalized to that operational path before save; the discovery id is never persisted as an executable URL.
+
+Capabilities are loaded lazily from the exact catalog-published endpoint only after resource selection. Concurrent catalog and per-resource capability reads are deduplicated in flight and bounded by a 10-second timeout, but successful permission-sensitive projections are not cached across requests until the host publishes a canonical authentication/context epoch. Denied, unavailable, ambiguous, stale and empty evidence fails closed, and later requests remain retryable. `canonicalOperations` gates group-by, timeseries and distribution, while `stats.fields[]` gates dimensions, metrics, aggregations and exact `distributionModes` eligibility for terms versus histogram. `/schemas/filtered` enrichment of field titles, types and `x-ui` remains a later schema-flow gate; capabilities remain the authority for eligibility.
+
+Target choices come only from existing top-level composition links whose source is the current Chart and whose exact structured source event port is public and non-deprecated. Raw `pointClick` evidence never authorizes a configured action; `events.pointClick` uses `pointAction`. Directly compatible widget ports are admitted; an explicit `transform.output.semanticKind` is inspected only as provisional local evidence. That local check does not replace a transform-output projection materialized and validated by Core, which remains a P2 gate. Destinations are limited to compatible public, non-deprecated widget inputs or explicitly writable declared page state. Each target carries `events[]`, so a link from `crossFilter` cannot authorize the same target for `pointClick`, `selectionChange` or `drillDown`; routes, nested ports, global actions, undeclared state and unconnected widgets are not synthesized.
+
+Resource, field and target catalogs, along with context diagnostics, are transient authoring evidence. Apply/save persists only the canonical widget inputs and `chartDocument`; it never serializes `availableResources`, `availableFields`, `availableTargets` or `contextDiagnostics` into the page definition.
+
+Visual authoring now consumes this projection, and the backend handler, resolver and validators execute the same event-scoped contract directly. P1 remains open only at the integration boundary: Page Builder/assistant requests still need to project the transient `availableTargets[].events` catalog through `validationContext` and surface the resulting fail-closed diagnostics. P2 remains open for canonical Core projections of transform-output semantics and target input-schema/port fields; backend-enriched `inputFields` is not a substitute for that visual composition contract.
 
 ## Public API Snapshot
 
-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`.
+Main exports include `PraxisChartComponent`, `PraxisMicroVisualizationComponent`, `PraxisChartConfigEditor`, chart event/config models, `PraxisXUiChartContract`, engine adapter and factory tokens, `providePraxisCharts`, canonical mapping/normalization/validation services, analytics chart services, chart metadata and `PRAXIS_CHARTS_AUTHORING_MANIFEST`.
 
 ## Official Links