@praxisui/dynamic-form 9.0.5-rc.10 → 9.0.5-rc.12

package/README.md

@@ -33,10 +33,14 @@ Peer dependencies:
 
 When `/schemas/filtered` publishes root-level `x-ui.formEffects`, the form can call a typed backend determination after a valid source field changes and fill mapped targets. The contract is backend-owned and transient: it is not copied to `FormConfig` and cannot be authored as a local callback.
 
-The runtime waits until entity/initial-value hydration finishes, debounces source changes, cancels stale requests, applies complete responses atomically and preserves user input by default with `if-pristine`. Hosts can observe metadata-only outcomes through `formEffectExecuted`; control and response values are not emitted in that diagnostic.
+The runtime waits until entity/initial-value hydration finishes, tracks asynchronous source validation, debounces source changes, cancels stale requests, applies complete responses atomically and preserves user input by default with `if-pristine`. A determination is pending from the source change through completion, including the debounce window, and submit is held until that work finishes. Failures receive a localized default message.
+
+Hosts can observe metadata-only outcomes through `formEffectExecuted`; control and response values are not emitted. Events use `pending`, `success`, `skipped` and `error`. A successful event can report `appliedTargetFields` and `preservedTargetFields` so operational telemetry distinguishes configured bindings from actual patches without exposing business values.
 
 Use `optionSource.dependsOn` for dependent option lists and a workflow action for persisted business transitions. Form effects are reserved for non-persisting queries such as postal-code or governed classification lookup.
 
+For consequential corporate decisions, the determination is only a draft enrichment or preview. The final backend command must revalidate any fiscal, pricing, eligibility, compliance or approval outcome against its governed and versioned domain authority.
+
 ## Minimum Local Runtime
 
 Use a local `FormConfig` when the host already knows the sections and fields.

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-08-12T23:49:15.227Z",
+  "generatedAt": "2026-08-13T13:48:00.302Z",
   "packageName": "@praxisui/dynamic-form",
-  "packageVersion": "9.0.5-rc.10",
+  "packageVersion": "9.0.5-rc.12",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 2,
@@ -355,7 +355,7 @@
           "name": "formEffectExecuted",
           "type": "FormEffectExecutionEvent",
           "required": false,
-          "description": "Emite diagnostico sem valores sensiveis após executar, ignorar ou falhar uma determinação publicada pelo backend."
+          "description": "Emite diagnóstico sem valores sensíveis ao iniciar, executar, ignorar ou falhar uma determinação, distinguindo alvos aplicados e preservados."
         }
       ],
       "configSchemaId": "FormConfig",

package/fesm2022/praxisui-dynamic-form.mjs

@@ -21,7 +21,7 @@ import { MatSnackBarModule } from '@angular/material/snack-bar';
 import * as i19 from '@angular/material/badge';
 import { MatBadgeModule } from '@angular/material/badge';
 import { map, firstValueFrom, BehaviorSubject, Subject, Subscription, merge, EMPTY, throwError, combineLatest, debounceTime as debounceTime$1, takeUntil as takeUntil$1 } from 'rxjs';
