@praxisui/dynamic-form 9.0.66 → 9.0.68-rc.0

package/docs/schema-loading-recovery.md

@@ -0,0 +1,74 @@
+# Schema loading: timeout, cancellation and recovery
+
+## Owner and configuration
+
+Schema transport policy belongs to Core. Dynamic Form consumes the existing
+`SchemaMetadataClient` through `SCHEMA_METADATA_CLIENT_OPTIONS`; there is no
+widget-specific timeout input or JSON property. A host configures the provider:
+
+```ts
+import { SCHEMA_METADATA_CLIENT_OPTIONS } from '@praxisui/core';
+
+{ provide: SCHEMA_METADATA_CLIENT_OPTIONS, useValue: { requestTimeoutMs: 15000 } }
+```
+
+The shared Core default is 30,000 ms. An explicit zero disables the deadline;
+cancellation remains available. Core also owns transport error names:
+`TimeoutError` and `AbortError`. The Form legacy Observable schema adapter uses
+the same configured deadline and unsubscribes when cancelled.
+
+## Runtime behavior
+
+A schema timeout reaches the existing recoverable initialization error surface.
+The message is localized in the Form catalog. Retry starts a new initialization;
+it does not silently replace the requested `/all` schema with the legacy
+`/filter` schema after a timeout or cancellation.
+
+Destroy, retry, mode changes, resource changes and explicit schema URL changes
+cancel the outstanding schema reads. Initialization generations prevent an older
+configuration read, schema result, error handler or finally block from modifying
+the replacement initialization. The saved page layout is retained for retry and
+reconciled with the canonical schema after a successful response.
+
+## Scope and limitations
+
+This is transport resilience. During the investigation, the backend returned
+HTTP 200 to the exact schema URL while the internal browser reported
+`ERR_BLOCKED_BY_CLIENT`. A recoverable timeout does not remove that client block
+and must not be reported as correcting its origin.
+
+The deadline does not bound all initialization work. Hook execution keeps its
+existing hook-registry policy. Diagnostic schema metadata persistence is not part
+of the transport deadline; a non-transient host with stalled persistence can
+still need separate investigation. Transient layout policy skips those writes.
+No general initialization budget or local business rule was introduced.
+
+## Focused validation
+
+`praxis-dynamic-form.schema-loading.spec.ts` covers pending schema → localized
+error → retry, no timeout fallback to a different schema contract, destroy,
+late schema results, and late saved configuration after superseding initialization.
+The fixtures use the existing sections-only `input-first` path so reconciliation
+cannot swallow the timeout and report success with missing field metadata.
+Transport fetch cancellation and concurrent-consumer behavior are tested in Core.
+Live browser and integrated package builds are recorded by the integration review.
+
+
+The focal schema-loading, external-config-hydration and entity-selection run
+passed 29 tests (`/private/tmp/praxis-form-schema-loading-tests.log`). This run
+includes the error/retry DOM and isolated service fixtures; it does not claim
+live network or production publication validation.
+
+### Non-cooperative custom transports
+
+The canonical Core transport reports `AbortError` on cancellation. Two additional
+regressions exercise a transport that ignores cancellation and later rejects with
+a generic error, through both generated-config and host-config initialization.
+The inner construction error handlers validate the initialization generation
+before changing UI state, so the old error cannot stop the newer loading state.
+The late-success and late-error paths are covered independently.
+
+The two generic late-error cases failed before the guard (`2 FAILED, 5 SUCCESS`)
+and all seven schema-loading tests passed afterwards. Logs:
+`/private/tmp/praxis-form-late-schema-rejection-red.log` and
+`/private/tmp/praxis-form-late-schema-rejection-green.log`.

package/docs/section-spacing-authoring-2026-09-08.md

@@ -0,0 +1,61 @@
+# Section spacing: canonical eligibility and clear copy
+
+Classification: `local-pequena`, owned by Dynamic Form's layout editor.
+Adherence: `ja-suportado-mal-nomeado-ou-mal-materializado`. Core already defines
+`FormSection.gapBottom` as space after the entire section. The Form runtime reads
+that field; no contract, runtime spacing rule, backend or public API changed.
+
+The toolbar described column spacing but wrote section `gapBottom`. Eligibility
+depended on a noncanonical `gapCustomized` marker rather than the existing value,
+so an explicitly authored gap without that marker could be overwritten. New
+sections and bulk updates also generated the marker despite the JSON API guide
+warning that it was not stable configuration.
+
+The command now fills only absent/null `gapBottom`, preserves explicit values
+(including zero), and emits nothing when no sections are eligible. It no longer
+generates or consults the old marker; unrelated unknown properties in a loaded
+document are not bulk-migrated by this operation. Non-finite proposed numbers
+are rejected. Changing the proposed value alone still does not emit config.
+The existing output-to-input host flow commits the emitted draft.
+
+Labels, tooltips and accessible names use the layout editor i18n catalog in
+pt-BR/en-US. **Espaço após as seções** and **Preencher espaços não definidos**
+explain the scope and distinguish this command from editor-only density/guides.
+Existing icons, control styling and theme tokens are retained.
+
+## Browser proof
+
+On `/page-builder-ia`, selected Ayla, opened the Form editor and Layout, and
+captured the rendered Layout baseline. Entering 24 kept **Sem alterações** and
+disabled Apply/Save. Invoking **Preencher espaços não definidos** enabled
+Apply/Save and disabled the fill command. Reading the actual JSON editor showed
+the canonical editor envelope with `gapBottom: 24` on the four previously unset
+sections and no `gapCustomized` property.
+
+Cancelled, confirmed discard and reopened Layout on the same page. Its full
+rendered text exactly matched the baseline. No Apply, component Save, page Save
+or employee write was performed. Screenshot review covered the dark desktop
+editor, expanded and reduced panels; the new label wrapped without overlap.
+This is not mobile or full screen-reader certification. The runtime effect of
+gapBottom was not newly changed or certified through a persisted save.
+
+## Validation and artifacts
+
+The focused toolbar/editor suite adds explicit spacing, zero, fill-once,
+non-finite values, no empty emission and marker-free section creation checks.
+The first compile required a fixture assertion to acknowledge EventEmitter's
+optional value argument; no production typing was relaxed.
+Logs: `/tmp/praxis-section-spacing-tests-final.log` and
+`/tmp/praxis-section-spacing-build.log`.
+Final result: **41 tests passed** and `npm run build:praxis-dynamic-form`
+succeeded through the official dependency/build closure. A final Config API
+GET matched the prior receipt exactly, including version 92 and ETag:
+`/tmp/praxis-section-spacing-config-after.json`. The existing port 4003 server
+remains available; no new server or interactive shell was started.
+
+README and the owning JSON API guide were corrected together. The existing Form
+authoring manifest does not declare the removed marker or a separate bulk-fill
+contract; no manifest input, operation or path changed. Public-site examples,
+HTTP corpus and registry generation require no new artifact for this editor
+correction. Existing skills already require canonical layout semantics and
+draft isolation; no skill guidance diverged and no sync was necessary.