@sapui5/sap.ushell 1.141.3 → 1.143.0

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 notifications 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();
+});

package/src/main/js/sap/ushell/modules/Search/SearchAPI.js

@@ -0,0 +1,271 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+/**
+ * @fileOverview The Search API for the Fiori Launchpad.
+ */
+
+sap.ui.define([
+    "sap/ui/core/Element",
+    "sap/ushell/modules/BaseAPI"
+], (
+    Element,
+    BaseAPI
+) => {
+    "use strict";
+    /**
+     * @alias sap.ushell.modules.Search.SearchAPI
+     * @class
+     * @description The API object for the Search module.
+     * This module cannot be required it gets injected in the constructor of the Search module.
+     * @see sap.ushell.modules.Search.Search
+     *
+     * @hideconstructor
+     *
+     * @since 1.142.0
+     * @private
+     * @ui5-restricted HAN-AS-INA-UI
+     */
+    class SearchAPI 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;
+
+        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 search 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 search button or undefined if not available.
+         * @since 1.142.0
+         * @private
+         */
+        #getShellHeaderSearchButton () {
+            if (this.#isShellBar()) {
+                // only available in ShellHeader
+                return;
+            }
+            return Element.getElementById("sf");
+        }
+
+        /**
+         * 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");
+        }
+
+        /**
+         * Gets the search field instance.
+         * In case the ShellHeader is used this method returns undefined as the search field is not available.
+         * @returns {Promise<sap.f.gen.ui5.webcomponents_fiori.dist.ShellBarSearch>|undefined} A promise that resolves to the search field instance or undefined if not available.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted HAN-AS-INA-UI
+         */
+        async getSearchField () {
+            if (this.#isShellBar()) {
+                return this.#oShellBar.getSearchField()[0];
+            }
+        }
+
+        /**
+         * Shows or hides the search field.
+         * Note: Hiding the search field will also collapse it if it is expanded.
+         *
+         * @param  {boolean} bShow Whether to show or hide the search field.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted HAN-AS-INA-UI
+         */
+        setShowSearchField (...args) {
+            if (this.#isShellBar()) {
+                this.#oShellBar.setShowSearchField(...args);
+            }
+        }
+
+        /**
+         * Gets whether the search field is shown or hidden.
+         *
+         * @returns {boolean|undefined} True if the search field is shown, false if it is hidden, or undefined if not available.
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted HAN-AS-INA-UI
+         */
+        getShowSearchField () {
+            if (this.#isShellBar()) {
+                return this.#oShellBar.getShowSearchField();
+            }
+        }
+
+        /**
+         * Binds the ShowSearchField property to a model. The model value must be compatible with
+         * the value of @see #setShowSearchField.
+         *
+         * @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
+         */
+        bindShowSearchField (sPath, oModel) {
+            this.bindModelProperty(sPath, oModel, "showSearchField", this.setShowSearchField.bind(this));
+        }
+
+        /**
+         * Unbinds the ShowSearchField property from a model.
+         *
+         * @since 1.142.0
+         * @private
+         * @ui5-restricted ANS
+         */
+        unbindShowSearchField () {
+            this.unbindModelProperty("showSearchField");
+        }
+
+        /**
+         * Attaches a handler to the search button press event.
+         * Fired, when the search button is activated.
+         * Note: You can prevent expanding/collapsing of the search field by calling <code>event.preventDefault()</code>.
+         *
+         * @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 HAN-AS-INA-UI
+         */
+        attachSearchButtonPress (...args) {
+            if (this.#isShellBar()) {
+                this.#oShellBar.attachSearchButtonClick(...args);
+            } else {
+                this.#getShellHeaderSearchButton()?.attachPress(...args);
+            }
+        }
+
+        /**
+         * Detaches a handler from the search button 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 HAN-AS-INA-UI
+         */
+        detachSearchButtonPress (...args) {
+            if (this.#isShellBar()) {
+                this.#oShellBar.detachSearchButtonClick(...args);
+            } else {
+                this.#getShellHeaderSearchButton()?.detachPress(...args);
+            }
+        }
+
+        /**
+         * Detaches a handler from the search button toggle event.
+         * Fired, when the search field is expanded or collapsed.
+         * Note: this event is only available when using the ShellBar.
+         *
+         * @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 HAN-AS-INA-UI
+         */
+        attachSearchFieldToggle (...args) {
+            if (this.#isShellBar()) {
+                this.#oShellBar.attachSearchFieldToggle(...args);
+            }
+        }
+
+        /**
+         * Detaches a handler from the search field toggle 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 HAN-AS-INA-UI
+         */
+        detachSearchFieldToggle (...args) {
+            if (this.#isShellBar()) {
+                this.#oShellBar.detachSearchFieldToggle(...args);
+            }
+        }
+
+        /**
+         * Attaches a handler to the search field clear event.
+         * Fired, when the search cancel button is activated.
+         * Note: You can prevent the default behavior (clearing the search field value)
+         * by calling <code>event.preventDefault()</code>. The search will still be closed.
+         * Note: The search-field-clear event is in an experimental state and is a
+         * subject to change.
+         * Note: this event is only available when using the ShellBar.
+         *
+         * @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
+         * @experimental
+         * @ui5-restricted HAN-AS-INA-UI
+         */
+        attachSearchFieldClear (...args) {
+            if (this.#isShellBar()) {
+                this.#oShellBar.attachSearchFieldClear(...args);
+            }
+        }
+
+        /**
+         * Detaches a handler from the search field clear 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
+         * @experimental
+         * @ui5-restricted HAN-AS-INA-UI
+         */
+        detachSearchFieldClear (...args) {
+            if (this.#isShellBar()) {
+                this.#oShellBar.detachSearchFieldClear(...args);
+            }
+        }
+    }
+
+    return SearchAPI;
+});

package/src/main/js/sap/ushell/modules/Search/SearchProvider.js

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