@openfin/workspace-platform 14.0.11 → 14.0.14

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

@@ -2,9 +2,23 @@ import type { DockProvider } from './shapes/dock';
 import { DockProviderRegistration } from './shapes/dock';
 export * from './shapes/dock';
 /**
- * Registers a Dock provider
- * @returns promise - invokes action
+ * API function to register a Dock provider.
+ *
+ * @remarks A Workspace Platform must be initialized.
+ *
+ * @throws An error if the Workspace Platform is not initialized.
+ * @throws An error if a Dock provider for this Workspace Platform is already registered.
+ * @throws An error if the Dock provider configuration contains buttons with duplicate ids. If no ids are specified, the buttons will be assigned ids automatically.
+ *
+ * @param provider - The Dock provider to register.
+ *
+ * @returns A promise that resolves with a `DockProviderRegistration` object once the Dock provider is successfully registered. This contains the client API version, Workspace Version and a function to update the Dock provider configuration.
+ *
+ * @example Register a Dock provider with a single button.
+ *
  * ```ts
+ * import { Dock, type DockProvider } from '@openfin/workspace';
+ *
  * const provider: DockProvider = {
  *      id: 'provider-id',
  *      title: 'Sample Dock',
@@ -21,36 +35,58 @@ export * from './shapes/dock';
  * };
  *
  * await Dock.register(provider)
+ *
+ * await Dock.show()
  * ```
  */
 export declare const register: (provider: DockProvider) => Promise<DockProviderRegistration>;
 /**
- * API function to Deregister a Dock provider
+ * API function to deregister a Dock provider.
+ *
+ * @remarks A Workspace Platform must be initialized, and the Dock provider must be registered for this function to take effect.
+ *
+ * @throws an error if the provider is not registered.
  *
- * @returns a promise that resolves once the dock is deregistered
+ * @returns a promise that resolves once the Dock provider is successfully deregistered.
+ *
+ * @example Deregister a Dock provider.
  *
  * ```ts
+ * import { Dock } from '@openfin/workspace';
+ *
  * await Dock.deregister();
  * ```
  */
 export declare const deregister: () => Promise<void>;
 /**
- * API function to minimize Dock
+ * API function to show the Dock UI.
+ *
+ * @remarks A Workspace Platform must be initialized, and at least one Dock provider must be registered for this function to take effect.
  *
- * @returns a promise that resolves once the dock is minimized
+ * @returns a promise that resolves once the Dock UI is hidden
+ *
+ * @example Show a Dock provider.
  *
  * ```ts
- * await Dock.minimize();
+ * import { Dock } from '@openfin/workspace';
+ *
+ * await Dock.show();
  * ```
  */
 export declare const minimize: () => Promise<void>;
 /**
- * API function to show Dock
+ * API function to hide the Dock UI.
+ *
+ * @remarks A Workspace Platform must be initialized, and at least one Dock provider must be registered for this function to take effect.
+ *
+ * @returns a promise that resolves once the Dock UI is hidden
  *
- * @returns a promise that resolves once the dock is shown
+ * @example Hide a Dock provider.
  *
  * ```ts
- * await Dock.show();
+ * import { Dock } from '@openfin/workspace';
+ *
+ * await Dock.hide();
  * ```
  */
 export declare const show: () => Promise<void>;

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

@@ -2,20 +2,91 @@ import type { CLIProvider, HomeProvider } from './shapes/home';
 import { HomeRegistration } from './shapes/home';
 export * from './shapes/home';
 /**
- * Register a provider that can return search results to Home.
- * @param provider the Home provider implementation.
+ * API function to register a Home provider.
+ *
+ * @remarks A Workspace Platform must be initialized.
+ *
+ * @throws An error if the Workspace Platform is not initialized.
+ * @throws An error if a Home provider with the same `id` is already registered.
+ *
+ * @param provider - The Home provider to register.
+ *
+ * @returns A promise that resolves with a `HomeRegistration` object once the Dock provider is successfully registered. This contains the client API version, Workspace Version and a function to set the search query.
+ *
+ * @example **Register a Basic Home provider**
+ *
+ * ```ts
+ * import { Home, type HomeProvider } from '@openfin/workspace';
+ *
+ * const provider: HomeProvider = {
+ *     title: "My Home Provider"
+ *     inputPlaceholder: "Search with My Home Provider",
+ *     icon: "https://www.openfin.co/favicon-32x32.png",
+ *     listTitle: "My Home Provider Results",
+ *     logoUrl: "https://www.openfin.co/favicon-32x32.png",
+ *     id: "my-home-provider",
+ *     onUserInput: (req, res) => {
+ *         console.log(req.query);
+ *         return { results: [], context: { filters: [] } }
+ *     },
+ *     dispatchFocusEvents: true,
+ * };
+ *
+ * await Home.register(provider)
+ *
+ * await Home.show()
+ * ```
  */
 export declare const register: (provider: HomeProvider | CLIProvider) => Promise<HomeRegistration>;
 /**
- * Deregister a provider.
+ * API function to deregister a Home provider.
+ *
+ * @remarks A Workspace Platform must be initialized, and the Home provider must be registered for this function to take effect.
+ *
+ * @throws an error if the provider is not registered.
+ *
  * @param providerId the Home provider ID.
+ *
+ * @returns a promise that resolves once the Home provider is successfully deregistered.
+ *
+ * @example Deregister a Home provider.
+ *
+ * ```ts
+ * import { Home } from '@openfin/workspace';
+ *
+ * await Home.deregister('my-home-provider');
+ * ```
  */
 export declare const deregister: (providerId: string) => Promise<void>;
 /**
- * Show the Home UI.
+ * API function to show the Home UI.
+ *
+ * @remarks A Workspace Platform must be initialized, and at least one Home provider must be registered for this function to take effect.
+ *
+ * @returns a promise that resolves once the Home UI is hidden
+ *
+ * @example Show a Home provider.
+ *
+ * ```ts
+ * import { Home } from '@openfin/workspace';
+ *
+ * await Home.show();
+ * ```
  */
 export declare function show(): Promise<void>;
 /**
- * Hide the Home UI.
+ * API function to hide the Home UI.
+ *
+ * @remarks A Workspace Platform must be initialized, and at least one Home provider must be registered for this function to take effect.
+ *
+ * @returns a promise that resolves once the Home UI is hidden
+ *
+ * @example Hide a Home provider.
+ *
+ * ```ts
+ * import { Home } from '@openfin/workspace';
+ *
+ * await Home.hide();
+ * ```
  */
 export declare function hide(): Promise<void>;

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

