Velocity-Deformed Cards

'use client';

import { useEffect, useRef, useState, type ReactNode, type RefObject } from 'react';
import { useRaf } from '@/hooks/use-raf';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { useScrollVelocity } from '@/hooks/use-scroll-velocity';
import { cn } from '@/lib/utils';

/* ==========================================================================
   Velocity-Deformed Cards
   --------------------------------------------------------------------------
   Scroll position tells you where the page is. Scroll *velocity* tells you
   how hard the user is pushing it, and that is the input that makes a list
   feel like it is made of something.

   Cards skew and stretch along the direction of travel, lag behind by an
   amount proportional to how fast you are going, and settle when you stop —
   with no easing curve anywhere. The ease-out is a property of the filter,
   not a keyframe: `useScrollVelocity` low-passes the raw delta, then damps
   toward that filtered value, so a step change in speed comes out the far
   end as a curve.

   Nothing here re-renders React. Velocity lives in a ref, transforms are
   written directly, and a stationary list writes nothing at all.
   ========================================================================== */

export interface VelocityDeformCardsProps {
  children: ReactNode;
  /** Degrees of skew at full velocity. */
  maxSkew?: number;
  /** Pixels a card trails behind at full velocity. */
  maxLag?: number;
  /** Stretch along the travel axis at full velocity, as a fraction. */
  maxStretch?: number;
  /** Velocity in px/s that counts as "full". */
  reference?: number;
  /** Fraction of the velocity gap remaining after one second. */
  smoothing?: number;
  /** Scroll container. Omit to auto-detect the nearest scrollable ancestor. */
  scroller?: RefObject<HTMLElement | null>;
  className?: string;
}

const SCROLLABLE = /(auto|scroll|overlay)/;

function nearestScroller(el: HTMLElement): HTMLElement {
  let node = el.parentElement;
  while (node) {
    if (SCROLLABLE.test(getComputedStyle(node).overflowY)) return node;
    node = node.parentElement;
  }
  return document.documentElement;
}

