feat: first draft of sections in RLSV3

Author: florianduros

apps/web/src/stores/room-list-v3/RoomListStoreV3.ts

@@ -15,7 +15,6 @@ import type { FilterKey } from "./skip-list/filters";
 import { AsyncStoreWithClient } from "../AsyncStoreWithClient";
 import SettingsStore from "../../settings/SettingsStore";
 import defaultDispatcher from "../../dispatcher/dispatcher";
-import { RoomSkipList } from "./skip-list/RoomSkipList";
 import { RecencySorter } from "./skip-list/sorters/RecencySorter";
 import { AlphabeticSorter } from "./skip-list/sorters/AlphabeticSorter";
 import { readReceiptChangeIsFor } from "../../utils/read-receipts";
@@ -36,6 +35,7 @@ import { Action } from "../../dispatcher/actions";
 import { UnreadSorter } from "./skip-list/sorters/UnreadSorter";
 import { getChangedOverrideRoomMutePushRules } from "./utils";
 import { isRoomVisible } from "./isRoomVisible";
+import { type Section, SectionStore } from "./SectionStore";
 
 /**
  * These are the filters passed to the room skip list.
@@ -64,7 +64,7 @@ export type RoomsResult = {
     // The filter queried
     filterKeys?: FilterKey[];
     // The resulting list of rooms
-    rooms: Room[];
+    sections: Section[];
 };
 
 export const LISTS_UPDATE_EVENT = RoomListStoreV3Event.ListsUpdate;
@@ -75,7 +75,11 @@ export const LISTS_LOADED_EVENT = RoomListStoreV3Event.ListsLoaded;
  * This store is being actively developed so expect the methods to change in future.
  */
 export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
