Inverse Scroll Scale

'use client';

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

/* ==========================================================================
   Inverse Scroll Scale
   --------------------------------------------------------------------------
   The usual scroll-scale grows an image as it rises. This one shrinks it:
   the media starts oversized at 1.25x and settles to exactly 1.0 as its top
   edge climbs through the first 60% of the scroller. It resolves *into* its
   frame instead of bursting out of it.

   Two details carry the whole effect.

   1. The 0.6 divisor. Scaling over the full viewport height means the image
      is still moving while you are already reading it. Finishing at 60%
      means it is at rest for the entire time it is the thing you are
      looking at — the motion is an arrival, not an ongoing state.

   2. It lands on exactly 1.0, so the frame is filled by construction. Any
      scale below 1 on an element sized to its frame would show a seam, so
      `from` must be >= 1 and the end of the ramp must be the identity.

   No GSAP. One rAF callback, gated by an IntersectionObserver so an
   off-screen instance costs nothing, and one transform write per frame.
   ========================================================================== */

export interface InverseScrollScaleProps {
  /** The media. Sized to fill the frame; it is what gets scaled. */
  children: ReactNode;
  /** Starting scale. Must be >= 1 or the frame shows through at the edges. */
  from?: number;
  /**
   * Fraction of the scroller height over which the scale resolves, measured
   * from the bottom edge upward. 0.6 finishes well before the top.
   */
  span?: number;
  /**
   * Fraction of the remaining gap left after one second. 0 writes the scroll
   * position straight through, which is the sharp, correct default.
   */
  smoothing?: number;
  /** The scroll container that owns the scroll position. Omit for the document. */
  scrollerRef?: RefObject<HTMLElement | null>;
  className?: string;
}

// #region critical
export function InverseScrollScale({
  children,
  from = 1.25,
  span = 0.6,
  smoothing = 0,
  scrollerRef,
  className,
}: InverseScrollScaleProps) {
  const frame = useRef<HTMLDivElement>(null);
  const media = useRef<HTMLDivElement>(null);
  const active = useRef(false);
  const scale = useRef(from);
  const written = useRef(-1);
  const reduced = useReducedMotion();

  // Gate the rAF work on visibility. Hand-rolled rather than `useInView`
  // because the observer needs a custom `root` — the demo's own scroller —
  // and a pooled observer keyed only by threshold would hand back one rooted
  // at the document.
  useEffect(() => {
    const el = frame.current;
    if (!el || reduced) return;

    const observer = new IntersectionObserver(
      (entries) => {
        for (const entry of entries) active.current = entry.isIntersecting;
      },
      { root: scrollerRef?.current ?? null, rootMargin: '20% 0px 20% 0px' },
    );
    observer.observe(el);
    return () => observer.disconnect();
  }, [reduced, scrollerRef]);

  useRaf(
    (dt) => {
      const el = frame.current;
      const target = media.current;
      if (!el || !target || !active.current) return;

      // One read pass, then one write pass. Reading the rect after writing a
      // transform in the same frame forces a synchronous layout.
      const scroller = scrollerRef?.current ?? null;
      const rect = el.getBoundingClientRect();
      const height = scroller ? scroller.clientHeight : window.innerHeight;
      const top = scroller ? rect.top - scroller.getBoundingClientRect().top : rect.top;

      // t is 0 while the frame's top edge is at the bottom of the scroller and
      // reaches 1 once it has risen `span` of the scroller's height.
      const t = clamp((height - top) / (span * height), 0, 1);
      const wanted = from - (from - 1) * t;

      scale.current =
        smoothing > 0 ? damp(scale.current, wanted, smoothing, dt) : wanted;

      // Four decimals is below one device pixel on a 4000px element, and the
      // equality check skips the style write on the many frames where nothing
      // changed — an idle instance then costs a rect read and nothing else.
      const next = Number(scale.current.toFixed(4));
      if (next === written.current) return;
      written.current = next;
      target.style.transform = `scale(${next})`;
    },
    !reduced,
  );
  // #endregion critical

  return (
    <div ref={frame} className={cn('relative overflow-hidden', className)}>
      <div
        ref={media}
        className="h-full w-full will-change-transform"
        // Reduced motion renders the resolved state: scale 1, frame filled.
        style={{ transform: `scale(${reduced ? 1 : from})` }}
      >
        {children}
      </div>
    </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,
  );
}