Drag-Throw Scroll

'use client';

import { useEffect, useRef, type ReactNode, type RefObject } from 'react';
import { useLenis } from '@/hooks/use-lenis';
import { useRaf } from '@/hooks/use-raf';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { clamp, damp, perFrameToSmoothing } from '@/lib/damp';
import { cn } from '@/lib/utils';

/* ==========================================================================
   Drag-Throw Scroll
   --------------------------------------------------------------------------
   Grab the page and pull it. Let go while still moving and it keeps going,
   decaying, exactly as far as the flick deserved. Wheel, drag and arrow keys
   all write to one scroll position, so the three inputs can never disagree.

   Two things make this hard, and neither is the drag itself.

   The first is the throw. Averaging "pixels since the last event" is the
   version everybody writes, and it is frame-rate dependent: the same physical
   flick produces half the velocity at 120 Hz because each event covers half
   the distance. Velocity here is measured in px per SECOND across a fixed
   100 ms window, so a flick throws the same distance on any display, and a
   drag that stalls before release throws nothing at all.

   The second is the pointer lifecycle. `setPointerCapture` on press keeps
   moves arriving after the pointer leaves the element — without it a fast
   drag dies the instant it crosses the edge and the content sticks
   mid-gesture. But capture can also be taken away without a `pointerup`:
   the OS claims the gesture, the element is detached, a second finger
   arrives. `pointercancel` and `lostpointercapture` are therefore both
   terminators, so there is no path that leaves the surface believing a
   finger is still down.
   ========================================================================== */

/** One position sample. `t` is `event.timeStamp`, i.e. ms on the page clock. */
interface Sample {
  y: number;
  t: number;
}

export interface DragThrowScrollProps {
  children?: ReactNode;
  /**
   * The box to scroll. Omit to drive the page through the shared Lenis
   * instance — which is also what gives the throw its glide.
   */
  scroller?: RefObject<HTMLElement | null>;
  /** Scroll px per pointer px, for mouse and pen. Touch is always 1. */
  multiplier?: number;
  /** Seconds of coast after release. Throw distance is velocity × this. */
  throwSeconds?: number;
  /** Arrow-key step in px, applied when the surface has focus. */
  keyStep?: number;
  enabled?: boolean;
  className?: string;
}

// #region critical
/**
 * Lenis's per-frame lerp for the throw, and the same curve expressed for
 * `damp` so a box scroller decays identically to the page. One number, two
 * sinks — tuning it in one place cannot desync them.
 */
const THROW_LERP = 0.05;
const THROW_SMOOTHING = perFrameToSmoothing(THROW_LERP);

const SAMPLE_COUNT = 5;
const SAMPLE_WINDOW_MS = 100;
const MIN_THROW_SPEED = 120;
const SETTLE_EPSILON = 0.5;
const KEY_STEP_SECONDS = 0.2;

/** Presses on real controls belong to those controls, not to the drag. */
const NO_DRAG = 'a,button,input,select,textarea,label,[data-no-drag]';

function scrollBoxOf(scroller?: RefObject<HTMLElement | null>): Element | null {
  if (scroller) return scroller.current;
  return typeof document === 'undefined' ? null : document.scrollingElement;
}

