@praxisui/dynamic-form 9.0.0-beta.0 → 9.0.0-beta.2

package/README.md

@@ -1,127 +1,65 @@
----
-title: "Dynamic Form"
-slug: "dynamic-form-overview"
-description: "Visao geral do @praxisui/dynamic-form com schema-driven UI, editor embutido, layout runtime e integracao orientada a contrato."
-doc_type: "reference"
-document_kind: "component-overview"
-component: "dynamic-form"
-category: "components"
-audience:
-  - "frontend"
-  - "host"
-  - "architect"
-level: "intermediate"
-status: "active"
-owner: "praxis-ui"
-tags:
-  - "dynamic-form"
-  - "schema-driven"
-  - "runtime"
-  - "layout"
-  - "config-editor"
-order: 30
-icon: "dynamic_form"
-toc: true
-sidebar: true
-search_boost: 1.0
-reading_time: 12
-estimated_setup_time: 20
-version: "1.0"
-related_docs:
-  - "dynamic-form-hot-metadata-updates"
-  - "praxis-dynamic-form-json-api"
-  - "host-integration-guide"
-  - "consumer-integration-quickstart"
-keywords:
-  - "FormConfig"
-  - "schema-driven"
-  - "layout editor"
-  - "settings integration"
-last_updated: "2026-04-12"
----
-
 # @praxisui/dynamic-form
 
-> Standalone dynamic form component with schema-driven UI, native field cascades, settings integration, and a built-in configuration editor.
-
-## Documentation
-
-- Official documentation: https://praxisui.dev
-- Quickstart reference app: https://github.com/codexrodrigues/praxis-ui-quickstart
-- Recommended for: schema-driven screens that need runtime forms, settings integration and contract-first metadata
+Schema-driven and metadata-driven form runtime for Praxis UI.
 
-## When to use
+Use this package to render `FormConfig` and `FieldMetadata`, connect forms to backend schema/submit endpoints, host visual configuration, and keep form layout, rules, actions, and submit payloads governed by shared Praxis contracts.
 
-- Build forms from metadata instead of hand-coding each screen
-- Keep runtime customization and layout governance inside the host application
-- Integrate with other `@praxisui/*` packages through shared contracts and settings flows
+## Official Links
 
-## Canonical submit contract
-
-When the host opens the form from backend `surfaces` or `actions`, the canonical runtime path is `schemaUrl + submitUrl + submitMethod`, and detached hosts may also pass `apiUrlEntry` when the current overlay does not inherit the route-scoped `API_URL`. The legacy `crud.create/update` fallback still exists only as transitional behavior for hosts that have not fully migrated to discovery-driven submit execution.
+- Documentation: https://praxisui.dev/docs/components
+- Live demo: https://praxis-ui-4e602.web.app
+- Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart
+- API quickstart: https://github.com/codexrodrigues/praxis-api-quickstart-public
+- Source: https://github.com/codexrodrigues/praxis-ui-angular/tree/main/projects/praxis-dynamic-form
+- Issues: https://github.com/codexrodrigues/praxis-ui-angular/issues
 
 ## Install
 
 ```bash
-npm i @praxisui/dynamic-form@beta
+npm i @praxisui/dynamic-form@latest
 ```
 
-Peer dependencies (Angular v20):
-- `@angular/core` `^20.0.0`
-- `@angular/common` `^20.0.0`
-- `@angular/cdk` `^20.0.0`
-- `@praxisui/core` `^9.0.0-beta.0`
-- `@praxisui/rich-content` `^9.0.0-beta.0`
-- `@praxisui/visual-builder` `^9.0.0-beta.0`
-- `@praxisui/settings-panel` `^9.0.0-beta.0`
-- `@praxisui/cron-builder` `^9.0.0-beta.0`
+Peer dependencies:
+
+- `@angular/common`, `@angular/core`, `@angular/forms`, `@angular/cdk`, `@angular/material`, `@angular/router` `^21.0.0`
+- `@praxisui/ai`, `@praxisui/core`, `@praxisui/dynamic-fields`, `@praxisui/metadata-editor`, `@praxisui/rich-content`, `@praxisui/settings-panel`, `@praxisui/visual-builder` `^9.0.0-beta.1`
+- `rxjs` `^7.8.0`
 
-## Quick Start
+## Minimum Local Runtime
 
-### 1) PraxisDynamicForm (standalone)
+Use a local `FormConfig` when the host already knows the sections and fields.
 
 ```ts
 import { Component } from '@angular/core';
+import { FormConfig } from '@praxisui/core';
 import { PraxisDynamicForm } from '@praxisui/dynamic-form';
-import type { FormConfig } from '@praxisui/core';
 
 @Component({
-  selector: 'app-form-demo',
   standalone: true,
+  selector: 'app-local-form',
   imports: [PraxisDynamicForm],
   template: `
     <praxis-dynamic-form
+      formId="employee-local-form"
+      mode="create"
       [config]="config"
-      [mode]="'create'"
-      [enableCustomization]="true"
-      (formSubmit)="onSubmit($event)"
-    ></praxis-dynamic-form>
+      (formSubmit)="save($event.formData)">
+    </praxis-dynamic-form>
   `,
 })
-export class FormDemoComponent {
+export class LocalFormComponent {
   config: FormConfig = {
     sections: [
       {
         id: 'main',
         title: 'Employee',
-        sectionHeader: {
-          mode: 'auto',
-          sourceField: 'employeePhoto',
-          initialsSourceField: 'fullName',
-          altField: 'fullName',
-        },
         rows: [
           {
             columns: [
               {
-                id: 'col-fullName',
-                items: [{ kind: 'field', id: 'field-fullName', fieldName: 'fullName' }],
-                fields: ['fullName'],
-              },
-              {
-                id: 'col-email',
-                items: [{ kind: 'field', id: 'field-email', fieldName: 'email' }],
-                fields: ['email'],
+                id: 'name-column',
+                items: [{ kind: 'field', id: 'name-field', fieldName: 'name' }],
+                fields: ['name'],
               },
             ],
           },
@@ -129,775 +67,160 @@ export class FormDemoComponent {
       },
     ],
     fieldMetadata: [
-      { name: 'employeePhoto', label: 'Photo', controlType: 'input' } as any,
-      { name: 'fullName', label: 'Full Name', controlType: 'input', required: true } as any,
-      { name: 'email', label: 'E-mail', controlType: 'email' } as any,
+      { name: 'name', label: 'Name', controlType: 'input', required: true },
     ],
   };
 
-  onSubmit(evt: any) {
-    console.log('Submitted:', evt);
-  }
+  save(payload: unknown): void {}
 }
 ```
 
