From f1e03d00221c17e889a150bca2abff4154eeff2e Mon Sep 17 00:00:00 2001
From: Min Idzelis <min123@gmail.com>
Date: Wed, 15 Oct 2025 13:13:05 -0400
Subject: [PATCH] fix(web): improve scrubber behavior on scroll-limited
 timelines (#22917)

Improves scroll indicator positioning when scrubbing through timelines with limited scrollable content (e.g., small albums). When a timeline's scrollable height is less than 50% of the viewport height, the scroll position is now properly distributed across the entire scrubber height, making the indicator more responsive and accurate.

Changes:
- Add `limitedScroll` state to detect scroll-constrained timelines (threshold: 50%)
- Introduce `ViewportTopMonth` type to handle lead-in/lead-out sections
- Calculate `totalViewerHeight` including top/bottom sections for accurate positioning
- Refactor scrubber to treat lead-in and lead-out as distinct scroll segments
- Update scroll position calculations to use relative percentages on constrained timelines
---
 .../lib/components/timeline/Scrubber.svelte   | 114 +++++++++---------
 .../lib/components/timeline/Timeline.svelte   | 102 ++++++----------
 .../timeline-manager.svelte.spec.ts           |   2 +-
 .../timeline-manager.svelte.ts                |  21 +++-
 .../lib/managers/timeline-manager/types.ts    |   4 +-
 web/src/lib/utils/timeline-util.ts            |   4 +-
 6 files changed, 120 insertions(+), 127 deletions(-)

diff --git a/web/src/lib/components/timeline/Scrubber.svelte b/web/src/lib/components/timeline/Scrubber.svelte
index 76a12ea1ec..2c22af98ad 100644
--- a/web/src/lib/components/timeline/Scrubber.svelte
+++ b/web/src/lib/components/timeline/Scrubber.svelte
@@ -1,9 +1,9 @@
 <script lang="ts">
   import { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
-  import type { ScrubberMonth } from '$lib/managers/timeline-manager/types';
+  import type { ScrubberMonth, ViewportTopMonth } from '$lib/managers/timeline-manager/types';
   import { mobileDevice } from '$lib/stores/mobile-device.svelte';
   import { getTabbable } from '$lib/utils/focus-util';
-  import { type ScrubberListener, type TimelineYearMonth } from '$lib/utils/timeline-util';
+  import { type ScrubberListener } from '$lib/utils/timeline-util';
   import { Icon } from '@immich/ui';
   import { mdiPlay } from '@mdi/js';
   import { clamp } from 'lodash-es';
@@ -24,9 +24,8 @@
     /** The percentage of scroll through the month that is currently intersecting the top boundary of the viewport */
     viewportTopMonthScrollPercent?: number;
     /** The year/month of the timeline month at the top of the viewport */
-    viewportTopMonth?: TimelineYearMonth;
-    /** Indicates whether the viewport is currently in the lead-out section (after all months) */
-    isInLeadOutSection?: boolean;
+    viewportTopMonth?: ViewportTopMonth;
+
     /** Width of the scrubber component in pixels (bindable for parent component margin adjustments) */
     scrubberWidth?: number;
     /** Callback fired when user interacts with the scrubber to navigate */
@@ -47,7 +46,6 @@
     timelineScrollPercent = 0,
     viewportTopMonthScrollPercent = 0,
     viewportTopMonth = undefined,
-    isInLeadOutSection = false,
     onScrub = undefined,
     onScrubKeyDown = undefined,
     startScrub = undefined,
@@ -94,11 +92,19 @@
   });
 
   const toScrollFromMonthGroupPercentage = (
-    scrubberMonth: { year: number; month: number } | undefined,
+    scrubberMonth: ViewportTopMonth,
     scrubberMonthPercent: number,
     scrubOverallPercent: number,
   ) => {
-    if (scrubberMonth) {
+    if (scrubberMonth === 'lead-in') {
+      return relativeTopOffset * scrubberMonthPercent;
+    } else if (scrubberMonth === 'lead-out') {
+      let offset = relativeTopOffset;
+      for (const segment of segments) {
+        offset += segment.height;
+      }
+      return offset + relativeBottomOffset * scrubberMonthPercent;
+    } else if (scrubberMonth) {
       let offset = relativeTopOffset;
       let match = false;
       for (const segment of segments) {
@@ -113,23 +119,16 @@
         offset += scrubberMonthPercent * relativeBottomOffset;
       }
       return offset;
-    } else if (isInLeadOutSection) {
-      let offset = relativeTopOffset;
-      for (const segment of segments) {
-        offset += segment.height;
-      }
-      offset += scrubOverallPercent * relativeBottomOffset;
-      return offset;
     } else {
       return scrubOverallPercent * (height - (PADDING_TOP + PADDING_BOTTOM));
     }
   };
-  let scrollY = $derived(
+  const scrollY = $derived(
     toScrollFromMonthGroupPercentage(viewportTopMonth, viewportTopMonthScrollPercent, timelineScrollPercent),
   );
-  let timelineFullHeight = $derived(timelineManager.scrubberTimelineHeight + timelineTopOffset + timelineBottomOffset);
-  let relativeTopOffset = $derived(toScrollY(timelineTopOffset / timelineFullHeight));
-  let relativeBottomOffset = $derived(toScrollY(timelineBottomOffset / timelineFullHeight));
+  const timelineFullHeight = $derived(timelineManager.scrubberTimelineHeight);
+  const relativeTopOffset = $derived(toScrollY(timelineTopOffset / timelineFullHeight));
+  const relativeBottomOffset = $derived(toScrollY(timelineBottomOffset / timelineFullHeight));
 
   type Segment = {
     count: number;
@@ -173,14 +172,13 @@
           segment.hasLabel = true;
           previousLabeledSegment = segment;
         }
-        if (i !== 1 && segment.height > 5 && dotHeight > MIN_DOT_DISTANCE) {
+        if (segment.height > 5 && dotHeight > MIN_DOT_DISTANCE) {
           segment.hasDot = true;
           dotHeight = 0;
         }
-
         height += segment.height;
-        dotHeight += segment.height;
       }
+      dotHeight += segment.height;
       segments.push(segment);
     }
 
@@ -197,7 +195,13 @@
     }
     return activeSegment?.dataset.label;
   });
