@praxisui/charts 10.0.0-rc.4 → 10.0.0-rc.41

package/README.md

@@ -257,6 +257,39 @@ follows the host. Palette inheritance is preserved. Explicit chart surface/backg
 and text colors remain authoritative; choosing them requires a coherent contrast pair.
 Changing the host theme updates inherited colors without modifying the chart document.
 
+Existing color strings in palette arrays, metric/series colors, surface backgrounds,
+text colors and gauge bands can reference host CSS custom properties (for example,
+`var(--md-sys-color-primary, #1263b4)`). The default engine resolves them against the
+chart host on every render and projects modern CSS colors such as OKLCH into sRGB
+for Canvas. Explicit literal colors and palette overrides retain precedence. Missing
+or invalid tokens use bounded engine defaults; gauge bands retain their semantic
+tone fallback. Persisted documents and source data remain unchanged. A string
+`theme.palette` in `x-ui.chart` still names a registered Praxis palette; use an array
+for individual CSS colors.
+
+Palette array items must be non-empty strings; malformed persisted values are
+rejected by canonical validation with the item path. Direct runtime color fields
+also fall back safely when untyped JSON supplies another value type. Color probes
+isolate their measured color from host CSS rules, including rules with `!important`.
+
+The engine also derives tooltip background, foreground and border from the host's
+existing popover roles, with card/foreground and Material fallbacks. Tooltip
+formatting, triggers and disabled state keep their authored semantics; these
+computed appearance values are transient and never saved into the chart document.
+
+### Governed Motion and Data Transitions
+
+`PraxisChartConfig.motion` and `PraxisXUiChartContract.motion` govern both initial entrance animations and data/filter transition animations without exposing raw engine timing properties:
+
+- `enabled: false`: disables initial and update animations (`animationThreshold: 0`).
+- `preset: 'subtle'`: fast, understated corporate cadence (`240ms` entrance, `200ms` update, `cubicOut`, `animationThreshold: 1000`).
+- `preset: 'standard'` (default when motion is enabled): balanced analytical transition (`420ms` entrance, `320ms` update, `cubicOut` / `cubicInOut`, `animationThreshold: 1500`).
+- `preset: 'expressive'`: emphasized storytelling cadence (`680ms` entrance, `520ms` update, `quinticOut` / `cubicInOut`, `animationThreshold: 2000`).
+
+When `queryContext`, `filterCriteria`, or `data` changes for the same governed chart structure and remote resource identity, the default ECharts adapter updates the existing instance with `{ notMerge: false, replaceMerge: ['series'] }` so bars, lines, slices, and gauges interpolate smoothly between filter states. Structural or chrome mutations (chart kind, axis bounds, legend/tooltip visibility, titles, or switching to a different remote `resourcePath`/`resourceKey`) force a clean state reset (`setOption(option, true)` or canvas teardown) so stale options never leak across resources.
+
+`PraxisChartComponent` also respects `@media (prefers-reduced-motion: reduce)` at the host level, disabling visual transitions automatically when the operating system requests reduced motion. In `PraxisChartConfigEditor`, the Motion tab provides a **Simulate transition** action (`simulateMotionTransition()`) and automatically previews preset changes on the live chart.
+
 ## Micro Visualizations
 
 Transparent charts inside `WidgetShell` inherit the shell foreground, including fixed dark finishes in a light application theme. The chart's opaque accessible-data panel pairs its own background with the corresponding foreground. Explicit chart text colors keep precedence.