export function DragThrowScroll({
  children,
  scroller,
  multiplier = 2,
  throwSeconds = 0.65,
  keyStep = 100,
  enabled = true,
  className,
}: DragThrowScrollProps) {
  const surface = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();

  /* Lenis owns the document and nothing else. A component pointed at its own
     box must not build one — and under reduced motion nobody wants smoothing
     at all, so the page sink degrades to direct `scrollTop` writes. The hook
     is refcounted: several of these on one page share the single instance
     rather than stacking `wheel` handlers that each call `preventDefault`. */
  const viaLenis = enabled && !reduced && scroller === undefined;
  const lenis = useLenis({ enabled: viaLenis });

  /** Coast target for the box sink. `null` means nothing is in flight. */
  const glide = useRef<number | null>(null);

  useRaf(
    (dt) => {
      const to = glide.current;
      const box = scrollBoxOf(scroller);
      if (to === null || !box) return;
      const next = damp(box.scrollTop, to, THROW_SMOOTHING, dt);
      // Snap and stop. An exponential never arrives, so without a floor this
      // writes a sub-pixel delta every frame forever and the loop never idles.
      if (Math.abs(to - next) < SETTLE_EPSILON) {
        glide.current = null;
        box.scrollTop = to;
        return;
      }
      box.scrollTop = next;
    },
    // Only the box sink needs a loop: Lenis animates its own scrollTo, and
    // reduced motion has nothing to animate.
    enabled && !reduced && scroller !== undefined,
  );

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

    let pointerId: number | null = null;
    let startY = 0;
    let startScroll = 0;
    let target = 0;
    let gain = 1;
    const samples: Sample[] = [];

    /* -- the sink: Lenis when it exists, the raw box otherwise -------------- */

    const read = (): number => {
      const l = lenis.current;
      // `scroll`, not `targetScroll`. This is read on press, and grabbing a
      // coasting page has to stop it where the content LOOKS, not where it was
      // headed — otherwise the first pixel of the drag jumps forward by
      // whatever the throw had left to run.
      if (l) return l.scroll;
      return scrollBoxOf(scroller)?.scrollTop ?? 0;
    };

    const limitOf = (): number => {
      const l = lenis.current;
      if (l) return l.limit;
      const box = scrollBoxOf(scroller);
      return box ? Math.max(0, box.scrollHeight - box.clientHeight) : 0;
    };

    /** Direct manipulation: the content is under a finger, so no smoothing. */
    const jump = (y: number) => {
      glide.current = null;
      const l = lenis.current;
      if (l) {
        l.scrollTo(y, { immediate: true });
        return;
      }
      const box = scrollBoxOf(scroller);
      if (box) box.scrollTop = y;
    };

    /** Release: an exponential decay toward the thrown target. */
    const coast = (y: number) => {
      const l = lenis.current;
      if (l) {
        l.scrollTo(y, { lerp: THROW_LERP });
        return;
      }
      glide.current = y;
    };

    const step = (y: number) => {
      const l = lenis.current;
      if (l) {
        l.scrollTo(y, { duration: KEY_STEP_SECONDS });
        return;
      }
      glide.current = null;
      scrollBoxOf(scroller)?.scrollTo({ top: y, behavior: reduced ? 'auto' : 'smooth' });
    };

    /* -- velocity ---------------------------------------------------------- */

    /**
     * Pointer velocity in px/s, measured from the oldest sample still inside
     * the window to the newest. Time-based rather than per-event, so the
     * number describes the hand rather than the display.
     */
    const velocityAt = (now: number): number => {
      let oldest: Sample | undefined;
      for (const sample of samples) {
        if (now - sample.t <= SAMPLE_WINDOW_MS) {
          oldest = sample;
          break;
        }
      }
      const newest = samples[samples.length - 1];
      if (!oldest || !newest) return 0;
      const span = newest.t - oldest.t;
      if (span <= 0) return 0;
      return ((newest.y - oldest.y) / span) * 1000;
    };

    /* -- pointer lifecycle ------------------------------------------------- */

    const onPointerDown = (e: PointerEvent) => {
      if (pointerId !== null || !e.isPrimary) return;
      if (e.pointerType === 'mouse' && e.button !== 0) return;
      if (e.target instanceof Element && e.target.closest(NO_DRAG)) return;

      pointerId = e.pointerId;
      // A finger is physically on the content: any gain but 1 slides the
      // content out from under it. A mouse is an indirect device with a
      // window-height of travel available, so it gets the multiplier.
      gain = e.pointerType === 'touch' ? 1 : multiplier;
      startY = e.clientY;
      startScroll = read();
      target = startScroll;
      jump(startScroll);
      samples.length = 0;
      samples.push({ y: e.clientY, t: e.timeStamp });
      // Captured on press, not on some later threshold: by the time a
      // threshold would trip, the pointer may already be off the element.
      el.setPointerCapture(e.pointerId);
      el.dataset.dragging = 'true';
    };

    const onPointerMove = (e: PointerEvent) => {
      if (e.pointerId !== pointerId) return;
      // Absolute, from the press point. Accumulating per-event deltas onto the
      // live scroll position loses whatever the sink has not applied yet, and
      // the content drifts behind the hand over a long drag.
      target = clamp(startScroll - (e.clientY - startY) * gain, 0, limitOf());
      jump(target);
      samples.push({ y: e.clientY, t: e.timeStamp });
      if (samples.length > SAMPLE_COUNT) samples.shift();
    };

    const release = (e: PointerEvent, thrown: boolean) => {
      if (e.pointerId !== pointerId) return;
      pointerId = null;
      el.dataset.dragging = 'false';
      if (el.hasPointerCapture(e.pointerId)) el.releasePointerCapture(e.pointerId);

      if (!thrown || reduced) {
        samples.length = 0;
        return;
      }
      samples.push({ y: e.clientY, t: e.timeStamp });
      const velocity = velocityAt(e.timeStamp);
      samples.length = 0;
      const scrollVelocity = -velocity * gain;
      if (Math.abs(scrollVelocity) < MIN_THROW_SPEED) return;
      coast(clamp(target + scrollVelocity * throwSeconds, 0, limitOf()));
    };

    const onPointerUp = (e: PointerEvent) => release(e, true);
    // Both of these are aborts, so neither throws. `pointercancel` is the OS
    // taking the gesture; `lostpointercapture` is the catch-all — capture
    // revoked with no `pointerup` at all, which is the one path that would
    // otherwise leave the surface stuck believing a finger is still down. It
    // also fires immediately after a normal release, where the `pointerId`
    // guard above has already made it a no-op.
    const onPointerCancel = (e: PointerEvent) => release(e, false);
    const onLostCapture = (e: PointerEvent) => release(e, false);

    // Native HTML5 drag on any image or link inside would hijack the gesture
    // and hand back a ghost image instead of a scroll.
    const onDragStart = (e: Event) => e.preventDefault();

    const onKeyDown = (e: KeyboardEvent) => {
      const dir = e.key === 'ArrowDown' ? 1 : e.key === 'ArrowUp' ? -1 : 0;
      if (dir === 0) return;
      e.preventDefault();
      step(clamp(read() + dir * keyStep, 0, limitOf()));
    };

    el.addEventListener('pointerdown', onPointerDown);
    el.addEventListener('pointermove', onPointerMove);
    el.addEventListener('pointerup', onPointerUp);
    el.addEventListener('pointercancel', onPointerCancel);
    el.addEventListener('lostpointercapture', onLostCapture);
    el.addEventListener('dragstart', onDragStart);
    el.addEventListener('keydown', onKeyDown);

    return () => {
      el.removeEventListener('pointerdown', onPointerDown);
      el.removeEventListener('pointermove', onPointerMove);
      el.removeEventListener('pointerup', onPointerUp);
      el.removeEventListener('pointercancel', onPointerCancel);
      el.removeEventListener('lostpointercapture', onLostCapture);
      el.removeEventListener('dragstart', onDragStart);
      el.removeEventListener('keydown', onKeyDown);
      if (pointerId !== null && el.hasPointerCapture(pointerId)) {
        el.releasePointerCapture(pointerId);
      }
      el.dataset.dragging = 'false';
      glide.current = null;
    };
  }, [scroller, lenis, multiplier, throwSeconds, keyStep, enabled, reduced]);
  // #endregion critical

  return (
    <div
      ref={surface}
      // Rendered rather than added later so the attribute exists in the
      // server markup and the `data-` variants below have something to miss.
      data-dragging="false"
      tabIndex={enabled ? 0 : -1}
      className={cn(
        'relative',
        enabled &&
          // `touch-action: none` is what stops the browser scrolling the page
          // itself while we scroll it: without it a touch drag is claimed by
          // the compositor, `pointermove` stops arriving, and the gesture ends
          // in a `pointercancel` on the first frame.
          'touch-none cursor-grab data-[dragging=true]:cursor-grabbing data-[dragging=true]:select-none',
        className,
      )}
    >
      {children}
    </div>
  );
}

