@praxisui/dynamic-form 9.0.0-beta.6 → 9.0.0-beta.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-form",
-  "version": "9.0.0-beta.6",
+  "version": "9.0.0-beta.61",
   "description": "Angular dynamic form engine for Praxis UI: metadata-driven forms, hooks, and services integrating @praxisui/* packages.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -9,13 +9,13 @@
     "@angular/forms": "^21.0.0",
     "@angular/material": "^21.0.0",
     "@angular/router": "^21.0.0",
-    "@praxisui/ai": "^9.0.0-beta.6",
-    "@praxisui/dynamic-fields": "^9.0.0-beta.6",
-    "@praxisui/metadata-editor": "^9.0.0-beta.6",
-    "@praxisui/rich-content": "^9.0.0-beta.6",
-    "@praxisui/settings-panel": "^9.0.0-beta.6",
-    "@praxisui/visual-builder": "^9.0.0-beta.6",
-    "@praxisui/core": "^9.0.0-beta.6",
+    "@praxisui/ai": "^9.0.0-beta.61",
+    "@praxisui/dynamic-fields": "^9.0.0-beta.61",
+    "@praxisui/metadata-editor": "^9.0.0-beta.61",
+    "@praxisui/rich-content": "^9.0.0-beta.61",
+    "@praxisui/settings-panel": "^9.0.0-beta.61",
+    "@praxisui/visual-builder": "^9.0.0-beta.61",
+    "@praxisui/core": "^9.0.0-beta.61",
     "rxjs": "^7.8.0"
   },
   "dependencies": {
@@ -30,6 +30,7 @@
   "keywords": [
     "angular",
     "praxisui",
+    "praxis",
     "dynamic-form",
     "metadata",
     "schema-driven",
@@ -46,7 +47,10 @@
     ".": {
       "types": "./types/praxisui-dynamic-form.d.ts",
       "default": "./fesm2022/praxisui-dynamic-form.mjs"
+    },
+    "./ai/component-registry.json": {
+      "default": "./ai/component-registry.json"
     }
   },
   "type": "module"
-}
+}

package/src/lib/config-editor/praxis-dynamic-form-config-editor.json-api.md

@@ -58,7 +58,9 @@ Este documento e a referencia canonica da API JSON de praxis-dynamic-form-config
 - O editor visual e o editor JSON operam sobre `DynamicFormAuthoringDocument`.
 - O editor JSON aceita apenas o envelope canônico; payloads legados pertencem aos caminhos de compatibilidade do runtime.
 - `Apply` e `Save` emitem um snapshot canonico completo com semantica `replace-all`.
-- Em comandos condicionais, o editor visual autora `globalAction.payload` estruturado; `globalAction.payloadExpr` fica reservado ao JSON avancado e e preservado no round-trip quando nenhum payload estruturado e definido.
+- Em comandos condicionais, o editor visual autora o efeito primario `effects[0].globalAction.payload` estruturado; `globalAction.payloadExpr` fica reservado ao JSON avancado e e preservado no round-trip quando nenhum payload estruturado e definido.
+- Regras com multiplos `effects` continuam JSON-avancadas para autoria completa; ao editar o efeito primario pela UI, efeitos secundarios existentes sao preservados para evitar perda silenciosa.
+- Em `formCommandRules[].policy`, o editor visual autora os campos comuns `distinct`, `distinctBy` e `runOnInitialEvaluation`; campos avancados vindos do JSON, como `trigger`, `debounceMs`, `errorPolicy` e `missingValuePolicy`, sao preservados no preview/apply, mas nao sao expostos como controles visuais completos.
 - `config`, `bindings` e `contextSnapshot` substituem integralmente o estado autoral anterior.
 - Ausencia de `bindings.mode` limpa o binding persistido e restaura o modo default efetivo do host.
 - Ausencia de `contextSnapshot.backConfig`, `contextSnapshot.presentation` ou `contextSnapshot.schemaPrefs` significa remocao explicita do bloco ausente.
@@ -101,7 +103,7 @@ Este documento e a referencia canonica da API JSON de praxis-dynamic-form-config
 | `messages` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `hooks` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `formRules` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
-| `formRulesState` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | Internal | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hints` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `api` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |
 | `metadata` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |
@@ -139,7 +141,7 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
 | messages | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Active. |
 | hooks | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Active. |
 | formRules | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Active. |
-| formRulesState | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Active. |
+| formRulesState | Estado interno de round-trip do builder visual. | verified | internal-derived | Gerado pelo editor a partir de `formRules`; nao escrever diretamente. |
 
 ### Nested configuration blocks
 
@@ -152,7 +154,7 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
 | `messages` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
 | `hooks` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
 | `formRules` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
-| `formRulesState` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | internal-derived | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hints` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
 | `api` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
 
