@praxisui/core 9.0.68-rc.3 → 10.0.0-rc.10

package/README.md

@@ -4,6 +4,80 @@ Shared contracts, tokens, services, metadata models, widget runtime primitives,
 
 Use this package directly when a host application or library needs Praxis UI types, global actions, metadata registries, schema clients, resource discovery, i18n, theme bridge, dynamic widget contracts, or shared runtime services.
 
+## Governed bulk client: basic synchronous slice
+
+`BulkOperationClientService` consumes the Metadata published `BulkExecutionContract`
+from an action or CRUD capability. `discoverAction` and `discoverCapability` use the
+existing resource discovery surface; operation paths and filtered schema URLs come
+from that descriptor. `evaluationSchema` loads the backend's filtered request schema
+for a caller to render the operation's form. The client admits only `SYNC`,
+`EXPLICIT` and `PER_ITEM` in this first Angular slice. A descriptor that also
+advertises query selection is usable only with an explicit target request here.
+
+The Quickstart candidate migrates its existing uniform update operation to an
+`ASYNC`-only profile; that host adoption is still being validated. BASIC omits
+an `ASYNC`-only operation without a `SYNC` fallback. Angular ASYNC support needs
+its own consumer implementation and acceptance; this note does not establish a
+Render deployment or an ASYNC UI journey.
+
+Provide the exact wire ID and opaque resource `expectedVersion` for every selected
+target. In particular, int64/Long IDs remain decimal strings; do not convert them
+through JavaScript numbers. Evaluate first, review the returned READY or BLOCKED
+proposal and its authorized paged results, then confirm a READY proposal using
+only `{ proposalId }` and one `Idempotency-Key`. `BulkSyncStateService.createSession`
+keeps that key fixed across a retry of the same confirmation. A new intention gets
+a new session. The key and proposal live only in that session; it makes no claim
+of recovery across a page reload.
+
+For a selected collection row that publishes a `self` link,
+`readTargetVersion(row._links, wireId, identityPath, options)` reads that exact
+item, verifies its returned identity and returns the original strong quoted ETag
+as `expectedVersion`. It rejects absent/weak ETags, foreign origins and mismatched
+IDs. Callers should bound concurrent reads and cancel them when their resource
+context closes. A row value, schema ETag or locally inferred URL is not a resource
+version.
+
+```ts
+const contract = await firstValueFrom(bulkClient.discoverCapability(resourceResponse, operationId));
+const session = bulkState.createSession(contract);
+const proposal = await session.evaluate(explicitSyncRequest);
+const preview = await firstValueFrom(bulkClient.readProposalResults(contract, proposal.proposalId));
+// Present proposal and preview to the person; a BLOCKED proposal cannot be confirmed.
+
+// In a separate, explicit confirmation action for a READY proposal:
+await session.confirm(idempotencyKeyForThisIntent);
+// On an uncertain HTTP failure, retain this session and retry with the same key.
+// The host schedules further authorized readbacks for an accepted nonterminal execution.
+if (!session.isTerminal()) await session.refreshExecution();
+if (session.isTerminal()) {
+  const results = await session.readResults();
+}
+```
+
+`resourceResponse`, `operationId`, the explicit request and the key come from the
+caller's governed selection and form flow; the client resolves operation URLs from
+the descriptor. The caller controls when to read status again and presents each
+authorized page of results. This example is a service integration sketch, not a
+ready visual workflow or a deployment claim.
+
+The backend is the authority on proposal expiry. A client clock hint must not
+block a same-key replay after an uncertain confirmation; the backend may return
+409 or 410 and the host must explain that state without inventing a new intent.
+
+HTTP 202, `RUNNING`, `CANCEL_REQUESTED` and `RECONCILIATION_REQUIRED` are not
+business success. Read the authorized execution until its reconciled terminal
+state and use the paged result reader for each item outcome. Preserve backend
+errors (including 409, 410, 429 and 503) for the host's governed UX mapping;
+do not turn them into a new submission with a new key. The backend continues to
+own authorization, policy, identity, idempotency, limits and the domain transaction.
+The table library has a candidate visual path for a published CRUD
+`bulk-update` capability in `UNIFORM_UPDATE` mode. It uses this client and a
+separate review/confirmation surface; it does not add a second backend contract.
+The service also supports typed command and per-item requests, but that table
+surface does not advertise them. Query selection, ASYNC jobs and ATOMIC mode are
+outside this Angular slice. This is not a claim that the reference host or full
+backend B7 acceptance is complete.
+
 ## Governed color palettes
 
 `materializeGovernedPaletteEntries(palette, purposes)` returns `MaterializedGovernedColorToken[]`, pairing each original `entry` with its resolved `color`. It preserves distinct token IDs even when CSS references/colors match, applies purpose filtering, and resolves fallback dependencies against the complete palette. Use this projection for identified swatches; do not zip color arrays to entries or infer identity from color equality. `materializeGovernedPaletteColors` remains the string-only projection of the same resolver.
