Iterate

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

@@ -8,6 +8,10 @@ Please see LICENSE files in the repository root for full details.
 import { LegacyModuleApiExtension } from "./legacy-modules";
 import { LegacyCustomisationsApiExtension } from "./legacy-customisations";
 
+/**
+ * Module interface for modules to implement.
+ * @public
+ */
 export interface Module {
     load(): Promise<void>;
 }
@@ -16,6 +20,10 @@ const moduleSignature: Record<keyof Module, Type> = {
     load: "function",
 };
 
+/**
+ * Module interface for modules to export as the default export.
+ * @public
+ */
 export interface ModuleFactory {
     readonly moduleApiVersion: string;
     new (api: Api): Module;
@@ -53,6 +61,11 @@ export function isModule(module: unknown): module is ModuleExport {
     );
 }
 
+/**
+ * The configuration for the application.
+ * Should be extended via declaration merging.
+ * @public
+ */
 export interface Config {
     // The branding name of the application
     brand: string;
@@ -60,12 +73,20 @@ export interface Config {
     // they are accessible at runtime all the same, see list at https://github.com/element-hq/element-web/blob/develop/docs/config.md
 }
 
+/**
+ * API for accessing the configuration.
+ * @public
+ */
 export interface ConfigApi {
     get(): Config;
     get<K extends keyof Config>(key: K): Config[K];
     get<K extends keyof Config = never>(key?: K): Config | Config[K];
 }
 
+/**
+ * The API for modules to interact with the application.
+ * @public
+ */
 export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiExtension {
     config: ConfigApi;
 }

packages/element-web-module-api/src/legacy-customisations.ts

@@ -9,11 +9,19 @@ Please see LICENSE files in the repository root for full details.
  * The types here suck but these customisations are deprecated and will be removed soon.
  */
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface AliasCustomisations {
     // E.g. prefer one of the aliases over another
     getDisplayAliasForAliasSet?(canonicalAlias: string | null, altAliases: string[]): string | null;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface ChatExportCustomisations<ExportFormat, ExportType> {
     /**
      * Force parameters in room chat export fields returned here are forced
@@ -33,6 +41,10 @@ export interface ChatExportCustomisations<ExportFormat, ExportType> {
     };
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface ComponentVisibilityCustomisations {
     /**
      * Determines whether or not the active MatrixClient user should be able to use
@@ -40,9 +52,8 @@ export interface ComponentVisibilityCustomisations {
      * 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.
+     * @param component - The component to check visibility for.
+     * @returns True (default) if the user is able to see the component, false otherwise.
      */
     shouldShowComponent?(
         component:
@@ -56,14 +67,26 @@ export interface ComponentVisibilityCustomisations {
     ): boolean;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface DirectoryCustomisations {
     requireCanonicalAliasAccessToPublish?(): boolean;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface LifecycleCustomisations {
     onLoggedOutAndStorageCleared?(): void;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface Media {
     readonly isEncrypted: boolean;
     readonly srcMxc: string;
@@ -77,16 +100,28 @@ export interface Media {
     downloadSource(): Promise<Response>;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface MediaContructable<PreparedMedia> {
     new (prepared: PreparedMedia): Media;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface MediaCustomisations<Content, Client, PreparedMedia> {
     readonly Media: MediaContructable<PreparedMedia>;
     mediaFromContent(content: Content, client?: Client): Media;
     mediaFromMxc(mxc?: string, client?: Client): Media;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface RoomListCustomisations<Room> {
     /**
      * Determines if a room is visible in the room list or not. By default,
@@ -96,12 +131,16 @@ export interface RoomListCustomisations<Room> {
      *
      * 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.
+     * @param room - The room to check the visibility of.
+     * @returns True if the room should be visible, false otherwise.
      */
     isRoomVisible?(room: Room): boolean;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface UserIdentifierCustomisations {
     /**
      * Customise display of the user identifier
@@ -112,6 +151,10 @@ export interface UserIdentifierCustomisations {
     getDisplayUserIdentifier(userId: string, opts: { roomId?: string; withDisplayName?: boolean }): string | null;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface WidgetPermissionsCustomisations<Widget, Capability> {
     /**
      * Approves the widget for capabilities that it requested, if any can be
@@ -120,14 +163,18 @@ export interface WidgetPermissionsCustomisations<Widget, Capability> {
      * 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
+     * @param widget - The widget to approve capabilities for.
+     * @param requestedCapabilities - The capabilities the widget requested.
+     * @returns Resolves to the capabilities that are approved for use
      * by the widget. If none are approved, this should return an empty Set.
      */
     preapproveCapabilities?(widget: Widget, requestedCapabilities: Set<Capability>): Promise<Set<Capability>>;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface WidgetVariablesCustomisations {
     /**
      * Provides a partial set of the variables needed to render any widget. If
@@ -151,54 +198,62 @@ export interface WidgetVariablesCustomisations {
      * Resolves to whether or not the customisation point is ready for variables
      * to be provided. This will block widgets being rendered.
      * If not provided, the app will assume that the customisation is always ready.
-     * @returns {Promise<boolean>} Resolves when ready.
+     * @returns a promise which resolves when ready.
      */
     isReady?(): Promise<void>;
 }
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export type LegacyCustomisations<T extends object> = (customisations: T) => void;
 
+/**
+ * @alpha
+ * @deprecated in favour of the new Module API
+ */
 export interface LegacyCustomisationsApiExtension {
     /**
-     * @deprecated
+     * @deprecated in favour of the new Module API
      */
     readonly _registerLegacyAliasCustomisations: LegacyCustomisations<AliasCustomisations>;
     /**
-     * @deprecated
+     * @deprecated in favour of the new Module API
      */
     readonly _registerLegacyChatExportCustomisations: LegacyCustomisations<ChatExportCustomisations<never, never>>;
     /**
-     * @deprecated
+     * @deprecated in favour of the new Module API
      */
     readonly _registerLegacyComponentVisibilityCustomisations: LegacyCustomisations<ComponentVisibilityCustomisations>;
     /**
-     * @deprecated
+     * @deprecated in favour of the new Module API
      */
     readonly _registerLegacyDirectoryCustomisations: LegacyCustomisations<DirectoryCustomisations>;
     /**
-     * @deprecated
+     * @deprecated in favour of the new Module API
      */
     readonly _registerLegacyLifecycleCustomisations: LegacyCustomisations<LifecycleCustomisations>;
     /**
-     * @deprecated
+     * @deprecated in favour of the new Module API
      */
     readonly _registerLegacyMediaCustomisations: LegacyCustomisations<MediaCustomisations<never, never, never>>;
     /**
-     * @deprecated
+     * @deprecated in favour of the new Module API
      */
     readonly _registerLegacyRoomListCustomisations: LegacyCustomisations<RoomListCustomisations<never>>;
     /**
-     * @deprecated
+     * @deprecated in favour of the new Module API
      */
     readonly _registerLegacyUserIdentifierCustomisations: LegacyCustomisations<UserIdentifierCustomisations>;
     /**
-     * @deprecated
+     * @deprecated in favour of the new Module API
      */
     readonly _registerLegacyWidgetPermissionsCustomisations: LegacyCustomisations<
         WidgetPermissionsCustomisations<never, never>
     >;
     /**
-     * @deprecated
+     * @deprecated in favour of the new Module API
      */
     readonly _registerLegacyWidgetVariablesCustomisations: LegacyCustomisations<WidgetVariablesCustomisations>;
 }

packages/element-web-module-api/src/legacy-modules.ts

@@ -9,13 +9,21 @@ Please see LICENSE files in the repository root for full details.
 // @ts-ignore -- optional interface, will gracefully degrade to `any` if `react-sdk-module-api` isn't installed
 import type { ModuleApi, RuntimeModule } from "@matrix-org/react-sdk-module-api";
 
+/**
+ * @alpha
+ * @deprecated in favour of the new module API
+ */
 export type RuntimeModuleConstructor = new (api: ModuleApi) => RuntimeModule;
 
+/**
+ * @alpha
+ * @deprecated in favour of the new module API
+ */
 /* eslint-disable @typescript-eslint/naming-convention */
 export interface LegacyModuleApiExtension {
     /**
-     * Register a legacy module based on @matrix-org/react-sdk-module-api
-     * @param LegacyModule the module class to register
+     * Register a legacy module based on \@matrix-org/react-sdk-module-api
+     * @param LegacyModule - the module class to register
      * @deprecated provided only as a transition path for legacy modules
      */
     _registerLegacyModule(LegacyModule: RuntimeModuleConstructor): Promise<void>;

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

@@ -9,12 +9,20 @@ import { satisfies } from "semver";
 
 import { Api, isModule, Module, ModuleExport } from "./api";
 
+/**
+ * Error thrown when a module is incompatible with the engine version.
+ * @public
+ */
 export class ModuleIncompatibleError extends Error {
     public constructor(pluginVersion: string) {
         super(`Plugin version ${pluginVersion} is incompatible with engine version ${__VERSION__}`);
     }
 }
 
+/**
+ * A module loader for loading and starting modules.
+ * @public
+ */
 export class ModuleLoader {
     public constructor(private api: Api) {}