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

package/docs/dynamic-form-rules-authoring-plan.md

@@ -0,0 +1,379 @@
+---
+title: "Dynamic Form Rules Authoring Plan"
+slug: "dynamic-form-rules-authoring-plan"
+description: "Plano canonico para evoluir a autoria de regras do Dynamic Form com builder visual, LLM, preview, validacao e visual blocks."
+doc_type: "guide"
+document_kind: "host-guide"
+category: "architecture"
+audience:
+  - "frontend"
+  - "host"
+  - "platform-team"
+  - "architect"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-form"
+  - "rules"
+  - "visual-builder"
+  - "llm"
+  - "visual-blocks"
+toc: true
+sidebar: true
+reading_time: "16 min"
+estimated_setup_time: "multi-phase"
+last_updated: "2026-04-22"
+source_of_truth:
+  - "projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts"
+  - "projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.html"
+  - "projects/praxis-dynamic-form/src/lib/utils/rule-converters.ts"
+  - "projects/praxis-dynamic-form/src/lib/utils/rule-property.utils.ts"
+  - "projects/praxis-dynamic-form/src/lib/services/form-rules.service.ts"
+  - "projects/praxis-core/src/lib/models/form/rule-property.schema.ts"
+  - "projects/praxis-dynamic-form/src/lib/ai/praxis-dynamic-form-authoring-manifest.ts"
+  - "projects/praxis-dynamic-form/docs/dynamic-form-llm-rule-authoring-guide.md"
+---
+
+# Dynamic Form Rules Authoring Plan
+
+Este plano define como a autoria de regras do Dynamic Form deve evoluir para suportar a complexidade real da funcionalidade: regras visuais, regras criadas por LLM, round-trip no builder, preview, alvos estruturais e blocos visuais.
+
+## Escopo deste documento
+
+Este documento governa a evolucao da experiencia de autoria de regras no editor do `praxis-dynamic-form`. Ele nao substitui a referencia JSON API nem o contrato de visual blocks; ele amarra esses contratos em uma estrategia implementavel para UX, validacao, LLM e testes.
+
+## Pre-requisitos
+
+- Conhecer `FormConfig`, `formRules` e `formRulesState`.
+- Conhecer Json Logic canonico usado pelo runtime Praxis.
+- Conhecer `FormColumn.items[]` para campos e blocos `richContent`.
+- Consultar `RULE_PROPERTY_SCHEMA` antes de adicionar qualquer propriedade nova por regra.
+
+## Estado atual
+
+O editor de configuracao do Dynamic Form usa um `mat-tab-group`. A aba `Regras` renderiza `praxis-visual-builder`:
+
+```html
+<praxis-visual-builder
+  [config]="ruleBuilderConfig"
+  [initialRules]="ruleBuilderState"
+  (rulesChanged)="onRulesChanged($event)">
+</praxis-visual-builder>
+```
+
+Quando o builder muda, o editor persiste dois artefatos:
+
+| Artefato | Papel | Quem deve escrever |
+| --- | --- | --- |
+| `formRules` | Contrato executavel pelo runtime. | Builder visual, LLM validada ou JSON editor. |
+| `formRulesState` | Estado visual para reabrir o builder sem perda. | Apenas o builder/conversores internos. |
+
+O runtime consome `formRules` via `FormRulesService`. `formRulesState` nao deve participar da execucao.
+
+## Partes da funcionalidade
+
+A funcionalidade completa tem oito partes, que hoje estao espalhadas:
+
+| Parte | Estado atual | Lacuna principal |
+| --- | --- | --- |
+| Descoberta de alvos | `createRuleBuilderConfig` mapeia campos, secoes, linhas, colunas, actions e visual blocks. | Falta mapa de impacto legivel para o usuario. |
+| Condicao | Builder converte condicoes simples para Json Logic. | Condicoes complexas podem virar runtime-only. |
+| Efeito | `RULE_PROPERTY_SCHEMA` define propriedades permitidas por alvo. | UI mostra propriedades por alvo, rejeicoes do sanitizer e oferece correcao assistida. |
+| Conversao | `rule-converters.ts` faz round-trip `formRules` <-> `RuleBuilderState` e preserva metadados semanticos como `type: "visualBlockGuidance"` via `config.ruleType`. | Nao ha status explicito de compatibilidade visual. |
+| Execucao | `FormRulesService` resolve valores calculados de campos em fase anterior, aplica propriedades saneadas e o editor oferece preview true/false para revisar o efeito antes de persistir. | Falta ampliar mensagens de diagnóstico para casos de sanitizer parcial. |
+| LLM | Manifesto publica operacoes locais de component/form authoring e preserva `rule.visualBlockGuidance.add` apenas como projecao visual opcional. | Business-rule authoring deve entrar por `domain-rules`/`shared_rule_authoring` antes de virar `form_config`. |
+| Visual blocks | Alvo `visualBlock` existe, entra em `targetSchemas.visualBlocks`, aceita `text`, `title` e `message` saneados e o painel de propriedades guia `textNodeId`, `titleNodeId` e `messageNodeId`. | Falta apenas ampliar biblioteca de exemplos visuais por domínio, sem mudar o contrato. |
+| Governanca | Propriedades nao whitelisted sao descartadas, aparecem para o autor e podem ser corrigidas pelo painel de diagnosticos. | Expandir telemetria/curadoria conforme o catalogo publico amadurecer. |
+
+## Modelo mental alvo
+
+A aba `Regras` deve virar uma experiencia guiada com cinco etapas internas:
+
+```mermaid
+flowchart LR
+  target["1. Alvo"] --> condition["2. Condicao"]
+  condition --> effect["3. Efeito"]
+  effect --> preview["4. Preview"]
+  preview --> review["5. Revisao"]
+  review --> apply["Aplicar em formRules"]
+```
+
+Isso nao exige trocar o editor inteiro para stepper. O editor geral pode continuar em abas. O fluxo guiado deve existir dentro da aba `Regras`.
+
+## Contrato de compatibilidade
+
+Toda regra deve receber um status calculado:
+
+| Status | Significado |
+| --- | --- |
+| `valid` | Executavel no runtime. |
+| `invalid-target` | Um ou mais targets nao existem. |
+| `invalid-condition` | Condicao nao e Json Logic valida. |
+| `invalid-value-expression` | Valor calculado de campo usa Json Logic invalido ou envelope ambiguo. |
+| `computed-value-iteration-limit` | Valores calculados encadeados nao estabilizaram dentro do limite do runtime. |
+| `unsupported-property` | Efeito contem propriedade fora do whitelist. |
+| `runtime-only` | Regra executa, mas nao reabre fielmente no builder visual. |
+| `visual-builder-compatible` | Regra executa e reabre no builder visual. |
+| `llm-generated-pending-review` | Sugestao da LLM ainda nao aprovada pelo usuario. |
+
+O status deve ser exibido na lista de regras, no painel de revisao e no resumo de alteracoes.
+
+## Regras criadas por LLM
+
+LLM pode sugerir materializacoes visuais derivadas, mas deve seguir estas politicas:
+
+- LLM nao usa `formRules` ou `visualBlockGuidance` como fonte canonica da regra de negocio.
+- Quando a decisao governada precisa aparecer na UI, a materializacao escreve apenas `formRules`.
+- LLM nunca escreve `formRulesState`.
+- Operacoes de IA `rule.visibility.add`, `rule.validation.add` e
+  `rule.visualBlockGuidance.add` exigem
+  `metadata.origin: "llm"` e `metadata.reviewStatus: "pending"` no manifesto.
+- Para regra de negocio, politica, elegibilidade, validacao, compliance ou
+  decisao compartilhada, preferir `domain-rules`/`shared_rule_authoring`.
+- Para materializacao visual derivada de uma decisao ja governada, aceitar
+  `rule.visualBlockGuidance.add` com `type: "visualBlockGuidance"`,
+  `targetType: "visualBlock"` e `context: "notification"`.
+- Toda condicao deve ser Json Logic canonico.
+- Valores calculados em `effect.properties.value` e
+  `effect.propertiesWhenFalse.value` devem usar envelope fechado e exclusivo:
+  exatamente `{ "expression": <JsonLogic> }` ou exatamente
+  `{ "literal": <valor> }`. Objetos literais estruturados precisam do envelope
+  `literal`; envelopes com chaves extras sao rejeitados.
+- Valores calculados sao resolvidos antes das demais propriedades por iteracao
+  limitada ate estabilizacao, entao regras dependentes nao devem depender da
+  ordem no array de `formRules`.
+- Toda propriedade deve existir em `RULE_PROPERTY_SCHEMA[targetType]`.
+- Todo target deve existir no `ruleBuilderConfig.targetSchemas`.
+- Remocao de regra exige confirmacao humana.
+- Regra criada por LLM entra como `llm-generated-pending-review`.
+- Ao aceitar, o editor tenta gerar `formRulesState` por `formLayoutRulesToBuilderState`.
+- O round-trip deve preservar metadados semanticos. Quando o builder precisar
+  usar `config.type` para o tipo visual do node, o discriminador da regra deve
+  viajar como `config.ruleType` e voltar para `formRules[].type`.
+- Se o round-trip perder semantica, a regra fica `runtime-only` e precisa aviso claro.
+
+O guia operacional para prompts, contexto minimo, exemplos LGPD e correcao de
+diagnostics fica em `./dynamic-form-llm-rule-authoring-guide.md`.
+
+## Visual blocks em regras
+
+O alvo `visualBlock` ja existe no schema de propriedades. No estado atual, o whitelist permite:
+
+| Propriedade | Uso |
+| --- | --- |
+| `visible` | Exibir quando a condicao e verdadeira. |
+| `hidden` | Ocultar quando a condicao e verdadeira. |
+| `text` | Sobrescrever texto apenas em documento simples ou node `text` identificado. |
+| `textNodeId` | Escolher explicitamente o node que recebera `text`. |
+| `title` | Sobrescrever titulo apenas em documento simples ou node `title` identificado. |
+| `titleNodeId` | Escolher explicitamente o node que recebera `title`. |
+| `message` | Sobrescrever mensagem apenas em documento simples ou node `message` identificado. |
+| `messageNodeId` | Escolher explicitamente o node que recebera `message`. |
+| `layout` | Alternar entre `block` e `inline`. |
+| `rootClassName` | Classe no wrapper raiz. |
+| `className` | Classe CSS do bloco. |
+| `style` | Estilo inline saneado. |
+
+O contrato seguro para `title`, `message` e `text` e:
+
+- aplicar apenas em documentos simples ou nodes identificados;
+- presets criados pelo layout usam ids convencionais: `text`, `title` e `message`;
+- nodes identificados podem estar no primeiro nivel ou aninhados em `compose`/`card`;
+- o painel de propriedades permite escolher um node identificado e persiste `textNodeId`, `titleNodeId` ou `messageNodeId`;
+- rejeitar HTML arbitrario, handlers, URLs inseguras e documentos inteiros;
+- preservar `RichContentDocument` original como fonte de verdade;
+- aplicar override em runtime sem transformar bloco visual em campo;
+- cobrir com testes unitarios de sanitizer, runtime e E2E visual.
+
+## Mapa de impacto
+
+Cada regra deve exibir:
+
+- alvos afetados;
+- campos usados na condicao;
+- propriedades alteradas em true/false;
+- se afeta submit;
+- se e visual-only;
+- se depende de bloco visual, secao, linha ou coluna;
+- se ha alvo inexistente;
+- se alguma propriedade foi descartada pelo sanitizer.
+
+Impacto esperado por alvo:
+
+| Target type | Impacto no submit | Observacao |
+| --- | --- | --- |
+| `field` | Pode afetar payload indiretamente por `required`, `disabled`, `readonly` e `defaultValue`. | Exige cuidado maior. |
+| `section` | Normalmente visual, mas pode ocultar varios campos. | Precisa listar campos descendentes. |
+| `row` | Visual/layout. | Pode esconder grupo de campos. |
+| `column` | Visual/layout. | Pode alterar alinhamento responsivo. |
+| `action` | Pode bloquear fluxo operacional. | `disabled`, `loading` e `visible` devem ser revisados. |
+| `visualBlock` | Visual-only. | Nunca entra em `fieldMetadata`, `FormControl` ou payload. |
+
+## Preview requerido
+
+O editor deve ter preview true/false por regra:
+
+1. O usuario escolhe uma regra.
+2. O painel mostra os campos usados na condicao.
+3. O usuario edita valores de exemplo.
+4. O editor avalia Json Logic.
+5. O preview aplica `properties` ou `propertiesWhenFalse`.
+6. O diff mostra o que muda no formulario.
+
+Esse preview deve funcionar sem backend. Para campos remotos/selects, usar valores de exemplo do metadata ou entrada manual.
+
+## Design e UX alvo
+
+A aba `Regras` deve ter tres areas:
+
+| Area | Conteudo |
+| --- | --- |
+| Lista | Regras, status, origem, alvo e busca/filtro. |
+| Builder | Fluxo Alvo -> Condicao -> Efeito. |
+| Preview | Estado true/false, impacto, JSON e diff. |
+
+Filtros minimos:
+
+- por alvo;
+- por origem: manual, JSON, LLM;
+- por status;
+- por propriedade alterada.
+
+Microcopy obrigatoria:
+
+- explicar que `formRules` executa no runtime;
+- explicar que `formRulesState` e somente para o builder visual;
+- marcar `runtime-only` sem tom de erro fatal;
+- marcar LLM como sugestao pendente de revisao.
+
+## Roadmap incremental
+
+### Fase 1 - Validador central
+
+Status: implementado.
+
+Criar um validador puro, sem UI, que recebe `FormConfig` e retorna status por regra.
+
+Entradas:
+
+- `formRules`;
+- `formRulesState`;
+- `fieldMetadata`;
+- `sections`;
+- `actions`;
+- `RULE_PROPERTY_SCHEMA`.
+
+Saida:
+
+```ts
+interface FormRuleDiagnostics {
+  ruleId: string;
+  status: RuleAuthoringStatus[];
+  targetRefs: Array<{ type: string; id: string; exists: boolean }>;
+  conditionRefs: string[];
+  acceptedProperties: string[];
+  rejectedProperties: string[];
+  runtimeOnlyReason?: string;
+}
+```
+
+### Fase 2 - Status na UI
+
+Status: implementado com diagnostics acionaveis e correcao assistida.
+
+Exibir diagnostics na aba `Regras`:
+
+- badge por regra;
+- resumo de problemas;
+- link para abrir o alvo no layout;
+- aviso quando o sanitizer descarta propriedade.
+- acao `Corrigir` para aplicar whitelist/saneamento central e regenerar `formRulesState`.
+
+### Fase 3 - Preview true/false
+
+Status: implementado como preview/diff de propriedades de regra; ainda cabe evolucao visual do formulario completo.
+
+Adicionar painel de preview isolado:
+
+- avaliar Json Logic com valores mockados;
+- mostrar `properties` versus `propertiesWhenFalse`;
+- aplicar preview visual sem persistir;
+- exibir diff JSON.
+
+### Fase 4 - LLM review lane
+
+Status: implementado para regras ja sugeridas/persistidas como pendentes; geracao de sugestao por LLM ainda e proxima evolucao.
+
+Criar fluxo de aceite para sugestoes de LLM:
+
+- `Generate suggestion`;
+- validar;
+- mostrar diff;
+- permitir editar antes de aplicar;
+- marcar origem `llm`;
+- gerar `formRulesState` somente apos aceite.
+
+### Fase 5 - Visual block text seguro
+
+Status: implementado como primeira versao segura.
+
+O suporte a `title`, `message` e `text` em regras de `visualBlock` fica limitado a:
+
+- nodes de texto simples;
+- nodes com `id` estavel;
+- ids convencionais gerados por presets do layout;
+- escolha explicita de node pelo painel de propriedades da regra;
+- overrides saneados em runtime;
+- sem mutar o documento original durante preview.
+
+### Fase 6 - Testes E2E visuais
+
+Status: cobertura implementada para os fluxos críticos; manter expansão incremental por domínio.
+
+Cobrir:
+
+- regra de field;
+- regra de section;
+- regra de action;
+- regra de row/column;
+- regra de visualBlock visible/style/text com node interno;
+- regra LLM pendente e aceita;
+- regra runtime-only;
+- round-trip builder;
+- formulario real de funcionarios.
+
+## Checklist de aceite
+
+- [x] Regra invalida nunca e aplicada silenciosamente em todos os fluxos de entrada cobertos: editor, manifesto LLM, JSON authoring e runtime.
+- [x] Propriedade descartada aparece na UI.
+- [x] LLM nao escreve `formRulesState`.
+- [x] Regra LLM so aplica apos revisao no fluxo de authoring do editor.
+- [x] Regra runtime-only permanece editavel em JSON e visivel na lista.
+- [x] Preview true/false funciona sem backend para propriedades de regra.
+- [x] Visual block continua fora de `fieldMetadata`, `FormControl` e payload.
+- [x] Text override de visual block e saneado e coberto por testes.
+- [x] Abrir, salvar, reabrir e renderizar preserva `formRules`, `formRulesState` e metadata de revisao LLM no round-trip coberto.
+- [x] A documentacao tecnica descreve limites do builder visual e da LLM.
+- [x] Publicar/espelhar guia na landing publica em `/components/dynamic-form/docs/rules-authoring`.
+- [x] Diagnostico diferencia propriedade fora do contrato, valor invalido e valor parcialmente saneado.
+- [x] Painel de diagnostics oferece correcao assistida para propriedades rejeitadas/saneadas e regenera `formRulesState`.
+- [x] Exemplos visuais por dominio demonstram `visualBlock` com regras de texto/estilo sem ampliar contrato.
+- [x] Exemplos de dominio conectados ao catalogo de recipes em `examples/ai-recipes/praxis-dynamic-form.visual-block-domain-rules.json`.
+
+## Proximos incrementos recomendados
+
+1. Manter E2E visual em formularios reais para regressao de payload, node interno e round-trip do builder.
+2. Espelhar a referencia JSON API atualizada na landing publica quando a pipeline de docs rodar.
+3. Publicar/curar o novo recipe de regras `visualBlock` na landing publica quando a pipeline de docs rodar.
+4. Evoluir a correcao assistida para sugerir substituicoes semanticas, nao apenas aplicar sanitizer deterministico.
+
+## Evidencia publicada
+
+- Guia tecnico canonico: `projects/praxis-dynamic-form/docs/dynamic-form-rules-authoring-plan.md`.
+- Guia operacional LLM/analista: `projects/praxis-dynamic-form/docs/dynamic-form-llm-rule-authoring-guide.md`.
+- Guia publico espelhado: `/components/dynamic-form/docs/rules-authoring`.
+- Recipe publico de dominio: `examples/ai-recipes/praxis-dynamic-form.visual-block-domain-rules.json`.
+- Cobertura focal de payload: `projects/praxis-dynamic-form/test-dev/e2e/funcionarios-form-demo-rules.playwright.spec.ts`.
+- Cobertura focal de editor de node interno, revisao LLM e correcao assistida: `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-rules.playwright.spec.ts`.
+- Cobertura focal de runtime fechado: `projects/praxis-dynamic-form/src/lib/services/form-rules.service.spec.ts`.

