@sapui5/sap.ushell 1.126.1 → 1.127.1

package/src/main/js/sap/ushell/state/StateRules.js

@@ -0,0 +1,295 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+    "sap/base/Log",
+    "sap/ushell/state/StateManager/LaunchpadState",
+    "sap/ushell/state/StateManager/Operation",
+    "sap/ushell/state/StateManager/ShellMode",
+    "sap/ushell/state/StrategyFactory"
+], function (
+    Log,
+    LaunchpadState,
+    Operation,
+    ShellMode,
+    StrategyFactory
+) {
+    "use strict";
+
+    // shortcut for sap.ushell.state.StateManager.ShellMode
+    const {
+        Default,
+        Standalone,
+        Embedded,
+        Merged,
+        Headerless,
+        Lean,
+        Blank,
+        Minimal
+    } = ShellMode;
+
+    /**
+     * @alias sap.ushell.state.StateRules
+     * @namespace
+     * @description StateRules is a helper class that applies rules to the state object.
+     * The rules are based on the shell configuration and the current shell mode.
+     *
+     * @since 1.127.0
+     * @private
+     */
+    class StateRules {
+        /**
+         * The shell configuration.
+         * @type {object}
+         */
+        #oShellConfig = null;
+
+        /**
+         * Sets the shell configuration.
+         * @param {object} oShellConfig The shell configuration.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.StateRules#setShellConfig
+         */
+        setShellConfig (oShellConfig) {
+            this.#oShellConfig = oShellConfig;
+        }
+
+        /**
+         * Applies the rules to the state data.
+         *  1. ShellMode
+         *  2. Move of items to the shell header
+         * The state rules are applied in-place.
+         * @param {object} oStateData The state data.
+         * @param {sap.ushell.state.StateManager.ShellMode} sShellMode The shell mode.
+         * @param {sap.ushell.state.StateManager.LaunchpadState} sLaunchpadState The launchpad state.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.StateRules#applyRules
+         */
+        applyRules (oStateData, sShellMode, sLaunchpadState) {
+            this.#applyShellMode(oStateData, sShellMode, sLaunchpadState);
+
+            this.#moveItemsToShellHeader(oStateData);
+
+            this.#ensureSingleFloatingAction(oStateData);
+            this.#ensureSingleSubHeader(oStateData);
+            this.#ensureSingleSidePaneContent(oStateData);
+
+            this.#ensureHeaderItemMaxLength(oStateData);
+        }
+
+        /**
+         * Applies the shell mode to the state data.
+         * @param {object} oStateData The state data.
+         * @param {sap.ushell.state.StateManager.ShellMode} sShellMode The shell mode.
+         * @param {sap.ushell.state.StateManager.LaunchpadState} sLaunchpadState The launchpad state.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #applyShellMode (oStateData, sShellMode, sLaunchpadState) {
+            // Header
+            if (sShellMode === Headerless) {
+                StrategyFactory.perform(oStateData, "header.visible", Operation.Set, false);
+            }
+
+            // Logo
+            let bShowLogo;
+            if (sLaunchpadState === LaunchpadState.Home) {
+                bShowLogo = ![Headerless, Embedded, Merged].includes(sShellMode);
+            } else { // app
+                bShowLogo = ![Headerless, Standalone, Embedded, Merged].includes(sShellMode);
+            }
+            StrategyFactory.perform(oStateData, "header.home.showLogo", Operation.Set, bShowLogo);
+
+            // Back Button
+            if (sLaunchpadState === LaunchpadState.Home) {
+                StrategyFactory.perform(oStateData, "header.headItems", Operation.Remove, "backBtn");
+            } else { // app
+                /*
+                 * lean:    back button is allowed but not shown by default
+                 * minimal: back button is allowed but not shown by default
+                 */
+                const bShowBackButton = [Default, Standalone, Embedded, Merged, Lean, Minimal].includes(sShellMode);
+                if (!bShowBackButton) {
+                    StrategyFactory.perform(oStateData, "header.headItems", Operation.Remove, "backBtn");
+                }
+            }
+
+            // User Action Menu
+            /*
+             * merged: user action menu is allowed but not shown by default
+             */
+            const bShowUserActionMenu = [Default, Standalone, Minimal, Embedded, Lean, Blank, Merged].includes(sShellMode);
+            if (!bShowUserActionMenu) {
+                StrategyFactory.perform(oStateData, "header.headEndItems", Operation.Remove, "userActionsMenuHeaderButton");
+            }
+
+            // AppFinder
+            let bShowAppFinder;
+            if (sLaunchpadState === LaunchpadState.Home) {
+                bShowAppFinder = [Default, Standalone, Minimal, Lean].includes(sShellMode);
+            } else { // app
+                bShowAppFinder = [Default, Minimal].includes(sShellMode);
+            }
+            if (!bShowAppFinder) {
+                StrategyFactory.perform(oStateData, "userActions.items", Operation.Remove, "openCatalogBtn");
+            }
+
+            // UserSettings
+            let bShowUserSettings;
+            if (sLaunchpadState === LaunchpadState.Home) {
+                bShowUserSettings = [Default, Standalone, Minimal, Lean].includes(sShellMode);
+            } else { // app
+                bShowUserSettings = [Default, Minimal].includes(sShellMode);
+            }
+            if (!bShowUserSettings) {
+                StrategyFactory.perform(oStateData, "userActions.items", Operation.Remove, "userSettingsBtn");
+            }
+
+            // NotificationsButton
+            let bShowNotificationsButton;
+            if (sLaunchpadState === LaunchpadState.Home) {
+                bShowNotificationsButton = [Default, Standalone, Minimal, Lean].includes(sShellMode);
+            } else { // app
+                bShowNotificationsButton = [Default, Minimal].includes(sShellMode);
+            }
+            if (!bShowNotificationsButton) {
+                StrategyFactory.perform(oStateData, "header.headEndItems", Operation.Remove, "NotificationsCountButton");
+            }
+        }
+
+        /**
+         * Moves items to the shell header based on the shell configuration.
+         * @param {object} oStateData The state data.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #moveItemsToShellHeader (oStateData) {
+            if (!this.#oShellConfig) {
+                Log.warning("StateRules not initialized: Cannot move UserAction ShellHeader");
+                return;
+            }
+
+            if (this.#oShellConfig.moveEditHomePageActionToShellHeader) {
+                // handled in runtime controller
+            }
+
+            if (this.#oShellConfig.moveAppFinderActionToShellHeader) {
+                if (oStateData.userActions.items.includes("openCatalogBtn")) {
+                    StrategyFactory.perform(oStateData, "userActions.items", Operation.Remove, "openCatalogBtn");
+                    StrategyFactory.perform(oStateData, "header.headEndItems", Operation.Add, "openCatalogBtn");
+                }
+            }
+
+            if (this.#oShellConfig.moveUserSettingsActionToShellHeader) {
+                if (oStateData.userActions.items.includes("userSettingsBtn")) {
+                    StrategyFactory.perform(oStateData, "userActions.items", Operation.Remove, "userSettingsBtn");
+                    StrategyFactory.perform(oStateData, "header.headEndItems", Operation.Add, "userSettingsBtn");
+                }
+            }
+
+            if (this.#oShellConfig.moveContactSupportActionToShellHeader) {
+                if (oStateData.userActions.items.includes("ContactSupportBtn")) {
+                    StrategyFactory.perform(oStateData, "userActions.items", Operation.Remove, "ContactSupportBtn");
+                    StrategyFactory.perform(oStateData, "header.headEndItems", Operation.Add, "ContactSupportBtn");
+                }
+            }
+        }
+
+        /**
+         * Ensures that the floating actions contains only one item.
+         * The last item is kept.
+         * @param {object} oStateData The state data.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #ensureSingleFloatingAction (oStateData) {
+            if (oStateData.floatingActions.items.length > 1) {
+                // remove all items except the last one
+                const aShallowCopy = [...oStateData.floatingActions.items];
+                for (let i = 0; i < aShallowCopy.length - 1; i++) {
+                    const sItem = aShallowCopy[i];
+                    StrategyFactory.perform(oStateData, "floatingActions.items", Operation.Remove, sItem);
+                }
+            }
+        }
+
+        /**
+         * Ensures that the subHeader contains only one item.
+         * The last item is kept.
+         * @param {object} oStateData The state data.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #ensureSingleSubHeader (oStateData) {
+            if (oStateData.subHeader.items.length > 1) {
+                // remove all items except the last one
+                const aShallowCopy = [...oStateData.subHeader.items];
+                for (let i = 0; i < aShallowCopy.length - 1; i++) {
+                    const sItem = aShallowCopy[i];
+                    StrategyFactory.perform(oStateData, "subHeader.items", Operation.Remove, sItem);
+                }
+            }
+        }
+
+        /**
+         * Ensures that the sidePane contains only one item.
+         * The last item is kept.
+         * @param {object} oStateData The state data.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #ensureSingleSidePaneContent (oStateData) {
+            if (oStateData.sidePane.items.length > 1) {
+                // remove all items except the last one
+                const aShallowCopy = [...oStateData.sidePane.items];
+                for (let i = 0; i < aShallowCopy.length - 1; i++) {
+                    const sItem = aShallowCopy[i];
+                    StrategyFactory.perform(oStateData, "sidePane.items", Operation.Remove, sItem);
+                }
+            }
+        }
+
+        /**
+         * Ensures that the header items do not exceed the maximum length.
+         * The first items are kept. The back button is usually the first item {@link sap.ushell.state.StrategyFactory.HeadItemsStrategy}.
+         * @param {object} oStateData The state data.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #ensureHeaderItemMaxLength (oStateData) {
+            const iHeaderItemMaxLength = 3;
+            const aShallowCopy = [...oStateData.header.headItems];
+            if (aShallowCopy.length > iHeaderItemMaxLength) {
+                // only keep the first items
+                for (let i = iHeaderItemMaxLength; i < aShallowCopy.length; i++) {
+                    const sItem = aShallowCopy[i];
+                    StrategyFactory.perform(oStateData, "header.headItems", Operation.Remove, sItem);
+                }
+            }
+        }
+
+        /**
+         * ONLY FOR TESTING!
+         * Resets the state rules.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.StateRules#reset
+         */
+        reset () {
+            this.#oShellConfig = null;
+        }
+    }
+
+    return new StateRules();
+
+});

