Scrub Timeline Spine

'use client';

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

/* ==========================================================================
   Scrub Timeline Spine
   --------------------------------------------------------------------------
   A vertical rule that fills as you scroll, with entries alternating either
   side of it. Two ideas make it work and both are easy to get wrong.

   1. Entries rest at 50% opacity, not 0. The animation adds emphasis to
      content that is already legible, rather than gating it behind a scroll
      event. The page still reads with JavaScript disabled and a screen
      reader never meets an invisible entry.

   2. `toggleActions: "play reverse play reverse"` — the four slots are
      onEnter, onLeave, onEnterBack, onLeaveBack. The usual
      "play none none none" fires once and never reverts, so scrolling back
      up shows a column of already-finished animations. Reversing on the way
      out makes the whole spine scrubbable in both directions.
   ========================================================================== */

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

export interface SpineEntry {
  /** Date, phase, or index. Rendered in the metadata voice. */
  label: string;
  title: string;
  body?: string;
}

export interface ScrubTimelineSpineProps {
  entries: SpineEntry[];
  /** Seconds of catch-up on the fill. */
  scrub?: number;
  /** Resting opacity of an inactive entry. Never 0 — see notes. */
  restOpacity?: number;
  /** Resting scale of an inactive entry. */
  restScale?: number;
  /** Seconds for one entry to come to full emphasis. */
  entryDuration?: number;
  fillStart?: string;
  fillEnd?: string;
  entryStart?: string;
  /** Container width, in px, below which entries stop alternating. */
  alternateAbove?: number;
  /** The scroll container that owns the scroll position. Omit for the document. */
  scrollerRef?: RefObject<HTMLElement | null>;
  className?: string;
}

// #region critical
export function ScrubTimelineSpine({
  entries,
  scrub = 0.6,
  restOpacity = 0.5,
  restScale = 0.9,
  entryDuration = 0.6,
  fillStart = 'top 55%',
  fillEnd = 'bottom 75%',
  entryStart = 'top 78%',
  alternateAbove = 420,
  scrollerRef,
  className,
}: ScrubTimelineSpineProps) {
  const root = useRef<HTMLDivElement>(null);
  const fill = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();
  const { width } = useResizeObserver(root);
  const alternate = width >= alternateAbove;

  useGsap(
    gsap,
    () => {
      const container = root.current;
      const line = fill.current;
      if (!container || !line) return;

      const items = Array.from(container.querySelectorAll<HTMLElement>('[data-spine-entry]'));
      const scroller = scrollerRef?.current ?? undefined;

      if (reduced) {
        gsap.set(line, { scaleY: 1 });
        gsap.set(items, { opacity: 1, scale: 1 });
        return;
      }

      gsap.fromTo(
        line,
        { scaleY: 0 },
        {
          scaleY: 1,
          ease: 'none',
          // transformOrigin is set in CSS too, but GSAP writes its own
          // transform string; without stating it here the fill grows from the
          // centre and the rule appears to unroll in both directions.
          transformOrigin: 'top center',
          scrollTrigger: {
            trigger: container,
            scroller,
            // Starts filling once the section is just past halfway up and
            // completes before its bottom leaves — so the rule is never still
            // filling while the last entry is already being read.
            start: fillStart,
            end: fillEnd,
            scrub,
            invalidateOnRefresh: true,
          },
        },
      );

      items.forEach((item, i) => {
        gsap.fromTo(
          item,
          { opacity: restOpacity, scale: restScale },
          {
            opacity: 1,
            scale: 1,
            duration: entryDuration,
            ease: 'power2.out',
            // Scale from the edge the entry hangs off, so it grows outward
            // from the spine. A centre origin pulls both columns toward the
            // middle and the rule looks like it is being squeezed.
            transformOrigin: alternate && i % 2 === 1 ? 'right center' : 'left center',
            scrollTrigger: {
              trigger: item,
              scroller,
              start: entryStart,
              // onEnter, onLeave, onEnterBack, onLeaveBack. Reversing on the
              // way out is what makes the column scrubbable upward as well as
              // downward.
              toggleActions: 'play reverse play reverse',
            },
          },
        );
      });
    },
    root,
    [
      scrub,
      restOpacity,
      restScale,
      entryDuration,
      fillStart,
      fillEnd,
      entryStart,
      alternate,
      reduced,
      entries.length,
    ],
  );
  // #endregion critical

  return (
    <div ref={root} className={cn('relative', className)}>
      {/* Track and fill are two elements: the track is the faint full-height
          rule that tells you how much is left, the fill is the scaled one. */}
      <div
        aria-hidden
        className={cn(
          'absolute top-0 h-full w-px bg-line',
          alternate ? 'left-1/2 -translate-x-1/2' : 'left-1',
        )}
      />
      <div
        ref={fill}
        aria-hidden
        className={cn(
          'absolute top-0 h-full w-px origin-top bg-accent',
          alternate ? 'left-1/2 -translate-x-1/2' : 'left-1',
        )}
        style={{ transform: 'scaleY(0)' }}
      />

      <ol className="relative flex flex-col gap-6">
        {entries.map((entry, i) => {
          const right = alternate && i % 2 === 1;
          return (
            <li
              key={entry.label + entry.title}
              className={cn(
                'flex',
                alternate ? 'w-1/2' : 'ml-6 w-full',
                right && 'self-end justify-start pl-6',
                alternate && !right && 'justify-end pr-6 text-right',
              )}
            >
              <div
                data-spine-entry
                className="w-full rounded-md border border-line bg-surface p-3 will-change-transform"
                style={{ opacity: restOpacity }}
              >
                <p className="meta">{entry.label}</p>
                <h3 className="mt-1.5 text-sm leading-snug tracking-tight text-fg">
                  {entry.title}
                </h3>
                {entry.body !== undefined && (
                  <p className="mt-1 text-xs leading-relaxed text-muted">{entry.body}</p>
                )}
              </div>
            </li>
          );
        })}
      </ol>
    </div>
  );
}

