Support a module API surface for custom functionality (#8246)

* Early implementation of module API surface + functions for ILAG module

* Wire up dialog functions and ILAG-needed surface

* Ensure component renders for modules get overridden

* Respond to changes from module API interface

* Use a real module-api dependency

* Update for new Dialogs interface

* Add support for getConfigValue from module API

* Update the remainder of the module API interface

* Docs & cleanup

* Add some unit tests around module stuff

Needs end-to-end tests still.

* Appease early linters

* Break import cycles by not directly depending on Lifecycle

* Appease the linter

* Fix bad merge

test/modules/AppModule-test.ts

@@ -0,0 +1,36 @@
+/*
+Copyright 2022 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 { MockModule } from "./MockModule";
+import { AppModule } from "../../src/modules/AppModule";
+
+describe("AppModule", () => {
+    describe("constructor", () => {
+        it("should call the factory immediately", () => {
+            let module: MockModule;
+            const appModule = new AppModule((api) => {
+                if (module) {
+                    throw new Error("State machine error: Factory called twice");
+                }
+                module = new MockModule(api);
+                return module;
+            });
+            expect(appModule.module).toBeDefined();
+            expect(appModule.module).toBe(module);
+            expect(appModule.api).toBeDefined();
+        });
+    });
+});

test/modules/MockModule.ts

@@ -0,0 +1,45 @@
+/*
+Copyright 2022 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 { RuntimeModule } from "@matrix-org/react-sdk-module-api/lib/RuntimeModule";
+import { ModuleApi } from "@matrix-org/react-sdk-module-api/lib/ModuleApi";
+
+import { ModuleRunner } from "../../src/modules/ModuleRunner";
+
+export class MockModule extends RuntimeModule {
+    public get apiInstance(): ModuleApi {
+        return this.moduleApi;
+    }
+
+    public constructor(moduleApi: ModuleApi) {
+        super(moduleApi);
+    }
+}
+
+export function registerMockModule(): MockModule {
+    let module: MockModule;
+    ModuleRunner.instance.registerModule(api => {
+        if (module) {
+            throw new Error("State machine error: ModuleRunner created the module twice");
+        }
+        module = new MockModule(api);
+        return module;
+    });
+    if (!module) {
+        throw new Error("State machine error: ModuleRunner did not create module");
+    }
+    return module;
+}

test/modules/ModuleComponents-test.tsx

@@ -0,0 +1,41 @@
+/*
+Copyright 2022 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 React from "react";
+import { mount } from "enzyme";
+import { TextInputField } from "@matrix-org/react-sdk-module-api/lib/components/TextInputField";
+import { Spinner as ModuleSpinner } from "@matrix-org/react-sdk-module-api/lib/components/Spinner";
+
+import "../../src/modules/ModuleRunner";
+
+describe("Module Components", () => {
+    // Note: we're not testing to see if there's components that are missing a renderFactory()
+    // but rather that the renderFactory() for components we do know about is actually defined
+    // and working.
+    //
+    // We do this by deliberately not importing the ModuleComponents file itself, relying on the
+    // ModuleRunner import to do its job (as per documentation in ModuleComponents).
+
+    it("should override the factory for a TextInputField", () => {
+        const component = mount(<TextInputField label="My Label" value="My Value" onChange={() => {}} />);
+        expect(component).toMatchSnapshot();
+    });
+
+    it("should override the factory for a ModuleSpinner", () => {
+        const component = mount(<ModuleSpinner />);
+        expect(component).toMatchSnapshot();
+    });
+});

test/modules/ModuleRunner-test.ts

@@ -0,0 +1,54 @@
+/*
+Copyright 2022 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 { RoomPreviewOpts, RoomViewLifecycle } from "@matrix-org/react-sdk-module-api/lib/lifecycles/RoomViewLifecycle";
+
+import { MockModule, registerMockModule } from "./MockModule";
+import { ModuleRunner } from "../../src/modules/ModuleRunner";
+
+describe("ModuleRunner", () => {
+    afterEach(() => {
+        ModuleRunner.instance.reset();
+    });
+
+    // Translations implicitly tested by ProxiedModuleApi integration tests.
+
+    describe("invoke", () => {
+        it("should invoke to every registered module", async () => {
+            const module1 = registerMockModule();
+            const module2 = registerMockModule();
+
+            const wrapEmit = (module: MockModule) => new Promise((resolve) => {
+                module.on(RoomViewLifecycle.PreviewRoomNotLoggedIn, (val1, val2) => {
+                    resolve([val1, val2]);
+                });
+            });
+            const promises = Promise.all([
+                wrapEmit(module1),
+                wrapEmit(module2),
+            ]);
+
+            const roomId = "!room:example.org";
+            const opts: RoomPreviewOpts = { canJoin: false };
+            ModuleRunner.instance.invoke(RoomViewLifecycle.PreviewRoomNotLoggedIn, opts, roomId);
+            const results = await promises;
+            expect(results).toEqual([
+                [opts, roomId], // module 1
+                [opts, roomId], // module 2
+            ]);
+        });
+    });
+});

test/modules/ProxiedModuleApi-test.ts

@@ -0,0 +1,79 @@
+/*
+Copyright 2022 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 { TranslationStringsObject } from "@matrix-org/react-sdk-module-api/lib/types/translations";
+
+import { ProxiedModuleApi } from "../../src/modules/ProxiedModuleApi";
+import { stubClient } from "../test-utils";
+import { setLanguage } from "../../src/languageHandler";
+import { ModuleRunner } from "../../src/modules/ModuleRunner";
+import { registerMockModule } from "./MockModule";
+
+describe("ProxiedApiModule", () => {
+    afterEach(() => {
+        ModuleRunner.instance.reset();
+    });
+
+    // Note: Remainder is implicitly tested from end-to-end tests of modules.
+
+    describe("translations", () => {
+        it("should cache translations", () => {
+            const api = new ProxiedModuleApi();
+            expect(api.translations).toBeFalsy();
+
+            const translations: TranslationStringsObject = {
+                ["custom string"]: {
+                    "en": "custom string",
+                    "fr": "custom french string",
+                },
+            };
+            api.registerTranslations(translations);
+            expect(api.translations).toBe(translations);
+        });
+
+        describe("integration", () => {
+            it("should translate strings using translation system", async () => {
+                // Test setup
+                stubClient();
+
+                // Set up a module to pull translations through
+                const module = registerMockModule();
+                const en = "custom string";
+                const de = "custom german string";
+                const enVars = "custom variable %(var)s";
+                const varVal = "string";
+                const deVars = "custom german variable %(var)s";
+                const deFull = `custom german variable ${varVal}`;
+                expect(module.apiInstance).toBeInstanceOf(ProxiedModuleApi);
+                module.apiInstance.registerTranslations({
+                    [en]: {
+                        "en": en,
+                        "de": de,
+                    },
+                    [enVars]: {
+                        "en": enVars,
+                        "de": deVars,
+                    },
+                });
+                await setLanguage("de"); // calls `registerCustomTranslations()` for us
+
+                // See if we can pull the German string out
+                expect(module.apiInstance.translateString(en)).toEqual(de);
+                expect(module.apiInstance.translateString(enVars, { var: varVal })).toEqual(deFull);
+            });
+        });
+    });
+});

test/modules/__snapshots__/ModuleComponents-test.tsx.snap

@@ -0,0 +1,66 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Module Components should override the factory for a ModuleSpinner 1`] = `
+<Spinner>
+  <Spinner
+    h={32}
+    w={32}
+  >
+    <div
+      className="mx_Spinner"
+    >
+      <div
+        aria-label="Loading..."
+        className="mx_Spinner_icon"
+        style={
+          Object {
+            "height": 32,
+            "width": 32,
+          }
+        }
+      />
+    </div>
+  </Spinner>
+</Spinner>
+`;
+
+exports[`Module Components should override the factory for a TextInputField 1`] = `
+<TextInputField
+  label="My Label"
+  onChange={[Function]}
+  value="My Value"
+>
+  <Field
+    autoComplete="off"
+    element="input"
+    label="My Label"
+    onChange={[Function]}
+    type="text"
+    validateOnBlur={true}
+    validateOnChange={true}
+    validateOnFocus={true}
+    value="My Value"
+  >
+    <div
+      className="mx_Field mx_Field_input"
+    >
+      <input
+        autoComplete="off"
+        id="mx_Field_1"
+        label="My Label"
+        onBlur={[Function]}
+        onChange={[Function]}
+        onFocus={[Function]}
+        placeholder="My Label"
+        type="text"
+        value="My Value"
+      />
+      <label
+        htmlFor="mx_Field_1"
+      >
+        My Label
+      </label>
+    </div>
+  </Field>
+</TextInputField>
+`;