astro-swiper 2.5.0 → 2.5.2

package/README.md

@@ -31,9 +31,8 @@ import { Swiper, SwiperWrapper, SwiperSlide } from "astro-swiper";
 ---
 
 <Swiper
-// check options at https://swiperjs.com/swiper-api
   options={{
-    loop: true,
+    loop: true,   // check options at https://swiperjs.com/swiper-api
     autoplay: {
       delay: 700,
       disableOnInteraction: false,
@@ -104,6 +103,96 @@ You can also look at how others are using `astro-swiper` in public github repo:
   [folex-lite-astro](https://github.com/getastrothemes/folex-lite-astro)
   using it in the portfolio page,...
 
+## API
+
+### `<Swiper/>`
+Main Swiper element. Inherits all `HTMLAttributes<'div'>` (class...) attributes.
+| Name | Type | Default | Description |
+| ---- | -----|-------- | -----------|
+| options | SwiperOptions | Swiperjs default | cf. [Swiperjs doc](https://swiperjs.com/swiper-api#parameters) |
+| options.astro | Cf. below description | undefined | astro specific options |
+| addDefaultClass | Boolean | true | Add class `.swiper` when true |
+
+`options.astro` is as follows:
+| Name | Type | Default | Description |
+| ---- | -----|-------- | -----------|
+| useCustomElement | boolean | true | when false, use a `<div>` to be as close as possible to swiperjs default. Use a custom element `<astro-swiper>` otherwise. |
+| thumbSwiperUniqueSelector | string starting with `#` or `.` | undefined | unique selector of the thumbnail swiper to link with, when using the thumbs module. When a thumbnail swiper is build, this parameter is provided on the main slider (the one with big slides, not the one to track the progress) and equal the unique selector of the thumbnail swiper (the one to track the progress). It is used to link the main swiper with the thumbnail swiper when using the thumbs module. |
+| intersectionObserver.initSwiper | boolean | false | true to initialize the swiper when the element appears in the screen |
+| intersectionObserver.disconnectOnInit | boolean | false | true to disconnect the observer once the swiper is initialized |
+| intersectionObserver.controlAutoplay | boolean | false | true to start and stop the autoplay when the swiper appears and disappears from the screen, respectively |
+| intersectionObserver.options | IntersectionObserverInit | undefined | cf. [mdn docs](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) |
+
+### `<SwiperWrapper/>`
+Wrapper of all slides. Inherits all `HTMLAttributes<'div'>` (class...)  attributes.
+| Name | Type | Default | Description |
+| ---- | -----|-------- | -----------|
+| addDefaultClass | Boolean | true | Add class `.swiper-wrapper` when true |
+
+### `<SwiperSlide/>`
+A single slide. Inherits all `HTMLAttributes<'div'>` (class...) attributes.
+| Name | Type | Default | Description |
+| ---- | -----|-------- | -----------|
+| addDefaultClass | Boolean | true | Add class `.swiper-slide` when true |
+
+### `<SwiperPagination/>`
+Pagination dots. Inherits all `HTMLAttributes<'div'>` (class...) attributes.
+| Name | Type | Default | Description |
+| ---- | -----|-------- | -----------|
+| addDefaultClass | Boolean | true | Add class `.swiper-pagination` when true |
+
+### `<SwiperButtonPrev/>` and `<SwiperButtonNext/>`
+Navigation arrows. Inherits all `HTMLAttributes<'div'>` (class...) attributes.
+| Name | Type | Default | Description |
+| ---- | -----|-------- | -----------|
+| addDefaultClass | Boolean | true | Add class `.swiper-button-prev` or `swiper-button-next` when true |
+
+### `<SwiperScrollbar/>`
+Scrollbar. Inherits all `HTMLAttributes<'div'>` (class...) attributes.
+| Name | Type | Default | Description |
+| ---- | -----|-------- | -----------|
+| addDefaultClass | Boolean | true | Add class `.swiper-scrollbar` when true |
+
+### `<SwiperLazyPreloader/>`
+Slide lazy loader. To be used inside a `<SwiperSlide/>`. Inherits all `HTMLAttributes<'div'>` (class...) attributes.
+| Name | Type | Default | Description |
+| ---- | -----|-------- | -----------|
+| addDefaultClass | Boolean | true | Add class `.swiper-lazy-preloader` when true |
+
+### `getSwiperFromUniqueSelector()`
+Function to be used in script part, to be able to retrieve the swiper instance given
+a unique selector (starting with a `.` or a `#`), once the `load` event is fired.
+This allows to use functions and events in swiper.
+
+Here is a snipset of the
+[Custom Pagination Demo](https://github.com/pascal-brand38/astro-dev/blob/main/src/content/docs/packages/astro-swiper/DemoPaginationCustom.astro):
+
+```jsx
+<Swiper
+  class="swiper-demo-pagination-custom"
+  options={{
+    ...
+    init: false,  // init in the script part
+  }}
+>
+  ...
+  <SwiperPagination />
+</Swiper>
+
+<script>
+  import type { PaginationOptions } from 'swiper/types';
+  import { getSwiperFromUniqueSelector } from 'astro-swiper'
+  window.addEventListener('load', () => {
+    const swiper = getSwiperFromUniqueSelector('.swiper-demo-pagination-custom');
+    (swiper!.params.pagination as PaginationOptions)!.renderBullet = function (index: number, className: string) {
+      return '<span class="' + className + '">' + (index + 1) + "</span>";
+    }
+    swiper!.init()
+  })
+</script>
+```
+
+
 ## Help needed?
 
 **Do you need help to integrate `astro-swiper` in your astro template / component?**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-swiper",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "Astro component for swiper, dedicated to slider / carousel / photo swiper / slide, including thumbnails",
   "type": "module",
   "main": "index.js",
@@ -30,8 +30,9 @@
     "src/**"
   ],
   "engines": {
-    "pnpm": ">=10.30.3",
-    "node": ">=20"
+    "node": ">=18",
+    "npm": ">=9.6.5",
+    "pnpm": ">=7.1.0"
   },
   "packageManager": "pnpm@10.30.3",
   "devDependencies": {

package/src/index.ts

@@ -96,6 +96,7 @@ export function getSwiperFromUniqueClass(uniqueClass: string): Swiper | undefine
 
 /** Retrieve the swiper instance from the unique selector provided when creating the swiper
  * @param uniqueSelector the unique selector provided when creating the swiper,
+ * @param options mayBeUndefined set to true to avoid warning when the swiper is not initialized yet, but will be in the future (for example when using thumbnails, the main swiper is created before the thumbnail swiper, so it is normal that it is not found at this moment)
  * @example const swiper = getSwiperFromUniqueSelector('.my-unique-class')
  *          const swiper = getSwiperFromUniqueSelector('#my-unique-id')
  */