@openfin/workspace-platform 13.1.5 → 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/internal/home/handlers/data.d.ts

@@ -0,0 +1,3 @@
+import { HomeClientApiDataRequest, HomeInternalDataResponse, HomeInternalErrorResponse, InternalDataResponse } from '../../../../../common/src/api/shapes/home';
+export declare function pushDataResponse(res: InternalDataResponse): Promise<void>;
+export declare function handleDataRequest(req: HomeClientApiDataRequest): Promise<HomeInternalDataResponse | HomeInternalErrorResponse>;

package/client-api/src/internal/home/handlers/disconnect.d.ts

@@ -0,0 +1 @@
+export declare function handleChannelDisconnection(): Promise<void>;

package/client-api/src/internal/home/handlers/index.d.ts

@@ -0,0 +1,6 @@
+import { SearchAPIClientChannelClient } from '../../../../../common/src/api/protocol/shapes/search';
+type HomeWorkspaceAPIClientChannelClient = SearchAPIClientChannelClient & {
+    homeChannelActionsRegistered?: boolean;
+};
+export declare function registerHomeChannelClientActions(channel: HomeWorkspaceAPIClientChannelClient): void;
+export {};

package/client-api/src/internal/home/handlers/result-dispatch.d.ts

@@ -0,0 +1,3 @@
+import type OpenFin from '@openfin/core';
+import type { HomeClientApiDispatchRequest } from '../../../../../common/src/api/shapes/home';
+export declare function handleResultDispatch(req: HomeClientApiDispatchRequest, identity: OpenFin.Identity): Promise<void>;

package/client-api/src/internal/home/handlers/search-close.d.ts

@@ -0,0 +1,5 @@
+import type { HomeClientApiSearchCloseRequest } from '../../../../../common/src/api/shapes/home';
+/**
+ * Listens for search requests that have been closed.
+ */
+export declare function handleSearchRequestClose(req: HomeClientApiSearchCloseRequest): void;

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

@@ -0,0 +1,4 @@
+import { ProvidersMap } from '../../../../client-api/src/internal/providers';
+import { CLIProvider, HomeProvider, RegisterMetaInfoInternal } from '../..';
+export declare const HomeProviders: ProvidersMap<CLIProvider | HomeProvider>;
+export declare const registerHomeProviderInternal: (provider: HomeProvider | CLIProvider) => Promise<RegisterMetaInfoInternal>;

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

@@ -0,0 +1,5 @@
+import type { InternalSearchListenerRequest } from '../../../../common/src/api/shapes/home';
+/**
+ * Map of search requests.
+ */
+export declare const searchRequests: Map<string, InternalSearchListenerRequest>;

package/client-api/src/internal/providers.d.ts

@@ -0,0 +1,63 @@
+import { ProviderType } from '../../../common/src/api/provider';
+export declare class ProviderNotRegisteredError extends Error {
+    constructor(providerType: ProviderType, id?: string);
+}
+export declare class ProviderAlreadyRegisteredError extends Error {
+    constructor(providerType: ProviderType, id?: string);
+}
+export declare class FailedToGetProviderError extends Error {
+    constructor(providerType: ProviderType, id?: string);
+}
+/**
+ * Utility class for managing providers.
+ */
+export declare class ProvidersMap<T extends {
+    id: string;
+}> {
+    private readonly providersMap;
+    private readonly providerType;
+    constructor(providerType: ProviderType);
+    /**
+     * Asserts that a provider is not already registered.
+     * @param provider The provider to check.
+     * @throws ProviderAlreadyRegisteredError if the provider already exists.
+     */
+    assertNotAlreadyRegistered(id: string): void;
+    /**
+     * Asserts that a provider is registered.
+     * @param provider The provider to check.
+     * @throws ProviderAlreadyRegisteredError if the provider already exists.
+     */
+    assertRegistered(id: string): void;
+    /**
+     * Gets a provider by id.
+     * @param id The id of the provider to get.
+     * @returns The provider if it exists, otherwise undefined.
+     */
+    getProvider(id: string): T | undefined;
+    /**
+     * Checks if a provider exists.
+     * @param id The id of the provider to check.
+     * @returns True if the provider exists, otherwise false.
+     */
+    hasProvider(id: string): boolean;
+    /**
+     * Sets a provider.
+     * @param provider The provider to set.
+     */
+    setProvider(provider: T): void;
+    /**
+     * Deletes a provider.
+     * @param id The id of the provider to delete.
+     */
+    deleteProvider(id: string): void;
+    /**
+     * Gets a provider by id or throws an error if it does not exist.
+     * @param id The id of the provider to get.
+     * @returns The provider if it exists.
+     * @throws An error if the provider does not exist.
+     * @see {@link ProviderNotRegisteredError}
+     */
+    getProviderOrFail(id: string): T;
+    clearProviders(): void;
+}

package/client-api/src/internal/storefront/handlers.d.ts

@@ -0,0 +1,9 @@
+import { WorkspaceAPIClientChannelClient } from '../../../../common/src/api/protocol/workspace';
+type StorefrontWorkspaceAPIClientChannelClient = WorkspaceAPIClientChannelClient & {
+    storefrontChannelActionsRegistered?: boolean;
+};
+/**
+ *  Registers a channel action for each function in the Storefront provider.
+ */
+export declare const registerStorefrontChannelClientActions: (channel: StorefrontWorkspaceAPIClientChannelClient) => void;
+export {};

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

@@ -0,0 +1,4 @@
+import { ProvidersMap } from '../../../../client-api/src/internal/providers';
+import { RegisterMetaInfoInternal, StorefrontProvider } from '../../../../client-api/src/shapes';
+export declare const StorefrontProviders: ProvidersMap<StorefrontProvider>;
+export declare const registerStorefrontProviderInternal: (provider: StorefrontProvider) => Promise<RegisterMetaInfoInternal>;

package/client-api/src/{internal.d.ts → internal/try-dispatch.d.ts}

@@ -1,4 +1,4 @@
-import { WorkspaceChannelAction } from '../../common/src/api/protocol/shapes/workspace';
+import { WorkspaceChannelAction } from '../../../common/src/api/protocol/shapes/workspace';
 export interface ChannelDispatch {
     action: WorkspaceChannelAction;
     payload?: any;

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 declare type RegisterMetaInfoInternal = Pick<RegistrationMetaInfo, 'workspaceVersion'>;