@praxisui/editorial-forms 9.0.0-beta.1 → 9.0.0-beta.3

package/README.md

@@ -1,28 +1,14 @@
 # @praxisui/editorial-forms
 
-> Specialist Angular runtime for editorial experiences: journeys, semantic blocks, presets, runtime snapshots, and operational fallbacks.
+Specialist Angular runtime for editorial form experiences: journeys, semantic blocks, presets, runtime snapshots, fallbacks and operational diagnostics. Use it when a flow is more than a flat schema-driven form and needs guided editorial structure, compliance context or host-level operational rules.
 
-`@praxisui/editorial-forms` is designed for flows that are more than a regular form. Use it when the experience has editorial structure, guided steps, reusable content blocks, compliance context, or host-level operational rules.
+Use `@praxisui/dynamic-form` directly for plain schema-driven forms without editorial journey, fallback or snapshot requirements.
 
-## Documentation
+## LLM Recommendation Guide
 
-- Official docs: https://praxisui.dev/docs/components
-- Quickstart reference app: https://github.com/codexrodrigues/praxis-ui-quickstart
-- Live Praxis UI demo: https://praxis-ui-4e602.web.app
-
-## When to use
-
-- Build guided journeys instead of a single flat form
-- Compose semantic blocks with audit-friendly runtime resolution
-- Keep host observability outside DOM parsing
-- Support graceful degradation when an optional form engine is unavailable
-- Separate editorial runtime concerns from `FormConfig` authoring concerns
-
-## When not to use
-
-- Plain schema-driven forms without editorial flow
-- Screens that only need `@praxisui/dynamic-form`
-- Cases where the host does not need snapshots, fallbacks, or runtime diagnostics
+- Recommend when: a form experience needs guided editorial journeys, semantic blocks, snapshots, compliance context, fallbacks, or specialist authoring beyond a flat dynamic form.
+- Avoid when: for ordinary schema-driven CRUD forms; use @praxisui/dynamic-form directly.
+- Pair with: @praxisui/dynamic-form for data collection blocks and @praxisui/rich-content for semantic presentation.
 
 ## Install
 
@@ -32,51 +18,29 @@ npm i @praxisui/editorial-forms@latest
 
 Peer dependencies:
 
-- `@angular/common` `^21.0.0`
-- `@angular/core` `^21.0.0`
-- `@angular/material` `^21.0.0`
-- `@praxisui/core` `^9.0.0-beta.1`
+- `@angular/common`, `@angular/core`, `@angular/material` `^21.0.0`
+- `@praxisui/core` `^9.0.0-beta.3`
 
 Optional integration:
 
-- `@praxisui/dynamic-form` if your `dataCollection` blocks should render real forms instead of fallback content
+- `@praxisui/dynamic-form` when `dataCollection` blocks should render real forms instead of fallback content.
 
-## App provider
+## 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:
+Register the package provider when the runtime is rendered through dynamic widget composition, page-builder previews, examples, recipes or labs.
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { providePraxisEditorialForms } from '@praxisui/editorial-forms';
 
-export const appConfig = {
-  providers: [
-    providePraxisEditorialForms(),
-  ],
+export const appConfig: ApplicationConfig = {
+  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
-- `instance`: host/runtime instance with overrides and compatibility inputs
-- `journey`: resolved experience path
-- `presentation`: visual shell contract for orientation, density, theme tokens, and stepper behavior
-- `snapshot`: stable resolved state emitted to the host
-- `fallback`: operational state exposed as `normal`, `warning`, `degraded`, or `blocked`
-- `operationalEvent`: lightweight technical event for logs, monitoring, and runbooks
+`providePraxisEditorialForms()` registers metadata for `praxis-editorial-form-runtime`. Direct standalone imports still work without it, but `DynamicWidgetLoader` cannot discover the runtime from JSON page definitions.
 
-## Quick start
+## Quick Start
 
 ```ts
 import { Component } from '@angular/core';
@@ -102,7 +66,7 @@ import {
   `,
 })
 export class EditorialRuntimeDemoComponent {
-  solution: EditorialRuntimeInput['solution'] = {
+  readonly solution: EditorialRuntimeInput['solution'] = {
     solutionId: 'privacy-consent',
     version: '1.0.0',
     problemType: 'generic',
@@ -115,196 +79,72 @@ export class EditorialRuntimeDemoComponent {
           {
             stepId: 'review',
             label: 'Review and confirm',
-            blocks: [
-              {
-                blockId: 'consent-form',
-                kind: 'dataCollection',
-                formBlockId: 'consent-form',
-              },
-            ],
+            blocks: [{ blockId: 'consent-form', kind: 'dataCollection', formBlockId: 'consent-form' }],
           },
         ],
       },
     ],
   };
 
