@openfin/workspace 3.0.0 → 4.4.0

package/README.md

@@ -1,28 +1,24 @@
-# Client API
+# Workspace Client API
 
-The Client API is a framework allowing custom integrations on top of workspace. Could be used in **any** and **only** OpenFin app.
+The Workspace Client APIs enable custom integrations with OpenFin Workspace. They can
+be used in _any_ and _only_ OpenFin apps.
 
-## Getting started
+The Storefront API is the first Client API created.
 
-Run `npm i -E @openfin/workspace`. See the APIs and examples below.
+**This API is [experimental](https://developers.openfin.co/of-docs/docs/experimental-apis).**
 
-## Store API
+## Installation
 
-API Reference: https://cdn.openfin.co/workspace/api/docs/interfaces/StorefrontAPI.html
+Run `npm i -E @openfin/workspace`.
 
-### `register(provider: StorefrontProvider): Promise<void>`
+## Storefront API documentation
 
-Registers a Storefront provider. Upon registering a provider, the title of your provider will appear in the drop down of the Storefront UI. When a user selects your Storefront, the methods on the provider object will be called to populate the UI. Throws an error if provider with `provider.id` already exists. See [reference](https://cdn.openfin.co/workspace/api/docs/interfaces/StorefrontProvider.html) for definition of `StorefrontProvider` interface.
+-   [Overview](https://developers.openfin.co/of-docs/doc/)
+-   [API Reference](https://cdn.openfin.co/workspace/api/docs/interfaces/StorefrontAPI.html)
 
-### `show(): Promise<void>`
+## Code examples
 
-Shows store window. Awaits for latest `Storefront.register()` internally so you don't have to. If store provider doesn't exist (`register` was not called before) then an error is thrown.
-
-### `hide(): Promise<void>`
-
-Hides store window. Awaits for latest `Storefront.register()` internally so you don't have to. If store provider doesn't exist (`register` was not called before) then an error is thrown.
-
-### Vanilla JS Example
+### Vanilla JS
 
 ```typescript
 import { Storefront, launchApp } from '@openfin/workspace';
@@ -35,7 +31,7 @@ Storefront.register({
     getLandingPage: fetchMyLandingPage,
     getNavigation: fetchMyNavigation,
     getFooter: fetchMyFooter,
-    launchApp: launchApp // OpenFins default implementation of launchApp, you can also define your own
+    launchApp: launchApp // OpenFin's default implementation of launchApp, you can also define your own
 });
 
 document.getElementById('show-btn').addEventListener('click', () => {
@@ -47,7 +43,7 @@ document.getElementById('hide-btn').addEventListener('click', () => {
 });
 ```
 
-### React Example
+### React
 
 ```typescript
 import { Storefront, launchApp } from '@openfin/workspace';
@@ -63,7 +59,7 @@ const App = () => {
             getLandingPage: fetchMyLandingPage,
             getNavigation: fetchMyNavigation,
             getFooter: fetchMyFooter,
-            launchApp: launchApp // OpenFins default implementation of launchApp, you can also define your own
+            launchApp: launchApp // OpenFin's default implementation of launchApp, you can also define your own
         });
     }, []);
 
@@ -75,3 +71,54 @@ const App = () => {
     );
 };
 ```
+
+## Home API
+
+API Reference: https://cdn.openfin.co/workspace/api/docs/interfaces/HomeAPI.html
+
+### `register(provider: HomeProvider): Promise<void>`
+
+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/api/docs/interfaces/HomeProvider.html) for definition of `HomeProvider` interface.
+
+### Vanilla JS Example
+
+```typescript
+import { Home, HomeActionName, HomeSearchTemplate } from '@openfin/workspace';
+import { fetchMyLongRunningQueryResults, executeMyAction } from './my-provider';
+
+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() };
+    }
+
+    // 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 }]
+            }
+        ]
+    };
+};
+
+/**
+ * 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);
+    }
+};
+
+Home.register({
+    id: 'my-home-provider',
+    title: 'My Home Provider',
+    onUserInput,
+    onResultDispatch
+});
+```

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

@@ -0,0 +1,19 @@
+import type { CLIProvider, HomeProvider } from './shapes';
+/**
+ * Register a provider that can return search results to Home.
+ * @param provider the Home provider implementation.
+ */
+export declare const register: (provider: HomeProvider | CLIProvider) => Promise<void>;
+/**
+ * Deregister a provider.
+ * @param provider the Home provider implementation.
+ */
+export declare const deregister: (providerId: string) => Promise<void>;
+/**
+ * Show the Home UI.
+ */
+export declare function show(): Promise<any>;
+/**
+ * Hide the Home UI.
+ */
+export declare function hide(): Promise<any>;

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

@@ -0,0 +1,14 @@
+import type { HomeAPI as HomeAPIType, LegacyAPI as LegacyAPIType, StorefrontAPI as StorefrontAPIType } from './shapes';
+export * from './shapes';
+/**
+  Namespace for Storefront integrations.
+*/
+export declare const Storefront: StorefrontAPIType;
+/**
+  Namespace for Home integrations.
+*/
+export declare const Home: HomeAPIType;
+/**
+  Namespace for Legacy integrations.
+*/
+export declare const Legacy: LegacyAPIType;

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

@@ -0,0 +1,3 @@
+import * as workspacesApi from '@common/api/workspaces';
+export declare const getPages: () => Promise<import("@common/api/pages/shapes").Page[]>;
+export declare const getWorkspaces: () => Promise<workspacesApi.Workspace[]>;