Initial support for runtime modules (#29104)

* Initial runtime Modules work

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Iterate

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Iterate

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Iterate

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Iterate

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

* Comments

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

---------

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

src/customisations/Alias.ts

@@ -6,19 +6,8 @@ SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Com
 Please see LICENSE files in the repository root for full details.
 */
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function getDisplayAliasForAliasSet(canonicalAlias: string | null, altAliases: string[]): string | null {
-    // E.g. prefer one of the aliases over another
-    return null;
-}
-
-// This interface summarises all available customisation points and also marks
-// them all as optional. This allows customisers to only define and export the
-// customisations they need while still maintaining type safety.
-export interface IAliasCustomisations {
-    getDisplayAliasForAliasSet?: typeof getDisplayAliasForAliasSet;
-}
+import type { AliasCustomisations } from "@element-hq/element-web-module-api";
 
 // A real customisation module will define and export one or more of the
-// customisation points that make up `IAliasCustomisations`.
-export default {} as IAliasCustomisations;
+// customisation points that make up `AliasCustomisations`.
+export default {} as AliasCustomisations;

src/customisations/ChatExport.ts

@@ -6,20 +6,13 @@ SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Com
 Please see LICENSE files in the repository root for full details.
 */
 
+import { type ChatExportCustomisations } from "@element-hq/element-web-module-api";
+
 import { type ExportFormat, type ExportType } from "../utils/exportUtils/exportUtils";
 
-export type ForceChatExportParameters = {
-    format?: ExportFormat;
-    range?: ExportType;
-    // must be < 10**8
-    // only used when range is 'LastNMessages'
-    // default is 100
-    numberOfMessages?: number;
-    includeAttachments?: boolean;
-    // maximum size of exported archive
-    // must be > 0 and < 8000
-    sizeMb?: number;
-};
+export type ForceChatExportParameters = ReturnType<
+    ChatExportCustomisations<ExportFormat, ExportType>["getForceChatExportParameters"]
+>;
 
 /**
  * Force parameters in room chat export
@@ -30,15 +23,8 @@ const getForceChatExportParameters = (): ForceChatExportParameters => {
     return {};
 };
 
-// This interface summarises all available customisation points and also marks
-// them all as optional. This allows customisers to only define and export the
-// customisations they need while still maintaining type safety.
-export interface IChatExportCustomisations {
-    getForceChatExportParameters: typeof getForceChatExportParameters;
-}
-
 // A real customisation module will define and export one or more of the
 // customisation points that make up `IChatExportCustomisations`.
 export default {
     getForceChatExportParameters,
-} as IChatExportCustomisations;
+} as ChatExportCustomisations<ExportFormat, ExportType>;

src/customisations/ComponentVisibility.ts

@@ -12,29 +12,7 @@ Please see LICENSE files in the repository root for full details.
 
 // Populate this class with the details of your customisations when copying it.
 
-import { type UIComponent } from "../settings/UIFeature";
-
-/**
- * Determines whether or not the active MatrixClient user should be able to use
- * the given UI component. If shown, the user might still not be able to use the
- * component depending on their contextual permissions. For example, invite options
- * might be shown to the user but they won't have permission to invite users to
- * the current room: the button will appear disabled.
- * @param {UIComponent} component The component to check visibility for.
- * @returns {boolean} True (default) if the user is able to see the component, false
- * otherwise.
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function shouldShowComponent(component: UIComponent): boolean {
-    return true; // default to visible
-}
-
-// This interface summarises all available customisation points and also marks
-// them all as optional. This allows customisers to only define and export the
-// customisations they need while still maintaining type safety.
-export interface IComponentVisibilityCustomisations {
-    shouldShowComponent?: typeof shouldShowComponent;
-}
+import { type ComponentVisibilityCustomisations as IComponentVisibilityCustomisations } from "@element-hq/element-web-module-api";
 
 // A real customisation module will define and export one or more of the
 // customisation points that make up the interface above.

src/customisations/Directory.ts

@@ -6,19 +6,8 @@ SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Com
 Please see LICENSE files in the repository root for full details.
 */
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function requireCanonicalAliasAccessToPublish(): boolean {
-    // Some environments may not care about this requirement and could return false
-    return true;
-}
-
-// This interface summarises all available customisation points and also marks
-// them all as optional. This allows customisers to only define and export the
-// customisations they need while still maintaining type safety.
-export interface IDirectoryCustomisations {
-    requireCanonicalAliasAccessToPublish?: typeof requireCanonicalAliasAccessToPublish;
-}
+import type { DirectoryCustomisations } from "@element-hq/element-web-module-api";
 
 // A real customisation module will define and export one or more of the
 // customisation points that make up `IDirectoryCustomisations`.
-export default {} as IDirectoryCustomisations;
+export default {} as DirectoryCustomisations;

src/customisations/Lifecycle.ts

@@ -6,18 +6,8 @@ SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Com
 Please see LICENSE files in the repository root for full details.
 */
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function onLoggedOutAndStorageCleared(): void {
-    // E.g. redirect user or call other APIs after logout
-}
-
-// This interface summarises all available customisation points and also marks
-// them all as optional. This allows customisers to only define and export the
-// customisations they need while still maintaining type safety.
-export interface ILifecycleCustomisations {
-    onLoggedOutAndStorageCleared?: typeof onLoggedOutAndStorageCleared;
-}
+import type { LifecycleCustomisations } from "@element-hq/element-web-module-api";
 
 // A real customisation module will define and export one or more of the
 // customisation points that make up `ILifecycleCustomisations`.
-export default {} as ILifecycleCustomisations;
+export default {} as LifecycleCustomisations;

src/customisations/Media.ts

@@ -10,6 +10,7 @@ import { type MatrixClient, parseErrorResponse, type ResizeMethod } from "matrix
 import { type MediaEventContent } from "matrix-js-sdk/src/types";
 import { type Optional } from "matrix-events-sdk";
 
+import type { MediaCustomisations, Media } from "@element-hq/element-web-module-api";
 import { MatrixClientPeg } from "../MatrixClientPeg";
 import { type IPreparedMedia, prepEventContentAsMedia } from "./models/IMediaEventContent";
 import { UserFriendlyError } from "../languageHandler";
@@ -25,7 +26,7 @@ import { UserFriendlyError } from "../languageHandler";
  * A media object is a representation of a "source media" and an optional
  * "thumbnail media", derived from event contents or external sources.
  */
-export class Media {
+class MediaImplementation implements Media {
     private client: MatrixClient;
 
     // Per above, this constructor signature can be whatever is helpful for you.
@@ -149,22 +150,27 @@ export class Media {
     }
 }
 
+export type { Media };
+
+type BaseMedia = MediaCustomisations<Partial<MediaEventContent>, MatrixClient, IPreparedMedia>;
+
 /**
  * Creates a media object from event content.
  * @param {MediaEventContent} content The event content.
- * @param {MatrixClient} client? Optional client to use.
- * @returns {Media} The media object.
+ * @param {MatrixClient} client Optional client to use.
+ * @returns {MediaImplementation} The media object.
  */
-export function mediaFromContent(content: Partial<MediaEventContent>, client?: MatrixClient): Media {
-    return new Media(prepEventContentAsMedia(content), client);
-}
+export const mediaFromContent: BaseMedia["mediaFromContent"] = (
+    content: Partial<MediaEventContent>,
+    client?: MatrixClient,
+): Media => new MediaImplementation(prepEventContentAsMedia(content), client);
 
 /**
  * Creates a media object from an MXC URI.
  * @param {string} mxc The MXC URI.
- * @param {MatrixClient} client? Optional client to use.
- * @returns {Media} The media object.
+ * @param {MatrixClient} client Optional client to use.
+ * @returns {MediaImplementation} The media object.
  */
-export function mediaFromMxc(mxc?: string, client?: MatrixClient): Media {
+export const mediaFromMxc: BaseMedia["mediaFromMxc"] = (mxc?: string, client?: MatrixClient): Media => {
     return mediaFromContent({ url: mxc }, client);
-}
+};

src/customisations/RoomList.ts

@@ -8,31 +8,10 @@
 
 import { type Room } from "matrix-js-sdk/src/matrix";
 
+import type { RoomListCustomisations as IRoomListCustomisations } from "@element-hq/element-web-module-api";
+
 // Populate this file with the details of your customisations when copying it.
 
-/**
- * Determines if a room is visible in the room list or not. By default,
- * all rooms are visible. Where special handling is performed by Element,
- * those rooms will not be able to override their visibility in the room
- * list - Element will make the decision without calling this function.
- *
- * This function should be as fast as possible to avoid slowing down the
- * client.
- * @param {Room} room The room to check the visibility of.
- * @returns {boolean} True if the room should be visible, false otherwise.
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function isRoomVisible(room: Room): boolean {
-    return true;
-}
-
-// This interface summarises all available customisation points and also marks
-// them all as optional. This allows customisers to only define and export the
-// customisations they need while still maintaining type safety.
-export interface IRoomListCustomisations {
-    isRoomVisible?: typeof isRoomVisible;
-}
-
 // A real customisation module will define and export one or more of the
 // customisation points that make up the interface above.
-export const RoomListCustomisations: IRoomListCustomisations = {};
+export const RoomListCustomisations: IRoomListCustomisations<Room> = {};

src/customisations/UserIdentifier.ts

@@ -6,6 +6,8 @@ SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Com
 Please see LICENSE files in the repository root for full details.
 */
 
+import type { UserIdentifierCustomisations } from "@element-hq/element-web-module-api";
+
 /**
  * Customise display of the user identifier
  * hide userId for guests, display 3pid
@@ -19,15 +21,8 @@ function getDisplayUserIdentifier(
     return userId;
 }
 
-// This interface summarises all available customisation points and also marks
-// them all as optional. This allows customisers to only define and export the
-// customisations they need while still maintaining type safety.
-export interface IUserIdentifierCustomisations {
-    getDisplayUserIdentifier: typeof getDisplayUserIdentifier;
-}
-
 // A real customisation module will define and export one or more of the
 // customisation points that make up `IUserIdentifierCustomisations`.
 export default {
     getDisplayUserIdentifier,
-} as IUserIdentifierCustomisations;
+} as UserIdentifierCustomisations;

src/customisations/WidgetPermissions.ts

@@ -9,33 +9,8 @@
 // Populate this class with the details of your customisations when copying it.
 import { type Capability, type Widget } from "matrix-widget-api";
 
-/**
- * Approves the widget for capabilities that it requested, if any can be
- * approved. Typically this will be used to give certain widgets capabilities
- * without having to prompt the user to approve them. This cannot reject
- * capabilities that Element will be automatically granting, such as the
- * ability for Jitsi widgets to stay on screen - those will be approved
- * regardless.
- * @param {Widget} widget The widget to approve capabilities for.
- * @param {Set<Capability>} requestedCapabilities The capabilities the widget requested.
- * @returns {Set<Capability>} Resolves to the capabilities that are approved for use
- * by the widget. If none are approved, this should return an empty Set.
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-async function preapproveCapabilities(
-    widget: Widget,
-    requestedCapabilities: Set<Capability>,
-): Promise<Set<Capability>> {
-    return new Set(); // no additional capabilities approved
-}
-
-// This interface summarises all available customisation points and also marks
-// them all as optional. This allows customisers to only define and export the
-// customisations they need while still maintaining type safety.
-export interface IWidgetPermissionCustomisations {
-    preapproveCapabilities?: typeof preapproveCapabilities;
-}
+import type { WidgetPermissionsCustomisations } from "@element-hq/element-web-module-api";
 
 // A real customisation module will define and export one or more of the
 // customisation points that make up the interface above.
-export const WidgetPermissionCustomisations: IWidgetPermissionCustomisations = {};
+export const WidgetPermissionCustomisations: WidgetPermissionsCustomisations<Widget, Capability> = {};

src/customisations/WidgetVariables.ts

@@ -7,41 +7,8 @@
  */
 
 // Populate this class with the details of your customisations when copying it.
-import { type ITemplateParams } from "matrix-widget-api";
-
-/**
- * Provides a partial set of the variables needed to render any widget. If
- * variables are missing or not provided then they will be filled with the
- * application-determined defaults.
- *
- * This will not be called until after isReady() resolves.
- * @returns {Partial<Omit<ITemplateParams, "widgetRoomId">>} The variables.
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function provideVariables(): Partial<Omit<ITemplateParams, "widgetRoomId">> {
-    return {};
-}
-
-/**
- * Resolves to whether or not the customisation point is ready for variables
- * to be provided. This will block widgets being rendered.
- * @returns {Promise<boolean>} Resolves when ready.
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-async function isReady(): Promise<void> {
-    return; // default no waiting
-}
-
-// This interface summarises all available customisation points and also marks
-// them all as optional. This allows customisers to only define and export the
-// customisations they need while still maintaining type safety.
-export interface IWidgetVariablesCustomisations {
-    provideVariables?: typeof provideVariables;
-
-    // If not provided, the app will assume that the customisation is always ready.
-    isReady?: typeof isReady;
-}
+import { type WidgetVariablesCustomisations } from "@element-hq/element-web-module-api";
 
 // A real customisation module will define and export one or more of the
 // customisation points that make up the interface above.
-export const WidgetVariableCustomisations: IWidgetVariablesCustomisations = {};
+export const WidgetVariableCustomisations: WidgetVariablesCustomisations = {};