peek-carousel 1.0.2

package/src/core/PeekCarousel.js

@@ -0,0 +1,294 @@
+import { validateOptions } from './config.js';
+import { SELECTORS, CLASS_NAMES } from './constants.js';
+import { getElement, getElements } from '../utils/dom.js';
+import { preloadImagesInRange } from '../utils/preloader.js';
+import { injectIcon, injectAutoRotateIcons } from '../utils/icons.js';
+import { Navigator } from '../modules/Navigator.js';
+import { Animator } from '../modules/Animator.js';
+import { AutoRotate } from '../modules/AutoRotate.js';
+import { EventHandler } from '../modules/EventHandler.js';
+import { UIManager } from '../modules/UIManager.js';
+
+const FULL_CIRCLE_DEGREES = 360;
+
+class PeekCarousel {
+  constructor(selector, options = {}) {
+    this.container = getElement(selector);
+    if (!this.container) {
+      throw new Error(`PeekCarousel: 셀렉터 "${selector}"에 해당하는 컨테이너를 찾을 수 없습니다`);
+    }
+
+    this.options = validateOptions(options);
+    this.initElements();
+
+    if (this.items.length === 0) {
+      throw new Error('PeekCarousel: 캐러셀 아이템을 찾을 수 없습니다');
+    }
+
+    this.state = {
+      currentIndex: this.options.startIndex,
+      angleUnit: FULL_CIRCLE_DEGREES / this.totalItems,
+    };
+
+    this.initModules();
+    this.init();
+  }
+
+  initElements() {
+    this.elements = {
+      carousel: this.container.querySelector(SELECTORS.carousel),
+      prevBtn: null,
+      nextBtn: null,
+      autoRotateBtn: null,
+      controls: null,
+      nav: null,
+    };
+
+    this.items = getElements(SELECTORS.item, this.container);
+    this.totalItems = this.items.length;
+    this.indicators = [];
+  }
+
+  initModules() {
+    this.navigator = new Navigator(this);
+    this.animator = new Animator(this);
+    this.autoRotate = new AutoRotate(this);
+    this.eventHandler = new EventHandler(this);
+    this.ui = new UIManager(this);
+  }
+
+  init() {
+    this.updateLayoutClass();
+    this.createNavigation();
+    this.createControls();
+    this.injectIcons();
+    this.createCounter();
+    this.setImageLoadingAttributes();
+    this.initCSSVariables();
+
+    this.eventHandler.init();
+    this.animator.updateCarousel();
+
+    if (this.options.autoRotate) {
+      this.autoRotate.start();
+    }
+
+    if (this.options.preloadRange > 0) {
+      this.preloadImages();
+    }
+  }
+
+  initCSSVariables() {
+    this.container.style.setProperty('--carousel-rotation', '0deg');
+    this.container.style.setProperty('--drag-offset', '0px');
+    this.container.style.setProperty('--drag-rotation', '0deg');
+    this.container.style.setProperty('--drag-rotation-y', '0deg');
+  }
+
+  createNavigation() {
+    if (!this.options.showNavigation) return;
+
+    const existingNav = this.container.querySelector(`.${CLASS_NAMES.nav}`);
+    if (existingNav) {
+      this.elements.nav = existingNav;
+      this.elements.prevBtn = existingNav.querySelector(SELECTORS.prevBtn);
+      this.elements.nextBtn = existingNav.querySelector(SELECTORS.nextBtn);
+      return;
+    }
+
+    const nav = document.createElement('div');
+    nav.className = CLASS_NAMES.nav;
+
+    const prevBtn = document.createElement('button');
+    prevBtn.className = `${CLASS_NAMES.navBtn} ${CLASS_NAMES.btn} ${CLASS_NAMES.prevBtn}`;
+    prevBtn.setAttribute('aria-label', 'Previous');
+
+    const nextBtn = document.createElement('button');
+    nextBtn.className = `${CLASS_NAMES.navBtn} ${CLASS_NAMES.btn} ${CLASS_NAMES.nextBtn}`;
+    nextBtn.setAttribute('aria-label', 'Next');
+
+    nav.appendChild(prevBtn);
+    nav.appendChild(nextBtn);
+    this.container.appendChild(nav);
+
+    this.elements.nav = nav;
+    this.elements.prevBtn = prevBtn;
+    this.elements.nextBtn = nextBtn;
+  }
+
+  createControls() {
+    if (!this.options.showIndicators && !this.options.showAutoRotateButton) return;
+
+    const existingControls = this.container.querySelector(`.${CLASS_NAMES.controls}`);
+    if (existingControls) {
+      this.elements.controls = existingControls;
+      const indicatorsWrapper = existingControls.querySelector(`.${CLASS_NAMES.indicators}`);
+      if (indicatorsWrapper && this.options.showIndicators) {
+        indicatorsWrapper.innerHTML = '';
+        this.createIndicators(indicatorsWrapper);
+      }
+      this.elements.autoRotateBtn = existingControls.querySelector(SELECTORS.autoRotateBtn);
+      return;
+    }
+
+    const controls = document.createElement('div');
+    controls.className = CLASS_NAMES.controls;
+
+    if (this.options.showIndicators) {
+      const indicatorsWrapper = document.createElement('div');
+      indicatorsWrapper.className = CLASS_NAMES.indicators;
+      this.createIndicators(indicatorsWrapper);
+      controls.appendChild(indicatorsWrapper);
+    }
+
+    if (this.options.showAutoRotateButton) {
+      const autoRotateBtn = document.createElement('button');
+      autoRotateBtn.className = `${CLASS_NAMES.autoRotateBtn} ${CLASS_NAMES.btn} ${CLASS_NAMES.btnAutoRotate}`;
+      autoRotateBtn.setAttribute('aria-label', 'Toggle auto-rotate');
+      autoRotateBtn.setAttribute('aria-pressed', 'false');
+      controls.appendChild(autoRotateBtn);
+      this.elements.autoRotateBtn = autoRotateBtn;
+    }
+
+    this.container.appendChild(controls);
+    this.elements.controls = controls;
+  }
+
+  createIndicators(wrapper) {
+    this.indicators = [];
+
+    for (let i = 0; i < this.totalItems; i++) {
+      const indicator = document.createElement('button');
+      const isActive = i === this.state.currentIndex;
+
+      indicator.className = CLASS_NAMES.indicator;
+      indicator.classList.add(CLASS_NAMES.indicatorPeek);
+      indicator.setAttribute('role', 'tab');
+      indicator.setAttribute('aria-label', `Image ${i + 1}`);
+      indicator.setAttribute('aria-selected', isActive ? 'true' : 'false');
+      indicator.setAttribute('tabindex', isActive ? '0' : '-1');
+
+      if (isActive) {
+        indicator.classList.add(CLASS_NAMES.indicatorActive);
+      }
+
+      wrapper.appendChild(indicator);
+      this.indicators.push(indicator);
+    }
+  }
+
+  injectIcons() {
+    const { prevBtn, nextBtn, autoRotateBtn } = this.elements;
+
+    if (prevBtn) injectIcon(prevBtn, 'prev');
+    if (nextBtn) injectIcon(nextBtn, 'next');
+    if (autoRotateBtn) injectAutoRotateIcons(autoRotateBtn);
+  }
+
+  createCounter() {
+    if (!this.options.showCounter) return;
+
+    const existingCounter = this.container.querySelector(`.${CLASS_NAMES.counter}`);
+    if (existingCounter) {
+      this.counterElement = existingCounter;
+      this.updateCounter();
+      return;
+    }
+
+    const counter = document.createElement('div');
+    counter.className = CLASS_NAMES.counter;
+    counter.setAttribute('aria-live', 'polite');
+    counter.setAttribute('aria-atomic', 'true');
+
+    counter.innerHTML = `
+      <span class="${CLASS_NAMES.counterCurrent}">${this.state.currentIndex + 1}</span>
+      <span class="${CLASS_NAMES.counterSeparator}">/</span>
+      <span class="${CLASS_NAMES.counterTotal}">${this.totalItems}</span>
+    `;
+
+    this.container.appendChild(counter);
+    this.counterElement = counter;
+  }
+
+  updateCounter() {
+    if (!this.counterElement) return;
+
+    const currentSpan = this.counterElement.querySelector(`.${CLASS_NAMES.counterCurrent}`);
+    if (currentSpan) {
+      currentSpan.textContent = this.state.currentIndex + 1;
+    }
+  }
+
+  setImageLoadingAttributes() {
+    const { startIndex } = this.options;
+    const preloadRange = this.options.preloadRange || 1;
+
+    for (let index = 0; index < this.items.length; index++) {
+      const item = this.items[index];
+      const img = item.querySelector(`.${CLASS_NAMES.image}`);
+      if (!img || img.hasAttribute('loading')) continue;
+
+      const distance = Math.abs(index - startIndex);
+      const isNearby = distance <= preloadRange;
+      img.setAttribute('loading', isNearby ? 'eager' : 'lazy');
+    }
+  }
+
+  updateLayoutClass() {
+    const currentMode = this.currentLayoutMode;
+    const newMode = this.options.layoutMode;
+
+    if (currentMode && currentMode !== newMode) {
+      this.container.classList.remove(`peek-carousel--${currentMode}`);
+    }
+
+    this.container.classList.add(`peek-carousel--${newMode}`);
+    this.currentLayoutMode = newMode;
+  }
+
+  preloadImages() {
+    preloadImagesInRange(this.items, this.state.currentIndex, this.options.preloadRange);
+  }
+
+  // [개발참고] Public API
+  next() {
+    this.navigator.next();
+  }
+
+  prev() {
+    this.navigator.prev();
+  }
+
+  goTo(index) {
+    this.navigator.goTo(index);
+  }
+
+  startAutoRotate() {
+    this.autoRotate.start();
+  }
+
+  stopAutoRotate() {
+    this.autoRotate.stop();
+  }
+
+  toggleAutoRotate() {
+    this.autoRotate.toggle();
+  }
+
+  destroy() {
+    this.autoRotate.destroy();
+    this.animator.stopMomentum();
+    this.eventHandler.destroy();
+    this.ui.destroy();
+  }
+
+  get currentIndex() {
+    return this.state.currentIndex;
+  }
+
+  get isAutoRotating() {
+    return this.autoRotate.isActive;
+  }
+}
+
+export default PeekCarousel;

