@praxisui/dynamic-form 8.0.0-beta.19 → 8.0.0-beta.20

package/README.md

@@ -501,11 +501,20 @@ e mantém `fields[]` sincronizado como projeção; `fieldMetadata[]` não é
 alterado.
 
 **Adicionar bloco visual** oferece presets internos como texto, aviso,
-separador e card informativo. Esses presets são apenas atalhos de authoring que
+separador, card informativo, `callout`, `keyValueList`, `recordSummary`,
+`disclosure` e `emptyState`. Esses presets são apenas atalhos de authoring que
 geram documentos `praxis.rich-content` válidos para itens `kind: 'richContent'`;
 eles não criam novo `kind`, não criam `FieldMetadata` e não participam do
 payload de submit.
 
+O runtime do formulário também passa `hostCapabilities` canônicos para
+`@praxisui/rich-content`, permitindo:
+- `actionButton` despachar ações via a mesma trilha de `customAction`/`globalAction`
+  já usada pelo formulário;
+- `requiresCapabilities` resolver capacidades como `form.mode.edit`,
+  `form.mode.view`, `form.customization.enabled`, `form.resource.connected` e
+  `form.actions.submit`.
+
 Exemplo mínimo de uma coluna com campo, bloco visual e projeção `fields[]`:
 
 ```json
@@ -587,7 +596,7 @@ Os paths micro são normalizados para `fieldMetadata[].<prop>` para garantir que
 ## Regras de formulário (novo contrato)
 
 - Formato: cada regra tem `targetType` (`field | section | action | row | column | visualBlock`), `targets: string[]` (IDs canônicos do alvo), e `effect` com `condition` (`JsonLogicExpression | null`), `properties` e `propertiesWhenFalse`.
-- Regras de orientação visual geradas por LLM devem usar `type: "visualBlockGuidance"`, `targetType: "visualBlock"`, `context: "notification"` e `metadata.origin: "llm"` com `metadata.reviewStatus: "pending"`; o editor aceita a sugestão, marca como `accepted` e materializa `formRulesState`.
+- Regra de negócio, política, elegibilidade, validação, compliance ou decisão compartilhada deve ser authorada no fluxo governado de `domain-rules`/`shared_rule_authoring`. `visualBlockGuidance` fica restrito a projeção visual opcional: quando uma decisão já governada precisar explicar impacto na UI, a materialização `form_config` pode gerar `type: "visualBlockGuidance"`, `targetType: "visualBlock"` e `metadata.origin: "llm"` com `metadata.reviewStatus: "pending"`; o editor aceita a projeção, marca como `accepted` e materializa `formRulesState` internamente para round-trip visual.
 - Compatibilidade: regras antigas (`context/targetField`) são migradas para `properties/targets` automaticamente; prefixes legados `section:/action:/row:/column:` continuam sendo normalizados quando representarem alvos tradicionais. Para header actions de seção, o ID canônico é preservado como `section:<sectionId>:header-action:<actionLogicalId>`.
 - Semântica de limpeza: valores `null` em `properties/propertiesWhenFalse` removem o override e retornam ao valor base do layout; ausência mantém o valor base.
 - Whitelist por tipo (somente propriedades a seguir são aplicadas; demais são descartadas e logadas em dev):
@@ -849,7 +858,7 @@ Apache-2.0 – see the `LICENSE` packaged with this library or the repository ro
     targetArtifactKey: 'funcionarios-form-demo',
     targetLayer: 'form_config',
     targetArtifactType: 'praxis-dynamic-form',
-    status: 'pending_review'
+    status: 'applied'
   }">
 </praxis-dynamic-form>
 ```
@@ -857,8 +866,10 @@ Apache-2.0 – see the `LICENSE` packaged with this library or the repository ro
 - `targetArtifactKey` usa `formId`/`componentInstanceId` quando omitido.
 - `targetLayer` default: `form_config`.
 - `targetArtifactType` default: `praxis-dynamic-form`.
-- `materializedPayload` pode ser um `FormLayoutRule` direto ou uma operação reconhecida, como `rule.visualBlockGuidance.add`.
+- Para consumo runtime, prefira `status: 'applied'`; `pending_review` pertence a etapas de governança antes da aplicação.
+- `materializedPayload` pode ser um `FormLayoutRule` direto ou uma operação reconhecida, como `rule.visualBlockGuidance.add`, desde que essa operação seja tratada como projeção visual derivada e não como fonte primária da regra de negócio.
 - A rastreabilidade da regra compartilhada fica em `metadata.domainRule`.