-Tip: connect to a backend resource by setting `resourcePath`/`resourceId`. The component can fetch schemas and reconcile local layout with server metadata when `enableCustomization` is true.
-For metadata-driven surfaces published by the backend, prefer passing `schemaUrl`, `submitUrl` and `submitMethod` explicitly. In dialog/drawer hosts detached from the route injector, pass `apiUrlEntry` in addition to `apiEndpointKey` so relative runtime URLs still resolve against the remote backend instead of the local shell origin.
-When a late `config` hydration rebuilds the surface, the runtime preserves the current form values already mounted in memory only when the logical context remains the same (`resourcePath`, `resourceId`, and mode). If the form was preloaded from `resourceId`, that entity hydration remains visible after the rebuild only for the same entity context; entity switches and create-mode transitions do not restore the previous record snapshot.
-
-## Local fields, transient state, and submit payloads
-
-`praxis-dynamic-form` supports host-owned fields that participate in the form runtime without becoming part of the backend DTO. This is the right model for confirmation controls, wizard state, client-side calculated previews, host notes, and other UI context that should be available to rules and hooks but should not be persisted by default.
-
-The submit contract exposes two values:
-
-| Property | Meaning | Typical consumer |
-| --- | --- | --- |
-| `formSubmit.formData` | filtered persistence payload after submit policy is applied | HTTP submit, persistence hooks, backend DTO integration |
-| `formSubmit.rawFormData` | full form value before filtering | host hooks, UI audit context, diagnostics, calculations |
-
-Default behavior:
-
-- schema-backed fields are included in `formData`.
-- fields with `source: 'local'` are omitted from `formData` and kept in `rawFormData`.
-- fields with `transient: true` are omitted from `formData` and kept in `rawFormData`.
-- `submitPolicy` has priority over `source` and `transient`.
-
-| `submitPolicy` | Effect |
-| --- | --- |
-| `include` | always include the field in `formData` |
-| `omit` | always omit the field from `formData` |
-| `includeWhenDirty` | include the field in `formData` only when the control is dirty |
-
-Example:
-
-```ts
-fieldMetadata: [
-  { name: 'fullName', label: 'Full name', controlType: 'input' },
-  {
-    name: 'approvalComment',
-    label: 'Approval comment',
-    controlType: 'textarea',
-    source: 'local',
-    submitPolicy: 'omit',
-  },
-  {
-    name: 'calculatedRiskScore',
-    label: 'Risk score',
-    controlType: 'numericTextBox',
-    transient: true,
-    readOnly: true,
-  },
-  {
-    name: 'manualOverrideReason',
-    label: 'Manual override reason',
-    controlType: 'textarea',
-    source: 'local',
-    submitPolicy: 'includeWhenDirty',
-  },
-];
-```
+## Minimum Backend Runtime
 
-For a submitted value like:
+For schema-driven backend surfaces, prefer explicit `schemaUrl`, `submitUrl`, and `submitMethod`.
 
-```json
-{
-  "fullName": "Ana Souza",
-  "approvalComment": "Checked with HR",
-  "calculatedRiskScore": 72,
-  "manualOverrideReason": "Approved exception"
-}
-```
-
-`rawFormData` keeps all four values. `formData` keeps `fullName` and, when dirty, `manualOverrideReason`; it omits `approvalComment` and `calculatedRiskScore`.
-
-Do not use local/transient fields to hide a backend contract problem. If a field exists in the backend schema, keep it server-backed and fix the canonical schema or metadata mapping instead of creating a parallel local convention.
-
-Presentation/read-only note:
-- `praxis-dynamic-form` hospeda `FieldMetadata`, mas não é o resolvedor direto de `valuePresentation`.
-- quando campos entram em modo view/presentation, a semântica de apresentação vem do metadata do campo e é resolvida por `@praxisui/dynamic-fields`.
-
-## Canonical editorial resolution for field editors
-
-Para nome, descricao e icone do tipo de campo no configurador/layout editor e no titulo do metadata editor:
-
-- `@praxisui/dynamic-form` nao mantem mapa editorial local por `controlType`;
-- a resolucao canonica vem de `ComponentMetadataRegistry.resolveEditorial(..., { namespace: 'dynamicFields' })`;
-- aliases e normalizacao de `controlType` sao apenas ponte tecnica de lookup, nao fonte de copy;
-- quando nao existe descriptor canonico para aquele tipo, o fallback aceito e tecnico/neutro.
-
-Fronteira operacional:
-
-- package-owned fields de `@praxisui/dynamic-fields`: consomem descriptor editorial canonico da lib;
-- `ComponentDocMeta` desses fields e derivado, nao a origem semantica;
-- catalogo/showcase continua derivado;
-- custom types do host seguem suportados via `ComponentMetadataRegistry.register(ComponentDocMeta)`, sem exigir mapa local no form.
-
-### Canonical DI contract for hosts
-
-`praxis-dynamic-form` does not register `GenericCrudService` internally.
-When the runtime uses `resourcePath`, `resourceId`, schema fetch, CRUD submit, or custom endpoints, the host must provide the service in the effective host scope.
-
-Canonical rule:
-- `praxis-table` is self-hosted for `GenericCrudService`.
-- `praxis-dynamic-form` is host-driven for `GenericCrudService`.
-- If the host needs a specific `endpointKey` or pre-configuration, it must provide and configure the same `GenericCrudService` instance before rendering the form.
-
-Minimal host example:
-
-```ts
-import { Component } from '@angular/core';
-import { GenericCrudService } from '@praxisui/core';
-import { PraxisDynamicForm } from '@praxisui/dynamic-form';
-
-@Component({
-  selector: 'app-form-host',
-  standalone: true,
-  imports: [PraxisDynamicForm],
-  providers: [GenericCrudService],
-  template: `
-    <praxis-dynamic-form
-      [formId]="'employees-form'"
-      [resourcePath]="'employees'"
-      [mode]="'edit'"
-    ></praxis-dynamic-form>
-  `,
-})
-export class FormHostComponent {}
-```
-
-If the host must force a non-default API endpoint, configure the service in the same host scope:
-
-```ts
-import { Component } from '@angular/core';
-import { ApiEndpoint, GenericCrudService } from '@praxisui/core';
-import { PraxisDynamicForm } from '@praxisui/dynamic-form';
-
-@Component({
-  selector: 'app-form-host',
-  standalone: true,
-  imports: [PraxisDynamicForm],
-  providers: [GenericCrudService],
-  template: `
-    <praxis-dynamic-form
-      [formId]="'employees-form'"
-      [resourcePath]="'human-resources/employees'"
-      [mode]="'edit'"
-    ></praxis-dynamic-form>
-  `,
-})
-export class FormHostComponent {
-  constructor(private readonly crud: GenericCrudService<any>) {
-    this.crud.configure('human-resources/employees', ApiEndpoint.HumanResources);
-  }
-}
-```
-
-Without that provider, a standalone host can fail with `NG0201: No provider found for _GenericCrudService`.
-
-### 2) Config Editor component
-
-Use the standalone editor directly to edit and reconcile the form configuration.
-
-```ts
-import { Component } from '@angular/core';
-import { MatDialog } from '@angular/material/dialog';
-import { PraxisDynamicFormConfigEditor } from '@praxisui/dynamic-form';
-import type { FormConfig } from '@praxisui/core';
-
-@Component({
-  selector: 'app-form-editor-launcher',
-  standalone: true,
-  template: `<button (click)="openEditor()">Open Config Editor</button>`,
-})
-export class FormEditorLauncherComponent {
-  constructor(private dialog: MatDialog) {}
-
-  openEditor() {
-    const initial: FormConfig = { sections: [] } as any;
-    this.dialog.open(PraxisDynamicFormConfigEditor, {
-      width: '1024px',
-      data: { formConfig: initial, formId: 'employees-form', mode: 'edit' },
-    });
-  }
-}
+```html
+<praxis-dynamic-form
+  formId="employee-edit"
+  mode="edit"
+  resourcePath="/api/employees"
+  [resourceId]="employeeId"
+  schemaUrl="/api/employees/schemas/edit"
+  readUrl="/api/employees/42"
+  submitUrl="/api/employees/42"
+  submitMethod="PUT"
+  (formSubmit)="onSubmitted($event)">
+</praxis-dynamic-form>
 ```
 
-Alternatively, when `enableCustomization` is true, `praxis-dynamic-form` renders a gear button that opens the editor internally.
-
-## Agentic Authoring & Manifest
+`resourcePath` can connect the form to backend discovery, but it is not the only or always preferred minimum. Detached dialog/drawer hosts may also need `apiEndpointKey` or `apiUrlEntry` so relative runtime URLs resolve against the intended backend.
 
-`praxis-dynamic-form` supports executable authoring contracts through the `ComponentAuthoringManifest`. This allows AI agents to perform structured, safe, and deterministic edits to the form configuration.
+When using resource, schema, read, or submit flows, the host must provide the effective API/CRUD service wiring for that scope.
 
-- **Manifest:** `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST`
-- **Editable targets:** `field`, `section`, `row`, `column`, `visualBlock`, `formAction`, `formRule`, `message`, `layoutPlacement`, `localField`, `schemaBackedField`.
-- **Operations:** Covers field property updates, local field lifecycle, layout item manipulation, visual block authoring, rule management, and action configuration declared in `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST`.
-- **Validation:** Deterministic validators cover ID uniqueness, layout integrity, rich content document validity, local/schema-backed separation, destructive confirmation, and editor round-trip preservation.
-- **Examples/evals:** Fixtures cover local transient fields, schema-backed relabeling, layout moves, visual block add/move, visibility rules, unknown target rejection, destructive confirmation, and save/reopen without drift.
-- **Round-trip:** Preserves editor state and ensures that AI-generated patches are compatible with the visual editor.
+## Runtime Inputs And Outputs
 
-For more details on authoring manifests, see `docs/ai/agentic-authoring/component-authoring-contracts/README.md`.
+Common inputs:
 
-## API Surface
+- `config`, `formId`, `componentInstanceId`
+- `mode`: `create | edit | view`
+- `resourcePath`, `resourceId`, `initialValue`
+- `schemaUrl`, `readUrl`, `submitUrl`, `submitMethod`, `responseSchemaUrl`
+- `apiEndpointKey`, `apiUrlEntry`
+- `actions`, `layout`, `backConfig`, `hooks`
+- `enableCustomization`
+- `readonlyModeGlobal`, `disabledModeGlobal`, `presentationModeGlobal`, `visibleGlobal`
+- `notifyIfOutdated`, `snoozeMs`, `autoOpenSettingsOnOutdated`
+- `domainRules`
+- `editorialContext`
 
-- Components: `PraxisDynamicForm`, `PraxisDynamicFormConfigEditor`, `JsonConfigEditorComponent`, `LayoutEditorComponent`
-- Services: `FormConfigService`, `FormLayoutService`, `DynamicFormLayoutService`, `FormContextService`
-- Utilities: form rule converters, normalize date arrays, **FormRulesService** (aplica regras de propriedades)
-- Metadata helpers: `providePraxisDynamicFormMetadata`
+Common outputs:
 
-## Editorial Hosting (Foundation)
+- `formSubmit`, `formCancel`, `formReset`
+- `formReady`, `valueChange`
+- `configChange`, `configPatchChange`
+- `syncCompleted`, `schemaStatusChange`
+- `loadingStateChange`, `initializationError`
+- `customAction`, `actionConfirmation`
+- `fieldRenderError`, `ruleDiagnosticsChange`
 
-O `@praxisui/dynamic-form` agora aceita uma surface fundacional para hospedar blocos editoriais ao redor do formulario, sem misturar esses blocos com `fieldMetadata` nem com `formData`.
+## Submit Contract
 
-Inputs relevantes:
-- `config.formBlocksBefore?: RichContentDocument | null`
-- `config.formBlocksBeforeActions?: RichContentDocument | null`
-- `config.formBlocksAfter?: RichContentDocument | null`
-- `config.editorialContext?: Record<string, unknown>`
-- `[editorialContext]?: Record<string, unknown>`
+`formSubmit` exposes both persistence data and full UI state:
 
-Precedencia de contexto editorial:
-1. runtime base do form
-2. `config.editorialContext`
-3. input host `[editorialContext]`
+- `formData`: filtered backend payload after submit policies are applied
+- `rawFormData`: complete form value bag, including UI-only values
 
-As camadas posteriores sobrescrevem as anteriores.
-
-Exemplo minimo:
+Host-owned fields that should participate in UI state but not be persisted by default belong in `FormConfig.fieldMetadata` with `source: 'local'` or `transient: true`.
 
 ```ts
