Module API Implementation: Builtins

src/modules/AccountDataApi.ts

@@ -0,0 +1,54 @@
+/*
+Copyright 2025 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { Watchable, type AccountDataApi as IAccountDataApi } from "@element-hq/element-web-module-api";
+import { ClientEvent, type MatrixEvent, type MatrixClient } from "matrix-js-sdk/src/matrix";
+
+import { MatrixClientPeg } from "../MatrixClientPeg";
+
+export class AccountDataApi implements IAccountDataApi {
+    public get(eventType: string): Watchable<unknown> {
+        const cli = MatrixClientPeg.safeGet();
+        return new AccountDataWatchable(cli, eventType);
+    }
+
+    public async set(eventType: string, content: any): Promise<void> {
+        const cli = MatrixClientPeg.safeGet();
+        //@ts-expect-error: JS-SDK accepts known event-types, intentionally allow arbitrary types.
+        await cli.setAccountData(eventType, content);
+    }
+
+    public async delete(eventType: string): Promise<void> {
+        const cli = MatrixClientPeg.safeGet();
+        //@ts-expect-error: JS-SDK accepts known event-types, intentionally allow arbitrary types.
+        await cli.deleteAccountData(eventType);
+    }
+}
+
+class AccountDataWatchable extends Watchable<unknown> {
+    public constructor(
+        private cli: MatrixClient,
+        private eventType: string,
+    ) {
+        //@ts-expect-error: JS-SDK accepts known event-types, intentionally allow arbitrary types.
+        super(cli.getAccountData(eventType)?.getContent());
+    }
+
+    private onAccountData = (event: MatrixEvent): void => {
+        if (event.getType() === this.eventType) {
+            this.value = event.getContent();
+        }
+    };
+
+    protected onFirstWatch(): void {
+        this.cli.on(ClientEvent.AccountData, this.onAccountData);
+    }
+
+    protected onLastWatch(): void {
+        this.cli.off(ClientEvent.AccountData, this.onAccountData);
+    }
+}

src/modules/Api.ts

@@ -27,7 +27,9 @@ import { NavigationApi } from "./Navigation.ts";
 import { openDialog } from "./Dialog.tsx";
 import { overwriteAccountAuth } from "./Auth.ts";
 import { ElementWebExtrasApi } from "./ExtrasApi.ts";
-import { ElementWebBuiltinsApi } from "./BuiltinsApi.ts";
+import { ElementWebBuiltinsApi } from "./BuiltinsApi.tsx";
+import { ClientApi } from "./ClientApi.ts";
+import { StoresApi } from "./StoresApi.ts";
 
 const legacyCustomisationsFactory = <T extends object>(baseCustomisations: T) => {
     let used = false;
@@ -84,6 +86,8 @@ export class ModuleApi implements Api {
     public readonly extras = new ElementWebExtrasApi();
     public readonly builtins = new ElementWebBuiltinsApi();
     public readonly rootNode = document.getElementById("matrixchat")!;
+    public readonly client = new ClientApi();
+    public readonly stores = new StoresApi();
 
     public createRoot(element: Element): Root {
         return createRoot(element);

src/modules/BuiltinsApi.tsx

@@ -0,0 +1,75 @@
+/*
+Copyright 2025 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import React from "react";
+import { type RoomViewProps, type BuiltinsApi } from "@element-hq/element-web-module-api";
+
+import { MatrixClientPeg } from "../MatrixClientPeg";
+import type { Room } from "matrix-js-sdk/src/matrix";
+
+interface RoomViewPropsWithRoomId extends RoomViewProps {
+    roomId?: string;
+}
+
+interface RoomAvatarProps {
+    room: Room;
+    size?: string;
+}
+
+interface Components {
+    roomView: React.ComponentType<RoomViewPropsWithRoomId>;
+    roomAvatar: React.ComponentType<RoomAvatarProps>;
+}
+
+export class ElementWebBuiltinsApi implements BuiltinsApi {
+    private _roomView?: React.ComponentType<RoomViewPropsWithRoomId>;
+    private _roomAvatar?: React.ComponentType<RoomAvatarProps>;
+
+    /**
+     * Sets the components used by the API.
+     *
+     * This only really exists here because referencing these components directly causes a nightmare of
+     * circular dependencies that break the whole app, so instead we avoid referencing it here
+     * and pass it in from somewhere it's already referenced (see related comment in app.tsx).
+     *
+     * @param component The components used by the api, see {@link Components}
+     */
+    public setComponents(components: Components): void {
+        this._roomView = components.roomView;
+        this._roomAvatar = components.roomAvatar;
+    }
+
+    public getRoomViewComponent(): React.ComponentType<RoomViewPropsWithRoomId> {
+        if (!this._roomView) {
+            throw new Error("No RoomView component has been set");
+        }
+
+        return this._roomView;
+    }
+
+    public getRoomAvatarComponent(): React.ComponentType<RoomAvatarProps> {
+        if (!this._roomAvatar) {
+            throw new Error("No RoomAvatar component has been set");
+        }
+
+        return this._roomAvatar;
+    }
+
+    public renderRoomView(roomId: string): React.ReactNode {
+        const Component = this.getRoomViewComponent();
+        return <Component roomId={roomId} />;
+    }
+
+    public renderRoomAvatar(roomId: string, size?: string): React.ReactNode {
+        const room = MatrixClientPeg.safeGet().getRoom(roomId);
+        if (!room) {
+            throw new Error(`No room such room: ${roomId}`);
+        }
+        const Component = this.getRoomAvatarComponent();
+        return <Component room={room} size={size} />;
+    }
+}