// #region critical
export function VelocityDeformCards({
  children,
  maxSkew = 5,
  maxLag = 28,
  maxStretch = 0.14,
  reference = 1400,
  smoothing = 0.0002,
  scroller,
  className,
}: VelocityDeformCardsProps) {
  const root = useRef<HTMLDivElement>(null);
  const cards = useRef<HTMLElement[]>([]);
  const written = useRef<string[]>([]);
  const lastVelocity = useRef('');
  const reduced = useReducedMotion();

  // The hook wants an element, not a ref, so the container is resolved once
  // after mount — `document.documentElement` is the window-scroll case and is
  // read through `scrollTop` there too, which is correct on every engine.
  const [host, setHost] = useState<HTMLElement | null>(null);
  useEffect(() => {
    const rootEl = root.current;
    if (!rootEl) return;
    setHost(scroller?.current ?? nearestScroller(rootEl));
  }, [scroller]);

  const velocity = useScrollVelocity({
    reference,
    smoothing,
    target: host === document.documentElement ? null : host,
  });

  // Cached rather than queried per frame: a `querySelectorAll` inside the rAF
  // loop is a forced style recalc 60 times a second for a list that changed
  // once.
  useEffect(() => {
    const rootEl = root.current;
    if (!rootEl) return;
    cards.current = Array.from(rootEl.querySelectorAll<HTMLElement>('[data-deform]'));
    written.current = cards.current.map(() => '');
  }, [children]);

  useRaf((_dt) => {
    const rootEl = root.current;
    if (!rootEl) return;

    if (reduced) {
      // One pass to clear, then nothing. The guard below keeps it to one pass.
      for (let i = 0; i < cards.current.length; i += 1) {
        if (written.current[i] === '') continue;
        written.current[i] = '';
        const card = cards.current[i];
        if (card) card.style.transform = '';
      }
      return;
    }

    // -1..1, already low-passed twice. Positive is scrolling down.
    const v = velocity.current.normalized;
    const magnitude = Math.abs(v);

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

      // Per-card depth is the whole effect: identical values make the list
      // move as one rigid sheet, varied values make it bend like cloth.
      const raw = Number.parseFloat(card.dataset.deform ?? '');
      const depth = Number.isFinite(raw) ? raw : 1;

      const lag = -v * maxLag * depth;
      const skew = -v * maxSkew * depth;
      const stretch = 1 + magnitude * maxStretch * depth;
      // Squash across the travel axis by half the stretch: the card keeps
      // roughly its area, which is what stops the deformation reading as a
      // scaling bug.
      const squash = 1 - magnitude * maxStretch * depth * 0.5;

      const transform =
        `translate3d(0, ${lag.toFixed(2)}px, 0) ` +
        `skewY(${skew.toFixed(2)}deg) ` +
        `scale(${squash.toFixed(4)}, ${stretch.toFixed(4)})`;

      // At rest every card produces the same string as last frame, so an idle
      // list costs one comparison per card and zero style invalidations.
      if (written.current[i] === transform) continue;
      written.current[i] = transform;
      card.style.transform = transform;
    }

    // Published for anything that would rather react in CSS than in JS —
    // guarded, so a stationary list stops writing to the DOM entirely.
    const text = v.toFixed(3);
    if (text !== lastVelocity.current) {
      lastVelocity.current = text;
      rootEl.style.setProperty('--scroll-velocity', text);
    }
  });
  // #endregion critical

  return (
    <div ref={root} className={cn('w-full', 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 { 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,
  );
}

'use client';

import { useRef } from 'react';
import { useRaf } from '@/hooks/use-raf';
import { clamp, damp } from '@/lib/damp';

/* ==========================================================================
   Smoothed scroll velocity.
   --------------------------------------------------------------------------
   Raw `scrollY` deltas are spiky: a trackpad emits bursts, a mouse wheel
   emits steps, and either one drives a geometry parameter into visible
   stutter. Two stages fix it — a one-pole low-pass on the delta itself, then
   a damped approach toward that filtered value, which is what produces the
   free ease-out when scrolling stops.

   Values are exposed through a ref, not state. A velocity that changes every
   frame must never re-render React.
   ========================================================================== */

export interface ScrollVelocity {
  /** Signed, in pixels per second, smoothed. */
  velocity: number;
  /** `velocity` normalised to roughly -1..1 for driving visual parameters. */
  normalized: number;
  /** -1 up, 1 down, 0 at rest. */
  direction: number;
  /** Current scroll offset in pixels. */
  scroll: number;
}

export interface UseScrollVelocityOptions {
  /** Velocity that maps to `normalized === 1`. Default 1500 px/s. */
  reference?: number;
  /** Fraction of the gap remaining after 1 s. Lower is snappier. */
  smoothing?: number;
  /** Read from this element instead of the window. */
  target?: HTMLElement | null;
}

export function useScrollVelocity(
  options: UseScrollVelocityOptions = {},
): { current: ScrollVelocity } {
  const { reference = 1500, smoothing = 0.0001, target = null } = options;

  const state = useRef<ScrollVelocity>({
    velocity: 0,
    normalized: 0,
    direction: 0,
    scroll: 0,
  });
  const last = useRef<number | null>(null);
  const raw = useRef(0);

  useRaf((dt) => {
    if (typeof window === 'undefined' || dt <= 0) return;

    const scroll = target ? target.scrollTop : window.scrollY;
    const previous = last.current;
    last.current = scroll;

    // First frame has no previous sample; a delta against 0 would read as a
    // full-page jump on any deep link.
    if (previous === null) {
      state.current.scroll = scroll;
      return;
    }

    const instant = (scroll - previous) / dt;
    // Stage 1: low-pass the instantaneous value so wheel steps stop ringing.
    raw.current = damp(raw.current, instant, 0.01, dt);
    // Stage 2: the value consumers read, softer again.
    const velocity = damp(state.current.velocity, raw.current, smoothing, dt);

    state.current = {
      velocity,
      normalized: clamp(velocity / reference, -1, 1),
      direction: Math.abs(velocity) < 1 ? 0 : Math.sign(velocity),
      scroll,
    };
  });

  return state;
}