@rethink-js/rt-slider 1.2.0 → 1.2.1

package/README.md

@@ -14,7 +14,7 @@
 - Support for **multiple instances**
 - A clean global API under `window.rtSlider`
 - Defensive fallbacks to native scrolling on mobile
-- Built-in **slide state tracking**, DOM attributes, and custom events for advanced UI sync
+- Built-in **slide state tracking**, **scroll progress tracking**, DOM attributes, and custom events for advanced UI sync
 
 **Primary dependency (GitHub):** <https://github.com/darkroomengineering/lenis>
 
@@ -63,7 +63,7 @@ Add the script to your page. To create a slider, add the `data-rt-slider` attrib
 - Auto-initialize on DOM ready
 - Load Lenis dynamically for desktop inertia
 - Apply native touch scrolling styles for mobile
-- Compute active slide state and progress automatically
+- Compute active slide state and overall scroll progress automatically
 - Expose slider state through attributes, events, and the global API
 
 Example:
@@ -192,9 +192,13 @@ As the slider moves, `rt-slider` writes state back to the DOM automatically.
 | `data-rt-slider-to-index`                 | Current segment end slide index            |
 | `data-rt-slider-segment-progress`         | Current segment progress from `0` to `1`   |
 | `data-rt-slider-segment-progress-percent` | Current segment progress from `0` to `100` |
+| `data-rt-slider-scroll-current`           | Current clamped horizontal scroll position |
+| `data-rt-slider-scroll-max`               | Maximum horizontal scroll position         |
 | `data-rt-slider-scroll-progress`          | Overall slider progress from `0` to `1`    |
 | `data-rt-slider-scroll-progress-percent`  | Overall slider progress from `0` to `100`  |
 | `data-rt-slider-scroll-direction`         | `forward`, `backward`, or `none`           |
+| `data-rt-slider-scroll-at-start`          | `true` when the slider is at the start     |
+| `data-rt-slider-scroll-at-end`            | `true` when the slider is at the end       |
 
 #### Per-item attributes
 
@@ -212,7 +216,7 @@ As the slider moves, `rt-slider` writes state back to the DOM automatically.
 | `data-rt-slider-item-anchor-progress-percent` | This slide's anchor position from `0` to `100`                             |
 | `data-rt-slider-item-distance`                | Distance in pixels from the current scroll position to this slide's anchor |
 
-These attributes are useful for CSS-driven animations, slide-aware UI, progress indicators, and syncing other interface elements to the slider.
+These attributes are useful for CSS-driven animations, slide-aware UI, progress indicators, edge-aware controls, and syncing other interface elements to the slider.
 
 ---
 
@@ -220,16 +224,21 @@ These attributes are useful for CSS-driven animations, slide-aware UI, progress
 
 Each slider instance dispatches events from the root element.
 
-| Event             | Description                                 |
-| ----------------- | ------------------------------------------- |
-| `rtSlider:slide`  | Fires when the computed slide state changes |
-| `rtSlider:active` | Fires when the active slide index changes   |
+| Event               | Description                                 |
+| ------------------- | ------------------------------------------- |
+| `rtSlider:progress` | Fires when computed scroll progress changes |
+| `rtSlider:slide`    | Fires when the computed slide state changes |
+| `rtSlider:active`   | Fires when the active slide index changes   |
 
 Example:
 
 ```js
 const slider = document.querySelector("[data-rt-slider]");
 
+slider.addEventListener("rtSlider:progress", function (event) {
+  console.log("Progress:", event.detail.progress);
+});
+
 slider.addEventListener("rtSlider:slide", function (event) {
   console.log(event.detail);
 });
@@ -239,7 +248,9 @@ slider.addEventListener("rtSlider:active", function (event) {
 });
 ```
 
-Both events include a full cloned slide-state object in `event.detail`.
+`rtSlider:progress` includes a cloned scroll-state object in `event.detail`.
+
+`rtSlider:slide` and `rtSlider:active` include a full cloned slide-state object in `event.detail`.
 
 ---
 
@@ -261,7 +272,7 @@ Each instance:
 
 - Has its own independent scroll physics
 - Calculates its own progress bars and button states
-- Tracks its own active slide and segment state
+- Tracks its own active slide, segment state, and overall scroll progress
 - Dispatches its own custom events
 - Is registered internally with a unique ID
 
