Add support for rendering a custom wrapper around Element

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.
 
+### Banner management
+From the `RuntimeModule` instance, modules can listen for `BannerLifecycle.Banner` to provide a banner. It will be 
+shown at the top of the Element.
+
 ## Contributing / developing
 
 Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for the mechanics of the contribution process.

package.json

@@ -44,11 +44,15 @@
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-matrix-org": "^0.4.0",
     "jest": "^27.5.1",
+    "react": "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/BannerLifecycle.ts

@@ -0,0 +1,41 @@
+/*
+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.
+*/
+
+/**
+ * Banner lifecycle events.
+ */
+export enum BannerLifecycle {
+    /**
+     * An event to request the banner. It is sent by Element to get the banner provided by the module if any.
+     */
+    Banner = "banner",
+}
+
+/**
+ * Opts object that is populated with the banner.
+ */
+export type BannerOpts = {
+    /**
+     * A banner to be shown at the top of Element. If not defined, then no change to the Element.
+     */
+    banner: JSX.Element | undefined;
+};
+
+/**
+ * Helper type that documents how to implement a banner listener.
+ */
+export type BannerListener = (opts: BannerOpts) => void;

src/lifecycles/types.ts

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

test/lifecycles/BannerLifecycle.test.ts

@@ -0,0 +1,49 @@
+/*
+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 { BannerOpts, BannerListener } from "../../src/lifecycles/BannerLifecycle";
+import { RuntimeModule } from "../../src/RuntimeModule";
+import { BannerLifecycle } from "../../src/lifecycles/BannerLifecycle";
+
+describe("BannerLifecycle", () => {
+    const customBanner = React.createElement('div');
+
+    let module: RuntimeModule;
+
+    beforeAll(() => {
+        module = new class extends RuntimeModule {
+            constructor() {
+                super(undefined as any);
+
+                this.on(BannerLifecycle.Banner, this.bannerListener);
+            }
+
+            protected bannerListener: BannerListener = (bannerOpts: BannerOpts) => {
+                bannerOpts.banner = customBanner;
+            };
+        };
+    });
+
+    it('should handle request to render the banner', () => {
+        const opts: BannerOpts = {banner: undefined};
+        module.emit(BannerLifecycle.Banner, opts);
+
+        expect(opts.banner).toBe(customBanner);
+    });
+});

yarn.lock

@@ -3292,7 +3292,7 @@ jest@^27.5.1:
     import-local "^3.0.2"
     jest-cli "^27.5.1"
 
-js-tokens@^4.0.0:
+"js-tokens@^3.0.0 || ^4.0.0", js-tokens@^4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-4.0.0.tgz#19203fb59991df98e3a287050d4647cdeaf32499"
   integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==
@@ -3448,6 +3448,13 @@ lodash@^4.7.0:
   resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz#679591c564c3bffaae8454cf0b3df370c3d6911c"
   integrity sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==
 
+loose-envify@^1.1.0:
+  version "1.4.0"
+  resolved "https://registry.yarnpkg.com/loose-envify/-/loose-envify-1.4.0.tgz#71ee51fa7be4caec1a63839f7e682d8132d30caf"
+  integrity sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==
+  dependencies:
+    js-tokens "^3.0.0 || ^4.0.0"
+
 lru-cache@^6.0.0:
   version "6.0.0"
   resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-6.0.0.tgz#6d6fe6570ebd96aaf90fcad1dafa3b2566db3a94"
@@ -3576,6 +3583,11 @@ nwsapi@^2.2.0:
   resolved "https://registry.yarnpkg.com/nwsapi/-/nwsapi-2.2.0.tgz#204879a9e3d068ff2a55139c2c772780681a38b7"
   integrity sha512-h2AatdwYH+JHiZpv7pt/gSX1XoRGb7L/qSIeuqA6GwYoF9w1vP1cw42TO0aI2pNyshRK5893hNSl+1//vHK7hQ==
 
+object-assign@^4.1.1:
+  version "4.1.1"
+  resolved "https://registry.yarnpkg.com/object-assign/-/object-assign-4.1.1.tgz#2109adc7965887cfc05cbbd442cac8bfbb360863"
+  integrity sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==
+
 object-inspect@^1.12.0, object-inspect@^1.9.0:
   version "1.12.0"
   resolved "https://registry.yarnpkg.com/object-inspect/-/object-inspect-1.12.0.tgz#6e2c120e868fd1fd18cb4f18c31741d0d6e776f0"
@@ -3807,6 +3819,14 @@ react-is@^17.0.1:
   resolved "https://registry.yarnpkg.com/react-is/-/react-is-17.0.2.tgz#e691d4a8e9c789365655539ab372762b0efb54f0"
   integrity sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==
 
+[email protected]:
+  version "17.0.2"
+  resolved "https://registry.yarnpkg.com/react/-/react-17.0.2.tgz#d0b5cc516d29eb3eee383f75b62864cfb6800037"
+  integrity sha512-gnhPt75i/dq/z3/6q/0asP78D0u592D5L1pd7M8P+dck6Fu/jJeL6iVVK23fptSUZj8Vjf++7wXA8UNclGQcbA==
+  dependencies:
+    loose-envify "^1.1.0"
+    object-assign "^4.1.1"
+
 readdirp@~3.6.0:
   version "3.6.0"
   resolved "https://registry.yarnpkg.com/readdirp/-/readdirp-3.6.0.tgz#74a370bd857116e245b29cc97340cd431a02a6c7"