feat: show call participants in room list (Discord-style)

apps/web/test/unit-tests/utils/room/canInviteTo-test.ts

@@ -0,0 +1,98 @@
+/*
+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 OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { mocked } from "jest-mock";
+import { JoinRule, Room } from "matrix-js-sdk/src/matrix";
+import { KnownMembership } from "matrix-js-sdk/src/types";
+
+import { shouldShowComponent } from "../../../../src/customisations/helpers/UIComponents";
+import { UIComponent } from "../../../../src/settings/UIFeature";
+import { canInviteTo } from "../../../../src/utils/room/canInviteTo";
+import { getMockClientWithEventEmitter, mockClientMethodsUser } from "../../../test-utils";
+
+jest.mock("../../../../src/customisations/helpers/UIComponents", () => ({
+    shouldShowComponent: jest.fn(),
+}));
+
+describe("canInviteTo()", () => {
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    const userId = "@alice:server.org";
+    const roomId = "!room:server.org";
+
+    const makeRoom = (): Room => {
+        const client = getMockClientWithEventEmitter({
+            ...mockClientMethodsUser(userId),
+        });
+        const room = new Room(roomId, client, userId);
+        jest.spyOn(room, "getMyMembership").mockReturnValue(KnownMembership.Join);
+        jest.spyOn(room, "getJoinRule").mockReturnValue(JoinRule.Public);
+        jest.spyOn(room, "canInvite").mockReturnValue(true);
+        return room;
+    };
+
+    beforeEach(() => {
+        mocked(shouldShowComponent).mockReturnValue(true);
+    });
+
+    describe("when user has permissions to issue an invite for this room", () => {
+        // aka when Room.canInvite is true
+
+        it("should return false when current user membership is not joined", () => {
+            const room = makeRoom();
+            jest.spyOn(room, "getMyMembership").mockReturnValue(KnownMembership.Invite);
+
+            expect(canInviteTo(room)).toEqual(false);
+        });
+
+        it("should return false when UIComponent.InviteUsers customisation hides invite", () => {
+            const room = makeRoom();
+            mocked(shouldShowComponent).mockReturnValue(false);
+
+            expect(canInviteTo(room)).toEqual(false);
+            expect(shouldShowComponent).toHaveBeenCalledWith(UIComponent.InviteUsers);
+        });
+
+        it("should return true when user can invite and is a room member", () => {
+            const room = makeRoom();
+
+            expect(canInviteTo(room)).toEqual(true);
+        });
+    });
+
+    describe("when user does not have permissions to issue an invite for this room", () => {
+        // aka when Room.canInvite is false
+
+        it("should return false when room is a private space", () => {
+            const room = makeRoom();
+            jest.spyOn(room, "getJoinRule").mockReturnValue(JoinRule.Invite);
+            jest.spyOn(room, "isSpaceRoom").mockReturnValue(true);
+            jest.spyOn(room, "canInvite").mockReturnValue(false);
+
+            expect(canInviteTo(room)).toEqual(false);
+        });
+
+        it("should return false when room is just a room", () => {
+            const room = makeRoom();
+            jest.spyOn(room, "canInvite").mockReturnValue(false);
+
+            expect(canInviteTo(room)).toEqual(false);
+        });
+
+        it("should return true when room is a public space", () => {
+            const room = makeRoom();
+            // default join rule is public
+            jest.spyOn(room, "isSpaceRoom").mockReturnValue(true);
+            jest.spyOn(room, "canInvite").mockReturnValue(false);
+
+            expect(canInviteTo(room)).toEqual(true);
+        });
+    });
+});

apps/web/test/unit-tests/utils/room/getJoinedNonFunctionalMembers-test.ts

@@ -0,0 +1,79 @@
+/*
+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 OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { mocked } from "jest-mock";
+import { type MatrixClient, Room, RoomMember } from "matrix-js-sdk/src/matrix";
+
+import { getFunctionalMembers } from "../../../../src/utils/room/getFunctionalMembers";
+import { getJoinedNonFunctionalMembers } from "../../../../src/utils/room/getJoinedNonFunctionalMembers";
+
+jest.mock("../../../../src/utils/room/getFunctionalMembers", () => ({
+    getFunctionalMembers: jest.fn(),
+}));
+
+describe("getJoinedNonFunctionalMembers", () => {
+    let room: Room;
+    let roomMember1: RoomMember;
+    let roomMember2: RoomMember;
+
+    beforeEach(() => {
+        room = new Room("!room:example.com", {} as unknown as MatrixClient, "@user:example.com");
+        room.getJoinedMembers = jest.fn();
+
+        roomMember1 = new RoomMember(room.roomId, "@user1:example.com");
+        roomMember2 = new RoomMember(room.roomId, "@user2:example.com");
+    });
+
+    describe("if there are no members", () => {
+        beforeEach(() => {
+            mocked(room.getJoinedMembers).mockReturnValue([]);
+            mocked(getFunctionalMembers).mockReturnValue([]);
+        });
+
+        it("should return an empty list", () => {
+            expect(getJoinedNonFunctionalMembers(room)).toHaveLength(0);
+        });
+    });
+
+    describe("if there are only regular room members", () => {
+        beforeEach(() => {
+            mocked(room.getJoinedMembers).mockReturnValue([roomMember1, roomMember2]);
+            mocked(getFunctionalMembers).mockReturnValue([]);
+        });
+
+        it("should return the room members", () => {
+            const members = getJoinedNonFunctionalMembers(room);
+            expect(members).toContain(roomMember1);
+            expect(members).toContain(roomMember2);
+        });
+    });
+
+    describe("if there are only functional room members", () => {
+        beforeEach(() => {
+            mocked(room.getJoinedMembers).mockReturnValue([]);
+            mocked(getFunctionalMembers).mockReturnValue(["@functional:example.com"]);
+        });
+
+        it("should return an empty list", () => {
+            expect(getJoinedNonFunctionalMembers(room)).toHaveLength(0);
+        });
+    });
+
+    describe("if there are some functional room members", () => {
+        beforeEach(() => {
+            mocked(room.getJoinedMembers).mockReturnValue([roomMember1, roomMember2]);
+            mocked(getFunctionalMembers).mockReturnValue([roomMember1.userId]);
+        });
+
+        it("should only return the non-functional members", () => {
+            const members = getJoinedNonFunctionalMembers(room);
+            expect(members).not.toContain(roomMember1);
+            expect(members).toContain(roomMember2);
+        });
+    });
+});

apps/web/test/unit-tests/utils/room/getRoomFunctionalMembers-test.ts

@@ -0,0 +1,49 @@
+/*
+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 OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { Room, UNSTABLE_ELEMENT_FUNCTIONAL_USERS } from "matrix-js-sdk/src/matrix";
+
+import { getFunctionalMembers } from "../../../../src/utils/room/getFunctionalMembers";
+import { createTestClient, mkEvent } from "../../../test-utils";
+
+describe("getRoomFunctionalMembers", () => {
+    const client = createTestClient();
+    const room = new Room("!room:example.com", client, client.getUserId()!);
+
+    it("should return an empty array if no functional members state event exists", () => {
+        expect(getFunctionalMembers(room)).toHaveLength(0);
+    });
+
+    it("should return an empty array if functional members state event does not have a service_members field", () => {
+        room.currentState.setStateEvents([
+            mkEvent({
+                event: true,
+                type: UNSTABLE_ELEMENT_FUNCTIONAL_USERS.name,
+                user: "@user:example.com)",
+                room: room.roomId,
+                skey: "",
+                content: {},
+            }),
+        ]);
+        expect(getFunctionalMembers(room)).toHaveLength(0);
+    });
+
+    it("should return service_members field of the functional users state event", () => {
+        room.currentState.setStateEvents([
+            mkEvent({
+                event: true,
+                type: UNSTABLE_ELEMENT_FUNCTIONAL_USERS.name,
+                user: "@user:example.com)",
+                room: room.roomId,
+                skey: "",
+                content: { service_members: ["@user:example.com"] },
+            }),
+        ]);
+        expect(getFunctionalMembers(room)).toEqual(["@user:example.com"]);
+    });
+});

apps/web/test/unit-tests/utils/room/getTagsForRoom-test.ts

@@ -0,0 +1,149 @@
+/*
+ * Copyright 2026 Element Creations Ltd.
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+ * Please see LICENSE files in the repository root for full details.
+ */
+
+import { JoinRule, type MatrixClient, type Room } from "matrix-js-sdk/src/matrix";
+import { KnownMembership } from "matrix-js-sdk/src/types";
+import { mocked } from "jest-mock";
+
+import { createTestClient, mkRoom } from "../../../test-utils";
+import { DefaultTagID } from "../../../../src/stores/room-list-v3/skip-list/tag";
+import { getTagsForRoom } from "../../../../src/utils/room/getTagsForRoom";
+import DMRoomMap from "../../../../src/utils/DMRoomMap";
+
+describe("getTagsForRoom", () => {
+    let client: MatrixClient;
+    let rooms: Room[];
+
+    beforeEach(() => {
+        client = createTestClient();
+        rooms = [];
+
+        const dmRoomMap = {
+            getUserIdForRoomId: jest.fn().mockReturnValue(undefined),
+        } as unknown as DMRoomMap;
+        DMRoomMap.setShared(dmRoomMap);
+    });
+
+    function makeRoom(roomId: string): Room {
+        mkRoom(client, roomId, rooms);
+        mocked(client).getRoom.mockImplementation((id) => rooms.find((r) => r.roomId === id) ?? null);
+        mocked(client).getRooms.mockImplementation(() => rooms);
+        return client.getRoom(roomId)!;
+    }
+
+    it("should return [Invite] for a room where the user is invited", () => {
+        const room = makeRoom("!invited:server");
+        (room.getMyMembership as jest.Mock).mockReturnValue(KnownMembership.Invite);
+
+        const tags = getTagsForRoom(room);
+        expect(tags).toEqual([DefaultTagID.Invite]);
+    });
+
+    it.each([KnownMembership.Leave, KnownMembership.Ban])(
+        "should return [Archived] for a room where the user has %s",
+        (membership) => {
+            const room = makeRoom(`!${membership.toLowerCase()}:server`);
+            (room.getMyMembership as jest.Mock).mockReturnValue(membership);
+
+            const tags = getTagsForRoom(room);
+            expect(tags).toEqual([DefaultTagID.Archived]);
+        },
+    );
+
+    describe("joined rooms", () => {
+        describe("with no user-defined tags and not a DM", () => {
+            it("should return [Untagged] when the room has no tags and is not a DM", () => {
+                const room = makeRoom("!plain:server");
+                (room.getMyMembership as jest.Mock).mockReturnValue(KnownMembership.Join);
+                (room as any).tags = {};
+
+                const tags = getTagsForRoom(room);
+                expect(tags).toEqual([DefaultTagID.Untagged]);
+            });
+        });
+
+        it("should return [DM] when the room is a DM", () => {
+            const room = makeRoom("!dm:server");
+            (room.getMyMembership as jest.Mock).mockReturnValue(KnownMembership.Join);
+            (room as any).tags = {};
+
+            mocked(DMRoomMap.shared().getUserIdForRoomId as jest.Mock).mockReturnValue("@alice:server");
+
+            const tags = getTagsForRoom(room);
+            expect(tags).toContain(DefaultTagID.DM);
+            expect(tags).not.toContain(DefaultTagID.Untagged);
+        });
+
+        describe("rooms with user-defined tags", () => {
+            it("should return the user-defined tags", () => {
+                const room = makeRoom("!tagged:server");
+                (room.getMyMembership as jest.Mock).mockReturnValue(KnownMembership.Join);
+                (room as any).tags = { "m.favourite": {}, "u.alice": {} };
+
+                const tags = getTagsForRoom(room);
+                expect(tags).toContain("m.favourite");
+                expect(tags).toContain("u.alice");
+                expect(tags).not.toContain(DefaultTagID.Untagged);
+            });
+
+            it("should not check DM status when user-defined tags are already present", () => {
+                const room = makeRoom("!tagged-dm:server");
+                (room.getMyMembership as jest.Mock).mockReturnValue(KnownMembership.Join);
+                (room as any).tags = { "m.lowpriority": {} };
+
+                // Even if the room is a DM, user-defined tags take priority
+                mocked(DMRoomMap.shared().getUserIdForRoomId as jest.Mock).mockReturnValue("@alice:server");
+
+                const tags = getTagsForRoom(room);
+                expect(tags).toContain("m.lowpriority");
+                expect(tags).not.toContain(DefaultTagID.DM);
+            });
+        });
+    });
+
+    describe("conference (call) rooms", () => {
+        it.each([JoinRule.Public, JoinRule.Knock])(
+            "should include Conference tag for a call room with %s join rule",
+            (joinRule) => {
+                const room = makeRoom(`!call:${joinRule}:server`);
+                (room.getMyMembership as jest.Mock).mockReturnValue(KnownMembership.Join);
+                (room.isCallRoom as jest.Mock).mockReturnValue(true);
+                (room.getJoinRule as jest.Mock).mockReturnValue(joinRule);
+
+                const tags = getTagsForRoom(room);
+                expect(tags).toContain(DefaultTagID.Conference);
+            },
+        );
+
+        it.each([JoinRule.Invite, JoinRule.Private])(
+            "should not include Conference tag for a call room with %s join rule",
+            (joinRule) => {
+                const room = makeRoom(`!call:${joinRule}:server`);
+                (room.getMyMembership as jest.Mock).mockReturnValue(KnownMembership.Join);
+                (room.isCallRoom as jest.Mock).mockReturnValue(true);
+                (room.getJoinRule as jest.Mock).mockReturnValue(joinRule);
+
+                const tags = getTagsForRoom(room);
+                expect(tags).not.toContain(DefaultTagID.Conference);
+            },
+        );
+
+        it("should include Conference alongside Untagged for a public call room with no other tags", () => {
+            const room = makeRoom("!callPublicPlain:server");
+            (room.getMyMembership as jest.Mock).mockReturnValue(KnownMembership.Join);
+            (room as any).tags = {};
+            (room.isCallRoom as jest.Mock).mockReturnValue(true);
+            (room.getJoinRule as jest.Mock).mockReturnValue(JoinRule.Public);
+
+            const tags = getTagsForRoom(room);
+            // Conference is added to the tag list before the Untagged fallback check,
+            // so tags.length is already 1 — Untagged is not appended.
+            expect(tags).toContain(DefaultTagID.Conference);
+            expect(tags).not.toContain(DefaultTagID.Untagged);
+        });
+    });
+});

