@openfin/workspace 14.0.11 → 14.0.14

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

@@ -3,8 +3,6 @@
  * 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';
@@ -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,12 +29,16 @@ 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;
         /**
@@ -57,6 +61,8 @@ 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();
@@ -69,11 +75,18 @@ export type CLISearchListenerResponse = SearchListenerResponse;
  *    searchListenerRequest.onClose(() => {
  *       myLongRunningQuery.close();
  *    });
+ *
+ *    // return any search results that are immediately available
+ *    return quickQuery.getResults();
  * }
  * ```
  */
-export 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.
@@ -390,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`.
@@ -408,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();
@@ -430,11 +446,19 @@ export type HomeDispatchedSearchResult = HomeSearchResult & DispatchedSearchResu
 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/store.d.ts

@@ -240,6 +240,8 @@ export interface StoreRegistration extends RegistrationMetaInfo {
      * @param request object that contains primary button and secondary buttons configs that will be
      * used to update button configuration returned by provider for an app.
      *
+     * @example Updating primary button title and disabled flag.
+     *
      * ```ts
      *  let storeRegistration: StoreRegistration | undefined;
      *
@@ -316,6 +318,8 @@ export type StorefrontDetailedNavigationItem = StorefrontNavigationItem & Storef
  *
  * <h3>Sample StorefrontProvider definition.</h3>
  *
+ * @example **Registering a StorefrontProvider**
+ *
  * Import required dependencies.
  * ```ts
  * import { Storefront, StorefrontProvider } from '@openfin/workspace';
@@ -329,7 +333,7 @@ export type StorefrontDetailedNavigationItem = StorefrontNavigationItem & Storef
  *   title: 'Sample Storefront',
  *   icon: 'https://www.openfin.co/favicon-32x32.png',
  *   getApps: () => { }, // Get apps to populate the platform's storefront
- *   getNavigation: () => {...}, // Get navigation selections for the left nav bar
+ *   getNavigation: () => {...}, // Get navigation selections for the left navigation bar
  *   getLandingPage: () => {...}, // Get main landing page for platform's storefront
  *   getFooter: () => {...}, // Get footer for the platform's storefront
  *   launchApp: () => {...}, // Launch an app provided by the platform's storefront
@@ -345,8 +349,9 @@ export interface StorefrontProvider extends ProviderInfo {
     /**
      * Get a list of apps to populate the platform's Storefront with.
      *
-     * ```ts
+     * @example An example of a `getApps` implementation that returns a single app.
      *
+     * ```ts
      * const app : App = {
      *      appId: 'uid'
      *      title: 'My App'
@@ -373,8 +378,9 @@ export interface StorefrontProvider extends ProviderInfo {
     /**
      * Get the main landing page for the platform's Storefront.
      *
-     * ```ts
+     * @example Landing page with hero, top row, middle row, and bottom row.
      *
