aplance-ui 1.1.1 → 1.2.0

package/registry/components/primitives/slider/slider.tsx

@@ -0,0 +1,1174 @@
+import {
+  Children,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type PointerEvent as ReactPointerEvent,
+  type ReactNode,
+  type TransitionEvent as ReactTransitionEvent,
+  type WheelEvent as ReactWheelEvent,
+} from "react";
+import clsx from "clsx";
+import { IconChevronLeft, IconChevronRight } from "@tabler/icons-react";
+import { useResizeObserver } from "../../../hooks/useResizeObserver";
+import { SliderContext, useSlider, type SliderApi } from "./slider-context";
+import type {
+  SliderAutoplayOptions,
+  SliderNavigationOptions,
+  SliderPaginationOptions,
+  SliderPaginationType,
+  SliderProps,
+  SliderSlideState,
+} from "./types";
+import {
+  clamp,
+  getSnapMax,
+  normalizeIndex,
+  resolveResponsive,
+  shouldIgnoreDrag,
+  wrap,
+} from "./utils";
+import s from "./slider.module.css";
+
+export {
+  sliderAlignments,
+  sliderEffects,
+  sliderPaginationTypes,
+} from "./types";
+export type {
+  SliderAlign,
+  SliderAutoplayOptions,
+  SliderEffect,
+  SliderHandle,
+  SliderNavigationOptions,
+  SliderPaginationOptions,
+  SliderPaginationType,
+  SliderProps,
+  SliderResponsive,
+  SliderResponsiveOptions,
+  SliderSlideState,
+  SliderSlidesPerView,
+} from "./types";
+
+// ─── Slider ───────────────────────────────────────────────────────────────────
+
+export const Slider = ({
+  children,
+  className,
+  style,
+  ref,
+  ariaLabel = "Slider",
+  effect: effectProp = "slide",
+  align: alignProp = "start",
+  centered: centeredProp = false,
+  slidesPerView: slidesPerViewProp = 1,
+  slidesPerGroup: slidesPerGroupProp = 1,
+  spaceBetween: spaceBetweenProp = 0,
+  responsive,
+  index: controlledIndex,
+  defaultIndex = 0,
+  onIndexChange,
+  onSlideChange,
+  loop = false,
+  rewind = false,
+  speed = 500,
+  easing = "cubic-bezier(0.4, 0, 0.2, 1)",
+  draggable = true,
+  swipeThreshold = 30,
+  dragIgnoreSelector = "a, button, input, textarea, select, summary, [role='button'], [data-slider-no-drag]",
+  keyboard = false,
+  mousewheel = false,
+  autoHeight = false,
+  autoplay = false,
+  pauseOnHover = true,
+  navigation = false,
+  pagination = false,
+  renderControls,
+  renderSlide,
+  onKeyDown,
+  onWheel,
+  onMouseEnter,
+  onMouseLeave,
+  onFocus,
+  onBlur,
+  ...rest
+}: SliderProps) => {
+  const uid = useId();
+  const slides = useMemo(
+    () =>
+      Children.toArray(children).filter(
+        (child) => child !== null && child !== undefined,
+      ),
+    [children],
+  );
+  const count = slides.length;
+
+  // ─── Measurement ────────────────────────────────────────────────────────────
+  // We read real `offsetLeft`/`offsetWidth` per slide instead of computing from
+  // `slidesPerView`/`spaceBetween` alone. This keeps `auto` widths, subpixel
+  // gaps, and `align=center` math accurate even when slide content changes.
+
+  const viewportRef = useRef<HTMLDivElement>(null);
+  const trackRef = useRef<HTMLDivElement>(null);
+  const slideRefs = useRef<Array<HTMLDivElement | null>>([]);
+  const [viewportWidth, setViewportWidth] = useState(0);
+  const [slideOffsets, setSlideOffsets] = useState<number[]>([]);
+  const [slideSizes, setSlideSizes] = useState<number[]>([]);
+  const [trackWidth, setTrackWidth] = useState(0);
+  const [hasMeasured, setHasMeasured] = useState(false);
+  const [isMotionReady, setIsMotionReady] = useState(false);
+  const [activeHeight, setActiveHeight] = useState<number | undefined>();
+
+  const measure = useCallback(() => {
+    const viewport = viewportRef.current;
+    const track = trackRef.current;
+    if (!viewport || !track) return;
+
+    setViewportWidth(viewport.clientWidth);
+    const offsets = slideRefs.current.map((node) => node?.offsetLeft ?? 0);
+    const sizes = slideRefs.current.map((node) => node?.offsetWidth ?? 0);
+    setSlideOffsets(offsets);
+    setSlideSizes(sizes);
+    setTrackWidth(track.scrollWidth);
+    setHasMeasured(true);
+
+    if (autoHeight) {
+      const activeNode = slideRefs.current.find(
+        (node) => node?.dataset.active === "true",
+      );
+      setActiveHeight(activeNode?.offsetHeight);
+    }
+  }, [autoHeight]);
+
+  useLayoutEffect(() => {
+    measure();
+  }, [measure]);
+  useResizeObserver(viewportRef, measure);
+  useResizeObserver(trackRef, measure);
+
+  // ─── Responsive resolution ──────────────────────────────────────────────────
+
+  const responsiveOptions = useMemo(
+    () =>
+      resolveResponsive(
+        viewportWidth,
+        {
+          slidesPerView: slidesPerViewProp,
+          slidesPerGroup: slidesPerGroupProp,
+          spaceBetween: spaceBetweenProp,
+          centered: centeredProp,
+          align: alignProp,
+          effect: effectProp,
+        },
+        responsive,
+      ),
+    [
+      alignProp,
+      centeredProp,
+      effectProp,
+      responsive,
+      slidesPerGroupProp,
+      slidesPerViewProp,
+      spaceBetweenProp,
+      viewportWidth,
+    ],
+  );
+
+  const slidesPerView =
+    responsiveOptions.slidesPerView === "auto"
+      ? "auto"
+      : Number.isFinite(responsiveOptions.slidesPerView)
+        ? Math.max(1, responsiveOptions.slidesPerView)
+        : 1;
+  const slidesPerGroup = Number.isFinite(responsiveOptions.slidesPerGroup)
+    ? Math.max(1, Math.floor(responsiveOptions.slidesPerGroup))
+    : 1;
+  const spaceBetween = Number.isFinite(responsiveOptions.spaceBetween)
+    ? Math.max(0, responsiveOptions.spaceBetween)
+    : 0;
+  const transitionDuration = Number.isFinite(speed) ? Math.max(0, speed) : 500;
+  const resolvedSwipeThreshold = Number.isFinite(swipeThreshold)
+    ? Math.max(1, swipeThreshold)
+    : 30;
+  const align = responsiveOptions.centered ? "center" : responsiveOptions.align;
+  const effect = responsiveOptions.effect;
+  const effectMode = effect;
+  const canLoop = loop && count > 1 && effectMode === "slide";
+  const baseMaxIndex =
+    effectMode === "slide" ? getSnapMax(count, slidesPerView) : Math.max(0, count - 1);
+  const maxIndex = useMemo(() => {
+    if (
+      canLoop ||
+      effectMode !== "slide" ||
+      !hasMeasured ||
+      viewportWidth <= 0 ||
+      trackWidth <= viewportWidth ||
+      slideOffsets.length < count
+    ) {
+      return baseMaxIndex;
+    }
+
+    const maxOffset = Math.max(0, trackWidth - viewportWidth);
+    const firstFlushIndex = slideOffsets
+      .slice(0, count)
+      .findIndex((offset) => offset >= maxOffset - 1);
+
+    return firstFlushIndex >= 0
+      ? Math.min(baseMaxIndex, firstFlushIndex)
+      : baseMaxIndex;
+  }, [
+    baseMaxIndex,
+    canLoop,
+    count,
+    effectMode,
+    hasMeasured,
+    slideOffsets,
+    trackWidth,
+    viewportWidth,
+  ]);
+  const snapCount = canLoop ? count : maxIndex + 1;
+
+  // ─── Index + clone bookkeeping ──────────────────────────────────────────────
+
+  const isControlled = controlledIndex !== undefined;
+
+  const [internalIndex, setInternalIndex] = useState(() =>
+    normalizeIndex(defaultIndex, count, maxIndex, loop),
+  );
+  const logicalIndex = normalizeIndex(
+    isControlled ? controlledIndex : internalIndex,
+    count,
+    maxIndex,
+    loop,
+  );
+
+  useEffect(() => {
+    if (!isControlled) {
+      setInternalIndex((current) => normalizeIndex(current, count, maxIndex, loop));
+    }
+  }, [count, isControlled, loop, maxIndex]);
+
+  // Clone N slides on each side so dragging/grouping past the edge always
+  // has real DOM under the cursor. `+1` is a buffer for partial-view layouts;
+  // `slidesPerView=auto` is unknowable up-front so we clone the full set.
+  const cloneCount = canLoop
+    ? slidesPerView === "auto"
+      ? count
+      : Math.min(
+          count,
+          Math.max(Math.ceil(slidesPerView), slidesPerGroup) + 1,
+        )
+    : 0;
+
+  const renderedSlides = useMemo(() => {
+    if (effectMode !== "slide" || cloneCount === 0) return slides;
+    return [
+      ...slides.slice(-cloneCount),
+      ...slides,
+      ...slides.slice(0, cloneCount),
+    ];
+  }, [cloneCount, effectMode, slides]);
+
+  useEffect(() => {
+    slideRefs.current.length = renderedSlides.length;
+  }, [renderedSlides.length]);
+
+  // ─── Visual state + drag refs ───────────────────────────────────────────────
+  // `visualIndex` is the position inside `renderedSlides` (includes clones);
+  // `logicalIndex` is what the parent sees (0..count-1). They diverge during
+  // loop wraparound and re-sync on the next snap-back.
+
+  const [visualIndex, setVisualIndex] = useState(() => cloneCount + logicalIndex);
+  const [transitionOff, setTransitionOff] = useState(false);
+  const [isAnimating, setIsAnimating] = useState(false);
+  const [dragOffset, setDragOffset] = useState(0);
+  const [isDragging, setIsDragging] = useState(false);
+  const [isHovering, setIsHovering] = useState(false);
+  const [isFocusWithin, setIsFocusWithin] = useState(false);
+  const [autoplayStopped, setAutoplayStopped] = useState(false);
+  const wheelLockRef = useRef(false);
+  const layoutSignatureRef = useRef("");
+  const dragStartRef = useRef<{
+    x: number;
+    y: number;
+    visualIndex: number;
+    logicalIndex: number;
+  } | null>(null);
+  const verticalLockRef = useRef(false);
+  const layoutSignature = [
+    align,
+    cloneCount,
+    effectMode,
+    renderedSlides.length,
+    slidesPerGroup,
+    slidesPerView,
+    spaceBetween,
+    viewportWidth,
+  ].join("|");
+
+  // When layout shape changes (responsive breakpoint flip, count change,
+  // align swap), drop transitions for the snap-into-place, then re-enable.
+  useLayoutEffect(() => {
+    if (layoutSignatureRef.current === layoutSignature) return;
+    layoutSignatureRef.current = layoutSignature;
+    setIsMotionReady(false);
+    setVisualIndex(cloneCount + logicalIndex);
+    measure();
+  }, [
+    cloneCount,
+    layoutSignature,
+    logicalIndex,
+    measure,
+  ]);
+
+  // Two rAFs: frame 1 commits the no-transition translate; frame 2 re-enables
+  // the transition so the NEXT user action animates from the settled state.
+  useEffect(() => {
+    if (!hasMeasured) return;
+    let secondFrame = 0;
+    const firstFrame = requestAnimationFrame(() => {
+      secondFrame = requestAnimationFrame(() => {
+        setIsMotionReady(true);
+      });
+    });
+
+    return () => {
+      cancelAnimationFrame(firstFrame);
+      cancelAnimationFrame(secondFrame);
+    };
+  }, [
+    hasMeasured,
+    layoutSignature,
+  ]);
+
+  // ─── Geometry ───────────────────────────────────────────────────────────────
+
+  const averageStride = useMemo(() => {
+    if (slideOffsets.length > 1) {
+      const diffs = slideOffsets
+        .slice(1)
+        .map((offset, index) => offset - slideOffsets[index])
+        .filter((value) => value > 0);
+      if (diffs.length > 0) {
+        return diffs.reduce((sum, value) => sum + value, 0) / diffs.length;
+      }
+    }
+
+    if (slidesPerView !== "auto" && viewportWidth > 0) {
+      return Math.max(
+        1,
+        (viewportWidth - (slidesPerView - 1) * spaceBetween) / slidesPerView +
+          spaceBetween,
+      );
+    }
+
+    return 1;
+  }, [slideOffsets, slidesPerView, spaceBetween, viewportWidth]);
+
+  const alignmentOffset = useMemo(() => {
+    if (effectMode !== "slide" || viewportWidth <= 0) return 0;
+    const width = slideSizes[visualIndex] ?? averageStride - spaceBetween;
+    if (align === "center") return Math.max(0, (viewportWidth - width) / 2);
+    if (align === "end") return Math.max(0, viewportWidth - width);
+    return 0;
+  }, [align, averageStride, effectMode, slideSizes, spaceBetween, viewportWidth, visualIndex]);
+
+  const baseOffset = effectMode === "slide" ? slideOffsets[visualIndex] ?? visualIndex * averageStride : 0;
+  const maxScroll = Math.max(0, trackWidth - viewportWidth);
+  const targetOffset =
+    effectMode === "slide" && !canLoop
+      ? clamp(baseOffset - alignmentOffset, 0, maxScroll)
+      : baseOffset - alignmentOffset;
+  const translate = -targetOffset + dragOffset;
+  const progress = snapCount <= 1 ? 1 : clamp(logicalIndex / (snapCount - 1), 0, 1);
+  const canNavigateLoop = loop && count > 1;
+  const isFirst = !canNavigateLoop && logicalIndex <= 0;
+  const isLast = !canNavigateLoop && logicalIndex >= maxIndex;
+  const autoplayOptions = useMemo<Required<SliderAutoplayOptions> | null>(
+    () => {
+      if (!autoplay) return null;
+
+      const options = typeof autoplay === "object" ? autoplay : {};
+      return {
+        delay:
+          typeof options.delay === "number" && Number.isFinite(options.delay)
+            ? Math.max(0, options.delay)
+            : 4000,
+        pauseOnHover: options.pauseOnHover ?? true,
+        pauseOnFocus: options.pauseOnFocus ?? true,
+        stopOnInteraction: options.stopOnInteraction ?? false,
+        reverseDirection: options.reverseDirection ?? false,
+      };
+    },
+    [autoplay],
+  );
+  const isAutoplayPaused =
+    Boolean(autoplayOptions) &&
+    ((autoplayOptions?.pauseOnHover && pauseOnHover && isHovering) ||
+      (autoplayOptions?.pauseOnFocus && isFocusWithin) ||
+      isDragging);
+
+  // ─── Imperative actions ─────────────────────────────────────────────────────
+
+  // Single setter for index + visual cursor. Skipping the change callbacks when
+  // the index doesn't actually move avoids spamming controlled parents during
+  // settle / clone snap-back.
+  const commitIndex = useCallback(
+    (nextIndex: number, nextVisualIndex?: number, animated = true) => {
+      if (count === 0) return;
+      const normalized = normalizeIndex(nextIndex, count, maxIndex, loop);
+      if (!isControlled) setInternalIndex(normalized);
+      if (normalized !== logicalIndex) {
+        onIndexChange?.(normalized);
+        onSlideChange?.(normalized);
+      }
+      setIsAnimating(animated && transitionDuration > 0 && effectMode === "slide");
+      setVisualIndex(nextVisualIndex ?? cloneCount + normalized);
+    },
+    [
+      cloneCount,
+      count,
+      effectMode,
+      isControlled,
+      logicalIndex,
+      loop,
+      maxIndex,
+      onIndexChange,
+      onSlideChange,
+      transitionDuration,
+    ],
+  );
+
+  const stopAutoplay = useCallback(() => {
+    setAutoplayStopped(true);
+  }, []);
+
+  const markInteraction = useCallback(() => {
+    if (autoplayOptions?.stopOnInteraction) {
+      stopAutoplay();
+    }
+  }, [autoplayOptions, stopAutoplay]);
+
+  const resolveStep = useCallback(
+    (steps: number | undefined) => {
+      const step = typeof steps === "number" && Number.isFinite(steps)
+        ? Math.floor(steps)
+        : slidesPerGroup;
+      const maxStep = canLoop && cloneCount > 0
+        ? cloneCount
+        : Number.MAX_SAFE_INTEGER;
+      return Math.min(Math.max(1, step), maxStep);
+    },
+    [canLoop, cloneCount, slidesPerGroup],
+  );
+
+  const next = useCallback(
+    (steps = slidesPerGroup) => {
+      if (count === 0) return;
+      markInteraction();
+      const step = resolveStep(steps);
+      if (!loop && isLast) {
+        if (rewind) commitIndex(0);
+        return;
+      }
+      commitIndex(logicalIndex + step, canLoop ? visualIndex + step : undefined);
+    },
+    [
+      canLoop,
+      commitIndex,
+      count,
+      isLast,
+      logicalIndex,
+      loop,
+      markInteraction,
+      rewind,
+      resolveStep,
+      slidesPerGroup,
+      visualIndex,
+    ],
+  );
+
+  const prev = useCallback(
+    (steps = slidesPerGroup) => {
+      if (count === 0) return;
+      markInteraction();
+      const step = resolveStep(steps);
+      if (!loop && isFirst) {
+        if (rewind) commitIndex(maxIndex);
+        return;
+      }
+      commitIndex(logicalIndex - step, canLoop ? visualIndex - step : undefined);
+    },
+    [
+      canLoop,
+      commitIndex,
+      count,
+      isFirst,
+      logicalIndex,
+      loop,
+      markInteraction,
+      maxIndex,
+      rewind,
+      resolveStep,
+      slidesPerGroup,
+      visualIndex,
+    ],
+  );
+
+  const goTo = useCallback(
+    (index: number) => {
+      if (count === 0) return;
+      markInteraction();
+      const normalized = normalizeIndex(index, count, maxIndex, loop);
+      // In loop mode, prefer the visual candidate closest to the current
+      // position so the track takes the short path instead of unwinding
+      // across the whole strip on a clicked dot.
+      const forwardDistance = wrap(normalized - logicalIndex, count);
+      const backwardDistance = wrap(logicalIndex - normalized, count);
+      let nextVisual = cloneCount + normalized;
+
+      if (canLoop) {
+        const maxRenderedIndex = renderedSlides.length - 1;
+        const candidates = [
+          visualIndex + forwardDistance,
+          visualIndex - backwardDistance,
+          nextVisual,
+        ].filter((candidate) => candidate >= 0 && candidate <= maxRenderedIndex);
+
+        nextVisual = candidates.reduce((best, candidate) =>
+          Math.abs(candidate - visualIndex) < Math.abs(best - visualIndex)
+            ? candidate
+            : best,
+        );
+      }
+
+      commitIndex(normalized, nextVisual);
+    },
+    [
+      canLoop,
+      cloneCount,
+      commitIndex,
+      count,
+      logicalIndex,
+      loop,
+      markInteraction,
+      maxIndex,
+      renderedSlides.length,
+      visualIndex,
+    ],
+  );
+
+  useEffect(() => {
+    if (isDragging || isAnimating) return;
+    setVisualIndex(cloneCount + logicalIndex);
+  }, [cloneCount, isAnimating, isDragging, logicalIndex]);
+
+  // ─── Loop snap + autoplay ───────────────────────────────────────────────────
+
+  // After a transition lands inside clone territory, jump (transition: none)
+  // to the equivalent real slot so wrap-around feels seamless.
+  const snapVisualIndex = useCallback(() => {
+    if (!canLoop || count === 0) return;
+    if (visualIndex < cloneCount) {
+      setTransitionOff(true);
+      setVisualIndex((current) => current + count);
+    } else if (visualIndex >= cloneCount + count) {
+      setTransitionOff(true);
+      setVisualIndex((current) => current - count);
+    }
+  }, [canLoop, cloneCount, count, visualIndex]);
+
+  const handleTrackTransitionEnd = useCallback((event: ReactTransitionEvent<HTMLDivElement>) => {
+    if (event.target !== event.currentTarget || event.propertyName !== "transform") {
+      return;
+    }
+    setIsAnimating(false);
+    snapVisualIndex();
+    measure();
+  }, [measure, snapVisualIndex]);
+
+  useEffect(() => {
+    if (!transitionOff) return;
+    let secondFrame = 0;
+    const firstFrame = requestAnimationFrame(() => {
+      secondFrame = requestAnimationFrame(() => setTransitionOff(false));
+    });
+    return () => {
+      cancelAnimationFrame(firstFrame);
+      cancelAnimationFrame(secondFrame);
+    };
+  }, [transitionOff]);
+
+  useEffect(() => {
+    if (!autoplayOptions || autoplayStopped || count <= 1) return;
+
+    if (autoplayOptions.pauseOnHover && pauseOnHover && isHovering) return;
+    if (autoplayOptions.pauseOnFocus && isFocusWithin) return;
+    if (isDragging || isAnimating) return;
+
+    const id = window.setTimeout(() => {
+      if (autoplayOptions.reverseDirection) prev();
+      else next();
+    }, autoplayOptions.delay);
+
+    return () => window.clearTimeout(id);
+  }, [
+    autoplayOptions,
+    autoplayStopped,
+    count,
+    isAnimating,
+    isDragging,
+    isFocusWithin,
+    isHovering,
+    logicalIndex,
+    next,
+    pauseOnHover,
+    prev,
+  ]);
+
+  // ─── Pointer / keyboard / wheel ─────────────────────────────────────────────
+
+  const handlePointerDown = (event: ReactPointerEvent<HTMLDivElement>) => {
+    if (
+      !draggable ||
+      count <= 1 ||
+      averageStride <= 0 ||
+      shouldIgnoreDrag(event.target, dragIgnoreSelector)
+    ) {
+      return;
+    }
+    if (event.pointerType === "mouse" && event.button !== 0) return;
+
+    markInteraction();
+    dragStartRef.current = {
+      x: event.clientX,
+      y: event.clientY,
+      visualIndex,
+      logicalIndex,
+    };
+    verticalLockRef.current = false;
+    setIsDragging(true);
+    setIsAnimating(false);
+    event.currentTarget.setPointerCapture?.(event.pointerId);
+  };
+
+  const handlePointerMove = (event: ReactPointerEvent<HTMLDivElement>) => {
+    const start = dragStartRef.current;
+    if (!start) return;
+
+    const dx = event.clientX - start.x;
+    const dy = event.clientY - start.y;
+
+    if (event.pointerType !== "mouse" && !verticalLockRef.current) {
+      if (Math.abs(dy) > Math.abs(dx) && Math.abs(dy) > 8) {
+        verticalLockRef.current = true;
+        dragStartRef.current = null;
+        setIsDragging(false);
+        setDragOffset(0);
+        event.currentTarget.releasePointerCapture?.(event.pointerId);
+        return;
+      }
+    }
+
+    // Rubber-band at non-loop edges: dampen drag so users feel the bound
+    // without breaking the snap-back on release.
+    const shouldRubberBand =
+      !loop && ((isFirst && dx > 0) || (isLast && dx < 0));
+    setDragOffset(shouldRubberBand ? dx * 0.35 : dx);
+  };
+
+  const finishDrag = (clientX: number) => {
+    const start = dragStartRef.current;
+    if (!start) return;
+
+    const dx = clientX - start.x;
+    dragStartRef.current = null;
+    setIsDragging(false);
+    setDragOffset(0);
+
+    if (Math.abs(dx) < resolvedSwipeThreshold) return;
+
+    const steps = Math.max(1, Math.round(Math.abs(dx) / Math.max(1, averageStride)));
+    if (dx < 0) next(steps);
+    else prev(steps);
+  };
+
+  const handlePointerUp = (event: ReactPointerEvent<HTMLDivElement>) => {
+    finishDrag(event.clientX);
+    event.currentTarget.releasePointerCapture?.(event.pointerId);
+  };
+
+  const handlePointerCancel = (event: ReactPointerEvent<HTMLDivElement>) => {
+    dragStartRef.current = null;
+    setIsDragging(false);
+    setDragOffset(0);
+    event.currentTarget.releasePointerCapture?.(event.pointerId);
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    onKeyDown?.(event);
+    if (event.defaultPrevented || !keyboard) return;
+    if (event.key === "ArrowRight") {
+      event.preventDefault();
+      next();
+    } else if (event.key === "ArrowLeft") {
+      event.preventDefault();
+      prev();
+    } else if (event.key === "Home") {
+      event.preventDefault();
+      goTo(0);
+    } else if (event.key === "End") {
+      event.preventDefault();
+      goTo(maxIndex);
+    }
+  };
+
+  const handleWheel = (event: ReactWheelEvent<HTMLDivElement>) => {
+    onWheel?.(event);
+    if (event.defaultPrevented || !mousewheel || wheelLockRef.current) return;
+    const delta = Math.abs(event.deltaX) > Math.abs(event.deltaY) ? event.deltaX : event.deltaY;
+    if (Math.abs(delta) < 20) return;
+
+    wheelLockRef.current = true;
+    window.setTimeout(() => {
+      wheelLockRef.current = false;
+    }, Math.max(250, transitionDuration));
+
+    if (delta > 0) next();
+    else prev();
+  };
+
+  // ─── Context + render ───────────────────────────────────────────────────────
+
+  const ctxValue: SliderApi = useMemo(
+    () => ({
+      index: logicalIndex,
+      activeIndex: logicalIndex,
+      count,
+      snapCount,
+      slidesPerView,
+      slidesPerGroup,
+      progress,
+      isLoop: loop,
+      isDragging,
+      isAutoplayPaused,
+      isFirst,
+      isLast,
+      canSlidePrev: !isFirst,
+      canSlideNext: !isLast,
+      next,
+      prev,
+      goTo,
+      slideTo: goTo,
+      stopAutoplay,
+    }),
+    [
+      count,
+      goTo,
+      isAutoplayPaused,
+      isDragging,
+      isFirst,
+      isLast,
+      logicalIndex,
+      loop,
+      next,
+      prev,
+      progress,
+      slidesPerGroup,
+      slidesPerView,
+      snapCount,
+      stopAutoplay,
+    ],
+  );
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      next,
+      prev,
+      goTo,
+      slideTo: goTo,
+      stopAutoplay,
+      index: logicalIndex,
+      count,
+      snapCount,
+    }),
+    [count, goTo, logicalIndex, next, prev, snapCount, stopAutoplay],
+  );
+
+  const trackStyle: CSSProperties =
+    effectMode === "slide"
+      ? {
+          gap: `${spaceBetween}px`,
+          transform: `translate3d(${translate}px, 0, 0)`,
+          transition:
+            !isMotionReady || transitionOff || isDragging
+              ? "none"
+              : `transform ${transitionDuration}ms ${easing}`,
+        }
+      : {
+          transition: transitionOff ? "none" : `height ${transitionDuration}ms ${easing}`,
+        };
+
+  const slideStyle: CSSProperties =
+    slidesPerView === "auto"
+      ? { flex: "0 0 auto" }
+      : effectMode === "slide"
+        ? {
+            flex: "0 0 auto",
+            width:
+              viewportWidth > 0
+                ? `${Math.max(0, (viewportWidth - (slidesPerView - 1) * spaceBetween) / slidesPerView)}px`
+                : `max(0px, calc((100% - ${(slidesPerView - 1) * spaceBetween}px) / ${slidesPerView}))`,
+          }
+        : {};
+
+  const viewportStyle: CSSProperties | undefined = autoHeight && activeHeight
+    ? { height: activeHeight }
+    : undefined;
+
+  const navOpts: SliderNavigationOptions =
+    typeof navigation === "object" && navigation !== null ? navigation : {};
+  const paginationOpts: SliderPaginationOptions =
+    typeof pagination === "object" && pagination !== null ? pagination : {};
+
+  return (
+    <SliderContext.Provider value={ctxValue}>
+      <div
+        className={clsx(
+          s.container,
+          effectMode !== "slide" && s.container_effect,
+          className,
+        )}
+        style={style}
+        role="region"
+        aria-roledescription="carousel"
+        aria-label={ariaLabel}
+        tabIndex={keyboard ? 0 : undefined}
+        onMouseEnter={(event) => {
+          onMouseEnter?.(event);
+          setIsHovering(true);
+        }}
+        onMouseLeave={(event) => {
+          onMouseLeave?.(event);
+          setIsHovering(false);
+        }}
+        onFocus={(event) => {
+          onFocus?.(event);
+          setIsFocusWithin(true);
+        }}
+        onBlur={(event) => {
+          onBlur?.(event);
+          if (!event.currentTarget.contains(event.relatedTarget)) {
+            setIsFocusWithin(false);
+          }
+        }}
+        onKeyDown={handleKeyDown}
+        onWheel={handleWheel}
+        {...rest}
+      >
+        <div
+          ref={viewportRef}
+          className={s.viewport}
+          style={{
+            ...viewportStyle,
+            visibility: hasMeasured ? undefined : "hidden",
+            cursor: draggable ? (isDragging ? "grabbing" : "grab") : undefined,
+            touchAction: draggable ? "pan-y" : undefined,
+          }}
+          onPointerDown={handlePointerDown}
+          onPointerMove={handlePointerMove}
+          onPointerUp={handlePointerUp}
+          onPointerCancel={handlePointerCancel}
+          onDragStart={(event) => event.preventDefault()}
+        >
+          <div
+            ref={trackRef}
+            className={clsx(
+              s.track,
+              effectMode === "fade" && s.track_fade,
+              effectMode === "scale" && s.track_scale,
+            )}
+            style={trackStyle}
+            onTransitionEnd={handleTrackTransitionEnd}
+          >
+            {renderedSlides.map((child, renderedIndex) => {
+              const realIndex = canLoop
+                  ? wrap(renderedIndex - cloneCount, count)
+                  : renderedIndex;
+              const isClone =
+                canLoop && (renderedIndex < cloneCount || renderedIndex >= cloneCount + count);
+              const visibleCount =
+                slidesPerView === "auto" ? 1 : Math.ceil(slidesPerView);
+              const isActive =
+                realIndex === logicalIndex &&
+                (effectMode === "slide" ? renderedIndex === visualIndex : !isClone);
+              const isVisible = effectMode !== "slide"
+                  ? realIndex === logicalIndex
+                  : renderedIndex >= visualIndex &&
+                    renderedIndex < visualIndex + visibleCount;
+              const state: SliderSlideState = {
+                index: realIndex,
+                renderedIndex,
+                isActive,
+                isVisible,
+                isClone,
+              };
+
+              return (
+                <div
+                  key={
+                    isValidElement(child) && child.key != null
+                      ? `${String(child.key)}-${renderedIndex}`
+                      : `${realIndex}-${renderedIndex}`
+                  }
+                  ref={(node) => {
+                    slideRefs.current[renderedIndex] = node;
+                  }}
+                  id={!isClone ? `${uid}-slide-${realIndex}` : undefined}
+                  className={clsx(
+                    s.slide,
+                    effectMode !== "slide" && s.slide_overlay,
+                    isActive && s.slide_active,
+                    isVisible && s.slide_visible,
+                  )}
+                  style={slideStyle}
+                  aria-hidden={isClone || (!isVisible && effectMode !== "slide") || undefined}
+                  data-active={isActive ? "true" : undefined}
+                  data-visible={isVisible ? "true" : undefined}
+                  data-clone={isClone ? "true" : undefined}
+                >
+                  {renderSlide ? renderSlide(child, state) : child}
+                </div>
+              );
+            })}
+          </div>
+
+          {navigation ? (
+            <>
+              <SliderNavButton
+                direction="prev"
+                icon={navOpts.prevIcon}
+                ariaLabel={navOpts.ariaPrev ?? "Previous slide"}
+                className={navOpts.className}
+              />
+              <SliderNavButton
+                direction="next"
+                icon={navOpts.nextIcon}
+                ariaLabel={navOpts.ariaNext ?? "Next slide"}
+                className={navOpts.className}
+              />
+            </>
+          ) : null}
+        </div>
+
+        {pagination ? (
+          <SliderPaginationView
+            type={paginationOpts.type ?? "dots"}
+            clickable={paginationOpts.clickable ?? true}
+            items={paginationOpts.items ?? "snaps"}
+            className={paginationOpts.className}
+          />
+        ) : null}
+
+        {renderControls?.(ctxValue)}
+      </div>
+    </SliderContext.Provider>
+  );
+};
+
+// ─── Built-in nav + pagination ────────────────────────────────────────────────
+
+type SliderNavButtonProps = {
+  direction: "prev" | "next";
+  icon?: ReactNode;
+  ariaLabel: string;
+  className?: string;
+};
+
+const SliderNavButton = ({
+  direction,
+  icon,
+  ariaLabel,
+  className,
+}: SliderNavButtonProps) => {
+  const { next, prev, isFirst, isLast } = useSlider();
+  const disabled = direction === "prev" ? isFirst : isLast;
+  const onClick = direction === "prev" ? prev : next;
+  const defaultIcon =
+    direction === "prev" ? <IconChevronLeft /> : <IconChevronRight />;
+
+  return (
+    <button
+      type="button"
+      className={clsx(s.nav, direction === "prev" ? s.nav_prev : s.nav_next, className)}
+      onClick={() => onClick()}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      data-slider-no-drag
+    >
+      {icon ?? defaultIcon}
+    </button>
+  );
+};
+
+type SliderPaginationViewProps = {
+  type: SliderPaginationType;
+  clickable: boolean;
+  items: "snaps" | "slides";
+  className?: string;
+};
+
+const SliderPaginationView = ({
+  type,
+  clickable,
+  items,
+  className,
+}: SliderPaginationViewProps) => {
+  const { index, count, snapCount, progress, goTo } = useSlider();
+  const total = items === "slides" ? count : snapCount;
+  if (total <= 0) return null;
+
+  if (type === "fraction") {
+    return (
+      <div className={clsx(s.fraction, className)} aria-live="polite">
+        <span>{Math.min(index + 1, total)}</span>
+        <span className={s.fraction_sep}>/</span>
+        <span>{total}</span>
+      </div>
+    );
+  }
+
+  if (type === "progress") {
+    return (
+      <div
+        className={clsx(s.progress, className)}
+        role="progressbar"
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-valuenow={Math.round(progress * 100)}
+      >
+        <div className={s.progress_bar} style={{ width: `${progress * 100}%` }} />
+      </div>
+    );
+  }
+
+  return (
+    <div className={clsx(s.dots, className)} role="tablist" aria-label="Slider pagination">
+      {Array.from({ length: total }).map((_, dotIndex) => {
+        const isActive = dotIndex === Math.min(index, total - 1);
+        return (
+          <button
+            key={dotIndex}
+            type="button"
+            role="tab"
+            aria-selected={isActive}
+            aria-label={`Go to slide ${dotIndex + 1}`}
+            tabIndex={clickable ? 0 : -1}
+            disabled={!clickable}
+            className={clsx(s.dot, isActive && s.dot_active)}
+            onClick={clickable ? () => goTo(dotIndex) : undefined}
+            data-slider-no-drag
+          />
+        );
+      })}
+    </div>
+  );
+};
+
+// ─── Sub-components for custom layouts ────────────────────────────────────────
+// Drop these inside `renderControls` (or any descendant of <Slider>) for full
+// composition. Each one consumes the same `useSlider()` context as the built-in
+// UI, so disabled/active states stay in sync.
+
+export const SliderPrev = ({
+  className,
+  children,
+  ariaLabel = "Previous slide",
+}: {
+  className?: string;
+  children?: ReactNode;
+  ariaLabel?: string;
+}) => {
+  const { prev, isFirst } = useSlider();
+  return (
+    <button
+      type="button"
+      className={clsx(s.custom_btn, className)}
+      onClick={() => prev()}
+      disabled={isFirst}
+      aria-label={ariaLabel}
+      data-slider-no-drag
+    >
+      {children ?? <IconChevronLeft />}
+    </button>
+  );
+};
+
+export const SliderNext = ({
+  className,
+  children,
+  ariaLabel = "Next slide",
+}: {
+  className?: string;
+  children?: ReactNode;
+  ariaLabel?: string;
+}) => {
+  const { next, isLast } = useSlider();
+  return (
+    <button
+      type="button"
+      className={clsx(s.custom_btn, className)}
+      onClick={() => next()}
+      disabled={isLast}
+      aria-label={ariaLabel}
+      data-slider-no-drag
+    >
+      {children ?? <IconChevronRight />}
+    </button>
+  );
+};
+
+export const SliderDots = ({
+  className,
+  clickable = true,
+  items = "snaps",
+}: {
+  className?: string;
+  clickable?: boolean;
+  items?: "snaps" | "slides";
+}) => (
+  <SliderPaginationView
+    type="dots"
+    clickable={clickable}
+    items={items}
+    className={clsx(s.dots_static, className)}
+  />
+);
+
+export const SliderFraction = ({ className }: { className?: string }) => (
+  <SliderPaginationView
+    type="fraction"
+    clickable={false}
+    items="snaps"
+    className={className}
+  />
+);
+
+export const SliderProgress = ({ className }: { className?: string }) => (
+  <SliderPaginationView
+    type="progress"
+    clickable={false}
+    items="snaps"
+    className={className}
+  />
+);
+
+export { useSlider };