@quadrel-enterprise-ui/framework 20.10.0 → 20.10.1

package/index.d.ts

@@ -9214,11 +9214,17 @@ interface QdPageCustomActionsLabel {
  */
 type QdInspectOperationMode = 'view' | 'edit';
 /**
- * @description Interface for the save action, including optional validation configuration.
+ * @description Common shape for all framework-managed commit actions (save, save draft, submit).
+ *
+ * Each commit action is built around a single `handler` whose return value tells the framework how
+ * the action ended (success / planned failure / error), with optional `onSuccess` / `onError` hooks
+ * for consumer-side reactions. Per-action interfaces (`QdPageSaveAction`, `QdPageSaveDraftAction`,
+ * `QdPageCreateSubmitAction`, `QdPageInspectSubmitAction`) extend this base with their action-specific
+ * options.
  */
-interface QdPageSaveAction {
+interface QdPageCommitAction {
     /**
-     * @description Label for the save action, used for translation.
+     * @description Label for the action, used for translation.
      *
      * * If no custom translation key is provided, a standard label will be used by default.
      */
@@ -9226,17 +9232,106 @@ interface QdPageSaveAction {
         i18n: string;
     };
     /**
-     * @description Triggered when the save action is executed.
+     * @description Triggered when the action is executed.
      *
      * Success criteria:
-     * - If the handler returns an Observable<boolean>, only the first emission after the save click counts:
-     *   - **true:** success - toggle to view and apply the saved values
-     *   - **false:** failure/cancel - stay in edit mode
-     * - If the handler returns no Observable (void), the save is treated as instant success (toggle + apply values).
+     * - If the handler returns an `Observable<boolean>`, only the first emission counts:
+     *   - **true:** success — the framework marks the form as saved (the page is no longer dirty).
+     *   - **false:** failure/cancel — the form stays dirty.
+     * - If the handler returns `void`, the action is treated as instant success and the form is marked as saved immediately.
+     *
+     * Errors emitted by the Observable trigger the optional `onError` hook, or fall back to `console.error` if
+     * `onError` is not configured. The form stays dirty either way.
+     *
+     * **When to emit `false` vs. let an error fly:**
+     * - `false` = predictable cancel/reject (user aborted, business rule, structured validation response from the backend).
+     * - Error = unexpected (network outage, 5xx, bug).
+     *
+     * Rule of thumb: if the UI can explain the cause to the user, emit `false` (plus a notification). Otherwise let the error propagate.
+     *
+     * ---
+     *
+     * **Anti-pattern: do not navigate from inside an async handler pipeline.**
      *
-     * On a successful save, the framework applies the values and resets its internal validation and change-tracking state.
+     * The framework runs the synchronous handler invocation inside its navigation-bypass window. For
+     * a sync `void` handler that calls `router.navigate(...)` directly, this is fine — the bypass is
+     * active and the form is marked as saved immediately afterwards.
+     *
+     * For an `Observable<boolean>` handler, the bypass window closes as soon as the handler returns
+     * the observable. Side effects wired into `tap` (or any later operator) run **after** the bypass
+     * has already closed AND **before** the framework marks the form as saved on the `true` emission.
+     * Navigating from there raises the unsaved-changes dialog — exactly what the framework is trying
+     * to suppress. Use `onSuccess` for navigation after async commits.
      */
     handler: (formValues?: any) => void | Observable<boolean>;
+    /**
+     * @description Optional callback invoked after the framework marks the form as saved on a successful commit.
+     *
+     * * Runs in the framework's navigation-bypass window, so router navigation from this hook does **not**
+     *   raise the unsaved-changes dialog.
+     *
+     * * For async handlers (returning `Observable<boolean>`), this hook is the **only** race-free place to
+     *   navigate. Side effects in `tap` run *before* the framework marks the form as saved; navigation
+     *   from there would still see a dirty form and trigger the dialog.
+     *
+     * @example
+     * ```ts
+     * submit: {
+     *   handler: (values) => api.create(values).pipe(map(() => true)),
+     *   onSuccess: () => router.navigateByUrl('/')
+     * }
+     * ```
+     */
+    onSuccess?: () => void;
+    /**
+     * @description Optional callback invoked when the handler observable emits an error.
+     *
+     * * Receives the original error from the observable.
+     *
+     * * **Not** invoked when the handler emits `false` — `false` is a planned outcome, errors are unexpected
+     *   (see the `handler` doc for the distinction).
+     *
+     * * **Does not run in the navigation-bypass window.** Navigation from this hook raises the unsaved-changes
+     *   dialog, because the form is still dirty after a failed commit — and the user usually wants to keep
+     *   their edits. To navigate away unconditionally (e.g. on auth expiry), call
+     *   `QdPageComponent.discardUnsavedChanges()` first to reset the form to its last saved state.
+     *
+     * * If `onError` is not configured, the framework falls back to `console.error` so failures never go silent.
+     *
+     * @example
+     * ```ts
+     * submit: {
+     *   handler: (values) => api.create(values).pipe(map(() => true)),
+     *   onSuccess: () => router.navigateByUrl('/'),
+     *   onError: (err) => notifications.error('i18n.create.failed', err)
+     * }
+     * ```
+     *
+     * @example
+     * Navigate away unconditionally from onError (e.g. auth-expiry redirect to login). Call `discardUnsavedChanges()` first to drop the dirty snapshot so the next navigation passes through without the dialog:
+     *
+     * ```ts
+     * @ViewChild(QdPageComponent) pageComponent!: QdPageComponent<MyModel>;
+     *
+     * submit: {
+     *   handler: (values) => api.save(values).pipe(map(() => true)),
+     *   onError: (err) => {
+     *     if (err.status === 401) {
+     *       this.pageComponent.discardUnsavedChanges();
+     *       this.router.navigateByUrl('/login');
+     *       return;
+     *     }
+     *     this.notifications.error('i18n.save.failed', err);
+     *   }
+     * }
+     * ```
+     */
+    onError?: (err: unknown) => void;
+}
+/**
+ * @description Interface for the save action, including optional validation configuration.
+ */
+interface QdPageSaveAction extends QdPageCommitAction {
     /**
      * @description Optional validation flag, defaults to true.
      * Determines whether form validation is required before saving and ensures that changes must be present in the form before saving.
@@ -9250,21 +9345,10 @@ interface QdPageSaveAction {
     hasValidation?: boolean;
 }
 /**
- * @description Interface for the safe draft action.
+ * @description Interface for the save draft action. Inherits the standard commit-action shape
+ * (`label`, `handler`, `onSuccess`, `onError`) without further options.
  */
-interface QdPageSaveDraftAction {
-    /**
-     * @description Label for the save draft action, used for translation.
-     *
-     * * If no custom translation key is provided, a standard label will be used by default.
-     */
-    label?: {
-        i18n: string;
-    };
-    /**
-     * @description Handler function that is triggered when the save draft action is executed.
-     */
-    handler: () => void;
+interface QdPageSaveDraftAction extends QdPageCommitAction {
 }
 /**
  * @description Interface for the cancel action, including an optional confirmation message.
@@ -9295,45 +9379,10 @@ interface QdPageCancelAction {
     };
 }
 /**
- * @description Interface for the submit action on create pages.
+ * @description Interface for the submit action on create pages. Inherits the standard commit-action
+ * shape (`label`, `handler`, `onSuccess`, `onError`) without further options.
  */
-interface QdPageCreateSubmitAction {
-    /**
-     * @description Label for the submit action, used for translation.
-     *
-     * * If no custom translation key is provided, a standard label will be used by default.
-     */
-    label?: {
-        i18n: string;
-    };
-    /**
-     * @description Handler function that is triggered when the submit action is executed.
-     */
-    handler: (formValues?: any) => void;
-}
-/**
- * @description Interface for the submit action.
- */
-interface QdPageSubmitAction {
-    /**
-     * @description Label for the submit action, used for translation.
-     *
-     * * If no custom translation key is provided, a standard label will be used by default.
-     */
-    label?: {
-        i18n: string;
-    };
-    /**
-     * @description Handler function that is triggered when the submit action is executed.
-     */
-    handler: (formValues?: any) => void;
-    /**
-     * @description By default, the visibility of the submit button depends on the page type and the operation mode.
-     * To completely hide the submit button, you can set this isHidden flag.
-     *
-     * @default false
-     */
-    isHidden?: boolean;
+interface QdPageCreateSubmitAction extends QdPageCommitAction {
 }
 /**
  * @description Interface for the edit action.
@@ -9375,9 +9424,18 @@ interface QdPageArchiveAction {
     handler: (formValues?: any) => void;
 }
 /**
- * @description Inspect-specific submit action configuration.
+ * @description Inspect-specific submit action configuration. Submit on inspect pages is a process
+ * action (status change, approval, workflow transition) and is only visible in **view** mode.
  */
-interface QdPageInspectSubmitAction extends QdPageSubmitAction {
+interface QdPageInspectSubmitAction extends QdPageCommitAction {
+    /**
+     * @description By default, the visibility of the submit button depends on the operation mode
+     * (visible in view mode, hidden in edit mode). Set this flag to hide the button entirely,
+     * regardless of mode.
+     *
+     * @default false
+     */
+    isHidden?: boolean;
     /**
      * @description Optional info message shown when submit is disabled on inspect pages for non-validation reasons.
      *
@@ -12806,6 +12864,22 @@ declare class QdSectionComponent implements OnInit, AfterViewInit, OnChanges, On
  *
  * 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.
@@ -12875,7 +12949,15 @@ declare class QdSectionComponent implements OnInit, AfterViewInit, OnChanges, On
  *         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'])
  *       }
  *     }
  *   };
@@ -12993,7 +13075,8 @@ declare class QdSectionComponent implements OnInit, AfterViewInit, OnChanges, On
  *   pageType: 'create',
  *   pageTypeConfig: {
  *     submit: {
- *       handler: (formValues) => handleSubmit(formValues)
+ *       handler: (formValues) => createApi.create(formValues).pipe(map(() => true)),
+ *       onSuccess: () => router.navigate(['/items'])
  *     }
  *   }
  * };
@@ -13086,7 +13169,14 @@ declare class QdSectionComponent implements OnInit, AfterViewInit, OnChanges, On
  *       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'])
  *     }
  *   }
  * };
@@ -13193,12 +13283,38 @@ declare class QdPageComponent<T extends object> implements OnInit, OnChanges, Af
     ngOnChanges(changes: SimpleChanges): void;
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
+    /**
+     * @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(): void;
     private checkConfigValidity;
     private setupCreatePageFooterActions;
     private handleCancelActionWithFormChanges;
     private initSaveDraftFooterAction;
     private updateInspectPageOperationMode;
-    private generateFooterActionHandler;
+    private generateCommitActionHandler;
     private setupCancelConfirmation;
     private initSubmitValidation;
     private setupPageDialogCloseContract;
@@ -13325,6 +13441,7 @@ declare class QdPageStoreService<T extends object> {
 declare class QdPageObjectHeaderComponent<T extends object> implements OnInit, OnChanges, OnDestroy {
     private pageObjectResolver;
     private formGroupManagerService;
+    private navigationInterceptor;
     private dialogComponent;
     private dialog;
     private confirmationDialogService;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadrel-enterprise-ui/framework",
-  "version": "20.10.0",
+  "version": "20.10.1",
   "exports": {
     "./jest-preset": "./jest-preset.js",
     "./package.json": {