Support being able to disable modal widget buttons (MSC2790 extension)

src/WidgetApi.ts

@@ -43,7 +43,10 @@ import {
     IModalWidgetOpenRequestData,
     IModalWidgetOpenRequestDataButton,
     IModalWidgetReturnData,
+    BuiltInModalButtonID,
+    ModalButtonID,
 } from "./interfaces/ModalWidgetActions";
+import { ISetModalButtonEnabledActionRequestData } from "./interfaces/SetModalButtonEnabledAction";
 import { ISendEventFromWidgetRequestData, ISendEventFromWidgetResponseData } from "./interfaces/SendEventAction";
 
 /**
@@ -188,6 +191,15 @@ export class WidgetApi extends EventEmitter {
         ).then(res => res.success);
     }
 
+    /**
+     * Opens a modal widget.
+     * @param {string} url The URL to the modal widget.
+     * @param {string} name The name of the widget.
+     * @param {IModalWidgetOpenRequestDataButton[]} buttons The buttons to have on the widget.
+     * @param {IModalWidgetCreateData} data Data to supply to the modal widget.
+     * @param {WidgetType} type The type of modal widget.
+     * @returns {Promise<void>} Resolves when the modal widget has been opened.
+     */
     public openModalWidget(
         url: string,
         name: string,
@@ -200,6 +212,11 @@ export class WidgetApi extends EventEmitter {
         ).then();
     }
 
+    /**
+     * Closes the modal widget. The widget's session will be terminated shortly after.
+     * @param {IModalWidgetReturnData} data Optional data to close the modal widget with.
+     * @returns {Promise<void>} Resolves when complete.
+     */
     public closeModalWidget(data: IModalWidgetReturnData = {}): Promise<void> {
         return this.transport.send<IModalWidgetReturnData>(WidgetApiFromWidgetAction.CloseModalWidget, data).then();
     }
@@ -222,6 +239,22 @@ export class WidgetApi extends EventEmitter {
         );
     }
 
+    /**
+     * Sets a button as disabled or enabled on the modal widget. Buttons are enabled by default.
+     * @param {ModalButtonID} buttonId The button ID to enable/disable.
+     * @param {boolean} isEnabled Whether or not the button is enabled.
+     * @returns {Promise<void>} Resolves when complete.
+     * @throws Throws if the button cannot be disabled, or the client refuses to disable the button.
+     */
+    public setModalButtonEnabled(buttonId: ModalButtonID, isEnabled: boolean): Promise<void> {
+        if (buttonId === BuiltInModalButtonID.Close) {
+            throw new Error("The close button cannot be disabled");
+        }
+        return this.transport.send<ISetModalButtonEnabledActionRequestData>(
+            WidgetApiFromWidgetAction.SetModalButtonEnabled, {button: buttonId, enabled: isEnabled},
+        ).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

@@ -47,6 +47,7 @@ export * from "./interfaces/OpenIDCredentialsAction";
 export * from "./interfaces/WidgetKind";
 export * from "./interfaces/ModalButtonKind";
 export * from "./interfaces/ModalWidgetActions";
+export * from "./interfaces/SetModalButtonEnabledAction";
 export * from "./interfaces/WidgetConfigAction";
 export * from "./interfaces/SendEventAction";
 export * from "./interfaces/IRoomEvent";

src/interfaces/ModalWidgetActions.ts

@@ -20,6 +20,11 @@ import { IWidgetApiAcknowledgeResponseData, IWidgetApiResponse } from "./IWidget
 import { IWidget } from "./IWidget";
 import { ModalButtonKind } from "./ModalButtonKind";
 
+export enum BuiltInModalButtonID {
+    Close = "m.close",
+}
+export type ModalButtonID = BuiltInModalButtonID | string;
+
 export interface IModalWidgetCreateData extends IWidgetApiRequestData {
     [key: string]: unknown;
 }
@@ -30,7 +35,7 @@ export interface IModalWidgetReturnData {
 
 // Types for a normal modal requesting the opening a modal widget
 export interface IModalWidgetOpenRequestDataButton {
-    id: "m.close" | string;
+    id: ModalButtonID;
     label: string;
     kind: ModalButtonKind | string;
 }

src/interfaces/SetModalButtonEnabledAction.ts

@@ -0,0 +1,34 @@
+/*
+ * 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 } from "./WidgetApiAction";
+import { IWidgetApiAcknowledgeResponseData } from "./IWidgetApiResponse";
+import { ModalButtonID } from "./ModalWidgetActions";
+
+export interface ISetModalButtonEnabledActionRequestData extends IWidgetApiRequestData {
+    enabled: boolean;
+    button: ModalButtonID;
+}
+
+export interface ISetModalButtonEnabledActionRequest extends IWidgetApiRequest {
+    action: WidgetApiFromWidgetAction.SetModalButtonEnabled;
+    data: ISetModalButtonEnabledActionRequestData;
+}
+
+export interface ISetModalButtonEnabledActionResponse extends ISetModalButtonEnabledActionRequest {
+    response: IWidgetApiAcknowledgeResponseData;
+}

src/interfaces/WidgetApiAction.ts

@@ -34,6 +34,7 @@ export enum WidgetApiFromWidgetAction {
     GetOpenIDCredentials = "get_openid",
     CloseModalWidget = "close_modal",
     OpenModalWidget = "open_modal",
+    SetModalButtonEnabled = "set_button_enabled",
     SendEvent = "send_event",
 }