Perspective Coverflow Scroller

'use client';

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

/* ==========================================================================
   Perspective Coverflow Scroller
   --------------------------------------------------------------------------
   Real 3D, driven by a real scrollbar. The browser owns the position: momentum,
   rubber-banding, trackpad physics, shift+wheel, keyboard paging and snapping
   are all native. This component never animates the scroll — it only reads
   `scrollLeft` and writes a transform per panel.

   That is the architectural difference from a JS-position carousel. There is
   no tween, no rAF loop that runs while idle, and no state to desynchronise:
   if the panel positions are right for a given `scrollLeft`, they are right
   for every `scrollLeft`.
   ========================================================================== */

export interface PerspectiveCoverflowScrollerProps {
  /** One panel per child. Each is wrapped in a snap-aligned cell. */
  children: ReactNode;
  /** Per-element perspective in px. Lower = more extreme foreshortening. */
  perspective?: number;
  /** Degrees of `rotateY` at the clamp. */
  rotation?: number;
  /** Pixels of `translateZ` at the clamp. Always negative in effect. */
  depth?: number;
  /** How much a panel shrinks at one half-width from centre. */
  scaleFalloff?: number;
  /** How much a panel fades at one half-width from centre. */
  opacityFalloff?: number;
  /** Clamp on the normalised offset. Past this, panels stop turning further. */
  maxOffset?: number;
  /** Which panel is centred on mount. Defaults to the middle of the set. */
  initialIndex?: number;
  className?: string;
  /** Applied to each snap cell — size the panels here. */
  panelClassName?: string;
  'aria-label'?: string;
}

const SNAP_ALIGN_CENTER = 'center';

