Added renderingSurface property to {app.Page.Context} (#2794)

* initial changes for renderingSurface data

* adding comments

* adding RenderingSurface to index.ts

* run changefile

* adding comments

* adding comments

* increase the bundle size

---------

Co-authored-by: Niharika <[email protected]>

Author: lakhveerk

change/@microsoft-teams-js-96be3430-7bd4-4a40-8554-4be120a97747.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Added `renderingSurface` property to `{app.Page.Context}` capability.",
+  "packageName": "@microsoft/teams-js",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

package.json

@@ -162,7 +162,7 @@
       "brotli": false,
       "path": "./packages/teams-js/dist/esm/packages/teams-js/src/index.js",
       "import": "{ app, authentication, pages }",
-      "limit": "57.204 KB"
+      "limit": "57.33 KB"
     },
     {
       "brotli": false,

packages/teams-js/src/public/app/app.ts

@@ -16,7 +16,15 @@ import { ApiName, ApiVersionNumber, getApiVersionTag, getLogger } from '../../in
 import { inServerSideRenderingEnvironment } from '../../internal/utils';
 import * as messageChannels from '../../private/messageChannels/messageChannels';
 import { AppId } from '../appId';
-import { ChannelType, FrameContexts, HostClientType, HostName, TeamType, UserTeamRole } from '../constants';
+import {
+  ChannelType,
+  FrameContexts,
+  HostClientType,
+  HostName,
+  RenderingSurfaces,
+  TeamType,
+  UserTeamRole,
+} from '../constants';
 import {
   ActionInfo,
   Context as LegacyContext,
@@ -297,6 +305,12 @@ export interface PageInfo {
    */
   frameContext: FrameContexts;
 
+  /**
+   * The mode or surface where the page is rendered (e.g. sidePanel, meetingStage, etc.)
+   * This will be used by the app developers in future to know where in the host the app is rendered instead of the frameContext.
+   */
+  renderingSurface?: RenderingSurfaces;
+
   /**
    * The developer-defined unique ID for the sub-page this content points to.
    * This field should be used to restore to a specific state within a page,
@@ -824,6 +838,7 @@ function transformLegacyContextToAppContext(legacyContext: LegacyContext): Conte
       // eslint-disable-next-line @typescript-eslint/ban-ts-comment
       // @ts-ignore
       frameContext: legacyContext.frameContext ? legacyContext.frameContext : GlobalVars.frameContext,
+      renderingSurface: legacyContext.renderingSurface ? legacyContext.renderingSurface : undefined,
       subPageId: legacyContext.subEntityId,
       isFullScreen: legacyContext.isFullScreen,
       isMultiWindow: legacyContext.isMultiWindow,

packages/teams-js/src/public/constants.ts

@@ -102,6 +102,21 @@ export enum FrameContexts {
   meetingStage = 'meetingStage',
 }
 
+/**
+ * RenderingSurfaces describes the context or surface in which your app is being displayed within the host application.
+ * This parameter allows your app to detect where it is rendered (for example, in a side panel or stage view)
+ * and adjust its behavior or UI accordingly. The intent is to help developers understand the user's context of use,
+ * not the exact pixel size or layout. If a host (such as Outlook Meeting Apps) changes the size of a surface (e.g., makes the side panel larger),
+ * it will still use the same RenderingSurface value. Developers are expected to use responsive UI techniques to adapt to size changes,
+ * since the user's context and intent remain the same even if the surface dimensions change.
+ */
+export enum RenderingSurfaces {
+  /**
+   * The mode the copilot app rendered by the host.
+   */
+  copilotSidePanel = 'copilotSidePanel',
+}
+
 /**
  * Indicates the team type, currently used to distinguish between different team
  * types in Office 365 for Education (team types 1, 2, 3, and 4).

packages/teams-js/src/public/index.ts

@@ -5,6 +5,7 @@ export {
   FrameContexts,
   HostClientType,
   HostName,
+  RenderingSurfaces,
   TaskModuleDimension,
   TeamType,
   UserTeamRole,

packages/teams-js/src/public/interfaces.ts

@@ -1,6 +1,14 @@
 /* eslint-disable @typescript-eslint/no-explicit-any*/
 
-import { ChannelType, DialogDimension, HostClientType, HostName, TeamType, UserTeamRole } from './constants';
+import {
+  ChannelType,
+  DialogDimension,
+  HostClientType,
+  HostName,
+  RenderingSurfaces,
+  TeamType,
+  UserTeamRole,
+} from './constants';
 import { FrameContexts } from './constants';
 
 /**
@@ -582,6 +590,14 @@ export interface Context {
    */
   frameContext?: FrameContexts;
 
+  /**
+   * @deprecated
+   * As of TeamsJS v2.0.0, please use {@link app.PageInfo.renderingSurface | app.Context.page.renderingSurface} instead
+   *
+   * The surface where the tab is rendered (sidePanel, meeting, chat, channel)
+   */
+  renderingSurface?: RenderingSurfaces;
+
   /**
    * @deprecated
    * As of TeamsJS v2.0.0, please use {@link app.Context | app.Context.sharepoint} instead

packages/teams-js/test/public/app.spec.ts

@@ -9,6 +9,7 @@ import {
   FrameContexts,
   HostClientType,
   HostName,
+  RenderingSurfaces,
   TeamType,
   UserTeamRole,
 } from '../../src/public/constants';
@@ -412,7 +413,7 @@ describe('Testing app capability', () => {
         message = utils.findMessageByFunc('getContext');
         expect(message).not.toBeNull();
       });
-
+  
       Object.values(FrameContexts).forEach((context) => {
         it(`app.getContext should successfully get frame context in ${context} context`, async () => {
           await utils.initializeWithContext(context);
@@ -556,6 +557,7 @@ describe('Testing app capability', () => {
             isMultiWindow: true,
             isBackgroundLoad: true,
             frameContext: context,
+            renderingSurface: RenderingSurfaces.copilotSidePanel,
             appLaunchId: 'appLaunchId',
             userDisplayName: 'someTestUser',
             teamSiteId: 'someSiteId',
@@ -588,6 +590,7 @@ describe('Testing app capability', () => {
             page: {
               id: 'someEntityId',
               subPageId: 'someSubEntityId',
+              renderingSurface: RenderingSurfaces.copilotSidePanel,
               isFullScreen: true,
               sourceOrigin: 'www.origin.com',
               frameContext: context,