@openfin/workspace-platform 19.1.18 → 19.1.20

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

@@ -1,5 +1,6 @@
 import { type CustomButtonConfig, type CustomDropdownConfig } from '../../../common/src/api/action';
 import { type RegistrationMetaInfo } from '../../../client-api/src/shapes/common';
+import { TaskbarIcon } from '../../../client-api-platform/src/shapes';
 import { type ProviderInfo } from './provider';
 /**
  * Allows you to hide buttons for different Workspace components in the Dock UI.
@@ -177,7 +178,7 @@ export interface DockProviderConfig {
     /**
      * Icon for the provider.
      */
-    icon: string;
+    icon: string | TaskbarIcon;
 }
 export interface DockProviderConfigWithIdentity extends ProviderInfo, DockProviderConfig {
 }

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

@@ -1,3 +1,4 @@
+import { TaskbarIcon } from '../../../client-api-platform/src/shapes';
 export interface ProviderInfo {
     /**
      * Unique identifier for the provider.
@@ -12,9 +13,13 @@ export interface ProviderInfo {
     /**
      * Icon for the provider.
      */
-    icon: string;
+    icon: string | TaskbarIcon;
     /**
      *  version of client SDK, set by the API
      */
     clientAPIVersion?: string;
+    /**
+     * The group name to group the taskbar icon with.
+     */
+    taskbarIconGroup?: string;
 }

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';
@@ -663,11 +663,15 @@ export interface BrowserWorkspacePlatformWindowOptions {
      * When true, disables the ability to close pages in the window. False by default.
      */
     preventPageClose?: boolean;
+    /**
+     * Taskbar Icon for the Browser Window. If light and dark icon are defined, then the taskbar icon will change when the scheme changes.
+     */
+    icon?: string | TaskbarIcon;
 }
 /**
  * Request for creating a browser window.
  */
-export interface BrowserCreateWindowRequest extends Omit<OpenFin.PlatformWindowCreationOptions, 'workspacePlatform'> {
+export interface BrowserCreateWindowRequest extends Omit<OpenFin.PlatformWindowCreationOptions, 'workspacePlatform' | 'icon'> {
     /** WorkspacePlatform specific window options. These options will not work unless a workspace platform has been initialized. */
     workspacePlatform: BrowserWorkspacePlatformWindowOptions | {
         /** For internal usage.  Defaults to 'browser' when Browser is enabled when the WorkspacePlatform is initialized.  In order to use
@@ -676,6 +680,10 @@ export interface BrowserCreateWindowRequest extends Omit<OpenFin.PlatformWindowC
          * */
         windowType: WindowType.Platform;
     };
+    /** The icon to display on the taskbar.
+     * @deprecated Use the icon property in the workspacePlatform object instead.
+     */
+    icon?: string;
 }
 /**
  * A window that is part of a browser snapshot.
@@ -1651,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.
@@ -2105,3 +2173,7 @@ export type OpenSaveMenuRequest = {
     menuType: SaveModalType.SAVE_WORKSPACE | SaveModalType.SAVE_WORKSPACE_AS | SaveModalType.RENAME_WORKSPACE;
     id?: never;
 };
+export type TaskbarIcon = {
+    dark: string;
+    light: string;
+};

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;
@@ -227,5 +253,7 @@ export type AddPagePayload = {
     identity: OpenFin.Identity;
     /** The page to attach. */
     page: PageWithUpdatableRuntimeAttribs;
+    /** Index at which the page should be added */
+    insertionIndex?: number;
 };
 export {};

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/route.d.ts

@@ -28,8 +28,8 @@ export declare enum PageRoute {
 export declare const Assets: {
     readonly IconOpenFinLogo: "/icons/openfinlogo.svg";
     readonly IconFilter: "/icons/filter.svg";
-    readonly LightStorefront: "/icons/lightstorefront.png";
-    readonly DarkStorefront: "/icons/darkstorefront.png";
+    readonly LightStorefront: "/icons/store-icon-light.png";
+    readonly DarkStorefront: "/icons/store-icon-dark.png";
     readonly CallIconLight: "/icons/call-icon-light.svg";
     readonly CallIconDark: "/icons/call-icon-dark.svg";
     readonly ChatIconLight: "/icons/chat-icon-light.svg";
@@ -45,6 +45,8 @@ export declare const Assets: {
         readonly Microsoft365Icon: "/microsoft-365-integration-assets/microsoft-365-icon.svg";
         readonly PDFFileIcon: "/microsoft-365-integration-assets/pdf-file-icon.svg";
     };
+    readonly DockIconLight: "/icons/dock-icon-light.png";
+    readonly DockIconDark: "/icons/dock-icon-dark.png";
 };
 /**
  * Home DeepLink Options