1//! A list element that can be used to render a large number of differently sized elements
   2//! efficiently. Clients of this API need to ensure that elements outside of the scrolled
   3//! area do not change their height for this element to function correctly. If your elements
   4//! do change height, notify the list element via [`ListState::splice`] or [`ListState::reset`].
   5//! In order to minimize re-renders, this element's state is stored intrusively
   6//! on your own views, so that your code can coordinate directly with the list element's cached state.
   7//!
   8//! If all of your elements are the same height, see [`crate::UniformList`] for a simpler API
   9
  10use crate::{
  11    AnyElement, App, AvailableSpace, Bounds, ContentMask, DispatchPhase, Edges, Element, EntityId,
  12    FocusHandle, GlobalElementId, Hitbox, HitboxBehavior, InspectorElementId, IntoElement,
  13    Overflow, Pixels, Point, ScrollDelta, ScrollWheelEvent, Size, Style, StyleRefinement, Styled,
  14    Window, point, px, size,
  15};
  16use collections::VecDeque;
  17use refineable::Refineable as _;
  18use std::{cell::RefCell, ops::Range, rc::Rc};
  19use sum_tree::{Bias, Dimensions, SumTree};
  20
  21type RenderItemFn = dyn FnMut(usize, &mut Window, &mut App) -> AnyElement + 'static;
  22
  23/// Construct a new list element
  24pub fn list(
  25    state: ListState,
  26    render_item: impl FnMut(usize, &mut Window, &mut App) -> AnyElement + 'static,
  27) -> List {
  28    List {
  29        state,
  30        render_item: Box::new(render_item),
  31        style: StyleRefinement::default(),
  32        sizing_behavior: ListSizingBehavior::default(),
  33    }
  34}
  35
  36/// A list element
  37pub struct List {
  38    state: ListState,
  39    render_item: Box<RenderItemFn>,
  40    style: StyleRefinement,
  41    sizing_behavior: ListSizingBehavior,
  42}
  43
  44impl List {
  45    /// Set the sizing behavior for the list.
  46    pub fn with_sizing_behavior(mut self, behavior: ListSizingBehavior) -> Self {
  47        self.sizing_behavior = behavior;
  48        self
  49    }
  50}
  51
  52/// The list state that views must hold on behalf of the list element.
  53#[derive(Clone)]
  54pub struct ListState(Rc<RefCell<StateInner>>);
  55
  56impl std::fmt::Debug for ListState {
  57    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
  58        f.write_str("ListState")
  59    }
  60}
  61
  62struct StateInner {
  63    last_layout_bounds: Option<Bounds<Pixels>>,
  64    last_padding: Option<Edges<Pixels>>,
  65    items: SumTree<ListItem>,
  66    logical_scroll_top: Option<ListOffset>,
  67    alignment: ListAlignment,
  68    overdraw: Pixels,
  69    reset: bool,
  70    #[allow(clippy::type_complexity)]
  71    scroll_handler: Option<Box<dyn FnMut(&ListScrollEvent, &mut Window, &mut App)>>,
  72    scrollbar_drag_start_height: Option<Pixels>,
  73    measuring_behavior: ListMeasuringBehavior,
  74    pending_scroll: Option<PendingScrollFraction>,
  75    follow_state: FollowState,
  76}
  77
  78/// Keeps track of a fractional scroll position within an item for restoration
  79/// after remeasurement.
  80struct PendingScrollFraction {
  81    /// The index of the item to scroll within.
  82    item_ix: usize,
  83    /// Fractional offset (0.0 to 1.0) within the item's height.
  84    fraction: f32,
  85}
  86
  87/// Controls whether the list automatically follows new content at the end.
  88#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
  89pub enum FollowMode {
  90    /// Normal scrolling — no automatic following.
  91    #[default]
  92    Normal,
  93    /// The list should auto-scroll along with the tail, when scrolled to bottom.
  94    Tail,
  95}
  96
  97#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
  98enum FollowState {
  99    #[default]
 100    Normal,
 101    Tail {
 102        is_following: bool,
 103    },
 104}
 105
 106impl FollowState {
 107    fn is_following(&self) -> bool {
 108        matches!(self, FollowState::Tail { is_following: true })
 109    }
 110
 111    fn has_stopped_following(&self) -> bool {
 112        matches!(
 113            self,
 114            FollowState::Tail {
 115                is_following: false
 116            }
 117        )
 118    }
 119
 120    fn start_following(&mut self) {
 121        if let FollowState::Tail {
 122            is_following: false,
 123        } = self
 124        {
 125            *self = FollowState::Tail { is_following: true };
 126        }
 127    }
 128}
 129
 130/// Whether the list is scrolling from top to bottom or bottom to top.
 131#[derive(Clone, Copy, Debug, Eq, PartialEq)]
 132pub enum ListAlignment {
 133    /// The list is scrolling from top to bottom, like most lists.
 134    Top,
 135    /// The list is scrolling from bottom to top, like a chat log.
 136    Bottom,
 137}
 138
 139/// A scroll event that has been converted to be in terms of the list's items.
 140pub struct ListScrollEvent {
 141    /// The range of items currently visible in the list, after applying the scroll event.
 142    pub visible_range: Range<usize>,
 143
 144    /// The number of items that are currently visible in the list, after applying the scroll event.
 145    pub count: usize,
 146
 147    /// Whether the list has been scrolled.
 148    pub is_scrolled: bool,
 149
 150    /// Whether the list is currently in follow-tail mode (auto-scrolling to end).
 151    pub is_following_tail: bool,
 152}
 153
 154/// The sizing behavior to apply during layout.
 155#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
 156pub enum ListSizingBehavior {
 157    /// The list should calculate its size based on the size of its items.
 158    Infer,
 159    /// The list should not calculate a fixed size.
 160    #[default]
 161    Auto,
 162}
 163
 164/// The measuring behavior to apply during layout.
 165#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
 166pub enum ListMeasuringBehavior {
 167    /// Measure all items in the list.
 168    /// Note: This can be expensive for the first frame in a large list.
 169    Measure(bool),
 170    /// Only measure visible items
 171    #[default]
 172    Visible,
 173}
 174
 175impl ListMeasuringBehavior {
 176    fn reset(&mut self) {
 177        match self {
 178            ListMeasuringBehavior::Measure(has_measured) => *has_measured = false,
 179            ListMeasuringBehavior::Visible => {}
 180        }
 181    }
 182}
 183
 184/// The horizontal sizing behavior to apply during layout.
 185#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
 186pub enum ListHorizontalSizingBehavior {
 187    /// List items' width can never exceed the width of the list.
 188    #[default]
 189    FitList,
 190    /// List items' width may go over the width of the list, if any item is wider.
 191    Unconstrained,
 192}
 193
 194struct LayoutItemsResponse {
 195    max_item_width: Pixels,
 196    scroll_top: ListOffset,
 197    item_layouts: VecDeque<ItemLayout>,
 198}
 199
 200struct ItemLayout {
 201    index: usize,
 202    element: AnyElement,
 203    size: Size<Pixels>,
 204}
 205
 206/// Frame state used by the [List] element after layout.
 207pub struct ListPrepaintState {
 208    hitbox: Hitbox,
 209    layout: LayoutItemsResponse,
 210}
 211
 212#[derive(Clone)]
 213enum ListItem {
 214    Unmeasured {
 215        size_hint: Option<Size<Pixels>>,
 216        focus_handle: Option<FocusHandle>,
 217    },
 218    Measured {
 219        size: Size<Pixels>,
 220        focus_handle: Option<FocusHandle>,
 221    },
 222}
 223
 224impl ListItem {
 225    fn size(&self) -> Option<Size<Pixels>> {
 226        if let ListItem::Measured { size, .. } = self {
 227            Some(*size)
 228        } else {
 229            None
 230        }
 231    }
 232
 233    fn size_hint(&self) -> Option<Size<Pixels>> {
 234        match self {
 235            ListItem::Measured { size, .. } => Some(*size),
 236            ListItem::Unmeasured { size_hint, .. } => *size_hint,
 237        }
 238    }
 239
 240    fn focus_handle(&self) -> Option<FocusHandle> {
 241        match self {
 242            ListItem::Unmeasured { focus_handle, .. } | ListItem::Measured { focus_handle, .. } => {
 243                focus_handle.clone()
 244            }
 245        }
 246    }
 247
 248    fn contains_focused(&self, window: &Window, cx: &App) -> bool {
 249        match self {
 250            ListItem::Unmeasured { focus_handle, .. } | ListItem::Measured { focus_handle, .. } => {
 251                focus_handle
 252                    .as_ref()
 253                    .is_some_and(|handle| handle.contains_focused(window, cx))
 254            }
 255        }
 256    }
 257}
 258
 259#[derive(Clone, Debug, Default, PartialEq)]
 260struct ListItemSummary {
 261    count: usize,
 262    rendered_count: usize,
 263    unrendered_count: usize,
 264    height: Pixels,
 265    has_focus_handles: bool,
 266}
 267
 268#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord)]
 269struct Count(usize);
 270
 271#[derive(Clone, Debug, Default)]
 272struct Height(Pixels);
 273
 274impl ListState {
 275    /// Construct a new list state, for storage on a view.
 276    ///
 277    /// The overdraw parameter controls how much extra space is rendered
 278    /// above and below the visible area. Elements within this area will
 279    /// be measured even though they are not visible. This can help ensure
 280    /// that the list doesn't flicker or pop in when scrolling.
 281    pub fn new(item_count: usize, alignment: ListAlignment, overdraw: Pixels) -> Self {
 282        let this = Self(Rc::new(RefCell::new(StateInner {
 283            last_layout_bounds: None,
 284            last_padding: None,
 285            items: SumTree::default(),
 286            logical_scroll_top: None,
 287            alignment,
 288            overdraw,
 289            scroll_handler: None,
 290            reset: false,
 291            scrollbar_drag_start_height: None,
 292            measuring_behavior: ListMeasuringBehavior::default(),
 293            pending_scroll: None,
 294            follow_state: FollowState::default(),
 295        })));
 296        this.splice(0..0, item_count);
 297        this
 298    }
 299
 300    /// Set the list to measure all items in the list in the first layout phase.
 301    ///
 302    /// This is useful for ensuring that the scrollbar size is correct instead of based on only rendered elements.
 303    pub fn measure_all(self) -> Self {
 304        self.0.borrow_mut().measuring_behavior = ListMeasuringBehavior::Measure(false);
 305        self
 306    }
 307
 308    /// Reset this instantiation of the list state.
 309    ///
 310    /// Note that this will cause scroll events to be dropped until the next paint.
 311    pub fn reset(&self, element_count: usize) {
 312        let old_count = {
 313            let state = &mut *self.0.borrow_mut();
 314            state.reset = true;
 315            state.measuring_behavior.reset();
 316            state.logical_scroll_top = None;
 317            state.scrollbar_drag_start_height = None;
 318            state.items.summary().count
 319        };
 320
 321        self.splice(0..old_count, element_count);
 322    }
 323
 324    /// Remeasure all items while preserving proportional scroll position.
 325    ///
 326    /// Use this when item heights may have changed (e.g., font size changes)
 327    /// but the number and identity of items remains the same.
 328    pub fn remeasure(&self) {
 329        let count = self.item_count();
 330        self.remeasure_items(0..count);
 331    }
 332
 333    /// Mark items in `range` as needing remeasurement while preserving
 334    /// the current scroll position. Unlike [`Self::splice`], this does
 335    /// not change the number of items or blow away `logical_scroll_top`.
 336    ///
 337    /// Use this when an item's content has changed and its rendered
 338    /// height may be different (e.g., streaming text, tool results
 339    /// loading), but the item itself still exists at the same index.
 340    pub fn remeasure_items(&self, range: Range<usize>) {
 341        let state = &mut *self.0.borrow_mut();
 342
 343        // If the scroll-top item falls within the remeasured range,
 344        // store a fractional offset so the layout can restore the
 345        // proportional scroll position after the item is re-rendered
 346        // at its new height.
 347        if let Some(scroll_top) = state.logical_scroll_top {
 348            if range.contains(&scroll_top.item_ix) {
 349                let mut cursor = state.items.cursor::<Count>(());
 350                cursor.seek(&Count(scroll_top.item_ix), Bias::Right);
 351
 352                if let Some(item) = cursor.item() {
 353                    if let Some(size) = item.size() {
 354                        let fraction = if size.height.0 > 0.0 {
 355                            (scroll_top.offset_in_item.0 / size.height.0).clamp(0.0, 1.0)
 356                        } else {
 357                            0.0
 358                        };
 359
 360                        state.pending_scroll = Some(PendingScrollFraction {
 361                            item_ix: scroll_top.item_ix,
 362                            fraction,
 363                        });
 364                    }
 365                }
 366            }
 367        }
 368
 369        // Rebuild the tree, replacing items in the range with
 370        // Unmeasured copies that keep their focus handles.
 371        let new_items = {
 372            let mut cursor = state.items.cursor::<Count>(());
 373            let mut new_items = cursor.slice(&Count(range.start), Bias::Right);
 374            let invalidated = cursor.slice(&Count(range.end), Bias::Right);
 375            new_items.extend(
 376                invalidated.iter().map(|item| ListItem::Unmeasured {
 377                    size_hint: item.size_hint(),
 378                    focus_handle: item.focus_handle(),
 379                }),
 380                (),
 381            );
 382            new_items.append(cursor.suffix(), ());
 383            new_items
 384        };
 385        state.items = new_items;
 386        state.measuring_behavior.reset();
 387    }
 388
 389    /// The number of items in this list.
 390    pub fn item_count(&self) -> usize {
 391        self.0.borrow().items.summary().count
 392    }
 393
 394    /// Inform the list state that the items in `old_range` have been replaced
 395    /// by `count` new items that must be recalculated.
 396    pub fn splice(&self, old_range: Range<usize>, count: usize) {
 397        self.splice_focusable(old_range, (0..count).map(|_| None))
 398    }
 399
 400    /// Register with the list state that the items in `old_range` have been replaced
 401    /// by new items. As opposed to [`Self::splice`], this method allows an iterator of optional focus handles
 402    /// to be supplied to properly integrate with items in the list that can be focused. If a focused item
 403    /// is scrolled out of view, the list will continue to render it to allow keyboard interaction.
 404    pub fn splice_focusable(
 405        &self,
 406        old_range: Range<usize>,
 407        focus_handles: impl IntoIterator<Item = Option<FocusHandle>>,
 408    ) {
 409        let state = &mut *self.0.borrow_mut();
 410
 411        let mut old_items = state.items.cursor::<Count>(());
 412        let mut new_items = old_items.slice(&Count(old_range.start), Bias::Right);
 413        old_items.seek_forward(&Count(old_range.end), Bias::Right);
 414
 415        let mut spliced_count = 0;
 416        new_items.extend(
 417            focus_handles.into_iter().map(|focus_handle| {
 418                spliced_count += 1;
 419                ListItem::Unmeasured {
 420                    size_hint: None,
 421                    focus_handle,
 422                }
 423            }),
 424            (),
 425        );
 426        new_items.append(old_items.suffix(), ());
 427        drop(old_items);
 428        state.items = new_items;
 429
 430        if let Some(ListOffset {
 431            item_ix,
 432            offset_in_item,
 433        }) = state.logical_scroll_top.as_mut()
 434        {
 435            if old_range.contains(item_ix) {
 436                *item_ix = old_range.start;
 437                *offset_in_item = px(0.);
 438            } else if old_range.end <= *item_ix {
 439                *item_ix = *item_ix - (old_range.end - old_range.start) + spliced_count;
 440            }
 441        }
 442    }
 443
 444    /// Set a handler that will be called when the list is scrolled.
 445    pub fn set_scroll_handler(
 446        &self,
 447        handler: impl FnMut(&ListScrollEvent, &mut Window, &mut App) + 'static,
 448    ) {
 449        self.0.borrow_mut().scroll_handler = Some(Box::new(handler))
 450    }
 451
 452    /// Get the current scroll offset, in terms of the list's items.
 453    pub fn logical_scroll_top(&self) -> ListOffset {
 454        self.0.borrow().logical_scroll_top()
 455    }
 456
 457    /// Scroll the list by the given offset
 458    pub fn scroll_by(&self, distance: Pixels) {
 459        if distance == px(0.) {
 460            return;
 461        }
 462
 463        let current_offset = self.logical_scroll_top();
 464        let state = &mut *self.0.borrow_mut();
 465        let mut cursor = state.items.cursor::<ListItemSummary>(());
 466        cursor.seek(&Count(current_offset.item_ix), Bias::Right);
 467
 468        let start_pixel_offset = cursor.start().height + current_offset.offset_in_item;
 469        let new_pixel_offset = (start_pixel_offset + distance).max(px(0.));
 470        if new_pixel_offset > start_pixel_offset {
 471            cursor.seek_forward(&Height(new_pixel_offset), Bias::Right);
 472        } else {
 473            cursor.seek(&Height(new_pixel_offset), Bias::Right);
 474        }
 475
 476        state.logical_scroll_top = Some(ListOffset {
 477            item_ix: cursor.start().count,
 478            offset_in_item: new_pixel_offset - cursor.start().height,
 479        });
 480    }
 481
 482    /// Scroll the list to the very end (past the last item).
 483    ///
 484    /// Unlike [`scroll_to_reveal_item`], this uses the total item count as the
 485    /// anchor, so the list's layout pass will walk backwards from the end and
 486    /// always show the bottom of the last item — even when that item is still
 487    /// growing (e.g. during streaming).
 488    pub fn scroll_to_end(&self) {
 489        let state = &mut *self.0.borrow_mut();
 490        let item_count = state.items.summary().count;
 491        state.logical_scroll_top = Some(ListOffset {
 492            item_ix: item_count,
 493            offset_in_item: px(0.),
 494        });
 495    }
 496
 497    /// Set the follow mode for the list. In `Tail` mode, the list
 498    /// will auto-scroll to the end and re-engage after the user
 499    /// scrolls back to the bottom. In `Normal` mode, no automatic
 500    /// following occurs.
 501    pub fn set_follow_mode(&self, mode: FollowMode) {
 502        let state = &mut *self.0.borrow_mut();
 503
 504        match mode {
 505            FollowMode::Normal => {
 506                state.follow_state = FollowState::Normal;
 507            }
 508            FollowMode::Tail => {
 509                state.follow_state = FollowState::Tail { is_following: true };
 510                if matches!(mode, FollowMode::Tail) {
 511                    let item_count = state.items.summary().count;
 512                    state.logical_scroll_top = Some(ListOffset {
 513                        item_ix: item_count,
 514                        offset_in_item: px(0.),
 515                    });
 516                }
 517            }
 518        }
 519    }
 520
 521    /// Returns whether the list is currently actively following the
 522    /// tail (snapping to the end on each layout).
 523    pub fn is_following_tail(&self) -> bool {
 524        matches!(
 525            self.0.borrow().follow_state,
 526            FollowState::Tail { is_following: true }
 527        )
 528    }
 529
 530    /// Returns whether the list is scrolled to the bottom
 531    pub fn is_at_bottom(&self) -> bool {
 532        let current_offset = self.scroll_px_offset_for_scrollbar().y.abs();
 533        let max_offset = self.max_offset_for_scrollbar().y;
 534        current_offset >= max_offset - px(1.0)
 535    }
 536
 537    /// Scroll the list to the given offset
 538    pub fn scroll_to(&self, mut scroll_top: ListOffset) {
 539        let state = &mut *self.0.borrow_mut();
 540        let item_count = state.items.summary().count;
 541        if scroll_top.item_ix >= item_count {
 542            scroll_top.item_ix = item_count;
 543            scroll_top.offset_in_item = px(0.);
 544        }
 545
 546        state.logical_scroll_top = Some(scroll_top);
 547    }
 548
 549    /// Scroll the list to the given item, such that the item is fully visible.
 550    pub fn scroll_to_reveal_item(&self, ix: usize) {
 551        let state = &mut *self.0.borrow_mut();
 552
 553        let mut scroll_top = state.logical_scroll_top();
 554        let height = state
 555            .last_layout_bounds
 556            .map_or(px(0.), |bounds| bounds.size.height);
 557        let padding = state.last_padding.unwrap_or_default();
 558
 559        if ix <= scroll_top.item_ix {
 560            scroll_top.item_ix = ix;
 561            scroll_top.offset_in_item = px(0.);
 562        } else {
 563            let mut cursor = state.items.cursor::<ListItemSummary>(());
 564            cursor.seek(&Count(ix + 1), Bias::Right);
 565            let bottom = cursor.start().height + padding.top;
 566            let goal_top = px(0.).max(bottom - height + padding.bottom);
 567
 568            cursor.seek(&Height(goal_top), Bias::Left);
 569            let start_ix = cursor.start().count;
 570            let start_item_top = cursor.start().height;
 571
 572            if start_ix >= scroll_top.item_ix {
 573                scroll_top.item_ix = start_ix;
 574                scroll_top.offset_in_item = goal_top - start_item_top;
 575            }
 576        }
 577
 578        state.logical_scroll_top = Some(scroll_top);
 579    }
 580
 581    /// Get the bounds for the given item in window coordinates, if it's
 582    /// been rendered.
 583    pub fn bounds_for_item(&self, ix: usize) -> Option<Bounds<Pixels>> {
 584        let state = &*self.0.borrow();
 585
 586        let bounds = state.last_layout_bounds.unwrap_or_default();
 587        let scroll_top = state.logical_scroll_top();
 588        if ix < scroll_top.item_ix {
 589            return None;
 590        }
 591
 592        let mut cursor = state.items.cursor::<Dimensions<Count, Height>>(());
 593        cursor.seek(&Count(scroll_top.item_ix), Bias::Right);
 594
 595        let scroll_top = cursor.start().1.0 + scroll_top.offset_in_item;
 596
 597        cursor.seek_forward(&Count(ix), Bias::Right);
 598        if let Some(&ListItem::Measured { size, .. }) = cursor.item() {
 599            let &Dimensions(Count(count), Height(top), _) = cursor.start();
 600            if count == ix {
 601                let top = bounds.top() + top - scroll_top;
 602                return Some(Bounds::from_corners(
 603                    point(bounds.left(), top),
 604                    point(bounds.right(), top + size.height),
 605                ));
 606            }
 607        }
 608        None
 609    }
 610
 611    /// Call this method when the user starts dragging the scrollbar.
 612    ///
 613    /// This will prevent the height reported to the scrollbar from changing during the drag
 614    /// as items in the overdraw get measured, and help offset scroll position changes accordingly.
 615    pub fn scrollbar_drag_started(&self) {
 616        let mut state = self.0.borrow_mut();
 617        state.scrollbar_drag_start_height = Some(state.items.summary().height);
 618    }
 619
 620    /// Called when the user stops dragging the scrollbar.
 621    ///
 622    /// See `scrollbar_drag_started`.
 623    pub fn scrollbar_drag_ended(&self) {
 624        self.0.borrow_mut().scrollbar_drag_start_height.take();
 625    }
 626
 627    /// Set the offset from the scrollbar
 628    pub fn set_offset_from_scrollbar(&self, point: Point<Pixels>) {
 629        self.0.borrow_mut().set_offset_from_scrollbar(point);
 630    }
 631
 632    /// Returns the maximum scroll offset according to the items we have measured.
 633    /// This value remains constant while dragging to prevent the scrollbar from moving away unexpectedly.
 634    pub fn max_offset_for_scrollbar(&self) -> Point<Pixels> {
 635        let state = self.0.borrow();
 636        point(Pixels::ZERO, state.max_scroll_offset())
 637    }
 638
 639    /// Returns the current scroll offset adjusted for the scrollbar
 640    pub fn scroll_px_offset_for_scrollbar(&self) -> Point<Pixels> {
 641        let state = &self.0.borrow();
 642
 643        if state.logical_scroll_top.is_none() && state.alignment == ListAlignment::Bottom {
 644            return Point::new(px(0.), -state.max_scroll_offset());
 645        }
 646
 647        let logical_scroll_top = state.logical_scroll_top();
 648
 649        let mut cursor = state.items.cursor::<ListItemSummary>(());
 650        let summary: ListItemSummary =
 651            cursor.summary(&Count(logical_scroll_top.item_ix), Bias::Right);
 652        let content_height = state.items.summary().height;
 653        let drag_offset =
 654            // if dragging the scrollbar, we want to offset the point if the height changed
 655            content_height - state.scrollbar_drag_start_height.unwrap_or(content_height);
 656        let offset = summary.height + logical_scroll_top.offset_in_item - drag_offset;
 657
 658        Point::new(px(0.), -offset)
 659    }
 660
 661    /// Return the bounds of the viewport in pixels.
 662    pub fn viewport_bounds(&self) -> Bounds<Pixels> {
 663        self.0.borrow().last_layout_bounds.unwrap_or_default()
 664    }
 665}
 666
 667impl StateInner {
 668    fn max_scroll_offset(&self) -> Pixels {
 669        let bounds = self.last_layout_bounds.unwrap_or_default();
 670        let height = self
 671            .scrollbar_drag_start_height
 672            .unwrap_or_else(|| self.items.summary().height);
 673        (height - bounds.size.height).max(px(0.))
 674    }
 675
 676    fn visible_range(
 677        items: &SumTree<ListItem>,
 678        height: Pixels,
 679        scroll_top: &ListOffset,
 680    ) -> Range<usize> {
 681        let mut cursor = items.cursor::<ListItemSummary>(());
 682        cursor.seek(&Count(scroll_top.item_ix), Bias::Right);
 683        let start_y = cursor.start().height + scroll_top.offset_in_item;
 684        cursor.seek_forward(&Height(start_y + height), Bias::Left);
 685        scroll_top.item_ix..cursor.start().count + 1
 686    }
 687
 688    fn scroll(
 689        &mut self,
 690        scroll_top: &ListOffset,
 691        height: Pixels,
 692        delta: Point<Pixels>,
 693        current_view: EntityId,
 694        window: &mut Window,
 695        cx: &mut App,
 696    ) {
 697        // Drop scroll events after a reset, since we can't calculate
 698        // the new logical scroll top without the item heights
 699        if self.reset {
 700            return;
 701        }
 702
 703        let padding = self.last_padding.unwrap_or_default();
 704        let scroll_max =
 705            (self.items.summary().height + padding.top + padding.bottom - height).max(px(0.));
 706        let new_scroll_top = (self.scroll_top(scroll_top) - delta.y)
 707            .max(px(0.))
 708            .min(scroll_max);
 709
 710        if self.alignment == ListAlignment::Bottom && new_scroll_top == scroll_max {
 711            self.logical_scroll_top = None;
 712        } else {
 713            let (start, ..) =
 714                self.items
 715                    .find::<ListItemSummary, _>((), &Height(new_scroll_top), Bias::Right);
 716            let item_ix = start.count;
 717            let offset_in_item = new_scroll_top - start.height;
 718            self.logical_scroll_top = Some(ListOffset {
 719                item_ix,
 720                offset_in_item,
 721            });
 722        }
 723
 724        if let FollowState::Tail { is_following } = &mut self.follow_state {
 725            if delta.y > px(0.) {
 726                *is_following = false;
 727            }
 728        }
 729
 730        if let Some(handler) = self.scroll_handler.as_mut() {
 731            let visible_range = Self::visible_range(&self.items, height, scroll_top);
 732            handler(
 733                &ListScrollEvent {
 734                    visible_range,
 735                    count: self.items.summary().count,
 736                    is_scrolled: self.logical_scroll_top.is_some(),
 737                    is_following_tail: matches!(
 738                        self.follow_state,
 739                        FollowState::Tail { is_following: true }
 740                    ),
 741                },
 742                window,
 743                cx,
 744            );
 745        }
 746
 747        cx.notify(current_view);
 748    }
 749
 750    fn logical_scroll_top(&self) -> ListOffset {
 751        self.logical_scroll_top
 752            .unwrap_or_else(|| match self.alignment {
 753                ListAlignment::Top => ListOffset {
 754                    item_ix: 0,
 755                    offset_in_item: px(0.),
 756                },
 757                ListAlignment::Bottom => ListOffset {
 758                    item_ix: self.items.summary().count,
 759                    offset_in_item: px(0.),
 760                },
 761            })
 762    }
 763
 764    fn scroll_top(&self, logical_scroll_top: &ListOffset) -> Pixels {
 765        let (start, ..) = self.items.find::<ListItemSummary, _>(
 766            (),
 767            &Count(logical_scroll_top.item_ix),
 768            Bias::Right,
 769        );
 770        start.height + logical_scroll_top.offset_in_item
 771    }
 772
 773    fn layout_all_items(
 774        &mut self,
 775        available_width: Pixels,
 776        render_item: &mut RenderItemFn,
 777        window: &mut Window,
 778        cx: &mut App,
 779    ) {
 780        match &mut self.measuring_behavior {
 781            ListMeasuringBehavior::Visible => {
 782                return;
 783            }
 784            ListMeasuringBehavior::Measure(has_measured) => {
 785                if *has_measured {
 786                    return;
 787                }
 788                *has_measured = true;
 789            }
 790        }
 791
 792        let mut cursor = self.items.cursor::<Count>(());
 793        let available_item_space = size(
 794            AvailableSpace::Definite(available_width),
 795            AvailableSpace::MinContent,
 796        );
 797
 798        let mut measured_items = Vec::default();
 799
 800        for (ix, item) in cursor.enumerate() {
 801            let size = item.size().unwrap_or_else(|| {
 802                let mut element = render_item(ix, window, cx);
 803                element.layout_as_root(available_item_space, window, cx)
 804            });
 805
 806            measured_items.push(ListItem::Measured {
 807                size,
 808                focus_handle: item.focus_handle(),
 809            });
 810        }
 811
 812        self.items = SumTree::from_iter(measured_items, ());
 813    }
 814
 815    fn layout_items(
 816        &mut self,
 817        available_width: Option<Pixels>,
 818        available_height: Pixels,
 819        padding: &Edges<Pixels>,
 820        render_item: &mut RenderItemFn,
 821        window: &mut Window,
 822        cx: &mut App,
 823    ) -> LayoutItemsResponse {
 824        let old_items = self.items.clone();
 825        let mut measured_items = VecDeque::new();
 826        let mut item_layouts = VecDeque::new();
 827        let mut rendered_height = padding.top;
 828        let mut max_item_width = px(0.);
 829        let mut scroll_top = self.logical_scroll_top();
 830
 831        if self.follow_state.is_following() {
 832            scroll_top = ListOffset {
 833                item_ix: self.items.summary().count,
 834                offset_in_item: px(0.),
 835            };
 836            self.logical_scroll_top = Some(scroll_top);
 837        }
 838
 839        let mut rendered_focused_item = false;
 840
 841        let available_item_space = size(
 842            available_width.map_or(AvailableSpace::MinContent, |width| {
 843                AvailableSpace::Definite(width)
 844            }),
 845            AvailableSpace::MinContent,
 846        );
 847
 848        let mut cursor = old_items.cursor::<Count>(());
 849
 850        // Render items after the scroll top, including those in the trailing overdraw
 851        cursor.seek(&Count(scroll_top.item_ix), Bias::Right);
 852        for (ix, item) in cursor.by_ref().enumerate() {
 853            let visible_height = rendered_height - scroll_top.offset_in_item;
 854            if visible_height >= available_height + self.overdraw {
 855                break;
 856            }
 857
 858            // Use the previously cached height and focus handle if available
 859            let mut size = item.size();
 860
 861            // If we're within the visible area or the height wasn't cached, render and measure the item's element
 862            if visible_height < available_height || size.is_none() {
 863                let item_index = scroll_top.item_ix + ix;
 864                let mut element = render_item(item_index, window, cx);
 865                let element_size = element.layout_as_root(available_item_space, window, cx);
 866                size = Some(element_size);
 867
 868                // If there's a pending scroll adjustment for the scroll-top
 869                // item, apply it, ensuring proportional scroll position is
 870                // maintained after re-measuring.
 871                if ix == 0 {
 872                    if let Some(pending_scroll) = self.pending_scroll.take() {
 873                        if pending_scroll.item_ix == scroll_top.item_ix {
 874                            scroll_top.offset_in_item =
 875                                Pixels(pending_scroll.fraction * element_size.height.0);
 876                            self.logical_scroll_top = Some(scroll_top);
 877                        }
 878                    }
 879                }
 880
 881                if visible_height < available_height {
 882                    item_layouts.push_back(ItemLayout {
 883                        index: item_index,
 884                        element,
 885                        size: element_size,
 886                    });
 887                    if item.contains_focused(window, cx) {
 888                        rendered_focused_item = true;
 889                    }
 890                }
 891            }
 892
 893            let size = size.unwrap();
 894            rendered_height += size.height;
 895            max_item_width = max_item_width.max(size.width);
 896            measured_items.push_back(ListItem::Measured {
 897                size,
 898                focus_handle: item.focus_handle(),
 899            });
 900        }
 901        rendered_height += padding.bottom;
 902
 903        // Prepare to start walking upward from the item at the scroll top.
 904        cursor.seek(&Count(scroll_top.item_ix), Bias::Right);
 905
 906        // If the rendered items do not fill the visible region, then adjust
 907        // the scroll top upward.
 908        if rendered_height - scroll_top.offset_in_item < available_height {
 909            while rendered_height < available_height {
 910                cursor.prev();
 911                if let Some(item) = cursor.item() {
 912                    let item_index = cursor.start().0;
 913                    let mut element = render_item(item_index, window, cx);
 914                    let element_size = element.layout_as_root(available_item_space, window, cx);
 915                    let focus_handle = item.focus_handle();
 916                    rendered_height += element_size.height;
 917                    measured_items.push_front(ListItem::Measured {
 918                        size: element_size,
 919                        focus_handle,
 920                    });
 921                    item_layouts.push_front(ItemLayout {
 922                        index: item_index,
 923                        element,
 924                        size: element_size,
 925                    });
 926                    if item.contains_focused(window, cx) {
 927                        rendered_focused_item = true;
 928                    }
 929                } else {
 930                    break;
 931                }
 932            }
 933
 934            scroll_top = ListOffset {
 935                item_ix: cursor.start().0,
 936                offset_in_item: rendered_height - available_height,
 937            };
 938
 939            match self.alignment {
 940                ListAlignment::Top => {
 941                    scroll_top.offset_in_item = scroll_top.offset_in_item.max(px(0.));
 942                    self.logical_scroll_top = Some(scroll_top);
 943                }
 944                ListAlignment::Bottom => {
 945                    scroll_top = ListOffset {
 946                        item_ix: cursor.start().0,
 947                        offset_in_item: rendered_height - available_height,
 948                    };
 949                    self.logical_scroll_top = None;
 950                }
 951            };
 952        }
 953
 954        // Measure items in the leading overdraw
 955        let mut leading_overdraw = scroll_top.offset_in_item;
 956        while leading_overdraw < self.overdraw {
 957            cursor.prev();
 958            if let Some(item) = cursor.item() {
 959                let size = if let ListItem::Measured { size, .. } = item {
 960                    *size
 961                } else {
 962                    let mut element = render_item(cursor.start().0, window, cx);
 963                    element.layout_as_root(available_item_space, window, cx)
 964                };
 965
 966                leading_overdraw += size.height;
 967                measured_items.push_front(ListItem::Measured {
 968                    size,
 969                    focus_handle: item.focus_handle(),
 970                });
 971            } else {
 972                break;
 973            }
 974        }
 975
 976        let measured_range = cursor.start().0..(cursor.start().0 + measured_items.len());
 977        let mut cursor = old_items.cursor::<Count>(());
 978        let mut new_items = cursor.slice(&Count(measured_range.start), Bias::Right);
 979        new_items.extend(measured_items, ());
 980        cursor.seek(&Count(measured_range.end), Bias::Right);
 981        new_items.append(cursor.suffix(), ());
 982        self.items = new_items;
 983
 984        // If follow_tail mode is on but the user scrolled away
 985        // (is_following is false), check whether the current scroll
 986        // position has returned to the bottom.
 987        if self.follow_state.has_stopped_following() {
 988            let padding = self.last_padding.unwrap_or_default();
 989            let total_height = self.items.summary().height + padding.top + padding.bottom;
 990            let scroll_offset = self.scroll_top(&scroll_top);
 991            if scroll_offset + available_height >= total_height - px(1.0) {
 992                self.follow_state.start_following();
 993            }
 994        }
 995
 996        // If none of the visible items are focused, check if an off-screen item is focused
 997        // and include it to be rendered after the visible items so keyboard interaction continues
 998        // to work for it.
 999        if !rendered_focused_item {
1000            let mut cursor = self
1001                .items
1002                .filter::<_, Count>((), |summary| summary.has_focus_handles);
1003            cursor.next();
1004            while let Some(item) = cursor.item() {
1005                if item.contains_focused(window, cx) {
1006                    let item_index = cursor.start().0;
1007                    let mut element = render_item(cursor.start().0, window, cx);
1008                    let size = element.layout_as_root(available_item_space, window, cx);
1009                    item_layouts.push_back(ItemLayout {
1010                        index: item_index,
1011                        element,
1012                        size,
1013                    });
1014                    break;
1015                }
1016                cursor.next();
1017            }
1018        }
1019
1020        LayoutItemsResponse {
1021            max_item_width,
1022            scroll_top,
1023            item_layouts,
1024        }
1025    }
1026
1027    fn prepaint_items(
1028        &mut self,
1029        bounds: Bounds<Pixels>,
1030        padding: Edges<Pixels>,
1031        autoscroll: bool,
1032        render_item: &mut RenderItemFn,
1033        window: &mut Window,
1034        cx: &mut App,
1035    ) -> Result<LayoutItemsResponse, ListOffset> {
1036        window.transact(|window| {
1037            match self.measuring_behavior {
1038                ListMeasuringBehavior::Measure(has_measured) if !has_measured => {
1039                    self.layout_all_items(bounds.size.width, render_item, window, cx);
1040                }
1041                _ => {}
1042            }
1043
1044            let mut layout_response = self.layout_items(
1045                Some(bounds.size.width),
1046                bounds.size.height,
1047                &padding,
1048                render_item,
1049                window,
1050                cx,
1051            );
1052
1053            // Avoid honoring autoscroll requests from elements other than our children.
1054            window.take_autoscroll();
1055
1056            // Only paint the visible items, if there is actually any space for them (taking padding into account)
1057            if bounds.size.height > padding.top + padding.bottom {
1058                let mut item_origin = bounds.origin + Point::new(px(0.), padding.top);
1059                item_origin.y -= layout_response.scroll_top.offset_in_item;
1060                for item in &mut layout_response.item_layouts {
1061                    window.with_content_mask(Some(ContentMask { bounds }), |window| {
1062                        item.element.prepaint_at(item_origin, window, cx);
1063                    });
1064
1065                    if let Some(autoscroll_bounds) = window.take_autoscroll()
1066                        && autoscroll
1067                    {
1068                        if autoscroll_bounds.top() < bounds.top() {
1069                            return Err(ListOffset {
1070                                item_ix: item.index,
1071                                offset_in_item: autoscroll_bounds.top() - item_origin.y,
1072                            });
1073                        } else if autoscroll_bounds.bottom() > bounds.bottom() {
1074                            let mut cursor = self.items.cursor::<Count>(());
1075                            cursor.seek(&Count(item.index), Bias::Right);
1076                            let mut height = bounds.size.height - padding.top - padding.bottom;
1077
1078                            // Account for the height of the element down until the autoscroll bottom.
1079                            height -= autoscroll_bounds.bottom() - item_origin.y;
1080
1081                            // Keep decreasing the scroll top until we fill all the available space.
1082                            while height > Pixels::ZERO {
1083                                cursor.prev();
1084                                let Some(item) = cursor.item() else { break };
1085
1086                                let size = item.size().unwrap_or_else(|| {
1087                                    let mut item = render_item(cursor.start().0, window, cx);
1088                                    let item_available_size =
1089                                        size(bounds.size.width.into(), AvailableSpace::MinContent);
1090                                    item.layout_as_root(item_available_size, window, cx)
1091                                });
1092                                height -= size.height;
1093                            }
1094
1095                            return Err(ListOffset {
1096                                item_ix: cursor.start().0,
1097                                offset_in_item: if height < Pixels::ZERO {
1098                                    -height
1099                                } else {
1100                                    Pixels::ZERO
1101                                },
1102                            });
1103                        }
1104                    }
1105
1106                    item_origin.y += item.size.height;
1107                }
1108            } else {
1109                layout_response.item_layouts.clear();
1110            }
1111
1112            Ok(layout_response)
1113        })
1114    }
1115
1116    // Scrollbar support
1117
1118    fn set_offset_from_scrollbar(&mut self, point: Point<Pixels>) {
1119        let Some(bounds) = self.last_layout_bounds else {
1120            return;
1121        };
1122        let height = bounds.size.height;
1123
1124        let padding = self.last_padding.unwrap_or_default();
1125        let content_height = self.items.summary().height;
1126        let scroll_max = (content_height + padding.top + padding.bottom - height).max(px(0.));
1127        let drag_offset =
1128            // if dragging the scrollbar, we want to offset the point if the height changed
1129            content_height - self.scrollbar_drag_start_height.unwrap_or(content_height);
1130        let new_scroll_top = (point.y - drag_offset).abs().max(px(0.)).min(scroll_max);
1131
1132        self.follow_state = FollowState::Normal;
1133
1134        if self.alignment == ListAlignment::Bottom && new_scroll_top == scroll_max {
1135            self.logical_scroll_top = None;
1136        } else {
1137            let (start, _, _) =
1138                self.items
1139                    .find::<ListItemSummary, _>((), &Height(new_scroll_top), Bias::Right);
1140
1141            let item_ix = start.count;
1142            let offset_in_item = new_scroll_top - start.height;
1143            self.logical_scroll_top = Some(ListOffset {
1144                item_ix,
1145                offset_in_item,
1146            });
1147        }
1148    }
1149}
1150
1151impl std::fmt::Debug for ListItem {
1152    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1153        match self {
1154            Self::Unmeasured { .. } => write!(f, "Unrendered"),
1155            Self::Measured { size, .. } => f.debug_struct("Rendered").field("size", size).finish(),
1156        }
1157    }
1158}
1159
1160/// An offset into the list's items, in terms of the item index and the number
1161/// of pixels off the top left of the item.
1162#[derive(Debug, Clone, Copy, Default)]
1163pub struct ListOffset {
1164    /// The index of an item in the list
1165    pub item_ix: usize,
1166    /// The number of pixels to offset from the item index.
1167    pub offset_in_item: Pixels,
1168}
1169
1170impl Element for List {
1171    type RequestLayoutState = ();
1172    type PrepaintState = ListPrepaintState;
1173
1174    fn id(&self) -> Option<crate::ElementId> {
1175        None
1176    }
1177
1178    fn source_location(&self) -> Option<&'static core::panic::Location<'static>> {
1179        None
1180    }
1181
1182    fn request_layout(
1183        &mut self,
1184        _id: Option<&GlobalElementId>,
1185        _inspector_id: Option<&InspectorElementId>,
1186        window: &mut Window,
1187        cx: &mut App,
1188    ) -> (crate::LayoutId, Self::RequestLayoutState) {
1189        let layout_id = match self.sizing_behavior {
1190            ListSizingBehavior::Infer => {
1191                let mut style = Style::default();
1192                style.overflow.y = Overflow::Scroll;
1193                style.refine(&self.style);
1194                window.with_text_style(style.text_style().cloned(), |window| {
1195                    let state = &mut *self.state.0.borrow_mut();
1196
1197                    let available_height = if let Some(last_bounds) = state.last_layout_bounds {
1198                        last_bounds.size.height
1199                    } else {
1200                        // If we don't have the last layout bounds (first render),
1201                        // we might just use the overdraw value as the available height to layout enough items.
1202                        state.overdraw
1203                    };
1204                    let padding = style.padding.to_pixels(
1205                        state.last_layout_bounds.unwrap_or_default().size.into(),
1206                        window.rem_size(),
1207                    );
1208
1209                    let layout_response = state.layout_items(
1210                        None,
1211                        available_height,
1212                        &padding,
1213                        &mut self.render_item,
1214                        window,
1215                        cx,
1216                    );
1217                    let max_element_width = layout_response.max_item_width;
1218
1219                    let summary = state.items.summary();
1220                    let total_height = summary.height;
1221
1222                    window.request_measured_layout(
1223                        style,
1224                        move |known_dimensions, available_space, _window, _cx| {
1225                            let width =
1226                                known_dimensions
1227                                    .width
1228                                    .unwrap_or(match available_space.width {
1229                                        AvailableSpace::Definite(x) => x,
1230                                        AvailableSpace::MinContent | AvailableSpace::MaxContent => {
1231                                            max_element_width
1232                                        }
1233                                    });
1234                            let height = match available_space.height {
1235                                AvailableSpace::Definite(height) => total_height.min(height),
1236                                AvailableSpace::MinContent | AvailableSpace::MaxContent => {
1237                                    total_height
1238                                }
1239                            };
1240                            size(width, height)
1241                        },
1242                    )
1243                })
1244            }
1245            ListSizingBehavior::Auto => {
1246                let mut style = Style::default();
1247                style.refine(&self.style);
1248                window.with_text_style(style.text_style().cloned(), |window| {
1249                    window.request_layout(style, None, cx)
1250                })
1251            }
1252        };
1253        (layout_id, ())
1254    }
1255
1256    fn prepaint(
1257        &mut self,
1258        _id: Option<&GlobalElementId>,
1259        _inspector_id: Option<&InspectorElementId>,
1260        bounds: Bounds<Pixels>,
1261        _: &mut Self::RequestLayoutState,
1262        window: &mut Window,
1263        cx: &mut App,
1264    ) -> ListPrepaintState {
1265        let state = &mut *self.state.0.borrow_mut();
1266        state.reset = false;
1267
1268        let mut style = Style::default();
1269        style.refine(&self.style);
1270
1271        let hitbox = window.insert_hitbox(bounds, HitboxBehavior::Normal);
1272
1273        // If the width of the list has changed, invalidate all cached item heights
1274        if state
1275            .last_layout_bounds
1276            .is_none_or(|last_bounds| last_bounds.size.width != bounds.size.width)
1277        {
1278            let new_items = SumTree::from_iter(
1279                state.items.iter().map(|item| ListItem::Unmeasured {
1280                    size_hint: None,
1281                    focus_handle: item.focus_handle(),
1282                }),
1283                (),
1284            );
1285
1286            state.items = new_items;
1287            state.measuring_behavior.reset();
1288        }
1289
1290        let padding = style
1291            .padding
1292            .to_pixels(bounds.size.into(), window.rem_size());
1293        let layout =
1294            match state.prepaint_items(bounds, padding, true, &mut self.render_item, window, cx) {
1295                Ok(layout) => layout,
1296                Err(autoscroll_request) => {
1297                    state.logical_scroll_top = Some(autoscroll_request);
1298                    state
1299                        .prepaint_items(bounds, padding, false, &mut self.render_item, window, cx)
1300                        .unwrap()
1301                }
1302            };
1303
1304        state.last_layout_bounds = Some(bounds);
1305        state.last_padding = Some(padding);
1306        ListPrepaintState { hitbox, layout }
1307    }
1308
1309    fn paint(
1310        &mut self,
1311        _id: Option<&GlobalElementId>,
1312        _inspector_id: Option<&InspectorElementId>,
1313        bounds: Bounds<crate::Pixels>,
1314        _: &mut Self::RequestLayoutState,
1315        prepaint: &mut Self::PrepaintState,
1316        window: &mut Window,
1317        cx: &mut App,
1318    ) {
1319        let current_view = window.current_view();
1320        window.with_content_mask(Some(ContentMask { bounds }), |window| {
1321            for item in &mut prepaint.layout.item_layouts {
1322                item.element.paint(window, cx);
1323            }
1324        });
1325
1326        let list_state = self.state.clone();
1327        let height = bounds.size.height;
1328        let scroll_top = prepaint.layout.scroll_top;
1329        let hitbox_id = prepaint.hitbox.id;
1330        let mut accumulated_scroll_delta = ScrollDelta::default();
1331        window.on_mouse_event(move |event: &ScrollWheelEvent, phase, window, cx| {
1332            if phase == DispatchPhase::Bubble && hitbox_id.should_handle_scroll(window) {
1333                accumulated_scroll_delta = accumulated_scroll_delta.coalesce(event.delta);
1334                let pixel_delta = accumulated_scroll_delta.pixel_delta(px(20.));
1335                list_state.0.borrow_mut().scroll(
1336                    &scroll_top,
1337                    height,
1338                    pixel_delta,
1339                    current_view,
1340                    window,
1341                    cx,
1342                )
1343            }
1344        });
1345    }
1346}
1347
1348impl IntoElement for List {
1349    type Element = Self;
1350
1351    fn into_element(self) -> Self::Element {
1352        self
1353    }
1354}
1355
1356impl Styled for List {
1357    fn style(&mut self) -> &mut StyleRefinement {
1358        &mut self.style
1359    }
1360}
1361
1362impl sum_tree::Item for ListItem {
1363    type Summary = ListItemSummary;
1364
1365    fn summary(&self, _: ()) -> Self::Summary {
1366        match self {
1367            ListItem::Unmeasured {
1368                size_hint,
1369                focus_handle,
1370            } => ListItemSummary {
1371                count: 1,
1372                rendered_count: 0,
1373                unrendered_count: 1,
1374                height: if let Some(size) = size_hint {
1375                    size.height
1376                } else {
1377                    px(0.)
1378                },
1379                has_focus_handles: focus_handle.is_some(),
1380            },
1381            ListItem::Measured {
1382                size, focus_handle, ..
1383            } => ListItemSummary {
1384                count: 1,
1385                rendered_count: 1,
1386                unrendered_count: 0,
1387                height: size.height,
1388                has_focus_handles: focus_handle.is_some(),
1389            },
1390        }
1391    }
1392}
1393
1394impl sum_tree::ContextLessSummary for ListItemSummary {
1395    fn zero() -> Self {
1396        Default::default()
1397    }
1398
1399    fn add_summary(&mut self, summary: &Self) {
1400        self.count += summary.count;
1401        self.rendered_count += summary.rendered_count;
1402        self.unrendered_count += summary.unrendered_count;
1403        self.height += summary.height;
1404        self.has_focus_handles |= summary.has_focus_handles;
1405    }
1406}
1407
1408impl<'a> sum_tree::Dimension<'a, ListItemSummary> for Count {
1409    fn zero(_cx: ()) -> Self {
1410        Default::default()
1411    }
1412
1413    fn add_summary(&mut self, summary: &'a ListItemSummary, _: ()) {
1414        self.0 += summary.count;
1415    }
1416}
1417
1418impl<'a> sum_tree::Dimension<'a, ListItemSummary> for Height {
1419    fn zero(_cx: ()) -> Self {
1420        Default::default()
1421    }
1422
1423    fn add_summary(&mut self, summary: &'a ListItemSummary, _: ()) {
1424        self.0 += summary.height;
1425    }
1426}
1427
1428impl sum_tree::SeekTarget<'_, ListItemSummary, ListItemSummary> for Count {
1429    fn cmp(&self, other: &ListItemSummary, _: ()) -> std::cmp::Ordering {
1430        self.0.partial_cmp(&other.count).unwrap()
1431    }
1432}
1433
1434impl sum_tree::SeekTarget<'_, ListItemSummary, ListItemSummary> for Height {
1435    fn cmp(&self, other: &ListItemSummary, _: ()) -> std::cmp::Ordering {
1436        self.0.partial_cmp(&other.height).unwrap()
1437    }
1438}
1439
1440#[cfg(test)]
1441mod test {
1442
1443    use gpui::{ScrollDelta, ScrollWheelEvent};
1444    use std::cell::Cell;
1445    use std::rc::Rc;
1446
1447    use crate::{
1448        self as gpui, AppContext, Context, Element, FollowMode, IntoElement, ListState, Render,
1449        Styled, TestAppContext, Window, div, list, point, px, size,
1450    };
1451
1452    #[gpui::test]
1453    fn test_reset_after_paint_before_scroll(cx: &mut TestAppContext) {
1454        let cx = cx.add_empty_window();
1455
1456        let state = ListState::new(5, crate::ListAlignment::Top, px(10.));
1457
1458        // Ensure that the list is scrolled to the top
1459        state.scroll_to(gpui::ListOffset {
1460            item_ix: 0,
1461            offset_in_item: px(0.0),
1462        });
1463
1464        struct TestView(ListState);
1465        impl Render for TestView {
1466            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1467                list(self.0.clone(), |_, _, _| {
1468                    div().h(px(10.)).w_full().into_any()
1469                })
1470                .w_full()
1471                .h_full()
1472            }
1473        }
1474
1475        // Paint
1476        cx.draw(point(px(0.), px(0.)), size(px(100.), px(20.)), |_, cx| {
1477            cx.new(|_| TestView(state.clone())).into_any_element()
1478        });
1479
1480        // Reset
1481        state.reset(5);
1482
1483        // And then receive a scroll event _before_ the next paint
1484        cx.simulate_event(ScrollWheelEvent {
1485            position: point(px(1.), px(1.)),
1486            delta: ScrollDelta::Pixels(point(px(0.), px(-500.))),
1487            ..Default::default()
1488        });
1489
1490        // Scroll position should stay at the top of the list
1491        assert_eq!(state.logical_scroll_top().item_ix, 0);
1492        assert_eq!(state.logical_scroll_top().offset_in_item, px(0.));
1493    }
1494
1495    #[gpui::test]
1496    fn test_scroll_by_positive_and_negative_distance(cx: &mut TestAppContext) {
1497        let cx = cx.add_empty_window();
1498
1499        let state = ListState::new(5, crate::ListAlignment::Top, px(10.));
1500
1501        struct TestView(ListState);
1502        impl Render for TestView {
1503            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1504                list(self.0.clone(), |_, _, _| {
1505                    div().h(px(20.)).w_full().into_any()
1506                })
1507                .w_full()
1508                .h_full()
1509            }
1510        }
1511
1512        // Paint
1513        cx.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, cx| {
1514            cx.new(|_| TestView(state.clone())).into_any_element()
1515        });
1516
1517        // Test positive distance: start at item 1, move down 30px
1518        state.scroll_by(px(30.));
1519
1520        // Should move to item 2
1521        let offset = state.logical_scroll_top();
1522        assert_eq!(offset.item_ix, 1);
1523        assert_eq!(offset.offset_in_item, px(10.));
1524
1525        // Test negative distance: start at item 2, move up 30px
1526        state.scroll_by(px(-30.));
1527
1528        // Should move back to item 1
1529        let offset = state.logical_scroll_top();
1530        assert_eq!(offset.item_ix, 0);
1531        assert_eq!(offset.offset_in_item, px(0.));
1532
1533        // Test zero distance
1534        state.scroll_by(px(0.));
1535        let offset = state.logical_scroll_top();
1536        assert_eq!(offset.item_ix, 0);
1537        assert_eq!(offset.offset_in_item, px(0.));
1538    }
1539
1540    #[gpui::test]
1541    fn test_measure_all_after_width_change(cx: &mut TestAppContext) {
1542        let cx = cx.add_empty_window();
1543
1544        let state = ListState::new(10, crate::ListAlignment::Top, px(0.)).measure_all();
1545
1546        struct TestView(ListState);
1547        impl Render for TestView {
1548            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1549                list(self.0.clone(), |_, _, _| {
1550                    div().h(px(50.)).w_full().into_any()
1551                })
1552                .w_full()
1553                .h_full()
1554            }
1555        }
1556
1557        let view = cx.update(|_, cx| cx.new(|_| TestView(state.clone())));
1558
1559        // First draw at width 100: all 10 items measured (total 500px).
1560        // Viewport is 200px, so max scroll offset should be 300px.
1561        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1562            view.clone().into_any_element()
1563        });
1564        assert_eq!(state.max_offset_for_scrollbar().y, px(300.));
1565
1566        // Second draw at a different width: items get invalidated.
1567        // Without the fix, max_offset would drop because unmeasured items
1568        // contribute 0 height.
1569        cx.draw(point(px(0.), px(0.)), size(px(200.), px(200.)), |_, _| {
1570            view.into_any_element()
1571        });
1572        assert_eq!(state.max_offset_for_scrollbar().y, px(300.));
1573    }
1574
1575    #[gpui::test]
1576    fn test_remeasure(cx: &mut TestAppContext) {
1577        let cx = cx.add_empty_window();
1578
1579        // Create a list with 10 items, each 100px tall. We'll keep a reference
1580        // to the item height so we can later change the height and assert how
1581        // `ListState` handles it.
1582        let item_height = Rc::new(Cell::new(100usize));
1583        let state = ListState::new(10, crate::ListAlignment::Top, px(10.));
1584
1585        struct TestView {
1586            state: ListState,
1587            item_height: Rc<Cell<usize>>,
1588        }
1589
1590        impl Render for TestView {
1591            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1592                let height = self.item_height.get();
1593                list(self.state.clone(), move |_, _, _| {
1594                    div().h(px(height as f32)).w_full().into_any()
1595                })
1596                .w_full()
1597                .h_full()
1598            }
1599        }
1600
1601        let state_clone = state.clone();
1602        let item_height_clone = item_height.clone();
1603        let view = cx.update(|_, cx| {
1604            cx.new(|_| TestView {
1605                state: state_clone,
1606                item_height: item_height_clone,
1607            })
1608        });
1609
1610        // Simulate scrolling 40px inside the element with index 2. Since the
1611        // original item height is 100px, this equates to 40% inside the item.
1612        state.scroll_to(gpui::ListOffset {
1613            item_ix: 2,
1614            offset_in_item: px(40.),
1615        });
1616
1617        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1618            view.clone().into_any_element()
1619        });
1620
1621        let offset = state.logical_scroll_top();
1622        assert_eq!(offset.item_ix, 2);
1623        assert_eq!(offset.offset_in_item, px(40.));
1624
1625        // Update the `item_height` to be 50px instead of 100px so we can assert
1626        // that the scroll position is proportionally preserved, that is,
1627        // instead of 40px from the top of item 2, it should be 20px, since the
1628        // item's height has been halved.
1629        item_height.set(50);
1630        state.remeasure();
1631
1632        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1633            view.into_any_element()
1634        });
1635
1636        let offset = state.logical_scroll_top();
1637        assert_eq!(offset.item_ix, 2);
1638        assert_eq!(offset.offset_in_item, px(20.));
1639    }
1640
1641    #[gpui::test]
1642    fn test_follow_tail_stays_at_bottom_as_items_grow(cx: &mut TestAppContext) {
1643        let cx = cx.add_empty_window();
1644
1645        // 10 items, each 50px tall → 500px total content, 200px viewport.
1646        // With follow-tail on, the list should always show the bottom.
1647        let item_height = Rc::new(Cell::new(50usize));
1648        let state = ListState::new(10, crate::ListAlignment::Top, px(0.));
1649
1650        struct TestView {
1651            state: ListState,
1652            item_height: Rc<Cell<usize>>,
1653        }
1654        impl Render for TestView {
1655            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1656                let height = self.item_height.get();
1657                list(self.state.clone(), move |_, _, _| {
1658                    div().h(px(height as f32)).w_full().into_any()
1659                })
1660                .w_full()
1661                .h_full()
1662            }
1663        }
1664
1665        let state_clone = state.clone();
1666        let item_height_clone = item_height.clone();
1667        let view = cx.update(|_, cx| {
1668            cx.new(|_| TestView {
1669                state: state_clone,
1670                item_height: item_height_clone,
1671            })
1672        });
1673
1674        state.set_follow_mode(FollowMode::Tail);
1675
1676        // First paint — items are 50px, total 500px, viewport 200px.
1677        // Follow-tail should anchor to the end.
1678        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1679            view.clone().into_any_element()
1680        });
1681
1682        // The scroll should be at the bottom: the last visible items fill the
1683        // 200px viewport from the end of 500px of content (offset 300px).
1684        let offset = state.logical_scroll_top();
1685        assert_eq!(offset.item_ix, 6);
1686        assert_eq!(offset.offset_in_item, px(0.));
1687        assert!(state.is_following_tail());
1688
1689        // Simulate items growing (e.g. streaming content makes each item taller).
1690        // 10 items × 80px = 800px total.
1691        item_height.set(80);
1692        state.remeasure();
1693
1694        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1695            view.into_any_element()
1696        });
1697
1698        // After growth, follow-tail should have re-anchored to the new end.
1699        // 800px total − 200px viewport = 600px offset → item 7 at offset 40px,
1700        // but follow-tail anchors to item_count (10), and layout walks back to
1701        // fill 200px, landing at item 7 (7 × 80 = 560, 800 − 560 = 240 > 200,
1702        // so item 8: 8 × 80 = 640, 800 − 640 = 160 < 200 → keeps walking →
1703        // item 7: offset = 800 − 200 = 600, item_ix = 600/80 = 7, remainder 40).
1704        let offset = state.logical_scroll_top();
1705        assert_eq!(offset.item_ix, 7);
1706        assert_eq!(offset.offset_in_item, px(40.));
1707        assert!(state.is_following_tail());
1708    }
1709
1710    #[gpui::test]
1711    fn test_follow_tail_disengages_on_user_scroll(cx: &mut TestAppContext) {
1712        let cx = cx.add_empty_window();
1713
1714        // 10 items × 50px = 500px total, 200px viewport.
1715        let state = ListState::new(10, crate::ListAlignment::Top, px(0.));
1716
1717        struct TestView(ListState);
1718        impl Render for TestView {
1719            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1720                list(self.0.clone(), |_, _, _| {
1721                    div().h(px(50.)).w_full().into_any()
1722                })
1723                .w_full()
1724                .h_full()
1725            }
1726        }
1727
1728        state.set_follow_mode(FollowMode::Tail);
1729
1730        // Paint with follow-tail — scroll anchored to the bottom.
1731        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, cx| {
1732            cx.new(|_| TestView(state.clone())).into_any_element()
1733        });
1734        assert!(state.is_following_tail());
1735
1736        // Simulate the user scrolling up.
1737        // This should disengage follow-tail.
1738        cx.simulate_event(ScrollWheelEvent {
1739            position: point(px(50.), px(100.)),
1740            delta: ScrollDelta::Pixels(point(px(0.), px(100.))),
1741            ..Default::default()
1742        });
1743
1744        assert!(
1745            !state.is_following_tail(),
1746            "follow-tail should disengage when the user scrolls toward the start"
1747        );
1748    }
1749
1750    #[gpui::test]
1751    fn test_follow_tail_disengages_on_scrollbar_reposition(cx: &mut TestAppContext) {
1752        let cx = cx.add_empty_window();
1753
1754        // 10 items × 50px = 500px total, 200px viewport.
1755        let state = ListState::new(10, crate::ListAlignment::Top, px(0.)).measure_all();
1756
1757        struct TestView(ListState);
1758        impl Render for TestView {
1759            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1760                list(self.0.clone(), |_, _, _| {
1761                    div().h(px(50.)).w_full().into_any()
1762                })
1763                .w_full()
1764                .h_full()
1765            }
1766        }
1767
1768        let view = cx.update(|_, cx| cx.new(|_| TestView(state.clone())));
1769
1770        state.set_follow_mode(FollowMode::Tail);
1771
1772        // Paint with follow-tail — scroll anchored to the bottom.
1773        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1774            view.clone().into_any_element()
1775        });
1776        assert!(state.is_following_tail());
1777
1778        // Simulate the scrollbar moving the viewport to the middle.
1779        // `set_offset_from_scrollbar` accepts a positive distance from the start.
1780        state.set_offset_from_scrollbar(point(px(0.), px(150.)));
1781
1782        let offset = state.logical_scroll_top();
1783        assert_eq!(offset.item_ix, 3);
1784        assert_eq!(offset.offset_in_item, px(0.));
1785        assert!(
1786            !state.is_following_tail(),
1787            "follow-tail should disengage when the scrollbar manually repositions the list"
1788        );
1789
1790        // A subsequent draw should preserve the user's manual position instead
1791        // of snapping back to the end.
1792        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1793            view.into_any_element()
1794        });
1795
1796        let offset = state.logical_scroll_top();
1797        assert_eq!(offset.item_ix, 3);
1798        assert_eq!(offset.offset_in_item, px(0.));
1799    }
1800
1801    #[gpui::test]
1802    fn test_set_follow_tail_snaps_to_bottom(cx: &mut TestAppContext) {
1803        let cx = cx.add_empty_window();
1804
1805        // 10 items × 50px = 500px total, 200px viewport.
1806        let state = ListState::new(10, crate::ListAlignment::Top, px(0.));
1807
1808        struct TestView(ListState);
1809        impl Render for TestView {
1810            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1811                list(self.0.clone(), |_, _, _| {
1812                    div().h(px(50.)).w_full().into_any()
1813                })
1814                .w_full()
1815                .h_full()
1816            }
1817        }
1818
1819        let view = cx.update(|_, cx| cx.new(|_| TestView(state.clone())));
1820
1821        // Scroll to the middle of the list (item 3).
1822        state.scroll_to(gpui::ListOffset {
1823            item_ix: 3,
1824            offset_in_item: px(0.),
1825        });
1826
1827        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1828            view.clone().into_any_element()
1829        });
1830
1831        let offset = state.logical_scroll_top();
1832        assert_eq!(offset.item_ix, 3);
1833        assert_eq!(offset.offset_in_item, px(0.));
1834        assert!(!state.is_following_tail());
1835
1836        // Enable follow-tail — this should immediately snap the scroll anchor
1837        // to the end, like the user just sent a prompt.
1838        state.set_follow_mode(FollowMode::Tail);
1839
1840        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1841            view.into_any_element()
1842        });
1843
1844        // After paint, scroll should be at the bottom.
1845        // 500px total − 200px viewport = 300px offset → item 6, offset 0.
1846        let offset = state.logical_scroll_top();
1847        assert_eq!(offset.item_ix, 6);
1848        assert_eq!(offset.offset_in_item, px(0.));
1849        assert!(state.is_following_tail());
1850    }
1851
1852    #[gpui::test]
1853    fn test_bottom_aligned_scrollbar_offset_at_end(cx: &mut TestAppContext) {
1854        let cx = cx.add_empty_window();
1855
1856        const ITEMS: usize = 10;
1857        const ITEM_SIZE: f32 = 50.0;
1858
1859        let state = ListState::new(
1860            ITEMS,
1861            crate::ListAlignment::Bottom,
1862            px(ITEMS as f32 * ITEM_SIZE),
1863        );
1864
1865        struct TestView(ListState);
1866        impl Render for TestView {
1867            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1868                list(self.0.clone(), |_, _, _| {
1869                    div().h(px(ITEM_SIZE)).w_full().into_any()
1870                })
1871                .w_full()
1872                .h_full()
1873            }
1874        }
1875
1876        cx.draw(point(px(0.), px(0.)), size(px(100.), px(100.)), |_, cx| {
1877            cx.new(|_| TestView(state.clone())).into_any_element()
1878        });
1879
1880        // Bottom-aligned lists start pinned to the end: logical_scroll_top returns
1881        // item_ix == item_count, meaning no explicit scroll position has been set.
1882        assert_eq!(state.logical_scroll_top().item_ix, ITEMS);
1883
1884        let max_offset = state.max_offset_for_scrollbar();
1885        let scroll_offset = state.scroll_px_offset_for_scrollbar();
1886
1887        assert_eq!(
1888            -scroll_offset.y, max_offset.y,
1889            "scrollbar offset ({}) should equal max offset ({}) when list is pinned to bottom",
1890            -scroll_offset.y, max_offset.y,
1891        );
1892    }
1893
1894    /// When the user scrolls away from the bottom during follow_tail,
1895    /// follow_tail suspends. If they scroll back to the bottom, the
1896    /// next paint should re-engage follow_tail using fresh measurements.
1897    #[gpui::test]
1898    fn test_follow_tail_reengages_when_scrolled_back_to_bottom(cx: &mut TestAppContext) {
1899        let cx = cx.add_empty_window();
1900
1901        // 10 items × 50px = 500px total, 200px viewport.
1902        let state = ListState::new(10, crate::ListAlignment::Top, px(0.));
1903
1904        struct TestView(ListState);
1905        impl Render for TestView {
1906            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1907                list(self.0.clone(), |_, _, _| {
1908                    div().h(px(50.)).w_full().into_any()
1909                })
1910                .w_full()
1911                .h_full()
1912            }
1913        }
1914
1915        let view = cx.update(|_, cx| cx.new(|_| TestView(state.clone())));
1916
1917        state.set_follow_mode(FollowMode::Tail);
1918
1919        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1920            view.clone().into_any_element()
1921        });
1922        assert!(state.is_following_tail());
1923
1924        // Scroll up — follow_tail should suspend (not fully disengage).
1925        cx.simulate_event(ScrollWheelEvent {
1926            position: point(px(50.), px(100.)),
1927            delta: ScrollDelta::Pixels(point(px(0.), px(50.))),
1928            ..Default::default()
1929        });
1930        assert!(!state.is_following_tail());
1931
1932        // Scroll back down to the bottom.
1933        cx.simulate_event(ScrollWheelEvent {
1934            position: point(px(50.), px(100.)),
1935            delta: ScrollDelta::Pixels(point(px(0.), px(-10000.))),
1936            ..Default::default()
1937        });
1938
1939        // After a paint, follow_tail should re-engage because the
1940        // layout confirmed we're at the true bottom.
1941        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1942            view.clone().into_any_element()
1943        });
1944        assert!(
1945            state.is_following_tail(),
1946            "follow_tail should re-engage after scrolling back to the bottom"
1947        );
1948    }
1949
1950    /// When an item is spliced to unmeasured (0px) while follow_tail
1951    /// is suspended, the re-engagement check should still work correctly
1952    #[gpui::test]
1953    fn test_follow_tail_reengagement_not_fooled_by_unmeasured_items(cx: &mut TestAppContext) {
1954        let cx = cx.add_empty_window();
1955
1956        // 20 items × 50px = 1000px total, 200px viewport, 1000px
1957        // overdraw so all items get measured during the follow_tail
1958        // paint (matching realistic production settings).
1959        let state = ListState::new(20, crate::ListAlignment::Top, px(1000.));
1960
1961        struct TestView(ListState);
1962        impl Render for TestView {
1963            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
1964                list(self.0.clone(), |_, _, _| {
1965                    div().h(px(50.)).w_full().into_any()
1966                })
1967                .w_full()
1968                .h_full()
1969            }
1970        }
1971
1972        let view = cx.update(|_, cx| cx.new(|_| TestView(state.clone())));
1973
1974        state.set_follow_mode(FollowMode::Tail);
1975
1976        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
1977            view.clone().into_any_element()
1978        });
1979        assert!(state.is_following_tail());
1980
1981        // Scroll up a meaningful amount — suspends follow_tail.
1982        // 20 items × 50px = 1000px. viewport 200px. scroll_max = 800px.
1983        // Scrolling up 200px puts us at 600px, clearly not at bottom.
1984        cx.simulate_event(ScrollWheelEvent {
1985            position: point(px(50.), px(100.)),
1986            delta: ScrollDelta::Pixels(point(px(0.), px(200.))),
1987            ..Default::default()
1988        });
1989        assert!(!state.is_following_tail());
1990
1991        // Invalidate the last item (simulates EntryUpdated calling
1992        // remeasure_items). This makes items.summary().height
1993        // temporarily wrong (0px for the invalidated item).
1994        state.remeasure_items(19..20);
1995
1996        // Paint — layout re-measures the invalidated item with its true
1997        // height. The re-engagement check uses these fresh measurements.
1998        // Since we scrolled 200px up from the 800px max, we're at
1999        // ~600px — NOT at the bottom, so follow_tail should NOT
2000        // re-engage.
2001        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
2002            view.clone().into_any_element()
2003        });
2004        assert!(
2005            !state.is_following_tail(),
2006            "follow_tail should not falsely re-engage due to an unmeasured item \
2007             reducing items.summary().height"
2008        );
2009    }
2010
2011    /// Calling `set_follow_mode(FollowState::Normal)` or dragging the scrollbar should
2012    /// fully disengage follow_tail — clearing any suspended state so
2013    /// follow_tail won’t auto-re-engage.
2014    #[gpui::test]
2015    fn test_follow_tail_suspended_state_cleared_by_explicit_actions(cx: &mut TestAppContext) {
2016        let cx = cx.add_empty_window();
2017
2018        // 10 items × 50px = 500px total, 200px viewport.
2019        let state = ListState::new(10, crate::ListAlignment::Top, px(0.)).measure_all();
2020
2021        struct TestView(ListState);
2022        impl Render for TestView {
2023            fn render(&mut self, _: &mut Window, _: &mut Context<Self>) -> impl IntoElement {
2024                list(self.0.clone(), |_, _, _| {
2025                    div().h(px(50.)).w_full().into_any()
2026                })
2027                .w_full()
2028                .h_full()
2029            }
2030        }
2031
2032        let view = cx.update(|_, cx| cx.new(|_| TestView(state.clone())));
2033
2034        state.set_follow_mode(FollowMode::Tail);
2035        // --- Part 1: set_follow_mode(FollowState::Normal) clears suspended state ---
2036
2037        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
2038            view.clone().into_any_element()
2039        });
2040
2041        // Scroll up — suspends follow_tail.
2042        cx.simulate_event(ScrollWheelEvent {
2043            position: point(px(50.), px(100.)),
2044            delta: ScrollDelta::Pixels(point(px(0.), px(50.))),
2045            ..Default::default()
2046        });
2047        assert!(!state.is_following_tail());
2048
2049        // Scroll back to the bottom — should re-engage follow_tail.
2050        cx.simulate_event(ScrollWheelEvent {
2051            position: point(px(50.), px(100.)),
2052            delta: ScrollDelta::Pixels(point(px(0.), px(-10000.))),
2053            ..Default::default()
2054        });
2055
2056        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
2057            view.clone().into_any_element()
2058        });
2059        assert!(
2060            state.is_following_tail(),
2061            "follow_tail should re-engage after scrolling back to the bottom"
2062        );
2063
2064        // --- Part 2: scrollbar drag clears suspended state ---
2065
2066        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
2067            view.clone().into_any_element()
2068        });
2069
2070        // Drag the scrollbar to the middle — should clear suspended state.
2071        state.set_offset_from_scrollbar(point(px(0.), px(150.)));
2072
2073        // Scroll to the bottom.
2074        cx.simulate_event(ScrollWheelEvent {
2075            position: point(px(50.), px(100.)),
2076            delta: ScrollDelta::Pixels(point(px(0.), px(-10000.))),
2077            ..Default::default()
2078        });
2079
2080        // Paint — should NOT re-engage because the scrollbar drag
2081        // cleared the suspended state.
2082        cx.draw(point(px(0.), px(0.)), size(px(100.), px(200.)), |_, _| {
2083            view.clone().into_any_element()
2084        });
2085        assert!(
2086            !state.is_following_tail(),
2087            "follow_tail should not re-engage after scrollbar drag cleared the suspended state"
2088        );
2089    }
2090}