/* ==========================================================================
   Frame-rate-independent interpolation.
   --------------------------------------------------------------------------
   The everywhere-idiom `x += (target - x) * 0.1` is a bug: it converges twice
   as fast on a 120 Hz display as on a 60 Hz one, so the same code feels
   different on different hardware and visibly speeds up when the browser
   drops frames. `damp` fixes it by raising the retention factor to the power
   of elapsed time, which is the exact continuous form of the same curve.
   ========================================================================== */

/**
 * Fraction of the remaining distance to close this frame.
 *
 * @param smoothing Fraction of the gap that REMAINS after one second.
 *   Smaller is snappier. 0.001 ≈ very fast, 0.01 ≈ fast, 0.1 ≈ soft,
 *   0.5 ≈ slow drift.
 * @param dt Seconds elapsed since the previous frame.
 */
export function dampFactor(smoothing: number, dt: number): number {
  return 1 - Math.pow(smoothing, dt);
}

/** Move `current` toward `target` at a rate independent of frame rate. */
export function damp(
  current: number,
  target: number,
  smoothing: number,
  dt: number,
): number {
  return current + (target - current) * dampFactor(smoothing, dt);
}

/**
 * The per-frame lerp constant an author measured at 60fps, converted into the
 * `smoothing` argument `damp` wants. Lets a source that says "0.1 per frame"
 * be ported without re-tuning by eye:
 *
 *   damp(x, t, perFrameToSmoothing(0.1), dt)
 */
