@openfin/core 33.76.27 → 33.76.36

package/src/api/platform/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Entry point for the OpenFin Platform namespace.
+ *
+ * Because TypeDoc does not currently support multiple modules with the same name, the module alias "PlatformModule" is used for
+ * the module containing static members of the `Platform` namespace (available under `fin.Platform`), while `Platform` documents
+ * instances of the OpenFin `Platform` class.
+ *
+ * @packageDocumentation
+ */
 import PlatformModule from './Factory';
 export default PlatformModule;
 export * from './Instance';

package/src/api/platform/index.js

@@ -1,4 +1,13 @@
 "use strict";
+/**
+ * Entry point for the OpenFin Platform namespace.
+ *
+ * Because TypeDoc does not currently support multiple modules with the same name, the module alias "PlatformModule" is used for
+ * the module containing static members of the `Platform` namespace (available under `fin.Platform`), while `Platform` documents
+ * instances of the OpenFin `Platform` class.
+ *
+ * @packageDocumentation
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);

package/src/api/platform/layout/Factory.d.ts

@@ -2,99 +2,76 @@ import type * as OpenFin from '../../../OpenFin';
 import { Base } from '../../base';
 import { Layout } from './Instance';
 type InitLayoutOptions = OpenFin.InitLayoutOptions;
-/**
- * @PORTED
- * InitLayoutOptions interface
- * @typedef { object } InitLayoutOptions
- * @property { string } [containerId] The id attribute of the container where the window's Layout should be initialized.  If not provided
- * then an element with id `layout-container` is used. We recommend using a div element.
- */
-/**
- * @PORTED
- * PresetLayoutOptions interface
- * @typedef { object } PresetLayoutOptions
- * @property { LayoutPresetTypes } presetType Which preset layout arrangement to use.
- * The preset options are `columns`, `grid`, `rows`, and `tabs`.
- */
-/**
- * LayoutConfig interface
- * @typedef { object } LayoutConfig
- * @property { Array<LayoutItem> } content Content of the layout.  There can only be one top-level LayoutItem in the content array.
- * We do not recommend trying to build Layouts or LayoutItems by hand and instead use calls such as {@link Platform#getSnapshot getSnapshot}
- * or our {@link https://openfin.github.io/golden-prototype/config-gen Layout Config Generation Tool }.
- * @property { LayoutSettings } settings Configuration for certain Layout behaviors. See the LayoutSettings interface.
- */
-/**
- * @PORTED
- * LayoutItem Interface
- * @typedef { object } LayoutItem Represents the arrangement of Views within a Platform window's Layout.  We do not recommend trying
- * to build Layouts or LayoutItems by hand and instead use calls such as {@link Platform#getSnapshot getSnapshot} or our
- * {@link https://openfin.github.io/golden-prototype/config-gen Layout Config Generation Tool }.
- * @property { string } type The type of the item. Possible values are 'row', 'column', 'stack', and 'component'.
- * @property { Array<LayoutItem> } [content] An array of configurations for items that will be created as children of this item.
- * @property { string } [componentName] Only a `component` type will have this property and it should be set to `view`.
- * @property { View~options } [componentState] Only a `component` type will have this property and it represents the view
- * options of a given component.
- */
-/**
- * @PORTED
- * LayoutSettings Interface
- * @typedef { object } LayoutSettings Represents a potential ways to customize behavior of your Layout
- * @property { boolean } [constrainDragToHeaders=false] Limits the area to which tabs can be dragged.
- * If true, stack headers are the only areas where tabs can be dropped.
- * @property { boolean } [hasHeaders=true] Turns tab headers on or off.
- * If false, the layout will be displayed with splitters only.
- * @property {object} [newTabButton]
- * Configuration of the Plus button that appears on each tabstrip. Upon pressing, a new tab
- * will be added to the tabstrip with the specified url.
- * @property {string} [newTabButton.url] Specifies the url that opens in the tab created upon pressing the button.
- * @property { boolean } [popoutWholeStack=false] Whether the popout button will only act on the entire stack,
- * as opposed to only the active tab.
- * @property { boolean } [preventDragIn=false] If true, tabs can't be dragged into the window.
- * @property { boolean } [preventDragOut=false] If true, tabs can't be dragged out of the window.
- * @property { boolean } [preventSplitterResize=false] If true, tab contents can't be resized by the user.
- * @property { boolean } [reorderEnabled=true] If true, the user can re-arrange the layout by
- * dragging items by their tabs to the desired location.
- * @property { boolean } [showCloseIcon=false] Whether to show the close button on stack header
- * (not to be confused with close button on every tab).
- * @property { boolean } [showMaximiseIcon=false] Whether to show the maximize button on stack header.
- * The button will maximize the current tab to fill the entire window.
- * @property { boolean } [showPopoutIcon=false] Whether to show the popout button on stack header.
- * The button will create a new window with current tab as its content.
- * In case `popoutWholeStack` is set to true, all tabs in the stack will be in the new window.
- */
-/**
- * @lends Platform#Layout
- */
 export declare class LayoutModule extends Base {
     #private;
     /**
      * Asynchronously returns a Layout object that represents a Window's layout.
-     * @param { Identity } identity
-     * @return {Promise.<Layout>}
-     * @tutorial Layout.wrap
+     * @param identity
+     *
+     * @example
+     * ```js
+     * let windowIdentity;
+     * if (!fin.me.isWindow) {
+     *     windowIdentity = fin.me.identity;
+     * } else if (fin.me.isView) {
+     *     windowIdentity = (await fin.me.getCurrentWindow()).identity;
+     * } else {
+     *     throw new Error('Not running in a platform View or Window');
+     * }
+     *
+     * const layout = await fin.Platform.Layout.wrap(windowIdentity);
+     * // Use wrapped instance to control layout, e.g.:
+     * const layoutConfig = await layout.getConfig();
+     * ```
      * @static
      */
     wrap(identity: OpenFin.Identity): Promise<OpenFin.Layout>;
     /**
      * Synchronously returns a Layout object that represents a Window's layout.
-     * @param { Identity } identity
-     * @return {Layout}
-     * @tutorial Layout.wrapSync
+     * @param identity
+     *
+     * @example
+     * ```js
+     * let windowIdentity;
+     * if (!fin.me.isWindow) {
+     *     windowIdentity = fin.me.identity;
+     * } else if (fin.me.isView) {
+     *     windowIdentity = (await fin.me.getCurrentWindow()).identity;
+     * } else {
+     *     throw new Error('Not running in a platform View or Window');
+     * }
+     *
+     * const layout = fin.Platform.Layout.wrapSync(windowIdentity);
+     * // Use wrapped instance to control layout, e.g.:
+     * const layoutConfig = await layout.getConfig();
+     * ```
      * @static
      */
     wrapSync(identity: OpenFin.Identity): OpenFin.Layout;
     /**
      * Asynchronously returns a Layout object that represents a Window's layout.
-     * @return {Promise.<Layout>}
-     * @tutorial Layout.getCurrent
+     *
+     * @example
+     * ```js
+     * const layout = await fin.Platform.Layout.getCurrent();
+     * // Use wrapped instance to control layout, e.g.:
+     * const layoutConfig = await layout.getConfig();
+     * ```
      * @static
      */
     getCurrent(): Promise<OpenFin.Layout>;
     /**
      * Synchronously returns a Layout object that represents a Window's layout.
-     * @return {Layout}
-     * @tutorial Layout.getCurrentSync
+     *
+     * @remarks Cannot be called from a view.
+     *
+     *
+     * @example
+     * ```js
+     * const layout = fin.Platform.Layout.getCurrentSync();
+     * // Use wrapped instance to control layout, e.g.:
+     * const layoutConfig = await layout.getConfig();
+     * ```
      * @static
      */
     getCurrentSync(): OpenFin.Layout;
@@ -103,8 +80,8 @@ export declare class LayoutModule extends Base {
      * If a containerId is not provided, this method attempts to find an element with the id `layout-container`.
      * A Layout will <a href="tutorial-Layout.DOMEvents.html">emit events locally</a> on the DOM element representing the layout-container.
      * In order to capture the relevant events during Layout initiation, set up the listeners on the DOM element prior to calling `init`.
-     * @param { InitLayoutOptions } [options] - Layout init options.
-     * @return { Promise<Layout> }
+     * @param options - Layout init options.
+     *
      * @static
      * @experimental
      * @tutorial Layout.init

package/src/api/platform/layout/Factory.js

@@ -16,70 +16,6 @@ exports.LayoutModule = void 0;
 /* eslint-disable no-undef, import/prefer-default-export */
 const base_1 = require("../../base");
 const Instance_1 = require("./Instance");
-/**
- * @PORTED
- * InitLayoutOptions interface
- * @typedef { object } InitLayoutOptions
- * @property { string } [containerId] The id attribute of the container where the window's Layout should be initialized.  If not provided
- * then an element with id `layout-container` is used. We recommend using a div element.
- */
-/**
- * @PORTED
- * PresetLayoutOptions interface
- * @typedef { object } PresetLayoutOptions
- * @property { LayoutPresetTypes } presetType Which preset layout arrangement to use.
- * The preset options are `columns`, `grid`, `rows`, and `tabs`.
- */
-/**
- * LayoutConfig interface
- * @typedef { object } LayoutConfig
- * @property { Array<LayoutItem> } content Content of the layout.  There can only be one top-level LayoutItem in the content array.
- * We do not recommend trying to build Layouts or LayoutItems by hand and instead use calls such as {@link Platform#getSnapshot getSnapshot}
- * or our {@link https://openfin.github.io/golden-prototype/config-gen Layout Config Generation Tool }.
- * @property { LayoutSettings } settings Configuration for certain Layout behaviors. See the LayoutSettings interface.
- */
-/**
- * @PORTED
- * LayoutItem Interface
- * @typedef { object } LayoutItem Represents the arrangement of Views within a Platform window's Layout.  We do not recommend trying
- * to build Layouts or LayoutItems by hand and instead use calls such as {@link Platform#getSnapshot getSnapshot} or our
- * {@link https://openfin.github.io/golden-prototype/config-gen Layout Config Generation Tool }.
- * @property { string } type The type of the item. Possible values are 'row', 'column', 'stack', and 'component'.
- * @property { Array<LayoutItem> } [content] An array of configurations for items that will be created as children of this item.
- * @property { string } [componentName] Only a `component` type will have this property and it should be set to `view`.
- * @property { View~options } [componentState] Only a `component` type will have this property and it represents the view
- * options of a given component.
- */
-/**
- * @PORTED
- * LayoutSettings Interface
- * @typedef { object } LayoutSettings Represents a potential ways to customize behavior of your Layout
- * @property { boolean } [constrainDragToHeaders=false] Limits the area to which tabs can be dragged.
- * If true, stack headers are the only areas where tabs can be dropped.
- * @property { boolean } [hasHeaders=true] Turns tab headers on or off.
- * If false, the layout will be displayed with splitters only.
- * @property {object} [newTabButton]
- * Configuration of the Plus button that appears on each tabstrip. Upon pressing, a new tab
- * will be added to the tabstrip with the specified url.
- * @property {string} [newTabButton.url] Specifies the url that opens in the tab created upon pressing the button.
- * @property { boolean } [popoutWholeStack=false] Whether the popout button will only act on the entire stack,
- * as opposed to only the active tab.
- * @property { boolean } [preventDragIn=false] If true, tabs can't be dragged into the window.
- * @property { boolean } [preventDragOut=false] If true, tabs can't be dragged out of the window.
- * @property { boolean } [preventSplitterResize=false] If true, tab contents can't be resized by the user.
- * @property { boolean } [reorderEnabled=true] If true, the user can re-arrange the layout by
- * dragging items by their tabs to the desired location.
- * @property { boolean } [showCloseIcon=false] Whether to show the close button on stack header
- * (not to be confused with close button on every tab).
- * @property { boolean } [showMaximiseIcon=false] Whether to show the maximize button on stack header.
- * The button will maximize the current tab to fill the entire window.
- * @property { boolean } [showPopoutIcon=false] Whether to show the popout button on stack header.
- * The button will create a new window with current tab as its content.
- * In case `popoutWholeStack` is set to true, all tabs in the stack will be in the new window.
- */
-/**
- * @lends Platform#Layout
- */
 class LayoutModule extends base_1.Base {
     constructor() {
         super(...arguments);
@@ -89,8 +25,8 @@ class LayoutModule extends base_1.Base {
          * If a containerId is not provided, this method attempts to find an element with the id `layout-container`.
          * A Layout will <a href="tutorial-Layout.DOMEvents.html">emit events locally</a> on the DOM element representing the layout-container.
          * In order to capture the relevant events during Layout initiation, set up the listeners on the DOM element prior to calling `init`.
-         * @param { InitLayoutOptions } [options] - Layout init options.
-         * @return { Promise<Layout> }
+         * @param options - Layout init options.
+         *
          * @static
          * @experimental
          * @tutorial Layout.init
@@ -111,9 +47,23 @@ class LayoutModule extends base_1.Base {
     }
     /**
      * Asynchronously returns a Layout object that represents a Window's layout.
-     * @param { Identity } identity
-     * @return {Promise.<Layout>}
-     * @tutorial Layout.wrap
+     * @param identity
+     *
+     * @example
+     * ```js
+     * let windowIdentity;
+     * if (!fin.me.isWindow) {
+     *     windowIdentity = fin.me.identity;
+     * } else if (fin.me.isView) {
+     *     windowIdentity = (await fin.me.getCurrentWindow()).identity;
+     * } else {
+     *     throw new Error('Not running in a platform View or Window');
+     * }
+     *
+     * const layout = await fin.Platform.Layout.wrap(windowIdentity);
+     * // Use wrapped instance to control layout, e.g.:
+     * const layoutConfig = await layout.getConfig();
+     * ```
      * @static
      */
     // eslint-disable-next-line class-methods-use-this
@@ -125,9 +75,23 @@ class LayoutModule extends base_1.Base {
     }
     /**
      * Synchronously returns a Layout object that represents a Window's layout.
-     * @param { Identity } identity
-     * @return {Layout}
-     * @tutorial Layout.wrapSync
+     * @param identity
+     *
+     * @example
+     * ```js
+     * let windowIdentity;
+     * if (!fin.me.isWindow) {
+     *     windowIdentity = fin.me.identity;
+     * } else if (fin.me.isView) {
+     *     windowIdentity = (await fin.me.getCurrentWindow()).identity;
+     * } else {
+     *     throw new Error('Not running in a platform View or Window');
+     * }
+     *
+     * const layout = fin.Platform.Layout.wrapSync(windowIdentity);
+     * // Use wrapped instance to control layout, e.g.:
+     * const layoutConfig = await layout.getConfig();
+     * ```
      * @static
      */
     // eslint-disable-next-line class-methods-use-this
@@ -139,8 +103,13 @@ class LayoutModule extends base_1.Base {
     }
     /**
      * Asynchronously returns a Layout object that represents a Window's layout.
-     * @return {Promise.<Layout>}
-     * @tutorial Layout.getCurrent
+     *
+     * @example
+     * ```js
+     * const layout = await fin.Platform.Layout.getCurrent();
+     * // Use wrapped instance to control layout, e.g.:
+     * const layoutConfig = await layout.getConfig();
+     * ```
      * @static
      */
     async getCurrent() {
@@ -155,8 +124,16 @@ class LayoutModule extends base_1.Base {
     }
     /**
      * Synchronously returns a Layout object that represents a Window's layout.
-     * @return {Layout}
-     * @tutorial Layout.getCurrentSync
+     *
+     * @remarks Cannot be called from a view.
+     *
+     *
+     * @example
+     * ```js
+     * const layout = fin.Platform.Layout.getCurrentSync();
+     * // Use wrapped instance to control layout, e.g.:
+     * const layoutConfig = await layout.getConfig();
+     * ```
      * @static
      */
     getCurrentSync() {

package/src/api/platform/layout/Instance.d.ts

@@ -4,53 +4,188 @@ import { Base } from '../../base';
 type Identity = OpenFin.Identity;
 type InitLayoutOptions = OpenFin.InitLayoutOptions;
 type PresetLayoutOptions = OpenFin.PresetLayoutOptions;
-/**
- * @lends Platform#Layout
- */
 export declare class Layout extends Base {
     #private;
+    /**
+     * Initialize the window's Layout.
+     *
+     * @remarks Must be called from a custom window that has a 'layout' option set upon creation of that window.  If a containerId
+     * is not provided, this method attempts to find an element with the id `layout-container`.
+     *
+     * A Layout will emit events locally on the DOM element representing the layout-container. In order to capture the relevant
+     * events during Layout initiation, set up the listeners on the DOM element prior to calling init.
+     *
+     * @example
+     * ```js
+     * // if no options are included, the layout in the window options is initialized in an element with the id `layout-container`
+     * const layout = await fin.Platform.Layout.init();
+     * ```
+     * <br /><br />
+     * # Example
+     * To target a different HTML element use the options object.
+     * ```js
+     * const containerId = 'my-custom-container-id';
+     *
+     * const myLayoutContainer = document.getElementById(containerId);
+     *
+     * myLayoutContainer.addEventListener('tab-created', function(event) {
+     *     const { tabSelector } = event.detail;
+     *     const tabElement = document.getElementById(tabSelector);
+     *     const existingColor = tabElement.style.backgroundColor;
+     *     tabElement.style.backgroundColor = "red";
+     *     setTimeout(() => {
+     *         tabElement.style.backgroundColor = existingColor;
+     *     }, 2000);
+     * });
+     *
+     * // initialize the layout into an existing HTML element with the div `my-custom-container-id`
+     * // the window must have been created with a layout in its window options
+     * const layout = await fin.Platform.Layout.init({ containerId });
+     * ```
+     */
     init: (options?: InitLayoutOptions) => Promise<Layout>;
     identity: Identity;
     private platform;
     wire: Transport;
+    /**
+     * @internal
+     */
     constructor(identity: OpenFin.Identity, wire: Transport);
     /**
      * Returns the configuration of the window's layout.  Returns the same information that is returned for all windows in getSnapshot.
-     * @return { Promise<LayoutConfig> }
-     * @tutorial Layout.getConfig
+     *
+     * @remarks Cannot be called from a View.
+     *
+     *
+     * @example
+     * ```js
+     * const layout = fin.Platform.Layout.getCurrentSync();
+     * // Use wrapped instance to get the layout configuration of the current window's Layout:
+     * const layoutConfig = await layout.getConfig();
+     * ```
      */
     getConfig(): Promise<any>;
     /**
-     * Retrieves the top level content item of the layout.
-     * @return {Promise<TabStack | ColumnOrRow>}
+     * Replaces a Platform window's layout with a new layout.
+     *
+     * @remarks Any views that were in the old layout but not the new layout will be destroyed. Views will be assigned a randomly generated name to avoid collisions.
+     * @example
+     * ```js
+     * let windowIdentity;
+     * if (fin.me.isWindow) {
+     *     windowIdentity = fin.me.identity;
+     * } else if (fin.me.isView) {
+     *     windowIdentity = (await fin.me.getCurrentWindow()).identity;
+     * } else {
+     *     throw new Error('Not running in a platform View or Window');
+     * }
+     *
+     * const layout = fin.Platform.Layout.wrapSync(windowIdentity);
+     *
+     * const newLayout = {
+     *     content: [
+     *         {
+     *             type: 'stack',
+     *             content: [
+     *                 {
+     *                     type: 'component',
+     *                     componentName: 'view',
+     *                     componentState: {
+     *                         name: 'new_component_A1',
+     *                         processAffinity: 'ps_1',
+     *                         url: 'https://www.example.com'
+     *                     }
+     *                 },
+     *                 {
+     *                     type: 'component',
+     *                     componentName: 'view',
+     *                     componentState: {
+     *                         name: 'new_component_A2',
+     *                         url: 'https://cdn.openfin.co/embed-web/chart.html'
+     *                     }
+     *                 }
+     *             ]
+     *         }
+     *     ]
+     * };
+     *
+     * layout.replace(newLayout);
+     * ```
      */
-    getRootItem(): Promise<OpenFin.ColumnOrRow | OpenFin.TabStack>;
+    replace: (layout: OpenFin.LayoutOptions) => Promise<void>;
     /**
-     * Replaces a Platform window's layout with a new layout.  Any views that were in the old layout but not the new layout
-     * will be destroyed.
-     * @param { LayoutConfig } layout New layout to implement in the target window.
-     * Please see explanation of a layout {@link https://developers.openfin.co/docs/platform-api#section-layout here}.
-     * @return { Promise<void> }
-     * @tutorial Layout.replace
+     * Retrieves the top level content item of the layout.
+     *
+     * @remarks Cannot be called from a view.
+     *
+     *
+     *
+     * @example
+     * ```js
+     * if (!fin.me.isWindow) {
+     *     throw new Error('Not running in a platform View.');
+     * }
+     *
+     * // From the layout window
+     * const layout = fin.Platform.Layout.getCurrentSync();
+     * // Retrieves the ColumnOrRow instance
+     * const rootItem = await layout.getRootItem();
+     * const content = await rootItem.getContent();
+     * console.log(`The root ColumnOrRow instance has ${content.length} item(s)`);
+     * ```
      */
-    replace: (layout: OpenFin.LayoutOptions) => Promise<void>;
+    getRootItem(): Promise<OpenFin.ColumnOrRow | OpenFin.TabStack>;
     /**
      * Replaces the specified view with a view with the provided configuration.
-     * The old view is stripped of its listeners and either closed or attached to the provider window
+     *
+     * @remarks The old view is stripped of its listeners and either closed or attached to the provider window
      * depending on `detachOnClose` view option.
-     * @param { Identity } viewToReplace Identity of the view to be replaced
-     * @param { View~options } newView Creation options of the new view.
-     * @return { Promise<void> }
-     * @tutorial Layout.replaceView
+     *
+     * @param viewToReplace Identity of the view to be replaced
+     * @param newView Creation options of the new view.
+     *
+     * @example
+     * ```js
+     * let currentWindow;
+     * if (fin.me.isWindow) {
+     *     currentWindow = fin.me;
+     * } else if (fin.me.isView) {
+     *     currentWindow = await fin.me.getCurrentWindow();
+     * } else {
+     *     throw new Error('Not running in a platform View or Window');
+     * }
+     *
+     * const layout = fin.Platform.Layout.wrapSync(currentWindow.identity);
+     * const viewToReplace = (await currentWindow.getCurrentViews())[0];
+     * const newViewConfig = {url: 'https://example.com'};
+     * await layout.replaceView(viewToReplace.identity, newViewConfig);
+     * ```
      */
     replaceView: (viewToReplace: Identity, newView: OpenFin.PlatformViewCreationOptions) => Promise<void>;
     /**
      * Replaces a Platform window's layout with a preset layout arrangement using the existing Views attached to the window.
      * The preset options are `columns`, `grid`, `rows`, and `tabs`.
-     * @param { PresetLayoutOptions } options Mandatory object with `presetType` property that sets which preset layout arrangement to use.
+     * @param options Mandatory object with `presetType` property that sets which preset layout arrangement to use.
      * The preset options are `columns`, `grid`, `rows`, and `tabs`.
-     * @return { Promise<void> }
-     * @tutorial Layout.applyPreset
+     *
+     * @example
+     * ```js
+     * let windowIdentity;
+     * if (fin.me.isWindow) {
+     *     windowIdentity = fin.me.identity;
+     * } else if (fin.me.isView) {
+     *     windowIdentity = (await fin.me.getCurrentWindow()).identity;
+     * } else {
+     *     throw new Error('Not running in a platform View or Window');
+     * }
+     *
+     * const layout = fin.Platform.Layout.wrapSync(windowIdentity);
+     * await layout.applyPreset({ presetType: 'grid' });
+     *
+     * // wait 5 seconds until you change the layout from grid to tabs
+     * await new Promise (res => setTimeout(res, 5000));
+     * await layout.applyPreset({ presetType: 'tabs' });
+     * ```
      */
     applyPreset: (options: PresetLayoutOptions) => Promise<void>;
 }