Expand support for MSC2873 (changing theme/language) (#117)

MSC2873 specifies some actions for updating the widget's theme/language after it's loaded, and I'd like to make use of them.

Author: robintown

src/ClientWidgetApi.ts

@@ -102,6 +102,7 @@ import {
     IDownloadFileActionFromWidgetActionRequest,
     IDownloadFileActionFromWidgetResponseData,
 } from "./interfaces/DownloadFileAction";
+import { IThemeChangeActionRequestData } from "./interfaces/ThemeChangeAction";
 
 /**
  * API handler for the client side of widgets. This raises events
@@ -896,6 +897,22 @@ export class ClientWidgetApi extends EventEmitter {
         }
     }
 
+    /**
+     * Informs the widget that the client's theme has changed.
+     * @param theme The theme data, as an object with arbitrary contents.
+     */
+    public updateTheme(theme: IThemeChangeActionRequestData): Promise<IWidgetApiResponseData> {
+        return this.transport.send(WidgetApiToWidgetAction.ThemeChange, theme);
+    }
+
+    /**
+     * Informs the widget that the client's language has changed.
+     * @param lang The BCP 47 identifier representing the client's current language.
+     */
+    public updateLanguage(lang: string): Promise<IWidgetApiResponseData> {
+        return this.transport.send(WidgetApiToWidgetAction.LanguageChange, { lang });
+    }
+
     /**
      * Takes a screenshot of the widget.
      * @returns Resolves to the widget's screenshot.

src/interfaces/ApiVersion.ts

@@ -23,6 +23,7 @@ export enum MatrixApiVersion {
 export enum UnstableApiVersion {
     MSC2762 = "org.matrix.msc2762",
     MSC2871 = "org.matrix.msc2871",
+    MSC2873 = "org.matrix.msc2873",
     MSC2931 = "org.matrix.msc2931",
     MSC2974 = "org.matrix.msc2974",
     MSC2876 = "org.matrix.msc2876",
@@ -41,6 +42,7 @@ export const CurrentApiVersions: ApiVersion[] = [
     //MatrixApiVersion.V010,
     UnstableApiVersion.MSC2762,
     UnstableApiVersion.MSC2871,
+    UnstableApiVersion.MSC2873,
     UnstableApiVersion.MSC2931,
     UnstableApiVersion.MSC2974,
     UnstableApiVersion.MSC2876,

src/interfaces/LanguageChangeAction.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2024 The Matrix.org Foundation C.I.C.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { IWidgetApiRequest, IWidgetApiRequestData } from "./IWidgetApiRequest";
+import { WidgetApiToWidgetAction } from "./WidgetApiAction";
+import { IWidgetApiAcknowledgeResponseData } from "./IWidgetApiResponse";
+
+export interface ILanguageChangeActionRequestData extends IWidgetApiRequestData {
+  /**
+   * The BCP 47 identifier for the client's current language.
+   */
+  lang: string;
+}
+
+export interface ILanguageChangeActionRequest extends IWidgetApiRequest {
+    action: WidgetApiToWidgetAction.LanguageChange;
+    data: ILanguageChangeActionRequestData;
+}
+
+export interface ILanguageChangeActionResponse extends ILanguageChangeActionRequest {
+    response: IWidgetApiAcknowledgeResponseData;
+}

src/interfaces/ThemeChangeAction.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2024 The Matrix.org Foundation C.I.C.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { IWidgetApiRequest, IWidgetApiRequestData } from "./IWidgetApiRequest";
+import { WidgetApiToWidgetAction } from "./WidgetApiAction";
+import { IWidgetApiAcknowledgeResponseData } from "./IWidgetApiResponse";
+
+export interface IThemeChangeActionRequestData extends IWidgetApiRequestData {
+  // The format of a theme is deliberately unstandardized
+}
+
+export interface IThemeChangeActionRequest extends IWidgetApiRequest {
+    action: WidgetApiToWidgetAction.ThemeChange;
+    data: IThemeChangeActionRequestData;
+}
+
+export interface IThemeChangeActionResponse extends IThemeChangeActionRequest {
+    response: IWidgetApiAcknowledgeResponseData;
+}

src/interfaces/WidgetApiAction.ts

@@ -18,6 +18,8 @@ export enum WidgetApiToWidgetAction {
     SupportedApiVersions = "supported_api_versions",
     Capabilities = "capabilities",
     NotifyCapabilities = "notify_capabilities",
+    ThemeChange = "theme_change",
+    LanguageChange = "language_change",
     TakeScreenshot = "screenshot",
     UpdateVisibility = "visibility",
     OpenIDCredentials = "openid_credentials",

test/ClientWidgetApi-test.ts

@@ -25,7 +25,7 @@ import { IWidgetApiRequest } from '../src/interfaces/IWidgetApiRequest';
 import { IReadRelationsFromWidgetActionRequest } from '../src/interfaces/ReadRelationsAction';
 import { ISupportedVersionsActionRequest } from '../src/interfaces/SupportedVersionsAction';
 import { IUserDirectorySearchFromWidgetActionRequest } from '../src/interfaces/UserDirectorySearchAction';
-import { WidgetApiFromWidgetAction } from '../src/interfaces/WidgetApiAction';
+import { WidgetApiFromWidgetAction, WidgetApiToWidgetAction } from '../src/interfaces/WidgetApiAction';
 import { WidgetApiDirection } from '../src/interfaces/WidgetApiDirection';
 import { Widget } from '../src/models/Widget';
 import { PostmessageTransport } from '../src/transport/PostmessageTransport';
@@ -2194,4 +2194,14 @@ describe('ClientWidgetApi', () => {
             });
         });
     });
+
+    it('updates theme', () => {
+        clientWidgetApi.updateTheme({ name: 'dark' });
+        expect(transport.send).toHaveBeenCalledWith(WidgetApiToWidgetAction.ThemeChange, { name: 'dark' });
+    });
+
+    it('updates language', () => {
+        clientWidgetApi.updateLanguage('tlh');
+        expect(transport.send).toHaveBeenCalledWith(WidgetApiToWidgetAction.LanguageChange, { lang: 'tlh' });
+    });
 });