@@ -277,10 +310,12 @@ The table-safe kinds currently aligned with `PraxisPresentationVisualizationKind
 - `delta`
 - `processFlow`
 
-The component does not instantiate ECharts. It renders lightweight HTML/CSS from `PraxisPresentationVisualizationConfig`
+The component does not instantiate ECharts. It renders lightweight HTML/CSS/SVG 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 `points` as the canonical numeric series for `line`, `area`, `column`, and `comparison` (accepting raw numbers or `{ value, label }` points);
 use `segments` for `stackedBar`, `thresholds` for `bullet`, and `items` for item/step-oriented visualizations such as `processFlow`.
+For `line`, `area`, and `column`, optional `min`/`max` bounds control the vertical domain, `target` and `baseline` render dashed horizontal reference lines inside the SVG plot, and `valueSuffix` appends a unit suffix to the interactive HUD pill and last-value badge.
+On non-`table-cell` surfaces (`list-item`, `object-header`, `card-summary`, `form-presentation`), `line`, `area`, and `column` expose a single keyboard stop (`tabindex="0"`) on the figure container supporting `ArrowLeft`/`ArrowRight`/`Home`/`End`/`Escape` point scrubbing with polite `aria-live` announcements, while `surface: 'table-cell'` keeps zero internal `tabindex` stops so table grid navigation remains unobstructed.
 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.
 
 Neutral micro visualizations inherit foreground from their container unless the existing `--prx-micro-text-color` token overrides it. Radial indicators with `surface: 'card-summary'` and `size: 'md'` or `'responsive'` render at 6rem; table-cell indicators retain their compact 24px geometry. This materializes existing surface/size semantics without changing the configuration shape.
@@ -291,13 +326,17 @@ The Dynamic Page Lab's preset studio includes “Testar com componentes reais”
 
 `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.
 
-For the direct runtime editor, Apply updates the chart and emits `chartDocumentApplied`; Save emits `chartDocumentSaved`. Both also emit `chartDocumentPatchChange` with an independent `inputPatch.chartDocument` snapshot for dynamic widget hosts. Dynamic Page/Page Builder updates its authored page, so Apply followed by Save Page preserves the canonical document. Apply alone does not persist the page remotely. Unrelated widget inputs and transient catalogs remain owned by their existing host/context boundaries.
+The direct runtime host opens `PraxisChartWidgetConfigEditor` with the existing `{ inputs }` envelope so the canonical document, derived `data` and separate `queryContext` share the Apply/Save boundary. Apply updates the runtime and emits `chartDocumentApplied`; Save emits `chartDocumentSaved`. Both document outputs retain their `PraxisXUiChartContract` shape. `chartDocumentPatchChange` carries independent snapshots in `inputPatch.chartDocument`, `data` and `queryContext` when applicable, plus mapped `config` for a config-driven host. Switching to `praxis.stats` clears local data precedence with `inputPatch.data: null`; clearing query context uses `queryContext: null`.
+
+The accepted editor state belongs to the opening owner inputs. An owner may echo the latest accepted value of each input one at a time, including fields omitted from a later patch; equivalent clones do not imply a new owner. Hosts must apply patches in order: an older value of the same input delivered after a newer accepted value is indistinguishable from an external override and is treated as one. A distinct external input change replaces the local document/data/context state, and old editor events are rejected even before the next render. Closing or destroying the owner releases the editor subscriptions. Cancel discards unapplied editor work; it does not undo a previous Apply. Dynamic Page/Page Builder can materialize the patch in its authored page, but external persistence remains the host's responsibility. Apply or Save alone is not proof of remote persistence; the standalone showcase keeps runtime state only. Transient catalogs remain outside the persisted input envelope.
 
 `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.
+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`. Coexisting `/stats/capabilities` endpoints do not conflict with the canonical collection `/capabilities` endpoint; `chart-resource-capabilities-endpoint-ambiguous` is emitted only when multiple distinct collection capability paths compete for the same resource. 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 reads are deduplicated in flight, with a 30-second catalog timeout and a 10-second per-resource capability 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. In `PraxisChartWidgetConfigEditor`, authoring context diagnostics are grouped by diagnostic code with occurrence counts, scope impact, and expandable details (affected resource paths, next steps, and technical code) without dirtying the editor draft. `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.
 
-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.
+When `source.kind === 'derived'`, `PraxisChartConfigEditor` and `PraxisChartWidgetConfigEditor` expose local dataset authoring (`inputs.data` / `localData`) in the Data tab, align the live preview with the widget's local records (falling back to an explicitly labeled synthetic sample only when local records are empty), and validate predictable runtime constraints before save—including single-bucket consolidation and scale range checks for `gauge`. Consolidation preserves the authored aggregation: SUM40+80 remains120, and a gauge scale0..100 reports `gauge-value-out-of-range` until the author changes the scale, data or aggregation explicitly. The editor never substitutes an average or clamps the value to make it fit. For `pie` and `donut` charts, omitting `labels` preserves the engine's default callout visibility (`labels.enabled: undefined`), while explicit `labels: false` or `labels: { enabled: false }` hides both slice labels and leader lines (`labelLine: { show: false }`).
 
 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.