@sapui5/sap.ushell 1.123.1 → 1.124.1

package/src/main/js/sap/ushell/services/{Extension/Header.js → FrameBoundExtension/Item.js}

@@ -1,37 +1,37 @@
 // Copyright (c) 2009-2023 SAP SE, All Rights Reserved
 
 /**
- * @fileOverview Defines the interface for extensions in the ShellHeader ShellArea.
+ * @fileOverview Defines a generic interface for extension items in ShellAreas.
  *
- * @version 1.123.1
+ * This interface does NOT work when called from within a iframe.
+ *
+ * @version 1.124.1
  */
 sap.ui.define([
     "sap/base/Log",
-    "sap/ushell/Config",
-    "sap/ushell/Container",
-    "sap/ushell/utils"
+    "sap/ushell/Config"
 ], function (
     Log,
-    Config,
-    Container,
-    ushellUtils
+    Config
 ) {
     "use strict";
 
     /**
-     * @alias sap.ushell.services.Extension.Header
+     * @alias sap.ushell.services.FrameBoundExtension.Item
      * @class
-     * @classdesc Extension point of the Header.
-     * To be instantiated by {@link sap.ushell.services.Extension}.
+     * @classdesc Item wrapping an item positioned in an extension point.
+     * To be instantiated by {@link sap.ushell.services.FrameBoundExtension}.
+     *
+     * <p><b>Restriction:</b> Does not work when called from within a iframe.
+     * The calling function has to be in the 'same frame' as the launchpad itself.</p>
      *
      * @hideconstructor
      *
-     * @since 1.120.0
-     * @experimental since 1.120.0
-     * @private
+     * @since 1.124.0
+     * @public
      */
-    class Header {
-        #renderer = Container.getRendererInternal();
+    class Item {
+        #control = null;
         #visibilityMap = {};
 
         /**
@@ -45,41 +45,57 @@ sap.ui.define([
          * @returns {Promise} Resolves after visibility was changed.
          */
         #visibilityHandler = async (visible, currentState, launchpadState) => {
-            const states = launchpadState ? [launchpadState] : undefined;
-            await ushellUtils.promisify(this.#renderer.setHeaderVisibility(visible, currentState, states));
+            throw new Error("Shall be implemented by item");
         };
 
+        constructor (oControl, visibilityHandler) {
+            this.#control = oControl;
+            this.#visibilityHandler = visibilityHandler;
+        }
+
         /**
-         * Overwrites the title in the header
-         * @param {string} newTitle The new title
-         * @returns {this} Reference to <code>this</code> for method chaining.
+         * Returns the related control instance.
+         * @returns {Promise<sap.ui.core.Control>} The control.
          *
-         * @since 1.120.0
-         * @private
+         * @since 1.124.0
+         * @public
          */
-        setTitle (newTitle) {
-            this.#renderer.setHeaderTitle(newTitle);
-            return this;
+        async getControl () {
+            return this.#control;
+        }
+
+        /**
+         * Destroys the item and it's related content.
+         * @returns {Promise} Resolves once the item was destroyed.
+         *
+         * @since 1.124.0
+         * @public
+         */
+        async destroy () {
+            this.hideForAllApps()
+                .hideForCurrentApp()
+                .hideOnHome();
+            this.#control.destroy();
         }
 
         /**
-         * @param {boolean} visible Whether the item should be visible or not
+         * @param {boolean} visible Whether the item should be visible or not.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @private
          */
         setVisibilityForCurrentApp (visible) {
             if (!visible && this.#visibilityMap[this.#getCurrentState()]) {
-                Log.warning("The header was set to 'visible' for the current launchpad state and cannot be turned off for this app");
+                Log.warning("The item was set to 'visible' for the current launchpad state and cannot be turned off for this app");
             }
             this.#visibilityHandler(visible, true, undefined);
         }
 
         /**
-         * @param {sap.ushell.renderer.Renderer.LaunchpadState} launchpadState The launchpad state to change
-         * @param {boolean} visible Whether the item should be visible or not
+         * @param {sap.ushell.renderer.Renderer.LaunchpadState} launchpadState The launchpad state to change.
+         * @param {boolean} visible Whether the item should be visible or not.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @private
          */
         setVisibilityForLaunchpadState (launchpadState, visible) {
@@ -93,8 +109,8 @@ sap.ui.define([
          * The item will <b>not<b> be added again if the user navigates back to the application.
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
-         * @private
+         * @since 1.124.0
+         * @public
          */
         showForCurrentApp () {
             this.setVisibilityForCurrentApp(true);
@@ -106,8 +122,8 @@ sap.ui.define([
          * Note: The item will not be hidden if it was set visible for all apps {@link #showForAllApps}
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
-         * @private
+         * @since 1.124.0
+         * @public
          */
         hideForCurrentApp () {
             if (this.#visibilityMap[this.#getCurrentState()]) {
@@ -122,8 +138,8 @@ sap.ui.define([
          * Does not change the visibility of the item for the launchpad "home".
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
-         * @private
+         * @since 1.124.0
+         * @public
          */
         showForAllApps () {
             this.setVisibilityForLaunchpadState("app", true);
@@ -135,8 +151,8 @@ sap.ui.define([
          * Does not change the visibility of the item for the launchpad "home".
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
-         * @private
+         * @since 1.124.0
+         * @public
          */
         hideForAllApps () {
             this.setVisibilityForLaunchpadState("app", false);
@@ -148,8 +164,8 @@ sap.ui.define([
          * Does not change the visibility of the item within applications.
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
-         * @private
+         * @since 1.124.0
+         * @public
          */
         showOnHome () {
             this.setVisibilityForLaunchpadState("home", true);
@@ -161,8 +177,8 @@ sap.ui.define([
          * Does not change the visibility of the item within applications.
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
-         * @private
+         * @since 1.124.0
+         * @public
          */
         hideOnHome () {
             this.setVisibilityForLaunchpadState("home", false);
@@ -173,7 +189,7 @@ sap.ui.define([
          * Returns the current state of the launchpad
          * @returns {sap.ushell.renderer.Renderer.LaunchpadState} The current state.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @private
          */
         #getCurrentState () {
@@ -182,5 +198,5 @@ sap.ui.define([
         }
     }
 
-    return Header;
+    return Item;
 });

package/src/main/js/sap/ushell/services/{Extension → FrameBoundExtension}/SidePane.js

@@ -3,10 +3,12 @@
 /**
  * @fileOverview Defines the interface for extensions in the SidePane ShellArea.
  *
- * @version 1.123.1
+ * This interface does NOT work when called from within a iframe.
+ *
+ * @version 1.124.1
  */
 sap.ui.define([
-    "./Item",
+    "sap/ushell/services/FrameBoundExtension/Item",
     "sap/ushell/Container",
     "sap/ushell/utils"
 ], function (
@@ -17,16 +19,17 @@ sap.ui.define([
     "use strict";
 
     /**
-     * @alias sap.ushell.services.Extension.SidePane
+     * @alias sap.ushell.services.FrameBoundExtension.SidePane
      * @class
      * @classdesc The side pane extension point is positioned next the launchpad content.
-     * To be instantiated by {@link sap.ushell.services.Extension}.
-     * <p><b>Restriction:</b> Might be ignored for apps running in an iframe</p>
+     * To be instantiated by {@link sap.ushell.services.FrameBoundExtension}.
+     *
+     * <p><b>Restriction:</b> Does not work when called from within a iframe.
+     * The calling function has to be in the 'same frame' as the launchpad itself.</p>
      *
      * @hideconstructor
      *
-     * @since 1.120.0
-     * @experimental since 1.120.0
+     * @since 1.124.0
      * @public
      */
     class SidePane {
@@ -56,9 +59,9 @@ sap.ui.define([
          * @param {object} controlProperties The properties that will be passed to the created control.
          * @param {object} [parameters] Additional parameters.
          * @param {string} [parameters.controlType=sap.m.Button] Defines the <code>controlType</code>.
-         * @returns {Promise<sap.ushell.services.Extension.Item>} The newly created item.
+         * @returns {Promise<sap.ushell.services.FrameBoundExtension.Item>} The newly created item.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @public
          */
         async createItem (controlProperties, parameters) {
@@ -91,7 +94,7 @@ sap.ui.define([
          * @param {sap.ushell.renderer.Renderer.LaunchpadState} launchpadState Whether the area should be visible this or not
          * @param {boolean} visible Whether the side pane should be visible or not
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @private
          */
         setVisibilityForLaunchpadState (launchpadState, visible) {
@@ -103,7 +106,7 @@ sap.ui.define([
          * Does not change the visibility of the side pane for the launchpad "home".
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @public
          */
         showForAllApps () {
@@ -116,7 +119,7 @@ sap.ui.define([
          * Does not change the visibility of the side pane for the launchpad "home".
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @public
          */
         hideForAllApps () {
@@ -129,7 +132,7 @@ sap.ui.define([
          * Does not change the visibility of the side pane within applications.
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @public
          */
         showOnHome () {
@@ -142,7 +145,7 @@ sap.ui.define([
          * Does not change the visibility of the area within applications.
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @public
          */
         hideOnHome () {

package/src/main/js/sap/ushell/services/{Extension → FrameBoundExtension}/ToolArea.js

@@ -3,10 +3,12 @@
 /**
  * @fileOverview Defines the interface for extensions in the ToolArea ShellArea.
  *
- * @version 1.123.1
+ * This interface does NOT work when called from within a iframe.
+ *
+ * @version 1.124.1
  */
 sap.ui.define([
-    "./Item",
+    "sap/ushell/services/FrameBoundExtension/Item",
     "sap/ushell/Container",
     "sap/ushell/utils"
 ], function (
@@ -17,16 +19,17 @@ sap.ui.define([
     "use strict";
 
     /**
-     * @alias sap.ushell.services.Extension.ToolArea
+     * @alias sap.ushell.services.FrameBoundExtension.ToolArea
      * @class
      * @classdesc The tool area extension point is positioned next the launchpad content.
-     * To be instantiated by {@link sap.ushell.services.Extension}.
-     * <p><b>Restriction:</b> Might be ignored for apps running in an iframe</p>
+     * To be instantiated by {@link sap.ushell.services.FrameBoundExtension}.
+     *
+     * <p><b>Restriction:</b> Does not work when called from within a iframe.
+     * The calling function has to be in the 'same frame' as the launchpad itself.</p>
      *
      * @hideconstructor
      *
-     * @since 1.120.0
-     * @experimental since 1.120.0
+     * @since 1.124.0
      * @public
      */
     class ToolArea {
@@ -54,9 +57,9 @@ sap.ui.define([
         /**
          * Creates an item in the tool area.
          * @param {object} controlProperties The properties that will be passed to the created control.
-         * @returns {Promise<sap.ushell.services.Extension.Item>} The newly created item.
+         * @returns {Promise<sap.ushell.services.FrameBoundExtension.Item>} The newly created item.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @public
          */
         async createItem (controlProperties) {
@@ -88,7 +91,7 @@ sap.ui.define([
          * @param {sap.ushell.renderer.Renderer.LaunchpadState} launchpadState Whether the area should be visible or not
          * @param {boolean} visible Whether the tool area should be visible or not
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @private
          */
         setVisibilityForLaunchpadState (launchpadState, visible) {
@@ -100,7 +103,7 @@ sap.ui.define([
          * Does not change the visibility of the tool area for the launchpad "home".
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @public
          */
         showForAllApps () {
@@ -113,7 +116,7 @@ sap.ui.define([
          * Does not change the visibility of the tool area for the launchpad "home".
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @public
          */
         hideForAllApps () {
@@ -126,7 +129,7 @@ sap.ui.define([
          * Does not change the visibility of the tool area within applications.
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @public
          */
         showOnHome () {
@@ -139,7 +142,7 @@ sap.ui.define([
          * Does not change the visibility of the tool area within applications.
          * @returns {this} Reference to <code>this</code> for method chaining.
          *
-         * @since 1.120.0
+         * @since 1.124.0
          * @public
          */
         hideOnHome () {