@openfin/workspace-platform 4.4.0 → 4.8.0

package/client-api-platform/src/api/app-directory.d.ts

@@ -1,7 +1,7 @@
-import type { LaunchAppPayload } from '../shapes';
+import type { LaunchAppRequest } from '../shapes';
 /**
  * Launch the app described by an App Directory entry.
  * @param app the app directory entry.
  * @param opts launch options.
  */
-export declare function launchApp({ app, target }: LaunchAppPayload): Promise<void | import("openfin-adapter").View | import("openfin-adapter").Application | import("openfin-adapter/src/api/platform").Platform | import("openfin-adapter").Identity>;
+export declare function launchApp({ app, target }: LaunchAppRequest): Promise<void | import("openfin-adapter").View | import("openfin-adapter").Application | import("openfin-adapter/src/api/platform").Platform | import("openfin-adapter").Identity>;

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

@@ -1,7 +1,7 @@
 /// <reference types="openfin-adapter/fin" />
 import type { AttachedPage, Page } from '@common/api/pages/shapes';
 import type { BrowserCreateWindowRequest, BrowserWindowModule } from '../../shapes';
-export declare const getBrowserApi: (identity: OpenFin.Identity) => {
+export declare const getBrowserApi: (identity: OpenFin.ApplicationIdentity) => {
     wrapSync: (windowIdentity: OpenFin.Identity) => {
         identity: OpenFin.Identity;
         openfinWindow: import("openfin-adapter").Window;
@@ -14,7 +14,7 @@ export declare const getBrowserApi: (identity: OpenFin.Identity) => {
         reorderPages: (req: any) => Promise<any>;
     };
     createWindow: (options: BrowserCreateWindowRequest) => Promise<BrowserWindowModule>;
-    getOpenPages: () => Promise<AttachedPage[]>;
+    getAllAttachedPages: () => Promise<AttachedPage[]>;
     getAllWindows: () => Promise<BrowserWindowModule[]>;
     launchPage: (page: Page) => Promise<BrowserWindowModule>;
     getUniquePageTitle: (title?: string) => Promise<any>;

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

@@ -5,7 +5,7 @@ import type { CreateSavedPageRequest, Page, UpdateSavedPageRequest } from '@clie
  * Get all open pages in which are attached to a window.
  * @returns the list of attached pages.
  */
-export declare const getOpenPages: () => Promise<import("@common/api/pages/shapes").AttachedPage[]>;
+export declare const getAllAttachedPages: () => Promise<import("@client-platform/shapes").AttachedPage[]>;
 export declare const createSavedPageInternal: ({ page }: CreateSavedPageRequest) => Promise<void>;
 export declare const deleteSavedPageInternal: (id: string) => Promise<void>;
 export declare const updateSavedPageInternal: ({ pageId, page }: UpdateSavedPageRequest) => Promise<any>;
@@ -14,11 +14,11 @@ export declare const attachPagesToWindow: (payload: AttachPagesToWindowPayload)
 export declare const updatePageForWindow: (payload: any) => Promise<void>;
 export declare const detachPagesFromWindow: (payload: any) => Promise<void>;
 export declare const setActivePageForWindow: (payload: any) => Promise<void>;
-export declare const getPagesForWindow: (identity: OpenFin.Identity) => Promise<import("@common/api/pages/shapes").AttachedPage[]>;
+export declare const getPagesForWindow: (identity: OpenFin.Identity) => Promise<import("@client-platform/shapes").AttachedPage[]>;
 export declare const getPageForWindow: ({ identity, pageId }: {
     identity: any;
     pageId: any;
-}) => Promise<import("@common/api/pages/shapes").AttachedPage>;
+}) => Promise<import("@client-platform/shapes").AttachedPage>;
 export declare const reorderPagesForWindow: (payload: any) => Promise<void>;
 export declare const getActivePageIdForWindow: (identity: any) => Promise<string>;
 /**

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

@@ -26,13 +26,14 @@ export declare enum ChannelAction {
     DetachPagesFromWindow = "detachPagesFromWindow",
     ReorderPagesForWindow = "reorderPagesForWindow",
     SetActivePageForWindow = "setActivePageForWindow",
-    GetOpenPages = "getOpenPages",
+    GetAllAttachedPages = "getAllAttachedPages",
     GetActivePageIdForWindow = "getActivePageIdForWindow",
     GetPagesForWindow = "getPagesForWindow",
     GetPageForWindow = "getPageForWindow",
     GetSavedPageMetadata = "getSavedPageMetadata",
     GetUniquePageTitle = "getUniquePageTitle",
-    GetLastFocusedBrowserWindow = "getLastFocusedBrowserWindow"
+    GetLastFocusedBrowserWindow = "getLastFocusedBrowserWindow",
+    GetThemes = "getThemes"
 }
 /**
  * Get a channel client for a specific Workspace platform.
@@ -44,4 +45,4 @@ export declare enum ChannelAction {
  *
  * @returns the channel client for the Workspace platform.
  */
-export declare const getChannelClient: (identity: OpenFin.Identity) => Promise<import("openfin-adapter").ChannelClient>;
+export declare const getChannelClient: (identity: OpenFin.ApplicationIdentity) => Promise<import("openfin-adapter").ChannelClient>;

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

@@ -0,0 +1,5 @@
+/// <reference types="openfin-adapter/fin" />
+import type { CustomThemes } from '@common/api/theming';
+export declare const getThemingApi: (identity: OpenFin.ApplicationIdentity) => {
+    getThemes: () => Promise<CustomThemes>;
+};

package/client-api-platform/src/api/workspace-module.d.ts

@@ -1,3 +1,3 @@
 /// <reference types="openfin-adapter/fin" />
 import type { WorkspacePlatformModule } from '../shapes';
-export declare const getWorkspacePlatformModule: (identity: OpenFin.Identity) => WorkspacePlatformModule;
+export declare const getWorkspacePlatformModule: (identity: OpenFin.ApplicationIdentity) => WorkspacePlatformModule;

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

@@ -2,5 +2,5 @@
 import type { WorkspacePlatformInitConfig, WorkspacePlatformModule } from './shapes';
 export * from './shapes';
 export declare const init: (options: WorkspacePlatformInitConfig) => Promise<void>;
-export declare const wrapSync: (identity: OpenFin.Identity) => WorkspacePlatformModule;
+export declare const wrapSync: (identity: OpenFin.ApplicationIdentity) => WorkspacePlatformModule;
 export declare const getCurrentSync: () => WorkspacePlatformModule;

package/client-api-platform/src/init/theming.d.ts

@@ -0,0 +1,9 @@
+import { CustomThemes } from '../shapes';
+export declare const getThemes: () => CustomThemes;
+/**
+ * initTheming()
+ * Accepts an array of CustomThemes objects and stores it
+ * @param customPaletteOptions - optional - array of custom color pallettes
+ * @returns array of custom theme objects
+ */
+export default function initTheming(customPalettes: CustomThemes): void;

package/client-api-platform/src/init/utils.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="openfin-adapter/fin" />
-export declare function overrideViewOptions(options: Partial<OpenFin.ViewOptions>): void;
+import { BrowserCreateWindowRequest } from '..';
+export declare function overrideViewOptions(options: Partial<OpenFin.ViewOptions>, initOptions: OpenFin.ViewOptions): OpenFin.ViewOptions & Partial<OpenFin.ViewOptions>;
 export declare const filterSnapshotWindows: (win: OpenFin.WindowOptions) => boolean;
 /**
  * fitToMonitor()
@@ -35,5 +36,5 @@ export declare const initWorkspacePlatformOptions: (options: LegacyWindowOptions
  * @param options - options used to handle layout settings
  * @returns processed or unprocesseed options
  */
-export declare const applyBrowserDefaults: (options: OpenFin.PlatformWindowCreationOptions) => OpenFin.PlatformWindowCreationOptions;
+export declare const applyBrowserDefaults: (options: OpenFin.PlatformWindowCreationOptions, initOptions: BrowserCreateWindowRequest) => OpenFin.PlatformWindowCreationOptions;
 export {};

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

@@ -2,46 +2,92 @@
 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';
+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: {
+        /** The initial set of pages to add to the created browser window. */
         pages: Page[];
+        /** The favicon to display on the top right of the created browser window. */
         favicon?: string;
+        /** A UI friendly title for the created browser window. */
         title?: string;
+        /** A URL to use when creating a new tab. */
         newTabUrl?: string;
+        /** A URL to use when creating the initial tab in a new page. */
         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.
+     * @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.
      */
     getPages(): Promise<AttachedPage[]>;
+    /**
+     * Set the active page for the browser window.
+     * @param id the id of the attached page to set as active.
+     */
     setActivePage(id: string): Promise<void>;
     /**
      * Attach a page to a browser window.
@@ -50,10 +96,25 @@ export interface BrowserWindowModule {
      * @param page the attach page to a browser window.
      */
     addPage(page: PageWithUpdatableRuntimeAttribs): Promise<void>;
+    /**
+     * Remove an attached page from the browser window.
+     * @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.
+     * @param req the update request.
+     */
+    updatePage(req: UpdateAttachedPageRequest): Promise<void>;
+    /**
+     * Reorder pages attached to the browser window.
+     * @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,20 +123,18 @@ 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.
      */
-    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.
      */
     getAllWindows(): Promise<BrowserWindowModule[]>;
     /**
      * Create a new browser window.
-     *
      * @param options the browser window creation options
      */
-    createWindow: (options: BrowserCreateWindowRequest) => Promise<BrowserWindowModule>;
+    createWindow(options: BrowserCreateWindowRequest): Promise<BrowserWindowModule>;
     /**
      * Get a unique title for a page.
      * @param title a prefix for the title.
@@ -86,18 +145,60 @@ export interface BrowserWindowFactory {
      */
     getLastFocusedWindow(): Promise<OpenFin.Identity>;
 }
+/**
+ * API for interacting with persistent storage.
+ */
 export interface WorkspacePlatformStorage {
+    /**
+     * Get all pages that are saved in persistent storage.
+     */
     getPages(): Promise<Page[]>;
+    /**
+     * Get a specific page in persistent storage.
+     * @param id the id of the page to get.
+     */
     getPage(id: string): Promise<Page>;
+    /**
+     * Create a page in persistent storage.
+     * @param page the page to create in persistent storage.
+     */
     createPage(page: CreateSavedPageRequest): Promise<void>;
+    /**
+     * Update a page in persistent storage.
+     * @param req the update saved page request.
+     */
     updatePage(req: UpdateSavedPageRequest): Promise<void>;
+    /**
+     * Delete a page from persistent storage.
+     * @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.
+     * @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 +206,73 @@ 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.
+     * @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: 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;
+    /** Config for overriding browser options and behavior. */
+    browser?: BrowserInitConfig;
+    /** License key for Workspace Platform. */
     licenseKey: string;
-    theme?: any;
+    /** Custom Themes object */
+    theme?: CustomThemes;
 }
+/**
+ * Callback for overriding a Workspace Platform Provider.
+ */
+export declare type BrowserOverrideCallback = OpenFin.OverrideCallback<WorkspacePlatformProvider>;
+/**
+ * Configuration for initializing a Browser.
+ */
 export interface BrowserInitConfig {
     defaultWindowOptions?: BrowserCreateWindowRequest;
     defaultViewOptions?: OpenFin.ViewOptions;
-    overrideCallback?: Partial<OpenFin.OverrideCallback<WorkspacePlatformProvider, WorkspacePlatformProvider>>;
+    overrideCallback?: BrowserOverrideCallback;
     interopOverride?: OpenFin.OverrideCallback<InteropBroker, InteropBroker>;
 }

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

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

@@ -0,0 +1,60 @@
+import type { ThemePaletteSet } from '@openfin/ui-library';
+export interface ComputedThemes extends Array<ComputedTheme> {
+}
+export interface ComputedTheme {
+    label: string;
+    logoUrl?: string;
+    theme: ThemePaletteSet;
+}
+export interface CustomThemes extends Array<CustomThemeOptions> {
+}
+export interface CustomThemeOptions {
+    label: string;
+    logoUrl?: string;
+    palette: CustomPaletteSet;
+}
+export interface DefaultPaletteSet {
+    brandPrimary: string;
+    brandSecondary: string;
+    backgroundPrimary: string;
+}
+export interface CustomPaletteSet extends DefaultPaletteSet {
+    functional1?: string;
+    functional2?: string;
+    functional3?: string;
+    functional4?: string;
+    functional5?: string;
+    functional6?: string;
+    functional7?: string;
+    functional8?: string;
+    functional9?: string;
+    functional10?: string;
+    statusSuccess?: string;
+    statusWarning?: string;
+    statusCritical?: string;
+    statusActive?: string;
+    inputBg?: string;
+    inputColor?: string;
+    inputPlaceholder?: string;
+    inputDisabled?: string;
+    inputFocused?: string;
+    textDefault?: string;
+    textHelp?: string;
+    textInactive?: string;
+    background1?: string;
+    background2?: string;
+    background3?: string;
+    background4?: string;
+    background5?: string;
+    background6?: string;
+}
+/**
+ * computeThemes()
+ * Accepts the array of registered CustomThemes objects
+ * Creates a light and dark palette from a tempalte overriding with custom options
+ * Uses createTheme to build theme object
+ * Creates a ThemePaletteSet
+ * @param customPalettes
+ * @returns theme object ready to be applied to the UI
+ */
+export declare const computeThemes: (customPalettes: CustomThemes) => ComputedThemes;

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

@@ -0,0 +1,57 @@
+import { CustomPaletteSet } from '@common/api/theming';
+/**
+ * Get hue from a CSS color
+ *
+ * The getHue function is used manage extracting hue from 3 types of css
+ * string input types. An object including hue, hsl, hsla, lightness and
+ * saturation are returned.
+ *
+ * Each function was copied css tricks and modified to fit this platform.
+ * Links above each function for technical details.
+ *
+ * Allowed formats:
+ *      RGB with or with out the alpha rgb(x,x,x) or rgba(x,x,x,x)
+ *      HEX 3 or 6 characters, plus hashtag #333 or #333333
+ *      HSL with or with out the alhpa hsl(x,x%,x%) or hsla(x,x%,x%,x)
+ *
+ * The hue value is used later to build an array of background colors in the
+ * theme that are various shades of the hue returned from this function.
+ *
+ * An invalid format should error telling the integrator how to fix the error.
+ * - Error for missing required options
+ * - Error for invalid css strings that are unable to be processed
+ *
+ * @param colorInput string - Supported formats rgb/RGB/rgba/RGBA, #000/#000000, hsl/HSL/hsla/HSLA
+ * @returns hue as string
+ */
+export declare const getHue: (colorInput: string) => string;
+export declare const makeBackgroundLayers: (hue: string) => {
+    light: {
+        background1: string;
+        background2: string;
+        background3: string;
+        background4: string;
+        background5: string;
+        background6: string;
+    };
+    dark: {
+        background1: string;
+        background2: string;
+        background3: string;
+        background4: string;
+        background5: string;
+        background6: string;
+    };
+};
+/**
+ * makePalette() - generic - doesn't care about scheme
+ *
+ * Accepts a default palette object, and a custom palette object.
+ * The default object gets overrides from customPalette and returns a new palette object.
+ * @param defaultPalette
+ * @param customPalette
+ * @returns { light: newPalette, dark: newPalette }
+ *
+ * TODO: DefaultPaletteSet isn't working, need to redo.
+ */
+export declare const makePalette: (defaultPalette: any, customPalette: CustomPaletteSet) => CustomPaletteSet;