@sapui5/sap.ushell 1.126.1 → 1.127.1

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

@@ -0,0 +1,209 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+    "sap/base/util/deepClone",
+    "sap/ui/core/Element"
+], function (
+    deepClone,
+    Element
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.state.ControlManager
+     * @namespace
+     * @description This class handles the lifecycle of controls created by the launchpad.
+     * The controls are destroyed in sync with the application lifecycle.
+     *
+     * @since 1.127.0
+     * @private
+     */
+    class ControlManager {
+        /**
+         * List of all managed controls.
+         * @type {sap.ui.core.ID[]}
+         */
+        #aAllControls = [];
+        /**
+         * List of all managed controls in the current state.
+         * @type {sap.ui.core.ID[]}
+         */
+        #aCurrentStateControls = [];
+        /**
+         * List of all managed controls in the base state.
+         * @type {sap.ui.core.ID[]}
+         */
+        #aBaseStateControls = [];
+
+        /**
+         * Adds a control to the list of managed controls.
+         * Only controls related to the current state are destroyed.
+         * Once a control is added related to the base state, it is not destroyed.
+         * @param {sap.ui.core.ID} sId The ID of the control.
+         * @param {boolean} bCurrentState Indicates whether the control is in the current state.
+         * @param {sap.ushell.state.StateManager.LaunchpadState} sCurrentLaunchpadState The current launchpad state.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ControlManager#addManagedControl
+         */
+        addManagedControl (sId, bCurrentState, sCurrentLaunchpadState) {
+            if (!this.#aAllControls.includes(sId)) {
+                this.#aAllControls.push(sId);
+            }
+
+            // any control that is created while the state is home should is considered as base state control
+            if (sCurrentLaunchpadState === "home") {
+                bCurrentState = false;
+            }
+
+            if (bCurrentState && !this.#aCurrentStateControls.includes(sId)) {
+                this.#aCurrentStateControls.push(sId);
+            } else if (!bCurrentState && !this.#aBaseStateControls.includes(sId)) {
+                this.#aBaseStateControls.push(sId);
+            }
+        }
+
+        /**
+         * Destroys all controls related to the current state.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ControlManager#destroyManagedControls
+         */
+        destroyManagedControls () {
+            this.#aCurrentStateControls.forEach((sId) => {
+                if (this.#aBaseStateControls.includes(sId)) {
+                    return;
+                }
+                this.destroyManagedControl(sId);
+            });
+            this.#aCurrentStateControls = [];
+        }
+
+        /**
+         * Destroys all controls known to the control manager.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        #destroyAllManagedControls () {
+            // shall only be called during flp destroy
+            this.#aAllControls.forEach((sId) => {
+                this.destroyManagedControl(sId);
+            });
+            this.#aAllControls = [];
+        }
+
+        /**
+         * Destroys the control with the given ID.
+         * It does not remove the control from the list of managed controls.
+         * @param {sap.ui.core.ID} sId The ID of the control.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ControlManager#destroyManagedControl
+         */
+        destroyManagedControl (sId) {
+            const oControl = Element.getElementById(sId);
+            if (oControl) {
+                oControl.destroy();
+            }
+        }
+
+        /**
+         * Stores the list of managed controls in the given storage entry.
+         * The stored list is used to restore the controls when the application is restarted.
+         *
+         * Once an application is stored the related controls are not directly managed anymore.
+         * Any other application reusing the same control without keep-alive will destroy the control implicitly on navigation.
+         * @param {object} oStorageEntry The storage entry.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ControlManager#storeList
+         */
+        storeList (oStorageEntry = {}) {
+            oStorageEntry.controlManager = {
+                currentControls: deepClone(this.#aCurrentStateControls)
+            };
+        }
+
+        /**
+         * Restores the list of managed controls from the given storage entry.
+         * @param {object} oStorageEntry The storage entry.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ControlManager#restoreList
+         */
+        restoreList (oStorageEntry = {}) {
+            const { currentControls } = oStorageEntry.controlManager || {};
+            if (currentControls) {
+                this.#aCurrentStateControls = deepClone(currentControls);
+            } else {
+                this.#aCurrentStateControls = [];
+            }
+        }
+
+        /**
+         * Flushes the list of managed controls.
+         * The controls are not destroyed.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ControlManager#flushList
+         */
+        flushList () {
+            this.#aCurrentStateControls = [];
+        }
+
+        /**
+         * Destroys the managed controls based on the storage entry.
+         * @param {object} oStorageEntry The storage entry.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ControlManager#destroyFromStorage
+         */
+        destroyFromStorage (oStorageEntry = {}) {
+            const { currentControls } = oStorageEntry.controlManager || {};
+
+            if (Array.isArray(currentControls)) {
+                currentControls.forEach((sId) => {
+                    this.destroyManagedControl(sId);
+                });
+            }
+        }
+
+        /**
+         * ONLY FOR TESTING!
+         * Resets the control manager.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ControlManager#reset
+         */
+        reset () {
+            this.destroy();
+
+            this.#aCurrentStateControls = [];
+            this.#aBaseStateControls = [];
+        }
+
+        /**
+         * Destroys all managed controls.
+         * Shall only be called by the state manager.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ControlManager#destroy
+         */
+        destroy () {
+            this.#destroyAllManagedControls();
+        }
+    }
+
+    return new ControlManager();
+
+});

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

