@openfin/workspace-platform 5.4.0 → 5.7.1

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

@@ -1,5 +1,7 @@
 /// <reference types="openfin-adapter/fin" />
 import type { InteropBroker } from 'openfin-adapter/src/api/interop';
+import { NamedIdentity } from 'openfin-adapter/src/identity';
+import { IconProps } from '@openfin/ui-library';
 import type { AttachedPage, Page, PageWithUpdatableRuntimeAttribs } from '../../common/src/api/pages/shapes';
 import type { CustomThemes } from '../../common/src/api/theming';
 import type { App } from '../../client-api/src/shapes';
@@ -30,6 +32,106 @@ export interface ReorderPagesRequest {
     /** An array of page ids that specify the order of the pages attached to the window. */
     pageIds: string[];
 }
+/**
+ * Request for opening a logo context menu in Browser.
+ */
+export interface OpenGlobalContextMenuRequest {
+    /** Screen x-coordinate where context menu should be shown. */
+    x: number;
+    /** Screen y-coordinate where context menu should be shown. */
+    y: number;
+    /** Miscellaneous options necessary for implementing custom logic in the provider override. */
+    customData?: any;
+}
+/**Shape of the data property of a context menu template item */
+export interface ContextMenuItemData {
+    type: string;
+    action?: CustomActionSpecifier;
+}
+/**Types of global context menu options, including pre-defined ones.
+ * User-defined context menu items should use the value `Custom` */
+export declare enum GlobalContextMenuOptionType {
+    NewWindow = "NewWindow",
+    NewPage = "NewPage",
+    CloseWindow = "CloseWindow",
+    OpenStorefront = "OpenStorefront",
+    Quit = "Quit",
+    Custom = "Custom"
+}
+/**Shape of the data property of a global context menu template item */
+export interface GlobalContextMenuItemData extends ContextMenuItemData {
+    type: GlobalContextMenuOptionType;
+}
+/**Configuration of an option in the global context menu */
+export interface GlobalContextMenuItemTemplate extends OpenFin.MenuItemTemplate {
+    data: GlobalContextMenuItemData;
+}
+/**Payload received by a Custom Action that is invoked by a custom context menu option */
+export interface GlobalContextMenuOptionActionPayload {
+    callerType: CustomActionCallerType.GlobalContextMenu;
+    windowIdentity: OpenFin.Identity;
+    customData: any | undefined;
+}
+/**
+ * Payload received by the openGlobalContextMenu provider override.
+ */
+export declare type OpenGlobalContextMenuPayload = OpenGlobalContextMenuRequest & {
+    /** Template defining the options to show in the context menu. */
+    template: GlobalContextMenuItemTemplate[];
+    /** Identity of the Browser window where context menu should be shown. */
+    identity: NamedIdentity;
+    /** Default function that handles stock context menu options. */
+    callback: (data: GlobalContextMenuItemData) => any;
+};
+export interface ViewTabContextMenuTemplate extends OpenFin.MenuItemTemplate {
+    data: ViewTabMenuData;
+}
+/**
+ * Request for opening a view tab context menu in Browser.
+ */
+export interface OpenViewTabContextMenuRequest {
+    /** Screen x-coordinate where context menu should be shown. */
+    x: number;
+    /** Screen y-coordinate where context menu should be shown. */
+    y: number;
+    /** Miscellaneous options necessary for implementing custom logic in the provider override. */
+    customData?: any;
+    /** Template defining the options to show in the context menu. */
+    template: ViewTabContextMenuTemplate[];
+    selectedViews: OpenFin.Identity[];
+}
+export declare enum ViewTabMenuOptionType {
+    NewView = "NewView",
+    DuplicateViews = "DuplicateView",
+    OpenWithDefaultBrowser = "OpenWithDefaultBrowser",
+    ReloadViews = "ReloadTab",
+    CloseViews = "CloseTab",
+    AddToChannel = "AddToChannel",
+    RemoveFromChannel = "RemoveFromChannel",
+    Custom = "Custom"
+}
+export interface ViewTabMenuData {
+    type: ViewTabMenuOptionType;
+    action?: CustomActionSpecifier;
+    option?: string;
+}
+export interface ViewTabCustomActionPayload {
+    callerType: CustomActionCallerType.ViewTabContextMenu;
+    /** Any data necessary for the functioning of specified custom action*/
+    customData: any;
+    /** Identity of the Browser window where context menu should be shown. */
+    windowIdentity: NamedIdentity;
+    selectedViews: OpenFin.Identity[];
+}
+/**
+ * Payload received by the openViewTabContextMenu provider override.
+ */
+export declare type OpenViewTabContextMenuPayload = OpenViewTabContextMenuRequest & {
+    /** Identity of the Browser window where context menu should be shown. */
+    identity: NamedIdentity;
+    /** Default function that handles stock context menu options. */
+    callback: (data: ViewTabMenuData, req: OpenViewTabContextMenuRequest) => any;
+};
 /**
  * Request to update the attributes of a page in which is attached to a running browser window.
  */
