@openfin/workspace-platform 5.3.0 → 5.3.1

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

@@ -1,59 +1,237 @@
 /// <reference types="openfin-adapter/fin" />
 import type { InteropBroker } from 'openfin-adapter/src/api/interop';
-import type { App } from '../../client-api/src/shapes';
 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';
+export type { CustomThemes } from '../../common/src/api/theming';
 export type { App, Image, AppIntent } from '../../client-api/src/shapes';
 export { AppManifestType } from '../../client-api/src/shapes';
+export type { AttachedPage, Page, PageWithUpdatableRuntimeAttribs, PageLayout, PageLayoutDetails } from '../../common/src/api/pages/shapes';
+/**
+ * Request for creating a saved page in persistent storage.
+ */
 export interface CreateSavedPageRequest {
+    /** The page to create. */
     page: Page;
 }
+/**
+ * Request for updating a saved page in persistent storage.
+ */
 export interface UpdateSavedPageRequest {
     /** The ID of the page to update. */
     pageId: string;
     /** The updated page. */
     page: Page;
 }
+/**
+ * Request for reordering the pages attached to a window.
+ */
 export interface ReorderPagesRequest {
-    /** The ordered ids of the attached pages. */
+    /** An array of page ids that specify the order of the pages attached to the window. */
     pageIds: string[];
 }
