astro-swiper 2.2.1 → 2.3.0

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "astro-swiper",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "Astro component for swiper, dedicated to slider / carousel / photo swiper / slide, including thumbnails",
+  "type": "module",
   "main": "index.js",
   "scripts": {
     "format": "biome format --write && prettier -w \"**/*.astro\"",
@@ -18,14 +19,19 @@
     "url": "https://github.com/pascal-brand38/astro-swiper/issues"
   },
   "homepage": "https://github.com/pascal-brand38/astro-swiper",
-  "exports": "./index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "default": "./index.ts"
+    }
+  },
   "files": [
     "index.ts",
     "src/**"
   ],
   "engines": {
     "pnpm": ">=10.30.3",
-    "node": ">=22"
+    "node": ">=20"
   },
   "packageManager": "pnpm@10.30.3",
   "devDependencies": {

package/src/components/Swiper.astro

@@ -43,13 +43,13 @@ const {
 
 <script>
   import Swiper from 'swiper/bundle';
-  import type { SwiperOptions } from 'swiper/types';
+  import type { AstroSwiperOptions } from 'astro-swiper';
 
   /** contains the swiper json object once created, for each uniqueClass */
   const _useSwiper: { [uniqueClass: string]: Swiper } = {};
 
   /** contains the option used when creating the swiper object for each uniqueClass */
-  const _useOptions: { [uniqueClass: string]: SwiperOptions } = {};
+  const _useOptions: { [uniqueClass: string]: AstroSwiperOptions } = {};
 
   /** contains all the uniqueClass that have their swiper object delayed because the
    * related thumbnail swiper is not created yet
@@ -57,6 +57,92 @@ const {
    */
   const _useDelaySwiper: { [uniqueClass: string]: string } = {};
 
+  // Init swipers that have delayed initialization because the thumbnail swiper is not created yet
+  // If this is now the case, then it is intialized, as well as its observer if needed
+  function _initDelayedSwipers() {
+    Object.keys(_useDelaySwiper).forEach((delayedClass) => {
+      // swiper of uniqueClass "delayedClass" is delayed because it needs the swiper of uniqueClass
+      // "delayedThumbClass" to be created first
+      const delayedThumbClass = _useDelaySwiper[delayedClass];
+      if (_useSwiper[delayedThumbClass]) {
+        // the thumbnail swiper is created, we can create the swiper
+        delete _useDelaySwiper[delayedClass]; // remove it from the delayed list
+        const delayedOptions = _useOptions[delayedClass];
+        delayedOptions.thumbs = {
+          swiper: _useSwiper[delayedThumbClass],    // add the thumbnail swiper link to the options
+          ...delayedOptions.thumbs,
+        };
+
+        _createSwiperAndObserver(delayedClass, delayedOptions, (document.querySelector(`.${delayedClass}`) as AstroSwiper));
+        _useOptions[delayedClass] = delayedOptions;   // update the options with the thumbnail link
+      }
+    });
+  }
+
+  // initialize the swiper instance
+  // the autoplay may be stopped manually if it should be started by the observer
+  function _initSwiper(uniqueClass: string, options: AstroSwiperOptions, element: AstroSwiper) {
+    const swiper = new Swiper(`.${uniqueClass}`, options);
+    _useSwiper[uniqueClass] = swiper;
+    element.astroSwiper = swiper;
+
+    // stop the autoplay if it will be started by the observer
+    if (options.astro?.intersectionObserver?.controlAutoplay && options.autoplay) {
+      swiper.autoplay.stop();
+    }
+
+    _initDelayedSwipers();
+    return swiper;
+  }
+
+  function _createObserver(uniqueClass: string, options: AstroSwiperOptions, element: AstroSwiper) {
+    const observerOptions = options.astro?.intersectionObserver || {};
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries[0].isIntersecting) {
+          if (observerOptions?.initSwiper && !element.astroSwiper) {
+            _initSwiper(uniqueClass, options, element);
+            if (observerOptions?.disconnectOnInit) {
+              observer.disconnect();
+            }
+          }
+        }
+
+        const swiper = element?.astroSwiper
+        if (!swiper) {
+          return;
+        }
+
+        if (observerOptions?.controlAutoplay && options.autoplay) {
+          if (entries[0].isIntersecting) {
+            swiper.autoplay.start();
+          } else {
+            swiper.autoplay.stop();
+          }
+        }
+      },
+      observerOptions.options,
+    );
+
+    observer.observe(element);
+    window.addEventListener("unload", observer.disconnect);
+  }
+
+  // create the swiper and the observer
+  // - init the swiper if it should not be done by the observer
+  // - create the observer if required
+  function _createSwiperAndObserver(uniqueClass: string, options: AstroSwiperOptions, element: AstroSwiper) {
+    if (!(options.astro?.intersectionObserver?.initSwiper)) {
+      // create the swiper immediatly
+      _initSwiper(uniqueClass, options, element);
+    }
+
+    // create the observer. It may init the swiper
+    if (options.astro?.intersectionObserver) {
+      _createObserver(uniqueClass, options, element);
+    }
+  }
+
   class AstroSwiper extends HTMLElement {
     /** pointer to the swiper structure that was created using "new",
      *  even when not initialized */
@@ -67,50 +153,26 @@ const {
       this.astroSwiper = undefined;
 
       // Read the message from the data attribute.
-      const options = JSON.parse(this.dataset.options || '{}');
+      const options: AstroSwiperOptions = JSON.parse(this.dataset.options || '{}');
       // to have more than 1 swiper in a single page
       const uniqueClass = this.dataset.uniqueclass || '';
       const linkToThumbUniqueClass = this.dataset.linktothumbuniqueclass || '';
 
-      if (linkToThumbUniqueClass === '') {
-        // no thumbnail link - the swiper can be created immediatly
-        const swiper = new Swiper(`.${uniqueClass}`, options);
-        _useSwiper[uniqueClass] = swiper;
-        this.astroSwiper = swiper;
-      } else {
-        // a thumbnail link is provided
-        // if the thumbnail swiper is already created, the main slider can be created also
-        // otherwise, it will be added in the delayed swiper list
-        if (_useSwiper[linkToThumbUniqueClass] !== undefined) {
+      // no thumbnail link, or link to thumbnail swiper already created,
+      // the swiper can be created or not immediatly depending on the observer option
+      if (!linkToThumbUniqueClass || _useSwiper[linkToThumbUniqueClass]) {
+        if (linkToThumbUniqueClass) {
           options.thumbs = { swiper: _useSwiper[linkToThumbUniqueClass], ...options.thumbs };
-          const swiper = new Swiper(`.${uniqueClass}`, options);
-          _useSwiper[uniqueClass] = swiper;
-          this.astroSwiper = swiper;
-        } else {
-          // cannot create the swiper as the thumbnail swiper not created yet
-          // will be done later
-          _useDelaySwiper[uniqueClass] = linkToThumbUniqueClass;
         }
+        // create the swiper and the observer if needed
+        _createSwiperAndObserver(uniqueClass, options, this);
+      } else {
+        // cannot create the swiper as the thumbnail swiper not created yet
+        // is delayed until the thumbnail swiper is initialized.
+        _useDelaySwiper[uniqueClass] = linkToThumbUniqueClass;
       }
 
       _useOptions[uniqueClass] = options;
-
-      // look if any delayed swiper can be created, that is its related thumbnail swiper is now created
-      Object.keys(_useDelaySwiper).forEach((delayedClass) => {
-        const delayedThumbClass = _useDelaySwiper[delayedClass];
-        if (_useSwiper[delayedThumbClass] !== undefined) {
-          const delayedOptions = _useOptions[delayedClass];
-          delayedOptions.thumbs = {
-            swiper: _useSwiper[delayedThumbClass],
-            ...delayedOptions.thumbs,
-          };
-          const swiper = new Swiper(`.${delayedClass}`, delayedOptions);
-          _useSwiper[delayedClass] = swiper;
-          (document.querySelector(`.${delayedClass}`) as AstroSwiper).astroSwiper = swiper;
-          _useOptions[delayedClass] = delayedOptions;
-          delete _useDelaySwiper[delayedClass];
-        }
-      });
     }
   }
 

package/src/index.ts

@@ -4,6 +4,32 @@
 import type { Swiper, SwiperOptions } from 'swiper/types';
 import type { HTMLAttributes } from 'astro/types';
 
+/** Swiper options for the Astro component.
+ * Basically the same as the original SwiperOptions, but extended
+ * with new capabilities
+*/
+export interface AstroSwiperOptions extends SwiperOptions {
+  /** options specific to astro-swiper component */
+  astro?: {
+    /** intersection observer options: an observer can be added to control the swiper when it appears / disappears in the screen.
+     * The observer is created using IntersectionObserver
+     * The behavior of the observer is controlled by the following properties
+     * When observer is not provided, no observer is created.
+     */
+    intersectionObserver?: {
+      /** true to initialize the swiper when the element appears in the screen */
+      initSwiper?: boolean;
+      /** true to disconnect the observer once the swiper is initialized */
+      disconnectOnInit?: boolean;
+      /** true to start and stop the autoplay when the swiper appears and disappears from the screen, respectively. */
+      controlAutoplay?: boolean;
+      /** options for the IntersectionObserver */
+      options?: IntersectionObserverInit;
+    }
+    /** TODO: uniqueClass and linkToThumbUniqueClass may be part of it */
+  }
+};
+
 /** properties passed to the <Swiper> component
  * It extends a div (that is may have class, style,...), plus other attributes
  * Note that all other components (<SwiperSlide>, <SwiperButtonNext>...) extends a div only
@@ -12,7 +38,7 @@ export interface AstroSwiperType extends HTMLAttributes<'div'> {
   /** swiper options, to set autoplay, navigation, thumbnails,...
    * check fullset of options: https://swiperjs.com/swiper-api#parameters
    */
-  options?: SwiperOptions;
+  options?: AstroSwiperOptions;
 
   /** unique class to be able to retrieve the swiper instance, if required
    * Mandatory on thumbnail for example