@praxisui/page-builder 10.0.0-rc.3 → 10.0.0-rc.31

package/README.md

@@ -4,6 +4,54 @@ Visual page and dashboard builder for Praxis UI applications.
 
 Use this package when an application must let users compose governed operational pages from registered widgets, visual layout, shell settings, component editors, `composition.links`, and optional AI-assisted authoring.
 
+## Dashboard pages and persistence ownership
+
+A dashboard is a `WidgetPageDefinition` rendered by `praxis-dynamic-page` and edited
+by `praxis-dynamic-page-builder`. The beta `PraxisDashboardPage` wrapper was removed;
+use these existing components instead. Application titles, toolbar presentation and
+business navigation remain host concerns.
+
+For manual page editing, opt in to the Core persistence lifecycle:
+
+```html
+<praxis-dynamic-page-builder
+  #builder
+  [page]="defaultPage"
+  [pageIdentity]="identity"
+  [autoPersist]="true"
+  [enableCustomization]="editing"
+  (persistenceChange)="persistence = $event"
+/>
+```
+
+`autoPersist` defaults to `false` on the builder, preserving its previous effective
+behavior (the child runtime previously always received `false`). Hosts that already
+persist `pageAuthoringChange`/`pageSaveRequested` must leave it disabled. Core Dynamic
+Page keeps its own existing default. Do not enable a second host writer when Core
+owns persistence.
+
+Pass `PageIdentity` with the application's actual tenant/user/route. Core uses the
+configured `ASYNC_CONFIG_STORAGE`; no separate localStorage cache, browser globals
+or persona-specific host reconciler is needed. Storage identity is not backend
+authorization. Persisted documents, including an empty widget list, are authoritative;
+new factory widgets are not silently appended to a user's saved page.
+
+`persistenceChange` forwards Core's operational `WidgetPagePersistenceState`:
+`idle`, `loading`, `saving`, `saved`, `resetting` or `error`, with `customized`, optional
+ISO `savedAt`, operation and a safe `errorKind`. Show success only after acknowledgement,
+and distinguish conflicts from a pending or failed write. It is not business metadata
+and must not be persisted in `WidgetPageDefinition`.
+
+`builder.resetPersistedPage(defaultPage)` deletes this identity's saved page and applies
+the supplied default only after acknowledgement. `builder.reloadPersistedPage(defaultPage)`
+explicitly discards the draft and reloads storage, using the supplied default when no saved
+page exists. Make that destructive-to-draft intent visible in the host. The existing Save
+button retries through Core for manually managed pages; conflicts require an explicit reload.
+
+For `authoringDocument` or agentic authoring, Core automatic persistence is disabled even
+when requested: the existing host/server apply lifecycle owns revisions and provenance.
+An AI preview must never be saved through an automatic generic config write.
+
 ## Widget shell editor integrity
 
 The shell editor exposes **Keep header visible while scrolling the page**
@@ -87,7 +135,7 @@ order, with natural content height. It replaces positions and width bounds only
 that device, preserves hidden widgets and other overrides, and leaves the base and
 other device layouts unchanged. Apply/Save materializes the existing
 `deviceLayouts[device].canvas` contract; Reset restores the original draft.
-Advanced JSON overrides remain available under **Advanced overrides**.
+Advanced JSON overrides remain available under **Advanced overrides** (`widgetOverrides`) and strictly validate the canonical `WidgetPageWidgetLayoutOverride` keys (`className`, `span`, `order`, `hidden`), diagnosing and rejecting unsupported properties such as `definition` or `inputs` without discarding the user's draft text.
 
 Reducing a device's column count also reflows inherited base positions in Core.
 Explicit device positions remain authoritative. With no device variant the base
@@ -113,7 +161,7 @@ documents already clamped by Core remain valid on opening: declared spans need
 not equal rendered spans. Invalid inherited bounds can be corrected in the same
 draft. The editor does not rewrite geometry to satisfy newly authored bounds.
 Dynamic title expressions are
-identified by stable widget key, not evaluated in the editor.
+identified by stable widget key and resolved friendly widget titles (from static shell metadata or inner widget titles), not evaluated in the editor.
 
 Apply previews the same document returned by Save; Reset reloads the input baseline.
 Pending changes are tracked independently of validity, including edits to an
