@openfin/core 33.76.27 → 33.76.36

package/src/api/platform/layout/entities/layout-entities.js

@@ -38,8 +38,67 @@ class LayoutNode {
          * ApiClient for {@link LayoutEntitiesController}
          */
         _LayoutNode_client.set(this, void 0);
+        /**
+         * 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}`);
+         * ```
+         */
         this.isRoot = () => __classPrivateFieldGet(this, _LayoutNode_client, "f").isRoot(this.entityId);
+        /**
+         * 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}`);
+         * ```
+         */
         this.exists = () => __classPrivateFieldGet(this, _LayoutNode_client, "f").exists(this.entityId);
+        /**
+         * 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();
+         * ```
+         */
         this.getParent = async () => {
             const parent = await __classPrivateFieldGet(this, _LayoutNode_client, "f").getParent(this.entityId);
             if (!parent) {
@@ -47,10 +106,70 @@ class LayoutNode {
             }
             return LayoutNode.getEntity(parent, __classPrivateFieldGet(this, _LayoutNode_client, "f"));
         };
+        /**
+         * 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`);
+         *
+         * ```
+         */
         this.createAdjacentStack = async (views, options) => {
             const entityId = await __classPrivateFieldGet(this, _LayoutNode_client, "f").createAdjacentStack(this.entityId, views, options);
             return LayoutNode.getEntity({ entityId, type: 'stack' }, __classPrivateFieldGet(this, _LayoutNode_client, "f"));
         };
+        /**
+         * 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`);
+         *
+         * ```
+         */
         this.getAdjacentStacks = async (edge) => {
             const adjacentStacks = await __classPrivateFieldGet(this, _LayoutNode_client, "f").getAdjacentStacks({
                 targetId: this.entityId,
@@ -117,7 +236,7 @@ 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.
@@ -125,7 +244,7 @@ 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.
@@ -133,7 +252,7 @@ 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}.
@@ -141,7 +260,7 @@ class TabStack extends LayoutNode {
      * @instance
      * @memberof TabStack
      * @param  {LayoutPosition} edge - Edge to check for any adjacent stacks.
-     * @returns {Promise<TabStack[]>}
+     *
      * @tutorial TabStack.getAdjacentStacks
      */
     /**
@@ -155,9 +274,9 @@ 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
      */
@@ -181,45 +300,104 @@ 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
          */
         this.getViews = () => __classPrivateFieldGet(this, _TabStack_client, "f").getStackViews(this.entityId);
         /**
          * 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
          */
         this.addView = async (view, options = { index: 0 }) => __classPrivateFieldGet(this, _TabStack_client, "f").addViewToStack(this.entityId, view, options);
         /**
          * 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);
+         * }
+         * ```
          */
         this.removeView = async (view) => {
             await __classPrivateFieldGet(this, _TabStack_client, "f").removeViewFromStack(this.entityId, view);
         };
         /**
          * 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
          */
         this.setActiveView = async (view) => {
@@ -240,7 +418,7 @@ 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.
@@ -248,7 +426,7 @@ 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.
@@ -256,7 +434,8 @@ 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}.
@@ -264,7 +443,7 @@ class ColumnOrRow extends LayoutNode {
      * @instance
      * @memberof ColumnOrRow
      * @param  {LayoutPosition} edge - Edge to check for any adjacent stacks.
-     * @returns {Promise<TabStack[]>}
+     *
      * @tutorial ColumnOrRow.getAdjacentStacks
      */
     /**
@@ -278,9 +457,9 @@ 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
      */
@@ -296,9 +475,22 @@ class ColumnOrRow extends LayoutNode {
          */
         _ColumnOrRow_client.set(this, void 0);
         /**
-         * 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)`);
+         * ```
          */
         this.getContent = async () => {
             const contentItemEntities = await __classPrivateFieldGet(this, _ColumnOrRow_client, "f").getContent(this.entityId);

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

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

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

@@ -1,4 +1,13 @@
 "use strict";
+/**
+ * Entry point for the OpenFin Layout namespace.
+ *
+ * Because TypeDoc does not currently support multiple modules with the same name, the module alias "LayoutModule" is used for
+ * the module containing static members of the `Layout` namespace (available under `fin.Layout`), while `Layout` documents
+ * instances of the OpenFin `Layout` 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);