package/src/main/js/sap/ushell/state/StrategyFactory/DefaultStrategy.js

@@ -0,0 +1,74 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+], function (
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.state.StrategyFactory.DefaultStrategy
+     * @namespace
+     * @description Default strategy for adding, removing and setting values.
+     *
+     * @since 1.127.0
+     * @private
+     */
+    class DefaultStrategy {
+        /**
+         * Adds a value to a list.
+         * <code>null</code>, <code>undefined</code> and duplicated values are ignored.
+         * @param {any[]} aList The list.
+         * @param {any} vValue The value to add.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.StrategyFactory.DefaultStrategy#add
+         */
+        add (aList, vValue) {
+            if (vValue === undefined || vValue === null) {
+                return;
+            }
+
+            if (aList.includes(vValue)) {
+                return;
+            }
+            aList.push(vValue);
+        }
+
+        /**
+         * Removes a value from a list.
+         * Does not fail if the value is not in the list.
+         * @param {any[]} aList The list.
+         * @param {any} vValue The value to remove.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.StrategyFactory.DefaultStrategy#remove
+         */
+        remove (aList, vValue) {
+            const iIndex = aList.indexOf(vValue);
+            if (iIndex === -1) {
+                return;
+            }
+            aList.splice(iIndex, 1);
+        }
+
+        /**
+         * Sets a value on an object.
+         * Also sets nested properties, but does not merge objects.
+         * @param {object} oNode The object.
+         * @param {string} sKey The key.
+         * @param {any} vValue The value.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.StrategyFactory.DefaultStrategy#set
+         */
+        set (oNode, sKey, vValue) {
+            oNode[sKey] = vValue;
+        }
+    }
+
+    return new DefaultStrategy();
+
+});

