@microsoft/teams-js 2.16.0-beta.0 → 2.16.0-beta.1

package/dist/MicrosoftTeams.d.ts

@@ -3630,9 +3630,9 @@ export interface DialogInfo {
 export type TaskInfo = DialogInfo;
 /**
     * @beta
-    * Data structure to be used with the {@link teamsCore.registerOnLoadHandler teamsCore.registerOnLoadHandler(handler: (context: LoadContext) => void): void} to pass the context to the app.
+    * Data structure to be used with the {@link app.lifecycle.registerOnResumeHandler app.lifecycle.registerOnResumeHandler(handler: (context: ResumeContext) => void): void} to pass the context to the app.
     */
-export interface LoadContext {
+export interface ResumeContext {
         /**
             * The entity that is requested to be loaded
             */
@@ -3642,6 +3642,11 @@ export interface LoadContext {
             */
         contentUrl: string;
 }
+/**
+    * @deprecated
+    * As of 2.14.1, please use ResumeContext instead.
+    */
+export type LoadContext = ResumeContext;
 /** Represents information about a frame within a tab or dialog module. */
 export interface FrameInfo {
         /**
@@ -4285,6 +4290,56 @@ export namespace app {
             * @returns Promise that will be fulfilled when the operation has completed
             */
         export function openLink(deepLink: string): Promise<void>;
+        /**
+            * A namespace for enabling the suspension or delayed termination of an app when the user navigates away.
+            * When an app registers for the registerBeforeSuspendOrTerminateHandler, it chooses to delay termination.
+            * When an app registers for both registerBeforeSuspendOrTerminateHandler and registerOnResumeHandler, it chooses the suspension of the app .
+            * Please note that selecting suspension doesn't guarantee prevention of background termination.
+            * The outcome is influenced by factors such as available memory and the number of suspended apps.
+            *
+            * @beta
+            */
+        export namespace lifecycle {
+                /**
+                    * Register on resume handler function type
+                    *
+                    * @param context - Data structure to be used to pass the context to the app.
+                    */
+                type registerOnResumeHandlerFunctionType = (context: ResumeContext) => void;
+                /**
+                    * Register before suspendOrTerminate handler function type
+                    *
+                    * @returns void
+                    */
+                type registerBeforeSuspendOrTerminateHandlerFunctionType = () => void;
+                /**
+                    * Registers a handler to be called before the page is suspended or terminated. Once a user navigates away from an app,
+                    * the handler will be invoked. App developers can use this handler to save unsaved data, pause sync calls etc.
+                    *
+                    * @param handler - The handler to invoke before the page is suspended or terminated. When invoked, app can perform tasks like cleanups, logging etc.
+                    * Upon returning, the app will be suspended or terminated.
+                    *
+                    */
+                export function registerBeforeSuspendOrTerminateHandler(handler: registerBeforeSuspendOrTerminateHandlerFunctionType): void;
+                /**
+                    * Registers a handler to be called when the page has been requested to resume from being suspended.
+                    *
+                    * @param handler - The handler to invoke when the page is requested to be resumed. The app is supposed to navigate to
+                    * the appropriate page using the ResumeContext. Once done, the app should then call {@link notifySuccess}.
+                    *
+                    * @beta
+                    */
+                export function registerOnResumeHandler(handler: registerOnResumeHandlerFunctionType): void;
+                /**
+                    * Checks if app.lifecycle is supported by the host.
+                    * @returns boolean to represent whether the lifecycle capability is supported
+                    * @throws Error if {@linkcode app.initialize} has not successfully completed
+                    *
+                    * @beta
+                    */
+                export function isSupported(): boolean;
+                export {};
+        }
         export {};
 }
 
@@ -6877,6 +6932,9 @@ export namespace teamsCore {
             *
             * @param handler - The handler to invoke when the page is loaded.
             *
+            * @deprecated
+            * As of 2.14.1, please use {@link app.lifecycle.registerOnResumeHandler} instead.
+            *
             * @beta
             */
         export function registerOnLoadHandler(handler: registerOnLoadHandlerFunctionType): void;
@@ -6889,6 +6947,8 @@ export namespace teamsCore {
             *
             * @param handler - The handler to invoke when the page is loaded.
             * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
+            *
+            * @deprecated
             */
         export function registerOnLoadHandlerHelper(handler: registerOnLoadHandlerFunctionType, versionSpecificHelper?: () => void): void;
         /**
@@ -6900,6 +6960,7 @@ export namespace teamsCore {
             * @param handler - The handler to invoke before the page is unloaded. If this handler returns true the page should
             * invoke the readyToUnload function provided to it once it's ready to be unloaded.
             *
+            * @deprecated
             * @beta
             */
         export function registerBeforeUnloadHandler(handler: registerBeforeUnloadHandlerFunctionType): void;
@@ -6913,6 +6974,8 @@ export namespace teamsCore {
             * @param handler - - The handler to invoke before the page is unloaded. If this handler returns true the page should
             * invoke the readyToUnload function provided to it once it's ready to be unloaded.
             * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
+            *
+            * @deprecated
             */
         export function registerBeforeUnloadHandlerHelper(handler: registerBeforeUnloadHandlerFunctionType, versionSpecificHelper?: () => void): void;
         /**

package/dist/MicrosoftTeams.js

@@ -1976,6 +1976,11 @@ var teamsRuntimeConfig = {
     hostVersionsInfo: teamsMinAdaptiveCardVersion,
     isLegacyTeams: true,
     supports: {
+        app: {
+            lifecycle: {
+                caching: {},
+            },
+        },
         appInstallDialog: {},
         appEntity: {},
         call: {},
@@ -2207,7 +2212,7 @@ var _minRuntimeConfigToUninitialize = {
  * @hidden
  *  Package version.
  */
-var version = "2.16.0-beta.0";
+var version = "2.16.0-beta.1";
 
 ;// CONCATENATED MODULE: ./src/internal/internalAPIs.ts
 
@@ -3674,6 +3679,66 @@ var app;
         });
     }
     app.openLink = openLink;
+    /**
+     * A namespace for enabling the suspension or delayed termination of an app when the user navigates away.
+     * When an app registers for the registerBeforeSuspendOrTerminateHandler, it chooses to delay termination.
+     * When an app registers for both registerBeforeSuspendOrTerminateHandler and registerOnResumeHandler, it chooses the suspension of the app .
+     * Please note that selecting suspension doesn't guarantee prevention of background termination.
+     * The outcome is influenced by factors such as available memory and the number of suspended apps.
+     *
+     * @beta
+     */
+    var lifecycle;
+    (function (lifecycle) {
+        /**
+         * Registers a handler to be called before the page is suspended or terminated. Once a user navigates away from an app,
+         * the handler will be invoked. App developers can use this handler to save unsaved data, pause sync calls etc.
+         *
+         * @param handler - The handler to invoke before the page is suspended or terminated. When invoked, app can perform tasks like cleanups, logging etc.
+         * Upon returning, the app will be suspended or terminated.
+         *
+         */
+        function registerBeforeSuspendOrTerminateHandler(handler) {
+            if (!handler) {
+                throw new Error('[app.lifecycle.registerBeforeSuspendOrTerminateHandler] Handler cannot be null');
+            }
+            if (!isSupported()) {
+                throw errorNotSupportedOnPlatform;
+            }
+            handlers_registerBeforeSuspendOrTerminateHandler(handler);
+        }
+        lifecycle.registerBeforeSuspendOrTerminateHandler = registerBeforeSuspendOrTerminateHandler;
+        /**
+         * Registers a handler to be called when the page has been requested to resume from being suspended.
+         *
+         * @param handler - The handler to invoke when the page is requested to be resumed. The app is supposed to navigate to
+         * the appropriate page using the ResumeContext. Once done, the app should then call {@link notifySuccess}.
+         *
+         * @beta
+         */
+        function registerOnResumeHandler(handler) {
+            if (!handler) {
+                throw new Error('[app.lifecycle.registerOnResumeHandler] Handler cannot be null');
+            }
+            if (!isSupported()) {
+                throw errorNotSupportedOnPlatform;
+            }
+            handlers_registerOnResumeHandler(handler);
+        }
+        lifecycle.registerOnResumeHandler = registerOnResumeHandler;
+        /**
+         * Checks if app.lifecycle is supported by the host.
+         * @returns boolean to represent whether the lifecycle capability is supported
+         * @throws Error if {@linkcode app.initialize} has not successfully completed
+         *
+         * @beta
+         */
+        function isSupported() {
+            var _a;
+            return ensureInitialized(runtime) && !!((_a = runtime.supports.app) === null || _a === void 0 ? void 0 : _a.lifecycle);
+        }
+        lifecycle.isSupported = isSupported;
+    })(lifecycle = app.lifecycle || (app.lifecycle = {}));
 })(app || (app = {}));
 /**
  * @hidden
@@ -4545,6 +4610,8 @@ var HandlersPrivate = /** @class */ (function () {
         HandlersPrivate.handlers['themeChange'] = handleThemeChange;
         HandlersPrivate.handlers['load'] = handleLoad;
         HandlersPrivate.handlers['beforeUnload'] = handleBeforeUnload;
+        HandlersPrivate.handlers['beforeSuspendOrTerminate'] = handleBeforeSuspendOrTerminate;
+        HandlersPrivate.handlers['resume'] = handleResume;
         pages.backStack._initialize();
     };
     /**
@@ -4557,6 +4624,8 @@ var HandlersPrivate = /** @class */ (function () {
         HandlersPrivate.themeChangeHandler = null;
         HandlersPrivate.loadHandler = null;
         HandlersPrivate.beforeUnloadHandler = null;
+        HandlersPrivate.beforeSuspendOrTerminateHandler = null;
+        HandlersPrivate.resumeHandler = null;
     };
     HandlersPrivate.handlers = {};
     return HandlersPrivate;
@@ -4668,6 +4737,8 @@ function handleThemeChange(theme) {
 /**
  * @internal
  * Limited to Microsoft-internal use
+ *
+ * @deprecated
  */
 function handlers_registerOnLoadHandler(handler) {
     HandlersPrivate.loadHandler = handler;
@@ -4676,6 +4747,8 @@ function handlers_registerOnLoadHandler(handler) {
 /**
  * @internal
  * Limited to Microsoft-internal use
+ *
+ * @deprecated
  */
 function handleLoad(context) {
     if (HandlersPrivate.loadHandler) {
@@ -4688,6 +4761,8 @@ function handleLoad(context) {
 /**
  * @internal
  * Limited to Microsoft-internal use
+ *
+ * @deprecated
  */
 function handlers_registerBeforeUnloadHandler(handler) {
     HandlersPrivate.beforeUnloadHandler = handler;
@@ -4696,6 +4771,8 @@ function handlers_registerBeforeUnloadHandler(handler) {
 /**
  * @internal
  * Limited to Microsoft-internal use
+ *
+ * @deprecated
  */
 function handleBeforeUnload() {
     var readyToUnload = function () {
@@ -4710,6 +4787,52 @@ function handleBeforeUnload() {
         }
     }
 }
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+function handlers_registerBeforeSuspendOrTerminateHandler(handler) {
+    HandlersPrivate.beforeSuspendOrTerminateHandler = handler;
+    handler && sendMessageToParent('registerHandler', ['beforeSuspendOrTerminate']);
+}
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+function handleBeforeSuspendOrTerminate() {
+    var readyToSuspendOrTerminate = function () {
+        sendMessageToParent('readyToSuspendOrTerminate', []);
+    };
+    if (HandlersPrivate.beforeSuspendOrTerminateHandler) {
+        HandlersPrivate.beforeSuspendOrTerminateHandler();
+    }
+    if (Communication.childWindow) {
+        sendMessageEventToChild('beforeSuspendOrTerminate');
+    }
+    else {
+        readyToSuspendOrTerminate();
+    }
+}
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+function handlers_registerOnResumeHandler(handler) {
+    HandlersPrivate.loadHandler = handler;
+    handler && sendMessageToParent('registerHandler', ['resume']);
+}
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+function handleResume(context) {
+    if (HandlersPrivate.loadHandler) {
+        HandlersPrivate.loadHandler(context);
+    }
+    if (Communication.childWindow) {
+        sendMessageEventToChild('resume', [context]);
+    }
+}
 
 ;// CONCATENATED MODULE: ./src/internal/communication.ts
 /* eslint-disable @typescript-eslint/ban-types */
@@ -7881,6 +8004,9 @@ var teamsCore;
      *
      * @param handler - The handler to invoke when the page is loaded.
      *
+     * @deprecated
+     * As of 2.14.1, please use {@link app.lifecycle.registerOnResumeHandler} instead.
+     *
      * @beta
      */
     function registerOnLoadHandler(handler) {
@@ -7900,6 +8026,8 @@ var teamsCore;
      *
      * @param handler - The handler to invoke when the page is loaded.
      * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
+     *
+     * @deprecated
      */
     function registerOnLoadHandlerHelper(handler, versionSpecificHelper) {
         // allow for registration cleanup even when not finished initializing
@@ -7919,6 +8047,7 @@ var teamsCore;
      * @param handler - The handler to invoke before the page is unloaded. If this handler returns true the page should
      * invoke the readyToUnload function provided to it once it's ready to be unloaded.
      *
+     * @deprecated
      * @beta
      */
     function registerBeforeUnloadHandler(handler) {
@@ -7939,6 +8068,8 @@ var teamsCore;
      * @param handler - - The handler to invoke before the page is unloaded. If this handler returns true the page should
      * invoke the readyToUnload function provided to it once it's ready to be unloaded.
      * @param versionSpecificHelper - The helper function containing logic pertaining to a specific version of the API.
+     *
+     * @deprecated
      */
     function registerBeforeUnloadHandlerHelper(handler, versionSpecificHelper) {
         // allow for registration cleanup even when not finished initializing