@@ -277,13 +288,15 @@ window.rtSlider;
 
 ### Common Methods
 
-| Method              | Description                                         |
-| ------------------- | --------------------------------------------------- |
-| `ids()`             | Returns an array of active slider IDs               |
-| `get(id)`           | Returns the slider instance object                  |
-| `getSlideState(id)` | Returns a cloned slide-state object for an instance |
-| `refresh()`         | Forces a recalculation of layout (all instances)    |
-| `destroy(id?)`      | Destroys specific instance or all if no ID given    |
+| Method               | Description                                          |
+| -------------------- | ---------------------------------------------------- |
+| `ids()`              | Returns an array of active slider IDs                |
+| `get(id)`            | Returns the slider instance object                   |
+| `getSlideState(id)`  | Returns a cloned slide-state object for an instance  |
+| `getScrollState(id)` | Returns a cloned scroll-state object for an instance |
+| `getProgress(id)`    | Returns overall slider progress from `0` to `1`      |
+| `refresh()`          | Forces a recalculation of layout (all instances)     |
+| `destroy(id?)`       | Destroys specific instance or all if no ID given     |
 
 Example usage:
 
@@ -291,9 +304,11 @@ Example usage:
 // Refresh layout after an AJAX load
 window.rtSlider.refresh();
 
-// Get computed slide state
+// Get computed state
 const ids = window.rtSlider.ids();
-const firstSliderState = window.rtSlider.getSlideState(ids[0]);
+const firstSliderSlideState = window.rtSlider.getSlideState(ids[0]);
+const firstSliderScrollState = window.rtSlider.getScrollState(ids[0]);
+const firstSliderProgress = window.rtSlider.getProgress(ids[0]);
 
 // Destroy a specific slider
 window.rtSlider.destroy("my-slider-id");
@@ -303,11 +318,13 @@ window.rtSlider.destroy("my-slider-id");
 
 When using `window.rtSlider.get(id)`, each instance also exposes helper methods:
 
-| Method               | Description                                           |
-| -------------------- | ----------------------------------------------------- |
-| `getSlideState()`    | Returns a cloned slide-state object for that instance |
-| `getActiveIndex()`   | Returns the current active slide index                |
-| `getActiveElement()` | Returns the current active slide element              |
+| Method               | Description                                            |
+| -------------------- | ------------------------------------------------------ |
+| `getSlideState()`    | Returns a cloned slide-state object for that instance  |
+| `getScrollState()`   | Returns a cloned scroll-state object for that instance |
+| `getProgress()`      | Returns overall slider progress from `0` to `1`        |
+| `getActiveIndex()`   | Returns the current active slide index                 |
+| `getActiveElement()` | Returns the current active slide element               |
 
 ---
 
@@ -342,11 +359,17 @@ It does not rely on console output during normal use. If initialization fails, t
 - Ensure the slider is actually scrollable. If content does not overflow horizontally, active state will still resolve, but progress and movement-driven changes will be limited.
 - Ensure `data-rt-item` matches the actual slide elements and not a wrapper around them.
 
+### Progress not reaching `1` at the end
+
+- `rt-slider` uses edge-aware scroll detection and clamps progress to `1` when the visible viewport reaches the end of the slider.
+- If you are building custom progress indicators, use `window.rtSlider.getProgress(id)`, `window.rtSlider.getScrollState(id)`, or the `rtSlider:progress` event instead of deriving progress manually from raw DOM measurements.
+
 ### Custom events not firing as expected
 
+- `rtSlider:progress` fires when computed scroll progress changes.
 - `rtSlider:slide` fires when computed slide state changes.
 - `rtSlider:active` fires when the active slide changes.
-- Both events are dispatched from the element with `data-rt-slider`, not from the list or item elements.
+- All events are dispatched from the element with `data-rt-slider`, not from the list or item elements.
 
 ---
 
@@ -355,7 +378,7 @@ It does not rely on console output during normal use. If initialization fails, t
 MIT License
 
 Package: `@rethink-js/rt-slider` <br>
