Merge matrix-react-sdk into element-web

Merge remote-tracking branch 'repomerge/t3chguy/repomerge' into t3chguy/repo-merge

Signed-off-by: Michael Telatynski <7t3chguy@gmail.com>

src/customisations/Alias.ts

@@ -0,0 +1,23 @@
+/*
+Copyright 2024 New Vector Ltd.
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+Please see LICENSE files in the repository root for full details.
+*/
+
+function getDisplayAliasForAliasSet(canonicalAlias: string | null, altAliases: string[]): string | null {
+    // E.g. prefer one of the aliases over another
+    return null;
+}
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface IAliasCustomisations {
+    getDisplayAliasForAliasSet?: typeof getDisplayAliasForAliasSet;
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up `IAliasCustomisations`.
+export default {} as IAliasCustomisations;

src/customisations/ChatExport.ts

@@ -0,0 +1,44 @@
+/*
+Copyright 2024 New Vector Ltd.
+Copyright 2022 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { ExportFormat, ExportType } from "../utils/exportUtils/exportUtils";
+
+export type ForceChatExportParameters = {
+    format?: ExportFormat;
+    range?: ExportType;
+    // must be < 10**8
+    // only used when range is 'LastNMessages'
+    // default is 100
+    numberOfMessages?: number;
+    includeAttachments?: boolean;
+    // maximum size of exported archive
+    // must be > 0 and < 8000
+    sizeMb?: number;
+};
+
+/**
+ * Force parameters in room chat export
+ * fields returned here are forced
+ * and not allowed to be edited in the chat export form
+ */
+const getForceChatExportParameters = (): ForceChatExportParameters => {
+    return {};
+};
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface IChatExportCustomisations {
+    getForceChatExportParameters: typeof getForceChatExportParameters;
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up `IChatExportCustomisations`.
+export default {
+    getForceChatExportParameters,
+} as IChatExportCustomisations;

src/customisations/ComponentVisibility.ts

@@ -0,0 +1,43 @@
+/*
+Copyright 2024 New Vector Ltd.
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+Please see LICENSE files in the repository root for full details.
+*/
+
+// Dev note: this customisation point is heavily inspired by UIFeature flags, though
+// with an intention of being used for more complex switching on whether or not a feature
+// should be shown.
+
+// Populate this class with the details of your customisations when copying it.
+
+import { UIComponent } from "../settings/UIFeature";
+
+/**
+ * Determines whether or not the active MatrixClient user should be able to use
+ * the given UI component. If shown, the user might still not be able to use the
+ * 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.
+ */
+function shouldShowComponent(component: UIComponent): boolean {
+    return true; // default to visible
+}
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface IComponentVisibilityCustomisations {
+    shouldShowComponent?: typeof shouldShowComponent;
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up the interface above.
+export const ComponentVisibilityCustomisations: IComponentVisibilityCustomisations = {
+    // while we don't specify the functions here, their defaults are described
+    // in their pseudo-implementations above.
+};

src/customisations/Directory.ts

@@ -0,0 +1,23 @@
+/*
+Copyright 2024 New Vector Ltd.
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+Please see LICENSE files in the repository root for full details.
+*/
+
+function requireCanonicalAliasAccessToPublish(): boolean {
+    // Some environments may not care about this requirement and could return false
+    return true;
+}
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface IDirectoryCustomisations {
+    requireCanonicalAliasAccessToPublish?: typeof requireCanonicalAliasAccessToPublish;
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up `IDirectoryCustomisations`.
+export default {} as IDirectoryCustomisations;

src/customisations/Lifecycle.ts

@@ -0,0 +1,22 @@
+/*
+Copyright 2024 New Vector Ltd.
+Copyright 2020 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+Please see LICENSE files in the repository root for full details.
+*/
+
+function onLoggedOutAndStorageCleared(): void {
+    // E.g. redirect user or call other APIs after logout
+}
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface ILifecycleCustomisations {
+    onLoggedOutAndStorageCleared?: typeof onLoggedOutAndStorageCleared;
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up `ILifecycleCustomisations`.
+export default {} as ILifecycleCustomisations;

src/customisations/Media.ts

@@ -0,0 +1,170 @@
+/*
+ * Copyright 2024 New Vector Ltd.
+ * Copyright 2021 The Matrix.org Foundation C.I.C.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+import { MatrixClient, parseErrorResponse, ResizeMethod } from "matrix-js-sdk/src/matrix";
+import { MediaEventContent } from "matrix-js-sdk/src/types";
+import { Optional } from "matrix-events-sdk";
+
+import { MatrixClientPeg } from "../MatrixClientPeg";
+import { IPreparedMedia, prepEventContentAsMedia } from "./models/IMediaEventContent";
+import { UserFriendlyError } from "../languageHandler";
+
+// Populate this class with the details of your customisations when copying it.
+
+// Implementation note: The Media class must complete the contract as shown here, though
+// the constructor can be whatever is relevant to your implementation. The mediaForX
+// functions below create an instance of the Media class and are used throughout the
+// project.
+
+/**
+ * A media object is a representation of a "source media" and an optional
+ * "thumbnail media", derived from event contents or external sources.
+ */
+export class Media {
+    private client: MatrixClient;
+
+    // Per above, this constructor signature can be whatever is helpful for you.
+    public constructor(
+        private prepared: IPreparedMedia,
+        client?: MatrixClient,
+    ) {
+        this.client = client ?? MatrixClientPeg.safeGet();
+        if (!this.client) {
+            throw new Error("No possible MatrixClient for media resolution. Please provide one or log in.");
+        }
+    }
+
+    /**
+     * True if the media appears to be encrypted. Actual file contents may vary.
+     */
+    public get isEncrypted(): boolean {
+        return !!this.prepared.file;
+    }
+
+    /**
+     * The MXC URI of the source media.
+     */
+    public get srcMxc(): string {
+        return this.prepared.mxc;
+    }
+
+    /**
+     * The MXC URI of the thumbnail media, if a thumbnail is recorded. Null/undefined
+     * otherwise.
+     */
+    public get thumbnailMxc(): Optional<string> {
+        return this.prepared.thumbnail?.mxc;
+    }
+
+    /**
+     * Whether or not a thumbnail is recorded for this media.
+     */
+    public get hasThumbnail(): boolean {
+        return !!this.thumbnailMxc;
+    }
+
+    /**
+     * The HTTP URL for the source media.
+     */
+    public get srcHttp(): string | null {
+        // eslint-disable-next-line no-restricted-properties
+        return this.client.mxcUrlToHttp(this.srcMxc, undefined, undefined, undefined, false, true) || null;
+    }
+
+    /**
+     * The HTTP URL for the thumbnail media (without any specified width, height, etc). Null/undefined
+     * if no thumbnail media recorded.
+     */
+    public get thumbnailHttp(): string | null {
+        if (!this.hasThumbnail) return null;
+        // eslint-disable-next-line no-restricted-properties
+        return this.client.mxcUrlToHttp(this.thumbnailMxc!, undefined, undefined, undefined, false, true);
+    }
+
+    /**
+     * Gets the HTTP URL for the thumbnail media with the requested characteristics, if a thumbnail
+     * is recorded for this media. Returns null/undefined otherwise.
+     * @param {number} width The desired width of the thumbnail.
+     * @param {number} height The desired height of the thumbnail.
+     * @param {"scale"|"crop"} mode The desired thumbnailing mode. Defaults to scale.
+     * @returns {string} The HTTP URL which points to the thumbnail.
+     */
+    public getThumbnailHttp(width: number, height: number, mode: ResizeMethod = "scale"): string | null {
+        if (!this.hasThumbnail) return null;
+        // scale using the device pixel ratio to keep images clear
+        width = Math.floor(width * window.devicePixelRatio);
+        height = Math.floor(height * window.devicePixelRatio);
+        // eslint-disable-next-line no-restricted-properties
+        return this.client.mxcUrlToHttp(this.thumbnailMxc!, width, height, mode, false, true);
+    }
+
+    /**
+     * Gets the HTTP URL for a thumbnail of the source media with the requested characteristics.
+     * @param {number} width The desired width of the thumbnail.
+     * @param {number} height The desired height of the thumbnail.
+     * @param {"scale"|"crop"} mode The desired thumbnailing mode. Defaults to scale.
+     * @returns {string} The HTTP URL which points to the thumbnail.
+     */
+    public getThumbnailOfSourceHttp(width: number, height: number, mode: ResizeMethod = "scale"): string | null {
+        // scale using the device pixel ratio to keep images clear
+        width = Math.floor(width * window.devicePixelRatio);
+        height = Math.floor(height * window.devicePixelRatio);
+        // eslint-disable-next-line no-restricted-properties
+        return this.client.mxcUrlToHttp(this.srcMxc, width, height, mode, false, true);
+    }
+
+    /**
+     * Creates a square thumbnail of the media. If the media has a thumbnail recorded, that MXC will
+     * be used, otherwise the source media will be used.
+     * @param {number} dim The desired width and height.
+     * @returns {string} An HTTP URL for the thumbnail.
+     */
+    public getSquareThumbnailHttp(dim: number): string | null {
+        dim = Math.floor(dim * window.devicePixelRatio); // scale using the device pixel ratio to keep images clear
+        if (this.hasThumbnail) {
+            return this.getThumbnailHttp(dim, dim, "crop");
+        }
+        return this.getThumbnailOfSourceHttp(dim, dim, "crop");
+    }
+
+    /**
+     * Downloads the source media.
+     * @returns {Promise<Response>} Resolves to the server's response for chaining.
+     */
+    public async downloadSource(): Promise<Response> {
+        const src = this.srcHttp;
+        if (!src) {
+            throw new UserFriendlyError("error|download_media");
+        }
+        const res = await fetch(src);
+        if (!res.ok) {
+            throw parseErrorResponse(res, await res.text());
+        }
+        return res;
+    }
+}
+
+/**
+ * Creates a media object from event content.
+ * @param {MediaEventContent} content The event content.
+ * @param {MatrixClient} client? Optional client to use.
+ * @returns {Media} The media object.
+ */
+export function mediaFromContent(content: Partial<MediaEventContent>, client?: MatrixClient): Media {
+    return new Media(prepEventContentAsMedia(content), client);
+}
+
+/**
+ * Creates a media object from an MXC URI.
+ * @param {string} mxc The MXC URI.
+ * @param {MatrixClient} client? Optional client to use.
+ * @returns {Media} The media object.
+ */
+export function mediaFromMxc(mxc?: string, client?: MatrixClient): Media {
+    return mediaFromContent({ url: mxc }, client);
+}

src/customisations/RoomList.ts

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2024 New Vector Ltd.
+ * Copyright 2020 The Matrix.org Foundation C.I.C.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+import { Room } from "matrix-js-sdk/src/matrix";
+
+// Populate this file with the details of your customisations when copying it.
+
+/**
+ * Determines if a room is visible in the room list or not. By default,
+ * all rooms are visible. Where special handling is performed by Element,
+ * those rooms will not be able to override their visibility in the room
+ * list - Element will make the decision without calling this function.
+ *
+ * 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.
+ */
+function isRoomVisible(room: Room): boolean {
+    return true;
+}
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface IRoomListCustomisations {
+    isRoomVisible?: typeof isRoomVisible;
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up the interface above.
+export const RoomListCustomisations: IRoomListCustomisations = {};

src/customisations/Security.ts

@@ -0,0 +1,73 @@
+/*
+Copyright 2024 New Vector Ltd.
+Copyright 2020 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+Please see LICENSE files in the repository root for full details.
+*/
+import { CryptoCallbacks } from "matrix-js-sdk/src/crypto-api";
+
+import { IMatrixClientCreds } from "../MatrixClientPeg";
+import { Kind as SetupEncryptionKind } from "../toasts/SetupEncryptionToast";
+
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars */
+function examineLoginResponse(response: any, credentials: IMatrixClientCreds): void {
+    // E.g. add additional data to the persisted credentials
+}
+
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars */
+function persistCredentials(credentials: IMatrixClientCreds): void {
+    // E.g. store any additional credential fields
+}
+
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars */
+function createSecretStorageKey(): Uint8Array | null {
+    // E.g. generate or retrieve secret storage key somehow
+    return null;
+}
+
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars */
+function getSecretStorageKey(): Uint8Array | null {
+    // E.g. retrieve secret storage key from some other place
+    return null;
+}
+
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars */
+function catchAccessSecretStorageError(e: unknown): void {
+    // E.g. notify the user in some way
+}
+
+/* eslint-disable-next-line @typescript-eslint/no-unused-vars */
+function setupEncryptionNeeded(kind: SetupEncryptionKind): boolean {
+    // E.g. trigger some kind of setup
+    return false;
+}
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface ISecurityCustomisations {
+    examineLoginResponse?: typeof examineLoginResponse;
+    persistCredentials?: typeof persistCredentials;
+    createSecretStorageKey?: typeof createSecretStorageKey;
+    getSecretStorageKey?: typeof getSecretStorageKey;
+    catchAccessSecretStorageError?: typeof catchAccessSecretStorageError;
+    setupEncryptionNeeded?: typeof setupEncryptionNeeded;
+    getDehydrationKey?: CryptoCallbacks["getDehydrationKey"];
+
+    /**
+     * When false, disables the post-login UI from showing. If there's
+     * an error during setup, that will be shown to the user.
+     *
+     * Note: when this is set to false then the app will assume the user's
+     * encryption is set up some other way which would circumvent the default
+     * UI, such as by presenting alternative UI.
+     */
+    SHOW_ENCRYPTION_SETUP_UI?: boolean; // default true
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up `ISecurityCustomisations`.
+export default {
+    SHOW_ENCRYPTION_SETUP_UI: true,
+} as ISecurityCustomisations;

src/customisations/UserIdentifier.ts

@@ -0,0 +1,33 @@
+/*
+Copyright 2024 New Vector Ltd.
+Copyright 2022 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+Please see LICENSE files in the repository root for full details.
+*/
+
+/**
+ * Customise display of the user identifier
+ * hide userId for guests, display 3pid
+ *
+ * Set withDisplayName to true when user identifier will be displayed alongside user name
+ */
+function getDisplayUserIdentifier(
+    userId: string,
+    { roomId, withDisplayName }: { roomId?: string; withDisplayName?: boolean },
+): string | null {
+    return userId;
+}
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface IUserIdentifierCustomisations {
+    getDisplayUserIdentifier: typeof getDisplayUserIdentifier;
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up `IUserIdentifierCustomisations`.
+export default {
+    getDisplayUserIdentifier,
+} as IUserIdentifierCustomisations;

src/customisations/WidgetPermissions.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2024 New Vector Ltd.
+ * Copyright 2020 The Matrix.org Foundation C.I.C.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+// Populate this class with the details of your customisations when copying it.
+import { Capability, Widget } from "matrix-widget-api";
+
+/**
+ * Approves the widget for capabilities that it requested, if any can be
+ * approved. Typically this will be used to give certain widgets capabilities
+ * without having to prompt the user to approve them. This cannot reject
+ * 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
+ * by the widget. If none are approved, this should return an empty Set.
+ */
+async function preapproveCapabilities(
+    widget: Widget,
+    requestedCapabilities: Set<Capability>,
+): Promise<Set<Capability>> {
+    return new Set(); // no additional capabilities approved
+}
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface IWidgetPermissionCustomisations {
+    preapproveCapabilities?: typeof preapproveCapabilities;
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up the interface above.
+export const WidgetPermissionCustomisations: IWidgetPermissionCustomisations = {};

src/customisations/WidgetVariables.ts

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2024 New Vector Ltd.
+ * Copyright 2021 The Matrix.org Foundation C.I.C.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+// Populate this class with the details of your customisations when copying it.
+import { ITemplateParams } from "matrix-widget-api";
+
+/**
+ * Provides a partial set of the variables needed to render any widget. If
+ * variables are missing or not provided then they will be filled with the
+ * application-determined defaults.
+ *
+ * This will not be called until after isReady() resolves.
+ * @returns {Partial<Omit<ITemplateParams, "widgetRoomId">>} The variables.
+ */
+function provideVariables(): Partial<Omit<ITemplateParams, "widgetRoomId">> {
+    return {};
+}
+
+/**
+ * Resolves to whether or not the customisation point is ready for variables
+ * to be provided. This will block widgets being rendered.
+ * @returns {Promise<boolean>} Resolves when ready.
+ */
+async function isReady(): Promise<void> {
+    return; // default no waiting
+}
+
+// This interface summarises all available customisation points and also marks
+// them all as optional. This allows customisers to only define and export the
+// customisations they need while still maintaining type safety.
+export interface IWidgetVariablesCustomisations {
+    provideVariables?: typeof provideVariables;
+
+    // If not provided, the app will assume that the customisation is always ready.
+    isReady?: typeof isReady;
+}
+
+// A real customisation module will define and export one or more of the
+// customisation points that make up the interface above.
+export const WidgetVariableCustomisations: IWidgetVariablesCustomisations = {};

src/customisations/helpers/UIComponents.ts

@@ -0,0 +1,14 @@
+/*
+Copyright 2024 New Vector Ltd.
+Copyright 2021 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { UIComponent } from "../../settings/UIFeature";
+import { ComponentVisibilityCustomisations } from "../ComponentVisibility";
+
+export function shouldShowComponent(component: UIComponent): boolean {
+    return ComponentVisibilityCustomisations.shouldShowComponent?.(component) ?? true;
+}

src/customisations/models/IMediaEventContent.ts

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2024 New Vector Ltd.
+ * Copyright 2021 The Matrix.org Foundation C.I.C.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+import { EncryptedFile, MediaEventContent } from "matrix-js-sdk/src/types";
+
+export interface IPreparedMedia extends IMediaObject {
+    thumbnail?: IMediaObject;
+}
+
+export interface IMediaObject {
+    mxc: string;
+    file?: EncryptedFile;
+}
+
+/**
+ * Parses an event content body into a prepared media object. This prepared media object
+ * can be used with other functions to manipulate the media.
+ * @param {MediaEventContent} content Unredacted media event content. See interface.
+ * @returns {IPreparedMedia} A prepared media object.
+ * @throws Throws if the given content cannot be packaged into a prepared media object.
+ */
+export function prepEventContentAsMedia(content: Partial<MediaEventContent>): IPreparedMedia {
+    let thumbnail: IMediaObject | undefined;
+    if (typeof content?.info === "object" && "thumbnail_url" in content.info && content.info.thumbnail_url) {
+        thumbnail = {
+            mxc: content.info.thumbnail_url,
+            file: content.info.thumbnail_file,
+        };
+    } else if (
+        typeof content?.info === "object" &&
+        "thumbnail_file" in content.info &&
+        typeof content?.info?.thumbnail_file === "object" &&
+        content?.info?.thumbnail_file?.url
+    ) {
+        thumbnail = {
+            mxc: content.info.thumbnail_file.url,
+            file: content.info.thumbnail_file,
+        };
+    }
+
+    if (content?.url) {
+        return {
+            thumbnail,
+            mxc: content.url,
+            file: content.file,
+        };
+    } else if (content?.file?.url) {
+        return {
+            thumbnail,
+            mxc: content.file.url,
+            file: content.file,
+        };
+    }
+
+    throw new Error("Invalid file provided: cannot determine MXC URI. Has it been redacted?");
+}