@openfin/workspace 13.1.5 → 14.0.14

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

@@ -1,41 +1,41 @@
-import { CustomButtonConfig, CustomDropdownConfig } from '../../../common/src/api/action';
-import { RegistrationMetaInfo } from '../../../client-api/src/shapes/common';
-import { ProviderInfo } from './provider';
+import { type CustomButtonConfig, type CustomDropdownConfig } from '../../../common/src/api/action';
+import { type RegistrationMetaInfo } from '../../../client-api/src/shapes/common';
+import { type ProviderInfo } from './provider';
 /**
  * Allows you to hide buttons for different Workspace components in the Dock UI.
  * By default, all components are shown.
  *
  * @deprecated Use {@link WorkspaceButtonsConfig} instead. To migrate to the new configuration, any buttons that you wish to hide should be omitted from the `buttons` array.
  *
- * @example
+ * @example Hide all Workspace component buttons in the Dock UI.
  * ```ts
  * const workspaceComponentButtonOptions: WorkspaceComponentButtonOptions = {
- *   hideHomeButton: true,
- *   hideWorkspacesButton: true,
- *   hideNotificationsButton: true,
- *   hideStorefrontButton: true
+ *     hideHomeButton: true,
+ *     hideWorkspacesButton: true,
+ *     hideNotificationsButton: true,
+ *     hideStorefrontButton: true
  * }
  * ```
  */
 export interface WorkspaceComponentButtonOptions {
     /**
      * Set to true to hide the Workspaces button from the Dock UI.
-     * Default value false.
+     * @default false.
      */
     hideWorkspacesButton?: boolean;
     /**
      * Set to true to hide the Home button from the Dock UI.
-     * Default value false.
+     * @default false.
      */
     hideHomeButton?: boolean;
     /**
      * Set to true to hide the Notifications button from the Dock UI.
-     * Default value false.
+     * @default false.
      */
     hideNotificationsButton?: boolean;
     /**
      * Set to true to hide the Storefront button from the Dock UI.
-     * Default value false.
+     * @default false.
      */
     hideStorefrontButton?: boolean;
 }
