Merge pull request #79 from element-hq/dbkr/module_experiments

Add some module interfaces

Author: dbkr

packages/element-web-module-api/element-web-module-api.api.md

@@ -35,15 +35,24 @@ export interface AliasCustomisations {
 //
 // @public
 export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiExtension, DialogApiExtension, AccountAuthApiExtension, ProfileApiExtension {
+    // @alpha
+    readonly builtins: BuiltinsApi;
     readonly config: ConfigApi;
     createRoot(element: Element): Root;
     // @alpha
     readonly customComponents: CustomComponentsApi;
+    // @alpha
+    readonly extras: ExtrasApi;
     readonly i18n: I18nApi;
     readonly navigation: NavigationApi;
     readonly rootNode: HTMLElement;
 }
 
+// @alpha
+export interface BuiltinsApi {
+    getRoomViewComponent(): React.ComponentType<RoomViewProps>;
+}
+
 // @alpha @deprecated (undocumented)
 export interface ChatExportCustomisations<ExportFormat, ExportType> {
     getForceChatExportParameters(): {
@@ -140,6 +149,11 @@ export interface DirectoryCustomisations {
     requireCanonicalAliasAccessToPublish?(): boolean;
 }
 
+// @alpha
+export interface ExtrasApi {
+    setSpacePanelItem(spaceKey: string, props: SpacePanelItemProps): void;
+}
+
 // @public
 export interface I18nApi {
     get language(): string;
@@ -186,6 +200,9 @@ export interface LifecycleCustomisations {
     onLoggedOutAndStorageCleared?(): void;
 }
 
+// @alpha
+export type LocationRenderFunction = () => JSX.Element;
+
 // @alpha
 export interface MatrixEvent {
     content: Record<string, unknown>;
@@ -272,6 +289,8 @@ export class ModuleLoader {
 
 // @public
 export interface NavigationApi {
+    // @alpha
+    registerLocationRenderer(path: string, renderer: LocationRenderFunction): void;
     toMatrixToLink(link: string, join?: boolean): Promise<void>;
 }
 
@@ -297,9 +316,24 @@ export interface RoomListCustomisations<Room> {
     isRoomVisible?(room: Room): boolean;
 }
 
+// @alpha
+export interface RoomViewProps {
+    roomId?: string;
+}
+
 // @alpha @deprecated (undocumented)
 export type RuntimeModuleConstructor = new (api: ModuleApi) => RuntimeModule;
 
+// @alpha
+export interface SpacePanelItemProps {
+    className?: string;
+    icon?: JSX.Element;
+    label: string;
+    onSelected: () => void;
+    style?: React.CSSProperties;
+    tooltip?: string;
+}
+
 // @public
 export type Translations = Record<string, {
     [ietfLanguageTag: string]: string;

packages/element-web-module-api/src/api/builtins.ts

@@ -0,0 +1,35 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * The props that must be passed to a RoomView component.
+ * @alpha Subject to change.
+ */
+export interface RoomViewProps {
+    /**
+     * The ID of the room to render.
+     */
+    roomId?: string;
+}
+
+/**
+ * Exposes components and classes that are part of Element Web to allow modules to
+ * render the components as part of their custom components or use the classes
+ * (because they can't import the components from Element Web since it would cause
+ * a dependency cycle)
+ * @alpha
+ */
+export interface BuiltinsApi {
+    /**
+     * Returns the RoomView component used by Element Web to render a room such that
+     * modules can render it as part of their own custom room views.
+     *
+     * @alpha
+     * @returns The RoomView component.
+     */
+    getRoomViewComponent(): React.ComponentType<RoomViewProps>;
+}

packages/element-web-module-api/src/api/extras.ts

@@ -0,0 +1,59 @@
+/*
+Copyright 2025 New Vector Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { JSX } from "react";
+
+/**
+ * Properties of an item added to the Space panel
+ * @alpha
+ */
+export interface SpacePanelItemProps {
+    /**
+     * A CSS class name for the item
+     */
+    className?: string;
+
+    /**
+     * An icon to show in the item. If not provided, no icon will be shown.
+     */
+    icon?: JSX.Element;
+
+    /**
+     * The label to show in the item
+     */
+    label: string;
+
+    /**
+     * A tooltip to show when hovering over the item
+     */
+    tooltip?: string;
+
+    /**
+     * Styles to apply to the item
+     */
+    style?: React.CSSProperties;
+
+    /**
+     * Callback when the item is selected
+     */
+    onSelected: () => void;
+}
+
+/**
+ * API for inserting extra UI into Element Web.
+ * @alpha Subject to change.
+ */
+export interface ExtrasApi {
+    /**
+     * Inserts an item into the space panel as if it were a space button, below
+     * buttons for other spaces.
+     * If called again with the same spaceKey, will update the existing item.
+     * @param spaceKey - A key to identify this space-like item.
+     * @param props - Properties of the item to add.
+     */
+    setSpacePanelItem(spaceKey: string, props: SpacePanelItemProps): void;
+}

packages/element-web-module-api/src/api/index.ts

@@ -15,6 +15,8 @@ import { NavigationApi } from "./navigation.ts";
 import { DialogApiExtension } from "./dialog.ts";
 import { AccountAuthApiExtension } from "./auth.ts";
 import { ProfileApiExtension } from "./profile.ts";
+import { ExtrasApi } from "./extras.ts";
+import { BuiltinsApi } from "./builtins.ts";
 
 /**
  * Module interface for modules to implement.
@@ -103,12 +105,24 @@ export interface Api
      */
     readonly customComponents: CustomComponentsApi;
 
+    /**
+     * Allows modules to render components that are part of Element Web.
+     * @alpha
+     */
+    readonly builtins: BuiltinsApi;
+
     /**
      * API to navigate the application.
      * @public
      */
     readonly navigation: NavigationApi;
 
+    /**
+     * Allows modules to insert extra UI into Element Web.
+     * @alpha
+     */
+    readonly extras: ExtrasApi;
+
     /**
      * Create a ReactDOM root for rendering React components.
      * Exposed to allow modules to avoid needing to bundle their own ReactDOM.

packages/element-web-module-api/src/api/navigation.ts

@@ -5,6 +5,15 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE files in the repository root for full details.
 */
 
+import { JSX } from "react";
+
+/**
+ * A function called to render a component when a user navigates to the corresponding
+ * location. Currently renders alongside just the SpacePanel.
+ * @alpha
+ */
+export type LocationRenderFunction = () => JSX.Element;
+
 /**
  * API methods to navigate the application.
  * @public
@@ -16,4 +25,12 @@ export interface NavigationApi {
      * @param join - If true, the user will be made to attempt to join the room/space if they are not already a member.
      */
     toMatrixToLink(link: string, join?: boolean): Promise<void>;
+
+    /**
+     * Register a renderer for a given location path.
+     * @param path - The location path to register the renderer for.
+     * @param renderer - The function that will render the component for the location.
+     * @alpha
+     */
+    registerLocationRenderer(path: string, renderer: LocationRenderFunction): void;
 }

packages/element-web-module-api/src/index.ts

@@ -11,10 +11,12 @@ export type { Config, ConfigApi } from "./api/config";
 export type { I18nApi, Variables, Translations } from "./api/i18n";
 export type * from "./models/event";
 export type * from "./api/custom-components";
+export type * from "./api/extras";
 export type * from "./api/legacy-modules";
 export type * from "./api/legacy-customisations";
 export type * from "./api/auth";
 export type * from "./api/dialog";
 export type * from "./api/profile";
 export type * from "./api/navigation";
+export type * from "./api/builtins";
 export * from "./api/watchable";