peek-carousel 1.0.2

package/src/modules/EventHandler.js

@@ -0,0 +1,390 @@
+import { KEYS, BREAKPOINTS } from '../core/constants.js';
+import { isMobile } from '../utils/helpers.js';
+
+const WHEEL_CONFIG = Object.freeze({
+  threshold: 50,
+  timeout: 150,
+  cooldown: 100,
+});
+
+const DRAG_CONFIG = Object.freeze({
+  touchThreshold: 15,
+  mouseThreshold: 10,
+  velocityThreshold: 0.5,
+});
+
+const RESIZE_DEBOUNCE = 100;
+
+export class EventHandler {
+  constructor(carousel) {
+    this.carousel = carousel;
+    this.boundHandlers = new Map();
+
+    this.touch = {
+      startX: 0,
+      endX: 0,
+    };
+
+    this.drag = {
+      active: false,
+      startX: 0,
+      currentX: 0,
+      lastX: 0,
+      lastTime: 0,
+      velocity: 0,
+    };
+
+    this.wheel = {
+      isScrolling: false,
+      scrollTimeout: null,
+      lastWheelTime: 0,
+      accumulatedDelta: 0,
+    };
+  }
+
+  init() {
+    this.initNavigationButtons();
+    this.initKeyboard();
+    this.initWheel();
+    this.initItemClick();
+    this.initIndicatorClick();
+    this.initTouch();
+    this.initMouse();
+    this.initResize();
+  }
+
+  stopAutoRotateAndNavigate(navigationFn) {
+    this.completeCurrentIndicator();
+    this.carousel.autoRotate.stop();
+    navigationFn();
+  }
+
+  completeCurrentIndicator() {
+    const currentIndicator = this.carousel.indicators[this.carousel.state.currentIndex];
+    if (currentIndicator && currentIndicator.classList.contains('peek-carousel__indicator--active')) {
+      currentIndicator.classList.add('peek-carousel__indicator--completed');
+    }
+  }
+
+  resetDragState(index) {
+    this.carousel.ui.removeDraggingClass(index);
+    this.carousel.ui.clearDragTransform();
+  }
+
+  updateDraggingClass(dragDistance, currentIndex, threshold) {
+    if (dragDistance > threshold) {
+      this.carousel.ui.addDraggingClass(currentIndex, 'right');
+    } else if (dragDistance < -threshold) {
+      this.carousel.ui.addDraggingClass(currentIndex, 'left');
+    }
+  }
+
+  initDragState(clientX) {
+    this.drag.active = true;
+    this.drag.startX = clientX;
+    this.drag.currentX = clientX;
+    this.drag.lastX = clientX;
+    this.drag.lastTime = Date.now();
+    this.drag.velocity = 0;
+  }
+
+  resetMouseCursor() {
+    this.carousel.elements.carousel.style.cursor = 'grab';
+  }
+
+  calculateWheelDelta(e) {
+    const deltaX = Math.abs(e.deltaX);
+    const deltaY = Math.abs(e.deltaY);
+    const isHorizontal = deltaX > deltaY;
+
+    // [개발참고] 수평: 왼쪽(-) = 다음, 오른쪽(+) = 이전
+    //            수직: 아래(+) = 다음, 위(-) = 이전
+    return isHorizontal ? -e.deltaX : e.deltaY;
+  }
+
+  resetWheelState() {
+    this.wheel.isScrolling = false;
+    this.wheel.accumulatedDelta = 0;
+  }
+
+  initNavigationButtons() {
+    const { prevBtn, nextBtn, autoRotateBtn } = this.carousel.elements;
+
+    if (prevBtn) {
+      this.addHandler(prevBtn, 'click', () => {
+        this.stopAutoRotateAndNavigate(() => this.carousel.navigator.prev());
+      });
+    }
+
+    if (nextBtn) {
+      this.addHandler(nextBtn, 'click', () => {
+        this.stopAutoRotateAndNavigate(() => this.carousel.navigator.next());
+      });
+    }
+
+    if (autoRotateBtn) {
+      this.addHandler(autoRotateBtn, 'click', () => {
+        this.carousel.autoRotate.toggle();
+      });
+    }
+  }
+
+  initKeyboard() {
+    if (!this.carousel.options.enableKeyboard) return;
+
+    const handler = (e) => {
+      const { navigator, autoRotate, totalItems } = this.carousel;
+
+      switch (e.key) {
+        case KEYS.arrowLeft:
+          autoRotate.stop();
+          navigator.prev();
+          break;
+
+        case KEYS.arrowRight:
+          autoRotate.stop();
+          navigator.next();
+          break;
+
+        case KEYS.home:
+          e.preventDefault();
+          autoRotate.stop();
+          navigator.goTo(0);
+          break;
+
+        case KEYS.end:
+          e.preventDefault();
+          autoRotate.stop();
+          navigator.goTo(totalItems - 1);
+          break;
+
+        case KEYS.space:
+          e.preventDefault();
+          autoRotate.toggle();
+          break;
+
+        default:
+          const numKey = parseInt(e.key);
+          if (numKey >= 1 && numKey <= totalItems) {
+            e.preventDefault();
+            autoRotate.stop();
+            navigator.goTo(numKey - 1);
+          }
+      }
+    };
+
+    this.addHandler(document, 'keydown', handler);
+  }
+
+  initWheel() {
+    if (!this.carousel.options.enableWheel) return;
+
+    const handler = (e) => {
+      const deltaX = Math.abs(e.deltaX);
+      const deltaY = Math.abs(e.deltaY);
+
+      if (deltaX < 1 && deltaY < 1) {
+        return;
+      }
+
+      if (deltaX === deltaY) {
+        return;
+      }
+
+      e.preventDefault();
+
+      const currentTime = Date.now();
+
+      if (currentTime - this.wheel.lastWheelTime < WHEEL_CONFIG.cooldown) {
+        return;
+      }
+
+      if (!this.wheel.isScrolling) {
+        this.wheel.isScrolling = true;
+        this.wheel.accumulatedDelta = 0;
+        this.carousel.autoRotate.stop();
+        this.carousel.animator.stopMomentum();
+      }
+
+      this.wheel.accumulatedDelta += this.calculateWheelDelta(e);
+
+      if (Math.abs(this.wheel.accumulatedDelta) >= WHEEL_CONFIG.threshold) {
+        const direction = this.wheel.accumulatedDelta > 0 ? 1 : -1;
+        this.carousel.navigator.rotate(direction);
+
+        this.wheel.accumulatedDelta = 0;
+        this.wheel.lastWheelTime = currentTime;
+      }
+
+      clearTimeout(this.wheel.scrollTimeout);
+      this.wheel.scrollTimeout = setTimeout(() => {
+        this.resetWheelState();
+      }, WHEEL_CONFIG.timeout);
+    };
+
+    this.addHandler(
+      this.carousel.elements.carousel,
+      'wheel',
+      handler,
+      { passive: false }
+    );
+  }
+
+  initItemClick() {
+    const { items } = this.carousel;
+    for (let i = 0; i < items.length; i++) {
+      this.addHandler(items[i], 'click', () => {
+        this.carousel.autoRotate.stop();
+        this.carousel.navigator.handleItemClick(i);
+      });
+    }
+  }
+
+  initIndicatorClick() {
+    const { indicators } = this.carousel;
+    for (let i = 0; i < indicators.length; i++) {
+      this.addHandler(indicators[i], 'click', () => {
+        this.carousel.autoRotate.stop();
+        this.carousel.navigator.handleIndicatorClick(i);
+      });
+    }
+  }
+
+  initTouch() {
+    if (!this.carousel.options.enableTouch) return;
+
+    this.addHandler(this.carousel.elements.carousel, 'touchstart', (e) => {
+      this.touch.startX = e.changedTouches[0].screenX;
+    });
+
+    this.addHandler(this.carousel.elements.carousel, 'touchmove', (e) => {
+      const touchCurrentX = e.changedTouches[0].screenX;
+      const dragDistance = touchCurrentX - this.touch.startX;
+      const { currentIndex } = this.carousel.state;
+
+      this.carousel.ui.updateDragTransform(dragDistance);
+      this.updateDraggingClass(dragDistance, currentIndex, DRAG_CONFIG.touchThreshold);
+    });
+
+    this.addHandler(this.carousel.elements.carousel, 'touchend', (e) => {
+      this.touch.endX = e.changedTouches[0].screenX;
+      const swipeDistance = this.touch.endX - this.touch.startX;
+      const { swipeThreshold } = this.carousel.options;
+      const { currentIndex } = this.carousel.state;
+
+      this.resetDragState(currentIndex);
+
+      if (swipeDistance < -swipeThreshold) {
+        this.carousel.autoRotate.stop();
+        this.carousel.navigator.next();
+      } else if (swipeDistance > swipeThreshold) {
+        this.carousel.autoRotate.stop();
+        this.carousel.navigator.prev();
+      }
+    });
+  }
+
+  initMouse() {
+    if (!this.carousel.options.enableMouse) return;
+
+    this.addHandler(this.carousel.elements.carousel, 'mousedown', (e) => {
+      if (isMobile()) return;
+
+      this.initDragState(e.clientX);
+      this.carousel.autoRotate.stop();
+      this.carousel.animator.stopMomentum();
+      this.carousel.elements.carousel.style.cursor = 'grabbing';
+      e.preventDefault();
+    });
+
+    this.addHandler(document, 'mousemove', (e) => {
+      if (!this.drag.active) return;
+
+      const currentTime = Date.now();
+      const deltaTime = currentTime - this.drag.lastTime;
+      const deltaX = e.clientX - this.drag.lastX;
+
+      if (deltaTime > 0) {
+        this.drag.velocity = deltaX / deltaTime;
+      }
+
+      this.drag.currentX = e.clientX;
+      this.drag.lastX = e.clientX;
+      this.drag.lastTime = currentTime;
+
+      const dragDistance = this.drag.currentX - this.drag.startX;
+      const { currentIndex } = this.carousel.state;
+
+      this.carousel.ui.updateDragTransform(dragDistance);
+      this.updateDraggingClass(dragDistance, currentIndex, DRAG_CONFIG.mouseThreshold);
+
+      if (Math.abs(dragDistance) > this.carousel.options.dragThreshold) {
+        const direction = dragDistance > 0 ? -1 : 1;
+        this.carousel.navigator.rotate(direction);
+        this.drag.startX = this.drag.currentX;
+        this.resetDragState(currentIndex);
+      }
+    });
+
+    this.addHandler(document, 'mouseup', () => {
+      if (!this.drag.active) return;
+
+      this.drag.active = false;
+      this.resetMouseCursor();
+
+      const { currentIndex } = this.carousel.state;
+      this.resetDragState(currentIndex);
+
+      if (Math.abs(this.drag.velocity) > DRAG_CONFIG.velocityThreshold) {
+        this.carousel.animator.startMomentum(this.drag.velocity);
+      }
+    });
+
+    this.addHandler(this.carousel.elements.carousel, 'mouseleave', () => {
+      if (this.drag.active) {
+        this.drag.active = false;
+        this.resetMouseCursor();
+
+        const { currentIndex } = this.carousel.state;
+        this.resetDragState(currentIndex);
+      }
+    });
+
+    if (window.innerWidth > BREAKPOINTS.mobile) {
+      this.resetMouseCursor();
+    }
+  }
+
+  initResize() {
+    let resizeTimer;
+    const handler = () => {
+      clearTimeout(resizeTimer);
+      resizeTimer = setTimeout(() => {
+        this.carousel.animator.updateCarousel();
+      }, RESIZE_DEBOUNCE);
+    };
+
+    this.addHandler(window, 'resize', handler);
+  }
+
+  addHandler(element, event, handler, options) {
+    element.addEventListener(event, handler, options);
+
+    const key = `${event}-${Date.now()}-${Math.random()}`;
+    this.boundHandlers.set(key, { element, event, handler, options });
+  }
+
+  destroy() {
+    if (this.wheel.scrollTimeout) {
+      clearTimeout(this.wheel.scrollTimeout);
+      this.wheel.scrollTimeout = null;
+    }
+
+    for (const { element, event, handler, options } of this.boundHandlers.values()) {
+      element.removeEventListener(event, handler, options);
+    }
+    this.boundHandlers.clear();
+
+    this.carousel = null;
+  }
+}

