From 3a5baec69958d37e882caa82e880ab44a04edf20 Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Wed, 29 Jan 2025 10:48:35 +0000 Subject: [PATCH] Iterate --- .../element-web-module-api/api-extractor.json | 454 ++++++++++++++++++ .../element-web-module-api.api.md | 224 +++++++++ packages/element-web-module-api/package.json | 12 +- packages/element-web-module-api/src/api.ts | 21 + .../src/legacy-customisations.ts | 93 +++- .../src/legacy-modules.ts | 12 +- packages/element-web-module-api/src/loader.ts | 8 + packages/element-web-module-api/tsconfig.json | 4 +- .../element-web-module-api/vite.config.ts | 6 +- 9 files changed, 803 insertions(+), 31 deletions(-) create mode 100644 packages/element-web-module-api/api-extractor.json create mode 100644 packages/element-web-module-api/element-web-module-api.api.md diff --git a/packages/element-web-module-api/api-extractor.json b/packages/element-web-module-api/api-extractor.json new file mode 100644 index 0000000000..e945efc023 --- /dev/null +++ b/packages/element-web-module-api/api-extractor.json @@ -0,0 +1,454 @@ +/** + * Config file for API Extractor. For more info, please visit: https://api-extractor.com + */ +{ + "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", + + /** + * Optionally specifies another JSON config file that this file extends from. This provides a way for + * standard settings to be shared across multiple projects. + * + * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains + * the "extends" field. Otherwise, the first path segment is interpreted as an NPM package name, and will be + * resolved using NodeJS require(). + * + * SUPPORTED TOKENS: none + * DEFAULT VALUE: "" + */ + // "extends": "./shared/api-extractor-base.json" + // "extends": "my-package/include/api-extractor-base.json" + + /** + * Determines the "" token that can be used with other config file settings. The project folder + * typically contains the tsconfig.json and package.json config files, but the path is user-defined. + * + * The path is resolved relative to the folder of the config file that contains the setting. + * + * The default value for "projectFolder" is the token "", which means the folder is determined by traversing + * parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder + * that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error + * will be reported. + * + * SUPPORTED TOKENS: + * DEFAULT VALUE: "" + */ + // "projectFolder": "..", + + /** + * (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis. API Extractor + * analyzes the symbols exported by this module. + * + * The file extension must be ".d.ts" and not ".ts". + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + */ + "mainEntryPointFilePath": "/lib/index.d.ts", + + /** + * A list of NPM package names whose exports should be treated as part of this package. + * + * For example, suppose that Webpack is used to generate a distributed bundle for the project "library1", + * and another NPM package "library2" is embedded in this bundle. Some types from library2 may become part + * of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly + * imports library2. To avoid this, we might specify: + * + * "bundledPackages": [ "library2" ], + * + * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been + * local files for library1. + * + * The "bundledPackages" elements may specify glob patterns using minimatch syntax. To ensure deterministic + * output, globs are expanded by matching explicitly declared top-level dependencies only. For example, + * the pattern below will NOT match "@my-company/example" unless it appears in a field such as "dependencies" + * or "devDependencies" of the project's package.json file: + * + * "bundledPackages": [ "@my-company/*" ], + */ + "bundledPackages": [], + + /** + * Specifies what type of newlines API Extractor should use when writing output files. By default, the output files + * will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead. + * To use the OS's default newline kind, specify "os". + * + * DEFAULT VALUE: "crlf" + */ + // "newlineKind": "crlf", + + /** + * Specifies how API Extractor sorts members of an enum when generating the .api.json file. By default, the output + * files will be sorted alphabetically, which is "by-name". To keep the ordering in the source code, specify + * "preserve". + * + * DEFAULT VALUE: "by-name" + */ + // "enumMemberOrder": "by-name", + + /** + * Set to true when invoking API Extractor's test harness. When `testMode` is true, the `toolVersion` field in the + * .api.json file is assigned an empty string to prevent spurious diffs in output files tracked for tests. + * + * DEFAULT VALUE: "false" + */ + // "testMode": false, + + /** + * Determines how the TypeScript compiler engine will be invoked by API Extractor. + */ + "compiler": { + /** + * Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * Note: This setting will be ignored if "overrideTsconfig" is used. + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/tsconfig.json" + */ + // "tsconfigFilePath": "/tsconfig.json", + /** + * Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk. + * The object must conform to the TypeScript tsconfig schema: + * + * http://json.schemastore.org/tsconfig + * + * If omitted, then the tsconfig.json file will be read from the "projectFolder". + * + * DEFAULT VALUE: no overrideTsconfig section + */ + // "overrideTsconfig": { + // . . . + // } + /** + * This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended + * and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when + * dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses + * for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck. + * + * DEFAULT VALUE: false + */ + // "skipLibCheck": true, + }, + + /** + * Configures how the API report file (*.api.md) will be generated. + */ + "apiReport": { + /** + * (REQUIRED) Whether to generate an API report. + */ + "enabled": true, + + /** + * The base filename for the API report files, to be combined with "reportFolder" or "reportTempFolder" + * to produce the full file path. The "reportFileName" should not include any path separators such as + * "\" or "/". The "reportFileName" should not include a file extension, since API Extractor will automatically + * append an appropriate file extension such as ".api.md". If the "reportVariants" setting is used, then the + * file extension includes the variant name, for example "my-report.public.api.md" or "my-report.beta.api.md". + * The "complete" variant always uses the simple extension "my-report.api.md". + * + * Previous versions of API Extractor required "reportFileName" to include the ".api.md" extension explicitly; + * for backwards compatibility, that is still accepted but will be discarded before applying the above rules. + * + * SUPPORTED TOKENS: , + * DEFAULT VALUE: "" + */ + // "reportFileName": "", + + /** + * To support different approval requirements for different API levels, multiple "variants" of the API report can + * be generated. The "reportVariants" setting specifies a list of variants to be generated. If omitted, + * by default only the "complete" variant will be generated, which includes all @internal, @alpha, @beta, + * and @public items. Other possible variants are "alpha" (@alpha + @beta + @public), "beta" (@beta + @public), + * and "public" (@public only). + * + * DEFAULT VALUE: [ "complete" ] + */ + // "reportVariants": ["public", "beta"], + + /** + * Specifies the folder where the API report file is written. The file name portion is determined by + * the "reportFileName" setting. + * + * The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy, + * e.g. for an API review. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/etc/" + */ + "reportFolder": "/" + + /** + * Specifies the folder where the temporary report file is written. The file name portion is determined by + * the "reportFileName" setting. + * + * After the temporary file is written to disk, it is compared with the file in the "reportFolder". + * If they are different, a production build will fail. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/" + */ + // "reportTempFolder": "/temp/", + + /** + * Whether "forgotten exports" should be included in the API report file. Forgotten exports are declarations + * flagged with `ae-forgotten-export` warnings. See https://api-extractor.com/pages/messages/ae-forgotten-export/ to + * learn more. + * + * DEFAULT VALUE: "false" + */ + // "includeForgottenExports": false + }, + + /** + * Configures how the doc model file (*.api.json) will be generated. + */ + "docModel": { + /** + * (REQUIRED) Whether to generate a doc model file. + */ + "enabled": true + + /** + * The output path for the doc model file. The file extension should be ".api.json". + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/temp/.api.json" + */ + // "apiJsonFilePath": "/temp/.api.json", + + /** + * Whether "forgotten exports" should be included in the doc model file. Forgotten exports are declarations + * flagged with `ae-forgotten-export` warnings. See https://api-extractor.com/pages/messages/ae-forgotten-export/ to + * learn more. + * + * DEFAULT VALUE: "false" + */ + // "includeForgottenExports": false, + + /** + * The base URL where the project's source code can be viewed on a website such as GitHub or + * Azure DevOps. This URL path corresponds to the `` path on disk. + * + * This URL is concatenated with the file paths serialized to the doc model to produce URL file paths to individual API items. + * For example, if the `projectFolderUrl` is "https://github.com/microsoft/rushstack/tree/main/apps/api-extractor" and an API + * item's file path is "api/ExtractorConfig.ts", the full URL file path would be + * "https://github.com/microsoft/rushstack/tree/main/apps/api-extractor/api/ExtractorConfig.js". + * + * This setting can be omitted if you don't need source code links in your API documentation reference. + * + * SUPPORTED TOKENS: none + * DEFAULT VALUE: "" + */ + // "projectFolderUrl": "http://github.com/path/to/your/projectFolder" + }, + + /** + * Configures how the .d.ts rollup file will be generated. + */ + "dtsRollup": { + /** + * (REQUIRED) Whether to generate the .d.ts rollup file. + */ + "enabled": true, + + /** + * Specifies the output path for a .d.ts rollup file to be generated without any trimming. + * This file will include all declarations that are exported by the main entry point. + * + * If the path is an empty string, then this file will not be written. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "/dist/.d.ts" + */ + "untrimmedFilePath": "/lib/.d.ts", + + /** + * Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release. + * This file will include only declarations that are marked as "@public", "@beta", or "@alpha". + * + * If the path is an empty string, then this file will not be written. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + "alphaTrimmedFilePath": "/lib/-alpha.d.ts", + + /** + * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release. + * This file will include only declarations that are marked as "@public" or "@beta". + * + * If the path is an empty string, then this file will not be written. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + "betaTrimmedFilePath": "/lib/-beta.d.ts", + + /** + * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release. + * This file will include only declarations that are marked as "@public". + * + * If the path is an empty string, then this file will not be written. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + "publicTrimmedFilePath": "/lib/-public.d.ts" + + /** + * When a declaration is trimmed, by default it will be replaced by a code comment such as + * "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the + * declaration completely. + * + * DEFAULT VALUE: false + */ + // "omitTrimmingComments": true + }, + + /** + * Configures how the tsdoc-metadata.json file will be generated. + */ + "tsdocMetadata": { + /** + * Whether to generate the tsdoc-metadata.json file. + * + * DEFAULT VALUE: true + */ + // "enabled": true, + /** + * Specifies where the TSDoc metadata file should be written. + * + * The path is resolved relative to the folder of the config file that contains the setting; to change this, + * prepend a folder token such as "". + * + * The default value is "", which causes the path to be automatically inferred from the "tsdocMetadata", + * "typings" or "main" fields of the project's package.json. If none of these fields are set, the lookup + * falls back to "tsdoc-metadata.json" in the package folder. + * + * SUPPORTED TOKENS: , , + * DEFAULT VALUE: "" + */ + // "tsdocMetadataFilePath": "/dist/tsdoc-metadata.json" + }, + + /** + * Configures how API Extractor reports error and warning messages produced during analysis. + * + * There are three sources of messages: compiler messages, API Extractor messages, and TSDoc messages. + */ + "messages": { + /** + * Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing + * the input .d.ts files. + * + * TypeScript message identifiers start with "TS" followed by an integer. For example: "TS2551" + * + * DEFAULT VALUE: A single "default" entry with logLevel=warning. + */ + "compilerMessageReporting": { + /** + * Configures the default routing for messages that don't match an explicit rule in this table. + */ + "default": { + /** + * Specifies whether the message should be written to the the tool's output log. Note that + * the "addToApiReportFile" property may supersede this option. + * + * Possible values: "error", "warning", "none" + * + * Errors cause the build to fail and return a nonzero exit code. Warnings cause a production build fail + * and return a nonzero exit code. For a non-production build (e.g. when "api-extractor run" includes + * the "--local" option), the warning is displayed but the build will not fail. + * + * DEFAULT VALUE: "warning" + */ + "logLevel": "warning" + + /** + * When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md), + * then the message will be written inside that file; otherwise, the message is instead logged according to + * the "logLevel" option. + * + * DEFAULT VALUE: false + */ + // "addToApiReportFile": false + } + + // "TS2551": { + // "logLevel": "warning", + // "addToApiReportFile": true + // }, + // + // . . . + }, + + /** + * Configures handling of messages reported by API Extractor during its analysis. + * + * API Extractor message identifiers start with "ae-". For example: "ae-extra-release-tag" + * + * DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings + */ + "extractorMessageReporting": { + "default": { + "logLevel": "warning" + // "addToApiReportFile": false + } + + // "ae-extra-release-tag": { + // "logLevel": "warning", + // "addToApiReportFile": true + // }, + // + // . . . + }, + + /** + * Configures handling of messages reported by the TSDoc parser when analyzing code comments. + * + * TSDoc message identifiers start with "tsdoc-". For example: "tsdoc-link-tag-unescaped-text" + * + * DEFAULT VALUE: A single "default" entry with logLevel=warning. + */ + "tsdocMessageReporting": { + "default": { + "logLevel": "warning" + // "addToApiReportFile": false + } + + // "tsdoc-link-tag-unescaped-text": { + // "logLevel": "warning", + // "addToApiReportFile": true + // }, + // + // . . . + } + } +} 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 new file mode 100644 index 0000000000..e70f3295f5 --- /dev/null +++ b/packages/element-web-module-api/element-web-module-api.api.md @@ -0,0 +1,224 @@ +## 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/). + +```ts +import { ModuleApi } from "@matrix-org/react-sdk-module-api"; +import { RuntimeModule } from "@matrix-org/react-sdk-module-api"; + +// @alpha @deprecated (undocumented) +export interface AliasCustomisations { + // (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 +// +// @public +export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiExtension { + // (undocumented) + config: ConfigApi; +} + +// @alpha @deprecated (undocumented) +export interface ChatExportCustomisations { + getForceChatExportParameters(): { + format?: ExportFormat; + 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; +} + +// @public +export interface Config { + // (undocumented) + brand: string; +} + +// @public +export interface ConfigApi { + // (undocumented) + get(): Config; + // (undocumented) + get(key: K): Config[K]; + // (undocumented) + get(key?: K): Config | Config[K]; +} + +// @alpha @deprecated (undocumented) +export interface DirectoryCustomisations { + // (undocumented) + requireCanonicalAliasAccessToPublish?(): boolean; +} + +// @alpha @deprecated (undocumented) +export type LegacyCustomisations = (customisations: T) => void; + +// @alpha @deprecated (undocumented) +export interface LegacyCustomisationsApiExtension { + // @deprecated (undocumented) + readonly _registerLegacyAliasCustomisations: LegacyCustomisations; + // @deprecated (undocumented) + readonly _registerLegacyChatExportCustomisations: LegacyCustomisations>; + // @deprecated (undocumented) + readonly _registerLegacyComponentVisibilityCustomisations: LegacyCustomisations; + // @deprecated (undocumented) + readonly _registerLegacyDirectoryCustomisations: LegacyCustomisations; + // @deprecated (undocumented) + readonly _registerLegacyLifecycleCustomisations: LegacyCustomisations; + // @deprecated (undocumented) + readonly _registerLegacyMediaCustomisations: LegacyCustomisations>; + // @deprecated (undocumented) + readonly _registerLegacyRoomListCustomisations: LegacyCustomisations>; + // @deprecated (undocumented) + readonly _registerLegacyUserIdentifierCustomisations: LegacyCustomisations; + // @deprecated (undocumented) + readonly _registerLegacyWidgetPermissionsCustomisations: LegacyCustomisations< + WidgetPermissionsCustomisations + >; + // @deprecated (undocumented) + readonly _registerLegacyWidgetVariablesCustomisations: LegacyCustomisations; +} + +// @alpha @deprecated (undocumented) +export interface LegacyModuleApiExtension { + // @deprecated + _registerLegacyModule(LegacyModule: RuntimeModuleConstructor): Promise; +} + +// @alpha @deprecated (undocumented) +export interface LifecycleCustomisations { + // (undocumented) + onLoggedOutAndStorageCleared?(): void; +} + +// @alpha @deprecated (undocumented) +export interface Media { + // (undocumented) + downloadSource(): Promise; + // (undocumented) + getSquareThumbnailHttp(dim: number): string | null; + // (undocumented) + getThumbnailHttp(width: number, height: number, mode?: "scale" | "crop"): string | null; + // (undocumented) + getThumbnailOfSourceHttp(width: number, height: number, mode?: "scale" | "crop"): string | null; + // (undocumented) + readonly hasThumbnail: boolean; + // (undocumented) + readonly isEncrypted: boolean; + // (undocumented) + readonly srcHttp: string | null; + // (undocumented) + readonly srcMxc: string; + // (undocumented) + readonly thumbnailHttp: string | null; + // (undocumented) + readonly thumbnailMxc: string | null | undefined; +} + +// @alpha @deprecated (undocumented) +export interface MediaContructable { + // (undocumented) + new (prepared: PreparedMedia): Media; +} + +// @alpha @deprecated (undocumented) +export interface MediaCustomisations { + // (undocumented) + readonly Media: MediaContructable; + // (undocumented) + mediaFromContent(content: Content, client?: Client): Media; + // (undocumented) + mediaFromMxc(mxc?: string, client?: Client): Media; +} + +// @public +export interface Module { + // (undocumented) + load(): Promise; +} + +// @public +export interface ModuleFactory { + // (undocumented) + new (api: Api): Module; + // (undocumented) + readonly moduleApiVersion: string; + // (undocumented) + readonly prototype: Module; +} + +// @public +export class ModuleIncompatibleError extends Error { + constructor(pluginVersion: string); +} + +// @public +export class ModuleLoader { + constructor(api: Api); + // Warning: (ae-forgotten-export) The symbol "ModuleExport" needs to be exported by the entry point index.d.ts + // + // (undocumented) + load(moduleExport: ModuleExport): Promise; + // (undocumented) + start(): Promise; +} + +// @alpha @deprecated (undocumented) +export interface RoomListCustomisations { + isRoomVisible?(room: Room): boolean; +} + +// @alpha @deprecated (undocumented) +export type RuntimeModuleConstructor = new (api: ModuleApi) => RuntimeModule; + +// @alpha @deprecated (undocumented) +export interface UserIdentifierCustomisations { + getDisplayUserIdentifier( + userId: string, + opts: { + roomId?: string; + withDisplayName?: boolean; + }, + ): string | null; +} + +// @alpha @deprecated (undocumented) +export interface WidgetPermissionsCustomisations { + preapproveCapabilities?(widget: Widget, requestedCapabilities: Set): Promise>; +} + +// @alpha @deprecated (undocumented) +export interface WidgetVariablesCustomisations { + isReady?(): Promise; + provideVariables?(): { + currentUserId: string; + userDisplayName?: string; + userHttpAvatarUrl?: string; + clientId?: string; + clientTheme?: string; + clientLanguage?: string; + deviceId?: string; + baseUrl?: string; + }; +} + +// (No @packageDocumentation comment for this package) +``` diff --git a/packages/element-web-module-api/package.json b/packages/element-web-module-api/package.json index 950f2b362e..c3b8093a61 100644 --- a/packages/element-web-module-api/package.json +++ b/packages/element-web-module-api/package.json @@ -6,22 +6,26 @@ "author": "element-hq", "license": "SEE LICENSE IN README.md", "type": "module", - "types": "./lib/index.d.ts", + "types": "./lib/element-web-module-api-alpha.d.ts", "exports": { ".": { - "types": "./lib/index.d.ts", + "types": "./lib/element-web-module-api-alpha.d.ts", "import": "./lib/element-web-plugin-engine.js", "require": "./lib/element-web-plugin-engine.umd.js" } }, + "files": [ + "lib" + ], "scripts": { - "prepare": "vite build", + "prepare": "vite build && api-extractor run", "lint:ts": "tsc --noEmit" }, "devDependencies": { "@matrix-org/react-sdk-module-api": "^2.5.0", - "@types/react": "^18", + "@microsoft/api-extractor": "^7.49.1", "@types/node": "^22.10.7", + "@types/react": "^18", "@types/semver": "^7.5.8", "matrix-web-i18n": "^3.3.0", "semver": "^7.6.3", diff --git a/packages/element-web-module-api/src/api.ts b/packages/element-web-module-api/src/api.ts index 06ddcaf26b..1ab56aadd4 100644 --- a/packages/element-web-module-api/src/api.ts +++ b/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; } @@ -16,6 +20,10 @@ const moduleSignature: Record = { 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(key: K): Config[K]; get(key?: K): Config | Config[K]; } +/** + * The API for modules to interact with the application. + * @public + */ export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiExtension { config: ConfigApi; } diff --git a/packages/element-web-module-api/src/legacy-customisations.ts b/packages/element-web-module-api/src/legacy-customisations.ts index bc1d963cd4..6374789b5b 100644 --- a/packages/element-web-module-api/src/legacy-customisations.ts +++ b/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 { /** * Force parameters in room chat export fields returned here are forced @@ -33,6 +41,10 @@ export interface ChatExportCustomisations { }; } +/** + * @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; } +/** + * @alpha + * @deprecated in favour of the new Module API + */ export interface MediaContructable { new (prepared: PreparedMedia): Media; } +/** + * @alpha + * @deprecated in favour of the new Module API + */ export interface MediaCustomisations { readonly Media: MediaContructable; mediaFromContent(content: Content, client?: Client): Media; mediaFromMxc(mxc?: string, client?: Client): Media; } +/** + * @alpha + * @deprecated in favour of the new Module API + */ export interface RoomListCustomisations { /** * Determines if a room is visible in the room list or not. By default, @@ -96,12 +131,16 @@ export interface RoomListCustomisations { * * 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 { /** * Approves the widget for capabilities that it requested, if any can be @@ -120,14 +163,18 @@ export interface WidgetPermissionsCustomisations { * 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} requestedCapabilities The capabilities the widget requested. - * @returns {Set} 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): Promise>; } +/** + * @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} Resolves when ready. + * @returns a promise which resolves when ready. */ isReady?(): Promise; } +/** + * @alpha + * @deprecated in favour of the new Module API + */ export type LegacyCustomisations = (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; /** - * @deprecated + * @deprecated in favour of the new Module API */ readonly _registerLegacyChatExportCustomisations: LegacyCustomisations>; /** - * @deprecated + * @deprecated in favour of the new Module API */ readonly _registerLegacyComponentVisibilityCustomisations: LegacyCustomisations; /** - * @deprecated + * @deprecated in favour of the new Module API */ readonly _registerLegacyDirectoryCustomisations: LegacyCustomisations; /** - * @deprecated + * @deprecated in favour of the new Module API */ readonly _registerLegacyLifecycleCustomisations: LegacyCustomisations; /** - * @deprecated + * @deprecated in favour of the new Module API */ readonly _registerLegacyMediaCustomisations: LegacyCustomisations>; /** - * @deprecated + * @deprecated in favour of the new Module API */ readonly _registerLegacyRoomListCustomisations: LegacyCustomisations>; /** - * @deprecated + * @deprecated in favour of the new Module API */ readonly _registerLegacyUserIdentifierCustomisations: LegacyCustomisations; /** - * @deprecated + * @deprecated in favour of the new Module API */ readonly _registerLegacyWidgetPermissionsCustomisations: LegacyCustomisations< WidgetPermissionsCustomisations >; /** - * @deprecated + * @deprecated in favour of the new Module API */ readonly _registerLegacyWidgetVariablesCustomisations: LegacyCustomisations; } diff --git a/packages/element-web-module-api/src/legacy-modules.ts b/packages/element-web-module-api/src/legacy-modules.ts index 8e7cc82ca8..baaad96b01 100644 --- a/packages/element-web-module-api/src/legacy-modules.ts +++ b/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; diff --git a/packages/element-web-module-api/src/loader.ts b/packages/element-web-module-api/src/loader.ts index 8f19cbb627..0b303a19df 100644 --- a/packages/element-web-module-api/src/loader.ts +++ b/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) {} diff --git a/packages/element-web-module-api/tsconfig.json b/packages/element-web-module-api/tsconfig.json index 6b52074a9f..3dee636915 100644 --- a/packages/element-web-module-api/tsconfig.json +++ b/packages/element-web-module-api/tsconfig.json @@ -1,8 +1,10 @@ { + "$schema": "http://json.schemastore.org/tsconfig", "extends": "../../tsconfig.json", "compilerOptions": { "outDir": "lib", - "jsx": "react-jsx" + "jsx": "react-jsx", + "declarationMap": true }, "include": ["src"] } diff --git a/packages/element-web-module-api/vite.config.ts b/packages/element-web-module-api/vite.config.ts index 75670d9ccd..0fee8e9834 100644 --- a/packages/element-web-module-api/vite.config.ts +++ b/packages/element-web-module-api/vite.config.ts @@ -23,11 +23,7 @@ export default defineConfig({ target: "esnext", sourcemap: true, }, - plugins: [ - dts({ - rollupTypes: true, - }), - ], + plugins: [dts()], define: { __VERSION__: JSON.stringify(process.env.npm_package_version), },