src/modules/ClientApi.ts

@@ -0,0 +1,20 @@
+/*
+Copyright 2025 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+import type { ClientApi as IClientApi, Room } from "@element-hq/element-web-module-api";
+import { Room as ModuleRoom } from "./models/Room";
+import { AccountDataApi } from "./AccountDataApi";
+import { MatrixClientPeg } from "../MatrixClientPeg";
+
+export class ClientApi implements IClientApi {
+    public readonly accountData = new AccountDataApi();
+
+    public getRoom(roomId: string): Room | null {
+        const sdkRoom = MatrixClientPeg.safeGet().getRoom(roomId);
+        if (sdkRoom) return new ModuleRoom(sdkRoom);
+        return null;
+    }
+}

src/modules/Navigation.ts

@@ -5,8 +5,11 @@ SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Com
 Please see LICENSE files in the repository root for full details.
 */
 
-import { type LocationRenderFunction, type NavigationApi as INavigationApi } from "@element-hq/element-web-module-api";
-
+import type {
+    LocationRenderFunction,
+    NavigationApi as INavigationApi,
+    OpenRoomOptions,
+} from "@element-hq/element-web-module-api";
 import { navigateToPermalink } from "../utils/permalinks/navigator.ts";
 import { parsePermalink } from "../utils/permalinks/Permalinks.ts";
 import dispatcher from "../dispatcher/dispatcher.ts";
@@ -21,27 +24,25 @@ export class NavigationApi implements INavigationApi {
 
         const parts = parsePermalink(link);
         if (parts?.roomIdOrAlias) {
-            if (parts.roomIdOrAlias.startsWith("#")) {
-                dispatcher.dispatch<ViewRoomPayload>({
-                    action: Action.ViewRoom,
-                    room_alias: parts.roomIdOrAlias,
-                    via_servers: parts.viaServers ?? undefined,
-                    auto_join: join,
-                    metricsTrigger: undefined,
-                });
-            } else {
-                dispatcher.dispatch<ViewRoomPayload>({
-                    action: Action.ViewRoom,
-                    room_id: parts.roomIdOrAlias,
-                    via_servers: parts.viaServers ?? undefined,
-                    auto_join: join,
-                    metricsTrigger: undefined,
-                });
-            }
+            this.openRoom(parts.roomIdOrAlias, {
+                viaServers: parts.viaServers ?? undefined,
+                autoJoin: join,
+            });
         }
     }
 
     public registerLocationRenderer(path: string, renderer: LocationRenderFunction): void {
         this.locationRenderers.set(path, renderer);
     }
+
+    public openRoom(roomIdOrAlias: string, opts: OpenRoomOptions = {}): void {
+        const key = roomIdOrAlias.startsWith("#") ? "room_alias" : "room_id";
+        dispatcher.dispatch<ViewRoomPayload>({
+            action: Action.ViewRoom,
+            [key]: roomIdOrAlias,
+            via_servers: opts.viaServers,
+            auto_join: opts.autoJoin,
+            metricsTrigger: undefined,
+        });
+    }
 }

