@praxisui/dynamic-form 7.0.0-beta.0 → 8.0.0-beta.1

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`.
@@ -666,9 +734,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.