Wrapping Drum Carousel

'use client';

import gsap from 'gsap';
import {
  Children,
  isValidElement,
  useCallback,
  useEffect,
  useRef,
  type ReactNode,
} from 'react';
import { useDrag } from '@/hooks/use-drag';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { useResizeObserver } from '@/hooks/use-resize-observer';
import { wrapIndex } from '@/lib/wrap';
import { cn } from '@/lib/utils';

/* ==========================================================================
   Wrapping Drum Carousel
   --------------------------------------------------------------------------
   A carousel that reads as a rotating drum while being entirely flat. There
   is no `rotateY`, no `translateZ`, no `perspective` — the component sets
   `rotationY: 0` and `z: 0` explicitly so that no ambient 3D can leak in from
   a parent. Depth comes from three flat properties moving together with
   distance from centre: `x`, `scale`, and `autoAlpha`.

   The endlessness comes from one function. `gsap.utils.wrap(-n/2, n/2)` maps
   `i - position` into a signed ring offset, so card 5 of 6 at position 0 sits
   one slot to the LEFT of centre rather than five slots to the right. The
   carousel has no ends and `position` may drift to ±10000 without breaking.
   ========================================================================== */

export interface WrappingDrumCarouselProps {
  /** One card per child. Each is wrapped in a positioned cell we control. */
  children: ReactNode;
  /** Card spacing as a fraction of stage width. */
  spacingRatio?: number;
  /** Upper bound on spacing in px, so an ultrawide monitor does not fling
   *  the neighbours into the next county. */
  maxSpacing?: number;
  /** How much a card shrinks by one slot out. */
  scaleFalloff?: number;
  className?: string;
  /** Applied to each positioned cell — this is where you size the cards. */
  cardClassName?: string;
  /** Fires with the wrapped index (always `0..count-1`) on every snap. */
  onIndexChange?: (index: number) => void;
}

const SNAP_DURATION = 0.7;
const WHEEL_STEP = 90;
const MAX_WHEEL_STEPS = 3;
const DRAG_THRESHOLD = 8;
const ALPHA_INTERCEPT = 1.15;
const ALPHA_SLOPE = 0.75;

