peek-carousel 1.0.2

package/src/styles/components/carousel/_carousel-classic.scss

@@ -0,0 +1,76 @@
+@use '../../base/variables' as *;
+@use 'carousel-variables' as *;
+@use 'carousel-mixins' as *;
+@use 'sass:list';
+
+.peek-carousel--classic {
+  overflow: hidden;
+
+  .peek-carousel__track {
+    transition: transform $transition-smooth;
+    transform: translateX(calc(var(--track-offset, 0px) + var(--drag-offset)));
+
+    &:active {
+      transition: transform $drag-transition-duration;
+    }
+  }
+
+  .peek-carousel__item {
+    position: absolute;
+    left: var(--item-x, 50%);
+    transform: translate(-50%, -50%) scale(var(--item-scale, 1));
+    opacity: 0;
+    visibility: hidden;
+    cursor: default;
+    z-index: $z-index-base;
+    @include classic-item-transition;
+
+    &--active {
+      opacity: 1;
+      visibility: visible;
+      z-index: $z-index-active;
+      cursor: grab;
+      @include classic-item-transition(0s);
+
+      &:active {
+        cursor: grabbing;
+      }
+
+      .peek-carousel__image {
+        box-shadow: list.join(
+          (0 40px 100px $color-primary-60,
+           0 0 40px $color-primary-40,
+           0 0 80px $color-secondary),
+          (),
+          $separator: comma
+        );
+        filter: brightness($classic-active-brightness) saturate($classic-active-saturation);
+      }
+    }
+
+    &--prev,
+    &--next {
+      opacity: $classic-peek-opacity;
+      visibility: visible;
+      z-index: $z-index-item;
+      cursor: pointer;
+      @include classic-item-transition(0s);
+
+      .peek-carousel__image {
+        filter: brightness($classic-peek-brightness) saturate($classic-peek-saturation);
+        box-shadow: 0 25px 60px rgba(0, 0, 0, 0.5);
+      }
+
+      &:hover .peek-carousel__image {
+        filter: brightness($classic-peek-hover-brightness) saturate($classic-peek-hover-saturation) !important;
+        box-shadow: 0 30px 70px $color-primary-30 !important;
+        transition: all $transition-base;
+      }
+    }
+
+    &:not(&--active):not(&--prev):not(&--next) .peek-carousel__image {
+      box-shadow: 0 10px 30px rgba(0, 0, 0, 0.3);
+      filter: brightness($classic-hidden-brightness) saturate($classic-hidden-saturation);
+    }
+  }
+}

package/src/styles/components/carousel/_carousel-mixins.scss

@@ -0,0 +1,18 @@
+@use '../../base/variables' as *;
+
+@mixin base-item-transition($visibility-delay: 0s) {
+  transition:
+    transform $transition-smooth,
+    opacity $transition-smooth,
+    visibility 0s $visibility-delay,
+    z-index 0s;
+}
+
+@mixin classic-item-transition($visibility-delay: $transition-smooth) {
+  transition:
+    transform $transition-smooth,
+    opacity $transition-smooth,
+    left $transition-smooth,
+    visibility 0s $visibility-delay,
+    z-index 0s;
+}

package/src/styles/components/carousel/_carousel-radial.scss

@@ -0,0 +1,72 @@
+@use '../../base/variables' as *;
+@use 'carousel-variables' as *;
+@use 'carousel-mixins' as *;
+@use 'sass:list';
+
+.peek-carousel--radial {
+  perspective: $perspective-distance;
+
+  .peek-carousel__track {
+    transition: transform $transition-smooth;
+    transform: rotateY(calc(var(--carousel-rotation, 0deg) + var(--drag-rotation-y)));
+
+    &:active {
+      transition: transform $drag-transition-duration;
+    }
+  }
+
+  .peek-carousel__item {
+    opacity: 0;
+    visibility: hidden;
+    cursor: default;
+    transform: translate(-50%, -50%)
+               rotateY(var(--item-angle))
+               translateZ(var(--item-radius));
+    @include base-item-transition($radial-visibility-delay);
+
+    &--active {
+      opacity: 1;
+      visibility: visible;
+      z-index: $z-index-active;
+      cursor: grab;
+      @include base-item-transition(0s);
+
+      &:active {
+        cursor: grabbing;
+      }
+
+      .peek-carousel__image {
+        box-shadow: list.join(
+          (0 40px 100px $color-primary-60,
+           0 0 40px $color-primary-40,
+           0 0 80px $color-secondary),
+          (),
+          $separator: comma
+        );
+        filter: brightness($radial-active-brightness) saturate($radial-active-saturation);
+      }
+    }
+
+    &--prev,
+    &--next {
+      opacity: $radial-peek-opacity;
+      visibility: visible;
+      z-index: $z-index-item;
+      @include base-item-transition(0s);
+
+      .peek-carousel__image {
+        filter: brightness($radial-peek-brightness) saturate($radial-peek-saturation);
+        box-shadow: 0 25px 60px rgba(0, 0, 0, 0.6);
+      }
+    }
+
+    &:not(&--active) .peek-carousel__image {
+      filter: brightness($radial-inactive-brightness) saturate($radial-inactive-saturation);
+      box-shadow: 0 20px 50px rgba(0, 0, 0, 0.5);
+    }
+
+    @media (max-width: $breakpoint-mobile) {
+      --item-radius: #{$item-mobile-radius};
+    }
+  }
+}