+- Quando o backend enviar `decisionDiagnostics`, o runtime preserva esse envelope em `metadata.domainRule.decisionDiagnostics`, mantendo a explicação canônica da decisão semântica governada junto da regra derivada.
 
 E2E vivo com API real:
 

package/docs/dynamic-form-authoring-document-semantics.md

@@ -0,0 +1,80 @@
+---
+title: "Dynamic Form Authoring Document Semantics"
+doc_type: "adr"
+component: "praxis-dynamic-form"
+status: "accepted"
+owner: "praxis-ui"
+last_updated: "2026-04-15"
+---
+
+# Dynamic Form Authoring Document Semantics
+
+## Decision
+
+`DynamicFormAuthoringDocument` e o snapshot canônico completo de autoria de `praxis-dynamic-form`.
+
+Ao aplicar um documento canônico:
+
+- `config` substitui integralmente a configuração anterior.
+- `bindings` substitui integralmente os bindings persistíveis anteriores.
+- ausência de `bindings.mode` implica limpeza do binding persistido e retorno ao modo default efetivo do host.
+- `contextSnapshot` substitui integralmente o contexto autoral persistido anterior.
+- ausência de `backConfig`, `presentation` ou `schemaPrefs` dentro de `contextSnapshot` significa remoção explícita do bloco ausente.
+
+Payloads legados ou parciais recebidos por APIs de compatibilidade, como `applyConfigFromAdapter(...)`, permanecem com semântica `merge-compat`: campos não informados devem ser preservados até migração completa para o contrato canônico.
+
+Valores de runtime/discovery, como `schemaUrl`, `submitUrl` e `submitMethod`, não fazem parte do `DynamicFormAuthoringDocument`. O editor pode exibi-los apenas como diagnóstico read-only do host atual, mas nunca os persiste em `bindings` ou `contextSnapshot`.
+
+## Field Metadata Editor Patches
+
+Patches vindos de `@praxisui/metadata-editor` para `fieldMetadata` seguem semantica de JSON Merge Patch no campo editado.
+
+Para `entityLookup`, o bloco `fieldMetadata[].optionSource` e aninhado e deve ser mesclado em profundidade. O dynamic-form deve preservar campos existentes, como `key`, `resourcePath`, `valuePropertyPath` e `capabilities.byIds`, quando o editor alterar apenas partes do contrato, como `dependsOn`, `selectionPolicy`, `detail` ou `capabilities.auditSnapshot`.
+
+Essa regra evita perda silenciosa do contrato canonico de Entity Lookup durante o fluxo: abrir editor -> aplicar/salvar -> reabrir editor -> runtime consumir.
+
+## Consequences
+
+- `backConfig`, `presentation` e `schemaPrefs` permanecem fora de `FormConfig`, mas fazem parte oficialmente do documento autoral persistível em `contextSnapshot`.
+- `Apply` e `Save` vindos do editor operam em modo `replace-all`.
+- `reset` do editor limpa todos os modos persistidos do artefato.
+- adapters legados continuam suportados sem limpeza destrutiva de contexto ausente.
+
+## Visual Blocks Inside Layout
+
+Blocos visuais dentro de seção, linha ou coluna devem seguir a decisão
+canônica registrada em:
+
+- `../../../docs/2026-04-dynamic-form-visual-blocks-layout-items-plan.md`
+- `../../../../docs/adr/ADR-0006-dynamic-form-layout-items-visual-blocks.md`
+- `./layout-items-visual-blocks.md`
+- `./dynamic-form-rules-authoring-plan.md`
+
+A semântica alvo é `FormColumn.items`, com uma union discriminada entre campo e
+rich content. `FormColumn.fields` pode ser aceito como entrada de migração para
+configurações antigas, mas não deve seguir como segunda fonte de verdade.
+
+O editor deve produzir e persistir o documento canônico, e o runtime deve
+consumi-lo sem adaptador oculto. O round-trip esperado é:
+
+`abrir editor -> adicionar bloco visual -> aplicar/salvar -> reabrir -> renderizar`
+
+Guardrail permanente:
+
+- bloco visual não entra em `fieldMetadata`;
+- bloco visual não cria `FormControl`;
+- bloco visual não entra no payload de submit;
+- bloco visual não usa `source`, `transient` ou `submitPolicy`.
+- operações AI para bloco visual devem escrever apenas em
+  `sections[].rows[].columns[].items[]`, usando itens `kind: 'richContent'`;
+- `sections[].rows[].columns[].fields[]` é apenas projeção/migração de campos
+  e não pode ser usado para representar bloco visual.
+- presets de bloco visual no editor são atalhos internos para criar
+  `RichContentDocument` com nodes já suportados por `@praxisui/rich-content`;
+  presets não introduzem novo `kind` nem contrato paralelo.
+- "Adicionar campo da API" reinsere somente campos já existentes em
+  `fieldMetadata[]` e ausentes de `columns[].items[]`; a operação escreve o
+  item `kind: 'field'` em `items[]` e preserva `fieldMetadata[]`.
+
+Em fase beta, não vamos deixar legado para trás sem migração, mas também não
+vamos manter legado como contrato paralelo permanente.

