@evermade/overflow-slider 3.2.0 → 3.2.1

package/README.md

@@ -33,7 +33,7 @@ npm install @evermade/overflow-slider
 
 Import the `OverflowSlider` along with plugins you want to use.
 
-```js
+```ts
 import { OverflowSlider } from '@evermade/overflow-slider';
 import DragScrollingPlugin from '@evermade/overflow-slider/plugins/drag-scrolling';
 import SkipLinksPlugin from '@evermade/overflow-slider/plugins/skip-links';
@@ -135,9 +135,9 @@ Usage:
 	--gap: 1.5rem;
 	gap: var(--gap);
 	> * {
-		--slidesPerView: 3;
+		--slides-per-view: 3;
 		@include slideWidth(
-			var(--slidesPerView),
+			var(--slides-per-view),
 			var(--gap),
 			var(--slider-container-width)
 		);
@@ -149,7 +149,280 @@ Note that if you are using FullWidthPlugin, you should use container width from
 
 ## Plugins
 
-TBA
+### DragScrollingPlugin
+
+This plugin allows you to scroll the slider by dragging with a mouse. This works with items that have links or are links themselves.
+
+```ts
+import DragScrollingPlugin from '@evermade/overflow-slider/plugins/drag-scrolling';
+
+const slider = new OverflowSlider(
+	document.querySelector( '.slider-container-here' ),
+	{},
+	[
+		DragScrollingPlugin(), // add options here or don't
+	]
+);
+```
+
+All options are optional.
+
+```ts
+type DragScrollingOptions = {
+	draggedDistanceThatPreventsClick: number, // default 10, how much user can drag before it's considered a drag and not a click in case of links
+};
+```
+
+### ArrowsPlugin
+
+This plugin adds previous and next arrows to the slider. You can customize the text, icons and class names.
+
+```ts
+import ArrowsPlugin from '@evermade/overflow-slider/plugins/arrows';
+
+const slider = new OverflowSlider(
+	document.querySelector( '.slider-container-here' ),
+	{},
+	[
+		ArrowsPlugin(), // add options here or don't
+	]
+);
+```
+
+All options are optional.
+
+```ts
+type ArrowsOptions = {
+	texts: {
+		buttonPrevious: string;
+		buttonNext: string;
+	},
+	icons: {
+		prev: string; // SVG or other HTML
+		next: string; // SVG or other HTML
+	},
+	classNames: {
+		navContainer: string;
+		prevButton: string;
+		nextButton: string;
+	},
+	container: HTMLElement | null, // container for both arrows
+	containerPrev: HTMLElement | null, // container for previous arrow
+	containerNext: HTMLElement | null, // container for next arrow
+};
+```
+
+### ScrollIndicatorPlugin
+
+This plugin adds a scroll indicator to the slider. The indicator is a bar that shows how much of the slider is scrolled. Scroll indicator is like a custom scrollbar that is always visible.
+
+```ts
+import ScrollIndicatorPlugin from '@evermade/overflow-slider/plugins/scroll-indicator';
+
+const slider = new OverflowSlider(
+	document.querySelector( '.slider-container-here' ),
+	{},
+	[
+		ScrollIndicatorPlugin(), // add options here or don't
+	]
+);
+```
+
+All options are optional.
+
+```ts
+type ScrollIndicatorOptions = {
+	classNames: {
+		scrollIndicator: string;
+		scrollIndicatorBar: string;
+		scrollIndicatorButton: string;
+	},
+	container: HTMLElement | null, // container for the scroll indicator
+};
+```
+
+### DotsPlugin
+
+This plugin adds dots to the slider. Dots are like pagination that shows how many slides there are and which one is active. For usability, scroll indicator is preferable.
+
+```ts
+import DotsPlugin from '@evermade/overflow-slider/plugins/dots';
+
+const slider = new OverflowSlider(
+	document.querySelector( '.slider-container-here' ),
+	{},
+	[
+		DotsPlugin(), // add options here or don't
+	]
+);
+```
+
+All options are optional.
+
+```ts
+type DotsOptions = {
+	texts: {
+		dotDescription: string;
+	},
+	classNames: {
+		dotsContainer: string;
+		dotsItem: string;
+	},
+	container: HTMLElement | null,
+};
+```
+
+### SkipLinksPlugin
+
+This plugin adds skip links to the slider for keyboard users. Skip links are links that allow users to skip the whole slider and land after it. This is useful for accessibility.
+
+```ts
+import SkipLinksPlugin from '@evermade/overflow-slider/plugins/skip-links';
+
+const slider = new OverflowSlider(
+	document.querySelector( '.slider-container-here' ),
+	{},
+	[
+		SkipLinksPlugin(), // add options here or don't
+	]
+);
+```
+
+All options are optional.
+
+```ts
+type SkipLinkOptions = {
+	texts: {
+		skipList: string;
+	},
+	classNames: {
+		skipLink: string;
+		skipLinkTarget: string;
+	},
+	containerBefore: HTMLElement | null,
+	containerAfter: HTMLElement | null,
+};
+```
+
+### FullWidthPlugin
+
+This plugin allows you to make the slider full width but have the start of the sliders aligned to your content width. They are scrollable to the full width but the slides are aligned to the content width for the start and end.
+
+```ts
+import FullWidthPlugin from '@evermade/overflow-slider/plugins/full-width';
+
+const slider = new OverflowSlider(
+	document.querySelector( '.slider-container-here' ),
+	{},
+	[
+		FullWidthPlugin(), // add options here or don't
+	]
+);
+```
+
+All options are optional.
+
+```ts
+type FullWidthOptions = {
+	targetWidth: ( slider: Slider ) => number,
+	addMarginBefore: boolean,
+	addMarginAfter: boolean,
+};
+```
+
+Example of `targetWidth` function:
+
+```ts
+const sliderElement = document.querySelector( '.slider-container-here' );
+const sliderWrapper = document.querySelector( '.slider-wrapper' );
+if ( !sliderElement || !sliderWrapper ) {
+	throw new Error( 'Slider element or wrapper not found' );
+}
+const slider = new OverflowSlider(
+	sliderElement,
+	{},
+	[
+		FullWidthPlugin({
+			targetWidth: ( slider ) => {
+				return sliderWrapper.offsetWidth;
+			},
+		}),
+	]
+);
+```
+
+### FadePlugin
+
+This plugin adds a hint that there are more slides to scroll to. It fades the slides at the start and end of the slider to hint that there are more slides to scroll to.
+
+```ts
+import FadePlugin from '@evermade/overflow-slider/plugins/fade';
+
+const slider = new OverflowSlider(
+	document.querySelector( '.slider-container-here' ),
+	{},
+	[
+		FadePlugin(), // add options here or don't
+	]
+);
+```
+
+All options are optional.
+
+```ts
+type FadeOptions = {
+	classNames: {
+		fadeItem: string;
+		fadeItemStart: string;
+		fadeItemEnd: string;
+	},
+	container: HTMLElement | null,
+	containerStart: HTMLElement | null,
+	containerEnd: HTMLElement | null,
+};
+```
+
+### ThumbnailsPlugin
+
+This plugin adds synchronized thumbnails to the slider. Thumbnails are like dots but they are images of the slides. They are synchronized with the main slider.
+
+```ts
+import ThumbnailsPlugin from '@evermade/overflow-slider/plugins/thumbnails';
+
+const slider = new OverflowSlider(
+	document.querySelector( '.slider-container-here' ),
+	{},
+	[
+		ThumbnailsPlugin(), // add options here or don't
+	]
+);
+```
+
+You need to set mainSlider reference.
+
+```ts
+type ThumbnailsOptions = {
+	mainSlider: Slider,
+}
+```
+
+Example:
+
+```ts
+const mainSlider = new OverflowSlider(
+	document.querySelector( '.slider-container-here' ),
+);
+
+const thumbnailsSlider = new OverflowSlider(
+	document.querySelector( '.thumbnails-container-here' ),
+	{},
+	[
+		ThumbnailsPlugin({
+			mainSlider: mainSlider,
+		}),
+	]
+);
+```
 
 ## Known issues
 
@@ -159,7 +432,7 @@ You can use use Overflow Slider within CSS grid but if you are using `fr` units
 
 ### CSS scroll-snap can be buggy
 
-If you are using `scroll-snap-type` CSS property, you might encounter some bugs like browser wants to snap to a slide regardless of margins.
+If you are using `scroll-snap-type` CSS property, you might encounter some bugs like browser wants to snap to a slide regardless of margins. It's most reliable when there's only one slide per view.
 
 ## Limitations
 
@@ -183,6 +456,11 @@ Auto-play is not supported at the moment but can probably be implemented as a pl
 
 ## Changelog
 
+### 3.2.1
+
+* Add: Documentation on plugins
+* Fix: Make types more strict and remove all "any" types
+
 ### 3.2.0
 
 * Add: RTL support

package/dist/core/slider.esm.js

@@ -78,7 +78,7 @@ function Slider(container, options, plugins) {
         let isScrolling = false;
         let isUserScrolling = false;
         let isProgrammaticScrolling = false;
-        // any scroll
+        // all types of scroll
         slider.container.addEventListener('scroll', () => {
             const newScrollLeft = slider.container.scrollLeft;
             if (Math.floor(scrollLeft) !== Math.floor(newScrollLeft)) {
@@ -463,8 +463,9 @@ function Slider(container, options, plugins) {
             });
         }
         const optionCallBack = (_a = slider === null || slider === void 0 ? void 0 : slider.options) === null || _a === void 0 ? void 0 : _a[name];
+        // Type guard to check if the option callback is a function
         if (typeof optionCallBack === 'function') {
-            optionCallBack(slider);
+            optionCallBack(slider); // Type assertion here
         }
     }
     slider = {

package/dist/core/utils.esm.js

@@ -12,7 +12,8 @@ function objectsAreEqual(obj1, obj2) {
         return false;
     }
     for (let key of keys1) {
-        if (obj2.hasOwnProperty(key) === false || obj1[key] !== obj2[key]) {
+        // Use `Object.prototype.hasOwnProperty.call` for better safety
+        if (!Object.prototype.hasOwnProperty.call(obj2, key) || obj1[key] !== obj2[key]) {
             return false;
         }
     }

package/dist/core/utils.min.js

@@ -1 +1 @@
-function e(t,n=1){const r=`${t}-${n}`;return document.getElementById(r)?e(t,n+1):r}function t(e,t){const n=Object.keys(e),r=Object.keys(t);if(n.length!==r.length)return!1;for(let r of n)if(!1===t.hasOwnProperty(r)||e[r]!==t[r])return!1;return!0}function n(e){if(0===e.children.length)return 0;const t=e.children[0],n=getComputedStyle(t),r=parseFloat(n.marginLeft),o=e.children[e.children.length-1],l=getComputedStyle(o);return r+parseFloat(l.marginRight)}export{e as generateId,n as getOutermostChildrenEdgeMarginSum,t as objectsAreEqual};
+function t(e,n=1){const r=`${e}-${n}`;return document.getElementById(r)?t(e,n+1):r}function e(t,e){const n=Object.keys(t),r=Object.keys(e);if(n.length!==r.length)return!1;for(let r of n)if(!Object.prototype.hasOwnProperty.call(e,r)||t[r]!==e[r])return!1;return!0}function n(t){if(0===t.children.length)return 0;const e=t.children[0],n=getComputedStyle(e),r=parseFloat(n.marginLeft),o=t.children[t.children.length-1],l=getComputedStyle(o);return r+parseFloat(l.marginRight)}export{t as generateId,n as getOutermostChildrenEdgeMarginSum,e as objectsAreEqual};

package/docs/dist/core/slider.esm.js

@@ -78,7 +78,7 @@ function Slider(container, options, plugins) {
         let isScrolling = false;
         let isUserScrolling = false;
         let isProgrammaticScrolling = false;
-        // any scroll
+        // all types of scroll
         slider.container.addEventListener('scroll', () => {
             const newScrollLeft = slider.container.scrollLeft;
             if (Math.floor(scrollLeft) !== Math.floor(newScrollLeft)) {
@@ -463,8 +463,9 @@ function Slider(container, options, plugins) {
             });
         }
         const optionCallBack = (_a = slider === null || slider === void 0 ? void 0 : slider.options) === null || _a === void 0 ? void 0 : _a[name];
+        // Type guard to check if the option callback is a function
         if (typeof optionCallBack === 'function') {
-            optionCallBack(slider);
+            optionCallBack(slider); // Type assertion here
         }
     }
     slider = {

package/docs/dist/core/utils.esm.js

@@ -12,7 +12,8 @@ function objectsAreEqual(obj1, obj2) {
         return false;
     }
     for (let key of keys1) {
-        if (obj2.hasOwnProperty(key) === false || obj1[key] !== obj2[key]) {
+        // Use `Object.prototype.hasOwnProperty.call` for better safety
+        if (!Object.prototype.hasOwnProperty.call(obj2, key) || obj1[key] !== obj2[key]) {
             return false;
         }
     }

package/docs/dist/core/utils.min.js

@@ -1 +1 @@
-function e(t,n=1){const r=`${t}-${n}`;return document.getElementById(r)?e(t,n+1):r}function t(e,t){const n=Object.keys(e),r=Object.keys(t);if(n.length!==r.length)return!1;for(let r of n)if(!1===t.hasOwnProperty(r)||e[r]!==t[r])return!1;return!0}function n(e){if(0===e.children.length)return 0;const t=e.children[0],n=getComputedStyle(t),r=parseFloat(n.marginLeft),o=e.children[e.children.length-1],l=getComputedStyle(o);return r+parseFloat(l.marginRight)}export{e as generateId,n as getOutermostChildrenEdgeMarginSum,t as objectsAreEqual};
+function t(e,n=1){const r=`${e}-${n}`;return document.getElementById(r)?t(e,n+1):r}function e(t,e){const n=Object.keys(t),r=Object.keys(e);if(n.length!==r.length)return!1;for(let r of n)if(!Object.prototype.hasOwnProperty.call(e,r)||t[r]!==e[r])return!1;return!0}function n(t){if(0===t.children.length)return 0;const e=t.children[0],n=getComputedStyle(e),r=parseFloat(n.marginLeft),o=t.children[t.children.length-1],l=getComputedStyle(o);return r+parseFloat(l.marginRight)}export{t as generateId,n as getOutermostChildrenEdgeMarginSum,e as objectsAreEqual};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@evermade/overflow-slider",
-	"version": "3.2.0",
+	"version": "3.2.1",
 	"description": "Accessible slider tha works with overflow: auto.",
 	"type": "module",
 	"main": "dist/index.js",

package/src/core/slider.ts

@@ -1,10 +1,10 @@
-import { Slider, SliderOptions, SliderPlugin } from './types';
+import { Slider, SliderOptions, SliderPlugin, SliderCallback } from './types';
 import details from './details';
 import { generateId, objectsAreEqual, getOutermostChildrenEdgeMarginSum } from './utils';
 
 export default function Slider( container: HTMLElement, options : SliderOptions, plugins? : SliderPlugin[] ) {
 	let slider: Slider;
-	let subs: { [key: string]: any[] } = {};
+	let subs: { [key: string]: SliderCallback[] } = {};
 
 	function init() {
 		slider.container = container;
@@ -91,7 +91,7 @@ export default function Slider( container: HTMLElement, options : SliderOptions,
 		let isUserScrolling = false;
 		let isProgrammaticScrolling = false;
 
-		// any scroll
+		// all types of scroll
 		slider.container.addEventListener('scroll', () => {
 			const newScrollLeft = slider.container.scrollLeft;
 			if ( Math.floor( scrollLeft ) !== Math.floor( newScrollLeft ) ) {
@@ -490,7 +490,7 @@ export default function Slider( container: HTMLElement, options : SliderOptions,
 		}
 	};
 
-	function on(name: string, cb: any) {
+	function on(name: string, cb: SliderCallback) {
 		if (!subs[name]) {
 			subs[name] = [];
 		}
@@ -500,12 +500,14 @@ export default function Slider( container: HTMLElement, options : SliderOptions,
 	function emit(name: string) {
 		if (subs && subs[name]) {
 			subs[name].forEach(cb => {
-					cb(slider);
+				cb(slider);
 			});
 		}
+
 		const optionCallBack = slider?.options?.[name];
+		// Type guard to check if the option callback is a function
 		if (typeof optionCallBack === 'function') {
-				optionCallBack(slider);
+			(optionCallBack as SliderCallback)(slider); // Type assertion here
 		}
 	};
 

package/src/core/types.ts

@@ -17,13 +17,17 @@ export type Slider<O = {}, C = {}, H extends string = string> = {
 	setScrollLeft: (value: number) => void
 	on: (
 		name: H | SliderHooks,
-		cb: (props: Slider<O, C, H>) => void
+		cb: SliderCallback
 	) => void
 	options: SliderOptions,
 	details: SliderDetails,
 	activeSlideIdx: number,
 } & C;
 
+export type SliderCallback<O = {}, C = {}, H extends string = string> = (
+	props: Slider<O, C, H>
+) => void;
+
 export type SliderOptions = {
 	scrollBehavior: string;
 	scrollStrategy: string;
@@ -31,7 +35,7 @@ export type SliderOptions = {
 	emulateScrollSnap: boolean;
 	emulateScrollSnapMaxThreshold: number;
 	rtl: boolean;
-	[key: string]: any;
+	[key: string]: unknown;
 }
 
 export type SliderDetails = {
@@ -65,7 +69,7 @@ export type HOOK_CONTENTS_CHANGED = 'contentsChanged';
 export type HOOK_CONTAINER_SIZE_CHANGED = 'containerSizeChanged';
 export type HOOK_ACTIVE_SLIDE_CHANGED = 'activeSlideChanged';
 
-// any type of scroll
+// all types of scroll
 export type HOOK_SCROLL_START = 'scrollStart';
 export type HOOK_SCROLL = 'scroll';
 export type HOOK_SCROLL_END = 'scrollEnd';

package/src/core/utils.ts

@@ -7,17 +7,21 @@ function generateId( prefix : string, i = 1 ): string {
 	return id;
 }
 
-function objectsAreEqual( obj1: any, obj2: any ) {
+function objectsAreEqual(obj1: Record<string, unknown>, obj2: Record<string, unknown>): boolean {
 	const keys1 = Object.keys(obj1);
 	const keys2 = Object.keys(obj2);
+
 	if (keys1.length !== keys2.length) {
-			return false;
+		return false;
 	}
+
 	for (let key of keys1) {
-			if (obj2.hasOwnProperty(key) === false || obj1[key] !== obj2[key]) {
-					return false;
-			}
+		// Use `Object.prototype.hasOwnProperty.call` for better safety
+		if (!Object.prototype.hasOwnProperty.call(obj2, key) || obj1[key] !== obj2[key]) {
+			return false;
+		}
 	}
+
 	return true;
 }
 

package/src/plugins/arrows/index.ts

@@ -35,7 +35,7 @@ export type ArrowsOptions = {
 	containerNext: HTMLElement | null,
 };
 
-export default function ArrowsPlugin( args: { [key: string]: any } ) {
+export default function ArrowsPlugin( args: { [key: string]: unknown } ) {
 	return ( slider: Slider ) => {
 
 		const options = <ArrowsOptions>{

package/src/plugins/dots/index.ts

@@ -20,7 +20,7 @@ const DEFAULT_CLASS_NAMES = {
 	dotsItem: 'overflow-slider__dot-item',
 };
 
-export default function DotsPlugin( args: { [key: string]: any } ) {
+export default function DotsPlugin( args: { [key: string]: unknown } ) {
 	return ( slider: Slider ) => {
 		const options = <DotsOptions>{
 			texts: {

package/src/plugins/drag-scrolling/index.ts

@@ -6,7 +6,7 @@ export type DragScrollingOptions = {
 	draggedDistanceThatPreventsClick: number,
 };
 
-export default function DragScrollingPlugin( args: { [key: string]: any } ) {
+export default function DragScrollingPlugin( args: { [key: string]: unknown } ) {
 	const options = <DragScrollingOptions>{
 		draggedDistanceThatPreventsClick: args?.draggedDistanceThatPreventsClick ?? DEFAULT_DRAGGED_DISTANCE_THAT_PREVENTS_CLICK,
 	};

package/src/plugins/fade/index.ts

@@ -11,7 +11,7 @@ export type FadeOptions = {
 	containerEnd: HTMLElement | null,
 };
 
-export default function FadePlugin( args: { [key: string]: any } ) {
+export default function FadePlugin( args: { [key: string]: unknown } ) {
 	return ( slider: Slider ) => {
 
 		const options = <FadeOptions>{

package/src/plugins/full-width/index.ts

@@ -8,7 +8,7 @@ export type FullWidthOptions = {
 	addMarginAfter: boolean,
 };
 
-export default function FullWidthPlugin( args: { [key: string]: any } ) {
+export default function FullWidthPlugin( args: { [key: string]: unknown } ) {
 	return ( slider: Slider ) => {
 
 		const options = <FullWidthOptions>{

package/src/plugins/scroll-indicator/index.ts

@@ -15,7 +15,7 @@ export type ScrollIndicatorOptions = {
 	container: HTMLElement | null,
 };
 
-export default function ScrollIndicatorPlugin(args: { [key: string]: any }) {
+export default function ScrollIndicatorPlugin(args: { [key: string]: unknown }) {
 	return (slider: Slider) => {
 
 		const options = <ScrollIndicatorOptions>{

package/src/plugins/skip-links/index.ts

@@ -22,7 +22,7 @@ export type SkipLinkOptions = {
 	containerAfter: HTMLElement | null,
 };
 
-export default function SkipLinksPlugin( args: { [key: string]: any } ) {
+export default function SkipLinksPlugin( args: { [key: string]: unknown } ) {
 	return ( slider: Slider ) => {
 		const options = <SkipLinkOptions>{
 			texts: {

package/src/plugins/thumbnails/index.ts

@@ -4,7 +4,7 @@ export type ThumbnailsOptions = {
 	mainSlider: Slider,
 };
 
-export default function FullWidthPlugin( args: { [key: string]: any } ) {
+export default function FullWidthPlugin( args: { [key: string]: unknown } ) {
 	return ( slider: Slider ) => {
 
 		const options = <ThumbnailsOptions>{