Rename top_excerpt to sticky_header_excerpt and improve docs

Co-authored-by: Michael <michael@zed.dev>

crates/editor/src/display_map.rs

@@ -32,7 +32,7 @@ use crate::{
 pub use block_map::{
     Block, BlockBufferRows, BlockChunks as DisplayChunks, BlockContext, BlockId, BlockMap,
     BlockPlacement, BlockPoint, BlockProperties, BlockStyle, CustomBlockId, RenderBlock,
-    TopExcerptInfo,
+    StickyHeaderExcerpt,
 };
 use block_map::{BlockRow, BlockSnapshot};
 use collections::{HashMap, HashSet};
@@ -1106,8 +1106,8 @@ impl DisplaySnapshot {
             .map(|(row, block)| (DisplayRow(row), block))
     }
 
-    pub fn top_excerpt(&self, row: DisplayRow) -> Option<TopExcerptInfo<'_>> {
-        self.block_snapshot.top_excerpt(row.0)
+    pub fn sticky_header_excerpt(&self, row: DisplayRow) -> Option<StickyHeaderExcerpt<'_>> {
+        self.block_snapshot.sticky_header_excerpt(row.0)
     }
 
     pub fn block_for_id(&self, id: BlockId) -> Option<Block> {

crates/editor/src/display_map/block_map.rs

@@ -1411,7 +1411,7 @@ impl BlockSnapshot {
         })
     }
 
-    pub fn top_excerpt(&self, top_row: u32) -> Option<TopExcerptInfo<'_>> {
+    pub fn sticky_header_excerpt(&self, top_row: u32) -> Option<StickyHeaderExcerpt<'_>> {
         let mut cursor = self.transforms.cursor::<BlockRow>(&());
         cursor.seek(&BlockRow(top_row), Bias::Left, &());
 