// #region critical
export function WrappingDrumCarousel({
  children,
  spacingRatio = 0.46,
  maxSpacing = 560,
  scaleFalloff = 0.2,
  className,
  cardClassName,
  onIndexChange,
}: WrappingDrumCarouselProps) {
  const stageRef = useRef<HTMLDivElement>(null);
  const cardsRef = useRef<Array<HTMLDivElement | null>>([]);
  /** Fractional carousel position. Tweened by the snap, driven raw by drag. */
  const posRef = useRef({ pos: 0 });
  /** Integer target index. Unwrapped — it counts up forever. */
  const indexRef = useRef(0);
  /** Last computed spacing in px. Drag divides by this for 1:1 tracking. */
  const stepRef = useRef(1);

  const reduced = useReducedMotion();
  const size = useResizeObserver(stageRef);

  const items = Children.toArray(children);
  const count = items.length;

  const notify = useRef(onIndexChange);
  notify.current = onIndexChange;

  /**
   * Lay every card out for the current `pos`. Called on mount, on resize,
   * on every frame of the snap tween, and on every pointermove during a drag.
   * It is a pure function of `pos` — there is no accumulated state in here,
   * which is why interrupting the tween mid-flight cannot desynchronise it.
   */
  const layout = useCallback(() => {
    const stage = stageRef.current;
    if (!stage || count === 0) return;

    const step = Math.min(spacingRatio * stage.clientWidth, maxSpacing);
    stepRef.current = step > 0 ? step : 1;

    // Signed ring offset in (-count/2, count/2]. The whole illusion is here.
    const ring = gsap.utils.wrap(-count / 2, count / 2);
    const pos = posRef.current.pos;

    for (let i = 0; i < count; i += 1) {
      const card = cardsRef.current[i];
      if (!card) continue;

      const offset = ring(i - pos);
      const distance = Math.abs(offset);

      gsap.set(card, {
        xPercent: -50,
        yPercent: -50,
        x: offset * step,
        // Explicitly flat. Without these two, a `transform-style: preserve-3d`
        // or a stray `rotateY` on an ancestor turns a deliberately 2D drum
        // into a half-broken 3D one that skews at the edges.
        rotationY: 0,
        z: 0,
        // Scale bottoms out at one slot out; alpha keeps falling and hits 0 at
        // distance 1.533. Cards therefore fade into fog rather than shrink to
        // a vanishing point — that mismatch is what sells the cylinder.
        scale: 1 - scaleFalloff * Math.min(distance, 1),
        autoAlpha: gsap.utils.clamp(0, 1, ALPHA_INTERCEPT - ALPHA_SLOPE * distance),
        zIndex: 100 - Math.round(10 * distance),
        transformOrigin: '50% 50%',
      });
    }
  }, [count, spacingRatio, maxSpacing, scaleFalloff]);

  /** Tween `pos` to an integer index and re-lay out on every frame. */
  const snapTo = useCallback(
    (index: number) => {
      indexRef.current = index;
      notify.current?.(wrapIndex(index, count));

      if (reduced) {
        // Not "duration 0" via the tween: a zero-duration gsap.to does not
        // guarantee an onUpdate call, so the layout would never run.
        posRef.current.pos = index;
        layout();
        return;
      }

      gsap.to(posRef.current, {
        pos: index,
        duration: SNAP_DURATION,
        ease: 'power3.out',
        overwrite: true,
        onUpdate: layout,
      });
    },
    [count, layout, reduced],
  );

  useDrag(stageRef, {
    threshold: DRAG_THRESHOLD,
    onDragStart: () => {
      // Kill the snap first or it keeps writing `pos` underneath the drag and
      // the cards visibly fight the finger.
      gsap.killTweensOf(posRef.current);
    },
    onDrag: (state) => {
      posRef.current.pos -= state.deltaX / stepRef.current;
      layout();
    },
    onDragEnd: (_state, moved) => {
      if (moved) snapTo(Math.round(posRef.current.pos));
    },
  });
  // #endregion critical

  // Re-lay out whenever the stage resizes: spacing is a fraction of width, so
  // a sidebar opening changes every card's position.
  useEffect(() => {
    layout();
  }, [layout, size.width, size.height]);

  useEffect(() => {
    const stage = stageRef.current;
    if (!stage) return;

    let accumulated = 0;

    const onWheel = (e: WheelEvent) => {
      // Only horizontal intent drives the drum. A trackpad's vertical swipe
      // belongs to the page — claiming it here would trap the scroll on any
      // page that puts this component in the middle of an article.
      if (Math.abs(e.deltaX) <= Math.abs(e.deltaY) || e.deltaX === 0) return;
      e.preventDefault();

      accumulated += e.deltaX;
      let steps = 0;
      while (Math.abs(accumulated) >= WHEEL_STEP && steps < MAX_WHEEL_STEPS) {
        const direction = accumulated > 0 ? 1 : -1;
        accumulated -= WHEEL_STEP * direction;
        snapTo(indexRef.current + direction);
        steps += 1;
      }
      // Drop the remainder once a step fired. Keeping it lets a long inertial
      // trackpad flick queue up steps that keep firing after the fingers lift.
      if (steps > 0) accumulated = 0;
    };

    // `passive: false` is required: preventDefault on a passive wheel listener
    // is ignored and logs a console warning on every event.
    stage.addEventListener('wheel', onWheel, { passive: false });
    return () => stage.removeEventListener('wheel', onWheel);
  }, [snapTo]);

  useEffect(() => {
    const position = posRef.current;
    const cells = cardsRef.current;
    return () => {
      gsap.killTweensOf(position);
      const live = cells.filter((c): c is HTMLDivElement => c !== null);
      if (live.length > 0) {
        gsap.killTweensOf(live);
        gsap.set(live, { clearProps: 'all' });
      }
    };
  }, []);

  return (
    <div
      ref={stageRef}
      className={cn(
        'relative h-full w-full touch-pan-y select-none overflow-hidden',
        'cursor-grab active:cursor-grabbing',
        className,
      )}
    >
      {items.map((child, i) => (
        <div
          key={isValidElement(child) && child.key !== null ? child.key : i}
          ref={(node) => {
            cardsRef.current[i] = node;
          }}
          // `invisible` for the first paint: layout() runs in an effect, so
          // without it every card flashes stacked at the centre for one frame.
          className={cn(
            'invisible absolute left-1/2 top-1/2 will-change-transform',
            cardClassName,
          )}
        >
          {child}
        </div>
      ))}
    </div>
  );
}

'use client';

import { useEffect, useRef, type RefObject } from 'react';

/* ==========================================================================
   Pointer drag with capture, a dead zone, and a click gate.
   --------------------------------------------------------------------------
   Three things every hand-rolled drag gets wrong:

   1. No pointer capture. Drag fast, leave the element, and `pointermove`
      stops firing — the track sticks mid-throw. `setPointerCapture` keeps
      events coming to the origin element until release.

   2. No dead zone. Without one, a 1 px wobble during a click is a drag, and
      the drag handler fights the click handler on every tap.

   3. The click still fires. After a real drag, the browser dispatches
      `click` on whatever is under the pointer, so throwing a carousel opens
      whichever slide you happen to release over. Swallowing that one click
      in the capture phase is the fix; `onDragEnd`'s `moved` flag tells the
      caller whether it happened.
   ========================================================================== */

