Converging Flow Steps

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

/* ==========================================================================
   Converging Flow Steps
   --------------------------------------------------------------------------
   A process diagram that assembles itself. The outer cards converge from
   opposite ends toward the middle, and the connectors between them pop in
   *after* the cards have already started moving — at 35% through the
   timeline. That ordering is the whole effect: connectors that arrive first,
   or at the same time, read as "here are some boxes with arrows". Connectors
   that arrive once the boxes are in motion read as "these things connect".

   `scrub: 1.2` is unusually slow, and correct for a diagram: you want it to
   settle into place rather than track your wheel.
   ========================================================================== */

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

export interface FlowStep {
  title: string;
  body?: string;
  /** Short label above the title — a number, a phase name. */
  kicker?: string;
}

export interface ConvergingFlowStepsProps {
  steps: FlowStep[];
  /** Outer-card travel as a percentage of its own size, along the layout axis. */
  converge?: number;
  /** Seconds of catch-up. Deliberately high — this is a diagram, not a hero. */
  scrub?: number;
  /** Timeline position, in seconds, at which the connectors begin. */
  connectorAt?: number;
  /** Seconds between connectors. */
  connectorStagger?: number;
  /** Container width, in px, below which the row becomes a column. */
  stackBelow?: number;
  start?: string;
  end?: string;
  /** The scroll container that owns the scroll position. Omit for the document. */
  scrollerRef?: RefObject<HTMLElement | null>;
  className?: string;
}

// #region critical
const CONNECTOR_SCALE = 0.6;

export function ConvergingFlowSteps({
  steps,
  converge = 14,
  scrub = 1.2,
  connectorAt = 0.35,
  connectorStagger = 0.2,
  stackBelow = 420,
  start = 'top 92%',
  end = 'center 52%',
  scrollerRef,
  className,
}: ConvergingFlowStepsProps) {
  const root = useRef<HTMLDivElement>(null);
  const reduced = useReducedMotion();
  const { width } = useResizeObserver(root);

  // The convergence axis has to follow the layout axis, or a stacked column
  // gets cards sliding in sideways past each other. Measured from the element
  // rather than the viewport: this component is often inside a panel that is
  // narrow while the window is wide.
  const stacked = width > 0 && width < stackBelow;

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

      const cards = Array.from(container.querySelectorAll<HTMLElement>('[data-flow-card]'));
      const connectors = Array.from(
        container.querySelectorAll<HTMLElement>('[data-flow-connector]'),
      );
      const first = cards[0];
      const last = cards[cards.length - 1];
      if (!first || !last) return;

      const axis = stacked ? 'yPercent' : 'xPercent';
      const tl = gsap.timeline({
        scrollTrigger: {
          trigger: container,
          scroller: scrollerRef?.current ?? undefined,
          start,
          end,
          scrub,
          invalidateOnRefresh: true,
        },
      });

      // Outer cards travel toward the centre from opposite ends. When there is
      // only one card, `first === last` and the two tweens would fight over
      // the same target, so it takes the middle treatment instead.
      if (first === last) {
        tl.fromTo(first, { autoAlpha: 0 }, { autoAlpha: 1, ease: 'none', duration: 1 }, 0);
      } else {
        tl.fromTo(
          first,
          { autoAlpha: 0, [axis]: -converge },
          { autoAlpha: 1, [axis]: 0, ease: 'none', duration: 1 },
          0,
        );
        tl.fromTo(
          last,
          { autoAlpha: 0, [axis]: converge },
          { autoAlpha: 1, [axis]: 0, ease: 'none', duration: 1 },
          0,
        );
      }

      // Everything between the ends has nowhere to converge from, so it only
      // fades. Giving it a direction too would make the row look like it was
      // being shuffled rather than closing.
      const middle = cards.slice(1, -1);
      if (middle.length > 0) {
        tl.fromTo(middle, { autoAlpha: 0 }, { autoAlpha: 1, ease: 'none', duration: 1 }, 0);
      }

      if (connectors.length > 0) {
        tl.fromTo(
          connectors,
          { autoAlpha: 0, scale: CONNECTOR_SCALE },
          {
            autoAlpha: 1,
            scale: 1,
            ease: 'none',
            duration: 1 - connectorAt,
            stagger: connectorStagger,
          },
          // Absolute timeline position in seconds. The cards occupy 0 -> 1, so
          // 0.35 puts the first connector a third of the way into their
          // travel: they are already moving when the link appears.
          connectorAt,
        );
      }
    },
    root,
    [converge, scrub, connectorAt, connectorStagger, start, end, stacked, reduced, steps.length],
  );
  // #endregion critical

  return (
    <div
      ref={root}
      className={cn(
        'flex items-stretch gap-2 rounded-lg bg-accent/8 p-4',
        stacked ? 'flex-col' : 'flex-row',
        className,
      )}
    >
      {/* `display: contents` on the wrapper keeps each card and its connector
          as direct flex items of the row while still sharing one React key. */}
      {steps.map((step, i) => (
        <div key={step.title} className="contents">
          {i > 0 && (
            <div
              data-flow-connector
              aria-hidden
              className="flex shrink-0 items-center justify-center text-accent"
            >
              <svg
                viewBox="0 0 24 24"
                className={cn('h-4 w-4', stacked && 'rotate-90')}
                fill="none"
                stroke="currentColor"
                strokeWidth="1.5"
                strokeLinecap="square"
              >
                <path d="M4 12h15M13 6l6 6-6 6" />
              </svg>
            </div>
          )}
          <div
            data-flow-card
            className="min-w-0 flex-1 rounded-md border border-line bg-surface p-3 will-change-transform"
          >
            {step.kicker !== undefined && <p className="meta">{step.kicker}</p>}
            <h3 className="mt-1.5 text-sm leading-snug tracking-tight text-fg">{step.title}</h3>
            {step.body !== undefined && (
              <p className="mt-1 text-xs leading-relaxed text-muted">{step.body}</p>
            )}
          </div>
        </div>
      ))}
    </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;
}