Praxis Charts Runtime Data
Use this skill for the Angular runtime side of Praxis charts. @praxisui/charts is the official runtime and cockpit materializer for governed chart decisions; it must not become the source of analytics business rules, metric vocabulary, SQL, or local dashboard semantics.
Pair it with:
praxis-dashboard-analyticswhen backend/stats/*,StatsFieldRegistry,@UiAnalytics, capabilities, filters, or option sources change.praxis-core-resource-runtimewhen chart data depends on core analytics schema contracts, stats request builders, resource discovery, or query context.praxis-charts-authoring-settingswhenconfig-editor, Settings Panel, or chart widget input editing changes.praxis-charts-ai-validationwhen chart authoring manifests, edit plans, validators, or registry assets change.praxis-charts-echarts-engine-boundaryfor ECharts adapter lifecycle, option building, engine providers, point-event mapping, and raw option safety.praxis-charts-analytics-interactionsfor stats execution, analytics projections,queryContext, drilldown, cross-filter, point selection, or dashboard interactions.praxis-charts-authoring-catalogsfor config editors, resource/field/target catalogs, preview mapping, and Settings Panel round-trip.praxis-charts-ai-handler-contractsfor runtime paths that are authorable by manifest operations or AI edit plans.praxis-angular-host-projectwhen a host must register providers or consume published chart packages.
Canonical Boundary
Treat PraxisXUiChartContract / x-ui.chart as the public chart document. Treat PraxisChartConfig as the runtime config derived from that document. Keep raw ECharts options behind ChartEngineAdapter, CHART_ENGINE, PraxisChartOptionBuilderService, and provider internals.
Before adding a chart input, adapter, event, data source field, stats option, or public export, inventory what the platform already knows and classify the need:
ja-suportado-so-ux: the chart/runtime can already materialize it; fix host usage, layout, or wiring.ja-suportado-mal-nomeado-ou-mal-materializado: the contract exists but chart document, projection id, resource path, label, or query mapping is wrong.suportado-parcialmente: a native chart path exists but a small platform extension is required.lacuna-real-de-contrato:x-ui.chart, core analytics, stats, capability, or option-source contracts lack data required for correct behavior.
Only lacuna-real-de-contrato justifies a new public contract. Do not solve missing metrics with frontend aliases, raw ECharts payloads, string-built stats URLs, dashboard-only field vocabularies, or keyword-based chart intent routing.
Required Source Inventory
When local praxis-ui-angular source is available, inspect the focused files before editing:
projects/praxis-charts/src/public-api.tsprojects/praxis-charts/src/lib/models/x-ui-chart.model.tsprojects/praxis-charts/src/lib/models/chart-events.model.tsprojects/praxis-charts/src/lib/models/chart-config.model.tsprojects/praxis-charts/src/lib/models/chart-dataset.model.tsprojects/praxis-charts/src/lib/services/chart-canonical-contract-mapper.service.tsprojects/praxis-charts/src/lib/services/chart-contract-normalizer.service.tsprojects/praxis-charts/src/lib/services/chart-contract-validation.service.tsprojects/praxis-charts/src/lib/services/chart-schema-mapper.service.tsprojects/praxis-charts/src/lib/services/chart-backend-payload-adapter.service.tsprojects/praxis-charts/src/lib/services/chart-stats-api.service.tsprojects/praxis-charts/src/lib/services/analytics-chart-config-adapter.service.tsprojects/praxis-charts/src/lib/services/analytics-chart-contract.service.tsprojects/praxis-charts/src/lib/components/praxis-chart/praxis-chart.component.tsprojects/praxis-charts/src/lib/praxis-chart.metadata.tsprojects/praxis-charts/src/lib/ai/praxis-charts-authoring-manifest.tsprojects/praxis-charts/src/lib/providers/charts.providers.ts- focused specs beside the changed service/model/component
Read projects/praxis-charts/AGENTS.md before editing chart runtime or authoring-adjacent code. Use praxis-angular-agents-governance if the local AGENTS file is missing, stale, or contradicts this skill.
Runtime Rules
Use <praxis-chart [chartDocument]="..."> for governed chart documents. Use [config] only when a canonical owner has already materialized PraxisChartConfig, such as a trusted adapter or a static local demo. Prefer chartDocument in dashboards, AI-authored widgets, page-builder widgets, and backend-provided catalog entries.
For remote analytics data:
- Use
source.kind = "praxis.stats"withsource.resourceandsource.operation. - Let
PraxisChartCanonicalContractMapperServicederivedataSource.query.statsPathandstatsRequest. - Let
PraxisChartStatsApiServiceexecutequery.statsPathplusquery.statsRequest. - Use
queryContextfor governed runtime context and cross-widget fan-out. The chart runtime mergesfiltersintoquery.filtersandstatsRequest.filter, and writessortandlimitto the runtimequeryobject. - Treat dynamic
queryContext.sort,limit,page, andmetaas context available onqueryRequestfor a host resolver or observability. The default stats client posts onlystatsRequest; it does not translatepage,meta, or dynamic sort into the stats payload. Static sort/limit authored inx-ui.chartremain part of the mapper-builtstatsRequestwhen the selected operation supports them. - Preserve governed
queryContext.filterExpressiononqueryRequest, but do not flatten it intostatsRequest.filter. The current defaultpraxis.statsclient rejects filter expressions with an explicit runtime error until native stats expression support is proven. - Do not claim native join support in the chart runtime. Model a cross-resource analytical need in the backend projection/stats contract or open a platform follow-up; never implement a dashboard-only join vocabulary.
- Keep capability decisions and safe metrics on the backend/catalog side; do not infer authorization from visible cards.
For declarative interactions:
- Treat
PraxisXUiChartContract.eventsas the canonical authoring document for chart interactions.PraxisChartCanonicalContractMapperServicederivesPraxisChartConfig.interactionsandeventActionsfrom it; do not wire ad hoc ECharts callbacks in hosts. - Keep
pointClickas renderer-neutral raw point evidence. Configured point-click actions must flow through the structuredpointActionoutput. - Use the typed outputs from
chart-events.model.ts:PraxisChartPointActionEvent,PraxisChartSelectionEvent,PraxisChartDrillDownEvent, andPraxisChartCrossFilterEvent. These outputs carryfilters, optional governedtarget, source point evidence, and the declared action. - Let
PraxisChartSchemaMapperServicederive widget outputs fromchart.events:pointAction,drillDown,selectionChange, andcrossFilter. Do not hand-author a different output vocabulary for Page Builder or dashboard widgets. - Keep
praxis-chart.metadata.ts,PRAXIS_CHARTS_AUTHORING_MANIFEST, component outputs, schema mapper outputs, and editor event operations aligned whenever an interaction field changes.
For x-ui.analytics.projections, use AnalyticsChartContractService and AnalyticsChartConfigAdapterService when the backend publishes discoverable analytics projections. The adapter may map projection intent to chart family, but the projection and executable stats fields remain owned by praxis-metadata-starter or the host resource.
For dashboard catalog payloads, choose the materialization path deliberately when the payload carries widget.chart:
PraxisChartBackendPayloadAdapterService.toWidgetInstancepreserves the canonical document aschartDocumentand also derivesconfig.PraxisChartSchemaMapperService.toWidgetDefinitioncurrently materializesconfiganddata; it does not preservechartDocumentfor editor round-trip.- Direct dashboard and Page Builder definitions may bind
[chartDocument]without pre-materializing config.
Do not assume the schema mapper and backend payload adapter have identical round-trip behavior. If a flow must reopen, explain, or reauthor the governed document, preserve chartDocument through the canonical path instead of reconstructing it from runtime config. Do not create a parallel widget schema if x-ui.chart plus widget shell/canvas metadata is enough.
Current governed presentations include ordinary series plus KPI, gauge, treemap, grouped scatter with two measures, funnel/pyramid, terms/histogram distribution, and comparison projections where the backend contract supports them. Each presentation must materialize from canonical capability/schema/stats evidence; do not map a chart type to a visually similar ECharts series when its dimension, measure, denominator, hierarchy, bucket, or comparison semantics are missing.
Shell Appearance Integration
Inspect praxis-chart.component.ts and praxis-micro-visualization.component.ts
when charts lose contrast inside a widget shell. Inherit shell foreground when no
explicit chart override is authored; retain deliberate chart configuration. The
accessible-data table has an opaque surface and must pair its own foreground with
that surface instead of inheriting light text onto white.
For micro visualizations, preserve --prx-micro-text-color precedence and use the
public total field for radial proportions. Card-summary radial presentations need
card-sized geometry; do not enlarge the compact table default globally. Cover both
contexts in the focused chart/micro specs and real-shell browser comparison. This
is runtime presentation, not a new governed analytics metric or chart catalog.
Presentation Microvisualizations
For <praxis-micro-visualization>, inspect
projects/praxis-charts/src/lib/components/praxis-micro-visualization/praxis-micro-visualization.component.ts
and its spec, plus the Core presentation model and HTML renderer. This path
consumes PraxisPresentationVisualizationConfig; it does not need ECharts or a
new x-ui.chart document. Use praxis-core-runtime-contracts for the canonical
distribution validity and denominator policy. Do not add consumer repair logic.
For stackedBar outside table cells, opt into the complete category legend with
legend: true and optional title. Preserve all categories, including zero
allocations; use the resolved total for both widths and localized percentages.
An explicit total above the sum leaves unallocated space. Materialized hex colors
override tones and must match between segment and swatch; tone fallback must also
match. Never give zero values a minimum visible width or shrink valid proportions.
Consume Core's getPraxisStackedBarPaintStyle for segment/swatch paint and follow
the host-token policy in praxis-core-runtime-contracts. Host gradients and
shadows that follow each category use currentColor, which Core sets locally;
do not reference --prx-micro-category-color from an ancestor token. Keep these
effects in trusted host CSS rather than metadata or a parallel chart config.
Track entry is a one-shot opacity fade, with duration/delay defaulting to 0ms
and easing to ease-out; reduced motion disables it even with host tokens set.
Preserve proportions and shadow halos: no width/scale/clip-path reveal. A zero
segment has no shadow even with host effects; its legend swatch keeps its style.
Use PraxisI18nService.getLocale() for visible and accessible percentages in
Charts; HTML consumers must pass the application locale to the Core renderer.
Keep explicit ariaLabel authoritative. Otherwise, when every segment is named,
generate the category/percentage summary even with legend: false or in table
cells; compact distributions with missing labels use fallbackText. Table cells
consume Core's normalized compact shape: no title or legend, and no HTML metadata
row. Invalid distributions render accessible fallbackText, with no partial bars
or fabricated percentages.
Run the focused microvisualization component spec and Core presentation model
spec, then the real Table and FieldShell DOM specs listed in
praxis-core-runtime-contracts. Prove computed colors, visible/zero dimensions,
all legend entries, denominator gaps, application locale selection, table
suppression, and adversarial fallback through the actual consumer. Build Core, Charts and a direct
consumer when the exported presentation contract changes; use focused consumer
E2E for affected public UI. Review package docs and public examples for parity,
and record any unexecuted consumer gates separately from source-level proof.
Apply Core's numerical regression procedure to both renderers: keep width
precision separate from rounded percentage labels; prove 201 equal categories
do not overflow, and hundreds of decimal fractions with an exact total do not
produce a false fallback, while genuinely incoherent tiny totals still fail.
Test Table with omitted/conflicting surface, rather than only a document that
already declares table-cell. For FieldShell DOM stability, require evidence that
getPresentationHtml ran through the OnPush view's own ChangeDetectorRef before
accepting an unchanged node as lifecycle proof. These gates require runtime
evidence; a skill update alone does not close a defect.
For host effects, include computed gradients/shadows, track height/radius/color,
zero-segment geometry and shadow suppression, default motion, and a real browser
reduced-motion override across Charts and the HTML consumers. A helper string or
media-query-dependent expectation alone does not prove those browser behaviors.
Operational Proof
Prove the guidance against source and focused specs before declaring the skill current:
- Happy path: map a valid
PraxisXUiChartContractwithsource.kind = "praxis.stats"; verify canonicalstatsPath, operation-specificstatsRequest, dimensions, metrics, filters, and projected rows. - Risk path: pass
queryContextwithfilters,sort,limit,page, andmeta; verify filters reachstatsRequest.filter, sort/limit reach the runtimequery, the complete context remains onqueryRequest, and the default stats POST does not silently promise unsupported dynamic pagination or ordering. - Risk path: pass a governed
queryContext.filterExpression; verifyqueryRequest.queryContext.filterExpressionis preserved and defaultpraxis.statsexecution rejects it explicitly instead of flattening it into unsafe filters. - Interaction path: configure
pointClick,selectionChange,drillDown, andcrossFilterinchartDocument.events; verify runtimeinteractions, typed component outputs, schema mapper widget outputs, metadata ports, and authoring manifest operations stay aligned. - Adversarial path: reject raw ECharts options, a host-built stats URL, a local metric alias, a frontend join contract, or a host-specific interaction vocabulary when the canonical chart/stats owner already exists.
Use the focused Angular gate from the praxis-ui-angular root, adapting the include list only when the audited surface is narrower:
npx ng test praxis-charts --watch=false --progress=false \
--include=projects/praxis-charts/src/lib/services/chart-canonical-contract-mapper.service.spec.ts \
--include=projects/praxis-charts/src/lib/services/chart-contract-normalizer.service.spec.ts \
--include=projects/praxis-charts/src/lib/services/chart-contract-validation.service.spec.ts \
--include=projects/praxis-charts/src/lib/services/chart-stats-api.service.spec.ts \
--include=projects/praxis-charts/src/lib/services/chart-schema-mapper.service.spec.ts \
--include=projects/praxis-charts/src/lib/services/chart-backend-payload-adapter.service.spec.ts \
--include=projects/praxis-charts/src/lib/components/praxis-chart/praxis-chart.component.spec.ts \
--include=projects/praxis-charts/src/lib/praxis-chart.metadata.spec.ts \
--include=projects/praxis-charts/src/lib/ai/praxis-charts-authoring-manifest.spec.ts \
--include=projects/praxis-charts/src/lib/config-editor/chart-authoring-coverage.matrix.spec.ts
npx ng build praxis-charts --configuration production
The focused specs prove Angular mapping and execution boundaries, not backend authorization, metric registration, or a published dashboard integration. Record those as unverified unless a real stats host and consumer smoke were also exercised.
Public API
Public exports in projects/praxis-charts/src/public-api.ts are contract surface. Before changing them, map impacted consumers: Angular hosts, page-builder/dynamic widget materialization, dashboard catalogs, AI registry ingestion, docs/examples, and any packages importing chart models/services.
Do not reexport another public lib's root barrel through charts as a convenience facade. If shared types are needed, prefer the canonical owner, a minimal stable export in the owner, or a structural local contract when that avoids improper coupling.
Validation
Use the narrowest reliable gate:
- changed model/mapper/validator: focused service specs for normalizer, validation, canonical mapper, schema mapper, and option builder as applicable.
- stats runtime:
chart-stats-api.service.spec.ts,analytics-chart-config-adapter.service.spec.ts, andanalytics-chart-contract.service.spec.ts. - component wiring/events: focused component specs for
PraxisChartComponent,chart-schema-mapper.service.spec.ts,praxis-chart.metadata.spec.ts, and the authoring manifest specs that provepointAction,selectionChange,drillDown,crossFilter, ports, and widget outputs. - public API change: build
@praxisui/chartsplus at least one direct consumer that imports the changed export. - dashboard integration: HTTP/schema smokes for the referenced stats resource plus Angular smoke proving
chartDocumentandqueryContextare used.
When validation is partial, state exactly which mapper/service/component specs ran and which dashboard/backend smokes remain unverified.