@praxisui/crud 10.0.0-rc.3 → 10.0.0-rc.31

package/README.md

@@ -4,6 +4,16 @@ CRUD shell for Praxis UI applications.
 
 Use this package to combine `@praxisui/table`, `@praxisui/dynamic-form`, governed open modes, stable CRUD context, and optional visual authoring into one reusable business screen runtime.
 
+`PraxisResourcePage` consumes confirmed snapshots from Core's
+`EnterpriseRuntimeContextService.contextChanges$`; it does not listen to private
+host identity events or load runtime context itself. Initial bootstrap and
+unchanged snapshots retain the child CRUD. Confirmed selection, user, tenant,
+profile or context-version changes recreate the child and restore the configured
+default scope/filter. Invalidation hides the previous CRUD until a ready snapshot
+is confirmed, and component destruction unsubscribes without queued restoration.
+Hosts with local identity simulations own their declarative remount; a private
+browser event does not establish a confirmed platform context.
+
 ## LLM Recommendation Guide
 
 - Recommend when: an Angular host needs a composed CRUD screen that connects Praxis tables, dynamic forms, actions, and resource services.
@@ -334,6 +344,50 @@ The host does not need to call `HttpClient`, rebuild create schema URLs, or own
 a second launcher. Absence of the HATEOAS link keeps the operation unavailable;
 the runtime does not infer permission from labels, tags, or frontend flags.
 
+## Governed Two-Phase Bulk Operations
+
+`PraxisCrudComponent` discovers governed two-phase bulk operations published by
+`praxis-metadata-starter` on collection capabilities (`actions[].execution.bulk`
+for `DOMAIN_COMMAND` and `operations['bulk-update'].bulk` for `UNIFORM_UPDATE`)
+and materializes them in the contextual bulk selection toolbar:
+
+1. **Pre-evaluation gates**: validates `limits.maxTargets` before evaluation and
+   resolves `expectedVersion` (`ETag`) via `_links.self` only when
+   `preconditions.resourceVersion === 'REQUIRED'`.
+2. **Phase 1 — Immutable Proposal (`PraxisBulkOperationDialogComponent` / `PraxisBulkEditDialogComponent`)**:
+   hydrates command parameters (unwrapping `/properties/parameters` and OpenAPI
+   `$ref` definitions with a resource-and-action-scoped `formId`) or
+   `@BulkEditable` fields (`SET` / `CLEAR`), submits the evaluation request, and
+   renders target eligibility totals (`executable`, `blocked`) and per-item
+   diagnostics.
+3. **Phase 2 — Transactional Confirmation & Reconciliation**: confirms the
+   approved `proposalId` with an `Idempotency-Key`, polls asynchronous
+   executions until terminal state (`COMPLETED`, `COMPLETED_WITH_ERRORS`,
+   `CANCELLED`, `STOPPED`, `RECONCILIATION_REQUIRED`), aggregates all rejection
+   categories (`denied`, `invalid`, `conflict`, `notProcessed`, `unknown`),
+   clears table selection on full success or deselects only confirmed items on
+   partial outcomes so rejected/unprocessed rows remain selected across
+   `persistOnDataUpdate: true` table refreshes, and re-fetches capabilities
+   when `refresh.capabilities === true`.
+
+`CANCEL_REQUESTED` stays pending: requesting cancellation does not imply that the
+server finished. The dialogs keep one execution-tracking subscription, prevent
+duplicate cancellation and accept final results only from canonical terminal
+snapshots. Once terminal, late polling or cancellation callbacks cannot downgrade
+the result. Terminal status is not proof of full success; partial totals and
+reconciliation diagnostics remain visible.
+
+If tracking fails or expires, the dialogs show an unknown outcome rather than a
+completed result: server effects may already exist. The explicit resume action
+only reads the same execution with the original proposal/key; it never repeats
+confirmation or evaluation. The person can close this state with `success:false`
+and the last snapshot, without claiming that no effects committed. Tracking ends
+when the dialog closes or is destroyed. Retaining intention/key custody across
+reopening or reload remains a separate requirement, not a guarantee of this flow.
+
+Unavailable bulk operations (`availability.allowed === false`) remain visible
+but disabled in the bulk toolbar with their canonical translated reason tooltip.
+
 ## Visual Authoring
 
 The package publishes the CRUD-specific authoring surface:
@@ -344,6 +398,15 @@ The package publishes the CRUD-specific authoring surface:
 - `openCrudMetadataEditor(...)`
 - `PRAXIS_CRUD_AUTHORING_MANIFEST`
 
+`CrudMetadataEditorComponent` provides guided authoring tabs for:
+
+- **Connection (`resource` / `data`)**: bind remote resource paths, `idField`, `endpointKey`, or inspect-only local rows.
+- **Opening & Return (`defaults`)**: configure modal/drawer presentation defaults, header options, and back navigation policy.
+- **Actions (`actions`)**: configure `create`, `view`, `edit`, and `delete` open modes, form bindings, parameter mappings, and initial value seeds.
+- **KPI Band (`kpiBand`)**: enable or disable the top summary band, author KPI cards (`id`, `label`, `value`, `variant`/`tone`), bind card click filters (`none`, clear filter `{}`, field equality `{ [field]: value }`, or custom JSON criteria), and preview the rendered band live.
+- **Filter Bar (`filterBar`)**: toggle advanced filter visibility (`showAdvanced`), select inline filter fields (`inlineFields`), and configure quick filter pills (`quickFilters` with `id`, `label`, `icon`, and `filter` criteria) without editing raw JSON.
+- **Table (`table`)**: embedded `<praxis-table-inline-authoring-editor>` with explicit column inheritance awareness. When `metadata.table.columns` is `[]` and the CRUD resolves columns dynamically from the bound resource schema (`effectiveTableConfig`), the editor surfaces an inheritance banner showing the resolved resource columns, forwards those columns into the inline table editor for direct inspection/customization, preserves `columns: []` when only toolbar or pagination settings change, and provides a one-click reset back to inherited resource columns after customization.
+
 Use this authoring surface to edit CRUD orchestration metadata. Do not build local CRUD editors in consuming apps when the needed behavior belongs to the package contract.
 
 ## AI Authoring
@@ -352,6 +415,8 @@ Use this authoring surface to edit CRUD orchestration metadata. Do not build loc
 
 - `resource.bind`
 - `list.surface.configure`
+- `list.kpiBand.configure`
+- `list.filterBar.configure`
 - `surface.create.configure`
 - `surface.edit.configure`
 - `surface.view.configure`
@@ -367,9 +432,10 @@ The manifest owns CRUD orchestration only. It delegates table, form, field, and
 Main exports:
 
 - `PraxisCrudComponent`
+- `PraxisBulkOperationDialogComponent`, `PraxisBulkEditDialogComponent`
 - `CrudLauncherService`
 - `DynamicFormDialogHostComponent`
-- `CrudMetadata`, `CrudActionFormContract`, `CrudDefaults`, `CrudParamMapping`
+- `CrudMetadata`, `CrudActionFormContract`, `CrudDefaults`, `CrudParamMapping`, `CrudKpiBandConfig`, `CrudKpiCardConfig`, `CrudKpiCardVariant`, `CrudFilterBarConfig`, `CrudFilterBarQuickFilter`
 - `DialogService`
 - `CrudPageHeaderComponent`
 - `CrudMetadataEditorComponent`