@praxisui/dynamic-form 8.0.0-beta.2 → 8.0.0-beta.21

package/docs/layout-items-visual-blocks.md

@@ -0,0 +1,406 @@
+---
+title: "Dynamic Form Layout Items and Visual Blocks"
+slug: "dynamic-form-layout-items-visual-blocks"
+description: "Guia canônico para usar FormColumn.items, campos da API e blocos visuais richContent no Dynamic Form."
+doc_type: "guide"
+document_kind: "contract-guide"
+category: "forms"
+audience:
+  - "frontend"
+  - "host"
+  - "platform-team"
+  - "architect"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-form"
+  - "layout-items"
+  - "visual-blocks"
+  - "rich-content"
+  - "form-column-items"
+toc: true
+sidebar: true
+reading_time: "12 min"
+estimated_setup_time: "20 min"
+last_updated: "2026-04-22"
+source_of_truth:
+  - "projects/praxis-dynamic-form/README.md"
+  - "projects/praxis-dynamic-form/docs/dynamic-form-authoring-document-semantics.md"
+  - "projects/praxis-dynamic-form/docs/dynamic-form-rules-authoring-plan.md"
+  - "projects/praxis-dynamic-form/src/lib/layout-editor/praxis-layout-editor.json-api.md"
+  - "projects/praxis-core/src/lib/models/form/form-layout-items.model.ts"
+  - "projects/praxis-core/src/lib/models/form/rule-property.schema.ts"
+---
+
+# Dynamic Form Layout Items and Visual Blocks
+
+`FormColumn.items` é o contrato canônico para ordenar campos da API e conteúdo visual dentro de uma coluna do Dynamic Form.
+
+A regra principal é simples: campos de negócio continuam em `fieldMetadata[]`; conteúdo visual explicativo entra em `columns[].items[]` como `kind: 'richContent'`.
+
+## Modelo mental
+
+```mermaid
+flowchart TD
+  metadata["fieldMetadata[]<br/>campos vindos do DTO/API"] --> fieldItem["items[]<br/>kind: field"]
+  richContent["RichContentDocument<br/>texto, aviso, separador ou card"] --> visualItem["items[]<br/>kind: richContent"]
+  fieldItem --> column["FormColumn.items[]<br/>ordem canônica"]
+  visualItem --> column
+  column --> runtime["Dynamic Form runtime"]
+  column --> editor["Layout editor"]
+  fieldItem --> payload["formData / payload HTTP"]
+  visualItem --> presentation["apenas apresentação"]
+```
+
+Use `items[]` quando a coluna precisa misturar campos e blocos visuais na mesma ordem. Use `fields[]` apenas como projeção derivada para compatibilidade e migração.
+
+## Contrato mínimo
+
+```json
+{
+  "sections": [
+    {
+      "id": "identity",
+      "rows": [
+        {
+          "columns": [
+            {
+              "id": "identity-main",
+              "items": [
+                {
+                  "kind": "richContent",
+                  "id": "identity-introduction-block",
+                  "layout": "block",
+                  "document": {
+                    "schemaVersion": 1,
+                    "nodes": [
+                      {
+                        "type": "paragraph",
+                        "text": "Revise os dados principais antes de salvar."
+                      }
+                    ]
+                  }
+                },
+                {
+                  "kind": "field",
+                  "id": "field-nome",
+                  "fieldName": "nome"
+                },
+                {
+                  "kind": "field",
+                  "id": "field-email",
+                  "fieldName": "email"
+                }
+              ],
+              "fields": ["nome", "email"]
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "fieldMetadata": [
+    { "name": "nome", "label": "Nome", "editorType": "text" },
+    { "name": "email", "label": "E-mail", "editorType": "email" }
+  ]
+}
+```
+
+Neste exemplo, `identity-introduction-block` é conteúdo visual. Ele não tem entrada em `fieldMetadata[]`, não cria `FormControl` e não participa do payload de submit.
+
+## Campos da API
+
+“Adicionar campo da API” significa reinserir no layout um campo que já existe em `fieldMetadata[]`, mas ainda não aparece em `columns[].items[]` como `kind: 'field'`.
+
+Essa ação não cria metadado novo. Ela apenas escreve um item de campo no layout:
+
+```json
+{
+  "kind": "field",
+  "id": "field-cargo",
+  "fieldName": "cargo"
+}
+```
+
+O editor deve manter `fields[]` sincronizado como projeção:
+
+```json
+{
+  "items": [
+    { "kind": "field", "id": "field-nome", "fieldName": "nome" },
+    { "kind": "field", "id": "field-cargo", "fieldName": "cargo" }
+  ],
+  "fields": ["nome", "cargo"]
+}
+```
+
+Campos já alocados no layout não devem aparecer novamente na lista de disponíveis. Quando um campo é removido do layout, ele volta para “Campos da API”.
+
+## Blocos visuais e presets
+
+“Adicionar bloco visual” cria um item `kind: 'richContent'` com um `RichContentDocument` válido. Presets como texto, aviso, separador e card informativo são atalhos de autoria: o preset não é persistido como semântica de runtime.
+
+Forma persistida correta:
+
+```json
+{
+  "kind": "richContent",
+  "id": "contact-guidance-block",
+  "layout": "block",
+  "document": {
+    "schemaVersion": 1,
+    "nodes": [
+      {
+        "type": "callout",
+        "tone": "info",
+        "title": "Dados de contato",
+        "body": "Use um e-mail corporativo e telefone com DDD."
+      }
+    ]
+  }
+}
+```
+
+Evite persistir IDs que pareçam contrato de preset, como `preset-notice-contact`. Prefira nomes de domínio, como `contact-guidance-block`. Isso deixa claro que o contrato persistido é `richContent`, não `presetId`.
+
+## Regras para visual blocks
+
+Blocos visuais podem participar de `formRules` como alvo `targetType: "visualBlock"`. Isso permite alterar visibilidade, classe, estilo e, de forma controlada, partes textuais do bloco conforme o estado do formulario.
+
+A regra continua visual-only: ela nunca transforma o bloco em campo, nunca cria `FormControl`, nunca escreve em `fieldMetadata[]` e nunca entra em `formData` ou no payload HTTP.
+
+### Propriedades permitidas
+
+| Propriedade | Uso seguro |
+| --- | --- |
+| `visible` / `hidden` | Exibir ou ocultar o bloco conforme a condicao. |
+| `layout` | Alternar entre `block` e `inline`, quando o host aceita essa variacao. |
+| `className` / `rootClassName` | Aplicar classes CSS controladas pelo host/design system. |
+| `style` | Aplicar estilo inline saneado pelo runtime. |
+| `text` | Sobrescrever texto apenas em documento simples ou node de texto identificado. |
+| `title` | Sobrescrever titulo apenas em documento simples, card/media/timeline suportado ou node identificado. |
+| `message` | Sobrescrever mensagem apenas em documento simples, card/media suportado ou node identificado. |
+| `textNodeId` / `titleNodeId` / `messageNodeId` | Selecionar explicitamente o node que recebera `text`, `title` ou `message`. |
+
+O editor visual deve mostrar para usuarios finais as propriedades de negocio (`text`, `title`, `message`, `visible`, `style` etc.) e tratar `*NodeId` como detalhe tecnico guiado por seletor de node. Quando o documento tem mais de um texto possivel, prefira sempre node explicito.
+
+Exemplo com nodes explicitos:
+
+```json
+{
+  "formRules": [
+    {
+      "id": "employee-guidance-by-status",
+      "targetType": "visualBlock",
+      "targets": ["employee-guidance-block"],
+      "effect": {
+        "condition": { "===": [{ "var": "ativo" }, false] },
+        "properties": {
+          "title": "Revise a inativacao",
+          "titleNodeId": "custom-title",
+          "message": "Informe justificativa antes de salvar.",
+          "messageNodeId": "custom-message",
+          "className": "employee-guidance-warning"
+        },
+        "propertiesWhenFalse": {
+          "title": "Cadastro ativo",
+          "titleNodeId": "custom-title",
+          "message": "Mantenha os dados funcionais atualizados.",
+          "messageNodeId": "custom-message",
+          "className": "employee-guidance-success"
+        }
+      }
+    }
+  ]
+}
+```
+
+### Exemplos por dominio
+
+Use exemplos de dominio quando a regra muda texto/estilo para orientar o usuario sem alterar payload. Esses exemplos devem continuar dentro do contrato `visualBlock`: nada de `document`, HTML livre, handlers ou campos falsos em `fieldMetadata`.
+
+#### RH: orientacao de funcionario inativo
+
+```json
+{
+  "formRules": [
+    {
+      "id": "employee-inactive-guidance",
+      "targetType": "visualBlock",
+      "targets": ["profile-status-card"],
+      "effect": {
+        "condition": { "===": [{ "var": "ativo" }, false] },
+        "properties": {
+          "title": "Funcionario inativo",
+          "titleNodeId": "profile-status-title",
+          "message": "Revise desligamento, acessos e justificativa antes de salvar.",
+          "messageNodeId": "profile-status-message",
+          "className": "employee-status-card employee-status-card--warning"
+        },
+        "propertiesWhenFalse": {
+          "title": "Funcionario ativo",
+          "titleNodeId": "profile-status-title",
+          "message": "Mantenha cargo, departamento e contatos atualizados.",
+          "messageNodeId": "profile-status-message",
+          "className": "employee-status-card employee-status-card--ok"
+        }
+      }
+    }
+  ]
+}
+```
+
+#### Compras: aviso de fornecedor critico
+
+```json
+{
+  "formRules": [
+    {
+      "id": "supplier-risk-guidance",
+      "targetType": "visualBlock",
+      "targets": ["supplier-risk-notice"],
+      "effect": {
+        "condition": { "in": [{ "var": "riscoFornecedor" }, ["alto", "critico"]] },
+        "properties": {
+          "message": "Fornecedor exige aprovacao de compliance antes da emissao do pedido.",
+          "messageNodeId": "message",
+          "className": "supplier-risk-notice supplier-risk-notice--critical"
+        },
+        "propertiesWhenFalse": {
+          "message": "Fornecedor sem bloqueios criticos para este pedido.",
+          "messageNodeId": "message",
+          "className": "supplier-risk-notice supplier-risk-notice--neutral"
+        }
+      }
+    }
+  ]
+}
+```
+
+#### Atendimento: copy operacional por prioridade
+
+```json
+{
+  "formRules": [
+    {
+      "id": "ticket-priority-copy",
+      "targetType": "visualBlock",
+      "targets": ["ticket-sla-guidance"],
+      "effect": {
+        "condition": { "===": [{ "var": "prioridade" }, "alta"] },
+        "properties": {
+          "text": "Prioridade alta: confirme impacto, prazo de SLA e responsavel de escalacao.",
+          "textNodeId": "text",
+          "rootClassName": "ticket-sla-guidance ticket-sla-guidance--high"
+        },
+        "propertiesWhenFalse": {
+          "text": "Registre contexto suficiente para triagem e acompanhamento.",
+          "textNodeId": "text",
+          "rootClassName": "ticket-sla-guidance ticket-sla-guidance--standard"
+        }
+      }
+    }
+  ]
+}
+```
+
+### Limites do override textual
+
+O suporte a `text`, `title` e `message` nao e um editor livre de documento rico. Ele e propositalmente limitado para evitar corrupcao estrutural do `RichContentDocument`.
+
+O runtime aplica override somente quando encontra um alvo seguro:
+
+- documento simples com um unico node textual ou um unico container simples;
+- node com id convencional `text`, `title` ou `message`;
+- node indicado explicitamente por `textNodeId`, `titleNodeId` ou `messageNodeId`;
+- nodes aninhados em `compose`, `card` ou `mediaBlock` quando o tipo suporta aquela propriedade.
+
+O runtime nao deve aceitar HTML arbitrario, handlers, URLs inseguras nem substituicao de documento inteiro via regra. Se o documento for ambiguo e nao houver node identificado, a regra textual deve ser ignorada de forma segura; a configuracao deve aparecer em diagnostico/editor como limite de autoria, nao como falha silenciosa.
+
+### DnD, alinhamento e UX
+
+Ao arrastar visual blocks entre campos, a experiencia esperada e a mesma dos campos:
+
+- preview e placeholder devem preservar largura, altura aproximada e espaçamento da coluna;
+- drop feedback deve indicar o ponto de insercao, nao apenas a coluna;
+- o bloco inserido entre campos deve manter alinhamento horizontal e ritmo vertical;
+- handles de arraste devem ser claros em hover/focus e nao disparar eventos dos controles do formulario;
+- selects, menus e campos interativos proximos nao devem abrir popup quando o usuario inicia drag pelo handle.
+
+No runtime, `kind: "richContent"` participa do mesmo ritmo vertical dos campos: o bloco ocupa a largura da coluna e reserva a margem de `--pfx-field-gap`, assim como os campos Material. O conteudo interno continua livre para ser texto, aviso, divisor ou card, mas exemplos publicos nao devem usar cards altos como substitutos de linhas sincronizadas entre colunas; quando o bloco for um painel explicativo grande, prefira uma linha dedicada, coluna lateral consistente ou bloco full-width.
+
+O teste de aceitacao deve validar tanto ordem do JSON quanto resultado visual no runtime. Em formularios reais, mova campo com regras entre secoes e confirme que a regra continua referenciando o campo por nome/id canonico, nao por indice visual.
+
+### LLM e regras
+
+LLMs podem sugerir regras para `visualBlock`, mas devem operar dentro do mesmo contrato:
+
+- escrever apenas `formRules`, nunca `formRulesState`;
+- usar somente propriedades publicadas em `RULE_PROPERTY_SCHEMA.visualBlock`;
+- referenciar apenas targets existentes em `columns[].items[]`;
+- usar `textNodeId`, `titleNodeId` ou `messageNodeId` quando o bloco tiver documento composto;
+- marcar a sugestao como pendente de revisao humana antes de persistir;
+- deixar o editor gerar ou reconciliar `formRulesState` apos aceite.
+
+Quando a regra sugerida nao faz round-trip para o builder visual, ela continua valida para runtime apenas se passar pelo validador de regras; nesse caso a UI deve trata-la como `runtime-only` e explicar a limitacao.
+
+## Submit e payload
+
+O runtime deve separar dados de negócio de conteúdo visual:
+
+| Superfície | Inclui campo da API | Inclui bloco visual |
+| --- | --- | --- |
+| `fieldMetadata[]` | Sim | Não |
+| `FormControl` | Sim | Não |
+| `formData` | Sim | Não |
+| Payload HTTP | Sim, conforme política do campo | Não |
+| `columns[].items[]` | Sim | Sim |
+| `columns[].fields[]` | Sim, como projeção | Não |
+
+Blocos visuais também não usam `source`, `transient` ou `submitPolicy`. Essas propriedades pertencem a campos. Se a experiencia precisa de valor, validacao, regras de campo ou leitura em `rawFormData`, use um campo local em `fieldMetadata[]`; se precisa apenas de orientacao visual ou texto condicionado, use `visualBlock`.
+
+## Responsividade e WCAG
+
+Blocos visuais entram no fluxo da coluna, então precisam respeitar o mesmo espaço dos campos.
+
+Use estas regras em exemplos e authoring corporativo:
+
+- Se um bloco usa composição horizontal com texto longo, habilite quebra de linha com `wrap: true` quando o node suportar.
+- Não coloque ação visual sem operação real conectada pelo host.
+- Não use bloco visual para capturar dado de negócio.
+- Não esconda validação, política ou decisão crítica apenas em texto decorativo.
+- Preserve contraste, foco navegável e nomes acessíveis quando o bloco incluir ações, links ou ícones.
+- Prefira texto curto, títulos objetivos e conteúdo que continue legível em zoom alto.
+
+## Quando usar
+
+Use bloco visual quando a coluna precisa de orientação, separação contextual, aviso operacional ou resumo informativo que pertence ao layout do formulário, mas não ao DTO.
+
+Use campo da API quando o dado já existe no contrato backend e apenas foi removido ou ocultado do layout atual.
+
+Use campo local, em ciclo separado, quando o dado precisa existir no formulário, mas não pertence ao DTO de submit por padrão. Esse caso exige `fieldMetadata[]` com semântica explícita de campo local/transiente.
+
+## Checklist enterprise
+
+Antes de publicar um exemplo ou configuração:
+
+- `items[]` é a fonte canônica da ordem da coluna.
+- `fields[]` contém apenas nomes de campos e está sincronizado com os itens `kind: 'field'`.
+- Blocos visuais não aparecem em `fieldMetadata[]`.
+- Blocos visuais não aparecem no payload de submit.
+- Regras de visual block alteram apenas apresentacao, classe, estilo ou texto seguro; elas nao criam valor persistivel.
+- Overrides textuais em documentos compostos usam node id explicito.
+- Regras sugeridas por LLM sao revisadas antes de persistir e nao escrevem `formRulesState`.
+- IDs de blocos descrevem o domínio, não o preset usado para criá-los.
+- Exemplos públicos declaram dependência operacional em `@praxisui/dynamic-form` com suporte a `FormColumn.items` e `richContent`.
+- Composições horizontais com texto longo foram revisadas em viewport móvel e zoom alto.
+- A documentação do host deixa claro qual ação é demonstrável e qual conteúdo é apenas apresentação.
+
+## Exemplo completo
+
+Use o recipe oficial como referência operacional completa:
+
+`examples/ai-recipes/praxis-dynamic-page.visual-block-presets-form.json`
+
+Ele demonstra campos remotos, blocos `richContent`, projeção `fields[]`, ausência de metadado para blocos visuais e uma página Dynamic Page preparada para catálogo público.