package/src/styles/components/carousel/_carousel-stack.scss

@@ -0,0 +1,84 @@
+@use '../../base/variables' as *;
+@use 'carousel-variables' as *;
+@use 'sass:list';
+
+.peek-carousel--stack {
+  .peek-carousel__track {
+    transition: none;
+    transform: none;
+  }
+
+  .peek-carousel__item {
+    cursor: pointer;
+    opacity: $stack-inactive-opacity;
+    visibility: visible;
+    transition:
+      transform $drag-transition-duration,
+      opacity $drag-transition-duration,
+      z-index 0s;
+
+    &:not(.peek-carousel__item--dragging-left):not(.peek-carousel__item--dragging-right) {
+      transition:
+        transform $stack-normal-transition,
+        opacity $stack-normal-transition,
+        z-index 0s;
+    }
+
+    &--active {
+      opacity: 1;
+      z-index: $z-index-active;
+
+      .peek-carousel__image {
+        box-shadow: list.join(
+          (0 40px 100px $color-primary-60,
+           0 0 40px $color-primary-40,
+           0 0 80px $color-secondary),
+          (),
+          $separator: comma
+        );
+        filter: brightness($stack-active-brightness) saturate($stack-active-saturation);
+      }
+    }
+
+    &:not(&--active) {
+      .peek-carousel__image {
+        box-shadow: 0 20px 50px rgba(0, 0, 0, 0.5);
+        filter: brightness($stack-inactive-brightness) saturate($stack-inactive-saturation);
+      }
+
+      &:hover .peek-carousel__image {
+        filter: brightness($stack-hover-brightness) saturate($stack-hover-saturation) !important;
+        box-shadow: 0 30px 70px $color-primary-30 !important;
+        transition: all $transition-base;
+      }
+    }
+
+    &--center {
+      transform: translate(-50%, -50%)
+                 scale(1.15)
+                 translateX(var(--drag-offset))
+                 rotateZ(var(--drag-rotation));
+    }
+
+    &--prev {
+      transform: translate(calc(-50% - 45%), -50%)
+                 scale(0.85)
+                 translateX(calc(-15px + var(--drag-offset)))
+                 rotateZ(var(--drag-rotation));
+    }
+
+    &--next {
+      transform: translate(calc(-50% + 45%), -50%)
+                 scale(0.85)
+                 translateX(calc(15px + var(--drag-offset)))
+                 rotateZ(var(--drag-rotation));
+    }
+
+    &--hidden {
+      transform: translate(-50%, -50%)
+                 scale(0.7)
+                 translateX(var(--drag-offset))
+                 rotateZ(var(--drag-rotation));
+    }
+  }
+}

package/src/styles/components/carousel/_carousel-variables.scss