export interface DragState {
  /** Pixels from the press point. */
  dx: number;
  dy: number;
  /** Pixels since the previous move event. */
  deltaX: number;
  deltaY: number;
  /** Viewport pixels. */
  clientX: number;
  clientY: number;
}

export interface UseDragOptions {
  /** Pixels of travel before it counts as a drag. Default 4. */
  threshold?: number;
  /** Ignore the wrong mouse buttons / a secondary touch. Default true. */
  primaryOnly?: boolean;
  onDragStart?: (state: DragState) => void;
  onDrag?: (state: DragState) => void;
  /** `moved` is false for a tap: the caller should treat it as a click. */
  onDragEnd?: (state: DragState, moved: boolean) => void;
  enabled?: boolean;
}

export function useDrag(
  ref: RefObject<HTMLElement | null>,
  options: UseDragOptions = {},
): { current: boolean } {
  const { threshold = 4, primaryOnly = true, enabled = true } = options;

  const dragging = useRef(false);
  const handlers = useRef(options);
  handlers.current = options;

  useEffect(() => {
    const el = ref.current;
    if (!el || !enabled) return;

    let pointerId: number | null = null;
    let startX = 0;
    let startY = 0;
    let lastX = 0;
    let lastY = 0;
    let passed = false;
    let swallowClick = false;

    const stateAt = (clientX: number, clientY: number): DragState => ({
      dx: clientX - startX,
      dy: clientY - startY,
      deltaX: clientX - lastX,
      deltaY: clientY - lastY,
      clientX,
      clientY,
    });

    const onPointerDown = (e: PointerEvent) => {
      if (primaryOnly && !e.isPrimary) return;
      if (e.pointerType === 'mouse' && e.button !== 0) return;
      pointerId = e.pointerId;
      startX = lastX = e.clientX;
      startY = lastY = e.clientY;
      passed = false;
      // Capture on press, not on threshold: by the time the threshold is
      // crossed the pointer may already be outside the element.
      el.setPointerCapture(e.pointerId);
    };

    const onPointerMove = (e: PointerEvent) => {
      if (pointerId !== e.pointerId) return;
      const state = stateAt(e.clientX, e.clientY);

      if (!passed) {
        if (Math.hypot(state.dx, state.dy) < threshold) return;
        passed = true;
        dragging.current = true;
        handlers.current.onDragStart?.(state);
      }

      handlers.current.onDrag?.(state);
      lastX = e.clientX;
      lastY = e.clientY;
    };

    const finish = (e: PointerEvent) => {
      if (pointerId !== e.pointerId) return;
      const state = stateAt(e.clientX, e.clientY);
      const moved = passed;

      if (el.hasPointerCapture(e.pointerId)) el.releasePointerCapture(e.pointerId);
      pointerId = null;
      passed = false;
      dragging.current = false;
      swallowClick = moved;

      handlers.current.onDragEnd?.(state, moved);
    };

    // Capture phase, so it runs before any child's own click handler.
    const onClick = (e: MouseEvent) => {
      if (!swallowClick) return;
      swallowClick = false;
      e.preventDefault();
      e.stopPropagation();
    };

    el.addEventListener('pointerdown', onPointerDown);
    el.addEventListener('pointermove', onPointerMove);
    el.addEventListener('pointerup', finish);
    el.addEventListener('pointercancel', finish);
    el.addEventListener('click', onClick, true);

    return () => {
      el.removeEventListener('pointerdown', onPointerDown);
      el.removeEventListener('pointermove', onPointerMove);
      el.removeEventListener('pointerup', finish);
      el.removeEventListener('pointercancel', finish);
      el.removeEventListener('click', onClick, true);
      if (pointerId !== null && el.hasPointerCapture(pointerId)) {
        el.releasePointerCapture(pointerId);
      }
      dragging.current = false;
    };
  }, [ref, threshold, primaryOnly, enabled]);

  return dragging;
}

'use client';

import { useSyncExternalStore } from 'react';

/* ==========================================================================
   prefers-reduced-motion, SSR-safe.
   --------------------------------------------------------------------------
   useSyncExternalStore rather than useState + useEffect: the server snapshot
   is an explicit `false`, so the markup React renders on the server and the
   markup it hydrates with agree, and the real value lands in the same commit
   as hydration instead of one frame later. A useEffect version flashes the
   animated variant before removing it — the exact thing the user asked not to
   see.

   Reduced motion is not "duration: 0". For most components here it means a
   different render: the final state, a static poster, or a paused frame.
   ========================================================================== */

