@quadrel-enterprise-ui/framework 20.10.0 → 20.10.1-beta.145.1

package/fesm2022/quadrel-enterprise-ui-framework.mjs

@@ -11402,7 +11402,7 @@ class QdDatepickerComponent {
     _onChange = () => { };
     _onTouched = () => { };
     ngOnInit() {
-        this.language ??= this.translateService.currentLang;
+        this.language = this.translateService?.currentLang ?? DEFAULT_LANGUAGE;
         this.subscribeToLanguageChange();
         this.subscribeToActionEmitterEvents();
         this.initControl();
@@ -27062,6 +27062,60 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.18", ngImpo
                 type: Input
             }] } });
 
+class QdPageCommitActionExecutor {
+    static execute(action, values, context) {
+        const { formGroupManager, navigationInterceptor, destroyed$, onAfterSnapshot } = context;
+        const captured = formGroupManager.captureFormValues();
+        let result$;
+        navigationInterceptor.executeWithBypass(() => {
+            const handlerResult = action.handler(values);
+            if (isObservable(handlerResult))
+                result$ = handlerResult;
+        });
+        const applySuccess = () => {
+            formGroupManager.setFormGroupsSnapshot(captured);
+            navigationInterceptor.executeWithBypass(() => {
+                try {
+                    onAfterSnapshot?.();
+                }
+                catch (err) {
+                    console.error('QD-UI | QdPage - internal onAfterSnapshot hook threw after form was marked as saved.', err);
+                }
+                try {
+                    action.onSuccess?.();
+                }
+                catch (err) {
+                    console.error('QD-UI | QdPage - onSuccess callback threw after form was marked as saved.', err);
+                }
+            });
+        };
+        if (result$) {
+            result$.pipe(take(1), takeUntil(destroyed$)).subscribe({
+                next: ok => {
+                    if (ok)
+                        applySuccess();
+                },
+                error: err => this.handleError(action, err)
+            });
+        }
+        else {
+            applySuccess();
+        }
+    }
+    static handleError(action, err) {
+        if (!action.onError) {
+            console.error('QD-UI | QdPage - Commit action observable errored — form was not marked as saved. Provide an `onError` hook on the action, or handle errors in the handler.', err);
+            return;
+        }
+        try {
+            action.onError(err);
+        }
+        catch (callbackErr) {
+            console.error('QD-UI | QdPage - onError callback threw.', callbackErr);
+        }
+    }
+}
+
 /**
  * The QdFormGroupManagerService provides centralized registration, snapshotting, and value tracking
  * for multiple Angular `FormGroup` instances. It supports efficient state restoration, including dynamic
@@ -27176,6 +27230,39 @@ class QdFormGroupManagerService {
     takeFormGroupsSnapshot() {
         this._formGroups.forEach((fg, key) => this._formGroupsSnapshot.set(key, fg.getRawValue()));
     }
+    /**
+     * Captures a deep-cloned snapshot of all current form values without mutating internal state.
+     *
+     * Used by framework orchestration code that needs to remember the "at click time" state of a form
+     * so the snapshot can later be set to exactly those values — even if the user edits the form
+     * while an async commit action is pending.
+     *
+     * Throws if any form value is not structured-cloneable (functions, symbols, DOM nodes).
+     */
+    captureFormValues() {
+        const captured = new Map();
+        this._formGroups.forEach((fg, key) => {
+            try {
+                captured.set(key, structuredClone(fg.getRawValue()));
+            }
+            catch (err) {
+                throw new Error(`QD-UI | QdFormGroupManager - captureFormValues() failed for group "${key}". ` +
+                    `Form values must be structured-cloneable. Non-cloneable values like functions, ` +
+                    `symbols, or DOM nodes are not supported. Original error: ${String(err)}`);
+            }
+        });
+        return captured;
+    }
+    /**
+     * Replaces the internal saved snapshot with the provided values.
+     *
+     * Intended to be paired with `captureFormValues()` so that the snapshot can be set to the
+     * values present when a commit action was initiated — independent of whether the user edited
+     * the form in the meantime.
+     */
+    setFormGroupsSnapshot(values) {
+        values.forEach((snapshot, key) => this._formGroupsSnapshot.set(key, snapshot));
+    }
     restoreFormGroupsFromSnapshot() {
         this._formGroups.forEach((fg, key) => {
             const snapshot = this._formGroupsSnapshot.get(key);
@@ -27185,20 +27272,6 @@ class QdFormGroupManagerService {
         });
         this.cancelPendingAsyncValidation();
     }
-    restoreFormGroup(fg, snapshot) {
-        Object.entries(fg.controls).forEach(([ctrlKey, ctrl]) => {
-            const newValue = snapshot[ctrlKey];
-            if (ctrl instanceof FormArray && Array.isArray(newValue)) {
-                this.resetFormArrayToValues(ctrl, newValue);
-            }
-            else if (ctrl instanceof FormGroup && newValue && typeof newValue === 'object') {
-                this.restoreFormGroup(ctrl, newValue);
-            }
-            else {
-                ctrl.reset(newValue);
-            }
-        });
-    }
     /**
      * Cancels any in-flight async validators on all registered form groups.
      *
@@ -27222,6 +27295,20 @@ class QdFormGroupManagerService {
             }
         });
     }
+    restoreFormGroup(fg, snapshot) {
+        Object.entries(fg.controls).forEach(([ctrlKey, ctrl]) => {
+            const newValue = snapshot[ctrlKey];
+            if (ctrl instanceof FormArray && Array.isArray(newValue)) {
+                this.resetFormArrayToValues(ctrl, newValue);
+            }
+            else if (ctrl instanceof FormGroup && newValue && typeof newValue === 'object') {
+                this.restoreFormGroup(ctrl, newValue);
+            }
+            else {
+                ctrl.reset(newValue);
+            }
+        });
+    }
     collectPendingControls(control) {
         const result = [];
         if (control instanceof FormGroup) {
@@ -27287,6 +27374,122 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.18", ngImpo
             type: Injectable
         }] });
 
+/**
+ * Intercepts router navigation when unsaved form changes exist on a QdPage.
+ *
+ * Provided per `QdPageComponent`. Activated automatically when the page enters an editable state
+ * (create pages or inspect pages in edit mode). Deactivated when the page returns to view mode.
+ *
+ * #### When navigation is intercepted
+ *
+ * - A `NavigationStart` event occurs (browser back, shell back button, or programmatic navigation).
+ * - The registered form groups report unsaved changes via `QdFormGroupManagerService.$hasValuesChanged()`.
+ *
+ * The navigation is cancelled and a confirmation dialog is shown. The user can either discard
+ * changes and proceed or stay on the page.
+ *
+ * #### When navigation is allowed
+ *
+ * - No unsaved changes exist — the form is either pristine or the framework has updated the
+ *   saved snapshot after a successful commit action (Submit, Save, SaveDraft).
+ * - The page switches to view mode via `deactivate()`.
+ *
+ * The service has no concept of "pending actions" or bypass windows. Framework actions update the
+ * saved snapshot directly via `QdFormGroupManagerService.setFormGroupsSnapshot(...)`; cancel-discard
+ * flows reset the form to the saved snapshot via `restoreFormGroupsFromSnapshot()`. Either way, the
+ * interceptor only observes the resulting form state — there is no time window where a bypass is active.
+ */
+class QdPageNavigationInterceptorService {
+    router = inject(Router);
+    formGroupManager = inject(QdFormGroupManagerService);
+    confirmationDialog = inject(QdConfirmationDialogOpenerService);
+    _destroy$ = new Subject();
+    _deactivate$ = new Subject();
+    /**
+     * Guards the re-dispatched navigation issued after the user confirms discard. While the dialog
+     * is open and while the confirmed target is being re-dispatched, the router events must not
+     * re-enter the interception pipeline — otherwise the dialog would open recursively.
+     */
+    _bypassInterception = false;
+    /**
+     * URL of the navigation target accepted by the user in the most recent discard-confirm dialog.
+     * Set by `navigateToConfirmedTarget()` and consumed once by `shouldIntercept()` when the
+     * corresponding `NavigationStart` arrives.
+     */
+    _confirmedTargetUrl;
+    _confirmationMessage;
+    ngOnDestroy() {
+        this._confirmedTargetUrl = undefined;
+        this._destroy$.next();
+        this._destroy$.complete();
+        this._deactivate$.complete();
+    }
+    /**
+     * Starts intercepting navigation events. Replaces any previously active listener.
+     */
+    activate(confirmationMessage) {
+        this._confirmationMessage = confirmationMessage;
+        this._deactivate$.next();
+        this.listenForUnsavedNavigationAttempts();
+    }
+    /**
+     * Stops intercepting and clears the pending confirmed-target bypass.
+     */
+    deactivate() {
+        this._deactivate$.next();
+        this._confirmedTargetUrl = undefined;
+    }
+    /**
+     * Runs the given action while temporarily suppressing navigation interception.
+     *
+     * Used by framework commit-action orchestration to wrap synchronous handler invocations and
+     * post-commit `onSuccess` callbacks: any router navigation that occurs during `action()` is
+     * passed through without raising the unsaved-changes dialog. Restoration happens in a `finally`
+     * block, so the flag is released even if `action()` throws.
+     */
+    executeWithBypass(action) {
+        this._bypassInterception = true;
+        try {
+            action();
+        }
+        finally {
+            this._bypassInterception = false;
+        }
+    }
+    listenForUnsavedNavigationAttempts() {
+        this.router.events
+            .pipe(filter$1((event) => event instanceof NavigationStart), filter$1(() => !this._bypassInterception), filter$1(event => this.shouldIntercept(event)), concatMap$1(event => this.checkForPendingChanges(event)), filter$1(({ hasChanges }) => hasChanges), exhaustMap(({ event }) => this.cancelNavigationAndConfirm(event)), filter$1(({ confirmed }) => confirmed), takeUntil$1(this._deactivate$), takeUntil$1(this._destroy$))
+            .subscribe(({ targetUrl }) => this.navigateToConfirmedTarget(targetUrl));
+    }
+    shouldIntercept(event) {
+        if (this._confirmedTargetUrl !== undefined && this._confirmedTargetUrl === event.url) {
+            this._confirmedTargetUrl = undefined;
+            return false;
+        }
+        return true;
+    }
+    checkForPendingChanges(event) {
+        return this.formGroupManager.$hasValuesChanged().pipe(take$1(1), map$1(hasChanges => ({ event, hasChanges })));
+    }
+    cancelNavigationAndConfirm(event) {
+        this._bypassInterception = true;
+        void this.router.navigateByUrl(this.router.url, { skipLocationChange: true });
+        return this.confirmationDialog
+            .showDiscardConfirmDialog(this._confirmationMessage, 'page-navigation-confirmation')
+            .pipe(map$1(confirmed => ({ confirmed, targetUrl: event.url })), finalize(() => (this._bypassInterception = false)));
+    }
+    navigateToConfirmedTarget(targetUrl) {
+        this._bypassInterception = false;
+        this._confirmedTargetUrl = targetUrl;
+        void this.router.navigateByUrl(targetUrl);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.18", ngImport: i0, type: QdPageNavigationInterceptorService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.18", ngImport: i0, type: QdPageNavigationInterceptorService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.18", ngImport: i0, type: QdPageNavigationInterceptorService, decorators: [{
+            type: Injectable
+        }] });
+
 class QdResolverTriggerService {
     route = inject(ActivatedRoute, { optional: true });
     shouldTriggerResolver(triggerOn) {
@@ -27336,6 +27539,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.18", ngImpo
 class QdPageObjectHeaderComponent {
     pageObjectResolver = inject(QD_PAGE_OBJECT_RESOLVER_TOKEN, { optional: true });
     formGroupManagerService = inject(QdFormGroupManagerService, { optional: true });
+    navigationInterceptor = inject(QdPageNavigationInterceptorService);
     dialogComponent = inject(QdDialogComponent, { optional: true });
     dialog = inject(QdDialogService);
     confirmationDialogService = inject(QdConfirmationDialogOpenerService);
@@ -27360,6 +27564,8 @@ class QdPageObjectHeaderComponent {
     _isLoadingSubject = new BehaviorSubject(false);
     _customActionsSubject = new BehaviorSubject({ actions: [] });
     _customActionsSub;
+    _metadataSub;
+    _streamPartial = {};
     _destroyed$ = new Subject();
     _availableContexts = 0;
     pageObjectData$ = this._pageObjectDataSubject.asObservable();
@@ -27450,19 +27656,21 @@ class QdPageObjectHeaderComponent {
                 if (originalUpdateMetadata)
                     originalUpdateMetadata(props);
             };
-            this.setupResolverTrigger();
         }
     }
     ngOnInit() {
         if (this.pageObjectResolver)
             this.setupResolverTrigger();
         this.updateCustomActions();
+        this.subscribeToMetadataStream();
         this.formGroupManagerService.takeFormGroupsSnapshot();
         this.initContexts();
     }
     ngOnChanges(changes) {
-        if (changes['config'] && !changes['config'].firstChange)
+        if (changes['config'] && !changes['config'].firstChange) {
             this.updateCustomActions();
+            this.subscribeToMetadataStream();
+        }
     }
     ngOnDestroy() {
         this.pageStoreService.toggleViewonly(false);
@@ -27470,8 +27678,8 @@ class QdPageObjectHeaderComponent {
         this._destroyed$.complete();
     }
     updateMetadata(metadata) {
-        const updatedMetadata = { ...this._pageObjectDataSubject.value, ...metadata };
-        this._pageObjectDataSubject.next(updatedMetadata);
+        this._streamPartial = { ...this._streamPartial, ...metadata };
+        this._pageObjectDataSubject.next({ ...this._pageObjectDataSubject.value, ...metadata });
     }
     handleAction(facet) {
         facet?.action?.handler();
@@ -27500,13 +27708,18 @@ class QdPageObjectHeaderComponent {
         });
     }
     save() {
-        const handleSuccess = () => {
-            this.formGroupManagerService.cancelPendingAsyncValidation();
-            this.pageStoreService.toggleViewonly(true);
-            this.formGroupManagerService.takeFormGroupsSnapshot();
-        };
-        const result = this.saveButton?.handler?.(this.formGroupManagerService.getAllValues());
-        isObservable(result) ? result.pipe(take(1)).subscribe((ok) => ok && handleSuccess()) : handleSuccess();
+        const saveAction = this.saveButton;
+        if (!saveAction)
+            return;
+        QdPageCommitActionExecutor.execute(saveAction, this.formGroupManagerService.getAllValues(), {
+            formGroupManager: this.formGroupManagerService,
+            navigationInterceptor: this.navigationInterceptor,
+            destroyed$: this._destroyed$,
+            onAfterSnapshot: () => {
+                this.formGroupManagerService.cancelPendingAsyncValidation();
+                this.pageStoreService.toggleViewonly(true);
+            }
+        });
     }
     changeContext(context, selection, event) {
         event.stopPropagation();
@@ -27530,11 +27743,11 @@ class QdPageObjectHeaderComponent {
     setupResolverTrigger() {
         this.resolverTriggerService
             .shouldTriggerResolver(this.pageObjectResolver.config?.triggerOn ?? 'pathParamsChange')
-            .pipe(takeUntil(this._destroyed$), filter(shouldTrigger => shouldTrigger), tap(() => this._isLoadingSubject.next(true)), switchMap(() => this.pageObjectResolver.resolve()), tap(objectData => this._pageObjectDataSubject.next(objectData)), tap(() => this._isLoadingSubject.next(false)), tap(() => this.formGroupManagerService.takeFormGroupsSnapshot()))
+            .pipe(takeUntil(this._destroyed$), filter(shouldTrigger => shouldTrigger), tap(() => this._isLoadingSubject.next(true)), switchMap(() => this.pageObjectResolver.resolve()), tap(objectData => this._pageObjectDataSubject.next({ ...objectData, ...this._streamPartial })), tap(() => this._isLoadingSubject.next(false)), tap(() => this.formGroupManagerService.takeFormGroupsSnapshot()))
             .subscribe();
     }
     initContexts() {
-        this.contexts$ = this.contextService.contexts$.pipe(map(contexts => contexts.filter(context => context.selection || this.config.pageType === 'overview')), map(contexts => contexts?.map(({ selection, context }) => ({
+        this.contexts$ = this.contextService.contexts$.pipe(map(contexts => contexts.filter(context => context.selection || this.config.pageType === 'overview')), map(contexts => contexts.map(({ selection, context }) => ({
             label: context.label.i18n,
             value: Array.isArray(selection?.value)
                 ? selection?.value.filter(item => item !== null && item !== undefined)
@@ -27545,7 +27758,7 @@ class QdPageObjectHeaderComponent {
             selection: selection?.value ?? []
         }))));
         this.contexts$
-            .pipe(takeUntil(this._destroyed$), tap(contexts => (this._availableContexts = contexts?.length ?? 0)))
+            .pipe(takeUntil(this._destroyed$), tap(contexts => (this._availableContexts = contexts.length)))
             .subscribe();
     }
     updateCustomActions() {
@@ -27562,6 +27775,13 @@ class QdPageObjectHeaderComponent {
         }
         this.subscribeToViewOnlyMode();
     }
+    subscribeToMetadataStream() {
+        this._metadataSub?.unsubscribe();
+        const metadata$ = this.config.metadata$;
+        if (!metadata$)
+            return;
+        this._metadataSub = metadata$.pipe(takeUntil(this._destroyed$)).subscribe(partial => this.updateMetadata(partial));
+    }
     subscribeToViewOnlyMode() {
         this._customActionsSub?.unsubscribe();
         this._customActionsSub = this.pageStoreService.isViewonly$
@@ -28564,126 +28784,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.18", ngImpo
                 type: Output
             }] } });
 
-/**
- * Intercepts router navigation when unsaved form changes exist on a QdPage.
- *
- * Provided per `QdPageComponent`. Activated automatically when the page enters an editable state
- * (create pages or inspect pages in edit mode). Deactivated when the page returns to view mode.
- *
- * #### When navigation is intercepted
- *
- * - The user has unsaved form changes (tracked via `QdFormGroupManagerService`).
- * - A `NavigationStart` event occurs (browser back, shell back button, or programmatic navigation).
- *
- * The current navigation is cancelled, and a confirmation dialog is shown. The user can either
- * discard changes and proceed or cancel and stay on the page.
- *
- * #### When navigation is allowed
- *
- * - No unsaved changes exist — navigation proceeds silently.
- * - A framework action (Submit, SaveDraft) wraps its handler via `executeWithBypass()`.
- * - A confirmed discard sets `allowNextNavigation()` before the cancel handler navigates.
- * - The page switches to view mode via `deactivate()`.
- *
- * Custom actions defined by the application are not bypassed. If a custom action navigates away
- * while unsaved changes exist, the confirmation dialog is shown.
- */
-class QdPageNavigationInterceptorService {
-    router = inject(Router);
-    formGroupManager = inject(QdFormGroupManagerService);
-    confirmationDialog = inject(QdConfirmationDialogOpenerService);
-    _destroy$ = new Subject();
-    _deactivate$ = new Subject();
-    _bypassInterception = false;
-    _allowedTargetUrls = new Set();
-    _confirmationMessage;
-    ngOnDestroy() {
-        this._allowedTargetUrls.clear();
-        this._destroy$.next();
-        this._destroy$.complete();
-        this._deactivate$.complete();
-    }
-    /**
-     * Starts intercepting navigation events. Replaces any previously active listener.
-     */
-    activate(confirmationMessage) {
-        this._confirmationMessage = confirmationMessage;
-        this._deactivate$.next();
-        this.listenForUnsavedNavigationAttempts();
-    }
-    /**
-     * Stops intercepting and clears all pending URL bypasses.
-     */
-    deactivate() {
-        this._deactivate$.next();
-        this._allowedTargetUrls.clear();
-    }
-    /**
-     * Whitelists the next navigation so it bypasses interception.
-     * Without a URL, any next navigation is bypassed (wildcard). With a URL, only that
-     * specific navigation is bypassed — non-matching navigations are still intercepted.
-     */
-    allowNextNavigation(targetUrl) {
-        this._allowedTargetUrls.add(targetUrl ?? '*');
-    }
-    /**
-     * Executes the callback with interception temporarily disabled.
-     * The callback must navigate synchronously — async navigation after the callback returns
-     * will not be bypassed. This works because Angular's router emits NavigationStart
-     * synchronously within the navigateByUrl() / navigate() call.
-     */
-    executeWithBypass(fn) {
-        this._bypassInterception = true;
-        try {
-            fn();
-        }
-        finally {
-            this._bypassInterception = false;
-        }
-    }
-    listenForUnsavedNavigationAttempts() {
-        this.router.events
-            .pipe(filter$1((event) => event instanceof NavigationStart), filter$1(() => !this._bypassInterception), filter$1(event => this.shouldIntercept(event)), concatMap$1(event => this.checkForPendingChanges(event)), filter$1(({ hasChanges }) => hasChanges), exhaustMap(({ event }) => this.cancelNavigationAndConfirm(event)), filter$1(({ confirmed }) => confirmed), takeUntil$1(this._deactivate$), takeUntil$1(this._destroy$))
-            .subscribe(({ targetUrl }) => this.navigateToConfirmedTarget(targetUrl));
-    }
-    shouldIntercept(event) {
-        if (this._allowedTargetUrls.has('*')) {
-            this._allowedTargetUrls.clear();
-            return false;
-        }
-        if (this._allowedTargetUrls.has(event.url)) {
-            this._allowedTargetUrls.delete(event.url);
-            return false;
-        }
-        return true;
-    }
-    checkForPendingChanges(event) {
-        return this.formGroupManager.$hasValuesChanged().pipe(take$1(1), map$1(hasChanges => ({ event, hasChanges })));
-    }
-    cancelNavigationAndConfirm(event) {
-        this._bypassInterception = true;
-        void this.router.navigateByUrl(this.router.url, { skipLocationChange: true });
-        return this.confirmationDialog
-            .showDiscardConfirmDialog(this._confirmationMessage, 'page-navigation-confirmation')
-            .pipe(map$1(confirmed => ({ confirmed, targetUrl: event.url })), finalize(() => (this._bypassInterception = false)));
-    }
-    navigateToConfirmedTarget(targetUrl) {
-        this._bypassInterception = false;
-        this._allowedTargetUrls.add(targetUrl);
-        void this.router.navigateByUrl(targetUrl);
-    }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.18", ngImport: i0, type: QdPageNavigationInterceptorService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.18", ngImport: i0, type: QdPageNavigationInterceptorService });
-}
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.18", ngImport: i0, type: QdPageNavigationInterceptorService, decorators: [{
-            type: Injectable
-        }] });
-
 class QdPageSubmitActionService {
     footerService = inject(QdPageFooterService);
     formGroupManagerService = inject(QdFormGroupManagerService);
+    navigationInterceptor = inject(QdPageNavigationInterceptorService);
     _labelI18n = 'i18n.qd.page.footer.submit';
-    _submitHandler;
+    _submitAction;
     _isVisible = true;
     _destroyed$ = new Subject();
     _cancelTrackFormValidity$ = new Subject();
@@ -28697,9 +28803,9 @@ class QdPageSubmitActionService {
         this._isVisible = isVisible;
         this.configureSubmitAction(pageTypeConfig.submit);
     }
-    configureSubmitAction(submitConfig) {
-        this._labelI18n = submitConfig.label?.i18n || 'i18n.qd.page.footer.submit';
-        this._submitHandler = this.buildSubmitHandler(submitConfig.handler);
+    configureSubmitAction(action) {
+        this._labelI18n = action.label?.i18n || 'i18n.qd.page.footer.submit';
+        this._submitAction = action;
         this.registerSubmitAction();
         this.trackFormValidity();
     }
@@ -28709,7 +28815,7 @@ class QdPageSubmitActionService {
                 key: 'submit',
                 action: {
                     titleI18n: this._labelI18n,
-                    handler: this._submitHandler,
+                    handler: (...args) => this.executeSubmit(...args),
                     isDisabled: true,
                     isVisible: this._isVisible,
                     type: QdFooterActionType.Primary
@@ -28717,12 +28823,16 @@ class QdPageSubmitActionService {
             }
         ]);
     }
-    buildSubmitHandler(originalHandler) {
-        return (...args) => {
-            if (!this.formGroupManagerService.hasFormGroups())
-                return originalHandler(...args);
-            return originalHandler(this.formGroupManagerService.getAllValues());
-        };
+    executeSubmit(...args) {
+        const action = this._submitAction;
+        if (!action)
+            return;
+        const values = this.formGroupManagerService.hasFormGroups() ? this.formGroupManagerService.getAllValues() : args;
+        QdPageCommitActionExecutor.execute(action, values, {
+            formGroupManager: this.formGroupManagerService,
+            navigationInterceptor: this.navigationInterceptor,
+            destroyed$: this._destroyed$
+        });
     }
     trackFormValidity() {
         this._cancelTrackFormValidity$.next();
@@ -28737,7 +28847,7 @@ class QdPageSubmitActionService {
                 key: 'submit',
                 action: {
                     titleI18n: this._labelI18n,
-                    handler: this._submitHandler,
+                    handler: (...args) => this.executeSubmit(...args),
                     isDisabled: !isValid,
                     isVisible: this._isVisible,
                     type: QdFooterActionType.Primary
@@ -28792,6 +28902,22 @@ const SAFE_BOTTOM_OFFSET_PX = 64;
  *
  * Please check the relevant interfaces for each page type: `QdPageConfigOverview`, `QdPageConfigCreate`, `QdPageConfigInspect`, and `QdPageConfigCustom`.
  *
+ * #### **Commit Actions**
+ *
+ * Commit actions (`submit`, `save`, `saveDraft`) can either run synchronously (handler returns `void`) or wait on an async result (handler returns `Observable<boolean>`). The framework waits for the first emission, advances the saved-state baseline on `true`, and exposes race-free hooks for side effects so navigation after a successful commit does not trigger the unsaved-changes dialog.
+ *
+ * `onSuccess` runs when the handler emits `true` (after the baseline has advanced), `onError` runs when the handler observable errors — e.g. a failed HTTP request that is not caught inside the pipeline.
+ *
+ * ```ts
+ * submit: {
+ *   handler: (formValues) => this.api.create(formValues).pipe(map(() => true)),
+ *   onSuccess: () => this.router.navigateByUrl('/'),
+ *   onError: (err) => this.notifications.add('', { type: 'critical', i18n: 'i18n.myApp.create.failed' })
+ * }
+ * ```
+ *
+ * The same mechanism applies to `save` and `saveDraft`. For the full contract (success vs. planned `false` vs. error, anti-patterns, `discardUnsavedChanges()`), see `QdPageCommitAction` and its action-specific extensions `QdPageSaveAction`, `QdPageSaveDraftAction`, `QdPageCreateSubmitAction`, and `QdPageInspectSubmitAction`.
+ *
  * #### **Validation/Parameterization**
  *
  * Validation and parameterization are covered in a dedicated chapter in the Storybook. Please check the "Validation" section for more information.
@@ -28861,7 +28987,15 @@ const SAFE_BOTTOM_OFFSET_PX = 64;
  *         handler: () => handleCancel()
  *       },
  *       save: {
- *         handler: (formValues) => handleSave(formValues)
+ *         handler: () => saveApi.save(form.value).pipe(
+ *           tap(result => notifications.success('Saved')),
+ *           map(() => true),
+ *           catchError(err => {
+ *             notifications.showError(err);
+ *             return of(false);
+ *           })
+ *         ),
+ *         onSuccess: () => router.navigate(['/overview'])
  *       }
  *     }
  *   };
@@ -28870,19 +29004,42 @@ const SAFE_BOTTOM_OFFSET_PX = 64;
  *
  * #### **Updating Facets**
  *
- * Typically, the values of the facets on a create or inspect page are set to read-only. However, there may be cases where, for example, a status change is needed, such as through a dialog. For this purpose, we have provided an update method. In the resolver service, define an empty method called `updateMetadata`. Inject this service using its type, and then call the `updateMetadata` method with the required parameter.
+ * Typically, the values of the facets on a create or inspect page are set to read-only. If a facet value needs to change at runtime — for instance after a status update from a dialog — push the partial update through an observable on the page config. The header subscribes to `QdPageConfig.metadata$` and shallow-merges every emission into the current object data.
  *
  * **Please note: These values should not be modified directly within a QdPage.**
  *
  * ```ts
- * @Injectable()
- * class MyObjectModelResolver implements QdPageObjectResolver<MyObjectModel> {
- *   config: QdPageObjectResolverConfig = {
- *     // your configuration options here
+ * @Component({
+ *   // ...
+ *   providers: [
+ *     {
+ *       provide: QD_PAGE_OBJECT_RESOLVER_TOKEN,
+ *       useClass: MyObjectModelResolver
+ *     }
+ *   ]
+ * })
+ * class MyPageComponent {
+ *   private metadataUpdates$ = new Subject<Partial<MyObjectModel>>();
+ *
+ *   pageConfig: QdPageConfig<MyObjectModel> = {
+ *     title: { i18n: 'i18n.page.title' },
+ *     pageType: 'inspect',
+ *     headerFacets: [ /* ... *\/ ],
+ *     metadata$: this.metadataUpdates$,
+ *     pageTypeConfig: { /* ... *\/ }
+ *   };
+ *
+ *   updateStatus() {
+ *     this.metadataUpdates$.next({ state: 'Updated' });
  *   }
+ * }
+ * ```
  *
- *   constructor(private http: HttpClient) {}
+ * Legacy approach (`@deprecated`): the resolver-level `updateMetadata` method is still wired up for backward compatibility, but prefer `metadata$` on the config for new code.
  *
+ * ```ts
+ * @Injectable()
+ * class MyObjectModelResolver implements QdPageObjectResolver<MyObjectModel> {
  *   resolve(): Observable<MyObjectModel> {
  *     // your implementation here
  *   }
@@ -28892,15 +29049,6 @@ const SAFE_BOTTOM_OFFSET_PX = 64;
  *   }
  * }
  *
- * @Component({
- *   // ...
- *   providers: [
- *     {
- *       provide: QD_PAGE_OBJECT_RESOLVER_TOKEN,
- *       useClass: MyObjectModelResolver
- *     }
- *   ]
- * })
  * class MyPageComponent {
  *   constructor(@Inject(QD_PAGE_OBJECT_RESOLVER_TOKEN) private objectResolver: MyObjectModelResolver) {}
  *
@@ -28979,7 +29127,8 @@ const SAFE_BOTTOM_OFFSET_PX = 64;
  *   pageType: 'create',
  *   pageTypeConfig: {
  *     submit: {
- *       handler: (formValues) => handleSubmit(formValues)
+ *       handler: (formValues) => createApi.create(formValues).pipe(map(() => true)),
+ *       onSuccess: () => router.navigate(['/items'])
  *     }
  *   }
  * };
@@ -29072,7 +29221,14 @@ const SAFE_BOTTOM_OFFSET_PX = 64;
  *       handler: () => handleCancel()
  *     },
  *     save: {
- *       handler: (formValues) => handleSave(formValues)
+ *       handler: (formValues) => saveApi.save(formValues).pipe(
+ *         map(() => true),
+ *         catchError(err => {
+ *           notifications.showError(err);
+ *           return of(false);
+ *         })
+ *       ),
+ *       onSuccess: () => router.navigate(['/overview'])
  *     }
  *   }
  * };
@@ -29216,7 +29372,7 @@ class QdPageComponent {
         if (this.config.pageType === 'create' && this.config?.pageTypeConfig?.cancel !== undefined)
             this.handleCancelActionWithFormChanges();
         if (this.config.pageType === 'create' && this.config?.pageTypeConfig?.saveDraft !== undefined)
-            this.initSaveDraftFooterAction();
+            this.initSaveDraftFooterAction(this.config.pageTypeConfig.saveDraft);
         if (this.config.pageType === 'inspect')
             this.pageStoreService.isViewonly$
                 .pipe(takeUntil(this._destroyed$))
@@ -29230,6 +29386,34 @@ class QdPageComponent {
         this._destroyed$.next();
         this._destroyed$.complete();
     }
+    /**
+     * @description Resets all registered form groups to their last saved snapshot, marking the page
+     * as no longer dirty.
+     *
+     * Intended for explicit consumer-driven discard scenarios where you want subsequent navigation
+     * to bypass the unsaved-changes dialog — for example inside a commit action's `onError` hook
+     * after an auth-expiry response, where the user must be redirected to the login page regardless
+     * of unsaved edits.
+     *
+     * Prefer this over wiring custom bypass logic; it keeps the discard explicit and auditable in
+     * application code.
+     *
+     * @example
+     * ```ts
+     * save: {
+     *   handler: (values) => api.save(values).pipe(map(() => true)),
+     *   onError: (err) => {
+     *     if (err.status === 401) {
+     *       this.pageComponent.discardUnsavedChanges();
+     *       this.router.navigateByUrl('/login');
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    discardUnsavedChanges() {
+        this.formGroupManagerService.restoreFormGroupsFromSnapshot();
+    }
     checkConfigValidity() {
         if (!this.config)
             console.warn('QdUi | QdPageComponent - To configure the page you should provide a valid config.');
@@ -29242,11 +29426,14 @@ class QdPageComponent {
             const action = pageTypeConfig[actionKey];
             if (!action)
                 continue;
+            const handler = actionKey === 'cancel'
+                ? () => action.handler()
+                : this.generateCommitActionHandler(action);
             actions.push({
                 actionKey,
                 partialAction: {
                     ...(action?.label?.i18n ? { titleI18n: action.label.i18n } : {}),
-                    handler: this.generateFooterActionHandler(action?.handler)
+                    handler
                 }
             });
         }
@@ -29263,25 +29450,20 @@ class QdPageComponent {
                     partialAction: {
                         handler: hasChanged
                             ? () => this.setupCancelConfirmation()
-                            : () => {
-                                this.navigationInterceptor.executeWithBypass(() => {
-                                    this.config?.pageTypeConfig?.cancel?.handler();
-                                });
-                            }
+                            : () => this.config?.pageTypeConfig?.cancel?.handler()
                     }
                 }
             ]);
         });
     }
-    initSaveDraftFooterAction() {
-        const pageTypeConfig = this.config.pageTypeConfig;
+    initSaveDraftFooterAction(saveDraft) {
         this.footerService.setActions([
             {
                 key: 'saveDraft',
                 action: {
-                    titleI18n: pageTypeConfig.saveDraft?.label?.i18n ?? 'i18n.qd.page.footer.saveDraft',
+                    titleI18n: saveDraft.label?.i18n ?? 'i18n.qd.page.footer.saveDraft',
                     type: QdFooterActionType.Secondary,
-                    handler: this.generateFooterActionHandler(pageTypeConfig?.saveDraft?.handler),
+                    handler: this.generateCommitActionHandler(saveDraft),
                     isVisible: true,
                     isDisabled: false
                 }
@@ -29308,12 +29490,14 @@ class QdPageComponent {
         if (this._isInitialized)
             this.operationModeChanged.emit(mode);
     }
-    generateFooterActionHandler(handler) {
+    generateCommitActionHandler(action) {
         return (...args) => {
-            if (!handler)
-                return;
             const values = this.formGroupManagerService.hasFormGroups() ? this.formGroupManagerService.getAllValues() : args;
-            this.navigationInterceptor.executeWithBypass(() => handler(values));
+            QdPageCommitActionExecutor.execute(action, values, {
+                formGroupManager: this.formGroupManagerService,
+                navigationInterceptor: this.navigationInterceptor,
+                destroyed$: this._destroyed$
+            });
         };
     }
     setupCancelConfirmation() {
@@ -29322,8 +29506,8 @@ class QdPageComponent {
             .showDiscardConfirmDialog(cancelConfig?.confirmationMessage, this.testId + '-cancel-confirmation')
             .pipe(filter$1(result => result), takeUntil(this._destroyed$))
             .subscribe(() => {
+            this.formGroupManagerService.restoreFormGroupsFromSnapshot();
             cancelConfig?.handler?.();
-            this.navigationInterceptor.allowNextNavigation();
         });
     }
     initSubmitValidation() {
@@ -29331,7 +29515,7 @@ class QdPageComponent {
         this.formGroupManagerService
             .$areFormGroupsValid()
             .pipe(takeUntil(this._cancelSubmitValidation$), takeUntil(this._destroyed$), tap(isValid => {
-            const submitDisabledInfoText = this.config.pageType === 'inspect' ? this.config.pageTypeConfig?.submit?.disabledInfo : undefined;
+            const submitDisabledInfoText = this.config.pageTypeConfig?.submit?.disabledInfo;
             this.footerService.updateActions([
                 {
                     actionKey: 'submit',