@openfin/core 33.76.27 → 33.76.36

package/src/api/interop/InteropClient.d.ts

@@ -74,21 +74,21 @@ import { Base } from '../base';
 /**
  * @typedef {function} setContext
  * @summary A SessionContextGroup instance method for setting a context in the SessionContextGroup.
- * @param {Context} context The Context to be set.
- * @return {Promise<void>}
+ * @param context The Context to be set.
+ *
  */
 /**
  * @typedef {function} getCurrentContext
  * @summary A SessionContextGroup instance method for getting the current context of a certain type.
- * @param {string} [contextType] The Context Type to get. If not specified the last contextType set would get used.
- * @return {Promise<Context>}
+ * @param contextType The Context Type to get. If not specified the last contextType set would get used.
+ *
  */
 /**
  * @typedef {function} addContextHandler
  * @summary A SessionContextGroup instance method for adding a handler for context change.
- * @param {ContextHandler} contextHandler The callback to be invoked. Is invoked when (a) the context changes or (b) immediately after getting created if the context is already set.
- * @param {string} [contextType] The context type this handler should listen to. If not specified, a global handler for all context types will get created. Only one global handler is allowed per SessionContextGroup.
- * @return {Promise<Subscription>}
+ * @param contextHandler The callback to be invoked. Is invoked when (a) the context changes or (b) immediately after getting created if the context is already set.
+ * @param contextType The context type this handler should listen to. If not specified, a global handler for all context types will get created. Only one global handler is allowed per SessionContextGroup.
+ *
  */
 /**
  * {@link https://developers.openfin.co/of-docs/docs/enable-color-linking}
@@ -140,27 +140,91 @@ import { Base } from '../base';
  *  * {@link InteropClient#getInfoForContextGroup getInfoForContextGroup(contextGroupId)}
  *  * {@link InteropClient#getAllClientsInContextGroup getAllClientsInContextGroup(contextGroupId)}
  *
-
- *
- * @hideconstructor
- * @class
  */
 export declare class InteropClient extends Base {
     #private;
+    /**
+     * @internal
+     */
     constructor(wire: Transport, name: string, interopConfig?: OpenFin.InteropConfig);
     /**
      * Sets a context for the context group of the current entity.
-     * @param { Context } context - New context to set.
-     * @return { Promise<void> }
-     * @tutorial interop.setContext
+     *
+     * @remarks The entity must be part of a context group in order set a context.
+     *
+     * @param context - New context to set.
+     *
+     * @example
+     * ```js
+     * setInstrumentContext = async (ticker) => {
+     *     fin.me.interop.setContext({type: 'instrument', id: {ticker}})
+     * }
+     *
+     * // The user clicks an instrument of interest. We want to set that Instrument context so that the rest of our workflow updates with information for that instrument
+     * instrumentElement.on('click', (evt) => {
+     *     setInstrumentContext(evt.ticker)
+     * })
+     * ```
      */
     setContext(context: OpenFin.Context): Promise<void>;
     /**
-     * Add a context handler for incoming context. If an entity is part of a context group, and then sets its context handler, it will receive all of its declared contexts.
-     * @param { ContextHandler } handler - Handler for incoming context.
-     * @param { string } [contextType] - The type of context you wish to handle.
-     * @return { Promise<Subscription> }
-     * @tutorial interop.addContextHandler
+     * Add a context handler for incoming context. If an entity is part of a context group, and then sets its context handler,
+     * it will receive all of its declared contexts.
+     *
+     * @param handler - Handler for incoming context.
+     * @param contextType - The type of context you wish to handle.
+     *
+     * @example
+     * ```js
+     * function handleIncomingContext(contextInfo) {
+     *     const { type, id } = contextInfo;
+     *     switch (type) {
+     *         case 'instrument':
+     *             handleInstrumentContext(contextInfo);
+     *             break;
+     *         case 'country':
+     *             handleCountryContext(contextInfo);
+     *             break;
+     *
+     *         default:
+     *             break;
+     *     }
+     * }
+     *
+     *
+     * function handleInstrumentContext(contextInfo) {
+     *     const { type, id } = contextInfo;
+     *     console.log('contextInfo for instrument', contextInfo)
+     * }
+     *
+     * function handleCountryContext(contextInfo) {
+     *     const { type, id } = contextInfo;
+     *     console.log('contextInfo for country', contextInfo)
+     * }
+     *
+     * fin.me.interop.addContextHandler(handleIncomingContext);
+     * ```
+     *
+     *
+     * We are also testing the ability to add a context handler for specific contexts. If you would like to use
+     * this, please make sure you add your context handlers at the top level of your application, on a page that
+     * does not navigate/reload/re-render, to avoid memory leaks.  This feature is experimental:
+     *
+     * ```js
+     * function handleInstrumentContext(contextInfo) {
+     *     const { type, id } = contextInfo;
+     *     console.log('contextInfo for instrument', contextInfo)
+     * }
+     *
+     * function handleCountryContext(contextInfo) {
+     *     const { type, id } = contextInfo;
+     *     console.log('contextInfo for country', contextInfo)
+     * }
+     *
+     *
+     * fin.me.interop.addContextHandler(handleInstrumentContext, 'instrument')
+     * fin.me.interop.addContextHandler(handleCountryContext, 'country')
+     * ```
      */
     addContextHandler(handler: OpenFin.ContextHandler, contextType?: string): Promise<{
         unsubscribe: () => void;
@@ -168,61 +232,135 @@ export declare class InteropClient extends Base {
     /**
      * Returns the Interop-Broker-defined context groups available for an entity to join.
      * Used by Platform Windows.
-     * @return { Promise<ContextGroupInfo[]>}
-     * @tutorial interop.getContextGroups
+     *
+     * @example
+     * ```js
+     * fin.me.interop.getContextGroups()
+     *         .then(contextGroups => {
+     *             contextGroups.forEach(contextGroup => {
+     *                 console.log(contextGroup.displayMetadata.name)
+     *                 console.log(contextGroup.displayMetadata.color)
+     *             })
+     *         })
+     * ```
      */
     getContextGroups(): Promise<OpenFin.ContextGroupInfo[]>;
     /**
      * Join all Interop Clients at the given identity to context group `contextGroupId`.
      * If no target is specified, it adds the sender to the context group.
-     * Because multiple Channel connections/Interop Clients can potentially exist at a `uuid`/`name` combo, we currently join all Channel connections/Interop Clients at the given identity to the context group.
+     *
+     * @remarks Because multiple Channel connections/Interop Clients can potentially exist at a `uuid`/`name` combo, we currently join all Channel connections/Interop Clients at the given identity to the context group.
      * If an `endpointId` is provided (which is unlikely, unless the call is coming from an external adapter), then we only join that single connection to the context group.
      * For all intents and purposes, there will only be 1 connection present in Platform and Browser implmentations, so this point is more-or-less moot.
      * Used by Platform Windows.
-     * @param { string } contextGroupId - Id of the context group.
-     * @param { Identity } [target] - Identity of the entity you wish to join to a context group.
-     * @return { Promise<void>}
-     * @tutorial interop.joinContextGroup
+     *
+     * @param contextGroupId - Id of the context group.
+     * @param target - Identity of the entity you wish to join to a context group.
+     *
+     * @example
+     * ```js
+     * joinViewToContextGroup = async (contextGroupId, view) => {
+     *     await fin.me.interop.joinContextGroup(contextGroupId, view);
+     * }
+     *
+     * getLastFocusedView()
+     *     .then(lastFocusedViewIdentity => {
+     *         joinViewToContextGroup('red', lastFocusedViewIdentity)
+     *     })
+     * ```
      */
     joinContextGroup(contextGroupId: string, target?: OpenFin.Identity): Promise<void>;
     /**
      * Removes the specified target from a context group.
      * If no target is specified, it removes the sender from their context group.
      * Used by Platform Windows.
-     * @param { Identity } [target] - Identity of the entity you wish to join to a context group.
-     * @return { Promise<void>}
-     * @tutorial interop.removeFromContextGroup
+     *
+     * @param target - Identity of the entity you wish to join to a context group.
+     *
+     * @example
+     * ```js
+     * removeViewFromContextGroup = async (view) => {
+     *     await fin.me.interop.removeFromContextGroup(view);
+     * }
+     *
+     * getLastFocusedView()
+     *     .then(lastFocusedViewIdentity => {
+     *         removeViewFromContextGroup(lastFocusedViewIdentity)
+     *     })
+     * ```
      */
     removeFromContextGroup(target?: OpenFin.Identity): Promise<void>;
     /**
      * Gets all clients for a context group.
-     * Used by Platform Windows.
-     * @param { string } contextGroupId - The id of context group you wish to get clients for.
-     * @return { Promise<ClientIdentity[]>}
-     * @tutorial interop.getAllClientsInContextGroup
+     *
+     * @remarks **This is primarily used for platform windows. Views within a platform should not have to use this API.**
+     *
+     * Returns the Interop-Broker-defined context groups available for an entity to join.
+     * @param contextGroupId - The id of context group you wish to get clients for.
+     *
+     * @example
+     * ```js
+     * fin.me.interop.getAllClientsInContextGroup('red')
+     *     .then(clientsInContextGroup => {
+     *         console.log(clientsInContextGroup)
+     *     })
+     * ```
      */
     getAllClientsInContextGroup(contextGroupId: string): Promise<OpenFin.ClientIdentity[]>;
     /**
      * Gets display info for a context group
-     * Used by Platform Windows.
-     * @param { string } contextGroupId - The id of context group you wish to get display info for.
-     * @return { Promise<ContextGroupInfo>}
-     * @tutorial interop.getInfoForContextGroup
+     *
+     * @remarks Used by Platform Windows.
+     * @param contextGroupId - The id of context group you wish to get display info for.
+     *
+     * @example
+     * ```js
+     * fin.me.interop.getInfoForContextGroup('red')
+     *     .then(contextGroupInfo => {
+     *         console.log(contextGroupInfo.displayMetadata.name)
+     *         console.log(contextGroupInfo.displayMetadata.color)
+     *     })
+     * ```
      */
     getInfoForContextGroup(contextGroupId: string): Promise<OpenFin.ContextGroupInfo | undefined>;
     /**
      * Sends an intent to the Interop Broker to resolve.
-     * @param { Intent } intent - The combination of an action and a context that is passed to an application for resolution.
-     * @return { Promise<unknown>}
-     * @tutorial interop.fireIntent
+     * @param intent - The combination of an action and a context that is passed to an application for resolution.
+     *
+     * @example
+     * ```js
+     * // View wants to fire an Intent after a user clicks on a ticker
+     * tickerElement.on('click', (element) => {
+     *     const ticker = element.innerText;
+     *     const intent = {
+     *         name: 'ViewChart',
+     *         context: {type: 'fdc3.instrument', id: { ticker }}
+     *     }
+     *
+     *     fin.me.interop.fireIntent(intent);
+     * })
+     * ```
      */
     fireIntent<T = unknown>(intent: OpenFin.Intent): Promise<T>;
     /**
      * Adds an intent handler for incoming intents. The last intent sent of the name subscribed to will be received.
-     * @param { IntentHandler } handler - Registered function meant to handle a specific intent type.
-     * @param { string } intentName - The name of an intent.
-     * @return { Promise<Subscription> }
-     * @tutorial interop.registerIntentHandler
+     * @param handler - Registered function meant to handle a specific intent type.
+     * @param intentName - The name of an intent.
+     *
+     * @example
+     * ```js
+     * const intentHandler = (intent) => {
+     *     const { context } = intent;
+     *     myViewChartHandler(context);
+     * };
+     *
+     * const subscription = await fin.me.interop.registerIntentHandler(intentHandler, 'ViewChart');
+     *
+     * function myAppCloseSequence() {
+     *     // to unsubscribe the handler, simply call:
+     *     subscription.unsubscribe();
+     * }
+     * ```
      */
     registerIntentHandler(handler: OpenFin.IntentHandler, intentName: string, options?: any): Promise<{
         unsubscribe: () => Promise<void>;
@@ -230,48 +368,134 @@ export declare class InteropClient extends Base {
     /**
      * Gets the last context of the Context Group currently subscribed to. It takes an optional Context Type and returns the
      * last context of that type.
-     * @param { string } [contextType]
-     * @return { Promise<Context> }
-     * @tutorial interop.getCurrentContext
+     * @param contextType
+     *
+     * @example
+     * ```js
+     * await fin.me.interop.joinContextGroup('yellow');
+     * await fin.me.interop.setContext({ type: 'instrument', id: { ticker: 'FOO' }});
+     * const currentContext = await fin.me.interop.getCurrentContext();
+     *
+     * // with a specific context
+     * await fin.me.interop.joinContextGroup('yellow');
+     * await fin.me.interop.setContext({ type: 'country', id: { ISOALPHA3: 'US' }});
+     * await fin.me.interop.setContext({ type: 'instrument', id: { ticker: 'FOO' }});
+     * const currentContext = await fin.me.interop.getCurrentContext('country');
+     * ```
      */
     getCurrentContext(contextType?: string): Promise<OpenFin.Context>;
     /**
      * Get information for a particular Intent from the Interop Broker.
-     * @param { InfoForIntentOptions } options
-     * @return { Promise<unknown> }
-     * @tutorial interop.getInfoForIntent
+     *
+     * @remarks To resolve this info, the function handleInfoForIntent is meant to be overridden in the Interop Broker.
+     * The format for the response will be determined by the App Provider overriding the function.
+     *
+     * @param options
+     *
+     * @example
+     * ```js
+     * const intentInfo = await fin.me.interop.getInfoForIntent('ViewChart');
+     * ```
      */
     getInfoForIntent<T = unknown>(options: OpenFin.InfoForIntentOptions): Promise<T>;
     /**
      * Get information from the Interop Broker on all Intents that are meant to handle a particular context.
-     * @param { Context } context
-     * @return { Promise<unknown> }
-     * @tutorial interop.getInfoForIntentsByContext
+     *
+     * @remarks To resolve this info, the function handleInfoForIntentsByContext is meant to be overridden in the Interop Broker.
+     * The format for the response will be determined by the App Provider overriding the function.
+     *
+     * @param context
+     *
+     * @example
+     * ```js
+     * tickerElement.on('click', (element) => {
+     *     const ticker = element.innerText;
+     *
+     *     const context = {
+     *         type: 'fdc3.instrument',
+     *         id: {
+     *             ticker
+     *         }
+     *     }
+     *
+     *     const intentsInfo = await fin.me.interop.getInfoForIntentByContext(context);
+     * })
+     * ```
      */
     getInfoForIntentsByContext<T = unknown>(context: OpenFin.Context): Promise<T>;
     /**
      * Sends a Context that will be resolved to an Intent by the Interop Broker.
      * This context accepts a metadata property.
-     * @param { ContextForIntent } context
-     * @return { Promise<unknown> }
-     * @tutorial interop.fireIntentForContext
+     *
+     * @remarks To resolve this info, the function handleFiredIntentByContext is meant to be overridden in the Interop Broker.
+     * The format for the response will be determined by the App Provider overriding the function.
+     *
+     * @param context
+     *
+     * @example
+     * ```js
+     * tickerElement.on('click', (element) => {
+     *     const ticker = element.innerText;
+     *
+     *     const context = {
+     *         type: 'fdc3.instrument',
+     *         id: {
+     *             ticker
+     *         }
+     *     }
+     *
+     *     const intentResolution = await fin.me.interop.fireIntentForContext(context);
+     * })
+     * ```
      */
     fireIntentForContext<T = unknown>(context: OpenFin.ContextForIntent): Promise<T>;
     /**
      * Join the current entity to session context group `sessionContextGroupId` and return a sessionContextGroup instance.
      * If the sessionContextGroup doesn't exist, one will get created.
-     * Session Context Groups do not persist between runs and aren't present on snapshots.
-     * @param { string } sessionContextGroupId - Id of the context group.
-     * @return { Promise<SessionContextGroup>}
-     * @tutorial interop.joinSessionContextGroup
+     *
+     * @remarks Session Context Groups do not persist between runs and aren't present on snapshots.
+     * @param sessionContextGroupId - Id of the context group.
+     *
+     * @example
+     * Say we want to have a Session Context Group that holds UI theme information for all apps to consume:
+     *
+     * My color-picker View:
+     * ```js
+     *     const themeSessionContextGroup = await fin.me.interop.joinSessionContextGroup('theme');
+     *
+     *     const myColorPickerElement = document.getElementById('color-palette-picker');
+     *     myColorPickerElement.addEventListener('change', event => {
+     *         themeSessionContextGroup.setContext({ type: 'color-palette', selection: event.value });
+     *     });
+     * ```
+     *
+     * In other views:
+     * ```js
+     *     const themeSessionContextGroup = await fin.me.interop.joinSessionContextGroup('theme');
+     *
+     *     const changeColorPalette = ({ selection }) => {
+     *         // change the color palette to the selection
+     *     };
+     *
+     *     // If the context is already set by the time the handler was set, the handler will get invoked immediately with the current context.
+     *     themeSessionContextGroup.addContextHandler(changeColorPalette, 'color-palette');
+     * ```
      */
     joinSessionContextGroup(sessionContextGroupId: string): Promise<OpenFin.SessionContextGroup>;
     /**
      * Register a listener that is called when the Interop Client has been disconnected from the Interop Broker.
      * Only one listener per Interop Client can be set.
      * @param listener
-     * @return { Promise<void> }
-     * @tutorial interop.onDisconnection
+     *
+     * @example
+     * ```js
+     * const listener = (event) => {
+     *     const { type, topic, brokerName} = event;
+     *     console.log(`Disconnected from Interop Broker ${brokerName} `);
+     * }
+     *
+     * await fin.me.interop.onDisconnection(listener);
+     * ```
      */
     onDisconnection(listener: OpenFin.InteropClientOnDisconnectionListener): Promise<void>;
     static ferryFdc3Call(interopClient: OpenFin.InteropClient, action: string, payload?: any): Promise<any>;