package/docs/hot-metadata-updates.md

@@ -0,0 +1,141 @@
+---
+title: "Dynamic Form Hot Metadata Updates"
+slug: "dynamic-form-hot-metadata-updates"
+description: "Guia operacional para aplicar patches de metadata em runtime no PraxisDynamicForm sem rebuild estrutural desnecessario."
+doc_type: "guide"
+document_kind: "host-guide"
+component: "dynamic-form"
+category: "integration"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-form"
+  - "hot-metadata"
+  - "runtime"
+  - "dynamic-fields"
+last_updated: "2026-03-07"
+toc: true
+sidebar: true
+related_docs:
+  - "dynamic-form-overview"
+  - "praxis-dynamic-form-json-api"
+  - "dynamic-fields-host-custom-field-guide"
+keywords:
+  - "hot update"
+  - "field metadata patch"
+  - "dynamic field loader"
+  - "component metadata registry"
+source_of_truth:
+  - "projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.ts"
+  - "projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.directive.ts"
+---
+
+# Dynamic Form Hot Metadata Updates
+
+## Objetivo
+
+Explicar como o `PraxisDynamicForm` aplica patches de metadata em runtime sem reconstruir o formulario inteiro quando isso nao e necessario.
+
+```mermaid
+flowchart LR
+    Patch["host aplica patch de metadata"] --> Runtime["PraxisDynamicForm"]
+    Runtime --> Hot["reaplica metadata no componente vivo"]
+    Runtime --> Refresh["refresh do loader afetado"]
+    Runtime --> Rebuild["buildFormFromConfig como fallback"]
+```
+
+## Pre-requisitos
+
+- entendimento basico de `FormConfig`, `FieldMetadata` e `DynamicFieldLoaderDirective`
+- familiaridade com o fluxo de configuracao de campos no `PraxisDynamicForm`
+
+## O que mudou no runtime
+
+- `PraxisDynamicForm` mantem referencias para os `DynamicFieldLoaderDirective` ativos, um por coluna.
+- Depois de aplicar um patch de metadata:
+  - atualiza o `FieldMetadata` canonico dentro da configuracao persistida;
+  - reusa o `FormControl` atual quando a mudanca e apenas de validacao/comportamento;
+  - reaplica metadata diretamente no componente vivo quando ele suporta hot metadata;
+  - faz `refresh()` apenas no loader afetado quando a mudanca exige rerender;
+  - cai em `buildFormFromConfig()` apenas como fallback seguro.
+
+## Quando o update continua hot
+
+O caminho de hot update e usado quando a alteracao nao muda a estrutura do campo, por exemplo:
+
+- `required`
+- `readonly`
+- `disabled`
+- `hidden`
+- `min`, `max`, `pattern`
+- labels, hints e metadata de apresentacao que o componente consegue receber em runtime
+
+Nesses casos o runtime:
+
+1. recalcula validators via `DynamicFormService.updateControlFromMetadata`;
+2. reaplica a metadata no componente por `setInputMetadata(...)` ou `WritableSignal`;
+3. evita rebuild completo do formulario.
+
+## Quando vira refresh estrutural
+
+Mudancas estruturais ainda exigem rerender do loader para manter integridade:
+
+- troca de `controlType`
+- inclusao ou remocao de campos
+- mudancas que alteram o conjunto de bindings esperados pelo componente
+
+Regra operacional:
+
+- se o loader da coluna for localizado, apenas ele e atualizado;
+- se o loader nao puder ser localizado, o runtime usa fallback seguro de rebuild do form.
+
+## Melhorias no DynamicFieldLoader
+
+O guard de rerender do loader passou a incluir no snapshot:
+
+- `required`
+- `readonly`
+- `disabled`
+- `hidden`
+
+Isso reduz casos em que o host alterava metadata valida mas a UI nao refletia a mudanca imediatamente.
+
+## Limites e pre-requisitos
+
+O hot update funciona melhor quando o field component:
+
+- expõe metadata por `WritableSignal`; ou
+- implementa `setInputMetadata(metadata)`; e
+- trabalha ligado a um `FormControl`
+
+Se o componente custom nao suporta isso, o runtime ainda funciona, mas cai no caminho de `loader.refresh()`.
+
+## Extensao no host
+
+Para fields custom do host:
+
+- registre o componente no `ComponentRegistryService`;
+- registre metadados editoriais no `ComponentMetadataRegistry`;
+- mantenha `controlType` e id de metadata alinhados;
+- implemente `setInputMetadata(...)` ou sinal equivalente para aproveitar hot updates.
+
+## Por que isso importa
+
+Em cenarios corporativos, esse fluxo reduz:
+
+- flicker visual
+- rebuilds desnecessarios
+- perda de foco durante configuracao de campos
+- custo de reconciliacao manual no host
+
+## Documentos relacionados
+
+- Dynamic Form overview: `dynamic-form-overview`
+- [Dynamic Form API](../src/lib/praxis-dynamic-form.json-api.md)
+- [Dynamic Fields Host Custom Field Guide](../../praxis-dynamic-fields/docs/dynamic-fields-host-custom-field-guide.md)