Ergon Dashboard Praxis Charts
Core Rule
Apply the root migration AGENTS.md before changing dashboard contracts,
analytics metadata, chart catalog shape, or Angular chart materialization.
Classify public contract or architecture changes in the phase/gate and record
whether the canonical owner is the Ergon dashboard host, praxis-dashboard
contracts, praxis-metadata-starter, praxis-config-starter, or
praxis-ui-angular.
Use this skill when working on Ergon dashboard chart materialization. Pair it with:
praxis-dashboard-analytics for backend /stats/*, @UiAnalytics, StatsFieldRegistry, and x-ui.analytics.projections.
praxis-angular-host-project for Angular host bootstrap, providers, routes, API URL, and Praxis package consumption.
praxis-ui-product-design only when visual polish, responsive layout, or screenshot QA is explicitly in scope.
praxis-dto-annotations when chart fields, filters, numeric semantics, @UiAnalytics, @Schema, @UISchema, x-ui.analytics, /schemas/filtered, or OpenAPI metadata change.
praxis-resource-entity-lookup-backend when dashboard filters or drill-down targets use governed option sources.
Do not create a custom chart abstraction over ECharts for Ergon dashboards. Use @praxisui/charts and keep ECharts behind the Praxis engine adapter.
Before adding dashboard-specific frontend adapters, inventory native Praxis
Charts/analytics support and classify the need as ja-suportado-so-ux,
ja-suportado-mal-nomeado-ou-mal-materializado, suportado-parcialmente, or
lacuna-real-de-contrato. Only real contract gaps should become Praxis Platform Follow-up; supported cases must use the native runtime path.
Contract Entry Gate
Before editing Ergon dashboard catalog, chart widgets, or Angular wiring, audit the canonical sources in this order:
praxis-metadata-starter: /stats/*, StatsFieldRegistry, @UiAnalytics, x-ui.analytics.projections, /schemas/filtered, capabilities, option sources, and the draft docs/spec/x-ui-chart.schema.json.
praxis-ui-angular: @praxisui/charts, PraxisXUiChartContract, PraxisChartComponent, PraxisChartCanonicalContractMapperService, PraxisChartStatsApiService, authoring manifest, and current component tests for chartDocument, queryContext, crossFilter, and load state.
- Ergon dashboard host artifacts:
GET /api/dashboard/catalog, load status, loadPolicy, capability decisions, official first-fold panels, and the stats resources that the catalog references.
Classify every requested dashboard improvement before adding a field, endpoint, adapter, or widget:
ja-suportado-so-ux: native chart/stat metadata exists; the Ergon UI must render or arrange it better.
ja-suportado-mal-nomeado-ou-mal-materializado: canonical data exists but catalog keys, labels, projection ids, or chart document fields need alignment.
suportado-parcialmente: a canonical surface exists but a small platform extension or host materialization is required.
lacuna-real-de-contrato: the dashboard cannot be implemented correctly without extending the canonical x-ui.chart, stats, capability, option-source, or chart-runtime contract.
Only lacuna-real-de-contrato justifies a new public contract. In that case, record the canonical owner, impacted consumers, derived docs/examples, minimum tests, and breaking-change risk before editing. Do not satisfy a cockpit-specific need by publishing raw ECharts options, local metric aliases, UI-only permissions, keyword-routed filters, or dashboard-only field vocabularies.
Workflow
- Read the current dashboard artifacts before editing:
D:\Developer\Techne\ErgonX\migracao\docs\migracao\dashboard-implementation-plan.md
D:\Developer\Techne\ErgonX\migracao\docs\migracao\dashboard-praxis-angular-charts-investigation.md
D:\Developer\Techne\ErgonX\migracao\docs\migracao\dashboard-gate.md
- If changing chart contracts or catalog shape, read
references/dashboard-chart-contracts.md.
- Prefer evolving
GET /api/dashboard/catalog to publish official chartDocument entries before adding frontend hardcode.
- Materialize official charts with
<praxis-chart [chartDocument]="...">; use [config] only when the backend or host already materialized PraxisChartConfig.
- Pass dashboard filters through structured
[queryContext]; do not manually concatenate statsPath, derive endpoints from strings, or duplicate stats request construction in Angular when x-ui.chart can derive it.
- Enforce Ergon load policy in the UI: do not query resources marked
READ_ONLY_BOUNDED_LEGACY during first paint or without explicit bounded period.
- Treat
STALE as blocked by default. For pilot/demo only, it may render first-fold charts when GET /api/dashboard/catalog publishes panels[].loadPolicy.allowStaleFirstPaint=true; keep Carga desatualizada visible and keep NOT_CONFIGURED, DENIED, ERROR_PUBLIC, RUNNING, PENDING, and READ_ONLY_BOUNDED_LEGACY blocked.
- Verify that user, empresa, HADES transaction, SQL, owner/schema, package names,
ROWID, FLAG_PACK, and internal metric aliases stay server-side.
- Verify that capability-protected metrics, such as folha amount charts, are absent or blocked unless the catalog publishes the required public capability decision. Do not infer authorization from menu visibility or card presence.
Required Frontend Pattern
Register charts once in the Angular host:
import { providePraxisCharts } from '@praxisui/charts';
export const appConfig = {
providers: [
...providePraxisCharts(),
],
};
Render charts through the Praxis component:
<praxis-chart
[chartDocument]="chartDocument"
[queryContext]="queryContext"
(queryRequest)="onQueryRequest($event)"
(loadStateChange)="onLoadStateChange($event)"
(crossFilter)="onCrossFilter($event)"
/>
Backend Contract Preference
For Ergon Cockpit charts, prefer:
source.kind = "praxis.stats"
source.resource = "api/dashboard/<recurso-agregado>"
source.operation = "group-by" | "timeseries" | "distribution"
sizing.mode = "fill-container" inside dashboard widgets
theme.surface.mode = "embedded" when the dashboard shell owns the card surface
Use x-ui.analytics.projections from /schemas/filtered for discovery and validation. Use GET /api/dashboard/catalog as the product-level source of official first-fold and drill-down charts.
GET /api/dashboard/catalog is a materialized product decision, not the owner of the chart vocabulary. It may choose which governed chart documents appear for the Cockpit, but x-ui.chart shape, stats operations, query context, events, sizing, theming, and validation must remain compatible with the canonical Praxis contracts.
When catalog entries include drill-down or cross-filter behavior, model them as structured chartDocument.events and governed queryContext mappings. Do not encode target selection with command words, regex matching, metric-name conventions, or Angular-specific switch statements.
Validation
Before calling the frontend ready:
- Confirm
@praxisui/charts is installed/available in the host.
- Confirm
providePraxisCharts() is registered.
- Confirm official dashboard widgets receive
chartDocument from catalog or a governed adapter, not local ad hoc ECharts options.
- Confirm each
chartDocument validates against PraxisXUiChartContract and uses source.kind="praxis.stats" with operation/resource/fields that exist in stats metadata.
- Confirm cross-filter and drill-down mappings emit structured
queryContext or governed navigation targets, not local keyword routing.
- Confirm
vinculos-agregados and folha-agregada charts point to their validated /stats/* resources.
- Confirm
frequencias-agregadas and horas-extras-agregadas obey requiresExplicitPeriod=true, maxPeriodDays, and firstPaintEligible=false when applicable.
- Confirm option-source-backed filters use governed option-source descriptors and by-ids reload behavior when selected labels must survive reopen or shared links.
- Confirm
STALE without allowStaleFirstPaint=true renders no chart/canvas and calls no /stats/*; confirm approved STALE renders with a visible stale warning.
- Run the relevant Angular tests/build and, for UI changes, perform browser/screenshot QA.
For the approved Ergon pilot/demo STALE path, use the repeatable local gate:
powershell -NoProfile -ExecutionPolicy Bypass `
-File tools/migration-factory/run-dashboard-stale-approved-pilot.ps1
This starts isolated backend/UI ports, enables ERGON_DASHBOARD_ALLOW_STALE_FIRST_PAINT=true, runs HTTP smoke, readiness without override, real Angular QA, writes evidence, and shuts down the temporary servers.
1---2name: ergon-dashboard-praxis-charts3description: Design, implement, or review the Ergon post-login Cockpit/dashboard frontend contract using Praxis Charts. Use when Codex must connect Ergon dashboard backend resources, GET /api/dashboard/catalog, x-ui.chart/PraxisXUiChartContract, x-ui.analytics.projections, @praxisui/charts, PraxisChartComponent, providePraxisCharts(), queryContext, load policies, or chart widgets before or during Angular UI implementation.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/ergon-dashboard-praxis-charts6---78# Ergon Dashboard Praxis Charts910## Core Rule1112Apply the root migration `AGENTS.md` before changing dashboard contracts,13analytics metadata, chart catalog shape, or Angular chart materialization.14Classify public contract or architecture changes in the phase/gate and record15whether the canonical owner is the Ergon dashboard host, `praxis-dashboard`16contracts, `praxis-metadata-starter`, `praxis-config-starter`, or17`praxis-ui-angular`.1819Use this skill when working on Ergon dashboard chart materialization. Pair it with:2021- `praxis-dashboard-analytics` for backend `/stats/*`, `@UiAnalytics`, `StatsFieldRegistry`, and `x-ui.analytics.projections`.22- `praxis-angular-host-project` for Angular host bootstrap, providers, routes, API URL, and Praxis package consumption.23- `praxis-ui-product-design` only when visual polish, responsive layout, or screenshot QA is explicitly in scope.24- `praxis-dto-annotations` when chart fields, filters, numeric semantics, `@UiAnalytics`, `@Schema`, `@UISchema`, `x-ui.analytics`, `/schemas/filtered`, or OpenAPI metadata change.25- `praxis-resource-entity-lookup-backend` when dashboard filters or drill-down targets use governed option sources.2627Do not create a custom chart abstraction over ECharts for Ergon dashboards. Use `@praxisui/charts` and keep ECharts behind the Praxis engine adapter.2829Before adding dashboard-specific frontend adapters, inventory native Praxis30Charts/analytics support and classify the need as `ja-suportado-so-ux`,31`ja-suportado-mal-nomeado-ou-mal-materializado`, `suportado-parcialmente`, or32`lacuna-real-de-contrato`. Only real contract gaps should become `Praxis33Platform Follow-up`; supported cases must use the native runtime path.3435## Contract Entry Gate3637Before editing Ergon dashboard catalog, chart widgets, or Angular wiring, audit the canonical sources in this order:38391. `praxis-metadata-starter`: `/stats/*`, `StatsFieldRegistry`, `@UiAnalytics`, `x-ui.analytics.projections`, `/schemas/filtered`, capabilities, option sources, and the draft `docs/spec/x-ui-chart.schema.json`.402. `praxis-ui-angular`: `@praxisui/charts`, `PraxisXUiChartContract`, `PraxisChartComponent`, `PraxisChartCanonicalContractMapperService`, `PraxisChartStatsApiService`, authoring manifest, and current component tests for `chartDocument`, `queryContext`, `crossFilter`, and load state.413. Ergon dashboard host artifacts: `GET /api/dashboard/catalog`, load status, `loadPolicy`, capability decisions, official first-fold panels, and the stats resources that the catalog references.4243Classify every requested dashboard improvement before adding a field, endpoint, adapter, or widget:4445- `ja-suportado-so-ux`: native chart/stat metadata exists; the Ergon UI must render or arrange it better.46- `ja-suportado-mal-nomeado-ou-mal-materializado`: canonical data exists but catalog keys, labels, projection ids, or chart document fields need alignment.47- `suportado-parcialmente`: a canonical surface exists but a small platform extension or host materialization is required.48- `lacuna-real-de-contrato`: the dashboard cannot be implemented correctly without extending the canonical `x-ui.chart`, stats, capability, option-source, or chart-runtime contract.4950Only `lacuna-real-de-contrato` justifies a new public contract. In that case, record the canonical owner, impacted consumers, derived docs/examples, minimum tests, and breaking-change risk before editing. Do not satisfy a cockpit-specific need by publishing raw ECharts options, local metric aliases, UI-only permissions, keyword-routed filters, or dashboard-only field vocabularies.5152## Workflow53541. Read the current dashboard artifacts before editing:55 - `D:\Developer\Techne\ErgonX\migracao\docs\migracao\dashboard-implementation-plan.md`56 - `D:\Developer\Techne\ErgonX\migracao\docs\migracao\dashboard-praxis-angular-charts-investigation.md`57 - `D:\Developer\Techne\ErgonX\migracao\docs\migracao\dashboard-gate.md`582. If changing chart contracts or catalog shape, read `references/dashboard-chart-contracts.md`.593. Prefer evolving `GET /api/dashboard/catalog` to publish official `chartDocument` entries before adding frontend hardcode.604. Materialize official charts with `<praxis-chart [chartDocument]="...">`; use `[config]` only when the backend or host already materialized `PraxisChartConfig`.615. Pass dashboard filters through structured `[queryContext]`; do not manually concatenate `statsPath`, derive endpoints from strings, or duplicate stats request construction in Angular when `x-ui.chart` can derive it.626. Enforce Ergon load policy in the UI: do not query resources marked `READ_ONLY_BOUNDED_LEGACY` during first paint or without explicit bounded period.637. Treat `STALE` as blocked by default. For pilot/demo only, it may render first-fold charts when `GET /api/dashboard/catalog` publishes `panels[].loadPolicy.allowStaleFirstPaint=true`; keep `Carga desatualizada` visible and keep `NOT_CONFIGURED`, `DENIED`, `ERROR_PUBLIC`, `RUNNING`, `PENDING`, and `READ_ONLY_BOUNDED_LEGACY` blocked.648. Verify that user, empresa, HADES transaction, SQL, owner/schema, package names, `ROWID`, `FLAG_PACK`, and internal metric aliases stay server-side.659. Verify that capability-protected metrics, such as folha amount charts, are absent or blocked unless the catalog publishes the required public capability decision. Do not infer authorization from menu visibility or card presence.6667## Required Frontend Pattern6869Register charts once in the Angular host:7071```ts72import { providePraxisCharts } from '@praxisui/charts';7374export const appConfig = {75 providers: [76 ...providePraxisCharts(),77 ],78};79```8081Render charts through the Praxis component:8283```html84<praxis-chart85 [chartDocument]="chartDocument"86 [queryContext]="queryContext"87 (queryRequest)="onQueryRequest($event)"88 (loadStateChange)="onLoadStateChange($event)"89 (crossFilter)="onCrossFilter($event)"90/>91```9293## Backend Contract Preference9495For Ergon Cockpit charts, prefer:9697- `source.kind = "praxis.stats"`98- `source.resource = "api/dashboard/<recurso-agregado>"`99- `source.operation = "group-by" | "timeseries" | "distribution"`100- `sizing.mode = "fill-container"` inside dashboard widgets101- `theme.surface.mode = "embedded"` when the dashboard shell owns the card surface102103Use `x-ui.analytics.projections` from `/schemas/filtered` for discovery and validation. Use `GET /api/dashboard/catalog` as the product-level source of official first-fold and drill-down charts.104105`GET /api/dashboard/catalog` is a materialized product decision, not the owner of the chart vocabulary. It may choose which governed chart documents appear for the Cockpit, but `x-ui.chart` shape, stats operations, query context, events, sizing, theming, and validation must remain compatible with the canonical Praxis contracts.106107When catalog entries include drill-down or cross-filter behavior, model them as structured `chartDocument.events` and governed `queryContext` mappings. Do not encode target selection with command words, regex matching, metric-name conventions, or Angular-specific switch statements.108109## Validation110111Before calling the frontend ready:112113- Confirm `@praxisui/charts` is installed/available in the host.114- Confirm `providePraxisCharts()` is registered.115- Confirm official dashboard widgets receive `chartDocument` from catalog or a governed adapter, not local ad hoc ECharts options.116- Confirm each `chartDocument` validates against `PraxisXUiChartContract` and uses `source.kind="praxis.stats"` with operation/resource/fields that exist in stats metadata.117- Confirm cross-filter and drill-down mappings emit structured `queryContext` or governed navigation targets, not local keyword routing.118- Confirm `vinculos-agregados` and `folha-agregada` charts point to their validated `/stats/*` resources.119- Confirm `frequencias-agregadas` and `horas-extras-agregadas` obey `requiresExplicitPeriod=true`, `maxPeriodDays`, and `firstPaintEligible=false` when applicable.120- Confirm option-source-backed filters use governed option-source descriptors and by-ids reload behavior when selected labels must survive reopen or shared links.121- Confirm `STALE` without `allowStaleFirstPaint=true` renders no chart/canvas and calls no `/stats/*`; confirm approved `STALE` renders with a visible stale warning.122- Run the relevant Angular tests/build and, for UI changes, perform browser/screenshot QA.123124For the approved Ergon pilot/demo `STALE` path, use the repeatable local gate:125126```powershell127powershell -NoProfile -ExecutionPolicy Bypass `128 -File tools/migration-factory/run-dashboard-stale-approved-pilot.ps1129```130131This starts isolated backend/UI ports, enables `ERGON_DASHBOARD_ALLOW_STALE_FIRST_PAINT=true`, runs HTTP smoke, readiness without override, real Angular QA, writes evidence, and shuts down the temporary servers.