From 83ab2f92246d02b9ba293a0026027cd15e60b86d Mon Sep 17 00:00:00 2001
From: Sudev Kiyada <sudev.kiyada@thomsonreuters.com>
Date: Fri, 9 Jan 2026 11:54:55 +0530
Subject: [PATCH] Get rid of ClampedProgress

---
 .../HorizontalScroller/Debug.svelte           |  61 +++++++--
 .../HorizontalScroller/HorizontalScroller.mdx |   2 +
 .../HorizontalScroller.stories.svelte         |  12 +-
 .../HorizontalScroller.svelte                 | 124 ++++++++----------
 .../demo/DemoSnippet.svelte                   |   4 +-
 5 files changed, 115 insertions(+), 88 deletions(-)

diff --git a/src/components/HorizontalScroller/Debug.svelte b/src/components/HorizontalScroller/Debug.svelte
index d24e01e5..c6b5be70 100644
--- a/src/components/HorizontalScroller/Debug.svelte
+++ b/src/components/HorizontalScroller/Debug.svelte
@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { map } from './utils';
+
   const { componentState } = $props();
 
   let isMoving = $state(false);
@@ -43,6 +45,36 @@
     }
     isMoving = false;
   }
+
+  let normalisedScrollProgress = $derived(
+    map(
+      componentState.scrollProgress,
+      componentState.clampStart ?? 0,
+      componentState.clampEnd ?? 1,
+      0,
+      1
+    )
+  );
+
+  let normalisedProgress = $derived(
+    map(
+      componentState.progress,
+      componentState.clampStart ?? 0,
+      componentState.clampEnd ?? 1,
+      0,
+      1
+    )
+  );
+
+  function mappedStop(stop: number): number {
+    return map(
+      stop,
+      componentState.clampStart ?? 0,
+      componentState.clampEnd ?? 1,
+      0,
+      1
+    );
+  }
 </script>
 
 <svelte:window onmousemove={onMouseMove} />
@@ -58,11 +90,12 @@
         >
       {/each}
     {:else}
