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

Co-authored-by: Michael Weimann <mail@michael-weimann.eu>
Co-authored-by: Germain <germain@souquet.com>
Co-authored-by: Mikhail Aheichyk <mikhail.aheichyk@nordeck.net>

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";