Custom component concept piece

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

@@ -4,6 +4,7 @@
 
 ```ts
 
+import { JSX } from 'react';
 import { ModuleApi } from '@matrix-org/react-sdk-module-api';
 import { Root } from 'react-dom/client';
 import { RuntimeModule } from '@matrix-org/react-sdk-module-api';
@@ -21,6 +22,8 @@ export interface AliasCustomisations {
 export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiExtension {
     readonly config: ConfigApi;
     createRoot(element: Element): Root;
+    // (undocumented)
+    readonly customComponents: CustomComponentsApi;
     readonly i18n: I18nApi;
     readonly rootNode: HTMLElement;
 }
@@ -57,6 +60,28 @@ export interface ConfigApi {
     get<K extends keyof Config = never>(key?: K): Config | Config[K];
 }
 
+// @public
+export type CustomComponentProps = {
+    [CustomComponentTarget.TextualEvent]: {
+        mxEvent: any;
+        stripReply: boolean;
+    };
+};
+
+// @public
+export type CustomComponentRenderFunction<T extends CustomComponentTarget> = (props: CustomComponentProps[T], originalComponent: JSX.Element) => JSX.Element | null;
+
+// @public
+export interface CustomComponentsApi {
+    register<T extends CustomComponentTarget>(target: T, renderer: CustomComponentRenderFunction<T>): void;
+}
+
+// @public
+export enum CustomComponentTarget {
+    // (undocumented)
+    TextualEvent = "TextualEvent"
+}
+
 // @alpha @deprecated (undocumented)
 export interface DirectoryCustomisations {
     // (undocumented)

packages/element-web-module-api/src/api/custom-components.ts

@@ -0,0 +1,86 @@
+import { ComponentType, JSX, MouseEventHandler, PropsWithChildren } from "react";
+
+/**
+ * Target of the renderer function.
+ * @public
+ */
+export enum CustomComponentTarget {
+    /**
+     * TODO: We should make this more descriptive.
+     * The renderer for text events in the timeline, such as "m.room.message"
+     */
+    TextualBody = "TextualBody",
+    MessageContextMenu = "MessageContextMenu",
+}
+
+export interface ContextMenuItem {
+    label: string;
+    iconClassName: string;
+    onClick: (
+        e: React.MouseEvent<Element> | React.KeyboardEvent<Element> | React.FormEvent<Element>,
+    ) => void | Promise<void>;
+}
+
+/**
+ * Properties for the render component.
+ * @public
+ */
+export type CustomComponentProps = {
+    [CustomComponentTarget.TextualBody]: {
+        /**
+         * The Matrix event information.
+         * TODO: Should this just use the types from matrix-js-sdk?
+         */
+        mxEvent: any;
+        /**
+         * Words to highlight on
+         */
+        highlights?: string[];
+        /**
+         * Should previews be shown for this event
+         */
+        showUrlPreview?: boolean;
+        /**
+         * Is this event being rendered to a static export
+         */
+        forExport?: boolean;
+    };
+    [CustomComponentTarget.MessageContextMenu]: {
+        /**
+         * The Matrix event information.
+         * TODO: Should this just use the types from matrix-js-sdk?
+         */
+        mxEvent: any;
+        /**
+         * Close the menu
+         */
+        closeMenu: () => void;
+    };
+};
+/**
+ * Render function. Returning null skips this function and passes it onto the next registered renderer.
+ * @public
+ */
+export type CustomComponentRenderFunction<T extends CustomComponentTarget> = (
+    props: CustomComponentProps[T],
+    originalComponent: JSX.Element,
+) => JSX.Element | null;
+
+/**
+ * The API for creating custom components.
+ * @public
+ */
+export interface CustomComponentsApi {
+    /**
+     * Register a renderer for a component type.
+     * @param target - The target type of component
+     * @param renderer - The render method.
+     */
+    register<T extends CustomComponentTarget>(target: T, renderer: CustomComponentRenderFunction<T>): void;
+
+    /**
+     * Register a context menu section with a given set of items.
+     * @param items - A set of items to render.
+     */
+    buildContextMenuBlock(items: ContextMenuItem[]): JSX.Element;
+}

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

@@ -10,6 +10,7 @@ import { LegacyModuleApiExtension } from "./legacy-modules";
 import { LegacyCustomisationsApiExtension } from "./legacy-customisations";
 import { ConfigApi } from "./config";
 import { I18nApi } from "./i18n";
+import { CustomComponentsApi, CustomComponentTarget } from "./custom-components";
 
 /**
  * Module interface for modules to implement.
@@ -86,6 +87,8 @@ export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiEx
      * @public
      */
     readonly rootNode: HTMLElement;
+
+    readonly customComponents: CustomComponentsApi;
     /**
      * 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/index.ts

@@ -9,5 +9,7 @@ export { ModuleLoader, ModuleIncompatibleError } from "./loader";
 export type { Api, Module, ModuleFactory } from "./api";
 export type { Config, ConfigApi } from "./api/config";
 export type { I18nApi, Variables, Translations } from "./api/i18n";
+export type * from "./api/custom-components";
+export { CustomComponentTarget } from "./api/custom-components";
 export type * from "./api/legacy-modules";
 export type * from "./api/legacy-customisations";