@openfin/workspace-platform 19.1.19 → 19.2.0

package/client-api-platform/src/api/pages/index.d.ts

@@ -1,6 +1,6 @@
 import type OpenFin from '@openfin/core';
-import type { AttachedPage, CopyPagePayload, DetachPagesFromWindowPayload, ExtendedAttachPagesToWindowPayload, HandleSaveModalOnPageClosePayload, ReorderPagesForWindowPayload, SaveModalOnPageCloseResult, SetActivePageForWindowPayload, UpdatePageForWindowPayload } from '../../../../common/src/api/pages/shapes';
-import type { CreateSavedPageRequest, HandlePageChangesPayload, ModifiedPageState, Page, UpdateSavedPageRequest } from '../../../../client-api-platform/src/shapes';
+import type { AttachedPage, CopyPagePayload, DetachPagesFromWindowPayload, ExtendedAttachPagesToWindowPayload, HandlePagesAndWindowClosePayload, HandlePagesAndWindowCloseResult, HandleSaveModalOnPageClosePayload, ReorderPagesForWindowPayload, SaveModalOnPageCloseResult, SetActivePageForWindowPayload, ShouldPageClosePayload, ShouldPageCloseResult, UpdatePageForWindowPayload } from '../../../../common/src/api/pages/shapes';
+import type { CreateSavedPageRequest, HandlePageChangesPayload, ModifiedPageState, Page, UpdateSavedPageRequest, WorkspacePlatformProvider } from '../../../../client-api-platform/src/shapes';
 /**
  * Get all open pages in which are attached to a window.
  * @returns the list of attached pages.
@@ -31,6 +31,17 @@ export declare const getActivePageIdForWindow: (identity: OpenFin.Identity) => P
  */
 export declare function getUniquePageTitle(initialName?: string): Promise<string>;
 export declare function handleSaveModalOnPageClose({ page }: HandleSaveModalOnPageClosePayload): Promise<SaveModalOnPageCloseResult>;
+/**
+ * Default implementation of shouldPageClose. If enableBeforeUnload isn't set to true, always returns True (proceed with close).
+ * If beforeunload handling is enabled, will return False if any views in the page are determined not to close.
+ */
+export declare function shouldPageClose(this: WorkspacePlatformProvider, { page, identity }: ShouldPageClosePayload): Promise<ShouldPageCloseResult>;
+/**
+ * Default implementation of handlePagesAndWindowClose. Will abort closing of the window if any of the pages within it are prevented from closing.
+ * @param payload Contains pages that were prevented from closing, pages that weren't, and identity of the window
+ * @returns {shouldWindowClose: boolean} which determines whether closing of the window will proceed
+ */
+export declare function handlePagesAndWindowClose(this: WorkspacePlatformProvider, { pagesPreventingClose, pagesNotPreventingClose, identity }: HandlePagesAndWindowClosePayload): Promise<HandlePagesAndWindowCloseResult>;
 export declare function copyPageOverride({ page }: CopyPagePayload): Promise<Page>;
 export declare function handlePageChanges(payload: HandlePageChangesPayload): Promise<ModifiedPageState>;
 /**

package/client-api-platform/src/shapes.d.ts

@@ -2,7 +2,7 @@ import type OpenFin from '@openfin/core';
 import { IconProps, Languages } from '@openfin/ui-library';
 import type { AnalyticsEvent, AnalyticsEventInternal } from '../../common/src/utils/usage-register';
 import { CustomActionSpecifier, CustomButtonConfig } from '../../common/src/api/action';
-import type { AddDefaultPagePayload, AttachedPage, CopyPagePayload, HandleSaveModalOnPageClosePayload, Page, PageWithUpdatableRuntimeAttribs, SaveModalOnPageCloseResult } from '../../common/src/api/pages/shapes';
+import type { AddDefaultPagePayload, AttachedPage, CopyPagePayload, HandlePagesAndWindowClosePayload, HandlePagesAndWindowCloseResult, HandleSaveModalOnPageClosePayload, Page, PageWithUpdatableRuntimeAttribs, SaveModalOnPageCloseResult, ShouldPageClosePayload, ShouldPageCloseResult, ViewsPreventingUnloadPayload } from '../../common/src/api/pages/shapes';
 import { SetActivePageForWindowPayload } from '../../common/src/api/pages/shapes';
 import { NotificationsCustomManifestOptions } from '../../common/src/api/shapes/notifications';
 import type { CustomThemes } from '../../common/src/api/theming';
@@ -11,7 +11,7 @@ import type { WorkflowIntegration } from '../../client-api/src/shapes/integratio
 export { AppManifestType } from '../../client-api/src/shapes';
 export type { App, AppIntent, Image } from '../../client-api/src/shapes';
 export type { CustomActionSpecifier, CustomButtonConfig } from '../../common/src/api/action';
-export type { AttachedPage, Page, PageLayout, PageLayoutDetails, PageWithUpdatableRuntimeAttribs, PanelConfigHorizontal, PanelConfigVertical, PanelConfig, ExtendedPanelConfig, CopyPagePayload, HandleSaveModalOnPageClosePayload, SaveModalOnPageCloseResult, SetActivePageForWindowPayload } from '../../common/src/api/pages/shapes';
+export type { AttachedPage, Page, PageLayout, PageLayoutDetails, PageWithUpdatableRuntimeAttribs, PanelConfigHorizontal, PanelConfigVertical, PanelConfig, ExtendedPanelConfig, CopyPagePayload, HandleSaveModalOnPageClosePayload, SaveModalOnPageCloseResult, SetActivePageForWindowPayload, ShouldPageClosePayload, ShouldPageCloseResult, ViewsPreventingUnloadPayload } from '../../common/src/api/pages/shapes';
 export { PanelPosition } from '../../common/src/api/pages/shapes';
 export type { CustomThemes, CustomThemeOptions, CustomThemeOptionsWithScheme, CustomPaletteSet, BaseThemeOptions, ThemeExtension, WorkspaceThemeSet, NotificationIndicatorColorsSet, NotificationIndicatorColorsSetDarkScheme, NotificationIndicatorColorsSetLightScheme, NotificationIndicatorColorsWithScheme } from '../../common/src/api/theming';
 export type { AnalyticsEvent } from '../../common/src/utils/usage-register';
@@ -1659,6 +1659,66 @@ export interface WorkspacePlatformProvider extends OpenFin.PlatformProvider {
      * and `false` otherwise.
      */
     handleSaveModalOnPageClose(payload: HandleSaveModalOnPageClosePayload): Promise<SaveModalOnPageCloseResult>;
