// Copyright (c) 2009-2026 SAP SE, All Rights Reserved

/**
 * @fileoverview This file contains the ApplicationHandle class.
 * It provides a handle to navigate to and manage an application.
 */
sap.ui.define([
    "sap/ushell/state/StateManager",
    "sap/ushell/utils"
], (
    StateManager,
    ushellUtils
) => {
    "use strict";

    // shortcut for sap.ushell.state.StateManager.LaunchpadState
    const LaunchpadState = StateManager.LaunchpadState;

    /**
     * @alias sap.ushell.appIntegration.ApplicationHandle
     * @class
     * @classdesc Provides a handle for navigating to and managing an application.
     * Contains references to the application container and navigation metadata.
     *
     * @private
     */
    class ApplicationHandle {
        static #oNavContainer = null;
        static #oAppLifeCycle = null;

        #sStorageAppId = null;
        #oResolvedHashFragment = null;
        #oApplicationContainer = null;
        #sNavigationRedirectHash = null;

        /**
         * Creates a new ApplicationHandle instance.
         * @param {string} sStorageAppId The storage application ID.
         * @param {object} oResolvedHashFragment The resolved hash fragment.
         * @param {sap.ushell.appIntegration.ApplicationContainer} oApplicationContainer The application container.
         * @param {string} sNavigationRedirectHash The navigation redirect hash, if any.
         *
         * @private
         */
        constructor (sStorageAppId, oResolvedHashFragment, oApplicationContainer, sNavigationRedirectHash) {
            this.#sStorageAppId = sStorageAppId;
            this.#oResolvedHashFragment = oResolvedHashFragment;
            this.#oApplicationContainer = oApplicationContainer;
            this.#sNavigationRedirectHash = sNavigationRedirectHash;
        }

        /**
         * Initializes the ApplicationHandle with navigation container and app lifecycle references.
         * @param {sap.ushell.appIntegration.AppLifeCycle} oAppLifeCycle The app lifecycle instance.
         * @param {sap.ushell.renderer.NavContainer} oNavContainer The navigation container.
         *
         * @private
         */
        static init (oAppLifeCycle, oNavContainer) {
            this.#oAppLifeCycle = oAppLifeCycle;
            this.#oNavContainer = oNavContainer;
        }

        /**
         * Navigates to the application.
         * @param {boolean} bIsNavToHome Whether this is a navigation to home.
         * @returns {Promise} Resolves when the navigation is complete.
         *
         * @private
         */
        async navTo (bIsNavToHome) {
            return ApplicationHandle.#oAppLifeCycle.oApplicationNavigateQueue.push(async () => {
                const sAppContainerId = this.#oApplicationContainer.getId();
                ApplicationHandle.#oNavContainer.navTo(sAppContainerId);

                ApplicationHandle.#oAppLifeCycle.switchViewState(
                    bIsNavToHome ? LaunchpadState.Home : LaunchpadState.App,
                    this.#sStorageAppId,
                    this.#oResolvedHashFragment.applicationType,
                    this.#oResolvedHashFragment.explicitNavMode
                );

                // await a tick to ensure the navigation is processed
                await ushellUtils.awaitTimeout(0);
            });
        }

        /**
         * Returns the navigation redirect hash if one was specified.
         * @returns {string|null} The navigation redirect hash or null.
         *
         * @private
         */
        getNavigationRedirectHash () {
            return this.#sNavigationRedirectHash;
        }
    }

    return ApplicationHandle;
});
