@praxisui/dynamic-form 8.0.0-beta.1 → 8.0.0-beta.12

package/README.md

@@ -70,10 +70,11 @@ Peer dependencies (Angular v20):
 - `@angular/core` `^20.0.0`
 - `@angular/common` `^20.0.0`
 - `@angular/cdk` `^20.0.0`
-- `@praxisui/core` `^0.0.1`
-- `@praxisui/visual-builder` `^0.0.1`
-- `@praxisui/settings-panel` `^0.0.1`
-- `@praxisui/cron-builder` `^0.0.1`
+- `@praxisui/core` `^8.0.0-beta.12`
+- `@praxisui/rich-content` `^8.0.0-beta.10`
+- `@praxisui/visual-builder` `^8.0.0-beta.10`
+- `@praxisui/settings-panel` `^8.0.0-beta.10`
+- `@praxisui/cron-builder` `^8.0.0-beta.10`
 
 ## Quick Start
 
@@ -112,8 +113,16 @@ export class FormDemoComponent {
         rows: [
           {
             columns: [
-              { id: 'col-fullName', fields: ['fullName'] },
-              { id: 'col-email', fields: ['email'] },
+              {
+                id: 'col-fullName',
+                items: [{ kind: 'field', id: 'field-fullName', fieldName: 'fullName' }],
+                fields: ['fullName'],
+              },
+              {
+                id: 'col-email',
+                items: [{ kind: 'field', id: 'field-email', fieldName: 'email' }],
+                fields: ['email'],
+              },
             ],
           },
         ],
@@ -316,6 +325,19 @@ export class FormEditorLauncherComponent {
 
 Alternatively, when `enableCustomization` is true, `praxis-dynamic-form` renders a gear button that opens the editor internally.
 
+## Agentic Authoring & Manifest
+
+`praxis-dynamic-form` supports executable authoring contracts through the `ComponentAuthoringManifest`. This allows AI agents to perform structured, safe, and deterministic edits to the form configuration.
+
+- **Manifest:** `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST`
+- **Editable targets:** `field`, `section`, `row`, `column`, `visualBlock`, `formAction`, `formRule`, `message`, `layoutPlacement`, `localField`, `schemaBackedField`.
+- **Operations:** Covers field property updates, local field lifecycle, layout item manipulation, visual block authoring, rule management, and action configuration declared in `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST`.
+- **Validation:** Deterministic validators cover ID uniqueness, layout integrity, rich content document validity, local/schema-backed separation, destructive confirmation, and editor round-trip preservation.
+- **Examples/evals:** Fixtures cover local transient fields, schema-backed relabeling, layout moves, visual block add/move, visibility rules, unknown target rejection, destructive confirmation, and save/reopen without drift.
+- **Round-trip:** Preserves editor state and ensures that AI-generated patches are compatible with the visual editor.
+
+For more details on authoring manifests, see `docs/ai/agentic-authoring/component-authoring-contracts/README.md`.
+
 ## API Surface
 
 - Components: `PraxisDynamicForm`, `PraxisDynamicFormConfigEditor`, `JsonConfigEditorComponent`, `LayoutEditorComponent`
@@ -419,8 +441,16 @@ const formConfig: FormConfig = {
       rows: [
         {
           columns: [
-            { fields: ['fullName'] },
-            { fields: ['workEmail'] },
+            {
+              id: 'registration-full-name',
+              items: [{ kind: 'field', id: 'field-fullName', fieldName: 'fullName' }],
+              fields: ['fullName'],
+            },
+            {
+              id: 'registration-work-email',
+              items: [{ kind: 'field', id: 'field-workEmail', fieldName: 'workEmail' }],
+              fields: ['workEmail'],
+            },
           ],
         },
       ],
@@ -452,10 +482,62 @@ Notas:
 
 See public exports: `projects/praxis-dynamic-form/src/public-api.ts`.
 
+## Blocos visuais em colunas
+
+O layout de coluna usa `sections[].rows[].columns[].items[]` como contrato
+canônico ordenado. Itens `kind: 'field'` referenciam
+`fieldMetadata[].name`; itens `kind: 'richContent'` hospedam um
+`RichContentDocument` dentro da coluna e não entram em `fieldMetadata`,
+`formData` ou payload HTTP.
+
+`sections[].rows[].columns[].fields[]` permanece aceito como entrada de
+migração e como projeção derivada dos itens `kind: 'field'`, mas não deve ser
+usado para criar blocos visuais.
+
+No editor visual, **Campos da API** lista apenas campos existentes em
+`fieldMetadata[]` que ainda não aparecem em `columns[].items[]` como
+`kind: 'field'`. Ao adicionar um campo, o editor reinsere o item em `items[]`
+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
+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.
+
+Exemplo mínimo de uma coluna com campo, bloco visual e projeção `fields[]`:
+
+```json
+{
+  "items": [
+    {
+      "kind": "richContent",
+      "id": "identity-guidance-block",
+      "document": {
+        "schemaVersion": 1,
+        "nodes": [
+          {
+            "type": "paragraph",
+            "text": "Revise os dados principais antes de salvar."
+          }
+        ]
+      }
+    },
+    { "kind": "field", "id": "field-nome", "fieldName": "nome" },
+    { "kind": "field", "id": "field-email", "fieldName": "email" }
+  ],
+  "fields": ["nome", "email"]
+}
+```
+
+Guia completo: `projects/praxis-dynamic-form/docs/layout-items-visual-blocks.md`.
+
 ## Documentacao Tecnica da Lib
 
 - `projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.json-api.md`
 - `projects/praxis-dynamic-form/docs/hot-metadata-updates.md`
+- `projects/praxis-dynamic-form/docs/layout-items-visual-blocks.md`
 
 ## Header de seção com avatar dinâmico
 
@@ -665,14 +747,14 @@ Cobertura ja estabilizada:
 - `JSON` com edicao real e bloqueio de payload invalido
 - `Hooks`
 - `Acoes` (`Botoes Padrao` e `Layout`)
-- `Acoes` customizadas profundas (`showAlert` simples e estruturado)
+- `Acoes` customizadas profundas (`dialog.alert` com `globalAction` simples e estruturado)
 - `Comportamento`
 - `Mensagens`
 - `Dicas e Tooltips`
 
 Ajuste tecnico aplicado durante essa fase:
 - [praxis-dynamic-form-config-editor.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts) agora chama `this.jsonEditor?.updateJsonFromConfig(this.editedConfig)` em `onConfigChange(...)` para manter o editor JSON sincronizado com mudancas vindas de abas como `Hooks`.
-- [actions-editor.component.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts) agora mescla catalogo legado + catalogo global do app para o editor de acoes customizadas.
+- [actions-editor.component.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts) agora usa o catalogo global canonico do app para o editor de acoes customizadas.
 - [actions-editor.component.ts](/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-dynamic-form/src/lib/actions-editor/actions-editor.component.ts) agora preserva draft local dos campos globais e usa `track` estavel em `actions.custom`.
 
 Comando base usado para rerodar suites isoladas:
@@ -720,6 +802,7 @@ Apache-2.0 – see the `LICENSE` packaged with this library or the repository ro
 - Fluxo de Schema (ETag/304, schemaId, reconciliação): `projects/praxis-core/docs/schema-flow.md` (canônico) e `docs/schemas/fluxo-schema.md` (resumo operacional)
 - Guia de implementação e metadados da cascata: `docs/CASCADE-NATIVA.md`
 - Padrões de endpoints (Options vs Filter) para selects: `projects/praxis-dynamic-fields/docs/generic-crud-service.md` (canônico) e `docs/DEVS-GENERIC-CRUD-SERVICE.md` (resumo operacional)
+- Recipe oficial de Entity Lookup corporativo com `RESOURCE_ENTITY`, `dependsOn`, `dependencyFilterMap`, reidratação por `by-ids` e política de seleção: `examples/ai-recipes/praxis-dynamic-form.entity-lookup-procurement.json`
 
 ## Verificação de Schema (ETag/If-None-Match)