@@ -9,22 +9,22 @@ export * from './shapes/home';
 export * from './shapes/store';
 export * from './shapes/dock';
 /**
-  Namespace for Storefront integrations.
-*/
+ * Namespace for Storefront integrations.
+ */
 export { StorefrontAPI as Storefront };
 /**
-  Namespace for Home integrations.
-*/
+ * Namespace for Home integrations.
+ */
 export { HomeAPI as Home };
 /**
-  Namespace for Dock integrations.
-*/
+ * Namespace for Dock integrations.
+ */
 export { DockAPI as Dock };
 /**
-  Namespace for Legacy integrations.
-*/
+ * Namespace for Legacy integrations.
+ */
 export { LegacyAPI as Legacy };
 /**
-  Namespace for Microflows integrations.
-*/
+ * Namespace for Microflows integrations.
+ */
 export { IntegrationsAPI as Integrations };

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

@@ -1,3 +1,4 @@
-import * as workspacesApi from '../../common/src/api/workspaces';
-export declare const getPages: () => Promise<import("client-api-platform").Page[]>;
-export declare const getWorkspaces: () => Promise<workspacesApi.Workspace[]>;
+/** @deprecated */
+export declare const getPages: () => unknown;
+/** @deprecated */
+export declare const getWorkspaces: () => unknown;

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

@@ -1,14 +1,25 @@
 export type { Action, DispatchedAction, 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 { Page, PageLayout, PageLayoutDetails, PanelConfig, PanelConfigHorizontal, PanelConfigVertical, PanelPosition } from '../../../common/src/api/pages/shapes';
 export { SearchTagBackground, ActionTrigger } from '../../../search-api/src/shapes';
 export type { ProviderInfo } from './provider';
 export type { BaseCustomButtonConfig, BaseCustomDropdownConfig, BaseCustomDropdownItem, BaseCustomDropdownItems, CustomActionSpecifier, CustomButtonConfig, CustomDropdownConfig } from '../../../common/src/api/action';
 /**
- * return by component.register function
+ * Registration meta info
+ *
+ * Returned when a Workspace component is registered.
  */
 export interface RegistrationMetaInfo {
+    /**
+     * Client API version
+     *
+     * This is the version of the Workspace client API that is being used to register the component.
+     */
     clientAPIVersion: string;
+    /**
+     * Workspace version
+     *
+     * This is the version of Workspace that the Workspace component is running on.
+     * This could be used to determine if the component is running on a version of Workspace that supports a particular feature.
+     */
     workspaceVersion: string;
 }
-export type RegisterMetaInfoInternal = Pick<RegistrationMetaInfo, 'workspaceVersion'>;

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 {
@@ -102,7 +102,10 @@ export interface DockDropdownConfig extends CustomDropdownConfig {
  * Dock button types
  */
 export type DockButton = {
-    /** Optional button identifier, if not provided will be automatically generated by the provider */ id?: string;
+    /**
+     * 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.
@@ -113,11 +116,11 @@ export type WorkspaceButton = 'switchWorkspace' | 'home' | 'notifications' | 'st
 /**
  * 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,7 +129,7 @@ export type WorkspaceButton = 'switchWorkspace' | 'home' | 'notifications' | 'st
  * ];
  * ```
  *
- * @example - Hide all of the workspace buttons.
+ * @example Hide all of the workspace buttons.
  *
  * ```ts
  * const workspaceButtonsConfig: WorkspaceButtonsConfig = [];
@@ -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);