package/src/core/config.js

@@ -0,0 +1,49 @@
+export const LAYOUT_MODES = Object.freeze({
+  STACK: 'stack',
+  RADIAL: 'radial',
+  CLASSIC: 'classic',
+});
+
+export const DEFAULT_OPTIONS = Object.freeze({
+  startIndex: 1,
+  layoutMode: LAYOUT_MODES.STACK,
+  autoRotate: false,
+  autoRotateInterval: 2500,
+  preloadRange: 2,
+  swipeThreshold: 50,
+  dragThreshold: 80,
+  enableKeyboard: true,
+  enableWheel: true,
+  enableTouch: true,
+  enableMouse: true,
+  showNavigation: true,
+  showCounter: true,
+  showIndicators: true,
+  showAutoRotateButton: true,
+});
+
+export function validateOptions(options) {
+  const validated = { ...DEFAULT_OPTIONS, ...options };
+
+  if (validated.startIndex < 0) {
+    console.warn('PeekCarousel: startIndex는 0 이상이어야 합니다. 기본값 1 사용');
+    validated.startIndex = 1;
+  }
+
+  if (!Object.values(LAYOUT_MODES).includes(validated.layoutMode)) {
+    console.warn(`PeekCarousel: 유효하지 않은 layoutMode "${validated.layoutMode}". 기본값 "stack" 사용`);
+    validated.layoutMode = LAYOUT_MODES.STACK;
+  }
+
+  if (validated.autoRotateInterval < 100) {
+    console.warn('PeekCarousel: autoRotateInterval은 100ms 이상이어야 합니다. 기본값 2500 사용');
+    validated.autoRotateInterval = 2500;
+  }
+
+  if (validated.preloadRange < 0) {
+    console.warn('PeekCarousel: preloadRange는 0 이상이어야 합니다. 기본값 2 사용');
+    validated.preloadRange = 2;
+  }
+
+  return validated;
+}

