Add support for rendering a custom wrapper around Element (#13)

Co-authored-by: Michael Weimann <[email protected]>
Co-authored-by: Germain <[email protected]>
Co-authored-by: Mikhail Aheichyk <[email protected]>

Author: 4 people

README.md

@@ -98,6 +98,10 @@ being raised for additional handling.
 The module can also change what room/user/entity the user is looking at, and join it (if it's a room), with 
 `navigatePermalink` on a `ModuleApi` instance.
 
+### Wrapper management
+From the `RuntimeModule` instance, modules can listen for `WrapperLifecycle.Wrapper` to provide a wrapper react component.
+It would wrap the `MatrixChat` component and let any consumer add a header, a footer.
+
 ## Contributing / developing
 
 Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for the mechanics of the contribution process.

jest.config.js

@@ -1,5 +1,6 @@
 /** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
 module.exports = {
   preset: 'ts-jest',
-  testEnvironment: 'node',
-};
+  testEnvironment: 'jsdom',
+  setupFilesAfterEnv: ["<rootDir>/test/setupTests.ts"],
+};

package.json

@@ -35,20 +35,28 @@
     "@babel/preset-env": "^7.16.11",
     "@babel/preset-react": "^7.16.7",
     "@babel/preset-typescript": "^7.16.7",
+    "@testing-library/jest-dom": "^5.16.5",
+    "@testing-library/react": "^12.1.5",
     "@types/jest": "^27.4.1",
     "@types/react": "^17",
+    "@types/react-dom": "^17.0.19",
     "@typescript-eslint/eslint-plugin": "^5.18.0",
     "@typescript-eslint/parser": "^5.18.0",
     "eslint": "^8.12.0",
     "eslint-config-google": "^0.14.0",
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-matrix-org": "^0.4.0",
     "jest": "^27.5.1",
+    "react": "17.0.2",
+    "react-dom": "^17.0.2",
     "rimraf": "^3.0.2",
     "ts-jest": "^27.1.4",
     "typescript": "^4.6.3"
   },
   "dependencies": {
     "@babel/runtime": "^7.17.9"
+  },
+  "peerDependencies": {
+    "react": "^17.0.2"
   }
 }

src/lifecycles/WrapperLifecycle.ts

@@ -0,0 +1,43 @@
+/*
+Copyright 2023 Mikhail Aheichyk
+Copyright 2023 Nordeck IT + Consulting GmbH.
+
+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 { ComponentType, PropsWithChildren } from 'react';
+
+/**
+ * Wrapper lifecycle events
+ */
+export enum WrapperLifecycle {
+    /**
+     * An event to request the wrapper. It is sent by Element to get the wrapper provided by the module if any.
+     */
+    Wrapper = 'wrapper'
+}
+
+/**
+ * Opts object that is populated with a Wrapper.
+ */
+export type WrapperOpts = {
+    /**
+     * A Wrapper React Component to be rendered around the Matrix Chat.
+     */
+    Wrapper: ComponentType<PropsWithChildren<{}>>;
+};
+
+/**
+ * Helper type that documents how to implement a wrapper listener.
+ */
+export type WrapperListener = (opts: WrapperOpts) => void;

src/lifecycles/types.ts

@@ -16,8 +16,10 @@ limitations under the License.
 
 import { RoomViewLifecycle } from "./RoomViewLifecycle";
 import { WidgetLifecycle } from "./WidgetLifecycle";
+import { WrapperLifecycle } from "./WrapperLifecycle";
 
 export type AnyLifecycle =
     | RoomViewLifecycle
     | WidgetLifecycle
+    | WrapperLifecycle
     ;

test/lifecycles/WrapperLifecycle.test.tsx

@@ -0,0 +1,64 @@
+/*
+Copyright 2023 Mikhail Aheichyk
+Copyright 2023 Nordeck IT + Consulting GmbH.
+
+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 { render, screen } from '@testing-library/react';
+
+import { RuntimeModule } from '../../src/RuntimeModule';
+import { WrapperLifecycle, WrapperListener, WrapperOpts } from '../../src/lifecycles/WrapperLifecycle';
+
+describe('WrapperLifecycle', () => {
+    let module: RuntimeModule;
+
+    beforeAll(() => {
+        module = new class extends RuntimeModule {
+            constructor() {
+                super(undefined as any);
+
+                this.on(WrapperLifecycle.Wrapper, this.wrapperListener);
+            }
+
+            protected wrapperListener: WrapperListener = (wrapperOpts: WrapperOpts) => {
+                wrapperOpts.Wrapper = ({ children }) => {
+                    return <>
+                        <header>Header</header>
+                        {children}
+                        <footer>Footer</footer>
+                    </>;
+                };
+            };
+        };
+    });
+
+    it('should wrap a matrix client with header and footer', () => {
+        const opts: WrapperOpts = { Wrapper: React.Fragment };
+        module.emit(WrapperLifecycle.Wrapper, opts);
+
+        render(<opts.Wrapper><span>MatrixChat</span></opts.Wrapper>);
+
+        const header = screen.getByRole('banner');
+        expect(header).toBeInTheDocument();
+        const matrixChat = screen.getByText(/MatrixChat/i);
+        expect(matrixChat).toBeInTheDocument();
+        const footer = screen.getByRole('contentinfo');
+        expect(footer).toBeInTheDocument();
+
+        expect(header.nextSibling).toBe(matrixChat);
+        expect(matrixChat.nextSibling).toBe(footer);
+    });
+});
+

test/setupTests.ts

@@ -0,0 +1,18 @@
+/*
+Copyright 2023 Mikhail Aheichyk
+Copyright 2023 Nordeck IT + Consulting GmbH.
+
+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 "@testing-library/jest-dom";