praxis-dynamic-form

Este documento e a referencia canonica da API JSON de praxis-dynamic-form.

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 herdado: Referencia canonica da JSON API do praxis-dynamic-form, com foco em:

Canonical authoring semantics

• Em Geral → Dados do formulário, Modo de dados e Modo de exibição são preferências independentes.

• bindings.presentationModeGlobal reutiliza o input runtime existente: true = Apresentação (efetiva somente em view), false = Campos de formulário, null/ausência = Automático, seguindo layoutPolicy.

• Em replace-all, omitir a preferência remove o override anterior; false deve ser preservado. Não existe um quarto valor em bindings.mode.

• O Page Builder projeta a preferência nos inputs do widget, preservando ausência de config em formulários schema-driven. No editor do runtime, Apply/Save também publicam mode e presentationModeGlobal em configPatchChange.inputPatch.

• contextSnapshot.presentation continua reservado aos estilos (tipografia, densidade e alinhamento), editáveis nos dois caminhos pela aba Estilo da apresentação; não é o seletor de ativação. O Filter Form não oferece o seletor de exibição porque seu runtime não suporta apresentação.

• DynamicFormAuthoringDocument e o snapshot canonico completo de autoria de praxis-dynamic-form.

• Quando aplicado por fluxos canonicos de editor, config, bindings e contextSnapshot possuem semantica replace-all.

• Ausencia de bindings.mode limpa o binding persistido e restaura o modo default efetivo do host.

• Ausencia de backConfig, presentation ou schemaPrefs no documento canonico significa remocao explicita do bloco ausente.

• backConfig, presentation e schemaPrefs permanecem fora de FormConfig, mas fazem parte oficialmente do documento autoral persistivel em contextSnapshot.

• APIs de compatibilidade como applyConfigFromAdapter(...) continuam aceitando payloads legados/parciais com semantica merge-compat, preservando campos nao informados.

Backend-owned reactive determinations

• x-ui.reactiveDeterminations e lido exclusivamente do request schema exato retornado por /schemas/filtered; nao integra nem e persistido em FormConfig.
• O runtime aceita somente o contrato fechado normalizado por normalizeReactiveDeterminations: trigger on-change, scope de create/edit, capability POST, no maximo 64 bindings totais, JSON Pointers sem duplicidade ou sobreposicao hierarquica e provenance estrutural. A lista e um unico grafo canonico: uma definicao invalida rejeita a projecao inteira, sem execucao parcial.
• href, request/response schemas e bindings sao compilados pelo Praxis Metadata. O Angular nao aceita callback, headers, method, URL ou write policy autorados pelo host/editor/LLM.
• Cada valor ou status relevante invalida imediatamente a geracao anterior, antes do debounce da proxima chamada; somente a geracao ainda autoritativa pode aplicar a resposta.
• Hrefs protocol-relative, com separadores codificados ou resolvidos fora da origem configurada da API falham de forma fechada.
• A resposta so e aplicada quando todos os bindings existem. Os controles alvo aninhados sao preenchidos antes da notificacao dos observers; determinacoes encadeadas recebem um unico sinal logico depois do commit completo, nao um disparo por output. A ordem da cadeia e derivada dos bindings existentes: downstream aguarda a geracao upstream e so executa apos outputs autoritativos ou inputs confirmados como inalterados. Output upstream null/undefined e geracao upstream com erro, invalida ou cancelada encerram downstream como skipped, sem chamada com dado ausente ou obsoleto. Se um controle rejeitar a escrita, o runtime tenta restaurar os anteriores e emite falha terminal. O resultado tem semantica fechada server-derived e substitui o draft alvo; o commit e um batch coordenado no cliente, sem promessa de transacao ACID.
• O estado permanece pending durante debounce, validacao assincrona e execucao. Uma tentativa de submit aguarda estabilizacao com timeout e repete a espera depois de hooks que podem alterar controles.
• Controles de output sao desabilitados transitoriamente como valores server-derived, sem mutar/persistir FormConfig; seus valores continuam em getRawValue(), valueChange e no payload de submit. Depois da hidratacao, fonte inicialmente preenchida entra em pending e e determinada antes de o draft ser considerado estavel; fonte inicial vazia encerra como skipped/initial-source-empty, satisfeita e sem HTTP. Alteracao programatica posterior em output owned invalida a autoridade anterior e reexecuta a capability.
• reactiveDeterminationExecuted publica apenas IDs, paths, provenance, estado (pending, success, skipped ou error), duracao, correlation ID e motivo. Valores do formulario e da resposta nao participam da evidencia.
• Hosts compostos recebem estado agregado por reactiveDeterminationPendingChange. Antes de navegar ou fechar, devem consultar hasPendingReactiveDeterminations() e hasUnsatisfiedReactiveDeterminations() e aguardar waitForReactiveDeterminations(timeoutMs?); retorno false indica timeout ou geração mais recente sem draft autoritativo e bloqueia a transição. Correlações canceladas recebem terminal skipped/superseded.
• Cascatas de opcoes continuam em optionSource.dependsOn; recommendations, side-effect refresh, backend validation e workflow actions permanecem capacidades separadas.
• O comando backend final continua responsavel por autorizacao, recomputacao e validacao de qualquer decisao consequente.