@@ -0,0 +1,180 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+    "sap/base/util/deepClone",
+    "sap/ui/base/EventProvider",
+    "sap/ushell/state/StrategyFactory"
+], function (
+    deepClone,
+    EventProvider,
+    StrategyFactory
+) {
+    "use strict";
+
+    /**
+     * @typedef {object} sap.ushell.state.CurrentState.Command
+     * A command that should be executed to update the state.
+     * @property {sap.ushell.state.StateManager.Path} path The path to the property that should be updated.
+     * @property {sap.ushell.state.StateManager.Operation} operation The operation that should be performed.
+     * @property {any} value The value that should be set.
+     *
+     * @since 1.127.0
+     * @private
+     */
+
+    /**
+     * @alias sap.ushell.state.CurrentState
+     * @namespace
+     * @description This class manages the current state of applications.
+     *
+     * @since 1.127.0
+     * @private
+     */
+    class CurrentState {
+        /**
+         * The list of commands that should be executed to update the state.
+         * @type {sap.ushell.state.CurrentState.Command[]}
+         */
+        #aCommandList = [];
+        /**
+         * The event provider that is used to notify listeners about state changes.
+         * @type {sap.ui.base.EventProvider}
+         */
+        #oEventProvider = new EventProvider();
+
+        /**
+         * Attaches an event handler to the state change event.
+         * The handler is called when the state changes e.g. when the state is restored or flushed.
+         * @param {object} oData An object that will be passed to the handler along with the event object when the event is fired
+         * @param {function} fnHandler The handler function to call when the event occurs.
+         * @param {object} oListener The data to be passed to the event handler.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.CurrentState#attachStateChange
+         */
+        attachStateChange (...args) {
+            this.#oEventProvider.attachEvent("stateChange", ...args);
+        }
+
+        /**
+         * Detaches an event handler from the state change event.
+         * @param {function} fnHandler The handler function.
+         * @param {object} oListener The data to be passed to the event handler.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.CurrentState#detachStateChange
+         */
+        detachStateChange (...args) {
+            this.#oEventProvider.detachEvent("stateChange", ...args);
+        }
+
+        /**
+         * Updates the state with the given operation and value.
+         * @param {sap.ushell.state.StateManager.Path} sPath The path to the property that should be updated.
+         * @param {sap.ushell.state.StateManager.Operation} sOperation The operation that should be performed.
+         * @param {any} vValue The value that should be set.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.CurrentState#updateState
+         */
+        updateState (sPath, sOperation, vValue) {
+            this.#aCommandList.push({
+                path: sPath,
+                value: vValue,
+                operation: sOperation
+            });
+        }
+
+        /**
+         * Flushes the state and prepares it for a new current state.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.CurrentState#flushState
+         */
+        flushState () {
+            this.#aCommandList = [];
+            this.#oEventProvider.fireEvent("stateChange");
+        }
+
+        /**
+         * Stores the current state in the given storage entry.
+         * The stored state is used to restore the state when the application is restarted.
+         * @param {object} oStorageEntry The storage entry.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.CurrentState#storeState
+         */
+        storeState (oStorageEntry) {
+            oStorageEntry.currentState = {
+                commandList: deepClone(this.#aCommandList)
+            };
+        }
+
+        /**
+         * Restores the state from the given storage entry.
+         * @param {object} oStorageEntry The storage entry.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.CurrentState#restoreState
+         */
+        restoreState (oStorageEntry) {
+            const { commandList } = oStorageEntry.currentState || {};
+            if (commandList) {
+                this.#aCommandList = deepClone(commandList);
+            } else {
+                this.#aCommandList = [];
+            }
+            this.#oEventProvider.fireEvent("stateChange");
+        }
+
+        /**
+         * Applies the current state to the given state data.
+         * The current state is applied in-place.
+         * @param {object} oStateData The state data.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.CurrentState#applyState
+         */
+        applyState (oStateData) {
+            this.#aCommandList.forEach(({ path, value, operation }) => {
+                StrategyFactory.perform(oStateData, path, operation, value);
+            });
+        }
+
+        /**
+         * ONLY FOR TESTING!
+         * Resets the current state.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.CurrentState#reset
+         */
+        reset () {
+            this.destroy();
+
+            this.#aCommandList = [];
+            this.#oEventProvider = new EventProvider();
+        }
+
+        /**
+         * Destroys the current state.
+         * Should only be called by the state manager.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.CurrentState#destroy
+         */
+        destroy () {
+            this.#oEventProvider.destroy();
+        }
+    }
+
+    return new CurrentState();
+});

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

