Make sending ContentLoaded optional for a widgetClient

spec/unit/embedded.spec.ts

@@ -87,9 +87,12 @@ describe("RoomWidgetClient", () => {
         client.stopClient();
     });
 
-    const makeClient = async (capabilities: ICapabilities): Promise<void> => {
+    const makeClient = async (
+        capabilities: ICapabilities,
+        sendContentLoaded: boolean | undefined = undefined,
+    ): Promise<void> => {
         const baseUrl = "https://example.org";
-        client = createRoomWidgetClient(widgetApi, capabilities, "!1:example.org", { baseUrl });
+        client = createRoomWidgetClient(widgetApi, capabilities, "!1:example.org", { baseUrl }, sendContentLoaded);
         expect(widgetApi.start).toHaveBeenCalled(); // needs to have been called early in order to not miss messages
         widgetApi.emit("ready");
         await client.startClient();
@@ -143,7 +146,7 @@ describe("RoomWidgetClient", () => {
         });
     });
 
-    describe("messages", () => {
+    describe("initialization", () => {
         it("requests permissions for specific message types", async () => {
             await makeClient({ sendMessage: [MsgType.Text], receiveMessage: [MsgType.Text] });
             expect(widgetApi.requestCapabilityForRoomTimeline).toHaveBeenCalledWith("!1:example.org");
@@ -158,6 +161,15 @@ describe("RoomWidgetClient", () => {
             expect(widgetApi.requestCapabilityToReceiveMessage).toHaveBeenCalledWith();
         });
 
+        it("sends content loaded when configured", async () => {
+            await makeClient({});
+            expect(widgetApi.sendContentLoaded).toHaveBeenCalled();
+        });
+
+        it("does not sent content loaded when configured", async () => {
+            await makeClient({}, false);
+            expect(widgetApi.sendContentLoaded).not.toHaveBeenCalled();
+        });
         // No point in testing sending and receiving since it's done exactly the
         // same way as non-message events
     });
@@ -305,12 +317,14 @@ describe("RoomWidgetClient", () => {
             expect(await emittedSync).toEqual(SyncState.Syncing);
         });
     });
+
     describe("oidc token", () => {
         it("requests an oidc token", async () => {
             await makeClient({});
             expect(await client.getOpenIdToken()).toStrictEqual(testOIDCToken);
         });
     });
+
     it("gets TURN servers", async () => {
         const server1: ITurnServer = {
             uris: [

src/embedded.ts

@@ -108,11 +108,20 @@ export class RoomWidgetClient extends MatrixClient {
     private lifecycle?: AbortController;
     private syncState: SyncState | null = null;
 
+    /**
+     *
+     * @param widgetApi - the widget api to use for the embedded "fake" client
+     * @param opts - Client related options
+     * @param sendContentLoaded - Whether to send a content loaded widget action immediately after initial setup.
+     *   Set to `false` if the widget uses `waitForIFrameLoad=true` (in this case the client does not expect a content loaded action at all),
+     *   or if the the widget wants to send the `ContentLoaded` action at a later point in time after the initial setup.
+     */
     public constructor(
         private readonly widgetApi: WidgetApi,
         private readonly capabilities: ICapabilities,
         private readonly roomId: string,
         opts: IMatrixClientCreateOpts,
+        sendContentLoaded = true,
     ) {
         super(opts);
 
@@ -165,7 +174,7 @@ export class RoomWidgetClient extends MatrixClient {
         // does *not* (yes, that is the right way around) wait for this event. Let's
         // start sending this, then once this has rolled out, we can change element-web to
         // use waitForIFrameLoad=false and have a widget API that's less racy.
-        widgetApi.sendContentLoaded();
+        if (sendContentLoaded) widgetApi.sendContentLoaded();
     }
 
     public async startClient(opts: IStartClientOpts = {}): Promise<void> {

src/matrix.ts

@@ -164,11 +164,26 @@ export function createClient(opts: ICreateClientOpts): MatrixClient {
     return new MatrixClient(amendClientOpts(opts));
 }
 
+/**
+ * Construct a Matrix Client that works in a widget.
+ * This client has a subset of features compared to a full client.
+ * It uses the widget-api to communicate with matrix. (widget \<-\> client \<-\> homeserver)
+ * @returns A new matrix client with a subset of features.
+ * @param opts - The configuration options for this client. These configuration
+ * options will be passed directly to {@link MatrixClient}.
+ * @param widgetApi - The widget api to use for communication.
+ * @param capabilities - The capabilities the widget client will request.
+ * @param roomId - The room id the widget is associated with.
+ * @param sendContentLoaded - Whether to send a content loaded widget action immediately after initial setup.
+ *   Set to `false` if the widget uses `waitForIFrameLoad=true` (in this case the client does not expect a content loaded action at all),
+ *   or if the the widget wants to send the `ContentLoaded` action at a later point in time after the initial setup.
+ */
 export function createRoomWidgetClient(
     widgetApi: WidgetApi,
     capabilities: ICapabilities,
     roomId: string,
     opts: ICreateClientOpts,
+    sendContentLoaded = true,
 ): MatrixClient {
-    return new RoomWidgetClient(widgetApi, capabilities, roomId, amendClientOpts(opts));
+    return new RoomWidgetClient(widgetApi, capabilities, roomId, amendClientOpts(opts), sendContentLoaded);
 }