---
title: "Dynamic Form Authoring Document Semantics"
doc_type: "adr"
component: "praxis-dynamic-form"
status: "accepted"
owner: "praxis-ui"
last_updated: "2026-08-19"
---

# Dynamic Form Authoring Document Semantics

## Decision

`DynamicFormAuthoringDocument` e o snapshot canônico completo de autoria de `praxis-dynamic-form`.

Ao aplicar um documento canônico:

- `config` substitui integralmente a configuração anterior.
- `bindings` substitui integralmente os bindings persistíveis anteriores.
- ausência de `bindings.mode` implica limpeza do binding persistido e retorno ao modo default efetivo do host.
- `contextSnapshot` substitui integralmente o contexto autoral persistido anterior.
- ausência de `backConfig`, `presentation` ou `schemaPrefs` dentro de `contextSnapshot` significa remoção explícita do bloco ausente.

Payloads legados ou parciais recebidos por APIs de compatibilidade, como `applyConfigFromAdapter(...)`, permanecem com semântica `merge-compat`: campos não informados devem ser preservados até migração completa para o contrato canônico.

## Filter Form projection

`praxis-filter-form` compartilha o mesmo documento canônico, parser e serializer,
mas não executa todo o runtime de `praxis-dynamic-form`. Seu editor preserva
`config` e `bindings.mode` no round-trip e mantém inputs do host que não pertencem
ao documento autoral.

O manifesto `PRAXIS_FILTER_FORM_AUTHORING_MANIFEST` é uma projeção fail-closed do
manifesto de Dynamic Form. A projeção referencia inputs, operações e requisitos
de round-trip por IDs estáveis; targets, validators e examples são fechados
transitivamente. Uma referência ausente invalida a materialização em vez de
publicar um manifesto parcial ou reutilizar um `componentId` enganoso.

O escopo do Filter Form contém somente as quinze operações de campos e layout que
o wrapper materializa. Permanecem fora da projeção `field.submitPolicy.set`, blocos
visuais, regras e configuração das ações submit/cancel/reset. Esses recursos
dependem de superfícies do Dynamic Form completo e não devem ser sugeridos para o
runtime reduzido de filtros.

Valores de runtime/discovery, como `schemaUrl`, `submitUrl` e `submitMethod`, nÃ£o fazem parte do `DynamicFormAuthoringDocument`. O editor pode exibi-los apenas como diagnÃ³stico read-only do host atual, mas nunca os persiste em `bindings` ou `contextSnapshot`.

## Field Metadata Editor Patches

Patches vindos de `@praxisui/metadata-editor` para `fieldMetadata` seguem semantica de JSON Merge Patch no campo editado.

Para `entityLookup`, o bloco `fieldMetadata[].optionSource` e aninhado e deve ser mesclado em profundidade. O dynamic-form deve preservar campos existentes, como `key`, `resourcePath`, `valuePropertyPath` e `capabilities.byIds`, quando o editor alterar apenas partes do contrato, como `dependsOn`, `selectionPolicy`, `detail` ou `capabilities.auditSnapshot`.

Essa regra evita perda silenciosa do contrato canonico de Entity Lookup durante o fluxo: abrir editor -> aplicar/salvar -> reabrir editor -> runtime consumir.

## Consequences

- `backConfig`, `presentation` e `schemaPrefs` permanecem fora de `FormConfig`, mas fazem parte oficialmente do documento autoral persistível em `contextSnapshot`.
- `Apply` e `Save` vindos do editor operam em modo `replace-all`.
- `reset` do editor limpa todos os modos persistidos do artefato.
- o wrapper de Filter Form delega `reset` ao editor canônico e preserva
  `config + bindings.mode` ao aplicar, salvar e reabrir;
- adapters legados continuam suportados sem limpeza destrutiva de contexto ausente.
- editores subordinados de seção, linha e coluna devem aplicar alterações pela localização estrutural capturada (`section`, `row`, `column`), nunca por busca global do primeiro `id` coincidente;
- IDs de linha devem ser únicos dentro da seção e IDs de coluna devem ser únicos dentro da linha;
- o estado `dirty` desses editores é reversível: restaurar o snapshot inicial deve desabilitar novamente Apply/Save.

## Visual Blocks Inside Layout

Blocos visuais dentro de seção, linha ou coluna devem seguir a decisão
canônica registrada em:

- `../../../docs/2026-04-dynamic-form-visual-blocks-layout-items-plan.md`
- `../../../../docs/adr/ADR-0006-dynamic-form-layout-items-visual-blocks.md`
- `./layout-items-visual-blocks.md`
- `./dynamic-form-rules-authoring-plan.md`

A semântica alvo é `FormColumn.items`, com uma union discriminada entre campo e
rich content. `FormColumn.fields` pode ser aceito como entrada de migração para
configurações antigas, mas não deve seguir como segunda fonte de verdade.

O editor deve produzir e persistir o documento canônico, e o runtime deve
consumi-lo sem adaptador oculto. O round-trip esperado é:

`abrir editor -> adicionar bloco visual -> aplicar/salvar -> reabrir -> renderizar`

Guardrail permanente:

- bloco visual não entra em `fieldMetadata`;
- bloco visual não cria `FormControl`;
- bloco visual não entra no payload de submit;
- bloco visual não usa `source`, `transient` ou `submitPolicy`.
- operações AI para bloco visual devem escrever apenas em
  `sections[].rows[].columns[].items[]`, usando itens `kind: 'richContent'`;
- `sections[].rows[].columns[].fields[]` é apenas projeção/migração de campos
  e não pode ser usado para representar bloco visual.
- presets de bloco visual no editor são atalhos internos para criar
  `RichContentDocument` com nodes já suportados por `@praxisui/rich-content`;
  presets não introduzem novo `kind` nem contrato paralelo.
- "Adicionar campo da API" reinsere somente campos já existentes em
  `fieldMetadata[]` e ausentes de `columns[].items[]`; a operação escreve o
  item `kind: 'field'` em `items[]` e preserva `fieldMetadata[]`.

Em fase beta, não vamos deixar legado para trás sem migração, mas também não
vamos manter legado como contrato paralelo permanente.

## Preferência inicial de apresentação

`bindings.presentationModeGlobal?: boolean | null` materializa no documento o input já existente do Dynamic Form. `true` solicita apresentação em `view`, `false` força campos e `null`/ausência herda `layoutPolicy`. A apresentação não altera `mode`; `create` e `edit` continuam permitindo preenchimento.

O editor Geral oferece ambas as escolhas. O wrapper do Page Builder publica a preferência nos inputs do widget sem persistir uma projeção de schema vazia. O editor aberto pelo runtime salva o snapshot completo de bindings em `form-inputs` e emite os bindings no patch parcial ao host. Em `input-first`, preferências locais não sobrescrevem os inputs. Omitir a preferência em replace-all limpa o override anterior.

Estilos permanecem em `contextSnapshot.presentation`, acessível pela aba **Estilo da apresentação** nos editores direto e do Page Builder. O input `presentation?: DynamicFormPresentationSnapshot | null` projeta esse bloco no widget, sem criar `config.sections` vazias; `null` limpa ajustes explícitos, enquanto ausência mantém a resolução padrão. O wrapper de Filter Form compartilha o documento, mas não oferece a ativação, pois seu runtime não implementa apresentação.


### Presentation style projection and editor UX

- `contextSnapshot.presentation` is the canonical style snapshot. The optional runtime input `presentation: DynamicFormPresentationSnapshot | null` projects it into page widgets independently of schema-generated `config`. Explicit styles take precedence over stored style preferences; `null` restores defaults and blocks stale stored overrides; omission retains normal style resolution.
- Runtime editor Apply/Save emits `presentation` with `mode` and `presentationModeGlobal` in `configPatchChange.inputPatch`. Widget save/reopen preserves the same snapshot; omitting the document block clears the widget projection with `null`.
- Numeric font sizes and label widths are pixels. Capturing a runtime `rem` size converts it using the host root font size; opening and saving must not reinterpret `0.78rem` as `0.78px`.
- **Geral → Dados do formulário** separates **Criar / Editar / Visualizar** from **Automático / Campos / Apresentação**. Selecting presentation in Create/Edit keeps the operation unchanged and explains the inactive state with an explicit action to switch to View.
- **Estilo da apresentação** remains discoverable regardless of the current mode. It previews sample data and does not activate presentation by itself. Filter Form does not expose this tab because it has no presentation runtime.
- Applying or finishing widget editing updates the page draft. **Salvar página** persists the composition. Shortening sample text affects the preview only.
