@openfin/workspace-platform 6.2.2 → 6.3.0

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

@@ -0,0 +1,5 @@
+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/shapes';

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

@@ -0,0 +1,415 @@
+/**
+ * Use relative paths here rather than aliases which mess
+ * up the packaged typing files. When writing code examples,
+ * for documentation, please use async/await syntax over .then()!
+ */
+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';
+import { CustomTemplate, ListPairs } from './templates';
+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",
+    /**
+     * Custom Template
+     */
+    Custom = "Custom",
+    /**
+     * 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;
+}
+/**
+ * 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> {
+}
+/**
+ * A Search Result that renders custom templates.
+ */
+export interface CLISearchResultCustom<A extends Action = Action> extends CLISearchResultWithTemplate<CLITemplate.Custom, CustomTemplate, 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> | CLISearchResultCustom<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.
+     *
+     * ```ts
+     *
+     * import { getAllData, getResultsByQuery } from './get-all-data';
+     *
+     * const onUserInput = async({ query }): Promise<CLISearchResponse> => {
+     *      if (!query) {
+     *          return getAllData();
+     *      }
+     *
+     *      // Provide an implmentation to fetch query-filtered search results
+     *      return getResultsByQuery(query);
+     * }
+     * ```
+     * @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.)
+     *
+     *
+     * ```ts
+     * import { getAvailableCommands } from './my-commands';
+     *
+     * const onResultDispatch = async(result: CLIDispatchedSearchResult): Promise<void> => {
+     *      try {
+     *          //Grab the command corresponding to the result
+     *          const availableCommands = await getAvailableCommands();
+     *          const commandToExecute = availableCommands.find((command) => command.key === result.key);
+     *
+     *          if (commantToExecute != undefined) {
+     *              await commandToExecute.action();
+     *          }
+     *      } catch (err) {
+     *          //Handle the error
+     *          log.error('Error trying to action show command %s', err, result.key);
+     *      }
+     *  }
+     *```
+     * @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)
+     * };
+     *
+     * const register = async () => {
+     *      await Home.register(myCLIProvider);
+     * }
+     * ```
+     *
+     * @param provider the provider implementation.
+     */
+    register(provider: HomeProvider | CLIProvider): Promise<void>;
+    /**
+     * Deregister a provider.
+     *
+     * ```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)
+     * };
+     *
+     * // Register and do some work with the provider
+     *
+     * const deregister = async () => {
+     *      await Home.deregister("my-cli-provider");
+     * }
+     * ```
+     * @param providerId the name of the provider.
+     */
+    deregister(providerId: string): Promise<void>;
+    /**
+     * Show the Home UI.
+     *
+     * ```ts
+     * import { Home } from './home'
+     *
+     * const show = async () => {
+     *      await Home.show();
+     *      // Do thing after show
+     * }
+     * ```
+     */
+    show(): Promise<void>;
+    /**
+     * Hide the Home UI.
+     *
+     * ```ts
+     * import { Home } from './home'
+     *
+     * const hide = async () => {
+     *      await Home.hide();
+     *      // Do thing after hide
+     * }
+     * ```
+     */
+    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)
+     *
+     * ```ts
+     * import { Legacy } from "@openfin/workspace";
+     *
+     * async logPages() {
+     *      const pages = await Legacy.getPages();
+     *      console.log(pages);
+     * }
+     *
+     * logPages();
+     * ```
+     */
+    getPages(): Promise<Page[]>;
+    /**
+     * Get the workspaces that a user had saved in a legacy version of Workspace. (pre 5.0.0)
+     *
+     * ```ts
+     * import { Legacy } from "@openfin/workspace";
+     *
+     * async logWorkspaces() {
+     *      const workspaces = await Legacy.getWorkspaces();
+     *      console.log(workspaces);
+     * }
+     *
+     * logWorkspaces();
+     * ```
+     */
+    getWorkspaces(): Promise<Workspace[]>;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * WARNING: Do not export from './notifications' here. Not unless we move 'openfin-notifications' here.
+ */
+export * from './common';
+export * from './home';
+export * from './store';
+export * from './templates';