feat: add overlap transition effect for carousel navigation, transparent background option

demo/configurator.ts

@@ -23,6 +23,7 @@ export function initConfigurator(): void {
   const cfgAutoplay = document.getElementById('cfg-autoplay') as HTMLInputElement
   const cfgCycle = document.getElementById('cfg-cycle') as HTMLInputElement
   const cfgCoverflow = document.getElementById('cfg-coverflow') as HTMLInputElement
+  const cfgTransparentBg = document.getElementById('cfg-transparent-bg') as HTMLInputElement
   const cfgTheme = document.getElementById('cfg-theme') as HTMLSelectElement
   const cfgTransition = document.getElementById('cfg-transition') as HTMLSelectElement
   const cfgControlsPosition = document.getElementById('cfg-controls-position') as HTMLSelectElement
@@ -42,8 +43,9 @@ export function initConfigurator(): void {
       autoplay: cfgAutoplay.checked,
       cycle: cfgCycle.checked,
       showCoverflow: cfgCoverflow.checked,
+      transparentBackground: cfgTransparentBg.checked,
       theme: cfgTheme.value as 'light' | 'dark',
-      transitionEffect: cfgTransition.value as 'fade' | 'slide' | 'zoom' | 'flip',
+      transitionEffect: cfgTransition.value as 'fade' | 'slide' | 'zoom' | 'flip' | 'overlap',
       controlsPosition: cfgControlsPosition.value as 'center' | 'bottom',
       zoomMin: parseFloat(cfgZoomMin.value),
       zoomMax: parseFloat(cfgZoomMax.value),
@@ -61,6 +63,7 @@ export function initConfigurator(): void {
     if (config.autoplay) opts.push(`  autoplay: true,`)
     if (!config.cycle) opts.push(`  cycle: false,`)
     if (config.showCoverflow) opts.push(`  showCoverflow: true,`)
+    if (config.transparentBackground) opts.push(`  transparentBackground: true,`)
     if (config.theme !== 'light') opts.push(`  theme: '${config.theme}',`)
     if (config.transitionEffect !== 'fade') opts.push(`  transitionEffect: '${config.transitionEffect}',`)
     if (config.controlsPosition !== 'center') opts.push(`  controlsPosition: '${config.controlsPosition}',`)
@@ -78,6 +81,9 @@ export function initConfigurator(): void {
     const posLabel = cfgControlsPosition.closest('label') as HTMLElement
     posLabel.style.display = cfgControls.checked ? '' : 'none'
 
+    // Reveal a checkerboard behind the carousel so transparency is visible
+    viewerEl!.classList.toggle('is-transparent-preview', config.transparentBackground === true)
+
     // Destroy and recreate (carousel doesn't have an update() method)
     if (instance) {
       viewerEl!.style.minHeight = `${viewerEl!.offsetHeight}px`
@@ -105,8 +111,8 @@ export function initConfigurator(): void {
   }
 
   // Bind all controls to rebuild
-  ;[cfgThumbnails, cfgBullets, cfgControls, cfgFilenames, cfgAutoplay, cfgCycle, cfgCoverflow].forEach((el) =>
-    el.addEventListener('change', rebuild),
+  ;[cfgThumbnails, cfgBullets, cfgControls, cfgFilenames, cfgAutoplay, cfgCycle, cfgCoverflow, cfgTransparentBg].forEach(
+    (el) => el.addEventListener('change', rebuild),
   )
   ;[cfgTheme, cfgTransition, cfgControlsPosition].forEach((el) => el.addEventListener('change', rebuild))
   ;[cfgZoomMin, cfgZoomMax, cfgZoomStep].forEach((el) => el.addEventListener('change', rebuild))

demo/demo.css

@@ -799,6 +799,19 @@ p code {
   border-radius: var(--demo-radius-sm);
 }
 
+/* Checkerboard backdrop — only shown while the transparent-background option is
+   on, so the see-through effect is obvious in the preview. */
+#configurator-carousel.is-transparent-preview {
+  background-image:
+    linear-gradient(45deg, rgba(0, 0, 0, 0.08) 25%, transparent 25%, transparent 75%, rgba(0, 0, 0, 0.08) 75%),
+    linear-gradient(45deg, rgba(0, 0, 0, 0.08) 25%, transparent 25%, transparent 75%, rgba(0, 0, 0, 0.08) 75%);
+  background-size: 24px 24px;
+  background-position:
+    0 0,
+    12px 12px;
+  border-radius: 16px;
+}
+
 .demo-configurator-panel {
   display: flex;
   flex-direction: column;

demo/demo.ts

@@ -134,6 +134,18 @@ new CloudImageCarousel('#transition-flip', {
   showBullets: true,
 }).init()
 
+// ==========================================================================
+// Transition: overlap (cover) — drag to navigate
+// ==========================================================================
+
+new CloudImageCarousel('#transition-overlap', {
+  images: DEMO_IMAGES,
+  transitionEffect: 'overlap',
+  cycle: true,
+  showThumbnails: false,
+  showBullets: true,
+}).init()
+
 // ==========================================================================
 // Zoom: default config
 // ==========================================================================

demo/index.html

@@ -321,7 +321,7 @@ <h3>Bottom</h3>
         <div class="demo-section-header">
           <div class="demo-section-label">Effects</div>
           <h2>Transitions</h2>
-          <p>Four built-in effects with configurable easing and duration via CSS variables.</p>
+          <p>Five built-in effects with configurable easing and duration via CSS variables.</p>
         </div>
         <div class="demo-grid-2">
           <div class="demo-card">
@@ -360,6 +360,15 @@ <h3>Flip</h3>
               <div class="demo-viewer"><div id="transition-flip"></div></div>
             </div>
           </div>
+          <div class="demo-card">
+            <div class="demo-card-header">
+              <h3>Overlap (drag)</h3>
+              <p><code>transitionEffect: 'overlap'</code> — drag the image to navigate</p>
+            </div>
+            <div class="demo-card-body">
+              <div class="demo-viewer"><div id="transition-overlap"></div></div>
+            </div>
+          </div>
         </div>
       </div>
     </section>
@@ -456,6 +465,10 @@ <h3>Options</h3>
                 <input type="checkbox" id="cfg-coverflow" />
                 <span class="demo-toggle-label">Coverflow</span>
               </label>
+              <label class="demo-toggle">
+                <input type="checkbox" id="cfg-transparent-bg" />
+                <span class="demo-toggle-label">Transparent background</span>
+              </label>
             </div>
             <div class="demo-configurator-controls" style="margin-top: 8px">
               <label class="demo-select-label">
@@ -472,6 +485,7 @@ <h3>Options</h3>
                   <option value="slide">slide</option>
                   <option value="zoom">zoom</option>
                   <option value="flip">flip</option>
+                  <option value="overlap">overlap</option>
                 </select>
               </label>
               <label class="demo-select-label">

examples/index.html

@@ -101,6 +101,20 @@ <h2>3. Coverflow (openbook) layout</h2>
 
     <div id="carousel-coverflow"></div>
 
+    <!-- ================================================================
+         Example 4: Overlap (cover) transition — drag to navigate
+         ================================================================ -->
+    <h2>4. Overlap transition (drag to navigate)</h2>
+    <pre><code>new CloudImageCarousel('#carousel-overlap', {
+  images: [...],
+  transitionEffect: 'overlap', // incoming image slides OVER the current one
+  cycle: true,
+  showBullets: true,
+})</code></pre>
+    <p class="subtitle">Drag the image left/right (mouse or touch) — the next/prev image rides over the current one and snaps on release.</p>
+
+    <div id="carousel-overlap"></div>
+
     <script src="/dist/carousel.min.js"></script>
     <script>
       // Method 1: JavaScript API
@@ -155,6 +169,24 @@ <h2>3. Coverflow (openbook) layout</h2>
         ],
       })
       carouselCoverflow.init()
+
+      // Method 4: Overlap (cover) transition — incoming image rides over the current
+      // one; drag left/right (mouse or touch) to navigate with live feedback.
+      const carouselOverlap = new CloudImageCarousel('#carousel-overlap', {
+        transitionEffect: 'overlap',
+        cycle: true,
+        showBullets: true,
+        showThumbnails: true,
+        showControls: true,
+        images: [
+          'https://demo.cloudimg.io/v7/https://samples.scaleflex.com/hotel.jpg',
+          'https://demo.cloudimg.io/v7/https://samples.scaleflex.com/birds.jpg',
+          'https://demo.cloudimg.io/v7/https://samples.scaleflex.com/perfume.jpg',
+          'https://demo.cloudimg.io/v7/https://samples.scaleflex.com/mountains.jpg',
+          'https://demo.cloudimg.io/v7/https://samples.scaleflex.com/house.jpg',
+        ],
+      })
+      carouselOverlap.init()
     </script>
   </body>
 </html>

src/constants/classes.constants.ts

@@ -15,6 +15,10 @@ export const CI_CAROUSEL_AUTOPLAY_CLASS = 'ci-carousel-autoplay' as const
 export const CI_CAROUSEL_SCROLL_HINT_CLASS = 'ci-carousel-scroll-hint' as const
 export const CI_CAROUSEL_SCROLL_HINT_VISIBLE_CLASS = 'ci-carousel-scroll-hint--visible' as const
 export const CI_CAROUSEL_DRAGGING_CLASS = 'ci-carousel-dragging' as const
+/** Container drag state during an overlap swipe (distinct from the zoom-pan wrapper-level dragging class). */
+export const CI_CAROUSEL_SWIPING_CLASS = 'ci-carousel-swiping' as const
+/** Applied to the incoming slide while it is being dragged in (makes the otherwise-hidden wrapper paintable). */
+export const CI_CAROUSEL_DRAG_INCOMING_CLASS = 'drag-incoming' as const
 
 // Controls classes
 export const CI_CAROUSEL_PREV_CLASS = 'ci-carousel-prev' as const
@@ -35,12 +39,14 @@ export const CI_CAROUSEL_COVERFLOW_PREV_CLASS = 'coverflow-prev' as const
 export const CI_CAROUSEL_COVERFLOW_NEXT_CLASS = 'coverflow-next' as const
 export const CI_CAROUSEL_COVERFLOW_FAR_PREV_CLASS = 'coverflow-far-prev' as const
 export const CI_CAROUSEL_COVERFLOW_FAR_NEXT_CLASS = 'coverflow-far-next' as const
+export const CI_CAROUSEL_COVERFLOW_INSTANT_CLASS = 'coverflow-instant' as const
 export const CI_CAROUSEL_HAS_COVERFLOW_CLASS = 'ci-carousel-has-coverflow' as const
 
 // Modifier classes
 export const CI_CAROUSEL_HAS_CONTROLS_CLASS = 'ci-carousel-has-controls' as const
 export const CI_CAROUSEL_HAS_THUMBNAILS_CLASS = 'ci-carousel-has-thumbnails' as const
 export const CI_CAROUSEL_HAS_BULLETS_CLASS = 'ci-carousel-has-bullets' as const
 export const CI_CAROUSEL_THEME_DARK_CLASS = 'ci-carousel-theme-dark' as const
+export const CI_CAROUSEL_TRANSPARENT_CLASS = 'ci-carousel-transparent' as const
 export const CI_CAROUSEL_IMAGE_ERROR_CLASS = 'ci-carousel-image-error' as const
 export const CI_CAROUSEL_IS_FULLSCREEN_CLASS = 'is-fullscreen' as const

src/constants/transitions.constants.ts

@@ -3,4 +3,5 @@ export const TRANSITION_EFFECTS = {
   FADE: 'fade',
   ZOOM: 'zoom',
   FLIP: 'flip',
+  OVERLAP: 'overlap',
 } as const