Pre-Scatter Horizontal Gallery

'use client';

import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
import { useEffect, useRef, useState, type ReactNode, type RefObject } from 'react';
import {
  PinnedHorizontalTrack,
  type PinnedTrack,
} from '@/components/motion/pinned-horizontal-track';
import { useReducedMotion } from '@/hooks/use-reduced-motion';
import { createRng } from '@/lib/prng';
import { cn } from '@/lib/utils';

/* ==========================================================================
   Pre-Scatter Horizontal Gallery
   --------------------------------------------------------------------------
   A pinned strip of media where nothing is quite on the grid. Each item sits
   at a small seeded horizontal offset from its slot, and as the strip travels
   it flies in from ahead and peels away behind — rotating through zero on the
   way past, so the whole gallery reads as one continuous drift rather than a
   sequence of arrivals.

   Two ideas do the work.

   The first is that the offsets are seeded, not random. `Math.random()` here
   would put the composition somewhere different on every reload, so a visual
   regression is invisible and the server and client disagree at hydration.

   The second is that every offset is a PERCENTAGE of the item's own width.
   The source measured its scatter in pixels off the container width, which
   has to be re-measured on every resize or the composition creeps. `xPercent`
   resolves against the element itself, so a resize moves nothing and there is
   nothing to invalidate.

   Position keywords are horizontal — `left 110%`, `right -10%` — because a
   trigger with a `containerAnimation` measures along the container's axis.
   Vertical keywords produce no error, no warning, and no animation.
   ========================================================================== */

if (typeof window !== 'undefined') {
  gsap.registerPlugin(ScrollTrigger);
}

export interface PrescatterHorizontalGalleryProps {
  /** Panels. Give each a width and `shrink-0`; mark the media `data-scatter`. */
  children: ReactNode;
  /** The scroll container the triggers read. Omit to use the document. */
  scroller?: RefObject<HTMLElement | null>;
  /** Anything hashable. The same seed always rebuilds the same composition. */
  seed?: number | string;
  /** Total resting spread, as a percentage of each item's own width. */
  scatter?: number;
  /** Peak tilt in degrees, alternating by index. */
  rotation?: number;
  /** Vertical throw as a percentage of item height, alternating by index. */
  lift?: number;
  /** Horizontal lag and lead as a percentage of item width. */
  sweep?: number;
  /** Seconds of catch-up on the strip itself. */
  scrub?: number;
  className?: string;
  trackClassName?: string;
}

// #region critical
/**
 * The item's leading edge crosses the container from just off the right
 * (110%) to two thirds in (65%), and its trailing edge leaves from a third in
 * (35%) to just past the left (-10%). The two ranges cannot overlap for any
 * item narrower than 1.3 containers, so every item gets a settled window in
 * the middle where it is simply itself.
 */
const ENTER_START = 'left 110%';
const ENTER_END = 'left 65%';
const EXIT_START = 'right 35%';
const EXIT_END = 'right -10%';

