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 index 56fa2bb0..2d341fde 100644 --- a/packages/element-web-module-api/element-web-module-api.api.md +++ b/packages/element-web-module-api/element-web-module-api.api.md @@ -35,15 +35,24 @@ export interface AliasCustomisations { // // @public export interface Api extends LegacyModuleApiExtension, LegacyCustomisationsApiExtension, DialogApiExtension, AccountAuthApiExtension, ProfileApiExtension { + // @alpha + readonly builtins: BuiltinsApi; readonly config: ConfigApi; createRoot(element: Element): Root; // @alpha readonly customComponents: CustomComponentsApi; + // @alpha + readonly extras: ExtrasApi; readonly i18n: I18nApi; readonly navigation: NavigationApi; readonly rootNode: HTMLElement; } +// @alpha +export interface BuiltinsApi { + getRoomViewComponent(): React.ComponentType; +} + // @alpha @deprecated (undocumented) export interface ChatExportCustomisations { getForceChatExportParameters(): { @@ -140,6 +149,11 @@ export interface DirectoryCustomisations { requireCanonicalAliasAccessToPublish?(): boolean; } +// @alpha +export interface ExtrasApi { + setSpacePanelItem(spaceKey: string, props: SpacePanelItemProps): void; +} + // @public export interface I18nApi { get language(): string; @@ -186,6 +200,9 @@ export interface LifecycleCustomisations { onLoggedOutAndStorageCleared?(): void; } +// @alpha +export type LocationRenderFunction = () => JSX.Element; + // @alpha export interface MatrixEvent { content: Record; @@ -272,6 +289,8 @@ export class ModuleLoader { // @public export interface NavigationApi { + // @alpha + registerLocationRenderer(path: string, renderer: LocationRenderFunction): void; toMatrixToLink(link: string, join?: boolean): Promise; } @@ -297,9 +316,24 @@ export interface RoomListCustomisations { isRoomVisible?(room: Room): boolean; } +// @alpha +export interface RoomViewProps { + roomId?: string; +} + // @alpha @deprecated (undocumented) export type RuntimeModuleConstructor = new (api: ModuleApi) => RuntimeModule; +// @alpha +export interface SpacePanelItemProps { + className?: string; + icon?: JSX.Element; + label: string; + onSelected: () => void; + style?: React.CSSProperties; + tooltip?: string; +} + // @public export type Translations = Record; +} diff --git a/packages/element-web-module-api/src/api/extras.ts b/packages/element-web-module-api/src/api/extras.ts new file mode 100644 index 00000000..1c8d355b --- /dev/null +++ b/packages/element-web-module-api/src/api/extras.ts @@ -0,0 +1,59 @@ +/* +Copyright 2025 New Vector Ltd. + +SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial +Please see LICENSE files in the repository root for full details. +*/ + +import { JSX } from "react"; + +/** + * Properties of an item added to the Space panel + * @alpha + */ +export interface SpacePanelItemProps { + /** + * A CSS class name for the item + */ + className?: string; + + /** + * An icon to show in the item. If not provided, no icon will be shown. + */ + icon?: JSX.Element; + + /** + * The label to show in the item + */ + label: string; + + /** + * A tooltip to show when hovering over the item + */ + tooltip?: string; + + /** + * Styles to apply to the item + */ + style?: React.CSSProperties; + + /** + * Callback when the item is selected + */ + onSelected: () => void; +} + +/** + * API for inserting extra UI into Element Web. + * @alpha Subject to change. + */ +export interface ExtrasApi { + /** + * Inserts an item into the space panel as if it were a space button, below + * buttons for other spaces. + * If called again with the same spaceKey, will update the existing item. + * @param spaceKey - A key to identify this space-like item. + * @param props - Properties of the item to add. + */ + setSpacePanelItem(spaceKey: string, props: SpacePanelItemProps): void; +} diff --git a/packages/element-web-module-api/src/api/index.ts b/packages/element-web-module-api/src/api/index.ts index 8a592607..dacc7501 100644 --- a/packages/element-web-module-api/src/api/index.ts +++ b/packages/element-web-module-api/src/api/index.ts @@ -15,6 +15,8 @@ import { NavigationApi } from "./navigation.ts"; import { DialogApiExtension } from "./dialog.ts"; import { AccountAuthApiExtension } from "./auth.ts"; import { ProfileApiExtension } from "./profile.ts"; +import { ExtrasApi } from "./extras.ts"; +import { BuiltinsApi } from "./builtins.ts"; /** * Module interface for modules to implement. @@ -103,12 +105,24 @@ export interface Api */ readonly customComponents: CustomComponentsApi; + /** + * Allows modules to render components that are part of Element Web. + * @alpha + */ + readonly builtins: BuiltinsApi; + /** * API to navigate the application. * @public */ readonly navigation: NavigationApi; + /** + * Allows modules to insert extra UI into Element Web. + * @alpha + */ + readonly extras: ExtrasApi; + /** * Create a ReactDOM root for rendering React components. * Exposed to allow modules to avoid needing to bundle their own ReactDOM. diff --git a/packages/element-web-module-api/src/api/navigation.ts b/packages/element-web-module-api/src/api/navigation.ts index a3b07327..f7d60b42 100644 --- a/packages/element-web-module-api/src/api/navigation.ts +++ b/packages/element-web-module-api/src/api/navigation.ts @@ -5,6 +5,15 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial Please see LICENSE files in the repository root for full details. */ +import { JSX } from "react"; + +/** + * A function called to render a component when a user navigates to the corresponding + * location. Currently renders alongside just the SpacePanel. + * @alpha + */ +export type LocationRenderFunction = () => JSX.Element; + /** * API methods to navigate the application. * @public @@ -16,4 +25,12 @@ export interface NavigationApi { * @param join - If true, the user will be made to attempt to join the room/space if they are not already a member. */ toMatrixToLink(link: string, join?: boolean): Promise; + + /** + * Register a renderer for a given location path. + * @param path - The location path to register the renderer for. + * @param renderer - The function that will render the component for the location. + * @alpha + */ + registerLocationRenderer(path: string, renderer: LocationRenderFunction): void; } diff --git a/packages/element-web-module-api/src/index.ts b/packages/element-web-module-api/src/index.ts index 196db8d9..e89adc48 100644 --- a/packages/element-web-module-api/src/index.ts +++ b/packages/element-web-module-api/src/index.ts @@ -11,10 +11,12 @@ export type { Config, ConfigApi } from "./api/config"; export type { I18nApi, Variables, Translations } from "./api/i18n"; export type * from "./models/event"; export type * from "./api/custom-components"; +export type * from "./api/extras"; export type * from "./api/legacy-modules"; export type * from "./api/legacy-customisations"; export type * from "./api/auth"; export type * from "./api/dialog"; export type * from "./api/profile"; export type * from "./api/navigation"; +export type * from "./api/builtins"; export * from "./api/watchable";