@@ -71,28 +71,28 @@ export interface DockButtonConfig extends CustomButtonConfig {
  *
  * ```ts
  * const sampleDropdownButton1: DockDropdownConfig = {
- *   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"
- *       }
- *     }
- *   ]
- * }
+ *     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",
+ *             },
+ *         },
+ *     ],
+ * };
  * ```
  */
 export interface DockDropdownConfig extends CustomDropdownConfig {
@@ -101,23 +101,26 @@ export interface DockDropdownConfig extends CustomDropdownConfig {
 /**
  * Dock button types
  */
-export declare type DockButton = {
-    /** Optional button identifier, if not provided will be automatically generated by the provider */ id?: string;
+export type DockButton = {
+    /**
+     * Optional button identifier, if not provided will be automatically generated by the provider
+     */
+    id?: string;
 } & (DockButtonConfig | DockDropdownConfig);
 /**
  * The names of the buttons for the workspace components on the Dock.
  *
  * Used in {@link WorkspaceButtonsConfig}.
  */
-export declare type WorkspaceButton = 'switchWorkspace' | 'home' | 'notifications' | 'store';
+export type WorkspaceButton = 'switchWorkspace' | 'home' | 'notifications' | 'store';
 /**
  * Controls the visibility as well as the order of buttons for workspace components on the Dock.
  *
- * To hide a button, remove it from the array.
+ * To omit a button from the Dock UI, simply omit it from the array.
  *
- * The array should not contain duplicate values.
+ * The array must not contain duplicate values. Any duplicate values will be removed.
  *
- * @example - Hide the Home button and move the Notifications button to the first position.
+ * @example Hide the Home button and move the Notifications button to the first position.
  * ```ts
  * const workspaceButtonsConfig: WorkspaceButtonsConfig = [
  *     'notifications',
@@ -126,13 +129,13 @@ export declare type WorkspaceButton = 'switchWorkspace' | 'home' | 'notification
  * ];
  * ```
  *
- * @example - Hide all of the workspace buttons.
+ * @example Hide all of the workspace buttons.
  *
  * ```ts
  * const workspaceButtonsConfig: WorkspaceButtonsConfig = [];
  * ```
  */
-export declare type WorkspaceButtonsConfig = WorkspaceButton[];
+export type WorkspaceButtonsConfig = WorkspaceButton[];
 /**
  * Configuration for the Dock provider.
  */
@@ -141,7 +144,7 @@ export interface DockProviderConfig {
      * Controls the visibility of buttons for workspace components on the Dock.
      * All components are visible by default, but you can hide any of them.
      *
-     * @default - All components are visible. (['switchWorkspace', 'home', 'notifications', 'store'])
+     * @default - All components are visible. `['switchWorkspace', 'home', 'notifications', 'store']`
      */
     workspaceComponents?: WorkspaceComponentButtonOptions | WorkspaceButtonsConfig;
     /**
@@ -172,54 +175,56 @@ export interface DockProviderConfigWithIdentity extends ProviderInfo, DockProvid
  *
  * Import required dependencies.
  * ```ts
- * import { Dock, DockProvider, DockButtonNames } from '@openfin/workspace';
  * import { CustomDropdownItemActionPayload, init } from "@openfin/workspace-platform";
+ * import { Dock, type DockProvider, DockButtonNames } from '@openfin/workspace';
  * ```
  *
  * Create provider object to pass to the static `register` function of the `Dock` type.
  *
  * ```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: [
+ *     id: "provider-id",
+ *     title: "Sample Dock",
+ *     icon: "https://www.openfin.co/favicon-32x32.png",
+ *     buttons: [
  *         {
- *           tooltip: 'Dropdown Button 1',
- *           iconUrl: 'https://www.openfin.co/favicon-32x32.png',
- *           action: {
- *              id: 'dropdownButton1',
- *              customData: "dropdownButton1 clicked"
- *           }
+ *             tooltip: "Sample Button 1",
+ *             iconUrl: "https://www.openfin.co/favicon-32x32.png",
+ *             action: {
+ *                 id: "sampleButton1",
+ *             },
  *         },
  *         {
- *           tooltip: 'Dropdown Button 2',
- *           iconUrl: 'https://www.openfin.co/favicon-32x32.png',
- *           action: {
- *               id: 'dropdownButton2',
- *               customData: "dropdownButton2 clicked"
- *           }
- *         }
- *       ]
- *     }
- *   ]
+ *             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",
+ *                     },
+ *                 },
+ *             ],
+ *         },
+ *     ],
  * };
  * ```
  *
+ * When a Dock button is clicked, the `action` object is passed to the `customActions` function defined as defined in the Workspace Platform `init` function.
+ *
+ * Initialize your Workspace Platform with ``customActions`` to be invoked by dock dropdown.
  *
- * Initialize ``workspace`` with ``customActions`` to be invoked by dock dropdown.
  *```ts
  * await init({
  *     browser: {},
@@ -235,10 +240,12 @@ export interface DockProviderConfigWithIdentity extends ProviderInfo, DockProvid
  *```
  *
  * Register Dock ``provider`` object.
+ *
  * ```ts
  * await Dock.register(provider);
  * ```
  * Show Dock.
+ *
  * ```ts
  * await Dock.show();
  * ```
@@ -263,16 +270,21 @@ export interface DockProviderRegistration extends RegistrationMetaInfo {
      * @param request The new Dock configuration.
      * @returns Promise that resolves when the update completes.
      *
-     * @example
+     * @example Update the Dock configuration. This example requires that you have already registered a Dock provider.
+     *
      * ```ts
+     * import { Dock, type DockProviderConfig } from '@openfin/workspace';
+     *
      * const newConfig: DockProviderConfig = {
-     *     buttons: [{
-     *         tooltip: 'Sample Button 1',
-     *         iconUrl: 'https://www.openfin.co/favicon-32x32.png',
-     *         action: {
-     *                 id: 'sampleButton1'
-     *             }
-     *     }]
+     *     buttons: [
+     *         {
+     *             tooltip: "Sample Button 1",
+     *             iconUrl: "https://www.openfin.co/favicon-32x32.png",
+     *             action: {
+     *                 id: "sampleButton1",
+     *             },
+     *         },
+     *     ],
      * };
      *
      * await dockProviderRegistration.updateDockProviderConfig(newConfig);

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

@@ -3,12 +3,10 @@
  * 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 { RegistrationMetaInfo } from './common';
 import { CustomTemplate, ListPairs } from './templates';
-export declare type CLISearchListenerRequest = SearchListenerRequest;
+export type CLISearchListenerRequest = SearchListenerRequest;
 /**
  * Representation of a search request from a specific invocation of a {@link HomeProvider | HomeProvider's} `onUserInput` listener function.
  */
@@ -22,6 +20,8 @@ export interface HomeSearchListenerRequest extends CLISearchListenerRequest {
         /**
          * Denotes that this search request should return search results
          * that represent content that a user has saved. (Workspaces, Pages)
+         *
+         * @deprecated This is no longer used.
          */
         isSaved: boolean;
         /**
@@ -29,30 +29,40 @@ export interface HomeSearchListenerRequest extends CLISearchListenerRequest {
          * that represents content that is stored in the platform.
          * This should exclude content that the user has saved.
          * (Workspaces, Pages, Views, Apps)
+         *
+         * @deprecated This is no longer used.
          */
         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.
+         *
+         * @deprecated This is no longer used.
          */
         isSearchEngines: boolean;
         /**
          * any user-selected filters will be populated here
-         * e.g  [{
-         *   title: 'Currency Pairs',
-         *   type: FilterOptionType.MultiSelect,
-         *   options: [{ value: 'GBPUSD', isSelected: true}]
+         *
+         * @example
+         * ```ts
+         * [{
+         *     title: 'Currency Pairs',
+         *     type: FilterOptionType.MultiSelect,
+         *     options: [{ value: 'GBPUSD', isSelected: true}]
          * }]
+         * ```
          */
         selectedFilters?: CLIFilter[];
     };
 }
-export declare type CLISearchListenerResponse = SearchListenerResponse;
+export 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.
  *
+ * @example
+ *
  * ```ts
  * function onUserInput(req: HomeSearchListenerRequest, res: HomeSearchListenerResponse) {
  *    searchListenerResponse.open();
@@ -65,11 +75,18 @@ export declare type CLISearchListenerResponse = SearchListenerResponse;
  *    searchListenerRequest.onClose(() => {
  *       myLongRunningQuery.close();
  *    });
+ *
+ *    // return any search results that are immediately available
+ *    return quickQuery.getResults();
  * }
  * ```
  */
-export declare type HomeSearchListenerResponse = Omit<CLISearchListenerResponse, 'respond'> & {
+export type HomeSearchListenerResponse = Omit<CLISearchListenerResponse, 'respond' | 'updateContext'> & {
     respond(results: HomeSearchResult[]): void;
+    /**
+     * Pushes a new context to the Home UI. This can be used to update the search filters
+     */
+    updateContext(context: HomeSearchResponse['context']): void;
 };
 /**
  * Enumerator for different types of actions that are built into the Home API.
@@ -95,11 +112,11 @@ export interface CLISuggestion extends CLIBuiltInAction<CLIAction.Suggestion> {
 /**
  * Union type that includes Home's built in search result actions.
  */
-export declare type HomeAction = CLISuggestion | Action;
+export type HomeAction = CLISuggestion | Action;
 /**
  * A search result that can be rendered by a Workspace component.
  */
-export declare type CLISearchResult<A extends Action> = SearchResult<A>;
+export type CLISearchResult<A extends Action> = SearchResult<A>;
 /**
  * A list of template types that determine how a search result is rendered.
  */
@@ -173,7 +190,7 @@ export interface ContactInfo {
      */
     buttons?: ContactInfoButtons[];
 }
-export declare type ButtonIcon = 
+export type ButtonIcon = 
 /**
  * The icon used for the button.
  */
@@ -187,7 +204,7 @@ string | {
      */
     dark: string;
 };
-export declare type ContactInfoButtons = {
+export type ContactInfoButtons = {
     type: 'button';
     /**
      * The icon to display on the button.
@@ -271,7 +288,7 @@ export interface CLISearchResultError<A extends Action = Action> extends CLISear
 /**
  * A search result that can be rendered by Home UI.
  */
-export declare type HomeSearchResult = CLISearchResultContact<HomeAction> | CLISearchResultSimpleText<HomeAction> | CLISearchResultList<HomeAction> | CLISearchResultPlain<HomeAction> | CLISearchResultCustom<HomeAction> | CLISearchResultLoading<HomeAction> | CLISearchResultError<HomeAction>;
+export type HomeSearchResult = CLISearchResultContact<HomeAction> | CLISearchResultSimpleText<HomeAction> | CLISearchResultList<HomeAction> | CLISearchResultPlain<HomeAction> | CLISearchResultCustom<HomeAction> | CLISearchResultLoading<HomeAction> | CLISearchResultError<HomeAction>;
 export declare enum CLIFilterOptionType {
     /**
      * Display a multi-select drop down for the options
@@ -325,7 +342,7 @@ export interface HomeSearchResponse extends CLISearchResponse {
 /**
  * A rendered search result that has been actioned by a user.
  */
-export declare type CLIDispatchedSearchResult = DispatchedSearchResult;
+export 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
@@ -386,9 +403,11 @@ export interface CLIProvider extends SearchProvider {
  *
  * <h3>Sample HomeProvider definition.</h3>
  *
+ * @example **Sample HomeProvider definition.*
+ *
  * Import required dependencies.
  * ```ts
- * import { Home, HomeProvider } from '@openfin/workspace';
+ * import { Home, type HomeProvider } from '@openfin/workspace';
  * ```
  *
  * Create provider object to configure `Home`.
@@ -404,10 +423,11 @@ export interface CLIProvider extends SearchProvider {
  * };
  * ```
  *
- * Register home ``provider`` object.
+ * Register home `provider` object.
  * ```ts
  * await Home.register(provider);
  * ```
+ *
  * Show Home.
  * ```ts
  * await Home.show();
@@ -419,22 +439,26 @@ export interface HomeProvider extends CLIProvider {
 /**
  * A rendered Home search result that has been actioned by a user.
  */
-export declare type HomeDispatchedSearchResult = HomeSearchResult & DispatchedSearchResult;
-export interface SearchQueryWithProviderID {
-    providerID: string;
-    query: string;
-}
+export type HomeDispatchedSearchResult = HomeSearchResult & DispatchedSearchResult;
 /**
  * Response from home registration which includes metadata and a function to inject search string into home search
  */
 export interface HomeRegistration extends RegistrationMetaInfo {
     /**
      * Function to inject search string into home search
+     *
+     * @remarks Calling this will switch the active provider within Home to the provider that was registered with this HomeRegistration.
+     *
+     * @throws An error if the Home Provider is no longer registered.
+     *
      * @param query search string
-     * @returns Promise<void>
+     *
+     * @returns A promise that resolves when the search string has been injected into home search
+     *
+     * @example Injecting a search string into Home search
      *
      * ```ts
-     * import Home, CLIProvider from '@openfin/workspace';
+     * import { Home, type CLIProvider } from '@openfin/workspace';
      *
      * import { fetchMySearchResults } from "./my-fetch-implementation";
      *
@@ -460,123 +484,10 @@ export interface HomeRegistration extends RegistrationMetaInfo {
      * document.body.appendChild(searchButton);
      *
      * searchButton.addEventListener('click', () => {
-     *     searchQueryMap.get('my-cli-provider')('my search string');
+     *     searchQueryMap.get('my-cli-provider')?.('my search string');
      * });
      *
      * ```
      */
     setSearchQuery(query: string): Promise<void>;
 }
-/**
- * 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 = {
-     *      id: "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<HomeRegistration>;
-    /**
-     * Deregister a provider.
-     *
-     * ```ts
-     * import { Home , CLIProvider } from "@openfin/workspace";
-     *
-     * import { fetchMySearchResults } from "./my-fetch-implementation";
-     *
-     * const myCLIProvider: CLIProvider = {
-     *      id: "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/notifications.d.ts

@@ -17,11 +17,11 @@ import type { NotificationPlatform as NotificationsPlatformInternal } from 'open
  * await register(platform);
  * ```
  */
-export declare type NotificationsPlatform = Omit<NotificationsPlatformInternal, 'theme'>;
+export type NotificationsPlatform = Omit<NotificationsPlatformInternal, 'theme'>;
 /**
  * Registration meta info returned by {@link register}
  */
-export declare type NotificationsRegistration = {
+export type NotificationsRegistration = {
     clientAPIVersion: string;
     notificationsVersion: string;
 };