@uniai-fe/uds-primitives 0.3.3 → 0.3.5

package/dist/styles.css

@@ -160,6 +160,19 @@
   --color-surface-strong,
   var(--color-cool-gray-20)
   );
+  --carousel-gap: var(--spacing-gap-5);
+  --carousel-inside-button-offset: var(--spacing-padding-2);
+  --carousel-control-button-size: var(--theme-size-medium-2);
+  --carousel-control-button-active: var(--color-cool-gray-20);
+  --carousel-control-button-disabled: var(--color-cool-gray-85);
+  --carousel-control-button-z-index: 50;
+  --carousel-control-button-padding-inline: var(--spacing-padding-5);
+  --carousel-control-button-gap: var(--spacing-gap-2);
+  --carousel-control-button-label-padding-prev: var(--spacing-padding-7);
+  --carousel-control-button-label-padding-next: var(--spacing-padding-7);
+  --carousel-button-label-color: var(--color-common-100);
+  --carousel-button-label-disabled-color: var(--color-label-neutral);
+  --carousel-button-label-font-size: var(--font-label-medium-size);
   --theme-checkbox-frame-size-medium: 20px;
   --theme-checkbox-frame-size-large: 24px;
   --theme-checkbox-indicator-size-medium: 16px;
@@ -1410,6 +1423,104 @@
 
 
 
+.carousel-container {
+  width: 100%;
+}
+
+.carousel-control {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: var(--carousel-gap);
+}
+.carousel-control[data-button-placement=inside] {
+  position: relative;
+  gap: 0;
+}
+.carousel-control[data-button-placement=inside] .carousel-move-button {
+  position: absolute;
+  top: 50%;
+  transform: translateY(-50%);
+}
+.carousel-control[data-button-placement=inside] .carousel-prev-button {
+  left: var(--carousel-inside-button-offset);
+}
+.carousel-control[data-button-placement=inside] .carousel-next-button {
+  right: var(--carousel-inside-button-offset);
+}
+
+.carousel-viewport {
+  width: 100%;
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-x: auto;
+  overflow-y: hidden;
+  scroll-snap-type: x proximity;
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+.carousel-viewport::-webkit-scrollbar {
+  display: none;
+}
+
+.carousel-track {
+  display: flex;
+  gap: var(--carousel-gap);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  scroll-behavior: smooth;
+}
+.carousel-track > * {
+  flex: 0 0 auto;
+  scroll-snap-align: start;
+}
+
+.carousel-item[data-carousel-focus=true] {
+  z-index: 1;
+}
+
+.carousel-move-button {
+  min-width: var(--carousel-control-button-size);
+  height: var(--carousel-control-button-size);
+  border-radius: calc(var(--carousel-control-button-size) / 2);
+  padding: 0 var(--carousel-control-button-padding-inline);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--carousel-control-button-gap);
+  cursor: pointer;
+  background: var(--carousel-control-button-active);
+  z-index: var(--carousel-control-button-z-index);
+}
+.carousel-move-button:disabled {
+  cursor: default;
+  background: var(--carousel-control-button-disabled);
+}
+.carousel-move-button:disabled .carousel-button-label {
+  color: var(--carousel-button-label-disabled-color);
+}
+.carousel-move-button.label-padding-prev {
+  padding-right: var(--carousel-control-button-label-padding-prev);
+}
+.carousel-move-button.label-padding-next {
+  padding-left: var(--carousel-control-button-label-padding-next);
+}
+
+.carousel-move-button-icon {
+  display: flex;
+  margin: 0;
+}
+
+.carousel-button-label {
+  font-size: var(--carousel-button-label-font-size);
+  font-weight: 400;
+  line-height: 1em;
+  color: var(--carousel-button-label-color);
+}
+
+
+
 .checkbox {
   display: inline-flex;
   align-items: center;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,

package/src/components/carousel/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useCarousel } from "../markup/Provider";
+export { useCarouselProviderController } from "./useContext";

package/src/components/carousel/hooks/useContext.ts

