@sapui5/sap.ushell 1.141.3 → 1.142.0

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);

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

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

package/src/main/js/sap/ushell/modules/loader/AbstractLoader.js

@@ -0,0 +1,95 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+/**
+ * @file Abstract module loader providing common functionality for all module loaders.
+ */
+sap.ui.define([
+    "sap/base/Log",
+    "sap/ushell/Config",
+    "sap/ushell/utils",
+    "sap/ushell/EventHub"
+], (
+    Log,
+    Config,
+    ushellUtils,
+    EventHub
+) => {
+    "use strict";
+
+    /**
+     * Abstract module loader
+     * @abstract
+     *
+     * @since 1.142.0
+     * @private
+     */
+    class AbstractLoader {
+        /**
+         * Doables to be used for cleaning up configuration listeners.
+         */
+        #aDoables = [];
+
+        /**
+         * Loads the module of the given module path and creates an instance of it.
+         *
+         * @param {string} sModulePath The module path to load the module.
+         * @param {object} oModuleAPI The module API instance.
+         * @returns {Promise} A promise that resolves with the module instance.
+         *
+         * @since 1.142.0
+         * @private
+         */
+        async loadModule (sModulePath, oModuleAPI) {
+            const oModuleLoaded = Promise.withResolvers();
+            EventHub.once("CoreResourcesComplementLoaded").do(async () => {
+                const [Module] = await ushellUtils.requireAsync([sModulePath]);
+                oModuleLoaded.resolve(new Module(oModuleAPI));
+            });
+            return oModuleLoaded.promise;
+        }
+
+        /**
+         * Reads the ushell Config at the given path, parses it as JSON, and returns the resulting object.
+         * If the configuration value is not set, it returns an empty object. It throws an error if parsing fails.
+         *
+         * @param {string} sPath The configuration path to read.
+         * @returns {object} The parsed JSON object from the configuration or an empty object if not set.
+         *
+         * @since 1.142.0
+         * @private
+         */
+        parseJSONFromConfig (sPath) {
+            const sConfigValue = Config.last(sPath);
+            if (sConfigValue) {
+                try {
+                    return JSON.parse(sConfigValue);
+                } catch (oError) {
+                    Log.error(`Failed to parse JSON from configuration at path: ${sPath}`, oError);
+                }
+            }
+            return {};
+        }
+
+        /**
+         * Registers a configuration listener for the given path and stores the doable for cleanup.
+         * @param {string} sPath The configuration path to listen to.
+         * @param {function} fnListener The listener function to be called on configuration changes.
+         * @since 1.142.0
+         * @private
+         */
+        registerConfigListener (sPath, fnListener) {
+            this.#aDoables.push(Config.on(sPath).do(fnListener));
+        }
+
+        /**
+         * Resets the loader by removing all configuration listeners.
+         * @since 1.142.0
+         * @private
+         */
+        async exit () {
+            this.#aDoables.forEach((oDoable) => oDoable.off());
+            this.#aDoables = [];
+        }
+    }
+    return AbstractLoader;
+});

package/src/main/js/sap/ushell/modules/loader/NotificationsLoader.js

@@ -0,0 +1,148 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+sap.ui.define([
+    "sap/ushell/Config",
+    "sap/ushell/modules/loader/AbstractLoader",
+    "sap/ushell/modules/Notifications/NotificationsAPI",
+    "sap/ushell/state/StateManager"
+], (
+    Config,
+    AbstractLoader,
+    NotificationsAPI,
+    StateManager
+) => {
+    "use strict";
+    const sConfigBasePath = "/core/notifications";
+
+    // shortcut for sap.ushell.state.StateManager.Operation
+    const Operation = StateManager.Operation;
+
+    /**
+     * Notifications component for the Fiori Launchpad.
+     *
+     * @augments sap.ushell.modules.loader.AbstractLoader
+     * @since 1.142.0
+     * @private
+     */
+    class NotificationsLoader extends AbstractLoader {
+        /**
+         * The instance of the loaded notifications module.
+         *
+         * @type {sap.ushell.modules.Notifications.NotificationsProvider|null}
+         * @since 1.142.0
+         * @private
+         */
+        #oModuleInstance;
+
+        /**
+         * The API object passed to the notifications module.
+         *
+         * @type {sap.ushell.modules.Notifications.NotificationsAPI}
+         * @since 1.142.0
+         * @private
+         */
+        #oModuleAPI;
+
+        /**
+         * A promise that resolves when the loader is initialized.
+         * @type {Promise}
+         */
+        #pInitialized;
+
+        /**
+         * Creates a new instance of the NotificationsLoader.
+         *
+         * @since 1.142.0
+         * @private
+         */
+        constructor () {
+            super();
+            this.#init();
+        }
+
+        /**
+         * Initializes the loader by setting up a listener for configuration changes.
+         * Loads or unloads the notifications module based on the configuration.
+         *
+         * @returns {Promise} A promise that resolves when the initialization is complete.
+         * @since 1.142.0
+         * @private
+         */
+        async #init () {
+            this.registerConfigListener("/core/notifications", async () => {
+                const bEnabled = Config.last("/core/notifications/enabled");
+                StateManager.updateAllBaseStates("header.notifications.visible", Operation.Set, bEnabled);
+                await this.#cleanup();
+                if (bEnabled) {
+                    this.#oModuleInstance = await this.#load();
+                }
+                this.#pInitialized.resolve();
+            });
+        }
+
+        /**
+         * Returns a promise that resolves when the loader is initialized.
+         * @returns {Promise} A promise that resolves when the loader is initialized.
+         * @since 1.142.0
+         * @private
+         */
+        initialized () {
+            return this.#pInitialized.promise;
+        }
+
+        /**
+         * Loads the notifications module and creates an instance of it.
+         *
+         * @returns {Promise<sap.ushell.modules.Notifications.NotificationsProvider>} A promise that resolves to the notifications module instance.
+         * @since 1.142.0
+         * @private
+         */
+        async #load () {
+            this.#oModuleAPI = new NotificationsAPI(this.parseJSONFromConfig(`${sConfigBasePath}/configuration`));
+
+            // load the module
+            return this.loadModule(Config.last(`${sConfigBasePath}/modulePath`), this.#oModuleAPI);
+        }
+
+        /**
+         * Resets the loader by cleaning up the current module instance and re-initializing it.
+         *
+         * @returns {Promise} A promise that resolves when the module instance is destroyed and references are cleared.
+         * @since 1.142.0
+         * @private
+         */
+        async reset () {
+            await this.exit();
+            await this.#init();
+        }
+
+        /**
+         * Cleans up the current module instance and clears the API reference.
+         * @returns {Promise} A promise that resolves when the cleanup is complete.
+         * @since 1.142.0
+         * @private
+         */
+        async #cleanup () {
+            if (this.#oModuleInstance && typeof this.#oModuleInstance.exit === "function") {
+                await this.#oModuleInstance.exit();
+            }
+            this.#oModuleAPI = null;
+            this.#oModuleInstance = null;
+            this.#pInitialized = Promise.withResolvers();
+        }
+
+        /**
+         * Cleans up the loader by resetting the module instance and calling the superclass exit method.
+         *
+         * @returns {Promise} A promise that resolves when the loader is cleaned up.
+         * @since 1.142.0
+         * @private
+         * @override
+         */
+        async exit () {
+            await super.exit();
+            await this.#cleanup();
+        }
+    }
+    return new NotificationsLoader();
+});