/** * 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 { Action, DispatchedSearchResult, SearchListenerRequest, SearchListenerResponse, SearchProvider, SearchResult } from '../../../search-api/src/index'; import { RegistrationMetaInfo } from './common'; import { CustomTemplate, ListPairs } from './templates'; export 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) * * @deprecated This is no longer used. */ 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) * * @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 * * @example * ```ts * [{ * title: 'Currency Pairs', * type: FilterOptionType.MultiSelect, * options: [{ value: 'GBPUSD', isSelected: true}] * }] * ``` */ selectedFilters?: CLIFilter[]; }; } 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(); * * const myLongRunningQuery = makeMyLongRunningQuery(searchListenerRequest.query); * myLongRunningQuery.onNewResults(myNewResults => { * searchListenerResponse.respond(myNewResults); * }); * * searchListenerRequest.onClose(() => { * myLongRunningQuery.close(); * }); * * // return any search results that are immediately available * return quickQuery.getResults(); * } * ``` */ export type HomeSearchListenerResponse = Omit & { 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. */ export declare enum CLIAction { Suggestion = "suggestion" } /** * An action that is built into Home. */ export interface CLIBuiltInAction extends Action { name: T; } /** * Built in action for suggesting another search to execute to the user. */ export interface CLISuggestion extends CLIBuiltInAction { /** * The query to search for if this action is selected. */ query: string; } /** * Union type that includes Home's built in search result actions. */ export type HomeAction = CLISuggestion | Action; /** * A search result that can be rendered by a Workspace component. */ export type CLISearchResult = SearchResult; /** * 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", /** * A Template that indicates that the search result details are being loaded */ Loading = "Loading", /** * A Template that indicates that a problem occurred with the search result details. */ Error = "Error" } /** * {@link SearchResult | Search result} template definition */ export interface CLISearchResultWithTemplate extends CLISearchResult { 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; /** * The contact's online status. */ onlineStatus?: 'offline' | 'do-not-disturb' | 'busy' | 'away' | 'available'; /** * An array of detail list objects that can be used for logical grouping of contact details. */ details: ListPairs[]; /** * An array of buttons to display on the contact card. */ buttons?: ContactInfoButtons[]; } export type ButtonIcon = /** * The icon used for the button. */ string | { /** * The icon used for the button in light mode. */ light: string; /** * The icon used for the button in dark mode. */ dark: string; }; export type SplitButtonOption = { /** * The label that appears on the button. */ label?: string; /** * The icon to display on the button. */ icon?: ButtonIcon; /** * The tooltip to display on the button. */ tooltip: string; /** * The action to execute when the button is clicked. */ action: string; }; export type SplitButton = { /** * The label that appears on the button. */ label?: string; /** * The icon to display on the button. */ icon?: ButtonIcon; /** * The tooltip to display on the button. */ tooltip: string; /** * The action to execute when the button is clicked. */ action: string; /** * The list of options to display in the dropdown. */ options: SplitButtonOption[]; }; export type ContactInfoButtons = { type: 'button'; /** * The icon to display on the button. */ icon: ButtonIcon; /** * The tooltip to display on the button. */ tooltip: string; /** * The action to execute when the button is clicked. */ action: string; } | (SplitButton & { type: 'dropdown'; }); /** * Contact Info Search Result */ export interface CLISearchResultContact extends CLISearchResultWithTemplate { } /** * A Search Result that renders custom templates. */ export interface CLISearchResultCustom extends CLISearchResultWithTemplate { } /** * Definition List Search Result */ export interface CLISearchResultList extends CLISearchResultWithTemplate { } /** * Non-Template Search Result */ export interface CLISearchResultPlain extends CLISearchResultWithTemplate { } /** * Simple Text Search Result */ export interface CLISearchResultSimpleText extends CLISearchResultWithTemplate { } /** * Loading Search Result */ export interface CLISearchResultLoading extends CLISearchResultWithTemplate { } /** * Error Search Result */ export interface CLISearchResultError extends CLISearchResultWithTemplate { } /** * A search result that can be rendered by Home UI. */ export type HomeSearchResult = CLISearchResultContact | CLISearchResultSimpleText | CLISearchResultList | CLISearchResultPlain | CLISearchResultCustom | CLISearchResultLoading | CLISearchResultError; 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[]; /** * 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 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 => { * if (!query) { * return getAllData(); * } * * // Provide an implementation 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; /** * 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 => { * try { * //Grab the command corresponding to the result * const availableCommands = await getAvailableCommands(); * const commandToExecute = availableCommands.find((command) => command.key === result.key); * * if (commandToExecute != 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; } /** * A CLI provider responds to search requests from Home UI. * Exposes search features that are specifically supported by Home. * *

Sample HomeProvider definition.

* * @example **Sample HomeProvider definition.* * * Import required dependencies. * ```ts * import { Home, type HomeProvider } from '@openfin/workspace'; * ``` * * Create provider object to configure `Home`. * * ```ts * const provider: HomeProvider = { * id: 'provider-id', * title: 'Sample Home', * icon: 'https://www.openfin.co/favicon-32x32.png', * description: 'A short description of the Search Provider.', * onResultDispatch: () => { } // Handle Result Dispatch * onUserInput: () => { } // Handle User Input * }; * ``` * * Register home `provider` object. * ```ts * await Home.register(provider); * ``` * * Show Home. * ```ts * await Home.show(); * ``` */ export interface HomeProvider extends CLIProvider { onUserInput(req: HomeSearchListenerRequest, res: HomeSearchListenerResponse): Promise; } /** * A rendered Home search result that has been actioned by a user. */ 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 * @param @optional additional options to set the search query * * @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, type CLIProvider } from '@openfin/workspace'; * * import { fetchMySearchResults } from "./my-fetch-implementation"; * * const searchQueryMap: Map void> = new Map(); * * // CLIProvider or HomeProvider * const myCLIProvider: CLIProvider = { * id: "my-cli-provider", * title: "My CLI Provider", * icon: "https://google.com/favicon.ico", * onUserInput: (req) => fetchMySearchResults(req.query) * }; * * // register home and get back a function to inject search string into home search * const { setSearchQuery } = await Home.register(myCLIProvider); * * // Store set query function in a map if you're using multiple providers * searchQueryMap.set(myCLIProvider.id, setSearchQuery); * * // Call the set query function for a specific provider the search should be injected into * const searchButton = document.createElement('button'); * searchButton.innerHTML = 'Search'; * document.body.appendChild(searchButton); * * searchButton.addEventListener('click', () => { * searchQueryMap.get('my-cli-provider')?.('my search string'); * }); * * ``` */ setSearchQuery(query: string, options?: SetSearchQueryOptions): Promise; } /** * Options to set the search query */ export interface SetSearchQueryOptions { /** * Whether to show home after setting the search query * @default true */ showHome?: boolean; }