-  const segmentDate = $derived.by(() => {
+  const segmentDate: ViewportTopMonth = $derived.by(() => {
+    if (activeSegment?.dataset.id === 'lead-in') {
+      return 'lead-in';
+    }
+    if (activeSegment?.dataset.id === 'lead-out') {
+      return 'lead-out';
+    }
     if (!activeSegment?.dataset.segmentYearMonth) {
       return undefined;
     }
@@ -215,7 +219,22 @@
     }
     return null;
   });
-  const scrollHoverLabel = $derived(scrollSegment?.dateFormatted || '');
+  const scrollHoverLabel = $derived.by(() => {
+    if (scrollY !== undefined) {
+      if (scrollY < relativeTopOffset) {
+        return segments.at(0)?.dateFormatted;
+      } else {
+        let offset = relativeTopOffset;
+        for (const segment of segments) {
+          offset += segment.height;
+        }
+        if (scrollY > offset) {
+          return segments.at(-1)?.dateFormatted;
+        }
+      }
+    }
+    return scrollSegment?.dateFormatted || '';
+  });
 
   const findElementBestY = (elements: Element[], y: number, ...ids: string[]) => {
     if (ids.length === 0) {
@@ -308,38 +327,23 @@
     isHoverOnPaddingTop = isOnPaddingTop;
     isHoverOnPaddingBottom = isOnPaddingBottom;
 
-    const scrollPercent = toTimelineY(hoverY);
+    const scrubData = {
+      scrubberMonth: segmentDate,
+      overallScrollPercent: toTimelineY(hoverY),
+      scrubberMonthScrollPercent: monthGroupPercentY,
+    };
     if (wasDragging === false && isDragging) {
-      void startScrub?.({
-        scrubberMonth: segmentDate!,
-        overallScrollPercent: scrollPercent,
-        scrubberMonthScrollPercent: monthGroupPercentY,
-      });
-      void onScrub?.({
-        scrubberMonth: segmentDate!,
-        overallScrollPercent: scrollPercent,
-        scrubberMonthScrollPercent: monthGroupPercentY,
-      });
+      void startScrub?.(scrubData);
+      void onScrub?.(scrubData);
     }
-
     if (wasDragging && !isDragging) {
-      void stopScrub?.({
-        scrubberMonth: segmentDate!,
-        overallScrollPercent: scrollPercent,
-        scrubberMonthScrollPercent: monthGroupPercentY,
-      });
+      void stopScrub?.(scrubData);
       return;
     }
-
     if (!isDragging) {
       return;
     }
-
-    void onScrub?.({
-      scrubberMonth: segmentDate!,
-      overallScrollPercent: scrollPercent,
-      scrubberMonthScrollPercent: monthGroupPercentY,
-    });
+    void onScrub?.(scrubData);
   };
   const getTouch = (event: TouchEvent) => {
     if (event.touches.length === 1) {
@@ -559,13 +563,8 @@
     class="relative"
     style:height={relativeTopOffset + 'px'}
     data-id="lead-in"
-    data-segment-year-month={segments.at(0)?.year + '-' + segments.at(0)?.month}
     data-label={segments.at(0)?.dateFormatted}
-  >
-    {#if relativeTopOffset > 6}
-      <div class="absolute end-3 h-[4px] w-[4px] rounded-full bg-gray-300"></div>
-    {/if}
-  </div>
+  ></div>
   <!-- Time Segment -->
   {#each segments as segment (segment.year + '-' + segment.month)}
     <div
@@ -587,5 +586,10 @@
       {/if}
     </div>
   {/each}
-  <div data-id="lead-out" class="relative" style:height={relativeBottomOffset + 'px'}></div>
+  <div
+    data-id="lead-out"
+    class="relative"
+    style:height={relativeBottomOffset + 'px'}
+    data-label={segments.at(-1)?.dateFormatted}
+  ></div>
 </div>
diff --git a/web/src/lib/components/timeline/Timeline.svelte b/web/src/lib/components/timeline/Timeline.svelte
index 74e6ac67ae..ed6e5c2eb4 100644
--- a/web/src/lib/components/timeline/Timeline.svelte
+++ b/web/src/lib/components/timeline/Timeline.svelte
@@ -12,14 +12,14 @@
   import type { DayGroup } from '$lib/managers/timeline-manager/day-group.svelte';
   import type { MonthGroup } from '$lib/managers/timeline-manager/month-group.svelte';
   import { TimelineManager } from '$lib/managers/timeline-manager/timeline-manager.svelte';
-  import type { TimelineAsset } from '$lib/managers/timeline-manager/types';
+  import type { TimelineAsset, ViewportTopMonth } from '$lib/managers/timeline-manager/types';
   import { assetsSnapshot } from '$lib/managers/timeline-manager/utils.svelte';
   import type { AssetInteraction } from '$lib/stores/asset-interaction.svelte';
   import { assetViewingStore } from '$lib/stores/asset-viewing.store';
   import { isSelectingAllAssets } from '$lib/stores/assets-store.svelte';
   import { mobileDevice } from '$lib/stores/mobile-device.svelte';
   import { navigate } from '$lib/utils/navigation';
-  import { getTimes, type ScrubberListener, type TimelineYearMonth } from '$lib/utils/timeline-util';
+  import { getTimes, type ScrubberListener } from '$lib/utils/timeline-util';
   import { type AlbumResponseDto, type PersonResponseDto } from '@immich/sdk';
   import { DateTime } from 'luxon';
   import { onMount, type Snippet } from 'svelte';
@@ -97,16 +97,11 @@
   // Note: There may be multiple months visible within the viewport at any given time.
   let viewportTopMonthScrollPercent = $state(0);
   // The timeline month intersecting the top position of the viewport
-  let viewportTopMonth: { year: number; month: number } | undefined = $state(undefined);
+  let viewportTopMonth: ViewportTopMonth = $state(undefined);
   // Overall scroll percentage through the entire timeline (0-1)
   let timelineScrollPercent: number = $state(0);
   let scrubberWidth = $state(0);
 
-  // 60 is the bottom spacer element at 60px
-  let bottomSectionHeight = 60;
-  // Indicates whether the viewport is currently in the lead-out section (after all months)
-  let isInLeadOutSection = $state(false);
-
   const isEmpty = $derived(timelineManager.isInitialized && timelineManager.months.length === 0);
   const maxMd = $derived(mobileDevice.maxMd);
   const usingMobileDevice = $derived(mobileDevice.pointerCoarse);
@@ -230,41 +225,36 @@
     }
   });
 
-  const getMaxScrollPercent = () => {
-    const totalHeight = timelineManager.timelineHeight + bottomSectionHeight + timelineManager.topSectionHeight;
-    return (totalHeight - timelineManager.viewportHeight) / totalHeight;
-  };
-
-  const getMaxScroll = () => {
-    if (!scrollableElement || !timelineElement) {
-      return 0;
-    }
-    return (
-      timelineManager.topSectionHeight +
-      bottomSectionHeight +
-      (timelineElement.clientHeight - scrollableElement.clientHeight)
-    );
-  };
-
-  const scrollToMonthGroupAndOffset = (monthGroup: MonthGroup, monthGroupScrollPercent: number) => {
-    const topOffset = monthGroup.top;
-    const maxScrollPercent = getMaxScrollPercent();
-    const delta = monthGroup.height * monthGroupScrollPercent;
+  const scrollToSegmentPercentage = (segmentTop: number, segmentHeight: number, monthGroupScrollPercent: number) => {
+    const topOffset = segmentTop;
+    const maxScrollPercent = timelineManager.maxScrollPercent;
+    const delta = segmentHeight * monthGroupScrollPercent;
     const scrollToTop = (topOffset + delta) * maxScrollPercent;
 
     timelineManager.scrollTo(scrollToTop);
   };
-
   // note: don't throttle, debounce, or otherwise make this function async - it causes flicker
   // this function scrolls the timeline to the specified month group and offset, based on scrubber interaction
   const onScrub: ScrubberListener = (scrubberData) => {
     const { scrubberMonth, overallScrollPercent, scrubberMonthScrollPercent } = scrubberData;
 
-    if (!scrubberMonth || timelineManager.timelineHeight < timelineManager.viewportHeight * 2) {
+    const leadIn = scrubberMonth === 'lead-in';
+    const leadOut = scrubberMonth === 'lead-out';
+    const noMonth = !scrubberMonth;
+
+    if (noMonth || timelineManager.limitedScroll) {
       // edge case - scroll limited due to size of content, must adjust - use use the overall percent instead
-      const maxScroll = getMaxScroll();
-      const offset = maxScroll * overallScrollPercent;
+      const maxScroll = timelineManager.maxScrollPercent;
+      const offset = maxScroll * overallScrollPercent * timelineManager.totalViewerHeight;
       timelineManager.scrollTo(offset);
+    } else if (leadIn) {
+      scrollToSegmentPercentage(0, timelineManager.topSectionHeight, scrubberMonthScrollPercent);
+    } else if (leadOut) {
+      scrollToSegmentPercentage(
+        timelineManager.topSectionHeight + timelineManager.assetsHeight,
+        timelineManager.bottomSectionHeight,
+        scrubberMonthScrollPercent,
+      );
     } else {
       const monthGroup = timelineManager.months.find(
         ({ yearMonth: { year, month } }) => year === scrubberMonth.year && month === scrubberMonth.month,
@@ -272,50 +262,41 @@
       if (!monthGroup) {
         return;
       }
-      scrollToMonthGroupAndOffset(monthGroup, scrubberMonthScrollPercent);
+      scrollToSegmentPercentage(monthGroup.top, monthGroup.height, scrubberMonthScrollPercent);
     }
   };
 
   // note: don't throttle, debounch, or otherwise make this function async - it causes flicker
   const handleTimelineScroll = () => {
-    isInLeadOutSection = false;
-
     if (!scrollableElement) {
       return;
     }
 
-    if (timelineManager.timelineHeight < timelineManager.viewportHeight * 2) {
+    if (timelineManager.limitedScroll) {
       // edge case - scroll limited due to size of content, must adjust -  use the overall percent instead
-      const maxScroll = getMaxScroll();
-      timelineScrollPercent = Math.min(1, scrollableElement.scrollTop / maxScroll);
+      const maxScroll = timelineManager.maxScroll;
 
+      timelineScrollPercent = Math.min(1, scrollableElement.scrollTop / maxScroll);
       viewportTopMonth = undefined;
       viewportTopMonthScrollPercent = 0;
     } else {
+      timelineScrollPercent = 0;
+
       let top = scrollableElement.scrollTop;
-      if (top < timelineManager.topSectionHeight) {
-        // in the lead-in area
-        viewportTopMonth = undefined;
-        viewportTopMonthScrollPercent = 0;
-        const maxScroll = getMaxScroll();
-
-        timelineScrollPercent = Math.min(1, scrollableElement.scrollTop / maxScroll);
-        return;
-      }
-
-      let maxScrollPercent = getMaxScrollPercent();
-      let found = false;
+      let maxScrollPercent = timelineManager.maxScrollPercent;
 
       const monthsLength = timelineManager.months.length;
       for (let i = -1; i < monthsLength + 1; i++) {
-        let monthGroup: TimelineYearMonth | undefined;
+        let monthGroup: ViewportTopMonth;
         let monthGroupHeight = 0;
         if (i === -1) {
           // lead-in
+          monthGroup = 'lead-in';
           monthGroupHeight = timelineManager.topSectionHeight;
         } else if (i === monthsLength) {
           // lead-out
-          monthGroupHeight = bottomSectionHeight;
+          monthGroup = 'lead-out';
+          monthGroupHeight = timelineManager.bottomSectionHeight;
         } else {
           monthGroup = timelineManager.months[i].yearMonth;
           monthGroupHeight = timelineManager.months[i].height;
@@ -334,18 +315,10 @@
             viewportTopMonth = timelineManager.months[i + 1].yearMonth;
             viewportTopMonthScrollPercent = 0;
           }
-
-          found = true;
           break;
         }
         top = next;
       }
-      if (!found) {
-        isInLeadOutSection = true;
-        viewportTopMonth = undefined;
-        viewportTopMonthScrollPercent = 0;
-        timelineScrollPercent = 1;
-      }
     }
   };
 
@@ -540,8 +513,7 @@
     {timelineManager}
     height={timelineManager.viewportHeight}
     timelineTopOffset={timelineManager.topSectionHeight}
-    timelineBottomOffset={bottomSectionHeight}
-    {isInLeadOutSection}
+    timelineBottomOffset={timelineManager.bottomSectionHeight}
     {timelineScrollPercent}
     {viewportTopMonthScrollPercent}
     {viewportTopMonth}
@@ -580,7 +552,7 @@
     bind:this={timelineElement}
     id="virtual-timeline"
     class:invisible
-    style:height={timelineManager.timelineHeight + 'px'}
+    style:height={timelineManager.totalViewerHeight + 'px'}
   >
     <section
       use:resizeObserver={topSectionResizeObserver}
@@ -636,11 +608,11 @@
     {/each}
     <!-- spacer for leadout -->
     <div
-      class="h-[60px]"
+      style:height={timelineManager.bottomSectionHeight + 'px'}
       style:position="absolute"
       style:left="0"
       style:right="0"
-      style:transform={`translate3d(0,${timelineManager.timelineHeight}px,0)`}
+      style:transform={`translate3d(0,${timelineManager.topSectionHeight + timelineManager.assetsHeight}px,0)`}
     ></div>
   </section>
 </section>
diff --git a/web/src/lib/managers/timeline-manager/timeline-manager.svelte.spec.ts b/web/src/lib/managers/timeline-manager/timeline-manager.svelte.spec.ts
index 7c448331ff..c9ac596e34 100644
--- a/web/src/lib/managers/timeline-manager/timeline-manager.svelte.spec.ts
+++ b/web/src/lib/managers/timeline-manager/timeline-manager.svelte.spec.ts
@@ -90,7 +90,7 @@ describe('TimelineManager', () => {
     });
 
     it('calculates timeline height', () => {
-      expect(timelineManager.timelineHeight).toBe(12_447.5);
+      expect(timelineManager.totalViewerHeight).toBe(12_507.5);
     });
   });
 
diff --git a/web/src/lib/managers/timeline-manager/timeline-manager.svelte.ts b/web/src/lib/managers/timeline-manager/timeline-manager.svelte.ts
index 23cf677b40..6b4de52467 100644
--- a/web/src/lib/managers/timeline-manager/timeline-manager.svelte.ts
+++ b/web/src/lib/managers/timeline-manager/timeline-manager.svelte.ts
@@ -48,7 +48,9 @@ export class TimelineManager {
   isInitialized = $state(false);
   months: MonthGroup[] = $state([]);
   topSectionHeight = $state(0);
-  timelineHeight = $derived(this.months.reduce((accumulator, b) => accumulator + b.height, 0) + this.topSectionHeight);
+  bottomSectionHeight = $state(60);
+  assetsHeight = $derived(this.months.reduce((accumulator, b) => accumulator + b.height, 0));
+  totalViewerHeight = $derived(this.topSectionHeight + this.assetsHeight + this.bottomSectionHeight);
   assetCount = $derived(this.months.reduce((accumulator, b) => accumulator + b.assetsCount, 0));
 
   albumAssets: Set<string> = new SvelteSet();
@@ -62,6 +64,7 @@ export class TimelineManager {
     top: this.#scrollTop,
     bottom: this.#scrollTop + this.viewportHeight,
   }));
+  limitedScroll = $derived(this.maxScrollPercent < 0.5);
 
   initTask = new CancellableTask(
     () => {
@@ -383,7 +386,9 @@ export class TimelineManager {
       updateGeometry(this, month, { invalidateHeight: changedWidth });
     }
     this.updateIntersections();
-    this.#createScrubberMonths();
+    if (changedWidth) {
+      this.#createScrubberMonths();
+    }
   }
 
   #createScrubberMonths() {
@@ -394,7 +399,7 @@ export class TimelineManager {
       title: month.monthGroupTitle,
       height: month.height,
     }));
-    this.scrubberTimelineHeight = this.timelineHeight;
+    this.scrubberTimelineHeight = this.totalViewerHeight;
   }
 
   createLayoutOptions() {
@@ -408,6 +413,16 @@ export class TimelineManager {
     };
   }
 
+  get maxScrollPercent() {
+    const totalHeight = this.totalViewerHeight;
+    const max = (totalHeight - this.viewportHeight) / totalHeight;
+    return max;
+  }
+
+  get maxScroll() {
+    return this.totalViewerHeight - this.viewportHeight;
+  }
+
   async loadMonthGroup(yearMonth: TimelineYearMonth, options?: { cancelable: boolean }): Promise<void> {
     let cancelable = true;
     if (options) {
diff --git a/web/src/lib/managers/timeline-manager/types.ts b/web/src/lib/managers/timeline-manager/types.ts
index fea62084b2..27c27dcb63 100644
--- a/web/src/lib/managers/timeline-manager/types.ts
+++ b/web/src/lib/managers/timeline-manager/types.ts
@@ -1,6 +1,8 @@
-import type { TimelineDate, TimelineDateTime } from '$lib/utils/timeline-util';
+import type { TimelineDate, TimelineDateTime, TimelineYearMonth } from '$lib/utils/timeline-util';
 import type { AssetStackResponseDto, AssetVisibility } from '@immich/sdk';
 
+export type ViewportTopMonth = TimelineYearMonth | undefined | 'lead-in' | 'lead-out';
+
 export type AssetApiGetTimeBucketsRequest = Parameters<typeof import('@immich/sdk').getTimeBuckets>[0];
 
 export type TimelineManagerOptions = Omit<AssetApiGetTimeBucketsRequest, 'size'> & {
diff --git a/web/src/lib/utils/timeline-util.ts b/web/src/lib/utils/timeline-util.ts
index 80cac0b738..673b929a1c 100644
--- a/web/src/lib/utils/timeline-util.ts
+++ b/web/src/lib/utils/timeline-util.ts
@@ -1,4 +1,4 @@
-import type { TimelineAsset } from '$lib/managers/timeline-manager/types';
+import type { TimelineAsset, ViewportTopMonth } from '$lib/managers/timeline-manager/types';
 import { locale } from '$lib/stores/preferences.store';
 import { getAssetRatio } from '$lib/utils/asset-utils';
 import { AssetTypeEnum, type AssetResponseDto } from '@immich/sdk';
@@ -24,7 +24,7 @@ export type TimelineDateTime = TimelineDate & {
 };
 
 export type ScrubberListener = (scrubberData: {
-  scrubberMonth: { year: number; month: number };
+  scrubberMonth: ViewportTopMonth;
   overallScrollPercent: number;
   scrubberMonthScrollPercent: number;
 }) => void | Promise<void>;