diff --git a/change/@microsoft-teams-js-d6cf9225-5ad1-4d9e-b546-46d05f114400.json b/change/@microsoft-teams-js-d6cf9225-5ad1-4d9e-b546-46d05f114400.json new file mode 100644 index 0000000000..0471a49db7 --- /dev/null +++ b/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" +} diff --git a/packages/teams-js/src/internal/appHelpers.ts b/packages/teams-js/src/internal/appHelpers.ts index db955a0e37..e701ce45ee 100644 --- a/packages/teams-js/src/internal/appHelpers.ts +++ b/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 { return new Promise((resolve) => { ensureInitialized( diff --git a/packages/teams-js/src/internal/handlers.ts b/packages/teams-js/src/internal/handlers.ts index d75980e1b7..1aec2a4578 100644 --- a/packages/teams-js/src/internal/handlers.ts +++ b/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) = 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 diff --git a/packages/teams-js/src/internal/telemetry.ts b/packages/teams-js/src/internal/telemetry.ts index 6492d215be..24289a90d5 100644 --- a/packages/teams-js/src/internal/telemetry.ts +++ b/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', diff --git a/packages/teams-js/src/public/app/app.ts b/packages/teams-js/src/public/app/app.ts index 8b2d5599f2..e82c90aa3d 100644 --- a/packages/teams-js/src/public/app/app.ts +++ b/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. *