-export interface UpdateOpenPageRequest {
+/**
+ * Request to update the attributes of a page in which is attached to a running browser window.
+ */
+export interface UpdateAttachedPageRequest {
     /** The ID of the page to update. */
     pageId: string;
     /** The updated page. */
     page: Partial<PageWithUpdatableRuntimeAttribs>;
 }
-export type { Page, PageLayout, PageLayoutDetails } from '../../common/src/api/pages/shapes';
-export declare type BrowserCreateWindowRequestInternal = BrowserCreateWindowRequest & OpenFin.WindowCreationOptions;
+/**
+ * Request for creating a browser window.
+ */
 export interface BrowserCreateWindowRequest extends Omit<OpenFin.PlatformWindowCreationOptions, 'workspacePlatform'> {
+    /** WorkspacePlatform specific window options. These options will not work unless a workspace platform has been initialized. */
     workspacePlatform: {
+        /** The initial set of pages to add to the created browser window. */
         pages: Page[];
+        /** The favicon to display on the top left of the created browser window. */
         favicon?: string;
+        /** A UI friendly title for the created browser window. */
         title?: string;
+        /**
+         * Landing page that shows up when you add a new tab from the plus button that exists in the tabstrip.
+         * If you do not provide a newTabUrl, then the plus button in the tabstrip will not be shown and users cannot create a new empty tab.
+         */
         newTabUrl?: string;
+        /**
+         * Landing page that shows up when you add a new page from the plus button that exists in the window frame where the page selector is shown.
+         * 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;
     };
 }
+/**
+ * A window that is part of a browser snapshot.
+ */
+export declare type BrowserSnapshotWindow = OpenFin.WindowCreationOptions & BrowserCreateWindowRequest;
+/**
+ * A browser snapshot.
+ */
+export interface BrowserSnapshot {
+    /** The state of the windows that were running at the time the snapshot was taken. */
+    windows: BrowserSnapshotWindow[];
+}
+/**
+ * Controller for interacting with a browser window.
+ */
 export interface BrowserWindowModule {
+    /** The identity of the browser window. */
     identity: OpenFin.Identity;
+    /** Underlying OpenFin window Controller. */
     openfinWindow: OpenFin.Window;
+    /**
+     * Get a page that is attached to the browser window.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * // assume a browser window already exists
+     * const windows = await workspacePlatform.Browser.getAllWindows();
+     * const page = await windows[0].getPage('MyPageId');
+     * ```
+     * @param id the id of the page to get.
+     */
     getPage(id: string): Promise<AttachedPage>;
     /**
      * Return all the pages that are attached to a browser window.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * // assume a browser window already exists
+     * const windows = await workspacePlatform.Browser.getAllWindows();
+     * const pages = await windows[0].getPages();
+     * ```
      */
     getPages(): Promise<AttachedPage[]>;
+    /**
+     * Set the active page for the browser window.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * // assume a browser window already exists
+     * const windows = await workspacePlatform.Browser.getAllWindows();
+     * await windows[0].setActivePage('MyPageId');
+     * ```
+     * @param id the id of the attached page to set as active.
+     */
     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.
      *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const layout = {
+     *      content: [
+     *          {
+     *              type: 'stack',
+     *              content: [
+     *                  {
+     *                      type: 'component',
+     *                      componentName: 'view',
+     *                      componentState: {
+     *                          name: 'myViewName',
+     *                          url: 'http://google.com'
+     *                      }
+     *                  }
+     *              ]
+     *           }
+     *      ]
+     * };
+     * const page = {
+     *      title: 'myPageTitle',
+     *      pageId: 'myPageId',
+     *      layout
+     * };
+     * // assume a browser window already exists
+     * const windows = await workspacePlatform.Browser.getAllWindows();
+     * await windows[0].addPage(page);
+     * ```
      * @param page the attach page to a browser window.
      */
     addPage(page: PageWithUpdatableRuntimeAttribs): Promise<void>;
+    /**
+     * Remove an attached page from the browser window.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * // assume a browser window already exists
+     * const windows = await workspacePlatform.Browser.getAllWindows();
+     * await windows[0].removePage('myPageId');
+     * ```
+     * @param id the id of the attached page to remove from the browser window.
+     */
     removePage(id: string): Promise<void>;
-    updatePage(req: UpdateOpenPageRequest): Promise<void>;
+    /**
+     * Update a page in which is attached to the browser window.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const layout = {
+     *      content: [
+     *          {
+     *              type: 'stack',
+     *              content: [
+     *                  {
+     *                      type: 'component',
+     *                      componentName: 'view',
+     *                      componentState: {
+     *                          name: 'myViewName',
+     *                          url: 'http://google.com'
+     *                      }
+     *                  }
+     *              ]
+     *           }
+     *      ]
+     * };
+     * const page = {
+     *      title: 'myPageTitle',
+     *      pageId: 'myPageId',
+     *      layout
+     * };
+     * // assume a browser window already exists
+     * const windows = await workspacePlatform.Browser.getAllWindows();
+     * const req = {
+     *      pageId: 'myPageId',
+     *      page
+     * };
+     * await windows[0].updatePage(req);
+     * ```
+     * @param req the update request.
+     */
+    updatePage(req: UpdateAttachedPageRequest): Promise<void>;
+    /**
+     * Reorder pages attached to the browser window.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * // assume a browser window already exists and has three pages in it
+     * const windows = await workspacePlatform.Browser.getAllWindows();
+     * await windows[0].reorderPages(['myPageId2', 'myPageId1', 'myPageId3']);
+     * ```
+     * @param req the reorder pages request.
+     */
     reorderPages(req: ReorderPagesRequest): Promise<void>;
 }
+/**
+ * Factory for wrapping browser windows and global operations.
+ */
 export interface BrowserWindowFactory {
     /**
      * Synchronously returns a Browser Window object that represents an existing window
@@ -62,42 +240,259 @@ export interface BrowserWindowFactory {
      */
     wrapSync: (identity: OpenFin.Identity) => BrowserWindowModule;
     /**
-     * Get a list of pages that are open on browser windows.
+     * Get a list of all pages that are attached to any running browser window.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const attachedPages = await workspacePlatform.Browser.getAllAttachedPages();
+     * ```
      */
-    getOpenPages(): Promise<AttachedPage[]>;
+    getAllAttachedPages(): Promise<AttachedPage[]>;
     /**
-     *  Get all the Browser Windows that are open in the Workspace Platform
+     *  Get all the Browser Windows that are running in the Workspace Platform.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
      *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const windows = await workspacePlatform.Browser.getAllWindows();
+     * ```
      */
     getAllWindows(): Promise<BrowserWindowModule[]>;
     /**
      * Create a new browser window.
      *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const layout = {
+     *      content: [
+     *          {
+     *              type: 'stack',
+     *              content: [
+     *                  {
+     *                      type: 'component',
+     *                      componentName: 'view',
+     *                      componentState: {
+     *                          name: 'myViewName',
+     *                          url: 'http://google.com'
+     *                      }
+     *                  }
+     *              ]
+     *           }
+     *      ]
+     * };
+     * const page = {
+     *      title: 'myPageTitle',
+     *      pageId: 'myPageId',
+     *      layout
+     * };
+     * const options: BrowserCreateWindowRequest = {
+     *      workspacePlatform {
+     *          pages: [page],
+     *          title: 'My Window Title',
+     *          favicon: 'https://google.com/favicon.ico'
+     *      }
+     * };
+     * const window = await workspacePlatform.Browser.createWindow(options);
+     * ```
+     *
      * @param options the browser window creation options
      */
-    createWindow: (options: BrowserCreateWindowRequest) => Promise<BrowserWindowModule>;
+    createWindow(options: BrowserCreateWindowRequest): Promise<BrowserWindowModule>;
     /**
      * Get a unique title for a page.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const uniqueTitle = await workspacePlatform.Browser.getUniquePageTitle('myTitle');
+     * ```
      * @param title a prefix for the title.
      */
     getUniquePageTitle(title?: string): Promise<string>;
     /**
      * Get the identity of the last focused Browser window.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const windowIdentity = await workspacePlatform.Browser.getLastFocusedWindow();
+     * ```
      */
     getLastFocusedWindow(): Promise<OpenFin.Identity>;
 }
+/**
+ * API for interacting with persistent storage.
+ */
 export interface WorkspacePlatformStorage {
+    /**
+     * Get all pages that are saved in persistent storage.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const pages = await workspacePlatform.Storage.getPages();
+     * ```
+     */
     getPages(): Promise<Page[]>;
+    /**
+     * Get a specific page in persistent storage.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const myPage = await workspacePlatform.Storage.getPage('myPageId');
+     * ```
+     * @param id the id of the page to get.
+     */
     getPage(id: string): Promise<Page>;
+    /**
+     * Create a page in persistent storage.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const layout = {
+     *      content: [
+     *          {
+     *              type: 'stack',
+     *              content: [
+     *                  {
+     *                      type: 'component',
+     *                      componentName: 'view',
+     *                      componentState: {
+     *                          name: 'myViewName',
+     *                          url: 'http://google.com'
+     *                      }
+     *                  }
+     *              ]
+     *           }
+     *      ]
+     * };
+     * const page = {
+     *      title: 'myPageTitle',
+     *      pageId: 'myPageId',
+     *      layout
+     * };
+     * await workspacePlatform.Storage.createPage({page});
+     * ```
+     * @param page the page to create in persistent storage.
+     */
     createPage(page: CreateSavedPageRequest): Promise<void>;
+    /**
+     * Update a page in persistent storage.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const layout = {
+     *      content: [
+     *          {
+     *              type: 'stack',
+     *              content: [
+     *                  {
+     *                      type: 'component',
+     *                      componentName: 'view',
+     *                      componentState: {
+     *                          name: 'myViewName',
+     *                          url: 'http://google.com'
+     *                      }
+     *                  }
+     *              ]
+     *           }
+     *      ]
+     * };
+     * const page = {
+     *      title: 'myPageTitle',
+     *      pageId: 'myPageId',
+     *      layout
+     * };
+     * const req = {
+     *      pageId: 'myPageId',
+     *      page
+     * };
+     * await workspacePlatform.Storage.updatePage(req);
+     * ```
+     * @param req the update saved page request.
+     */
     updatePage(req: UpdateSavedPageRequest): Promise<void>;
+    /**
+     * Delete a page from persistent storage.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * await workspacePlatform.Storage.deletePage('myPageId');
+     * ```
+     * @param id the id of the page to delete.
+     */
     deletePage(id: string): Promise<void>;
+    /**
+     * Save a page in persistent storage.
+     *
+     * This is a helper function that will call `getPage` to determine if a page is already in storage.
+     * If the page is already in storage, it will call `updatePage`.
+     * If it does not exist in storage, the function will call `createPage` instead.
+     *
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const layout = {
+     *      content: [
+     *          {
+     *              type: 'stack',
+     *              content: [
+     *                  {
+     *                      type: 'component',
+     *                      componentName: 'view',
+     *                      componentState: {
+     *                          name: 'myViewName',
+     *                          url: 'http://google.com'
+     *                      }
+     *                  }
+     *              ]
+     *           }
+     *      ]
+     * };
+     * const page = {
+     *      title: 'myPageTitle',
+     *      pageId: 'myPageId',
+     *      layout
+     * };
+     * await workspacePlatform.Storage.savePage(page);
+     * ```
+     * @param page the page to save.
+     */
     savePage(page: Page): Promise<void>;
 }
-export interface LaunchAppPayload {
+/**
+ * Request for launching an application.
+ */
+export interface LaunchAppRequest {
     target?: OpenFin.EntityInfo;
     app: App;
 }
+/**
+ * Get Themes from API
+ */
+export interface ThemeApi {
+    getThemes(): Promise<CustomThemes>;
+}
+/**
+ * Controller for a Workspace Platform.
+ */
 export interface WorkspacePlatformModule extends OpenFin.Platform {
     /**
      * Launch a browser snapshot that contains windows with pages.
@@ -105,29 +500,131 @@ export interface WorkspacePlatformModule extends OpenFin.Platform {
      * @param snapshot the browser snapshot to launch or a url or filepath to retrieve a JSON snapshot.
      */
     applySnapshot(snapshot: BrowserSnapshot | string): Promise<OpenFin.Platform>;
+    /**
+     * Get a snapshot that contains browser windows with pages.
+     */
     getSnapshot(): Promise<BrowserSnapshot>;
-    launchApp: (payload: LaunchAppPayload) => Promise<void>;
+    /**
+     * Launch an application.
+     * ```ts
+     * import * as WorkspacePlatform from '@openfin/workspace-platform';
+     *
+     * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+     * const req = {
+     *      app: {
+     *          appId: 'myAppId',
+     *          title: 'appTitle',
+     *          manifest: 'http://localhost/app.json',
+     *          manifestType: AppManifestType.Manifest,
+     *          icons:[
+     *              {
+     *                  icon: "https://cdn.openfin.co/demos/notifications/generator/images/icon-blue.png",
+     *                  src: "https://cdn.openfin.co/demos/notifications/generator/images/icon-blue.png",
+     *                  type: "ico",
+     *              },
+     *          ]
+     *      }
+     * }
+     * workspacePlatform.launchApp(req);
+     *
+     * ```
+     * @param req the launch app request.
+     */
+    launchApp(req: LaunchAppRequest): Promise<void>;
+    /**
+     * The browser window factory for the Workspace Platform.
+     */
     Browser: BrowserWindowFactory;
+    /**
+     * The storage API for the Workspace Platform.
+     */
     Storage: WorkspacePlatformStorage;
-}
-export interface BrowserSnapshot {
-    windows: BrowserCreateWindowRequestInternal[];
+    /**
+     * Theme API for the Workspace Platform.
+     */
+    Theme: ThemeApi;
 }
 export interface WorkspacePlatformProvider extends OpenFin.PlatformProvider {
+    /**
+     * Implementation for getting a list of saved pages from persistent storage.
+     * @param query an optional query.
+     */
     getSavedPages(query?: string): Promise<Page[]>;
+    /**
+     * Implementation for getting a single page in persistent storage.
+     * @param id
+     */
     getSavedPage(id: string): Promise<Page>;
+    /**
+     * Implementation for creating a saved page in persistent storage.
+     * @param req the create saved page request.
+     */
     createSavedPage(req: CreateSavedPageRequest): Promise<void>;
+    /**
+     * Implementation for updating a saved page in persistent storage.
+     * @param req the update saved page request.
+     */
     updateSavedPage(req: UpdateSavedPageRequest): Promise<void>;
+    /**
+     * Implementation for deleting a saved page in persistent storage.
+     * @param id of the id of the page to delete.
+     */
     deleteSavedPage(id: string): Promise<void>;
 }
+/**
+ * Configuration for initializing a Workspace platform.
+ */
 export interface WorkspacePlatformInitConfig {
-    browser: BrowserInitConfig;
-    licenseKey: string;
-    theme?: any;
+    /** Config for overriding browser options and behavior. */
+    browser?: BrowserInitConfig;
+    /** Custom Themes object */
+    theme?: CustomThemes;
 }
+/**
+ * Extend or replace default functionality in order to customize behavior of a Workspace Platform Provider.
+ *
+ * To implement your own handlers for Workspace Platform behavior, extend the provided class and override any methods you'd like to alter.
+ *
+ * ```ts
+ * import * as WorkspacePlatform from '@openfin/workspace-platform';
+ * import { UpdateSavedPageRequest } from '../../client-api-platform/src/shapes';
+ *
+ * const overrideCallback: WorkspacePlatform.BrowserOverrideCallback = async (
+ *    WorkspacePlatformProvider
+ * ) => {
+ *   class Override extends WorkspacePlatformProvider {
+ *       updateSavedPage = async (req: UpdateSavedPageRequest): Promise<void> => {
+ *           console.log(`saving page ${req.page.pageId}`);
+ *           // calling custom function to the save page here
+ *      };
+ *   }
+ *   return new Override();
+ * };
+ *
+ * await WorkspacePlatform.init({
+ *  browser: { overrideCallback },
+ * });
+ */
+export declare type BrowserOverrideCallback = OpenFin.OverrideCallback<WorkspacePlatformProvider>;
+/**
+ * Configuration for initializing a Browser.
+ */
 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;
+    /**
+     * 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.
+     */
     defaultViewOptions?: OpenFin.ViewOptions;
-    overrideCallback?: Partial<OpenFin.OverrideCallback<WorkspacePlatformProvider, WorkspacePlatformProvider>>;
+    /**
+     * Override workspace platform behavior
+     */
+    overrideCallback?: BrowserOverrideCallback;
+    /**
+     * Override workspace platform interop behavior
+     * https://cdn.openfin.co/docs/javascript/stable/InteropBroker.html
+     */
     interopOverride?: OpenFin.OverrideCallback<InteropBroker, InteropBroker>;
 }

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

@@ -1,4 +1,4 @@
-import type { Page } from '@common/api/pages/shapes';
+import type { Page } from '../../../../common/src/api/pages/shapes';
 export declare const store: import("idb-keyval").UseStore;
 export declare function getPage(id: string): Promise<Page>;
 export declare function getPageList(filter?: string): Promise<Page[]>;
@@ -9,4 +9,4 @@ export declare function deletePage(id: string): Promise<void>;
 export declare function updatePage({ pageId, page }: {
     pageId: any;
     page: any;
-}): Promise<boolean>;
+}): Promise<void>;

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

@@ -1,4 +1,4 @@
-import { LayoutExtended } from '@common/utils/layout';
+import { LayoutExtended } from '../../../../common/src/utils/layout';
 import type { AttachedPage, Page, PageLayout, PageWithUpdatableRuntimeAttribs } from './shapes';
 export declare function getLegacyPages(): Promise<Page[]>;
 export declare function cleanPage(page: AttachedPage): Page;
@@ -14,3 +14,9 @@ export declare const getPageLayout: (layout: any) => Promise<PageLayout>;
  * @param layout the layout for the page.
  */
 export declare const makePage: (title: string, layout: LayoutExtended) => Promise<PageWithUpdatableRuntimeAttribs>;
+/**
+ * Clone a page.
+ * @param page the page to clone.
+ * @returns a clone of the given page.
+ */
+export declare const clonePage: (page: Page) => Promise<PageWithUpdatableRuntimeAttribs>;

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

@@ -1,4 +1,4 @@
-import type { AttachedPage, PageLayout } from '@common/api/pages/shapes';
+import type { AttachedPage, PageLayout } from '../../../../common/src/api/pages/shapes';
 interface Workstack {
     id: string;
     name: string;

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

@@ -26,7 +26,8 @@ export declare enum ChannelAction {
     HideHome = "hide-home",
     AssignHomeSearchContext = "assign-home-search-context",
     GetLegacyPages = "get-legacy-pages",
-    GetLegacyWorkspaces = "get-legacy-workspaces"
+    GetLegacyWorkspaces = "get-legacy-workspaces",
+    GetComputedPlatformTheme = "get-computed-platform-theme"
 }
 export interface ChannelClient extends OpenFin.ChannelClient {
     dispatch: (action: ChannelAction, payload: any) => Promise<any>;