-      {#each componentState.triggerStops as stop, index}
-        {#if index < componentState.triggerStops.length - 1}
+      {@const stops = componentState.triggerStops.map((x) => mappedStop(x))}
+      {#each stops as stop, index}
+        {#if index < stops.length - 1}
           <span
             class="stops"
-            style={`left: ${(stop + (componentState.triggerStops[index + 1] ?? componentState.triggerStops[componentState.triggerStops.length - 1])) * 0.5 * 100}%;`}
+            style={`left: ${(stop + (stops[index + 1] ?? stops[stops.length - 1])) * 0.5 * 100}%;`}
             >|</span
           >
         {/if}
@@ -86,6 +119,14 @@
       CONSOLE
     </summary>
     <div class="state-debug">
+      <!--  -->
+      <p>Raw progress:</p>
+      <div style="display: flex; flex-direction: column; gap: 4px;">
+        <p class="state-value">
+          <span class="tag">{componentState.rawProgress}</span>
+        </p>
+      </div>
+      <!--  -->
       <!--  -->
       <p>Scroll progress:</p>
       <div style="display: flex; flex-direction: column; gap: 4px;">
@@ -93,14 +134,14 @@
           {@render triggerPoints()}
           <span
             class="progress-stop"
-            style={`left: ${componentState.scrollProgress * 100}%; transform: translateX(-50%);`}
+            style={`left: ${normalisedScrollProgress * 100}%; transform: translateX(-50%);`}
             >{fmt.format(componentState.scrollProgress)}</span
           >
           &nbsp;
         </p>
         <div id="video-progress-bar">
           <div
-            style="width: {componentState.scrollProgress * 100}%; height: 100%;"
+            style="width: {normalisedScrollProgress * 100}%; height: 100%;"
           ></div>
         </div>
       </div>
@@ -110,20 +151,20 @@
         <p class="state-value progress-value">
           {#if componentState.stops.length > 0}
             {#each componentState.stops as stop}
-              <span class="stops" style={`left: ${stop * 100}%;`}>{stop}</span>
+              <span class="stops" style={`left: ${mappedStop(stop) * 100}%;`}
+                >{stop}</span
+              >
             {/each}
           {/if}
           <span
             class="progress-stop"
-            style={`left: ${componentState.progress * 100}%; transform: translateX(-50%);`}
+            style={`left: ${normalisedProgress * 100}%; transform: translateX(-50%);`}
             >{fmt.format(componentState.progress)}</span
           >
           &nbsp;
         </p>
         <div id="video-progress-bar">
-          <div
-            style="width: {componentState.progress * 100}%; height: 100%;"
-          ></div>
+          <div style="width: {normalisedProgress * 100}%; height: 100%;"></div>
         </div>
       </div>
       <!--  -->
diff --git a/src/components/HorizontalScroller/HorizontalScroller.mdx b/src/components/HorizontalScroller/HorizontalScroller.mdx
index 8a75c884..55b78b41 100644
--- a/src/components/HorizontalScroller/HorizontalScroller.mdx
+++ b/src/components/HorizontalScroller/HorizontalScroller.mdx
@@ -18,6 +18,8 @@ To use the `HorizontalScroller` component, import it and provide the children co
 
 > 💡TIP: Use `lvh` or `svh` units instead of `vh` unit for the height, as [these units](https://www.w3.org/TR/css-values-4/#large-viewport-size) are more reliable on mobile or other devices where elements such as the address bar toggle between being shown and hidden.
 
+Use `showDebugInfo` prop to visualize the scroll progress and other useful debug information. The `Raw progress` indicates the vertical progress with values in the range 0...1 indicating the content being locked. The `Scroll Progress` value indicates the vertical progress mapped to clampStart and clampEnd values. By default these are 0 and 1 respectively. Finally, the `Progress` value indicates the horizontal scroll progress after applying stops and easing (if any).
+
 [Demo](?path=/story/components-graphics-horizontalscroller--demo)
 
 ```svelte
diff --git a/src/components/HorizontalScroller/HorizontalScroller.stories.svelte b/src/components/HorizontalScroller/HorizontalScroller.stories.svelte
index f494b6a1..1e58a827 100644
--- a/src/components/HorizontalScroller/HorizontalScroller.stories.svelte
+++ b/src/components/HorizontalScroller/HorizontalScroller.stories.svelte
@@ -45,14 +45,16 @@
 </Story>
 
 <Story
-  name="Extended demo"
+  name="Extended boundaries"
   args={{
     children: DemoSnippet,
     height: '200lvh',
-    clampedProgress: true,
-    clampStart: -1,
-    clampEnd: 2,
+    clampStart: -0.5,
+    clampEnd: 1.5,
     showDebugInfo: true,
+    scrubbed: true,
+    stops: [0, 1],
+    easing: quartInOut,
   }}
 >
   {#snippet children(args)}
@@ -67,7 +69,7 @@
     height: '200lvh',
     stops: [0.2, 0.5, 0.6, 0.7],
     duration: 400,
-    scrubbed: false,
+    scrubbed: true,
     easing: quartInOut,
     showDebugInfo: true,
     direction: 'left',
diff --git a/src/components/HorizontalScroller/HorizontalScroller.svelte b/src/components/HorizontalScroller/HorizontalScroller.svelte
index 47693b8a..4664d5a8 100644
--- a/src/components/HorizontalScroller/HorizontalScroller.svelte
+++ b/src/components/HorizontalScroller/HorizontalScroller.svelte
@@ -1,5 +1,5 @@
 <script lang="ts">
-  import { type Snippet } from 'svelte';
+  import { onMount, type Snippet } from 'svelte';
   import { Tween } from 'svelte/motion';
   import type { Action } from 'svelte/action';
   import { clamp, map } from './utils/index';
@@ -30,31 +30,18 @@
     duration?: number;
     /** Whether to show debug info */
     showDebugInfo?: boolean;
-  }
-
-  interface ClampedProps extends Props {
-    /** Whether the progress value should be clamped */
-    clampedProgress: true;
-    /** Start value for clamping. Only effective when clampedProgress is true. */
+    /** Modified starting scale. Default is 0 */
     clampStart?: number;
-    /** End value for clamping. Only effective when clampedProgress is true. */
+    /** Modified ending scale. Default is 1 */
     clampEnd?: number;
   }
 
-  interface UnclampedProps extends Props {
-    /** Whether the progress value should be clamped */
-    clampedProgress?: false;
-    clampStart?: never;
-    clampEnd?: never;
-  }
-
   let {
     id = '',
     class: cls = '',
     height = '200lvh',
     direction = 'right',
     scrollProgress = $bindable(0),
-    clampedProgress = true,
     clampStart = 0,
     clampEnd = 1,
     children,
@@ -64,24 +51,25 @@
     easing: ease = (t) => t,
     duration = 400,
     showDebugInfo = false,
-  }: ClampedProps | UnclampedProps = $props();
+  }: Props = $props();
 
   let componentState = $derived.by(() => ({
     scrollProgress,
     progress: progressTween.current,
     direction,
-    clampedProgress,
     clampStart,
     clampEnd,
-    triggerStops: scrubbed ? stops : unscrubbedStops,
+    triggerStops: scrubbed ? stops : divisions,
     stops: stops,
     handleScroll,
     scrubbed,
     easing: ease,
     duration,
+    rawProgress,
   }));
+
   let progressTween: Tween<number> = $state(
-    new Tween(0, { duration, easing: ease })
+    new Tween(clampStart, { duration, easing: ease })
   );
   let container: HTMLDivElement | undefined = $state(undefined);
   let containerHeight: number = $state(0);
@@ -89,108 +77,101 @@
   let content: HTMLDivElement | undefined = $state(undefined);
   let contentWidth: number = $state(0);
   let screenHeight: number = $state(0);
-  let unscrubbedStops: number[] = $derived(
-    [...stops, 0, 1].sort((a, b) => a - b)
-  );
   let divisions: number[] = $derived(
-    [...stops, clampStart ?? 0, clampEnd ?? 1].sort((a, b) => a - b)
+    [...stops, clampStart, clampEnd].sort((a, b) => a - b)
   );
   let divisionsCount: number = $derived.by(() => divisions.length - 1);
 
-  let translateX: number = $derived.by(() => {
-    let processedProgress = progressTween.current;
-    let normalisedProgress = processedProgress;
-    if (clampedProgress) {
-      processedProgress = Math.min(
-        Math.max(progressTween.current, clampStart),
-        clampEnd
-      );
+  let rawProgress: number | 'user defined' = $state(0);
 
-      processedProgress = map(processedProgress, 0, 1, clampStart, clampEnd);
-      normalisedProgress =
-        direction === 'right' ? processedProgress : (
-          clampEnd - processedProgress
-        );
-    } else {
-      normalisedProgress =
-        direction === 'right' ? processedProgress : 1 - processedProgress;
-    }
+  // handles horizontal translation of the content
+  let translateX: number = $derived.by(() => {
+    let processedProgress = clamp(progressTween.current, clampStart, clampEnd);
+    let normalisedProgress = processedProgress;
+
+    normalisedProgress =
+      direction === 'right' ? processedProgress : clampEnd - processedProgress;
 
     const translate = -(contentWidth - containerWidth) * normalisedProgress;
 
     return translate;
   });
 
+  onMount(() => {
+    // Initialize scrollProgress to clampStart on mount
+    scrollProgress = clampStart;
+  });
+
   const scrollListener: Action = () => {
     if (handleScroll) {
       window.addEventListener('scroll', handleScrollFunction, {
         passive: true,
       });
     } else {
+      // set rawProgress to user defined when handleScroll is false
+      rawProgress = 'user defined';
       window.addEventListener('scroll', () => handleStops(scrollProgress), {
         passive: true,
       });
     }
   };
 
+  // calculates distance scrolled inside the container
   function handleScrollFunction() {
     if (!container) return;
 
-    const rawProgress =
+    rawProgress =
       (-container?.offsetTop + window?.scrollY) /
       (containerHeight - screenHeight);
 
     handleStops(rawProgress);
   }
 
+  // updates progressTween based on stops and scrubbed settings
   function handleStops(rawProgress: number) {
-    scrollProgress =
-      clampedProgress ? clamp(rawProgress, clampStart, clampEnd) : rawProgress;
+    scrollProgress = map(rawProgress, 0, 1, clampStart, clampEnd);
+
     if (!stops || stops.length === 0) {
-      progressTween.set(ease(clamp(rawProgress, 0, 1)), {
+      progressTween.set(ease(map(rawProgress, 0, 1, clampStart, clampEnd)), {
         duration: 0,
       });
       return;
     }
 
     if (!scrubbed) {
-      for (let i = 0; i < unscrubbedStops.length; i++) {
+      for (let i = 0; i < divisions.length; i++) {
         if (
-          rawProgress > unscrubbedStops[i] &&
-          rawProgress <=
-            (unscrubbedStops[i + 1] ??
-              unscrubbedStops[unscrubbedStops.length - 1])
+          scrollProgress > divisions[i] &&
+          scrollProgress <=
+            (divisions[i + 1] ?? divisions[divisions.length - 1])
         ) {
           const midPoint =
-            unscrubbedStops[i] +
-            ((unscrubbedStops[i + 1] ??
-              unscrubbedStops[unscrubbedStops.length - 1]) -
-              unscrubbedStops[i]) *
+            divisions[i] +
+            ((divisions[i + 1] ?? divisions[divisions.length - 1]) -
+              divisions[i]) *
               0.5;
           if (
-            rawProgress >= midPoint &&
+            scrollProgress >= midPoint &&
             progressTween.target !==
-              (unscrubbedStops[i + 1] ??
-                unscrubbedStops[unscrubbedStops.length - 1])
+              (divisions[i + 1] ?? divisions[divisions.length - 1])
           ) {
             progressTween.set(
-              unscrubbedStops[i + 1] ??
-                unscrubbedStops[unscrubbedStops.length - 1]
+              divisions[i + 1] ?? divisions[divisions.length - 1]
             );
             return;
           } else if (
-            rawProgress < midPoint &&
-            progressTween.target !== unscrubbedStops[i]
+            scrollProgress < midPoint &&
+            progressTween.target !== divisions[i]
           ) {
-            progressTween.set(unscrubbedStops[i]);
+            progressTween.set(divisions[i]);
             return;
           }
         } else if (
-          rawProgress <
-          unscrubbedStops[0] + (unscrubbedStops[1] ?? 0) * 0.5
+          scrollProgress <
+          divisions[0] + (divisions[1] ?? clampStart) * 0.5
         ) {
-          if (progressTween.target !== unscrubbedStops[0]) {
-            progressTween.set(unscrubbedStops[0]);
+          if (progressTween.target !== divisions[0]) {
+            progressTween.set(divisions[0]);
             return;
           }
         } else {
@@ -201,15 +182,16 @@
       for (let i = 0; i < divisions.length; i++) {
         let oneByDivCount = 1 / divisionsCount;
 
-        let normalStart = i == 0 ? 0 : oneByDivCount * i;
-        let normalEnd = i == divisionsCount - 1 ? 1 : oneByDivCount * (i + 1);
+        let normalStart = i == 0 ? clampStart : oneByDivCount * i;
+        let normalEnd =
+          i == divisionsCount - 1 ? clampEnd : oneByDivCount * (i + 1);
 
-        if (rawProgress >= normalStart && rawProgress < normalEnd) {
+        if (scrollProgress >= normalStart && scrollProgress < normalEnd) {
           let stopStart = divisions[i];
-          let stopEnd = divisions[i + 1] ?? 1;
+          let stopEnd = divisions[i + 1] ?? clampEnd;
           let newProgressVal =
             stopStart +
-            ease(map(rawProgress, normalStart, normalEnd, 0, 1)) *
+            ease(map(scrollProgress, normalStart, normalEnd, 0, 1)) *
               (stopEnd - stopStart);
 
           progressTween.set(newProgressVal, { duration: 0 });
diff --git a/src/components/HorizontalScroller/demo/DemoSnippet.svelte b/src/components/HorizontalScroller/demo/DemoSnippet.svelte
index c03c1ff7..62f27205 100644
--- a/src/components/HorizontalScroller/demo/DemoSnippet.svelte
+++ b/src/components/HorizontalScroller/demo/DemoSnippet.svelte
@@ -1,7 +1,7 @@
-<div style="width: 400vw; height: 100lvh; border: 2px solid red;">
+<div style="width: 400vw; height: 100lvh;">
   <img
     src="https://picsum.photos/1200/640?t=1"
     alt="Sample"
-    style="width: 100%; height: 100%; object-fit: cover; padding: 0; margin: 0;"
+    style="width: 100%; height: 100%; object-fit: cover; padding: 0; margin: 0; background-color: #ccc;"
   />
 </div>