mv element-web-module-api module-api

2026-04-13 09:18:23 +01:00
parent ec8b7bf109
commit ad2e6d37bc
34 changed files with 546 additions and 546 deletions
@@ -0,0 +1,68 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { type IWidget } from "matrix-widget-api";
+
+/**
+ * Containers that control where a widget is displayed on the screen.
+ *
+ * "top" is the app drawer, and currently the only sensible value.
+ *
+ * "right" is the right panel, and the default for widgets. Setting
+ * this as a container on a widget is essentially like saying "no
+ * changes needed", though this may change in the future.
+ *
+ * "center" was uncodumented at time of porting this from an enum.
+ * Possibly when a widget replaces the main chat view like element call.
+ *
+ * @alpha Subject to change.
+ */
+export type Container = "top" | "right" | "center";
+
+/**
+ * An API for interfacing with widgets in Element Web, including getting what widgets
+ * are active in a given room.
+ * @alpha Subject to change.
+ */
+export interface WidgetApi {
+    /**
+     * Gets the widgets active in a given room.
+     *
+     * @param roomId - The room to get the widgets for.
+     */
+    getWidgetsInRoom(roomId: string): IWidget[];
+
+    /**
+     * Gets the URL of a widget's avatar, if it has one.
+     *
+     * @param app - The widget to get the avatar URL for.
+     * @param width - Optional width to resize the avatar to.
+     * @param height - Optional height to resize the avatar to.
+     * @param resizeMethod - Optional method to use when resizing the avatar.
+     * @returns The URL of the widget's avatar, or null if it doesn't have one.
+     */
+    getAppAvatarUrl(app: IWidget, width?: number, height?: number, resizeMethod?: string): string | null;
+
+    /**
+     * Checks if a widget is in a specific container in a given room.
+     *
+     * @param app - The widget to check.
+     * @param container - The container to check.
+     * @param roomId - The room to check in.
+     * @returns True if the widget is in the specified container, false otherwise.
+     */
+    isAppInContainer(app: IWidget, container: Container, roomId: string): boolean;
+
+    /**
+     * Moves a widget to a specific container in a given room.
+     *
+     * @param app - The widget to move.
+     * @param container - The container to move the widget to.
+     * @param roomId - The room to move the widget in.
+     */
+    moveAppToContainer(app: IWidget, container: Container, roomId: string): void;
+}