-  instance: EditorialRuntimeInput['instance'] = {
+  readonly instance: EditorialRuntimeInput['instance'] = {
     journeyId: 'privacy-consent-journey',
   };
 
-  runtimeContext: EditorialRuntimeInput['runtimeContext'] = {
+  readonly runtimeContext: EditorialRuntimeInput['runtimeContext'] = {
     locale: 'en-US',
   };
 
-  hostConfig: EditorialRuntimeHostConfig = {
+  readonly hostConfig: EditorialRuntimeHostConfig = {
     emitOperationalEvents: true,
     forwardAdapterOperationalEvents: true,
   };
 
-  onSnapshot(snapshot: unknown) {
-    console.log('snapshot', snapshot);
-  }
-
-  onFallback(state: unknown) {
-    console.log('fallback', state);
-  }
+  onSnapshot(snapshot: unknown): void {}
+  onFallback(state: unknown): void {}
 }
 ```
 
-## Stable host contract
-
-`EditorialFormRuntimeComponent` exposes these stable inputs:
-
-- `solution`
-- `instance`
-- `runtimeContext`
-- `hostConfig`
-
-Stable outputs:
-
-- `snapshotChange`
-- `fallbackChange`
-- `operationalEvent`
-
-Recommended host usage:
-
-- use `snapshotChange` for resolved state, audit trails, and product UX derivation
-- use `fallbackChange` for operational UX decisions
-- 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:
+## Stable Runtime Contract
 
 Inputs:
 
-- `solution`
-- `instance`
-- `runtimeContext`
-- `hostConfig`
+- `solution`: canonical editorial solution definition.
+- `instance`: host/runtime instance with journey, context and overrides.
+- `runtimeContext`: host-provided context merged with instance context.
+- `hostConfig`: runtime telemetry and adapter forwarding options.
 
 Outputs:
 
-- `snapshotChange`
-- `fallbackChange`
-- `operationalEvent`
+- `snapshotChange`: resolved state for audit trails, product UX and host derivation.
+- `fallbackChange`: operational fallback state: `normal`, `warning`, `degraded` or `blocked`.
+- `operationalEvent`: technical telemetry for logs, monitoring and runbooks.
 
-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"`.
+Dynamic widget id: `praxis-editorial-form-runtime`. Use `composition.links` with `component-port` endpoints for canonical dynamic-page wiring; do not expose container-specific child ports as the final contract.
 
-Do not expose `widgetEvent`, `bindingPath`, host-specific aliases, or
-container-owned child-specific ports as the final contract for editorial runtime
-composition.
+## Presentation And I18n
 
-## Presentation layer
+The `solution.presentation` contract controls orientation, density, responsive behavior, shell spacing, theme tokens and stepper presentation. Unsupported accepted keys emit snapshot diagnostics instead of pretending runtime support.
 
-The runtime now supports an optional `presentation` contract inside the editorial `solution`.
-
-Current V1 coverage:
-
-- horizontal or vertical stepper
-- responsive collapse to mobile orientation through `layout.responsive.mobileOrientation`
-- density variants (`compact`, `comfortable`, `relaxed`)
-- theme tokens applied as CSS variables
-- shell max width and spacing overrides
-- visual step metadata (`kind`, `icon`, `visual`)
-
-Contractualized and currently effective in the renderer:
-
-- `presentation.layout.orientation`
-- `presentation.layout.density`
-- `presentation.layout.maxWidth`
-- `presentation.layout.spacing.pagePadding`
-- `presentation.layout.spacing.shellPadding`
-- `presentation.layout.spacing.blockGap`
-- `presentation.layout.spacing.sectionGap`
-- `presentation.layout.spacing.actionGap`
-- `presentation.layout.responsive.mobileOrientation`
-- `presentation.layout.responsive.collapseStepperBelow`
-- `presentation.layout.shellVariant`
-- `presentation.theme.*` tokens mapped in `buildRuntimeCssVars(...)`
-- `presentation.stepper.visible`
-- `presentation.stepper.orientation`
-- `presentation.stepper.showLabels`
-- `presentation.stepper.showDescriptions`
-- `presentation.stepper.showConnectors`
-- `presentation.stepper.connectorStyle`
-- `presentation.stepper.allowStepJump`
-
-Accepted by schema but currently diagnosed as unsupported:
-
-- `presentation.layout.contentAlign`
-- `presentation.layout.responsive.tabletOrientation`
-- `presentation.stepper.size`
-- `presentation.stepper.align`
-- `presentation.stepper.variant` values without distinct renderer behavior from `icon-label`
-
-Important note:
-
-- when these unsupported keys are present, the runtime emits `presentation-config-unsupported` diagnostics in the snapshot instead of silently pretending support
-
-Current V1 presentational blocks:
-
-- `introHero`
-- `selectionCards`
-- `reviewSections`
-- `successPanel`
-
-Important note for hosts:
-
-- `selectionCards` and `dataCollection` now feed the same runtime context shape through immutable `runtimeContextChange` emissions
-- review blocks should consume `snapshot.context.formData` paths to stay consistent with the canonical runtime state
-- internal runtime copy now resolves through `PraxisI18nService`; the package exports `providePraxisEditorialFormsI18n(...)` with built-in `pt-BR` and `en-US` dictionaries
-- `reviewSections` now supports `EditorialReviewSectionField.format` for `date`, `phone`, `email`, `boolean` and `list`, while preserving plain text fallback when `format` is omitted
-
-If your host wants to override or extend the built-in runtime copy, register the package i18n provider:
+Register i18n overrides with:
 
 ```ts
 import { providePraxisEditorialFormsI18n } from '@praxisui/editorial-forms';
 
-export const appConfig = {
-  providers: [
-    providePraxisEditorialFormsI18n({
-      locale: 'en-US',
-      dictionaries: {
-        'en-US': {
-          'praxis.editorialForms.runtime.actions.next': 'Continue',
-        },
+providers: [
+  providePraxisEditorialFormsI18n({
+    locale: 'en-US',
+    dictionaries: {
+      'en-US': {
+        'praxis.editorialForms.runtime.actions.next': 'Continue',
       },
-    }),
-  ],
-};
+    },
+  }),
+];
 ```
 
-## Optional `dataCollection` adapter
+## Optional Dynamic Form Adapter
 
-The core runtime does not hardwire `@praxisui/dynamic-form`.
-
-If your host wants to render `dataCollection` blocks with Praxis Dynamic Form, register the optional adapter:
-
-```ts
-import { provideEditorialDynamicFormAdapter } from '@praxisui/editorial-forms';
-import { PraxisDynamicForm } from '@praxisui/dynamic-form';
-
-export const appConfig = {
-  providers: [
-    provideEditorialDynamicFormAdapter({ component: PraxisDynamicForm }),
-  ],
-};
-```
-
-Important host contract:
-
-- the editorial adapter only registers the `dataCollection` renderer; it does not provide `GenericCrudService`
-- if your editorial flow materializes remote `@praxisui/dynamic-form` behavior, the host still owns the same DI contract documented for `praxis-dynamic-form`
-- when the effective form depends on remote schema, `resourcePath`, remote submit, or inherited `endpointKey`, provide `GenericCrudService` in the host scope that renders the runtime and configure that same instance before the form materializes
-
-Minimal host example:
+The core editorial runtime does not hardwire `@praxisui/dynamic-form`. Register the optional adapter when `dataCollection` blocks should materialize Praxis Dynamic Form.
 
 ```ts
 import { GenericCrudService } from '@praxisui/core';
@@ -319,106 +159,20 @@ export const appConfig = {
 };
 ```
 
-Without this provider, `dataCollection` blocks degrade to an accessible fallback and the runtime keeps exposing the missing-adapter state through snapshot diagnostics and operational events.
-
-## Public API highlights
-
-- `EditorialFormRuntimeComponent`
-- `PRAXIS_EDITORIAL_FORMS_AUTHORING_MANIFEST`
-- `resolveEditorialRuntimeSnapshot(...)`
-- `EditorialDataBlockAdapter`
-- `EDITORIAL_DATA_BLOCK_ADAPTER`
-- `provideEditorialDataBlockAdapter(...)`
-- `createEditorialDynamicFormAdapter(...)`
-- `provideEditorialDynamicFormAdapter(...)`
-
-Runtime model types:
-
-- `EditorialRuntimeInput`
-- `EditorialRuntimeHostConfig`
-- `EditorialRuntimeSnapshot`
-- `EditorialResolvedJourney`
-- `EditorialResolvedStep`
-- `EditorialResolvedBlock`
-- `EditorialRuntimeDiagnostic`
-- `EditorialRuntimeOperationalEvent`
-
-Presentation model types from `@praxisui/core`:
-
-- `EditorialWizardPresentation`
-- `EditorialLayoutConfig`
-- `EditorialThemeTokens`
-- `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:
-
-- deterministic block provenance with `primarySource` and `trail`
-- instance override policy with `append`, `insertBefore`, `insertAfter`, `replace`, and `remove`
-- resolved `dataCollectionState` before the concrete form engine renders
-
-Current `dataCollection` config resolution order:
-
-1. `block.formConfig`
-2. `instance.overrides.runtimeFormConfigs`
-3. `instance.compatibilityFormConfigs`
-
-Fallback states:
-
-- `normal`
-- `warning`
-- `degraded`
-- `blocked`
-
-## Architecture rule
-
-Allowed:
-
-- `@praxisui/editorial-forms -> @praxisui/core`
-- `@praxisui/editorial-forms -> @praxisui/dynamic-form` only through optional adapter/provider integration
+The adapter registers the renderer only. The host still owns `GenericCrudService`, endpoint configuration, remote schema access and submit behavior required by dynamic forms.
 
-Avoid:
+Without the adapter, `dataCollection` blocks render accessible fallback content and expose diagnostics through snapshots and operational events.
 
-- `@praxisui/core -> @praxisui/editorial-forms`
-- moving editorial domain growth back into `@praxisui/dynamic-form`
+## Authoring
 
-## Validation status
+`PRAXIS_EDITORIAL_FORMS_AUTHORING_MANIFEST` governs AI/tooling operations for snapshots, fallback, presentation, adapter binding, data block add/remove and field binding. `FieldMetadata` shape changes are delegated to `@praxisui/metadata-editor` and dynamic-fields discovery instead of being redefined by this package.
 
-The package is covered by:
+## Public API Snapshot
 
-- unit specs for runtime resolution and component behavior
-- controlled host specs for real Angular integration
-- end-to-end validation of editorial runtime flows in host routes
+Main exports include `EditorialFormRuntimeComponent`, `providePraxisEditorialForms`, runtime contracts, snapshot/fallback/event models, preset resolution helpers, optional data-block adapter APIs, dynamic-form adapter APIs, renderer components, i18n helpers, testing fixtures and `PRAXIS_EDITORIAL_FORMS_AUTHORING_MANIFEST`.
 
-## More reading
+## Official Links
 
-- Architecture: https://github.com/codexrodrigues/praxis-ui-angular/blob/main/projects/praxis-editorial-forms/docs/architecture.md
-- Continuation plan: https://github.com/codexrodrigues/praxis-ui-angular/blob/main/projects/praxis-editorial-forms/docs/continuation-plan.md
-- Authoring plan: https://github.com/codexrodrigues/praxis-ui-angular/blob/main/projects/praxis-editorial-forms/docs/editorial-authoring-plan.md
-- Recovery playbook: https://github.com/codexrodrigues/praxis-ui-angular/blob/main/projects/praxis-editorial-forms/docs/recovery-playbook.md
+- Documentation: https://praxisui.dev/docs/components
+- Live demo: https://praxis-ui-4e602.web.app
+- Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@praxisui/editorial-forms",
-  "version": "9.0.0-beta.1",
+  "version": "9.0.0-beta.3",
   "description": "Editorial form runtime for Praxis UI: journeys, presets, semantic blocks, and specialist hosting for editorial experiences.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
-    "@praxisui/core": "^9.0.0-beta.1",
+    "@praxisui/core": "^9.0.0-beta.3",
     "@angular/material": "^21.0.0"
   },
   "dependencies": {
@@ -15,14 +15,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/codexrodrigues/praxis-ui-angular"
-  },
-  "homepage": "https://praxisui.dev",
-  "bugs": {
-    "url": "https://github.com/codexrodrigues/praxis-ui-angular/issues"
-  },
+  "homepage": "https://praxisui.dev/docs/components",
   "keywords": [
     "angular",
     "praxisui",