@@ -39,6 +141,78 @@ export interface UpdateAttachedPageRequest {
     /** The updated page. */
     page: Partial<PageWithUpdatableRuntimeAttribs>;
 }
+/**
+ * Types of buttons on browser windows
+ */
+export declare enum BrowserButtonType {
+    ShowHideTabs = "ShowHideTabs",
+    ColorLinking = "ColorLinking",
+    PresetLayouts = "PresetLayouts",
+    SavePage = "SavePage",
+    Minimise = "Minimise",
+    Maximise = "Maximise",
+    Close = "Close",
+    Custom = "Custom"
+}
+/**
+ * The shape of the payload sent by a custom button click to a custom action handler
+ */
+export interface CustomButtonActionPayload {
+    /** Calling the CustomButton type */
+    callerType: CustomActionCallerType.CustomButton;
+    /** Identity for the current window. */
+    windowIdentity: OpenFin.Identity;
+    /** Any data necessary for the functioning of specified custom action*/
+    customData: any;
+    /** Screen x-coordinate where custom button should be shown. */
+    x: number;
+    /** Screen y-coordinate where custom button should be shown. */
+    y: number;
+}
+/**
+ * Custom browser buttons
+ */
+export interface CustomBrowserButtonConfig {
+    /** Type of cutom browser button */
+    type: BrowserButtonType.Custom;
+    /** Button name text when hovered over */
+    tooltip: string;
+    /** Disable custom button true or false */
+    disabled?: boolean;
+    /** icon URL for icon image */
+    iconUrl: string;
+    /** Custom action once the button is clicked */
+    action: CustomActionSpecifier;
+}
+/**
+ * Default Browser Button types
+ */
+export interface PreDefinedButtonConfig {
+    /** Type of default browser button */
+    type: BrowserButtonType;
+    /** Button name text when hovered over */
+    tooltip?: string;
+    /** icon URL for icon image */
+    iconUrl?: string;
+    iconProps?: IconProps;
+}
+declare type ShowHideTabsConfig = {
+    type: BrowserButtonType.ShowHideTabs;
+};
+/**
+ *  Buttons on the left of WindowStateButtonOptions
+ */
+export declare type IconTrayButton = ShowHideTabsConfig | CustomBrowserButtonConfig | PreDefinedButtonConfig;
+export interface IconTrayOptions {
+    buttons: IconTrayButton[];
+}
+/**
+ * Buttons to the top far right of Browser
+ */
+export declare type WindowStateButton = CustomBrowserButtonConfig | PreDefinedButtonConfig;
+export interface WindowStateButtonOptions {
+    buttons: WindowStateButton[];
+}
 /**
  * Request for creating a browser window.
  */
@@ -61,6 +235,14 @@ export interface BrowserCreateWindowRequest extends Omit<OpenFin.PlatformWindowC
          * If you do not provide a newPageUrl, then the new Page plus button will not be shown and you cannot create a new empty Page or Window.
          */
         newPageUrl?: string;
