@praxisui/dynamic-form 8.0.0-beta.11 → 8.0.0-beta.13

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'],
+              },
             ],
           },
         ],
@@ -321,10 +330,10 @@ Alternatively, when `enableCustomization` is true, `praxis-dynamic-form` renders
 `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:** 10 target kinds: `field`, `section`, `row`, `column`, `formAction`, `formRule`, `message`, `layoutPlacement`, `localField`, `schemaBackedField`.
-- **Operations:** Supports 22 operations covering field property updates, local field lifecycle, layout manipulation, rule management, and action configuration.
-- **Validation:** 19 deterministic validators ensure uniqueness of IDs, layout integrity, local/schema-backed separation, destructive confirmation, and editor round-trip preservation.
-- **Examples/evals:** 8 fixtures cover local transient fields, schema-backed relabeling, layout moves, visibility rules, unknown target rejection, destructive confirmation, and save/reopen without drift.
+- **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`.
@@ -432,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'],
+            },
           ],
         },
       ],
@@ -465,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