@openfin/workspace-platform 11.0.6 → 12.1.0

package/README.md

@@ -9,7 +9,7 @@ Run `npm i -E @openfin/workspace-platform`.
 ## Workspace Platform API documentation
 
 -   [Overview](https://developers.openfin.co/of-docs/docs/workspace-sdk)
--   [API Reference](https://cdn.openfin.co/workspace/docs/platform/latest/index.html)
+-   [API Reference](https://workspace.openfin.co/workspace/docs/platform/latest/index.html)
 -   [Example projects using Workspace Platform](https://github.com/built-on-openfin/workspace-starter)
 
 ## Code examples

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

@@ -5,6 +5,21 @@ export * from './shapes/dock';
  * Registers a Dock provider
  * @returns promise - invokes action
  * ```ts
+ * const provider: DockProvider = {
+ *      id: 'provider-id',
+ *      title: 'Sample Dock',
+ *      icon: 'https://www.openfin.co/favicon-32x32.png',
+ *      buttons: [
+ *           {
+ *              tooltip: 'Sample Button 1',
+ *              iconUrl: 'https://www.openfin.co/favicon-32x32.png',
+ *               action: {
+ *                   id: 'sampleButton1'
+ *               }
+ *           }
+ *       ]
+ * };
+ *
  * await Dock.register(provider)
  * ```
  */

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

@@ -39,7 +39,7 @@ export interface WorkspaceComponentButtonOptions {
  * A dropdown button presents a list of options the user can choose from.
  * An action button initiates a single task or action only.
  */
-export declare enum DockButtonNames {
+export declare const enum DockButtonNames {
     ActionButton = "ActionButton",
     DropdownButton = "DropdownButton"
 }

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

@@ -315,6 +315,35 @@ export interface CLIProvider extends SearchProvider {
 /**
  * A CLI provider responds to search requests from Home UI.
  * Exposes search features that are specifically supported by Home.
+ *
+ * <h3>Sample HomeProvider definition.</h3>
+ *
+ * Import required dependencies.
+ * ```ts
+ * import { Home, HomeProvider } from '@openfin/workspace';
+ * ```
+ *
+ * Create provider object to configure `Home`.
+ *
+ * ```ts
+ * const provider: HomeProvider = {
+ *   id: 'provider-id',
+ *   title: 'Sample Home',
+ *   icon: 'https://www.openfin.co/favicon-32x32.png',
+ *   description: 'A short description of the Search Provider.',
+ *   onResultDispatch: () => { } // Handle Result Dispatch
+ *   onUserInput: () => { } // Handle User Input
+ * };
+ * ```
+ *
+ * Register home ``provider`` object.
+ * ```ts
+ * await Home.register(provider);
+ * ```
+ * Show Home.
+ * ```ts
+ * await Home.show();
+ * ```
  */
 export interface HomeProvider extends CLIProvider {
     onUserInput(req: HomeSearchListenerRequest, res: HomeSearchListenerResponse): Promise<HomeSearchResponse>;
@@ -328,7 +357,7 @@ export interface SearchQueryWithProviderID {
     query: string;
 }
 /**
- * Reponse from home registration which includes metadata and a function to inject search string into home search
+ * Response from home registration which includes metadata and a function to inject search string into home search
  */
 export interface HomeRegistration extends RegistrationMetaInfo {
     /**

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

@@ -3,6 +3,7 @@
  * up the packaged typing files. When writing code examples,
  * for documentation, please use async/await syntax over .then()!
  */
+import { UpdateButtonConfigRequest } from '../../../client-api/src/store';
 import { CustomButtonConfig, RegistrationMetaInfo } from './common';
 import { ProviderInfo } from './provider';
 /**
@@ -225,6 +226,31 @@ export interface StorefrontNavigationItemAppGrid extends StorefrontNavigationIte
      */
     templateData: StorefrontAppGrid;
 }
+/**
+ * Response from store registration which includes metadata and a function to update app cards buttons.
+ */
+export interface StoreRegistration extends RegistrationMetaInfo {
+    /**
+     * Function to updates app card button config.
+     * @example Updating primary button title and disabled flag.
+     * @param request object that contains primary button and secondary buttons configs that will be
+     * used to update button configuration returned by provider for an app.
+     *
+     * ```ts
+     *  registration = await Store.register(provider);
+     *  registration.updateAppCardButtons({
+     *    appId: request.payload.appId,
+     *    primaryButton: {
+     *        ...request.payload.sourcePrimaryButton,
+     *        title: "Primary button is now disabled",
+     *        disabled: true
+     *    },
+     *    secondaryButtons: request.payload.sourceSecondaryButtons
+     *  });
+     * ```
+     */
+    updateAppCardButtons: (request: UpdateButtonConfigRequest) => Promise<void>;
+}
 /**
  * Template for rendering a navigation item that renders another landing page when clicked.
  */
@@ -248,6 +274,33 @@ export interface StorefrontProviderInfo extends ProviderInfo {
 /**
  * Describes a Storefront provided by a platform.
  * A platform must provide an object that satisfies this interface in order to register with the Storefront.
+ *
+ * <h3>Sample StorefrontProvider definition.</h3>
+ *
+ * Import required dependencies.
+ * ```ts
+ * import { Storefront, StorefrontProvider } from '@openfin/workspace';
+ * ```
+ *
+ * Create provider object to configure `Storefront`.
+ *
+ * ```ts
+ * const provider: StorefrontProvider = {
+ *   id: 'provider-id',
+ *   title: 'Sample Storefront',
+ *   icon: 'https://www.openfin.co/favicon-32x32.png',
+ *   getApps: () => { }, // Get apps to populate the platform's storefront
+ *   getNavigation: () => {...}, // Get navigation selections for the left nav bar
+ *   getLandingPage: () => {...}, // Get main landing page for platform's storefront
+ *   getFooter: () => {...}, // Get footer for the platform's storefront
+ *   launchApp: () => {...}, // Launch an app provided by the platform's storefront
+ * };
+ * ```
+ *
+ * Register storefront ``provider`` object.
+ * ```ts
+ * await Storefront.register(provider);
+ * ```
  */
 export interface StorefrontProvider extends StorefrontProviderInfo {
     /**
@@ -314,6 +367,7 @@ export interface StorefrontProvider extends StorefrontProviderInfo {
     getLandingPage(): Promise<StorefrontLandingPage>;
     /**
      * Get the Storefront navigation sections for the left nav bar.
+     *
      * ```ts
      * const navigationSections: [StorefrontNavigationSection, StorefrontNavigationSection] = [
      *   {
@@ -426,7 +480,7 @@ export interface StorefrontAPI {
    */
     register(provider: StorefrontProvider): Promise<RegistrationMetaInfo>;
     /**
-     * Deregister a provider.
+     * Deregister a [[StorefrontProvider]].
      *
      * ```ts
      * import { Storefront, StorefrontProvider } from "@openfin/workspace";

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

@@ -1,10 +1,15 @@
-import type { StorefrontProvider } from './shapes/store';
+import type { StorefrontProvider, StoreRegistration } from './shapes/store';
 export * from './shapes/store';
-import type { RegistrationMetaInfo } from '../../client-api/src/shapes';
+import { StoreButtonConfig } from './shapes/store';
 /**
  * Registers a Storefront provider
  */
-export declare const register: (provider: StorefrontProvider) => Promise<RegistrationMetaInfo>;
+export declare const register: (provider: StorefrontProvider) => Promise<StoreRegistration>;
+export interface UpdateButtonConfigRequest {
+    appId: string;
+    primaryButton: StoreButtonConfig;
+    secondaryButtons: StoreButtonConfig[];
+}
 /**
  * Deregister a Storefront provider
  */

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

@@ -1,4 +1,47 @@
 import type OpenFin from '@openfin/core';
 import { WorkspacePlatformModule } from '../shapes';
+/**
+ * Synchronously returns a Platform object that represents an existing platform.
+ *
+ * ```ts
+ * import * as WorkspacePlatform from '@openfin/workspace-platform';
+ *
+ * // declare platform identity
+ * const myPlatformIdentity: OpenFin.ApplicationIdentity = {
+ *      uuid: 'testPlatform',
+ *      name: 'Test Platform'
+ * };
+ *
+ * // get the platform representing myPlatformIdentity
+ * const platform = WorkspacePlatform.wrapSync(myPlatformIdentity);
+ *
+ * // do something with platform. e.g. create a window
+ * platform.createWindow({
+ *      layout: {
+ *          content: [
+ *              {
+ *                  type: 'component',
+ *                  componentName: 'Example View',
+ *                  componentState: {
+ *                      name: 'example_view_1'
+ *                      url: 'https://cdn.openfin.co/docs/javascript/canary/Platform.html'
+ *                  }
+ *              }
+ *          ]
+ *      }
+ * });
+ * ```
+ */
 export declare const wrapSync: (identity: OpenFin.ApplicationIdentity) => WorkspacePlatformModule;
+/**
+ * Synchronously returns a Platform object that represents the current platform.
+ *
+ * ```ts
+ * import * as WorkspacePlatform from '@openfin/workspace-platform';
+ * // get current Workspace Platform
+ * const workspacePlatform = WorkspacePlatform.getCurrentSync();
+ * // do something with workspacePlatform. e.g. get snapshot of browser window with pages
+ * const snapshot = await workspacePlatform.getSnapshot();
+ * ```
+ */
 export declare const getCurrentSync: () => WorkspacePlatformModule;

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

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

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

@@ -13,7 +13,7 @@ import type { WorkspacePlatformInitConfig } from '../shapes';
  *      brandSecondary: '#1FF58A',
  *      backgroundPrimary: '#F8E71C', // hex, rgb/rgba, hsl/hsla only - no string colors: 'red'
  *   }
- * }
+ * }];
  *
  * const overrideCallback: WorkspacePlatform.WorkspacePlatformOverrideCallback = async (
  *     WorkspacePlatformProvider

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

@@ -4,7 +4,7 @@ import type { AnalyticsEvent } from '../../common/src/utils/usage-register';
 import { CustomActionSpecifier, CustomButtonConfig } from '../../common/src/api/action';
 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';
+import type { App, StoreButtonConfig } from '../../client-api/src/shapes';
 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';
@@ -73,7 +73,7 @@ export declare enum GlobalContextMenuOptionType {
 /**
  * Types of color scheme.
  */
-export declare enum ColorSchemeOptionType {
+export declare const enum ColorSchemeOptionType {
     Light = "light",
     Dark = "dark",
     System = "system"
@@ -298,9 +298,9 @@ export interface StoreCustomButtonActionPayload extends Omit<CustomButtonActionP
      * Invoking application id.
      */
     appId: string;
-    /**
-     * callerType - StoreCustomButton type.
-     */
+    sourceButtonConfig: StoreButtonConfig;
+    secondaryButtons: StoreButtonConfig[];
+    primaryButton: StoreButtonConfig;
     callerType: CustomActionCallerType.StoreCustomButton;
     storeFrontProviderId: string;
 }
@@ -1093,6 +1093,7 @@ export interface WorkspacePlatformModule extends OpenFin.Platform {
     getSnapshot(): Promise<BrowserSnapshot>;
     /**
      * Launch an application.
+     *
      * ```ts
      * import * as WorkspacePlatform from '@openfin/workspace-platform';
      *
@@ -1380,6 +1381,11 @@ export interface WorkspacePlatformInitConfig {
  *
  *       // add a custom menu item in View Tab Context Menu
  *       openViewTabContextMenu = async (payload: OpenViewTabContextMenuPayload, callerIdentity) => {
+ *           const viewsInfo = await Promise.all(payload.selectedViews.map(async (v) => fin.View.wrapSync(v).getInfo()));
+ *
+ *           const enableBack = viewsInfo.every((viewInfo) => viewInfo.canNavigateBack === true);
+ *           const enableForward = viewsInfo.every((viewInfo) => viewInfo.canNavigateForward === true);
+ *
  *           return super.openViewTabContextMenu({
  *               ...payload,
  *               template: [
@@ -1394,68 +1400,51 @@ export interface WorkspacePlatformInitConfig {
  *                           }
  *                       }
  *                   },
- *                   ...payload.template
- *               ]
- *           }, callerIdentity);
- *       };
- *
- *       // add a custom menu item (forward/back) in View Tab Context Menu
- *       openViewTabContextMenu = async (payload: OpenViewTabContextMenuPayload, callerIdentity) => {
- *           const viewsInfo = await Promise.all(payload.selectedViews.map(async (v) => fin.View.wrapSync(v).getInfo()));
- *
- *           const enableBack = viewsInfo.every((viewInfo) => viewInfo.canNavigateBack === true);
- *           const enableForward = viewsInfo.every((viewInfo) => viewInfo.canNavigateForward === true);
- *
- *
- *           return super.openViewTabContextMenu({
- *               ...payload,
- *               template: [
- *                  {
+ *                   {
  *                      type: 'normal',
  *                      label: 'Back',
  *                      data: {
  *                          type: ViewTabMenuOptionType.Back
  *                      },
  *                      enabled: enableBack
- *                  },
- *                  {
+ *                   },
+ *                   {
  *                      type: 'normal',
  *                      label: 'Forward',
  *                      data: {
  *                          type: ViewTabMenuOptionType.Forward
  *                      },
  *                      enabled: enableForward
- *                  },
- *                  ...payload.template
+ *                   },
+ *                   ...payload.template
  *               ]
  *           }, callerIdentity);
  *       };
  *
  *       // add a custom menu item in Save Context Menu
- *         openSaveButtonContextMenu = (req: WorkspacePlatform.OpenSaveButtonContextMenuPayload, callerIdentity: OpenFin.Identity) => {
- *           return super.openSaveButtonContextMenu(
- *               {
- *                   ...req,
- *                   template: [
- *                       ...req.template,
- *                       {
- *                           label: 'Save custom option',
- *                           data: {
- *                               type: SaveButtonContextMenuOptionType.Custom,
- *                               action: {
- *                                   id: 'sample-custom-action-name',
- *                                   customData: {
- *                                       someProp: 'Save Button task'
- *                                   }
- *                               }
- *                           }
- *                       }
- *                   ]
- *               },
- *               callerIdentity
- *              );
- *          }
- *      }
+ *       openSaveButtonContextMenu = (req: WorkspacePlatform.OpenSaveButtonContextMenuPayload, callerIdentity: OpenFin.Identity) => {
+ *         return super.openSaveButtonContextMenu(
+ *             {
+ *                 ...req,
+ *                 template: [
+ *                     ...req.template,
+ *                     {
+ *                         label: 'Save custom option',
+ *                         data: {
+ *                             type: SaveButtonContextMenuOptionType.Custom,
+ *                             action: {
+ *                                 id: 'sample-custom-action-name',
+ *                                 customData: {
+ *                                     someProp: 'Save Button task'
+ *                                 }
+ *                             }
+ *                         }
+ *                     }
+ *                 ]
+ *             },
+ *             callerIdentity
+ *            );
+ *        }
  *   }
  *   return new Override();
  * };
@@ -1483,7 +1472,7 @@ export declare type WorkspacePlatformOverrideCallback = OpenFin.OverrideCallback
  * @deprecated
  */
 export declare type BrowserOverrideCallback = WorkspacePlatformOverrideCallback;
-/**`
+/**
  * Configuration for initializing a Browser.
  */
 export interface BrowserInitConfig {

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

@@ -22,12 +22,12 @@ export declare enum WorkspaceChannelAction {
     GetStorefrontProviderFooter = "get-storefront-provider-footer",
     GetStorefrontProviderNavigation = "get-storefront-provider-navigation",
     LaunchStorefrontProviderApp = "launch-storefront-provider-app",
+    UpdateAppCardButtonConfig = "update-app-card-button-config",
     ShowHome = "show-home",
     HideHome = "hide-home",
     AssignHomeSearchContext = "assign-home-search-context",
     SetSearchQuery = "set-search-query",
     OpenHomeAndSetSearchQuery = "open-home-and-set-search-query",
-    SetStoreButtonState = "set-store-button-state",
     GetLegacyPages = "get-legacy-pages",
     GetLegacyWorkspaces = "get-legacy-workspaces",
     GetComputedPlatformTheme = "get-computed-platform-theme",

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

@@ -16,6 +16,5 @@ export interface SearchItem {
     requestReload?: () => any;
 }
 export declare type Topic = typeof homeSearchTopic;
-export declare function waitForSearchRegistration(): Promise<void>;
 export declare function getTopic(topic: Topic): Promise<SearchTopicClient>;
 export declare function mapSearchResponsesToItems(topic: Topic, responses: SearchProviderResponse[]): SearchItem[];

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

@@ -4,7 +4,8 @@ export declare enum ApplicationUUID {
      * The UUID of workspace.
      * Home is a part of this application.
      */
-    Workspace = "openfin-browser"
+    Workspace = "openfin-workspace",
+    OldWorkspace = "openfin-browser"
 }
 export interface ApplicationEvent {
     viewIdentity?: OpenFin.Identity;
@@ -12,12 +13,6 @@ export interface ApplicationEvent {
     uuid?: string;
 }
 export declare type ApplicationListener = (ev: ApplicationEvent) => void;
-export declare enum ApplicationEventType {
-    RunRequested = "run-requested",
-    WindowOptionsChanged = "window-options-changed",
-    WindowClosed = "window-closed",
-    WindowCreated = "window-created"
-}
 export declare enum LaunchModeType {
     FinProtocol = "fin-protocol"
 }

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

@@ -10,26 +10,6 @@ export declare enum WindowName {
     BrowserWindow = "internal-generated-window",
     ClassicWindow = "internal-generated-classic-window"
 }
-export declare enum WindowEvent {
-    Shown = "shown",
-    BoundsChanged = "bounds-changed",
-    LayoutReady = "layout-ready",
-    EndUserBoundsChanging = "end-user-bounds-changing",
-    Blurred = "blurred",
-    Closed = "closed",
-    CloseRequested = "close-requested",
-    Focused = "focused",
-    ShowRequested = "show-requested",
-    ViewCrashed = "view-crashed",
-    ViewAttached = "view-attached",
-    ViewDetached = "view-detached",
-    ViewPageTitleUpdated = "view-page-title-updated",
-    ViewDestroyed = "view-destroyed",
-    OptionsChanged = "options-changed"
-}
-export declare enum WebWindowEvent {
-    BeforeUnload = "beforeunload"
-}
 export interface WindowIdentity {
     uuid: ApplicationUUID | string;
     name: WindowName | string;