@@ -1434,7 +1434,7 @@ impl BlockSnapshot {
                     };
 
                     if matches_start && top_row <= end {
-                        return next_excerpt.as_ref().map(|excerpt| TopExcerptInfo {
+                        return next_excerpt.as_ref().map(|excerpt| StickyHeaderExcerpt {
                             next_buffer_row: None,
                             next_excerpt_controls_present: *show_excerpt_controls,
                             excerpt,
@@ -1443,7 +1443,7 @@ impl BlockSnapshot {
 
                     let next_buffer_row = if *starts_new_buffer { Some(end) } else { None };
 
-                    return prev_excerpt.as_ref().map(|excerpt| TopExcerptInfo {
+                    return prev_excerpt.as_ref().map(|excerpt| StickyHeaderExcerpt {
                         excerpt,
                         next_buffer_row,
                         next_excerpt_controls_present: *show_excerpt_controls,
@@ -1452,18 +1452,19 @@ impl BlockSnapshot {
                 Some(Block::FoldedBuffer {
                     prev_excerpt: Some(excerpt),
                     ..
-                }) => {
-                    if top_row <= start {
-                        return Some(TopExcerptInfo {
-                            next_buffer_row: Some(end),
-                            next_excerpt_controls_present: false,
-                            excerpt,
-                        });
-                    }
+                }) if top_row <= start => {
+                    return Some(StickyHeaderExcerpt {
+                        next_buffer_row: Some(end),
+                        next_excerpt_controls_present: false,
+                        excerpt,
+                    });
                 }
-                _ => {}
+                Some(Block::FoldedBuffer { .. }) | Some(Block::Custom(_)) | None => {}
             }
 
+            // This is needed to iterate past None / FoldedBuffer / Custom blocks. For FoldedBuffer,
+            // if scrolled slightly past the header of a folded block, the next block is needed for
+            // the sticky header.
             cursor.next(&());
         }
 
@@ -1753,7 +1754,7 @@ impl<'a> BlockChunks<'a> {
     }
 }
 
-pub struct TopExcerptInfo<'a> {
+pub struct StickyHeaderExcerpt<'a> {
     pub excerpt: &'a ExcerptInfo,
     pub next_excerpt_controls_present: bool,
     pub next_buffer_row: Option<u32>,

crates/editor/src/element.rs

@@ -22,7 +22,7 @@ use crate::{
     EditorSnapshot, EditorStyle, ExpandExcerpts, FocusedBlock, GutterDimensions, HalfPageDown,
     HalfPageUp, HandleInput, HoveredCursor, HoveredHunk, InlineCompletion, JumpData, LineDown,
     LineUp, OpenExcerpts, PageDown, PageUp, Point, RowExt, RowRangeExt, SelectPhase, Selection,
-    SoftWrap, ToPoint, ToggleFold, TopExcerptInfo, CURSORS_VISIBLE_FOR, FILE_HEADER_HEIGHT,
+    SoftWrap, StickyHeaderExcerpt, ToPoint, ToggleFold, CURSORS_VISIBLE_FOR, FILE_HEADER_HEIGHT,
     GIT_BLAME_MAX_AUTHOR_CHARS_DISPLAYED, MAX_LINE_LEN, MULTI_BUFFER_EXCERPT_HEADER_HEIGHT,
     MULTI_BUFFER_EXCERPT_HEADER_PADDING,
 };
@@ -2210,7 +2210,7 @@ impl EditorElement {
         resized_blocks: &mut HashMap<CustomBlockId, u32>,
         selections: &[Selection<Point>],
         is_row_soft_wrapped: impl Copy + Fn(usize) -> bool,
-        top_excerpt_id: Option<ExcerptId>,
+        sticky_header_excerpt_id: Option<ExcerptId>,
         cx: &mut WindowContext,
     ) -> (AnyElement, Size<Pixels>) {
         let mut element = match block {
@@ -2340,7 +2340,7 @@ impl EditorElement {
                 if let Some(next_excerpt) = next_excerpt {
                     let jump_data = jump_data(snapshot, block_row_start, *height, next_excerpt, cx);
                     if *starts_new_buffer {
-                        if top_excerpt_id != Some(next_excerpt.id) {
+                        if sticky_header_excerpt_id != Some(next_excerpt.id) {
                             result = result.child(self.render_buffer_header(
                                 next_excerpt,
                                 false,
@@ -2683,7 +2683,7 @@ impl EditorElement {
         line_layouts: &[LineWithInvisibles],
         selections: &[Selection<Point>],
         is_row_soft_wrapped: impl Copy + Fn(usize) -> bool,
-        top_excerpt_id: Option<ExcerptId>,
+        sticky_header_excerpt_id: Option<ExcerptId>,
         cx: &mut WindowContext,
     ) -> Result<Vec<BlockLayout>, HashMap<CustomBlockId, u32>> {
         let (fixed_blocks, non_fixed_blocks) = snapshot
@@ -2722,7 +2722,7 @@ impl EditorElement {
                 &mut resized_blocks,
                 selections,
                 is_row_soft_wrapped,
-                top_excerpt_id,
+                sticky_header_excerpt_id,
                 cx,
             );
             fixed_block_max_width = fixed_block_max_width.max(element_size.width + em_width);
@@ -2770,7 +2770,7 @@ impl EditorElement {
                 &mut resized_blocks,
                 selections,
                 is_row_soft_wrapped,
-                top_excerpt_id,
+                sticky_header_excerpt_id,
                 cx,
             );
 
@@ -2818,7 +2818,7 @@ impl EditorElement {
                             &mut resized_blocks,
                             selections,
                             is_row_soft_wrapped,
-                            top_excerpt_id,
+                            sticky_header_excerpt_id,
                             cx,
                         );
 
@@ -2887,11 +2887,11 @@ impl EditorElement {
 
     fn layout_sticky_buffer_header(
         &self,
-        TopExcerptInfo {
+        StickyHeaderExcerpt {
             excerpt,
             next_excerpt_controls_present,
             next_buffer_row,
-        }: TopExcerptInfo<'_>,
+        }: StickyHeaderExcerpt<'_>,
         scroll_position: f32,
         line_height: Pixels,
         snapshot: &EditorSnapshot,
@@ -6116,12 +6116,13 @@ impl Element for EditorElement {
                     let scroll_range_bounds = scrollbar_range_data.scroll_range;
                     let mut scroll_width = scroll_range_bounds.size.width;
 
-                    let top_excerpt = if snapshot.buffer_snapshot.show_headers() {
-                        snapshot.top_excerpt(start_row)
+                    let sticky_header_excerpt = if snapshot.buffer_snapshot.show_headers() {
+                        snapshot.sticky_header_excerpt(start_row)
                     } else {
                         None
                     };
-                    let top_excerpt_id = top_excerpt.as_ref().map(|top| top.excerpt.id);
+                    let sticky_header_excerpt_id =
+                        sticky_header_excerpt.as_ref().map(|top| top.excerpt.id);
 
                     let blocks = cx.with_element_namespace("blocks", |cx| {
                         self.render_blocks(
@@ -6138,7 +6139,7 @@ impl Element for EditorElement {
                             &line_layouts,
                             &local_selections,
                             is_row_soft_wrapped,
-                            top_excerpt_id,
+                            sticky_header_excerpt_id,
                             cx,
                         )
                     });
@@ -6152,10 +6153,10 @@ impl Element for EditorElement {
                         }
                     };
 
-                    let sticky_buffer_header = top_excerpt.map(|top_excerpt| {
+                    let sticky_buffer_header = sticky_header_excerpt.map(|sticky_header_excerpt| {
                         cx.with_element_namespace("blocks", |cx| {
                             self.layout_sticky_buffer_header(
-                                top_excerpt,
+                                sticky_header_excerpt,
                                 scroll_position.y,
                                 line_height,
                                 &snapshot,