Praxis Charts ECharts Engine Boundary
Use this skill for the boundary that materializes canonical Praxis chart decisions in Apache ECharts. Hosts, authoring flows, metadata, AI tools, and persisted documents depend on PraxisXUiChartContract, PraxisChartConfig, and renderer-neutral events. ECharts modules, instances, options, params, and timing heuristics remain adapter-owned implementation details.
Pair it with:
praxis-charts-runtime-data for config normalization, data resolution, transformation, and runtime states.
praxis-charts-analytics-interactions when point events become selection, drilldown, cross-filter, or query context.
praxis-charts-authoring-settings and praxis-charts-authoring-catalogs when editor previews must use the production materialization path.
praxis-charts-ai-handler-contracts and praxis-charts-ai-validation when AI operations could bypass canonical chart decisions.
praxis-angular-public-api-governance before exporting an adapter, token, provider, compiler, or engine-owned type.
Canonical Ownership
Follow this direction of dependency:
x-ui.chart -> normalizer/validator/mapper -> PraxisChartConfig plus resolved rows -> internal engine option compiler -> PraxisChartEngineAdapter -> ECharts instance
- Add missing semantics to the canonical chart document, mapper, validator, or runtime config before changing ECharts options.
- Treat
PraxisChartEngineAdapter, PRAXIS_CHART_ENGINE_FACTORY, and providePraxisCharts({ engineFactory }) as the renderer-neutral extension boundary when they are public.
- Keep the option compiler adapter-owned. A service that returns
EChartsCoreOption is not a renderer-neutral public Praxis service and must not be root-exported merely for convenience.
- Never persist, accept from AI, or expose raw
EChartsCoreOption, formatter functions, ECharts params, or module constructors as the primary host contract.
- Keep
PraxisMicroVisualizationComponent separate. It materializes compact core presentation contracts with lightweight HTML/CSS/SVG and does not share ECharts lifecycle or option semantics.
Source Audit
Read projects/praxis-charts/AGENTS.md before editing. Inspect at least:
projects/praxis-charts/README.md and src/public-api.ts
src/lib/adapters/chart-engine.adapter.ts
src/lib/adapters/echarts/echarts-engine.adapter.ts
src/lib/adapters/echarts/echarts-option-builder.service.ts
src/lib/tokens/chart-engine.token.ts
src/lib/providers/charts.providers.ts
src/lib/services/chart-data-transformer.service.ts
src/lib/components/praxis-chart/praxis-chart.component.ts
src/lib/components/praxis-micro-visualization/praxis-micro-visualization.component.ts
- direct consumers, authoring manifests, README examples, and focused specs for all of the above
Do not infer coverage from a spec filename. Read its assertions and compare them with the lifecycle and event matrix below.
Provider Boundary
providePraxisCharts() installs the default ECharts renderer through PRAXIS_CHART_ENGINE_FACTORY. Hosts replace the renderer through the documented providePraxisCharts({ engineFactory }) path, or by intentionally providing the factory token from the same canonical owner.
- A component-level provider shadows environment/root providers. Do not provide the concrete ECharts adapter locally when the public contract promises host replacement through the provider bundle.
- Preserve one mutable engine instance per chart component or host element. The factory may be shared by DI, but the component must call it to obtain a fresh adapter instance for that chart.
- Test the real public registration path.
TestBed.overrideComponent() proves test substitution, not that providePraxisCharts({ engineFactory }) is replaceable in production.
- Keep metadata registration and table inline-renderer registration in the provider bundle independent from the choice of chart engine.
Engine Lifecycle
The mutable instance belongs to a specific host element:
- Initialize once for the current host after it has a renderable size.
- Re-render canonical config/data with replacement semantics appropriate to the full derived option; stale series or handlers must not survive.
- Remove prior ECharts, zrender, and DOM handlers before installing callbacks for the new payload.
- Resize from the observed current host without creating a second instance.
- If the host element changes, detach handlers, dispose the old instance, observe the new element, and initialize again.
- On loading, empty, error, or component destruction, cancel scheduled work, disconnect/reset observers, remove handlers, and dispose idempotently.
Track host identity explicitly in the adapter or owning runtime. if (!chart) init(host) is insufficient if render() can receive another element. A cached ResizeObserver must likewise rebind when Angular recreates #chartHost after a state transition.
Keep ECharts use(...), renderer selection, and browser-only initialization centralized in the implementation path. Audit SSR/import safety separately from DOM-time safety; a browser guard around render() does not make module-level side effects automatically SSR-safe.
Map KPI, gauge, treemap, grouped scatter, funnel/pyramid, histogram, and
comparison only from renderer-neutral Praxis config. Keep ECharts series/options
derived and transient. Preserve feature-injector locale, accessible table
contrast, semantic point identity, and deterministic resize/dispose behavior.
Host Theme Color Materialization
When implementing CSS-driven chart appearance, inspect the private
adapters/echarts/echarts-host-colors.ts path and the component's ancestor theme
observer. Existing canonical palette, series, surface and gauge color fields
already accept strings; do not add a parallel theme input or raw engine options
only to carry host colors.
Resolve CSS custom properties in the actual chart host and project modern CSS
colors into Canvas-compatible sRGB at render time. Copy only canonical color
fields; preserve authored documents, rows, valid literal colors and explicit
series overrides. Cache within one render, clean probes in all exit paths and
use bounded field-appropriate fallbacks for missing/cyclic tokens or unavailable
DOM/Canvas. Clear CSSOM probe values before assignments that the browser may reject;
isolate the probe's color assignment from host/global descendant selectors,
including !important, while preserving inherited custom properties. Prove this
with var(), OKLCH/color-mix and tooltip foreground/background under hostile CSS.
Treat persisted JSON as untyped: canonical palette validation must reject non-string,
blank or invalid-container values before mapping; the private renderer must also
narrow color values before trimming and use bounded fallbacks for malformed direct
runtime inputs. Include validator/mapper and adapter tests, not only typed fixtures.
Classify renderer compatibility with its actual color parser, not an alphabetic or
regex guess that would mistake CSS system colors for engine-supported names.
Semantic gauge tones should follow host status colors while valid explicit colors
retain precedence.
Tooltip chrome should consume existing host popover/foreground/border roles through
the same private resolver. Materialize only tooltips enabled by the option compiler;
preserve trigger, formatter, disabled absence and responsive base/media options.
Do not introduce persisted tooltip color fields to repair engine light defaults.
A class/style/data-theme change must repaint even if the inherited theme document
or text color is unchanged. Prove token changes, separate hosts, cleanup, alpha,
SSR/import safety and color-document immutability. Palette editors must split
only top-level separators so rgb(...) and nested var(..., fallback) survive
edit/apply/reopen. Confirm the consumed package contains this materialization
before advising a host to use token-bound colors; older packages may forward
var() directly to the engine. Fixed palette literals remain intentional and
must not be silently replaced on theme changes.
Event Materialization
- Convert series clicks to
PraxisChartPointEvent; never emit raw ECharts params.
- Preserve the canonical chart id, semantic series identity, category, normalized value, and source data needed by governed interactions.
- Grid/category fallback must reject non-finite coordinates, pixels outside the plot, unavailable axes, failed conversions, and out-of-range categories without emitting.
- Do not silently assign a category click to the first series in a multi-series chart. First classify whether existing optional event fields can represent a category-only interaction; introduce a contract only if downstream selection/cross-filter semantics cannot be expressed correctly.
- Audit vertical and horizontal category axes, multiple series, tuples, object values, primitive values, missing category data, and unsupported chart families.
- Deduplicate ECharts, zrender, and captured DOM notifications deterministically where possible. A short wall-clock window is a heuristic, not proof that two callbacks represent the same user action.
- Re-rendered callbacks must use the newest payload and must never retain stale config, rows, or handlers.
Option Safety
- Compile only validated Praxis semantics into ECharts options. Engine defaults are derived materialization, not a second source of truth.
- Preserve stable ids and replace removed series, axes, titles, legends, datasets, visual maps, and interaction state when config changes.
- Keep formatters and callbacks library-owned; do not execute arbitrary functions supplied by metadata, persisted config, AI output, or host JSON.
- Register only required ECharts modules and renderers, and update tests/build whenever a supported Praxis chart family needs another module.
- Keep theme, accessibility, labels, sizing, and visual decisions aligned with canonical config. Do not add ECharts-shaped aliases when an existing Praxis field is merely under-materialized.
Inventory Before New Contract
Classify each request before editing:
ja-suportado-so-ux: canonical config already expresses the decision; sizing, theme, label, state, or event presentation needs correction.
ja-suportado-mal-nomeado-ou-mal-materializado: an exported option compiler or ECharts-shaped name duplicates semantics already owned by Praxis contracts.
suportado-parcialmente: token/provider, host lifecycle, event model, option compiler, or observer exists but substitution, cleanup, mapping, or tests are incomplete.
lacuna-real-de-contrato: no canonical document field, runtime model, renderer-neutral event, or adapter operation can express required behavior.
Only lacuna-real-de-contrato justifies a new public field or API. During beta, correct the canonical export/provider surface and update consumers in the same cycle instead of adding compatibility aliases.
Validation Matrix
Choose the smallest commands that prove the changed behavior, but require assertions for every affected row:
- adapter instance: init once, update, current-host identity, host replacement, resize, idempotent destroy, and re-render after destroy;
- handlers: ECharts
off/on, zrender detach/attach, DOM capture detach/attach, latest payload, and deterministic duplicate suppression;
- fallback events: invalid/outside pixels, vertical/horizontal categories, bounds, multi-series semantics, tuples, objects, and primitives;
- component DI: default registration and a custom engine through the real host/provider path, with multiple chart components isolated;
- component host: zero-size defer, ready -> non-ready -> ready host recreation, observer rebind, scheduled-frame cancellation, and final cleanup;
- option compiler and transformer: supported chart families, replacement safety, canonical mapping, and no executable/raw option ingress;
- micro visualization: remains functional without instantiating ECharts;
- public API: focal library build plus a direct consumer build when exports or providers change.
Typical focal gates are:
npx ng test praxis-charts --watch=false --progress=false --include='projects/praxis-charts/src/lib/adapters/echarts/echarts-engine.adapter.spec.ts' --include='projects/praxis-charts/src/lib/adapters/echarts/echarts-option-builder.service.spec.ts' --include='projects/praxis-charts/src/lib/services/chart-data-transformer.service.spec.ts'
npx ng test praxis-charts --watch=false --progress=false --include='projects/praxis-charts/src/lib/components/praxis-chart/praxis-chart.component.spec.ts' --include='projects/praxis-charts/src/lib/components/praxis-micro-visualization/praxis-micro-visualization.component.spec.ts'
npm run build:praxis-charts
An existing helper-only adapter spec does not prove lifecycle or event wiring. Report exact assertions that ran, gaps left unproved, derived docs/examples/manifests reviewed, and whether a direct consumer build was required.
Axis Contrast and Surface Evidence
EChartsOptionBuilderService must project the effective Praxis theme.textColor into both axisLabel.color and nameTextStyle.color. Cover primary/secondary axes, horizontal orientation and scatter: styling tick values alone leaves axis names at engine defaults. Keep this mapping inside the adapter, without exposing ECharts-shaped metadata.
Validate theme changes against both the engine canvas and the rendered HTML surface, not only text tokens or the outer widget. In applyInheritedTheme, an explicitly embedded/transparent chart must not inherit the page preset's contained background while taking the host foreground. Preserve the inherited palette and authored surface/background/text overrides. Test a dark/light/dark host transition with the executive page preset, the actual shell computed background, and an unchanged input document. Inspect widget-chart-theme.playwright.spec.ts in the Dynamic Page Lab for the real consumer proof. Axis-name mapping alone does not prove that foreground and surface provenance agree; explicit custom colors still require a coherent pair.
1---2name: praxis-charts-echarts-engine-boundary3description: "Use when Codex must implement, audit, or consume @praxisui/charts engine behavior: PraxisChartEngineAdapter, PRAXIS_CHART_ENGINE_FACTORY, providePraxisCharts, EChartsEngineAdapter, internal option compilation, module registration, host/resize/dispose lifecycle, point and category event mapping, micro-visualization separation, or ECharts type leakage through public APIs."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-charts-echarts-engine-boundary6---78# Praxis Charts ECharts Engine Boundary910Use this skill for the boundary that materializes canonical Praxis chart decisions in Apache ECharts. Hosts, authoring flows, metadata, AI tools, and persisted documents depend on `PraxisXUiChartContract`, `PraxisChartConfig`, and renderer-neutral events. ECharts modules, instances, options, params, and timing heuristics remain adapter-owned implementation details.1112Pair it with:1314- `praxis-charts-runtime-data` for config normalization, data resolution, transformation, and runtime states.15- `praxis-charts-analytics-interactions` when point events become selection, drilldown, cross-filter, or query context.16- `praxis-charts-authoring-settings` and `praxis-charts-authoring-catalogs` when editor previews must use the production materialization path.17- `praxis-charts-ai-handler-contracts` and `praxis-charts-ai-validation` when AI operations could bypass canonical chart decisions.18- `praxis-angular-public-api-governance` before exporting an adapter, token, provider, compiler, or engine-owned type.1920## Canonical Ownership2122Follow this direction of dependency:2324`x-ui.chart` -> normalizer/validator/mapper -> `PraxisChartConfig` plus resolved rows -> internal engine option compiler -> `PraxisChartEngineAdapter` -> ECharts instance2526- Add missing semantics to the canonical chart document, mapper, validator, or runtime config before changing ECharts options.27- Treat `PraxisChartEngineAdapter`, `PRAXIS_CHART_ENGINE_FACTORY`, and `providePraxisCharts({ engineFactory })` as the renderer-neutral extension boundary when they are public.28- Keep the option compiler adapter-owned. A service that returns `EChartsCoreOption` is not a renderer-neutral public Praxis service and must not be root-exported merely for convenience.29- Never persist, accept from AI, or expose raw `EChartsCoreOption`, formatter functions, ECharts params, or module constructors as the primary host contract.30- Keep `PraxisMicroVisualizationComponent` separate. It materializes compact core presentation contracts with lightweight HTML/CSS/SVG and does not share ECharts lifecycle or option semantics.3132## Source Audit3334Read `projects/praxis-charts/AGENTS.md` before editing. Inspect at least:3536- `projects/praxis-charts/README.md` and `src/public-api.ts`37- `src/lib/adapters/chart-engine.adapter.ts`38- `src/lib/adapters/echarts/echarts-engine.adapter.ts`39- `src/lib/adapters/echarts/echarts-option-builder.service.ts`40- `src/lib/tokens/chart-engine.token.ts`41- `src/lib/providers/charts.providers.ts`42- `src/lib/services/chart-data-transformer.service.ts`43- `src/lib/components/praxis-chart/praxis-chart.component.ts`44- `src/lib/components/praxis-micro-visualization/praxis-micro-visualization.component.ts`45- direct consumers, authoring manifests, README examples, and focused specs for all of the above4647Do not infer coverage from a spec filename. Read its assertions and compare them with the lifecycle and event matrix below.4849## Provider Boundary5051- `providePraxisCharts()` installs the default ECharts renderer through `PRAXIS_CHART_ENGINE_FACTORY`. Hosts replace the renderer through the documented `providePraxisCharts({ engineFactory })` path, or by intentionally providing the factory token from the same canonical owner.52- A component-level provider shadows environment/root providers. Do not provide the concrete ECharts adapter locally when the public contract promises host replacement through the provider bundle.53- Preserve one mutable engine instance per chart component or host element. The factory may be shared by DI, but the component must call it to obtain a fresh adapter instance for that chart.54- Test the real public registration path. `TestBed.overrideComponent()` proves test substitution, not that `providePraxisCharts({ engineFactory })` is replaceable in production.55- Keep metadata registration and table inline-renderer registration in the provider bundle independent from the choice of chart engine.5657## Engine Lifecycle5859The mutable instance belongs to a specific host element:60611. Initialize once for the current host after it has a renderable size.622. Re-render canonical config/data with replacement semantics appropriate to the full derived option; stale series or handlers must not survive.633. Remove prior ECharts, zrender, and DOM handlers before installing callbacks for the new payload.644. Resize from the observed current host without creating a second instance.655. If the host element changes, detach handlers, dispose the old instance, observe the new element, and initialize again.666. On loading, empty, error, or component destruction, cancel scheduled work, disconnect/reset observers, remove handlers, and dispose idempotently.6768Track host identity explicitly in the adapter or owning runtime. `if (!chart) init(host)` is insufficient if `render()` can receive another element. A cached `ResizeObserver` must likewise rebind when Angular recreates `#chartHost` after a state transition.6970Keep ECharts `use(...)`, renderer selection, and browser-only initialization centralized in the implementation path. Audit SSR/import safety separately from DOM-time safety; a browser guard around `render()` does not make module-level side effects automatically SSR-safe.7172Map KPI, gauge, treemap, grouped scatter, funnel/pyramid, histogram, and73comparison only from renderer-neutral Praxis config. Keep ECharts series/options74derived and transient. Preserve feature-injector locale, accessible table75contrast, semantic point identity, and deterministic resize/dispose behavior.7677## Host Theme Color Materialization7879When implementing CSS-driven chart appearance, inspect the private80`adapters/echarts/echarts-host-colors.ts` path and the component's ancestor theme81observer. Existing canonical palette, series, surface and gauge color fields82already accept strings; do not add a parallel theme input or raw engine options83only to carry host colors.8485Resolve CSS custom properties in the actual chart host and project modern CSS86colors into Canvas-compatible sRGB at render time. Copy only canonical color87fields; preserve authored documents, rows, valid literal colors and explicit88series overrides. Cache within one render, clean probes in all exit paths and89use bounded field-appropriate fallbacks for missing/cyclic tokens or unavailable90DOM/Canvas. Clear CSSOM probe values before assignments that the browser may reject;91isolate the probe's color assignment from host/global descendant selectors,92including `!important`, while preserving inherited custom properties. Prove this93with `var()`, OKLCH/color-mix and tooltip foreground/background under hostile CSS.94Treat persisted JSON as untyped: canonical palette validation must reject non-string,95blank or invalid-container values before mapping; the private renderer must also96narrow color values before trimming and use bounded fallbacks for malformed direct97runtime inputs. Include validator/mapper and adapter tests, not only typed fixtures.9899Classify renderer compatibility with its actual color parser, not an alphabetic or100regex guess that would mistake CSS system colors for engine-supported names.101Semantic gauge tones should follow host status colors while valid explicit colors102retain precedence.103104Tooltip chrome should consume existing host popover/foreground/border roles through105the same private resolver. Materialize only tooltips enabled by the option compiler;106preserve trigger, formatter, disabled absence and responsive base/media options.107Do not introduce persisted tooltip color fields to repair engine light defaults.108109A class/style/data-theme change must repaint even if the inherited theme document110or text color is unchanged. Prove token changes, separate hosts, cleanup, alpha,111SSR/import safety and color-document immutability. Palette editors must split112only top-level separators so `rgb(...)` and nested `var(..., fallback)` survive113edit/apply/reopen. Confirm the consumed package contains this materialization114before advising a host to use token-bound colors; older packages may forward115`var()` directly to the engine. Fixed palette literals remain intentional and116must not be silently replaced on theme changes.117118## Event Materialization119120- Convert series clicks to `PraxisChartPointEvent`; never emit raw ECharts params.121- Preserve the canonical chart id, semantic series identity, category, normalized value, and source data needed by governed interactions.122- Grid/category fallback must reject non-finite coordinates, pixels outside the plot, unavailable axes, failed conversions, and out-of-range categories without emitting.123- Do not silently assign a category click to the first series in a multi-series chart. First classify whether existing optional event fields can represent a category-only interaction; introduce a contract only if downstream selection/cross-filter semantics cannot be expressed correctly.124- Audit vertical and horizontal category axes, multiple series, tuples, object values, primitive values, missing category data, and unsupported chart families.125- Deduplicate ECharts, zrender, and captured DOM notifications deterministically where possible. A short wall-clock window is a heuristic, not proof that two callbacks represent the same user action.126- Re-rendered callbacks must use the newest payload and must never retain stale config, rows, or handlers.127128## Option Safety129130- Compile only validated Praxis semantics into ECharts options. Engine defaults are derived materialization, not a second source of truth.131- Preserve stable ids and replace removed series, axes, titles, legends, datasets, visual maps, and interaction state when config changes.132- Keep formatters and callbacks library-owned; do not execute arbitrary functions supplied by metadata, persisted config, AI output, or host JSON.133- Register only required ECharts modules and renderers, and update tests/build whenever a supported Praxis chart family needs another module.134- Keep theme, accessibility, labels, sizing, and visual decisions aligned with canonical config. Do not add ECharts-shaped aliases when an existing Praxis field is merely under-materialized.135136## Inventory Before New Contract137138Classify each request before editing:139140- `ja-suportado-so-ux`: canonical config already expresses the decision; sizing, theme, label, state, or event presentation needs correction.141- `ja-suportado-mal-nomeado-ou-mal-materializado`: an exported option compiler or ECharts-shaped name duplicates semantics already owned by Praxis contracts.142- `suportado-parcialmente`: token/provider, host lifecycle, event model, option compiler, or observer exists but substitution, cleanup, mapping, or tests are incomplete.143- `lacuna-real-de-contrato`: no canonical document field, runtime model, renderer-neutral event, or adapter operation can express required behavior.144145Only `lacuna-real-de-contrato` justifies a new public field or API. During beta, correct the canonical export/provider surface and update consumers in the same cycle instead of adding compatibility aliases.146147## Validation Matrix148149Choose the smallest commands that prove the changed behavior, but require assertions for every affected row:150151- adapter instance: init once, update, current-host identity, host replacement, resize, idempotent destroy, and re-render after destroy;152- handlers: ECharts `off/on`, zrender detach/attach, DOM capture detach/attach, latest payload, and deterministic duplicate suppression;153- fallback events: invalid/outside pixels, vertical/horizontal categories, bounds, multi-series semantics, tuples, objects, and primitives;154- component DI: default registration and a custom engine through the real host/provider path, with multiple chart components isolated;155- component host: zero-size defer, ready -> non-ready -> ready host recreation, observer rebind, scheduled-frame cancellation, and final cleanup;156- option compiler and transformer: supported chart families, replacement safety, canonical mapping, and no executable/raw option ingress;157- micro visualization: remains functional without instantiating ECharts;158- public API: focal library build plus a direct consumer build when exports or providers change.159160Typical focal gates are:161162```bash163npx ng test praxis-charts --watch=false --progress=false --include='projects/praxis-charts/src/lib/adapters/echarts/echarts-engine.adapter.spec.ts' --include='projects/praxis-charts/src/lib/adapters/echarts/echarts-option-builder.service.spec.ts' --include='projects/praxis-charts/src/lib/services/chart-data-transformer.service.spec.ts'164npx ng test praxis-charts --watch=false --progress=false --include='projects/praxis-charts/src/lib/components/praxis-chart/praxis-chart.component.spec.ts' --include='projects/praxis-charts/src/lib/components/praxis-micro-visualization/praxis-micro-visualization.component.spec.ts'165npm run build:praxis-charts166```167168An existing helper-only adapter spec does not prove lifecycle or event wiring. Report exact assertions that ran, gaps left unproved, derived docs/examples/manifests reviewed, and whether a direct consumer build was required.169170## Axis Contrast and Surface Evidence171172EChartsOptionBuilderService must project the effective Praxis theme.textColor into both axisLabel.color and nameTextStyle.color. Cover primary/secondary axes, horizontal orientation and scatter: styling tick values alone leaves axis names at engine defaults. Keep this mapping inside the adapter, without exposing ECharts-shaped metadata.173174Validate theme changes against both the engine canvas and the rendered HTML surface, not only text tokens or the outer widget. In `applyInheritedTheme`, an explicitly embedded/transparent chart must not inherit the page preset's contained background while taking the host foreground. Preserve the inherited palette and authored surface/background/text overrides. Test a dark/light/dark host transition with the executive page preset, the actual shell computed background, and an unchanged input document. Inspect `widget-chart-theme.playwright.spec.ts` in the Dynamic Page Lab for the real consumer proof. Axis-name mapping alone does not prove that foreground and surface provenance agree; explicit custom colors still require a coherent pair.