+    /**
+     * This override is called upon closing of the page by user or for each page in a window that is being closed by user.
+     *
+     * In case of closing a page individually, the close operation will be aborted if a False value is returned.
+     *
+     * In case of closing a window, the return value will be used to form payload of handlePagesAndWindowClose override, which determines whether the window should proceed with closing.
+     *
+     * Default behavior: if beforeunload is disabled for the platform, True is always returned.
+     * If enableBeforeUnload is set to true and getUserDecisionForBeforeUnload override is configured to respect beforeunload decisions of views,
+     * then True is only returned if no views are preventing unload.
+     */
+    shouldPageClose(payload: ShouldPageClosePayload): Promise<ShouldPageCloseResult>;
+    /**
+     * This override is called upon closing of a window by user and its return value determines whether the window should proceed closing.
+     * pagesPreventingClose and pagesNotPreventingClose represent pages in the window, grouped based on the value returned by shouldPageClose override for each page.
+     * Default implementation will abort closing of the window if any of the pages within it are prevented from closing.
+     * @param payload Contains pages that were prevented from closing, pages that weren't, and identity of the window
+     * @returns `Promise<{shouldWindowClose: boolean}>` which determines whether closing of the window will proceed
+     */
+    handlePagesAndWindowClose(payload: HandlePagesAndWindowClosePayload): Promise<HandlePagesAndWindowCloseResult>;
+    /**
+     * Handle the decision of whether a Window, Page or specific View should close when trying to prevent an unload. This is meant to be overridden.
+     * Called in {@link WorkspacePlatformProvider.closeWindow} and {@link WorkspacePlatformProvider.closeView}.
+     *
+     * When closing a Page, this override is called by {@link WorkspacePlatformProvider.shouldPageClose}
+     * and page proceeds to close if all views passed in are determined to close. In this case, the `closeType` property will have `'page'` value.
+     *
+     * Normally you would use this method to show a dialog indicating that there are Views that are trying to prevent an unload.
+     * By default it will always return all Views passed into it as meaning to close.
+     * @param payload
+     * @example
+     *
+     * ```js
+     * const overrideCallback = (PlatformProvider) => {
+     *     class Override extends PlatformProvider {
+     *         async getUserDecisionForBeforeUnload(payload, callerIdentity) {
+     *             const { windowShouldClose, viewsPreventingUnload, viewsNotPreventingUnload, windowId, closeType } = payload;
+     *
+     *             // launch dialog and wait for user response
+     *             const continueWithClose = await showDialog(viewsPreventingUnload, windowId, closeType);
+     *
+     *             if (continueWithClose) {
+     *                 return { windowShouldClose, viewsToClose: [...viewsNotPreventingUnload, ...viewsPreventingUnload] };
+     *             } else {
+     *                 return { windowShouldClose: false, viewsToClose: [] };
+     *             }
+     *         }
+     *     }
+     *     return new Override();
+     * }
+     *
+     * fin.Platform.init({ overrideCallback });
+     *
+     * async function showDialog(viewsPreventingUnload, windowId, closeType) {
+     *     // Show a dialog and await for user response
+     * }
+     * ```
+     *
+     */
+    getUserDecisionForBeforeUnload(payload: ViewsPreventingUnloadPayload): Promise<OpenFin.BeforeUnloadUserDecision>;
     /**
      * Implementation for setting the active page in a browser window.
      * Called when the active page is changed and on browser window creation.

package/common/src/api/pages/shapes.d.ts

@@ -196,6 +196,29 @@ export type PanelConfig = (PanelConfigHorizontal | PanelConfigVertical) & {
 export type ExtendedPanelConfig = PanelConfig & {
     viewOptions: PanelConfig['viewOptions'] & OpenFin.Identity;
 };
+export interface ShouldPageClosePayload {
+    /** The page that is closing. */
+    page: AttachedPage;
+    /** The OF window identity containing the page. */
+    identity: OpenFin.Identity;
+    /** The type of close operation that triggered the override */
+    closeType: 'page' | 'window' | 'view';
+}
+export interface ViewsPreventingUnloadPayload extends Omit<OpenFin.ViewsPreventingUnloadPayload, 'closeType'> {
+    closeType: OpenFin.ViewsPreventingUnloadPayload['closeType'] | 'page';
+}
+export interface HandlePagesAndWindowClosePayload {
+    /** Pages for which `shouldPageClose` override returned false */
+    pagesPreventingClose: AttachedPage[];
+    /** Pages for which `shouldPageClose` override returned true */
+    pagesNotPreventingClose: AttachedPage[];
+    /** Identity of the Browser window */
+    identity: OpenFin.Identity;
+}
+export interface HandlePagesAndWindowCloseResult {
+    /** Determines whether closing of the window should proceed. */
+    shouldWindowClose: boolean;
+}
 export interface HandleSaveModalOnPageClosePayload {
     /** The page that is closing. */
     page: AttachedPage;
@@ -206,6 +229,9 @@ export interface SaveModalOnPageCloseResult {
     /** If false, a modal informing that unsaved changes will be lost will not be displayed. */
     shouldShowModal: boolean;
 }
+export interface ShouldPageCloseResult {
+    shouldPageClose: boolean;
+}
 export interface CopyPagePayload {
     /** The OF browser identity containing the page to copy. */
     identity: OpenFin.Identity;

package/common/src/api/protocol/workspace-platform.d.ts

@@ -59,6 +59,8 @@ export declare enum WorkspacePlatformChannelAction {
     GetDockProviderConfig = "getDockProviderConfig",
     SaveDockProviderConfig = "saveDockProviderConfig",
     HandleSaveModalOnPageClose = "handleSaveModalOnPageClose",
+    ShouldPageClose = "shouldPageClose",
+    ShouldWindowClose = "shouldWindowClose",
     CopyPage = "copyPage",
     HandlePageChanges = "handlePageChanges",
     MarkUnsavedPagesAsSavedInternal = "markUnsavedPagesAsSavedInternal",

package/common/src/utils/popup-window.d.ts

@@ -14,12 +14,21 @@ export declare enum SaveMenuType {
  */
 export declare const getSaveContextMenuTemplate: (saveMenuType?: SaveMenuType) => OpenFin.MenuItemTemplate[];
 export declare function showModalWin<T extends keyof UserMenuParams>(params: UserMenuParams[T], windowOpts: OptionalExceptFor<OpenFin.WindowOptions, 'x' | 'y' | 'defaultWidth' | 'url' | 'name'>): Promise<OpenFin.Window>;
-export interface SearchMenuChannelRequest {
+export type SearchMenuChannelFocusView = {
+    type: 'focus-search-menu';
+};
+export type SearchMenuChannelViewResized = {
+    type: 'view-resized';
+    height: number;
+    width: number;
+};
+export type SearchMenuChannelUpdateState = {
     selectedViews: OpenFin.Identity[];
     openViews: OpenFin.Identity[];
     windowId: OpenFin.Identity;
-    type?: 'focus-view';
-}
+    type: 'update-search-menu-state';
+};
+export type SearchMenuChannelRequest = SearchMenuChannelFocusView | SearchMenuChannelViewResized | SearchMenuChannelUpdateState;
 export declare enum ContextMenuType {
     GlobalMenu = "global-menu",
     ContextMenu = "context-menu",
@@ -42,9 +51,6 @@ export type SearchMenuChannelResponse = {
     selectedView: OpenFin.Identity;
     inputUpdate?: string;
     trigger?: SiteAction;
-} | {
-    type: 'expand-status-changed';
-    isExpanded: boolean;
 } | {
     type: 'update-input';
     inputText: string;
@@ -52,7 +58,6 @@ export type SearchMenuChannelResponse = {
     landingPage: boolean;
 } | {
     type: 'resize-view';
-    isExpanded: boolean;
     height: number;
     width: number;
 };