@openfin/workspace 1.8.0 → 4.0.0

package/README.md

@@ -1,7 +1,124 @@
-# Client API
+# Workspace Client API
 
-The Client API is a framework allowing custom integrations on top of workspace.
+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.
 
-TBD
+**This API is [experimental](https://developers.openfin.co/of-docs/docs/experimental-apis).**
+
+## Installation
+
+Run `npm i -E @openfin/workspace`.
+
+## Storefront API documentation
+
+-   [Overview](https://developers.openfin.co/of-docs/doc/)
+-   [API Reference](https://cdn.openfin.co/workspace/api/docs/interfaces/StorefrontAPI.html)
+
+## Code examples
+
+### Vanilla JS
+
+```typescript
+import { Storefront, launchApp } from '@openfin/workspace';
+import { fetchMyApps, fetchMyLandingPage, fetchMyNavigation, fetchMyFooter } from './my-storefront-provider';
+
+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
+});
+
+document.getElementById('show-btn').addEventListener('click', () => {
+    Storefront.show();
+});
+
+document.getElementById('hide-btn').addEventListener('click', () => {
+    Storefront.hide();
+});
+```
+
+### 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>
+        </>
+    );
+};
+```
+
+## 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/common.d.ts

@@ -0,0 +1,6 @@
+import type { App } from './shapes';
+/**
+ * Default Workspace implementation for launching an application.
+ * @param app the application to launch.
+ */
+export declare const launchApp: (app: App) => Promise<void>;

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,11 @@
+import type { HomeAPI as HomeAPIType, StorefrontAPI as StorefrontAPIType } from './shapes';
+export * from './shapes';
+export * from './common';
+/**
+  Namespace for Storefront integrations.
+*/
+export declare const Storefront: StorefrontAPIType;
+/**
+  Namespace for Home integrations.
+*/
+export declare const Home: HomeAPIType;

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

@@ -0,0 +1 @@
+export {};