@praxisui/dynamic-form 10.0.0-rc.4 → 10.0.0-rc.41

package/README.md

@@ -29,6 +29,14 @@ Peer dependencies:
 - `@praxisui/ai`, `@praxisui/core`, `@praxisui/dynamic-fields`, `@praxisui/metadata-editor`, `@praxisui/rich-content`, `@praxisui/settings-panel`, `@praxisui/visual-builder` `^9.0.0-beta.12`
 - `rxjs` `^7.8.0`
 
+## Original item revision on submit
+
+In edit mode, the form keeps a single strong `ETag` together with the item representation returned by its hydration GET (`readUrl`, custom `getById` endpoint or ordinary resource GET). Automatic PUT/PATCH sends that exact tag as `If-Match`; it never performs another GET during submit to acquire a newer revision. A successful response that contains the corresponding item representation replaces both cached data and revision from that same response, including server normalization. A command acknowledgment or incomplete representation cannot rotate the original item snapshot. A shared CRUD cache read by another consumer cannot replace the form's original revision.
+
+The snapshot is transient and belongs to the resource identity, read/write target and API context. Preparation, reads and writes share a generation: switching away and back, reloading or destroying the surface cannot make an old callback current again. Obsolete automatic responses do not emit submit result events, run result hooks, publish field errors or reset a newer submit's loading state. If an obsolete preparation hook retained the reused form group, the draft requires explicit reload before another write. Changing those bindings requires hydration again. Missing or weak read ETags are not converted into versions; unversioned endpoints remain usable, while a versioned host can reject a missing precondition with `428`. After `412`/`428`, or a successful versioned write without its next ETag, automatic submission requires an explicit reload. Closing and reopening a surface or retrying its initialization loads the new representation; retrying submit alone cannot silently refresh the revision.
+
+Explicit `submitResourceVersion` and the existing cross-resource version target inputs retain their command semantics and precedence. They remain host-owned inputs; same-resource editing needs no additional authoring fields. Backend authorization, concurrency and lifecycle policy remain authoritative.
+
 ## Reactive backend determinations
 
 When the exact request schema from `/schemas/filtered` publishes root-level `x-ui.reactiveDeterminations`, the form executes the Metadata-compiled backend capability after a valid source changes and applies server-derived draft values. After edit/create hydration, an already populated source is also validated before the draft can be reported as stable; an empty initial source settles as not applicable without an HTTP call. The projection is one closed graph: if any definition is malformed, the complete projection is rejected instead of partially executing. It remains backend-owned, tenant-neutral and transient: it is never copied to `FormConfig` and cannot be authored as a callback, URL or local write policy.
@@ -47,6 +55,12 @@ Use `optionSource.dependsOn` for dependent option lists and workflow actions for
 
 Use a local `FormConfig` when the host already knows the sections and fields.
 