+        iconTrayOptions?: IconTrayOptions;
+        windowStateButtonOptions?: WindowStateButtonOptions;
+        /**
+         * Remove the Page UI and only allow a single page in the browser window.
+         * Must be set to true for this behavior.  If this is not set to false,
+         * then an empty `pages` option will be populated with a single page.
+         */
+        disableMultiplePages?: boolean;
     };
 }
 /**
@@ -110,7 +292,7 @@ export interface BrowserWindowModule {
      */
     getPages(): Promise<AttachedPage[]>;
     /**
-     * Set the active page for the browser window.
+     * Set the active page for the browser window.  If `multiplePagesDisabled` is `true` an error will be thrown.
      *
      * ```ts
      * import * as WorkspacePlatform from '@openfin/workspace-platform';
@@ -125,7 +307,7 @@ export interface BrowserWindowModule {
     setActivePage(id: string): Promise<void>;
     /**
      * Attach a page to a browser window.
-     * If a page with same id or title is attached to an existing browser window, an error will be thrown.
+     * If `multiplePagesDisabled` is `true` or a page with same id or title is attached to an existing browser window, an error will be thrown.
      *
      * ```ts
      * import * as WorkspacePlatform from '@openfin/workspace-platform';
@@ -219,7 +401,7 @@ export interface BrowserWindowModule {
      */
     updatePage(req: UpdateAttachedPageRequest): Promise<void>;
     /**
-     * Reorder pages attached to the browser window.
+     * Reorder pages attached to the browser window.  If `multiplePagesDisabled` is `true` an error will be thrown.
      *
      * ```ts
      * import * as WorkspacePlatform from '@openfin/workspace-platform';
@@ -232,6 +414,7 @@ export interface BrowserWindowModule {
      * @param req the reorder pages request.
      */
     reorderPages(req: ReorderPagesRequest): Promise<void>;
+    _openViewTabContextMenu(req: OpenViewTabContextMenuRequest): Promise<void>;
 }
 /**
  * Factory for wrapping browser windows and global operations.
@@ -574,11 +757,56 @@ export interface WorkspacePlatformProvider extends OpenFin.PlatformProvider {
      * @param id of the id of the page to delete.
      */
     deleteSavedPage(id: string): Promise<void>;
