@praxisui/page-builder 10.0.0-rc.4 → 10.0.0-rc.41

package/README.md

@@ -4,6 +4,56 @@ 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.
 
+For the prospective governed-page journey, see [Create, review and publish pages — UX design](https://github.com/codexrodrigues/praxis-ui-angular/blob/main/projects/praxis-page-builder/docs/governed-page-publication-ux.md). This is a storyboard and acceptance criteria for subsequent host/lifecycle integration; it does not make page creation or publication available in the current builder.
+
+## 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 +137,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 +163,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 +185,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 +200,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 +293,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 +582,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,9 +1148,70 @@ 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
 
 - [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 -->
+
+### Optional editing highlight
+
+This feature was added in source after `10.0.0-rc.36`; it is not yet part of a published package release.
+
+`WidgetShellConfig.appearance.card.interactionHighlight` selects `standard` or
+`gradient`. Omit it to inherit the shell preset; the final default is `standard`.
+An explicit `standard` overrides a gradient preset. This is editing chrome: it
+appears on selection or keyboard focus while customization is enabled, never as a
+permanent border in the published page. Focusing a child control does not change selection; the highlight itself does not emit selection.
+The gradient uses the current primary, tertiary and secondary theme tokens. Resize
+grips follow the same choice. Internal control focus indicators remain intact;
+blocked canvas operations retain the error indicator and forced colors use a solid
+system-color outline. The highlight follows the resolved card radius (square for
+content-only shells).
+
+```json
+{"shell":{"kind":"dashboard-card","appearance":{"card":{"interactionHighlight":"gradient"}}}}
+```
+
+In Widget settings → Appearance, choose Inherit, Standard or Gradient and inspect
+its preview. Apply updates the local draft; the host controls remote persistence.
+Saving the settings panel alone is not proof of a server write: the reference Page
+Builder host requires Save page. Reopening and Reset preserve the distinction between
+an omitted value and an explicit override. Editing appearance on a widget without a
+shell preserves content-only presentation (`kind: 'none'`); a card requires an explicit
+choice. The option does not change child component inputs or enable customization.
+
+This preference controls editing appearance; it grants no authorization and carries
+no business selection state. The host integrates persistence, identity and tenant
+scope through the canonical configuration infrastructure, including its ETag
+contract; this option requires no separate ETag implementation in the host. Editing only this preference must preserve unrelated
+shell settings, including `bodyLayout`, `windowActions` and action `pressed` values.
+Local editor round-trip tests do not prove remote tenant isolation or ETag behavior.
+
+The existing AI operation `widget.shell.configure` merges partial shell input.
+Omitting `interactionHighlight` from that input preserves an existing override; it
+does not perform the visual editor's Inherit action, which removes the field from
+the complete saved document. Explicit `standard` disables the gradient but remains
+an override. Resetting an existing override to inherited styling through this AI
+operation remains unsupported; this option does not imply full editor/AI parity.
+
+The historical live shell-authoring trial recorded in the validation report did
+not establish SSE, apply and persisted reopen support: its global assistant entry
+had no pinned widget target. Contextual child authoring also needs the correct
+operation owner and complete Page Builder document, rather than a child manifest
+and `definition.inputs`. Schema publication and compiler unit tests alone do not
+prove that journey. This integration preserves current dispatch; the historical
+failure is not a claim that every path on the current main has been disproven.
+Use the separately validated visual editor path for this preference until a
+successful shell-authoring AI journey is recorded for the integrated source.
+
+## Reusable copy and save-as journey
+
+`PraxisPageCopyActionComponent` and `PraxisPageSaveAsComponent` provide reusable authoring controls for copying the current draft and saving a new page with a menu name/icon and confirmed internal route. Hosts provide an explicit `PageSaveAsAdapter`; the controls own validation feedback, retry snapshot/key, busy state, obsolete callback rejection and the last confirmed link. They do not provide storage or grant publication authority.
+
+Connect `saveRequested` to `DynamicPageBuilderComponent.saveCurrentPage()` and its `pageSaveRequested` to `saveAs.save($event)` with `autoPersist=false`. Keep host routing, persistence and authorization in the adapter. See [contract, integration and proof limits](https://github.com/codexrodrigues/praxis-ui-angular/blob/main/projects/praxis-page-builder/docs/page-save-as.md). The first Hero proof is browser-local, not governed corporate publication; importing hosts require the matching packaged API before merge.