package/src/modules/Navigator.js

@@ -0,0 +1,116 @@
+import { normalizeIndex } from '../utils/helpers.js';
+
+const PROXIMITY_THRESHOLD = 2;
+
+export class Navigator {
+  constructor(carousel) {
+    this.carousel = carousel;
+  }
+
+  get currentIndex() {
+    return this.carousel.state.currentIndex;
+  }
+
+  set currentIndex(value) {
+    this.carousel.state.currentIndex = normalizeIndex(value, this.carousel.totalItems);
+  }
+
+  getShortestDistance(from, to) {
+    const total = this.carousel.totalItems;
+    const normalizedTo = normalizeIndex(to, total);
+    const normalizedFrom = normalizeIndex(from, total);
+
+    const forwardDist = (normalizedTo - normalizedFrom + total) % total;
+    const backwardDist = (normalizedFrom - normalizedTo + total) % total;
+
+    return forwardDist <= backwardDist ? forwardDist : -backwardDist;
+  }
+
+  isNearby(from, to) {
+    const distance = Math.abs(this.getShortestDistance(from, to));
+    return distance <= PROXIMITY_THRESHOLD;
+  }
+
+  updateAfterNavigation() {
+    this.carousel.animator.updateCarousel();
+    this.carousel.updateCounter();
+
+    if (this.carousel.options.preloadRange > 0) {
+      this.carousel.preloadImages();
+    }
+  }
+
+  rotate(direction) {
+    this.currentIndex = this.currentIndex + direction;
+    this.updateAfterNavigation();
+  }
+
+  next() {
+    this.rotate(1);
+  }
+
+  prev() {
+    this.rotate(-1);
+  }
+
+  goTo(index) {
+    const normalizedIndex = normalizeIndex(index, this.carousel.totalItems);
+    if (normalizedIndex === this.currentIndex) return;
+
+    this.currentIndex = normalizedIndex;
+    this.updateAfterNavigation();
+  }
+
+  navigateIfDifferent(targetIndex, callback) {
+    const normalizedIndex = normalizeIndex(targetIndex, this.carousel.totalItems);
+    if (normalizedIndex === this.currentIndex) return false;
+
+    callback(normalizedIndex);
+    return true;
+  }
+
+  handleItemClick(index) {
+    this.navigateIfDifferent(index, (normalizedIndex) => {
+      const { layoutMode } = this.carousel.options;
+
+      if (layoutMode === 'radial') {
+        this.handleRadialItemClick(normalizedIndex);
+      } else {
+        this.handleStackItemClick(normalizedIndex);
+      }
+    });
+  }
+
+  handleRadialItemClick(normalizedIndex) {
+    const shortestDist = this.getShortestDistance(this.currentIndex, normalizedIndex);
+
+    if (Math.abs(shortestDist) > 1) {
+      const direction = shortestDist > 0 ? 1 : -1;
+      this.rotate(direction);
+    } else {
+      this.rotate(shortestDist);
+    }
+  }
+
+  handleStackItemClick(normalizedIndex) {
+    if (this.isNearby(this.currentIndex, normalizedIndex)) {
+      const shortestDist = this.getShortestDistance(this.currentIndex, normalizedIndex);
+      this.rotate(shortestDist);
+    } else {
+      this.goTo(normalizedIndex);
+    }
+  }
+
+  handleIndicatorClick(index) {
+    this.navigateIfDifferent(index, (normalizedIndex) => {
+      const { layoutMode } = this.carousel.options;
+
+      if (layoutMode === 'radial') {
+        const shortestDist = this.getShortestDistance(this.currentIndex, normalizedIndex);
+        this.rotate(shortestDist);
+      } else {
+        this.goTo(normalizedIndex);
+      }
+    });
+  }
+}