-import { debounceTime, map as map$1, distinctUntilChanged, switchMap, catchError, takeUntil, skip, take, timeout, tap, startWith, finalize } from 'rxjs/operators';
+import { tap, debounceTime, map as map$1, filter, switchMap, catchError, finalize, takeUntil, skip, take, timeout, startWith } from 'rxjs/operators';
 import * as i1 from '@praxisui/core';
 import { serializeEntityLookupValueForPayload, PraxisI18nService, PraxisIconButtonComponent, PraxisIconDirective, providePraxisI18nConfig, RULE_PROPERTY_SCHEMA, FIELD_METADATA_CAPABILITIES, migrateFormLayoutRule, PraxisJsonLogicService, normalizeFormLayoutItems, deepMerge, createDefaultFormConfig, normalizeFormConfig as normalizeFormConfig$1, ensureIds, createEmptyRichContentDocument, resolveHidden, resolveOrder, resolveSpan, projectGroupedCommandPartialRows, isPraxisRuntimeGlobalActionEffect, ASYNC_CONFIG_STORAGE, withFormConfigSections, createFieldLayoutItem, getFormLayoutFieldNames, LoggerService, createCorporateLoggerConfig, ConsoleLoggerSink, GlobalActionService, ResourceQuickConnectComponent, composeHeadersWithVersion, buildApiUrl, mapFieldDefinitionsToMetadata, reconcileFormConfig, materializeFormLayoutFromMetadata, syncWithServerMetadata, PRAXIS_LOADING_CTX, evaluateFieldAccess, normalizeControlTypeKey, normalizePraxisEffectPolicy, buildPraxisEffectDistinctKey, getFormColumnFieldNames, resolveGroupedCommandPartialRowSpans, resolveOffset, buildSchemaIdStorageKeySegment, buildSchemaId, fetchWithETag, resolveControlTypeAlias, getTextTransformer, MemoryCacheAdapter, LocalStorageCacheAdapter, SchemaMetadataClient, normalizeFormEffects, CONNECTION_STORAGE, API_URL, PRAXIS_LOADING_RENDERER, FORM_HOOKS_PRESETS, EmptyStateCardComponent, isValidFormConfig, ComponentMetadataRegistry, FieldControlType, isRequiredGlobalActionPayloadMissing, GLOBAL_ACTION_CATALOG, PRAXIS_GLOBAL_ACTION_CATALOG, getGlobalActionCatalog, SURFACE_OPEN_I18N_NAMESPACE, getGlobalActionUiSchema, getRequiredGlobalActionPayloadKeys, hasMeaningfulGlobalActionPayloadValue, SurfaceOpenActionEditorComponent, SURFACE_OPEN_I18N_CONFIG, validateGlobalActionRefs, normalizeFormMetadata } from '@praxisui/core';
 import * as i1$1 from '@praxisui/dynamic-fields';