export function PerspectiveCoverflowScroller({
  children,
  perspective = 1300,
  rotation = 40,
  depth = 130,
  scaleFalloff = 0.12,
  opacityFalloff = 0.35,
  maxOffset = 1.2,
  initialIndex,
  className,
  panelClassName,
  'aria-label': ariaLabel = 'Gallery',
}: PerspectiveCoverflowScrollerProps) {
  const scrollerRef = useRef<HTMLDivElement>(null);
  const trackRef = useRef<HTMLDivElement>(null);
  const panelsRef = useRef<Array<HTMLDivElement | null>>([]);
  /** Layout centre of each panel, in track coordinates. Scroll-independent. */
  const centresRef = useRef<number[]>([]);
  const centredRef = useRef(false);

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

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

  // #region critical
  /**
   * Cache each panel's layout centre and pad the track so the first and last
   * panel can reach the middle of the viewport.
   *
   * `offsetLeft`/`offsetWidth` are *layout* values: unaffected by `scrollLeft`
   * and, critically, unaffected by the transforms this component writes.
   * Reading `getBoundingClientRect()` in the scroll handler instead would feed
   * each panel's own `scale()` back into the next frame's offset.
   */
  const measure = useCallback(() => {
    const scroller = scrollerRef.current;
    const track = trackRef.current;
    if (!scroller || !track) return;

    const panels = panelsRef.current;
    const first = panels[0];
    const last = panels[count - 1];

    // Half a viewport minus half a panel. The source of this technique used a
    // fixed `24vw`, which is wrong for any panel that is not ~52vw wide and
    // wrong for every container that is not the viewport.
    if (first) {
      track.style.paddingLeft = `${Math.max(0, (scroller.clientWidth - first.offsetWidth) / 2)}px`;
    }
    if (last) {
      track.style.paddingRight = `${Math.max(0, (scroller.clientWidth - last.offsetWidth) / 2)}px`;
    }

    // Read after the padding write: the padding moves every offsetLeft.
    centresRef.current = panels.map((panel) =>
      panel ? panel.offsetLeft + panel.offsetWidth / 2 : 0,
    );
  }, [count]);

  /** Write one transform per panel from the current scroll position. */
  const update = useCallback(() => {
    const scroller = scrollerRef.current;
    if (!scroller) return;

    const half = scroller.clientWidth / 2 || 1;
    const scroll = scroller.scrollLeft;
    const panels = panelsRef.current;
    const centres = centresRef.current;

    for (let i = 0; i < panels.length; i += 1) {
      const panel = panels[i];
      const centre = centres[i];
      if (!panel || centre === undefined) continue;

      if (reduced) {
        panel.style.transform = '';
        panel.style.opacity = '';
        continue;
      }

      // Signed, normalised distance from the viewport centre: -1 = one half
      // width to the left, +1 = one half width to the right.
      const r = clamp((centre - scroll - half) / half, -maxOffset, maxOffset);
      const away = Math.abs(r);

      // Perspective lives *in the transform*, not on the parent. A shared
      // parent perspective gives every panel the same vanishing point, so
      // edge panels skew as well as rotate; per-element perspective turns each
      // panel about its own centre, which is the coverflow look.
      panel.style.transform =
        `perspective(${perspective}px) ` +
        `translateZ(${(-depth * away).toFixed(1)}px) ` +
        `rotateY(${(-rotation * r).toFixed(2)}deg) ` +
        `scale(${(1 - scaleFalloff * Math.min(away, 1)).toFixed(3)})`;

      // Two different clamps on purpose: scale bottoms out at 1, opacity keeps
      // going to `maxOffset`. Distant panels stay proportionate while fading.
      panel.style.opacity = (1 - opacityFalloff * Math.min(away, maxOffset)).toFixed(2);
    }
  }, [reduced, perspective, rotation, depth, scaleFalloff, opacityFalloff, maxOffset]);

  useEffect(() => {
    const scroller = scrollerRef.current;
    if (!scroller) return;

    measure();

    // Start centred on a panel, not on the midpoint of the scroll range: with
    // an even count the midpoint falls in the gap between two panels and the
    // component opens looking like nothing is selected.
    if (!centredRef.current && count > 0) {
      const target = initialIndex ?? Math.floor((count - 1) / 2);
      const centre = centresRef.current[clamp(Math.round(target), 0, count - 1)];
      if (centre !== undefined) {
        scroller.scrollLeft = centre - scroller.clientWidth / 2;
      }
      centredRef.current = true;
    }

    update();

    let frame = 0;
    const onScroll = () => {
      // Coalesce: a trackpad fires `scroll` far more often than the compositor
      // paints, and each handler run writes N transforms.
      if (frame !== 0) return;
      frame = requestAnimationFrame(() => {
        frame = 0;
        update();
      });
    };

    scroller.addEventListener('scroll', onScroll, { passive: true });

    return () => {
      scroller.removeEventListener('scroll', onScroll);
      if (frame !== 0) cancelAnimationFrame(frame);
    };
  }, [measure, update, count, initialIndex]);
  // #endregion critical

  // The track's content box changes when a web font swaps or a child resizes,
  // and neither fires `scroll` or a window `resize`. Observing the track is the
  // deterministic replacement for the usual "recompute at 300 ms and 1000 ms".
  useEffect(() => {
    const track = trackRef.current;
    if (!track || typeof ResizeObserver === 'undefined') return;
    const observer = new ResizeObserver(() => {
      measure();
      update();
    });
    observer.observe(track);
    return () => observer.disconnect();
  }, [measure, update]);

  useEffect(() => {
    measure();
    update();
  }, [measure, update, size.width, size.height]);

  return (
    <div
      ref={scrollerRef}
      role="region"
      aria-label={ariaLabel}
      tabIndex={0}
      className={cn(
        'h-full w-full overflow-x-auto overflow-y-hidden',
        '[-ms-overflow-style:none] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden',
        'focus-visible:outline-none',
        className,
      )}
      style={{ scrollSnapType: 'x proximity' }}
    >
      <div ref={trackRef} className="flex h-full w-max items-center gap-4 md:gap-8">
        {items.map((child, i) => (
          <div
            key={isValidElement(child) && child.key !== null ? child.key : i}
            ref={(node) => {
              panelsRef.current[i] = node;
            }}
            className={cn('shrink-0 will-change-transform', panelClassName)}
            style={{ scrollSnapAlign: SNAP_ALIGN_CENTER }}
          >
            {child}
          </div>
        ))}
      </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 { 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;
}