---
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: "13 min"
estimated_setup_time: "20 min"
last_updated: "2026-06-16"
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, card informativo e prova de contrato são atalhos de autoria: o preset não é persistido como semântica de runtime.

Use o preset de prova de contrato quando a UI precisar explicar por que `items[]` é a ordem canônica e `fields[]` é apenas projeção derivada. Ele materializa uma `keyValueList` empilhada, sem criar novo `kind`, sem escrever em `fieldMetadata[]` e sem entrar no payload de submit.

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.

### Tema, tokens e contraste

Visual blocks hospedados pelo Dynamic Form devem herdar a identidade visual do host, nao o fallback visual isolado de `@praxisui/rich-content`.

O caminho preferencial continua sendo o bridge de tema do host:

- hosts Material M3 devem expor `--mat-sys-*` e `--md-sys-color-*` no mesmo escopo visual;
- hosts Praxis/landing podem expor tokens genericos como `--foreground`, `--muted-foreground`, `--card`, `--surface-dim`, `--border`, `--primary`, `--primary-container` e `--primary-container-fg`;
- Dynamic Form resolve esses tokens para `--pfx-editorial-form-*` e aplica a superficie resultante aos blocos `richContent`;
- regras de visual block podem publicar `className` semantico, mas nao devem hardcodar cor para corrigir tema.

Ao validar um formulario com `kind: "richContent"`, teste claro e escuro no mesmo host. No minimo confira card, titulo, subtitulo, texto secundario, badge, metricas e progress label. O criterio operacional e WCAG AA para texto normal: contraste igual ou superior a `4.5:1` entre texto e superficie efetiva.

Se um visual block ficar ilegivel no tema escuro, investigue primeiro o escopo dos tokens do host. O erro mais comum e misturar uma superficie escura do shell com fallbacks claros de `rich-content`, ou expor `--mat-sys-*` sem alias compativel para `--md-sys-color-*`.

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.
