@openfin/workspace-platform 5.2.0 → 5.5.0

package/README.md

@@ -1,4 +1,4 @@
-# Workspace Client API
+# Workspace Platform API
 
 The Workspace Platform Client APIs allow integrators to create their own Workspace platforms.
 
@@ -10,13 +10,40 @@ Run `npm i -E @openfin/workspace-platform`.
 
 ## Workspace Platform API documentation
 
--   [Overview](https://developers.openfin.co/of-docs/doc/)
--   [API Reference](https://cdn.openfin.co/workspace/api/platform/docs/)
+-   [Overview](https://developers.openfin.co/of-docs/docs/workspace-sdk)
+-   [API Reference](https://cdn.openfin.co/workspace/api/platform/docs/latest/index.html)
+-   [Example projects using Workspace Platform](https://github.com/built-on-openfin/workspace-starter)
 
 ## Code examples
 
+### Initilaize a Workspace Platform
+
 ```typescript
 import * as WorkspacePlatform from '@openfin/workspace-platform';
 
-WorkspacePlatform.init();
+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
+        }
+    }
+];
+
+const overrideCallback: WorkspacePlatform.BrowserOverrideCallback = async (WorkspacePlatformProvider) => {
+    class Override extends WorkspacePlatformProvider {
+        async quit(payload, callerIdentity) {
+            return super.quit(payload, callerIdentity);
+        }
+    }
+    return new Override();
+};
+
+await WorkspacePlatform.init({
+    browser: { overrideCallback },
+    theme: customThemes
+});
 ```

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

@@ -0,0 +1,597 @@
+/**
+ * Use relative paths here rather than aliases which mess
+ * up the packaged typing files
+ */
+import type { Page } from '../../common/src/api/pages/shapes';
+import type { Workspace } from '../../common/src/api/workspaces';
+import type { Action, DispatchedSearchResult, SearchListenerRequest, SearchListenerResponse, SearchProvider, SearchResult } from '../../search-api/src/index';
+export type { Action, 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 { SearchTagBackground } from '../../search-api/src/index';
+/**
+ * Describes the type of the app directory entry `manifest` attributes.
+ * Launch mechanics are determined by the manifest type.
+ */
+export declare enum AppManifestType {
+    /**
+     * A snapshot manifest.
+     */
+    Snapshot = "snapshot",
+    /**
+     * A classic OpenFin app manifest.
+     */
+    Manifest = "manifest",
+    /**
+     * A view manifest.
+     */
+    View = "view",
+    /**
+     * A manifest for an external application.
+     */
+    External = "external"
+}
+export interface AppIntent {
+    name: string;
+    displayName: string;
+    contexts: string[];
+}
+/**
+ * Detailed metadata describing an image.
+ */
+export interface Image {
+    src: string;
+    type?: string;
+    size?: string;
+    purpose?: string;
+}
+/**
+ * Detailed metadata describing an application.
+ */
+export interface App {
+    /**
+     * Unique identifier for an application.
+     */
+    appId: string;
+    /**
+     * A UI friendly title for the application.
+     */
+    title: string;
+    /**
+     * URL to application manifest.
+     */
+    manifest: string;
+    /**
+     * UI friendly description for an application.
+     */
+    description?: string;
+    /**
+     * Describes the type of manifest resolved by the `manifest` field.
+     * Launch mechanics are determined by the manifest type.
+     */
+    manifestType: AppManifestType | string;
+    /**
+     * A list of icons that can be rendered in UI for this application.
+     */
+    icons: Image[];
+    /**
+     * A list of optional images that highlight application functionality.
+     */
+    images?: Image[];
+    intents?: AppIntent[];
+    tags?: string[];
+    version?: string;
+    publisher: string;
+    contactEmail?: string;
+    supportEmail?: string;
+}
+export declare enum StorefrontTemplate {
+    LandingPage = "landingPage",
+    AppGrid = "appGrid"
+}
+/**
+ * Represents a link to be rendered inside Storefront.
+ */
+export interface StorefrontLink {
+    /**
+     * A UI friendly title to render the link as.
+     */
+    title: string;
+    /**
+     * When the rendered `title` text is clicked, the user will be navigated to this URL.
+     */
+    url: string;
+}
+export interface StorefrontFooter {
+    /**
+     * A logo to be displayed on the Storefront's footer.
+     */
+    logo: Image;
+    /**
+     * A set of links to display on Storefront's footer.
+     */
+    links: [StorefrontLink?, StorefrontLink?, StorefrontLink?];
+    text: string;
+}
+/**
+ * Render a navigation section on the left panel of Storefront.
+ */
+export interface StorefrontNavigationSection {
+    /**
+     * Unique identifier for the navigation section.
+     */
+    id: string;
+    /**
+     * The UI friendly title of the navigation section.
+     */
+    title: string;
+    /**
+     * Navigation items to render under this section.
+     * 1-5 Navigation Items are supported.
+     */
+    items: [
+        StorefrontNavigationItem,
+        StorefrontNavigationItem?,
+        StorefrontNavigationItem?,
+        StorefrontNavigationItem?,
+        StorefrontNavigationItem?
+    ];
+}
+export interface StorefrontLandingPage {
+    hero?: {
+        title: string;
+        description: string;
+        cta: StorefrontNavigationItem;
+        image: Image;
+    };
+    topRow: {
+        title: string;
+        items: [
+            StorefrontDetailedNavigationItem?,
+            StorefrontDetailedNavigationItem?,
+            StorefrontDetailedNavigationItem?,
+            StorefrontDetailedNavigationItem?
+        ];
+    };
+    middleRow: {
+        title: string;
+        apps: [App?, App?, App?, App?, App?, App?];
+    };
+    bottomRow: {
+        title: string;
+        items: [
+            StorefrontDetailedNavigationItem?,
+            StorefrontDetailedNavigationItem?,
+            StorefrontDetailedNavigationItem?
+        ];
+    };
+}
+/**
+ * Render a grid of applications in Storefront.
+ */
+export interface StorefrontAppGrid {
+    /**
+     * The apps to render in the grid.
+     */
+    apps: App[];
+}
+export interface StorefrontNavigationItemBase {
+    /**
+     * An ID for referencing the navigation item. Must be unique.
+     */
+    id: string;
+    /**
+     * UI friendly name for the navigation item.
+     */
+    title: string;
+}
+export interface StorefrontNavigationItemDetails {
+    description: string;
+    image: Image;
+}
+/**
+ * Template for rendering a navigation item that renders a app grid when clicked.
+ */
+export interface StorefrontNavigationItemAppGrid extends StorefrontNavigationItemBase {
+    templateId: StorefrontTemplate.AppGrid;
+    /**
+     * Render an app grid when navigation item is pressed.
+     */
+    templateData: StorefrontAppGrid;
+}
+/**
+ * Template for rendering a navigation item that renders another landing page when clicked.
+ */
+export interface StorefrontNavigationItemLandingPage extends StorefrontNavigationItemBase {
+    templateId: StorefrontTemplate.LandingPage;
+    /**
+     * Render a landing page when navigation item is pressed.
+     */
+    templateData: StorefrontLandingPage;
+}
+/**
+ * Render an item in the navigation bar of Storefront.
+ */
+export declare type StorefrontNavigationItem = StorefrontNavigationItemAppGrid | StorefrontNavigationItemLandingPage;
+/**
+ *  Render an item in the navigation bar of Storefront with a description and image.
+ */
+export declare type StorefrontDetailedNavigationItem = StorefrontNavigationItem & StorefrontNavigationItemDetails;
+export interface StorefrontProviderInfo {
+    /**
+     * Unique identifier for the Storefront provider.
+     */
+    id: string;
+    /**
+     * A UI friendly title for the platform Storefront.
+     * This will be used in the Storefront selection dropdown.
+     */
+    title: string;
+    /**
+     * Icon for storefront provider.
+     * Visible next to title in storefront provider selector UI
+     */
+    icon: string;
+}
+/**
+ * Describes a Storefront provided by a platform.
+ * A platform must provide an object that satisfies this interface in order to register with the Storefront.
+ */
+export interface StorefrontProvider extends StorefrontProviderInfo {
+    /**
+     * Get a list of apps to populate the platform's Storefront with.
+     */
+    getApps(): Promise<App[]>;
+    /**
+     * Get the main landing page for the platform's Storefront.
+     */
+    getLandingPage(): Promise<StorefrontLandingPage>;
+    /**
+     * Get the Storefront navigation sections for the left nav bar.
+     */
+    getNavigation(): Promise<[StorefrontNavigationSection?, StorefrontNavigationSection?]>;
+    /**
+     * Get the footer for the platform's Storefront.
+     */
+    getFooter(): Promise<StorefrontFooter>;
+    /**
+     * Launch an app provided by the platform's Storefront.
+     */
+    launchApp(app: App): Promise<void>;
+}
+/**
+ * Interface that contains functions for integrating with Storefront.
+ */
+export interface StorefrontAPI {
+    /**
+     * Registers a [[`StorefrontProvider`]]. Upon registering a provider,
+     * the title of your provider appears in the menu of the Storefront UI.
+     * 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.
+     * @param provider the implementation of a Storefront provider.
+
+     */
+    register(provider: StorefrontProvider): Promise<void>;
+    /**
+     * Deregister a provider.
+     * @param id the id of the provider.
+     */
+    deregister(id: string): Promise<void>;
+    /**
+     * 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).
+     */
+    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).
+     */
+    hide(): Promise<void>;
+}
+export declare type CLISearchListenerRequest = SearchListenerRequest;
+/**
+ * Representation of a search request from a specific invocation of a {@link HomeProvider | HomeProvider's} `onUserInput` listener function.
+ */
+export interface HomeSearchListenerRequest extends CLISearchListenerRequest {
+    context: {
+        /**
+         * Denotes that this Home search request was triggered via
+         * the user selecting a suggestion from this provider.
+         */
+        isSuggestion: boolean;
+        /**
+         * Denotes that this search request should return search results
+         * that represent content that a user has saved. (Workspaces, Pages)
+         */
+        isSaved: boolean;
+        /**
+         * Denotes that this search request should return search results
+         * that represents content that is stored in the platform.
+         * This should exclude content that the user has saved.
+         * (Workspaces, Pages, Views, Apps)
+         */
+        isStore: boolean;
+        /**
+         * Denotes that this search request should return search results
+         * that represent other Home search providers. If the user chooses to
+         * launch one of these apps, they should register a Home provider.
+         */
+        isSearchEngines: boolean;
+        /**
+         * any user-selected filters will be populated here
+         * e.g  [{
+         *   title: 'Currency Pairs',
+         *   type: FilterOptionType.MultiSelect,
+         *   options: [{ value: 'GBPUSD', isSelected: true}]
+         * }]
+         */
+        selectedFilters?: CLIFilter[];
+    };
+}
+export declare type CLISearchListenerResponse = SearchListenerResponse;
+/**
+ * Representation of a search response from a specific invocation of a {@link HomeProvider | HomeProvider's} `onUserInput` listener function.
+ * Can optionally be used to push search results to the Home UI.
+ *
+ * ```ts
+ * function onUserInput(req: HomeSearchListenerRequest, res: HomeSearchListenerResponse) {
+ *    searchListenerResponse.open();
+ *
+ *    const myLongRunningQuery = makeMyLongRunningQuery(searchListenerRequest.query);
+ *    myLongRunningQuery.onNewResults(myNewResults => {
+ *       searchListenerResponse.respond(myNewResults);
+ *    });
+ *
+ *    searchListenerRequest.onClose(() => {
+ *       myLongRunningQuery.close();
+ *    });
+ * }
+ * ```
+ */
+export declare type HomeSearchListenerResponse = Omit<CLISearchListenerResponse, 'respond'> & {
+    respond(results: HomeSearchResult[]): void;
+};
+/**
+ * Enumerator for different types of actions that are built into the Home API.
+ */
+export declare enum CLIAction {
+    Suggestion = "suggestion"
+}
+/**
+ * An action that is built into Home.
+ */
+export interface CLIBuiltInAction<T extends CLIAction> extends Action {
+    name: T;
+}
+/**
+ * Built in action for suggesting another search to execute to the user.
+ */
+export interface CLISuggestion extends CLIBuiltInAction<CLIAction.Suggestion> {
+    /**
+     * The query to search for if this action is selected.
+     */
+    query: string;
+}
+/**
+ * Union type that includes Home's built in search result actions.
+ */
+export declare type HomeAction = CLISuggestion | Action;
+/**
+ * A search result that can be rendered by a Workspace component.
+ */
+export declare type CLISearchResult<A extends Action> = SearchResult<A>;
+/**
+ * A list of template types that determine how a search result is rendered.
+ */
+export declare enum CLITemplate {
+    /**
+     * Contact Information Template
+     */
+    Contact = "Contact",
+    /**
+     * Definition List Template
+     */
+    List = "List",
+    /**
+     * Non-Template search result.
+     */
+    Plain = "Plain",
+    /**
+     * Simple Text Template
+     */
+    SimpleText = "SimpleText"
+}
+/**
+ * {@link SearchResult | Search result} template definition
+ */
+export interface CLISearchResultWithTemplate<T extends keyof typeof CLITemplate, C, A extends Action> extends CLISearchResult<A> {
+    template: T;
+    templateContent: C;
+}
+export declare type ListPairs = [string, string][];
+/**
+ * Contact Data.
+ */
+export interface ContactInfo {
+    /**
+     * Name of the contact.
+     */
+    name: string;
+    /**
+     * Title of the contact.
+     */
+    title?: string;
+    /**
+     * URL for the contact's profile photo.
+     */
+    photoUrl?: string;
+    /**
+     * A flag to indicate that the contact card should display the contact's initials as profile photo if the photo url is undefined.
+     */
+    useInitials?: boolean;
+    /**
+     * An array of detail list objects that can be used for logical grouping of contact details.
+     */
+    details: ListPairs[];
+}
+/**
+ *  Contact Info Search Result
+ */
+export interface CLISearchResultContact<A extends Action = Action> extends CLISearchResultWithTemplate<CLITemplate.Contact, ContactInfo, A> {
+}
+/**
+ * Definition List Search Result
+ */
+export interface CLISearchResultList<A extends Action = Action> extends CLISearchResultWithTemplate<CLITemplate.List, ListPairs, A> {
+}
+/**
+ *  Non-Template Search Result
+ */
+export interface CLISearchResultPlain<A extends Action = Action> extends CLISearchResultWithTemplate<CLITemplate.Plain, undefined, A> {
+}
+/**
+ * Simple Text Search Result
+ */
+export interface CLISearchResultSimpleText<A extends Action = Action> extends CLISearchResultWithTemplate<CLITemplate.SimpleText, string, A> {
+}
+/**
+ * A search result that can be rendered by Home UI.
+ */
+export declare type HomeSearchResult = CLISearchResultContact<HomeAction> | CLISearchResultSimpleText<HomeAction> | CLISearchResultList<HomeAction> | CLISearchResultPlain<HomeAction>;
+export declare enum CLIFilterOptionType {
+    /**
+     * Display a multi-select drop down for the options
+     */
+    MultiSelect = "MultiSelect"
+}
+/**
+ * An option object containing values to filter
+ */
+export interface CLIFilterOption {
+    value: string;
+    isSelected?: boolean;
+}
+/**
+ * A search filter that will be rendered by a Workspace component.
+ */
+export interface CLIFilter {
+    id: string;
+    title: string;
+    type?: CLIFilterOptionType;
+    options: CLIFilterOption[] | CLIFilterOption;
+}
+/**
+ * An object returned from a CLI provider's 'onUserInput' function containing search results.
+ */
+export interface CLISearchResponse {
+    /**
+     * The search results to render in the Workspace component.
+     */
+    results: CLISearchResult<Action>[];
+    /**
+     * Additional custom context to pass back to the Workspace component.
+     */
+    context?: any;
+}
+/**
+ * An object resolved from 'onUserInput' function containing search results and optional filters.
+ */
+export interface HomeSearchResponse extends CLISearchResponse {
+    /**
+     * The search results to render in the Home UI.
+     */
+    results: HomeSearchResult[];
+    /**
+     * Filters to render in the Home UI.
+     */
+    context?: {
+        filters?: CLIFilter[];
+    };
+}
+/**
+ * A rendered search result that has been actioned by a user.
+ */
+export declare type CLIDispatchedSearchResult = DispatchedSearchResult;
+/**
+ * A CLI provider responds to search requests from Workspace components.
+ * Upon receiving a search request, a CLI provider can return search results that can be rendered and interacted with
+ * by a user by the requesting Workspace component.
+ */
+export interface CLIProvider extends SearchProvider {
+    /**
+     * Function that is called when a search request is triggered due to user input.
+     * @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.
+     */
+    onUserInput(req: CLISearchListenerRequest, res: CLISearchListenerResponse): Promise<CLISearchResponse>;
+    /**
+     * 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.)
+     * @param result the search result with the action that was selected by the user.
+     */
+    onResultDispatch?(result: CLIDispatchedSearchResult): Promise<void>;
+}
+/**
+ * A CLI provider responds to search requests from Home UI.
+ * Exposes search features that are specifically supported by Home.
+ */
+export interface HomeProvider extends CLIProvider {
+    onUserInput(req: HomeSearchListenerRequest, res: HomeSearchListenerResponse): Promise<HomeSearchResponse>;
+}
+/**
+ * Interface that contains functions for integrating with Home.
+ */
+export interface HomeAPI {
+    /**
+     * Register a provider that can return search results to Home.
+     *
+     * ```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)
+     * };
+     *
+     * Home.register(myCLIProvider);
+     * ```
+     *
+     * @param provider the provider implementation.
+     */
+    register(provider: HomeProvider | CLIProvider): Promise<void>;
+    /**
+     * Deregister a provider.
+     * @param providerId the name of the provider.
+     */
+    deregister(providerId: string): Promise<void>;
+    /**
+     * Show the Home UI.
+     */
+    show(): Promise<void>;
+    /**
+     * Hide the Home UI.
+     */
+    hide(): Promise<void>;
+}
+/**
+ * Interface that contains functions that aid in recovering legacy features of Workspace.
+ */
+export interface LegacyAPI {
+    /**
+     * Get the pages that a user had saved in a legacy version of Workspace. (pre 5.0.0)
+     */
+    getPages(): Promise<Page[]>;
+    /**
+     * Get the workspaces that a user had saved in a legacy version of Workspace. (pre 5.0.0)
+     */
+    getWorkspaces(): Promise<Workspace[]>;
+}

package/client-api-platform/src/api/app-directory.d.ts

@@ -0,0 +1,7 @@
+import type { LaunchAppRequest } from '../shapes';
+/**
+ * Launch the app described by an App Directory entry.
+ * @param app the app directory entry.
+ * @param opts launch options.
+ */
+export declare function launchApp({ app, target }: LaunchAppRequest): Promise<void | import("openfin-adapter").View | import("openfin-adapter").Application | import("openfin-adapter/src/api/platform").Platform | import("openfin-adapter").Identity>;

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

@@ -0,0 +1,13 @@
+/// <reference types="openfin-adapter/fin" />
+import type { AttachedPage, Page, PageWithUpdatableRuntimeAttribs } from '../../../../common/src/api/pages/shapes';
+export declare const getBrowserModule: (identity: OpenFin.Identity) => {
+    identity: OpenFin.Identity;
+    openfinWindow: import("openfin-adapter").Window;
+    getPages: () => Promise<AttachedPage[]>;
+    getPage: (pageId: string) => Promise<AttachedPage>;
+    addPage: (page: PageWithUpdatableRuntimeAttribs) => Promise<void>;
+    removePage: (id: Page['pageId']) => Promise<void>;
+    setActivePage: (id: Page['pageId']) => Promise<void>;
+    updatePage: (req: any) => Promise<any>;
+    reorderPages: (req: any) => Promise<any>;
+};

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

@@ -0,0 +1,22 @@
+/// <reference types="openfin-adapter/fin" />
+import type { AttachedPage, Page } from '../../../../common/src/api/pages/shapes';
+import type { BrowserCreateWindowRequest, BrowserWindowModule } from '../../shapes';
+export declare const getBrowserApi: (identity: OpenFin.ApplicationIdentity) => {
+    wrapSync: (windowIdentity: OpenFin.Identity) => {
+        identity: OpenFin.Identity;
+        openfinWindow: import("openfin-adapter").Window;
+        getPages: () => Promise<AttachedPage[]>;
+        getPage: (pageId: string) => Promise<AttachedPage>;
+        addPage: (page: import("@common/api/pages/shapes").PageWithUpdatableRuntimeAttribs) => Promise<void>;
+        removePage: (id: string) => Promise<void>;
+        setActivePage: (id: string) => Promise<void>;
+        updatePage: (req: any) => Promise<any>;
+        reorderPages: (req: any) => Promise<any>;
+    };
+    createWindow: (options: BrowserCreateWindowRequest) => Promise<BrowserWindowModule>;
+    getAllAttachedPages: () => Promise<AttachedPage[]>;
+    getAllWindows: () => Promise<BrowserWindowModule[]>;
+    launchPage: (page: Page) => Promise<BrowserWindowModule>;
+    getUniquePageTitle: (title?: string) => Promise<any>;
+    getLastFocusedWindow: () => Promise<any>;
+};