@sapui5/sap.ushell 1.139.0 → 1.141.0

package/src/main/js/sap/ushell/library.js

@@ -45,7 +45,7 @@ sap.ui.define([
     const oUshellLibrary = Library.init({
         name: "sap.ushell",
         apiVersion: 2,
-        version: "1.139.0",
+        version: "1.141.0",
         dependencies: [
             "sap.ui.core",
             "sap.m"

package/src/main/js/sap/ushell/modules/NavigationMenu/ListProvider.js

@@ -0,0 +1,56 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+/**
+ * @file This is an empty wrapper for the ListProvider implementation to document the required interface
+ */
+sap.ui.define([
+], (
+) => {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.modules.NavigationMenu.ListProvider
+     * @class
+     * @description The required interface for a navigation menu list provider.
+     *
+     * @abstract
+     *
+     * @since 1.141.0
+     * @private
+     * @ui5-restricted SAL
+     */
+    class ListProvider {
+        /**
+         * @param {sap.ushell.modules.NavigationMenu.ListProviderAPI} oListProviderAPI - The API for the list provider
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        constructor (oListProviderAPI) {}
+
+        /**
+         * @returns {Promise<sap.tnt.NavigationList>} A promise that resolves to the root item of the navigation list.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        async getRootItem () {
+            throw new Error("Method not implemented.");
+        }
+
+        /**
+         * @returns {Promise<string>} A promise that resolves to the selected key from the spaces.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        async findSelectedKey () {
+            throw new Error("Method not implemented.");
+        }
+    }
+
+    return ListProvider;
+});

package/src/main/js/sap/ushell/modules/NavigationMenu/ListProviderAPI.js

@@ -0,0 +1,119 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+/**
+ * @file This is an empty wrapper for the ListProviderAPI implementation to document the required interface
+ */
+sap.ui.define([
+], (
+) => {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.modules.NavigationMenu.ListProviderAPI
+     * @namespace
+     * @description The API for an navigation menu list provider.
+     * This module cannot be required it gets injected in the constructor of the ListProvider.
+     *
+     * @hideconstructor
+     *
+     * @since 1.141.0
+     * @private
+     * @ui5-restricted SAL
+     */
+    class ListProviderAPI {
+        /**
+         * Returns the configuration value for the provided path.
+         * The configuration path has to be provided in dot notation.
+         * The contents of the configuration have to be set with the setter methods in {@link sap.ushell.modules.NavigationMenu}.
+         * @param {string} sPath The configuration path to get the value for.
+         * @returns {any} The configuration value for the provided path.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        getConfigValue (sPath) {
+            // eslint-disable-next-line no-constant-condition
+            if (false) {
+                return undefined; // allows to defined @returns type
+            }
+
+            throw new Error("Method not implemented.");
+        }
+
+        /**
+         * Returns the navigation container facade. With this a list provider can make updates in the surrounding NavContainer.
+         * @returns {sap.ushell.modules.NavigationMenu.NavContainer} The navigation container facade.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        getNavContainerFacade () {
+            // eslint-disable-next-line no-constant-condition
+            if (false) {
+                return undefined; // allows to defined @returns type
+            }
+
+            throw new Error("Method not implemented.");
+        }
+
+        /**
+         * Updates the selected key in the navigation container based on {@link sap.ushell.modules.NavigationMenu.ListProvider#findSelectedKey}.
+         * @returns {Promise} Resolves once selected key was updated
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        async updateSelectedKey () {
+            throw new Error("Method not implemented.");
+        }
+
+        /**
+         * Opens the side navigation.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        openSideNavigation () {
+            throw new Error("Method not implemented.");
+        }
+
+        /**
+         * Closes the side navigation.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        closeSideNavigation () {
+            throw new Error("Method not implemented.");
+        }
+
+        /**
+         * Expands the side navigation.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        expandSideNavigation () {
+            throw new Error("Method not implemented.");
+        }
+
+        /**
+         * Collapses the side navigation.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        collapseSideNavigation () {
+            throw new Error("Method not implemented.");
+        }
+    }
+
+    return ListProviderAPI;
+});

package/src/main/js/sap/ushell/modules/NavigationMenu/NavContainer.js

@@ -0,0 +1,60 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+/**
+ * @file This is an empty wrapper for the NavContainer API which provides methods to interact with the navigation menu container.
+ */
+sap.ui.define([
+], (
+) => {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.modules.NavigationMenu.NavContainer
+     * @namespace
+     * @description The API to interact with the navigation menu container.
+     * This module cannot be required. It has to be fetched via the respective APIs e.g. {@link sap.ushell.modules.NavigationMenu.ListProviderAPI#getNavContainerFacade}.
+     * @hideconstructor
+     *
+     * @since 1.141.0
+     * @private
+     * @ui5-restricted SAL
+     */
+    class NavContainer {
+        /**
+         * Adds a control to the navigation container.
+         * @param {sap.ui.core.Control} oControl The control to add.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        add (oControl) {
+            throw new Error("Method not implemented.");
+        }
+
+        /**
+         * Navigates to the specified control.
+         * @param {string|sap.ui.core.Control} vControl The control to navigate to.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        to (vControl) {
+            throw new Error("Method not implemented.");
+        }
+
+        /**
+         * Navigates to the root control.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        toRoot () {
+            throw new Error("Method not implemented.");
+        }
+    }
+
+    return NavContainer;
+});

package/src/main/js/sap/ushell/modules/NavigationMenu/NavigationMenuMode.js

@@ -0,0 +1,37 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+sap.ui.define([
+], (
+) => {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.modules.NavigationMenu.NavigationMenuMode
+     * @enum {string}
+     *
+     * @since 1.141.0
+     * @private
+     * @ui5-restricted SAL
+     */
+    const NavigationMenuMode = {
+        /**
+         * Renders the NavigationMenu primarily as docked area.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        Docked: "Docked",
+
+        /**
+         * Renders the NavigationMenu primarily as popover.
+         *
+         * @since 1.141.0
+         * @private
+         * @ui5-restricted SAL
+         */
+        Popover: "Popover"
+    };
+
+    return NavigationMenuMode;
+});

package/src/main/js/sap/ushell/modules/NavigationMenu.js

@@ -6,26 +6,21 @@
  * The navigation menu is an extension of the sap.tnt.SideNavigation that provides navigation capabilities.
  */
 sap.ui.define([
-    "sap/ushell/Config"
+    "sap/ushell/Config",
+    "sap/ushell/modules/NavigationMenu/NavigationMenuMode"
 ], (
-    Config
+    Config,
+    NavigationMenuMode
 ) => {
     "use strict";
 
-    /**
-     * @enum {string} NavigationMenuMode - Defines the position of the navigation menu.
-     * @private
-     * @ui5-restricted SAL
-     */
-    const NavigationMenuMode = {
-        Docked: "Docked",
-        Popover: "Popover"
-    };
-
     /**
      * @alias sap.ushell.modules.NavigationMenu
      * @namespace
      * @description The navigation menu API provides a way of placing content on the navigation menu.
+     * The ListProviders have to provide items as {@link sap.tnt.NavigationList} which is then embedded in the {@link sap.tnt.SideNavigation}.
+     * The items have to provide unique keys to have them properly selected on navigation. The selected key has to be determined by the
+     * extending ListProvider via {@link sap.ushell.modules.NavigationMenu.ListProvider#findSelectedKey}.
      *
      * @since 1.136.0
      * @private
@@ -41,7 +36,9 @@ sap.ui.define([
         /**
          * Sets the navigation list provider for the navigation menu.
          *
-         * @param {string} sModulePath The module path of the navigation list provider.
+         * @param {string} sModulePath
+         * The module path of the navigation list provider.
+         * The module needs to fulfill the {@link sap.ushell.modules.NavigationMenu.ListProvider} interface.
          * @param {object} oConfiguration The configuration object for the navigation list provider.
          *
          * @since 1.136.0
@@ -58,7 +55,9 @@ sap.ui.define([
         /**
          * Sets the navigation list provider for the fixed area of the navigation menu.
          *
-         * @param {string} sModulePath The module path of the navigation list provider.
+         * @param {string} sModulePath
+         * The module path of the navigation list provider.
+         * The module needs to fulfill the {@link sap.ushell.modules.NavigationMenu.ListProvider} interface.
          * @param {object} oConfiguration The configuration object for the navigation list provider.
          *
          * @since 1.136.0
@@ -75,10 +74,12 @@ sap.ui.define([
         /**
          * Sets the mode of the navigation menu.
          *
-         * @param {NavigationMenuMode} sMode The mode of the navigation menu. Can be "Docked" or "Popover".
+         * @param {sap.ushell.modules.NavigationMenu.NavigationMenuMode} sMode The mode of the navigation menu. Can be "Docked" or "Popover".
+         *
+         * @private
          */
         setMode (sMode) {
-            if (sMode !== NavigationMenuMode.Docked && sMode !== NavigationMenuMode.Popover) {
+            if (!Object.values(NavigationMenuMode).includes(sMode)) {
                 throw new Error(`Invalid mode: ${sMode}`);
             }
             Config.emit("/core/sideNavigation/mode", sMode);

package/src/main/js/sap/ushell/navigation/NavigationState.js

@@ -20,7 +20,6 @@ sap.ui.define([
      * @private
      */
     class NavigationState {
-
         /**
          * The variable that indicates if a navigation is ongoing or not.
          * @type {boolean}
@@ -34,7 +33,6 @@ sap.ui.define([
          */
         #oEventProvider = new EventProvider();
 
-
         /**
          * Starts the navigation state changed event to start the navigation
          *
@@ -119,7 +117,6 @@ sap.ui.define([
         destroy () {
             this.#oEventProvider.destroy();
         }
-
     }
 
     return new NavigationState();

package/src/main/js/sap/ushell/navigationMode.js

@@ -11,7 +11,7 @@
  * Method Compute is used by ClientSide TargetResolution and takes not only the
  * next application but also the current application into account.
  *
- * @version 1.139.0
+ * @version 1.141.0
  */
 sap.ui.define([
     "sap/base/Log",
@@ -32,7 +32,7 @@ sap.ui.define([
      *  the service configuration object
      */
     const oExport = {};
-    const _validateServiceConfiguration = function (oEnableInPlaceForClassicUIs) {
+    function _validateServiceConfiguration (oEnableInPlaceForClassicUIs) {
         let bIsValid = true;
 
         if (oEnableInPlaceForClassicUIs) {
@@ -54,10 +54,10 @@ sap.ui.define([
                 `Actual parameter: ${JSON.stringify(oEnableInPlaceForClassicUIs)}`,
                 "sap.ushell.services.navigationMode");
         }
-    };
+    }
 
     // enableInPlaceForClassicUIs
-    const _getClassicUITechnologyForApplicationType = function (sApplicationType) {
+    function _getClassicUITechnologyForApplicationType (sApplicationType) {
         switch (sApplicationType) {
             case "TR":
                 return "GUI";
@@ -68,7 +68,7 @@ sap.ui.define([
             default:
                 return undefined;
         }
-    };
+    }
 
     oExport._isInplaceEnabledForApplicationType = function (sApplicationType) {
         const oEnableInPlaceForClassicUIsConfig = Config.last("/core/navigation/enableInPlaceForClassicUIs");

package/src/main/js/sap/ushell/override.js

@@ -144,12 +144,11 @@ sap.ui.define([
                 }
                 if (oNewGroup.key !== sGroup) {
                     let oGroupHeader;
-                    let oHeader;
                     // If factory is defined use it
                     if (oBindingInfo.groupHeaderFactory) {
                         oGroupHeader = oBindingInfo.groupHeaderFactory(oNewGroup);
                     }
-                    oHeader = oGroupHeader || new GroupHeaderListItem({
+                    const oHeader = oGroupHeader || new GroupHeaderListItem({
                         title: oNewGroup.text || oNewGroup.key
                     }).addStyleClass("sapMListHdr");
 

package/src/main/js/sap/ushell/performance/FesrEnhancer.js

@@ -11,13 +11,15 @@ sap.ui.define([
     "sap/base/util/deepExtend",
     "sap/ui/performance/trace/FESR",
     "sap/ushell/EventHub",
-    "sap/ushell/performance/ShellAnalytics"
+    "sap/ushell/performance/ShellAnalytics",
+    "sap/ushell/renderer/RendererManagedComponents"
 ], (
     Log,
     deepExtend,
     FESR,
     EventHub,
-    ShellAnalytics
+    ShellAnalytics,
+    RendererManagedComponents
 ) => {
     "use strict";
 
@@ -265,17 +267,18 @@ sap.ui.define([
 
         /**
          * Shortens a value at the end according to the formatting key and
-         * does not shortens the postfix
+         * does not shorten the postfix
          * which is considered part of the length.
          *
          * @param {string|int} vValue the Value
          * @param {string} sFormatKey The formatting key
+         * @param {int} [iModifiedMaxLength=0] The modified max length to be used for shortening
          * @returns {sShortenedValue} The shortened value
          *
          * @private
          * @since 1.121.0
          */
-        shortenWithPostfix: function (vValue, sFormatKey) {
+        shortenWithPostfix: function (vValue, sFormatKey, iModifiedMaxLength = 0) {
             const oFormatter = oFieldFormatting[sFormatKey];
             // if no formatter pass through the value
             if (oFormatter) {
@@ -288,12 +291,14 @@ sap.ui.define([
                         // add it again.
                         const oPostfixFormatter = {
                             ...oFormatter,
-                            maxLength: oFormatter.maxLength - oFormatter.postfix.length
+                            maxLength: oFormatter.maxLength - oFormatter.postfix.length + iModifiedMaxLength
                         };
+                        // Format the value without postfix
                         const sShortenedWithoutPostfix = this.shortenAccordingToFormatter(
                             vValue.slice(0, -1 * oPostfixFormatter.postfix.length),
                             oPostfixFormatter
                         );
+                        // return the shortened value with postfix
                         return sShortenedWithoutPostfix + oPostfixFormatter.postfix;
                     }
                 }
@@ -302,11 +307,38 @@ sap.ui.define([
             return vValue;
         },
 
+        /**
+         * Sanitizes the value according to the given format key.
+         * Only supported fields are sanitized.
+         * If the value is a string and contains a colon, it is shortened
+         * to the maximum length defined in the formatter, keeping the postfix.
+         * @param {string|int} vValue The value to be sanitized
+         * @param {string} sFormatKey The format key to be used for sanitization
+         * @returns {string|int|undefined} The sanitized value or undefined if the field is not supported or the value is falsy
+         * @private
+         * @since 1.139.0
+         */
+        sanitizeValue: function (vValue, sFormatKey) {
+            // only keep supported fields and actual values
+            if (aSupportedFields.includes(sFormatKey) && vValue) {
+                // shorten if max Length is provided else keep it as it is
+                if (typeof (vValue) === "string" && vValue.includes(":")) {
+                    // strip the postfix and shorten the first part
+                    // and add the second part again.
+                    const [sPrefix, sPostfix] = vValue.split(":");
+                    return `${this.shortenWithPostfix(sPrefix, sFormatKey, -5)}:${sPostfix}`;
+                }
+                // shorten the value according to the formatter
+                return this.shortenWithPostfix(vValue, sFormatKey);
+            }
+        },
+
         /**
          * Sanitizes the enhancement according to object oFieldFormatting.
          * Only attributes in array aSupportedFields are treated.
          * Attributes are shortened if max length is given.
          * Postfix is taking into account if given.
+         * It deletes attributes whose values are undefined.
          *
          * @param {object} oEnhancement Enhancement to be sanitized
          * @returns {object} santized Enhancement
@@ -317,10 +349,9 @@ sap.ui.define([
         sanitizeEnhancement: function (oEnhancement) {
             return Object.keys(oEnhancement).reduce((oResult, sKey) => {
                 const vValue = oEnhancement[sKey];
-                // only keep supported fields and actual values
-                if (aSupportedFields.includes(sKey) && vValue) {
-                    // shorten if max Length is provided else keep it as it is
-                    oResult[sKey] = this.shortenWithPostfix(vValue, sKey);
+                const sSanitizedValue = this.sanitizeValue(vValue, sKey);
+                if (sSanitizedValue !== undefined) {
+                    oResult[sKey] = sSanitizedValue;
                 }
                 return oResult;
             }, {});
@@ -404,16 +435,21 @@ sap.ui.define([
                 } else {
                     // case app finder, pages, and homepage
                     switch (oFesrHandle.appNameLong) {
-                        case "sap.ushell.components.homepage":
-                        case "sap.ushell.components.pages":
-                            sDeterminedScenario = SCENARIOS.HOME_INITIAL;
-                            break;
                         case "sap.ushell.components.appfinder":
                             sDeterminedScenario = SCENARIOS.FINDER_INITIAL;
                             break;
                         default:
-                            // application direct start
-                            sDeterminedScenario = SCENARIOS.APP_INITIAL;
+                            if (RendererManagedComponents.isManagedComponentName(oFesrHandle.appNameLong)) {
+                                // managed renderer component, e.g. "sap.ushell.components.pages", or menu
+                                if (oLastClosedRecord.getStep() === SCENARIOS.APP_INITIAL) {
+                                    sDeterminedScenario = SCENARIOS.APP_INITIAL;
+                                } else {
+                                    sDeterminedScenario = SCENARIOS.HOME_INITIAL;
+                                }
+                            } else {
+                                // application direct start / menu without web component
+                                sDeterminedScenario = SCENARIOS.APP_INITIAL;
+                            }
                     }
                 }
 

package/src/main/js/sap/ushell/performance/ShellAnalytics.js

@@ -3,7 +3,7 @@
  * @fileOverview Provides analytical data like duration for navigation steps in the shell, in FLP,
  *               in particular an array of all statistical records
  *
- * @version 1.139.0
+ * @version 1.141.0
  */
 sap.ui.define([
     "sap/base/Log",

package/src/main/js/sap/ushell/performance/StatisticalRecord.js

@@ -3,12 +3,13 @@
  * @fileOverview Class for statistical record
  *               It should contain data like step, duration after a navigation in the shell, can have status open.
  *               The closing of a record is logged in debug mode
- * @version 1.139.0
+ * @version 1.141.0
  */
 sap.ui.define([
     "sap/base/Log",
-    "sap/ui/performance/trace/Interaction"
-], (Log, Interaction) => {
+    "sap/ui/performance/trace/Interaction",
+    "sap/ushell/api/performance/Extension"
+], (Log, Interaction, Extension) => {
     "use strict";
 
     const sModuleName = "StatisticalRecord";
@@ -20,6 +21,8 @@ sap.ui.define([
         ERROR: "ERROR"
     };
 
+    const oExtension = new Extension();
+
     class StatisticalRecord {
         // ==================== For debugging ====================
         /**
@@ -167,7 +170,13 @@ sap.ui.define([
          *
          * @returns {string} sStep The navigation step
          */
+        // eslint-disable-next-line complexity
         #calculateStep () {
+            Log.debug(`${sLogPrefix} Calculating Step`, null, sModuleName);
+            const oNavigationSource = oExtension.getNavigationSource();
+            // padded navigation source with a colon to separate it from the step
+            // e.g. ":siBa" or the empty string if no navigation source is defined
+            const sPaddedNavigationSource = oNavigationSource ? `:${oNavigationSource.id}` : "";
             const bIsTargetHome = this.#targetIsHomeApp || this.#isFLPHome(this.#targetApplication);
             const bIsSourceHome = this.#sourceIsHomeApp || this.#isFLPHome(this.#sourceApplication);
 
@@ -190,35 +199,35 @@ sap.ui.define([
             // if source and target application are not the homepage it is an app to app navigation.
             // if homepage is started the source application is undefined
             if (!bIsTargetHome && !bIsSourceHome) {
-                return `A2A@${this.#sourceApplication}`;
+                return `A2A@${this.#sourceApplication}${sPaddedNavigationSource}`;
             }
 
             // back to the homepage from some app
             if (this.#sourceApplication && bIsTargetHome && !bIsSourceHome) {
-                return `FLP_BACK@${this.#sourceApplication}`;
+                return `FLP_BACK@${this.#sourceApplication}${sPaddedNavigationSource}`;
             }
 
             // if navigation within home
             if (bIsSourceHome && bIsTargetHome) {
                 if (["FLP_FINDER", "FLP_HOME"].includes(this.#targetApplication)) {
-                    return `${this.#targetApplication}@H2H`;
+                    return `${this.#targetApplication}@H2H${sPaddedNavigationSource}`;
                 }
                 // back to custom home
                 if (this.#targetIsHomeApp) {
-                    return `${this.#targetApplication}@H2H`;
+                    return `${this.#targetApplication}@H2H${sPaddedNavigationSource}`;
                 }
                 // to a page
-                return `${this.#targetApplicationData.pageId}@H2H`;
+                return `${this.#targetApplicationData.pageId}@H2H${sPaddedNavigationSource}`;
             }
 
             // start app from flp home
             if (this.#isFLPHome(this.#sourceApplication)) {
-                return "FLP@HOMEPAGE_TILE";
+                return `FLP@HOMEPAGE_TILE${sPaddedNavigationSource}`;
             }
 
             // start app from custom home
             if (this.#sourceIsHomeApp) {
-                return "APPSTART@CUSTOMHOME";
+                return `APPSTART@CUSTOMHOME${sPaddedNavigationSource}`;
             }
             return "";
         }