---
title: "praxis-layout-editor JSON API (Canonical)"
slug: "praxis-layout-editor-json-api"
doc_type: "api-reference"
component: "praxis-layout-editor"
document_kind: "json-api-canonical"
reference_mode: "canonical"
contract_format: "json"
contract_source: "runtime-and-code"
description: "Referencia canonica do contrato JSON do componente praxis-layout-editor."
category: "components"
sub_category: "config-editor"
audience:
  - "frontend"
  - "architect"
  - "platform-team"
level: "advanced"
status: "active"
owner: "praxis-ui"
source_of_truth:
  - "projects/praxis-dynamic-form/src/lib/layout-editor/layout-editor.component.ts"
  - "projects/praxis-dynamic-form/src/lib/layout-editor/layout-editor.component.spec.ts"
  - "projects/praxis-core/src/lib/models/form/form-config.model.ts"
source_of_truth_last_verified: "2026-03-05"
last_updated: "2026-03-05"
toc: true
sidebar: true
tags:
  - "json-api"
  - "canonical-contract"
  - "praxis-layout-editor"
api_stability: "canonical"
schema_verified: true
runtime_verified: false
editor_coverage_verified: false
runtime_scope: "public"
legacy_paths_present: false
has_known_mismatches: true
related_components:
  - "praxis-table"
---

# praxis-layout-editor

Este documento e a referencia canonica da API JSON de praxis-layout-editor.

## Summary

- Tipo documental: API reference canonica de contrato JSON.
- Source of truth: runtime e codigo declarados no frontmatter.
- Objetivo operacional: consulta rapida, auditavel e deterministica sob pressao.
- Resumo funcional: `praxis-layout-editor` é o editor visual de estrutura de formulário (`sections/rows/columns/items`) com drag and drop. Ele recebe um `FormConfig`, ordena campos da API e blocos visuais em `FormColumn.items[]`, mantém `fields[]` apenas como projeção de campos e emite versões atualizadas do layout conforme a interação.

## Scope and positioning

- Escopo: contrato JSON publico e limites de comportamento observavel.
- Fora de escopo: tutorial de adocao e walkthrough operacional detalhado.
- Posicionamento: referencia canonicamente governada para consumidores, arquitetos e mantenedores.

## Source of truth

| Source | Kind | Notes |
| --- | --- | --- |
| projects/praxis-dynamic-form/src/lib/layout-editor/layout-editor.component.ts | runtime-code | Source de implementacao declarado no repositorio. |
| projects/praxis-dynamic-form/src/lib/layout-editor/layout-editor.component.spec.ts | runtime-code | Source de implementacao declarado no repositorio. |
| projects/praxis-core/src/lib/models/form/form-config.model.ts | runtime-code | Source de implementacao declarado no repositorio. |

## Support legend

- Active: suportado e observado no runtime atual.
- Partial: suporte parcial, com restricoes conhecidas.
- Declared-only: declarado em tipos/schema sem ligacao runtime confirmada.
- Schema-only: presente em schema/modelo sem confirmacao de execucao.
- Deprecated: mantido por compatibilidade legada com migracao prevista.

## Contract classification

### Canonical paths (public contract)

| Path | Type | Required | Default | Status | Notes |
| --- | --- | --- | --- | --- | --- |
| `sections[]` | `FormSection[]` | Sim | `[]` | Active | Base estrutural do canvas. |
| `sections[].rows[]` | `FormRow[]` | Sim | `[]` | Active | Grade interna por seção. |
| `sections[].rows[].columns[]` | `FormColumn[]` | Sim | `[]` | Active | Unidades de drop de campos e blocos visuais. |
| `sections[].rows[].columns[].items[]` | `FormLayoutItem[]` | Não | derivado de `fields[]` quando ausente | Active | Ordem canônica de campos e blocos visuais. |
| `sections[].rows[].columns[].fields[]` | `string[]` | Não | projeção de `items[]` | Active | Projeção/migração dos itens de campo; não representa bloco visual. |
| `fieldMetadata[]` | `FieldMetadata[]` | Sim | `[]` | Active | Fonte para lista de campos disponíveis. |
| `fieldMetadata[].formHidden` | `boolean` | Não | `false` | Active | Campos ocultos não aparecem na palette. |
| `actions/behavior/messages/hooks/api/...` | objeto | Não | n/a | Declared-only | Não manipulados neste editor de layout. |

