@praxisui/editorial-forms 8.0.0-beta.7 → 8.0.0-beta.71

package/README.md

@@ -40,6 +40,31 @@ Optional integration:
 
 - `@praxisui/dynamic-form` if your `dataCollection` blocks should render real forms instead of fallback content
 
+## App provider
+
+Register the package provider in hosts that render the runtime through dynamic
+widget composition, including `@praxisui/core` dynamic pages, page-builder
+previews, examples, recipes and labs:
+
+```ts
+import { providePraxisEditorialForms } from '@praxisui/editorial-forms';
+
+export const appConfig = {
+  providers: [
+    providePraxisEditorialForms(),
+  ],
+};
+```
+
+`providePraxisEditorialForms()` registers the package dynamic widget metadata for
+`praxis-editorial-form-runtime`. It does not register the optional
+`@praxisui/dynamic-form` adapter and does not create a global singleton runtime
+graph.
+
+Without this provider, hosts may still use `EditorialFormRuntimeComponent`
+directly through a standalone import, but `DynamicWidgetLoader` cannot discover
+`praxis-editorial-form-runtime` from a JSON page definition.
+
 ## Core concepts
 
 - `solution`: canonical editorial definition
@@ -78,18 +103,21 @@ import {
 export class EditorialRuntimeDemoComponent {
   solution: EditorialRuntimeInput['solution'] = {
     solutionId: 'privacy-consent',
+    version: '1.0.0',
+    problemType: 'generic',
+    title: 'Privacy consent',
     journeys: [
       {
-        id: 'privacy-consent-journey',
-        title: 'Privacy consent',
+        journeyId: 'privacy-consent-journey',
+        label: 'Privacy consent',
         steps: [
           {
-            id: 'review',
-            title: 'Review and confirm',
+            stepId: 'review',
+            label: 'Review and confirm',
             blocks: [
               {
-                id: 'consent-form',
-                type: 'dataCollection',
+                blockId: 'consent-form',
+                kind: 'dataCollection',
                 formBlockId: 'consent-form',
               },
             ],
@@ -144,6 +172,34 @@ Recommended host usage:
 - use `operationalEvent` for technical telemetry, not as primary user-facing UI content
 - keep `runtimeContext` immutable from the host side; the runtime now emits refreshed state as blocks and adapters materialize `formData`
 
+## Dynamic widget composition
+
+The runtime publishes `praxis-editorial-form-runtime` as dynamic widget metadata
+with these canonical component ports:
+
+Inputs:
+
+- `solution`
+- `instance`
+- `runtimeContext`
+- `hostConfig`
+
+Outputs:
+
+- `snapshotChange`
+- `fallbackChange`
+- `operationalEvent`
+
+Nested dynamic page links must target these ports through
+`composition.links` using `component-port` endpoints. When the editorial runtime
+is nested inside a container such as Tabs or Expansion, persist the nested child
+identity through `nestedPath` and keep the terminal segment as a widget segment
+with stable `key` and `componentType: "praxis-editorial-form-runtime"`.
+
+Do not expose `widgetEvent`, `bindingPath`, host-specific aliases, or
+container-owned child-specific ports as the final contract for editorial runtime
+composition.
+
 ## Presentation layer
 
 The runtime now supports an optional `presentation` contract inside the editorial `solution`.
@@ -267,6 +323,7 @@ Without this provider, `dataCollection` blocks degrade to an accessible fallback
 ## Public API highlights
 
 - `EditorialFormRuntimeComponent`
+- `PRAXIS_EDITORIAL_FORMS_AUTHORING_MANIFEST`
 - `resolveEditorialRuntimeSnapshot(...)`
 - `EditorialDataBlockAdapter`
 - `EDITORIAL_DATA_BLOCK_ADAPTER`
@@ -293,6 +350,30 @@ Presentation model types from `@praxisui/core`:
 - `EditorialStepperConfig`
 - `EditorialStepVisualConfig`
 
+## Agentic authoring contract
+
+`PRAXIS_EDITORIAL_FORMS_AUTHORING_MANIFEST` is the executable AI authoring contract for this package.
+
+The manifest governs editorial document orchestration:
+
+- `snapshot.set`
+- `fallback.configure`
+- `presentation.configure`
+- `adapter.bind`
+- `dataBlock.add`
+- `dataBlock.remove`
+- `fieldBinding.set`
+
+Boundary rules:
+
+- `solution`, `instance` and `runtimeContext` resolve into `EditorialRuntimeSnapshot` without hidden drift
+- `fallback` must be explicit and backed by diagnostics
+- `presentation` only changes `solution.presentation`; it must not mutate domain data
+- `dataCollection` blocks require a registered adapter that supports the requested context
+- `dataBlock` authoring uses canonical `blockId` and `kind`; `id` and `type` are not accepted aliases
+- `snapshot.set` updates canonical runtime inputs (`solution`, `instance.context`, and `runtimeContext`) and does not persist active journey state as `instance.journeyId`
+- `FieldMetadata` shape changes are delegated to `@praxisui/metadata-editor` and dynamic-fields discovery instead of being redefined here
+
 ## Resolution and fallback behavior
 
 The resolved snapshot formalizes: