Custom component concept piece

2025-05-16 15:49:07 +01:00
parent 079f3392bb
commit c9ea5f8f4f
4 changed files with 349 additions and 233 deletions
@@ -1,233 +1,258 @@
-## API Report File for "@element-hq/element-web-module-api"
+## API Report File for "@element-hq/element-web-module-api"
-
+
-> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
-
+
-```ts
+```ts
-
+
-import { ModuleApi } from '@matrix-org/react-sdk-module-api';
+import { JSX } from 'react';
-import { Root } from 'react-dom/client';
+import { ModuleApi } from '@matrix-org/react-sdk-module-api';
-import { RuntimeModule } from '@matrix-org/react-sdk-module-api';
+import { Root } from 'react-dom/client';
-
+import { RuntimeModule } from '@matrix-org/react-sdk-module-api';
-// @alpha @deprecated (undocumented)
+
-export interface AliasCustomisations {
+// @alpha @deprecated (undocumented)
-    // (undocumented)
+export interface AliasCustomisations {
-    getDisplayAliasForAliasSet?(canonicalAlias: string | null, altAliases: string[]): string | null;
+    // (undocumented)
-}
+    getDisplayAliasForAliasSet?(canonicalAlias: string | null, altAliases: string[]): string | null;
-
+}
-// Warning: (ae-incompatible-release-tags) The symbol "Api" is marked as @public, but its signature references "LegacyModuleApiExtension" which is marked as @alpha
+
-// Warning: (ae-incompatible-release-tags) The symbol "Api" is marked as @public, but its signature references "LegacyCustomisationsApiExtension" which is marked as @alpha
+// Warning: (ae-incompatible-release-tags) The symbol "Api" is marked as @public, but its signature references "LegacyModuleApiExtension" which is marked as @alpha
-//
+// Warning: (ae-incompatible-release-tags) The symbol "Api" is marked as @public, but its signature references "LegacyCustomisationsApiExtension" which is marked as @alpha
-// @public
+//
-export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiExtension {
+// @public
-    readonly config: ConfigApi;
+export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiExtension {
-    createRoot(element: Element): Root;
+    readonly config: ConfigApi;
-    readonly i18n: I18nApi;
+    createRoot(element: Element): Root;
-    readonly rootNode: HTMLElement;
+    // (undocumented)
-}
+    readonly customComponents: CustomComponentsApi;
-
+    readonly i18n: I18nApi;
-// @alpha @deprecated (undocumented)
+    readonly rootNode: HTMLElement;
-export interface ChatExportCustomisations<ExportFormat, ExportType> {
+}
-    getForceChatExportParameters(): {
+
-        format?: ExportFormat;
+// @alpha @deprecated (undocumented)
-        range?: ExportType;
+export interface ChatExportCustomisations<ExportFormat, ExportType> {
-        numberOfMessages?: number;
+    getForceChatExportParameters(): {
-        includeAttachments?: boolean;
+        format?: ExportFormat;
-        sizeMb?: number;
+        range?: ExportType;
-    };
+        numberOfMessages?: number;
-}
+        includeAttachments?: boolean;
-
+        sizeMb?: number;
-// @alpha @deprecated (undocumented)
+    };
-export interface ComponentVisibilityCustomisations {
+}
-    shouldShowComponent?(component: "UIComponent.sendInvites" | "UIComponent.roomCreation" | "UIComponent.spaceCreation" | "UIComponent.exploreRooms" | "UIComponent.addIntegrations" | "UIComponent.filterContainer" | "UIComponent.roomOptionsMenu"): boolean;
+
-}
+// @alpha @deprecated (undocumented)
-
+export interface ComponentVisibilityCustomisations {
-// @public
+    shouldShowComponent?(component: "UIComponent.sendInvites" | "UIComponent.roomCreation" | "UIComponent.spaceCreation" | "UIComponent.exploreRooms" | "UIComponent.addIntegrations" | "UIComponent.filterContainer" | "UIComponent.roomOptionsMenu"): boolean;
-export interface Config {
+}
-    // (undocumented)
+
-    brand: string;
+// @public
-}
+export interface Config {
-
+    // (undocumented)
-// @public
+    brand: string;
-export interface ConfigApi {
+}
-    // (undocumented)
+
-    get(): Config;
+// @public
-    // (undocumented)
+export interface ConfigApi {
-    get<K extends keyof Config>(key: K): Config[K];
+    // (undocumented)
-    // (undocumented)
+    get(): Config;
-    get<K extends keyof Config = never>(key?: K): Config | Config[K];
+    // (undocumented)
-}
+    get<K extends keyof Config>(key: K): Config[K];
-
+    // (undocumented)
-// @alpha @deprecated (undocumented)
+    get<K extends keyof Config = never>(key?: K): Config | Config[K];
-export interface DirectoryCustomisations {
+}
-    // (undocumented)
+
-    requireCanonicalAliasAccessToPublish?(): boolean;
+// @public
-}
+export type CustomComponentProps = {
-
+    [CustomComponentTarget.TextualEvent]: {
-// @public
+        mxEvent: any;
-export interface I18nApi {
+        stripReply: boolean;
-    get language(): string;
+    };
-    register(translations: Partial<Translations>): void;
+};
-    translate(key: keyof Translations, variables?: Variables): string;
+
-}
+// @public
-
+export type CustomComponentRenderFunction<T extends CustomComponentTarget> = (props: CustomComponentProps[T], originalComponent: JSX.Element) => JSX.Element | null;
-// @alpha @deprecated (undocumented)
+
-export type LegacyCustomisations<T extends object> = (customisations: T) => void;
+// @public
-
+export interface CustomComponentsApi {
-// @alpha @deprecated (undocumented)
+    register<T extends CustomComponentTarget>(target: T, renderer: CustomComponentRenderFunction<T>): void;
-export interface LegacyCustomisationsApiExtension {
+}
-    // @deprecated (undocumented)
+
-    readonly _registerLegacyAliasCustomisations: LegacyCustomisations<AliasCustomisations>;
+// @public
-    // @deprecated (undocumented)
+export enum CustomComponentTarget {
-    readonly _registerLegacyChatExportCustomisations: LegacyCustomisations<ChatExportCustomisations<never, never>>;
+    // (undocumented)
-    // @deprecated (undocumented)
+    TextualEvent = "TextualEvent"
-    readonly _registerLegacyComponentVisibilityCustomisations: LegacyCustomisations<ComponentVisibilityCustomisations>;
+}
-    // @deprecated (undocumented)
+
-    readonly _registerLegacyDirectoryCustomisations: LegacyCustomisations<DirectoryCustomisations>;
+// @alpha @deprecated (undocumented)
-    // @deprecated (undocumented)
+export interface DirectoryCustomisations {
-    readonly _registerLegacyLifecycleCustomisations: LegacyCustomisations<LifecycleCustomisations>;
+    // (undocumented)
-    // @deprecated (undocumented)
+    requireCanonicalAliasAccessToPublish?(): boolean;
-    readonly _registerLegacyMediaCustomisations: LegacyCustomisations<MediaCustomisations<never, never, never>>;
+}
-    // @deprecated (undocumented)
+
-    readonly _registerLegacyRoomListCustomisations: LegacyCustomisations<RoomListCustomisations<never>>;
+// @public
-    // @deprecated (undocumented)
+export interface I18nApi {
-    readonly _registerLegacyUserIdentifierCustomisations: LegacyCustomisations<UserIdentifierCustomisations>;
+    get language(): string;
-    // @deprecated (undocumented)
+    register(translations: Partial<Translations>): void;
-    readonly _registerLegacyWidgetPermissionsCustomisations: LegacyCustomisations<WidgetPermissionsCustomisations<never, never>>;
+    translate(key: keyof Translations, variables?: Variables): string;
-    // @deprecated (undocumented)
+}
-    readonly _registerLegacyWidgetVariablesCustomisations: LegacyCustomisations<WidgetVariablesCustomisations>;
+
-}
+// @alpha @deprecated (undocumented)
-
+export type LegacyCustomisations<T extends object> = (customisations: T) => void;
-// @alpha @deprecated (undocumented)
+
-export interface LegacyModuleApiExtension {
+// @alpha @deprecated (undocumented)
-    // @deprecated
+export interface LegacyCustomisationsApiExtension {
-    _registerLegacyModule(LegacyModule: RuntimeModuleConstructor): Promise<void>;
+    // @deprecated (undocumented)
-}
+    readonly _registerLegacyAliasCustomisations: LegacyCustomisations<AliasCustomisations>;
-
+    // @deprecated (undocumented)
-// @alpha @deprecated (undocumented)
+    readonly _registerLegacyChatExportCustomisations: LegacyCustomisations<ChatExportCustomisations<never, never>>;
-export interface LifecycleCustomisations {
+    // @deprecated (undocumented)
-    // (undocumented)
+    readonly _registerLegacyComponentVisibilityCustomisations: LegacyCustomisations<ComponentVisibilityCustomisations>;
-    onLoggedOutAndStorageCleared?(): void;
+    // @deprecated (undocumented)
-}
+    readonly _registerLegacyDirectoryCustomisations: LegacyCustomisations<DirectoryCustomisations>;
-
+    // @deprecated (undocumented)
-// @alpha @deprecated (undocumented)
+    readonly _registerLegacyLifecycleCustomisations: LegacyCustomisations<LifecycleCustomisations>;
-export interface Media {
+    // @deprecated (undocumented)
-    // (undocumented)
+    readonly _registerLegacyMediaCustomisations: LegacyCustomisations<MediaCustomisations<never, never, never>>;
-    downloadSource(): Promise<Response>;
+    // @deprecated (undocumented)
-    // (undocumented)
+    readonly _registerLegacyRoomListCustomisations: LegacyCustomisations<RoomListCustomisations<never>>;
-    getSquareThumbnailHttp(dim: number): string | null;
+    // @deprecated (undocumented)
-    // (undocumented)
+    readonly _registerLegacyUserIdentifierCustomisations: LegacyCustomisations<UserIdentifierCustomisations>;
-    getThumbnailHttp(width: number, height: number, mode?: "scale" | "crop"): string | null;
+    // @deprecated (undocumented)
-    // (undocumented)
+    readonly _registerLegacyWidgetPermissionsCustomisations: LegacyCustomisations<WidgetPermissionsCustomisations<never, never>>;
-    getThumbnailOfSourceHttp(width: number, height: number, mode?: "scale" | "crop"): string | null;
+    // @deprecated (undocumented)
-    // (undocumented)
+    readonly _registerLegacyWidgetVariablesCustomisations: LegacyCustomisations<WidgetVariablesCustomisations>;
-    readonly hasThumbnail: boolean;
+}
-    // (undocumented)
+
-    readonly isEncrypted: boolean;
+// @alpha @deprecated (undocumented)
-    // (undocumented)
+export interface LegacyModuleApiExtension {
-    readonly srcHttp: string | null;
+    // @deprecated
-    // (undocumented)
+    _registerLegacyModule(LegacyModule: RuntimeModuleConstructor): Promise<void>;
-    readonly srcMxc: string;
+}
-    // (undocumented)
+
-    readonly thumbnailHttp: string | null;
+// @alpha @deprecated (undocumented)
-    // (undocumented)
+export interface LifecycleCustomisations {
-    readonly thumbnailMxc: string | null | undefined;
+    // (undocumented)
-}
+    onLoggedOutAndStorageCleared?(): void;
-
+}
-// @alpha @deprecated (undocumented)
+
-export interface MediaContructable<PreparedMedia> {
+// @alpha @deprecated (undocumented)
-    // (undocumented)
+export interface Media {
-    new (prepared: PreparedMedia): Media;
+    // (undocumented)
-}
+    downloadSource(): Promise<Response>;
-
+    // (undocumented)
-// @alpha @deprecated (undocumented)
+    getSquareThumbnailHttp(dim: number): string | null;
-export interface MediaCustomisations<Content, Client, PreparedMedia> {
+    // (undocumented)
-    // (undocumented)
+    getThumbnailHttp(width: number, height: number, mode?: "scale" | "crop"): string | null;
-    readonly Media: MediaContructable<PreparedMedia>;
+    // (undocumented)
-    // (undocumented)
+    getThumbnailOfSourceHttp(width: number, height: number, mode?: "scale" | "crop"): string | null;
-    mediaFromContent(content: Content, client?: Client): Media;
+    // (undocumented)
-    // (undocumented)
+    readonly hasThumbnail: boolean;
-    mediaFromMxc(mxc?: string, client?: Client): Media;
+    // (undocumented)
-}
+    readonly isEncrypted: boolean;
-
+    // (undocumented)
-// @public
+    readonly srcHttp: string | null;
-export interface Module {
+    // (undocumented)
-    // (undocumented)
+    readonly srcMxc: string;
-    load(): Promise<void>;
+    // (undocumented)
-}
+    readonly thumbnailHttp: string | null;
-
+    // (undocumented)
-// @public
+    readonly thumbnailMxc: string | null | undefined;
-export interface ModuleFactory {
+}
-    // (undocumented)
+
-    new (api: Api): Module;
+// @alpha @deprecated (undocumented)
-    // (undocumented)
+export interface MediaContructable<PreparedMedia> {
-    readonly moduleApiVersion: string;
+    // (undocumented)
-    // (undocumented)
+    new (prepared: PreparedMedia): Media;
-    readonly prototype: Module;
+}
-}
+
-
+// @alpha @deprecated (undocumented)
-// @public
+export interface MediaCustomisations<Content, Client, PreparedMedia> {
-export class ModuleIncompatibleError extends Error {
+    // (undocumented)
-    constructor(pluginVersion: string);
+    readonly Media: MediaContructable<PreparedMedia>;
-}
+    // (undocumented)
-
+    mediaFromContent(content: Content, client?: Client): Media;
-// @public
+    // (undocumented)
-export class ModuleLoader {
+    mediaFromMxc(mxc?: string, client?: Client): Media;
-    constructor(api: Api);
+}
-    // Warning: (ae-forgotten-export) The symbol "ModuleExport" needs to be exported by the entry point index.d.ts
+
-    //
+// @public
-    // (undocumented)
+export interface Module {
-    load(moduleExport: ModuleExport): Promise<void>;
+    // (undocumented)
-    // (undocumented)
+    load(): Promise<void>;
-    start(): Promise<void>;
+}
-}
+
-
+// @public
-// @alpha @deprecated (undocumented)
+export interface ModuleFactory {
-export interface RoomListCustomisations<Room> {
+    // (undocumented)
-    isRoomVisible?(room: Room): boolean;
+    new (api: Api): Module;
-}
+    // (undocumented)
-
+    readonly moduleApiVersion: string;
-// @alpha @deprecated (undocumented)
+    // (undocumented)
-export type RuntimeModuleConstructor = new (api: ModuleApi) => RuntimeModule;
+    readonly prototype: Module;
-
+}
-// @public
+
-export type Translations = Record<string, {
+// @public
-    [ietfLanguageTag: string]: string;
+export class ModuleIncompatibleError extends Error {
-}>;
+    constructor(pluginVersion: string);
-
+}
-// @alpha @deprecated (undocumented)
+
-export interface UserIdentifierCustomisations {
+// @public
-    getDisplayUserIdentifier(userId: string, opts: {
+export class ModuleLoader {
-        roomId?: string;
+    constructor(api: Api);
-        withDisplayName?: boolean;
+    // Warning: (ae-forgotten-export) The symbol "ModuleExport" needs to be exported by the entry point index.d.ts
-    }): string | null;
+    //
-}
+    // (undocumented)
-
+    load(moduleExport: ModuleExport): Promise<void>;
-// @public
+    // (undocumented)
-export type Variables = {
+    start(): Promise<void>;
-    count?: number;
+}
-    [key: string]: number | string | undefined;
+
-};
+// @alpha @deprecated (undocumented)
-
+export interface RoomListCustomisations<Room> {
-// @alpha @deprecated (undocumented)
+    isRoomVisible?(room: Room): boolean;
-export interface WidgetPermissionsCustomisations<Widget, Capability> {
+}
-    preapproveCapabilities?(widget: Widget, requestedCapabilities: Set<Capability>): Promise<Set<Capability>>;
+
-}
+// @alpha @deprecated (undocumented)
-
+export type RuntimeModuleConstructor = new (api: ModuleApi) => RuntimeModule;
-// @alpha @deprecated (undocumented)
+
-export interface WidgetVariablesCustomisations {
+// @public
-    isReady?(): Promise<void>;
+export type Translations = Record<string, {
-    provideVariables?(): {
+    [ietfLanguageTag: string]: string;
-        currentUserId: string;
+}>;
-        userDisplayName?: string;
+
-        userHttpAvatarUrl?: string;
+// @alpha @deprecated (undocumented)
-        clientId?: string;
+export interface UserIdentifierCustomisations {
-        clientTheme?: string;
+    getDisplayUserIdentifier(userId: string, opts: {
-        clientLanguage?: string;
+        roomId?: string;
-        deviceId?: string;
+        withDisplayName?: boolean;
-        baseUrl?: string;
+    }): string | null;
-    };
+}
-}
+
-
+// @public
-// (No @packageDocumentation comment for this package)
+export type Variables = {
-
+    count?: number;
-```
+    [key: string]: number | string | undefined;
 };
 // @alpha @deprecated (undocumented)
 export interface WidgetPermissionsCustomisations<Widget, Capability> {
    preapproveCapabilities?(widget: Widget, requestedCapabilities: Set<Capability>): Promise<Set<Capability>>;
 }
 // @alpha @deprecated (undocumented)
 export interface WidgetVariablesCustomisations {
    isReady?(): Promise<void>;
    provideVariables?(): {
        currentUserId: string;
        userDisplayName?: string;
        userHttpAvatarUrl?: string;
        clientId?: string;
        clientTheme?: string;
        clientLanguage?: string;
        deviceId?: string;
        baseUrl?: string;
    };
 }
 // (No @packageDocumentation comment for this package)
 ```
@@ -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;
 }
@@ -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.
@@ -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";