export function PrescatterHorizontalGallery({
  children,
  scroller,
  seed = 'gallery',
  scatter = 32,
  rotation = 40,
  lift = 150,
  sweep = 400,
  scrub = 1,
  className,
  trackClassName,
}: PrescatterHorizontalGalleryProps) {
  const root = useRef<HTMLDivElement>(null);
  // The strip's tween is built in a child's effect, so it arrives one commit
  // late. State, not a ref: the arrival has to re-run the builder below.
  const [track, setTrack] = useState<PinnedTrack | null>(null);
  const reduced = useReducedMotion();

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

    const containerAnimation = track?.animation;
    const scrollerEl = scroller?.current ?? undefined;

    const ctx = gsap.context(() => {
      const targets = Array.from(rootEl.querySelectorAll<HTMLElement>('[data-scatter]'));
      const rng = createRng(seed);

      targets.forEach((el, i) => {
        // Drawn for every item whether or not it animates, so adding motion
        // never shifts the resting composition.
        const rest = (rng() - 0.5) * scatter;
        // Parity, not the generator: alternating up/down and cw/ccw is a
        // rhythm, and a random sign clumps three the same way and looks broken.
        const dir = i % 2 === 0 ? 1 : -1;

        gsap.set(el, { xPercent: rest });
        // The resting scatter is layout. Under reduced motion the composition
        // survives and only the flight is dropped.
        if (reduced || !containerAnimation) return;

        gsap.fromTo(
          el,
          { xPercent: rest + sweep, yPercent: dir * lift, rotation: dir * rotation },
          {
            xPercent: rest,
            yPercent: 0,
            rotation: 0,
            ease: 'none',
            scrollTrigger: {
              trigger: el,
              scroller: scrollerEl,
              containerAnimation,
              start: ENTER_START,
              end: ENTER_END,
              // `true`, not a number. The strip already scrubs with catch-up,
              // and these triggers read the strip's progress rather than the
              // scrollbar, so they inherit that smoothing. A second scrub
              // value smooths the smoothed signal and the items swim.
              scrub: true,
            },
          },
        );

        gsap.fromTo(
          el,
          { xPercent: rest, yPercent: 0, rotation: 0 },
          {
            xPercent: rest - sweep,
            yPercent: -dir * lift,
            rotation: -dir * rotation,
            ease: 'none',
            // The single most important line here. A `fromTo` renders its
            // from-state at creation, so without this the exit immediately
            // overwrites the entry's from-state — every item starts on the
            // grid instead of off-stage, and the entry appears not to exist.
            immediateRender: false,
            scrollTrigger: {
              trigger: el,
              scroller: scrollerEl,
              containerAnimation,
              start: EXIT_START,
              end: EXIT_END,
              scrub: true,
            },
          },
        );
      });
    }, rootEl);

    return () => ctx.revert();
  }, [track, scroller, seed, scatter, rotation, lift, sweep, reduced]);
  // #endregion critical

  return (
    <div ref={root} className={cn('relative h-full w-full', className)}>
      <PinnedHorizontalTrack
        scroller={scroller}
        scrub={scrub}
        // `null` on teardown, so the builder above drops a reverted tween
        // instead of handing it to a new set of triggers.
        onTrack={setTrack}
        trackClassName={trackClassName}
      >
        {children}
      </PinnedHorizontalTrack>
    </div>
  );
}

'use client';

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

/* ==========================================================================
   Pinned Horizontal Track
   --------------------------------------------------------------------------
   Vertical scroll drives horizontal travel. One element is pinned, a strip
   inside it translates on x, and the pin lasts exactly as many scroll pixels
   as the strip has to travel — so one wheel notch moves the track by the
   same distance it would have moved the page.

   The whole construction rests on one measurement, `scrollWidth -
   clientWidth`, and the only way to get it wrong is to take it once. Fonts
   swap after first paint, images decode late, the container resizes: every
   one of those changes the number. It is therefore read through a function
   that ScrollTrigger re-invokes on refresh, for both the tween target and
   the pin duration, so the two can never disagree.
   ========================================================================== */

// Registering twice is a no-op inside GSAP, but module evaluation also
// happens during prerender, where ScrollTrigger has no document to measure.
if (typeof window !== 'undefined') {
  gsap.registerPlugin(ScrollTrigger);
}

/** Handed to the parent so sibling systems can drive off the same pin. */
export interface PinnedTrack {
  /** The x tween. Pass as `containerAnimation` to reveal triggers. */
  animation: gsap.core.Tween;
  /** The pin itself. `trigger.end - trigger.start` is the scroll span. */
  trigger: ScrollTrigger;
  /** Live horizontal travel in px. Re-measured on call, never cached. */
  getDistance: () => number;
}

export interface PinnedHorizontalTrackProps {
  /** Panels. Give them a width and `shrink-0`; the track is a flex row. */
  children: ReactNode;
  /**
   * The scroll container the trigger reads. Omit to use the document.
   * Required whenever the component lives inside its own scroll box.
   */
  scroller?: RefObject<HTMLElement | null>;
  /** Seconds of catch-up. 0 locks to the scrollbar, 1 glides behind it. */
  scrub?: number;
  /** Receives the tween and trigger on build, `null` on teardown. */
  onTrack?: (track: PinnedTrack | null) => void;
  className?: string;
  trackClassName?: string;
}

// #region critical
export function PinnedHorizontalTrack({
  children,
  scroller,
  scrub = 1,
  onTrack,
  className,
  trackClassName,
}: PinnedHorizontalTrackProps) {
  const root = useRef<HTMLDivElement>(null);
  const track = useRef<HTMLDivElement>(null);
  const onTrackRef = useRef(onTrack);
  onTrackRef.current = onTrack;
  const reduced = useReducedMotion();

  useEffect(() => {
    const rootEl = root.current;
    const trackEl = track.current;
    if (!rootEl || !trackEl || reduced) return;

    // `undefined` means "the document" to ScrollTrigger. Passing `null` would
    // be read as an explicit scroller and throw on the first refresh.
    const scrollerEl = scroller?.current ?? undefined;

    // The single source of truth. Both the tween's end value and the pin's
    // duration call it, so a refresh that changes one changes the other.
    const distanceOf = () => Math.max(0, trackEl.scrollWidth - rootEl.clientWidth);

    let cancelled = false;

    const ctx = gsap.context(() => {
      const animation = gsap.to(trackEl, {
        // Function-based value: re-evaluated by `invalidateOnRefresh`.
        x: () => -distanceOf(),
        ease: 'none',
        scrollTrigger: {
          trigger: rootEl,
          scroller: scrollerEl,
          pin: true,
          anticipatePin: 1,
          scrub,
          start: 'top top',
          // 1 px of scroll buys 1 px of track. Expressing the end as a
          // percentage of viewport height instead makes the mapping depend
          // on window shape, and the track finishes early on a short screen.
          end: () => `+=${Math.max(1, distanceOf())}`,
          invalidateOnRefresh: true,
        },
      });

      const trigger = animation.scrollTrigger;
      if (trigger) {
        onTrackRef.current?.({ animation, trigger, getDistance: distanceOf });
      }
    }, rootEl);

    // The most-forgotten line in scroll-driven layout. A font swap changes
    // `scrollWidth` after the pin has already been measured, and the last
    // panel becomes unreachable because the pin ends before the track does.
    void document.fonts?.ready.then(() => {
      if (!cancelled) ScrollTrigger.refresh();
    });

    return () => {
      cancelled = true;
      onTrackRef.current?.(null);
      // revert(), not kill(): it also removes the pin-spacer GSAP injected
      // into the DOM and restores the inline transform on the strip.
      ctx.revert();
    };
  }, [scroller, scrub, reduced]);
  // #endregion critical

  return (
    <div
      ref={root}
      className={cn(
        'relative h-full w-full overflow-hidden',
        // Reduced motion keeps every panel reachable — by thumb, trackpad
        // and keyboard — instead of stranding them behind a dead pin.
        reduced && 'overflow-x-auto',
        className,
      )}
    >
      <div
        ref={track}
        className={cn('flex h-full items-stretch will-change-transform', trackClassName)}
      >
        {children}
      </div>
    </div>
  );
}

/* ==========================================================================
   Seeded randomness.
   --------------------------------------------------------------------------
   `Math.random()` in a particle field means the server and the client
   disagree, which React reports as a hydration mismatch, and it means the
   layout is different on every reload so a visual regression is invisible.
   Every component that scatters something uses a seeded generator instead.
   ========================================================================== */

export type Rng = () => number;

/**
 * mulberry32 — 32-bit, fast, and good enough for visual scatter. Returns a
 * function yielding floats in [0, 1).
 */
export function mulberry32(seed: number): Rng {
  let a = seed >>> 0;
  return function next() {
    a = (a + 0x6d2b79f5) >>> 0;
    let t = a;
    t = Math.imul(t ^ (t >>> 15), t | 1);
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

/** Turn any string into a 32-bit seed, so `seed="hero"` is reproducible. */
export function hashSeed(input: string): number {
  let h = 2166136261 >>> 0;
  for (let i = 0; i < input.length; i++) {
    h ^= input.charCodeAt(i);
    h = Math.imul(h, 16777619);
  }
  return h >>> 0;
}

export function createRng(seed: number | string): Rng {
  return mulberry32(typeof seed === 'string' ? hashSeed(seed) : seed);
}

export function randRange(rng: Rng, min: number, max: number): number {
  return min + rng() * (max - min);
}

export function randInt(rng: Rng, min: number, maxExclusive: number): number {
  return Math.floor(randRange(rng, min, maxExclusive));
}

/**
 * Uniform point on a unit sphere. Naive angle-pairing clusters at the poles;
 * this inverts the cosine so density is even.
 */
export function randOnSphere(rng: Rng): [number, number, number] {
  const u = rng() * 2 - 1;
  const theta = rng() * Math.PI * 2;
  const r = Math.sqrt(1 - u * u);
  return [r * Math.cos(theta), r * Math.sin(theta), u];
}

/** Uniform point in a unit disc — `sqrt` prevents crowding at the centre. */
export function randInDisc(rng: Rng): [number, number] {
  const r = Math.sqrt(rng());
  const theta = rng() * Math.PI * 2;
  return [r * Math.cos(theta), r * Math.sin(theta)];
}

/** In-place Fisher-Yates using the supplied generator. */
export function shuffle<T>(rng: Rng, arr: T[]): T[] {
  for (let i = arr.length - 1; i > 0; i--) {
    const j = randInt(rng, 0, i + 1);
    const a = arr[i] as T;
    const b = arr[j] as T;
    arr[i] = b;
    arr[j] = a;
  }
  return arr;
}

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