@openfin/workspace 11.0.1 → 11.0.2

package/README.md

@@ -1,124 +1,160 @@
-# Workspace Client API
+# OpenFin Workspace Client API
 
-The Workspace Client APIs enable custom integrations with OpenFin Workspace. They can
-be used in _any_ and _only_ OpenFin apps.
+The Workspace Client APIs enable custom integrations with OpenFin Workspace.
 
-The Storefront API is the first Client API created.
+## Prerequisites
 
-**This API is [experimental](https://developers.openfin.co/of-docs/docs/experimental-apis).**
+-   [Node.js](https://nodejs.org/en/) v16.0.0 or higher
+-   [npm](https://www.npmjs.com/)
 
-## Installation
+## Install
 
-Run `npm i -E @openfin/workspace`.
+With npm:
 
-## Storefront API documentation
+```
+$ npm i @openfin/workspace@latest
+```
 
--   [Overview](https://developers.openfin.co/of-docs/doc/)
--   [API Reference](https://cdn.openfin.co/workspace/docs/api/interfaces/StorefrontAPI.html)
+With yarn:
 
-## Code examples
+```
+$ yarn global add @openfin/workspace
+```
 
-### Vanilla JS
+## Usage and Code Samples
 
-```typescript
-import { Storefront, launchApp } from '@openfin/workspace';
-import { fetchMyApps, fetchMyLandingPage, fetchMyNavigation, fetchMyFooter } from './my-storefront-provider';
+Prior to using Workspace, a Workspace Platform must be initialized.
 
-Storefront.register({
-    id: 'my-storefront',
-    title: 'My Storefront',
-    getApps: fetchMyApps,
-    getLandingPage: fetchMyLandingPage,
-    getNavigation: fetchMyNavigation,
-    getFooter: fetchMyFooter,
-    launchApp: launchApp // OpenFin's default implementation of launchApp, you can also define your own
-});
+### Home API
 
-document.getElementById('show-btn').addEventListener('click', () => {
-    Storefront.show();
-});
+-   [Overview](https://developers.openfin.co/of-docs/docs/cli-providers)
+-   [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/home.html)
 
-document.getElementById('hide-btn').addEventListener('click', () => {
-    Storefront.hide();
-});
-```
+```ts
+import Home, CLIProvider from '@openfin/workspace';
 
-### React
-
-```typescript
-import { Storefront, launchApp } from '@openfin/workspace';
-import { fetchMyApps, fetchMyLandingPage, fetchMyNavigation, fetchMyFooter } from './my-storefront-provider';
-import React, { useEffect } from 'react';
-
-const App = () => {
-    useEffect(() => {
-        Storefront.register({
-            id: 'my-storefront',
-            title: 'My Storefront',
-            getApps: fetchMyApps,
-            getLandingPage: fetchMyLandingPage,
-            getNavigation: fetchMyNavigation,
-            getFooter: fetchMyFooter,
-            launchApp: launchApp // OpenFin's default implementation of launchApp, you can also define your own
-        });
-    }, []);
-
-    return (
-        <>
-            <button onClick={Storefront.show}>Show Store</button>
-            <button onClick={Storefront.hide}>Hide Store</button>
-        </>
-    );
+import { fetchMySearchResults } from "./my-fetch-implementation";
+
+const searchQueryMap: Map<string, (query: string) => void> = new Map();
+
+// CLIProvider or HomeProvider
+const myCLIProvider: CLIProvider = {
+     id: "my-cli-provider",
+     title: "My CLI Provider",
+     icon: "https://google.com/favicon.ico",
+     onUserInput: (req) => fetchMySearchResults(req.query)
 };
+
+// register home and get back a function to inject search string into home search
+const { setSearchQuery } = await Home.register(myCLIProvider);
+
+// Store set query function in a map if you're using multiple providers
+searchQueryMap.set(myCLIProvider.id, setSearchQuery);
+
+// Call the set query function for a specific provider the search should be injected into
+const searchButton = document.createElement('button');
+searchButton.innerHTML = 'Search';
+document.body.appendChild(searchButton);
+
+searchButton.addEventListener('click', () => {
+       searchQueryMap.get('my-cli-provider')('my search string');
+});
+
 ```
 
-## Home API
+### Storefront API
+
+-   [Overview](https://developers.openfin.co/of-docs/docs/provide-storefront-content)
+-   [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/store.html)
 
-API Reference: https://cdn.openfin.co/workspace/docs/api/interfaces/HomeAPI.html
+```ts
+import { Storefront, StorefrontProvider } from "@openfin/workspace";
 
-### `register(provider: HomeProvider): Promise<void>`
+// Declare a storefront provider
+const provider: 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: () => {...}
+    };
+```
 
-Registers a Home provider. Upon registering a provider, the search results from your provider will be rendered inside Home. See API reference for details which view each topic maps too. Throws an error if provider with `provider.id` already exists. See [reference](https://cdn.openfin.co/workspace/docs/api/interfaces/HomeProvider.html) for definition of `HomeProvider` interface.
+Register Storefront `provider` object.
 
-### Vanilla JS Example
+```ts
+await Storefront.register(myStorefrontProvider);
+```
 
-```typescript
-import { Home, HomeActionName, HomeSearchTemplate } from '@openfin/workspace';
-import { fetchMyLongRunningQueryResults, executeMyAction } from './my-provider';
+Show Storefront.
 
-const onUserInput = ({ query, context }) => {
-    // If the current search was triggered from the user selecting a suggestion, execute a expensive query.
-    if (context.isSuggestion) {
-        return { results: fetchMyLongRunningQueryResults() };
-    }
+```ts
+await Storefront.show();
+```
 
-    // Otherwise, return a cheap suggestion.
-    // You can use the `Suggestion` action that is built into the Home UI.
-    return {
-        results: [
-            {
-                key: '0',
-                template: HomeSearchTemplate.Plain,
-                title: `Search my home provider for ${query}`,
-                actions: [{ name: HomeActionName.Suggestion, query }]
+### Dock API
+
+-   [Overview](https://developers.openfin.co/of-docs/docs/dock-overview)
+-   [API Reference](https://developer.openfin.co/workspace/docs/api/latest/modules/dock.html)
+
+```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'
             }
-        ]
-    };
+        },
+        {
+            type: DockButtonNames.DropdownButton,
+            tooltip: 'Sample Dropdown Button',
+            iconUrl: 'https://www.openfin.co/favicon-32x32.png',
+            options: [
+                {
+                    tooltip: 'Dropdown Button 1',
+                    iconUrl: 'https://www.openfin.co/favicon-32x32.png',
+                    action: {
+                        id: 'dropdownButton1',
+                        customData: 'dropdownButton1 clicked'
+                    }
+                },
+                {
+                    tooltip: 'Dropdown Button 2',
+                    iconUrl: 'https://www.openfin.co/favicon-32x32.png',
+                    action: {
+                        id: 'dropdownButton2',
+                        customData: 'dropdownButton2 clicked'
+                    }
+                }
+            ]
+        }
+    ]
 };
+```
 
-/**
- * Optional method for executing actions that are specific to your Home provider.
- */
-const onResultDispatch = (res) => {
-    if (res.action === 'execute-my-action') {
-        return executeMyAction(res.data);
-    }
-};
+Register dock `provider` object.
 
-Home.register({
-    id: 'my-home-provider',
-    title: 'My Home Provider',
-    onUserInput,
-    onResultDispatch
-});
+```ts
+await Dock.register(provider);
 ```
+
+Show Dock.
+
+```ts
+await Dock.show();
+```
+
+## For more information
+
+-   [Developer guide](https://developers.openfin.co/of-docs/docs/overview-of-workspace).
+-   [API reference](https://developer.openfin.co/workspace/docs/api/latest/index.html).
+-   See the [workspace-starter](https://github.com/built-on-openfin/workspace-starter) project for example code.
+-   See the [versions page](https://developer.openfin.co/versions/#/?product=Workspace) for a list of all available versions.

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

@@ -1,7 +1,7 @@
 export type { Action, DispatchedAction, DispatchedSearchResult, SearchListenerRequest, SearchListenerResponse, SearchProviderInfo, SearchResult, ScoreOrder, SearchTag, SearchProvider, UserInputListener, ResultDispatchListener, SearchResponse } from '../../../search-api/src/index';
 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 type { Page, PageLayout, PageLayoutDetails, PanelConfig, PanelConfigHorizontal, PanelConfigVertical, PanelPosition } from '../../../common/src/api/pages/shapes';
 export { SearchTagBackground, ActionTrigger } from '../../../search-api/src/shapes';
 export type { ProviderInfo } from './provider';
 export type { BaseCustomButtonConfig, BaseCustomDropdownConfig, BaseCustomDropdownItem, BaseCustomDropdownItems, CustomActionSpecifier, CustomButtonConfig, CustomDropdownConfig } from '../../../common/src/api/action';

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

@@ -1,4 +1,4 @@
 import { AttachedPage, ExtendedPanelConfig, PanelConfig } from '../../../common/src/api/pages/shapes';
 export declare function convertPanelViewOpts(panels: PanelConfig[]): ExtendedPanelConfig[];
-export declare function createPanelViewsForPages(pages: AttachedPage[]): Promise<import("@openfin/core/src/api/view").View[][]>;
+export declare function createPanelViewsForPages(pages: AttachedPage[]): Promise<void>;
 export declare function createPanelViews(panels: PanelConfig[]): Promise<import("@openfin/core/src/api/view").View[]>;

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

@@ -99,18 +99,27 @@ export interface GetSavedPageMetadataPayload {
     /** The id of the page to get the save state of. */
     pageId: string;
 }
+/**
+ * Possible positions than a fixed view panel can take.
+ */
 export declare enum PanelPosition {
     Left = "Left",
     Right = "Right",
     Top = "Top",
     Bottom = "Bottom"
 }
+/**
+ * Properties specific to a horizontal fixed view panel (top or bottom)
+ */
 export interface PanelConfigHorizontal {
     /** Position of the panel in the page. */
     position: PanelPosition.Top | PanelPosition.Bottom;
     /** Size of the top/bottom panel, formatted as CSS property value with units. E.g. "0px", "10%", "3rem". */
     height: string;
 }
+/**
+ * Properties specific to a vertical fixed view panel (left or right)
+ */
 export interface PanelConfigVertical {
     /** Position of the panel in the page. */
     position: PanelPosition.Left | PanelPosition.Right;
@@ -123,6 +132,18 @@ export interface PanelConfigVertical {
      * thus taking priority over the bottom panel.*/
     extendToBottom?: boolean;
 }
+/**
+ * Configuration of an individual fixed view panel
+ *
+ * Example:
+ * ```ts
+ * {
+ *    position: PanelPosition.Left,
+ *    width: '140px',
+ *    viewOptions: { url: 'https://example.com'}
+ * }
+ * ```
+ */
 export declare type PanelConfig = (PanelConfigHorizontal | PanelConfigVertical) & {
     /** The options with which to initialize the panel view.*/
     viewOptions: Omit<OpenFin.PlatformViewCreationOptions, 'bounds' | 'target'>;