@openfin/core 33.76.31 → 33.76.36

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

@@ -13,10 +13,10 @@ const base_1 = require("../../base");
 const common_utils_1 = require("../common-utils");
 const layout_entities_1 = require("./entities/layout-entities");
 const layout_constants_1 = require("./layout.constants");
-/**
- * @lends Platform#Layout
- */
 class Layout extends base_1.Base {
+    /**
+     * @internal
+     */
     // eslint-disable-next-line no-shadow
     constructor(identity, wire) {
         super(wire);
@@ -27,12 +27,51 @@ class Layout extends base_1.Base {
          */
         _Layout_layoutClient.set(this, new lazy_1.Lazy(async () => layout_entities_1.LayoutNode.newLayoutEntitiesClient(await this.platform.getClient(), layout_constants_1.LAYOUT_CONTROLLER_ID, this.identity)));
         /**
-         * 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
+         * 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);
+         * ```
          */
         this.replace = async (layout) => {
             this.wire.sendAction('layout-replace').catch((e) => {
@@ -46,12 +85,29 @@ class Layout extends base_1.Base {
         };
         /**
          * 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);
+         * ```
          */
         this.replaceView = async (viewToReplace, newView) => {
             this.wire.sendAction('layout-replace-view').catch((e) => {
@@ -66,10 +122,27 @@ class Layout extends base_1.Base {
         /**
          * 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' });
+         * ```
          */
         this.applyPreset = async (options) => {
             this.wire.sendAction('layout-apply-preset').catch((e) => {
@@ -97,8 +170,16 @@ class Layout extends base_1.Base {
     }
     /**
      * 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();
+     * ```
      */
     async getConfig() {
         this.wire.sendAction('layout-get-config').catch((e) => {
@@ -111,7 +192,24 @@ class Layout extends base_1.Base {
     }
     /**
      * Retrieves the top level content item of the layout.
-     * @return {Promise<TabStack | ColumnOrRow>}
+     *
+     * @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)`);
+     * ```
      */
     async getRootItem() {
         this.wire.sendAction('layout-get-root-item').catch(() => {

package/src/api/platform/layout/entities/layout-entities.d.ts

@@ -31,12 +31,131 @@ export declare abstract class LayoutNode {
      */
     static newLayoutEntitiesClient: (client: OpenFin.ChannelClient, controllerId: string, identity: OpenFin.Identity) => Promise<LayoutEntitiesClient>;
     static getEntity: (definition: OpenFin.LayoutEntityDefinition, client: LayoutEntitiesClient) => ColumnOrRow | TabStack;
+    /**
+     * Checks if the TabStack or ColumnOrRow is the root content item
+     *
+     * @example
+     * ```js
+     * if (!fin.me.isView) {
+     *     throw new Error('Not running in a platform View.');
+     * }
+     *
+     * const stack = await fin.me.getCurrentStack();
+     * const isRoot = await stack.isRoot();
+     * // The TabStack is root: false
+     * console.log(`The TabStack is root: ${isRoot}`);
+     *
+     * // Retrieves the parent ColumnOrRow
+     * const parent = await stack.getParent();
+     * const parentIsRoot = await parent.isRoot();
+     * // The parent ColumnOrRow is root: true
+     * console.log(`The parent ColumnOrRow is root: ${parentIsRoot}`);
+     * ```
+     */
     isRoot: () => Promise<boolean>;
+    /**
+     * Checks if the TabStack or ColumnOrRow exists
+     *
+     * @example
+     * ```js
+     * if (!fin.me.isView) {
+     *     throw new Error('Not running in a platform View.');
+     * }
+     *
+     * const stack = await fin.me.getCurrentStack();
+     * // Retrieves the parent ColumnOrRow
+     * const columnOrRow = await stack.getParent();
+     * let exists = await stack.exists();
+     * // or
+     * let exists = await columnOrRow.exists();
+     * // The entity exists: true
+     * console.log(`The entity exists: ${exists}`);
+     * ```
+     */
     exists: () => Promise<boolean>;
+    /**
+     * Retrieves the parent of the TabStack or ColumnOrRow
+     *
+     * @example
+     * ```js
+     * if (!fin.me.isView) {
+     *     throw new Error('Not running in a platform View.');
+     * }
+     *
+     * const stack = await fin.me.getCurrentStack();
+     * // Retrieves the parent ColumnOrRow
+     * const columnOrRow = await stack.getParent();
+     *
+     * // undefined if entity is the root item
+     * let parent = await columnOrRow.getParent();
+     * // or
+     * let parent = await stack.getParent();
+     * ```
+     */
     getParent: () => Promise<ColumnOrRow | TabStack | undefined>;
+    /**
+     * Creates a new TabStack adjacent to the given TabStack or ColumnOrRow. Inputs can be new views to create, or existing views.
+     *
+     * @example
+     * ```js
+     * if (!fin.me.isView) {
+     *     throw new Error('Not running in a platform View.');
+     * }
+     *
+     * const stack = await fin.me.getCurrentStack();
+     * const columnOrRow = await stack.getParent();
+     *
+     * // Create view references by supplying a 'name' and 'url'
+     * const views = [
+     *     // if 'name' is undefined, one will be generated
+     *     // if 'url' is undefined, it will default the view URL to 'about:blank'
+     *     { name: 'google-view', url: 'http://google.com/'},
+     *     { name: 'of-developers-view', url: 'http://developers.openfin.co/'},
+     * ];
+     *
+     * // Create a view beforehand to be included in the new tab stack
+     * const outsideView = await fin.View.create({
+     *     name: 'outside-bloomberg-view',
+     *     url: 'https://bloomberg.com/',
+     *     target: fin.me.identity,
+     * });
+     *
+     * // Views to add can be identities, or the reference views mentioned above
+     * const viewsToAdd = [outsideView.identity, ...views];
+     *
+     * // Possible position inputs: 'right' | 'left' | 'top' | 'bottom'
+     * let stackFrom = await columnOrRow.createAdjacentStack(viewsToAdd, { position: 'right' });
+     * // Or
+     * let newStack = await stack.createAdjacentStack(viewsToAdd, { position: 'right' });
+     * console.log(`A new TabStack created to the right has ${newStack.length} views in it`);
+     *
+     * ```
+     */
     createAdjacentStack: (views: OpenFin.PlatformViewCreationOptions[], options: {
         position?: OpenFin.LayoutPosition;
     }) => Promise<TabStack>;
+    /**
+     * Retrieves the adjacent TabStacks of the given TabStack or ColumnOrRow
+     *
+     * @example
+     * ```js
+     * if (!fin.me.isView) {
+     *     throw new Error('Not running in a platform View.');
+     * }
+     *
+     * const stack = await fin.me.getCurrentStack();
+     * const columnOrRow = await stack.getParent();
+     * // Possible position inputs: 'right' | 'left' | 'top' | 'bottom'
+     * let rightStacks = await columnOrRow.getAdjacentStacks('right');
+     * let leftStacks = await columnOrRow.getAdjacentStacks('left');
+     * // or
+     * let rightStacks = await stack.getAdjacentStacks('right');
+     * let leftStacks = await stack.getAdjacentStacks('left');
+     *
+     * console.log(`The entity has ${rightStacks.length} stacks to the right, and ${leftStacks.length} stacks to the left`);
+     *
+     * ```
+     */
     getAdjacentStacks: (edge: OpenFin.LayoutPosition) => Promise<TabStack[]>;
 }
 /**
@@ -64,7 +183,7 @@ export declare class TabStack extends LayoutNode {
      * @memberof TabStack
      * @instance
      * @tutorial TabStack.isRoot
-     * @return {Promise<boolean>} Resolves true if this TabStack is the top level content item, or false if it is not.
+     * @returns Resolves true if this TabStack is the top level content item, or false if it is not.
      */
     /**
      * Determines if this  {@link TabStack} exists.
@@ -72,7 +191,7 @@ export declare class TabStack extends LayoutNode {
      * @instance
      * @memberof TabStack
      * @tutorial TabStack.exists
-     * @return {Promise<boolean>} Resolves true if this is the TabStack exists, or false if it has been destroyed.
+     * @returns Resolves true if this is the TabStack exists, or false if it has been destroyed.
      */
     /**
      * Retrieves the parent {@link ColumnOrRow} of this {@link TabStack}, if one exists.
@@ -80,7 +199,7 @@ export declare class TabStack extends LayoutNode {
      * @instance
      * @memberof TabStack
      * @tutorial TabStack.getParent
-     * @return {Promise<ColumnOrRow | TabStack | undefined>} Promise resolving with the {@link ColumnOrRow} that contains this item, or undefined if this {@link TabStack} is the root content item or does not exist.
+     * @returns is the root content item or does not exist.
      */
     /**
      * Returns all the adjacent stacks that share an edge with the given {@link TabStack}.
@@ -88,7 +207,7 @@ export declare class TabStack extends LayoutNode {
      * @instance
      * @memberof TabStack
      * @param  {LayoutPosition} edge - Edge to check for any adjacent stacks.
-     * @returns {Promise<TabStack[]>}
+     *
      * @tutorial TabStack.getAdjacentStacks
      */
     /**
@@ -102,9 +221,9 @@ export declare class TabStack extends LayoutNode {
      * @function createAdjacentStack
      * @instance
      * @memberof TabStack
-     * @param {View~options} views - List of identities or view creation options of the views to include in the stack
-     * @param {StackCreationOptions} options - Creation options.
-     * @returns {Promise<TabStack>} The created TabStack.
+     * @param views - List of identities or view creation options of the views to include in the stack
+     * @param options - Creation options.
+     * @returns The created TabStack.
      * @tutorial TabStack.createAdjacentStack
      * @experimental
      */
@@ -122,43 +241,102 @@ export declare class TabStack extends LayoutNode {
      * If that happens and then getViews() is called, it will return the identities in a different order than
      * than the currently rendered tab order.
      *
-     * @returns {Promise<Identity[]>} Resolves with a list containing the {@link OpenFin.Identity identities} of each view belonging to the {@link TabStack}.
+     *
      * @throws If the {@link TabStack} has been destroyed.
-     * @tutorial TabStack.getViews
+     * @example
+     * ```js
+     * if (!fin.me.isView) {
+     *     throw new Error('Not running in a platform View.');
+     * }
+     *
+     * const stack = await fin.me.getCurrentStack();
+     * // Alternatively, you can wrap any view and get the stack from there
+     * // const viewFromSomewhere = fin.View.wrapSync(someView.identity);
+     * // const stack = await viewFromSomewhere.getCurrentStack();
+     * const views = await stack.getViews();
+     * console.log(`Stack contains ${views.length} view(s)`);
+     * ```
      * @experimental
      */
     getViews: () => Promise<OpenFin.Identity[]>;
     /**
      * Adds or creates a view in this {@link TabStack}.
      *
-     * Known Issue: If adding a view overflows the tab-container, the added view will be set as active
+     * @remarks Known Issue: If adding a view overflows the tab-container, the added view will be set as active
      * and rendered at the front of the tab-stack, while the underlying order of tabs will remain unchanged.
      *
-     * @param {View~options} view The identity of an existing view to add, or options to create a view.
-     * @param {TabStack~AddViewOptions} options Optional view options: index number used to insert the view into the stack at that index. Defaults to 0 (front of the stack)
-     * @returns {Promise<identity>} Resolves with the {@link OpenFin.Identity identity} of the added view.
+     * @param view The identity of an existing view to add, or options to create a view.
+     * @param options Optional view options: index number used to insert the view into the stack at that index. Defaults to 0 (front of the stack)
+     * @returns Resolves with the {@link OpenFin.Identity identity} of the added view.
      * @throws If the view does not exist or fails to create.
      * @throws If the {@link TabStack} has been destroyed.
-     * @tutorial TabStack.addView
+     * @example
+     * ```js
+     * if (!fin.me.isView) {
+     *     throw new Error('Not running in a platform View.');
+     * }
+     *
+     * const stack = await fin.me.getCurrentStack();
+     * // Alternatively, you can wrap any view and get the stack from there
+     * // const viewFromSomewhere = fin.View.wrapSync(someView.identity);
+     * // const stack = await viewFromSomewhere.getCurrentStack();
+     * const googleViewIdentity = await stack.addView({ name: 'google-view', url: 'http://google.com/' });
+     * console.log('Identity of the google view just added', { googleViewIdentity });
+     * // pass in { index: number } to set the index in the stack. Here 1 means, end of the stack (defaults to 0)
+     * const appleViewIdentity = await stack.addView({ name: 'apple-view', url: 'http://apple.com/' }, { index: 1 });
+     * console.log('Identity of the apple view just added', { appleViewIdentity });
+     * ```
      * @experimental
      */
     addView: (view: OpenFin.Identity | OpenFin.PlatformViewCreationOptions, options?: OpenFin.AddViewToStackOptions) => Promise<OpenFin.Identity>;
     /**
      * Removes a view from this {@link TabStack}.
-     * @param {Identity} view - Identity of the view to remove.
+     *
+     * @remarks Throws an exception if the view identity does not exist or was already destroyed.
+     *
+     * @param view - Identity of the view to remove.
      * @throws If the view does not exist or does not belong to the stack.
      * @throws If the {@link TabStack} has been destroyed.
-     * @return {Promise<void>}
-     * @tutorial TabStack.removeView
+     *
+     * @example
+     * ```js
+     * if (!fin.me.isView) {
+     *     throw new Error('Not running in a platform View.');
+     * }
+     *
+     * const stack = await fin.me.getCurrentStack();
+     * const googleViewIdentity = await stack.addView({ name: 'google-view', url: 'http://google.com/' });
+     *
+     * await stack.removeView(googleViewIdentity);
+     *
+     * try {
+     *     await stack.removeView(googleViewIdentity);
+     * } catch (error) {
+     *     // Tried to remove a view ('google-view') which does not belong to the stack.
+     *     console.log(error);
+     * }
+     * ```
      */
     removeView: (view: OpenFin.Identity) => Promise<void>;
     /**
      * Sets the active view of the {@link TabStack} without focusing it.
-     * @param {Identity} view - Identity of the view to activate.
-     * @returns {Promise<void>} Promise which resolves with void once the view has been activated.
+     * @param view - Identity of the view to activate.
+     * @returns Promise which resolves with void once the view has been activated.
      * @throws If the {@link TabStack} has been destroyed.
      * @throws If the view does not exist.
-     * @tutorial TabStack.setActiveView
+     * @example
+     * Change the active tab of a known View's TabStack:
+     * ```js
+     * const targetView = fin.View.wrapSync({ uuid: 'uuid', name: 'view-name' });
+     * const stack = await targetView.getCurrentStack();
+     * await stack.setActiveView(targetView.identity);
+     * ```
+     *
+     * Set the current View as active within its TabStack:
+     * ```js
+     * const stack = await fin.me.getCurrentStack();
+     * await stack.setActiveView(fin.me.identity);
+     * ```
      * @experimental
      */
     setActiveView: (view: OpenFin.Identity) => Promise<void>;
@@ -174,7 +352,7 @@ export declare class ColumnOrRow extends LayoutNode {
      * @memberof ColumnOrRow
      * @instance
      * @tutorial ColumnOrRow.isRoot
-     * @return {Promise<boolean>} Resolves true if this TabStack is the top level content item, or false if it is not.
+     * @returns Resolves true if this TabStack is the top level content item, or false if it is not.
      */
     /**
      * Determines if this  {@link ColumnOrRow} exists.
@@ -182,7 +360,7 @@ export declare class ColumnOrRow extends LayoutNode {
      * @instance
      * @memberof ColumnOrRow
      * @tutorial ColumnOrRow.exists
-     * @return {Promise<boolean>} Resolves true if the TabStack exists, or false if it has been destroyed.
+     * @returns Resolves true if the TabStack exists, or false if it has been destroyed.
      */
     /**
      * Retrieves the parent {@link ColumnOrRow} of this {@link ColumnOrRow}, if one exists.
@@ -190,7 +368,8 @@ export declare class ColumnOrRow extends LayoutNode {
      * @instance
      * @memberof ColumnOrRow
      * @tutorial ColumnOrRow.getParent
-     * @return {Promise<ColumnOrRow | undefined>} Promise resolving with the {@link ColumnOrRow} that contains this item, or undefined if this {@link ColumnOrRow} does not exist or is the root content item.
+     * @returns Promise resolving with the {@link ColumnOrRow} that contains this item, or undefined if
+     * this {@link ColumnOrRow}does not exist or is the root content item.
      */
     /**
      * Returns all the adjacent stacks that share an edge with the given {@link ColumnOrRow}.
@@ -198,7 +377,7 @@ export declare class ColumnOrRow extends LayoutNode {
      * @instance
      * @memberof ColumnOrRow
      * @param  {LayoutPosition} edge - Edge to check for any adjacent stacks.
-     * @returns {Promise<TabStack[]>}
+     *
      * @tutorial ColumnOrRow.getAdjacentStacks
      */
     /**
@@ -212,9 +391,9 @@ export declare class ColumnOrRow extends LayoutNode {
      * @function createAdjacentStack
      * @instance
      * @memberof ColumnOrRow
-     * @param {View~options} views - List of identities or view creation options of the views to include in the stack
-     * @param {StackCreationOptions} options - Creation options.
-     * @returns {Promise<TabStack>} The created TabStack
+     * @param views - List of identities or view creation options of the views to include in the stack
+     * @param options - Creation options.
+     * @returns The created TabStack
      * @tutorial ColumnOrRow.createAdjacentStack
      * @experimental
      */
@@ -227,9 +406,22 @@ export declare class ColumnOrRow extends LayoutNode {
      */
     readonly type: 'column' | 'row';
     /**
-     * Retrieves a list of all content items belonging to this {@link ColumnOrRow} in order of appearance.
-     * @returns {Promise<Array<ColumnOrRow | TabStack>>} Resolves with a list containing {@link ColumnOrRow} and {@link TabStack} items belonging to this {@link ColumnOrRow}.
-     * @tutorial ColumnOrRow.getContent
+     * Retrieves the content array of the ColumnOrRow
+     *
+     * @example
+     * ```js
+     * if (!fin.me.isView) {
+     *     throw new Error('Not running in a platform View.');
+     * }
+     *
+     * const stack = await fin.me.getCurrentStack();
+     * // Retrieves the parent ColumnOrRow
+     * const columnOrRow = await stack.getParent();
+     *
+     * // returns [TabStack]
+     * const contentArray = await columnOrRow.getContent();
+     * console.log(`The ColumnOrRow has ${contentArray.length} item(s)`);
+     * ```
      */
     getContent: () => Promise<(ColumnOrRow | TabStack)[]>;
 }