+With `configPersistenceStrategy="input-first"`, an explicitly bound host configuration remains authoritative even when it contains only actions or other policies. The schema for the current operation supplies missing fields and layout; stale persisted fields are not used to fill those gaps.
+
+Each form owns its mutable `GenericCrudService` and editor field/rule context. Sibling forms cannot change one another's resource, custom endpoints or schema client. This is a breaking beta correction for hosts that previously replaced an ancestor `GenericCrudService`: configure the form through `resourcePath`, `apiEndpointKey`, `apiUrlEntry` and the direct-form `customEndpoints` input. An ancestor service subclass is no longer used by the form; HTTP interceptors, `API_URL` and shared infrastructure remain inherited. Tests that substitute the client must use `TestBed.overrideComponent(PraxisDynamicForm, { add: { providers: [{ provide: GenericCrudService, useValue: crudMock }] } })`, retaining the other component providers.
+
+An explorer combining selectors from several resources is a local form, not an edit command for one of those resource DTOs. Its fields may query real API options through their own resource metadata while remaining `source: 'local'` with `submitPolicy: 'omit'`. Use a distinct form identity when replacing a schema-backed command with such an explorer; persisted connections are still restored for their original identity. The `/dependency-fields-demo` reference follows this pattern and gives the current host definition precedence with `configPersistenceStrategy="input-first"`; its previous `cascade-*` configurations and connections are left untouched.
+
 ```ts
 import { Component } from '@angular/core';
 import { FormConfig } from '@praxisui/core';
@@ -739,3 +753,81 @@ suportada, ocupa a linha seguinte. Nenhum documento ou protocolo de Save é alte
 - [Canonical technical overview: Overview](https://praxisui.dev/docs/components/praxis-dynamic-form)
 - [Praxis Angular public catalog](https://praxisui.dev/angular)
 <!-- praxis-npm-catalog-links:end -->
+
+### Filhos de páginas governadas
+
+Consulte [o adapter nativo de página](docs/governed-page-widget-adapter.md) para reconstrução sem defaults, presença exata, identidade derivada e execução sem preferências concorrentes.
+
+### Schema-backed custom fields
+
+Core expands an object marked `x-ui.customFieldsContainer: true` (or the inline
+`customFields` object) into fields named `customFields.<key>`. Dynamic Form uses
+those names as nested reactive-form paths and keeps the wire payload nested:
+`{ "customFields": { "numero_calcado": 38, "data_exame": "2026-10-27" } }`.
+The `customField`, `customFieldKey` and `customFieldScope` metadata identifies
+schema-backed fields; it does not make them local/transient authoring fields.
+Saved containers colliding with the server's expanded namespace are replaced by
+its direct children, including a container previously marked `source: 'local'`.
+Noncolliding local fields and existing child placement remain. Restrictive parent
+flags remain restrictive in children; they do not create a submit omission policy.
+
+Date controls hydrate nested API values without mutating the input. Submit applies
+the same date/lookup serialization, required/dirty handling and omission policies
+to flat and dotted names. Missing nested values do not create containers. Filter
+Form preserves supported nested values during same-context metadata rebuilds,
+unless the new field has an explicit default (reset). A removed server field can
+remain as metadata for layout continuity, but becomes disabled and omitted from
+applicable payloads. Hidden alone is not omission: explicit local and legitimate
+hidden fields keep their published semantics. No host adapter is needed for the
+supported nested value paths.
+
+Temporal normalization is metadata-aware: legacy date tuples and local datetime
+strings are transformed only on declared temporal fields, including collection
+item schemas. Numeric/unknown arrays such as `[2026, 10, 27]` remain arrays;
+ordinary/unknown strings retain their spaces and date-like text. The `DateInput`
+control follows date-only serialization. A same-context metadata rebuild can
+restore nested dirty/touched control paths, including collection items, without
+marking unrelated controls touched. This does not preserve a draft across every
+reset, identity switch or retry.
+
+Scalar arrays use the operation schema's `fieldMetadata[].items`, separately
+from object collections' `array.itemSchema.fields`. Core's shared normalizer turns
+valid UI tokens into declared strings, safe integers, finite numbers or exact
+booleans and enforces the item enum after conversion. Date/date-time item formats
+use that same contract. An invalid/null item rejects the entire projection rather
+than silently dropping it; an optional null container and an empty array remain
+distinct valid inputs. Form validation and prepared submit must agree, so a token
+such as `12.5` cannot be submitted as an integer. This subset does not promise
+integer precision beyond JavaScript's safe range or an object-array editor.
+
+Record paths do not traverse array intermediates in computed-rule contexts;
+collection submit uses its own item-schema pipeline. The canonical Metadata key
+policy rejects reserved control names such as `constructor`, `toString` and
+`hasOwnProperty`; payload helper support does not relax that policy. Existing
+stored definitions with such keys require a backend migration.
+
+Read-only/disabled does not automatically mean omission from `getRawValue()`.
+The canonical backend command request projection excludes read-only custom fields
+from properties and required, while response schemas retain them for display.
+Use the exact operation request schema; merging response fields into commands or
+adding an unimplemented `x-ui.submitPolicy` adapter would break that boundary.
+Reconciliation treats a successful empty schema as authoritative. Removed
+server-backed fields become hidden, disabled and `submitPolicy: 'omit'`, including
+manual sync and Filter; explicit local fields remain local. Reappearance restores
+the current server constraints rather than stale saved required/type/enum/items.
+
+Each fresh schema-loading cycle revalidates HTTP and normalizes its body; compiled
+L1 is not a readiness shortcut. A matching 304 can reuse the cached representation.
+Status 0, denied access, malformed schema and failed saved-config reconciliation
+cannot make the old form ready. Authorization errors show access feedback without
+a generic retry action; timeout/transport failures retain their retry surface.
+Schema loading/error or a known unconfirmed enterprise context blocks submit.
+Context changes cancel obsolete reads, revalidate metadata and invalidate the old
+initial-value seed; retry is not a general cross-context autosave guarantee.
+
+The confirmed enterprise context supplies effective tenant/locale and context
+version. Explicit schema URLs conflicting with that context are rejected. Identity
+visible only to cookies/interceptors still requires a captured context version or
+complete cache/session invalidation by the host; backend authorization is always
+required. See the [enterprise review](https://github.com/codexrodrigues/praxis-ui-angular/pull/658)
+for source, candidate gates, host proof and remaining adoption limits.