@openfin/core 33.76.27 → 33.76.36

package/src/api/interop/InteropClient.js

@@ -89,21 +89,21 @@ const utils_1 = require("./utils");
 /**
  * @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}
@@ -155,12 +155,11 @@ const utils_1 = require("./utils");
  *  * {@link InteropClient#getInfoForContextGroup getInfoForContextGroup(contextGroupId)}
  *  * {@link InteropClient#getAllClientsInContextGroup getAllClientsInContextGroup(contextGroupId)}
  *
-
- *
- * @hideconstructor
- * @class
  */
 class InteropClient extends base_1.Base {
+    /**
+     * @internal
+     */
     constructor(wire, name, interopConfig = {}) {
         super(wire);
         _InteropClient_clientPromise.set(this, void 0);
@@ -177,9 +176,22 @@ class InteropClient extends base_1.Base {
     */
     /**
      * 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)
+     * })
+     * ```
      */
     async setContext(context) {
         this.wire.sendAction('interop-client-set-context').catch((e) => {
@@ -189,11 +201,63 @@ class InteropClient extends base_1.Base {
         return client.dispatch('setContext', { context });
     }
     /**
-     * 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')
+     * ```
      */
     async addContextHandler(handler, contextType) {
         this.wire.sendAction('interop-client-add-context-handler').catch((e) => {
@@ -227,8 +291,17 @@ class InteropClient extends base_1.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)
+     *             })
+     *         })
+     * ```
      */
     async getContextGroups() {
         this.wire.sendAction('interop-client-get-context-groups').catch((e) => {
@@ -240,14 +313,26 @@ class InteropClient extends base_1.Base {
     /**
      * 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)
+     *     })
+     * ```
      */
     async joinContextGroup(contextGroupId, target) {
         this.wire.sendAction('interop-client-join-context-group').catch((e) => {
@@ -263,9 +348,20 @@ class InteropClient extends base_1.Base {
      * 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)
+     *     })
+     * ```
      */
     async removeFromContextGroup(target) {
         this.wire.sendAction('interop-client-remove-from-context-group').catch((e) => {
@@ -276,10 +372,19 @@ class InteropClient extends base_1.Base {
     }
     /**
      * 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)
+     *     })
+     * ```
      */
     async getAllClientsInContextGroup(contextGroupId) {
         this.wire.sendAction('interop-client-get-all-clients-in-context-group').catch((e) => {
@@ -293,10 +398,18 @@ class InteropClient extends base_1.Base {
     }
     /**
      * 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)
+     *     })
+     * ```
      */
     async getInfoForContextGroup(contextGroupId) {
         this.wire.sendAction('interop-client-get-info-for-context-group').catch((e) => {
@@ -310,9 +423,21 @@ class InteropClient extends base_1.Base {
     }
     /**
      * 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);
+     * })
+     * ```
      */
     async fireIntent(intent) {
         this.wire.sendAction('interop-client-fire-intent').catch((e) => {
@@ -323,10 +448,23 @@ class InteropClient extends base_1.Base {
     }
     /**
      * 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();
+     * }
+     * ```
      */
     async registerIntentHandler(handler, intentName, options) {
         this.wire.sendAction('interop-client-register-intent-handler').catch((e) => {
@@ -351,9 +489,20 @@ class InteropClient extends base_1.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');
+     * ```
      */
     async getCurrentContext(contextType) {
         this.wire.sendAction('interop-client-get-current-context').catch((e) => {
@@ -364,9 +513,16 @@ class InteropClient extends base_1.Base {
     }
     /**
      * 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');
+     * ```
      */
     async getInfoForIntent(options) {
         this.wire.sendAction('interop-client-get-info-for-intent').catch((e) => {
@@ -377,9 +533,27 @@ class InteropClient extends base_1.Base {
     }
     /**
      * 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);
+     * })
+     * ```
      */
     async getInfoForIntentsByContext(context) {
         this.wire.sendAction('interop-client-get-info-for-intents-by-context').catch((e) => {
@@ -391,9 +565,27 @@ class InteropClient extends base_1.Base {
     /**
      * 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);
+     * })
+     * ```
      */
     async fireIntentForContext(context) {
         this.wire.sendAction('interop-client-fire-intent-for-context').catch((e) => {
@@ -405,10 +597,34 @@ class InteropClient extends base_1.Base {
     /**
      * 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');
+     * ```
      */
     async joinSessionContextGroup(sessionContextGroupId) {
         try {
@@ -436,8 +652,16 @@ class InteropClient extends base_1.Base {
      * 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);
+     * ```
      */
     async onDisconnection(listener) {
         this.wire.sendAction('interop-client-add-ondisconnection-listener').catch((e) => {

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

@@ -7,8 +7,8 @@ export default class SessionContextGroupClient extends Base {
     constructor(wire: Transport, client: Promise<OpenFin.ChannelClient>, id: string);
     /**
      * Sets a context for the session context group.
-     * @param { Context } context - New context to set.
-     * @return { Promise<void> }
+     * @param context - New context to set.
+     *
      * @tutorial interop.setContext
      */
     setContext(context: OpenFin.Context): Promise<void>;

package/src/api/interop/SessionContextGroupClient.js

@@ -23,8 +23,8 @@ class SessionContextGroupClient extends base_1.Base {
     }
     /**
      * Sets a context for the session context group.
-     * @param { Context } context - New context to set.
-     * @return { Promise<void> }
+     * @param context - New context to set.
+     *
      * @tutorial interop.setContext
      */
     async setContext(context) {

package/src/api/interop/fdc3/documentationStub.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Prior to the move to TypeDoc, OpenFin maintained a copy of the FDC3 documentation under this namespace.  To avoid
+ * duplication, these types have been removed from the OpenFin documentation.
+ *
+ * These types can be found in the official FDC3 documentation at https://fdc3.finos.org/docs/api/ref/Types.
+ *
+ * @packageDocumentation
+ */
+/**
+ * @hidden
+ *
+ * Export required to allow import into typedoc entry point.
+ */
+export declare const placeholder = "placeholder";

package/src/api/interop/fdc3/documentationStub.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Prior to the move to TypeDoc, OpenFin maintained a copy of the FDC3 documentation under this namespace.  To avoid
+ * duplication, these types have been removed from the OpenFin documentation.
+ *
+ * These types can be found in the official FDC3 documentation at https://fdc3.finos.org/docs/api/ref/Types.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.placeholder = void 0;
+/**
+ * @hidden
+ *
+ * Export required to allow import into typedoc entry point.
+ */
+exports.placeholder = 'placeholder';