src/InsightProviderInterface.js

/**
 * Interface each ipro.js has to implement
 * @interface
 */
export default class InsightProvider {

  /**
   * Creates an instance of an ipro
   * @param  {InsightProviderOptions} insightProviderOptions create options
   * @return {InsightProvider|Promise<InsightProvider>} returns instance or Promise of an instance of InsightProvider
   */
  static create(insightProviderOptions) {}

  /**
   * @typedef {Object} InsightProviderOptions
   * @desc Options for creating an ipro
   * @property {string} baseUrl - The base url of the ipro. This is the absolute path or url under which the ipro.js is externally exposed via pdms-router.
   *    For example if the ipro.js is exposed under /ipro/work-activity/ipro.js baseUrl shall contain `/ipro/work-activity`. Commonly baseUrl will contain the path taken from `serviceUrl` which the ipro used to register
   *    at service catalog. An ipro's UI can use the `baseUrl` to load assets / files relative to it's own ipro.js location. E.g. `baseUrl` + '/assets/mycss.css` will resolve to `/ipro/work-activity/assets/mycss.css`.
   *    It's the applications' responsibility to determine the `baseUrl` of an ipro and pass it in as option for the construction of the ipro.
   * @property {Size} [size] - The size of an ipro inside an application. This is the size the application 'asks' the ipro to render itself, so that it exactly fits in the uiContainer provided by the application.
   * @property {string} [locale] - The locale which an ipro is supposed to use. If not provided the ipro has to determine the locale by itself or use an ipro specific default.
   * @property {Element} uiContainer - The DOM element into which the ipro is requested to render / place itself.
   * @property {Configuration} [config] - The requested configuration / variant of the ipro.
   * @property {string} [variantId] - The variantId an ipro should load. This is to be consumed by variant management enabled ipros. Variant management enabled ipros should not consume the older `config.id` property anymore!
   * @property {ContextChangeHandler} [contextChangeHandler] - (deprecated) The contextChangeHandler callback function.
   * @property {IntentHandler} [intentHandler] - (deprecated) The intentHandler callback function (depricated with v2.1.0).
   * @property {IntentManager} [intentManager] - intentManager to execute intents.
   */

  /**
   * @typedef {Object} Configuration
   * The requested configuration / variant of the ipro. Most ipros can be configured differently, for example to behave differently in AHCC versus another application. The config.id is an identifier for a particular
   * configuration set the application wants the ipro to load. As of PDMS 1.0 FP02 AHCC for example will always populate config.id with the value `com.sap.pdms.app.ahcc` so that the ahcc specific configuration an an ipro is loaded.
   * If an ipro has no ability to handle and store different configurations it can simply ignore this property.
   * If an application passes undefined or null as `config.id`, the ipro should either:
   * - load a default configuration by itself
   * - throw an Exception / reject a Promise with the error message that no `config.id` property was passed by the application even though it's required.
   * If an application passes a config.id which is invalid or not configured for the given ipro, the ipro should:
   * - throw an Exception / reject a Promise with an error message that indicaets the given `config.id` is not yet configured for this ipro.
   * @property {string} id - The id of an ipro configuration
   */

  /**
   * Gets the metadata of an ipro
   * @return {InsightProviderMetadata} The metadata of an InsightProvider
   */
  static getMetadata() {}
  /**
   * @typedef {Object} InsightProviderMetadata
   * @desc The metadata of an ipro.
   * @property {!string} apiVersion - The API version of an ipro ui. This document describes API version "3.0.0". `apiVersion` adheres to [semantic versioning](http://semver.org/).
   * @property {!string} type - The unique type id of an ipro. This should match the `ID` field in the `mtad.yaml` file. E.g. `com.sap.pdms.ipro.api.3dviz`.
   * @property {string} [uiFramework] - defines the ui framework used by the implementation. Possible values are sap.pdms.ipro.api.Framework.NATIVE (default) and sap.pdms.ipro.api.Framework.UI5.
   * @property {InsightProviderDataInterface} [dataInterface] - <Experimental> Defines the data interface of an ipro.
   * @property {Feature} [features] - <Experimental> The supported features of an ipro.
   * @property {Size} [preferredSize] - <Experimental> The preferred size of an ipro.
   */

  /**
   * @typedef {Object} InsightProviderDataInterface
   * @experimental Not actively used by any application as of PDMS 1.0 FP02.
   * @desc The data input and output for an ipro. Whenever the context for an EntityType listed in
   * `input` has changed the application will call the ipro `setContext` method to pass in the new context.
   * By adding a EntityType to `output` an ipro signals to an application that it might change the context
   * for that EntityType. Declaring `input` and `output` enables an application to discover possible data flows
   * between ipros. An `output` context of one ipro can be declared as an `input` context of another.
   * Declaring a `InsightProviderDataInterface` is optional. If not declared the following
   * `InsightProviderDataInterface` is assumed by default:
   * ```js
   * {
   *  input: ['PrimaryObject'],
   *  output: ['PrimaryObject']
   * }
   * ```
   * @property {Array<EntityType>} [input]
   * @property {Array<EntityType>} [output]
   */

