@praxisui/charts 10.0.0-rc.3 → 10.0.0-rc.31

package/README.md

@@ -257,6 +257,26 @@ 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.
+
 ## 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.
@@ -291,13 +311,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.
 

package/ai/component-registry.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-07T02:07:06.204Z",
+  "generatedAt": "2026-10-16T17:45:27.774Z",
   "packageName": "@praxisui/charts",
-  "packageVersion": "10.0.0-rc.3",
+  "packageVersion": "10.0.0-rc.31",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
-  "componentCount": 3,
+  "componentCount": 4,
   "components": {
     "praxis-analytics-presentation": {
       "id": "praxis-analytics-presentation",
@@ -424,6 +424,13 @@
             }
           }
         },
+        {
+          "name": "resourceKey",
+          "type": "string | null",
+          "required": false,
+          "description": "Canonical resource identifier used to automatically discover and execute /stats services on the Praxis backend.",
+          "default": null
+        },
         {
           "name": "data",
           "type": "PraxisChartDataRow[]",
@@ -687,6 +694,22 @@
             "group": "config"
           }
         },
+        {
+          "id": "resourceKey",
+          "label": "Resource Key",
+          "direction": "input",
+          "semanticKind": "value",
+          "description": "Canonical resource identifier used to automatically discover and execute /stats services on the Praxis backend.",
+          "schema": {
+            "id": "string",
+            "kind": "ts-type",
+            "ref": "string"
+          },
+          "exposure": {
+            "public": true,
+            "group": "data"
+          }
+        },
         {
           "id": "pointClick",
           "label": "Point Click",
@@ -1244,7 +1267,6 @@
         }
       ],
       "configEditor": {
-        "component": "[ref:PraxisChartWidgetConfigEditor]",
         "title": "Configure chart"
       },
       "authoringManifestRef": {
@@ -3547,9 +3569,9 @@
         {
           "chunkIndex": 0,
           "chunkKind": "summary",
-          "content": "Component ID: praxis-chart\nSelector: praxis-chart\nFriendly Name: Praxis Chart\nDescription: Chart component for analytics and metadata-driven visualizations in Praxis UI.\nLib/Package: @praxisui/charts\nTags: chart, analytics, widget, visualization\nInputs:\n  - config (PraxisChartConfig)\n  - data (PraxisChartDataRow[])\n  - chartDocument (PraxisXUiChartContract | null)\n  - queryContext (PraxisDataQueryContext | null)\n  - remoteDataResolver (PraxisChartRemoteDataResolver | null)\n  - filterCriteria (Record<string, unknown> | null)\n  - enableCustomization (boolean)\n  - availableResources (ReadonlyArray<ChartEditorResourceOption>)\n  - availableFields (ReadonlyArray<ChartEditorFieldOption>)\n  - availableTargets (ReadonlyArray<ChartEditorTargetOption>)\nOutputs:\n  - pointClick (PraxisChartPointEvent)\n  - pointAction (PraxisChartPointActionEvent)\n  - selectionChange (PraxisChartSelectionEvent)\n  - drillDown (PraxisChartDrillDownEvent)\n  - crossFilter (PraxisChartCrossFilterEvent)\n  - queryRequest (PraxisChartQueryRequestEvent)\n  - loadStateChange (PraxisChartLoadState)\n  - chartDocumentApplied (PraxisXUiChartContract)\n  - chartDocumentSaved (PraxisXUiChartContract)\n  - chartDocumentPatchChange (PraxisChartDocumentPatchChangeEvent)\nInsertion Presets:\n  - canonical-chart: Canonical chart - Creates a chart widget from the canonical x-ui.chart authoring document.\n",
+          "content": "Component ID: praxis-chart\nSelector: praxis-chart\nFriendly Name: Praxis Chart\nDescription: Chart component for analytics and metadata-driven visualizations in Praxis UI.\nLib/Package: @praxisui/charts\nTags: chart, analytics, widget, visualization\nInputs:\n  - config (PraxisChartConfig)\n  - resourceKey (string | null)\n  - data (PraxisChartDataRow[])\n  - chartDocument (PraxisXUiChartContract | null)\n  - queryContext (PraxisDataQueryContext | null)\n  - remoteDataResolver (PraxisChartRemoteDataResolver | null)\n  - filterCriteria (Record<string, unknown> | null)\n  - enableCustomization (boolean)\n  - availableResources (ReadonlyArray<ChartEditorResourceOption>)\n  - availableFields (ReadonlyArray<ChartEditorFieldOption>)\n  - availableTargets (ReadonlyArray<ChartEditorTargetOption>)\nOutputs:\n  - pointClick (PraxisChartPointEvent)\n  - pointAction (PraxisChartPointActionEvent)\n  - selectionChange (PraxisChartSelectionEvent)\n  - drillDown (PraxisChartDrillDownEvent)\n  - crossFilter (PraxisChartCrossFilterEvent)\n  - queryRequest (PraxisChartQueryRequestEvent)\n  - loadStateChange (PraxisChartLoadState)\n  - chartDocumentApplied (PraxisXUiChartContract)\n  - chartDocumentSaved (PraxisXUiChartContract)\n  - chartDocumentPatchChange (PraxisChartDocumentPatchChangeEvent)\nInsertion Presets:\n  - canonical-chart: Canonical chart - Creates a chart widget from the canonical x-ui.chart authoring document.\n",
           "sourcePointer": "projects/praxis-charts/src/lib/praxis-chart.metadata.ts",
-          "contentHash": "2ca641ce6260ffda9f9278a77c49b6538d96b1bf61640cf269ba510b521af788",
+          "contentHash": "e1c99961aba854e05112df6c72c6dd3d90a1d9ef8bc3b8d03c5f956f624835cc",
           "sourceKind": "component_definition",
           "sourceId": "praxis-chart",
           "corpusVersion": "1.0.0"
@@ -3839,6 +3861,181 @@
           "corpusVersion": "1.0.0"
         }
       ]