@@ -329,7 +331,7 @@ A entrada operacional vem via `SETTINGS_PANEL_DATA` (injetado pelo settings pane
 | `messages` | Active | Editado na aba Mensagens. |
 | `hooks` | Active | Editado na aba Hooks e JSON. |
 | `formRules` | Active | Gerado pela aba Regras (visual builder). |
-| `formRulesState` | Active | Persistido para round-trip sem perda. |
+| `formRulesState` | Internal | Persistido somente como estado de round-trip do builder visual; nao e contrato autoravel. |
 | `hints` | Active | Editado na aba Dicas e Tooltips. |
 | `api` | Partial | Sem aba dedicada; passa por JSON editor quando presente. |
 | `metadata` | Partial | Mantido em round-trip; sem painel dedicado. |
@@ -410,7 +412,7 @@ Correcao: e diff estrutural para UX do painel, nao auditoria de negocio.
 | `messages` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `hooks` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `formRules` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
-| `formRulesState` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | Internal | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hints` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
 | `api` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |
 | `metadata` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |

package/src/lib/praxis-dynamic-form.json-api.md

@@ -129,9 +129,10 @@ Essa fronteira preserva a premissa de plataforma: o formulario materializa e exp
 | `messages` | not-specified | not-specified | n/a | Partial | Chaves principais de submit/confirmacao usadas; contrato e mais amplo. |
 | `formRules` | not-specified | not-specified | n/a | Active | Aplicadas no pipeline de regras do runtime. |
 | `formCommandRules` | not-specified | not-specified | n/a | Active | Regras condicionais de comando avaliadas sobre `formData` estabilizado depois de `formRules`; primeiro corte suporta `global-action`. |
-| `formRulesState` | not-specified | not-specified | n/a | Active | Persistido para round-trip do builder visual. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | Internal | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hooks` | not-specified | not-specified | n/a | Active | Integracao de ciclo (before/after) via runtime de hooks. |
 | `hints` | not-specified | not-specified | n/a | Declared-only | Mantido no contrato/editor; sem render dedicado no template principal. |
+| `helpPresentation` | `FormHelpPresentationConfig` | No | `{ display: "inline" }` | Active | Politica visual para exibir `hint`/`helpText` dos campos sem alterar semantica dos DTOs; erros de validacao continuam inline. |
 | `fieldMetadata[].array` | `FieldArrayConfig` | No | n/a | Active | Contrato de Editable Collection apenas quando `fieldMetadata[].controlType === "array"` ou quando `x-ui.array` foi publicado explicitamente. |
 
 Nota editorial:
@@ -192,7 +193,7 @@ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecn
 | `api` | not-specified | not-specified | n/a | component-defined | Declarado no modelo; sem binding operacional direto no runtime atual. |
 | `messages` | not-specified | not-specified | n/a | component-defined | Chaves principais de submit/confirmacao usadas; contrato e mais amplo. |
 | `formRules` | not-specified | not-specified | n/a | component-defined | Aplicadas no pipeline de regras do runtime. |
-| `formRulesState` | not-specified | not-specified | n/a | component-defined | Persistido para round-trip do builder visual. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | internal-derived | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hooks` | not-specified | not-specified | n/a | component-defined | Integracao de ciclo (before/after) via runtime de hooks. |
 | `sections[].sectionHeader` | `FormSectionHeaderConfig` | No | n/a | Active | Header visual rico da seção com suporte a avatar dinâmico resolvido a partir de `formData`. |
 
@@ -559,7 +560,7 @@ No ecossistema Praxis, ele funciona tanto como runtime final quanto como superfi
 
 | Input | Tipo | Default | Status | Runtime notes |
 | --- | --- | --- | --- | --- |
-| `config` | `FormConfig` | `{ sections: [] }` | Active | Contrato principal consumido no ciclo inteiro. |
+| `config` | `FormConfig` | `{ sections: [] }` | Active | Contrato principal consumido no ciclo inteiro. `sections` é opcional somente para forms schema-driven com grounding explícito (`metadata.source='schema'`, schema metadata ou fonte runtime como `schemaUrl`/`resourcePath`); ausência de layout manual é normalizada internamente como array vazio e permite que `layoutPolicy`/schema materializem agrupamentos. |
 | `resourcePath` | `string \| undefined` | `undefined` | Active | Habilita carga de schema/dados remotos. Opcional quando `schemaUrl` explícito é fornecido. |
 | `resourceId` | `string \| number \| undefined` | `undefined` | Active | Carrega entidade no modo `edit/view`. |
 | `mode` | `'create' \| 'edit' \| 'view'` | `'create'` | Active | Governa submit, leitura e apresentacao. |
@@ -576,6 +577,8 @@ No ecossistema Praxis, ele funciona tanto como runtime final quanto como superfi
 | `formId` | `string \| undefined` | `undefined` | Active | Chave de persistencia e identidade logica. |
 | `componentInstanceId` | `string \| undefined` | `undefined` | Active | Isola instancias com mesmo `formId`. |
 | `layout` | `FormLayout \| undefined` | `undefined` | Partial | Funciona como override estrutural em parte dos fluxos de layout/editor. |
+| `generatedLayoutPreset` | `'default' \| 'compactPresentation'` | `'default'` | Active | Usado apenas ao criar a configuracao inicial a partir de schema/metadata; nao reprocessa layouts persistidos ou authorados. |
+| `layoutPolicy` | `DynamicFormLayoutPolicy \| null` | `null` | Active | Politica opt-in para materializar layout a partir do schema atual. Use `source: 'schema'` com `persistence: 'transient'` para detalhe/read-only e command forms schema-driven sem persistir `sections` geradas nem reabrir configuracao local salva; politicas de host em `config`, como `helpPresentation`, continuam sendo aplicadas ao layout materializado. Em `mode='view'`, `intent: 'detail'` ou `preset: 'compactPresentation'` ativa apresentacao quando `presentationModeGlobal` nao foi informado; use `[presentationModeGlobal]=false` para controles read-only tradicionais. No preset `compactPresentation`, `x-ui.width` explicito empacota campos em linhas de 12 colunas e tem precedencia sobre `detailSummary.columns` por default; campos sem width permanecem full-width, a menos que `detailSummary.columns`/`responsiveColumns` declare a densidade do resumo. Use `detailSummary.widthPrecedence='summary'` quando a densidade do resumo read-only deve sobrescrever `x-ui.width` apenas nessa surface compacta. Use `responsiveColumns`, por exemplo `{ lg: 3, md: 2, sm: 1 }`, para drawers, side sheets e painéis corporativos estreitos sem copiar `FormConfig.sections` locais. `schemaType` e `schemaOperation` sao validados contra `schemaUrl` quando a URL declara esses parametros. |
 | `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. |
@@ -588,8 +591,34 @@ No ecossistema Praxis, ele funciona tanto como runtime final quanto como superfi
 | `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. |
 
+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:
+
+| Surface | Inputs | Contract gate |
+| --- | --- | --- |
+| Detail/read-only | `layoutPolicy.source='schema'`, `intent='detail'`, `preset='compactPresentation'`, `persistence='transient'`, `schemaType='response'` | Response DTO publishes business grouping, order, labels, value presentation and safe widths. |
+| Create/edit | `layoutPolicy.source='schema'`, `intent='command'`, `preset='groupedCommand'`, `persistence='transient'`, `schemaType='request'` | Request DTO/write contract publishes only editable fields, validators, options and help text required for the command. |
+| Dense command drawer | `config.helpPresentation.display='auto'` with `preferPopoverForControls` for select, checkbox, toggle, date/datepickers and numeric controls | DTO help text is semantic and not a substitute for validation messages. |
+| Input-heavy operational form | `fieldIconPolicy='presentation-only'` | Icons remain useful in read-only presentation but do not crowd editable controls. |
+
+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:
@@ -686,7 +715,7 @@ Precedencias importantes:
 | `api` | Declared-only | Declarado no modelo; sem binding operacional direto no runtime atual. |
 | `messages` | Partial | Chaves principais de submit/confirmacao usadas; contrato e mais amplo. |
 | `formRules` | Active | Aplicadas no pipeline de regras do runtime. |
-| `formRulesState` | Active | Persistido para round-trip do builder visual. |
+| `formRulesState` | Internal | Persistido somente como estado de round-trip do builder visual; nao e contrato autoravel. |
 | `hooks` | Active | Integracao de ciclo (before/after) via runtime de hooks. |
 | `hints` | Declared-only | Mantido no contrato/editor; sem render dedicado no template principal. |
 
@@ -863,7 +892,7 @@ O runtime emite `target-not-found` quando uma regra aponta para `section`, `row`
 | `api` | not-specified | not-specified | n/a | Declared-only | Declarado no modelo; sem binding operacional direto no runtime atual. |
 | `messages` | not-specified | not-specified | n/a | Partial | Chaves principais de submit/confirmacao usadas; contrato e mais amplo. |
 | `formRules` | not-specified | not-specified | n/a | Active | Aplicadas no pipeline de regras do runtime. |
-| `formRulesState` | not-specified | not-specified | n/a | Active | Persistido para round-trip do builder visual. |
+| `formRulesState` | internal-round-trip | Gerado pelo builder visual; nao e alvo de autoria manual ou IA. | n/a | Internal | Estado visual derivado de `formRules` para reabertura do editor. |
 | `hooks` | not-specified | not-specified | n/a | Active | Integracao de ciclo (before/after) via runtime de hooks. |
 | `hints` | not-specified | not-specified | n/a | Declared-only | Mantido no contrato/editor; sem render dedicado no template principal. |