@@ -135,7 +183,7 @@ Page, the editor receives transient runtime validation through `SETTINGS_PANEL_D
 Apply/Save and reopen check the current active-device geometry and report the minimum
 beside the height field. The callback and observed dimensions never enter the document.
 Changed columns, gap, width or shell styling require Automatic height, Apply, then
-reopening before choosing a measured height. Other device variants must be checked
+reopening before choosing a measured height. When switching a visual template (`themePreset` / `layoutPreset`) triggers rendered-height validation blocks on widgets with adjustable heights, the editor surfaces an actionable banner across Studio tabs listing all affected widgets with their friendly names and current pixel heights, offering direct navigation to **Widget limits** or a one-click conversion to **Automatic** height that preserves a summary of the previous pixel measurements for review. Other device variants must be checked
 on their corresponding device. Standalone/custom hosts without this runtime context
 retain numeric validation only. Core's scroll-layout shell now recovers access after
 late header/content growth by temporarily scrolling the header and body together
@@ -150,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**:
+
+- Both `PageConfigEditorComponent` and `DynamicPageConfigEditorComponent` offer guided DataSource cards (`id`, `kind`, `endpointKey`, `resourcePath`, `method`, `targetStatePath`, `errorPolicy`, `refreshIntervalMs`, `autoFetch`, `query`, `transform`, `fallbackValue`, `description`) synchronized bidirectionally with the advanced JSON editor (`[data-testid="page-datasources-json"]`).
+- Both editors accept Array or Object-Map JSON input, normalize saved definitions to the canonical `WidgetPageDataSourceDefinition[]` array, and enforce symmetric validation across guided and raw JSON authoring—failing closed (blocking Apply/Save and surfacing `editor.errors.dataSourcesInvalid` on the State tab) when an entry is missing `id` or `resourcePath`, duplicates a normalized `id`, sets an unsupported `kind`/`method`/`errorPolicy`, sets a negative or non-finite `refreshIntervalMs`, passes a non-object `query`, declares an incomplete `transform` (`path`, `group-by-map`, `timeseries-last`), 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.
@@ -236,6 +291,8 @@ source fails closed.
 - `enableAgenticAuthoring`, `agenticAuthoringProvider`, `agenticAuthoringModel`, `agenticAuthoringScope`
 - `agenticAuthoringIncludeLlmDiagnostics`, `agenticAuthoringEnableStreaming`, `agenticAuthoringContextHints`
 - `showPageLifecycleActions`, `canDeleteSavedPage`, `pageLifecycleBusy`
+- `showGovernanceToolbar`: boolean flag to render a built-in top governance toolbar (with canvas title, layout persistence status badge, last saved time, factory reset button, and customization toggle), enabling 100% declarative page hosting without imperative toolbar boilerplate
+- `governanceToolbarTitle`: optional string providing the canvas or dashboard title displayed in the governance toolbar
 
 All omitted `authoringCapabilities` entries remain enabled for backward compatibility. The grant is
 never written to `WidgetPageDefinition` and does not authorize AI operations; manifests, backend
@@ -523,6 +580,23 @@ Schema-derived table columns already use the canonical `TableConfig.columnProjec
 
 `ComponentDocMeta.insertionPresets` remains the canonical catalog for reusable defaults owned by one component. It is not a page/domain template system: do not publish Employee Operations presets from CRUD, tabs, or related-resource outlet metadata merely to shorten a business recipe.
 
+To streamline host registration of widget providers and component metadata without repetitive manual bootstrap code, `@praxisui/page-builder` exports the `providePraxisPageBuilderWidgets(widgets?: Array<Provider | ComponentDocMeta>)` helper. Hosts can supply a bundle of standard providers or direct `ComponentDocMeta` objects; any `ComponentDocMeta` passed is automatically registered with `ComponentMetadataRegistry` during environment initialization:
+
+```ts
+import { providePraxisPageBuilderWidgets } from '@praxisui/page-builder';
+import { providePraxisListMetadata } from '@praxisui/list';
+import { providePraxisTableMetadata } from '@praxisui/table';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...providePraxisPageBuilderWidgets([
+      providePraxisListMetadata(),
+      providePraxisTableMetadata(),
+    ]),
+  ],
+};
+```
+
 For complete governed page templates, the additive `UiCompositionPlanTemplateReference` pins the canonical `ai_registry` key and complete `configJson` SHA-256. The Config Starter resolves the active `SYSTEM/GLOBAL` record, verifies the exact hash, extracts its governed `authoringPlan`, and only then invokes the existing compiler. Angular consumers can use the pure `resolveUiCompositionPlanTemplate` helper only with an explicitly supplied `UiCompositionPlanTemplateMaterialization`; the helper performs no HTTP, search, or implicit selection. The first contract accepts no non-empty overrides, fails closed for missing, inactive, malformed, or stale references, and never persists the unresolved reference. `version` and `etag` are retained as audit evidence, while `configSha256` is the required content pin.
 
 Keep the compact authoring plan, the compiled executable page, and the surrounding recipe metadata as distinct artifacts. `UiCompositionPlan` is the reviewable authoring intent; `WidgetPageDefinition` is the explicit runtime graph; recipe metadata and operational evidence document when and how the example should be used. The server compiler must produce the same executable page as the Page Builder compiler before persistence.
@@ -1072,6 +1146,10 @@ losing unrelated context. Arrangement choices track their draft baseline even wh
 selected distribution initially produces no changes, so later edits clear stale status.
 These fixes are not part of the already published 9.0.68-rc.2 package.
 
+`retryPersistedPage()` retries the current draft after a non-conflict save failure,
+including empty pages, without emitting host save lifecycle events. Conflicts require
+explicit `reloadPersistedPage(defaultPage)`; reload discards the local draft.
+
 <!-- praxis-npm-catalog-links:start -->
 ## Official documentation and examples