export function perFrameToSmoothing(alpha: number, baseFps = 60): number {
  return Math.pow(1 - alpha, baseFps);
}

export function lerp(a: number, b: number, t: number): number {
  return a + (b - a) * t;
}

export function clamp(v: number, min: number, max: number): number {
  return v < min ? min : v > max ? max : v;
}

export function inverseLerp(a: number, b: number, v: number): number {
  return a === b ? 0 : (v - a) / (b - a);
}

export function mapRange(
  v: number,
  inMin: number,
  inMax: number,
  outMin: number,
  outMax: number,
  doClamp = true,
): number {
  const t = inverseLerp(inMin, inMax, v);
  const r = lerp(outMin, outMax, doClamp ? clamp(t, 0, 1) : t);
  return r;
}

/** GLSL `smoothstep`, same semantics, for parity between JS and shader code. */
export function smoothstep(edge0: number, edge1: number, x: number): number {
  const t = clamp(inverseLerp(edge0, edge1, x), 0, 1);
  return t * t * (3 - 2 * t);
}

/**
 * Gaussian falloff, `exp(-d²)`. Yields 1.000 / 0.368 / 0.018 / 0.0001 at
 * distances 0 / 1 / 2 / 3 — a continuous focus scalar with no thresholds and
 * no branches, which is why carousels that use it feel analogue rather than
 * stepped.
 */
export function gaussian(distance: number, falloff = 1): number {
  const d = distance * falloff;
  return Math.exp(-(d * d));
}

'use client';

import Lenis from 'lenis';
import { useEffect, useRef } from 'react';

/* ==========================================================================
   One Lenis instance, driven by whichever clock is already running.
   --------------------------------------------------------------------------
   Two failure modes this exists to prevent:

   1. Two rAF loops. Lenis self-drives via `autoRaf` by default. If GSAP's
      ticker is also running, scroll position advances on one clock while
      ScrollTrigger reads it on another, and pinned sections jitter by a
      frame. Passing a `ticker` disables `autoRaf` and hands Lenis to that
      clock instead — the documented integration.

   2. Two Lenis instances. Mount a second one and both listen on `wheel`,
      both call `preventDefault`, and scrolling runs at double speed. The
      module-level refcount below makes a second mount reuse the first
      instance rather than build a rival.
   ========================================================================== */

export interface LenisTicker {
  add: (fn: (time: number) => void) => void;
  remove: (fn: (time: number) => void) => void;
  /**
   * `threshold` is required, matching `gsap.ticker`, which types it as
   * `number | boolean`. Declaring it optional here made the parameter
   * `number | undefined` and no longer satisfiable by GSAP's own ticker.
   */
  lagSmoothing?: (threshold: number, adjustedLag?: number) => void;
}

export interface UseLenisOptions {
  /** Seconds to settle. Ignored when `easing` drives duration. */
  duration?: number;
  easing?: (t: number) => number;
  orientation?: 'vertical' | 'horizontal';
  smoothWheel?: boolean;
  wheelMultiplier?: number;
  touchMultiplier?: number;
  infinite?: boolean;
  /**
   * Drive Lenis from this clock instead of its own rAF. Pass `gsap.ticker`
   * when the page also uses ScrollTrigger.
   */
  ticker?: LenisTicker;
  /** Called on every scroll frame. Held in a ref, so it needs no memo. */
  onScroll?: (lenis: Lenis) => void;
  /** Skip entirely — for `prefers-reduced-motion`, or on touch devices. */
  enabled?: boolean;
}

