Adding OsLocaleInfoChangeHandler for os locale info changes

change/@microsoft-teams-js-d6cf9225-5ad1-4d9e-b546-46d05f114400.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Adding osLocaleInfoHandler for the app module to handle OS locale info changes.",
+  "packageName": "@microsoft/teams-js",
+  "email": "ravasili@microsoft.com_msteamsmdb",
+  "dependentChangeType": "patch"
+}

packages/teams-js/src/internal/appHelpers.ts

@@ -23,6 +23,7 @@ import {
 import * as app from '../public/app/app';
 import { FrameContexts } from '../public/constants';
 import * as dialog from '../public/dialog/dialog';
+import { LocaleInfo } from '../public/interfaces';
 import * as menus from '../public/menus';
 import * as pages from '../public/pages/pages';
 import {
@@ -232,6 +233,15 @@ export function registerOnThemeChangeHandlerHelper(apiVersionTag: string, handle
   Handlers.registerOnThemeChangeHandler(apiVersionTag, handler);
 }
 
+export function registerOnOsLocaleInfoChangeHandlerHelper(
+  apiVersionTag: string,
+  handler: (info: LocaleInfo) => void,
+): void {
+  // allow for registration cleanup even when not called initialize
+  !isNullOrUndefined(handler) && ensureInitializeCalled();
+  Handlers.registerOnOsLocaleInfoChangeHandler(apiVersionTag, handler);
+}
+
 export function openLinkHelper(apiVersionTag: string, deepLink: string): Promise<void> {
   return new Promise<void>((resolve) => {
     ensureInitialized(

packages/teams-js/src/internal/handlers.ts

@@ -2,7 +2,7 @@
 
 import { ApiName, ApiVersionNumber, getApiVersionTag } from '../internal/telemetry';
 import { FrameContexts } from '../public/constants';
-import { HostToAppPerformanceMetrics, LoadContext, ResumeContext } from '../public/interfaces';
+import { HostToAppPerformanceMetrics, LoadContext, LocaleInfo, ResumeContext } from '../public/interfaces';
 import { runtime } from '../public/runtime';
 import { sendMessageEventToChild, shouldEventBeRelayedToChild } from './childCommunication';
 import { sendMessageToParent } from './communication';
@@ -33,6 +33,7 @@ class HandlersPrivate {
   public static beforeSuspendOrTerminateHandler: null | (() => Promise<void>) = null;
   public static resumeHandler: null | ((context: ResumeContext) => void) = null;
   public static hostToAppPerformanceMetricsHandler: null | ((metrics: HostToAppPerformanceMetrics) => void) = null;
+  public static osLocaleInfoChangeHandler: null | ((info: LocaleInfo) => void) = null;
 
   /**
    * @internal
@@ -42,6 +43,7 @@ class HandlersPrivate {
   public static initializeHandlers(): void {
     // ::::::::::::::::::::MicrosoftTeams SDK Internal :::::::::::::::::
     HandlersPrivate.handlers['themeChange'] = handleThemeChange;
+    HandlersPrivate.handlers['osLocaleInfoChange'] = handleOsLocaleInfoChange;
     HandlersPrivate.handlers['load'] = handleLoad;
     HandlersPrivate.handlers['beforeUnload'] = handleBeforeUnload;
     initializeBackStackHelper();
@@ -55,6 +57,7 @@ class HandlersPrivate {
   public static uninitializeHandlers(): void {
     HandlersPrivate.handlers = {};
     HandlersPrivate.themeChangeHandler = null;
+    HandlersPrivate.osLocaleInfoChangeHandler = null;
     HandlersPrivate.loadHandler = null;
     HandlersPrivate.beforeUnloadHandler = null;
     HandlersPrivate.beforeSuspendOrTerminateHandler = null;
@@ -170,6 +173,15 @@ export function registerOnThemeChangeHandler(apiVersionTag: string, handler: (th
   !isNullOrUndefined(handler) && sendMessageToParent(apiVersionTag, 'registerHandler', ['themeChange']);
 }
 
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export function registerOnOsLocaleInfoChangeHandler(apiVersionTag: string, handler: (info: LocaleInfo) => void): void {
+  HandlersPrivate.osLocaleInfoChangeHandler = handler;
+  !isNullOrUndefined(handler) && sendMessageToParent(apiVersionTag, 'registerHandler', ['osLocaleInfoChange']);
+}
+
 /**
  * @internal
  * Limited to Microsoft-internal use
@@ -184,6 +196,20 @@ export function handleThemeChange(theme: string): void {
   }
 }
 
+/**
+ * @internal
+ * Limited to Microsoft-internal use
+ */
+export function handleOsLocaleInfoChange(info: LocaleInfo): void {
+  if (HandlersPrivate.osLocaleInfoChangeHandler) {
+    HandlersPrivate.osLocaleInfoChangeHandler(info);
+  }
+
+  if (shouldEventBeRelayedToChild()) {
+    sendMessageEventToChild('osLocaleInfoChange', [info]);
+  }
+}
+
 /**
  * @internal
  * Limited to Microsoft-internal use

packages/teams-js/src/internal/telemetry.ts

@@ -72,6 +72,7 @@ export const enum ApiName {
   App_NotifySuccess = 'app.notifySuccess',
   App_OpenLink = 'app.openLink',
   App_RegisterOnThemeChangeHandler = 'app.registerOnThemeChangeHandler',
+  App_RegisterOnOsLocaleInfoChangeHandler = 'app.registerOnOsLocaleInfoChangeHandler',
   AppInitialization_NotifyAppLoaded = 'appInitialization.notifyAppLoaded',
   AppInitialization_NotifyExpectedFailure = 'appInitialization.notifyExpectedFailure',
   AppInitialization_NotifyFailure = 'appInitialization.notifyFailure',

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

@@ -584,6 +584,10 @@ export interface Context {
  * This function is passed to registerOnThemeHandler. It is called every time the user changes their theme.
  */
 export type themeHandler = (theme: string) => void;
+/**
+ * This function is passed to registerOnOsLocaleInfoChangeHandler. It is called every time the host updates the OS locale info.
+ */
+export type osLocaleInfoHandler = (info: LocaleInfo) => void;
 
 /**
  * This function is passed to registerHostToAppPerformanceMetricsHandler. It is called every time a response is received from the host with metrics for analyzing message delay. See {@link HostToAppPerformanceMetrics} to see which metrics are passed to the handler.
@@ -759,6 +763,21 @@ export function registerOnThemeChangeHandler(handler: themeHandler): void {
   );
 }
 
+/**
+ * Registers a handler for OS locale info changes.
+ *
+ * @remarks
+ * Only one handler can be registered at a time. A subsequent registration replaces an existing registration.
+ *
+ * @param handler - The handler to invoke when the OS locale info changes.
+ */
+export function registerOnOsLocaleInfoChangeHandler(handler: osLocaleInfoHandler): void {
+  appHelpers.registerOnOsLocaleInfoChangeHandlerHelper(
+    getApiVersionTag(appTelemetryVersionNumber, ApiName.App_RegisterOnOsLocaleInfoChangeHandler),
+    handler,
+  );
+}
+
 /**
  * Registers a function for handling data of host to app message delay.
  *