@@ -0,0 +1,118 @@
+@use '../../base/variables' as *;
+@use 'sass:map';
+
+$breakpoint-mobile: 768px;
+$drag-transition-duration: 0.05s;
+$perspective-distance: 1200px;
+
+$carousel-animation: (
+  duration: 0.8s,
+  delay: 0.1s,
+  initial-offset: 30px
+);
+
+// 아이템 크기 설정
+$item-config: (
+  default: (
+    scale: 0.8,
+    radius: 400px
+  ),
+  mobile: (
+    min-width: 280px,
+    max-width: 400px,
+    radius: 300px
+  )
+);
+
+// 하위 호환성 - 개별 변수
+$animation-duration: map.get($carousel-animation, duration);
+$animation-delay: map.get($carousel-animation, delay);
+$initial-offset: map.get($carousel-animation, initial-offset);
+
+$item-default-scale: map.get(map.get($item-config, default), scale);
+$item-default-radius: map.get(map.get($item-config, default), radius);
+$item-mobile-min-width: map.get(map.get($item-config, mobile), min-width);
+$item-mobile-max-width: map.get(map.get($item-config, mobile), max-width);
+$item-mobile-radius: map.get(map.get($item-config, mobile), radius);
+
+$stack-mode: (
+  inactive-opacity: 0.5,
+  normal-transition: 0.5s,
+  active: (
+    brightness: 1.2,
+    saturation: 1.1
+  ),
+  inactive: (
+    brightness: 0.7,
+    saturation: 0.85
+  ),
+  hover: (
+    brightness: 0.9,
+    saturation: 1
+  )
+);
+
+$stack-inactive-opacity: map.get($stack-mode, inactive-opacity);
+$stack-normal-transition: map.get($stack-mode, normal-transition);
+$stack-active-brightness: map.get(map.get($stack-mode, active), brightness);
+$stack-active-saturation: map.get(map.get($stack-mode, active), saturation);
+$stack-inactive-brightness: map.get(map.get($stack-mode, inactive), brightness);
+$stack-inactive-saturation: map.get(map.get($stack-mode, inactive), saturation);
+$stack-hover-brightness: map.get(map.get($stack-mode, hover), brightness);
+$stack-hover-saturation: map.get(map.get($stack-mode, hover), saturation);
+
+$radial-mode: (
+  visibility-delay: 0.5s,
+  peek-opacity: 0.3,
+  active: (
+    brightness: 1.2,
+    saturation: 1.1
+  ),
+  inactive: (
+    brightness: 0.7,
+    saturation: 0.85
+  ),
+  peek: (
+    brightness: 0.8,
+    saturation: 0.9
+  )
+);
+
+$radial-visibility-delay: map.get($radial-mode, visibility-delay);
+$radial-peek-opacity: map.get($radial-mode, peek-opacity);
+$radial-active-brightness: map.get(map.get($radial-mode, active), brightness);
+$radial-active-saturation: map.get(map.get($radial-mode, active), saturation);
+$radial-inactive-brightness: map.get(map.get($radial-mode, inactive), brightness);
+$radial-inactive-saturation: map.get(map.get($radial-mode, inactive), saturation);
+$radial-peek-brightness: map.get(map.get($radial-mode, peek), brightness);
+$radial-peek-saturation: map.get(map.get($radial-mode, peek), saturation);
+
+$classic-mode: (
+  peek-opacity: 0.6,
+  active: (
+    brightness: 1.15,
+    saturation: 1.1
+  ),
+  peek: (
+    brightness: 0.8,
+    saturation: 0.95
+  ),
+  peek-hover: (
+    brightness: 1,
+    saturation: 1.05
+  ),
+  hidden: (
+    brightness: 0.5,
+    saturation: 0.7
+  )
+);
+
+$classic-peek-opacity: map.get($classic-mode, peek-opacity);
+$classic-active-brightness: map.get(map.get($classic-mode, active), brightness);
+$classic-active-saturation: map.get(map.get($classic-mode, active), saturation);
+$classic-peek-brightness: map.get(map.get($classic-mode, peek), brightness);
+$classic-peek-saturation: map.get(map.get($classic-mode, peek), saturation);
+$classic-peek-hover-brightness: map.get(map.get($classic-mode, peek-hover), brightness);
+$classic-peek-hover-saturation: map.get(map.get($classic-mode, peek-hover), saturation);
+$classic-hidden-brightness: map.get(map.get($classic-mode, hidden), brightness);
+$classic-hidden-saturation: map.get(map.get($classic-mode, hidden), saturation);

package/src/styles/peek-carousel.scss

@@ -0,0 +1,11 @@
+/**
+ * PeekCarousel - Peek 효과를 가진 캐러셀
+ * @version 1.0.0
+ * @license MIT
+ */
+
+@use 'base/accessibility';
+@use 'components/carousel';
+@use 'components/indicators';
+@use 'components/navigation';
+@use 'components/counter';

package/src/utils/dom.js

