# @praxisui/editorial-forms

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.

Use `@praxisui/dynamic-form` directly for plain schema-driven forms without editorial journey, fallback or snapshot requirements.

## LLM Recommendation Guide

- 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

```bash
npm i @praxisui/editorial-forms@rc
```

Peer dependencies:

- `@angular/common`, `@angular/core`, `@angular/material` `^21.0.0`
- `@praxisui/core` `^9.0.0-beta.12`

Optional integration:

- `@praxisui/dynamic-form` when `dataCollection` blocks should render real forms instead of fallback content.

## App Provider

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: ApplicationConfig = {
  providers: [providePraxisEditorialForms()],
};
```

`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

```ts
import { Component } from '@angular/core';
import {
  EditorialFormRuntimeComponent,
  type EditorialRuntimeHostConfig,
  type EditorialRuntimeInput,
} from '@praxisui/editorial-forms';

@Component({
  selector: 'app-editorial-runtime-demo',
  standalone: true,
  imports: [EditorialFormRuntimeComponent],
  template: `
    <praxis-editorial-form-runtime
      [solution]="solution"
      [instance]="instance"
      [runtimeContext]="runtimeContext"
      [hostConfig]="hostConfig"
      (snapshotChange)="onSnapshot($event)"
      (fallbackChange)="onFallback($event)"
    />
  `,
})
export class EditorialRuntimeDemoComponent {
  readonly solution: EditorialRuntimeInput['solution'] = {
    solutionId: 'privacy-consent',
    version: '1.0.0',
    problemType: 'generic',
    title: 'Privacy consent',
    journeys: [
      {
        journeyId: 'privacy-consent-journey',
        label: 'Privacy consent',
        steps: [
          {
            stepId: 'review',
            label: 'Review and confirm',
            blocks: [{ blockId: 'consent-form', kind: 'dataCollection', formBlockId: 'consent-form' }],
          },
        ],
      },
    ],
  };

  readonly instance: EditorialRuntimeInput['instance'] = {
    journeyId: 'privacy-consent-journey',
  };

  readonly runtimeContext: EditorialRuntimeInput['runtimeContext'] = {
    locale: 'en-US',
  };

  readonly hostConfig: EditorialRuntimeHostConfig = {
    emitOperationalEvents: true,
    forwardAdapterOperationalEvents: true,
  };

  onSnapshot(snapshot: unknown): void {}
  onFallback(state: unknown): void {}
}
```

## Stable Runtime Contract

Inputs:

- `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`: 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.

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.

## Presentation And I18n

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.

Register i18n overrides with:

```ts
import { providePraxisEditorialFormsI18n } from '@praxisui/editorial-forms';

providers: [
  providePraxisEditorialFormsI18n({
    locale: 'en-US',
    dictionaries: {
      'en-US': {
        'praxis.editorialForms.runtime.actions.next': 'Continue',
      },
    },
  }),
];
```

## Optional Dynamic Form Adapter

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';
import { provideEditorialDynamicFormAdapter } from '@praxisui/editorial-forms';
import { PraxisDynamicForm } from '@praxisui/dynamic-form';

export const appConfig = {
  providers: [
    GenericCrudService,
    provideEditorialDynamicFormAdapter({ component: PraxisDynamicForm }),
  ],
};
```

The adapter registers the renderer only. The host still owns `GenericCrudService`, endpoint configuration, remote schema access and submit behavior required by dynamic forms.

Without the adapter, `dataCollection` blocks render accessible fallback content and expose diagnostics through snapshots and operational events.

## Authoring

`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.

## Public API Snapshot

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`.

## Official Links

- Documentation: https://praxisui.dev/docs/components
- Live demo: https://praxis-ui-4e602.web.app
- Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart