@rethink-js/rt-slider 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +138 -38
  2. package/dist/index.js +381 -2
  3. package/dist/index.js.map +3 -3
  4. package/dist/index.min.js +2 -2
  5. package/dist/index.min.js.map +3 -3
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -14,7 +14,7 @@
14
14
  - Support for **multiple instances**
15
15
  - A clean global API under `window.rtSlider`
16
16
  - Defensive fallbacks to native scrolling on mobile
17
- - Clear console logs for debugging and verification
17
+ - Built-in **slide state tracking**, DOM attributes, and custom events for advanced UI sync
18
18
 
19
19
  **Primary dependency (GitHub):** <https://github.com/darkroomengineering/lenis>
20
20
 
@@ -63,6 +63,8 @@ Add the script to your page. To create a slider, add the `data-rt-slider` attrib
63
63
  - Auto-initialize on DOM ready
64
64
  - Load Lenis dynamically for desktop inertia
65
65
  - Apply native touch scrolling styles for mobile
66
+ - Compute active slide state and progress automatically
67
+ - Expose slider state through attributes, events, and the global API
66
68
 
67
69
  Example:
68
70
 
@@ -84,10 +86,11 @@ Example:
84
86
 
85
87
  ## 3. Activation Rules
86
88
 
87
- The library activates when **any** of the following are true:
89
+ The library activates when **all** of the following are true:
88
90
 
89
91
  - An element with the attribute `data-rt-slider` is found in the DOM.
90
- - The required `data-rt-list` and `data-rt-item` selectors resolve to valid elements within that container.
92
+ - The required `data-rt-list` and `data-rt-item` selectors are present on that container.
93
+ - The `data-rt-list` selector resolves to a valid element within that container.
91
94
 
92
95
  If these conditions are met, the library initializes the instance automatically.
93
96
 
@@ -119,17 +122,20 @@ If these conditions are met, the library initializes the instance automatically.
119
122
 
120
123
  ### Core Attributes (Selectors)
121
124
 
122
- | Attribute | Description | Required |
123
- | ---------------------- | ----------------------------------------------- | -------- |
124
- | `data-rt-slider` | Activates the slider instance | **Yes** |
125
- | `data-rt-slider-id` | Optional identifier (auto-generated if missing) | No |
126
- | `data-rt-list` | Selector for the scrollable wrapper | **Yes** |
127
- | `data-rt-item` | Selector for individual slides | **Yes** |
128
- | `data-rt-spacer` | Selector/Class for edge spacers (padding) | No |
129
- | `data-rt-btn-prev` | Selector for "Previous" button | No |
130
- | `data-rt-btn-next` | Selector for "Next" button | No |
131
- | `data-rt-scroll-track` | Selector for custom scrollbar track | No |
132
- | `data-rt-scroll-bar` | Selector for custom scrollbar thumb | No |
125
+ | Attribute | Description | Required |
126
+ | ----------------------- | ---------------------------------------------------------- | -------- |
127
+ | `data-rt-slider` | Activates the slider instance | **Yes** |
128
+ | `data-rt-slider-id` | Optional identifier (auto-generated if missing) | No |
129
+ | `data-rt-list` | Selector for the scrollable wrapper | **Yes** |
130
+ | `data-rt-item` | Selector for individual slides | **Yes** |
131
+ | `data-rt-spacer` | Selector/Class for edge spacers (padding) | No |
132
+ | `data-rt-btn-prev` | Selector for "Previous" button | No |
133
+ | `data-rt-btn-next` | Selector for "Next" button | No |
134
+ | `data-rt-scroll-track` | Selector for custom scrollbar track | No |
135
+ | `data-rt-scroll-bar` | Selector for custom scrollbar thumb | No |
136
+ | `data-rt-margin-ref` | Selector used to align slide anchors to a layout reference | No |
137
+ | `data-rt-overlay-start` | Selector for the leading edge overlay | No |
138
+ | `data-rt-overlay-end` | Selector for the trailing edge overlay | No |
133
139
 
134
140
  ---
135
141
 
@@ -145,15 +151,18 @@ These attributes control the Lenis instance used on desktop.
145
151
  ></div>