AI assistant and semantic authoring boundary

praxis-dynamic-form usa o copiloto semantico Praxis como superficie assistiva contextual, nao como fonte primaria de regra de negocio. O componente pode abrir o assistente a partir de controles de configuracao, floating help ou selecao do canvas, mas a presenca global, minimizacao e retomada da sessao pertencem ao PraxisAssistantSessionRegistryService.

Contrato operacional:

• a integracao nova deve abrir PraxisAiAssistantShellComponent; PraxisAiAssistantComponent permanece legado para novos fluxos inteligentes;
• a identidade canonica da sessao segue form:{routeKey}:{componentInstanceId || formId || 'form'};
• o contexto assistivel publico e PraxisAssistantContextSnapshot, com identity, target, contextItems, authoringManifestRef, resourcePath, schemaFields, digests seguros e hints de governanca;
• o snapshot pode apontar para field, schemaBackedField, localField, section, row, column, visualBlock, formAction, message ou rule, mas nao deve transportar form.value, rawFormData, config completa, notas privadas, estado runtime bruto, diagnostics arbitrarios, pendingPatch, File, Blob, bytes, base64 ou previewUrl;
• turnos do assistente usam AgenticAuthoringTurnClientService e /api/praxis/config/ai/authoring/turn/stream/**; indisponibilidade do transporte falha de forma fechada e nao reabre o caminho legado getPatch;
• o grounding do turno pode incluir schemaFields e dataProfile estruturais produzidos pelo adapter, mas nunca valores dos controles; anexos sao reduzidos a nome, tipo, MIME, tamanho, origem e indicador de preview;
• edicao local so pode ser aplicada quando a resposta for compilada para componentEditPlan validado pelo manifesto autoral do componente;
• patches livres retornados por backend/LLM sem plano compilado sao rejeitados pelo turn flow;
• pedidos sobre regra de negocio compartilhada, elegibilidade, compliance, LGPD, politica, acesso, aprovacao, publicacao, materializacao ou enforcement devem virar handoff governado para domain-rules, nao patch local de formulario;
• em mode="view" sem customizacao, ou quando o host estiver readonly, o assistente opera apenas em inline-help, explain e diagnose; local-apply e manifest-compile ficam bloqueados.

Essa fronteira preserva a premissa de plataforma: o formulario materializa e explica decisoes governadas, mas nao redefine sozinho a semantica canonica da decisao.

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

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)

Nota editorial:

• praxis-dynamic-form carrega e orquestra FieldMetadata, mas a resolução de valuePresentation em display/read-only pertence ao runtime de @praxisui/dynamic-fields.
• fieldMetadata[].source, fieldMetadata[].transient e fieldMetadata[].submitPolicy governam campos locais do host. Campos com source: "local" ou transient: true participam de validação, regras, visibilidade e valueChange, mas são omitidos de formSubmit.formData e do payload HTTP por default.
• fieldMetadata[].submitPolicy tem prioridade sobre source e transient: include força envio, omit força omissão e includeWhenDirty envia apenas quando o controle estiver dirty.
• Dentro de array.itemSchema.fields, includeWhenDirty considera o item ou subcampo especifico dirty, como participantes.0 ou participantes.0.observacao. O FormArray pai dirty, como participantes, nao torna todos os subcampos de todos os itens elegiveis para submit.
• O evento formSubmit mantém formData como payload persistível filtrado e expõe rawFormData para hosts que precisam ler os campos locais/transientes no contexto de UI.
• O evento payloadPreviewChange projeta o payload persistível atual sem executar hooks de submit nem disparar HTTP. formData usa o mesmo pipeline síncrono de normalização/políticas do submit, rawFormData preserva o estado completo e changedFields lista somente paths de controles dirty.
• Botões com type="reset" preservam a semântica canônica de reset mesmo quando recebem um id editorial próprio. O runtime impede o reset nativo do navegador, restaura o snapshot hidratado, marca o formulário como pristine/untouched e publica nova prévia com reason: "reset".
• Configs persistidas são reconciliadas com o schema estrutural antes da montagem. Campos locais explícitos são preservados, mas campos server-backed recebem novamente a semântica publicada pelo backend, incluindo endpoint, resourcePath, optionLabelKey e optionValueKey.
• Para selects com x-ui.endpoint terminando em /options/filter, endpoint é a operação concreta de opções e resourcePath é o recurso dono. O runtime deve chamar /options/filter; não deve converter esse endpoint para /filter.

Supported legacy paths

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

Internal-only paths

Experimental paths

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

Nested configuration blocks

Editable Collection field contract

Editable Collection e o contrato publico para listas editaveis de objetos dentro de fieldMetadata[].

O runtime trata um campo como Editable Collection somente quando o campo declara controlType: "array" ou quando a metadata veio com array explicitamente. Um schema OpenAPI com type: "array" usado por controles simples, como chipInput ou multiSelect, nao deve receber fieldMetadata[].array por normalizacao implicita.

Subconjunto suportado no beta atual:

O host deve persistir formSubmit.formData para fluxos normais. formSubmit.rawFormData existe para auditoria, diagnostico e hooks de UI, mas nao substitui o payload normalizado.

Input bindings

initialValue is an active component input for host-authored or complementary field values. In edit/view, the runtime applies it without redefining the canonical remote entity loaded through resourcePath and resourceId. In create, including item-scoped command forms, it is the only supported source of initial values: a contextual resourceId never triggers entity hydration.

Section header visual contract

• avatar-image aceita URL, data URL, File, Blob, ArrayBuffer, views tipadas e objetos com chaves como url, src, dataUrl, base64 ou bytes.
• auto tenta imagem, depois iniciais vindas de initialsSourceField ou altField, e por fim o emptyState.
• Se nenhum valor estiver disponível ainda, o runtime não falha: aplica emptyState e mantém o cabeçalho estável em fluxos create.
• Nas superfícies de authoring da lib, sections[].headerActions[].action sugere o catálogo global canônico do core e mantém fallback para valor customizado livre por compatibilidade.
• Quando a ação global selecionada exigir payload/param obrigatório, o authoring deve sinalizar isso explicitamente ao usuário antes da persistência; no caso de surface.open, o authoring canônico usa editor especializado em vez de texto cru.
• Em formRules para targetType: 'section', o builder pode governar tanto sectionHeader inteiro quanto subpaths tipados como sectionHeader.mode, sectionHeader.emptyState e sectionHeader.size, além de headerActions como objeto agregado.
• Em formRules, targets usam IDs canônicos do alvo. Para ações globais de formulário isso continua sendo o ID lógico da action; para ações de header de seção, o ID canônico é section:<sectionId>:header-action:<actionLogicalId>, evitando colisão com actions globais do form e entre seções.
• 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.

Field rule computed value contract

Regras com targetType: "field" podem usar effect.properties.value e effect.propertiesWhenFalse.value para escrever declarativamente o valor do FormControl alvo. O envelope canônico é fechado e exclusivo: exatamente { "expression": <JsonLogic> } para valores calculados ou exatamente { "literal": <valor> } para valores literais estruturados. Primitivos, null e arrays continuam aceitos como literais; objetos JSON Logic legados de operador único continuam aceitos para compatibilidade no runtime. O authoring visual e o editor JSON rejeitam objetos literais ambíguos sem envelope, como { "startDate": "...", "endDate": "..." }, e envelopes com chaves extras, como { "literal": 1, "expression": { "var": "age" } }. Valores calculados são resolvidos em uma fase anterior à aplicação das demais propriedades, com iteração limitada até estabilização, para que regras dependentes não fiquem acopladas à ordem do array.

Conditional command rule contract

Politica de erro do runtime: falhas de GlobalActionService.executeRef(...) em comandos condicionais sao fail-closed. Resultado success: false ou excecao assincrona gera diagnostico e nao reexecuta em loop enquanto a condicao continuar verdadeira. Quando GlobalActionService nao esta disponivel, acoes mutaveis (api.post, api.put, api.patch, api.delete) nao caem para customAction.

formCommandRules separa comandos com side effect das regras de propriedade. A regra é avaliada depois de formRules estabilizar fieldValues, então casos como birthDate -> age -> dialog.alert não dependem da ordem do array. O primeiro corte suporta apenas effects[].kind: "global-action" e executa globalAction via GlobalActionService.executeRef(...). Por padrão, comandos usam trigger: "on-condition-enter" e runOnInitialEvaluation: false; trigger: "while-true" não executa global-action nesta versão. distinct usa chave composta por componente, regra, efeito, action, contexto e valor de distinctBy, e a memória é limpa quando a condição volta a falso. No editor visual, payloadExpr permanece escape hatch de JSON avancado: o editor preserva payloadExpr existente quando nenhum payload estruturado e definido, mas campos estruturados authoram payload literal.

Exemplo:

{
  "formRules": [
    {
      "id": "birth-date-computes-age",
      "targetType": "field",
      "targets": ["age"],
      "effect": {
        "condition": { "!": [{ "isBlank": [{ "var": "birthDate" }] }] },
        "properties": {
          "value": { "expression": { "yearsSince": [{ "var": "birthDate" }] } }
        },
        "propertiesWhenFalse": {
          "value": { "literal": null }
        }
      }
    }
  ]
}

Visual block rule contract

Itens de layout kind: "richContent" podem ser alvo de formRules com targetType: "visualBlock". O target é sempre o id do item em sections[].rows[].columns[].items[]; o bloco visual não recebe entrada em fieldMetadata[], não cria FormControl e não entra em formSubmit.formData nem no payload HTTP.

Subconjunto público de propriedades suportadas para targetType: "visualBlock":

Exemplo canônico:

{
  "formRules": [
    {
      "id": "employee-guidance-by-status",
      "targetType": "visualBlock",
      "targets": ["employee-guidance-block"],
      "effect": {
        "condition": { "===": [{ "var": "ativo" }, false] },
        "properties": {
          "title": "Revise a inativação",
          "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"
        }
      }
    }
  ]
}

Limites de segurança:

• text, title e message não aceitam HTML arbitrário, handlers, scripts ou substituição completa do RichContentDocument.
• Em documentos compostos, prefira sempre textNodeId, titleNodeId ou messageNodeId; sem node explícito, o runtime só aplica override quando encontra alvo simples ou convencional seguro.
• Regras de visualBlock são visual-only. Use campo local (fieldMetadata[].source: "local") quando a experiência precisar de valor, validação de campo, leitura em rawFormData ou participação explícita no payload via submitPolicy.

Output events

External side channels

Host/runtime dependencies

Coverage matrix

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. inputs explícitos (config, resourcePath, mode, flags globais)
2. hidratação de preferências de input (formInputsKey) e conexão persistida
3. initializeForm(): config local persistida (formConfigKey) ou criação a partir do servidor
4. normalização final via normalizeFormConfig()
5. overrides de runtime (hooks, backConfig, customEndpoints, presentation vars)

Fallback order

config local persistida -> config default criada do schema remoto -> erro de inicialização (quando formId e uma fonte schema-backed, resourcePath ou schemaUrl, estão ausentes no fluxo corporativo).

Override points

• @Input() públicos (config, hooks, layout, backConfig, customEndpoints)
• edição em runtime via SettingsPanelService
• persistência de host (ASYNC_CONFIG_STORAGE, CONNECTION_STORAGE)

Runtime normalization

• normalizeFormConfig() estabiliza ids e estrutura antes do build/render.
• applyPresentationVars() resolve precedência entre configuração persistida e config em memória.
• resolveSchemaPrefs() consolida preferências locais e fallback global de notificação de drift.

Precedence rules

• @Input() hooks sobrescreve config.hooks por estágio.
• backConfig.confirmOnDirty sobrescreve behavior.confirmOnUnsavedChanges.
• resourcePath explícito no input tem precedência sobre conexão persistida.

Validation and error semantics

Validation model

Error semantics

Falhas de inicialização (config-load/form-build) são bloqueantes e emitem initializationError. Divergências de schema são tratadas como estado (schemaOutdated) com emissão de evento, sem interromper formulário já carregado.

No submit, RestApiResponse.errors é materializado somente quando a resposta possui status HTTP 4xx conhecido. Cada detalhe cujo target resolve um controle é anexado como erro server, sem remover validadores do cliente, e desaparece quando aquele controle muda. Erros de outros campos permanecem ativos; todos os erros de servidor são limpos no início da próxima tentativa e após sucesso. target aceita path Angular pontuado ou JSON Pointer. Targets desconhecidos não são inferidos por texto e continuam como feedback global.

Precedência do feedback: resposta 4xx com detalhes governados > mensagem customizada de submit ou create/update > fallback normalizado e localizado. Falhas de rede, respostas 5xx e respostas sem status confiável nunca expõem message/errors do payload e usam as chaves global.submitError.*. visibleWhen, mensagens locais e validação visual não substituem a autorização e a validação de negócio do backend.

Fail-open / fail-closed behavior

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

Detailed API

Preserved technical reference (normalized from previous revision)

Referencia canonica da JSON API do praxis-dynamic-form, com foco em:

• contrato declarado (FormConfig + inputs/outputs do componente);
• comportamento que o runtime consome de fato;
• limites conhecidos para uso corporativo (governanca, observabilidade, UX e risco).

Legenda de suporte:

• Active: consumido no runtime atual.
• Partial: consumido parcialmente (subconjunto funcional).
• Declared-only: declarado no contrato, sem consumo direto no runtime atual.

Table of contents

• Overview
• Checklist corporativo pre-flight
• API
  • Component inputs
  • Component outputs
  • Data mode e fluxo
• FormConfig coverage matrix
• Behavior e Messages coverage detalhado
• DynamicFieldLoader error bridge
• Seguranca e fronteiras de responsabilidade
• Exemplos JSON
• Known limitations and pending investigation
• Source references

Overview

praxis-dynamic-form e um runtime de formulario schema-driven orientado por FormConfig.

Fluxo macro:

1. Resolve configuracao (local, remota ou defaults).
2. Normaliza estrutura (sections/rows/columns/fieldMetadata) e IDs.
3. Monta FormGroup, aplica regras e estados globais.
4. Renderiza campos via DynamicFieldLoaderDirective.
5. Executa submit/cancel/reset/custom actions com hooks e mensagens.
6. Emite eventos para host (estado, erros, sincronizacao e acao).

No ecossistema Praxis, ele funciona tanto como runtime final quanto como superficie de edicao (settings panel + config editor) para round-trip de JSON.

Checklist corporativo pre-flight

• Defina formId estavel por tela/uso para evitar colisao de persistencia.
• Em cenarios multi-instancia na mesma pagina, use componentInstanceId.
• Se o formulario for remoto, valide resourcePath e ciclo de schema (schemaStatusChange).
• Declare explicitamente estrategia de modos (create/edit/view) no host.
• Trate fieldRenderError no host para observabilidade de render por campo.
• Garanta autorizacao no backend para submit/custom actions; regras visuais no front nao sao controle de acesso.

API

Component inputs

initialValue is part of the public runtime contract and accepts Record<string, unknown> | null for local initial values.

O authoring emite o warning dynamicForm.config.layout.groupedCommand.row.incomplete quando uma linha gerada com dois ou mais campos ocupa menos de 12 colunas. Com partialRowStrategy='fill-compatible', o warning desaparece quando a projeção resolve a linha; ele permanece acionável para preserve ou quando controles compactos/fixos/desconhecidos não podem ser redistribuídos. | backConfig | BackConfig \| undefined | undefined | Active | Integra retorno/navegacao no painel de configuracao; confirmOnDirty tem precedencia sobre behavior.confirmOnUnsavedChanges no cancel. | | hooks | FormHooksLayout \| undefined | undefined | Active | Override direto de hooks sobre config.hooks. | | customEndpoints | EndpointConfig | {} | Active | Override de endpoints no CRUD service interno. | | removeEmptyContainersOnSave | boolean | false | Active | Sanitiza secoes/linhas/colunas vazias na persistencia de config. | | reactiveValidation | boolean \| null | null | Active | Override de validacao reativa (valueChanges). | | reactiveValidationDebounceMs | number \| null | null | Active | Debounce da validacao reativa. | | notifyIfOutdated | 'inline' \| 'snackbar' \| 'both' \| 'none' | 'both' | Active | Canal de aviso de schema desatualizado quando a customizacao estiver ativa. | | snoozeMs | number | 86400000 | Active | Janela de supressao de notificacao. | | autoOpenSettingsOnOutdated | boolean | false | Active | Auto-abertura do settings quando schema diverge. | | readonlyModeGlobal | boolean \| null | null | Active | Estado global de leitura propagado para loader. | | disabledModeGlobal | boolean \| null | null | Active | Estado global de desabilitado propagado para loader. | | presentationModeGlobal | boolean \| null | null | Active | Modo apresentacao global (efetivo em view). | | fieldIconPolicy | 'all' \| 'presentation-only' \| 'none' | 'all' | Active | Controla icones prefixIcon/suffixIcon vindos da metadata dos campos. all preserva o comportamento atual; presentation-only mantem icones decorativos no modo apresentacao e oculta os slots de icone em controles input/read-only tradicionais; none oculta esses slots em todos os modos. | | visibleGlobal | boolean \| null | null | Active | Visibilidade global propagada para loader. |

Perfil público local somente-leitura

PRAXIS_DYNAMIC_FORM_COMPONENT_METADATA.runtimeProfiles publica public-local-readonly para hosts públicos não confiáveis. O profile aceita somente mode='view', readonlyModeGlobal=true, estratégia input-first, initialValue local e um subconjunto explícito de chaves de config, layout e FieldMetadata. Controles remotos, endpoints, option sources, rich content, hooks, rules, commands, actions, customização, assistente e IDs de persistência invalidam o profile. Chaves desconhecidas também invalidam o documento para que novas capacidades futuras não sejam liberadas implicitamente.

O profile declara effects: [] e não é grant de autorização. O host continua responsável por validar o candidate e bloquear rede por padrão. No runtime, onSubmit() retorna sem emitir evento e sem chamar create/update quando o form está em readonly ou presentation, inclusive em submit programático.

In compactPresentation runtime detail surfaces, rows, columns and sections are visible only when they contain at least one field that can be materialized after metadata visibility and field-rule overrides are resolved. Boolean values, including false, are valid presentation values and must not be treated as empty detail content. If no field in a section is materialized, the section is hidden instead of rendering an orphan title.

Migration baseline for ErgonX-style screens

For enterprise migrations that must become templates for many screens, layoutPolicy, helpPresentation and fieldIconPolicy should be selected as part of the DTO/schema handoff, not patched locally after visual review.

Recommended baseline:

If a field requires a local label, local help text, local option mapping or local code/description composition to look correct, the schema is not ready for scalable migration. Fix the backend DTO, OpenAPI x-ui metadata or option/value-presentation contract first.

Regras compartilhadas materializadas

domainRules separa regra corporativa compartilhavel de regra materializada no FormConfig. Quando habilitado, o componente consulta o backend de configuracao via DomainRuleFormRulesService, transforma cada materializacao em FormLayoutRule e aplica a lista combinada:

1. config.formRules
2. regras vindas de domain_rule_materialization.materializedPayload

Exemplo:

<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>

Campos de PraxisDynamicFormDomainRulesOptions:

Materializacoes diretas podem persistir um FormLayoutRule em materializedPayload. O adaptador tambem reconhece operation: "rule.visualBlockGuidance.add" e converte para regra targetType: "visualBlock" como projecao visual derivada, preservando rastreabilidade em metadata.domainRule sem transformar o formulario em fonte primaria da regra de negocio. Quando o backend enviar decisionDiagnostics, o adaptador carrega esse envelope para metadata.domainRule.decisionDiagnostics, incluindo sourceHashPresent e sourceHash quando disponiveis, mantendo a explicacao canonica da decisao semanticamente authorada por IA junto da regra derivada, sem transformar o formulario em fonte primaria da regra de negocio.

Teste vivo de referencia:

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

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".

Component outputs

Data mode e fluxo

• mode='create': cria registro ou materializa um comando; nunca carrega a entidade por resourceId, e valores iniciais devem vir de initialValue.
• mode='edit': carrega entidade por resourceId quando disponivel.
• mode='view': foco em leitura/apresentacao; actions de edicao podem ser suprimidas.

Precedencias importantes:

1. Inputs explicitos do host (ex.: reactiveValidation) sobrescrevem comportamento no config.behavior.
2. hooks input sobrescreve config.hooks.
3. Preferencias de outdated schema combinam input + widget/global defaults.

FormConfig coverage matrix

Behavior e Messages coverage detalhado

behavior.*

messages.*

DynamicFieldLoader error bridge

praxis-dynamic-form encaminha erros de render por campo para o host via fieldRenderError.

Payload:

{
  phase: 'executeRendering' | 'detectChanges';
  fieldName: string;
  error: unknown;
  fatal: boolean;
}

Politica atual do loader:

• Erro por campo nao derruba automaticamente o formulario inteiro.
• Erros de lifecycle Angular (NG0205, injector/view destroyed) sao marcados como fatal=true para o ciclo atual.
• O runtime evita emissao duplicada quando o erro fatal ja foi reportado em etapa anterior.

Recomendacao corporativa:

• Capture fieldRenderError no host e envie para telemetria com formId, resourcePath, mode e fieldName.
• Use alerta operacional apenas para fatal=true repetido em ambiente de producao.

Seguranca e fronteiras de responsabilidade

• hidden, readonly, disabled, presentation sao controles de UX no front-end.
• Validacao e autorizacao de negocio devem ser reforcadas no backend.
• Acoes custom emitidas pelo componente (customAction) nao substituem checagens de permissao server-side.

Exemplos JSON

1) Baseline create/edit (foco em contrato ativo)

{
  "sections": [
    {
      "id": "main",
      "title": "Cadastro",
      "rows": [
        {
          "id": "r1",
          "columns": [
            { "id": "c1", "fields": ["name", "email"] }
          ]
        }
      ]
    }
  ],
  "fieldMetadata": [
    { "name": "name", "label": "Nome", "controlType": "input", "required": true },
    { "name": "email", "label": "Email", "controlType": "input" }
  ],
  "behavior": {
    "confirmOnUnsavedChanges": true,
    "reactiveValidation": true,
    "reactiveValidationDebounceMs": 200
  },
  "messages": {
    "loading": { "submit": "Salvando cadastro..." },
    "confirmations": { "cancel": "Descartar alteracoes?" },
    "createRegistrySuccess": "Registro criado com sucesso",
    "updateRegistrySuccess": "Registro atualizado com sucesso"
  }
}

2) View + apresentacao global

{
  "sections": [
    {
      "id": "view-main",
      "title": "Resumo",
      "rows": [
        {
          "id": "vr1",
          "columns": [
            { "id": "vc1", "fields": ["status", "owner"] }
          ]
        }
      ]
    }
  ],
  "fieldMetadata": [
    { "name": "status", "label": "Status", "controlType": "input" },
    { "name": "owner", "label": "Responsavel", "controlType": "input" }
  ],
  "actions": {
    "submit": { "visible": false, "label": "Salvar" },
    "cancel": { "visible": true, "label": "Voltar" },
    "reset": { "visible": false, "label": "Limpar" }
  }
}

No host Angular:

<praxis-dynamic-form
  [config]="formConfig"
  mode="view"
  [presentationModeGlobal]="true"
  (fieldRenderError)="onFieldRenderError($event)"
  (ruleDiagnosticsChange)="onRuleDiagnosticsChange($event)">
</praxis-dynamic-form>

ruleDiagnosticsChange nao aplica UI propria no formulario. Ele existe para governanca do host: logar regras invalidas, sinalizar configuracao inconsistente ao autor ou impedir publicacao de metadata sem esconder o problema dentro do runtime. O runtime emite target-not-found quando uma regra aponta para section, row, column, action ou visualBlock inexistente no FormConfig resolvido; para campos, o codigo legado field-target-not-found permanece.

Known limitations and pending investigation

1. FormConfig.api segue Declared-only no runtime principal.
2. Cobertura de behavior e parcial; varios campos continuam sem binding dedicado.
3. Cobertura de messages e parcial para chaves fora do fluxo principal de submit/confirmacao.
4. Ainda falta bateria de stress dedicada para corrida teardown/render alem de NG0205.
5. hints permanece no contrato/editor sem exposicao no template principal.

Source references

• projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.ts
• projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.html
• projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts
• projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.directive.ts
• projects/praxis-core/src/lib/models/form/form-config.model.ts
• projects/praxis-core/src/lib/models/form/form-layout.model.ts

JSON path index

Events

Styling API

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

{
  "sections": []
}

Typical/common

{
  "sections": [
    {
      "id": "main",
      "title": "Dados",
      "sectionHeader": {
        "mode": "auto",
        "sourceField": "employeePhoto",
        "initialsSourceField": "fullName",
        "altField": "fullName"
      },
      "rows": [
        {
          "id": "r1",
          "columns": [
            {
              "id": "c1",
              "span": 12,
              "fields": ["fullName"]
            }
          ]
        }
      ]
    }
  ],
  "fieldMetadata": [
    { "name": "employeePhoto", "label": "Foto", "controlType": "input" },
    { "name": "fullName", "label": "Nome", "controlType": "input" }
  ]
}

Advanced

{
  "sections": [],
  "behavior": {
    "reactiveValidation": true,
    "reactiveValidationDebounceMs": 300
  },
  "messages": {
    "customActions": {
      "submit": {
        "success": "Registro salvo com sucesso."
      }
    }
  },
  "hooks": {
    "beforeSubmit": [
      {
        "type": "custom",
        "handler": "sanitizePayload"
      }
    ]
  }
}

Enterprise scenario

{
  "sections": [],
  "api": {
    "resourcePath": "customers",
    "schemaSource": "resource"
  },
  "behavior": {
    "notifyIfOutdated": "both",
    "autoOpenSettingsOnOutdated": true
  },
  "messages": {
    "global": {
      "saveError": "Nao foi possivel salvar no momento."
    }
  }
}

Known limitations and mismatches

Compatibility and migration notes

Source references

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.

Orientação antes da seleção de um registro

O editor nativo, em Geral → Sem registro selecionado, materializa o contrato existente PraxisDynamicFormEmptyState em bindings.emptyState. O wrapper Page Builder projeta esse binding para inputs.emptyState; Apply, Save e JSON usam o mesmo documento. Não pertence a FormConfig nem substitui o modo dos dados.

title é obrigatório e não pode conter apenas espaços. description e icon são textos opcionais; a cópia de negócio permanece literal, sem ser interpretada automaticamente como chave i18n. O seletor usa o catálogo canônico de ícones. Restaurar o ícone padrão limpa a escolha explícita. Os controles do editor usam o catálogo i18n Form; a aparência runtime usa os tokens do empty state compartilhado.

As opções de aparência ficam em disclosure avançado: tone (neutral, primary, secondary), variant (card, inline, panel, transparent), alignment (start, center), density (compact, comfortable) e iconContainer (none, circle, soft). Ausência de opção herda o padrão do componente; JSON inválido produz diagnóstico.

A orientação aparece somente em mode=view, sem registro selecionado nem snapshot local. Criar e Editar preservam a configuração sem exibi-la. Desligar grava null, que impede reativação por uma preferência antiga; substituir um documento que omite o binding também limpa a orientação. Em input-first, a página governa o valor. Filter Form não expõe essa seção, pois não possui contexto de seleção equivalente.