@@ -631,6 +631,9 @@ const PRAXIS_DYNAMIC_FORM_I18N_CONFIG = {
                 'layout.defaultSectionTitle': 'Informações',
                 'actions.invalidRequired': 'Preencha os campos obrigatórios para continuar.',
                 'actions.invalidRequiredWithFields': 'Preencha: {{fields}}.',
+                'runtime.formEffect.error': 'Não foi possível atualizar os campos relacionados. Revise os dados ou tente novamente.',
+                'runtime.formEffect.submitPending': 'Aguarde a atualização dos campos relacionados antes de salvar.',
+                'common.dismiss': 'Fechar',
                 'config.tabs.mobileLabel': 'Seção do editor',
                 'config.tabs.general': 'Geral',
                 'config.tabs.schema': 'Verificação de Schema',
@@ -1116,6 +1119,9 @@ const PRAXIS_DYNAMIC_FORM_I18N_CONFIG = {
 ]`,
             },
             'en-US': {
+                'runtime.formEffect.error': 'Related fields could not be updated. Review the data or try again.',
+                'runtime.formEffect.submitPending': 'Wait for related fields to finish updating before saving.',
+                'common.dismiss': 'Dismiss',
                 'settings.title': 'Form Configuration',
                 'layout.defaultSectionTitle': 'Information',
                 'actions.invalidRequired': 'Complete the required fields to continue.',
@@ -10566,9 +10572,14 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImpo
  * scripts, expressions, arbitrary URLs, headers, or methods supplied by consumers.
  */
 class FormEffectRuntimeService {
+    pendingEffectsByForm = new WeakMap();
+    hasPending(form) {
+        return (this.pendingEffectsByForm.get(form)?.size ?? 0) > 0;
+    }
     connect(form, effects, executor, onEvent) {
         const composite = new Subscription();
         for (const effect of effects) {
+            let lastExecutedFingerprint = null;
             const sourceControls = effect.trigger.fields
                 .map((field) => form.get(field))
                 .filter((control) => !!control);
@@ -10576,29 +10587,40 @@ class FormEffectRuntimeService {
                 onEvent?.(this.event(effect, 'skipped', createCorrelationId(), 0, 'source-control-missing'));
                 continue;
             }
-            const sourceChanges$ = merge(...sourceControls.map((control) => control.valueChanges));
+            const sourceChanges$ = merge(...sourceControls.flatMap((control) => [control.valueChanges, control.statusChanges]));
             composite.add(sourceChanges$
-                .pipe(debounceTime(effect.trigger.debounceMs), map$1(() => this.buildInvocation(form, effect, sourceControls)), distinctUntilChanged((previous, current) => previous.fingerprint === current.fingerprint), switchMap((invocation) => {
-                if (effect.trigger.requiresValidSources && sourceControls.some((control) => control.invalid)) {
+                .pipe(tap(() => this.markPending(form, effect.id, true)), debounceTime(effect.trigger.debounceMs), map$1(() => this.buildInvocation(form, effect, sourceControls)), filter((invocation) => {
+                if (effect.trigger.requiresValidSources &&
+                    sourceControls.some((control) => control.pending || control.invalid)) {
+                    this.markPending(form, effect.id, false);
                     onEvent?.(this.event(effect, 'skipped', invocation.correlationId, 0, 'invalid-source'));
-                    return EMPTY;
+                    return false;
                 }
+                if (invocation.fingerprint === lastExecutedFingerprint) {
+                    this.markPending(form, effect.id, false);
+                    return false;
+                }
+                return true;
+            }), switchMap((invocation) => {
+                lastExecutedFingerprint = invocation.fingerprint;
                 const startedAt = Date.now();
+                this.markPending(form, effect.id, true);
+                onEvent?.(this.event(effect, 'pending', invocation.correlationId, 0));
                 return executor(effect, invocation.body, invocation.correlationId).pipe(map$1((response) => ({ response, startedAt, correlationId: invocation.correlationId })), catchError(() => {
                     onEvent?.(this.event(effect, 'error', invocation.correlationId, Date.now() - startedAt, 'operation-failed'));
                     return EMPTY;
-                }));
+                }), finalize(() => this.markPending(form, effect.id, false)));
             }))
                 .subscribe(({ response, startedAt, correlationId }) => {
-                const patch = this.buildAtomicPatch(form, effect, response);
-                if (patch === null) {
+                const result = this.buildAtomicPatch(form, effect, response);
+                if (result === null) {
                     onEvent?.(this.event(effect, 'error', correlationId, Date.now() - startedAt, 'response-binding-missing'));
                     return;
                 }
-                if (Object.keys(patch).length) {
-                    form.patchValue(patch, { emitEvent: true });
+                if (Object.keys(result.patch).length) {
+                    form.patchValue(result.patch, { emitEvent: true });
                 }
-                onEvent?.(this.event(effect, 'success', correlationId, Date.now() - startedAt));
+                onEvent?.(this.event(effect, 'success', correlationId, Date.now() - startedAt, undefined, Object.keys(result.patch), result.preserved));
             }));
         }
         return composite;
@@ -10621,22 +10643,25 @@ class FormEffectRuntimeService {
             return null;
         }
         const patch = {};
+        const preserved = [];
         for (const binding of effect.outputs) {
             const control = form.get(binding.formField);
             if (!control) {
                 return null;
             }
             if (binding.writePolicy === 'if-pristine' && !control.pristine) {
+                preserved.push(binding.formField);
                 continue;
             }
             if (binding.writePolicy === 'if-empty' && !isEmptyValue(control.value)) {
+                preserved.push(binding.formField);
                 continue;
             }
             patch[binding.formField] = response[binding.operationField];
         }
-        return patch;
+        return { patch, preserved };
     }
-    event(effect, status, correlationId, durationMs, reason) {
+    event(effect, status, correlationId, durationMs, reason, appliedTargetFields, preservedTargetFields) {
         return {
             effectId: effect.id,
             operationId: effect.operation.operationId,
@@ -10646,8 +10671,22 @@ class FormEffectRuntimeService {
             correlationId,
             durationMs,
             ...(reason ? { reason } : {}),
+            ...(appliedTargetFields ? { appliedTargetFields } : {}),
+            ...(preservedTargetFields ? { preservedTargetFields } : {}),
         };
     }
+    markPending(form, effectId, pending) {
+        const effects = this.pendingEffectsByForm.get(form) ?? new Set();
+        if (pending) {
+            effects.add(effectId);
+            this.pendingEffectsByForm.set(form, effects);
+            return;
+        }
+        effects.delete(effectId);
+        if (!effects.size) {
+            this.pendingEffectsByForm.delete(form);
+        }
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FormEffectRuntimeService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: FormEffectRuntimeService, providedIn: 'root' });
 }
@@ -12812,9 +12851,15 @@ class PraxisDynamicForm {
                 return this.http
                     .post(this.resolveApiHref(effect.operation.path), requestBody, { headers })
                     .pipe(map$1((response) => this.unwrapRestApiResponse(response)));
-            }, (event) => this.formEffectExecuted.emit(event));
+            }, (event) => this.handleFormEffectExecutionEvent(event));
         });
     }
+    handleFormEffectExecutionEvent(event) {
+        this.formEffectExecuted.emit(event);
+        if (event.status !== 'error')
+            return;
+        this.snackBar.open(this.i18n.t('runtime.formEffect.error', undefined, 'Não foi possível atualizar os campos relacionados. Revise os dados ou tente novamente.', PRAXIS_DYNAMIC_FORM_I18N_NAMESPACE), this.i18n.t('common.dismiss', undefined, 'Fechar', PRAXIS_DYNAMIC_FORM_I18N_NAMESPACE), { duration: 7000 });
+    }
     resetDependencyPolicySubscription() {
         this.dependencyPolicySubscription?.unsubscribe();
         this.dependencyPolicySubscription = null;
@@ -15028,6 +15073,10 @@ class PraxisDynamicForm {
         if (this.entityHydrationPending) {
             return;
         }
+        if (this.formEffectRuntime.hasPending(this.form)) {
+            this.snackBar.open(this.i18n.t('runtime.formEffect.submitPending', undefined, 'Aguarde a atualização dos campos relacionados antes de salvar.', PRAXIS_DYNAMIC_FORM_I18N_NAMESPACE), this.i18n.t('common.dismiss', undefined, 'Fechar', PRAXIS_DYNAMIC_FORM_I18N_NAMESPACE), { duration: 5000 });
+            return;
+        }
         this.clearSubmitFieldErrors();
         // Hooks: beforeValidate
         try {
@@ -31253,7 +31302,7 @@ const PRAXIS_DYNAMIC_FORM_COMPONENT_METADATA = {
         { name: 'customAction', type: 'FormCustomActionEvent', description: 'Emite quando uma acao customizada e executada' },
         { name: 'actionConfirmation', type: 'FormActionConfirmationEvent', description: 'Resultado de confirmacoes de acoes' },
         { name: 'schemaStatusChange', type: '{ outdated: boolean; serverHash?: string; lastVerifiedAt?: string; formId?: string }', description: 'Emite quando o status do schema muda' },
-        { name: 'formEffectExecuted', type: 'FormEffectExecutionEvent', description: 'Emite diagnostico sem valores sensiveis após executar, ignorar ou falhar uma determinação publicada pelo backend.' },
+        { name: 'formEffectExecuted', type: 'FormEffectExecutionEvent', description: 'Emite diagnóstico sem valores sensíveis ao iniciar, executar, ignorar ou falhar uma determinação, distinguindo alvos aplicados e preservados.' },
     ],
     actions: [
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-form",
-  "version": "9.0.5-rc.10",
+  "version": "9.0.5-rc.12",
   "description": "Angular dynamic form engine for Praxis UI: metadata-driven forms, hooks, and services integrating @praxisui/* packages.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -9,13 +9,13 @@
     "@angular/forms": "^21.0.0",
     "@angular/material": "^21.0.0",
     "@angular/router": "^21.0.0",
-    "@praxisui/ai": "^9.0.5-rc.10",
-    "@praxisui/dynamic-fields": "^9.0.5-rc.10",
-    "@praxisui/metadata-editor": "^9.0.5-rc.10",
-    "@praxisui/rich-content": "^9.0.5-rc.10",
-    "@praxisui/settings-panel": "^9.0.5-rc.10",
-    "@praxisui/visual-builder": "^9.0.5-rc.10",
-    "@praxisui/core": "^9.0.5-rc.10",
+    "@praxisui/ai": "^9.0.5-rc.12",
+    "@praxisui/dynamic-fields": "^9.0.5-rc.12",
+    "@praxisui/metadata-editor": "^9.0.5-rc.12",
+    "@praxisui/rich-content": "^9.0.5-rc.12",
+    "@praxisui/settings-panel": "^9.0.5-rc.12",
+    "@praxisui/visual-builder": "^9.0.5-rc.12",
+    "@praxisui/core": "^9.0.5-rc.12",
     "rxjs": "^7.8.0"
   },
   "dependencies": {

package/src/lib/praxis-dynamic-form.json-api.md

@@ -79,9 +79,9 @@ Este documento e a referencia canonica da API JSON de praxis-dynamic-form.
 
 - `x-ui.formEffects` e lido exclusivamente do schema raiz retornado por `/schemas/filtered`; nao integra nem e persistido em `FormConfig`.
 - O runtime aceita somente o contrato fechado normalizado por `normalizeFormEffects`: gatilho `value-change`, operação `POST`, bindings de entrada/saida e politicas `if-pristine`, `if-empty` ou `replace`.
-- Determinacoes nao executam na hidratacao inicial. Depois da hidratacao, mudanças nos controles fonte usam debounce e cancelamento latest-wins.
+- Determinacoes nao executam na hidratacao inicial. Depois da hidratacao, mudancas nos controles fonte acompanham validacao assincrona, usam debounce e cancelamento latest-wins. O estado permanece pending inclusive durante o debounce, e o submit nao prossegue enquanto a determinacao mais recente estiver pendente.
 - A resposta so gera patch quando todos os bindings de saida existem; o patch e atomico e respeita a politica de escrita de cada alvo.
-- `formEffectExecuted` publica apenas IDs, nomes de campos, estado, duracao, correlation ID e motivo; valores do formulario e da resposta nao participam do diagnostico.
+- `formEffectExecuted` publica apenas IDs, nomes de campos, estado (`pending`, `success`, `skipped` ou `error`), duracao, correlation ID e motivo. Em sucesso, pode distinguir alvos efetivamente aplicados e preservados; valores do formulario e da resposta nao participam do diagnostico.
 - Form effects sao backend-owned e nao aparecem como capacidade autoravel por editor ou IA. Cascatas de opcoes continuam em `optionSource.dependsOn`; transicoes persistentes continuam em workflow actions.
 
 ## AI assistant and semantic authoring boundary

package/types/praxisui-dynamic-form.d.ts

@@ -367,10 +367,13 @@ type FormEffectExecutor = (effect: FormEffectDefinition, requestBody: Record<str
  * scripts, expressions, arbitrary URLs, headers, or methods supplied by consumers.
  */
 declare class FormEffectRuntimeService {
+    private readonly pendingEffectsByForm;
+    hasPending(form: FormGroup): boolean;
     connect(form: FormGroup, effects: FormEffectDefinition[], executor: FormEffectExecutor, onEvent?: (event: FormEffectExecutionEvent) => void): Subscription;
     private buildInvocation;
     private buildAtomicPatch;
     private event;
+    private markPending;
     static ɵfac: i0.ɵɵFactoryDeclaration<FormEffectRuntimeService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<FormEffectRuntimeService>;
 }
@@ -1049,6 +1052,7 @@ declare class PraxisDynamicForm implements OnInit, OnChanges, OnDestroy {
     private resetFormValueChangesSubscription;
     private resetFormEffectSubscription;
     private scheduleFormEffectsActivation;
+    private handleFormEffectExecutionEvent;
     private resetDependencyPolicySubscription;
     private setupEntityLookupDependencyPolicies;
     private applyEntityLookupDependencyPolicy;