@@ -0,0 +1,565 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import type {
+  CarouselContextValue,
+  CarouselProviderControllerParams,
+} from "../types";
+import { normalizePositiveInteger, resolveIndexFromScrollLeft } from "../utils";
+
+/**
+ * Hook 내부 처리 파이프라인
+ * 1) ref/state 준비
+ * 2) count/edge/index 계산 함수 준비
+ * 3) Prev/Next 이동 함수 준비
+ * 4) scroll 이벤트 동기화 effect 등록
+ * 5) 외부 콜백/정리 effect 등록
+ * 6) context value를 memo로 반환
+ *
+ * 아래 코드는 이 1~6 순서를 강제적으로 유지해서,
+ * 디버깅할 때 "어디를 먼저 봐야 하는지"를 눈에 바로 들어오게 만든다.
+ */
+
+/**
+ * 자동 visibleCount 계산이 불가능할 때 사용할 최소 슬롯 수
+ * - 0 슬롯을 허용하면 maxIndex 계산과 이동 계산이 붕괴되므로 1을 유지한다.
+ */
+const DEFAULT_VISIBLE_COUNT = 1;
+/**
+ * 버튼 이동량 기본값
+ * - count가 없거나 비정상이어도 최소 1 page는 이동 가능하도록 보정한다.
+ */
+const DEFAULT_BUTTON_MOVE_COUNT = 1;
+/**
+ * smooth scroll 이후 programmatic 잠금 해제 대기 시간
+ * - 브라우저별 scroll 이벤트 지연/잔진동을 흡수하기 위한 완충 시간이다.
+ */
+const SCROLL_SETTLE_MS = 240;
+
+/**
+ * Carousel Hook; Provider 제어 로직 통합 Hook
+ * @hook
+ * @param {CarouselProviderControllerParams} params Provider 제어 파라미터
+ * @param {number} [params.buttonMoveCount] Prev/Next 기본 viewport page 이동 개수
+ * @param {number} [params.visibleCount] viewport 내 표시 item 개수 고정값
+ * @param {(index: number) => void} [params.onIndexChange] 현재 index 변경 콜백
+ * @returns {CarouselContextValue} Carousel context에 주입할 제어 상태/핸들러 묶음
+ * @example
+ * const contextValue = useCarouselProviderController({
+ *   buttonMoveCount: 1,
+ *   visibleCount: undefined,
+ *   onIndexChange: index => console.log(index),
+ * });
+ */
+export const useCarouselProviderController = ({
+  buttonMoveCount,
+  visibleCount: fixedVisibleCount,
+  onIndexChange,
+}: CarouselProviderControllerParams): CarouselContextValue => {
+  /**
+   * ---------------------------------------------------------------------------
+   * [Section 1] DOM Ref 계층
+   * ---------------------------------------------------------------------------
+   * - viewportRef: scroll 좌표의 source of truth
+   * - trackRef: panel 좌표(offsetLeft) 계산 source
+   * - scrollSettleTimer: smooth scroll settle 타이밍 제어
+   * - isProgrammaticScroll: 사용자/코드 주도 스크롤 분기
+   * - scrollFrame: scroll 이벤트 RAF 압축 제어
+   * ---------------------------------------------------------------------------
+   */
+  /**
+   * viewport: 실제 스크롤 좌표를 읽고/쓰기 하는 기준 요소
+   */
+  const viewportRef = useRef<HTMLDivElement | null>(null);
+  /**
+   * track: panel(li) 집합. panel offsetLeft를 읽어 index를 계산한다.
+   */
+  const trackRef = useRef<HTMLUListElement | null>(null);
+  /**
+   * programmatic 이동 종료 타이머 id
+   */
+  const scrollSettleTimer = useRef<number | null>(null);
+  /**
+   * 코드 주도 스크롤 여부 플래그
+   * - true면 scroll 핸들러에서 사용자 스크롤 계산을 잠시 중단한다.
+   */
+  const isProgrammaticScroll = useRef(false);
+  /**
+   * scroll 이벤트 RAF 압축용 id
+   */
+  const scrollFrame = useRef<number | null>(null);
+
+  /**
+   * ---------------------------------------------------------------------------
+   * [Section 2] 상태 계층
+   * ---------------------------------------------------------------------------
+   * - itemCount: Track에서 보고한 panel 개수
+   * - visibleCount: 현재 viewport에 동시 표시 가능한 슬롯
+   * - currentIndex: scroll 좌표를 기반으로 계산된 현재 index
+   * - focusIndex: 사용자가 선택한 의도 상태 index
+   * - isScrollAtStart/End: 버튼 disabled 계산용 edge 상태
+   * ---------------------------------------------------------------------------
+   */
+  /**
+   * Track에서 등록된 panel 개수
+   */
+  const [itemCount, setItemCount] = useState(0);
+  /**
+   * viewport에 동시에 표시되는 panel 슬롯 수
+   */
+  const [visibleCount, setVisibleCount] = useState(
+    normalizePositiveInteger(fixedVisibleCount, DEFAULT_VISIBLE_COUNT),
+  );
+  /**
+   * viewport 좌측 edge 기준 현재 index
+   */
+  const [currentIndex, setCurrentIndex] = useState(0);
+  /**
+   * 사용자 선택(focus/selected) 상태 index
+   * - scroll index와 분리해서 마지막 아이템 선택 무결성을 유지한다.
+   */
+  const [focusIndex, setFocusIndexState] = useState(0);
+  /**
+   * scroll 시작 edge 도달 여부
+   */
+  const [isScrollAtStart, setIsScrollAtStart] = useState(true);
+  /**
+   * scroll 끝 edge 도달 여부
+   */
+  const [isScrollAtEnd, setIsScrollAtEnd] = useState(false);
+
+  /**
+   * ---------------------------------------------------------------------------
+   * [Section 3] 파생값 계층
+   * ---------------------------------------------------------------------------
+   * maxIndex:
+   * - "이론상 마지막 item index"가 아니라
+   * - "좌측 정렬 가능한 마지막 index"를 의미한다.
+   *
+   * defaultMoveCount:
+   * - 외부 입력(buttonMoveCount)을 안전한 양의 정수로 보정한 값
+   * - onPrev/onNext 기본 호출 경로에서 사용한다.
+   * ---------------------------------------------------------------------------
+   */
+  /**
+   * 이동 가능한 마지막 index
+   * - visibleCount를 반영한 scroll 가능 범위의 상한이다.
+   */
+  const maxIndex = useMemo(
+    () => Math.max(itemCount - visibleCount, 0),
+    [itemCount, visibleCount],
+  );
+
+  /**
+   * Provider에서 주입된 buttonMoveCount를 안전한 양의 정수로 보정한다.
+   */
+  const defaultMoveCount = useMemo(
+    () => normalizePositiveInteger(buttonMoveCount, DEFAULT_BUTTON_MOVE_COUNT),
+    [buttonMoveCount],
+  );
+
+  /**
+   * ---------------------------------------------------------------------------
+   * [Section 4] 등록/계산 함수 계층
+   * ---------------------------------------------------------------------------
+   * registerItemCount:
+   * - Track에서 계산한 child count를 Provider state로 전달한다.
+   * - item 수가 줄면 currentIndex를 즉시 clamp한다.
+   *
+   * updateVisibleCount:
+   * - fixedVisibleCount가 있으면 해당 값 우선
+   * - 없으면 viewport/panel 폭으로 슬롯 자동 계산
+   * - 계산 실패 시 DEFAULT_VISIBLE_COUNT로 안전 복귀
+   * ---------------------------------------------------------------------------
+   */
+  // Track 렌더 수를 context state로 동기화한다.
+  const registerItemCount = useCallback(
+    (count: number) => {
+      // count는 외부 입력이므로 항상 정수/0 이상으로 정규화한다.
+      const normalizedCount = Math.max(0, Math.floor(count));
+      setItemCount(normalizedCount);
+      // 현재 index가 새로운 범위를 벗어나면 즉시 범위 내로 축소한다.
+      setCurrentIndex(previousIndex =>
+        Math.min(previousIndex, Math.max(normalizedCount - visibleCount, 0)),
+      );
+    },
+    [visibleCount],
+  );
+
+  // visibleCount를 fixed 우선, 자동 계산 보조 순서로 갱신한다.
+  const updateVisibleCount = useCallback(() => {
+    // fixed 모드 여부와 무관하게 먼저 안전한 정수로 보정한다.
+    const normalizedFixedVisibleCount = normalizePositiveInteger(
+      fixedVisibleCount,
+      DEFAULT_VISIBLE_COUNT,
+    );
+
+    // [Case A] 외부 fixedVisibleCount가 있으면 자동 계산을 건너뛴다.
+    if (typeof fixedVisibleCount === "number") {
+      setVisibleCount(normalizedFixedVisibleCount);
+      setCurrentIndex(previousIndex =>
+        Math.min(
+          previousIndex,
+          Math.max(itemCount - normalizedFixedVisibleCount, 0),
+        ),
+      );
+      return;
+    }
+
+    // [Case B] 자동 계산에 필요한 ref/children이 준비되지 않았으면 기본값으로 복귀한다.
+    if (!viewportRef.current || !trackRef.current?.children.length) {
+      setVisibleCount(DEFAULT_VISIBLE_COUNT);
+      return;
+    }
+
+    const firstPanel = trackRef.current.children[0] as HTMLElement;
+    const secondPanel = trackRef.current.children[1] as HTMLElement | undefined;
+    const viewportWidth = viewportRef.current.clientWidth;
+    const panelWidth = secondPanel
+      ? secondPanel.offsetLeft - firstPanel.offsetLeft
+      : firstPanel.getBoundingClientRect().width;
+
+    // [Guard] panel width가 비정상일 경우 계산을 포기한다.
+    if (panelWidth <= 0) {
+      setVisibleCount(DEFAULT_VISIBLE_COUNT);
+      return;
+    }
+
+    // [Case C] 자동 계산 성공: floor(viewport/panel)로 표시 슬롯 수를 계산한다.
+    const slots = Math.max(Math.floor(viewportWidth / panelWidth), 1);
+    setVisibleCount(slots);
+    setCurrentIndex(previousIndex =>
+      Math.min(previousIndex, Math.max(itemCount - slots, 0)),
+    );
+  }, [fixedVisibleCount, itemCount]);
+
+  useEffect(() => {
+    // item 수/폭 조건 변화 시 visibleCount를 재계산한다.
+    updateVisibleCount();
+  }, [updateVisibleCount, itemCount]);
+
+  useEffect(() => {
+    /**
+     * ResizeObserver effect
+     * - viewport width가 바뀌면 visibleCount를 재계산한다.
+     * - SSR/legacy 보호: ResizeObserver 미지원 환경은 조용히 건너뛴다.
+     */
+    // viewport 리사이즈를 감시해 visibleCount를 동기화한다.
+    if (!viewportRef.current || typeof ResizeObserver === "undefined") {
+      return;
+    }
+
+    const observer = new ResizeObserver(() => {
+      updateVisibleCount();
+    });
+
+    observer.observe(viewportRef.current);
+    return () => observer.disconnect();
+  }, [updateVisibleCount]);
+
+  const clampIndex = useCallback(
+    (index: number) => Math.max(0, Math.min(index, maxIndex)),
+    [maxIndex],
+  );
+
+  /**
+   * clampFocusIndex가 clampIndex와 분리된 이유
+   * - clampIndex는 "scroll 가능한 좌측 anchor 범위(maxIndex)"를 따른다.
+   * - clampFocusIndex는 "선택 가능한 item 범위(itemCount-1)"를 따른다.
+   * - 즉, 같은 index라도 clamp 목적이 다르므로 함수를 분리한다.
+   */
+  // focus는 선택 상태이므로 itemCount-1까지 허용한다.
+  const clampFocusIndex = useCallback(
+    (index: number) => Math.max(0, Math.min(index, Math.max(itemCount - 1, 0))),
+    [itemCount],
+  );
+
+  // Prev/Next disabled 상태를 실제 scroll edge 기준으로 계산한다.
+  const syncScrollEdgeState = useCallback(() => {
+    // edge 계산은 viewport scroll 좌표를 단일 source로 삼는다.
+    const viewport = viewportRef.current;
+    if (!viewport) {
+      return;
+    }
+
+    const maxScrollLeft = Math.max(
+      viewport.scrollWidth - viewport.clientWidth,
+      0,
+    );
+    // 1px 허용오차로 sub-pixel 오차를 흡수한다.
+    setIsScrollAtStart(viewport.scrollLeft <= 1);
+    setIsScrollAtEnd(viewport.scrollLeft >= maxScrollLeft - 1);
+  }, []);
+
+  const scrollToIndex = useCallback(
+    (index: number) => {
+      // moveTo(index) 호출 시 panel anchor로 정밀 이동한다.
+      if (!viewportRef.current || !trackRef.current) {
+        return;
+      }
+
+      const panel = trackRef.current.children[index] as HTMLElement | undefined;
+      if (!panel) {
+        return;
+      }
+
+      const targetLeft = panel.offsetLeft;
+      const currentLeft = viewportRef.current.scrollLeft;
+
+      // 목표 지점과 현재 지점이 거의 같으면 scroll 호출을 생략한다.
+      if (Math.abs(currentLeft - targetLeft) < 1) {
+        setCurrentIndex(index);
+        return;
+      }
+
+      // programmatic 이동 시작
+      isProgrammaticScroll.current = true;
+      viewportRef.current.scrollTo({
+        left: targetLeft,
+        behavior: "smooth",
+      });
+
+      setCurrentIndex(index);
+
+      if (scrollSettleTimer.current) {
+        window.clearTimeout(scrollSettleTimer.current);
+      }
+
+      scrollSettleTimer.current = window.setTimeout(() => {
+        // 이동 settle 이후 사용자 스크롤 계산 경로를 다시 연다.
+        isProgrammaticScroll.current = false;
+        syncScrollEdgeState();
+      }, SCROLL_SETTLE_MS);
+    },
+    [syncScrollEdgeState],
+  );
+
+  const moveTo = useCallback(
+    (index: number) => {
+      // focus는 의도 상태, current는 scroll 상태로 분리해서 갱신한다.
+      // 1) focusIndex 먼저 반영
+      // 2) scroll anchor index로 clamp
+      // 3) 실제 스크롤 실행
+      const nextIndex = clampIndex(index);
+      const nextFocusIndex = clampFocusIndex(index);
+      setFocusIndexState(nextFocusIndex);
+      if (nextIndex === currentIndex) {
+        return;
+      }
+      scrollToIndex(nextIndex);
+    },
+    [clampFocusIndex, clampIndex, currentIndex, scrollToIndex],
+  );
+
+  const moveByViewport = useCallback(
+    (count: number) => {
+      // Prev/Next는 item 단위가 아닌 viewport width(page) 단위 이동을 사용한다.
+      const viewport = viewportRef.current;
+      if (!viewport) {
+        return;
+      }
+
+      const normalizedCount = normalizePositiveInteger(
+        Math.abs(count),
+        DEFAULT_BUTTON_MOVE_COUNT,
+      );
+      const direction = count >= 0 ? 1 : -1;
+      // delta = viewport width * 이동 페이지 수 * 방향
+      const delta = viewport.clientWidth * normalizedCount * direction;
+      const maxScrollLeft = Math.max(
+        viewport.scrollWidth - viewport.clientWidth,
+        0,
+      );
+      const targetScrollLeft = Math.min(
+        Math.max(viewport.scrollLeft + delta, 0),
+        maxScrollLeft,
+      );
+
+      // 실제 이동량이 0이면 좌표는 그대로, edge 상태만 최신화한다.
+      if (Math.abs(targetScrollLeft - viewport.scrollLeft) < 1) {
+        syncScrollEdgeState();
+        return;
+      }
+
+      isProgrammaticScroll.current = true;
+      viewport.scrollTo({
+        left: targetScrollLeft,
+        behavior: "smooth",
+      });
+
+      const panels = trackRef.current?.children;
+      if (panels && panels.length) {
+        // 목표 scrollLeft 기준 index를 선반영해 상태 표시 지연을 줄인다.
+        const resolvedIndex = resolveIndexFromScrollLeft({
+          panels,
+          scrollLeft: targetScrollLeft,
+          maxIndex,
+        });
+        setCurrentIndex(resolvedIndex);
+      }
+
+      if (scrollSettleTimer.current) {
+        window.clearTimeout(scrollSettleTimer.current);
+      }
+      scrollSettleTimer.current = window.setTimeout(() => {
+        // settle 타이머 종료 시 사용자 스크롤 계산 경로를 다시 연다.
+        isProgrammaticScroll.current = false;
+        syncScrollEdgeState();
+      }, SCROLL_SETTLE_MS);
+    },
+    [maxIndex, syncScrollEdgeState],
+  );
+
+  const onPrevBy = useCallback(
+    (count: number) => {
+      // count는 항상 양수 정수로 보정한 뒤 음수 방향으로 이동한다.
+      const normalizedCount = normalizePositiveInteger(count, 1);
+      moveByViewport(-normalizedCount);
+    },
+    [moveByViewport],
+  );
+
+  const onNextBy = useCallback(
+    (count: number) => {
+      // count는 항상 양수 정수로 보정한 뒤 양수 방향으로 이동한다.
+      const normalizedCount = normalizePositiveInteger(count, 1);
+      moveByViewport(normalizedCount);
+    },
+    [moveByViewport],
+  );
+
+  const onPrev = useCallback(() => {
+    // Provider 기본 이동량 기반 이전 이동
+    onPrevBy(defaultMoveCount);
+  }, [defaultMoveCount, onPrevBy]);
+
+  const onNext = useCallback(() => {
+    // Provider 기본 이동량 기반 다음 이동
+    onNextBy(defaultMoveCount);
+  }, [defaultMoveCount, onNextBy]);
+
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport) {
+      return;
+    }
+
+    /**
+     * scroll 핸들러 설계 의도
+     * 1) edge 상태는 매 이벤트에서 즉시 반영
+     * 2) programmatic 이동 중이면 사용자 index 계산 중단
+     * 3) RAF로 최종 좌표를 읽어 currentIndex를 1회 업데이트
+     */
+    const handleScroll = () => {
+      // 매 scroll마다 edge를 우선 계산해 disabled 정합성을 유지한다.
+      syncScrollEdgeState();
+
+      if (isProgrammaticScroll.current || !trackRef.current) {
+        return;
+      }
+
+      if (scrollFrame.current) {
+        // 이전 프레임 예약이 있으면 취소하고 마지막 이벤트만 반영한다.
+        cancelAnimationFrame(scrollFrame.current);
+      }
+
+      scrollFrame.current = requestAnimationFrame(() => {
+        // RAF 타이밍의 최종 scrollLeft를 기준으로 index를 계산한다.
+        const { scrollLeft } = viewport;
+        const panels = trackRef.current?.children;
+
+        if (!panels || !panels.length) {
+          return;
+        }
+        const resolvedIndex = resolveIndexFromScrollLeft({
+          panels,
+          scrollLeft,
+          maxIndex,
+        });
+        setCurrentIndex(previousIndex =>
+          // 불필요 렌더를 피하기 위해 동일값 업데이트는 생략한다.
+          previousIndex === resolvedIndex ? previousIndex : resolvedIndex,
+        );
+      });
+    };
+
+    viewport.addEventListener("scroll", handleScroll, { passive: true });
+
+    return () => {
+      viewport.removeEventListener("scroll", handleScroll);
+      if (scrollFrame.current) {
+        cancelAnimationFrame(scrollFrame.current);
+        scrollFrame.current = null;
+      }
+    };
+  }, [maxIndex, syncScrollEdgeState]);
+
+  useEffect(() => {
+    // 외부 동기화 콜백(onIndexChange) 전달
+    if (typeof onIndexChange === "function") {
+      onIndexChange(currentIndex);
+    }
+  }, [currentIndex, onIndexChange]);
+
+  useEffect(() => {
+    // 아이템 수 감소 시 focusIndex 범위를 보정한다.
+    setFocusIndexState(previousFocusIndex =>
+      Math.min(previousFocusIndex, Math.max(itemCount - 1, 0)),
+    );
+  }, [itemCount]);
+
+  useEffect(() => {
+    // 상태 변화마다 edge를 재평가해 버튼 disabled 오차를 줄인다.
+    syncScrollEdgeState();
+  }, [currentIndex, itemCount, syncScrollEdgeState, visibleCount]);
+
+  useEffect(() => {
+    // 언마운트 시 타이머를 정리한다.
+    return () => {
+      if (scrollSettleTimer.current) {
+        window.clearTimeout(scrollSettleTimer.current);
+      }
+    };
+  }, []);
+
+  return useMemo<CarouselContextValue>(
+    () => ({
+      // Provider가 필요한 모든 상태/핸들러를 단일 객체로 제공한다.
+      viewportRef,
+      trackRef,
+      onPrev,
+      onNext,
+      onPrevBy,
+      onNextBy,
+      moveBy: moveByViewport,
+      moveTo,
+      registerItemCount,
+      itemCount,
+      visibleCount,
+      currentIndex,
+      focusIndex,
+      maxIndex,
+      isReachStart: isScrollAtStart,
+      isReachEnd: isScrollAtEnd,
+    }),
+    [
+      // 아래 dependency 배열은 "상태 묶음 객체의 재생성 기준"을 명확히 고정한다.
+      // - 핸들러 레퍼런스와 상태값이 바뀌는 경우에만 contextValue를 갱신한다.
+      currentIndex,
+      itemCount,
+      isScrollAtEnd,
+      isScrollAtStart,
+      maxIndex,
+      moveByViewport,
+      moveTo,
+      onNext,
+      onNextBy,
+      onPrev,
+      onPrevBy,
+      focusIndex,
+      registerItemCount,
+      visibleCount,
+    ],
+  );
+};

package/src/components/carousel/img/chevron-left.svg

@@ -0,0 +1,3 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M15 4L7 12L15 20" stroke="white" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>