package/src/main/js/sap/ushell/state/StrategyFactory/FloatingActionsStrategy.js

@@ -0,0 +1,78 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+    "sap/base/Log",
+    "sap/ui/core/Element"
+], function (
+    Log,
+    Element
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.state.StrategyFactory.FloatingActionsStrategy
+     * @namespace
+     * @description Strategy for adding items to the floating actions area.
+     *
+     * @since 1.127.0
+     * @private
+     */
+    class FloatingActionsStrategy {
+        /**
+         * Adds an item to the list.
+         * Does not add the item:
+         *  - if the control doesn't exist
+         * @param {sap.ui.core.ID[]} aList The list.
+         * @param {sap.ui.core.ID} sNewItem The item to add.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.StrategyFactory.FloatingActionsStrategy#add
+         */
+        add (aList, sNewItem) {
+            if (!Element.getElementById(sNewItem)) {
+                Log.warning(`Failed to find control with id '${sNewItem}'`);
+                return;
+            }
+
+            if (aList.includes(sNewItem)) {
+                this.#removeFloatingAction(aList, sNewItem);
+            }
+
+            this.#addFloatingAction(aList, sNewItem);
+        }
+
+        /**
+         * Removes the item from the list.
+         * @param {sap.ui.core.ID[]} aList The list.
+         * @param {sap.ui.core.ID} sItemToRemove The item to remove.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #removeFloatingAction (aList, sItemToRemove) {
+            const iIndex = aList.indexOf(sItemToRemove);
+
+            if (iIndex === -1) {
+                return;
+            }
+
+            aList.splice(iIndex, 1);
+        }
+
+        /**
+         * Adds the item to the list.
+         * @param {sap.ui.core.ID[]} aList The list.
+         * @param {sap.ui.core.ID} sNewItem The item to add.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #addFloatingAction (aList, sNewItem) {
+            aList.push(sNewItem);
+        }
+    }
+
+    return new FloatingActionsStrategy();
+
+});

package/src/main/js/sap/ushell/state/StrategyFactory/HeadEndItemsStrategy.js

@@ -0,0 +1,130 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+    "sap/base/Log",
+    "sap/ui/core/Element",
+    "sap/ushell/api/NewExperience"
+], function (
+    Log,
+    Element,
+    NewExperience
+) {
+    "use strict";
+
+    const iMaxLength = 10;
+
+    /**
+     * @alias sap.ushell.state.StrategyFactory.HeadEndItemsStrategy
+     * @namespace
+     * @description Strategy for adding items to the head end item area.
+     *
+     * @since 1.127.0
+     * @private
+     */
+    class HeadEndItemsStrategy {
+        /**
+         * Adds an item to the list.
+         * Does not add the item:
+         *  - if it is already in the list
+         *  - if the control doesn't exist
+         *  - if the max length would be exceeded
+         * Applies a custom sorting.
+         * @param {sap.ui.core.ID[]} aList The list.
+         * @param {sap.ui.core.ID} sNewItem The item to add.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.StrategyFactory.HeadEndItemsStrategy#add
+         */
+        add (aList, sNewItem) {
+            if (aList.includes(sNewItem)) {
+                return;
+            }
+            if (!Element.getElementById(sNewItem)) {
+                Log.warning(`Failed to find control with id '${sNewItem}'`);
+                return;
+            }
+            if (this.#exceedsMaxLength([...aList, sNewItem])) {
+                Log.error("The maximum number of head end items has been reached. The item could not be added.");
+            } else {
+                this.#addHeaderItems(aList, sNewItem);
+            }
+        }
+
+        /**
+         * Checks if the max length would be exceeded.
+         * Reserved ids are not counted.
+         * @param {sap.ui.core.ID} aList The list.
+         * @returns {boolean} True if the max length would be exceeded, false otherwise.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #exceedsMaxLength (aList) {
+            const aListWithoutDuplicates = [...new Set(aList)];
+            const aReservedIds = [
+                "endItemsOverflowBtn"
+            ];
+
+            const iCurrentLength = aListWithoutDuplicates.filter((sItem) => {
+                return !aReservedIds.includes(sItem);
+            }).length;
+
+            return iCurrentLength > iMaxLength;
+        }
+
+        /**
+         * Adds the item to the list.
+         * Applies sorting based on a predefined scale.
+         * @param {sap.ui.core.ID[]} aList The list.
+         * @param {sap.ui.core.ID} sNewItem The item to add.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #addHeaderItems (aList, sNewItem) {
+            aList.push(sNewItem);
+
+            /*
+             * HeaderEndItems has the following order:
+             * - search
+             * - Joule
+             * - copilot
+             * - custom items
+             * - notification
+             * - overflow button (before me area)
+             * - UserActionsMenu
+             * - product switch
+             */
+
+            /* eslint-disable quote-props */
+            const oScale = {
+                "sf": -3,
+                "sap.das.webclientplugin.s4.shellitem": -2, // Joule S4
+                "sap.das.webclientplugin.workzone.shellitem": -2, // Joule work zone
+                "copilotBtn": -1,
+                //0 custom items
+                "NotificationsCountButton": 1,
+                "endItemsOverflowBtn": 2,
+                "userActionsMenuHeaderButton": 3,
+                "productSwitchBtn": 4
+            };
+            oScale[NewExperience.getOverflowItemId()] = -4;
+            /* eslint-enable quote-props */
+
+            aList.sort((sItem1, sItem2) => {
+                const iPriority1 = oScale[sItem1] || 0;
+                const iPriority2 = oScale[sItem2] || 0;
+
+                if (iPriority1 === iPriority2) {
+                    return sItem1.localeCompare(sItem2);
+                }
+
+                return iPriority1 - iPriority2;
+            });
+        }
+    }
+
+    return new HeadEndItemsStrategy();
+
+});

