mirrors/element-web
1
0
Fork 0
mirror of https://github.com/vector-im/element-web.git synced 2026-05-04 11:51:36 +02:00
Code Issues Projects Releases Wiki Activity

Iterate

Browse Source
This commit is contained in:
Michael Telatynski 2025-01-29 10:48:35 +00:00
parent 3d94420f9f
commit 3a5baec699
9 changed files with 803 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

454
packages/element-web-module-api/api-extractor.json Normal file
View File

@ -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 "<projectFolder>" 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 "<lookup>", 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: <lookup>
* DEFAULT VALUE: "<lookup>"
*/
// "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 "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
*/
"mainEntryPointFilePath": "<projectFolder>/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 "<projectFolder>".
*
* Note: This setting will be ignored if "overrideTsconfig" is used.
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/tsconfig.json"
*/
// "tsconfigFilePath": "<projectFolder>/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: <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<unscopedPackageName>"
*/
// "reportFileName": "<unscopedPackageName>",
/**
* 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 "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/etc/"
*/
"reportFolder": "<projectFolder>/"
/**
* 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 "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/"
*/
// "reportTempFolder": "<projectFolder>/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 "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
*/
// "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.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 `<projectFolder>` 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 "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
*/
"untrimmedFilePath": "<projectFolder>/lib/<unscopedPackageName>.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 "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
"alphaTrimmedFilePath": "<projectFolder>/lib/<unscopedPackageName>-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 "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
"betaTrimmedFilePath": "<projectFolder>/lib/<unscopedPackageName>-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 "<projectFolder>".
*
* SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: ""
*/
"publicTrimmedFilePath": "<projectFolder>/lib/<unscopedPackageName>-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 "<projectFolder>".
*
* The default value is "<lookup>", 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: <projectFolder>, <packageName>, <unscopedPackageName>
* DEFAULT VALUE: "<lookup>"
*/
// "tsdocMetadataFilePath": "<projectFolder>/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
// },
//
// . . .
}
}
}

224
packages/element-web-module-api/element-web-module-api.api.md Normal file
View File

@ -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<ExportFormat, ExportType> {
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<K extends keyof Config>(key: K): Config[K];
// (undocumented)
get<K extends keyof Config = never>(key?: K): Config | Config[K];
}
// @alpha @deprecated (undocumented)
export interface DirectoryCustomisations {
// (undocumented)
requireCanonicalAliasAccessToPublish?(): boolean;
}
// @alpha @deprecated (undocumented)
export type LegacyCustomisations<T extends object> = (customisations: T) => void;
// @alpha @deprecated (undocumented)
export interface LegacyCustomisationsApiExtension {
// @deprecated (undocumented)
readonly _registerLegacyAliasCustomisations: LegacyCustomisations<AliasCustomisations>;
// @deprecated (undocumented)
readonly _registerLegacyChatExportCustomisations: LegacyCustomisations<ChatExportCustomisations<never, never>>;
// @deprecated (undocumented)
readonly _registerLegacyComponentVisibilityCustomisations: LegacyCustomisations<ComponentVisibilityCustomisations>;
// @deprecated (undocumented)
readonly _registerLegacyDirectoryCustomisations: LegacyCustomisations<DirectoryCustomisations>;
// @deprecated (undocumented)
readonly _registerLegacyLifecycleCustomisations: LegacyCustomisations<LifecycleCustomisations>;
// @deprecated (undocumented)
readonly _registerLegacyMediaCustomisations: LegacyCustomisations<MediaCustomisations<never, never, never>>;
// @deprecated (undocumented)
readonly _registerLegacyRoomListCustomisations: LegacyCustomisations<RoomListCustomisations<never>>;
// @deprecated (undocumented)
readonly _registerLegacyUserIdentifierCustomisations: LegacyCustomisations<UserIdentifierCustomisations>;
// @deprecated (undocumented)
readonly _registerLegacyWidgetPermissionsCustomisations: LegacyCustomisations<
WidgetPermissionsCustomisations<never, never>
>;
// @deprecated (undocumented)
readonly _registerLegacyWidgetVariablesCustomisations: LegacyCustomisations<WidgetVariablesCustomisations>;
}
// @alpha @deprecated (undocumented)
export interface LegacyModuleApiExtension {
// @deprecated
_registerLegacyModule(LegacyModule: RuntimeModuleConstructor): Promise<void>;
}
// @alpha @deprecated (undocumented)
export interface LifecycleCustomisations {
// (undocumented)
onLoggedOutAndStorageCleared?(): void;
}
// @alpha @deprecated (undocumented)
export interface Media {
// (undocumented)
downloadSource(): Promise<Response>;
// (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<PreparedMedia> {
// (undocumented)
new (prepared: PreparedMedia): Media;
}
// @alpha @deprecated (undocumented)
export interface MediaCustomisations<Content, Client, PreparedMedia> {
// (undocumented)
readonly Media: MediaContructable<PreparedMedia>;
// (undocumented)
mediaFromContent(content: Content, client?: Client): Media;
// (undocumented)
mediaFromMxc(mxc?: string, client?: Client): Media;
}
// @public
export interface Module {
// (undocumented)
load(): Promise<void>;
}
// @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<void>;
// (undocumented)
start(): Promise<void>;
}
// @alpha @deprecated (undocumented)
export interface RoomListCustomisations<Room> {
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<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)
```

12
packages/element-web-module-api/package.json
View File

@ -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",

21
packages/element-web-module-api/src/api.ts
View File

@ -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;
}

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

@ -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>;
}

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

@ -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>;

8
packages/element-web-module-api/src/loader.ts
View File

@ -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) {}

4
packages/element-web-module-api/tsconfig.json
View File

@ -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"]
}

6
packages/element-web-module-api/vite.config.ts
View File

@ -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),
},