### Supported legacy paths

Nenhum path legado suportado foi identificado nesta revisão baseada em evidência textual preservada.

### Internal-only paths

| Path | Internal consumer | Runtime presence | Public support | Notes |
| --- | --- | --- | --- | --- |
| not-yet-mapped | not-yet-verified | not-yet-verified | No | Caminhos internos nao mapeados explicitamente nesta revisao automatizada. |

### Experimental paths

| Path | Enablement (flag/guard) | Stability | Rollout notes | Notes |
| --- | --- | --- | --- | --- |
| not-yet-mapped | not-yet-verified | Experimental | not-yet-verified | Registrar somente quando houver evidencia em runtime/codigo. |

## Overview

Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecnico existente. O conteudo detalhado anterior foi preservado para manter rastreabilidade historica e reduzir perda de contexto.

## Public contract surface

### Top-level configuration blocks

| Block | Purpose | Required | Merge strategy | Notes |
| --- | --- | --- | --- | --- |
| sections[] | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 4 path(s) mapeado(s), status predominante Active. |
| fieldMetadata[] | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 2 path(s) mapeado(s), status predominante Active. |
| actions/behavior/messages/hooks/api/ | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Declared-only. |

### Nested configuration blocks

| Path | Type | Required | Default | Constraints | Notes |
| --- | --- | --- | --- | --- | --- |
| `sections[]` | `FormSection[]` | Sim | `[]` | component-defined | Base estrutural do canvas. |
| `sections[].rows[]` | `FormRow[]` | Sim | `[]` | component-defined | Grade interna por seção. |
| `sections[].rows[].columns[]` | `FormColumn[]` | Sim | `[]` | component-defined | Unidades de drop de campos e blocos visuais. |
| `sections[].rows[].columns[].items[]` | `FormLayoutItem[]` | Não | derivado de `fields[]` quando ausente | component-defined | Ordem canônica de campos e blocos visuais. |
| `sections[].rows[].columns[].fields[]` | `string[]` | Não | projeção de `items[]` | component-defined | Projeção/migração dos itens de campo. |
| `fieldMetadata[]` | `FieldMetadata[]` | Sim | `[]` | component-defined | Fonte para lista de campos disponíveis. |
| `fieldMetadata[].formHidden` | `boolean` | Não | `false` | component-defined | Campos ocultos não aparecem na palette. |
| `actions/behavior/messages/hooks/api/...` | objeto | Não | n/a | component-defined | Não manipulados neste editor de layout. |

### Input bindings

| Binding/Path | Type | Required | Source | Runtime normalization | Notes |
| --- | --- | --- | --- | --- | --- |
| `config` | `FormConfig` | Sim | component-input | not-yet-verified | Fonte do layout e dos campos disponiveis. |

### Output events

| Event | Payload | Trigger | Stability | Notes |
| --- | --- | --- | --- | --- |
| `configChange` | `FormConfig` | Toda alteracao estrutural (add/remove/reorder/drop/update style). | Partial | Preservado da documentação anterior. |
| `select` | `{ type, sectionIndex?, rowIndex?, columnIndex?, fieldName? }` | Alteracao de foco/selecao no editor. | Partial | Preservado da documentação anterior. |

### External side channels

| Channel | Direction | Contract | Failure mode | Notes |
| --- | --- | --- | --- | --- |
| host/services/storage | bidirectional | see-detailed-api | not-yet-verified | Side channels dependem do componente e do host consumidor. |

### Host/runtime dependencies

| Dependency | Required | Environment | Purpose | Notes |
| --- | --- | --- | --- | --- |
| see-source-of-truth | true | browser/dev/prod/ssr | runtime linkage | Confirmar por componente quando necessario. |

## Coverage matrix