146
152
  ```
147
153
 
148
- | Attribute | Description | Default |
149
- | ----------------------------- | -------------------------------------- | ------------- |
150
- | `data-rt-slider-lerp` | Inertia interpolation (lower = slower) | `0.1` |
151
- | `data-rt-slider-duration` | Scroll duration (alt to lerp) | `1.2` |
152
- | `data-rt-slider-easing` | Easing function (e.g., `easeOutExpo`) | `easeOutQuad` |
153
- | `data-rt-slider-orientation` | Scroll orientation | `horizontal` |
154
- | `data-rt-slider-smooth-wheel` | Enable mouse wheel smoothing | `true` |
155
- | `data-rt-slider-infinite` | Infinite scrolling | `false` |
156
- | `data-rt-slider-auto-resize` | Recalculate on window resize | `true` |
154
+ | Attribute | Description | Default |
155
+ | ------------------------------------ | -------------------------------------- | ------------- |
156
+ | `data-rt-slider-lerp` | Inertia interpolation (lower = slower) | Lenis default |
157
+ | `data-rt-slider-duration` | Scroll duration (alt to lerp) | Lenis default |
158
+ | `data-rt-slider-easing` | Easing function (e.g., `easeOutExpo`) | Lenis default |
159
+ | `data-rt-slider-orientation` | Scroll orientation | `horizontal` |
160
+ | `data-rt-slider-gesture-orientation` | Gesture orientation | `horizontal` |
161
+ | `data-rt-slider-smooth-wheel` | Enable mouse wheel smoothing | `true` |
162
+ | `data-rt-slider-wheel-multiplier` | Multiplier for wheel-based scrolling | Lenis default |
163
+ | `data-rt-slider-touch-multiplier` | Multiplier for touch-based scrolling | Lenis default |
164
+ | `data-rt-slider-infinite` | Infinite scrolling | `false` |
165
+ | `data-rt-slider-auto-resize` | Recalculate on window resize | `true` |
157
166
 
158
167
  ---
159
168
 
@@ -170,6 +179,70 @@ Used to pass complex configuration objects directly to the underlying Lenis inst
170
179
 
171
180
  ---
172
181
 
182
+ ### Slide State Output
183
+
184
+ As the slider moves, `rt-slider` writes state back to the DOM automatically.
185
+
186
+ #### Root attributes
187
+
188
+ | Attribute | Description |
189
+ | ----------------------------------------- | ------------------------------------------ |
190
+ | `data-rt-slider-active-index` | Current nearest active slide index |
191
+ | `data-rt-slider-from-index` | Current segment start slide index |
192
+ | `data-rt-slider-to-index` | Current segment end slide index |
193
+ | `data-rt-slider-segment-progress` | Current segment progress from `0` to `1` |
194
+ | `data-rt-slider-segment-progress-percent` | Current segment progress from `0` to `100` |
195
+ | `data-rt-slider-scroll-progress` | Overall slider progress from `0` to `1` |
196
+ | `data-rt-slider-scroll-progress-percent` | Overall slider progress from `0` to `100` |
197
+ | `data-rt-slider-scroll-direction` | `forward`, `backward`, or `none` |
198
+
199
+ #### Per-item attributes
200
+
201
+ | Attribute | Description |
202
+ | --------------------------------------------- | -------------------------------------------------------------------------- |
203
+ | `data-rt-slider-item-index` | Slide index |
204
+ | `data-rt-slider-item-active` | `true` when this item is the active slide |
205
+ | `data-rt-slider-item-from` | `true` when this item is the current segment start |
206
+ | `data-rt-slider-item-to` | `true` when this item is the current segment end |
207
+ | `data-rt-slider-item-previous` | `true` when this item is immediately before the active slide |
208
+ | `data-rt-slider-item-next` | `true` when this item is immediately after the active slide |
209
+ | `data-rt-slider-item-before-active` | `true` when this item is before the active slide |
210
+ | `data-rt-slider-item-after-active` | `true` when this item is after the active slide |
211
+ | `data-rt-slider-item-anchor-progress` | This slide's anchor position from `0` to `1` |
212
+ | `data-rt-slider-item-anchor-progress-percent` | This slide's anchor position from `0` to `100` |
213
+ | `data-rt-slider-item-distance` | Distance in pixels from the current scroll position to this slide's anchor |
214
+
215
+ These attributes are useful for CSS-driven animations, slide-aware UI, progress indicators, and syncing other interface elements to the slider.
216
+
217
+ ---
218
+
219
+ ### Custom Events
220
+
221
+ Each slider instance dispatches events from the root element.
222
+
223
+ | Event | Description |
224
+ | ----------------- | ------------------------------------------- |
225
+ | `rtSlider:slide` | Fires when the computed slide state changes |
226
+ | `rtSlider:active` | Fires when the active slide index changes |
227
+
228
+ Example:
229
+
230
+ ```js
231
+ const slider = document.querySelector("[data-rt-slider]");
232
+
233
+ slider.addEventListener("rtSlider:slide", function (event) {
234
+ console.log(event.detail);
235
+ });
236
+
237
+ slider.addEventListener("rtSlider:active", function (event) {
238
+ console.log("Active slide:", event.detail.active.index);
239
+ });
240
+ ```
241
+
242
+ Both events include a full cloned slide-state object in `event.detail`.
243
+
244
+ ---
245
+
173
246
  ### Dependency Loader Overrides
174
247
 
175
248
  The library automatically loads Lenis from a CDN if not present. You can rely on the default or load your own version before `rt-slider`.
@@ -186,9 +259,11 @@ The library automatically loads Lenis from a CDN if not present. You can rely on
186
259
 
187
260
  Each instance:
188
261
 
189
- - Has its own independent scroll physics.
190
- - Calculates its own progress bars and button states.
191
- - Is registered internally with a unique ID.
262
+ - Has its own independent scroll physics
263
+ - Calculates its own progress bars and button states
264
+ - Tracks its own active slide and segment state
265
+ - Dispatches its own custom events
266
+ - Is registered internally with a unique ID
192
267
 
193
268
  ---
194
269
 
@@ -202,12 +277,13 @@ window.rtSlider;
202
277
 
203
278
  ### Common Methods
204
279
 
205
- | Method | Description |
206
- | -------------- | ------------------------------------------------ |
207
- | `ids()` | Returns an array of active slider IDs |
208
- | `get(id)` | Returns the slider instance object |
209
- | `refresh()` | Forces a recalculation of layout (all instances) |
210
- | `destroy(id?)` | Destroys specific instance or all if no ID given |
280
+ | Method | Description |
281
+ | ------------------- | --------------------------------------------------- |
282
+ | `ids()` | Returns an array of active slider IDs |
283
+ | `get(id)` | Returns the slider instance object |
284
+ | `getSlideState(id)` | Returns a cloned slide-state object for an instance |
285
+ | `refresh()` | Forces a recalculation of layout (all instances) |
286
+ | `destroy(id?)` | Destroys specific instance or all if no ID given |
211
287
 
212
288
  Example usage:
213
289
 
@@ -215,19 +291,31 @@ Example usage:
215
291
  // Refresh layout after an AJAX load
216
292
  window.rtSlider.refresh();
217
293
 
294
+ // Get computed slide state
295
+ const ids = window.rtSlider.ids();
296
+ const firstSliderState = window.rtSlider.getSlideState(ids[0]);
297
+
218
298
  // Destroy a specific slider
219
299
  window.rtSlider.destroy("my-slider-id");
220
300
  ```