-GitHub: [https://github.com/Rethink-JS/rt-slider](https://github.com/Rethink-JS/rt-slider)
+GitHub: [https://github.com/Rethink-JS/rt-slider](https://github.com/Rethink-JS)
 
 ---
 

package/dist/index.js

@@ -1,4 +1,4 @@
-/*! @rethink-js/rt-slider v1.2.0 | MIT */
+/*! @rethink-js/rt-slider v1.2.1 | MIT */
 (() => {
   // src/index.js
   (function() {
@@ -317,6 +317,7 @@
       this._lastGapPx = 0;
       this.slideState = null;
       this._slideStateSig = "";
+      this._progressSig = "";
       this._lastSlideStateActiveIndex = -1;
       this._lastSlideStateScrollLeft = 0;
       var self = this;
@@ -336,6 +337,9 @@
       var dpr = Math.max(1, window.devicePixelRatio || 1);
       return 1 / dpr;
     };
+    Slider.prototype.scrollEdgeEpsilon = function() {
+      return Math.max(2, this.devicePixelEpsilon() * 4);
+    };
     Slider.prototype.listGap = function() {
       var cs = getComputedStyle(this.list);
       var g1 = parseFloat(cs.columnGap || "0") || 0;
@@ -436,6 +440,38 @@
     Slider.prototype.maxScroll = function() {
       return Math.max(0, this.scroller.scrollWidth - this.scroller.clientWidth);
     };
+    Slider.prototype.getLiveScrollMetrics = function() {
+      var scrollWidth = Math.max(0, this.scroller.scrollWidth || 0);
+      var clientWidth = Math.max(0, this.scroller.clientWidth || 0);
+      var max = Math.max(0, scrollWidth - clientWidth);
+      var current = this.safeClampScroll(this.scroller.scrollLeft);
+      var epsilon = this.scrollEdgeEpsilon();
+      if (max <= 0 || scrollWidth <= clientWidth + epsilon) {
+        return {
+          current: 0,
+          max: 0,
+          progress: 0,
+          progressPercent: 0,
+          isAtStart: true,
+          isAtEnd: true
+        };
+      }
+      var atStart = current <= epsilon;
+      var atEnd = current >= max - epsilon || current + clientWidth >= scrollWidth - epsilon;
+      if (atStart) current = 0;
+      if (atEnd) current = max;
+      var progress = max > 0 ? clamp(current / max) : 0;
+      if (atEnd) progress = 1;
+      if (atStart) progress = 0;
+      return {
+        current,
+        max,
+        progress,
+        progressPercent: progress * 100,
+        isAtStart: atStart,
+        isAtEnd: atEnd
+      };
+    };
     Slider.prototype.updateOverlays = function() {
       if (!this.overlayStart && !this.overlayEnd) return;
       var total = this.scroller.scrollWidth;
@@ -451,13 +487,9 @@
         setVis(this.overlayEnd, false);
         return;
       }
-      var m = this.maxScroll();
-      var current = this.scroller.scrollLeft;
-      var tolerance = 10;
-      var atStart = current <= tolerance;
-      var atEnd = current >= m - tolerance;
-      setVis(this.overlayStart, !atStart);
-      setVis(this.overlayEnd, !atEnd);
+      var metrics = this.getLiveScrollMetrics();
+      setVis(this.overlayStart, !metrics.isAtStart);
+      setVis(this.overlayEnd, !metrics.isAtEnd);
     };
     Slider.prototype.updateButtons = function() {
       if (!this.btnPrev && !this.btnNext) return;
@@ -477,17 +509,13 @@
       }
       if (this.btnPrev) this.btnPrev.style.display = "";
       if (this.btnNext) this.btnNext.style.display = "";
-      var m = this.maxScroll();
-      var current = this.scroller.scrollLeft;
-      var tolerance = 10;
-      var atStart = current <= tolerance;
-      var atEnd = current >= m - tolerance;
+      var metrics = this.getLiveScrollMetrics();
       if (this.btnPrev) {
-        if (atStart) this.btnPrev.classList.add("inactive");
+        if (metrics.isAtStart) this.btnPrev.classList.add("inactive");
         else this.btnPrev.classList.remove("inactive");
       }
       if (this.btnNext) {
-        if (atEnd) this.btnNext.classList.add("inactive");
+        if (metrics.isAtEnd) this.btnNext.classList.add("inactive");
         else this.btnNext.classList.remove("inactive");
       }
     };
@@ -501,10 +529,10 @@
       var avgItemWidth = total / Math.max(1, items + 2);
       var visibleItems = Math.max(1, Math.round(visible / avgItemWidth));
       var barWidth = Math.max(8, visibleItems / (items + 2) * trackWidth);
-      var maxS = Math.max(1, total - visible);
+      var metrics = this.getLiveScrollMetrics();
+      var maxS = Math.max(1, metrics.max);
       var maxX = Math.max(0, trackWidth - barWidth);
-      var progress = Math.min(1, Math.max(0, this.scroller.scrollLeft / maxS));
-      var x = maxX * progress;
+      var x = maxX * metrics.progress;
       return {
         trackWidth,
         barWidth,
@@ -565,7 +593,9 @@
         self._touchClampTimer = 0;
         var cur = self.scroller.scrollLeft;
         var max = self.maxScroll();
-        var eps = 1;
+        var clientWidth = Math.max(0, self.scroller.clientWidth || 0);
+        var scrollWidth = Math.max(0, self.scroller.scrollWidth || 0);
+        var eps = self.scrollEdgeEpsilon();
         if (!Number.isFinite(cur)) {
           self.scroller.scrollLeft = 0;
         } else if (cur < -eps || cur > max + eps) {
@@ -574,6 +604,10 @@
           self.scroller.scrollLeft = 0;
         } else if (cur > max) {
           self.scroller.scrollLeft = max;
+        } else if (cur <= eps) {
+          self.scroller.scrollLeft = 0;
+        } else if (cur + clientWidth >= scrollWidth - eps) {
+          self.scroller.scrollLeft = max;
         }
         self.updateScrollbar();
         self.updateButtons();
@@ -659,7 +693,8 @@
       return bestIdx;
     };
     Slider.prototype.getItemAnchorScrolls = function(items) {
-      var current = this.safeClampScroll(this.scroller.scrollLeft);
+      var metrics = this.getLiveScrollMetrics();
+      var current = metrics.current;
       var alignLeft = this.getAlignTargetLeft();
       var anchors = [];
       var last = -Infinity;
@@ -673,6 +708,13 @@
         anchors.push(anchor);
         last = anchor;
       }
+      if (anchors.length) {
+        var max = this.maxScroll();
+        var eps = this.scrollEdgeEpsilon();
+        if (anchors[0] <= eps) anchors[0] = 0;
+        if (anchors[anchors.length - 1] >= max - eps)
+          anchors[anchors.length - 1] = max;
+      }
       return anchors;
     };
     Slider.prototype.cloneSlideState = function(state2) {
@@ -734,6 +776,18 @@
         })
       };
     };