  /**
   * getContext allows an application to query the context of an ipro.
   * @param {ContextQuery} contextQuery - The context query object
   * @return {Context | Promise<Context>} - Context result or a promise resolving with a context result.
   */
  getContext(contextQuery) {}

  /**
   * This is called from the application to set a new context (e.g. the `assetIds` / `primaryObjects`) that an ipro should
   * analyze and display. For most ipros that means they will apply a filter, make a backend ajax request and display the data associated with the given context.
   * The passed `contextResult` parameter can have contexts of different entity types. The ipro should only react to the entitytypes it supports and simply ignore
   * the other given entity types.
   *
   * @param  {Context} context The new context for the ipro.
   * @return {void|Promise<void>} - Return void synchronously or return a Promise<void> that is rejected or resolved once all async operations (e.g. backend requests, onAfterRendering) are completed.
   */
  setContext(context) {}

  /**
   * Called by an application to enable an ipro to release
   * any resources before being removed from the application.
   *
   * @return {void}
   */
  destroy() {}

  /**
   * Gets the `uiContainer` DOM element. This element has been previously passed into the 'create' factory function of the ipro class.
   *
   * @return {Element} - The parent DOM element / container of the ipro
   */
  getUiContainer() {}

  /**
   * @deprecated since version 3.0.0
   * 
   * Sets callback function to notify an application whenever the context of a given EntityType has changed. insightProvider argument of the function is the ipro that has changed the context. The contextQuery argument specifies which context has been changed. In a typical immplementation of this function an application will evaluate which context has been changed, call the getContext method of insightProvider to retrieve the new context, and then call setContext of interested ipros to pass in the new context.
   * @param {ContextChangeHandler} contextChangeHandler - The context change handler function.
   * @return {void}
   */
  setContextChangeHandler(contextChangeHandler) {}

  /**
   * @deprecated since version 3.0.0
   * 
   * returns the current contextChangeHandler.
   * @return {ContextChangeHandler} - The context change handler function
   */
  getContextChangeHandler() {}

  /**
   * @deprecated since version 3.0.0
   * 
   * Sets callback function to notify an application whenever an ipro communicates an intent.
   * An intent is an action that an ipro wants to trigger without knowing the exact details of that action.
   * The one intent currently being defined is sap.pdms.ipro.api.StandardIntent.NAVIGATE_TO_CONTEXT.
   * For instance, an ipro might expose a "Details" button to allow the user to navigate to the details page for a given EntityType.
   * The ipro does not know what would be a suitable details page for this EntityType.
   * So it communicates to the application the intent to navigate and then it is up to the application to implement the actual navigation.
   * An intent can be thought of as an action whose implementation details are unknown to the ipro and thus represents an additional level of decoupling between actors expressing an intent and actors reacting to it.
   * insightProvider argument is the ipro that has expressed the intent. intentType defines the type of intent.
   * The only current intent type is sap.pdms.ipro.api.StandardIntent.NAVIGATE_TO_CONTEXT.
   * intentParams provides additional information to the intent depending on the intentType.
   *
   * @param  {IntentHandler} intentHandler - The intent handler function
   * @return {void}
   */
  setIntentHandler(intentHandler) {}

  /**
   * @deprecated since version 3.0.0
   * 
   * Returns the current intentHandler.
   * @return {IntentHandler} - The intent handler function
   */
  getIntentHandler() {}

  /**
   * <Optional Method> Sets the size of the ipro. setSize will be called by the application after the uiContainer has been resized.
   * @param {Size} size
   */
  setSize(size) {}

  /**
   * <Optional Method> Gets the size of the ipro.
   * @return {Size} - The size of an ipro
   */
  getSize() {}
  /**
   * @typedef {Object} Size
   * @desc The size of an ipro
   * @property {number} width
   * @property {number} height
   */
}

/**
 * @typedef {string} EntityType
 * @desc An EntityType as string. E.g. `Asset`, `DerivedSignal`.
 */

/**
 * @typedef {string} EntityId
 * @desc An identifier for a single entity. E.g. an asset with id `LC-5001`.
 */

/**
 * @typedef {Object} EntityObject
 * @desc An object which describes an entity. The object structure is specific to every {@link EntityType}.
 */