package/docs/dynamic-form-llm-rule-authoring-guide.md

@@ -0,0 +1,313 @@
+---
+title: "Dynamic Form LLM Rule Authoring Guide"
+slug: "dynamic-form-llm-rule-authoring-guide"
+description: "Guia operacional para criar, explicar, revisar e aplicar regras de Dynamic Form com apoio de LLM."
+doc_type: "guide"
+document_kind: "host-guide"
+category: "architecture"
+audience:
+  - "business-analyst"
+  - "frontend"
+  - "host"
+  - "platform-team"
+  - "llm-agent"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-form"
+  - "rules"
+  - "llm"
+  - "json-logic"
+  - "governance"
+toc: true
+sidebar: true
+reading_time: "10 min"
+last_updated: "2026-04-22"
+source_of_truth:
+  - "projects/praxis-dynamic-form/docs/dynamic-form-rules-authoring-plan.md"
+  - "projects/praxis-dynamic-form/src/lib/ai/dynamic-form-rule-authoring-context.ts"
+  - "projects/praxis-dynamic-form/src/lib/ai/form-ai-capabilities.ts"
+  - "projects/praxis-dynamic-form/src/lib/utils/rule-authoring-diagnostics.ts"
+  - "projects/praxis-dynamic-form/src/lib/services/form-rules.service.ts"
+  - "projects/praxis-core/src/lib/models/form/rule-property.schema.ts"
+---
+
+# Dynamic Form LLM Rule Authoring Guide
+
+Este guia define como um analista, host corporativo ou agente LLM deve pedir,
+gerar, explicar, revisar e aplicar regras em `praxis-dynamic-form`.
+
+O objetivo e tirar a regra do improviso. A LLM nao deve "adivinhar codigo"; ela
+deve operar sobre o vocabulario autoral publicado pelo componente:
+
+- `formRules` e o contrato executavel.
+- `formRulesState` e estado interno do builder visual.
+- `fieldMetadata[].name` identifica campos de negocio.
+- `sections[].rows[].columns[].items[]` identifica layout canonico.
+- `RULE_PROPERTY_SCHEMA` define quais propriedades cada alvo aceita.
+- `rule-authoring-diagnostics` e `ruleDiagnosticsChange` fecham o ciclo de
+  validacao e explicacao.
+
+## Contrato de responsabilidade
+
+| Papel | Pode fazer | Nao deve fazer |
+| --- | --- | --- |
+| Analista | Descrever intencao, revisar impacto, aceitar ou rejeitar sugestao. | Editar `formRulesState` manualmente. |
+| LLM | Gerar proposta em `formRules`, explicar impacto e corrigir diagnostics. | Escrever JS, handler, funcao ou regra fora de Json Logic. |
+| Editor | Validar alvo, condicao, propriedades e round-trip visual. | Aplicar regra invalida silenciosamente. |
+| Runtime | Aplicar somente propriedades saneadas e emitir diagnostics. | Criar campos, controles ou payload a partir de visual block. |
+
+## Contexto minimo que a LLM precisa receber
+
+A LLM nao precisa analisar codigo em runtime. Ela precisa receber um pacote de
+conhecimento serializado pelo host/editor:
+
+```json
+{
+  "component": "praxis-dynamic-form",
+  "capabilityCatalogVersion": "v1.11",
+  "fields": [
+    { "name": "tipoContrato", "label": "Tipo de contrato", "type": "select" },
+    { "name": "dataFim", "label": "Data fim", "type": "date" }
+  ],
+  "targets": {
+    "field": ["tipoContrato", "dataFim"],
+    "section": ["dados-contratuais"],
+    "action": ["submit", "cancel"],
+    "visualBlock": ["aviso-lgpd"]
+  },
+  "allowedRuleProperties": {
+    "field": ["visible", "required", "disabled", "readonly", "label", "hint"],
+    "visualBlock": ["visible", "hidden", "text", "title", "message", "rootClassName"]
+  },
+  "visualBlockNodes": {
+    "aviso-lgpd": [
+      { "id": "title", "label": "Aviso LGPD", "kind": "card", "roles": ["title"] },
+      { "id": "message", "label": "Aviso", "kind": "text", "roles": ["text", "message"] }
+    ]
+  },
+  "existingRules": [],
+  "diagnostics": []
+}
+```
+
+Esse pacote deve ser derivado de `FormConfig`, do catalogo de capacidades e dos
+diagnostics atuais. Ele e o "mapa semantico operacional" do formulario.
+
+No runtime/editor, use `buildDynamicFormRuleAuthoringContext(config)` para
+montar esse pacote de forma canonica. A funcao publica:
+
+- remove campos `formHidden` dos alvos de regra;
+- coleta campos, secoes, linhas, colunas, actions e visual blocks;
+- publica `allowedRuleProperties` a partir de `RULE_PROPERTY_SCHEMA`;
+- publica `visualBlockNodes` com os nos editaveis de cada rich content block
+  quando regras puderem alterar `text`, `title` ou `message`;
+- inclui `existingRules` e `diagnostics`;
+- carrega guardrails permanentes para a LLM, incluindo a regra de que
+  `formRulesState` e gerado apenas por internals Praxis apos revisao humana.
+
+## Prompt recomendado para criar regra
+
+Use pedidos com intencao, alvo, condicao, efeito e criterio de aceite:
+
+```text
+Crie uma regra para o formulario de funcionario.
+
+Intencao: quando tipoContrato for "temporario", o campo dataFim deve ficar
+obrigatorio e visivel. Quando nao for temporario, dataFim deve ficar opcional.
+
+Use somente JSON Logic canonico.
+Use somente alvos existentes no target catalog.
+Nao altere formRulesState.
+Marque metadata.origin como "llm" e metadata.reviewStatus como "pending".
+Explique o impacto antes de aplicar.
+```
+
+Resposta esperada da LLM:
+
+```json
+{
+  "formRules": [
+    {
+      "id": "rule-data-fim-contrato-temporario",
+      "name": "Data fim obrigatoria para contrato temporario",
+      "description": "Exige data fim quando o contrato do funcionario for temporario.",
+      "metadata": {
+        "origin": "llm",
+        "reviewStatus": "pending"
+      },
+      "targetType": "field",
+      "targets": ["dataFim"],
+      "effect": {
+        "condition": {
+          "==": [{ "var": "tipoContrato" }, "temporario"]
+        },
+        "properties": {
+          "visible": true,
+          "required": true
+        },
+        "propertiesWhenFalse": {
+          "required": false
+        }
+      }
+    }
+  ]
+}
+```
+
+## Prompt para regra LGPD
+
+```text
+Crie uma regra LGPD para o formulario.
+
+Quando o campo consentimentoLgpd for false, o botao submit deve ficar
+desabilitado e o bloco visual aviso-lgpd deve mostrar a mensagem:
+"Aceite o termo de privacidade para continuar."
+
+Use targetType "action" para submit e "visualBlock" para aviso-lgpd.
+Nao coloque aviso-lgpd em fieldMetadata.
+Nao crie FormControl para aviso-lgpd.
+Use JSON Logic canonico.
+Deixe a sugestao pendente de revisao humana.
+```
+
+Resposta esperada:
+
+```json
+{
+  "formRules": [
+    {
+      "id": "rule-submit-bloqueado-sem-lgpd",
+      "name": "Bloquear envio sem consentimento LGPD",
+      "metadata": {
+        "origin": "llm",
+        "reviewStatus": "pending"
+      },
+      "targetType": "action",
+      "targets": ["submit"],
+      "effect": {
+        "condition": { "===": [{ "var": "consentimentoLgpd" }, false] },
+        "properties": { "disabled": true },
+        "propertiesWhenFalse": { "disabled": false }
+      }
+    },
+    {
+      "id": "rule-aviso-lgpd-sem-consentimento",
+      "name": "Aviso LGPD sem consentimento",
+      "metadata": {
+        "origin": "llm",
+        "reviewStatus": "pending"
+      },
+      "targetType": "visualBlock",
+      "targets": ["aviso-lgpd"],
+      "effect": {
+        "condition": { "===": [{ "var": "consentimentoLgpd" }, false] },
+        "properties": {
+          "visible": true,
+          "message": "Aceite o termo de privacidade para continuar."
+        },
+        "propertiesWhenFalse": {
+          "visible": false
+        }
+      }
+    }
+  ]
+}
+```
+
+## Prompt para explicar regra existente
+
+```text
+Explique esta regra para um analista de negocio.
+
+Responda com:
+1. Quando ela dispara.
+2. O que ela altera.
+3. Se afeta payload ou apenas UI.
+4. Riscos de negocio.
+5. Diagnostics que precisam correcao.
+```
+
+A explicacao deve traduzir Json Logic para linguagem de dominio e citar os
+alvos por label quando o contexto tiver label disponivel.
+
+## Prompt para corrigir diagnostics
+
+```text
+Corrija as regras abaixo usando os diagnostics do editor.
+
+Nao mude a intencao de negocio.
+Se um alvo nao existir, proponha o alvo existente mais proximo e explique.
+Se uma propriedade for rejeitada pelo schema, substitua por uma propriedade
+permitida ou remova com justificativa.
+Mantenha metadata.reviewStatus como "pending".
+```
+
+Mapeamento operacional:
+
+| Diagnostic | Acao esperada da LLM |
+| --- | --- |
+| `missing-targets` | Pedir ou preencher `targets`. |
+| `field-target-not-found` | Trocar por `fieldMetadata[].name` existente. |
+| `target-not-found` | Trocar por alvo existente no mesmo `targetType`. |
+| `invalid-condition` | Reescrever como Json Logic canonico. |
+| `unsupported-property` | Usar propriedade permitida por `RULE_PROPERTY_SCHEMA`. |
+| `unsupported-target-type` | Escolher um `targetType` permitido. |
+| `missing-effect` | Criar `effect.condition` e `effect.properties`. |
+| `rule-evaluation-error` | Simplificar condicao e remover operadores nao suportados. |
+
+Quando o diagnostic envolver apenas propriedade rejeitada, valor invalido ou
+valor parcialmente saneado, o editor tambem pode aplicar a acao deterministica
+`Corrigir`. Essa acao usa o mesmo sanitizer central do runtime, remove ou
+coage propriedades conforme `RULE_PROPERTY_SCHEMA` e regenera `formRulesState`.
+Use LLM quando a correcao exigir decisao semantica de dominio, por exemplo
+trocar uma propriedade inexistente por outra intencionalmente equivalente ou
+explicar por que uma regra deve ser removida.
+
+## Fluxo de aplicacao seguro
+
+1. Host/editor monta o pacote de contexto.
+2. LLM gera uma proposta por operacao autoral ou em `formRules`.
+   Para regra de negocio, politica, elegibilidade, validacao, compliance ou
+   decisao compartilhada, use `domain-rules`/`shared_rule_authoring` antes de
+   materializar `form_config`. Para uma projecao visual derivada de decisao ja
+   governada, aceite `operationId: "rule.visualBlockGuidance.add"` com
+   `type: "visualBlockGuidance"`, `targetType: "visualBlock"`,
+   `context: "notification"` e metadata pendente.
+3. Compilador/adapter rejeita qualquer tentativa de gravar `formRulesState`.
+4. Editor valida alvos, condicao e propriedades.
+5. Editor mostra diff e impacto para o analista.
+6. Analista aceita, edita ou rejeita.
+7. Ao aceitar, editor marca `metadata.reviewStatus: "accepted"`.
+8. Editor tenta gerar `formRulesState` por conversor interno.
+9. Runtime aplica regra e emite `ruleDiagnosticsChange` se houver problema.
+
+## Guardrails permanentes
+
+- Nunca persistir codigo executavel em regra.
+- Nunca editar `formRulesState` diretamente por LLM.
+- Nunca tentar contornar essa regra no patch final: `compileAiResponse` e
+  `applyPatch` tambem rejeitam escrita direta em `formRulesState`.
+- Nunca materializar regra visual direto no estado do builder. O editor preserva
+  semantica de `formRules[].type` usando `config.ruleType` internamente no
+  round-trip.
+- Nunca criar alvo que nao exista no mapa de targets.
+- Nunca usar propriedade fora do schema permitido.
+- Nunca tratar `visualBlock` como campo.
+- Para `visualBlock` com varios nos editaveis, usar o node id correspondente em
+  `textNodeId`, `titleNodeId` ou `messageNodeId`.
+- Nunca esconder erro de regra: todo descarte deve virar diagnostic ou status.
+- Regras LLM entram como `pending`; aceite humano e uma decisao explicita.
+
+## Sinal de prontidao para runtime
+
+Uma regra esta pronta para runtime quando:
+
+- todos os targets existem;
+- a condicao e Json Logic valida;
+- as propriedades passam pelo whitelist;
+- o impacto foi explicado;
+- o preview true/false foi revisado;
+- a origem/revisao esta coerente;
+- o runtime nao emite diagnostic apos aplicar.