@twistedandy/better-carousel 0.0.0-stage → 1.0.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/LICENSE +21 -0
- package/README.md +838 -2
- package/dist/better-carousel.css +1 -0
- package/dist/better-carousel.js +3175 -0
- package/dist/better-carousel.min.js +1 -0
- package/package.json +55 -5
- package/src/index.js +49 -0
- package/src/scripts/autoplay.js +288 -0
- package/src/scripts/carousel.js +834 -0
- package/src/scripts/geometry.js +429 -0
- package/src/scripts/input.js +432 -0
- package/src/scripts/layout.js +205 -0
- package/src/scripts/loop.js +83 -0
- package/src/scripts/markup.js +268 -0
- package/src/scripts/motion.js +232 -0
- package/src/scripts/navigation.js +209 -0
- package/src/scripts/options.js +153 -0
- package/src/styles/better-carousel.scss +323 -0
- package/src/types/better-carousel.d.ts +309 -0
|
@@ -0,0 +1,429 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Snap math: the snaps, the active slide, the slides in view and the progress. This module does not use the DOM.
|
|
3
|
+
*
|
|
4
|
+
* All values are on the main axis, in px. A slide is { start, end }: its border box at location 0, relative to the viewport start.
|
|
5
|
+
* The location L is the translate of the container. A slide shows at start + L.
|
|
6
|
+
* In loop mode, the period is the length of one copy of the slides. Without loop, it is 0.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { cloneCount } from './loop.js';
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Keep a value between two limits.
|
|
13
|
+
*
|
|
14
|
+
* @param {number} value
|
|
15
|
+
* @param {number} min
|
|
16
|
+
* @param {number} max
|
|
17
|
+
* @returns {number}
|
|
18
|
+
*/
|
|
19
|
+
export function clamp(value, min, max) {
|
|
20
|
+
return Math.min(max, Math.max(min, value));
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Get a valid snap index. In loop mode, the index goes around. Without loop, it stops at the first or the last snap.
|
|
25
|
+
*
|
|
26
|
+
* @param {number} index
|
|
27
|
+
* @param {number} count The number of snaps.
|
|
28
|
+
* @param {number} [period]
|
|
29
|
+
* @returns {number}
|
|
30
|
+
*/
|
|
31
|
+
export function snapIndex(index, count, period) {
|
|
32
|
+
return period ? (index % count + count) % count : clamp(index, 0, count - 1);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Get the offset of a snap from the viewport start.
|
|
37
|
+
*
|
|
38
|
+
* @param {string|Function} align 'start', 'center', 'end' or (viewSize, snapSize, index) => offset.
|
|
39
|
+
* @param {number} view The viewport size.
|
|
40
|
+
* @param {number} size The snap size.
|
|
41
|
+
* @param {number} index The snap index.
|
|
42
|
+
* @returns {number}
|
|
43
|
+
*/
|
|
44
|
+
export function alignOffset(align, view, size, index) {
|
|
45
|
+
if (typeof align === 'function') {
|
|
46
|
+
return align(view, size, index);
|
|
47
|
+
}
|
|
48
|
+
return align === 'center' ? (view - size) / 2 : align === 'end' ? view - size : 0;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Get the first start and the last end of the slides.
|
|
53
|
+
*
|
|
54
|
+
* @param {Array<{start: number, end: number}>} slides
|
|
55
|
+
* @returns {{start: number, end: number, size: number, max: number}} max is the size of the largest slide.
|
|
56
|
+
*/
|
|
57
|
+
export function bounds(slides) {
|
|
58
|
+
let start = Infinity,
|
|
59
|
+
end = -Infinity,
|
|
60
|
+
max = 0;
|
|
61
|
+
|
|
62
|
+
for (const slide of slides) {
|
|
63
|
+
start = Math.min(start, slide.start);
|
|
64
|
+
end = Math.max(end, slide.end);
|
|
65
|
+
max = Math.max(max, slide.end - slide.start);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
return { start, end, size: end - start, max };
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Put the slides that start at the same position (1 px or less) into one column.
|
|
73
|
+
* In a flex row, one column has one slide. In a grid, a column can have more slides.
|
|
74
|
+
*
|
|
75
|
+
* @param {Array<{start: number, end: number}>} slides
|
|
76
|
+
* @returns {Array<{start: number, end: number}>} The columns, sorted by start.
|
|
77
|
+
*/
|
|
78
|
+
export function columns(slides) {
|
|
79
|
+
const order = slides.map((slide, index) => index).sort((a, b) => slides[a].start - slides[b].start || a - b),
|
|
80
|
+
list = [];
|
|
81
|
+
|
|
82
|
+
let column;
|
|
83
|
+
|
|
84
|
+
for (const index of order) {
|
|
85
|
+
const slide = slides[index];
|
|
86
|
+
if (column && slide.start - column.start <= 1) {
|
|
87
|
+
column.end = Math.max(column.end, slide.end);
|
|
88
|
+
} else {
|
|
89
|
+
column = { start: slide.start, end: slide.end };
|
|
90
|
+
list.push(column);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
return list;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Put the columns into groups. One group gives one snap.
|
|
99
|
+
*
|
|
100
|
+
* @param {Array<{start: number, end: number}>} list The columns.
|
|
101
|
+
* @param {number} view
|
|
102
|
+
* @param {number|string} count A number of columns, or 'auto' for as many as fit in the viewport.
|
|
103
|
+
* @returns {Array<{start: number, end: number}>}
|
|
104
|
+
*/
|
|
105
|
+
export function groups(list, view, count) {
|
|
106
|
+
const result = [];
|
|
107
|
+
|
|
108
|
+
let group,
|
|
109
|
+
size = 0;
|
|
110
|
+
|
|
111
|
+
for (const column of list) {
|
|
112
|
+
const fit = count === 'auto' ? group && column.end - group.start <= view + 1 : size < count;
|
|
113
|
+
if (group && fit) {
|
|
114
|
+
group.end = Math.max(group.end, column.end);
|
|
115
|
+
size++;
|
|
116
|
+
} else {
|
|
117
|
+
group = { start: column.start, end: column.end };
|
|
118
|
+
result.push(group);
|
|
119
|
+
size = 1;
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
return result;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Get the distance between two locations. In loop mode, use the shortest distance modulo the period.
|
|
128
|
+
*
|
|
129
|
+
* @param {number} a
|
|
130
|
+
* @param {number} b
|
|
131
|
+
* @param {number} [period] The loop period, or 0 if the loop is off.
|
|
132
|
+
* @returns {number} a - b
|
|
133
|
+
*/
|
|
134
|
+
export function distance(a, b, period) {
|
|
135
|
+
const value = a - b;
|
|
136
|
+
return period ? value - Math.round(value / period) * period : value;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Compute the snaps.
|
|
141
|
+
*
|
|
142
|
+
* @param {object} args
|
|
143
|
+
* @param {Array<{start: number, end: number}>} args.slides
|
|
144
|
+
* @param {number} args.view The viewport size.
|
|
145
|
+
* @param {string|Function} args.align
|
|
146
|
+
* @param {number|string} args.slidesPerSnap
|
|
147
|
+
* @param {string|boolean} args.containScroll 'trimSnaps', 'keepSnaps' or false.
|
|
148
|
+
* @param {number} [args.period] The loop period, or 0 if the loop is off.
|
|
149
|
+
* @returns {{snaps: Array<{location: number, slide: number}>, min: number, max: number}}
|
|
150
|
+
* Each snap has its location and its active slide. min and max are the limits of the location if the loop is off.
|
|
151
|
+
* With the loop, max is the location of the first snap, where the progress is 0.
|
|
152
|
+
*/
|
|
153
|
+
export function snaps({ slides, view, align, slidesPerSnap, containScroll, period = 0 }) {
|
|
154
|
+
const content = bounds(slides);
|
|
155
|
+
|
|
156
|
+
let max = -content.start || 0,
|
|
157
|
+
min = view - content.end,
|
|
158
|
+
list = groups(columns(slides), view, slidesPerSnap).map((group, index) => alignOffset(align, view, group.end - group.start, index) - group.start);
|
|
159
|
+
|
|
160
|
+
if (!period) {
|
|
161
|
+
if (containScroll) {
|
|
162
|
+
list = list.map((location) => clamp(location, min, max));
|
|
163
|
+
} else {
|
|
164
|
+
max = Math.max(...list);
|
|
165
|
+
min = Math.min(...list);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
if (period || containScroll !== 'keepSnaps') {
|
|
170
|
+
list = list.filter((location, index) => !index || Math.abs(distance(location, list[index - 1], period)) > 1);
|
|
171
|
+
if (period && list.length > 1 && Math.abs(distance(list[0], list[list.length - 1], period)) <= 1) {
|
|
172
|
+
list.pop();
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
const result = list.map((location) => ({ location, slide: activeSlide(slides, location, view, align, period) }));
|
|
177
|
+
|
|
178
|
+
// Without the loop, a trimmed snap at an end can get the slide of the snap next to it. Then it takes the nearest slide on its own side.
|
|
179
|
+
const fix = (snap, from, to) => {
|
|
180
|
+
const slide = activeSlide(slides, snap.location, view, align, 0, from, to);
|
|
181
|
+
snap.slide = slide > -1 ? slide : snap.slide;
|
|
182
|
+
};
|
|
183
|
+
|
|
184
|
+
if (!period && result.length > 1) {
|
|
185
|
+
const first = result[0],
|
|
186
|
+
last = result[result.length - 1];
|
|
187
|
+
if (first.slide >= result[1].slide) {
|
|
188
|
+
fix(first, 0, result[1].slide);
|
|
189
|
+
}
|
|
190
|
+
if (last.slide <= result[result.length - 2].slide) {
|
|
191
|
+
fix(last, result[result.length - 2].slide + 1, slides.length);
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
return {
|
|
196
|
+
snaps: result,
|
|
197
|
+
min,
|
|
198
|
+
max: period ? list[0] : max
|
|
199
|
+
};
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Find the slide whose anchor is nearest to the align point at a location.
|
|
204
|
+
* The anchor is the start for 'start', the center for 'center' and the end for 'end'.
|
|
205
|
+
* If two slides have the same distance, the lower index wins.
|
|
206
|
+
*
|
|
207
|
+
* @param {Array<{start: number, end: number}>} slides
|
|
208
|
+
* @param {number} location
|
|
209
|
+
* @param {number} view
|
|
210
|
+
* @param {string|Function} align
|
|
211
|
+
* @param {number} [period]
|
|
212
|
+
* @param {number} [from] The first slide to look at.
|
|
213
|
+
* @param {number} [to] The slide after the last slide to look at.
|
|
214
|
+
* @returns {number} The slide index, or -1 if the range is empty.
|
|
215
|
+
*/
|
|
216
|
+
export function activeSlide(slides, location, view, align, period, from = 0, to = slides.length) {
|
|
217
|
+
let best = -1,
|
|
218
|
+
gap = Infinity;
|
|
219
|
+
|
|
220
|
+
slides.forEach((slide, index) => {
|
|
221
|
+
const value = Math.abs(distance(slide.start + location, alignOffset(align, view, slide.end - slide.start, index), period));
|
|
222
|
+
if (index >= from && index < to && value < gap - 0.5) {
|
|
223
|
+
gap = value;
|
|
224
|
+
best = index;
|
|
225
|
+
}
|
|
226
|
+
});
|
|
227
|
+
|
|
228
|
+
return best;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* Find the snap of a slide: the snap whose active slide it is, or the snap nearest to the raw location of the slide.
|
|
233
|
+
*
|
|
234
|
+
* @param {Array<{location: number, slide: number}>} list The snaps.
|
|
235
|
+
* @param {Array<{start: number, end: number}>} slides
|
|
236
|
+
* @param {number} index The slide index.
|
|
237
|
+
* @param {number} view
|
|
238
|
+
* @param {string|Function} align
|
|
239
|
+
* @param {number} [period]
|
|
240
|
+
* @returns {number} The snap index.
|
|
241
|
+
*/
|
|
242
|
+
export function snapOfSlide(list, slides, index, view, align, period) {
|
|
243
|
+
const found = list.findIndex((snap) => snap.slide === index),
|
|
244
|
+
slide = slides[index];
|
|
245
|
+
|
|
246
|
+
if (found > -1 || !slide) {
|
|
247
|
+
return Math.max(found, 0);
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
return nearestSnap(list, alignOffset(align, view, slide.end - slide.start, index) - slide.start, period);
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/**
|
|
254
|
+
* Find the snap nearest to a location.
|
|
255
|
+
*
|
|
256
|
+
* @param {Array<{location: number}>} list The snaps.
|
|
257
|
+
* @param {number} location
|
|
258
|
+
* @param {number} [period]
|
|
259
|
+
* @returns {number} The snap index.
|
|
260
|
+
*/
|
|
261
|
+
export function nearestSnap(list, location, period) {
|
|
262
|
+
let best = 0,
|
|
263
|
+
gap = Infinity;
|
|
264
|
+
|
|
265
|
+
list.forEach((snap, index) => {
|
|
266
|
+
const value = Math.abs(distance(snap.location, location, period));
|
|
267
|
+
if (value < gap) {
|
|
268
|
+
gap = value;
|
|
269
|
+
best = index;
|
|
270
|
+
}
|
|
271
|
+
});
|
|
272
|
+
|
|
273
|
+
return best;
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/**
|
|
277
|
+
* Get the location of a snap that is nearest to the current location. In loop mode, a snap has a location in each period.
|
|
278
|
+
*
|
|
279
|
+
* @param {number} target The snap location.
|
|
280
|
+
* @param {number} location The current location.
|
|
281
|
+
* @param {number} [period]
|
|
282
|
+
* @param {number} [direction] 1 to go forward (a smaller location), -1 to go back, 0 for the shortest path.
|
|
283
|
+
* @returns {number}
|
|
284
|
+
*/
|
|
285
|
+
export function targetLocation(target, location, period, direction = 0) {
|
|
286
|
+
if (!period) {
|
|
287
|
+
return target;
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
if (direction > 0) {
|
|
291
|
+
return target + (Math.ceil((location - 0.5 - target) / period) - 1) * period;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
if (direction < 0) {
|
|
295
|
+
return target + (Math.floor((location + 0.5 - target) / period) + 1) * period;
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
return location + distance(target, location, period);
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
/**
|
|
302
|
+
* Get the progress of a location, from 0 to 1.
|
|
303
|
+
*
|
|
304
|
+
* @param {number} location
|
|
305
|
+
* @param {{min: number, max: number, period: number}} limits The limits of the location and the loop period. With the loop, max is the location of the first snap.
|
|
306
|
+
* @returns {number}
|
|
307
|
+
*/
|
|
308
|
+
export function progress(location, { min, max, period }) {
|
|
309
|
+
if (period) {
|
|
310
|
+
const value = (max - location) / period;
|
|
311
|
+
return value - Math.floor(value);
|
|
312
|
+
}
|
|
313
|
+
return max > min ? clamp((max - location) / (max - min), 0, 1) : 0;
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/**
|
|
317
|
+
* Find the slides that show at a location.
|
|
318
|
+
*
|
|
319
|
+
* @param {Array<{start: number, end: number}>} slides
|
|
320
|
+
* @param {number} location
|
|
321
|
+
* @param {number} view
|
|
322
|
+
* @param {number} threshold The part of a slide that must show, from 0 to 1. With 0, any part is enough.
|
|
323
|
+
* @param {number} [period]
|
|
324
|
+
* @returns {number[]} The slide indexes.
|
|
325
|
+
*/
|
|
326
|
+
export function inView(slides, location, view, threshold, period) {
|
|
327
|
+
const result = [];
|
|
328
|
+
|
|
329
|
+
slides.forEach((slide, index) => {
|
|
330
|
+
const size = slide.end - slide.start,
|
|
331
|
+
start = period ? distance(slide.start + location + size / 2, view / 2, period) + view / 2 - size / 2 : slide.start + location,
|
|
332
|
+
visible = Math.min(start + size, view) - Math.max(start, 0);
|
|
333
|
+
|
|
334
|
+
if (visible > 0 && visible >= threshold * size - 0.5) {
|
|
335
|
+
result.push(index);
|
|
336
|
+
}
|
|
337
|
+
});
|
|
338
|
+
|
|
339
|
+
return result;
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
/**
|
|
343
|
+
* Get the position of a location between the snaps, as a fractional snap index: 2.4 is between snap 2 and snap 3.
|
|
344
|
+
* In loop mode, a value after the last snap goes to the first snap again.
|
|
345
|
+
*
|
|
346
|
+
* @param {Array<{location: number}>} list The snaps.
|
|
347
|
+
* @param {number} location
|
|
348
|
+
* @param {number} [period]
|
|
349
|
+
* @returns {number}
|
|
350
|
+
*/
|
|
351
|
+
export function snapPosition(list, location, period) {
|
|
352
|
+
const last = list.length - 1,
|
|
353
|
+
first = list[0].location,
|
|
354
|
+
at = period ? first - ((first - location) % period + period) % period : clamp(location, list[last].location, first);
|
|
355
|
+
|
|
356
|
+
let index = 0;
|
|
357
|
+
|
|
358
|
+
while (index < last && list[index + 1].location >= at) {
|
|
359
|
+
index++;
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
const from = list[index].location,
|
|
363
|
+
to = index < last ? list[index + 1].location : first - period;
|
|
364
|
+
|
|
365
|
+
return index + (to < from ? (from - at) / (from - to) : 0);
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/**
|
|
369
|
+
* Compute the geometry of a carousel from the layout reads: the loop period, the snaps, and the logical snaps.
|
|
370
|
+
* With clones, a logical snap is a snap whose active slide is an original slide.
|
|
371
|
+
*
|
|
372
|
+
* @param {object} layout The result of readLayout().
|
|
373
|
+
* @param {{view: number, slides: Array<{start: number, end: number}>, gap: number}} rects The result of readRects(). The slides after the first count slides are clones.
|
|
374
|
+
* @param {{start: number, size: number}} area The result of visibleArea().
|
|
375
|
+
* @param {number} count The number of original slides.
|
|
376
|
+
* @param {object} options The options of the carousel.
|
|
377
|
+
* @returns {object} The geometry. If the carousel needs a different number of clones, only { copies }: the number of copies of all slides.
|
|
378
|
+
* map gives the logical snap of each snap.
|
|
379
|
+
*/
|
|
380
|
+
export function compute(layout, rects, area, count, options) {
|
|
381
|
+
const content = bounds(rects.slides.slice(0, count)),
|
|
382
|
+
fit = content.size <= rects.view + 1 && !(options.autoScroll && options.loop),
|
|
383
|
+
loop = options.loop && !fit && count,
|
|
384
|
+
// The loop period: the distance from the first slide start to the same point in the next copy of the slides
|
|
385
|
+
period = loop ? bounds(rects.slides).size + rects.gap : 0,
|
|
386
|
+
copies = loop && options.clones ? cloneCount(content.size + rects.gap, area.size, content.max) : 0;
|
|
387
|
+
|
|
388
|
+
if (copies * count !== rects.slides.length - count) {
|
|
389
|
+
return { copies };
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
const geo = { ...layout, ...rects, area, fit, count, period, min: 0, max: 0 };
|
|
393
|
+
|
|
394
|
+
if (fit) {
|
|
395
|
+
geo.snaps = [{ location: 0, slide: activeSlide(rects.slides, 0, rects.view, layout.align) }];
|
|
396
|
+
} else {
|
|
397
|
+
Object.assign(geo, snaps({ ...rects, align: layout.align, slidesPerSnap: options.slidesPerSnap, containScroll: options.containScroll, period }));
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
const list = geo.snaps.map((snap, index) => index).filter((index) => !copies || geo.snaps[index].slide < count);
|
|
401
|
+
|
|
402
|
+
geo.logical = list;
|
|
403
|
+
geo.map = geo.snaps.map((snap, index) => copies ? Math.max(0, list.findIndex((item) => geo.snaps[item].slide % count === snap.slide % count)) : index);
|
|
404
|
+
|
|
405
|
+
return geo;
|
|
406
|
+
}
|
|
407
|
+
|
|
408
|
+
/**
|
|
409
|
+
* Find the snap of a logical snap that is nearest to a location. With clones, a logical snap has more than one snap.
|
|
410
|
+
*
|
|
411
|
+
* @param {{snaps: Array<{location: number}>, map: number[], period: number}} geo The result of compute().
|
|
412
|
+
* @param {number} index The logical snap.
|
|
413
|
+
* @param {number} location
|
|
414
|
+
* @returns {number} The snap index.
|
|
415
|
+
*/
|
|
416
|
+
export function physicalSnap(geo, index, location) {
|
|
417
|
+
let best = -1,
|
|
418
|
+
gap = Infinity;
|
|
419
|
+
|
|
420
|
+
geo.snaps.forEach((snap, item) => {
|
|
421
|
+
const value = Math.abs(distance(snap.location, location, geo.period));
|
|
422
|
+
if (geo.map[item] === index && value < gap) {
|
|
423
|
+
gap = value;
|
|
424
|
+
best = item;
|
|
425
|
+
}
|
|
426
|
+
});
|
|
427
|
+
|
|
428
|
+
return best < 0 ? clamp(index, 0, geo.snaps.length - 1) : best;
|
|
429
|
+
}
|