-    private roomSkipList?: RoomSkipList;
+    /**
+     * The section store holds the actual skip lists that are used to store rooms.
+     */
+    private sectionStore?: SectionStore;
+
     private readonly msc3946ProcessDynamicPredecessor: boolean;
 
     public constructor(dispatcher: MatrixDispatcher) {
@@ -100,14 +104,14 @@ export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
      * Check whether the initial list of rooms has loaded.
      */
     public get isLoadingRooms(): boolean {
-        return !this.roomSkipList?.initialized;
+        return !this.sectionStore?.initialized;
     }
 
     /**
      * Get a list of sorted rooms.
      */
     public getSortedRooms(): Room[] {
-        if (this.roomSkipList?.initialized) return Array.from(this.roomSkipList);
+        if (this.sectionStore?.initialized) return this.sectionStore.getSortedRooms();
         else return [];
     }
 
@@ -120,25 +124,32 @@ export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
      */
     public getSortedRoomsInActiveSpace(filterKeys?: FilterKey[]): RoomsResult {
         const spaceId = SpaceStore.instance.activeSpace;
-        if (this.roomSkipList?.initialized)
+        console.log(
+            "Getting sorted rooms in active space with filters",
+            filterKeys,
+            "and spaceId",
+            spaceId,
+            this.sectionStore?.getSections(filterKeys),
+        );
+        if (this.sectionStore?.initialized)
             return {
                 spaceId: spaceId,
                 filterKeys,
-                rooms: Array.from(this.roomSkipList.getRoomsInActiveSpace(filterKeys)),
+                sections: this.sectionStore.getSections(filterKeys),
             };
-        else return { spaceId: spaceId, filterKeys, rooms: [] };
+        else return { spaceId: spaceId, filterKeys, sections: [] };
     }
 
     /**
      * Resort the list of rooms using a different algorithm.
      * @param algorithm The sorting algorithm to use.
      */
     public resort(algorithm: SortingAlgorithm): void {
-        if (!this.roomSkipList) throw new Error("Cannot resort room list before skip list is created.");
+        if (!this.sectionStore) throw new Error("Cannot resort room list before skip list is created.");
         if (!this.matrixClient) throw new Error("Cannot resort room list without matrix client.");
-        if (this.roomSkipList.activeSortAlgorithm === algorithm) return;
+        if (this.sectionStore.activeSortAlgorithm === algorithm) return;
         const sorter = this.getSorterFromSortingAlgorithm(algorithm, this.matrixClient.getSafeUserId());
-        this.roomSkipList.useNewSorter(sorter, this.getRooms());
+        this.sectionStore.useNewSorter(sorter, this.getRooms());
         this.emit(LISTS_UPDATE_EVENT);
         SettingsStore.setValue("RoomList.preferredSorting", null, SettingLevel.DEVICE, algorithm);
     }
@@ -147,26 +158,26 @@ export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
      * Currently active sorting algorithm if the store is ready or undefined otherwise.
      */
     public get activeSortAlgorithm(): SortingAlgorithm | undefined {
-        return this.roomSkipList?.activeSortAlgorithm;
+        return this.sectionStore?.activeSortAlgorithm;
     }
 
     protected async onReady(): Promise<any> {
-        if (this.roomSkipList?.initialized || !this.matrixClient) return;
+        if (this.sectionStore?.initialized || !this.matrixClient) return;
         const sorter = this.getPreferredSorter(this.matrixClient.getSafeUserId());
-        this.roomSkipList = new RoomSkipList(sorter, FILTERS);
+        this.sectionStore = new SectionStore(sorter, FILTERS);
         await SpaceStore.instance.storeReadyPromise;
         const rooms = this.getRooms();
-        this.roomSkipList.seed(rooms);
+        this.sectionStore.seed(rooms);
         this.emit(LISTS_LOADED_EVENT);
         this.emit(LISTS_UPDATE_EVENT);
     }
 
     protected async onNotReady(): Promise<void> {
-        this.roomSkipList = undefined;
+        this.sectionStore = undefined;
     }
 
     protected async onAction(payload: ActionPayload): Promise<void> {
-        if (!this.matrixClient || !this.roomSkipList?.initialized) return;
+        if (!this.matrixClient || !this.sectionStore?.initialized) return;
 
         /**
          * For the kind of updates that we care about (represented by the cases below),
@@ -242,7 +253,7 @@ export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
                     (oldMembership === EffectiveMembership.Invite || oldMembership === EffectiveMembership.Join) &&
                     newMembership === EffectiveMembership.Leave
                 ) {
-                    this.roomSkipList.removeRoom(payload.room);
+                    this.sectionStore.removeRoom(payload.room);
                     this.emit(LISTS_UPDATE_EVENT);
                     return;
                 }
@@ -258,7 +269,7 @@ export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
                     );
                     const predecessors = roomUpgradeHistory.slice(0, roomUpgradeHistory.indexOf(room));
                     for (const predecessor of predecessors) {
-                        this.roomSkipList.removeRoom(predecessor);
+                        this.sectionStore.removeRoom(predecessor);
                     }
                 }
 
@@ -268,7 +279,7 @@ export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
 
             case Action.AfterForgetRoom: {
                 const room = payload.room;
-                this.roomSkipList.removeRoom(room);
+                this.sectionStore.removeRoom(room);
                 this.emit(LISTS_UPDATE_EVENT);
                 break;
             }
@@ -279,6 +290,8 @@ export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
      * This method deals with the two types of account data payloads that we care about.
      */
     private handleAccountDataPayload(payload: ActionPayload): void {
+        if (!this.sectionStore) throw new Error("sectionStore hasn't been created yet!");
+
         const eventType = payload.event_type;
         let needsEmit = false;
         switch (eventType) {
@@ -293,7 +306,7 @@ export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
                             logger.warn(`${roomId} was found in DMs but the room is not in the store`);
                             continue;
                         }
-                        this.roomSkipList!.reInsertRoom(room);
+                        this.sectionStore.reInsertRoom(room);
                         needsEmit = true;
                     }
                 }
@@ -307,7 +320,7 @@ export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
                     .map((id) => this.matrixClient?.getRoom(id))
                     .filter((room) => !!room);
                 for (const room of rooms) {
-                    this.roomSkipList!.reInsertRoom(room);
+                    this.sectionStore.reInsertRoom(room);
                     needsEmit = true;
                 }
                 break;
@@ -354,24 +367,24 @@ export class RoomListStoreV3Class extends AsyncStoreWithClient<EmptyObject> {
      * @param isNewRoom Set this to true if this a new room that the isn't already in the skiplist
      */
     private addRoomAndEmit(room: Room, isNewRoom = false): void {
-        if (!this.roomSkipList) throw new Error("roomSkipList hasn't been created yet!");
+        if (!this.sectionStore) throw new Error("roomSkipList hasn't been created yet!");
         if (isNewRoom) {
             if (!isRoomVisible(room)) {
                 logger.info(
                     `RoomListStoreV3: Refusing to add new room ${room.roomId} because isRoomVisible returned false.`,
                 );
                 return;
             }
-            this.roomSkipList.addNewRoom(room);
+            this.sectionStore.addNewRoom(room);
         } else {
-            this.roomSkipList.reInsertRoom(room);
+            this.sectionStore.reInsertRoom(room);
         }
         this.emit(LISTS_UPDATE_EVENT);
     }
 
     private onActiveSpaceChanged(): void {
-        if (!this.roomSkipList) return;
-        this.roomSkipList.calculateActiveSpaceForNodes();
+        if (!this.sectionStore) return;
+        this.sectionStore.calculateActiveSpaceForNodes();
         this.emit(LISTS_UPDATE_EVENT);
     }
 }

apps/web/src/stores/room-list-v3/SectionStore.ts

@@ -0,0 +1,188 @@
+/*
+ * 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 { type Room } from "matrix-js-sdk/src/matrix";
+
+import { ExcludeTagsFilter } from "./skip-list/filters/ExcludeTagsFilter";
+import { TagFilter } from "./skip-list/filters/TagFilter";
+import { RoomSkipList } from "./skip-list/RoomSkipList";
+import { type SortingAlgorithm, type Sorter } from "./skip-list/sorters";
+import { DefaultTagID } from "./skip-list/tag";
+import { type FilterKey, type Filter } from "./skip-list/filters";
+import { filterBoolean } from "../../utils/arrays";
+
+/**
+ * Represents a named section of rooms in the room list, identified by a tag.
+ */
+export interface Section {
+    /** The tag that identifies this section. */
+    tag: string;
+    /** The ordered list of rooms belonging to this section. */
+    rooms: Room[];
+}
+
+/**
+ * A synthetic tag used to represent the "Chats" section, which contains
+ * every room that does not belong to any other explicit tag section.
+ */
+export const CHATS_TAG = "chats";
+
+/**
+ * Manages an ordered collection of {@link RoomSkipList}s, one per tag section,
+ * and exposes a unified API for seeding, mutating, and querying the room list.
+ *
+ * Each section is backed by a {@link RoomSkipList} that keeps rooms sorted
+ * according to the active {@link Sorter} and filtered by the section-specific
+ * {@link Filter} as well as any additional filters supplied at construction time.
+ */
+export class SectionStore {
+    /**
+     * Maps section tags to their corresponding skip lists.
+     */
+    private roomSkipListByTag: Map<string, RoomSkipList> = new Map();
+    /**
+     * Maps section tags to their corresponding tag filters, used to determine which rooms belong in which sections.
+     */
+    private filterByTag: Map<string, Filter> = new Map();
+
+    /**
+     * Defines the display order of sections.
+     */
+    private sortedTags: string[] = [DefaultTagID.Favourite, CHATS_TAG, DefaultTagID.LowPriority];
+
+    /**
+     * Creates a new `SectionStore`.
+     *
+     * @param sorter - The sorting algorithm used to order rooms within each section.
+     * @param filters - Additional filters applied on top of each section's built-in tag filter.
+     */
+    public constructor(
+        private sorter: Sorter,
+        filters: Filter[],
+    ) {
+        const tagsToExclude = this.sortedTags.filter((tag) => tag !== CHATS_TAG);
+        this.sortedTags.forEach((tag) => {
+            const filter = tag === CHATS_TAG ? new ExcludeTagsFilter(tagsToExclude) : new TagFilter(tag);
+            this.filterByTag.set(tag, filter);
+            this.roomSkipListByTag.set(tag, new RoomSkipList(sorter, [filter, ...filters]));
+        });
+    }
+
+    /**
+     * Whether every section's underlying skip list has been seeded and is ready
+     * to serve room data. Returns `false` if any section has not yet been initialized.
+     */
+    public get initialized(): boolean {
+        return this.sortedTags.every((tag) => this.roomSkipListByTag.get(tag)?.initialized);
+    }
+
+    /**
+     * Seeds all section skip lists with an initial set of rooms.
+     * Each room is placed into whichever sections its tags qualify it for.
+     * Must be called before any mutation methods.
+     *
+     * @param rooms - The full list of rooms to seed the store with.
+     */
+    public seed(rooms: Room[]): void {
+        console.log("Seeding section store with rooms", rooms);
+        this.runOnAllList((list) => list.seed(rooms));
+    }
+
+    /**
+     * Replaces the active sorter and rebuilds all section skip lists from scratch.
+     *
+     * @param sorter - The new sorting algorithm to use.
+     * @param rooms - The full list of rooms used to re-seed the store after the sorter change.
+     */
+    public useNewSorter(sorter: Sorter, rooms: Room[]): void {
+        this.roomSkipListByTag.forEach((skipList) => skipList.useNewSorter(sorter, rooms));
+    }
+
+    /**
+     * The currently active sorting algorithm.
+     */
+    public get activeSortAlgorithm(): SortingAlgorithm {
+        return this.sorter.type;
+    }
+
+    /**
+     * Re-evaluates the active space membership for every room node across all
+     * section skip lists. Should be called whenever the active space changes so
+     * that space-filtered queries return up-to-date results.
+     */
+    public calculateActiveSpaceForNodes(): void {
+        this.runOnAllList((list) => list.calculateActiveSpaceForNodes());
+    }
+
+    /**
+     * Inserts a newly joined room into all relevant section skip lists.
+     * Throws if the room is already present in any skip list.
+     *
+     * @param room - The room to add.
+     */
+    public addNewRoom(room: Room): void {
+        this.runOnAllList((list) => list.addNewRoom(room));
+    }
+
+    /**
+     * Removes a room from all section skip lists.
+     * Has no effect on sections that do not contain the room.
+     *
+     * @param room - The room to remove.
+     */
+    public removeRoom(room: Room): void {
+        this.runOnAllList((list) => list.removeRoom(room));
+    }
+
+    /**
+     * Re-inserts a room into its correct sorted position across all section skip
+     * lists. Use this when a room's sort key has changed (e.g. a new message was
+     * received) so that it is repositioned without a full rebuild.
+     *
+     * @param room - The room to re-insert.
+     */
+    public reInsertRoom(room: Room): void {
+        this.runOnAllList((list) => list.reInsertRoom(room));
+    }
+
+    // TODO incorrect implementation
+    // Rooms are not sorted across sections, but rather within each section.
+    public getSortedRooms(): Room[] {
+        return this.sortedTags.map((tag) => Array.from(this.roomSkipListByTag.get(tag) || [])).flat();
+    }
+
+    /**
+     * Returns one {@link Section} per tag, each containing the rooms that belong
+     * to that section and are part of the currently active space. Optionally
+     * further restricts each section's rooms to those matching the given filter keys.
+     *
+     * @param filterKeys - An optional list of {@link FilterKey}s used to narrow
+     *   the rooms returned within each section (e.g. only unread or mention rooms).
+     * @returns An array of sections in display order: Favourites, All Chats, Low Priority.
+     */
+    public getSections(filterKeys?: FilterKey[]): Section[] {
+        return this.sortedTags.map((tag) => {
+            const filters = filterBoolean([this.filterByTag.get(tag)?.key, ...(filterKeys || [])]);
+
+            return {
+                tag,
+                rooms: Array.from(this.roomSkipListByTag.get(tag)?.getRoomsInActiveSpace(filters) || []),
+            };
+        });
+    }
+
+    /**
+     * Runs the provided callback on all the skip lists
+     * @param cb The callback to run on all the skip lists
+     */
+    private runOnAllList(cb: (list: RoomSkipList) => void): void {
+        this.sortedTags.forEach((tag) => {
+            const skipList = this.roomSkipListByTag.get(tag);
+            if (skipList) cb(skipList);
+        });
+    }
+}