+    /**
+     * Implementation for showing a global context menu given a menu template,
+     * handler callback, and screen coordinates
+     * @param req the payload received by the provider call
+     * @param callerIdentity OF identity of the entity from which the request originated
+     */
+    openGlobalContextMenu(req: OpenGlobalContextMenuPayload, callerIdentity: any): any;
+    /**
+     * Implementation for showing a view tab context menu given a menu template,
+     * handler callback, and screen coordinates
+     * @param req the payload received by the provider call
+     * @param callerIdentity OF identity of the entity from which the request originated
+     */
+    openViewTabContextMenu(req: OpenViewTabContextMenuPayload, callerIdentity: any): any;
+}
+/**
+ * The origins from which a custom action can be invoked
+ */
+export declare enum CustomActionCallerType {
+    CustomButton = "CustomButton",
+    GlobalContextMenu = "GlobalContextMenu",
+    ViewTabContextMenu = "ViewTabContextMenu",
+    API = "API"
+}
+/**The payload received by a Custom Action.
+ * The `callerType` property can be used to determine what data is available in the payload and cast accordingly.
+ * When `callerType == CustomActionCallerType.API`, the payload is defined by the code directly invoking the action.*/
+export declare type CustomActionPayload = {
+    callerType: CustomActionCallerType.API;
+} | CustomButtonActionPayload | GlobalContextMenuOptionActionPayload | ViewTabCustomActionPayload;
+/**
+ * Configures a custom action when the control is invoked
+ */
+export interface CustomActionSpecifier {
+    /** Identifier of a custom action defined at platform initialization*/
+    id: string;
+    /** Any data necessary for the functioning of specified custom action*/
+    customData?: any;
+}
+/**
+ * Defines custom action map where the key is the custom action ID and value is the action handler
+ */
+export interface CustomActionsMap {
+    [actionId: string]: (payload: CustomActionPayload) => any;
 }
 /**
  * Configuration for initializing a Workspace platform.
  */
 export interface WorkspacePlatformInitConfig {
+    customActions?: CustomActionsMap;
     /** Config for overriding browser options and behavior. */
     browser?: BrowserInitConfig;
     /** Custom Themes object
@@ -657,6 +885,8 @@ export interface BrowserInitConfig {
      * Default options for creating a new browser window. Any option not included in WorkspacePlatform.getCurrentSync().Browser.createWindow(options) call will default to the value provided in this field.
      */
     defaultWindowOptions?: BrowserCreateWindowRequest;
+    /** Default options when creating a new page. If `iconUrl`, `unsavedIconUrl` or `closeButton` are not defined when creating a page, setting will default to `defaultPageOptions`. */
+    defaultPageOptions?: Pick<Page, 'iconUrl' | 'unsavedIconUrl' | 'closeButton'>;
     /**
      * The default options when creating a new browser window. Any option not included in WorkspacePlatform.getCurrentSync().Browser.createView(options) call will default to the value provided in this field.
      */

package/common/src/api/browser-protocol.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="openfin-adapter/fin" />
+export declare const getWindowChannelId: (identity: OpenFin.Identity) => string;
+export declare const getChannelClient: (identity: OpenFin.Identity) => Promise<import("openfin-adapter").ChannelClient>;
+/**
+ * If the browser window is reloaded too quickly, runtime will
+ * respond that the channel provider has already been created.
+ * Hence, we retry a couple of times to make sure this does not occur.
+ * (Should only happen in local development)
+ */
+export declare const createChannel: () => Promise<import("openfin-adapter").ChannelProvider>;
+export interface AddToChannelRequest {
+    newChannelId: string;
+    selectedViews: OpenFin.Identity[];
+}
+export declare enum ChannelAction {
+    CloseBrowserWindow = "close-browser-window",
+    QuitPlatform = "quit-platform",
+    CloseActivePage = "close-active-page",
+    AddToChannel = "add-to-channel",
+    RemoveFromChannel = "remove-from-channel"
+}

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

@@ -21,7 +21,6 @@ export declare enum EventType {
     AttachedPagesToWindow = "attached-pages-to-window",
     DetachedPagesFromWindow = "detached-pages-from-window"
 }
-export declare const getWindowChannelId: (identity: OpenFin.Identity) => string;
 export declare const getEventEmitter: (identity: OpenFin.Identity) => {
     emit: (event: string | number, ...payload: any[]) => Promise<void>;
     addListener: (event: string | number, listener: import("@common/utils/shared-emitter").Listener) => void;

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

@@ -6,7 +6,7 @@ interface Workstack {
     layout: PageLayout;
     isActive: boolean;
 }
-export declare function convertWorkstackToAttachedPage(workstack: Workstack & AttachedPage): AttachedPage;
+export declare function convertWorkstackToAttachedPage({ id, name, ...rest }: Workstack & AttachedPage): AttachedPage;
 /**
  * Attempts to fix any misconfigurations in a list of attached pages.
  * @param pages the pages to fix.

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

@@ -20,8 +20,17 @@ export interface Page {
     tooltip?: string;
     /** True if the page is read only. In this state, the page is locked and cannot be unlocked. */
     isReadOnly?: boolean;
+    /** Icon that appears on a page tab if there are unsaved changes (dirty state). If 'undefined', default icon will appear. */
+    unsavedIconUrl?: string;
+    /** Icon that appears on a page tab if there are no unsaved changes. If 'undefined', default icon will appear. */
+    iconUrl?: string;
     /** The layout of the page. */
     layout: PageLayout;
+    /** Used to manipulate behaviour of a close button on a page tab. If `undefined`, then close button is visible and actionable. */
+    closeButton?: {
+        hidden?: boolean;
+        disabled?: boolean;
+    };
 }
 declare type AttachedPageMetadata = {
     /** The window the page is currently attached to. */

package/common/src/utils/context-menu.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="openfin-adapter/fin" />
+import { _Window } from 'openfin-adapter/src/api/window';
+export declare enum MenuItemType {
+    Label = "normal",
+    Separator = "separator",
+    Submenu = "submenu",
+    Checkbox = "checkbox"
+}
+export declare type ShowContextMenuResponse = OpenFin.MenuResult & {
+    data: string;
+};
+export default function showContextMenu(opts: OpenFin.ShowPopupMenuOptions, win?: _Window): Promise<ShowContextMenuResponse>;

package/common/src/utils/env.d.ts

@@ -12,19 +12,18 @@ export declare const isWindowDefinedWithIndexDB: boolean;
 export declare const finUUID: string;
 export declare const finName: string;
 export declare const finEntityType: "" | import("openfin-adapter/src/shapes/EntityType").EntityType;
-export declare const env: Env;
 export declare const isEnvLocal: boolean;
 export declare const isEnvDev: boolean;
 export declare const isEnvStaging: boolean;
 export declare const isEnvProd: boolean;
-export declare const isLibrary: boolean;
 export declare const workspaceProviderFinsLink: string;
 export declare const workspaceProviderFallbackUrl: string;
-export declare const workspaceAppsUrl: string;
-export declare const workspaceStorefrontFooterUrl: string;
-export declare const workspaceStorefrontLandingPageUrl: string;
-export declare const workspaceStorefrontNavigationUrl: string;
-export declare const workspaceShareUrl: string;
 export declare const workspaceCdnUrl: string;
 export declare const workspaceCdnEnvUrl: string;
 export declare const workspaceRuntimeVersion: string;
+/**
+ * A promise that resolves when:
+ *    - The window 'load' event is fired.
+ *    - The window first paint occurs.
+ */
+export declare const firstPaint: Promise<void>;

package/common/src/utils/global-context-menu.d.ts

@@ -0,0 +1,3 @@
+import { NamedIdentity } from 'openfin-adapter/src/identity';
+import { GlobalContextMenuItemTemplate } from '../../../client-api-platform/src/shapes';
+export declare const getGlobalContextMenuTemplate: (winIdentity: NamedIdentity) => Promise<GlobalContextMenuItemTemplate[]>;

package/common/src/utils/landing-page.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="openfin-adapter/fin" />
+import { NamedIdentity } from 'openfin-adapter/src/identity';
+interface LandingPageUrls {
+    newPageUrl: string | false;
+    newTabUrl: string | false;
+}
+export declare const getLandingPageUrls: (winIdentity?: NamedIdentity) => Promise<LandingPageUrls>;
+export declare const checkHasNewTabUrl: () => Promise<boolean>;
+export declare const getNewLandingTabViewOptions: (target: OpenFin.Identity) => Promise<OpenFin.PlatformViewCreationOptions>;
+export declare const makeNewLandingPage: (winIdentity?: NamedIdentity) => Promise<import("client-api-platform").PageWithUpdatableRuntimeAttribs>;
+export {};

package/common/src/utils/layout.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="openfin-adapter/fin" />
+import { NamedIdentity } from 'openfin-adapter/src/identity';
 export declare type LayoutComponentStateExtended = OpenFin.LayoutComponent['componentState'] & {
     name: string;
     uuid: string;
@@ -40,7 +41,7 @@ export declare type LayoutDOMEventListener = (ev: LayoutDOMEvent) => void;
  */
 export declare const cloneLayoutAndRemoveNames: (layout: any) => any;
 export declare const mapContentComponentState: (content: OpenFin.LayoutContent | LayoutContentExtended) => LayoutComponentStateExtended[];
-export declare const getLayoutWithSingleView: (title: string, url: string) => Promise<any>;
+export declare const getLayoutWithSingleView: (title: string, url: string, winIdentity?: NamedIdentity) => Promise<any>;
 export declare const isLayoutTabActive: (tabSelector: string) => boolean;
 export declare const containerId = "layout_container";
 export declare const getViewComponents: () => LayoutContentExtended;

package/common/src/utils/merge-deep.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Deep merge a set of source objects into a single target object.
+ * @param target the target object to merge sources into.
+ * @param sources the source objects to merge into the target. (FIFO)
+ */
+export declare function mergeDeep(target: any, ...sources: any[]): any;

package/common/src/utils/strings.d.ts

@@ -1,5 +1,3 @@
 export declare const capitalize: (s: string) => string;
-export declare const titleize: (s: string) => string;
 export declare const pascalize: (s: string) => string;
-export declare const slugify: (s: string) => string;
 export declare const isStringMatchesQuery: (title: string, query?: string) => boolean;

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

@@ -147,4 +147,5 @@ export declare const isStorefrontWindowRunning: () => Promise<boolean>;
 export declare const isHomeWindowRunning: () => Promise<boolean>;
 export declare const showAndFocusStorefront: () => Promise<void>;
 export declare const centerWindowIfOffScreen: (windowIdentity?: WindowIdentity) => Promise<void>;
+export declare const getDisableMultiplePagesOption: (identity: WindowIdentity) => Promise<any>;
 export {};