@praxisui/charts 9.0.0-beta.72 → 9.0.0-beta.74

package/README.md

@@ -119,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
@@ -180,7 +187,17 @@ Rich charts still use the canonical `x-ui.chart` document flow above; micro visu
 
 ## 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.
+
+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