src/modules/StoresApi.ts

@@ -0,0 +1,106 @@
+/*
+Copyright 2025 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+import {
+    type StoresApi as IStoresApi,
+    type RoomListStoreApi as IRoomListStore,
+    type Room,
+    Watchable,
+} from "@element-hq/element-web-module-api";
+
+import type { RoomListStoreV3Class, RoomListStoreV3Event } from "../stores/room-list-v3/RoomListStoreV3";
+import { Room as ModuleRoom } from "./models/Room";
+
+interface RlsEvents {
+    LISTS_LOADED_EVENT: RoomListStoreV3Event.ListsLoaded;
+    LISTS_UPDATE_EVENT: RoomListStoreV3Event.ListsUpdate;
+}
+
+export class RoomListStoreApi implements IRoomListStore {
+    private rls?: RoomListStoreV3Class;
+    private LISTS_LOADED_EVENT?: RoomListStoreV3Event.ListsLoaded;
+    private LISTS_UPDATE_EVENT?: RoomListStoreV3Event.ListsUpdate;
+    public readonly moduleLoadPromise: Promise<void>;
+
+    public constructor() {
+        this.moduleLoadPromise = this.init();
+    }
+
+    /**
+     * Load the RLS through a dynamic import. This is necessary to prevent
+     * circular dependency issues.
+     */
+    private async init(): Promise<void> {
+        const module = await import("../stores/room-list-v3/RoomListStoreV3");
+        this.rls = module.default.instance;
+        this.LISTS_LOADED_EVENT = module.LISTS_LOADED_EVENT;
+        this.LISTS_UPDATE_EVENT = module.LISTS_UPDATE_EVENT;
+    }
+
+    public getRooms(): RoomsWatchable {
+        return new RoomsWatchable(this.roomListStore, this.events);
+    }
+
+    private get events(): RlsEvents {
+        if (!this.LISTS_LOADED_EVENT || !this.LISTS_UPDATE_EVENT) {
+            throw new Error("Event type was not loaded correctly, did you forget to await waitForReady()?");
+        }
+        return { LISTS_LOADED_EVENT: this.LISTS_LOADED_EVENT, LISTS_UPDATE_EVENT: this.LISTS_UPDATE_EVENT };
+    }
+
+    private get roomListStore(): RoomListStoreV3Class {
+        if (!this.rls) {
+            throw new Error("rls is undefined, did you forget to await waitForReady()?");
+        }
+        return this.rls;
+    }
+
+    public async waitForReady(): Promise<void> {
+        // Wait for the module to load first
+        await this.moduleLoadPromise;
+
+        // Check if RLS is already loaded
+        if (!this.roomListStore.isLoadingRooms) return;
+
+        // Await a promise that resolves when RLS has loaded
+        const { promise, resolve } = Promise.withResolvers<void>();
+        const { LISTS_LOADED_EVENT } = this.events;
+        this.roomListStore.once(LISTS_LOADED_EVENT, resolve);
+        await promise;
+    }
+}
+
+class RoomsWatchable extends Watchable<Room[]> {
+    public constructor(
+        private readonly rls: RoomListStoreV3Class,
+        private readonly events: RlsEvents,
+    ) {
+        super(rls.getSortedRooms().map((sdkRoom) => new ModuleRoom(sdkRoom)));
+    }
+
+    private onRlsUpdate = (): void => {
+        this.value = this.rls.getSortedRooms().map((sdkRoom) => new ModuleRoom(sdkRoom));
+    };
+
+    protected onFirstWatch(): void {
+        this.rls.on(this.events.LISTS_UPDATE_EVENT, this.onRlsUpdate);
+    }
+
+    protected onLastWatch(): void {
+        this.rls.off(this.events.LISTS_UPDATE_EVENT, this.onRlsUpdate);
+    }
+}
+
+export class StoresApi implements IStoresApi {
+    private roomListStoreApi?: IRoomListStore;
+
+    public get roomListStore(): IRoomListStore {
+        if (!this.roomListStoreApi) {
+            this.roomListStoreApi = new RoomListStoreApi();
+        }
+        return this.roomListStoreApi;
+    }
+}