Add filter function / hints

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

@@ -62,8 +62,9 @@ export interface ConfigApi {
 
 // @public
 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
+    // Warning: (ae-incompatible-release-tags) The symbol "registerMessageRenderer" is marked as @public, but its signature references "CustomMessageRenderFunction" which is marked as @alpha
-    registerMessageRenderer(eventType: string | RegExp, renderer: CustomMessageRenderFunction): void;
+    // Warning: (ae-incompatible-release-tags) The symbol "registerMessageRenderer" is marked as @public, but its signature references "CustomMessageRenderHints" which is marked as @alpha
+    registerMessageRenderer(eventType: string | ((mxEvent: MatrixEvent) => boolean), renderer: CustomMessageRenderFunction, hints?: CustomMessageRenderHints): void;
 }
 
 // @alpha
@@ -71,13 +72,15 @@ export type CustomMessageComponentProps = {
     mxEvent: MatrixEvent;
 };
 
-// Warning: (ae-incompatible-release-tags) The symbol "CustomMessageRenderFunction" is marked as @beta, but its signature references "CustomMessageComponentProps" which is marked as @alpha
+// @alpha
-// Warning: (ae-incompatible-release-tags) The symbol "CustomMessageRenderFunction" is marked as @beta, but its signature references "OriginalComponentProps" which is marked as @alpha
-//
-// @beta
 export type CustomMessageRenderFunction = (
 props: CustomMessageComponentProps,
-originalComponent?: (props?: OriginalComponentProps) => React.JSX.Element) => JSX.Element | null;
+originalComponent?: (props?: OriginalComponentProps) => React.JSX.Element) => JSX.Element;
+
+// @alpha
+export type CustomMessageRenderHints = {
+    allowEditingEvent?: boolean;
+};
 
 // @alpha @deprecated (undocumented)
 export interface DirectoryCustomisations {

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

@@ -15,6 +15,7 @@ import type { MatrixEvent } from "matrix-js-sdk/lib/matrix";
 export type CustomMessageComponentProps = {
     /**
      * The Matrix event for this textual body.
+     * @alpha
      */
     mxEvent: MatrixEvent;
 };
@@ -31,9 +32,23 @@ export type OriginalComponentProps = {
     showUrlPreview?: boolean;
 };
 
+/**
+ * Hints to specify to Element when rendering events.
+ * @alpha Subject to change.
+ */
+export type CustomMessageRenderHints = {
+    /**
+     * Should the event be allowed to be edited in the client. This should
+     * be set to false if you override the render function, as the module
+     * API has no way to display message editing at the moment.
+     * Default is true.
+     */
+    allowEditingEvent?: boolean;
+};
+
 /**
  * Function used to render a message component.
- * @beta Unlikely to change
+ * @alpha Unlikely to change
  */
 export type CustomMessageRenderFunction = (
     /**
@@ -44,7 +59,7 @@ export type CustomMessageRenderFunction = (
      * Render function for the original component. This may be omitted if the message would not normally be rendered.
      */
     originalComponent?: (props?: OriginalComponentProps) => React.JSX.Element,
-) => JSX.Element | null;
+) => JSX.Element;
 
 /**
  * API for inserting custom components into Element.
@@ -54,29 +69,30 @@ export interface CustomComponentsApi {
     /**
      * Register a renderer for a message type in the timeline.
      *
-     * The render function should either return a rendered component, or `null` if the
+     * The render function should return a rendered component.
-     * 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
+     * Multiple render function may be registered for a single event type, however the first matching
-     * non-null result will be used. If all results are null, or no registrations exist
+     * result will be used. If no events match or are registered then the originalComponent is rendered.
-     * for a target then the original component is used.
      *
-     * @param eventType - The event type this renderer is for. Use a RegExp instance if you want to target multiple types.
+     * @param eventTypeOrFilter - The event type this renderer is for. Use a function for more complex filtering.
      * @param renderer - The render function.
+     * @param hints - Hints that alter the way the tile is handled.
      * @example
      * ```
      *  customComponents.registerMessageRenderer("m.room.message", (props, originalComponent) => {
      *       return <YourCustomComponent mxEvent={props.mxEvent} />;
      *  });
-     *  customComponents.registerMessageRenderer(/m\.room\.(topic|name)/, (props, originalComponent) => {
+     *  customComponents.registerMessageRenderer(
-     *       if (props.mxEvent.isState()) {
+     *      (mxEvent) => mxEvent.getType().matches(/m\.room\.(topic|name)/) && mxEvent.isState(),
-     *           return <YourCustomStateRenderer mxEvent={props.mxEvent} />;
+     *      (props, originalComponent) => {
-     *       }
+     *          return <YourCustomStateRenderer mxEvent={props.mxEvent} />;
-     *       // Passthrough.
+     *      }
-     *       return null;
+     * );
-     *  });
      * ```
      */
-    registerMessageRenderer(eventType: string | RegExp, renderer: CustomMessageRenderFunction): void;
+    registerMessageRenderer(
+        eventTypeOrFilter: string | ((mxEvent: MatrixEvent) => boolean),
+        renderer: CustomMessageRenderFunction,
+        hints?: CustomMessageRenderHints,
+    ): void;
 }