+     * ```ts
      * const landingPage : StorefrontLandingPage = {
      *   hero: {
      *      title: 'My Landing Page',
@@ -386,15 +392,15 @@ export interface StorefrontProvider extends ProviderInfo {
      *   },
      *   topRow: {
      *       title: 'Top Row Title',
-     *       items: //array of StorefrontNavigationItem
+     *       items: [ /* array of StorefrontNavigationItem *\/ ]
      *   },
      *   middleRow: {
      *       title: 'Middle Row Title',
-     *       apps: //array of apps
+     *       items: [ /* array of Apps *\/ ]
      *   },
      *   bottomRow: {
      *       title: 'Bottom Row Title',
-     *       items: //array of StorefrontNavigationItem
+     *       items: [ /* array of StorefrontNavigationItem *\/ ]
      *   }
      * }
      *
@@ -407,17 +413,19 @@ export interface StorefrontProvider extends ProviderInfo {
     /**
      * Get the Storefront navigation sections for the left nav bar.
      *
+     * @example An example of a navigation section with a title and navigation items.
+     *
      * ```ts
      * const navigationSections: [StorefrontNavigationSection, StorefrontNavigationSection] = [
      *   {
      *       id: 'first id',
      *       title: 'title',
-     *       items: //array of navigation items
+     *       items: [ /* array of navigation items *\/ ]
      *   },
      *   {
      *       id: 'second id'
      *       title: 'title',
-     *       items: //array of navigation items
+     *       items: [ /* array of navigation items *\/ ]
      *   }
      * ]
      *
@@ -434,6 +442,11 @@ export interface StorefrontProvider extends ProviderInfo {
     /**
      * Get the footer for the platform's Storefront.
      *
+     * The footer is a section displayed at the bottom of the Storefront. It can contain a logo, text, and links.
+     *
+     *
+     * @example An example implementation of `getFooter`:
+     *
      * ```ts
      * const footer: StorefrontFooter = {
      *      logo: { src: './images/image', size: '32' },
@@ -453,6 +466,8 @@ export interface StorefrontProvider extends ProviderInfo {
     /**
      * Launch an app provided by the platform's Storefront.
      *
+     *
+     * @example An example implementation of `launchApp`:
      * ```ts
      * import { getStorefrontProvider } from "./my-provider";
      *
@@ -481,6 +496,8 @@ export interface StorefrontProvider extends ProviderInfo {
      * }
      * ```
      * @param app the app to launch.
+     *
+     * @returns a promise that resolves when the app has been launched.
      */
     launchApp(app: App): Promise<void>;
 }

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

@@ -1,15 +1,23 @@
+/**
+ * Entry points for the OpenFin Workspace Store API.
+ *
+ * The Store API allows you to register a Store provider with the Workspace Platform.
+ *
+ * @packageDocumentation
+ */
 import type { StorefrontProvider, StoreRegistration } from './shapes/store';
 export * from './shapes/store';
 /**
  * Registers a {@link StorefrontProvider}.
  *
- * Throws an error if a provider with the same `id` already exists.
+ * @throws Error if a provider with the same `id` already exists.
+ * @throws Error if Workspace Platform is not initialized.
  *
  * @param provider the implementation of a Storefront provider.
  *
  * @example
  * ```ts
- * import { Storefront, StorefrontProvider } from "@openfin/workspace";
+ * import { Storefront, type StorefrontProvider } from "@openfin/workspace";
  *
  * const myStorefrontProvider: StorefrontProvider = {
  *      id: "my-storefront-id"
@@ -23,19 +31,20 @@ export * from './shapes/store';
  * };
  *
  * await Storefront.register(myStorefrontProvider);
- *
  * ```
  */
 export declare const register: (provider: StorefrontProvider) => Promise<StoreRegistration>;
 /**
  * API function to deregister a Storefront provider.
  *
- * @param id the id of the provider to deregister.
- * @returns promise - resolves once the provider is deregistered.
+ * @param providerId the id of the provider to deregister.
+ * @returns promise that resolves once the provider is deregistered.
  *
+ * @throws an error if the provider is not currently registered.
  * @example
+ *
  * ```ts
- * import { Storefront, StorefrontProvider } from "@openfin/workspace";
+ * import { Storefront, type StorefrontProvider } from "@openfin/workspace";
  *
  * const myStorefrontProvider: StorefrontProvider = {
  *      id: "my-storefront-id"
@@ -51,29 +60,36 @@ export declare const register: (provider: StorefrontProvider) => Promise<StoreRe
  * await Storefront.register(myStorefrontProvider);
  *
  * await Storefront.deregister("my-storefront-id");
- *
  * ```
  */
 export declare const deregister: (providerId: string) => Promise<void>;
 /**
- * API function to hide the Storefront window.
- * @returns promise - invokes hide action
+ * API function to hide the Store UI.
+ *
+ * @remarks At least one Store provider must be registered for this function to take effect.
+ *
+ * @returns a promise that resolves once the Store UI is hidden.
+ *
+ * @example Hide a Store provider.
  *
- * @example
  * ```ts
- * import { Storefront } from "@openfin/workspace";
+ * import { Storefront } from '@openfin/workspace';
  *
  * await Storefront.hide();
  * ```
  */
 export declare const hide: () => Promise<void>;
 /**
- * API function to show the Storefront window.
- * @returns promise - invokes show action
+ * API function to show the Store UI.
+ *
+ * @remarks At least one Store provider must be registered for this function to take effect.
+ *
+ * @returns a promise that resolves once the Store UI is shown
+ *
+ * @example Show a Store provider.
  *
- * @example
  * ```ts
- * import { Storefront } from "@openfin/workspace";
+ * import { Storefront } from '@openfin/workspace';
  *
  * await Storefront.show();
  * ```

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

@@ -1481,38 +1481,45 @@ export interface AnalyticsConfig {
  */
 export interface WorkspacePlatformInitConfig {
     customActions?: CustomActionsMap;
-    /** Config for overriding browser options and behavior.
-     *  Set to null to initialize the platform without the browser
+    /**
+     * Config for overriding browser options and behavior.
+     * Set to null to initialize the platform without the browser
      */
     browser?: BrowserInitConfig | null;
-    /** Custom Themes object
+    /**
+     * Customize the Looks and Feel of the Workspace Platform by providing a custom palette.
+     *
+     * Two palettes are provided by default: `light` and `dark`.
+     * The `dark` palette is used by default.
+     *
+     * @example
      *
      * ```ts
      * import * as WorkspacePlatform from '@openfin/workspace-platform';
      *
      * // This is the palette used to create the OpenFin dark theme
      * const customPalette: WorkspacePlatform.CustomPaletteSet = {
-     *   brandPrimary: '#504CFF',
-     *   brandSecondary: '#383A40',
-     *   backgroundPrimary: '#000',
-     *   background1: '#111214',
-     *   background2: '#1E1F23',
-     *   background3: '#24262B',
-     *   background4: '#2F3136',
-     *   background5: '#383A40',
-     *   background6: '#53565F',
-     *   statusSuccess: '#35C759',
-     *   statusWarning: '#C93400',
-     *   statusCritical: '#000',
-     *   statusActive: '#0879C4',
-     *   inputBackground: '#53565F',
-     *   inputColor: '#FFFFFF',
-     *   inputPlaceholder: '#C9CBD2',
-     *   inputDisabled: '#7D808A',
-     *   inputFocused: '#C9CBD2',
-     *   textDefault: '#FFFFFF',
-     *   textHelp: '#C9CBD2',
-     *   textInactive: '#7D808A',
+     *     brandPrimary: '#504CFF',
+     *     brandSecondary: '#383A40',
+     *     backgroundPrimary: '#000',
+     *     background1: '#111214',
+     *     background2: '#1E1F23',
+     *     background3: '#24262B',
+     *     background4: '#2F3136',
+     *     background5: '#383A40',
+     *     background6: '#53565F',
+     *     statusSuccess: '#35C759',
+     *     statusWarning: '#C93400',
+     *     statusCritical: '#000',
+     *     statusActive: '#0879C4',
+     *     inputBackground: '#53565F',
+     *     inputColor: '#FFFFFF',
+     *     inputPlaceholder: '#C9CBD2',
+     *     inputDisabled: '#7D808A',
+     *     inputFocused: '#C9CBD2',
+     *     textDefault: '#FFFFFF',
+     *     textHelp: '#C9CBD2',
+     *     textInactive: '#7D808A',
      * };
      *
      * const customTheme: WorkspacePlatform.CustomThemes = [{

package/common/src/api/search/common.d.ts

@@ -5,6 +5,8 @@ export interface InternalSearchListenerResponse {
     setResultBuffer(results: HomeSearchResult[]): void;
     getRevokedBuffer(): string[];
     setRevokedBuffer(resultIds: string[]): void;
+    getUpdatedContext(): any;
+    setUpdatedContext(context: any): void;
     onChange(): void;
     getStatus(): InternalSearchListenerResponseStatus;
     res: HomeSearchListenerResponse;

package/common/src/api/theming.d.ts

@@ -6,8 +6,7 @@ export type WorkspaceComponentSetSelectedSchemePayload = {
     identity: OpenFin.Identity;
 };
 export type BrowserSetSelectedSchemePayload = string;
-export interface ComputedThemes extends Array<ComputedTheme> {
-}
+export type ComputedThemes = ComputedTheme[];
 export interface ComputedTheme {
     label: string;
     logoUrl?: string;
@@ -22,14 +21,27 @@ export interface CustomThemeOptions extends BaseThemeOptions {
     palette: CustomPaletteSet;
 }
 export interface CustomThemeOptionsWithScheme extends BaseThemeOptions {
+    /**
+     * The default color scheme for this theme.
+     *
+     * This will be used as a fallback if the user has not yet selected a color scheme, or there was an error fetching the user's color scheme.
+     *
+     * @default 'dark'
+     */
     default?: 'light' | 'dark';
+    /**
+     * The palette for this theme.
+     *
+     * When a user selects a color scheme, the palette will be updated to match the selected scheme.
+     *
+     * If `system` is selected, the palette will be updated to match the user's system color scheme.
+     */
     palettes: {
         light: CustomPaletteSet;
         dark: CustomPaletteSet;
     };
 }
-export interface CustomThemes extends Array<CustomThemeOptions | CustomThemeOptionsWithScheme> {
-}
+export type CustomThemes = (CustomThemeOptions | CustomThemeOptionsWithScheme)[];
 export interface DefaultPaletteSet {
     brandPrimary: string;
     brandSecondary: string;