@@ -0,0 +1,75 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+    "sap/ushell/state/ControlManager",
+    "sap/ushell/state/CurrentState"
+], function (
+    ControlManager,
+    CurrentState
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.state.KeepAlive
+     * @namespace
+     * @description This module is a facade for the keep-alive mechanism in the state management.
+     *
+     * @since 1.127.0
+     * @private
+     */
+    class KeepAlive {
+        /**
+         * Stores the current state of the application.
+         * The stored state is used to restore the application when it is restarted.
+         * @param {object} oStorageEntry The storage entry.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.KeepAlive#store
+         */
+        store (oStorageEntry) {
+            CurrentState.storeState(oStorageEntry);
+            // Store controls list and empty it afterwards because the keep-alive app still need them in future
+            ControlManager.storeList(oStorageEntry);
+        }
+
+        /**
+         * Restores the state of the application.
+         * @param {object} oStorageEntry The storage entry.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.KeepAlive#restore
+         */
+        restore (oStorageEntry) {
+            CurrentState.restoreState(oStorageEntry);
+            ControlManager.restoreList(oStorageEntry);
+        }
+
+        /**
+         * Flushes the current state of the application.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.KeepAlive#flush
+         */
+        flush () {
+            CurrentState.flushState();
+            ControlManager.flushList();
+        }
+
+        /**
+         * Destroys the managed controls based on the storage entry.
+         * @param {object} oStorageEntry The storage entry.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.KeepAlive#destroy
+         */
+        destroy (oStorageEntry) {
+            ControlManager.destroyFromStorage(oStorageEntry);
+        }
+    }
+
+    return new KeepAlive();
+});

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