| Surface | Verified | Coverage status | Evidence | Notes |
| --- | --- | --- | --- | --- |
| Runtime | false | Partial | source_of_truth + conteudo preservado | Revisao estrutural concluida; validacao comportamental fina pode exigir follow-up. |
| Schema/Types | true | Partial | interfaces/modelos citados | Mapeamento formal de todos os campos ainda pode requerer refinamento. |
| Editor/Tooling | false | Partial | secoes de editor quando presentes | Cobertura de editor/tooling nem sempre confirmada por evidencia direta. |

## Runtime coverage boundaries

- Cobertura consolidada com base em documentacao existente e source of truth declarado.
- Comportamentos fora de evidencia direta foram marcados como not-yet-verified ou Partial.
- Compatibilidade legada, quando detectada, foi separada em classificacao explicita.

## Resolution model

### Merge order

1. defaults do componente
2. contrato JSON recebido
3. overrides de host/runtime
4. normalizacoes internas

### Fallback order

contrato explicito -> aliases legados (quando suportados) -> defaults internos -> comportamento seguro

### Override points

- inputs publicos do componente
- configuracao JSON de runtime
- integracoes de host (servicos/tokens/adapters)

### Runtime normalization

Campos e aliases preservados do documento anterior devem convergir progressivamente para paths canonicos declarados.

### Precedence rules

Quando houver conflito entre alias e path canonico, priorizar path canonico e manter alias apenas para backward compatibility.

## Validation and error semantics

### Validation model

| Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
| --- | --- | --- | --- | --- |
| see-detailed-api | runtime | warn-or-reject | not-yet-standardized | Semantica de validacao preservada do documento anterior. |

### Error semantics

Erros devem ser classificados em warnings recuperaveis versus falhas bloqueantes. Quando a evidencia nao estiver explicita, tratar como not yet verified.

### Fail-open / fail-closed behavior

| Condition | Mode | Runtime behavior | Consumer impact |
| --- | --- | --- | --- |
| invalid-or-unknown-field | component-defined | not-yet-verified | Variavel por componente; requer verificacao em runtime. |

### Invalid or unknown field handling

- Campos desconhecidos: comportamento depende da estrategia do componente (ignore, warn ou reject).
- Campos invalidos: podem gerar fallback, warning ou falha conforme implementacao.
- Registrar divergencias observadas em Known limitations and mismatches.

### Runtime warnings vs hard failures

| Condition | Severity | Observability | Consumer action |
| --- | --- | --- | --- |
| partial-or-declared-only-coverage | warning | logs/eventos do componente | confirmar ligacao runtime antes de uso critico |

## Detailed API

### Preserved technical reference (normalized from previous revision)

### 1. Visao Geral e Quando Usar
`praxis-layout-editor` e o editor visual de estrutura de formulario (`sections/rows/columns/items`) com drag and drop.
Ele recebe um `FormConfig`, ordena campos da API e blocos visuais em
`FormColumn.items[]` e emite versoes atualizadas do layout conforme a
interacao.

Use quando precisar de:
- montagem visual de secoes e colunas;
- distribuicao de campos e blocos visuais por drag and drop;
- reordenacao de secoes, campos e itens visuais;
- feedback de selecao de elemento (section/row/column/field/visualBlock) para editores auxiliares.

### 2. API do Componente

#### 2.1 Inputs
| Input | Tipo | Obrigatorio | Status | Comportamento |
| --- | --- | --- | --- | --- |
| `config` | `FormConfig` | Sim | Active | Fonte do layout e dos campos disponiveis. |

#### 2.2 Outputs
| Output | Payload | Quando emite |
| --- | --- | --- |
| `configChange` | `FormConfig` | Toda alteracao estrutural (add/remove/reorder/drop/update style). |
| `select` | `{ type, sectionIndex?, rowIndex?, columnIndex?, fieldName? }` | Alteracao de foco/selecao no editor. |