'use client';

import { useEffect, useRef, type DependencyList, type RefObject } from 'react';

/* ==========================================================================
   gsap.context() with the teardown wired up.
   --------------------------------------------------------------------------
   Every animation, ScrollTrigger and SplitText created inside the callback is
   recorded by the context and killed by `ctx.revert()`. `revert()` — not
   `kill()` — is the one that also restores inline styles GSAP wrote, which is
   what stops a component from unmounting mid-tween and leaving a stray
   `transform` on a DOM node that React then reuses.

   Under React 19 StrictMode every effect runs twice in development. Without a
   context that reverts, you get two ScrollTriggers on the same element, each
   scrubbing the same property, and a 2x-speed animation that only reproduces
   in dev.
   ========================================================================== */

type ContextFunc = (context: {
  add: (fn: () => void) => void;
  [key: string]: unknown;
}) => void | (() => void);

interface GsapLike {
  context: (
    fn: ContextFunc,
    scope?: Element | string | object,
  ) => { revert: () => void };
}

/**
 * Runs `callback` inside a `gsap.context()` scoped to `scope`, reverting on
 * unmount and whenever `deps` change.
 *
 * `gsap` is passed in rather than imported so this hook carries no dependency
 * of its own — the component that animates is the one that imports GSAP.
 */
export function useGsap(
  gsap: GsapLike,
  callback: ContextFunc,
  scope: RefObject<Element | null>,
  deps: DependencyList = [],
): void {
  const callbackRef = useRef(callback);
  callbackRef.current = callback;

  useEffect(() => {
    const el = scope.current;
    if (!el) return;

    const ctx = gsap.context((self) => callbackRef.current(self), el);
    return () => ctx.revert();
    // `callback` is deliberately excluded: it is held in a ref so callers do
    // not have to memoise it. Re-run by changing `deps`.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [gsap, scope, ...deps]);
}

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