@openfin/workspace-platform 5.3.1 → 5.6.3

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

@@ -1,6 +1,7 @@
 /**
  * Use relative paths here rather than aliases which mess
- * up the packaged typing files
+ * up the packaged typing files. When writing code examples,
+ * for documentation, please use async/await syntax over .then()!
  */
 import type { Page } from '../../common/src/api/pages/shapes';
 import type { Workspace } from '../../common/src/api/workspaces';
@@ -9,7 +10,7 @@ export type { Action, DispatchedSearchResult, SearchListenerRequest, SearchListe
 export type { Workspace } from '../../common/src/api/workspaces';
 export type { LayoutExtended, LayoutContentExtended, LayoutSettingsExtended, LayoutContentItemExtended, LayoutComponentExtended, LayoutComponentStateExtended, LayoutStack } from '../../common/src/utils/layout';
 export type { Page, PageLayout, PageLayoutDetails } from '../../common/src/api/pages/shapes';
-export { SearchTagBackground } from '../../search-api/src/index';
+export { SearchTagBackground } from '../../search-api/src/shapes';
 /**
  * Describes the type of the app directory entry `manifest` attributes.
  * Launch mechanics are determined by the manifest type.
@@ -241,22 +242,138 @@ export interface StorefrontProviderInfo {
 export interface StorefrontProvider extends StorefrontProviderInfo {
     /**
      * Get a list of apps to populate the platform's Storefront with.
+     *
+     * ```ts
+     *
+     * const app : App = {
+     *      appId: 'uid'
+     *      title: 'My App'
+     *      manifest: `https://openfin-iex.experolabs.com/openfin/manifests/cash-flow.json`,
+     *      icons: [
+     *          {
+     *              src: '/icon.png'
+     *          }
+     *      ],
+     *      contactEmail: contact@email.com,
+     *      supportEmail: support@email.com,
+     *      publisher: 'My Publisher',
+     *      tags: [],
+     *      images: [],
+     *      intents: []
+     * }
+     *
+     * const getApps = async (): Promise<App[]> => {
+     *      return [app];
+     * }
+     * ```
      */
     getApps(): Promise<App[]>;
     /**
      * Get the main landing page for the platform's Storefront.
+     *
+     * ```ts
+     *
+     * const landingPage : StorefrontLandingPage = {
+     *   hero: {
+     *      title: 'My Landing Page',
+     *      description: 'description',
+     *      cta: navigationItems[0],
+     *      image: {
+     *          src: './images/image.png'
+     *      }
+     *   },
+     *   topRow: {
+     *       title: 'Top Row Title',
+     *       items: //array of StorefrontNavigationItem
+     *   },
+     *   middleRow: {
+     *       title: 'Middle Row Title',
+     *       apps: //array of apps
+     *   },
+     *   bottomRow: {
+     *       title: 'Bottom Row Title',
+     *       items: //array of StorefrontNavigationItem
+     *   }
+     * }
+     *
+     * const getLandingPage = async (): Promise<StorefrontLandingPage> => {
+     *      return landingPage;
+     * }
+     *```
      */
     getLandingPage(): Promise<StorefrontLandingPage>;
     /**
      * Get the Storefront navigation sections for the left nav bar.
+     * ```ts
+     * const navigationSections: [StorefrontNavigationSection, StorefrontNavigationSection] = [
+     *   {
+     *       id: 'first id',
+     *       title: 'title',
+     *       items: //array of navigation items
+     *   },
+     *   {
+     *       id: 'second id'
+     *       title: 'title',
+     *       items: //array of navigation items
+     *   }
+     * ]
+     *
+     * const getNavigation = async (): Promise<[StorefrontNavigationSection, StorefrontNavigationSection]>  => {
+     *      return navigationSections;
+     * }
+     *```
      */
     getNavigation(): Promise<[StorefrontNavigationSection?, StorefrontNavigationSection?]>;
     /**
      * Get the footer for the platform's Storefront.
+     *
+     * ```ts
+     * const footer: StorefrontFooter = {
+     *      logo: { src: './images/image', size: '32' },
+     *      text: 'footer text',
+     *      links: [
+     *          { title:'title', url: 'https://openfin.co' },
+     *          { title: 'title', url: 'https://openfin.co'}
+     *      ]
+     * }
+     *
+     * const getFooter = async (): Promise<StorefrontFooter> => {
+     *      return footer;
+     * }
+     * ```
      */
     getFooter(): Promise<StorefrontFooter>;
     /**
      * Launch an app provided by the platform's Storefront.
+     *
+     * ```ts
+     * import { getStorefrontProvider } from "./my-provider";
+     *
+     * //Grab your provider
+     * const myStoreFrontProvider: StorefrontProvider = getStorefrontProvider();
+     *
+     * const app : App = {
+     *      appId: 'uid'
+     *      title: 'My App'
+     *      manifest: `https://openfin-iex.experolabs.com/openfin/manifests/cash-flow.json`,
+     *      icons: [
+     *          {
+     *              src: './image.png'
+     *          }
+     *      ],
+     *      contactEmail: contact@email.com,
+     *      supportEmail: support@email.com,
+     *      publisher: 'My Publisher',
+     *      tags: [],
+     *      images: [],
+     *      intents: []
+     * }
+     *
+     * const launch = async () => {
+     *      await myStorefrontProvider.launchApp(app);
+     * }
+     * ```
+     * @param app the app to launch.
      */
     launchApp(app: App): Promise<void>;
 }