@@ -0,0 +1,53 @@
+export function getElement(selector) {
+  if (typeof selector === 'string') {
+    return document.querySelector(selector);
+  }
+  return selector instanceof HTMLElement ? selector : null;
+}
+
+export function getElements(selector, parent = document) {
+  if (typeof selector !== 'string') return [];
+  return Array.from(parent.querySelectorAll(selector));
+}
+
+export function addClass(element, ...classes) {
+  if (element instanceof HTMLElement && classes.length > 0) {
+    element.classList.add(...classes);
+  }
+}
+
+export function removeClass(element, ...classes) {
+  if (element instanceof HTMLElement && classes.length > 0) {
+    element.classList.remove(...classes);
+  }
+}
+
+export function toggleClass(element, className, force) {
+  if (element instanceof HTMLElement && className) {
+    element.classList.toggle(className, force);
+  }
+}
+
+export function setStyle(element, property, value) {
+  if (element instanceof HTMLElement && property) {
+    element.style[property] = value;
+  }
+}
+
+export function setCSSVar(element, property, value) {
+  if (element instanceof HTMLElement && property) {
+    element.style.setProperty(property, value);
+  }
+}
+
+export function setAttribute(element, name, value) {
+  if (element instanceof HTMLElement && name) {
+    element.setAttribute(name, value);
+  }
+}
+
+export function removeAttribute(element, name) {
+  if (element instanceof HTMLElement && name) {
+    element.removeAttribute(name);
+  }
+}

package/src/utils/helpers.js

@@ -0,0 +1,46 @@
+export function isMobile() {
+  return window.innerWidth <= 768;
+}
+
+export function normalizeIndex(index, length) {
+  if (length <= 0) return 0;
+  return ((index % length) + length) % length;
+}
+
+export function clamp(value, min, max) {
+  if (min > max) [min, max] = [max, min];
+  return Math.min(Math.max(value, min), max);
+}
+
+export function debounce(func, wait) {
+  if (typeof func !== 'function') {
+    throw new TypeError('첫 번째 인자는 함수여야 합니다');
+  }
+
+  let timeout;
+  return function executedFunction(...args) {
+    const context = this;
+    const later = () => {
+      clearTimeout(timeout);
+      func.apply(context, args);
+    };
+    clearTimeout(timeout);
+    timeout = setTimeout(later, wait);
+  };
+}
+
+export function throttle(func, limit) {
+  if (typeof func !== 'function') {
+    throw new TypeError('첫 번째 인자는 함수여야 합니다');
+  }
+
+  let inThrottle;
+  return function executedFunction(...args) {
+    const context = this;
+    if (!inThrottle) {
+      func.apply(context, args);
+      inThrottle = true;
+      setTimeout(() => (inThrottle = false), limit);
+    }
+  };
+}

package/src/utils/icons.js