package/src/core/constants.js

@@ -0,0 +1,73 @@
+export const CLASS_NAMES = Object.freeze({
+  carousel: 'peek-carousel',
+  track: 'peek-carousel__track',
+  item: 'peek-carousel__item',
+  itemActive: 'peek-carousel__item--active',
+  itemPrev: 'peek-carousel__item--prev',
+  itemNext: 'peek-carousel__item--next',
+  itemCenter: 'peek-carousel__item--center',
+  itemHidden: 'peek-carousel__item--hidden',
+  itemDraggingLeft: 'peek-carousel__item--dragging-left',
+  itemDraggingRight: 'peek-carousel__item--dragging-right',
+  figure: 'peek-carousel__figure',
+  image: 'peek-carousel__image',
+  caption: 'peek-carousel__caption',
+  nav: 'peek-carousel__nav',
+  navBtn: 'nav-btn',
+  btn: 'peek-carousel__btn',
+  prevBtn: 'prev-btn',
+  nextBtn: 'next-btn',
+  autoRotateBtn: 'auto-rotate-btn',
+  btnAutoRotate: 'peek-carousel__btn--auto-rotate',
+  btnActive: 'peek-carousel__btn--active',
+  controls: 'peek-carousel__controls',
+  indicators: 'peek-carousel__indicators',
+  indicator: 'indicator',
+  indicatorPeek: 'peek-carousel__indicator',
+  indicatorActive: 'peek-carousel__indicator--active',
+  indicatorProgress: 'peek-carousel__indicator--progress',
+  indicatorCompleted: 'peek-carousel__indicator--completed',
+  counter: 'peek-carousel__counter',
+  counterCurrent: 'peek-carousel__counter-current',
+  counterSeparator: 'peek-carousel__counter-separator',
+  counterTotal: 'peek-carousel__counter-total',
+  playIcon: 'play-icon',
+  pauseIcon: 'pause-icon',
+});
+
+export const SELECTORS = Object.freeze({
+  carousel: '.peek-carousel__track',
+  item: '.peek-carousel__item',
+  indicator: '.indicator',
+  prevBtn: '.prev-btn',
+  nextBtn: '.next-btn',
+  autoRotateBtn: '.auto-rotate-btn',
+  playIcon: '.play-icon',
+  pauseIcon: '.pause-icon',
+  image: 'img',
+});
+
+export const ARIA = Object.freeze({
+  current: 'aria-current',
+  selected: 'aria-selected',
+  pressed: 'aria-pressed',
+  label: 'aria-label',
+  tabindex: 'tabindex',
+});
+
+export const BREAKPOINTS = Object.freeze({
+  mobile: 768, // [개발참고] px
+});
+
+export const DURATIONS = Object.freeze({
+  transition: 500, // [개발참고] ms
+  progressReset: 10, // [개발참고] ms
+});
+
+export const KEYS = Object.freeze({
+  arrowLeft: 'ArrowLeft',
+  arrowRight: 'ArrowRight',
+  home: 'Home',
+  end: 'End',
+  space: ' ',
+});