@@ -0,0 +1,112 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+    "sap/base/util/deepClone",
+    "sap/ui/model/json/JSONModel",
+    "sap/ushell/Config",
+    "sap/ushell/utils/RestrictedJSONModel"
+], function (
+    deepClone,
+    JSONModel,
+    Config,
+    RestrictedJSONModel
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.state.ShellModel
+     * @namespace
+     * @description The model representing the current state of the shell.
+     * The model is a read-only model. It is updated by the state manager.
+     * The controller can access to bind to this model.
+     *
+     * @since 1.127.0
+     * @private
+     */
+    class ShellModel {
+        /**
+         * The model representing the current state of the shell.
+         * @type {sap.ushell.utils.RestrictedJSONModel}
+         */
+        #model = new RestrictedJSONModel();
+        /**
+         * The model representing the configuration of the shell.
+         * References <code>/core/shell/model</code> of the {@link sap.ushell.Config}.
+         * @type {sap.ui.model.json.JSONModel}
+         */
+        #configModel = Config.createModel("/core/shell/model", JSONModel);
+
+        /**
+         * Updates the model with the given state data.
+         * Should only be called by the state manager.
+         * @param {object} oStateData The calculated state data.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ShellModel#updateModel
+         */
+        updateModel (oStateData) {
+            const oClonedState = deepClone(oStateData);
+            this.#model._setData(oClonedState);
+        }
+
+        /**
+         * Returns the model representing the current state of the shell.
+         * This model is a read-only model.
+         * @returns {sap.ui.model.Model} The model.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ShellModel#getModel
+         */
+        getModel () {
+            return this.#model;
+        }
+
+        /**
+         * Returns the model representing the configuration of the shell.
+         * The config model is based on {@link sap.ushell.Config}.
+         * With this any updates are delayed by a tick.
+         * However, the <code>getProperty</code> result is updated immediately.
+         * @returns {sap.ui.model.Model} The model.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ShellModel#getConfigModel
+         */
+        getConfigModel () {
+            return this.#configModel;
+        }
+
+        /**
+         * ONLY FOR TESTING!
+         * Resets the model.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ShellModel#reset
+         */
+        reset () {
+            this.destroy();
+
+            this.#model = new RestrictedJSONModel();
+            this.#configModel = Config.createModel("/core/shell/model", JSONModel);
+        }
+
+        /**
+         * Destroys the model.
+         * Should only be called by the state manager.
+         *
+         * @since 1.127.0
+         * @private
+         * @alias sap.ushell.state.ShellModel#destroy
+         */
+        destroy () {
+            this.#model.destroy();
+            this.#configModel.destroy();
+        }
+    }
+
+    return new ShellModel();
+
+});

package/src/main/js/sap/ushell/state/StateManager/LaunchpadState.js

@@ -0,0 +1,40 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+], function (
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.state.StateManager.LaunchpadState
+     * @enum {string}
+     *
+     * @since 1.127.0
+     * @private
+     */
+    const LaunchpadState = {
+        /**
+         * Describes any view that is considered a home view.
+         *  - Classic Homepage
+         *  - Pages Runtime
+         *  - (Custom)MyHome
+         *
+         * @since 1.127.0
+         * @private
+         */
+        Home: "home",
+
+        /**
+         * Describes any view that is NOT a home view.
+         * - App Finder
+         * - Search
+         * - Applications
+         *
+         * @since 1.127.0
+         * @private
+         */
+        App: "app"
+    };
+
+    return LaunchpadState;
+});

package/src/main/js/sap/ushell/state/StateManager/Operation.js

@@ -0,0 +1,42 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+sap.ui.define([
+], function (
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.state.StateManager.Operation
+     * @enum {string}
+     *
+     * @since 1.127.0
+     * @private
+     */
+    const Operation = {
+        /**
+         * Adds an item to a list.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        Add: "add",
+
+        /**
+         * Removes an item from a list.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        Remove: "remove",
+
+        /**
+         * Sets a property on an object.
+         *
+         * @since 1.127.0
+         * @private
+         */
+        Set: "set"
+    };
+
+    return Operation;
+});