@rethink-js/rt-slider 1.0.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.
- package/README.md +143 -45
- package/dist/index.js +489 -27
- package/dist/index.js.map +3 -3
- package/dist/index.min.js +2 -2
- package/dist/index.min.js.map +3 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,6 @@
|
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@rethink-js/rt-slider)
|
|
6
6
|
[](https://www.jsdelivr.com/package/npm/@rethink-js/rt-slider)
|
|
7
|
-
[](https://bundlephobia.com/package/@rethink-js/rt-slider)
|
|
8
7
|
[](https://opensource.org/licenses/MIT)
|
|
9
8
|
|
|
10
9
|
`rt-slider` is a lightweight JavaScript utility that creates touch-friendly sliders with smooth inertia scrolling and physics with:
|
|
@@ -15,7 +14,7 @@
|
|
|
15
14
|
- Support for **multiple instances**
|
|
16
15
|
- A clean global API under `window.rtSlider`
|
|
17
16
|
- Defensive fallbacks to native scrolling on mobile
|
|
18
|
-
-
|
|
17
|
+
- Built-in **slide state tracking**, DOM attributes, and custom events for advanced UI sync
|
|
19
18
|
|
|
20
19
|
**Primary dependency (GitHub):** <https://github.com/darkroomengineering/lenis>
|
|
21
20
|
|
|
@@ -42,14 +41,13 @@
|
|
|
42
41
|
### 1.1 CDN (jsDelivr)
|
|
43
42
|
|
|
44
43
|
```html
|
|
45
|
-
<script src="
|
|
44
|
+
<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-slider@latest/dist/index.min.js"></script>
|
|
46
45
|
```
|
|
47
46
|
|
|
48
47
|
### 1.2 npm
|
|
49
48
|
|
|
50
49
|
```bash
|
|
51
50
|
npm install @rethink-js/rt-slider
|
|
52
|
-
|
|
53
51
|
```
|
|
54
52
|
|
|
55
53
|
Then bundle or load `dist/index.min.js` as appropriate for your build setup.
|
|
@@ -65,6 +63,8 @@ Add the script to your page. To create a slider, add the `data-rt-slider` attrib
|
|
|
65
63
|
- Auto-initialize on DOM ready
|
|
66
64
|
- Load Lenis dynamically for desktop inertia
|
|
67
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
|
|
68
68
|
|
|
69
69
|
Example:
|
|
70
70
|
|
|
@@ -77,7 +77,7 @@ Example:
|
|
|
77
77
|
</div>
|
|
78
78
|
</div>
|
|
79
79
|
|
|
80
|
-
<script src="
|
|
80
|
+
<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-slider@latest/dist/index.min.js"></script>
|
|
81
81
|
```
|
|
82
82
|
|
|
83
83
|
> Note: If you do not provide `data-rt-list` and `data-rt-item`, the slider will not initialize.
|
|
@@ -86,10 +86,11 @@ Example:
|
|
|
86
86
|
|
|
87
87
|
## 3. Activation Rules
|
|
88
88
|
|
|
89
|
-
The library activates when **
|
|
89
|
+
The library activates when **all** of the following are true:
|
|
90
90
|
|
|
91
91
|
- An element with the attribute `data-rt-slider` is found in the DOM.
|
|
92
|
-
- The required `data-rt-list` and `data-rt-item` selectors
|
|
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.
|
|
93
94
|
|
|
94
95
|
If these conditions are met, the library initializes the instance automatically.
|
|
95
96
|
|
|
@@ -121,17 +122,20 @@ If these conditions are met, the library initializes the instance automatically.
|
|
|
121
122
|
|
|
122
123
|
### Core Attributes (Selectors)
|
|
123
124
|
|
|
124
|
-
| Attribute
|
|
125
|
-
|
|
|
126
|
-
| `data-rt-slider`
|
|
127
|
-
| `data-rt-slider-id`
|
|
128
|
-
| `data-rt-list`
|
|
129
|
-
| `data-rt-item`
|
|
130
|
-
| `data-rt-spacer`
|
|
131
|
-
| `data-rt-btn-prev`
|
|
132
|
-
| `data-rt-btn-next`
|
|
133
|
-
| `data-rt-scroll-track`
|
|
134
|
-
| `data-rt-scroll-bar`
|
|
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 |
|
|
135
139
|
|
|
136
140
|
---
|
|
137
141
|
|
|
@@ -147,15 +151,18 @@ These attributes control the Lenis instance used on desktop.
|
|
|
147
151
|
></div>
|
|
148
152
|
```
|
|
149
153
|
|
|
150
|
-
| Attribute
|
|
151
|
-
|
|
|
152
|
-
| `data-rt-slider-lerp`
|
|
153
|
-
| `data-rt-slider-duration`
|
|
154
|
-
| `data-rt-slider-easing`
|
|
155
|
-
| `data-rt-slider-orientation`
|
|
156
|
-
| `data-rt-slider-
|
|
157
|
-
| `data-rt-slider-
|
|
158
|
-
| `data-rt-slider-
|
|
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` |
|
|
159
166
|
|
|
160
167
|
---
|
|
161
168
|
|
|
@@ -172,13 +179,77 @@ Used to pass complex configuration objects directly to the underlying Lenis inst
|
|
|
172
179
|
|
|
173
180
|
---
|
|
174
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
|
+
|
|
175
246
|
### Dependency Loader Overrides
|
|
176
247
|
|
|
177
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`.
|
|
178
249
|
|
|
179
|
-
| Attribute
|
|
180
|
-
|
|
|
181
|
-
| `data-rt-lenis="true"` | Add this to a script tag to identify external Lenis |
|
|
250
|
+
| Attribute | Description |
|
|
251
|
+
| ----------------------------- | --------------------------------------------------- |
|
|
252
|
+
| `data-rt-slider-lenis="true"` | Add this to a script tag to identify external Lenis |
|
|
182
253
|
|
|
183
254
|
---
|
|
184
255
|
|
|
@@ -188,9 +259,11 @@ The library automatically loads Lenis from a CDN if not present. You can rely on
|
|
|
188
259
|
|
|
189
260
|
Each instance:
|
|
190
261
|
|
|
191
|
-
- Has its own independent scroll physics
|
|
192
|
-
- Calculates its own progress bars and button states
|
|
193
|
-
-
|
|
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
|
|
194
267
|
|
|
195
268
|
---
|
|
196
269
|
|
|
@@ -204,12 +277,13 @@ window.rtSlider;
|
|
|
204
277
|
|
|
205
278
|
### Common Methods
|
|
206
279
|
|
|
207
|
-
| Method
|
|
208
|
-
|
|
|
209
|
-
| `ids()`
|
|
210
|
-
| `get(id)`
|
|
211
|
-
| `
|
|
212
|
-
| `
|
|
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 |
|
|
213
287
|
|
|
214
288
|
Example usage:
|
|
215
289
|
|
|
@@ -217,19 +291,31 @@ Example usage:
|
|
|
217
291
|
// Refresh layout after an AJAX load
|
|
218
292
|
window.rtSlider.refresh();
|
|
219
293
|
|
|
294
|
+
// Get computed slide state
|
|
295
|
+
const ids = window.rtSlider.ids();
|
|
296
|
+
const firstSliderState = window.rtSlider.getSlideState(ids[0]);
|
|
297
|
+
|
|
220
298
|
// Destroy a specific slider
|
|
221
299
|
window.rtSlider.destroy("my-slider-id");
|
|
222
300
|
```
|
|
223
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
|
+
|
|
224
312
|
---
|
|
225
313
|
|
|
226
314
|
## 7. Console Logging
|
|
227
315
|
|
|
228
|
-
`rt-slider` operates silently by default
|
|
316
|
+
`rt-slider` operates silently by default.
|
|
229
317
|
|
|
230
|
-
|
|
231
|
-
- JSON configuration is invalid.
|
|
232
|
-
- 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.
|
|
233
319
|
|
|
234
320
|
---
|
|
235
321
|
|
|
@@ -239,16 +325,28 @@ window.rtSlider.destroy("my-slider-id");
|
|
|
239
325
|
|
|
240
326
|
- Ensure `data-rt-slider` is present on the parent.
|
|
241
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.
|
|
242
329
|
|
|
243
330
|
### Buttons not working
|
|
244
331
|
|
|
245
|
-
- 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.
|
|
246
333
|
- If buttons are outside the slider container, give them the attribute `data-rt-slider-for="slider-id"`.
|
|
247
334
|
|
|
248
335
|
### Scrollbar not moving
|
|
249
336
|
|
|
250
337
|
- Ensure `data-rt-scroll-track` and `data-rt-scroll-bar` are set correctly.
|
|
251
|
-
- The "bar"
|
|
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.
|
|
252
350
|
|
|
253
351
|
---
|
|
254
352
|
|