package/src/modules/Animator.js

@@ -0,0 +1,244 @@
+import { normalizeIndex } from '../utils/helpers.js';
+import { CLASS_NAMES } from '../core/constants.js';
+
+const RADIAL_RADIUS = 400;
+
+const CLASSIC_POSITIONS = Object.freeze({
+  center: { x: 50, scale: 1 },
+  peek: { scale: 1 },
+  hidden: { scale: 0.85 },
+});
+
+const CLASSIC_SPACING = Object.freeze({
+  gapPercent: 5,
+  additionalMobile: 40,
+  additionalDesktop: 15,
+  mobileBreakpoint: 768,
+});
+
+const MOMENTUM_CONFIG = Object.freeze({
+  friction: 0.92,
+  minVelocity: 0.05,
+  navigationThreshold: 1.5,
+  dampingFactor: 0.6,
+});
+
+const STACK_POSITION_CLASSES = [
+  CLASS_NAMES.itemCenter,
+  CLASS_NAMES.itemPrev,
+  CLASS_NAMES.itemNext,
+  CLASS_NAMES.itemHidden,
+];
+
+export class Animator {
+  constructor(carousel) {
+    this.carousel = carousel;
+    this.momentumAnimation = null;
+    this.isAnimating = false;
+  }
+
+  normalizeAngleDiff(diff) {
+    return ((diff + 180) % 360) - 180;
+  }
+
+  round(value, decimals = 2) {
+    return Math.round(value * 10 ** decimals) / 10 ** decimals;
+  }
+
+  getAdjacentIndices(currentIndex) {
+    return {
+      prev: normalizeIndex(currentIndex - 1, this.carousel.totalItems),
+      next: normalizeIndex(currentIndex + 1, this.carousel.totalItems),
+    };
+  }
+
+  setCarouselRotation(angle) {
+    const rounded = this.round(angle, 2);
+    this.carousel.container.style.setProperty('--carousel-rotation', `${rounded}deg`);
+  }
+
+  setCSSVariables(element, variables) {
+    for (const [key, value] of Object.entries(variables)) {
+      element.style.setProperty(key, value);
+    }
+  }
+
+  updateRadialRotation(currentIndex) {
+    const targetAngle = -this.carousel.state.angleUnit * currentIndex;
+    const currentRotation = this.carousel.container.style.getPropertyValue('--carousel-rotation');
+
+    if (!currentRotation || currentRotation === '0deg') {
+      this.setCarouselRotation(targetAngle);
+      return;
+    }
+
+    // [개발참고] 최단 경로 계산: -180 ~ 180 범위로 정규화
+    const currentAngle = parseFloat(currentRotation);
+    const diff = this.normalizeAngleDiff(targetAngle - currentAngle);
+    const finalAngle = currentAngle + diff;
+    this.setCarouselRotation(finalAngle);
+  }
+
+  updateCarousel() {
+    const { currentIndex } = this.carousel.state;
+    const { layoutMode } = this.carousel.options;
+
+    if (layoutMode === 'stack' || layoutMode === 'classic') {
+      this.setCarouselRotation(0);
+    } else if (layoutMode === 'radial') {
+      this.updateRadialRotation(currentIndex);
+    }
+
+    this.updateActiveItem();
+  }
+
+  updateActiveItem() {
+    const { currentIndex } = this.carousel.state;
+    const { layoutMode } = this.carousel.options;
+
+    this.carousel.ui.updateActiveStates(currentIndex);
+
+    if (layoutMode === 'radial') {
+      this.updateRadialPositions(currentIndex);
+    } else if (layoutMode === 'classic') {
+      this.updateClassicPositions(currentIndex);
+    } else {
+      this.updateStackPositions(currentIndex);
+    }
+  }
+
+  updateRadialPositions(currentIndex) {
+    const { angleUnit } = this.carousel.state;
+
+    for (let i = 0; i < this.carousel.items.length; i++) {
+      const item = this.carousel.items[i];
+      const angle = angleUnit * i;
+
+      this.setCSSVariables(item, {
+        '--item-angle': `${this.round(angle, 2)}deg`,
+        '--item-radius': `${RADIAL_RADIUS}px`,
+      });
+    }
+
+    const { prev, next } = this.getAdjacentIndices(currentIndex);
+    this.carousel.ui.setPeekItems(prev, next);
+  }
+
+  updateStackPositions(currentIndex) {
+    const { prev, next } = this.getAdjacentIndices(currentIndex);
+
+    for (let i = 0; i < this.carousel.items.length; i++) {
+      const item = this.carousel.items[i];
+
+      item.classList.remove(...STACK_POSITION_CLASSES);
+
+      if (i === currentIndex) {
+        item.classList.add(CLASS_NAMES.itemCenter);
+      } else if (i === prev) {
+        item.classList.add(CLASS_NAMES.itemPrev);
+      } else if (i === next) {
+        item.classList.add(CLASS_NAMES.itemNext);
+      } else {
+        item.classList.add(CLASS_NAMES.itemHidden);
+      }
+    }
+  }
+
+  calculateClassicSpacing(containerWidth) {
+    const itemWidth = Math.max(300, Math.min(containerWidth * 0.35, 500));
+    const isMobile = containerWidth <= CLASSIC_SPACING.mobileBreakpoint;
+
+    const itemHalfPercent = (itemWidth / containerWidth) * 50;
+    const baseSpacing = itemHalfPercent + CLASSIC_SPACING.gapPercent;
+    const additionalSpacing = isMobile
+      ? CLASSIC_SPACING.additionalMobile
+      : CLASSIC_SPACING.additionalDesktop;
+
+    return baseSpacing + additionalSpacing;
+  }
+
+  getClassicItemPosition(itemIndex, currentIndex, itemSpacing) {
+    const { prev, next } = this.getAdjacentIndices(currentIndex);
+
+    if (itemIndex === currentIndex) {
+      return {
+        x: CLASSIC_POSITIONS.center.x,
+        scale: CLASSIC_POSITIONS.center.scale,
+      };
+    }
+
+    if (itemIndex === prev) {
+      return {
+        x: CLASSIC_POSITIONS.center.x - itemSpacing,
+        scale: CLASSIC_POSITIONS.peek.scale,
+      };
+    }
+
+    if (itemIndex === next) {
+      return {
+        x: CLASSIC_POSITIONS.center.x + itemSpacing,
+        scale: CLASSIC_POSITIONS.peek.scale,
+      };
+    }
+
+    const distanceFromCurrent = itemIndex - currentIndex;
+    return {
+      x: distanceFromCurrent < 0
+        ? CLASSIC_POSITIONS.center.x - itemSpacing * 2
+        : CLASSIC_POSITIONS.center.x + itemSpacing * 2,
+      scale: CLASSIC_POSITIONS.hidden.scale,
+    };
+  }
+
+  updateClassicPositions(currentIndex) {
+    const { prev, next } = this.getAdjacentIndices(currentIndex);
+    const containerWidth = this.carousel.container.offsetWidth;
+    const itemSpacing = this.calculateClassicSpacing(containerWidth);
+
+    for (let i = 0; i < this.carousel.items.length; i++) {
+      const item = this.carousel.items[i];
+      const { x, scale } = this.getClassicItemPosition(i, currentIndex, itemSpacing);
+
+      this.setCSSVariables(item, {
+        '--item-x': `${this.round(x, 2)}%`,
+        '--item-scale': String(scale),
+      });
+    }
+
+    this.carousel.ui.setPeekItems(prev, next);
+  }
+
+  startMomentum(velocity) {
+    this.stopMomentum();
+
+    let currentVelocity = velocity;
+
+    const momentumStep = () => {
+      currentVelocity *= MOMENTUM_CONFIG.friction;
+
+      if (Math.abs(currentVelocity) < MOMENTUM_CONFIG.minVelocity) {
+        this.stopMomentum();
+        return;
+      }
+
+      if (Math.abs(currentVelocity) > MOMENTUM_CONFIG.navigationThreshold) {
+        const direction = currentVelocity > 0 ? -1 : 1;
+        this.carousel.navigator.rotate(direction);
+        currentVelocity *= MOMENTUM_CONFIG.dampingFactor;
+      }
+
+      this.momentumAnimation = requestAnimationFrame(momentumStep);
+    };
+
+    this.isAnimating = true;
+    this.momentumAnimation = requestAnimationFrame(momentumStep);
+  }
+
+  stopMomentum() {
+    if (this.momentumAnimation) {
+      cancelAnimationFrame(this.momentumAnimation);
+      this.momentumAnimation = null;
+    }
+    this.isAnimating = false;
+  }
+}

package/src/modules/AutoRotate.js

@@ -0,0 +1,43 @@
+export class AutoRotate {
+  constructor(carousel) {
+    this.carousel = carousel;
+    this.interval = null;
+    this.isActive = false;
+  }
+
+  setActiveState(isActive) {
+    this.isActive = isActive;
+    this.carousel.ui.updateAutoRotateButton(isActive);
+  }
+
+  toggle() {
+    this.isActive ? this.stop() : this.start();
+  }
+
+  start() {
+    if (this.isActive) return;
+
+    this.setActiveState(true);
+
+    const rotateInterval = this.carousel.options.autoRotateInterval;
+    this.interval = setInterval(() => {
+      this.carousel.navigator.next();
+    }, rotateInterval);
+  }
+
+  stop() {
+    if (!this.isActive) return;
+
+    this.setActiveState(false);
+
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+  }
+
+  destroy() {
+    this.stop();
+    this.carousel = null;
+  }
+}