@praxisui/charts 3.0.0-beta.1 → 3.0.0-beta.3

package/README.md

@@ -110,6 +110,124 @@ export class ChartDemoComponent {
 
 See the public exports in `projects/praxis-charts/src/public-api.ts`.
 
+## Runtime Model
+
+O runtime atual de `@praxisui/charts` opera em duas trilhas principais:
+
+- `dataSource.kind = "local"` para datasets entregues diretamente ao componente
+- `dataSource.kind = "remote"` para datasets remotos, com foco canônico em `praxis.stats`
+
+No modo remoto, o componente:
+
+- emite `queryRequest`
+- chama `PraxisChartStatsApiService`
+- transforma a resposta agregada em `PraxisChartDataRow[]`
+- renderiza o estado `loading`, `empty`, `error` ou `ready`
+
+### Versão Pedagógica de Alto Nível
+
+Esta é a leitura adequada para documentação pública e landing pages.
+
+```mermaid
+sequenceDiagram
+    participant Host as Host
+    participant Chart as praxis-chart
+    participant Stats as PraxisChartStatsApiService
+    participant Backend as API Praxis Stats
+
+    Host->>Chart: fornece config local ou remote
+    alt fonte local
+        Chart->>Chart: transforma dados locais e renderiza
+    else fonte remota
+        Chart-->>Host: emite queryRequest
+        Chart->>Stats: executa consulta praxis.stats
+        Stats->>Backend: POST /stats/*
+        Backend-->>Stats: retorna buckets/pontos agregados
+        Stats-->>Chart: entrega linhas canônicas
+        Chart->>Chart: renderiza loading, ready, empty ou error
+    end
+```
+
+Leitura pedagógica:
+
+1. **O host entrega um contrato declarativo**, não opções brutas do engine.
+2. **O componente resolve a fonte de dados**: local ou remota.
+3. **Quando a fonte é remota, a integração canônica é `praxis.stats`**.
+4. **O chart renderiza estados de UX e a visualização final a partir de linhas canônicas**.
+
+### Versão Detalhada e Fiel ao Runtime Atual
+
+```mermaid
+sequenceDiagram
+    participant Host as Host
+    participant Chart as PraxisChartComponent
+    participant Mapper as Canonical Mapper / config remoto
+    participant Stats as PraxisChartStatsApiService
+    participant Backend as API /stats
+    participant Engine as Chart Engine Adapter
+
+    Host->>Chart: [config] e opcionalmente [data]
+    alt data explicito fornecido
+        Chart->>Chart: resolvedData = data input
+    else fonte local
+        Chart->>Chart: resolvedData = dataSource.items
+    else fonte remote
+        Chart->>Chart: buildRemoteSignature(config)
+        Chart-->>Host: queryRequest({ chartId, dataSource, query })
+        Chart->>Stats: execute(event, config)
+        Stats->>Stats: valida statsPath + statsRequest
+        Stats->>Backend: POST {statsPath}
+        Backend-->>Stats: envelope com data agregada
+        Stats->>Stats: converte buckets/points em PraxisChartDataRow[]
+        Stats-->>Chart: rows remotas resolvidas
+    end
+
+    Chart->>Chart: resolve loadState (loading/empty/error/ready)
+    alt ready
+        Chart->>Engine: render(host, { config, data })
+    else not ready
+        Chart->>Engine: destroy()
+    end
+```
+
+### Limites Atuais do Contrato Canônico
+
+O mapper `x-ui.chart -> PraxisChartConfig` já impõe limites importantes que precisam aparecer na documentação pública:
+
+- `source.kind` suportado hoje: `praxis.stats` e `derived`
+- `source.kind = "praxis.stats"` exige `source.resource` e `source.operation`
+- agregações suportadas: `count`, `sum`, `avg`, `min`, `max`
+- `distinct-count` ainda não está implementado
+- charts `pie` e `donut` aceitam apenas uma métrica
+- charts cartesianos `praxis.stats` podem declarar múltiplas métricas apenas em `group-by` e `timeseries`
+- `distribution` continua single-métrica
+- `combo` exige pelo menos duas métricas e, no modo `praxis.stats`, suporta apenas `group-by` ou `timeseries`
+- `axis: "secondary"` é exclusivo de `combo`
+- `selectionChange` e `crossFilter` declarativos ainda não estão implementados
+- `theme.variant` e `theme.palette` por token ainda não estão implementados
+
+## Fluxo Canonico de `praxis.stats`
+
+Quando o contrato remoto vem do mapper canônico, o caminho gerado hoje segue a forma:
+
+- `{resourcePath}/stats/group-by`
+- `{resourcePath}/stats/timeseries`
+- `{resourcePath}/stats/distribution`
+
+O `PraxisChartStatsApiService`:
+
+- monta a URL final usando `API_URL`
+- normaliza o path remoto
+- envia `statsRequest` via `POST`
+- converte buckets/pontos em linhas canônicas para o runtime do chart
+
+Observação importante:
+
+- o runtime atual assume envelope com `data`
+- `queryRequest` é emitido para observabilidade do host antes da execução remota
+- a execução remota automática hoje está acoplada a `praxis.stats`; não existe ainda um hook público de override do request dentro do componente
+- a trilha canônica `x-ui.chart -> PraxisChartConfig -> praxis.stats` já promove múltiplas métricas para charts cartesianos suportados; para evitar semântica enganosa, `combo` segue sendo o único caso com eixo secundário e mistura heterogênea de séries
+
 ## Current Scope
 
 This first published version is focused on the core runtime:
@@ -118,6 +236,16 @@ This first published version is focused on the core runtime:
 - canonical chart contracts and runtime models
 - the initial ECharts-based engine adapter
 - metadata and mapping hooks for registry and dynamic widget composition
+- remote execution focused on canonical `praxis.stats`
+
+## Current Non-Goals
+
+The current runtime does not yet expose as stable public surface:
+
+- direct host control over raw ECharts options as the primary contract
+- declarative cross-filter orchestration
+- declarative selectionChange runtime actions
+- palette token indirection or theme variants from `x-ui.chart`
 
 ## Notes for Hosts
 

package/fesm2022/praxisui-charts.mjs

@@ -1113,7 +1113,7 @@ const PRAXIS_CHART_COMPONENT_METADATA = {
         {
             name: 'queryRequest',
             type: 'PraxisChartQueryRequestEvent',
-            description: 'Emitted before a remote praxis.stats datasource is resolved, allowing host-side observability or overrides.',
+            description: 'Emitted before a remote praxis.stats datasource is resolved, allowing host-side observability of the outgoing request.',
         },
         {
             name: 'loadStateChange',
@@ -1617,8 +1617,13 @@ class PraxisChartCanonicalContractMapperService {
                 throw new Error('x-ui.chart combo charts over praxis.stats currently support only group-by or timeseries operations in @praxisui/charts.');
             }
         }
-        if (contract.source.kind === 'praxis.stats' && contract.metrics.length > 1 && contract.kind !== 'combo') {
-            throw new Error('x-ui.chart praxis.stats currently supports a single metric per chart in @praxisui/charts.');
+        if (contract.kind !== 'combo' && contract.metrics.some((metric) => metric.axis === 'secondary')) {
+            throw new Error('x-ui.chart axis="secondary" is supported only for combo charts in @praxisui/charts.');
+        }
+        if (contract.source.kind === 'praxis.stats'
+            && contract.source.operation === 'distribution'
+            && contract.metrics.length > 1) {
+            throw new Error('x-ui.chart praxis.stats distribution currently supports only a single metric in @praxisui/charts.');
         }
         if (contract.kind === 'horizontal-bar' && contract.orientation && contract.orientation !== 'horizontal') {
             throw new Error('x-ui.chart kind="horizontal-bar" requires orientation="horizontal" when orientation is provided.');
@@ -1640,6 +1645,7 @@ class PraxisChartCanonicalContractMapperService {
         const firstDimension = contract.dimensions?.[0];
         const firstMetric = contract.metrics?.[0];
         const secondaryMetric = contract.metrics?.find((metric) => metric.axis === 'secondary');
+        const metricCount = contract.metrics?.length ?? 0;
         if (contract.kind === 'pie' || contract.kind === 'donut') {
             return {
                 x: {
@@ -1669,7 +1675,7 @@ class PraxisChartCanonicalContractMapperService {
                 type: firstDimension?.role === 'time' ? 'time' : 'category',
             },
             y: {
-                label: this.toLabel(firstMetric?.label),
+                label: metricCount > 1 ? undefined : this.toLabel(firstMetric?.label),
                 type: 'value',
             },
             ySecondary: contract.kind === 'combo' && secondaryMetric
@@ -2518,6 +2524,72 @@ const PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA = {
         },
     },
 };
+const PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR = {
+    schemaMeta: {
+        schemaId: 'api/human-resources/vw-analytics-folha-pagamento|post|response|tenant:demo|locale:pt-BR',
+        schemaHash: 'published-hash-payroll-multi-metric-bar-v1',
+        resourcePath: 'api/human-resources/vw-analytics-folha-pagamento',
+        operation: 'post',
+        schemaType: 'response',
+        source: 'backend',
+    },
+    widget: {
+        kind: 'x-ui.chart',
+        key: 'payroll-multi-metric-bar',
+        layout: { col: 1, row: 13, colSpan: 12, rowSpan: 4 },
+        shell: {
+            title: 'Comparativo por departamento',
+            subtitle: 'Bar chart multi-metrico sobre praxis.stats group-by',
+        },
+        chart: {
+            version: '0.1.0',
+            kind: 'bar',
+            preset: 'comparison',
+            chartId: 'payroll-multi-metric-bar',
+            title: { key: 'charts.payroll.multiMetric.title', fallback: 'Comparativo por departamento' },
+            subtitle: {
+                key: 'charts.payroll.multiMetric.subtitle',
+                fallback: 'Massa liquida e desconto medio via group-by sem eixo secundario',
+            },
+            height: 340,
+            source: {
+                kind: 'praxis.stats',
+                resource: 'api/human-resources/vw-analytics-folha-pagamento',
+                operation: 'group-by',
+                options: {
+                    orderBy: 'value-desc',
+                    limit: 8,
+                },
+            },
+            dimensions: [
+                {
+                    field: 'departamento',
+                    label: 'Departamento',
+                    role: 'category',
+                },
+            ],
+            metrics: [
+                {
+                    field: 'salarioLiquido',
+                    label: 'Massa liquida',
+                    aggregation: 'sum',
+                    color: '#1263b4',
+                },
+                {
+                    field: 'pctDesconto',
+                    label: 'Desconto medio',
+                    aggregation: 'avg',
+                    color: '#0f766e',
+                },
+            ],
+            legend: { enabled: true },
+            tooltip: { enabled: true },
+            theme: {
+                palette: ['#1263b4', '#0f766e'],
+            },
+        },
+    },
+};
 const PRAXIS_CHART_BACKEND_MOCK_SCATTER = {
     schemaMeta: {
         schemaId: 'api/human-resources/vw-analytics-folha-pagamento|post|response|tenant:demo|locale:pt-BR',
@@ -2650,6 +2722,7 @@ function buildPraxisChartMockWidgetPage(adapter) {
             withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_DONUT)),
             withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_HORIZONTAL_BAR)),
             withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA)),
+            withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR)),
             withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_SCATTER)),
             withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_COMBO)),
         ],
