@praxisui/dynamic-fields 9.0.0-rc.3 → 9.0.0-rc.4

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-07-25T01:22:20.531Z",
+  "generatedAt": "2026-07-26T03:19:30.955Z",
   "packageName": "@praxisui/dynamic-fields",
-  "packageVersion": "9.0.0-rc.3",
+  "packageVersion": "9.0.0-rc.4",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 76,

package/docs/dynamic-fields-field-selection-guide.md

@@ -149,6 +149,8 @@ Checklist minimo para promocao:
 - o recurso oferece busca paginada e reidratacao por ids (`filter` e `byIds`) para valores salvos;
 - `selectionPolicy` documenta status, elegibilidade e preservacao de valor historico quando aplicavel;
 - dependencias entre entidades usam `dependsOn` e `dependencyFilterMap`, sem inferencia por nome de campo no Angular;
+- ao mudar uma dependencia canonica, o runtime limpa por padrao a selecao dependente, emite a alteracao para continuar a cascata e preserva apenas o valor hidratado na montagem inicial;
+- use `selectionPolicy.allowRetainInvalidExistingValue=true` somente quando o dominio permitir manter explicitamente uma selecao historica fora do novo conjunto de opcoes;
 - surfaces de detalhe sao publicadas pelo recurso quando `navigateToDetail` estiver habilitado;
 - existe demo jogavel cobrindo campo de formulario e, quando o uso for filtro, `inlineEntityLookup`;
 - existe teste focal ou e2e cobrindo busca, selecao, reidratacao e estado bloqueado/historico;

package/fesm2022/praxisui-dynamic-fields.mjs

@@ -4340,15 +4340,21 @@ class SimpleBaseSelectComponent extends SimpleBaseInputComponent {
         const debounceMs = Number(meta.dependencyDebounceMs ?? this.global.getDynamicFields()?.cascade?.debounceMs ?? 150);
         const mergeStrategy = meta.dependencyMergeStrategy ?? 'merge';
         const loadOnChange = meta.dependencyLoadOnChange ?? this.global.getDynamicFields()?.cascade?.loadOnChange ?? 'respectLoadOn';
+        let dependencySnapshotInitialized = false;
         // Subscribe to combined changes
         this.dependencySub = combineLatest(streams)
             .pipe(debounceTime(debounceMs))
             .subscribe((values) => {
             const availableControls = controls.filter((entry) => !!entry.control);
             const fragment = this.applyDependencyValues(meta, availableControls, values);
-            // Reset value when configured
-            if (meta.resetOnDependentChange) {
-                this.setValue(null, { emitEvent: false });
+            const isInitialDependencySnapshot = !dependencySnapshotInitialized;
+            dependencySnapshotInitialized = true;
+            if (!isInitialDependencySnapshot &&
+                this.shouldResetOnDependencyChange(meta) &&
+                this.hasMeaningfulSelectValue(this.control().value)) {
+                const emptyValue = this.multiple() ? [] : null;
+                this.setValue(emptyValue, { emitEvent: true });
+                this.control().markAsDirty();
             }
             // Trigger reload according to strategy
             if (!this.resourcePath())
@@ -4375,6 +4381,21 @@ class SimpleBaseSelectComponent extends SimpleBaseInputComponent {
             });
         });
     }
+    shouldResetOnDependencyChange(meta) {
+        if (meta.resetOnDependentChange !== undefined) {
+            return meta.resetOnDependentChange === true;
+        }
+        const hasCanonicalDependencies = Array.isArray(meta.optionSource?.dependsOn) &&
+            meta.optionSource.dependsOn.length > 0;
+        const retainsInvalidExistingValue = meta.optionSource?.selectionPolicy?.allowRetainInvalidExistingValue === true;
+        return hasCanonicalDependencies && !retainsInvalidExistingValue;
+    }
+    hasMeaningfulSelectValue(value) {
+        if (Array.isArray(value)) {
+            return value.length > 0;
+        }
+        return value !== null && value !== undefined && value !== '';
+    }
     extractDependencyValue(raw, path) {
         if (raw == null)
             return raw;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@praxisui/dynamic-fields",
-  "version": "9.0.0-rc.3",
+  "version": "9.0.0-rc.4",
   "description": "Angular Material-based dynamic form fields for Praxis UI with lazy loading and metadata-driven rendering.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
@@ -11,8 +11,8 @@
     "@angular/platform-browser": "^21.0.0",
     "@angular/router": "^21.0.0",
     "rxjs": "^7.8.0",
-    "@praxisui/core": "^9.0.0-rc.3",
-    "@praxisui/cron-builder": "^9.0.0-rc.3"
+    "@praxisui/core": "^9.0.0-rc.4",
+    "@praxisui/cron-builder": "^9.0.0-rc.4"
   },
   "dependencies": {
     "libphonenumber-js": "^1.12.41",

package/src/lib/components/material-async-select/pdx-material-async-select.json-api.md

@@ -416,6 +416,8 @@ Notas de runtime:
 - em `optionSource`, o filtro envia `includeIds` somente quando `optionSource.includeIds=true` e nao ha termo de busca ativo; quando ausente, `false` ou durante busca digitada, valores selecionados sao reidratados por `/option-sources/{sourceKey}/options/by-ids`.
 - durante busca digitada, a lista visivel usa apenas os itens da pagina remota filtrada. Opcoes reidratadas por ID preservam o display fechado, mas nao podem substituir ou inflar o resultado da busca.
 - em `optionSource`, dependencias declaradas por `dependsOn` e `dependencyFilterMap` sao materializadas como filtros estruturados `equals` no envelope canonico de opcoes.
+- depois da montagem inicial, a mudanca de qualquer dependencia canonica limpa o valor selecionado e o texto exibido antes de recarregar as opcoes. A limpeza emite `valueChanges` para invalidar dependentes posteriores na mesma cadeia.
+- `optionSource.selectionPolicy.allowRetainInvalidExistingValue=true` permite reter explicitamente um valor historico; `resetOnDependentChange=false` permanece como opt-out de compatibilidade para metadata legado.
 - `onSearch` limpa estado local e reinicia pagina para novo termo.
 - `loadMore` nao inicia a primeira carga remota; a primeira pagina respeita `loadOn`, abertura do painel, reload explicito ou mudanca de dependencia.
 - `loadMore` incrementa pagina somente quando ja existe pagina remota carregada e `endReached=false`.

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

@@ -1283,6 +1283,8 @@ declare abstract class SimpleBaseSelectComponent<T = any> extends SimpleBaseInpu
     private ensureCurrentValueLoaded;
     /** (Re)configure dependency observers based on metadata and current FormGroup */
     protected setupDependencies(): void;
+    private shouldResetOnDependencyChange;
+    private hasMeaningfulSelectValue;
     protected extractDependencyValue(raw: any, path?: string): any;
     protected applyDependencyCriteria(fragment: Record<string, any>, strategy?: 'merge' | 'replace'): void;
     protected onDependenciesChanged(): void;