@sapui5/sap.ushell 1.141.3 → 1.142.0

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

@@ -0,0 +1,107 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+/**
+ * @file The modules base API providing common functionality for all module APIs.
+ */
+sap.ui.define([
+    "sap/base/util/ObjectPath"
+], (
+    ObjectPath
+) => {
+    "use strict";
+
+    /**
+     * The base API class for all module APIs.
+     *
+     * @since 1.142.0
+     * @private
+     */
+    class BaseAPI {
+        /**
+         * @type {object} The configuration object for the module.
+         */
+        #oConfig;
+        /**
+         * @type {object} An object to store property bindings to models.
+         * The keys are property aliases, the values are objects containing the model and the binding.
+         * @example
+         * {
+         *   "propertyAlias1": {
+         *     model: oModel,
+         *     binding: oBinding
+         *   },
+         *   "propertyAlias2": {
+         *     model: oModel2,
+         *     binding: oBinding2
+         *   }
+         * }
+         */
+        #oPropertyBindings = {};
+
+        /**
+         * Creates a new instance of the BaseAPI class.
+         *
+         * @param {object} [oConfig={}] The configuration object for the module.
+         *
+         * @since 1.142.0
+         * @private
+         */
+        constructor (oConfig = {}) {
+            this.#oConfig = oConfig;
+        }
+
+        /**
+         * Gets a configuration value by its path.
+         * @param {string} sPath The path to the configuration value, using dot notation for nested properties.
+         * @returns {any} The configuration value at the given path, or undefined if not found.
+         * If the path is empty, the entire configuration object is returned.
+         *
+         * @since 1.142.0
+         * @private
+         */
+        getConfigValue (sPath) {
+            return ObjectPath.get(sPath, this.#oConfig);
+        }
+
+        /**
+         * Binds a property of the module API to a model property.
+         * When the model property changes, the provided setter callback is called with the new value.
+         *
+         * @param {string} sPath The absolute path to the property in the model.
+         * @param {sap.ui.model.Model} oModel The model to bind to.
+         * @param {string} sPropertyAlias The alias for the property in the module API.
+         * @param {function} fnChangeHandler The callback function to call when the model property changes.
+         *
+         * @since 1.142.0
+         * @private
+         */
+        bindModelProperty (sPath, oModel, sPropertyAlias, fnChangeHandler) {
+            const oBinding = oModel.bindProperty(sPath);
+            oBinding.attachChange(() => {
+                fnChangeHandler(oBinding.getValue());
+            });
+            // store the binding to be able to unbind it later
+            this.#oPropertyBindings[sPropertyAlias] = {
+                model: oModel,
+                binding: oBinding
+            };
+            // initialize the property with the current value
+            fnChangeHandler(oBinding.getValue());
+        }
+
+        /**
+         * Unbinds a property of the module API from its model.
+         * @param {string} sPropertyAlias The alias for the property in the module API to unbind.
+         * @since 1.142.0
+         * @private
+         */
+        unbindModelProperty (sPropertyAlias) {
+            const oModelData = this.#oPropertyBindings[sPropertyAlias];
+            if (oModelData) {
+                oModelData.binding.destroy();
+                delete this.#oPropertyBindings[sPropertyAlias];
+            }
+        }
+    }
+    return BaseAPI;
+});

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

@@ -0,0 +1,43 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+/**
+ * @file This is an empty wrapper for the BaseProvider module implementation to document the required interface
+ */
+
+sap.ui.define([
+    "sap/ushell/modules/BaseAPI"
+], (
+    BaseAPI
+) => {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.modules.BaseProvider
+     * @interface
+     * @description The BaseProvider interface which all module providers should implement.
+     *
+     * @since 1.142.0
+     * @private
+     */
+    class BaseProvider {
+        /**
+         * Creates a new instance of the Provider module.
+         *
+         * @param {sap.ushell.modules.BaseAPI} oAPI The API instance of the module.
+         * @since 1.142.0
+         * @private
+         */
+        constructor (oAPI) {}
+
+        /**
+         * Cleans up the provider instance before destruction.
+         *
+         * @returns {Promise} A promise that resolves when the exit is completed.
+         *
+         * @since 1.142.0
+         * @private
+         */
+        async exit () {}
+    }
+    return BaseProvider;
+});

package/src/main/js/sap/ushell/modules/Notifications/NotificationsAPI.js