package/src/main/js/sap/ushell/state/StrategyFactory/HeadItemsStrategy.js

@@ -0,0 +1,104 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+    "sap/base/Log",
+    "sap/ui/core/Element"
+], function (
+    Log,
+    Element
+) {
+    "use strict";
+
+    const iMaxLength = 3;
+
+    /**
+     * @alias sap.ushell.state.StrategyFactory.HeadItemsStrategy
+     * @namespace
+     * @description Strategy for adding items to the head item area.
+     *
+     * @since 1.127.0
+     * @private
+     */
+    class HeadItemsStrategy {
+        /**
+         * Adds an item to the list.
+         * Does not add the item:
+         *  - if it is already in the list
+         *  - if the control doesn't exist
+         *  - if the max length would be exceeded
+         * Applies a custom sorting.
+         * @param {sap.ui.core.ID[]} aList The list.
+         * @param {sap.ui.core.ID} sNewItem The item to add.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.StrategyFactory.HeadItemsStrategy#add
+         */
+        add (aList, sNewItem) {
+            if (aList.includes(sNewItem)) {
+                return;
+            }
+            if (!Element.getElementById(sNewItem)) {
+                Log.warning(`Failed to find control with id '${sNewItem}'`);
+                return;
+            }
+            if (this.#exceedsMaxLength([...aList, sNewItem])) {
+                Log.error("The maximum number of head items has been reached. The item could not be added.");
+            } else {
+                this.#addHeaderItems(aList, sNewItem);
+            }
+        }
+
+        /**
+         * Checks if the max length would be exceeded.
+         * Reserved ids are not counted.
+         * @param {sap.ui.core.ID} aList The list.
+         * @returns {boolean} True if the max length would be exceeded, false otherwise.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #exceedsMaxLength (aList) {
+            const aListWithoutDuplicates = [...new Set(aList)];
+            const aReservedIds = [
+                "backBtn"
+            ];
+
+            const iCurrentLength = aListWithoutDuplicates.filter((sItem) => {
+                return !aReservedIds.includes(sItem);
+            }).length;
+
+            return iCurrentLength > iMaxLength;
+        }
+
+        /**
+         * Adds the item to the list.
+         * Applies sorting based on a predefined scale.
+         * @param {sap.ui.core.ID[]} aList The list.
+         * @param {sap.ui.core.ID} sNewItem The item to add.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #addHeaderItems (aList, sNewItem) {
+            aList.push(sNewItem);
+
+            /* eslint-disable quote-props */
+            const oScale = {
+                "backBtn": -1
+                //0 custom items
+            };
+            /* eslint-enable quote-props */
+
+            aList.sort((sItem1, sItem2) => {
+                const iPriority1 = oScale[sItem1] || 0;
+                const iPriority2 = oScale[sItem2] || 0;
+
+                return iPriority1 - iPriority2;
+            });
+        }
+    }
+
+    return new HeadItemsStrategy();
+
+});