@sapui5/sap.ushell 1.138.1 → 1.139.0

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

@@ -26,18 +26,18 @@
  * disables dark mode automatic, the currently active theme remains selected. In the settings dialog,
  * the selected entry switches, for example, from ABC set to the (current) ABC High Contrast Light.
  *
- * @version 1.138.1
+ * @version 1.139.0
  * @private
  */
 sap.ui.define([
     "sap/base/Log",
     "sap/ui/core/Theming",
     "sap/ushell/Container"
-], function (
+], (
     Log,
     Theming,
     Container
-) {
+) => {
     "use strict";
 
     const PREFERS_DARK = "(prefers-color-scheme: dark)";
@@ -122,7 +122,7 @@ sap.ui.define([
      * @since 1.72.0
      * @private
      */
-    function DarkModeSupport () {}
+    function DarkModeSupport() { }
 
     /**
      * @alias sap.ushell.services.DarkModeSupport.Mode
@@ -167,7 +167,7 @@ sap.ui.define([
 
     // If the current theme belongs to a set, switch to another theme in the set
     // according to user preferences (dark/contrast)
-    DarkModeSupport.prototype._toggleDarkModeBasedOnSystemColorScheme = function () {
+    DarkModeSupport.prototype._toggleDarkModeBasedOnSystemColorScheme = async function () {
         const sCurrentTheme = this._getCurrentTheme();
         const oThemeSet = this._getThemeSet(sCurrentTheme);
         const oCurrentTheme = this._getThemeFromSet(oThemeSet, sCurrentTheme);
@@ -178,20 +178,19 @@ sap.ui.define([
             // find the theme that corresponds to the browser preference
             // if not found (no contrast pairs), try the dark/light pair
             const oNewTheme = this._findThemeInSet(oThemeSet, sColorScheme, sContrast) ||
-            this._findThemeInSet(oThemeSet, sColorScheme, oCurrentTheme.contrast);
+                this._findThemeInSet(oThemeSet, sColorScheme, oCurrentTheme.contrast);
             if (oNewTheme?.id && oNewTheme.id !== oCurrentTheme.id) {
+                const oUserInfo = await Container.getServiceAsync("UserInfo");
+                await oUserInfo.updateThemeRoot(oNewTheme.id);
                 // store in personalization - for fixing race condition with the way the theme gets propagated to WZ advanced
                 Container.getUser().setTheme(oNewTheme.id); // setTheme also applies it
-
-                Container.getServiceAsync("UserInfo").then(function (oUserInfo) {
-                    oUserInfo.updateUserPreferences(Container.getUser());
-                });
+                oUserInfo.updateUserPreferences(Container.getUser());
             }
         }
     };
 
     DarkModeSupport.prototype._applyDefaultUserTheme = function () {
-        var oUser = Container.getUser();
+        const oUser = Container.getUser();
         if (oUser.constants && oUser.constants.themeFormat) {
             oUser.applyTheme(oUser.getTheme(oUser.constants.themeFormat.ORIGINAL_THEME));
         }
@@ -230,8 +229,8 @@ sap.ui.define([
         }
 
         this._aThemeSets = oThemeList?.sets?.length ? oThemeList.sets : _aDefaultThemeSets;
-        //set the correct theme mode based on the current system preference
-        this._toggleDarkModeBasedOnSystemColorScheme();
+
+        await this._toggleDarkModeBasedOnSystemColorScheme();
         this._toggleMediaListener(true);
     };
 
@@ -240,9 +239,9 @@ sap.ui.define([
         this._applyDefaultUserTheme(); // restore the default theme from settings
     };
 
-    DarkModeSupport.prototype.toggleDetection = function (bActive) {
+    DarkModeSupport.prototype.toggleDetection = async function (bActive) {
         if (bActive) {
-            this.enableDarkModeBasedOnSystem();
+            await this.enableDarkModeBasedOnSystem();
         } else {
             this.disableDarkModeBasedOnSystem();
         }
@@ -260,7 +259,9 @@ sap.ui.define([
         const aThemeSets = this._aThemeSets || [];
 
         // Returns true if the set does contain the theme sTheme
-        const _isValid = (oSet) => !!oSet?.set.themes?.find?.((theme) => theme?.id === sTheme);
+        function _isValid(oSet) {
+            return !!oSet?.set.themes?.find?.((theme) => theme?.id === sTheme);
+        }
 
         const oUserSet = aThemeSets.find((oSet) => oSet.id === sUserSet);
         // Regular case: check the saved set ID from the user profile for validity and return the corresponding set

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

@@ -5,9 +5,10 @@
  * @deprecated since 1.93
  */
 sap.ui.define([
-    "sap/ui/thirdparty/URI",
-    "sap/base/util/ObjectPath"
-], function (URI, ObjectPath) {
+    "sap/ui/thirdparty/URI"
+], (
+    URI
+) => {
     "use strict";
 
     /**
@@ -77,7 +78,7 @@ sap.ui.define([
          * @deprecated since 1.93
          */
         this.getPathOfURL = function (sURL) {
-            var oURI = new URI(sURL);
+            const oURI = new URI(sURL);
             return oURI.pathname();
         };
     }

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

@@ -3,15 +3,15 @@
 /**
  * @fileOverview Defines a generic interface for extension items in ShellAreas.
  *
- * @version 1.138.1
+ * @version 1.139.0
  */
 sap.ui.define([
     "sap/base/Log",
     "sap/ushell/state/StateManager"
-], function (
+], (
     Log,
     StateManager
-) {
+) => {
     "use strict";
 
     /**
@@ -47,21 +47,16 @@ sap.ui.define([
             throw new Error("Shall be implemented by item");
         };
 
-        constructor (oControl, visibilityHandler, controlWasPreCreated) {
+        constructor (oControl, visibilityHandler) {
             this.#control = oControl;
             this.#visibilityHandler = visibilityHandler;
 
             /*
-             * if the control was pre-created the application should take care of the control life cycle.
              * Add the control to the managed queue by default and remove it once it is related to a base state.
+             * Reset control manager entries triggered by the renderer API.
              */
-            if (!controlWasPreCreated) {
-                // Reset control manager entries triggered by the renderer API.
-                StateManager.removeManagedControl(this.#control.getId());
-                StateManager.addManagedControl(this.#control.getId());
-            } else {
-                Log.warning("The control was pre-created and the application is responsible for the control life cycle");
-            }
+            StateManager.removeManagedControl(this.#control.getId());
+            StateManager.addManagedControl(this.#control.getId());
         }
 
         /**

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

@@ -5,19 +5,21 @@
  * This files exposes an API to extend the launchpad with new elements.
  * It is exposed publicly and meant to be used by apps and plugins.
  *
- * @version 1.138.1
+ * @version 1.139.0
  */
 sap.ui.define([
+    "sap/base/Log",
     "sap/ui/core/Element",
     "sap/ushell/services/Extension/Item",
     "sap/ushell/Container",
     "sap/ushell/utils"
-], function (
+], (
+    Log,
     Element,
     ExtensionItem,
     Container,
     ushellUtils
-) {
+) => {
     "use strict";
 
     /**
@@ -92,14 +94,14 @@ sap.ui.define([
      * <b>Restrictions:</b>
      * <ul>
      * <li>The control properties are only allowed to contain primitive properties and event handlers.
-     * Aggregations, controls and types with prototypes are not allowed!</li>
+     * Bindings, aggregations, controls and objects with prototypes are not allowed!</li>
+     * <li>The created controls cannot have stable ids! Instead you can provide a help id.</li>
      * <li>The event handlers are not bound to the actual control and do not receive the event arguments.</li>
      * </ul>
      *
      * @example
      *
      *   Extension.createHeaderItem({
-     *       id: "headerItem1",
      *       ariaLabel: "headerItem-ariaLabel",
      *       ariaHaspopup: "dialog",
      *       icon: "sap-icon://action-settings",
@@ -110,39 +112,51 @@ sap.ui.define([
      *       }
      *   }, {
      *       position: "begin"
+     *       helpId: "myHeaderItemHelpId"
      *   })
      *
      * @param {sap.ushell.ui.shell.ShellHeadItem.Properties} controlProperties The properties that will be passed to the created control.
      * @param {object} [parameters] Additional parameters.
      * @param {string} [parameters.position=end] Possible values are <code>begin</code> and <code>end</code>.
+     * @param {string} [parameters.helpId] The help id of the user action. This allows to assign help content to the user action.
      * @returns {Promise<sap.ushell.services.Extension.Item>} The newly created header item.
      *
      * @since 1.120.0
      * @public
      */
     Extension.prototype.createHeaderItem = async function (controlProperties, parameters = {}) {
-        const { position } = parameters;
+        if (controlProperties.id) {
+            if (Element.getElementById(controlProperties.id)) {
+                throw new Error("The control id is not allowed for header items! The id will be generated automatically and must not be set by the application.");
+            }
+
+            Log.error("The control id is not allowed for header items! The id will be generated automatically. - For plugins use sap.ushell.services.FrameBoundExtension instead.");
+            delete controlProperties.id; // remove the id to prevent issues
+        }
+
+        const { position, helpId } = parameters;
         const aValidPositions = ["begin", "end", undefined];
         if (!aValidPositions.includes(position)) {
             throw new Error(`Unexpected Input: '${position}' is not a valid position!`);
         }
 
         if (position === "begin") {
-            return this._createHeaderStartItem(controlProperties);
+            return this._createHeaderStartItem(controlProperties, helpId);
         }
         // "end" or undefined
-        return this._createHeaderEndItem(controlProperties);
+        return this._createHeaderEndItem(controlProperties, helpId);
     };
 
     /**
      * Creates a header item in the shell header next to the company logo.
      * @param {object} controlProperties The properties that will be passed to the created control.
+     * @param {string} [helpId] The help id of the header item. This allows to assign help content to the header item.
      * @returns {Promise<sap.ushell.services.Extension.Item>} The newly created header item.
      *
      * @since 1.120.0
      * @private
      */
-    Extension.prototype._createHeaderStartItem = async function (controlProperties) {
+    Extension.prototype._createHeaderStartItem = async function (controlProperties, helpId) {
         const oRenderer = Container.getRendererInternal();
         const aCreateArgs = [
             controlProperties,
@@ -154,22 +168,26 @@ sap.ui.define([
         const fnShow = oRenderer.showHeaderItem.bind(oRenderer);
         const fnHide = oRenderer.hideHeaderItem.bind(oRenderer);
 
-        const bControlWasPreCreated = !!Element.getElementById(controlProperties.id);
         const oControl = await this._createControl(fnCreate, aCreateArgs);
         const fnVisibilityHandler = this._createItemVisibilityHandler(oControl.getId(), fnShow, fnHide);
 
-        return new ExtensionItem(oControl, fnVisibilityHandler, bControlWasPreCreated);
+        if (helpId) {
+            oControl.data("help-id", helpId, true);
+        }
+
+        return new ExtensionItem(oControl, fnVisibilityHandler);
     };
 
     /**
      * Creates a header item in the shell header next to the user action menu.
      * @param {object} controlProperties The properties that will be passed to the created control.
+     * @param {string} [helpId] The help id of the user action. This allows to assign help content to the user action.
      * @returns {Promise<sap.ushell.services.Extension.Item>} The newly created header item.
      *
      * @since 1.120.0
      * @private
      */
-    Extension.prototype._createHeaderEndItem = async function (controlProperties) {
+    Extension.prototype._createHeaderEndItem = async function (controlProperties, helpId) {
         const oRenderer = Container.getRendererInternal();
 
         const aCreateArgs = [
@@ -182,11 +200,14 @@ sap.ui.define([
         const fnShow = oRenderer.showHeaderEndItem.bind(oRenderer);
         const fnHide = oRenderer.hideHeaderEndItem.bind(oRenderer);
 
-        const bControlWasPreCreated = !!Element.getElementById(controlProperties.id);
         const oControl = await this._createControl(fnCreate, aCreateArgs);
         const fnVisibilityHandler = this._createItemVisibilityHandler(oControl.getId(), fnShow, fnHide);
 
-        return new ExtensionItem(oControl, fnVisibilityHandler, bControlWasPreCreated);
+        if (helpId) {
+            oControl.data("help-id", helpId, true);
+        }
+
+        return new ExtensionItem(oControl, fnVisibilityHandler);
     };
 
     // ========================================== UserAction ====================================================================
@@ -199,32 +220,43 @@ sap.ui.define([
      * <b>Restrictions:</b>
      * <ul>
      * <li>The control properties are only allowed to contain primitive properties and event handlers.
-     * Aggregations, controls and types with prototypes are not allowed!</li>
+     * Bindings, aggregations, controls and objects with prototypes are not allowed!</li>
+     * <li>The created controls cannot have stable ids! Instead you can provide a help id.</li>
      * <li>The event handlers are not bound to the actual control and do not receive the event arguments.</li>
      * </ul>
      *
      * @example
      *
      *   Extension.createUserAction({
-     *       id: "userAction1",
      *       text: "New UserAction",
      *       icon: "sap-icon://refresh",
      *       press: () => {
      *           MessageToast.show("Press UserAction");
      *       }
      *   }, {
-     *       controlType: "sap.ushell.ui.launchpad.ActionItem"
+     *       controlType: "sap.ushell.ui.launchpad.ActionItem",
+     *       helpId: "myUserActionHelpId"
      *   })
      *
      * @param {object} controlProperties The properties that will be passed to the created control.
      * @param {object} [parameters] Additional parameters.
      * @param {string} [parameters.controlType=sap.ushell.ui.launchpad.ActionItem] Defines the <code>controlType</code> of the item.
+     * @param {string} [parameters.helpId] The help id of the user action. This allows to assign help content to the user action.
      * @returns {Promise<sap.ushell.services.Extension.Item>} The newly created user action.
      *
      * @since 1.120.0
      * @public
      */
     Extension.prototype.createUserAction = async function (controlProperties, parameters = {}) {
+        if (controlProperties.id) {
+            if (Element.getElementById(controlProperties.id)) {
+                throw new Error("The control id is not allowed for header items! The id will be generated automatically and must not be set by the application.");
+            }
+
+            Log.error("The control id is not allowed for header items! The id will be generated automatically. - For plugins use sap.ushell.services.FrameBoundExtension instead.");
+            delete controlProperties.id; // remove the id to prevent issues
+        }
+
         const oRenderer = Container.getRendererInternal();
 
         const aCreateArgs = [{
@@ -238,11 +270,14 @@ sap.ui.define([
         const fnShow = oRenderer.showActionButton.bind(oRenderer);
         const fnHide = oRenderer.hideActionButton.bind(oRenderer);
 
-        const bControlWasPreCreated = !!Element.getElementById(controlProperties.id);
         const oControl = await this._createControl(fnCreate, aCreateArgs);
         const fnVisibilityHandler = this._createItemVisibilityHandler(oControl.getId(), fnShow, fnHide);
 
-        return new ExtensionItem(oControl, fnVisibilityHandler, bControlWasPreCreated);
+        if (parameters.helpId) {
+            oControl.data("help-id", parameters.helpId, true);
+        }
+
+        return new ExtensionItem(oControl, fnVisibilityHandler);
     };
 
     // ========================================== second Title ====================================================================