@@ -0,0 +1,253 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+sap.ui.define([
+    "sap/ui/core/Element",
+    "sap/ushell/modules/BaseAPI",
+    "sap/ushell/state/StateManager"
+], (
+    Element,
+    BaseAPI,
+    StateManager
+) => {
+    "use strict";
+
+    // shortcut for sap.ushell.state.StateManager.Operation
+    const Operation = StateManager.Operation;
+
+    /**
+     * @alias sap.ushell.modules.Notifications.NotificationsAPI
+     * @namespace
+     * @description The API object for the Notifications module.
+     * This module cannot be required it gets injected in the constructor of the Notifications module.
+     * @see sap.ushell.modules.Notifications.Notifications
+     *
+     * @hideconstructor
+     *
+     * @since 1.142.0
+     * @private
+     * @ui5-restricted ANS
+     */
+    class NotificationsAPI extends BaseAPI {
+        /**
+         * The instance of the ShellBar or ShellHeader depending on the ushell Config.
+         *
+         * @type {sap.f.gen.ui5.webcomponents_fiori.dist.ShellBar|sap.ushell.ui.ShellHeader}
+         * @since 1.142.0
+         * @private
+         */
+        #oShellBar;
+
+        /**
+         * Creates a new instance of the NotificationsAPI.
+         *
+         * @param {object} oConfig The configuration object for the notifications module.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        constructor (oConfig) {
+            super(oConfig);
+            this.#oShellBar = Element.getElementById("shell-header")?.getComponentInstance?.()?.getRootControl()?.byId("shellBar");
+            if (!this.#oShellBar) {
+                // use the ShellHeader for compatibility reasons
+                this.#oShellBar = Element.getElementById("shell-header");
+            }
+        }
+
+        /**
+         * Gets the notifications button by ID as it would be expected in the ShellHeader.
+         * In case the ShellBar is used this method returns undefined as the button is not available.
+         *
+         * @returns {sap.ushell.ui.shell.ShellHeadItem|undefined} The notifications button or undefined if not available.
+         * @since 1.142.0
+         * @private
+         */
+        #getShellHeaderNotificationsButton () {
+            if (this.#isShellBar()) {
+                // only available in ShellBar
+                return;
+            }
+            return Element.getElementById("NotificationsCountButton");
+        }
+
+        /**
+         * Checks if the ShellBar instance is available. This is used as long as the ShellHeader may still be used.
+         *
+         * @returns {boolean} True if the ShellBar instance is available, false otherwise.
+         * @since 1.142.0
+         * @private
+         */
+        #isShellBar () {
+            return this.#oShellBar?.isA("sap.f.gen.ui5.webcomponents_fiori.dist.ShellBar");
+        }
+
+        /**
+         * Sets the notifications count.
+         *
+         * @param {int} iCount The notifications count to set.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        setNotificationsCount (iCount) {
+            if (this.#isShellBar()) {
+                // need to map 0 to undefined as ShellBar would show "0" otherwise
+                this.#oShellBar.setNotificationsCount(iCount || undefined);
+            } else {
+                this.#getShellHeaderNotificationsButton()?.setFloatingNumber(iCount);
+            }
+        }
+
+        /**
+         * Gets the notifications count.
+         *
+         * @returns {int} The current notifications count.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        getNotificationsCount () {
+            if (this.#isShellBar()) {
+                return parseInt(this.#oShellBar.getNotificationsCount(), 10) || 0;
+            }
+            return this.#getShellHeaderNotificationsButton()?.getFloatingNumber();
+        }
+
+        /**
+         * Binds the notifications count property to a model. The model value must be compatible with
+         * the value of @see #setNotificationsCount.
+         *
+         * @param {string} sPath Absolute path to the property in the model.
+         * @param {sap.ui.model.Model} oModel The model to bind to.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        bindNotificationsCount (sPath, oModel) {
+            this.bindModelProperty(sPath, oModel, "notificationsCount", this.setNotificationsCount.bind(this));
+        }
+
+        /**
+         * Unbinds the notifications count property from a model.
+         *
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        unbindNotificationsCount () {
+            this.unbindModelProperty("notificationsCount");
+        }
+
+        /**
+         * Sets whether notifications should be currently shown.
+         * The actual value can differ from the set value due FLP state management.
+         *
+         * @param {boolean} bShow Whether to show notifications.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        setShowNotifications (bShow) {
+            StateManager.updateAllBaseStates("header.notifications.visible", Operation.Set, bShow);
+        }
+
+        /**
+         * Returns whether notifications are currently shown.
+         * The returned value can differ from last set value due FLP state management.
+         *
+         * @returns {boolean} Whether notifications are shown.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        getShowNotifications () {
+            if (this.#isShellBar()) {
+                return this.#oShellBar.getShowNotifications();
+            }
+            return this.#getShellHeaderNotificationsButton()?.getVisible();
+        }
+
+        /**
+         * Binds the the notifaction visibility to a model. The model value must be compatible with
+         * the value of @see #setShowNotifications.
+         *
+         * @param {string} sPath Absolute path to the property in the model.
+         * @param {sap.ui.model.Model} oModel The model to bind to.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        bindShowNotifications (sPath, oModel) {
+            this.bindModelProperty(sPath, oModel, "showNotifications", this.setShowNotifications.bind(this));
+        }
+
+        /**
+         * Unbinds the notifaction visibility.
+         *
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        unbindShowNotifications () {
+            this.unbindModelProperty("showNotifications");
+        }
+
+        /**
+         * Attaches a handler to the notifications press event.
+         *
+         * @param {object} [oData] An object that will be passed to the handler along with the event object when the event is fired
+         * @param {function} fnFunction The handler function to call when the event occurs.
+         * This function will be called in the context of the oListener instance (if present)
+         * or on the event provider instance. The event object (@see: sap.ui.base.Event) is provided
+         * as first argument of the handler. Handlers must not change the content of the event.
+         * The second argument is the specified oData instance (if present).
+         * @param {object} [oListener] The object that wants to be notified when the event occurs (this context within the handler function).
+         *
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        attachNotificationsPress (...args) {
+            if (this.#isShellBar()) {
+                this.#oShellBar.attachNotificationsClick(...args);
+            } else {
+                this.#getShellHeaderNotificationsButton()?.attachPress(...args);
+            }
+        }
+
+        /**
+         * Detaches a handler from the notifications press event.
+         *
+         * @param {function} fnFunction The handler function to detach from the event.
+         * @param {object} [oListener] The object that wanted to be notified when the event occurred.
+         *
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        detachNotificationsPress (...args) {
+            if (this.#isShellBar()) {
+                this.#oShellBar.detachNotificationsClick(...args);
+            } else {
+                this.#getShellHeaderNotificationsButton()?.detachPress(...args);
+            }
+        }
+
+        /**
+         * Gets the DOM reference for the notifications area.
+         *
+         * @returns {Element} The DOM reference.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        getNotificationsDomRef () {
+            if (this.#isShellBar()) {
+                return this.#oShellBar.getNotificationsDomRef();
+            }
+            return this.#getShellHeaderNotificationsButton()?.getDomRef();
+        }
+    }
+
+    return NotificationsAPI;
+});

package/src/main/js/sap/ushell/modules/Notifications/NotificationsProvider.js

@@ -0,0 +1,50 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+/**
+ * @file This is an empty wrapper for the NotificationsProvider module implementation to document the required interface
+ */
+sap.ui.define([
+    "sap/ushell/modules/BaseProvider"
+], (
+    BaseProvider
+) => {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.modules.Notifications.NotificationsProvider
+     * @class
+     * @description The required interface for a Notifications module.
+     *
+     * @abstract
+     *
+     * @since 1.142.0
+     * @private
+     *
+     * @ui5-restricted ANS
+     */
+    class NotificationsProvider extends BaseProvider {
+        /**
+         * Loads the search component and initializes the search functionality.
+         * @param {sap.ushell.modules.Notifications.NotificationsAPI} oNotificationsAPI The side navigation API object.
+         *
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        constructor (oNotificationsAPI) {
+            super(oNotificationsAPI);
+        }
+
+        /**
+         * Cleans up the component instance.
+         *
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        exit () {
+            // to be overridden by subclasses
+        }
+    }
+    return NotificationsProvider;
+}, false);

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

@@ -0,0 +1,53 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+/**
+ * @file This module provides an API for configuring the notifications of the Launchpad shell bar.
+ * It allows adding a NotificationsProvider to the notifications via for example a Plugin.
+ */
+
+sap.ui.define([
+    "sap/ushell/Config",
+    "sap/ushell/utils"
+], (
+    Config,
+    ushellUtils
+) => {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.modules.Notifications
+     * @namespace
+     * @description The Notifications module API to set a NotficiationsProvider and Config.
+     *
+     * @since 1.142.0
+     * @private
+     *
+     * @ui5-restricted ANS
+     */
+    class Notifications {
+        /**
+         * Sets the notifications provider for the notifications module.
+         * @param {string} sModulePath The module path of the notifications provider.
+         * @param {object} oConfiguration  The configuration object for the notifications provider.
+         *
+         * @returns {Promise} A promise that resolves when the configuration is set.
+         *
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        async setNotificationsProvider (sModulePath, oConfiguration) {
+            Config.emit("/core/notifications", {
+                enabled: true,
+                modulePath: sModulePath,
+                configuration: JSON.stringify(oConfiguration || {})
+            });
+
+            // ensure the NotificationsLoader is loaded so it can react to the config change.
+            // This may happen asynchronously if the FLP was not configured to use notifications at startup.
+            const [oNotificationsLoader] = await ushellUtils.requireAsync(["sap/ushell/modules/loader/NotificationsLoader"]);
+            await oNotificationsLoader.initialized();
+        }
+    }
+    return new Notifications();
+});