diff --git a/packages/element-web-module-api/element-web-module-api.api.md b/packages/element-web-module-api/element-web-module-api.api.md index 18cfa96c1b..2914fc8603 100644 --- a/packages/element-web-module-api/element-web-module-api.api.md +++ b/packages/element-web-module-api/element-web-module-api.api.md @@ -61,29 +61,25 @@ export interface ConfigApi { } // @public -export type CustomComponentProps = { - [CustomComponentTarget.TextualBody]: { - mxEvent: MatrixEvent; - highlights?: string[]; - showUrlPreview?: boolean; - forExport?: boolean; - }; +export interface CustomComponentsApi { + // Warning: (ae-incompatible-release-tags) The symbol "registerMessageRenderer" is marked as @public, but its signature references "CustomMessageRenderFunction" which is marked as @beta + registerMessageRenderer(eventType: string | RegExp, renderer: CustomMessageRenderFunction): void; +} + +// @alpha +export type CustomMessageComponentProps = { + mxEvent: MatrixEvent; + highlights?: string[]; + showUrlPreview?: boolean; + forExport?: boolean; }; -// @public -export type CustomComponentRenderFunction = ( -props: CustomComponentProps[T], -originalComponent: () => JSX.Element) => JSX.Element | null; - -// @public -export interface CustomComponentsApi { - register(target: T, renderer: CustomComponentRenderFunction): void; -} - -// @public -export enum CustomComponentTarget { - TextualBody = "TextualBody" -} +// Warning: (ae-incompatible-release-tags) The symbol "CustomMessageRenderFunction" is marked as @beta, but its signature references "CustomMessageComponentProps" which is marked as @alpha +// +// @beta +export type CustomMessageRenderFunction = ( +props: CustomMessageComponentProps, +originalComponent?: () => React.JSX.Element) => JSX.Element | null; // @alpha @deprecated (undocumented) export interface DirectoryCustomisations { diff --git a/packages/element-web-module-api/src/api/custom-components.ts b/packages/element-web-module-api/src/api/custom-components.ts index 1c1c68b91b..3cae10b61c 100644 --- a/packages/element-web-module-api/src/api/custom-components.ts +++ b/packages/element-web-module-api/src/api/custom-components.ts @@ -9,54 +9,42 @@ import type { JSX } from "react"; import type { MatrixEvent } from "matrix-js-sdk"; /** - * Targets in Element for custom components. - * @public + * Properties for all message components. + * @alpha Subject to change. */ -export enum CustomComponentTarget { +export type CustomMessageComponentProps = { /** - * Component that renders "m.room.message" events in the room timeline. + * The Matrix event for this textual body. */ - TextualBody = "TextualBody", -} + mxEvent: MatrixEvent; + /** + * Words to highlight on (e.g. from search results). + * May be undefined if the client does not need to highlight + */ + highlights?: string[]; + /** + * Should previews be shown for this event + */ + showUrlPreview?: boolean; + /** + * Is this event being rendered to a static export + */ + forExport?: boolean; +}; /** - * Properties for the render component. - * @public + * Function used to render a message component. + * @beta Unlikely to change */ -export type CustomComponentProps = { - [CustomComponentTarget.TextualBody]: { - /** - * The Matrix event for this textual body. - */ - mxEvent: MatrixEvent; - /** - * Words to highlight on (e.g. from search results). - * May be undefined if the client does not need to highlight - */ - highlights?: string[]; - /** - * Should previews be shown for this event - */ - showUrlPreview?: boolean; - /** - * Is this event being rendered to a static export - */ - forExport?: boolean; - }; -}; -/** - * Render function. Returning null skips this function and passes it onto the next registered renderer. - * @public - */ -export type CustomComponentRenderFunction = ( +export type CustomMessageRenderFunction = ( /** - * Properties from the given target to be used for rendering. + * Properties for the message to be renderered. */ - props: CustomComponentProps[T], + props: CustomMessageComponentProps, /** - * Render function for the original component. + * Render function for the original component. This may be omitted if the message would not normally be rendered. */ - originalComponent: () => JSX.Element, + originalComponent?: () => React.JSX.Element, ) => JSX.Element | null; /** @@ -65,16 +53,18 @@ export type CustomComponentRenderFunction = ( */ export interface CustomComponentsApi { /** - * Register a renderer for a component type. + * Register a renderer for a message type in the timeline. + * * The render function should either return a rendered component, or `null` if the - * component should not be overidden. + * component should not be overidden (for instance, to passthrough to another module or allow + * the application complete control) * * Multiple render function may be registered for a single target, however the first * non-null result will be used. If all results are null, or no registrations exist * for a target then the original component is used. * - * @param target - The target location for the component. - * @param renderer - The render method. + * @param eventType - The event type this renderer is for. Use a RegExp instance if you want to target multiple types. + * @param renderer - The render function. */ - register(target: T, renderer: CustomComponentRenderFunction): void; + registerMessageRenderer(eventType: string | RegExp, renderer: CustomMessageRenderFunction): void; } diff --git a/packages/element-web-module-api/src/api/index.ts b/packages/element-web-module-api/src/api/index.ts index feb97cbe51..3e9d4d072f 100644 --- a/packages/element-web-module-api/src/api/index.ts +++ b/packages/element-web-module-api/src/api/index.ts @@ -89,7 +89,7 @@ export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiEx readonly rootNode: HTMLElement; /** - * The custom components API. + * The custom message component API. * @public */ readonly customComponents: CustomComponentsApi; diff --git a/packages/element-web-module-api/src/index.ts b/packages/element-web-module-api/src/index.ts index 6640814d1f..4fbf15e9ba 100644 --- a/packages/element-web-module-api/src/index.ts +++ b/packages/element-web-module-api/src/index.ts @@ -10,6 +10,5 @@ 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";