@praxisui/core 10.0.0-rc.15 → 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-14T16:04:24.084Z",
+  "generatedAt": "2026-10-14T22:05:37.957Z",
   "packageName": "@praxisui/core",
-  "packageVersion": "10.0.0-rc.15",
+  "packageVersion": "10.0.0-rc.17",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 4,

package/fesm2022/praxisui-core.mjs

@@ -5532,8 +5532,28 @@ class GenericCrudService {
             .post(url, entity, {
             headers: composeHeadersWithVersion(entry),
             context: options?.httpContext,
+            observe: 'response',
         })
-            .pipe(catchError(this.handleError));
+            .pipe(map((response) => {
+            const isHttpResponse = response &&
+                typeof response === 'object' &&
+                'body' in response &&
+                'headers' in response;
+            if (!isHttpResponse) {
+                return response;
+            }
+            const idField = this._lastResourceMeta.idField || 'id';
+            const createdId = response.body?.data?.[idField] ??
+                response.body?.data?.id;
+            if (createdId !== undefined && createdId !== null) {
+                const versionKey = this.resourceVersionKey(createdId, options);
+                return this.captureResourceVersion(versionKey, response);
+            }
+            if (!response.body) {
+                throw new Error('Resource response body is empty.');
+            }
+            return response.body;
+        }), catchError(this.handleError));
     }
     /**
      * Atualiza um registro existente.
@@ -5558,6 +5578,26 @@ class GenericCrudService {
     update(id, entity, options) {
         return this.updateResponse(id, entity, options).pipe(map((r) => r.data));
     }
+    getResourceVersion(id, options) {
+        if (id === undefined || id === null || !this.configured) {
+            return null;
+        }
+        const versionKey = this.resourceVersionKey(id, options);
+        return this._resourceEtags.get(versionKey) ?? null;
+    }
+    setResourceVersion(id, etag, options) {
+        if (id === undefined || id === null || !this.configured) {
+            return;
+        }
+        const versionKey = this.resourceVersionKey(id, options);
+        const formatted = this.normalizeEtagToken(etag);
+        if (formatted) {
+            this._resourceEtags.set(versionKey, formatted);
+        }
+        else {
+            this._resourceEtags.delete(versionKey);
+        }
+    }
     updateResponse(id, entity, options) {
         if (id === undefined || id === null)
             throw new Error(this.errorMessages.emptyId);
@@ -5568,10 +5608,12 @@ class GenericCrudService {
         const url = this.getEndpointUrl('update', id, options?.parentPath, options?.endpointKey);
         const versionKey = this.resourceVersionKey(id, options);
         let headers = composeHeadersWithVersion(entry);
-        const etag = this._resourceEtags.get(versionKey);
+        const etag = this._resourceEtags.get(versionKey) ||
+            this.normalizeEtagToken(entity?.resourceVersion) ||
+            null;
         if (etag) {
             headers = (headers instanceof HttpHeaders ? headers : new HttpHeaders(headers))
-                .set('If-Match', etag);
+                .set('If-Match', this.ensureEtagFormat(etag));
         }
         return this.http
             .put(url, entity, {
@@ -5594,7 +5636,9 @@ class GenericCrudService {
         return [buildApiUrl(entry), tenant, environment, this.resourcePath, options?.parentPath ?? '', String(id)].join('|');
     }
     captureResourceVersion(key, response) {
-        const etag = response.headers.get('ETag');
+        const etag = this.normalizeEtagToken(response.headers?.get('ETag')) ||
+            this.normalizeEtagToken(response.body?.data?.resourceVersion) ||
+            null;
         if (etag) {
             this._resourceEtags.set(key, etag);
         }
@@ -5603,6 +5647,26 @@ class GenericCrudService {
         }
         return response.body;
     }
+    normalizeEtagToken(etag) {
+        if (typeof etag !== 'string' && typeof etag !== 'number') {
+            return null;
+        }
+        const trimmed = String(etag).trim();
+        if (!trimmed) {
+            return null;
+        }
+        const inner = trimmed.replace(/^(?:W\/)?"|"$/g, '').trim();
+        if (!inner) {
+            return null;
+        }
+        return this.ensureEtagFormat(trimmed);
+    }
+    ensureEtagFormat(etag) {
+        if (/^(?:W\/)?".+"$/.test(etag)) {
+            return etag;
+        }
+        return `"${etag.replace(/^"|"$/g, '')}"`;
+    }
     /**
      * Remove um registro pelo ID.
      *
@@ -5631,6 +5695,7 @@ class GenericCrudService {
         this.ensureConfigured();
         const entry = this.resolveEndpointEntry(options?.endpointKey);
         const url = this.getEndpointUrl('delete', id, options?.parentPath, options?.endpointKey);
+        const versionKey = this.resourceVersionKey(id, options);
         debugCrudService('[CRUD:Service] delete:request', {
             url,
             id,
@@ -5642,7 +5707,7 @@ class GenericCrudService {
             headers: composeHeadersWithVersion(entry),
             context: options?.httpContext,
         })
-            .pipe(catchError(this.handleError));
+            .pipe(tap(() => this._resourceEtags.delete(versionKey)), catchError(this.handleError));
     }
     /**
      * Realiza exclusão de múltiplos registros sequencialmente.
@@ -13237,6 +13302,13 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImpo
                     type: Optional
                 }] }] });
 
+const DEFAULT_FRAMEWORK_VERSION_MESSAGES = new Set([
+    'resource version is stale.',
+    'resource version is required.',
+    'the resource changed after it was read. reload it before deciding whether to retry.',
+    'the resource changed after it was read. reload and try again.',
+    'this operation requires a current resource version in if-match.',
+]);
 /**
  * Maps HTTP or network errors to user-friendly messages.
  * This service centralizes error messaging so UI components don't
@@ -13258,14 +13330,19 @@ class ErrorMessageService {
             ? this.normalizeDetails(payload?.['errors'])
             : [];
         if (details.length) {
+            const topMessage = this.textValue(payload?.['message']);
+            const resolvedTopMessage = this.resolveVersionPreconditionCopy(details[0].code, topMessage ?? details[0].message, status);
             return {
-                message: this.textValue(payload?.['message']) ?? details[0].message,
+                message: resolvedTopMessage,
                 details,
             };
         }
         const publicMessage = this.textValue(payload?.['message']);
         if (publicMessage && isPublicClientError) {
-            return { message: publicMessage, details: [] };
+            return {
+                message: this.resolveVersionPreconditionCopy(undefined, publicMessage, status),
+                details: [],
+            };
         }
         return { message: this.fallbackMessage(status), details: [] };
     }
@@ -13283,6 +13360,12 @@ class ErrorMessageService {
         if (status !== undefined && status >= 500) {
             return this.tx('global.submitError.server', 'Erro interno no servidor. Tente novamente mais tarde.');
         }
+        if (status === 412) {
+            return this.staleResourceVersionMessage();
+        }
+        if (status === 428) {
+            return this.resourceVersionRequiredMessage();
+        }
         if (status === 400 || status === 422) {
             return this.tx('global.submitError.invalidData', 'Dados inválidos ou inconsistentes. Verifique os campos e tente novamente.');
         }
@@ -13293,17 +13376,40 @@ class ErrorMessageService {
             return [];
         return value.flatMap((item) => {
             const detail = this.objectValue(item);
-            const message = this.textValue(detail?.['message']) ?? this.textValue(detail?.['detail']);
-            if (!message)
+            const rawMessage = this.textValue(detail?.['message']) ?? this.textValue(detail?.['detail']);
+            if (!rawMessage)
                 return [];
+            const code = this.textValue(detail?.['code']);
+            const message = this.resolveVersionPreconditionCopy(code, rawMessage, undefined);
             return [{
                     message,
-                    code: this.textValue(detail?.['code']),
+                    code,
                     target: this.textValue(detail?.['target']),
                     category: this.textValue(detail?.['category']),
                 }];
         });
     }
+    resolveVersionPreconditionCopy(code, candidateMessage, status) {
+        const normalizedCode = String(code ?? '').trim().toUpperCase();
+        const isDefaultFrameworkCopy = DEFAULT_FRAMEWORK_VERSION_MESSAGES.has(candidateMessage.trim().toLowerCase());
+        if ((normalizedCode === 'STALE_RESOURCE_VERSION' || status === 412) &&
+            isDefaultFrameworkCopy) {
+            return this.staleResourceVersionMessage();
+        }
+        if ((normalizedCode === 'RESOURCE_VERSION_REQUIRED' ||
+            normalizedCode === 'MISSING_IF_MATCH' ||
+            status === 428) &&
+            isDefaultFrameworkCopy) {
+            return this.resourceVersionRequiredMessage();
+        }
+        return candidateMessage;
+    }
+    staleResourceVersionMessage() {
+        return this.tx('global.submitError.staleResourceVersion', 'Este registro foi alterado após a leitura. Recarregue os dados e revise antes de tentar salvar novamente.');
+    }
+    resourceVersionRequiredMessage() {
+        return this.tx('global.submitError.resourceVersionRequired', 'A versão atual do registro é obrigatória para confirmar esta alteração. Recarregue o registro e tente novamente.');
+    }
     objectValue(value) {
         return value !== null && typeof value === 'object' && !Array.isArray(value)
             ? value
@@ -39980,7 +40086,7 @@ class WidgetPageDataSourceRuntimeService {
     /**
      * Constrói a URL canônica completa para o resourcePath declarado no dataSource.
      */
