@praxisui/core 10.0.0-rc.16 → 10.0.0-rc.17

package/README.md

@@ -93,6 +93,15 @@ backend B7 acceptance is complete.
 
 `GovernedColorPaletteService` is the canonical Angular client for color-palette projections published by Praxis Config. Published palettes carry a stable `familyKey`, an explicit `variant` identity and token-level `displayName`/`aliases`; incomplete legacy projections are rejected before caching. The service supports list/read/capabilities/preview, exact `list(familyKey)` queries, tenant/environment-isolated caching, conditional ETag revalidation and deterministic `version`/`etag` pins. Consumers may use names and aliases for presentation and discovery only: `paletteKey` and `tokenId` remain the persisted identities, and local metadata must not become a second source of governance. `GovernedColorTokenSelection` carries the exact palette/version/ETag/token observation beside the existing CSS-string field value; applications persist it only through an explicit domain field or mapping.
 
+## Declarative Page DataSources (`page.dataSources`)
+
+`WidgetPageDefinition.dataSources` and `WidgetPageDataSourceRuntimeService` allow dynamic pages and dashboards to fetch backend KPIs, group-by aggregations, and time-series metrics without imperative host `HttpClient` orchestration:
+
+- **Endpoint resolution (`endpointKey` + `resourcePath`)**: resolves URLs through the `API_URL` token using `endpointKey` (falling back to `'default'`) so multi-service enterprise hosts route each DataSource to its target microservice.
+- **Transform presets & JsonLogic**: supports `{ kind: 'path', path }`, `{ kind: 'group-by-map', mappings, totalField }` (initializing declared keys with `0` for sparse buckets), `{ kind: 'timeseries-last', mappings }`, or arbitrary JsonLogic expressions.
+- **Transient state overlay (`targetStatePath`)**: merges resolved payloads into a non-persisted runtime overlay over `page.state.values[targetStatePath]` and coalesces concurrent emissions via microtask batching before re-evaluating `page.state.derived` and `composition.links`. Live runtime payloads never dirty `authoredPageDefinition` or trigger `autoPersist` writes.
+- **Resilience & visibility-aware polling**: `errorPolicy` (`'fallback' | 'silent' | 'propagate'`) applies `fallbackValue` only before the first successful response so transient network errors during polling (`refreshIntervalMs`) never overwrite live data with static fallbacks. Subsequent poll ticks pause while `document.visibilityState === 'hidden'` and resume immediately on `visibilitychange`.
+
 ## LLM Recommendation Guide
 
 - `BUILTIN_WIDGET_SHELL_PRESETS` is the canonical catalog for reusable shell

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-14T20:20:10.826Z",
+  "generatedAt": "2026-10-14T22:05:37.957Z",
   "packageName": "@praxisui/core",
-  "packageVersion": "10.0.0-rc.16",
+  "packageVersion": "10.0.0-rc.17",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 4,

package/fesm2022/praxisui-core.mjs

@@ -40174,17 +40174,51 @@ class WidgetPageDataSourceRuntimeService {
         }
         return request$.pipe(map((res) => this.transformPayload(res, dataSource)));
     }