-import type { FormConfig } from '@praxisui/core';
-
-const formConfig: FormConfig = {
-  editorialContext: {
-    accountName: 'Helena Costa',
-    accountRole: 'Gestora financeira',
-    accountContext: {
-      user: {
-        name: 'Helena Costa',
-        email: 'helena.costa@praxis.demo',
-        role: 'Gestora financeira',
-      },
-      tenant: {
-        name: 'Praxis Holding',
-      },
-    },
-  },
-  formBlocksBefore: {
-    kind: 'praxis.rich-content',
-    version: '1.0.0',
-    nodes: [
-      {
-        type: 'mediaBlock',
-        title: 'Praxis Summit 2026',
-        subtitle: 'Inscricao institucional',
-        description:
-          'Experiencia institucional com composicao editorial hospedada antes do formulario.',
-        icon: 'event',
-      },
-      {
-        type: 'card',
-        content: [
-          { type: 'text', text: 'Antes de comecar', variant: 'title' },
-          {
-            type: 'text',
-            text: 'Confirme os dados abaixo antes do envio e consulte a documentacao se precisar de suporte.',
-          },
-        ],
-      },
-    ],
-  },
-  formBlocksBeforeActions: {
-    kind: 'praxis.rich-content',
-    version: '1.0.0',
-    nodes: [
-      {
-        type: 'card',
-        content: [
-          { type: 'text', text: 'Conta atual', variant: 'title' },
-          { type: 'text', textExpr: '${accountContext.user.name}' },
-          { type: 'text', textExpr: '${accountContext.user.email}' },
-        ],
-      },
-    ],
-  },
-  formBlocksAfter: {
-    kind: 'praxis.rich-content',
-    version: '1.0.0',
-    nodes: [
-      {
-        type: 'card',
-        content: [
-          { type: 'text', text: 'Praxis', variant: 'title' },
-          { type: 'text', text: 'Todos os direitos reservados.' },
-        ],
-      },
-    ],
-  },
-  sections: [
+const config: FormConfig = {
+  sections: [],
+  fieldMetadata: [
+    { name: 'fullName', label: 'Full name', controlType: 'input' },
     {
-      id: 'registration',
-      title: 'Dados da inscricao',
-      rows: [
-        {
-          columns: [
-            {
-              id: 'registration-full-name',
-              items: [{ kind: 'field', id: 'field-fullName', fieldName: 'fullName' }],
-              fields: ['fullName'],
-            },
-            {
-              id: 'registration-work-email',
-              items: [{ kind: 'field', id: 'field-workEmail', fieldName: 'workEmail' }],
-              fields: ['workEmail'],
-            },
-          ],
-        },
-      ],
+      name: 'approvalComment',
+      label: 'Approval comment',
+      controlType: 'textarea',
+      source: 'local',
+      submitPolicy: 'omit',
     },
-  ],
-  fieldMetadata: [
-    { name: 'fullName', label: 'Nome completo', controlType: 'input', required: true },
-    { name: 'workEmail', label: 'E-mail corporativo', controlType: 'email', required: true },
-  ],
-};
-```
-
-Uso no host:
-
-```html
-<praxis-dynamic-form
-  [config]="formConfig"
-  [editorialContext]="{ accountName: 'Helena Costa', accountRole: 'Host override' }"
-></praxis-dynamic-form>
-```
-
-Notas:
-- `formBlocksBefore`, `formBlocksBeforeActions` e `formBlocksAfter` nao entram em `formData`.
-- `editorialContext` deve ser tratado como imutavel; mutacoes in-place nao invalidam o cache do host.
-- A surface editorial agora usa `RichContentDocument`, delegando os nodes para `@praxisui/rich-content`.
-- `formBlocksBeforeActions` renderiza depois das secoes e antes da area principal de acoes, sendo o slot recomendado para blocos contextuais como `form:user-context-summary`.
-- `formBlocksAfter` permanece como slot de fechamento e continua renderizando depois do formulario inteiro, incluindo os CTAs.
-- secoes agora suportam `appearance` (`card|plain|step`) e `stepLabel` para cabecalhos mais estruturados.
-
-See public exports: `projects/praxis-dynamic-form/src/public-api.ts`.
-
-## Blocos visuais em colunas
-
-O layout de coluna usa `sections[].rows[].columns[].items[]` como contrato
-canônico ordenado. Itens `kind: 'field'` referenciam
-`fieldMetadata[].name`; itens `kind: 'richContent'` hospedam um
-`RichContentDocument` dentro da coluna e não entram em `fieldMetadata`,
-`formData` ou payload HTTP.
-
-`sections[].rows[].columns[].fields[]` permanece aceito como entrada de
-migração e como projeção derivada dos itens `kind: 'field'`, mas não deve ser
-usado para criar blocos visuais.
-
-No editor visual, **Campos da API** lista apenas campos existentes em
-`fieldMetadata[]` que ainda não aparecem em `columns[].items[]` como
-`kind: 'field'`. Ao adicionar um campo, o editor reinsere o item em `items[]`
-e mantém `fields[]` sincronizado como projeção; `fieldMetadata[]` não é
-alterado.
-
-**Adicionar bloco visual** oferece presets internos como texto, aviso,
-separador, card informativo, `callout`, `keyValueList`, `recordSummary`,
-`disclosure` e `emptyState`. Esses presets são apenas atalhos de authoring que
-geram documentos `praxis.rich-content` válidos para itens `kind: 'richContent'`;
-eles não criam novo `kind`, não criam `FieldMetadata` e não participam do
-payload de submit.
-
-O runtime do formulário também passa `hostCapabilities` canônicos para
-`@praxisui/rich-content`, permitindo:
-- `actionButton` despachar ações via a mesma trilha de `customAction`/`globalAction`
-  já usada pelo formulário;
-- `requiresCapabilities` resolver capacidades como `form.mode.edit`,
-  `form.mode.view`, `form.customization.enabled`, `form.resource.connected` e
-  `form.actions.submit`.
-
-Exemplo mínimo de uma coluna com campo, bloco visual e projeção `fields[]`:
-
-```json
-{
-  "items": [
     {
-      "kind": "richContent",
-      "id": "identity-guidance-block",
-      "document": {
-        "schemaVersion": 1,
-        "nodes": [
-          {
-            "type": "paragraph",
-            "text": "Revise os dados principais antes de salvar."
-          }
-        ]
-      }
+      name: 'manualOverrideReason',
+      label: 'Manual override reason',
+      controlType: 'textarea',
+      source: 'local',
+      submitPolicy: 'includeWhenDirty',
     },
-    { "kind": "field", "id": "field-nome", "fieldName": "nome" },
-    { "kind": "field", "id": "field-email", "fieldName": "email" }
   ],
-  "fields": ["nome", "email"]
-}
-```
-
-Guia completo: `projects/praxis-dynamic-form/docs/layout-items-visual-blocks.md`.
-
-## Authoring e Persistência em Hosts
-
-- `configChange` preserva o contrato legado e continua emitindo `FormConfig` para consumidores diretos.
-- `configPatchChange` é o output recomendado para hosts genéricos, como Page Builder e páginas dinâmicas, persistirem autoria assistida: o payload segue `{ inputPatch: { config: FormConfig } }`.
-- Fluxos de IA e editores devem materializar alterações no `FormConfig` canônico do componente; o host decide onde gravar `inputs.config`.
-
-## Documentacao Tecnica da Lib
-
-- `projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.json-api.md`
-- `projects/praxis-dynamic-form/docs/hot-metadata-updates.md`
-- `projects/praxis-dynamic-form/docs/layout-items-visual-blocks.md`
-
-## Header de seção com avatar dinâmico
-
-- `FormSection.icon` continua suportado como identidade visual estática do header.
-- `FormSection.sectionHeader` amplia o contrato para permitir avatar resolvido a partir do `formData`, sem perder compatibilidade com `icon`.
-- `FormSection.headerActions` permite ações iconográficas no canto direito do header da seção, reutilizando o mesmo output `customAction` com `source: 'section-header'` e `sectionId`.
-- Modos suportados:
-  - `icon`: usa o ícone estático da seção e, se ele estiver vazio, pode reutilizar `fallbackIcon` como identidade visual explícita do header.
-  - `avatar-image`: tenta resolver uma imagem a partir de `sourceField`.
-  - `avatar-initials`: deriva iniciais a partir de `initialsSourceField` e, na ausência dele, usa `altField`.
-  - `auto`: tenta imagem, depois iniciais e por fim aplica o fallback configurado.
-- Campos principais de `sectionHeader`:
-  - `sourceField`: field cujo valor atual representa foto/avatar.
-  - `initialsSourceField`: field textual usado para derivar iniciais.
-  - `altField`: field usado como texto acessível do avatar e fallback textual para iniciais.
-  - `fallbackIcon`: ícone usado quando a fonte dinâmica estiver vazia ou inválida, e também como fallback explícito do modo `icon` quando `FormSection.icon` não estiver definido.
-  - `emptyState`: `fallback-icon`, `placeholder-avatar` ou `none`, útil sobretudo em fluxos `create`; o padrão efetivo é `placeholder-avatar`, neutro para qualquer domínio. Quando `fallback-icon` é usado, o ícone permanece dentro da moldura/avatar e continua obedecendo `size`.
-  - `size`: tamanho semântico do avatar (`sm`, `md` ou `lg`), materializado pelo runtime por meio dos tokens `--pfx-form-section-avatar-size*`.
-  - `initialsMaxLength`: máximo de letras no avatar textual, normalizado para `1..4`.
-- Campos principais de `headerActions[]`:
-  - `id`, `label`, `icon`
-  - `action` (opcional; se vazio, usa `id`; quando informado, ele vira o nome lógico emitido e a base de rules/mensagens)
-  - `tooltip` (opcional; se vazio, usa `label`)
-  - `color`, `visible`, `disabled`, `loading`
-  - `className` (classe CSS opcional aplicada ao botão do header)
-  - `style` (objeto de estilo inline opcional; no editor é informado como JSON)
-- Formatos de imagem aceitos pelo runtime:
-  - URL
-  - data URL base64
-  - `File`/`Blob`
-  - objetos com `url`, `src`, `dataUrl`, `base64` ou `bytes`
-- Comportamento típico em cadastro:
-  - formulário vazio: mostra placeholder neutro por padrão, ou `fallbackIcon` se `emptyState` pedir isso
-  - nome preenchido, sem foto: `auto` pode mostrar iniciais
-  - foto preenchida: mostra a imagem
-
-## IA — catálogo de capacidades (composição)
-
-O copiloto semântico do formulário usa o shell global de `@praxisui/ai` e registra uma sessão segura no `PraxisAssistantSessionRegistryService`. O botão local apenas abre o contexto do formulário; minimizar/reabrir deve preservar a sessão no cockpit global, sem tratar o formulário como fonte primária de regra de negócio.
-
-O assistente usa um catálogo agregado de capabilities para gerar patches seguros:
-
-- **Macro (FormConfig)**: layout, regras, ações, hooks e mensagens (`form-ai-capabilities`).
-- **Base (FieldMetadata)**: propriedades comuns de campos (`field-metadata-ai-capabilities`).
-- **Micro (por controlType)**: overlay específico de cada input (`@praxisui/dynamic-fields`).
-
-Os paths micro são normalizados para `fieldMetadata[].<prop>` para garantir que os patches apontem para a raiz correta do formulário.
-
-O fluxo agentic-authoring do formulário exige `componentEditPlan` validado pelo `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST` antes de aplicar patch local. Prompts de regra de negócio, política, elegibilidade, compliance, LGPD, aprovação/publicação ou decisão compartilhada devem seguir para `domain-rules`/`shared_rule_authoring`; em `view` sem customização ou readonly, o assistente opera apenas como ajuda/diagnóstico e não aplica mutação local.
-
-## Regras de formulário (novo contrato)
-
-- Formato: cada regra tem `targetType` (`field | section | action | row | column | visualBlock`), `targets: string[]` (IDs canônicos do alvo), e `effect` com `condition` (`JsonLogicExpression | null`), `properties` e `propertiesWhenFalse`.
-- Regra de negócio, política, elegibilidade, validação, compliance ou decisão compartilhada deve ser authorada no fluxo governado de `domain-rules`/`shared_rule_authoring`. `visualBlockGuidance` fica restrito a projeção visual opcional: quando uma decisão já governada precisar explicar impacto na UI, a materialização `form_config` pode gerar `type: "visualBlockGuidance"`, `targetType: "visualBlock"` e `metadata.origin: "llm"` com `metadata.reviewStatus: "pending"`; o editor aceita a projeção, marca como `accepted` e materializa `formRulesState` internamente para round-trip visual.
-- Compatibilidade: regras antigas (`context/targetField`) são migradas para `properties/targets` automaticamente; prefixes legados `section:/action:/row:/column:` continuam sendo normalizados quando representarem alvos tradicionais. Para header actions de seção, o ID canônico é preservado como `section:<sectionId>:header-action:<actionLogicalId>`.
-- Semântica de limpeza: valores `null` em `properties/propertiesWhenFalse` removem o override e retornam ao valor base do layout; ausência mantém o valor base.
-- Whitelist por tipo (somente propriedades a seguir são aplicadas; demais são descartadas e logadas em dev):
-  - `field`: `visible`, `required`, `readonly`, `disabled`, `className`, `style`, `label`, `description`, `placeholder`, `hint`, `tooltip`, `prefixIcon`, `suffixIcon`, `prefixText`, `suffixText`, `defaultValue`, `value`, `options` (array `{label,value,disabled?}`), `appearance` (`fill|outline`), `color` (`primary|accent|warn`), `floatLabel` (`auto|always|never`), `hintPosition` (`start|end`), `validators` (primitivos por chave).
-  - `section`: `visible`, `title`, `description`, `icon`, `sectionHeader` (objeto rico), `headerActions` (ações contextuais do cabeçalho) e tambem subpropriedades tipadas como `sectionHeader.mode`, `sectionHeader.sourceField`, `sectionHeader.initialsSourceField`, `sectionHeader.altField`, `sectionHeader.fallbackIcon`, `sectionHeader.emptyState`, `sectionHeader.size`, `sectionHeader.initialsMaxLength`, `className`, `style`, `collapsible`, `collapsed`, `headerTooltip`, `headerAlign` (`start|center`), `appearance` (`card|plain|step`), `stepLabel`, gaps (`gapBottom`, `titleGapBottom`, `descriptionGapBottom`), cores/tipografia (`titleColor`, `descriptionColor`, `titleStyle`, `descriptionStyle`).
-  - `action`: `visible`, `disabled`, `loading`, `label`, `icon`, `tooltip`, `color` (`primary|accent|warn|basic`), `variant` (`raised|stroked|flat|fab`), `size` (`small|medium|large`), `className`, `style`.
-  - `row`: `visible`, `gap`, `rowGap`, `className`, `style`.
-  - `column`: `visible`, `span`, `offset`, `order`, `hidden`, `align` (`start|center|end|stretch`), `padding`, `className`, `style`.
-  - `visualBlock`: `visible`, `hidden`, `layout`, `className`, `rootClassName`, `style`, `text`, `title`, `message`; para documentos compostos, use `textNodeId`, `titleNodeId` ou `messageNodeId` para apontar o node textual seguro.
-- IDs canônicos de regras para actions do header de seção usam o formato `section:<sectionId>:header-action:<actionLogicalId>`, evitando colisão com botões globais e com ações repetidas em seções diferentes.
-- Se a seção ainda não tiver `id`, o runtime aceita o fallback `header-action:<actionLogicalId>` por compatibilidade; para contratos persistidos, prefira sempre materializar `section.id`.
-- Valores calculados: regras de `targetType: "field"` podem escrever `effect.properties.value` ou `effect.propertiesWhenFalse.value`. Use envelope fechado e exclusivo: exatamente `{ "expression": <JsonLogic> }` para calcular ou exatamente `{ "literal": <valor> }` para valor estruturado. Primitivos, `null` e arrays continuam aceitos como literais; objetos literais devem usar `{ "literal": ... }` para não serem tratados como Json Logic legado. Envelopes com chaves extras ou com `literal` e `expression` juntos são inválidos.
-- Ordem de regras: valores calculados são resolvidos em fase anterior, com iteração limitada até estabilizar, antes da aplicação das demais propriedades. Assim uma regra pode calcular `age` e outra regra pode depender de `age` sem depender da posição no array.
-- Comandos condicionais: `formCommandRules` é a superfície aditiva para side effects governados, avaliada depois que `formRules` estabilizam valores calculados. O primeiro corte suporta `effects[].kind: "global-action"` com `globalAction: GlobalActionRef`, policy operacional (`trigger`, `distinct`, `distinctBy`, `debounceMs`, `errorPolicy`, `runOnInitialEvaluation`) e default `trigger: "on-condition-enter"`. Comandos não devem ser colocados em `formRules[].effect.properties`. No editor visual, `payloadExpr` permanece escape hatch de JSON avancado: ele e preservado quando ja existe e nenhum payload estruturado e definido, mas novos campos visuais authoram `payload` literal.
-- Runtime (FormRulesService): filtra por whitelist, converte tipos (enum/number/boolean/string), saneia objetos (`options/validators/style`), aplica remoção de chaves com `null`, resolve `fieldValues` calculados e retorna mapas `fieldProps/sectionProps/actionProps/rowProps/columnProps/visualBlockProps`.
-- Renderização: `PraxisDynamicForm` aplica overrides em campos/seções/ações/linhas/colunas/blocos visuais (visibilidade, gaps, padding, classes, estilos, labels e texto seguro, conforme o tipo); colunas respeitam `align/span/offset/order/hidden/padding` vindo das regras.
-- Regras de `visualBlock` são visual-only: elas não criam `FieldMetadata`, `FormControl`, valor em `formData` ou payload HTTP. Use campo local com `submitPolicy` quando a experiência precisar de valor persistível ou leitura em `rawFormData`.
-
-Politica de erro dos comandos condicionais: falhas de `GlobalActionService.executeRef(...)` geram diagnostico sem propagar excecao para o ciclo do form, e a memoria `distinct` evita repeticao enquanto a condicao segue verdadeira. Sem `GlobalActionService`, actions mutaveis (`api.post`, `api.put`, `api.patch`, `api.delete`) falham fechado e nao sao emitidas via `customAction`.
-
-### Builder integrado
-
-- No editor visual, use a aba “Propriedades” (integrada ao builder) para selecionar o alvo (`targetType` + autocomplete de IDs de campos/seções/ações/linhas/colunas/blocos visuais), escolher propriedades whitelisted e definir valores para `properties` (branch true) e `propertiesWhenFalse` (branch false). Botão “Limpar override” remove a propriedade (equivalente a `null`).
-- Para `visualBlock`, o painel de propriedades exibe um seletor de node quando a propriedade é `text`, `title` ou `message`; o editor persiste `textNodeId`, `titleNodeId` ou `messageNodeId` automaticamente para evitar sobrescrever o node errado em documentos compostos.
-- No round-trip do builder, `config.type` continua sendo reservado para o tipo visual do node; semântica de regra como `visualBlockGuidance` é preservada internamente em `config.ruleType` e volta para `formRules[].type`.
-- A aba de Propriedades usa inputs tipados (enum/number/boolean/string/JSON) conforme o schema injetado; valores inválidos são ignorados.
-- O config editor fornece `targetSchemas` (campos/seções/ações/linhas/colunas/blocos visuais) e `targetPropertySchemas` para o builder; `formRules` são salvas no formato canônico (sem `context/targetField`).
-
-## Layout padrão (sem FormConfig)
-
-Quando o componente não recebe uma `FormConfig` prévia (primeira execução), ele gera um layout padrão a partir do metadata do backend:
-
-- Linhas/colunas: 2 campos por linha (padrão). Em telas pequenas (xs/sm) os campos empilham (1 por linha), e a partir de md ficam lado a lado.
-- Responsividade do grid (12 colunas):
-  - xs: 12, sm: 12, md: 6, lg: 6, xl: 6 (para 2 por linha). Para outros valores, a regra é `base = floor(12 / fieldsPerRow)`.
-- Largura dos campos: `mat-form-field { width: 100% }` e um **allow‑list** de tipos “input‑like” em `data-field-type` recebem `width: 100%`. Controles compactos (ex.: checkbox/radio/toggle/rating/slider) **não** são forçados a preencher a coluna.
-- Editor de Configuração: ao abrir a aba “Layout”, o editor reflete esse layout padrão; ao aplicar/salvar, persiste a `FormConfig` no storage do host.
-- Personalização: você pode ajustar o layout pelo Editor (arrastar/seções/linhas/colunas, alterar spans) ou fornecer uma `FormConfig` completa via `[config]`.
-
-## Form Actions — Layout & Styling
-
-A barra de ações (onde ficam "ENVIAR", "Cancelar", etc.) é configurável via `config.actions` e pelo Editor (aba "Ações").
-
-Defaults
-- Rótulo do botão principal: `ENVIAR`.
-- Posição estrutural: `afterSections` (renderiza abaixo da última seção).
-- Alinhamento: `right`.
-- Orientação: `horizontal`.
-- Espaçamento: `normal`.
-- Background: sem cor por padrão (herda da superfície). Configure via `containerStyles` ou `containerClassName` se desejar uma superfície própria.
-
-Estrutura (parcial)
-```ts
-interface FormActionsLayout {
-  submit: FormActionButton;     // id, label, color, type, variant, shortcut, etc.
-  cancel: FormActionButton;
-  reset: FormActionButton;
-  custom?: FormActionButton[];  // botões extras
-
-  // Layout/posicionamento
-  placement?: 'afterSections' | 'insideLastSection' | 'top';
-  position?: 'left' | 'center' | 'right' | 'justified' | 'split';
-  orientation?: 'horizontal' | 'vertical';
-  spacing?: 'compact' | 'normal' | 'spacious';
-  sticky?: boolean; // fixa a barra (bottom)
-
-  // Estilização do container
-  containerClassName?: string;      // adiciona classe ao container
-  containerStyles?: { [k: string]: any }; // estilos inline (camelCase)
-
-  // Mobile
-  mobile?: { position?: 'left'|'center'|'right'|'justified'; orientation?: 'horizontal'|'vertical'; collapseToMenu?: boolean };
-}
-```
-
-Exemplo (config)
-```ts
-config.actions = {
-  submit: { visible: true, label: 'ENVIAR', type: 'submit', color: 'primary', variant: 'raised', shortcut: 'ctrl+s' },
-  cancel: { visible: true, label: 'Cancelar', type: 'button', color: 'basic' },
-  reset:  { visible: false, label: 'Reset' },
-  placement: 'afterSections',
-  position: 'right',
-  orientation: 'horizontal',
-  spacing: 'normal',
-  sticky: false,
-  containerClassName: 'my-form-actions',
-  containerStyles: {
-    background: 'var(--md-sys-color-surface-container)',
-    border: '1px solid var(--md-sys-color-outline-variant)',
-    borderRadius: '12px',
-    padding: '12px 16px'
-  },
-  mobile: { collapseToMenu: true }
 };
 ```
 
-CSS por classe (opcional)
-```scss
-.my-form-actions {
-  background: var(--md-sys-color-surface-container);
-  border: 1px solid var(--md-sys-color-outline-variant);
-  border-radius: 12px;
-  padding: 12px 16px;
-}
-```
-
-Dicas
-- Cores do botão: use `color` = `primary|accent|warn|basic` (respeitam o tema Material).
-- Tokens M3: prefira `--md-sys-*` para cores/superfícies.
-- Mobile: ative `collapseToMenu` para colapsar botões extras em menu nas telas pequenas.
-- A classe de tema é decisão do host (`.dark-theme` ou `.theme-dark`/`.theme-light`); mantenha tokens e componentes no mesmo escopo.
-- Editor integrado:
-  - `Ações > Botões Customizados` permite editar `label`, `icon`, `color`, `variant`, `size`, `tooltip`, `shortcut`, `className`, `disabled`, `loading` e `style` (JSON).
-  - `Seção > Cabeçalho` permite editar `headerActions[]` sem JSON manual, incluindo adicionar, remover e reordenar ações do header.
-  - No campo `action`, o editor sugere o catálogo global canônico do core e mantém fallback para ação customizada livre; o valor salvo continua compatível com `action` textual legado.
-  - Ações globais no header seguem o mesmo princípio operacional do restante da plataforma: dependem de executor no app (`ActionResolver`) e validam parâmetro obrigatório quando o catálogo exigir.
-  - Para `surface.open`, o editor expõe o authoring especializado da surface em vez de reduzir tudo a texto cru.
-  - A mesma aba permite reordenar `actions.custom[]` pelos controles de mover para cima/baixo; a ordem salva é a mesma ordem renderizada no runtime, sempre depois de `submit/cancel/reset`.
-
-### Tokens M3 obrigatórios (host)
-
-Para que o builder e os editores respeitem o tema do app host:
-
-- Superfícies: `--md-sys-color-surface`, `--md-sys-color-surface-variant`, `--md-sys-color-surface-container-*`
-- Texto/contorno: `--md-sys-color-on-surface`, `--md-sys-color-on-surface-variant`, `--md-sys-color-outline`, `--md-sys-color-outline-variant`
-- Semânticos: `--md-sys-color-primary`, `--md-sys-color-secondary`, `--md-sys-color-tertiary`, `--md-sys-color-error`
-- Containers: `--md-sys-color-primary-container`, `--md-sys-color-secondary-container`, `--md-sys-color-tertiary-container`, `--md-sys-color-error-container`
-- Elevação: `--md-sys-elevation-level1`–`--md-sys-elevation-level3`
-
-
-## Section titles — espaçamento global
-
-O título de seção usa por padrão `margin: 0 0 6px 0`. Você pode ajustar globalmente via CSS var:
-
-```scss
-/* Global (app host) */
-:root { --pfx-section-title-mb: 10px; } // ex.: 10px abaixo do título
-```
-
-Ou por seção, via metadado `titleGapBottom` (em pixels), que aplica inline somente naquela seção.
+Do not model backend DTO fields as local/transient fields. If a field belongs to the public backend schema, fix the canonical schema or metadata mapping.
 
-## Compatibility
+## Layout, Rules, And Rich Content
 
-- `@praxisui/dynamic-form` `0.0.x` → Angular `20.x`
-- Module format: `ESM2022`
+`FormConfig` owns sections, rows, columns, field placement, visual blocks, rules, hooks, and actions.
 
-## Crash Recovery Checkpoint
+- `sections[].rows[].columns[].items[]` is the ordered layout contract.
+- `kind: "field"` references `fieldMetadata[].name`.
+- `kind: "richContent"` hosts a `RichContentDocument` and does not enter `fieldMetadata`, `formData`, or HTTP payloads.
+- `formRules` govern visibility, required state, values, labels, styles, and other whitelisted runtime properties.
+- `formCommandRules` are used for governed side effects such as global actions.
 
-Estado registrado em `2026-03-15` para retomada rapida do trabalho de E2E do editor `/form-config-editor`.
+Presentation formatting of field values is resolved by `@praxisui/dynamic-fields` from field metadata such as `valuePresentation`.
 
-Suites Playwright ja adicionadas e validadas:
-- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-smoke.playwright.spec.ts`
-- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-layout.playwright.spec.ts`
-- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-rules.playwright.spec.ts`
-- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-cascades.playwright.spec.ts`
-- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-json.playwright.spec.ts`
-- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-hooks.playwright.spec.ts`
-- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-actions.playwright.spec.ts`
-- `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-actions-custom.playwright.spec.ts`
+## Visual Editor
 
-Cobertura ja estabilizada:
-- smoke das tabs principais do editor integrado
-- `Layout`
-- `Regras`
-- `Cascatas`
-- `JSON` com edicao real e bloqueio de payload invalido
-- `Hooks`
-- `Acoes` (`Botoes Padrao` e `Layout`)
-- `Acoes` customizadas profundas (`dialog.alert` com `globalAction` simples e estruturado)
-- `Comportamento`
-- `Mensagens`
-- `Dicas e Tooltips`
+Use `PraxisDynamicFormConfigEditor` directly or enable customization on the runtime.
 
-Ajuste tecnico aplicado durante essa fase:
-- [praxis-dynamic-form-config-editor.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts) agora chama `this.jsonEditor?.updateJsonFromConfig(this.editedConfig)` em `onConfigChange(...)` para manter o editor JSON sincronizado com mudancas vindas de abas como `Hooks`.
-- [actions-editor.component.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts) agora usa o catalogo global canonico do app para o editor de acoes customizadas.
-- [actions-editor.component.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts) agora preserva draft local dos campos globais e usa `track` estavel em `actions.custom`.
-
-Comando base usado para rerodar suites isoladas:
+```ts
+import { PraxisDynamicFormConfigEditor } from '@praxisui/dynamic-form';
 
-```bash
-node ./node_modules/playwright/cli.js test --config tools/e2e/playwright/praxis-dynamic-form-config-editor.playwright.config.ts <spec>
+dialog.open(PraxisDynamicFormConfigEditor, {
+  width: '1024px',
+  data: {
+    formConfig: config,
+    formId: 'employee-edit',
+    mode: 'edit',
+  },
+});
 ```
 
-Se houver crash, retomar daqui:
-1. garantir que o app esteja no ar
-2. rerodar a ultima suite alterada
-3. proximo alvo pendente: consolidar a bateria completa ou seguir para outra area residual do editor
+The editor preserves the same `FormConfig` contract used by the runtime. Field type names, descriptions, and icons come from the dynamic-fields editorial metadata chain, not from a local map inside Dynamic Form.
 
-## License
+## AI Authoring
 
-Apache-2.0 – see the `LICENSE` packaged with this library or the repository root.
+`PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST` declares executable operations for governed edits to:
 
-# Praxis Dynamic Form — Cascata vs Connections
+- fields and local fields
+- sections, rows, columns, and layout placement
+- visual blocks
+- form actions
+- form rules and messages
+- schema-backed field edits
 
-### Concept Usage
+The manifest is meant to keep AI-generated patches compatible with the visual editor and the runtime `FormConfig` contract.
 
-- Data-driven forms
-- Declarative UI
-- Schema-driven UI
+## Public API
 
-## Quando usar cada mecanismo
+Main exports:
 
-- Connections (dot‑path)
-  - Para orquestração “externa” (entre widgets, tabs, tabelas ou fora do formulário).
-  - Escrevem em `inputs.config.*` do widget do formulário, inclusive metadados de campos (ex.: `inputs.config.fieldMetadata[i].filterCriteria`).
-  - Escala bem para cenários de página e integração cross‑widget.
+- `PraxisDynamicForm`
+- `PraxisFilterForm`
+- `PraxisDynamicFormConfigEditor`
+- `JsonConfigEditorComponent`
+- `LayoutEditorComponent`
+- `PraxisFormActionsComponent`
+- `FormConfigService`, `FormLayoutService`, `DynamicFormLayoutService`, `FormContextService`, `FormRulesService`, `DomainRuleFormRulesService`
+- widget config editors for dynamic form and filter form
+- metadata providers such as `providePraxisDynamicFormMetadata`
+- rule utilities, date normalization, settings-panel providers
+- `FORM_AI_CAPABILITIES`, `FORM_COMPONENT_AI_CAPABILITIES`
+- `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST`
 
-- Cascata nativa (campo→campo, intra‑form)
-  - Declarativa via metadata (`dependencyFields`, `resetOnDependentChange`, etc.).
-  - Observa `FormControl.valueChanges` dos campos dependentes, aplica `filterCriteria` e recarrega conforme estratégia (`loadOn`, `dependencyLoadOnChange`).
-  - Elimina código ad hoc na página.
-
-## Convivência e fonte de verdade
-
-- Se Connections atualizam `filterCriteria` de um campo, considere desativar a cascata nativa nesse campo (`enableDependencyCascade: false`) ou usar `dependencyLoadOnChange: 'manual'` (cascata só atualiza filtros e Connections disparam o load).
-- Estratégia de merge recomendada: `dependencyMergeStrategy: 'merge'` para preservar chaves vindas de Connections.
-
-## Links úteis
-
-- Fluxo de Schema (ETag/304, schemaId, reconciliação): `projects/praxis-core/docs/schema-flow.md` (canônico) e `docs/schemas/fluxo-schema.md` (resumo operacional)
-- Guia de implementação e metadados da cascata: `docs/CASCADE-NATIVA.md`
-- Padrões de endpoints (Options vs Filter) para selects: `projects/praxis-dynamic-fields/docs/generic-crud-service.md` (canônico) e `docs/DEVS-GENERIC-CRUD-SERVICE.md` (resumo operacional)
-- Recipe oficial de Entity Lookup corporativo com `RESOURCE_ENTITY`, `dependsOn`, `dependencyFilterMap`, reidratação por `by-ids` e política de seleção: `examples/ai-recipes/praxis-dynamic-form.entity-lookup-procurement.json`
-- Recipe oficial de comandos condicionais governados com `formCommandRules`, `GlobalActionRef`, policy operacional, valor calculado e date range confirmado: `examples/ai-recipes/praxis-dynamic-form.command-rules.json`
-
-## Verificação de Schema (ETag/If-None-Match)
-
-- Inputs (opcionais; ativos apenas com `enableCustomization=true`):
-  - `notifyIfOutdated: 'inline' | 'snackbar' | 'both' | 'none' = 'both'`
-  - `snoozeMs: number = 86400000`
-  - `autoOpenSettingsOnOutdated: boolean = false`
-- Output:
-  - `schemaStatusChange: { outdated: boolean; serverHash?: string; lastVerifiedAt?: string; formId?: string }`
-- Persistência (ConfigStorage):
-  - `form-schema-meta:{formId}` → `{ serverHash?: string; lastVerifiedAt?: string }`
-  - `form-schema-prefs:{formId}` → `{ notifyIfOutdated?, snoozeMs?, autoOpenSettingsOnOutdated? }`
-  - Por hash (suppress): `schemaIgnore:{formId}:{hash}`, `schemaSnooze:{formId}:{hash}`, `schemaNotified:{formId}:{hash}`
-- Comportamento:
-  - Quando existe uma config persistida para o `formId`, o componente normaliza a config local, baixa o schema estrutural canônico e reconcilia `fieldMetadata` antes de montar o formulário.
-  - Essa reconciliação preserva customizações locais intencionais, incluindo campos com `source: "local"`, `transient: true` e `submitPolicy`, mas atualiza semântica server-backed publicada pelo schema.
-  - Campos de select publicados com `x-ui.endpoint` em `/options/filter` preservam `endpoint` como operação concreta e `resourcePath` como recurso dono. Isso evita usar `/filter` ou consultar schema do endpoint de options por engano.
-  - 304 em verificações posteriores apenas atualiza `lastVerifiedAt` e emite `schemaStatusChange(outdated=false)`.
-  - 200 em verificações posteriores atualiza `serverHash/lastVerifiedAt`, define `schemaOutdated = enableCustomization && hadBase` e emite `schemaStatusChange`.
-  - Primeira vez (sem base): baixa o corpo do schema para gerar o layout; persiste `form-schema-meta:{formId}`.
-  - Notificações respeitam preferências e são one‑shot por hash; o banner/snackbar oferecem ações para Reconciliar, Lembrar depois (snooze) e Ignorar.
-
-### URL da API (absoluto vs relativo)
-
-- Quando `API_URL.default.baseUrl` for relativo (ex.: `'/api'`), a lib resolve a origem a partir de `location.origin` no browser. Isso cobre o cenário comum com proxy de dev (`/api`, `/schemas`).
-- Em SSR (sem `location.origin`), configure `baseUrl` absoluto (ex.: `https://api.acme.com/api`) para evitar erros do tipo “Invalid URL” ao construir chamadas de `/schemas/filtered`.
-- O `GenericCrudService.getSchemasFilteredBaseUrl()` retorna sempre uma URL absoluta; o `SchemaMetadataClient` também aceita `baseUrl` relativo quando há origin disponível.
-
-## Regras de Domínio Compartilhadas
-
-`praxis-dynamic-form` pode consumir regras materializadas pelo backend sem gravá-las dentro de `FormConfig`. O input `domainRules` é opt-in e combina as regras remotas com `config.formRules` no mesmo `FormRulesService`.
-
-```html
-<praxis-dynamic-form
-  formId="funcionarios-form-demo"
-  [config]="formConfig"
-  [domainRules]="{
-    enabled: true,
-    targetArtifactKey: 'funcionarios-form-demo',
-    targetLayer: 'form_config',
-    targetArtifactType: 'praxis-dynamic-form',
-    status: 'applied'
-  }">
-</praxis-dynamic-form>
-```
-
-- `targetArtifactKey` usa `formId`/`componentInstanceId` quando omitido.
-- `targetLayer` default: `form_config`.
-- `targetArtifactType` default: `praxis-dynamic-form`.
-- Para consumo runtime, prefira `status: 'applied'`; `pending_review` pertence a etapas de governança antes da aplicação.
-- `materializedPayload` pode ser um `FormLayoutRule` direto ou uma operação reconhecida, como `rule.visualBlockGuidance.add`, desde que essa operação seja tratada como projeção visual derivada e não como fonte primária da regra de negócio.
-- A rastreabilidade da regra compartilhada fica em `metadata.domainRule`.
-- Quando o backend enviar `decisionDiagnostics`, o runtime preserva esse envelope em `metadata.domainRule.decisionDiagnostics`, mantendo a explicação canônica da decisão semântica governada junto da regra derivada.
-
-E2E vivo com API real:
-
-```bash
-PAX_PROXY_TARGET=https://praxis-api-quickstart.onrender.com \
-node scripts/run-playwright-with-dev-host.js \
-  --port 4003 \
-  --path /funcionarios-form-demo \
-  --spec projects/praxis-dynamic-form/test-dev/e2e/funcionarios-form-demo-domain-rules.playwright.spec.ts
-```
+## Notes
 
-Validado em 2026-04-23 contra `praxis-api-quickstart` publicado no Render com
-`praxis-config-starter:0.1.0-rc.22`: o spec confirmou resposta 200 de
-`/api/praxis/config/domain-rules/materializations` e presença de materialização
-`form_config` com `operation: "rule.visualBlockGuidance.add"`.
+- Separate local-only, backend schema-driven, and authored/customizable usage before deciding the minimum host setup.
+- Keep backend schema fields server-backed; use local/transient metadata only for UI-owned state.
+- Prefer explicit `schemaUrl + submitUrl + submitMethod` for backend-published surfaces and actions.
+- Use the official documentation for full recipes on cascades, schema reconciliation, domain rules, action layout, and visual editor workflows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-form",
-  "version": "9.0.0-beta.0",
+  "version": "9.0.0-beta.2",
   "description": "Angular dynamic form engine for Praxis UI: metadata-driven forms, hooks, and services integrating @praxisui/* packages.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -9,13 +9,13 @@
     "@angular/forms": "^21.0.0",
     "@angular/material": "^21.0.0",
     "@angular/router": "^21.0.0",
-    "@praxisui/ai": "^9.0.0-beta.0",
-    "@praxisui/dynamic-fields": "^9.0.0-beta.0",
-    "@praxisui/metadata-editor": "^9.0.0-beta.0",
-    "@praxisui/rich-content": "^9.0.0-beta.0",
-    "@praxisui/settings-panel": "^9.0.0-beta.0",
-    "@praxisui/visual-builder": "^9.0.0-beta.0",
-    "@praxisui/core": "^9.0.0-beta.0",
+    "@praxisui/ai": "^9.0.0-beta.2",
+    "@praxisui/dynamic-fields": "^9.0.0-beta.2",
+    "@praxisui/metadata-editor": "^9.0.0-beta.2",
+    "@praxisui/rich-content": "^9.0.0-beta.2",
+    "@praxisui/settings-panel": "^9.0.0-beta.2",
+    "@praxisui/visual-builder": "^9.0.0-beta.2",
+    "@praxisui/core": "^9.0.0-beta.2",
     "rxjs": "^7.8.0"
   },
   "dependencies": {
@@ -28,7 +28,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/codexrodrigues/praxis-ui-angular"
+    "url": "git+https://github.com/codexrodrigues/praxis-ui-angular.git"
   },
   "homepage": "https://praxisui.dev",
   "bugs": {