const QUERY = '(prefers-reduced-motion: reduce)';

function subscribe(onChange: () => void) {
  if (typeof window === 'undefined' || !window.matchMedia) return () => {};
  const mql = window.matchMedia(QUERY);
  mql.addEventListener('change', onChange);
  return () => mql.removeEventListener('change', onChange);
}

function getSnapshot() {
  if (typeof window === 'undefined' || !window.matchMedia) return false;
  return window.matchMedia(QUERY).matches;
}

function getServerSnapshot() {
  return false;
}

export function useReducedMotion(): boolean {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

/** Generic media-query hook, same SSR guarantees. */
export function useMediaQuery(query: string): boolean {
  return useSyncExternalStore(
    (onChange) => {
      if (typeof window === 'undefined' || !window.matchMedia) return () => {};
      const mql = window.matchMedia(query);
      mql.addEventListener('change', onChange);
      return () => mql.removeEventListener('change', onChange);
    },
    () => {
      if (typeof window === 'undefined' || !window.matchMedia) return false;
      return window.matchMedia(query).matches;
    },
    () => false,
  );
}

'use client';

import { useEffect, useState, type RefObject } from 'react';

/* ==========================================================================
   Element size, from one shared ResizeObserver.
   --------------------------------------------------------------------------
   Sized from the element rather than the window because a preview in a grid
   cell resizes when the grid reflows, not when the viewport does. Reading
   `window.innerWidth` is the reason so many canvas components are correct on
   load and wrong after a sidebar opens.
   ========================================================================== */

export interface Size {
  width: number;
  height: number;
}

type Handler = (size: Size) => void;

let observer: ResizeObserver | null = null;
const handlers = new Map<Element, Handler>();

function ensureObserver(): ResizeObserver | null {
  if (typeof ResizeObserver === 'undefined') return null;
  observer ??= new ResizeObserver((entries) => {
    for (const entry of entries) {
      const box = entry.contentBoxSize?.[0];
      const size: Size = box
        ? { width: box.inlineSize, height: box.blockSize }
        : { width: entry.contentRect.width, height: entry.contentRect.height };
      handlers.get(entry.target)?.(size);
    }
  });
  return observer;
}

export function useResizeObserver(ref: RefObject<Element | null>): Size {
  const [size, setSize] = useState<Size>({ width: 0, height: 0 });

  useEffect(() => {
    const el = ref.current;
    const ro = ensureObserver();
    if (!el || !ro) return;

    // Seed synchronously: waiting for the first observer callback leaves one
    // frame where a canvas is sized 0x0, which some drivers log as an error.
    const rect = el.getBoundingClientRect();
    setSize({ width: rect.width, height: rect.height });

    handlers.set(el, (next) =>
      setSize((prev) =>
        prev.width === next.width && prev.height === next.height ? prev : next,
      ),
    );
    ro.observe(el);

    return () => {
      handlers.delete(el);
      ro.unobserve(el);
    };
  }, [ref]);

  return size;
}

/* ==========================================================================
   Ring index arithmetic.
   --------------------------------------------------------------------------
   Anything that loops — a drum carousel, an infinite marquee, a cylinder of
   image planes — needs to answer "how far is item i from position p" in a way
   that treats the sequence as a circle. A plain `i - p` says item 0 is 18 away
   from item 18 in a list of 19, when really it is 1 step back.
   ========================================================================== */

/** True modulo. Unlike `%`, the result is never negative. */
export function mod(n: number, m: number): number {
  return ((n % m) + m) % m;
}

/**
 * Shortest signed distance from `position` to index `i` around a ring of
 * `count` items. Result is in `(-count/2, count/2]`; negative means "behind".
 *
 * This one function is what makes a finite array behave like an infinite one.
 */
export function wrappedOffset(i: number, position: number, count: number): number {
  if (count <= 0) return 0;
  let offset = mod(i - position, count);
  if (offset > count / 2) offset -= count;
  return offset;
}

/** Wrap `value` into `[min, max)`, e.g. an angle into `[-PI, PI)`. */
export function wrapRange(value: number, min: number, max: number): number {
  const span = max - min;
  if (span <= 0) return min;
  return mod(value - min, span) + min;
}

/** Wrap an index into `[0, count)`. Accepts fractional and negative input. */
export function wrapIndex(i: number, count: number): number {
  return count <= 0 ? 0 : mod(i, count);
}

/**
 * Shortest signed angular distance from `a` to `b` in radians, in `(-PI, PI]`.
 * Prevents a rotation tween from taking the long way round.
 */
export function shortestAngle(a: number, b: number): number {
  return wrapRange(b - a, -Math.PI, Math.PI);
}