+    },
+    "praxis-micro-visualization": {
+      "id": "praxis-micro-visualization",
+      "description": "Renderiza micro-visualizações ultraleves e autônomas (bullet, radial, sparkline, processFlow, comparison, etc.) como widget independente no canvas ou célula.",
+      "inputs": [
+        {
+          "name": "visualization",
+          "type": "PraxisPresentationVisualizationConfig",
+          "required": false,
+          "description": "Configuração estruturada da micro-visualização (kind, value, target, points, thresholds, tone, etc.).",
+          "default": {
+            "kind": "radial",
+            "value": 75,
+            "total": 100,
+            "tone": "primary",
+            "fallbackText": "75%"
+          }
+        },
+        {
+          "name": "fallbackText",
+          "type": "string",
+          "required": false,
+          "description": "Texto exibido caso a visualização não seja suportada ou esteja em fallback.",
+          "default": ""
+        }
+      ],
+      "outputs": [],
+      "configSchemaId": null,
+      "selector": "praxis-micro-visualization",
+      "friendlyName": "Micro-visualização Analítica",
+      "icon": "ssid_chart",
+      "tags": [
+        "chart",
+        "analytics",
+        "widget",
+        "microchart",
+        "visualization",
+        "sparkline",
+        "bullet",
+        "radial"
+      ],
+      "lib": "@praxisui/charts",
+      "insertionPresets": [
+        {
+          "id": "bullet-kpi",
+          "label": "Bullet Graph KPI",
+          "description": "Microchart do tipo bullet com faixas de tolerância e valor meta.",
+          "icon": "linear_scale",
+          "inputs": {
+            "visualization": {
+              "kind": "bullet",
+              "value": 78,
+              "target": 90,
+              "total": 100,
+              "tone": "success",
+              "fallbackText": "Performance Operacional",
+              "thresholds": [
+                {
+                  "value": 50,
+                  "tone": "danger",
+                  "label": "Crítico"
+                },
+                {
+                  "value": 75,
+                  "tone": "warning",
+                  "label": "Atenção"
+                },
+                {
+                  "value": 100,
+                  "tone": "success",
+                  "label": "Ideal"
+                }
+              ]
+            }
+          }
+        },
+        {
+          "id": "radial-score",
+          "label": "Radial Score",
+          "description": "Medidor circular compacto de pontuação ou progresso percentual.",
+          "icon": "radio_button_checked",
+          "inputs": {
+            "visualization": {
+              "kind": "radial",
+              "value": 85,
+              "total": 100,
+              "tone": "primary",
+              "fallbackText": "Prontidão: 85%"
+            }
+          }
+        },
+        {
+          "id": "sparkline-area",
+          "label": "Sparkline de Tendência (Área)",
+          "description": "Minigráfico contínuo de área para visualização de tendência temporal.",
+          "icon": "show_chart",
+          "inputs": {
+            "visualization": {
+              "kind": "area",
+              "tone": "info",
+              "points": [
+                {
+                  "value": 12,
+                  "label": "Jan"
+                },
+                {
+                  "value": 19,
+                  "label": "Fev"
+                },
+                {
+                  "value": 15,
+                  "label": "Mar"
+                },
+                {
+                  "value": 27,
+                  "label": "Abr"
+                },
+                {
+                  "value": 34,
+                  "label": "Mai"
+                }
+              ],
+              "fallbackText": "Tendência Trimestral"
+            }
+          }
+        },
+        {
+          "id": "process-flow",
+          "label": "Fluxo de Etapas (Process Flow)",
+          "description": "Indicador visual compacto de etapas sequenciais ou esteira de estados.",
+          "icon": "route",
+          "inputs": {
+            "visualization": {
+              "kind": "processFlow",
+              "points": [
+                {
+                  "label": "Triagem",
+                  "icon": "check",
+                  "tone": "success"
+                },
+                {
+                  "label": "Análise",
+                  "icon": "sync",
+                  "tone": "info"
+                },
+                {
+                  "label": "Aprovação",
+                  "icon": "schedule",
+                  "tone": "warning"
+                },
+                {
+                  "label": "Conclusão",
+                  "icon": "flag",
+                  "tone": "neutral"
+                }
+              ],
+              "fallbackText": "Etapa 2/4: Em Análise"
+            }
+          }
+        }
+      ],
+      "source": "projects/praxis-charts/src/lib/praxis-micro-visualization.metadata.ts",
+      "exportName": "PRAXIS_MICRO_VISUALIZATION_COMPONENT_METADATA",
+      "chunks": [
+        {
+          "chunkIndex": 0,
+          "chunkKind": "summary",
+          "content": "Component ID: praxis-micro-visualization\nSelector: praxis-micro-visualization\nFriendly Name: Micro-visualização Analítica\nDescription: Renderiza micro-visualizações ultraleves e autônomas (bullet, radial, sparkline, processFlow, comparison, etc.) como widget independente no canvas ou célula.\nLib/Package: @praxisui/charts\nTags: chart, analytics, widget, microchart, visualization, sparkline, bullet, radial\nInputs:\n  - visualization (PraxisPresentationVisualizationConfig)\n  - fallbackText (string)\nInsertion Presets:\n  - bullet-kpi: Bullet Graph KPI - Microchart do tipo bullet com faixas de tolerância e valor meta.\n  - radial-score: Radial Score - Medidor circular compacto de pontuação ou progresso percentual.\n  - sparkline-area: Sparkline de Tendência (Área) - Minigráfico contínuo de área para visualização de tendência temporal.\n  - process-flow: Fluxo de Etapas (Process Flow) - Indicador visual compacto de etapas sequenciais ou esteira de estados.\n",
+          "sourcePointer": "projects/praxis-charts/src/lib/praxis-micro-visualization.metadata.ts",
+          "contentHash": "455a9d78d9176e7b267f6cb9f0a511dffd981c889b810b09ea1b45952512d060",
+          "sourceKind": "component_definition",
+          "sourceId": "praxis-micro-visualization",
+          "corpusVersion": "1.0.0"
+        }
+      ]
     }
   },
   "note": "Package-scoped Praxis component registry for source-free agent discovery. Use the canonical ingestion registry for cross-package aggregate analysis."