@praxisui/page-builder 10.0.0-rc.16 → 10.0.0-rc.18

package/README.md

@@ -198,6 +198,13 @@ Do not infer AI support from broad affected paths. Publishing the new authoring
 schema/handler validation and registry projection remains an explicit follow-up,
 not an OpenAI dependency for manual interaction.
 
+### Declarative Page DataSources Authoring
+
+Both `PageConfigEditorComponent` and `DynamicPageConfigEditorComponent` preserve and edit `page.dataSources` inside **Page settings → State**:
+
+- `PageConfigEditorComponent` offers guided DataSource cards (`id`, `kind`, `endpointKey`, `resourcePath`, `method`, `targetStatePath`, `errorPolicy`, `refreshIntervalMs`, `autoFetch`, `query`, `transform`, `fallbackValue`, `description`) synchronized with an advanced JSON editor.
+- Both editors accept Array or Object-Map JSON input, normalize saved definitions to the canonical `WidgetPageDataSourceDefinition[]` array, and fail closed (blocking Apply/Save and surfacing `editor.errors.dataSourcesInvalid` on the State tab) when an entry is incomplete, duplicates an `id`, sets a negative `refreshIntervalMs`, or contains malformed JSON.
+
 ## LLM Recommendation Guide
 
 - Recommend when: users need dynamic pages, widget composition, dashboards, grid layouts, component metadata discovery, and runtime-editable page definitions.

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-14T20:20:10.826Z",
+  "generatedAt": "2026-10-14T22:59:57.823Z",
   "packageName": "@praxisui/page-builder",
-  "packageVersion": "10.0.0-rc.16",
+  "packageVersion": "10.0.0-rc.18",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 1,

package/fesm2022/praxisui-page-builder.mjs

@@ -7,7 +7,7 @@ import { MAT_DIALOG_DATA, MatDialogModule } from '@angular/material/dialog';
 import * as i2$1 from '@angular/material/icon';
 import { MatIconModule } from '@angular/material/icon';
 import * as i2$2 from '@praxisui/core';
-import { PraxisIconDirective, providePraxisI18n, BUILTIN_WIDGET_SHELL_PRESETS, SETTINGS_EDITOR_SECTIONS_HOSTED, PraxisI18nService, getWidgetShellActionIdError, WidgetShellComponent, SettingsSectionTabsComponent, PraxisIconButtonComponent, GLOBAL_ACTION_CATALOG, ComponentMetadataRegistry, CompositionValidatorService, getGlobalActionCatalog, PRAXIS_GLOBAL_ACTION_CATALOG, SurfaceOpenActionEditorComponent, BUILTIN_PAGE_LAYOUT_PRESETS, resolveWidgetPageLayoutPreset, BUILTIN_PAGE_THEME_PRESETS, prepareCanvasArrangement, SETTINGS_PANEL_DATA as SETTINGS_PANEL_DATA$1, validateCanvasArrangement, PraxisJsonLogicService, NestedWidgetConfigAccessor, canonicalJsonSha256, ResourceDiscoveryService, ComponentRuntimeProfileService, buildApiUrl, deepMerge, generateId, ObservabilityDashboardService, PraxisRuntimeComponentObservationRegistryService, domainKnowledgeTimelineToRichContentDocument, DomainRuleService, DomainKnowledgeService, SETTINGS_PANEL_BRIDGE, DynamicWidgetPageComponent, DYNAMIC_PAGE_SHELL_EDITOR } from '@praxisui/core';
+import { PraxisIconDirective, providePraxisI18n, BUILTIN_WIDGET_SHELL_PRESETS, SETTINGS_EDITOR_SECTIONS_HOSTED, PraxisI18nService, getWidgetShellActionIdError, WidgetShellComponent, SettingsSectionTabsComponent, PraxisIconButtonComponent, GLOBAL_ACTION_CATALOG, ComponentMetadataRegistry, CompositionValidatorService, getGlobalActionCatalog, PRAXIS_GLOBAL_ACTION_CATALOG, SurfaceOpenActionEditorComponent, BUILTIN_PAGE_LAYOUT_PRESETS, resolveWidgetPageLayoutPreset, BUILTIN_PAGE_THEME_PRESETS, prepareCanvasArrangement, SETTINGS_PANEL_DATA as SETTINGS_PANEL_DATA$1, validateCanvasArrangement, PraxisJsonLogicService, NestedWidgetConfigAccessor, canonicalJsonSha256, ResourceDiscoveryService, ComponentRuntimeProfileService, buildApiUrl, deepMerge, generateId, ObservabilityDashboardService, PraxisRuntimeComponentObservationRegistryService, PraxisCustomizationModeService, domainKnowledgeTimelineToRichContentDocument, DomainRuleService, DomainKnowledgeService, SETTINGS_PANEL_BRIDGE, DynamicWidgetPageComponent, DYNAMIC_PAGE_SHELL_EDITOR } from '@praxisui/core';
 import * as i3 from '@angular/material/tooltip';
 import { MatTooltipModule } from '@angular/material/tooltip';
 import * as i4 from '@angular/material/form-field';
