MSC2790 Modal Widgets

src/AlmostEventEmitter.ts

@@ -15,7 +15,7 @@
  */
 
 // because we don't have real EventEmitter support :(
-export class AlmostEventEmitter extends EventTarget {
+export abstract class AlmostEventEmitter extends EventTarget {
     public once<T extends Event>(event: string, handler: (ev: T) => void) {
         const fn = (ev: T) => {
             try {

src/ClientWidgetApi.ts

@@ -34,6 +34,12 @@ import { CurrentApiVersions } from "./interfaces/ApiVersion";
 import { IScreenshotActionResponseData } from "./interfaces/ScreenshotAction";
 import { IVisibilityActionRequestData } from "./interfaces/VisibilityAction";
 import { IWidgetApiResponseData } from "./interfaces/IWidgetApiResponse";
+import {
+    IModalWidgetButtonClickedRequestData,
+    IModalWidgetOpenRequestData,
+    IModalWidgetOpenRequestDataButton,
+    IModalWidgetReturnData,
+} from "./interfaces/ModalWidgetActions";
 
 /**
  * API handler for the client side of widgets. This raises events
@@ -201,4 +207,20 @@ export class ClientWidgetApi extends AlmostEventEmitter {
             visible: isVisible,
         });
     }
+
+    public sendWidgetConfig(data: IModalWidgetOpenRequestData): Promise<void> {
+        return this.transport.send<IModalWidgetOpenRequestData>(WidgetApiToWidgetAction.WidgetConfig, data).then();
+    }
+
+    public notifyModalWidgetButtonClicked(id: IModalWidgetOpenRequestDataButton["id"]): Promise<void> {
+        return this.transport.send<IModalWidgetButtonClickedRequestData>(
+            WidgetApiToWidgetAction.ButtonClicked, {id},
+        ).then();
+    }
+
+    public notifyModalWidgetClose(data: IModalWidgetReturnData): Promise<void> {
+        return this.transport.send<IModalWidgetReturnData>(
+            WidgetApiToWidgetAction.CloseModalWidget, data,
+        ).then();
+    }
 }

src/WidgetApi.ts

@@ -37,6 +37,13 @@ import {
     OpenIDRequestState,
 } from "./interfaces/GetOpenIDAction";
 import { IOpenIDCredentialsActionRequest } from "./interfaces/OpenIDCredentialsAction";
+import { MatrixWidgetType, WidgetType } from "./interfaces/WidgetType";
+import {
+    IModalWidgetCreateData,
+    IModalWidgetOpenRequestData,
+    IModalWidgetOpenRequestDataButton,
+    IModalWidgetReturnData,
+} from "./interfaces/ModalWidgetActions";
 
 /**
  * API handler for widgets. This raises events for each action
@@ -180,6 +187,22 @@ export class WidgetApi extends AlmostEventEmitter {
         ).then(res => res.success);
     }
 
+    public openModalWidget(
+        url: string,
+        name: string,
+        buttons: IModalWidgetOpenRequestDataButton[] = [],
+        data: IModalWidgetCreateData = {},
+        type: WidgetType = MatrixWidgetType.Custom,
+    ): Promise<void> {
+        return this.transport.send<IModalWidgetOpenRequestData>(
+            WidgetApiFromWidgetAction.OpenModalWidget, { type, url, name, buttons, data },
+        ).then();
+    }
+
+    public closeModalWidget(data: IModalWidgetReturnData = {}): Promise<void> {
+        return this.transport.send<IModalWidgetReturnData>(WidgetApiFromWidgetAction.CloseModalWidget, data).then();
+    }
+
     /**
      * Starts the communication channel. This should be done early to ensure
      * that messages are not missed. Communication can only be stopped by the client.

src/index.ts

@@ -45,6 +45,9 @@ export * from "./interfaces/VisibilityAction";
 export * from "./interfaces/GetOpenIDAction";
 export * from "./interfaces/OpenIDCredentialsAction";
 export * from "./interfaces/WidgetKind";
+export * from "./interfaces/ModalButtonKind";
+export * from "./interfaces/ModalWidgetActions";
+export * from "./interfaces/WidgetConfigAction";
 
 // Complex models
 export * from "./models/validation/url";

src/interfaces/ModalButtonKind.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright 2020 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.
+ */
+
+export enum ModalButtonKind {
+    Primary = "m.primary",
+    Secondary = "m.secondary",
+    Warning = "m.warning",
+    Danger = "m.danger",
+    Link = "m.link",
+}

src/interfaces/ModalWidgetActions.ts

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2020 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 { WidgetApiFromWidgetAction, WidgetApiToWidgetAction } from "./WidgetApiAction";
+import { IWidgetApiAcknowledgeResponseData, IWidgetApiResponse } from "./IWidgetApiResponse";
+import { IWidget } from "./IWidget";
+import { ModalButtonKind } from "./ModalButtonKind";
+
+export interface IModalWidgetCreateData extends IWidgetApiRequestData {
+    [key: string]: unknown;
+}
+
+export interface IModalWidgetReturnData {
+    [key: string]: unknown;
+}
+
+// Types for a normal modal requesting the opening a modal widget
+export interface IModalWidgetOpenRequestDataButton {
+    id: "m.close" | string;
+    label: string;
+    kind: ModalButtonKind | string;
+}
+
+export interface IModalWidgetOpenRequestData extends IModalWidgetCreateData, Omit<IWidget, "id" | "creatorUserId"> {
+    buttons?: IModalWidgetOpenRequestDataButton[];
+}
+
+export interface IModalWidgetOpenRequest extends IWidgetApiRequest {
+    action: WidgetApiFromWidgetAction.OpenModalWidget;
+    data: IModalWidgetOpenRequestData;
+}
+
+export interface IModalWidgetOpenResponse extends IWidgetApiResponse {
+    response: IWidgetApiAcknowledgeResponseData;
+}
+
+// Types for a modal widget receiving notifications that its buttons have been pressed
+export interface IModalWidgetButtonClickedRequestData extends IWidgetApiRequestData {
+    id: IModalWidgetOpenRequestDataButton["id"];
+}
+
+export interface IModalWidgetButtonClickedRequest extends IWidgetApiRequest {
+    action: WidgetApiToWidgetAction.ButtonClicked;
+    data: IModalWidgetButtonClickedRequestData;
+}
+
+export interface IModalWidgetButtonClickedResponse extends IWidgetApiResponse {
+    response: IWidgetApiAcknowledgeResponseData;
+}
+
+// Types for a modal widget requesting close
+export interface IModalWidgetCloseRequest extends IWidgetApiRequest {
+    action: WidgetApiFromWidgetAction.CloseModalWidget;
+    data: IModalWidgetReturnData;
+}
+
+export interface IModalWidgetCloseResponse extends IWidgetApiResponse {
+    response: IWidgetApiAcknowledgeResponseData;
+}
+
+// Types for a normal widget being notified that the modal widget it opened has been closed
+export interface IModalWidgetCloseNotificationRequest extends IWidgetApiRequest {
+    action: WidgetApiToWidgetAction.CloseModalWidget;
+    data: IModalWidgetReturnData;
+}
+
+export interface IModalWidgetCloseNotificationResponse extends IWidgetApiResponse {
+    response: IWidgetApiAcknowledgeResponseData;
+}

src/interfaces/WidgetApiAction.ts

@@ -19,15 +19,20 @@ export enum WidgetApiToWidgetAction {
     Capabilities = "capabilities",
     TakeScreenshot = "screenshot",
     UpdateVisibility = "visibility",
-    OpenIDCredentials = "openid_credentials"
+    OpenIDCredentials = "openid_credentials",
+    WidgetConfig = "widget_config",
+    CloseModalWidget = "close_modal",
+    ButtonClicked = "button_clicked",
 }
 
 export enum WidgetApiFromWidgetAction {
     SupportedApiVersions = "supported_api_versions",
     ContentLoaded = "content_loaded",
     SendSticker = "m.sticker",
     UpdateAlwaysOnScreen = "set_always_on_screen",
-    GetOpenIDCredentials = "get_openid"
+    GetOpenIDCredentials = "get_openid",
+    CloseModalWidget = "close_modal",
+    OpenModalWidget = "open_modal",
 }
 
 export type WidgetApiAction = WidgetApiToWidgetAction | WidgetApiFromWidgetAction | string;

src/interfaces/WidgetConfigAction.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2020 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 } from "./IWidgetApiRequest";
+import { WidgetApiToWidgetAction } from "./WidgetApiAction";
+import { IWidgetApiAcknowledgeResponseData, IWidgetApiResponse } from "./IWidgetApiResponse";
+import { IModalWidgetOpenRequestData } from "./ModalWidgetActions";
+
+export interface IWidgetConfigRequest extends IWidgetApiRequest {
+    action: WidgetApiToWidgetAction.WidgetConfig;
+    data: IModalWidgetOpenRequestData;
+}
+
+export interface IWidgetConfigResponse extends IWidgetApiResponse {
+    response: IWidgetApiAcknowledgeResponseData;
+}

src/transport/ITransport.ts

@@ -15,6 +15,7 @@
  */
 
 import {
+    IWidgetApiAcknowledgeResponseData,
     IWidgetApiRequest,
     IWidgetApiRequestData,
     IWidgetApiResponse,
@@ -75,8 +76,10 @@ export interface ITransport extends EventTarget {
      * to the remote end's response, or throws with an Error if the request
      * failed.
      */
-    send<T extends IWidgetApiRequestData, R extends IWidgetApiResponseData>(action: WidgetApiAction, data: T)
-        : Promise<R>;
+    send<T extends IWidgetApiRequestData, R extends IWidgetApiResponseData = IWidgetApiAcknowledgeResponseData>(
+        action: WidgetApiAction,
+        data: T
+    ): Promise<R>;
 
     /**
      * Sends a request to the remote end. This is similar to the send() function