apps/web/test/unit-tests/utils/room/inviteToRoom-test.ts

@@ -0,0 +1,57 @@
+/*
+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 OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { Room } from "matrix-js-sdk/src/matrix";
+
+import defaultDispatcher from "../../../../src/dispatcher/dispatcher";
+import { inviteToRoom } from "../../../../src/utils/room/inviteToRoom";
+import { getMockClientWithEventEmitter } from "../../../test-utils";
+
+describe("inviteToRoom()", () => {
+    const userId = "@alice:server.org";
+    const roomId = "!room:server.org";
+
+    const makeRoom = (): Room => {
+        const client = getMockClientWithEventEmitter({
+            isGuest: jest.fn(),
+        });
+        const room = new Room(roomId, client, userId);
+        return room;
+    };
+
+    beforeEach(() => {
+        // stub
+        jest.spyOn(defaultDispatcher, "dispatch").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    it("requires registration when a guest tries to invite to a room", () => {
+        const room = makeRoom();
+
+        jest.spyOn(room.client, "isGuest").mockReturnValue(true);
+
+        inviteToRoom(room);
+
+        expect(defaultDispatcher.dispatch).toHaveBeenCalledTimes(1);
+        expect(defaultDispatcher.dispatch).toHaveBeenCalledWith({ action: "require_registration" });
+    });
+
+    it("opens the room inviter", () => {
+        const room = makeRoom();
+
+        jest.spyOn(room.client, "isGuest").mockReturnValue(false);
+
+        inviteToRoom(room);
+
+        expect(defaultDispatcher.dispatch).toHaveBeenCalledTimes(1);
+        expect(defaultDispatcher.dispatch).toHaveBeenCalledWith({ action: "view_invite", roomId });
+    });
+});

apps/web/test/unit-tests/utils/room/shouldEncryptRoomWithSingle3rdPartyInvite-test.ts

@@ -0,0 +1,102 @@
+/*
+Copyright 2024 New Vector Ltd.
+Copyright 2023 The Matrix.org Foundation C.I.C.
+
+SPDX-License-Identifier: AGPL-3.0-only OR GPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { mocked } from "jest-mock";
+import { type MatrixClient, type MatrixEvent, Room } from "matrix-js-sdk/src/matrix";
+
+import DMRoomMap from "../../../../src/utils/DMRoomMap";
+import { shouldEncryptRoomWithSingle3rdPartyInvite } from "../../../../src/utils/room/shouldEncryptRoomWithSingle3rdPartyInvite";
+import { privateShouldBeEncrypted } from "../../../../src/utils/rooms";
+import { mkRoomMemberJoinEvent, mkThirdPartyInviteEvent, stubClient } from "../../../test-utils";
+
+jest.mock("../../../../src/utils/rooms", () => ({
+    privateShouldBeEncrypted: jest.fn(),
+}));
+
+describe("shouldEncryptRoomWithSingle3rdPartyInvite", () => {
+    let client: MatrixClient;
+    let thirdPartyInviteEvent: MatrixEvent;
+    let roomWithOneThirdPartyInvite: Room;
+
+    beforeAll(() => {
+        client = stubClient();
+        DMRoomMap.makeShared(client);
+    });
+
+    beforeEach(() => {
+        roomWithOneThirdPartyInvite = new Room("!room1:example.com", client, client.getSafeUserId());
+        thirdPartyInviteEvent = mkThirdPartyInviteEvent(
+            client.getSafeUserId(),
+            "user@example.com",
+            roomWithOneThirdPartyInvite.roomId,
+        );
+
+        roomWithOneThirdPartyInvite.currentState.setStateEvents([
+            mkRoomMemberJoinEvent(client.getSafeUserId(), roomWithOneThirdPartyInvite.roomId),
+            thirdPartyInviteEvent,
+        ]);
+        jest.spyOn(DMRoomMap.shared(), "getRoomIds").mockReturnValue(new Set([roomWithOneThirdPartyInvite.roomId]));
+    });
+
+    describe("when well-known promotes encryption", () => {
+        beforeEach(() => {
+            mocked(privateShouldBeEncrypted).mockReturnValue(true);
+        });
+
+        it("should return true + invite event for a DM room with one third-party invite", () => {
+            expect(shouldEncryptRoomWithSingle3rdPartyInvite(roomWithOneThirdPartyInvite)).toEqual({
+                shouldEncrypt: true,
+                inviteEvent: thirdPartyInviteEvent,
+            });
+        });
+
+        it("should return false for a non-DM room with one third-party invite", () => {
+            mocked(DMRoomMap.shared().getRoomIds).mockReturnValue(new Set());
+
+            expect(shouldEncryptRoomWithSingle3rdPartyInvite(roomWithOneThirdPartyInvite)).toEqual({
+                shouldEncrypt: false,
+            });
+        });
+
+        it("should return false for a DM room with two members", () => {
+            roomWithOneThirdPartyInvite.currentState.setStateEvents([
+                mkRoomMemberJoinEvent("@user2:example.com", roomWithOneThirdPartyInvite.roomId),
+            ]);
+
+            expect(shouldEncryptRoomWithSingle3rdPartyInvite(roomWithOneThirdPartyInvite)).toEqual({
+                shouldEncrypt: false,
+            });
+        });
+
+        it("should return false for a DM room with two third-party invites", () => {
+            roomWithOneThirdPartyInvite.currentState.setStateEvents([
+                mkThirdPartyInviteEvent(
+                    client.getSafeUserId(),
+                    "user2@example.com",
+                    roomWithOneThirdPartyInvite.roomId,
+                ),
+            ]);
+
+            expect(shouldEncryptRoomWithSingle3rdPartyInvite(roomWithOneThirdPartyInvite)).toEqual({
+                shouldEncrypt: false,
+            });
+        });
+    });
+
+    describe("when well-known does not promote encryption", () => {
+        beforeEach(() => {
+            mocked(privateShouldBeEncrypted).mockReturnValue(false);
+        });
+
+        it("should return false for a DM room with one third-party invite", () => {
+            expect(shouldEncryptRoomWithSingle3rdPartyInvite(roomWithOneThirdPartyInvite)).toEqual({
+                shouldEncrypt: false,
+            });
+        });
+    });
+});

apps/web/test/unit-tests/utils/room/tagRoom-test.ts

@@ -0,0 +1,178 @@
+/*
+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 OR LicenseRef-Element-Commercial
+Please see LICENSE files in the repository root for full details.
+*/
+
+import { Room } from "matrix-js-sdk/src/matrix";
+
+import RoomListActions from "../../../../src/actions/RoomListActions";
+import defaultDispatcher from "../../../../src/dispatcher/dispatcher";
+import { DefaultTagID, type TagID } from "../../../../src/stores/room-list-v3/skip-list/tag";
+import { CUSTOM_SECTION_TAG_PREFIX } from "../../../../src/stores/room-list-v3/section";
+import { tagRoom } from "../../../../src/utils/room/tagRoom";
+import { getMockClientWithEventEmitter } from "../../../test-utils";
+import * as getTagsForRoomUtils from "../../../../src/utils/room/getTagsForRoom";
+
+describe("tagRoom()", () => {
+    const userId = "@alice:server.org";
+    const roomId = "!room:server.org";
+    const customTag = `${CUSTOM_SECTION_TAG_PREFIX}my-section`;
+
+    const makeRoom = (tags: TagID[] = []): Room => {
+        const client = getMockClientWithEventEmitter({
+            isGuest: jest.fn(),
+        });
+        const room = new Room(roomId, client, userId);
+
+        jest.spyOn(getTagsForRoomUtils, "getTagsForRoom").mockReturnValue(tags);
+
+        return room;
+    };
+
+    beforeEach(() => {
+        // stub
+        jest.spyOn(defaultDispatcher, "dispatch").mockImplementation(() => {});
+        jest.spyOn(RoomListActions, "tagRoom").mockReturnValue({ action: "mocked_tag_room_action", fn: () => {} });
+    });
+
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    it("does nothing when room tag is not allowed", () => {
+        const room = makeRoom();
+
+        tagRoom(room, DefaultTagID.ServerNotice);
+
+        expect(defaultDispatcher.dispatch).not.toHaveBeenCalled();
+        expect(RoomListActions.tagRoom).not.toHaveBeenCalled();
+    });
+
+    describe("when a room has no tags", () => {
+        it("should tag a room as favourite", () => {
+            const room = makeRoom();
+
+            tagRoom(room, DefaultTagID.Favourite);
+
+            expect(defaultDispatcher.dispatch).toHaveBeenCalled();
+            expect(RoomListActions.tagRoom).toHaveBeenCalledWith(
+                room.client,
+                room,
+                null, // remove
+                DefaultTagID.Favourite, // add
+            );
+        });
+
+        it("should tag a room low priority", () => {
+            const room = makeRoom();
+
+            tagRoom(room, DefaultTagID.LowPriority);
+
+            expect(defaultDispatcher.dispatch).toHaveBeenCalled();
+            expect(RoomListActions.tagRoom).toHaveBeenCalledWith(
+                room.client,
+                room,
+                null, // remove
+                DefaultTagID.LowPriority, // add
+            );
+        });
+
+        it("should tag a room with a custom section", () => {
+            const room = makeRoom();
+
+            tagRoom(room, customTag);
+
+            expect(defaultDispatcher.dispatch).toHaveBeenCalled();
+            expect(RoomListActions.tagRoom).toHaveBeenCalledWith(
+                room.client,
+                room,
+                null, // remove
+                customTag, // add
+            );
+        });
+    });
+
+    describe("when a room is tagged as favourite", () => {
+        it("should unfavourite a room", () => {
+            const room = makeRoom([DefaultTagID.Favourite]);
+
+            tagRoom(room, DefaultTagID.Favourite);
+
+            expect(defaultDispatcher.dispatch).toHaveBeenCalled();
+            expect(RoomListActions.tagRoom).toHaveBeenCalledWith(
+                room.client,
+                room,
+                DefaultTagID.Favourite, // remove
+                null, // add
+            );
+        });
+
+        it("should tag a room low priority", () => {
+            const room = makeRoom([DefaultTagID.Favourite]);
+
+            tagRoom(room, DefaultTagID.LowPriority);
+
+            expect(defaultDispatcher.dispatch).toHaveBeenCalled();
+            expect(RoomListActions.tagRoom).toHaveBeenCalledWith(
+                room.client,
+                room,
+                DefaultTagID.Favourite, // remove
+                DefaultTagID.LowPriority, // add
+            );
+        });
+    });
+    describe("when a room is tagged as low priority", () => {
+        it("should favourite a room", () => {
+            const room = makeRoom([DefaultTagID.LowPriority]);
+
+            tagRoom(room, DefaultTagID.Favourite);
+
+            expect(defaultDispatcher.dispatch).toHaveBeenCalled();
+            expect(RoomListActions.tagRoom).toHaveBeenCalledWith(
+                room.client,
+                room,
+                DefaultTagID.LowPriority, // remove
+                DefaultTagID.Favourite, // add
+            );
+        });
+
+        it("should untag a room low priority", () => {
+            const room = makeRoom([DefaultTagID.LowPriority]);
+
+            tagRoom(room, DefaultTagID.LowPriority);
+
+            expect(defaultDispatcher.dispatch).toHaveBeenCalled();
+            expect(RoomListActions.tagRoom).toHaveBeenCalledWith(
+                room.client,
+                room,
+                DefaultTagID.LowPriority, // remove
+                null, // add
+            );
+        });
+    });
+
+    describe("when a room is tagged with a custom section", () => {
+        const otherCustomTag = `${CUSTOM_SECTION_TAG_PREFIX}other-section`;
+
+        it.each([
+            { label: "untag the custom section", applyTag: customTag, expectedAdd: null },
+            { label: "replace with favourite", applyTag: DefaultTagID.Favourite, expectedAdd: DefaultTagID.Favourite },
+            { label: "replace with another custom section", applyTag: otherCustomTag, expectedAdd: otherCustomTag },
+        ])("should $label", ({ applyTag, expectedAdd }) => {
+            const room = makeRoom([customTag]);
+
+            tagRoom(room, applyTag);
+
+            expect(defaultDispatcher.dispatch).toHaveBeenCalled();
+            expect(RoomListActions.tagRoom).toHaveBeenCalledWith(
+                room.client,
+                room,
+                customTag, // remove
+                expectedAdd, // add
+            );
+        });
+    });
+});