-    resolveUrl(resourcePath) {
+    resolveUrl(resourcePath, endpointKey) {
         const trimmed = (resourcePath || '').trim();
         if (!trimmed)
             return '';
@@ -39989,7 +40095,10 @@ class WidgetPageDataSourceRuntimeService {
         }
         let base = '';
         if (this.apiUrlConfig) {
-            const entry = this.apiUrlConfig['default'] || Object.values(this.apiUrlConfig)[0];
+            const key = (endpointKey || 'default').trim() || 'default';
+            const entry = this.apiUrlConfig[key] ||
+                this.apiUrlConfig['default'] ||
+                Object.values(this.apiUrlConfig)[0];
             if (entry) {
                 base = buildApiUrl(entry);
             }
@@ -40008,7 +40117,7 @@ class WidgetPageDataSourceRuntimeService {
         if (!this.http) {
             return of(dataSource.fallbackValue ?? null);
         }
-        const url = this.resolveUrl(dataSource.resourcePath);
+        const url = this.resolveUrl(dataSource.resourcePath, dataSource.endpointKey);
         if (!url) {
             return of(dataSource.fallbackValue ?? null);
         }
@@ -40032,7 +40141,8 @@ class WidgetPageDataSourceRuntimeService {
         if (!this.http) {
             return of(dataSource.fallbackValue ?? null);
         }
-        const url = resolvedUrl ?? this.resolveUrl(dataSource.resourcePath);
+        const url = resolvedUrl ??
+            this.resolveUrl(dataSource.resourcePath, dataSource.endpointKey);
         if (!url) {
             return of(dataSource.fallbackValue ?? null);
         }
@@ -40064,28 +40174,65 @@ 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();
-        for (const ds of dataSources) {
+        const visibilityCallbacks = [];
+        for (const ds of normalizedDataSources) {
             if (ds.autoFetch === false) {
                 continue;
             }
             const targetPath = ds.targetStatePath || ds.id;
             const intervalMs = ds.refreshIntervalMs ?? 0;
             let hasSucceededOnce = false;
+            let skippedWhileHidden = false;
             onDiagnostic?.({
                 dataSourceId: ds.id,
                 status: 'loading',
             });
             const runSingleFetch$ = () => this.executeRawRequest(ds).pipe(map((value) => {
                 hasSucceededOnce = true;
+                skippedWhileHidden = false;
                 const now = new Date().toISOString();
                 onDiagnostic?.({
                     dataSourceId: ds.id,
@@ -40120,16 +40267,43 @@ class WidgetPageDataSourceRuntimeService {
             }));
             const stream$ = intervalMs > 0
                 ? timer(0, intervalMs).pipe(takeUntil(destroy$), switchMap(() => {
-                    if (typeof document !== 'undefined' &&
+                    if (hasSucceededOnce &&
+                        typeof document !== 'undefined' &&
                         document.visibilityState === 'hidden') {
+                        skippedWhileHidden = true;
                         return EMPTY;
                     }
                     return runSingleFetch$();
                 }))
                 : runSingleFetch$().pipe(takeUntil(destroy$));
             stream$.subscribe();
+            if (intervalMs > 0) {
+                visibilityCallbacks.push(() => {
+                    if (skippedWhileHidden) {
+                        skippedWhileHidden = false;
+                        runSingleFetch$().pipe(takeUntil(destroy$)).subscribe();
+                    }
+                });
+            }
+        }
+        const onVisibilityChange = () => {
+            if (typeof document !== 'undefined' && document.visibilityState === 'visible') {
+                for (const cb of visibilityCallbacks) {
+                    cb();
+                }
+            }
+        };
+        if (visibilityCallbacks.length > 0 &&
+            typeof document !== 'undefined' &&
+            typeof document.addEventListener === 'function') {
+            document.addEventListener('visibilitychange', onVisibilityChange);
         }
         return () => {
+            if (visibilityCallbacks.length > 0 &&
+                typeof document !== 'undefined' &&
+                typeof document.removeEventListener === 'function') {
+                document.removeEventListener('visibilitychange', onVisibilityChange);
+            }
             destroy$.next();
             destroy$.complete();
         };
@@ -45716,6 +45890,7 @@ class DynamicWidgetPageComponent {
     pendingDataSourceUpdates = [];
     isCoalescingDataSourceUpdates = false;
     dataSourceRuntimeOverlay = new Map();
+    dataSourceDiagnostics = new Map();
     nestedWidgetAccessor = new NestedWidgetConfigAccessor();
     settingsPanel = inject(SETTINGS_PANEL_BRIDGE, {
         optional: true,
@@ -45807,6 +45982,7 @@ class DynamicWidgetPageComponent {
         this.pendingDataSourceUpdates = [];
         this.isCoalescingDataSourceUpdates = false;
         this.dataSourceRuntimeOverlay.clear();
+        this.dataSourceDiagnostics.clear();
         this.persistenceGeneration++;
         this.persistenceLoad?.unsubscribe();
         this.persistenceMutation?.unsubscribe();
@@ -45891,6 +46067,9 @@ class DynamicWidgetPageComponent {
                 this.getDataSourcesSignature(this.pageDefinition?.dataSources) !==
                     this.currentDataSourcesSignature) {
                 this.dataSourceRuntimeOverlay.clear();
+                this.dataSourceDiagnostics.clear();
+                this.pendingDataSourceUpdates = [];
+                this.currentDataSourcesSignature = null;
             }
             this.pageRuntime = this.buildStateRuntime(this.pageDefinition?.state, this.pageDefinition?.context);
             this.pageState = this.pageRuntime.state;
@@ -45992,13 +46171,21 @@ class DynamicWidgetPageComponent {
         const state = this.stateFromCompositionSnapshot(pageWithPatchedInputs.state, cycle.snapshot.state.primaryValues);
         const runtimeStatePaths = Array.from(new Set((cycle.snapshot.state.changedPaths || []).filter((path) => typeof path === 'string')));
         const updatedPrimaryStatePaths = runtimeStatePaths.filter((path) => !this.areStateValuesEqual(this.conn.extractByPath(this.stateRuntime.normalizeState(page.state).values || {}, path), this.conn.extractByPath(state.values || {}, path)));
+        for (const changedPath of updatedPrimaryStatePaths) {
+            this.dataSourceRuntimeOverlay.delete(changedPath);
+        }
+        const nextRuntime = this.buildStateRuntime(state, pageWithPatchedInputs.context);
         let widgets = this.cloneWidgets(pageWithPatchedInputs.widgets || []);
         const directDelivery = this.applyCompositionWidgetDeliveries(widgets, cycle);
         widgets = directDelivery.widgets;
-        const projectedWidgets = this.projectPersistentCompositionStateInputs(widgets, cycle.snapshot.state, cycle.snapshot.generatedAt);
+        const effectiveCompositionState = {
+            ...cycle.snapshot.state,
+            primaryValues: this.cloneStateValues(nextRuntime.primaryValues),
+            derivedValues: this.cloneStateValues(nextRuntime.derivedValues),
+        };
+        const projectedWidgets = this.projectPersistentCompositionStateInputs(widgets, effectiveCompositionState, cycle.snapshot.generatedAt);
         const stateProjectionChanged = !this.areStateValuesEqual(widgets, projectedWidgets);
         widgets = projectedWidgets;
-        const nextRuntime = this.buildStateRuntime(state, pageWithPatchedInputs.context);
         if (this.isTransientOnlyCompositionCycle(cycle) &&
             !updatedPrimaryStatePaths.length &&
             !directDelivery.changed &&
@@ -46214,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) {
@@ -46826,12 +47012,16 @@ class DynamicWidgetPageComponent {
             return { page };
         }
         const state = this.stateFromCompositionSnapshot(page.state, cycle.snapshot.state.primaryValues);
+        const runtime = this.buildStateRuntime(state, page.context);
         let widgets = this.cloneWidgets(page.widgets || []);
         widgets = this.applyCompositionWidgetDeliveries(widgets, cycle).widgets;
         if (this.compositionDefinition) {
-            widgets = this.projectPersistentCompositionStateInputs(widgets, cycle.snapshot.state, cycle.snapshot.generatedAt);
+            widgets = this.projectPersistentCompositionStateInputs(widgets, {
+                ...cycle.snapshot.state,
+                primaryValues: this.cloneStateValues(runtime.primaryValues),
+                derivedValues: this.cloneStateValues(runtime.derivedValues),
+            }, cycle.snapshot.generatedAt);
         }
-        const runtime = this.buildStateRuntime(state, page.context);
         return {
             page: { ...page, widgets, state },
             runtime,
@@ -46948,10 +47138,14 @@ class DynamicWidgetPageComponent {
             return;
         }
         const state = this.stateFromCompositionSnapshot(page.state, cycle.snapshot.state.primaryValues);
+        const runtime = this.buildStateRuntime(state, page.context);
         let widgets = this.cloneWidgets(page.widgets || []);
         widgets = this.applyCompositionWidgetDeliveries(widgets, cycle).widgets;
-        widgets = this.projectPersistentCompositionStateInputs(widgets, cycle.snapshot.state, cycle.snapshot.generatedAt);
-        const runtime = this.buildStateRuntime(state, page.context);
+        widgets = this.projectPersistentCompositionStateInputs(widgets, {
+            ...cycle.snapshot.state,
+            primaryValues: this.cloneStateValues(runtime.primaryValues),
+            derivedValues: this.cloneStateValues(runtime.derivedValues),
+        }, cycle.snapshot.generatedAt);
         this.applyPageUpdate({ ...page, widgets, state }, true, runtime, false, true, false);
     }
     matchesRuntimeSourceRef(endpoint, sourceRef) {
@@ -48623,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)
@@ -48639,14 +48840,14 @@ 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),
-                            transientValues: {},
+                            primaryValues: this.cloneStateValues(effectiveRuntime.primaryValues),
+                            derivedValues: this.cloneStateValues(effectiveRuntime.derivedValues),
+                            transientValues: this.cloneStateValues(this.compositionRuntime.getSnapshot().state.transientValues),
                             changedPaths: [],
                             diagnostics: [],
                         },
@@ -48658,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();
@@ -48676,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 &&
@@ -48730,7 +48931,7 @@ class DynamicWidgetPageComponent {
                 state: {
                     primaryValues: this.cloneStateValues(nextRuntime.primaryValues),
                     derivedValues: this.cloneStateValues(nextRuntime.derivedValues),
-                    transientValues: {},
+                    transientValues: this.cloneStateValues(this.compositionRuntime.getSnapshot().state.transientValues),
                     changedPaths: updates.map((u) => u.targetStatePath),
                     diagnostics: [],
                 },
@@ -48747,6 +48948,17 @@ class DynamicWidgetPageComponent {
         this.reportStateDiagnostics(nextRuntime.diagnostics);
         this.changeDetector.markForCheck();
     }
+    handleDataSourceDiagnostic(diagnostic) {
+        if (this.destroyed) {
+            return;
+        }
+        this.dataSourceDiagnostics.set(diagnostic.dataSourceId, diagnostic);
+        if (diagnostic.status === 'error') {
+            this.reportStateDiagnostics([
+                `DataSource "${diagnostic.dataSourceId}" failed: ${diagnostic.error || 'unknown error'}`,
+            ]);
+        }
+    }
     restartDataSources(page) {
         const dataSources = page?.dataSources;
         const signature = this.getDataSourcesSignature(dataSources);
@@ -48755,12 +48967,15 @@ 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));
+        this.dataSourceTeardown = this.dataSourceRuntime.startDataSources(normalizedDataSources, (update) => this.handleDataSourceUpdate(update), (diagnostic) => this.handleDataSourceDiagnostic(diagnostic));
     }
     applyLayout(layout, grouping, deviceLayoutColumnsSelected = false) {
         this.layout = layout;
@@ -49102,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;
     }
@@ -51240,7 +51459,13 @@ class DynamicWidgetPageComponent {
             cloned.layout = { ...page.layout };
         }
         if (page.grouping) {
-            cloned.grouping = [...page.grouping];
+            cloned.grouping = this.cloneStateValues(page.grouping);
+        }
+        if (page.dataSources) {
+            cloned.dataSources = this.cloneStateValues(page.dataSources);
+        }
+        if (page.composition) {
+            cloned.composition = this.cloneStateValues(page.composition);
         }
         if (page.canvas) {
             cloned.canvas = {
@@ -51251,16 +51476,20 @@ class DynamicWidgetPageComponent {
             };
         }
         if (page.context) {
-            cloned.context = { ...page.context };
+            cloned.context = this.cloneStateValues(page.context);
         }
         if (page.state) {
             const stateObj = {
-                values: page.state.values ? { ...page.state.values } : {},
+                values: page.state.values
+                    ? this.cloneStateValues(page.state.values)
+                    : {},
             };
-            if (page.state.schema !== undefined)
-                stateObj.schema = page.state.schema;
-            if (page.state.derived !== undefined)
-                stateObj.derived = page.state.derived;
+            if (page.state.schema !== undefined) {
+                stateObj.schema = this.cloneStateValues(page.state.schema);
+            }
+            if (page.state.derived !== undefined) {
+                stateObj.derived = this.cloneStateValues(page.state.derived);
+            }
             cloned.state = stateObj;
         }
         return cloned;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/core",
-  "version": "10.0.0-rc.15",
+  "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

@@ -6363,9 +6363,13 @@ declare class GenericCrudService<T, ID extends string | number = string | number
      * @returns Observable com a entidade atualizada.
      */
     update(id: ID, entity: T, options?: CrudOperationOptions): Observable<T>;
+    getResourceVersion(id: ID, options?: CrudOperationOptions): string | null;
+    setResourceVersion(id: ID, etag: string | null | undefined, options?: CrudOperationOptions): void;
     updateResponse(id: ID, entity: T, options?: CrudOperationOptions): Observable<RestApiResponse<T>>;
     private resourceVersionKey;
     private captureResourceVersion;
+    private normalizeEtagToken;
+    private ensureEtagFormat;
     /**
      * Remove um registro pelo ID.
      *
@@ -10840,6 +10844,9 @@ declare class ErrorMessageService {
     getSubmitErrorMessage(error: unknown): string;
     private fallbackMessage;
     private normalizeDetails;
+    private resolveVersionPreconditionCopy;
+    private staleResourceVersionMessage;
+    private resourceVersionRequiredMessage;
     private objectValue;
     private textValue;
     private numberValue;
@@ -16232,6 +16239,8 @@ interface WidgetPageDataSourceDefinition {
     kind?: WidgetPageDataSourceKind;
     /** Caminho do recurso canônico no backend Praxis (ex: 'human-resources/funcionarios/stats/group-by'). */
     resourcePath: string;
+    /** Chave opcional do endpoint configurado em API_URL (padrão: 'default'). */
+    endpointKey?: string;
     /** Método HTTP utilizado (padrão: 'POST' para endpoints /stats, 'GET' para recursos padrão). */
     method?: WidgetPageDataSourceMethod;
     /** Parâmetros de consulta (query params para GET ou corpo da requisição para POST de analytics). */
@@ -18246,17 +18255,25 @@ declare class WidgetPageDataSourceRuntimeService {
     /**
      * Constrói a URL canônica completa para o resourcePath declarado no dataSource.
      */
-    resolveUrl(resourcePath: string): string;
+    resolveUrl(resourcePath: string, endpointKey?: string): string;
     /**
      * Executa uma única consulta para um DataSource e retorna o resultado transformado.
      */
     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.
      */
@@ -18776,6 +18793,7 @@ declare class DynamicWidgetPageComponent implements OnChanges, OnDestroy {
     private pendingDataSourceUpdates;
     private isCoalescingDataSourceUpdates;
     private readonly dataSourceRuntimeOverlay;
+    private readonly dataSourceDiagnostics;
     private readonly nestedWidgetAccessor;
     private readonly settingsPanel;
     private readonly defaultShellEditor;
@@ -19007,6 +19025,7 @@ declare class DynamicWidgetPageComponent implements OnChanges, OnDestroy {
     private applyPageUpdate;
     private handleDataSourceUpdate;
     private flushPendingDataSourceUpdates;
+    private handleDataSourceDiagnostic;
     private restartDataSources;
     private applyLayout;
     private applyCanvasLayout;