+    /**
+     * Normaliza `page.dataSources` aceitando tanto o formato canônico em Array quanto Object Map indexado por id.
+     */
+    normalizeDataSources(dataSources) {
+        if (!dataSources || typeof dataSources !== 'object') {
+            return [];
+        }
+        if (Array.isArray(dataSources)) {
+            return dataSources.filter((item) => !!item &&
+                typeof item === 'object' &&
+                !Array.isArray(item) &&
+                typeof item.id === 'string' &&
+                item.id.trim().length > 0 &&
+                typeof item.resourcePath === 'string' &&
+                item.resourcePath.trim().length > 0);
+        }
+        return Object.entries(dataSources)
+            .filter(([key, item]) => key.trim().length > 0 &&
+            !!item &&
+            typeof item === 'object' &&
+            !Array.isArray(item) &&
+            typeof item.resourcePath === 'string' &&
+            item.resourcePath.trim().length > 0)
+            .map(([key, item]) => {
+            const candidateId = item.id;
+            return {
+                ...item,
+                id: typeof candidateId === 'string' && candidateId.trim().length > 0
+                    ? candidateId.trim()
+                    : key.trim(),
+            };
+        });
+    }
     /**
      * Inicia a orquestração reativa de todos os DataSources declarados em uma página dinâmica.
      * Retorna uma função de teardown que cancela todas as requisições em voo e timers de polling.
      */
     startDataSources(dataSources, onUpdate, onDiagnostic) {
-        if (!dataSources || !dataSources.length) {
+        const normalizedDataSources = this.normalizeDataSources(dataSources);
+        if (!normalizedDataSources.length) {
             return () => { };
         }
         const destroy$ = new Subject();
         const visibilityCallbacks = [];
-        for (const ds of dataSources) {
+        for (const ds of normalizedDataSources) {
             if (ds.autoFetch === false) {
                 continue;
             }
@@ -46034,6 +46068,7 @@ class DynamicWidgetPageComponent {
                     this.currentDataSourcesSignature) {
                 this.dataSourceRuntimeOverlay.clear();
                 this.dataSourceDiagnostics.clear();
+                this.pendingDataSourceUpdates = [];
                 this.currentDataSourcesSignature = null;
             }
             this.pageRuntime = this.buildStateRuntime(this.pageDefinition?.state, this.pageDefinition?.context);
@@ -46366,9 +46401,8 @@ class DynamicWidgetPageComponent {
         };
     }
     getDataSourcesSignature(dataSources) {
-        return dataSources && dataSources.length > 0
-            ? JSON.stringify(dataSources)
-            : null;
+        const normalized = this.dataSourceRuntime.normalizeDataSources(dataSources);
+        return normalized.length > 0 ? JSON.stringify(normalized) : null;
     }
     bootstrapCompositionAdapter(page) {
         if (!page) {
@@ -48783,15 +48817,22 @@ class DynamicWidgetPageComponent {
             themePreset: themePreset || undefined,
         }, persist);
     }
-    applyAuthoringPageUpdate(next, persist = true, runtime = this.buildStateRuntime(next.state, next.context), syncCompositionAdapter = true, skipStateWidgetProjection = false, emitUnchangedCanonicalPage = true) {
+    applyAuthoringPageUpdate(next, persist = true, runtime, syncCompositionAdapter = true, skipStateWidgetProjection = false, emitUnchangedCanonicalPage = true) {
         this.applyPageUpdate(next, persist, runtime, syncCompositionAdapter, skipStateWidgetProjection, emitUnchangedCanonicalPage);
         if (this.authoredPageDefinition) {
             this.pageAuthoringChange.emit(this.clonePageDefinition(this.authoredPageDefinition));
         }
     }
-    applyPageUpdate(next, persist = true, runtime = this.buildStateRuntime(next.state, next.context), syncCompositionAdapter = true, skipStateWidgetProjection = false, emitUnchangedCanonicalPage = true) {
+    applyPageUpdate(next, persist = true, runtime, syncCompositionAdapter = true, skipStateWidgetProjection = false, emitUnchangedCanonicalPage = true) {
         this.assertNoLegacyConnections(next);
-        const normalized = { ...next, state: runtime.state };
+        if (this.getDataSourcesSignature(next.dataSources) !==
+            this.currentDataSourcesSignature) {
+            this.dataSourceRuntimeOverlay.clear();
+            this.dataSourceDiagnostics.clear();
+            this.pendingDataSourceUpdates = [];
+        }
+        const effectiveRuntime = runtime ?? this.buildStateRuntime(next.state, next.context);
+        const normalized = { ...next, state: effectiveRuntime.state };
         const normalizedWidgets = this.applyEditShellActions(normalized.widgets || []);
         const bootstrapSnapshot = syncCompositionAdapter
             ? this.bootstrapCompositionAdapter(normalized)
@@ -48799,13 +48840,13 @@ class DynamicWidgetPageComponent {
         const stateBoundWidgets = skipStateWidgetProjection
             ? normalizedWidgets
             : bootstrapSnapshot
-                ? this.applyBootstrapCompositionHydration(normalizedWidgets, bootstrapSnapshot, runtime)
+                ? this.applyBootstrapCompositionHydration(normalizedWidgets, bootstrapSnapshot, effectiveRuntime)
                 : this.compositionDefinition
                     ? this.compositionRuntime.projectStateWidgetInputs(this.compositionDefinition, {
                         widgets: normalizedWidgets,
                         state: {
-                            primaryValues: this.cloneStateValues(runtime.primaryValues),
-                            derivedValues: this.cloneStateValues(runtime.derivedValues),
+                            primaryValues: this.cloneStateValues(effectiveRuntime.primaryValues),
+                            derivedValues: this.cloneStateValues(effectiveRuntime.derivedValues),
                             transientValues: this.cloneStateValues(this.compositionRuntime.getSnapshot().state.transientValues),
                             changedPaths: [],
                             diagnostics: [],
@@ -48818,9 +48859,9 @@ class DynamicWidgetPageComponent {
         });
         this.pageDefinition = hydrated;
         this.page = hydrated;
-        this.pageState = runtime.state;
-        this.pageRuntime = runtime;
-        this.applyResponsivePresentation(hydrated, hydrated?.widgets || stateBoundWidgets, runtime);
+        this.pageState = effectiveRuntime.state;
+        this.pageRuntime = effectiveRuntime;
+        this.applyResponsivePresentation(hydrated, hydrated?.widgets || stateBoundWidgets, effectiveRuntime);
         this.restartDataSources(hydrated);
         if (this.widgetEventBus) {
             this.wiringSubscription?.unsubscribe();
@@ -48836,7 +48877,7 @@ class DynamicWidgetPageComponent {
         if (authoredPageChanged || emitUnchangedCanonicalPage) {
             this.pageChange.emit(canonicalPage);
         }
-        this.reportStateDiagnostics(runtime.diagnostics);
+        this.reportStateDiagnostics(effectiveRuntime.diagnostics);
         if (authoredPageChanged &&
             persist &&
             this.autoPersist &&
@@ -48927,12 +48968,14 @@ class DynamicWidgetPageComponent {
         this.currentDataSourcesSignature = signature;
         this.dataSourceRuntimeOverlay.clear();
         this.dataSourceDiagnostics.clear();
+        this.pendingDataSourceUpdates = [];
         this.dataSourceTeardown?.();
         this.dataSourceTeardown = undefined;
-        if (!dataSources || dataSources.length === 0) {
+        const normalizedDataSources = this.dataSourceRuntime.normalizeDataSources(dataSources);
+        if (normalizedDataSources.length === 0) {
             return;
         }
-        this.dataSourceTeardown = this.dataSourceRuntime.startDataSources(dataSources, (update) => this.handleDataSourceUpdate(update), (diagnostic) => this.handleDataSourceDiagnostic(diagnostic));
+        this.dataSourceTeardown = this.dataSourceRuntime.startDataSources(normalizedDataSources, (update) => this.handleDataSourceUpdate(update), (diagnostic) => this.handleDataSourceDiagnostic(diagnostic));
     }
     applyLayout(layout, grouping, deviceLayoutColumnsSelected = false) {
         this.layout = layout;
@@ -49274,7 +49317,11 @@ class DynamicWidgetPageComponent {
         }
         return this.compositionRuntime.projectStateWidgetInputs(this.compositionDefinition, {
             widgets,
-            state: snapshot.state,
+            state: {
+                ...snapshot.state,
+                primaryValues: this.cloneStateValues(this.pageRuntime.primaryValues),
+                derivedValues: this.cloneStateValues(this.pageRuntime.derivedValues),
+            },
             now: snapshot.generatedAt,
         }).widgets;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/core",
-  "version": "10.0.0-rc.16",
+  "version": "10.0.0-rc.17",
   "description": "Core library for Praxis UI Workspace: types, tokens, services and utilities shared across @praxisui/* packages.",
   "peerDependencies": {
     "@angular/cdk": "^21.0.0",

package/types/praxisui-core.d.ts

@@ -18261,11 +18261,19 @@ declare class WidgetPageDataSourceRuntimeService {
      */
     fetchDataSource(dataSource: WidgetPageDataSourceDefinition): Observable<unknown>;
     private executeRawRequest;
+    /**
+     * Normaliza `page.dataSources` aceitando tanto o formato canônico em Array quanto Object Map indexado por id.
+     */
+    normalizeDataSources(dataSources: WidgetPageDataSourceDefinition[] | Record<string, Omit<WidgetPageDataSourceDefinition, 'id'> & {
+        id?: string;
+    }> | undefined | null): WidgetPageDataSourceDefinition[];
     /**
      * Inicia a orquestração reativa de todos os DataSources declarados em uma página dinâmica.
      * Retorna uma função de teardown que cancela todas as requisições em voo e timers de polling.
      */
-    startDataSources(dataSources: WidgetPageDataSourceDefinition[] | undefined, onUpdate: (event: WidgetPageDataSourceUpdateEvent) => void, onDiagnostic?: (diagnostic: WidgetPageDataSourceDiagnostic) => void): () => void;
+    startDataSources(dataSources: WidgetPageDataSourceDefinition[] | Record<string, Omit<WidgetPageDataSourceDefinition, 'id'> & {
+        id?: string;
+    }> | undefined, onUpdate: (event: WidgetPageDataSourceUpdateEvent) => void, onDiagnostic?: (diagnostic: WidgetPageDataSourceDiagnostic) => void): () => void;
     /**
      * Transforma a resposta bruta do backend aplicando envelope canônico ou JsonLogic.
      */