let shared: Lenis | null = null;
let refCount = 0;

export function useLenis(options: UseLenisOptions = {}): { current: Lenis | null } {
  const {
    duration,
    easing,
    orientation = 'vertical',
    smoothWheel = true,
    wheelMultiplier,
    touchMultiplier,
    infinite = false,
    ticker,
    onScroll,
    enabled = true,
  } = options;

  const instance = useRef<Lenis | null>(null);
  const onScrollRef = useRef(onScroll);
  onScrollRef.current = onScroll;

  useEffect(() => {
    if (!enabled) return;

    if (shared === null) {
      shared = new Lenis({
        ...(duration === undefined ? {} : { duration }),
        ...(easing === undefined ? {} : { easing }),
        orientation,
        smoothWheel,
        ...(wheelMultiplier === undefined ? {} : { wheelMultiplier }),
        ...(touchMultiplier === undefined ? {} : { touchMultiplier }),
        infinite,
        // A ticker owns the clock; `autoRaf` would be the second one.
        autoRaf: ticker === undefined,
      });
    }

    const lenis = shared;
    refCount += 1;
    instance.current = lenis;

    const handleScroll = () => onScrollRef.current?.(lenis);
    lenis.on('scroll', handleScroll);

    const update = (time: number) => lenis.raf(time * 1000); // ticker is in seconds
    if (ticker) {
      ticker.add(update);
      // Default lag smoothing freezes GSAP's clock after a 500 ms stall while
      // Lenis keeps its own time, so the two desync exactly when the page is
      // busiest. 0 disables it.
      ticker.lagSmoothing?.(0);
    }

    return () => {
      lenis.off('scroll', handleScroll);
      if (ticker) ticker.remove(update);
      instance.current = null;
      refCount -= 1;
      if (refCount === 0) {
        lenis.destroy();
        shared = null;
      }
    };
  }, [
    duration,
    easing,
    orientation,
    smoothWheel,
    wheelMultiplier,
    touchMultiplier,
    infinite,
    ticker,
    enabled,
  ]);

  return instance;
}

'use client';

import { useEffect, useRef } from 'react';

/* ==========================================================================
   One shared requestAnimationFrame loop.
   --------------------------------------------------------------------------
   Forty components each calling requestAnimationFrame means forty callbacks
   the browser schedules separately and forty chances to read layout after a
   write. One loop, one ordered pass, one place to clamp delta time.

   Delta is clamped to 100 ms. Without that, returning to a backgrounded tab
   delivers a multi-second dt and every physics integration in the page
   explodes on the first frame back.
   ========================================================================== */

export type RafCallback = (dt: number, elapsed: number) => void;

const callbacks = new Set<RafCallback>();
let frame = 0;
let last = 0;
let start = 0;

const MAX_DT = 0.1;
const DEFAULT_DT = 1 / 60;

function tick(now: number) {
  frame = requestAnimationFrame(tick);
  const dt = last === 0 ? DEFAULT_DT : Math.min((now - last) / 1000, MAX_DT);
  last = now;
  const elapsed = (now - start) / 1000;
  // Copy: a callback may unsubscribe itself (or another) mid-iteration.
  for (const cb of Array.from(callbacks)) {
    if (callbacks.has(cb)) cb(dt, elapsed);
  }
}

function subscribe(cb: RafCallback) {
  callbacks.add(cb);
  if (frame === 0) {
    start = performance.now();
    last = 0;
    frame = requestAnimationFrame(tick);
  }
  return () => {
    callbacks.delete(cb);
    if (callbacks.size === 0 && frame !== 0) {
      cancelAnimationFrame(frame);
      frame = 0;
      last = 0;
    }
  };
}

/**
 * Run `cb` every frame while `enabled`.
 *
 * The callback is held in a ref, so it does not need to be memoised and the
 * subscription is never torn down just because the closure changed identity.
 */
export function useRaf(cb: RafCallback, enabled = true): void {
  const ref = useRef(cb);
  ref.current = cb;

  useEffect(() => {
    if (!enabled) return;
    return subscribe((dt, elapsed) => ref.current(dt, elapsed));
  }, [enabled]);
}

'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,
  );
}