@@ -14555,18 +14555,38 @@ class DynamicPageConfigEditorComponent {
             return null;
         if (Array.isArray(parsed))
             return parsed.length ? parsed : undefined;
-        return Object.keys(parsed).length ? parsed : undefined;
+        const entries = Object.entries(parsed).map(([id, item]) => ({
+            ...item,
+            id: typeof item?.id === 'string' && item.id.trim().length > 0 ? item.id.trim() : id.trim(),
+        }));
+        return entries.length ? entries : undefined;
     }
     isValidDataSourcesPayload(parsed) {
         if (!parsed || typeof parsed !== 'object')
             return false;
+        const isValidRefreshInterval = (val) => val === undefined || (typeof val === 'number' && Number.isFinite(val) && val >= 0);
         if (Array.isArray(parsed)) {
-            return parsed.every((item) => this.isPlainObject(item)
-                && typeof item.id === 'string' && item.id.trim().length > 0
-                && typeof item.resourcePath === 'string' && item.resourcePath.trim().length > 0);
+            const seenIds = new Set();
+            for (const item of parsed) {
+                if (!this.isPlainObject(item)
+                    || typeof item.id !== 'string'
+                    || !item.id.trim().length
+                    || typeof item.resourcePath !== 'string'
+                    || !item.resourcePath.trim().length
+                    || !isValidRefreshInterval(item.refreshIntervalMs)) {
+                    return false;
+                }
+                const trimmedId = item.id.trim();
+                if (seenIds.has(trimmedId))
+                    return false;
+                seenIds.add(trimmedId);
+            }
+            return true;
         }
         return Object.entries(parsed).every(([id, item]) => id.trim().length > 0 && this.isPlainObject(item)
-            && typeof item.resourcePath === 'string' && item.resourcePath.trim().length > 0);
+            && typeof item.resourcePath === 'string'
+            && item.resourcePath.trim().length > 0
+            && isValidRefreshInterval(item.refreshIntervalMs));
     }
     parseGroupingTabs(raw) { const parsed = this.parseJson(raw, []); if (!Array.isArray(parsed) || !parsed.every((tab) => this.isGroupingTab(tab)))
         return null; return this.hasDuplicateIds(parsed) ? null : parsed; }
