Add event listeners (for non-context events) to the Desktop Agent API (e.g. for changes to the current User channel)

[kriswest]

Enhancement Request

Use Case:

Typical Desktop Agent implementations for containers allow the end user to set the current User Channel for an app through an appropriate UX. However, applications may also implement their own channel management UX, by gathering details of the channels with fdc3.getUserChannels and effecting changes by calling the fdc3.joinUserChannel and fdc3.leaveCurrentChannel. There is currently no support for listening to changes to the current channel setting - which may be made outside of the application (e.g. via a channel selection menu on the window titlebar or other chrome), making it difficult to update any built-in UI for changes made. To help these use cases to work together, and to enable other use cases where the application's behaviour changes once it is linked to a channel, an event listener for channel changes is needed.

Additionally, (and as discussed at #1106) it is anticipated that FDC3 for the web will increase the need for the ability to listen for changes, as channel selector might be implemented in a number of forms (e.g. floating channel selector rendered within the window, in an outer window (where the application is embedded in an ifrmae within the window), etc..

As discussed at #1160 and #1196, the current proposal is to add a generic addEventListener function, for future-proofing against future events (other than context and intent listeners which have their own API signatures) being added to the FDC3 API. A number of FDC3 participants noted that connection events may be useful for FDC3 in a Web browser (loss of Connection, DA was closed etc.).

Proposed function:

/** Register a handler for events from the Desktop Agent. Whenever the handler function 
 * is called it will be passed an event object with details related to the event.
 * @parm {FDC3EventType  | null} type If non-null, only events of the specified type will be received by the handler. 
 * @param {EventHandler} handler A function that events received will be passed to. 
 */
addEventListener(type: FDC3EventType  | null, handler: EventHandler): Promise<Listener>;

/** Type representing a handler function for events from the Desktop Agent. 
 * @param {FDC3Event} event The handler function will be passed an `FDC3Event` Object 
 * providing details of the event (such as a change of channel membership for the app) as the only 
 * parameter.
 */
type EventHandler = (event: FDC3Event) => void;

/**
 * Enumeration defining the types of (non-context and non-intent) events that may be received
   via the FDC3 API's `addEventListener` function. 
 */
enum FDC3EventType = {
  USER_CHANNEL_CHANGED = "USER_CHANNEL_CHANGED"
}

/**
 * Type representing the format of event objects that may be received
   via the FDC3 API's `addEventListener` function. 
 */
type FDC3Event = {
  readonly type: FDC3EventType;
  readonly details: any;
}

/**
 * Type representing the format of event USER_CHANNEL_CHANGED objects
 */
type FDC3ChannelChangedEvent extends FDC3Event {
  readonly type: FDC3EventType.USER_CHANNEL_CHANGED;
  readonly details: {
    currentChannelId: string | null
  };
}

[kriswest]

Reviewed at:

• #1137 And agreed to push to SWG at its next meeting for discussion and hopefully approval.

[kriswest]

Action item from SWG meeting:

• @kriswest update the proposal for https://github.com/finos/FDC3/issues/1136 as discussed (generic addEventListener function for future proofing) and add to a future meeting agenda for further discussion.

[kriswest]

Proposal updated to a generic event listener function (for future proofing in case we introduce additional events - as discussed at #1160).

For posterity the original proposal was:

/** Register a handler for changes to the current User channel. Whenever the handler is called
 * it will be passed the updated channel membership for the application.
 */
addUserChannelChangeListener(handler: ChannelChangeHandler): Promise<Listener>;

/** Type representing a handler function for User channel membership changes. 
 * @param {Channel | null} currentChannel The handler function will be passed the current channel 
 * membership for the application as the only parameter, or null if the app is not a member of any 
 * User channels.
 */
type UserChannelChangeHandler = (currentChannel: Channel | null) => void;