Migration Guide: v0.2.x to v0.3.0

This guide helps you upgrade from Continuous Carousel v0.2.x to v0.3.0.

What's New in v0.3.0

• ES6 Modules - Modern module system with tree-shaking support
• Enhanced Performance - requestAnimationFrame-based animations (60fps)
• Automatic Pause - IntersectionObserver pauses carousel when off-screen
• Responsive - ResizeObserver auto-recalculates on resize
• CSS Custom Properties - Cleaner styling without inline styles
• Extended API - New play(), pause(), destroy(), updateConfig() methods
• Event Callbacks - Hook into slide changes and lifecycle events
• Better Accessibility - Improved ARIA support

Breaking Changes

None!

v0.3.0 is fully backward compatible with v0.2.x. Your existing code will continue to work without modifications.

Recommended Updates

While not required, these updates take advantage of new features:

1. Use ES6 Modules (Optional)

Before (v0.2.x):

<script src="continuous-carousel.js"></script>
<script>
  ContinuousCarousel('myCarousel');
</script>

After (v0.3.0):

<script type="module">
  import ContinuousCarousel from './dist/continuous-carousel.esm.js';
  ContinuousCarousel('myCarousel');
</script>

2. Use New Configuration Options

Before (v0.2.x):

// Only data attributes were supported
<div id="myCarousel" data-direction="horizontal" data-num-visible="1">

After (v0.3.0):

// Options can be passed programmatically
const carousel = ContinuousCarousel('myCarousel', {
  direction: 'horizontal',
  numVisible: 1,
  interval: 3000,
  pauseOnHover: true
});

3. Use Public API Methods

New in v0.3.0:

const carousel = ContinuousCarousel('myCarousel');

// Control playback
carousel.play();
carousel.pause();
carousel.destroy();

// Update settings
carousel.updateConfig({ interval: 5000 });

4. Use Event Callbacks

New in v0.3.0:

const carousel = ContinuousCarousel('myCarousel', {
  onSlideChange: (index) => {
    console.log('Current slide:', index);
  },
  onPause: () => {
    console.log('Carousel paused');
  },
  onPlay: () => {
    console.log('Carousel resumed');
  }
});

5. Enable Pause on Hover

New in v0.3.0:

const carousel = ContinuousCarousel('myCarousel', {
  pauseOnHover: true
});

Package Installation

Before (v0.2.x):

npm install continuous-carousel@0.2.1

After (v0.3.0):

npm install continuous-carousel@0.3.0

Module Exports

v0.3.0 properly supports both CommonJS and ES modules:

CommonJS:

const ContinuousCarousel = require('continuous-carousel');

ES Modules:

import ContinuousCarousel from 'continuous-carousel';

File Structure Changes

Distribution Files

Before (v0.2.x):

• continuous-carousel.js
• continuous-carousel.css

After (v0.3.0):

• dist/continuous-carousel.js - UMD build (ES5, for browsers)
• dist/continuous-carousel.min.js - UMD minified
• dist/continuous-carousel.esm.js - ES6 modules
• dist/continuous-carousel.esm.min.js - ES6 minified
• dist/continuous-carousel.min.css - Minified CSS

Update your paths:

<!-- Before -->
<link rel="stylesheet" href="continuous-carousel.css">
<script src="continuous-carousel.js"></script>

<!-- After -->
<link rel="stylesheet" href="dist/continuous-carousel.min.css">
<script src="dist/continuous-carousel.min.js"></script>

CSS Changes

CSS Custom Properties

v0.3.0 uses CSS custom properties instead of inline styles. This improves performance and allows easier customization.

No action required - existing styles continue to work.

Optional enhancement:

.c-carousel-container {
  --carousel-item-width: 300px;
  --carousel-item-height: 200px;
  --carousel-transition-duration: 1000ms;
}

New Features You Can Use

1. Automatic Visibility Detection

Carousel automatically pauses when scrolled off-screen (saves battery):

const carousel = ContinuousCarousel('myCarousel', {
  observeVisibility: true  // Default: true
});

2. Automatic Resize Handling

Carousel recalculates dimensions on window resize:

const carousel = ContinuousCarousel('myCarousel', {
  observeResize: true  // Default: true
});

3. Custom Timing

const carousel = ContinuousCarousel('myCarousel', {
  interval: 4000,              // 4 seconds between slides
  transitionDuration: 800      // 800ms transition
});

4. Disable Autoplay

const carousel = ContinuousCarousel('myCarousel', {
  autoplay: false  // Start paused
});

// Start manually
carousel.play();

Complete Example: Before & After

Before (v0.2.x)

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="continuous-carousel.css">
</head>
<body>
  <div id="myCarousel" class="c-carousel-container" data-direction="horizontal" data-num-visible="1">
    <ul class="c-carousel-group">
      <li class="c-carousel-item">1</li>
      <li class="c-carousel-item">2</li>
      <li class="c-carousel-item">3</li>
    </ul>
  </div>

  <script src="continuous-carousel.js"></script>
  <script>
    ContinuousCarousel('myCarousel');
  </script>
</body>
</html>

After (v0.3.0)

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/continuous-carousel.min.css">
</head>
<body>
  <div id="myCarousel" class="c-carousel-container" data-direction="horizontal" data-num-visible="1">
    <ul class="c-carousel-group">
      <li class="c-carousel-item">1</li>
      <li class="c-carousel-item">2</li>
      <li class="c-carousel-item">3</li>
    </ul>
  </div>

  <script type="module">
    import ContinuousCarousel from './dist/continuous-carousel.esm.js';

    const carousel = ContinuousCarousel('myCarousel', {
      interval: 3000,
      pauseOnHover: true,
      onSlideChange: (index) => {
        console.log('Slide', index);
      }
    });
  </script>
</body>
</html>

Troubleshooting

Issue: Carousel not found

Problem: ContinuousCarousel is not defined

Solution: Update script path to include dist/ directory:

<script src="dist/continuous-carousel.min.js"></script>

Issue: Styles not loading

Problem: Carousel has no styling

Solution: Update CSS path:

<link rel="stylesheet" href="dist/continuous-carousel.min.css">

Issue: Module import error

Problem: ES module import fails

Solution: Add type="module" to script tag:

<script type="module">
  import ContinuousCarousel from './dist/continuous-carousel.esm.js';
</script>

Summary

v0.3.0 is a non-breaking upgrade that adds powerful new features while maintaining full backward compatibility. You can upgrade immediately and adopt new features at your own pace.

Minimum required changes:

1. Update npm package: npm install continuous-carousel@0.3.0
2. Update file paths: Add dist/ prefix to JS/CSS imports

Recommended enhancements:

1. Switch to ES6 modules for better tree-shaking
2. Use new configuration options for more control
3. Add event callbacks for custom behavior
4. Enable pauseOnHover for better UX