@@ -211,7 +285,37 @@ Peer dependencies:
 
 ## Theme And Icons
 
-Import the theme bridge after Angular Material and CDK overlay styles.
+### Canonical SCSS Theming (Recommended)
+
+Import the canonical theming mixins to bridge host design tokens (OKLCH, Material 3, Tailwind, etc.) to Praxis components:
+
+```scss
+@use "@angular/cdk/overlay-prebuilt.css";
+@use "@praxisui/core/theming" as praxis;
+
+// Option A: Bundle light theme, dark mode overrides, widget shell, and tooltip enhancements
+@include praxis.praxis-theme-bundle();
+
+// Option B: Granular configuration with custom design tokens
+:root {
+  @include praxis.define-praxis-theme((
+    'primary': var(--primary),
+    'surface': var(--card),
+    'border': var(--border)
+  ));
+}
+
+.dark {
+  @include praxis.praxis-dark-theme-overrides();
+}
+
+@include praxis.praxis-shell-styles();
+@include praxis.praxis-tooltip-styles();
+```
+
+### Static Theme Bridge (Legacy)
+
+For simple or static setups, you can still import the prebuilt CSS bridge directly:
 
 ```scss
 @import "@angular/cdk/overlay-prebuilt.css";
@@ -421,6 +525,20 @@ Hosts that maintain an authored source separately from runtime state should cons
 `pageChange` remains the compatibility stream for every canonical page update, including persistent
 runtime state; transient composition projections remain excluded from both outputs.
 
+With `autoPersist` enabled, pass a stable `pageIdentity` to scope the document and
+listen to `persistenceChange: WidgetPagePersistenceState` for `loading`, `saving`,
+`saved`, `resetting`, `idle` or `error`. `savedAt` is emitted only after the
+storage confirms a save. An empty `{ widgets: [] }` document is a valid customized
+page; absence of a stored document falls back to the host's page. The runtime
+serializes save and reset operations for the identity so each storage call uses
+the latest provider ETag. A 409/412 conflict blocks later writes until the host
+explicitly calls `reloadPersistedPage(defaultPage)`, which discards the current
+draft. `resetPersistedPage(defaultPage)` clears storage and applies the factory
+page only after acknowledgement. `persistCurrentPage(page?)` requests an
+explicit save or retries a recoverable save failure; callers can pass the exact
+authored snapshot they want saved. Completion without a storage value reports
+`errorKind: 'unacknowledged'` rather than claiming success.
+
 Pointer drag/resize in the canvas snapshots rendered CSS Grid track sizes and gutters at gesture
 start. Content-sized rows are not treated as uniformly sized `rowUnit` rows. Horizontal resize
 snaps to columns; vertical resize in `autoRows: 'content'` authors the item's independent
@@ -1034,3 +1152,30 @@ Nested shells isolate their material CSS properties: an outer thick/dashed borde
 blur does not become an inner widget's default. Intentional inheritance through
 `context.ui.shell.preset/presets` remains supported. This isolation does not remove
 the host's shared theme tokens.
+
+## App shell: host appearance
+
+`PraxisAppShellComponent` materializes the host theme for both the sidebar and
+header. The existing theme roles `--sidebar` (falling back to `--card`),
+`--surface-gradient` (falling back to `--card`), `--command-gradient`,
+`--sidebar-foreground`, `--sidebar-primary`, `--sidebar-accent`,
+`--sidebar-accent-foreground`, `--primary-deep`, `--primary-foreground`,
+`--accent`, `--secondary`, `--overlay`
+and `--shadow-panel` apply to the native chrome and brand icon. Navigation,
+loading and mobile behavior do not change when these colors change. Without host
+theme tokens, the brand uses a dark blue fallback with a white icon; custom host
+colors should always supply their corresponding foreground roles.
+
+Semantic badges use tinted surfaces with the host's foreground. Success,
+warning and info consume `--praxis-success`, `--praxis-warning` and
+`--praxis-info`; the established `--ready`/`--warning` variables and bounded
+fallbacks remain available. Error consumes `--destructive`. Hosts should use
+these existing roles rather than overriding private shell selectors. No new
+shell input, saved layout field or theme-specific component is required.
+
+<!-- praxis-npm-catalog-links:start -->
+## Official documentation and examples
+
+- [Canonical technical overview: Overview](https://praxisui.dev/docs/components/praxis-core)
+- [Praxis Angular public catalog](https://praxisui.dev/angular)
+<!-- praxis-npm-catalog-links:end -->

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-10T02:26:52.714Z",
+  "generatedAt": "2026-10-13T14:47:21.726Z",
   "packageName": "@praxisui/core",
-  "packageVersion": "9.0.68-rc.3",
+  "packageVersion": "10.0.0-rc.10",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 4,
@@ -530,6 +530,12 @@
           "required": false,
           "description": "Emitido quando a página canônica muda por authoring ou por estado runtime persistente; projeções transitórias permanecem somente no runtime."
         },
+        {
+          "name": "persistenceChange",
+          "type": "WidgetPagePersistenceState",
+          "required": false,
+          "description": "Estado da carga, gravação ou reset da página após resposta do storage, incluindo customized, savedAt e falhas de conflito ou ausência de confirmação."
+        },
         {
           "name": "pageAuthoringChange",
           "type": "WidgetPageDefinition",
@@ -1414,7 +1420,8 @@
           "valueKind": "enum",
           "allowedValues": [
             "block",
-            "swap"
+            "swap",
+            "push-down"
           ],
           "description": "Politica de colisao do canvas espacial."
         },
@@ -3085,9 +3092,9 @@
         {
           "chunkIndex": 0,
           "chunkKind": "summary",
-          "content": "Component ID: praxis-dynamic-page\nSelector: praxis-dynamic-page\nFriendly Name: Dynamic Page\nDescription: Página dinâmica com widgets e composition.links em layout responsivo, incluindo mediação runtime para rich-content hospedado.\nCategory: page\nLib/Package: @praxisui/core\nTags: widget, page, dynamic, layout\nInputs:\n  - page (WidgetPageDefinition)\n  - context (Record<string, any>)\n  - strictValidation (boolean)\n  - enableCustomization (boolean)\n  - authoringCapabilities (WidgetPageAuthoringCapabilities)\n  - showPageSettingsButton (boolean)\n  - shellEditorComponent (Type<any>)\n  - pageEditorComponent (Type<any>)\n  - autoPersist (boolean)\n  - pageIdentity (PageIdentity)\n  - componentInstanceId (string)\nOutputs:\n  - pageChange (WidgetPageDefinition)\n  - pageAuthoringChange (WidgetPageDefinition)\n  - widgetEvent (WidgetEventEnvelope)\n  - widgetDiagnosticsChange (Record<string, WidgetResolutionDiagnostic>)\n",
+          "content": "Component ID: praxis-dynamic-page\nSelector: praxis-dynamic-page\nFriendly Name: Dynamic Page\nDescription: Página dinâmica com widgets e composition.links em layout responsivo, incluindo mediação runtime para rich-content hospedado.\nCategory: page\nLib/Package: @praxisui/core\nTags: widget, page, dynamic, layout\nInputs:\n  - page (WidgetPageDefinition)\n  - context (Record<string, any>)\n  - strictValidation (boolean)\n  - enableCustomization (boolean)\n  - authoringCapabilities (WidgetPageAuthoringCapabilities)\n  - showPageSettingsButton (boolean)\n  - shellEditorComponent (Type<any>)\n  - pageEditorComponent (Type<any>)\n  - autoPersist (boolean)\n  - pageIdentity (PageIdentity)\n  - componentInstanceId (string)\nOutputs:\n  - pageChange (WidgetPageDefinition)\n  - persistenceChange (WidgetPagePersistenceState)\n  - pageAuthoringChange (WidgetPageDefinition)\n  - widgetEvent (WidgetEventEnvelope)\n  - widgetDiagnosticsChange (Record<string, WidgetResolutionDiagnostic>)\n",
           "sourcePointer": "projects/praxis-core/src/lib/widgets/dynamic-widget-page.metadata.ts",
-          "contentHash": "d3f9a1519379d733fb13af496aff99953cd5a37399555955cbf747457185c2e3",
+          "contentHash": "d16589daf72efcc199d385b1147bf0764f30a33343d9fe16486fdc2836a15d78",
           "sourceKind": "component_definition",
           "sourceId": "praxis-dynamic-page",
           "corpusVersion": "1.0.0"