### 3. Cobertura JSON de `config`
| Caminho | Status | Runtime notes |
| --- | --- | --- |
| `sections[]` | Active | Base estrutural do canvas. |
| `sections[].rows[]` | Active | Grade interna por secao. |
| `sections[].rows[].columns[]` | Active | Unidades de drop de campos. |
| `sections[].rows[].columns[].items[]` | Active | Ordem canônica de campos e blocos visuais. |
| `sections[].rows[].columns[].fields[]` | Active | Projeção/migração dos itens de campo. |
| `fieldMetadata[]` | Active | Fonte para lista de campos disponíveis. |
| `fieldMetadata[].formHidden` | Active | Campos ocultos não aparecem na palette. |
| `actions/behavior/messages/hooks/api/...` | Declared-only | Não manipulados neste editor de layout. |

Extensoes de runtime no editor (fora do contrato canonico):
- `section.gapCustomized` (controle interno de aplicacao de gap).

### 4. Mapeamento de Comportamento
- Palette de campos:
  - `availableFields` = `fieldMetadata` não oculto e ainda não alocado em `sections[].rows[].columns[].items[]` como item `kind: 'field'`.
  - A ação "Campos da API" reinsere apenas campos já existentes em `fieldMetadata[]`; ela grava `kind: 'field'` em `items[]` e atualiza `fields[]` somente como projeção derivada.
  - Estado colapsado da palette é persistido em `LayoutPrefsService`.
- Blocos visuais:
  - A ação "Adicionar bloco visual" oferece presets de authoring internos para texto, aviso, separador, card informativo, `callout`, `keyValueList`, prova de contrato, `recordSummary`, `disclosure` e `emptyState`.
  - Cada preset gera `RichContentDocument` válido em item `kind: 'richContent'`; presets não criam novo `kind`, não escrevem em `fieldMetadata[]` e não entram no payload de submit.
  - Presets como `emptyState` já podem semear `actionButton`, e o runtime do formulário encaminha essas ações pela mesma trilha de `customAction/globalAction` usada pelos demais CTAs do componente.
  - O guia didático completo está em `projects/praxis-dynamic-form/docs/layout-items-visual-blocks.md`.
- Drag and drop:
  - move entre colunas, entre linhas/secoes e entre palette/canvas.
  - reordenacao de secoes via `dropSection`.
- Operacoes estruturais:
  - `addSection`, `removeSection`, `onSectionUpdated`, `onApplyStyleToAll`.
- Emissao:
  - toda alteracao gera novo `FormConfig` em `configChange`.

### 5. Exemplo Minimo
```html
<praxis-layout-editor
  [config]="editedConfig"
  (configChange)="onLayoutConfigChange($event)"
></praxis-layout-editor>
```

### 6. Exemplo Corporativo (inspector lateral por selecao)
```html
<praxis-layout-editor
  [config]="editedConfig"
  (configChange)="editedConfig = $event"
  (select)="onLayoutSelect($event)"
></praxis-layout-editor>
```

```ts
onLayoutSelect(sel: any) {
  if (sel?.type === 'column') {
    this.openColumnInspector(sel.sectionIndex, sel.rowIndex, sel.columnIndex);
  }
}
```

### 7. Problemas Comuns e Armadilhas
1. Passar `config` sem `sections` ou sem `fieldMetadata`.
Correcao: envie objeto completo; faltas reduzem operacoes do editor.

2. Esperar que campos com `formHidden=true` aparecam na palette.
Correcao: esses campos sao filtrados por design.

3. Alterar estado externo sem refletir de volta em `[config]`.
Correcao: trate `configChange` como fonte oficial de atualizacao no host.

4. Assumir que este editor atualiza `actions/messages/behavior`.
Correcao: ele cobre layout; demais blocos sao editados em componentes dedicados.

5. Ignorar `select` e perder contexto de qual elemento esta em foco.
Correcao: conecte `select` com painel lateral/inspector quando houver.

6. Persistir extensoes internas (`gapCustomized`) como se fossem contrato estavel.
Correcao: trate como detalhe de editor; sanitize se necessario no pipeline.

### 8. Referencias Cruzadas
- Orquestrador superior: `projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts`
- Componentes auxiliares: `section-configurator.component.ts`, `field-configurator.component.ts`
- Modelo base: `projects/praxis-core/src/lib/models/form/form-config.model.ts`

