@sapui5/sap.ushell 1.119.3 → 1.120.1

package/src/main/js/sap/ushell/services/CommonDataModel.js

@@ -1,8 +1,8 @@
 // Copyright (c) 2009-2023 SAP SE, All Rights Reserved
 
 /**
- * @file Exposes a CommonDataModel based site document in a platform neutral format to it's clients
- * @version 1.119.3
+ * @file Exposes a CommonDataModel-based site document in a platform-neutral format to it's clients
+ * @version 1.120.1
  */
 sap.ui.define([
     "sap/ushell/services/_CommonDataModel/PersonalizationProcessor",
@@ -59,6 +59,15 @@ sap.ui.define([
     };
 
     /**
+     * @alias sap.ushell.services.CommonDataModel
+     * @class
+     * @classdesc The Unified Shell's CommonDataModel service.
+     * Exposes a CommonDataModel-based site document in a platform-neutral format to its clients.
+     *
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
+     * <code>sap.ushell.Container.getServiceAsync("CommonDataModel")</code>. For details, see
+     * {@link sap.ushell.services.Container#getServiceAsync}.
+     *
      * @param {object} oAdapter
      *   Adapter, provides an array of Inbounds
      * @param {object} oContainerInterface
@@ -68,9 +77,10 @@ sap.ui.define([
      * @param {object} oServiceConfiguration
      *   The service configuration not in use
      *
-     * @class
-     * @see {@link sap.ushell.services.Container#getServiceAsync}
+     * @hideconstructor
+     *
      * @since 1.40.0
+     * @private
      */
     function CommonDataModel (oAdapter, oContainerInterface, sParameters, oServiceConfiguration) {
         this._oAdapter = oAdapter;

package/src/main/js/sap/ushell/services/Configuration.js

@@ -4,7 +4,7 @@
  * @fileOverview The Unified Shell's Configuration service enables Components of any kind to consume parts of Configuration
  * provided by the shell. It allows to attach on updates and receive the current values
  *
- * @version 1.119.3
+ * @version 1.120.1
  */
 sap.ui.define([
     "sap/ushell/Config",
@@ -13,17 +13,18 @@ sap.ui.define([
     "use strict";
 
     /**
-     * This method MUST be called by the Unified Shell's container only, others MUST call
-     * <code>sap.ushell.Container.getServiceAsync("Configuration").then(function (Configuration) {});</code>.
-     * Constructs a new Configuration service.
+     * @alias sap.ushell.services.Configuration
+     * @class
+     * @classdesc The unified shell's Configuration service.
+     * Allows attaching to <b>selected</b> launchpad configuration settings and their value changes.
      *
-     * @name sap.ushell.services.Configuration
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
+     * <code>sap.ushell.Container.getServiceAsync("Configuration")</code>. For details, see
+     * {@link sap.ushell.services.Container#getServiceAsync}.
      *
-     * @class The unified shell's Configuration service, which allows to attach to <b>selected</b>
-     * launchpad configuration settings and their value changes.
+     * @hideconstructor
      *
      * @since 1.64.0
-     * @see sap.ushell.services.Container#getServiceAsync
      * @public
      */
     function Configuration () {
@@ -33,9 +34,9 @@ sap.ui.define([
          * The returned value can directly be used in {@link sap.m.GenericTile#sizeBehavior}.
          *
          * Once attached, <code>fnCallback</code> will be called once initially for the <b>current value</b>
-         * and afterwards everytime the value changed.
+         * and afterwards every time the value changed.
          *
-         * Please ensure to detach from the registry by calling <code>.detach</code> on the retuned object
+         * Please ensure to detach from the registry by calling <code>.detach</code> on the returned object
          * e.g. in the destroy function of your component or controller! Make sure that you do not attach
          * twice with the same function as otherwise a detach cannot be performed later!
          *
@@ -46,7 +47,7 @@ sap.ui.define([
          * // the callback that is called whenever the property changes
          * var fnCallback = function (sSizeBehavior) {
          *     // do something with sSizeBehavior like setting it on a
-         *     // sap.m.GernericTile via model and data binding!
+         *     // sap.m.GenericTile via model and data binding!
          * };
          *
          *

package/src/main/js/sap/ushell/services/ConfigurationDefaults.js

@@ -3,7 +3,7 @@
 /**
  * @fileOverview The Unified Shell's Configuration Defaults service exposes default configurations set in the code base.
  *
- * @version 1.119.3
+ * @version 1.120.1
  */
 sap.ui.define([
     "sap/base/Log",
@@ -12,17 +12,20 @@ sap.ui.define([
     "use strict";
 
     /**
-     * This method MUST be called by the Unified Shell's container only, others MUST call
-     * <code>sap.ushell.Container.getServiceAsync("ConfigurationDefaults").then(function (ConfigurationDefaults) {});</code>.
-     * Constructs a new Configuration service.
+     * @alias sap.ushell.services.ConfigurationDefaults
+     * @class
+     * @classdesc The Unified Shell's Configuration Defaults service.
+     * Exposes default configurations set in the code base.
      *
-     * @name sap.ushell.services.ConfigurationDefaults
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
+     * <code>sap.ushell.Container.getServiceAsync("ConfigurationDefaults")</code>. For details, see
+     * {@link sap.ushell.services.Container#getServiceAsync}.
      *
      * @param {object} oAdapter The service adapter for the ConfigurationDefaults service
      *
-     * @class
+     * @hideconstructor
+     *
      * @since 1.70.0
-     * @see sap.ushell.services.Container#getServiceAsync
      * @private
      */
     function ConfigurationDefaults (oAdapter) {
@@ -57,9 +60,9 @@ sap.ui.define([
                     var aResult = aConfigurationPaths.reduce(function (oDefaultsResult, sPath) {
                         var oResolvedDefaults;
                         if (that._isValidConfigPath(sPath)) {
-                            var aPath = sPath.split("/"),
-                                sPropertyName = aPath.pop(),
-                                oObject = oDefaultConfig;
+                            var aPath = sPath.split("/");
+                            var sPropertyName = aPath.pop();
+                            var oObject = oDefaultConfig;
 
                             for (var i = 0; i < aPath.length && oObject; i++) {
                                 oObject = oObject[aPath[i]];

package/src/main/js/sap/ushell/services/Container.js

@@ -14,7 +14,7 @@ sap.ui.define([
      *
      * @param {object} oAdapter the platform-specific adapter corresponding to this service
      * @class
-     * @classdesc The Unified Shell's container which manages renderers, services, and adapters.
+     * @classdesc The Unified Shell's container. Manages renderers, services, and adapters.
      * @alias sap.ushell.services.Container
      * @since 1.15.0
      * @deprecated since 1.101

package/src/main/js/sap/ushell/services/ContentExtensionAdapterFactory.js

@@ -4,7 +4,7 @@
  * default adapter.
  * Once instantiated, returns a map of adapters to be used by the LaunchPage Service
  *
- * @version 1.119.3
+ * @version 1.120.1
  */
 sap.ui.define([
     "sap/ushell/Config",

package/src/main/js/sap/ushell/services/CrossApplicationNavigation.js

@@ -5,8 +5,8 @@
  * This file exposes an API to perform (invoke) Cross Application Navigation for applications.
  * It exposes interfaces to perform a hash change and/or trigger an external navigation.
  *
- * @deprecated since 1.120
- * @version 1.119.3
+ * @deprecated since 1.120 Please use {@link sap.ushell.services.Navigation} instead
+ * @version 1.120.1
  */
 sap.ui.define([
     "sap/ushell/services/AppConfiguration",
@@ -50,8 +50,9 @@ sap.ui.define([
     /**
      * @alias sap.ushell.services.CrossApplicationNavigation
      * @class
-     * @classdesc The Unified Shell's CrossApplicationNavigation service allows to navigate to "external" targets outside of the currently running app (but still in scope
-     * of the current Fiori launchpad) or create links to such external targets.
+     * @classdesc The Unified Shell's CrossApplicationNavigation service.
+     * Allows navigating to "external" targets outside of the currently running app (but still in scope of the current Fiori launchpad)
+     * or to create links to such external targets.
      *
      * To use the CrossApplicationNavigation service you can retrieve an instance via ushell's Container:
      * <pre>
@@ -113,6 +114,7 @@ sap.ui.define([
      * @see sap.ushell.services.Container#getServiceAsync
      *
      * @since 1.15.0
+     * @deprecated since 1.120 Please use {@link sap.ushell.services.Navigation} instead
      * @public
      */
     function CrossApplicationNavigation (oContainerInterface, sParameters, oServiceConf) {
@@ -746,7 +748,7 @@ sap.ui.define([
          * A navigation to the Fiori launchpad Home is performed when this method is called on a first navigation.
          * In all other cases, this function simply performs a browser back navigation.
          *
-         * Please note that the behavior of this method is subject to change and therefore it may not yield to the expected results
+         * Note that the behavior of this method is subject to change and therefore it may not yield to the expected results
          * especially on mobile devices where "back" is the previous inner-app state if these are put into the history!
          *
          * @returns {Promise<undefined>} A promise which resolves once the back navigation was triggered
@@ -1387,7 +1389,7 @@ sap.ui.define([
          *   <ul>
          *     <li>
          *     <b>required</b>: whether the parameter must be required (true) or not required (false) in the signature of the matching target
-         *     (once the navigation occurs to the returned link). Please note that this option will be effective if the Fiori Launchpad is
+         *     (once the navigation occurs to the returned link). Note that this option will be effective if the Fiori Launchpad is
          *     configured to resolve navigation targets via <code>sap.ushell.services.ClientSideTargetResolution</code>
          *     and therefore may not be supported in all platforms.<br />
          *

package/src/main/js/sap/ushell/services/DarkModeSupport.js

@@ -5,7 +5,7 @@
  *
  * The service provide dark mode support functionality
  *
- * @version 1.119.3
+ * @version 1.120.1
  */
 sap.ui.define([
     "sap/base/Log",
@@ -27,10 +27,16 @@ sap.ui.define([
     var PREFERS_DARK_COLOR_QUERY = "(prefers-color-scheme: dark)";
 
     /**
-     * Dark Mode service.
-     *
-     * @name sap.ushell.services.DarkModeSupport
+     * @alias sap.ushell.services.DarkModeSupport
      * @class
+     * @classdesc Dark Mode service.
+     *
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
+     * <code>sap.ushell.Container.getServiceAsync("DarkModeSupport")</code>. For details, see
+     * {@link sap.ushell.services.Container#getServiceAsync}.
+     *
+     * @hideconstructor
+     *
      * @since 1.72.0
      * @private
      */
@@ -130,8 +136,8 @@ sap.ui.define([
     DarkModeSupport.prototype._toggleDarkModeBasedOnSystemColorScheme = function () {
         var sCurrentTheme = this._getCurrentTheme();
         if (this.darkMediaQueryList && this.isThemeSupportDarkMode(sCurrentTheme)) {
-            var oSupportedThemePair = this._findSupportedThemePair(sCurrentTheme),
-                bIsDarkModeInSystem = this.darkMediaQueryList.matches;
+            var oSupportedThemePair = this._findSupportedThemePair(sCurrentTheme);
+            var bIsDarkModeInSystem = this.darkMediaQueryList.matches;
 
             var sToTheme = bIsDarkModeInSystem ? oSupportedThemePair.dark : oSupportedThemePair.light;
             sap.ushell.Container.getUser().applyTheme(sToTheme);
@@ -152,8 +158,8 @@ sap.ui.define([
      * @private
      */
     DarkModeSupport.prototype.toggleModeChange = function () {
-        var sCurrentTheme = this._getCurrentTheme(),
-            oSupportedThemePair = this._findSupportedThemePair(sCurrentTheme);
+        var sCurrentTheme = this._getCurrentTheme();
+        var oSupportedThemePair = this._findSupportedThemePair(sCurrentTheme);
         if (oSupportedThemePair) {
             var sToTheme = sCurrentTheme === oSupportedThemePair.light
                 ? oSupportedThemePair.dark
@@ -211,8 +217,8 @@ sap.ui.define([
      * @private
      */
     DarkModeSupport.prototype.getCurrentThemeMode = function () {
-        var sCurrentTheme = this._getCurrentTheme(),
-            oSupportedThemePair = this._findSupportedThemePair(sCurrentTheme);
+        var sCurrentTheme = this._getCurrentTheme();
+        var oSupportedThemePair = this._findSupportedThemePair(sCurrentTheme);
         if (oSupportedThemePair) {
             return sCurrentTheme === oSupportedThemePair.light
                 ? DarkModeSupport.Mode.LIGHT

package/src/main/js/sap/ushell/services/EndUserFeedback.js

@@ -17,7 +17,7 @@ sap.ui.define([
      * @class
      * @classdesc The Unified Shell's end user feedback service.
      * This service is deprecated and does nothing.
-     * End user feedback functionality s not part of the ushell library.
+     * End user feedback functionality is not part of the ushell library.
      *
      * @public
      * @see sap.ushell.services.Container#getServiceAsync

package/src/main/js/sap/ushell/services/Extension/FloatingContainer.js

@@ -0,0 +1,103 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+/**
+ * @fileOverview Defines the interface for extensions in the FloatingContainer ShellArea.
+ *
+ * @version 1.120.1
+ */
+sap.ui.define([
+    "sap/ushell/Container"
+], function (
+    Container
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.services.Extension.FloatingContainer
+     * @class
+     * @classdesc The FloatingContainer.
+     * To be instantiated by {@link sap.ushell.services.Extension}.
+     * <p><b>Restriction:</b> Might be ignored for apps running in an iframe</p>
+     *
+     * @hideconstructor
+     *
+     * @since 1.120.0
+     * @experimental since 1.120.0
+     * @private
+     * @ui5-restricted
+     */
+    class FloatingContainer {
+        #renderer = Container.getRendererInternal();
+        #eventDelegate = null;
+
+        /**
+         * Sets the content of the FloatingContainer.
+         * @param {sap.ui.core.Control} control The actual content of the extension.
+         * @param {string} dragSelector CSS selector describing the drag handle to enable drag and drop.
+         * @returns {sap.ushell.services.Extension.FloatingContainer} this to allow method chaining.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        setContent (control, dragSelector) {
+            this.#renderer.setFloatingContainerContent(control);
+            this.#eventDelegate = {
+                onAfterRendering: () => {
+                    this.#renderer.setFloatingContainerDragSelector(dragSelector);
+                }
+            };
+            control.addEventDelegate(this.#eventDelegate, this);
+            return this;
+        }
+
+        /**
+         * @returns {sap.ushell.services.Extension.FloatingContainer} this to allow method chaining.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        show () {
+            this.#renderer.setFloatingContainerVisibility(true);
+            return this;
+        }
+
+        /**
+         * @returns {sap.ushell.services.Extension.FloatingContainer} this to allow method chaining.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        hide () {
+            this.#renderer.setFloatingContainerVisibility(false);
+            return this;
+        }
+
+        /**
+         * @returns {Promise<boolean>} Whether the floating container is currently in <code>docked</code> state.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        async isDocked () {
+            const sFloatingContainerState = this.#renderer.getFloatingContainerState() || "";
+            return sFloatingContainerState.startsWith("docked");
+        }
+
+        /**
+         * @returns {Promise<boolean>} Whether the floating container is currently visible.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        async isVisible () {
+            return this.#renderer.getFloatingContainerVisiblity();
+        }
+    }
+
+    return FloatingContainer;
+});

package/src/main/js/sap/ushell/services/Extension/Footer.js

@@ -0,0 +1,61 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+/**
+ * @fileOverview Defines the interface for extensions in the Footer ShellArea.
+ *
+ * @version 1.120.1
+ */
+sap.ui.define([
+    "sap/ushell/Container"
+], function (
+    Container
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.services.Extension.Footer
+     * @class
+     * @classdesc The footer extension point is positioned below 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>
+     *
+     * @hideconstructor
+     *
+     * @since 1.120.0
+     * @experimental since 1.120.0
+     * @public
+     */
+    class Footer {
+        #renderer = Container.getRendererInternal();
+        #control = null;
+
+        constructor (control) {
+            this.#control = control;
+        }
+
+        /**
+         * Returns the related control instance.
+         * @returns {Promise<sap.ui.core.Control>} The control.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        async getControl () {
+            return this.#control;
+        }
+
+        /**
+         * Destroys the footer.
+         * @returns {Promise} Resolves once the footer was destroyed.
+         *
+         * @since 1.120.0
+         * @public
+         */
+        async destroy () {
+            this.#renderer.removeFooterById(this.#control.getId());
+        }
+    }
+
+    return Footer;
+});

package/src/main/js/sap/ushell/services/Extension/Header.js

@@ -0,0 +1,193 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+/**
+ * @fileOverview Defines the interface for extensions in the ShellHeader ShellArea.
+ *
+ * @version 1.120.1
+ */
+sap.ui.define([
+    "sap/base/Log",
+    "sap/ushell/Config",
+    "sap/ushell/Container",
+    "sap/ushell/utils"
+], function (
+    Log,
+    Config,
+    Container,
+    ushellUtils
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.services.Extension.Header
+     * @class
+     * @classdesc Extension point of the Header.
+     * To be instantiated by {@link sap.ushell.services.Extension}.
+     *
+     * @hideconstructor
+     *
+     * @since 1.120.0
+     * @experimental since 1.120.0
+     * @private
+     * @ui5-restricted
+     */
+    class Header {
+        #renderer = Container.getRendererInternal();
+        #visibilityMap = {};
+
+        /**
+         * @param {boolean} visible
+         *   Whether the item shall be visible or not.
+         * @param {boolean} currentState
+         *   Whether the new visibility shall be applied only to the 'currentState'.
+         * @param {sap.ushell.renderer.Renderer.LaunchpadState} launchpadState
+         *   To which launchpad state the new visibility shall be applied.
+         *   Is only Considered if <code>currentState</code> is <code>false</code>.
+         * @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));
+        };
+
+        /**
+         * Overwrites the title in the header
+         * @param {string} newTitle The new title
+         * @returns {sap.ushell.services.Extension.Header} this to allow method chaining.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        setTitle (newTitle) {
+            this.#renderer.setHeaderTitle(newTitle);
+            return this;
+        }
+
+        /**
+         * @param {boolean} visible Whether the item should be visible or not
+         *
+         * @since 1.120.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");
+            }
+            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
+         *
+         * @since 1.120.0
+         * @private
+         */
+        setVisibilityForLaunchpadState (launchpadState, visible) {
+            this.#visibilityMap[launchpadState] = visible;
+            this.#visibilityHandler(visible, false, launchpadState);
+        }
+
+        /**
+         * Shows the item for the current application.
+         * The item will be hidden after the user navigates away from this application.
+         * The item will <b>not<b> be added again if the user navigates back to the application.
+         * @returns {sap.ushell.services.Extension.Header} this to allow method chaining.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        showForCurrentApp () {
+            this.setVisibilityForCurrentApp(true);
+            return this;
+        }
+
+        /**
+         * Hides the item for the current application.
+         * Note: The item will not be hidden if it was set visible for all apps {@link #showForAllApps}
+         * @returns {sap.ushell.services.Extension.Header} this to allow method chaining.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        hideForCurrentApp () {
+            if (this.#visibilityMap[this.#getCurrentState()]) {
+                Log.warning("The extension was set visible for the current launchpad state and cannot be turned off for this app");
+            }
+            this.setVisibilityForCurrentApp(false);
+            return this;
+        }
+
+        /**
+         * Shows the item for all applications.
+         * Does not change the visibility of the item for the launchpad "home".
+         * @returns {sap.ushell.services.Extension.Header} this to allow method chaining.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        showForAllApps () {
+            this.setVisibilityForLaunchpadState("app", true);
+            return this;
+        }
+
+        /**
+         * Shows the item for all applications.
+         * Does not change the visibility of the item for the launchpad "home".
+         * @returns {sap.ushell.services.Extension.Header} this to allow method chaining.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        hideForAllApps () {
+            this.setVisibilityForLaunchpadState("app", false);
+            return this;
+        }
+
+        /**
+         * Shows the item for launchpad "home".
+         * Does not change the visibility of the item within applications.
+         * @returns {sap.ushell.services.Extension.Header} this to allow method chaining.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        showOnHome () {
+            this.setVisibilityForLaunchpadState("home", true);
+            return this;
+        }
+
+        /**
+         * Hides the item for launchpad "home".
+         * Does not change the visibility of the item within applications.
+         * @returns {sap.ushell.services.Extension.Header} this to allow method chaining.
+         *
+         * @since 1.120.0
+         * @private
+         * @ui5-restricted
+         */
+        hideOnHome () {
+            this.setVisibilityForLaunchpadState("home", false);
+            return this;
+        }
+
+        /**
+         * @returns {sap.ushell.renderer.Renderer.LaunchpadState} The current state.
+         *
+         * @since 1.120.0
+         * @private
+         */
+        #getCurrentState () {
+            const sCurrentState = Config.last("/core/shell/model/currentState/stateName");
+            return sCurrentState;
+        }
+    }
+
+    return Header;
+});