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

package/README.md

@@ -37,7 +37,7 @@ keywords:
   - "schema-driven"
   - "layout editor"
   - "settings integration"
-last_updated: "2026-03-22"
+last_updated: "2026-04-12"
 ---
 
 # @praxisui/dynamic-form
@@ -136,6 +136,74 @@ Tip: connect to a backend resource by setting `resourcePath`/`resourceId`. The c
 For metadata-driven surfaces published by the backend, prefer passing `schemaUrl`, `submitUrl` and `submitMethod` explicitly. In dialog/drawer hosts detached from the route injector, pass `apiUrlEntry` in addition to `apiEndpointKey` so relative runtime URLs still resolve against the remote backend instead of the local shell origin.
 When a late `config` hydration rebuilds the surface, the runtime preserves the current form values already mounted in memory only when the logical context remains the same (`resourcePath`, `resourceId`, and mode). If the form was preloaded from `resourceId`, that entity hydration remains visible after the rebuild only for the same entity context; entity switches and create-mode transitions do not restore the previous record snapshot.
 
+## Local fields, transient state, and submit payloads
+
+`praxis-dynamic-form` supports host-owned fields that participate in the form runtime without becoming part of the backend DTO. This is the right model for confirmation controls, wizard state, client-side calculated previews, host notes, and other UI context that should be available to rules and hooks but should not be persisted by default.
+
+The submit contract exposes two values:
+
+| Property | Meaning | Typical consumer |
+| --- | --- | --- |
+| `formSubmit.formData` | filtered persistence payload after submit policy is applied | HTTP submit, persistence hooks, backend DTO integration |
+| `formSubmit.rawFormData` | full form value before filtering | host hooks, UI audit context, diagnostics, calculations |
+
+Default behavior:
+
+- schema-backed fields are included in `formData`.
+- fields with `source: 'local'` are omitted from `formData` and kept in `rawFormData`.
+- fields with `transient: true` are omitted from `formData` and kept in `rawFormData`.
+- `submitPolicy` has priority over `source` and `transient`.
+
+| `submitPolicy` | Effect |
+| --- | --- |
+| `include` | always include the field in `formData` |
+| `omit` | always omit the field from `formData` |
+| `includeWhenDirty` | include the field in `formData` only when the control is dirty |
+
+Example:
+
+```ts
+fieldMetadata: [
+  { name: 'fullName', label: 'Full name', controlType: 'input' },
+  {
+    name: 'approvalComment',
+    label: 'Approval comment',
+    controlType: 'textarea',
+    source: 'local',
+    submitPolicy: 'omit',
+  },
+  {
+    name: 'calculatedRiskScore',
+    label: 'Risk score',
+    controlType: 'numericTextBox',
+    transient: true,
+    readOnly: true,
+  },
+  {
+    name: 'manualOverrideReason',
+    label: 'Manual override reason',
+    controlType: 'textarea',
+    source: 'local',
+    submitPolicy: 'includeWhenDirty',
+  },
+];
+```
+
+For a submitted value like:
+
+```json
+{
+  "fullName": "Ana Souza",
+  "approvalComment": "Checked with HR",
+  "calculatedRiskScore": 72,
+  "manualOverrideReason": "Approved exception"
+}
+```
+
+`rawFormData` keeps all four values. `formData` keeps `fullName` and, when dirty, `manualOverrideReason`; it omits `approvalComment` and `calculatedRiskScore`.
+
+Do not use local/transient fields to hide a backend contract problem. If a field exists in the backend schema, keep it server-backed and fix the canonical schema or metadata mapping instead of creating a parallel local convention.
+
 Presentation/read-only note:
 - `praxis-dynamic-form` hospeda `FieldMetadata`, mas não é o resolvedor direto de `valuePresentation`.
 - quando campos entram em modo view/presentation, a semântica de apresentação vem do metadata do campo e é resolvida por `@praxisui/dynamic-fields`.
@@ -248,6 +316,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:** 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.
+- **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`
@@ -597,14 +678,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:
@@ -652,6 +733,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)
 
@@ -666,9 +748,11 @@ Apache-2.0 – see the `LICENSE` packaged with this library or the repository ro
   - `form-schema-prefs:{formId}` → `{ notifyIfOutdated?, snoozeMs?, autoOpenSettingsOnOutdated? }`
   - Por hash (suppress): `schemaIgnore:{formId}:{hash}`, `schemaSnooze:{formId}:{hash}`, `schemaNotified:{formId}:{hash}`
 - Comportamento:
-  - Quando já existe base local (ex.: `config.sections.length > 0`), o componente faz uma verificação leve via `/schemas/filtered` com `If-None-Match`.
-  - 304 → apenas atualiza `lastVerifiedAt` e emite `schemaStatusChange(outdated=false)`.
-  - 200 → atualiza `serverHash/lastVerifiedAt`, define `schemaOutdated = enableCustomization && hadBase`, emite `schemaStatusChange`. Não aplica schema automaticamente.
+  - Quando existe uma config persistida para o `formId`, o componente normaliza a config local, baixa o schema estrutural canônico e reconcilia `fieldMetadata` antes de montar o formulário.
+  - Essa reconciliação preserva customizações locais intencionais, incluindo campos com `source: "local"`, `transient: true` e `submitPolicy`, mas atualiza semântica server-backed publicada pelo schema.
+  - Campos de select publicados com `x-ui.endpoint` em `/options/filter` preservam `endpoint` como operação concreta e `resourcePath` como recurso dono. Isso evita usar `/filter` ou consultar schema do endpoint de options por engano.
+  - 304 em verificações posteriores apenas atualiza `lastVerifiedAt` e emite `schemaStatusChange(outdated=false)`.
+  - 200 em verificações posteriores atualiza `serverHash/lastVerifiedAt`, define `schemaOutdated = enableCustomization && hadBase` e emite `schemaStatusChange`.
   - Primeira vez (sem base): baixa o corpo do schema para gerar o layout; persiste `form-schema-meta:{formId}`.
   - Notificações respeitam preferências e são one‑shot por hash; o banner/snackbar oferecem ações para Reconciliar, Lembrar depois (snooze) e Ignorar.