### 9. Premissas
- O host e responsavel por persistencia e versionamento da configuracao resultante.
- Integridade de `fieldMetadata.name` deve ser preservada para evitar perda de mapeamento.
- Validacao de regras de negocio nao e responsabilidade deste editor visual.

### 10. Relatorio de Validacao Estrutural
- Visao geral: PASS
- Inputs/outputs: PASS
- Cobertura de JSON por status: PASS
- Mapeamento de comportamento: PASS
- Exemplo minimo: PASS
- Exemplo corporativo: PASS
- Problemas comuns (>=5): PASS
- Referencias cruzadas: PASS
- Premissas explicitas: PASS

## JSON path index

| Path | Type | Required | Default | Status | Notes |
| --- | --- | --- | --- | --- | --- |
| `sections[]` | `FormSection[]` | Sim | `[]` | Active | Base estrutural do canvas. |
| `sections[].rows[]` | `FormRow[]` | Sim | `[]` | Active | Grade interna por seção. |
| `sections[].rows[].columns[]` | `FormColumn[]` | Sim | `[]` | Active | Unidades de drop de campos e blocos visuais. |
| `sections[].rows[].columns[].items[]` | `FormLayoutItem[]` | Não | derivado de `fields[]` quando ausente | Active | Ordem canônica de campos e blocos visuais. |
| `sections[].rows[].columns[].fields[]` | `string[]` | Não | projeção de `items[]` | Active | Projeção/migração dos itens de campo. |
| `fieldMetadata[]` | `FieldMetadata[]` | Sim | `[]` | Active | Fonte para lista de campos disponíveis. |
| `fieldMetadata[].formHidden` | `boolean` | Não | `false` | Active | Campos ocultos não aparecem na palette. |
| `actions/behavior/messages/hooks/api/...` | objeto | Não | n/a | Declared-only | Não manipulados neste editor de layout. |

## Events

| Event | Payload | Trigger | Stability | Notes |
| --- | --- | --- | --- | --- |
| `configChange` | `FormConfig` | Toda alteracao estrutural (add/remove/reorder/drop/update style). | Partial | Preservado da documentação anterior. |
| `select` | `{ type, sectionIndex?, rowIndex?, columnIndex?, fieldName? }` | Alteracao de foco/selecao no editor. | Partial | Preservado da documentação anterior. |

## Styling API

| Token/Class | Scope | Purpose | Notes |
| --- | --- | --- | --- |
| see-detailed-api | component | styling/runtime | Consolidar naming canonico quando aplicavel. |

## Editor and tooling notes

- Cobertura de editor/tooling foi separada da cobertura de runtime para evitar confusao de suporte.
- Quando nao houver evidencia direta no codigo, o status deve permanecer not yet verified.

## Examples

### Minimal valid

```json
{}
```

### Typical/common

```json
{}
```

### Advanced

```json
{}
```

### Enterprise scenario

```json
{}
```

## Known limitations and mismatches

| Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
| --- | --- | --- | --- | --- | --- |
| coverage/mapping | Evidência textual preservada indica itens Partial/Declared-only. | Cobertura confirmada por evidência runtime + schema + editor. | Pode gerar uso de paths não totalmente ligados. | to-be-linked | next-doc-cycle |

## Compatibility and migration notes

| Concern | Affected versions | Migration action | Deadline | Notes |
| --- | --- | --- | --- | --- |
| legacy aliases and mixed status vocabulary | pre-canonical docs | unificar para taxonomia canonica (Active/Partial/Declared-only/...) | next-doc-cycle | manter backward compatibility documentada |

## Source references

| Source type | Path/URL | Why it is source of truth | Last verified (YYYY-MM-DD) | Notes |
| --- | --- | --- | --- | --- |
| local-file | projects/praxis-dynamic-form/src/lib/layout-editor/layout-editor.component.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
| local-file | projects/praxis-dynamic-form/src/lib/layout-editor/layout-editor.component.spec.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
| local-file | projects/praxis-core/src/lib/models/form/form-config.model.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
