@twistedandy/better-carousel 1.0.0 → 1.1.1

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.
@@ -1,139 +1,139 @@
1
- // The types of Better Carousel. The members of Options come from scripts/reference.js: run "npm run docs" after a change there.
2
- // The other types are written by hand. tests/docs.test.js compares the options and the events with the code.
3
-
4
- /** The options of the autoplay. */
5
- export interface AutoplayOptions {
6
- /** The time on each slide, in ms, or an array with one time for each snap. A `data-delay` attribute on a slide sets the time of that slide. @default 4000 */
7
- delay?: number | number[];
8
- /** A drag, an arrow or a dot stops the autoplay. @default true */
9
- stopOnInteraction?: boolean;
10
- /** Pause while the mouse is on the carousel. @default false */
11
- pauseOnHover?: boolean;
12
- /** Pause while the keyboard focus is in the carousel. @default true */
13
- pauseOnFocus?: boolean;
14
- /** Stop at the last snap, if `loop` is `false`. @default false */
15
- stopOnLastSnap?: boolean;
16
- /** Start with the carousel. @default true */
17
- playOnInit?: boolean;
18
- /** Jump to the next slide with no motion. @default false */
19
- instant?: boolean;
20
- /**
21
- * Show the time to the next slide. The carousel calls this function when the timer starts, with the delay in ms.
22
- * The function can return a function that the carousel calls when this timer ends or stops. @default null
23
- */
24
- timer?: ((delay: number, carousel: Carousel) => (() => void) | void) | null;
25
- }
26
-
27
- /** The options of the auto scroll. */
28
- export interface AutoScrollOptions {
29
- /** The speed in px per second. @default 120 */
30
- speed?: number;
31
- /** @default 'next' */
32
- direction?: 'next' | 'prev';
33
- /** The time in ms before the start, and after an interaction. @default 1000 */
34
- startDelay?: number;
35
- /** A drag, an arrow or a dot stops the auto scroll. @default true */
36
- stopOnInteraction?: boolean;
37
- /** Pause while the mouse is on the carousel. @default false */
38
- pauseOnHover?: boolean;
39
- /** Pause while the keyboard focus is in the carousel. @default true */
40
- pauseOnFocus?: boolean;
41
- /** Start with the carousel. @default true */
42
- playOnInit?: boolean;
43
- }
44
-
45
- /** The state that the `progress` callback gets. The carousel uses the same object for each call: read the values during the call. */
46
- export interface ProgressState {
47
- /** The progress, from 0 to 1. In loop mode, it goes from 1 back to 0. */
48
- progress: number;
49
- /** The position between the snaps: 2.4 is between snap 2 and snap 3. */
50
- snap: number;
51
- }
52
-
53
- /** The state that the `offset` callback gets for a slide. The carousel uses the same object for each call: read the values during the call. */
54
- export interface OffsetState {
55
- /** The slide element, or a clone of it. */
56
- node: HTMLElement;
57
- /** The slide index. A clone gives the index of its slide. */
58
- index: number;
59
- /** The distance from the snap position of the slide, in slides: 0 at the snap position, 1 for the next slide, -1 for the previous slide. */
60
- offset: number;
61
- /** The same distance in px, on the screen: a positive value is to the right or down. */
62
- distance: number;
63
- /** The size of the slide on the main axis, in px. */
64
- size: number;
65
- /** The part of the slide in the viewport, from 0 to 1. */
66
- visible: number;
67
- }
68
-
69
- /** The texts for screen readers. `%d` is the slide number, and `%n` is the number of slides. */
70
- export interface Labels {
71
- /** @default 'Carousel' */
72
- carousel?: string;
73
- /** @default '%d of %n' */
74
- slide?: string;
75
- /** @default 'Previous slide' */
76
- prev?: string;
77
- /** @default 'Next slide' */
78
- next?: string;
79
- /** @default 'Go to slide %d' */
80
- dot?: string;
81
- /** @default 'Start the slide show' */
82
- play?: string;
83
- /** @default 'Stop the slide show' */
84
- pause?: string;
85
- }
86
-
87
- /** The class names to change. `prefix` sets the names that the object does not change. */
88
- export interface ClassNames {
89
- /** @default 'better' */
90
- prefix?: string;
91
- root?: string;
92
- viewport?: string;
93
- container?: string;
94
- /** On the root, if all slides fit. */
95
- fit?: string;
96
- horizontal?: string;
97
- vertical?: string;
98
- /** On the root, with `autoHeight`. */
99
- autoHeight?: string;
100
- button?: string;
101
- prevButton?: string;
102
- nextButton?: string;
103
- /** The window of the dots. */
104
- dots?: string;
105
- /** The row of the dots that slides in the window. */
106
- dotsTrack?: string;
107
- /** The marker of the selected dot, on top of the dots. */
108
- dotsMarker?: string;
109
- /** On the window of the dots, with `dotsStyle: 'all'`. */
110
- dotsAll?: string;
111
- dot?: string;
112
- playButton?: string;
113
- /** @default 'clone' */
114
- clone?: string;
115
- /** The selected slide. @default 'selected' */
116
- selected?: string;
117
- /** The slides in view. The default is an empty string: no class. */
118
- inView?: string;
119
- /** @default 'dragging' */
120
- dragging?: string;
121
- /** @default 'playing' */
122
- playing?: string;
123
- /** The dot two places before the selected dot. @default 'first' */
124
- first?: string;
125
- /** The dot before the selected dot. @default 'prev' */
126
- prev?: string;
127
- /** The selected dot. @default 'current' */
128
- current?: string;
129
- /** The dot after the selected dot. @default 'next' */
130
- next?: string;
131
- /** The dot two places after the selected dot. @default 'last' */
132
- last?: string;
133
- }
134
-
135
- /** The options. Set them in the call, in the `data-carousel` attribute as JSON, or in `BetterCarousel.defaults`. */
136
- export interface Options {
1
+ // The types of Better Carousel. The members of Options come from scripts/reference.js: run "npm run docs" after a change there.
2
+ // The other types are written by hand. tests/docs.test.js compares the options and the events with the code.
3
+
4
+ /** The options of the autoplay. */
5
+ export interface AutoplayOptions {
6
+ /** The time on each slide, in ms, or an array with one time for each snap. A `data-delay` attribute on a slide sets the time of that slide. @default 4000 */
7
+ delay?: number | number[];
8
+ /** A drag, an arrow or a dot stops the autoplay. @default true */
9
+ stopOnInteraction?: boolean;
10
+ /** Pause while the mouse is on the carousel. @default false */
11
+ pauseOnHover?: boolean;
12
+ /** Pause while the keyboard focus is in the carousel. @default true */
13
+ pauseOnFocus?: boolean;
14
+ /** Stop at the last snap, if `loop` is `false`. @default false */
15
+ stopOnLastSnap?: boolean;
16
+ /** Start with the carousel. @default true */
17
+ playOnInit?: boolean;
18
+ /** Jump to the next slide with no motion. @default false */
19
+ instant?: boolean;
20
+ /**
21
+ * Show the time to the next slide. The carousel calls this function when the timer starts, with the delay in ms.
22
+ * The function can return a function that the carousel calls when this timer ends or stops. @default null
23
+ */
24
+ timer?: ((delay: number, carousel: Carousel) => (() => void) | void) | null;
25
+ }
26
+
27
+ /** The options of the auto scroll. */
28
+ export interface AutoScrollOptions {
29
+ /** The speed in px per second. @default 120 */
30
+ speed?: number;
31
+ /** @default 'next' */
32
+ direction?: 'next' | 'prev';
33
+ /** The time in ms before the start, and after an interaction. @default 1000 */
34
+ startDelay?: number;
35
+ /** A drag, an arrow or a dot stops the auto scroll. @default true */
36
+ stopOnInteraction?: boolean;
37
+ /** Pause while the mouse is on the carousel. @default false */
38
+ pauseOnHover?: boolean;
39
+ /** Pause while the keyboard focus is in the carousel. @default true */
40
+ pauseOnFocus?: boolean;
41
+ /** Start with the carousel. @default true */
42
+ playOnInit?: boolean;
43
+ }
44
+
45
+ /** The state that the `progress` callback gets. The carousel uses the same object for each call: read the values during the call. */
46
+ export interface ProgressState {
47
+ /** The progress, from 0 to 1. In loop mode, it goes from 1 back to 0. */
48
+ progress: number;
49
+ /** The position between the snaps: 2.4 is between snap 2 and snap 3. */
50
+ snap: number;
51
+ }
52
+
53
+ /** The state that the `offset` callback gets for a slide. The carousel uses the same object for each call: read the values during the call. */
54
+ export interface OffsetState {
55
+ /** The slide element, or a clone of it. */
56
+ node: HTMLElement;
57
+ /** The slide index. A clone gives the index of its slide. */
58
+ index: number;
59
+ /** The distance from the snap position of the slide, in slides: 0 at the snap position, 1 for the next slide, -1 for the previous slide. */
60
+ offset: number;
61
+ /** The same distance in px, on the screen: a positive value is to the right or down. */
62
+ distance: number;
63
+ /** The size of the slide on the main axis, in px. */
64
+ size: number;
65
+ /** The part of the slide in the viewport, from 0 to 1. */
66
+ visible: number;
67
+ }
68
+
69
+ /** The texts for screen readers. `%d` is the slide number, and `%n` is the number of slides. */
70
+ export interface Labels {
71
+ /** @default 'Carousel' */
72
+ carousel?: string;
73
+ /** @default '%d of %n' */
74
+ slide?: string;
75
+ /** @default 'Previous slide' */
76
+ prev?: string;
77
+ /** @default 'Next slide' */
78
+ next?: string;
79
+ /** @default 'Go to slide %d' */
80
+ dot?: string;
81
+ /** @default 'Start the slide show' */
82
+ play?: string;
83
+ /** @default 'Stop the slide show' */
84
+ pause?: string;
85
+ }
86
+
87
+ /** The class names to change. `prefix` sets the names that the object does not change. */
88
+ export interface ClassNames {
89
+ /** @default 'better' */
90
+ prefix?: string;
91
+ root?: string;
92
+ viewport?: string;
93
+ container?: string;
94
+ /** On the root, if all slides fit. */
95
+ fit?: string;
96
+ horizontal?: string;
97
+ vertical?: string;
98
+ /** On the root, with `autoHeight`. */
99
+ autoHeight?: string;
100
+ button?: string;
101
+ prevButton?: string;
102
+ nextButton?: string;
103
+ /** The window of the dots. */
104
+ dots?: string;
105
+ /** The row of the dots that slides in the window. */
106
+ dotsTrack?: string;
107
+ /** The marker of the selected dot, on top of the dots. */
108
+ dotsMarker?: string;
109
+ /** On the window of the dots, with `dotsStyle: 'all'`. */
110
+ dotsAll?: string;
111
+ dot?: string;
112
+ playButton?: string;
113
+ /** @default 'clone' */
114
+ clone?: string;
115
+ /** The selected slide. @default 'selected' */
116
+ selected?: string;
117
+ /** The slides in view. The default is an empty string: no class. */
118
+ inView?: string;
119
+ /** @default 'dragging' */
120
+ dragging?: string;
121
+ /** @default 'playing' */
122
+ playing?: string;
123
+ /** The dot two places before the selected dot. @default 'first' */
124
+ first?: string;
125
+ /** The dot before the selected dot. @default 'prev' */
126
+ prev?: string;
127
+ /** The selected dot. @default 'current' */
128
+ current?: string;
129
+ /** The dot after the selected dot. @default 'next' */
130
+ next?: string;
131
+ /** The dot two places after the selected dot. @default 'last' */
132
+ last?: string;
133
+ }
134
+
135
+ /** The options. Set them in the call, in the `data-carousel` attribute as JSON, or in `BetterCarousel.defaults`. */
136
+ export interface Options {
137
137
  // <!-- generated:options -->
138
138
  /** The axis of the motion. With `'auto'`, the CSS of the container sets the axis. @default 'auto' @see {@link https://twistedandy.github.io/better-carousel/#switch | example} */
139
139
  axis?: 'x' | 'y' | 'auto';
@@ -211,99 +211,99 @@ export interface Options {
211
211
  progress?: boolean | ((state: ProgressState, carousel: Carousel) => void);
212
212
  /** Follow the distance of each slide from its snap position, in slides. `true` sets `--better-offset` on each slide. A function gets `{ node, index, offset, distance, size, visible }` for each slide on each frame of a motion. @default false */
213
213
  offset?: boolean | ((state: OffsetState, carousel: Carousel) => void);
214
- // <!-- /generated -->
215
- }
216
-
217
- /** The names of the events. */
218
- export type EventName =
219
- | 'init'
220
- | 'reinit'
221
- | 'resize'
222
- | 'select'
223
- | 'scroll'
224
- | 'settle'
225
- | 'dragstart'
226
- | 'dragend'
227
- | 'slidesinview'
228
- | 'slideschanged'
229
- | 'slidefocus'
230
- | 'autoplay:play'
231
- | 'autoplay:stop'
232
- | 'autoscroll:play'
233
- | 'autoscroll:stop'
234
- | 'destroy';
235
-
236
- export type EventHandler = (carousel: Carousel, name: EventName) => void;
237
-
238
- /** The control of the auto scroll. */
239
- export interface PlayControl {
240
- play(): void;
241
- stop(): void;
242
- isPlaying(): boolean;
243
- }
244
-
245
- /** The control of the autoplay. */
246
- export interface AutoplayControl extends PlayControl {
247
- /** Start the delay again. */
248
- reset(): void;
249
- }
250
-
251
- /** A carousel. A snap index and a slide index are different: a snap can show more than one slide. */
252
- export interface Carousel {
253
- /** Go to a snap. With `instant` set to `true`, jump with no motion. */
254
- goToSnap(snap: number, instant?: boolean): void;
255
- goToNext(instant?: boolean): void;
256
- goToPrev(instant?: boolean): void;
257
- /** Go to the snap that shows a slide. This slide becomes the selected slide. */
258
- goToSlide(slide: number, instant?: boolean): void;
259
- /** `true` if a next snap exists. In a loop, `true` if not all slides fit. */
260
- canGoToNext(): boolean;
261
- /** `true` if a previous snap exists. In a loop, `true` if not all slides fit. */
262
- canGoToPrev(): boolean;
263
- /** The index of the selected snap. */
264
- selectedSnap(): number;
265
- /** The index of the snap before the selected snap. */
266
- previousSnap(): number;
267
- /** The index of the selected slide. With `sync`, the slide that is selected in the other carousel. */
268
- selectedSlide(): number;
269
- /** The index of the snap that shows a slide. */
270
- snapOfSlide(slide: number): number;
271
- /** The progress of each snap, from 0 to 1. */
272
- snapProgress(): number[];
273
- /** The progress now, from 0 to 1, also during a motion. */
274
- progress(): number;
275
- /** The indexes of the slides in view. */
276
- slidesInView(): number[];
277
- /** The slides. The list does not include the clones. */
278
- slideNodes(): HTMLElement[];
279
- rootNode(): HTMLElement;
280
- viewportNode(): HTMLElement;
281
- containerNode(): HTMLElement;
282
- /** `true` if all slides fit in the viewport. */
283
- isFit(): boolean;
284
- /** The options that apply now, after the breakpoints. */
285
- options(): Options;
286
- /** Merge new options and start again. The selected slide stays. */
287
- reinit(options?: Options): void;
288
- /** Stop the carousel and restore the markup. */
289
- destroy(): void;
290
- on(name: EventName, handler: EventHandler): Carousel;
291
- off(name: EventName, handler: EventHandler): Carousel;
292
- /** Only with the `autoplay` option. */
293
- autoplay?: AutoplayControl;
294
- /** Only with the `autoScroll` option. */
295
- autoScroll?: PlayControl;
296
- }
297
-
298
- declare const BetterCarousel: {
299
- /** Start a carousel on a container or on its viewport. If the element has a carousel, return that carousel. */
300
- (element: HTMLElement, options?: Options): Carousel;
301
- /** The options for all carousels. Set it before you start the carousels. */
302
- defaults: Options;
303
- /** The carousel of a root, a viewport or a container. */
304
- get(element: Element): Carousel | undefined;
305
- /** Start a carousel on each element that matches the selector. */
306
- initAll(selector: string, options?: Options): Carousel[];
307
- };
308
-
309
- export default BetterCarousel;
214
+ // <!-- /generated -->
215
+ }
216
+
217
+ /** The names of the events. */
218
+ export type EventName =
219
+ | 'init'
220
+ | 'reinit'
221
+ | 'resize'
222
+ | 'select'
223
+ | 'scroll'
224
+ | 'settle'
225
+ | 'dragstart'
226
+ | 'dragend'
227
+ | 'slidesinview'
228
+ | 'slideschanged'
229
+ | 'slidefocus'
230
+ | 'autoplay:play'
231
+ | 'autoplay:stop'
232
+ | 'autoscroll:play'
233
+ | 'autoscroll:stop'
234
+ | 'destroy';
235
+
236
+ export type EventHandler = (carousel: Carousel, name: EventName) => void;
237
+
238
+ /** The control of the auto scroll. */
239
+ export interface PlayControl {
240
+ play(): void;
241
+ stop(): void;
242
+ isPlaying(): boolean;
243
+ }
244
+
245
+ /** The control of the autoplay. */
246
+ export interface AutoplayControl extends PlayControl {
247
+ /** Start the delay again. */
248
+ reset(): void;
249
+ }
250
+
251
+ /** A carousel. A snap index and a slide index are different: a snap can show more than one slide. */
252
+ export interface Carousel {
253
+ /** Go to a snap. With `instant` set to `true`, jump with no motion. */
254
+ goToSnap(snap: number, instant?: boolean): void;
255
+ goToNext(instant?: boolean): void;
256
+ goToPrev(instant?: boolean): void;
257
+ /** Go to the snap that shows a slide. This slide becomes the selected slide. */
258
+ goToSlide(slide: number, instant?: boolean): void;
259
+ /** `true` if a next snap exists. In a loop, `true` if not all slides fit. */
260
+ canGoToNext(): boolean;
261
+ /** `true` if a previous snap exists. In a loop, `true` if not all slides fit. */
262
+ canGoToPrev(): boolean;
263
+ /** The index of the selected snap. */
264
+ selectedSnap(): number;
265
+ /** The index of the snap before the selected snap. */
266
+ previousSnap(): number;
267
+ /** The index of the selected slide. With `sync`, the slide that is selected in the other carousel. */
268
+ selectedSlide(): number;
269
+ /** The index of the snap that shows a slide. */
270
+ snapOfSlide(slide: number): number;
271
+ /** The progress of each snap, from 0 to 1. */
272
+ snapProgress(): number[];
273
+ /** The progress now, from 0 to 1, also during a motion. */
274
+ progress(): number;
275
+ /** The indexes of the slides in view. */
276
+ slidesInView(): number[];
277
+ /** The slides. The list does not include the clones. */
278
+ slideNodes(): HTMLElement[];
279
+ rootNode(): HTMLElement;
280
+ viewportNode(): HTMLElement;
281
+ containerNode(): HTMLElement;
282
+ /** `true` if all slides fit in the viewport. */
283
+ isFit(): boolean;
284
+ /** The options that apply now, after the breakpoints. */
285
+ options(): Options;
286
+ /** Merge new options and start again. The selected slide stays. */
287
+ reinit(options?: Options): void;
288
+ /** Stop the carousel and restore the markup. */
289
+ destroy(): void;
290
+ on(name: EventName, handler: EventHandler): Carousel;
291
+ off(name: EventName, handler: EventHandler): Carousel;
292
+ /** Only with the `autoplay` option. */
293
+ autoplay?: AutoplayControl;
294
+ /** Only with the `autoScroll` option. */
295
+ autoScroll?: PlayControl;
296
+ }
297
+
298
+ declare const BetterCarousel: {
299
+ /** Start a carousel on a container or on its viewport. If the element has a carousel, return that carousel. */
300
+ (element: HTMLElement, options?: Options): Carousel;
301
+ /** The options for all carousels. Set it before you start the carousels. */
302
+ defaults: Options;
303
+ /** The carousel of a root, a viewport or a container. */
304
+ get(element: Element): Carousel | undefined;
305
+ /** Start a carousel on each element that matches the selector. */
306
+ initAll(selector: string, options?: Options): Carousel[];
307
+ };
308
+
309
+ export default BetterCarousel;