@@ -270,12 +387,58 @@ export interface StorefrontAPI {
      * When a user selects your Storefront, the methods on the provider
      * object are called to populate the UI. Throws an error if a provider with
      * the same `id` already exists.
+     *
+     * ```ts
+     * import { Storefront, StorefrontProvider } from "@openfin/workspace";
+     *
+     * //Declare a provider
+     * const myStorefrontProvider: StorefrontProvider = {
+     *      id: "my-storefront-id"
+     *      title: "My StorefrontProvider"
+     *      icon: "https://cdn.openfin.co/demos/notifications/generator/images/icon-blue.png",
+     *      getApps: () => {...},
+     *      getNavigation: () => {...},
+     *      getLandingPage: () => {...},
+     *      getFooter: () => {...},
+     *      launchApp: () => {...}
+     * };
+     *
+     * const registerProvider = async () => {
+     *      await Storefront.register(myStorefrontProvider);
+     * }
+     * ```
      * @param provider the implementation of a Storefront provider.
 
      */
     register(provider: StorefrontProvider): Promise<void>;
     /**
      * Deregister a provider.
+     *
+     * ```ts
+     * import { Storefront, StorefrontProvider } from "@openfin/workspace";
+     *
+     * //Instantiate a StorefrontProvider
+     * const myStorefrontProvider: StorefrontProvider = {
+     *      id: "my-storefront-id"
+     *      title: "My StoreFrontProvider"
+     *      icon: "https://cdn.openfin.co/demos/notifications/generator/images/icon-blue.png",
+     *      getApps: () => {...},
+     *      getNavigation: () => {...},
+     *      getLandingPage: () => {...},
+     *      getFooter: () => {...},
+     *      launchApp: () => {...}
+     * };
+     *
+     * const register = async () => {
+     *      await Storefront.register(myStorefrontProvider);
+     * }
+     *
+     * //Do work with myStorefrontProvider
+     *
+     * const deregister = async () => {
+     *      await Storefront.deregister("my-storefront-id");
+     * }
+     * ```
      * @param id the id of the provider.
      */
     deregister(id: string): Promise<void>;
@@ -283,12 +446,30 @@ export interface StorefrontAPI {
      * Shows the Storefront window. Awaits for the latest [[`Storefront.register()`]]
      * internally, so you don't have to. Throws an error if a [[StorefrontProvider]]
      * doesn't exist (i.e., because `register()` not called previously).
+     *
+     * ```ts
+     * import { Storefront } from "@openfin/workspace";
+     *
+     * const show = async () => {
+     *      await Storefront.show();
+     *      //Do thing after show
+     * }
+     * ```
      */
     show(): Promise<void>;
     /**
      * Hides the Storefront window. Awaits for the latest [[`Storefront.register()`]]
      * internally, so you don't have to. Throws an error if a [[StorefrontProvider]]
      * doesn't exist (i.e., because `register()` was not called previously).
+     *
+     * ```ts
+     * import { Storefront } from "@openfin/workspace";
+     *
+     * const hide = async () => {
+     *      await Storefront.hidef();
+     *      //Do thing after show
+     * }
+     * ```
      */
     hide(): Promise<void>;
 }
@@ -524,6 +705,20 @@ export declare type CLIDispatchedSearchResult = DispatchedSearchResult;
 export interface CLIProvider extends SearchProvider {
     /**
      * Function that is called when a search request is triggered due to user input.
+     *
+     * ```ts
+     *
+     * import { getAllData, getResultsByQuery } from './get-all-data';
+     *
+     * const onUserInput = async({ query }): Promise<CLISearchResponse> => {
+     *      if (!query) {
+     *          return getAllData();
+     *      }
+     *
+     *      // Provide an implmentation to fetch query-filtered search results
+     *      return getResultsByQuery(query);
+     * }
+     * ```
      * @param req describes search request.
      * @param res can be used to stream search results back to the requesting Workspace component.
      * @returns an object that contains the search results to render in the requesting Workspace component.
@@ -532,6 +727,26 @@ export interface CLIProvider extends SearchProvider {
     /**
      * Callback that is invoked when ever a search result returned by this provider
      * is interacted with from a Workspace component. (clicked, pressed enter, hotkey pressed, etc.)
+     *
+     *
+     * ```ts
+     * import { getAvailableCommands } from './my-commands';
+     *
+     * const onResultDispatch = async(result: CLIDispatchedSearchResult): Promise<void> => {
+     *      try {
+     *          //Grab the command corresponding to the result
+     *          const availableCommands = await getAvailableCommands();
+     *          const commandToExecute = availableCommands.find((command) => command.key === result.key);
+     *
+     *          if (commantToExecute != undefined) {
+     *              await commandToExecute.action();
+     *          }
+     *      } catch (err) {
+     *          //Handle the error
+     *          log.error('Error trying to action show command %s', err, result.key);
+     *      }
+     *  }
+     *```
      * @param result the search result with the action that was selected by the user.
      */
     onResultDispatch?(result: CLIDispatchedSearchResult): Promise<void>;
@@ -562,7 +777,9 @@ export interface HomeAPI {
      *      onUserInput: (req) => fetchMySearchResults(req.query)
      * };
      *
-     * Home.register(myCLIProvider);
+     * const register = async () => {
+     *      await Home.register(myCLIProvider);
+     * }
      * ```
      *
      * @param provider the provider implementation.
@@ -570,15 +787,52 @@ export interface HomeAPI {
     register(provider: HomeProvider | CLIProvider): Promise<void>;
     /**
      * Deregister a provider.
+     *
+     * ```ts
+     * import { Home , CLIProvider } from "@openfin/workspace";
+     *
+     * import { fetchMySearchResults } from "./my-fetch-implementation";
+     *
+     * const myCLIProvider: CLIProvider = {
+     *      name: "my-cli-provider",
+     *      title: "My CLI Provider",
+     *      icon: "https://google.com/favicon.ico",
+     *      onUserInput: (req) => fetchMySearchResults(req.query)
+     * };
+     *
+     * // Register and do some work with the provider
+     *
+     * const deregister = async () => {
+     *      await Home.deregister("my-cli-provider");
+     * }
+     * ```
      * @param providerId the name of the provider.
      */
     deregister(providerId: string): Promise<void>;
     /**
      * Show the Home UI.
+     *
+     * ```ts
+     * import { Home } from './home'
+     *
+     * const show = async () => {
+     *      await Home.show();
+     *      // Do thing after show
+     * }
+     * ```
      */
     show(): Promise<void>;
     /**
      * Hide the Home UI.
+     *
+     * ```ts
+     * import { Home } from './home'
+     *
+     * const hide = async () => {
+     *      await Home.hide();
+     *      // Do thing after hide
+     * }
+     * ```
      */
     hide(): Promise<void>;
 }
@@ -588,10 +842,32 @@ export interface HomeAPI {
 export interface LegacyAPI {
     /**
      * Get the pages that a user had saved in a legacy version of Workspace. (pre 5.0.0)
+     *
+     * ```ts
+     * import { Legacy } from "@openfin/workspace";
+     *
+     * async logPages() {
+     *      const pages = await Legacy.getPages();
+     *      console.log(pages);
+     * }
+     *
+     * logPages();
+     * ```
      */
     getPages(): Promise<Page[]>;
     /**
      * Get the workspaces that a user had saved in a legacy version of Workspace. (pre 5.0.0)
+     *
+     * ```ts
+     * import { Legacy } from "@openfin/workspace";
+     *
+     * async logWorkspaces() {
+     *      const workspaces = await Legacy.getWorkspaces();
+     *      console.log(workspaces);
+     * }
+     *
+     * logWorkspaces();
+     * ```
      */
     getWorkspaces(): Promise<Workspace[]>;
 }

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

@@ -1,5 +1,6 @@
 /// <reference types="openfin-adapter/fin" />
 import type { AttachedPage, Page, PageWithUpdatableRuntimeAttribs } from '../../../../common/src/api/pages/shapes';
+import { OpenGlobalContextMenuRequest } from '../../../../client-api-platform/src/shapes';
 export declare const getBrowserModule: (identity: OpenFin.Identity) => {
     identity: OpenFin.Identity;
     openfinWindow: import("openfin-adapter").Window;
@@ -10,4 +11,5 @@ export declare const getBrowserModule: (identity: OpenFin.Identity) => {
     setActivePage: (id: Page['pageId']) => Promise<void>;
     updatePage: (req: any) => Promise<any>;
     reorderPages: (req: any) => Promise<any>;
+    _openGlobalContextMenu: (req: OpenGlobalContextMenuRequest) => Promise<any>;
 };

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

@@ -12,6 +12,7 @@ export declare const getBrowserApi: (identity: OpenFin.ApplicationIdentity) => {
         setActivePage: (id: string) => Promise<void>;
         updatePage: (req: any) => Promise<any>;
         reorderPages: (req: any) => Promise<any>;
+        _openGlobalContextMenu: (req: import("../../shapes").OpenGlobalContextMenuRequest) => Promise<any>;
     };
     createWindow: (options: BrowserCreateWindowRequest) => Promise<BrowserWindowModule>;
     getAllAttachedPages: () => Promise<AttachedPage[]>;

package/client-api-platform/src/api/context-menu/browser-logo-handler.d.ts

@@ -0,0 +1,10 @@
+import { NamedIdentity } from 'openfin-adapter/src/identity';
+export declare enum MenuData {
+    NewWindow = "NEW_WINDOW",
+    NewPage = "NEW_PAGE",
+    CloseWindow = "CLOSE_WINDOW",
+    OpenStorefront = "OPEN_STOREFRONT",
+    Quit = "QUIT"
+}
+declare const handler: (winIdentity: NamedIdentity, data: MenuData) => Promise<void>;
+export default handler;

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

@@ -0,0 +1,6 @@
+import { NamedIdentity } from 'openfin-adapter/src/identity';
+import { OpenGlobalContextMenuPayload, OpenGlobalContextMenuRequest } from '../../../../client-api-platform/src/shapes';
+export declare function openGlobalContextMenuInternal(payload: OpenGlobalContextMenuRequest & {
+    identity: NamedIdentity;
+}, callerIdentity: any): Promise<void>;
+export declare const openGlobalContextMenu: (payload: OpenGlobalContextMenuPayload, callerIdentity: any) => Promise<void>;

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

@@ -4,7 +4,7 @@
  * a Workspace Platform's address space.
  *
  * When adding a new channel action make sure to add a function that's name matches
- * the value of the enum for the remote procedure in the Workspace Platform overrides.
+ * the value of the enum for the remote procedure in the Workspace Platform overrides and the override-callback.
  * All of the registered channel action handlers can be found here in the platform's overrides:
  * @see link: [Provider Protocol Handlers](https://github.com/openfin/workspace/client-api-platform/src/init/override-callback.ts)
  */
@@ -33,7 +33,9 @@ export declare enum ChannelAction {
     GetSavedPageMetadata = "getSavedPageMetadata",
     GetUniquePageTitle = "getUniquePageTitle",
     GetLastFocusedBrowserWindow = "getLastFocusedBrowserWindow",
-    GetThemes = "getThemes"
+    GetThemes = "getThemes",
+    OpenGlobalContextMenuInternal = "openGlobalContextMenuInternal",
+    InvokeCustomActionInternal = "invokeCustomActionInternal"
 }
 /**
  * Get a channel client for a specific Workspace platform.

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

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

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

@@ -10,28 +10,28 @@ export * from './shapes';
  * const customThemes: WorkspacePlatform.CustomThemes = [{
  *   label: "OpenFin's Custom Theme",
  *   palette: {
- *      brandPrimary: '#F51F63, // required
- *      brandSecondary: '#1FF58A', // required
- *      backgroundPrimary: '#F8E71C', // required - hex, rgb/rgba, hsl/hsla only - no string colors: 'red'
- *      background2: '#7D808A' // any of the optional colors
+ *      // Required color options
+ *      brandPrimary: '#F51F63',
+ *      brandSecondary: '#1FF58A',
+ *      backgroundPrimary: '#F8E71C', // hex, rgb/rgba, hsl/hsla only - no string colors: 'red'
  *   }
  * }
  *
  * const overrideCallback: WorkspacePlatform.BrowserOverrideCallback = async (
- *    WorkspacePlatformProvider
- * ) => {
+ *     WorkspacePlatformProvider
+ *   ) => {
  *   class Override extends WorkspacePlatformProvider {
- *       async quit(payload, callerIdentity) {
- *           return super.quit(payload, callerIdentity);
- *       }
+ *     async quit(payload, callerIdentity) {
+ *       return super.quit(payload, callerIdentity);
+ *     }
  *   }
  *   return new Override();
  * };
  *
  *
  * await WorkspacePlatform.init({
- *  browser: { overrideCallback },
- *  theme: customThemes
+ *   browser: { overrideCallback },
+ *   theme: customThemes
  * });
  * ```
  * @param options options for configuring the platform.

package/client-api-platform/src/init/custom-actions.d.ts

@@ -0,0 +1,3 @@
+import { CustomActionsMap, InvokeCustomActionRequest } from '..';
+export declare const initCustomActions: (actions: CustomActionsMap) => void;
+export declare const invokeCustomActionInternal: ({ actionId, payload }: InvokeCustomActionRequest) => any;

package/client-api-platform/src/init/override-callback.d.ts

@@ -1,3 +1,4 @@
 /// <reference types="openfin-adapter/fin" />
 import type { BrowserInitConfig } from '../../../client-api-platform/src/shapes';
-export declare const getOverrideCallback: (initOptions: BrowserInitConfig) => OpenFin.OverrideCallback<OpenFin.PlatformProvider>;
+import { WorkspacePlatformProvider } from '..';
+export declare const getOverrideCallback: (initOptions: BrowserInitConfig) => OpenFin.OverrideCallback<WorkspacePlatformProvider>;

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

@@ -1,7 +1,8 @@
 /// <reference types="openfin-adapter/fin" />
 import { Identity } from 'openfin-adapter';
+import type { CustomThemeOptions } from '../../../common/src/api/theming';
 import { BrowserCreateWindowRequest } from '..';
-export declare function overrideViewOptions(options: Partial<OpenFin.ViewOptions>, initOptions: OpenFin.ViewOptions): OpenFin.ViewOptions & Partial<OpenFin.ViewOptions>;
+export declare function overrideViewOptions(options: Partial<OpenFin.ViewOptions>, initOptions: OpenFin.ViewOptions): any;
 export declare function preserveInteropIfManifestConflict(opts: Partial<OpenFin.ViewOptions>, fetchManifest: ({ manifestUrl: string }: {
     manifestUrl: any;
 }, callerIdentity: Identity) => any, callerIdentity: Identity): Promise<any>;
@@ -40,5 +41,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, initOptions: BrowserCreateWindowRequest) => OpenFin.PlatformWindowCreationOptions;
+export declare const applyBrowserDefaults: (options: OpenFin.PlatformWindowCreationOptions, initOptions: BrowserCreateWindowRequest, theme: CustomThemeOptions) => OpenFin.PlatformWindowCreationOptions;
 export {};