/**
 * @typedef {string} ContextSelector
 * @desc Defines what result set should be returned from a `getContext` call.
 * Possible values are: `sap.pdms.ipro.api.ContextSelector.SELECTED` or `sap.pdms.ipro.api.ContextSelector.ALL`.
 * `sap.pdms.ipro.api.ContextSelector.SELECTED` indicates that the ipro is supposed to
 * return all entities that are currently selected usually through a user interaction. E.g. In table based ipro this
 * refers normally to the selected rows or more specifically the context of those selected rows (e.g. all `primaryObjectsId`s associated with the selected context).
 * `sap.pdms.ipro.api.ContextSelector.ALL` indicates that the ipro is supposed to return all entities.
 */

/**
 * @typedef {string} ContextResultType
 * @desc Indicates the return type of the context query. Possible values
 * are sap.pdms.ipro.api.ContextReturnType.ID or sap.pdms.ipro.api.ContextReturnType.OBJECT.
 * If sap.pdms.ipro.api.ContextReturnType.OBJECT is specified an array of ids is returned.
 * If sap.pdms.ipro.api.ContextReturnType.OBJECT is specified an array of plain JavaScript objects is returned.
 */

/**
 * @typedef {Object} Pagination
 * @experimental Not actively used by any application or ipro as of PDMS 1.0 FP02.
 * @desc Allows to restrict the number of entities returned from a context query.
 * This parameter implies that the context query results are returned in a specific order.
 * @property {number} skip - Specifies the number of entities according to that order of the list.
 * @property {number} top - Defines the offset.
 */

/**
 * @typedef {Object} ContextQueryOptions
 * @desc The options for a context query for a specific {@link EntityType}.
 * @property {ContextSelector} selector - Choose which slice of the overall ipro context should be returned from `getContext` call. It's similar to a filter.
 * Is either `sap.pdms.ipro.api.ContextSelector.SELECTED` or `sap.pdms.ipro.api.ContextSelector.ALL`.
 * @property {ContextResultType} [contextResultType] - The type / structure an ipro should return for the given contextQuery.
 * @property {Pagination} [pagination] - Allows to limit the resultset size and skip a number of elements in the resultset.
 */

/**
 * @typedef {Object<EntityType, ContextQueryOptions>} ContextQuery
 * @desc An Object whose keys are the {@link EntityType}s to query and whose values are the {@link ContextQueryOptions} for the requested entity.
 * In general the ContextQuery expresses which information the application requests from the ipro.
 * @example {PrimaryObject: {selector: sap.pdms.ipro.api.ContextSelector.SELECTED}}
 */

/**
 * @typedef {Object<EntityType, Array<EntityId>|Array<EntityObject>>} Context
 * @desc The result of a context query. A `ContextResult` is an object whose keys are {@link EntityType}s and whose values are {@link Array}s of {@link EntityId}s or {@link EntityObject}s
 * @example <caption>Sample context query result</caption>
 * {
 *  PrimaryObject: ['1000', '1001', '1003'],
 *  DerivedSignal: [{foo: 'bar'}, {hello: 'world'}]
 * }
 */

/**
 * @typedef {Object} Feature
 * @experimental
 * @desc The supported features of an ipro.
 * @property {boolean} [pagination]
 */

/**
 * @typedef {function(ipro: InsightProvider, contextQuery: ContextQuery): void} ContextChangeHandler
 * @desc Callback function to inform an application that the context of an insightProvider has changed.
 * In a typical implementation of this function an application will evaluate which context has changed,
 * call the `getContext` method of `insightProvider` to retrieve the new context,
 * and then call `setContext` of interested ipros to pass in the new context.
 * {Object} insightProvider - The ipro that has changed the context
 * {ContextQuery} contextQuery - The context that has changed.
 */

/**
 * @typedef {function(): void} IntentHandler
 * @desc Callback function to inform an application of an intent of an insightProvider.
 * An intent is an action that an ipro wants to trigger without knowing the exact details of that action.
 * The one intent currently being defined is sap.pdms.ipro.api.StandardIntent.NAVIGATE_TO_CONTEXT.
 * For instance, an ipro might expose a "Details" button to allow the user to navigate to the details page
 * for a given EntityType. The ipro does not know what would be a suitable details page for this EntityType.
 * So it communicates to the application the intent to navigate and then it is up to the application to
 * implement the actual navigation. An intent can be thought of as an action whose implementation details
 * are unknown to the ipro and thus represents an additional level of decoupling between actors expressing
 * an intent and actors reacting to it.
 * @param {Object} insightProvider - The ipro that has an intent
 * @param {StandardIntent|string} intentType - The type of the intent
 * @param {IntentParams} intentParams - The intent parameters
 */

/**
 * @typedef {any} IntentParams
 * @desc The intent specific parameters. The expected parameter structure has to be defined by the intent type.
 * @example <caption>Parameter for an intent of type `sap.pdms.ipro.api.StandardIntent.NAVIGATE_TO_CONTEXT`</caption>
 * {PrimaryObject: '1001'}
 */