feat(sdk): Add pagination loading indicator as a virtual timeline item

Author: jplatte

bindings/matrix-sdk-ffi/src/timeline.rs

@@ -159,6 +159,7 @@ impl TimelineItem {
                 Some(VirtualTimelineItem::DayDivider { year: *year, month: *month, day: *day })
             }
             Item::Virtual(VItem::ReadMarker) => Some(VirtualTimelineItem::ReadMarker),
+            Item::Virtual(VItem::LoadingIndicator) => Some(VirtualTimelineItem::LoadingIndicator),
             Item::Event(_) => None,
         }
     }
@@ -589,8 +590,12 @@ pub enum VirtualTimelineItem {
         /// A value between 1 and 31.
         day: u32,
     },
+
     /// The user's own read marker.
     ReadMarker,
+
+    /// A loading indicator for a pagination request.
+    LoadingIndicator,
 }
 
 #[extension_trait]

crates/matrix-sdk/src/room/timeline/event_handler.rs

@@ -523,31 +523,39 @@ impl<'a, 'i> TimelineEventHandler<'a, 'i> {
 
                 match position {
                     TimelineItemPosition::Start => {
+                        // If there is a loading indicator at the top, check for / insert the day
+                        // divider at position 1 and the new event at 2 rather than 0 and 1.
+                        let offset =
+                            match self.timeline_items.first().and_then(|item| item.as_virtual()) {
+                                Some(VirtualTimelineItem::LoadingIndicator) => 1,
+                                _ => 0,
+                            };
+
                         // Check if the earliest day divider has the same date as this event.
                         if let Some(VirtualTimelineItem::DayDivider { year, month, day }) =
-                            self.timeline_items.get(0).and_then(|item| item.as_virtual())
+                            self.timeline_items.get(offset).and_then(|item| item.as_virtual())
                         {
                             if let Some(day_divider_item) = maybe_create_day_divider_from_ymd(
                                 (*year, *month, *day),
                                 timestamp_to_ymd(*origin_server_ts),
                             ) {
                                 self.timeline_items.insert_cloned(
-                                    0,
+                                    offset,
                                     Arc::new(TimelineItem::Virtual(day_divider_item)),
                                 );
                             }
                         } else {
                             // The list must always start with a day divider.
                             let (year, month, day) = timestamp_to_ymd(*origin_server_ts);
                             self.timeline_items.insert_cloned(
-                                0,
+                                offset,
                                 Arc::new(TimelineItem::Virtual(VirtualTimelineItem::day_divider(
                                     year, month, day,
                                 ))),
                             );
                         }
 
-                        self.timeline_items.insert_cloned(1, item)
+                        self.timeline_items.insert_cloned(offset + 1, item)
                     }
                     TimelineItemPosition::End => {
                         // Check if the latest event has the same date as this event.

crates/matrix-sdk/src/room/timeline/inner.rs

@@ -145,6 +145,28 @@ impl TimelineInner {
         }
     }
 
+    #[instrument(skip_all)]
+    pub(super) fn add_loading_indicator(&self) {
+        let mut lock = self.items.lock_mut();
+        if lock.first().map_or(false, |item| item.is_loading_indicator()) {
+            warn!("There is already a loading indicator");
+            return;
+        }
+
+        lock.insert_cloned(0, Arc::new(TimelineItem::loading_indicator()));
+    }
+
+    #[instrument(skip_all)]
+    pub(super) fn remove_loading_indicator(&self) {
+        let mut lock = self.items.lock_mut();
+        if !lock.first().map_or(false, |item| item.is_loading_indicator()) {
+            warn!("There is no loading indicator");
+            return;
+        }
+
+        lock.remove(0);
+    }
+
     pub(super) async fn handle_fully_read(&self, raw: Raw<FullyReadEvent>) {
         let fully_read_event = match raw.deserialize() {
             Ok(ev) => ev.content.event_id,

crates/matrix-sdk/src/room/timeline/mod.rs

@@ -167,6 +167,7 @@ impl Timeline {
     #[instrument(skip(self), fields(room_id = %self.room.room_id()))]
     pub async fn paginate_backwards(&self, limit: UInt) -> Result<PaginationOutcome> {
         let mut start_lock = self.start_token.lock().await;
+        self.inner.add_loading_indicator();
         let messages = self
             .room
             .messages(assign!(MessagesOptions::backward(), {
@@ -181,6 +182,7 @@ impl Timeline {
             num_updates += self.inner.handle_back_paginated_event(room_ev, own_user_id).await;
         }
 
+        self.inner.remove_loading_indicator();
         let outcome = PaginationOutcome { more_messages: messages.end.is_some(), num_updates };
         *start_lock = messages.end;
 
@@ -327,6 +329,14 @@ impl TimelineItem {
             _ => None,
         }
     }
+
+    fn loading_indicator() -> Self {
+        Self::Virtual(VirtualTimelineItem::LoadingIndicator)
+    }
+
+    fn is_loading_indicator(&self) -> bool {
+        matches!(self, Self::Virtual(VirtualTimelineItem::LoadingIndicator))
+    }
 }
 
 /// The result of a successful pagination request.

crates/matrix-sdk/src/room/timeline/virtual_item.rs

@@ -28,8 +28,12 @@ pub enum VirtualTimelineItem {
         /// A value between 1 and 31.
         day: u32,
     },
+
     /// The user's own read marker.
     ReadMarker,
+
+    /// A loading indicator for a pagination request.
+    LoadingIndicator,
 }
 
 impl VirtualTimelineItem {

crates/matrix-sdk/tests/integration/room/timeline.rs

@@ -261,10 +261,18 @@ async fn back_pagination() {
 
     timeline.paginate_backwards(uint!(10)).await.unwrap();
 
-    let _day_divider = assert_matches!(
+    let loading = assert_matches!(
         timeline_stream.next().await,
         Some(VecDiff::Push { value }) => value
     );
+    assert_matches!(loading.as_virtual().unwrap(), VirtualTimelineItem::LoadingIndicator);
+
+    let day_divider = assert_matches!(
+        timeline_stream.next().await,
+        Some(VecDiff::Push { value }) => value
+    );
+    assert_matches!(day_divider.as_virtual().unwrap(), VirtualTimelineItem::DayDivider { .. });
+
     let message = assert_matches!(
         timeline_stream.next().await,
         Some(VecDiff::Push { value }) => value
@@ -278,14 +286,17 @@ async fn back_pagination() {
 
     let message = assert_matches!(
         timeline_stream.next().await,
-        Some(VecDiff::InsertAt { index: 1, value }) => value
+        Some(VecDiff::InsertAt { index: 2, value }) => value
     );
     let msg = assert_matches!(
         message.as_event().unwrap().content(),
         TimelineItemContent::Message(msg) => msg
     );
     let text = assert_matches!(msg.msgtype(), MessageType::Text(text) => text);
     assert_eq!(text.body, "the world is big");
+
+    // Removal of the loading indicator
+    assert_matches!(timeline_stream.next().await, Some(VecDiff::RemoveAt { index: 0 }));
 }
 
 #[async_test]