+    Slider.prototype.cloneScrollState = function(scroll) {
+      if (!scroll) return null;
+      return {
+        current: scroll.current,
+        max: scroll.max,
+        progress: scroll.progress,
+        progressPercent: scroll.progressPercent,
+        direction: scroll.direction,
+        isAtStart: scroll.isAtStart,
+        isAtEnd: scroll.isAtEnd
+      };
+    };
     Slider.prototype.dispatchSliderEvent = function(name, detail) {
       var payload = this.cloneSlideState(detail);
       try {
@@ -749,6 +803,21 @@
         this.root.dispatchEvent(ev);
       }
     };
+    Slider.prototype.dispatchProgressEvent = function(name, detail) {
+      var payload = this.cloneScrollState(detail);
+      try {
+        this.root.dispatchEvent(
+          new CustomEvent(name, {
+            bubbles: true,
+            detail: payload
+          })
+        );
+      } catch (e) {
+        var ev = document.createEvent("CustomEvent");
+        ev.initCustomEvent(name, true, false, payload);
+        this.root.dispatchEvent(ev);
+      }
+    };
     Slider.prototype.applySlideStateAttributes = function(state2) {
       var root = this.root;
       root.setAttribute(
@@ -768,6 +837,14 @@
         "data-rt-slider-segment-progress-percent",
         String(round(state2.segment.progressPercent, 4))
       );
+      root.setAttribute(
+        "data-rt-slider-scroll-current",
+        String(round(state2.scroll.current, 4))
+      );
+      root.setAttribute(
+        "data-rt-slider-scroll-max",
+        String(round(state2.scroll.max, 4))
+      );
       root.setAttribute(
         "data-rt-slider-scroll-progress",
         String(round(state2.scroll.progress, 6))
@@ -780,6 +857,14 @@
         "data-rt-slider-scroll-direction",
         state2.scroll.direction
       );
+      root.setAttribute(
+        "data-rt-slider-scroll-at-start",
+        state2.scroll.isAtStart ? "true" : "false"
+      );
+      root.setAttribute(
+        "data-rt-slider-scroll-at-end",
+        state2.scroll.isAtEnd ? "true" : "false"
+      );
       for (var i = 0; i < state2.slides.length; i++) {
         var slide = state2.slides[i];
         var el = slide.element;
@@ -826,8 +911,9 @@
     };
     Slider.prototype.buildSlideState = function() {
       var items = this.getOrderedItems();
-      var max = this.maxScroll();
-      var current = this.safeClampScroll(this.scroller.scrollLeft);
+      var metrics = this.getLiveScrollMetrics();
+      var max = metrics.max;
+      var current = metrics.current;
       var prevScroll = this._lastSlideStateScrollLeft;
       var scrollDirection = "none";
       if (current > prevScroll + 0.01) scrollDirection = "forward";
@@ -839,11 +925,11 @@
           scroll: {
             current,
             max,
-            progress: max > 0 ? clamp(current / max) : 0,
-            progressPercent: max > 0 ? clamp(current / max) * 100 : 0,
+            progress: metrics.progress,
+            progressPercent: metrics.progressPercent,
             direction: scrollDirection,
-            isAtStart: current <= 0.5,
-            isAtEnd: current >= max - 0.5
+            isAtStart: metrics.isAtStart,
+            isAtEnd: metrics.isAtEnd
           },
           active: {
             index: -1,
@@ -950,11 +1036,11 @@
         scroll: {
           current,
           max,
-          progress: max > 0 ? clamp(current / max) : 0,
-          progressPercent: max > 0 ? clamp(current / max) * 100 : 0,
+          progress: metrics.progress,
+          progressPercent: metrics.progressPercent,
           direction: scrollDirection,
-          isAtStart: current <= 0.5,
-          isAtEnd: current >= max - 0.5
+          isAtStart: metrics.isAtStart,
+          isAtEnd: metrics.isAtEnd
         },
         active: {
           index: nearestIndex,
@@ -989,9 +1075,14 @@
       var state2 = this.buildSlideState();
       var prevActiveIndex = this._lastSlideStateActiveIndex;
       var sig = state2.active.index + "|" + state2.segment.fromIndex + "|" + state2.segment.toIndex + "|" + round(state2.segment.progress, 4) + "|" + round(state2.scroll.progress, 4) + "|" + state2.scroll.direction;
+      var progressSig = round(state2.scroll.progress, 6) + "|" + round(state2.scroll.current, 4) + "|" + round(state2.scroll.max, 4) + "|" + state2.scroll.direction + "|" + (state2.scroll.isAtStart ? "1" : "0") + "|" + (state2.scroll.isAtEnd ? "1" : "0");
       this.slideState = state2;
       this.applySlideStateAttributes(state2);
       this._lastSlideStateScrollLeft = state2.scroll.current;
+      if (force || progressSig !== this._progressSig) {
+        this._progressSig = progressSig;
+        this.dispatchProgressEvent("rtSlider:progress", state2.scroll);
+      }
       if (force || sig !== this._slideStateSig) {
         this._slideStateSig = sig;
         this.dispatchSliderEvent("rtSlider:slide", state2);
@@ -1005,6 +1096,14 @@
       if (!this.slideState) this.updateSlideState(true);
       return this.cloneSlideState(this.slideState);
     };
+    Slider.prototype.getScrollState = function() {
+      var state2 = this.getSlideState();
+      return state2 ? this.cloneScrollState(state2.scroll) : null;
+    };
+    Slider.prototype.getProgress = function() {
+      var scroll = this.getScrollState();
+      return scroll ? scroll.progress : 0;
+    };
     Slider.prototype.getActiveIndex = function() {
       var state2 = this.getSlideState();
       return state2 && state2.active ? state2.active.index : -1;
@@ -1739,6 +1838,14 @@
           var inst = state.instances[id];
           return inst ? inst.getSlideState() : null;
         },
+        getScrollState: function(id) {
+          var inst = state.instances[id];
+          return inst ? inst.getScrollState() : null;
+        },
+        getProgress: function(id) {
+          var inst = state.instances[id];
+          return inst ? inst.getProgress() : 0;
+        },
         refresh: function() {
           var keys = state.order;
           for (var i = 0; i < keys.length; i++) {