@@ -2668,6 +2741,7 @@ function buildPraxisChartMockGridPage(adapter) {
             withShowcaseViewToggle(adapter.toGridWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_DONUT)),
             withShowcaseViewToggle(adapter.toGridWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_HORIZONTAL_BAR)),
             withShowcaseViewToggle(adapter.toGridWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA)),
+            withShowcaseViewToggle(adapter.toGridWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR)),
             withShowcaseViewToggle(adapter.toGridWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_SCATTER)),
             withShowcaseViewToggle(adapter.toGridWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_COMBO)),
         ],
@@ -2714,6 +2788,7 @@ function buildPraxisChartInteractiveWidgetPage(adapter) {
             },
             withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_DONUT)),
             withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA)),
+            withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR)),
             withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_SCATTER)),
             withShowcaseViewToggle(adapter.toWidgetInstance(PRAXIS_CHART_BACKEND_MOCK_COMBO)),
         ],
@@ -2768,18 +2843,25 @@ function buildPraxisChartInteractiveGridPage(adapter) {
                     layout: { col: 1, row: 13, colSpan: 12, rowSpan: 4 },
                 },
             })),
+            withShowcaseViewToggle(adapter.toGridWidgetInstance({
+                ...PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR,
+                widget: {
+                    ...PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR.widget,
+                    layout: { col: 1, row: 17, colSpan: 12, rowSpan: 4 },
+                },
+            })),
             withShowcaseViewToggle(adapter.toGridWidgetInstance({
                 ...PRAXIS_CHART_BACKEND_MOCK_SCATTER,
                 widget: {
                     ...PRAXIS_CHART_BACKEND_MOCK_SCATTER.widget,
-                    layout: { col: 1, row: 17, colSpan: 12, rowSpan: 4 },
+                    layout: { col: 1, row: 21, colSpan: 12, rowSpan: 4 },
                 },
             })),
             withShowcaseViewToggle(adapter.toGridWidgetInstance({
                 ...PRAXIS_CHART_BACKEND_MOCK_COMBO,
                 widget: {
                     ...PRAXIS_CHART_BACKEND_MOCK_COMBO.widget,
-                    layout: { col: 1, row: 21, colSpan: 12, rowSpan: 4 },
+                    layout: { col: 1, row: 25, colSpan: 12, rowSpan: 4 },
                 },
             })),
         ],