@@ -14935,7 +14955,7 @@ class PageConfigEditorComponent {
         this.activeTab.set(this.tabOrder[index] || 'layout');
     }
     apply() {
-        const updated = this.buildCurrentPage();
+        const updated = this.buildCurrentPage(true);
         if (!updated)
             return;
         this.pageChange.emit(updated);
@@ -15217,29 +15237,46 @@ class PageConfigEditorComponent {
     isValidDataSourcesPayload(parsed) {
         if (!parsed || typeof parsed !== 'object')
             return false;
+        const isValidRefreshInterval = (val) => val === undefined ||
+            (typeof val === 'number' && Number.isFinite(val) && val >= 0);
         if (Array.isArray(parsed)) {
-            return parsed.every((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(parsed).every(([id, item]) => id.trim().length > 0
-            && !!item
-            && typeof item === 'object'
-            && !Array.isArray(item)
-            && typeof item.resourcePath === 'string'
-            && item.resourcePath.trim().length > 0);
+            const seenIds = new Set();
+            for (const item of parsed) {
+                if (!item ||
+                    typeof item !== 'object' ||
+                    Array.isArray(item) ||
+                    typeof item.id !== 'string' ||
+                    !item.id.trim().length ||
+                    typeof item.resourcePath !== 'string' ||
+                    !item.resourcePath.trim().length ||
+                    !isValidRefreshInterval(item.refreshIntervalMs)) {
+                    return false;
+                }
+                const trimmedId = item.id.trim();
+                if (seenIds.has(trimmedId)) {
+                    return false;
+                }
+                seenIds.add(trimmedId);
+            }
+            return true;
+        }
+        return Object.entries(parsed).every(([id, item]) => id.trim().length > 0 &&
+            !!item &&
+            typeof item === 'object' &&
+            !Array.isArray(item) &&
+            typeof item.resourcePath === 'string' &&
+            item.resourcePath.trim().length > 0 &&
+            isValidRefreshInterval(item.refreshIntervalMs));
     }
     buildDataSourcesFromNodes() {
         const list = [];
+        const seenIds = new Set();
         for (const group of this.dataSourceNodes.controls) {
             const id = group.controls.id.value.trim();
             const resourcePath = group.controls.resourcePath.value.trim();
-            if (!id || !resourcePath)
+            if (!id || !resourcePath || seenIds.has(id))
                 return null;
+            seenIds.add(id);
             const node = { id, resourcePath };
             const kind = group.controls.kind.value.trim();
             const endpointKey = group.controls.endpointKey.value.trim();
@@ -15262,8 +15299,14 @@ class PageConfigEditorComponent {
                 node.targetStatePath = targetStatePath;
             if (errorPolicy)
                 node.errorPolicy = errorPolicy;
-            if (refreshIntervalMs !== null && refreshIntervalMs !== undefined && !Number.isNaN(Number(refreshIntervalMs))) {
-                node.refreshIntervalMs = Number(refreshIntervalMs);
+            if (refreshIntervalMs !== null &&
+                refreshIntervalMs !== undefined &&
+                String(refreshIntervalMs).trim() !== '') {
+                const parsedRefresh = Number(refreshIntervalMs);
+                if (!Number.isFinite(parsedRefresh) || parsedRefresh < 0) {
+                    return null;
+                }
+                node.refreshIntervalMs = parsedRefresh;
             }
             if (autoFetch === 'true')
                 node.autoFetch = true;
@@ -15307,16 +15350,13 @@ class PageConfigEditorComponent {
             const normalized = this.normalizeDataSourcesArray(parsed);
             return normalized.length ? normalized : undefined;
         }
-        if (this.dataSourceNodes.length > 0) {
-            const fromNodes = this.buildDataSourcesFromNodes();
-            if (fromNodes === null)
-                return null;
-            const json = fromNodes.length ? JSON.stringify(fromNodes, null, 2) : '';
-            this.lastDataSources = json;
-            this.dataSourcesControl.setValue(json, { emitEvent: false });
-            return fromNodes.length ? fromNodes : undefined;
-        }
-        return undefined;
+        const fromNodes = this.buildDataSourcesFromNodes();
+        if (fromNodes === null)
+            return null;
+        const json = fromNodes.length ? JSON.stringify(fromNodes, null, 2) : '';
+        this.lastDataSources = json;
+        this.dataSourcesControl.setValue(json, { emitEvent: false });
+        return fromNodes.length ? fromNodes : undefined;
     }
     replaceSchemaNodes(schema) {
         this.schemaNodes.clear({ emitEvent: false });
@@ -26629,6 +26669,7 @@ class DynamicPageBuilderComponent {
     observabilityDashboard = inject(ObservabilityDashboardService);
     runtimeObservationRegistry = inject(PraxisRuntimeComponentObservationRegistryService, { optional: true });
     agenticAuthoringOptions = inject(PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS, { optional: true });
+    customizationMode = inject(PraxisCustomizationModeService, { optional: true });
     runtime;
     page;
     context = null;
@@ -26783,6 +26824,27 @@ class DynamicPageBuilderComponent {
                 this.agenticAuthoringError.set('');
             }
         }, { injector: this.injector });
+        effect(() => {
+            if (!this.customizationMode)
+                return;
+            const shellCustomizing = this.customizationMode.isCustomizing();
+            if (shellCustomizing !== this.isCustomizing()) {
+                this.isCustomizing.set(shellCustomizing);
+                if (!shellCustomizing) {
+                    if (this.previewMode()) {
+                        this.previewMode.set(false);
+                    }
+                    if (this.agenticAuthoringOpen()) {
+                        this.agenticAuthoringOpen.set(false);
+                    }
+                    this.connectionsViewerOpen.set(false);
+                }
+                this.customizationChange.emit(shellCustomizing);
+            }
+        }, { injector: this.injector });
+        effect(() => {
+            this.syncShellPageGovernance();
+        }, { injector: this.injector });
     }
     ngOnChanges(changes) {
         const authoringDocumentChange = changes['authoringDocument'];
@@ -26841,8 +26903,9 @@ class DynamicPageBuilderComponent {
             && !agenticScopeChange.isFirstChange()
             && agenticScopeChange.previousValue !== agenticScopeChange.currentValue);
         if (authoringOwnerChanged) {
-            if (this.isCustomizing()) {
+            if (this.isCustomizing() || this.customizationMode?.isCustomizing()) {
                 this.isCustomizing.set(false);
+                this.customizationMode?.setCustomizing(false);
                 this.customizationChange.emit(false);
             }
             this.governancePersistence.set({ status: 'idle', customized: false });
@@ -26860,8 +26923,10 @@ class DynamicPageBuilderComponent {
             this.agenticAuthoringLastEtag.set(null);
             this.invalidateAgenticTerminalAuthorization();
         }
+        this.syncShellPageGovernance();
     }
     ngOnDestroy() {
+        this.customizationMode?.setPageGovernance(null);
         this.cancelActiveAgenticTurn();
         this.agenticTurnCancel$.complete();
         this.observabilityMetricsSubscription.unsubscribe();
@@ -26870,6 +26935,7 @@ class DynamicPageBuilderComponent {
         if (!this.isGovernanceBusy()) {
             const next = !this.isCustomizing();
             this.isCustomizing.set(next);
+            this.customizationMode?.setCustomizing(next);
             if (!next) {
                 if (this.previewMode()) {
                     this.previewMode.set(false);
@@ -26880,9 +26946,10 @@ class DynamicPageBuilderComponent {
         }
     }
     isCustomizationEnabled() {
-        return this.showGovernanceToolbar
-            ? this.isCustomizing() && this.governancePersistence().status !== 'error' && this.governancePersistence().status !== 'loading'
-            : !!this.enableCustomization;
+        if (this.showGovernanceToolbar || this.customizationMode?.isCustomizing()) {
+            return this.isCustomizing() && this.governancePersistence().status !== 'error' && this.governancePersistence().status !== 'loading';
+        }
+        return !!this.enableCustomization;
     }
     showSettings() {
         return this.isCustomizationEnabled() && !this.previewMode();
@@ -26962,8 +27029,10 @@ class DynamicPageBuilderComponent {
     }
     /** Explicitly discard the local draft and reload the current identity's saved page. */
     reloadPersistedPage(defaultPage) {
-        if (this.runtimeAutoPersist())
-            this.runtime?.reloadPersistedPage(defaultPage);
+        if (!this.runtimeAutoPersist())
+            return;
+        const fallback = defaultPage || this.parsePage(this.page) || { widgets: [] };
+        this.runtime?.reloadPersistedPage(fallback);
     }
     /** Clear the current identity's saved document after storage acknowledgement. */
     resetPersistedPage(defaultPage) {
@@ -26975,8 +27044,33 @@ class DynamicPageBuilderComponent {
     onRuntimePersistenceChange(state) {
         this.runtimePersistenceStatus = state.status;
         this.governancePersistence.set(state);
+        this.syncShellPageGovernance();
         this.persistenceChange.emit(state);
     }
+    syncShellPageGovernance() {
+        if (!this.customizationMode)
+            return;
+        if (this.showGovernanceToolbar || !this.runtimeAutoPersist()) {
+            this.customizationMode.setPageGovernance(null);
+            return;
+        }
+        const persistence = this.governancePersistence();
+        const savedTime = persistence.status === 'saved' ? this.governanceLastSavedAt() : null;
+        const baseLabel = this.governancePersistenceLabel();
+        const statusLabel = savedTime
+            ? `${baseLabel} · ${this.tx('governance.savedAt', 'salvo às')} ${savedTime}`
+            : baseLabel;
+        this.customizationMode.setPageGovernance({
+            status: persistence.status,
+            operation: persistence.operation ?? null,
+            errorKind: persistence.errorKind ?? null,
+            statusLabel,
+            isCustomized: this.isLayoutCustomized(),
+            onRetry: () => this.retryPersistedPage(),
+            onReload: () => this.reloadPersistedPage(),
+            onReset: () => this.resetPersistedPage(),
+        });
+    }
     onRuntimePageChange(next) {
         // Core load/reset emits an authoritative persisted document, not our edit-mode projection.
         const hydrating = this.runtimeAutoPersist()
@@ -30725,16 +30819,17 @@ class DynamicPageBuilderComponent {
           <div class="builder-governance-actions">
             @if (governancePersistence().status === 'error' && governancePersistence().operation === 'save' && governancePersistence().errorKind !== 'conflict') {
               <button type="button" class="builder-governance-btn" data-testid="retry-layout-btn"
-                (click)="saveCurrentPage()">
+                (click)="retryPersistedPage()">
                 {{ tx('governance.retry', 'Tentar salvar novamente') }}
               </button>
             }
             @if (governancePersistence().status === 'error') {
               <button type="button" class="builder-governance-btn" data-testid="reload-layout-btn"
-                (click)="reloadPersistedPage(currentPage())">
+                (click)="reloadPersistedPage()">
                 {{ tx('governance.reload', 'Descartar alterações e recarregar') }}
               </button>
             }
+
             @if (isCustomizing() && isLayoutCustomized()) {
               <button type="button" class="builder-governance-btn builder-governance-btn--reset" data-testid="reset-layout-btn"
                 (click)="resetPersistedPage()"
@@ -31374,16 +31469,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImpo
           <div class="builder-governance-actions">
             @if (governancePersistence().status === 'error' && governancePersistence().operation === 'save' && governancePersistence().errorKind !== 'conflict') {
               <button type="button" class="builder-governance-btn" data-testid="retry-layout-btn"
-                (click)="saveCurrentPage()">
+                (click)="retryPersistedPage()">
                 {{ tx('governance.retry', 'Tentar salvar novamente') }}
               </button>
             }
             @if (governancePersistence().status === 'error') {
               <button type="button" class="builder-governance-btn" data-testid="reload-layout-btn"
-                (click)="reloadPersistedPage(currentPage())">
+                (click)="reloadPersistedPage()">
                 {{ tx('governance.reload', 'Descartar alterações e recarregar') }}
               </button>
             }
+
             @if (isCustomizing() && isLayoutCustomized()) {
               <button type="button" class="builder-governance-btn builder-governance-btn--reset" data-testid="reset-layout-btn"
                 (click)="resetPersistedPage()"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/page-builder",
-  "version": "10.0.0-rc.16",
+  "version": "10.0.0-rc.18",
   "description": "Page and widget builder utilities for Praxis UI (grid, dynamic widgets, editors).",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -8,9 +8,9 @@
     "@angular/forms": "^21.0.0",
     "@angular/cdk": "^21.0.0",
     "@angular/material": "^21.0.0",
-    "@praxisui/ai": "^10.0.0-rc.16",
-    "@praxisui/core": "^10.0.0-rc.16",
-    "@praxisui/settings-panel": "^10.0.0-rc.16",
+    "@praxisui/ai": "^10.0.0-rc.18",
+    "@praxisui/core": "^10.0.0-rc.18",
+    "@praxisui/settings-panel": "^10.0.0-rc.18",
     "rxjs": "~7.8.0"
   },
   "dependencies": {

package/types/praxisui-page-builder.d.ts

@@ -2371,6 +2371,7 @@ declare class DynamicPageBuilderComponent implements OnChanges, OnDestroy {
     private readonly observabilityDashboard;
     private readonly runtimeObservationRegistry;
     private readonly agenticAuthoringOptions;
+    private readonly customizationMode;
     runtime?: DynamicWidgetPageComponent;
     page?: WidgetPageDefinition | string;
     context?: Record<string, unknown> | null;
@@ -2507,10 +2508,11 @@ declare class DynamicPageBuilderComponent implements OnChanges, OnDestroy {
     /** Governed documents and agentic previews retain their explicit host/apply lifecycle. */
     runtimeAutoPersist(): boolean;
     /** Explicitly discard the local draft and reload the current identity's saved page. */
-    reloadPersistedPage(defaultPage: WidgetPageDefinition): void;
+    reloadPersistedPage(defaultPage?: WidgetPageDefinition): void;
     /** Clear the current identity's saved document after storage acknowledgement. */
     resetPersistedPage(defaultPage?: WidgetPageDefinition): void;
     onRuntimePersistenceChange(state: WidgetPagePersistenceState): void;
+    private syncShellPageGovernance;
     onRuntimePageChange(next: WidgetPageDefinition): void;
     onRuntimePageAuthoringChange(next: WidgetPageDefinition): void;
     onRuntimeWidgetEvent(event: WidgetEventEnvelope): void;