221
301
 
302
+ ### Instance Helpers
303
+
304
+ When using `window.rtSlider.get(id)`, each instance also exposes helper methods:
305
+
306
+ | Method | Description |
307
+ | -------------------- | ----------------------------------------------------- |
308
+ | `getSlideState()` | Returns a cloned slide-state object for that instance |
309
+ | `getActiveIndex()` | Returns the current active slide index |
310
+ | `getActiveElement()` | Returns the current active slide element |
311
+
222
312
  ---
223
313
 
224
314
  ## 7. Console Logging
225
315
 
226
- `rt-slider` operates silently by default but provides warnings if:
316
+ `rt-slider` operates silently by default.
227
317
 
228
- - Required selectors (`data-rt-list`, `data-rt-item`) are missing.
229
- - JSON configuration is invalid.
230
- - Dependency loading fails.
318
+ It does not rely on console output during normal use. If initialization fails, the most common causes are invalid selectors, missing required attributes, or invalid external configuration.
231
319
 
232
320
  ---
233
321
 
@@ -237,16 +325,28 @@ window.rtSlider.destroy("my-slider-id");
237
325
 
238
326
  - Ensure `data-rt-slider` is present on the parent.
239
327
  - **Crucial:** Ensure `data-rt-list` and `data-rt-item` attributes match valid elements inside the container.
328
+ - Ensure the `data-rt-list` selector resolves successfully inside the slider root.
240
329
 
241
330
  ### Buttons not working
242
331
 
243
- - Ensure the selectors in `data-rt-btn-prev` match your button elements.
332
+ - Ensure the selectors in `data-rt-btn-prev` and `data-rt-btn-next` match your button elements.
244
333
  - If buttons are outside the slider container, give them the attribute `data-rt-slider-for="slider-id"`.
245
334
 
246
335
  ### Scrollbar not moving
247
336
 
248
337
  - Ensure `data-rt-scroll-track` and `data-rt-scroll-bar` are set correctly.
249
- - The "bar" must be a child of the "track" in the DOM for standard styling, though the logic handles positioning.
338
+ - The "bar" should be inside the "track" for the cleanest result, though the logic handles positioning independently.
339
+
340
+ ### Slide state attributes not updating
341
+
342
+ - 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.
343
+ - Ensure `data-rt-item` matches the actual slide elements and not a wrapper around them.
344
+
345
+ ### Custom events not firing as expected
346
+
347
+ - `rtSlider:slide` fires when computed slide state changes.
348
+ - `rtSlider:active` fires when the active slide changes.
349
+ - Both events are dispatched from the element with `data-rt-slider`, not from the list or item elements.
250
350
 
251
351
  ---
252
352