@@ -3007,6 +3089,8 @@ class PraxisChartCompositionShowcaseComponent {
                 return 'Envelope horizontal-bar';
             case 'stacked-area':
                 return 'Envelope stacked-area';
+            case 'multi-metric-bar':
+                return 'Envelope multi-metric bar';
             case 'scatter':
                 return 'Envelope scatter';
             case 'combo':
@@ -3027,6 +3111,8 @@ class PraxisChartCompositionShowcaseComponent {
                 return PRAXIS_CHART_BACKEND_MOCK_HORIZONTAL_BAR;
             case 'stacked-area':
                 return PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA;
+            case 'multi-metric-bar':
+                return PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR;
             case 'scatter':
                 return PRAXIS_CHART_BACKEND_MOCK_SCATTER;
             case 'combo':
@@ -3081,6 +3167,9 @@ class PraxisChartCompositionShowcaseComponent {
               <button type="button" [class.active]="payloadMode() === 'stacked-area'" (click)="payloadMode.set('stacked-area')">
                 Stacked area
               </button>
+              <button type="button" [class.active]="payloadMode() === 'multi-metric-bar'" (click)="payloadMode.set('multi-metric-bar')">
+                Multi-metric bar
+              </button>
               <button type="button" [class.active]="payloadMode() === 'scatter'" (click)="payloadMode.set('scatter')">
                 Scatter
               </button>
@@ -3195,6 +3284,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
               <button type="button" [class.active]="payloadMode() === 'stacked-area'" (click)="payloadMode.set('stacked-area')">
                 Stacked area
               </button>
+              <button type="button" [class.active]="payloadMode() === 'multi-metric-bar'" (click)="payloadMode.set('multi-metric-bar')">
+                Multi-metric bar
+              </button>
               <button type="button" [class.active]="payloadMode() === 'scatter'" (click)="payloadMode.set('scatter')">
                 Scatter
               </button>
@@ -3272,5 +3364,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.17", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-export { PRAXIS_CHART_BACKEND_MOCK_BAR, PRAXIS_CHART_BACKEND_MOCK_COMBO, PRAXIS_CHART_BACKEND_MOCK_DONUT, PRAXIS_CHART_BACKEND_MOCK_HORIZONTAL_BAR, PRAXIS_CHART_BACKEND_MOCK_SCATTER, PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA, PRAXIS_CHART_BACKEND_MOCK_TIMESERIES, PRAXIS_CHART_COMPONENT_METADATA, PRAXIS_CHART_DRILLDOWN_DATA_BY_MONTH, PRAXIS_CHART_DRILLDOWN_PANEL_METADATA, PRAXIS_CHART_ENGINE, PRAXIS_CHART_STATE_PROBE_COMPONENT_METADATA, PraxisChartBackendPayloadAdapterService, PraxisChartCanonicalContractMapperService, PraxisChartComponent, PraxisChartCompositionShowcaseComponent, PraxisChartDataTransformerService, PraxisChartDrilldownPanelComponent, PraxisChartOptionBuilderService, PraxisChartSchemaMapperService, PraxisChartStateProbeComponent, PraxisChartStatsApiService, buildPraxisChartInteractiveGridPage, buildPraxisChartInteractiveWidgetPage, buildPraxisChartMockGridPage, buildPraxisChartMockWidgetPage, providePraxisChartDrilldownPanelMetadata, providePraxisChartStateProbeMetadata, providePraxisCharts, providePraxisChartsMetadata };
+export { PRAXIS_CHART_BACKEND_MOCK_BAR, PRAXIS_CHART_BACKEND_MOCK_COMBO, PRAXIS_CHART_BACKEND_MOCK_DONUT, PRAXIS_CHART_BACKEND_MOCK_HORIZONTAL_BAR, PRAXIS_CHART_BACKEND_MOCK_MULTI_METRIC_BAR, PRAXIS_CHART_BACKEND_MOCK_SCATTER, PRAXIS_CHART_BACKEND_MOCK_STACKED_AREA, PRAXIS_CHART_BACKEND_MOCK_TIMESERIES, PRAXIS_CHART_COMPONENT_METADATA, PRAXIS_CHART_DRILLDOWN_DATA_BY_MONTH, PRAXIS_CHART_DRILLDOWN_PANEL_METADATA, PRAXIS_CHART_ENGINE, PRAXIS_CHART_STATE_PROBE_COMPONENT_METADATA, PraxisChartBackendPayloadAdapterService, PraxisChartCanonicalContractMapperService, PraxisChartComponent, PraxisChartCompositionShowcaseComponent, PraxisChartDataTransformerService, PraxisChartDrilldownPanelComponent, PraxisChartOptionBuilderService, PraxisChartSchemaMapperService, PraxisChartStateProbeComponent, PraxisChartStatsApiService, buildPraxisChartInteractiveGridPage, buildPraxisChartInteractiveWidgetPage, buildPraxisChartMockGridPage, buildPraxisChartMockWidgetPage, providePraxisChartDrilldownPanelMetadata, providePraxisChartStateProbeMetadata, providePraxisCharts, providePraxisChartsMetadata };
 //# sourceMappingURL=praxisui-charts.mjs.map