@@ -0,0 +1,92 @@
+const iconCache = new Map();
+
+function createSVGIcon(path, options = {}) {
+  const {
+    width = 24,
+    height = 24,
+    viewBox = '0 0 24 24',
+    fill = 'none',
+    stroke = 'currentColor',
+    strokeWidth = 2,
+    strokeLinecap = 'round',
+    strokeLinejoin = 'round',
+    className = '',
+  } = options;
+
+  const cacheKey = `${path}-${JSON.stringify(options)}`;
+  if (iconCache.has(cacheKey)) {
+    return iconCache.get(cacheKey);
+  }
+
+  const svg = `<svg width="${width}" height="${height}" viewBox="${viewBox}" fill="${fill}" xmlns="http://www.w3.org/2000/svg" class="${className}"><path d="${path}" stroke="${stroke}" stroke-width="${strokeWidth}" stroke-linecap="${strokeLinecap}" stroke-linejoin="${strokeLinejoin}"/></svg>`;
+
+  iconCache.set(cacheKey, svg);
+  return svg;
+}
+
+export const ICONS = {
+  prev: {
+    path: 'M15 18L9 12L15 6',
+    options: {},
+  },
+  next: {
+    path: 'M9 18L15 12L9 6',
+    options: {},
+  },
+  play: {
+    path: 'M8 6.5v11l9-5.5z',
+    options: {
+      fill: 'currentColor',
+      stroke: 'currentColor',
+      strokeWidth: 0,
+      strokeLinecap: 'round',
+      strokeLinejoin: 'round',
+    },
+  },
+  pause: {
+    path: 'M7 5.5C7 5.22386 7.22386 5 7.5 5H9.5C9.77614 5 10 5.22386 10 5.5V18.5C10 18.7761 9.77614 19 9.5 19H7.5C7.22386 19 7 18.7761 7 18.5V5.5ZM14 5.5C14 5.22386 14.2239 5 14.5 5H16.5C16.7761 5 17 5.22386 17 5.5V18.5C17 18.7761 16.7761 19 16.5 19H14.5C14.2239 19 14 18.7761 14 18.5V5.5Z',
+    options: {
+      fill: 'currentColor',
+      stroke: 'none',
+    },
+  },
+};
+
+export function getIcon(iconName, customOptions = {}) {
+  const icon = ICONS[iconName];
+  if (!icon) {
+    console.warn(`PeekCarousel: 아이콘 "${iconName}"을 찾을 수 없습니다`);
+    return '';
+  }
+
+  const options = { ...icon.options, ...customOptions };
+  return createSVGIcon(icon.path, options);
+}
+
+export function injectIcon(button, iconName, options = {}) {
+  if (!button || !(button instanceof HTMLElement)) return;
+
+  if (button.querySelector('svg')) {
+    return;
+  }
+
+  const iconHTML = getIcon(iconName, options);
+  if (iconHTML) {
+    button.innerHTML = iconHTML;
+  }
+}
+
+export function injectAutoRotateIcons(button) {
+  if (!button || !(button instanceof HTMLElement)) return;
+
+  if (button.querySelector('svg')) {
+    return;
+  }
+
+  const playHTML = getIcon('play', { className: 'play-icon' });
+  const pauseHTML = getIcon('pause', { className: 'pause-icon' });
+
+  if (playHTML && pauseHTML) {
+    button.innerHTML = playHTML + pauseHTML;
+  }
+}

package/src/utils/preloader.js

@@ -0,0 +1,69 @@
+const loadingCache = new Map();
+
+export function preloadImage(src) {
+  return new Promise((resolve, reject) => {
+    if (!src) {
+      reject(new Error('이미지 소스가 제공되지 않았습니다'));
+      return;
+    }
+
+    if (loadingCache.has(src)) {
+      return loadingCache.get(src);
+    }
+
+    const img = new Image();
+    const promise = new Promise((res, rej) => {
+      img.onload = () => {
+        loadingCache.delete(src);
+        res(img);
+      };
+      img.onerror = () => {
+        loadingCache.delete(src);
+        rej(new Error(`이미지 로드 실패: ${src}`));
+      };
+      img.src = src;
+    });
+
+    loadingCache.set(src, promise);
+    promise.then(resolve, reject);
+  });
+}
+
+export function preloadImages(sources) {
+  if (!sources || sources.length === 0) {
+    return Promise.resolve([]);
+  }
+
+  const uniqueSources = [...new Set(sources)];
+  return Promise.all(uniqueSources.map(src => preloadImage(src)));
+}
+
+export function preloadImagesInRange(items, currentIndex, range) {
+  if (!items || items.length === 0 || range < 0) {
+    return;
+  }
+
+  const totalItems = items.length;
+  const imagesToPreload = new Set();
+
+  for (let distance = 1; distance <= range; distance++) {
+    const prevIndex = (currentIndex - distance + totalItems) % totalItems;
+    const nextIndex = (currentIndex + distance) % totalItems;
+
+    const prevImg = items[prevIndex]?.querySelector('img');
+    const nextImg = items[nextIndex]?.querySelector('img');
+
+    if (prevImg && prevImg.src && !prevImg.complete) {
+      imagesToPreload.add(prevImg.src);
+    }
+    if (nextImg && nextImg.src && !nextImg.complete) {
+      imagesToPreload.add(nextImg.src);
+    }
+  }
+
+  if (imagesToPreload.size > 0) {
+    preloadImages([...imagesToPreload]).catch(err => {
+      console.warn('일부 이미지 프리로드 실패:', err);
+    });
+  }
+}

package/types/index.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 {
+  constructor(selector: string | HTMLElement, options?: PeekCarouselOptions);
+
+  get currentIndex(): number;
+  get totalItems(): number;
+  get isAutoRotating(): boolean;
+
+  next(): void;
+  prev(): void;
+  goTo(index: number): void;
+  startAutoRotate(): void;
+  stopAutoRotate(): void;
+  toggleAutoRotate(): void;
+  updateLayoutClass(): void;
+  destroy(): void;
+}