@praxisui/page-builder 9.0.68-rc.3 → 10.0.0-rc.10

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**
@@ -345,9 +393,21 @@ Feedback cycles are validated before authoring and runtime delivery. Direct or i
 The visual connection editor is an authoring surface over the saved `composition.links` document. It does not create a parallel graph DSL.
 
 Invalid JSON in an embedded Surface editor starts or retains the connection draft
-and blocks Apply. Correcting that text still respects the other connection
+and blocks Apply unless a payload expression is the effective source. Correcting that text still respects the other connection
 diagnostics; Cancel discards the transient text without publishing a page change.
 
+For a `global-action` target, absence of both structured `payload` and
+`payloadExpr` means the action receives the value delivered by the connection;
+it is not an implicit literal. A pre-existing `payloadExpr` remains the effective
+source even when a structured payload is preserved, until the author explicitly
+chooses a source. The Connection Editor does not author or edit expression text.
+Choosing structured data removes the existing expression; if no structured value
+is then present, delivery remains the source. An invalid structured Surface draft
+may stay locally preserved while an expression is active, but it is not the active
+payload and does not publish a page change. Cancel discards that transient draft
+with the rest of the connection transaction. Returning to a source without an
+expression reactivates its error and Apply block until the draft is repaired or discarded.
+
 Current capabilities include:
 
 - inspecting persisted links, endpoints, intent, condition, transform and policy through the on-demand **Inspector**; opening it from the toolbar, canvas, link list, **Locate**, or port catalogue brings focus to the inspector header; catalogue and inspector are mutually exclusive. Dismissal restores the initiating catalogue, selected port and connection when applicable, including its internal scroll position; Escape closes one inspection layer at a time. Other entries restore their initiating control, with the editor as fallback when a canvas target is offscreen;
@@ -511,6 +571,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.
@@ -1059,3 +1136,14 @@ and block value production with a localized diagnostic, allowing correction with
 losing unrelated context. Arrangement choices track their draft baseline even when the
 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
+
+- [Canonical technical overview: Overview](https://praxisui.dev/docs/components/praxis-page-builder)
+- [Praxis Angular public catalog](https://praxisui.dev/angular)
+<!-- praxis-npm-catalog-links:end -->