package/src/modules/UIManager.js

@@ -0,0 +1,170 @@
+import { CLASS_NAMES, ARIA, DURATIONS } from '../core/constants.js';
+import { addClass, removeClass, setAttribute, setCSSVar } from '../utils/dom.js';
+
+const DRAG_TRANSFORM_CONFIG = Object.freeze({
+  stack: {
+    maxDrag: 200,
+    offsetMultiplier: 100,
+    rotationMultiplier: 3,
+  },
+  radial: {
+    rotationSensitivity: 0.2,
+  },
+  classic: {
+    dragSensitivity: 0.5,
+  },
+});
+
+export class UIManager {
+  constructor(carousel) {
+    this.carousel = carousel;
+  }
+
+  updateActiveStates(currentIndex) {
+    for (let i = 0; i < this.carousel.items.length; i++) {
+      const item = this.carousel.items[i];
+      removeClass(item, CLASS_NAMES.itemActive, CLASS_NAMES.itemPrev, CLASS_NAMES.itemNext);
+      item.removeAttribute(ARIA.current);
+    }
+
+    for (let i = 0; i < this.carousel.indicators.length; i++) {
+      const indicator = this.carousel.indicators[i];
+      removeClass(
+        indicator,
+        CLASS_NAMES.indicatorActive,
+        CLASS_NAMES.indicatorProgress
+      );
+      setAttribute(indicator, ARIA.selected, 'false');
+      setAttribute(indicator, ARIA.tabindex, '-1');
+    }
+
+    const currentItem = this.carousel.items[currentIndex];
+    const currentIndicator = this.carousel.indicators[currentIndex];
+
+    if (currentItem) {
+      addClass(currentItem, CLASS_NAMES.itemActive);
+      setAttribute(currentItem, ARIA.current, 'true');
+    }
+
+    if (currentIndicator) {
+      removeClass(currentIndicator, CLASS_NAMES.indicatorCompleted);
+      addClass(currentIndicator, CLASS_NAMES.indicatorActive);
+      setAttribute(currentIndicator, ARIA.selected, 'true');
+      setAttribute(currentIndicator, ARIA.tabindex, '0');
+
+      if (this.carousel.autoRotate.isActive) {
+        this.updateIndicatorProgress(currentIndicator);
+      }
+    }
+  }
+
+  updateIndicatorProgress(indicator) {
+    setCSSVar(
+      indicator,
+      '--progress-duration',
+      `${this.carousel.options.autoRotateInterval}ms`
+    );
+
+    setTimeout(() => {
+      if (indicator) {
+        addClass(indicator, CLASS_NAMES.indicatorProgress);
+      }
+    }, DURATIONS.progressReset);
+  }
+
+  clearPeekItems() {
+    for (let i = 0; i < this.carousel.items.length; i++) {
+      const item = this.carousel.items[i];
+      removeClass(item, CLASS_NAMES.itemPrev, CLASS_NAMES.itemNext);
+    }
+  }
+
+  setPeekItems(prevIndex, nextIndex) {
+    const prevItem = this.carousel.items[prevIndex];
+    const nextItem = this.carousel.items[nextIndex];
+
+    if (prevItem) addClass(prevItem, CLASS_NAMES.itemPrev);
+    if (nextItem) addClass(nextItem, CLASS_NAMES.itemNext);
+  }
+
+  updateAutoRotateButton(isActive) {
+    const { autoRotateBtn } = this.carousel.elements;
+    if (!autoRotateBtn) return;
+
+    if (isActive) {
+      addClass(autoRotateBtn, CLASS_NAMES.btnActive);
+      setAttribute(autoRotateBtn, ARIA.pressed, 'true');
+    } else {
+      removeClass(autoRotateBtn, CLASS_NAMES.btnActive);
+      setAttribute(autoRotateBtn, ARIA.pressed, 'false');
+    }
+  }
+
+  addDraggingClass(index, direction) {
+    const item = this.carousel.items[index];
+    if (!item) return;
+
+    const leftClass = CLASS_NAMES.itemDraggingLeft;
+    const rightClass = CLASS_NAMES.itemDraggingRight;
+
+    removeClass(item, leftClass, rightClass);
+
+    if (direction === 'left') {
+      addClass(item, leftClass);
+    } else if (direction === 'right') {
+      addClass(item, rightClass);
+    }
+  }
+
+  removeDraggingClass(index) {
+    const item = this.carousel.items[index];
+    if (!item) return;
+
+    removeClass(item, CLASS_NAMES.itemDraggingLeft, CLASS_NAMES.itemDraggingRight);
+  }
+
+  round(value, decimals = 2) {
+    return Math.round(value * 10 ** decimals) / 10 ** decimals;
+  }
+
+  applyEasing(progress) {
+    return progress * (2 - Math.abs(progress));
+  }
+
+  updateDragTransform(dragDistance) {
+    const { layoutMode } = this.carousel.options;
+
+    if (layoutMode === 'stack') {
+      // [개발참고] Stack 모드: 탄성 효과 적용 (easeOutQuad)
+      const config = DRAG_TRANSFORM_CONFIG.stack;
+      const clampedDrag = Math.max(-config.maxDrag, Math.min(config.maxDrag, dragDistance));
+      const progress = clampedDrag / config.maxDrag;
+      const easedProgress = this.applyEasing(progress);
+
+      const dragOffset = this.round(easedProgress * config.offsetMultiplier);
+      const dragRotation = this.round(easedProgress * config.rotationMultiplier);
+
+      this.carousel.container.style.setProperty('--drag-offset', `${dragOffset}px`);
+      this.carousel.container.style.setProperty('--drag-rotation', `${dragRotation}deg`);
+    } else if (layoutMode === 'radial') {
+      const config = DRAG_TRANSFORM_CONFIG.radial;
+      const dragRotation = this.round(dragDistance * config.rotationSensitivity);
+
+      this.carousel.container.style.setProperty('--drag-rotation-y', `${dragRotation}deg`);
+    } else if (layoutMode === 'classic') {
+      const config = DRAG_TRANSFORM_CONFIG.classic;
+      const dragOffset = this.round(dragDistance * config.dragSensitivity);
+
+      this.carousel.container.style.setProperty('--drag-offset', `${dragOffset}px`);
+    }
+  }
+
+  clearDragTransform() {
+    this.carousel.container.style.setProperty('--drag-offset', '0px');
+    this.carousel.container.style.setProperty('--drag-rotation', '0deg');
+    this.carousel.container.style.setProperty('--drag-rotation-y', '0deg');
+  }
+
+  destroy() {
+  }
+}

package/src/peek-carousel.d.ts

@@ -0,0 +1,34 @@
+export interface PeekCarouselOptions {
+  startIndex?: number;
+  layoutMode?: 'stack' | 'radial' | 'classic';
+  autoRotate?: boolean;
+  autoRotateInterval?: number;
+  swipeThreshold?: number;
+  dragThreshold?: number;
+  preloadRange?: number;
+  enableKeyboard?: boolean;
+  enableWheel?: boolean;
+  enableTouch?: boolean;
+  enableMouse?: boolean;
+  showNavigation?: boolean;
+  showCounter?: boolean;
+  showIndicators?: boolean;
+  showAutoRotateButton?: boolean;
+}
+
+export default class PeekCarousel {
+  currentIndex: number;
+  totalItems: number;
+  isAutoRotating: boolean;
+
+  constructor(selector: string | HTMLElement, options?: PeekCarouselOptions);
+
+  next(): void;
+  prev(): void;
+  goTo(index: number): void;
+  startAutoRotate(): void;
+  stopAutoRotate(): void;
+  toggleAutoRotate(): void;
+  updateLayoutClass(): void;
+  destroy(): void;
+}