Sticky Deck

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

"use client";

import * as React from "react";
import {
  motion,
  useMotionValue,
  useMotionValueEvent,
  useReducedMotion,
  useScroll,
  useSpring,
  useTransform,
  type MotionValue,
} from "motion/react";

import { cn } from "@/lib/utils";

/* ─────────────────────────────────────────────────────────
 * STICKY DECK STORYBOARD   (driven by scroll, not time)
 *
 *  arrive   a card scrolls up with the page, 1:1, and pins at
 *           `top`. Its travel is native `position: sticky`, so
 *           it never lags the finger or the wheel
 *  cover    the next card's top edge reaches this card's bottom
 *           edge, and this card starts settling back one layer
 *           in step with the next card's travel:
 *             rises `offsetStep`, so its top edge peeks out
 *             scales toward `scaleTo` from that top edge
 *             dims toward `dimTo` brightness
 *           it lands back there the moment the next card pins
 *  deeper   every card already in the deck settles one more
 *           layer at the same time; scale and dim compound
 *  past     beyond `depth` layers a card slides under the one
 *  depth    in front of it and fades out
 *  end      the last card pins and the whole deck holds for
 *           `hold`, then scrolls away together
 *
 *  pointer  over a buried card's edge: it lifts half a step.
 *           Click it and the deck scrolls back to that card
 *  keyboard focus inside a card scrolls the deck to it
 *  reduced  no rise, scale or lift; cards stay sticky and dim
 * ───────────────────────────────────────────────────────── */

const DECK = {
  top: 96, // px from the top of the scrollport to the front card
  offsetStep: 16, // px each buried card peeks out above the one in front
  scaleTo: 0.94, // scale one layer back; compounds per layer
  dimTo: 0.86, // brightness one layer back; compounds per layer
  depth: 3, // layers that stay visible behind the front card
  hold: "20vh", // scroll the finished deck stays pinned before it moves on
  lift: 0.5, // share of offsetStep a buried card rises under the pointer
  buried: 0.5, // layers of cover from which a card's edge is clickable
};

const LIFT_SPRING = { visualDuration: 0.3, bounce: 0.25 };

/** Lets you drive the deck from outside, e.g. a list of steps beside it. */
export interface StickyDeckApi {
  /** Scrolls until this card is at the front of the deck. */
  scrollTo: (index: number) => void;
}

type Geometry = {
  /** Each card's resting (unpinned) top edge, from the deck's border edge, in px. */
  offsets: number[];
  heights: number[];
  /** The cards' `top`, resolved to px. */
  top: number;
};

type Deck = {
  /**
   * Where the deck is, in cards: -1 before the first card arrives, i when card
   * i has just pinned, i + 0.5 when the next card covers half of it.
   */
  position: MotionValue<number>;
  top: number | string;
  offsetStep: number;
  scaleTo: number;
  dimTo: number;
  depth: number;
  reduced: boolean;
  register: (index: number, element: HTMLElement | null) => () => void;
  scrollTo: (index: number) => void;
};

type Card = {
  index: number;
  /** 0 → 1 as the card travels into place; 1 once it pins. */
  progress: MotionValue<number>;
  /** How many cards cover it: 0 at the front, 1 one layer back, fractional in between. */
  depth: MotionValue<number>;
};

const DeckContext = React.createContext<Deck | null>(null);
const IndexContext = React.createContext(-1);
const CardContext = React.createContext<Card | null>(null);

function useDeck() {
  const deck = React.useContext(DeckContext);
  if (!deck) throw new Error("<StickyDeckCard> must be rendered inside <StickyDeck>.");
  return deck;
}

/* ── StickyDeck ─────────────────────────────────────────── */

export interface StickyDeckProps extends React.HTMLAttributes<HTMLDivElement> {
  /**
   * Where the front card pins, from the top of the scrollport. A number is in
   * px; a string is any CSS length. Leave room above it for the edges that
   * peek out: `depth * offsetStep`.
   */
  top?: number | string;
  /** How far each buried card's top edge peeks out above the card in front, in px. */
  offsetStep?: number;
  /** Scale of the card one layer back. Each further layer multiplies it again. */
  scaleTo?: number;
  /** Brightness of the card one layer back, from 0 to 1. Each further layer multiplies it again. */
  dimTo?: number;
  /** How many cards stay visible behind the front one. Deeper cards fade out. */
  depth?: number;
  /**
   * How much more scrolling the finished deck stays pinned for, after the last
   * card lands and the deck's gap passes, before it moves on with the page. A
   * number is in px; a string is any CSS length.
   */
  hold?: number | string;
  /**
   * Scroll container to track. Defaults to the window. Pass it when the deck
   * scrolls inside an `overflow-y-auto` box.
   */
  containerRef?: React.RefObject<HTMLElement | null>;
  /** Called with the index of the front card whenever it changes. */
  onActiveChange?: (index: number) => void;
  /** Receives `{ scrollTo(index) }`, to bring a card to the front from outside the deck. */
  apiRef?: React.Ref<StickyDeckApi>;
}

/**
 * A column of cards that pin one after another as you scroll. Each new card
 * slides over the last while the deck behind it settles back a layer, so the
 * buried cards' top edges peek out above the front one. Give the cards the
 * same height.
 */
export function StickyDeck({
  top = DECK.top,
  offsetStep = DECK.offsetStep,
  scaleTo = DECK.scaleTo,
  dimTo = DECK.dimTo,
  depth = DECK.depth,
  hold = DECK.hold,
  containerRef,
  onActiveChange,
  apiRef,
  className,
  children,
  ...props
}: StickyDeckProps) {
  const rootRef = React.useRef<HTMLDivElement>(null);
  const cardsRef = React.useRef<(HTMLElement | null)[]>([]);
  const geometryRef = React.useRef<Geometry>({ offsets: [], heights: [], top: 0 });
  const observerRef = React.useRef<ResizeObserver | null>(null);
  const reduced = useReducedMotion() ?? false;
  const position = useMotionValue(-1);
  const { scrollY } = useScroll({ container: containerRef });

  const cards = React.Children.toArray(children);
  const count = cards.length;

  /** The top of the scrollport, in viewport px. Null until the container mounts. */
  const viewTop = React.useCallback(() => {
    if (!containerRef) return 0;
    const container = containerRef.current;
    return container ? container.getBoundingClientRect().top + container.clientTop : null;
  }, [containerRef]);

  // Reads the deck's live position, so content shifting above it never leaves
  // the cards out of step. Called on every scroll frame: one or two rect reads.
  const update = React.useCallback(() => {
    const root = rootRef.current;
    const view = viewTop();
    const { offsets, heights, top } = geometryRef.current;
    if (!root || view === null || !offsets.length) return;

    const deckTop = root.getBoundingClientRect().top - view;
    // Card i arrives over the distance of the card it covers: it starts when
    // its top edge meets that card's bottom edge and ends when it pins.
    let next = -1;
    for (let i = 0; i < offsets.length; i++) {
      const span = Math.max(heights[i - 1] ?? heights[i], 1);
      next += clamp((top + span - (deckTop + offsets[i])) / span, 0, 1);
    }
    position.set(next);
  }, [position, viewTop]);

  // Resting positions come from the flex column's own arithmetic. A pinned
  // card's rect (and offsetTop) already includes its sticky shift.
  const measure = React.useCallback(() => {
    const root = rootRef.current;
    const elements = cardsRef.current.filter((element): element is HTMLElement => !!element);
    if (!root || !elements.length) return;

    const deckStyle = getComputedStyle(root);
    const gap = px(deckStyle.rowGap);
    let y = px(deckStyle.borderTopWidth) + px(deckStyle.paddingTop);
    const offsets: number[] = [];
    const heights: number[] = [];
    elements.forEach((element, i) => {
      const style = getComputedStyle(element);
      y += (i ? gap : 0) + px(style.marginTop);
      offsets.push(y);
      heights.push(element.offsetHeight);
      y += element.offsetHeight + px(style.marginBottom);
    });
    geometryRef.current = { offsets, heights, top: px(getComputedStyle(elements[0]).top) };
    update();
  }, [update]);

  const register = React.useCallback(
    (index: number, element: HTMLElement | null) => {
      if (!element) return () => {};
      cardsRef.current[index] = element;
      // Observing reports the size once, which measures the deck again.
      observerRef.current?.observe(element);
      return () => {
        if (cardsRef.current[index] === element) cardsRef.current[index] = null;
        observerRef.current?.unobserve(element);
      };
    },
    [],
  );

  const scrollTo = React.useCallback(
    (index: number) => {
      const root = rootRef.current;
      const view = viewTop();
      const { offsets, top } = geometryRef.current;
      if (!root || view === null || offsets[index] === undefined) return;

      // The card is at the front when its resting top edge sits at `top`.
      const delta = root.getBoundingClientRect().top - view + offsets[index] - top;
      if (Math.abs(delta) < 1) return;
      const behavior = matchMedia("(prefers-reduced-motion: reduce)").matches ? "instant" : "smooth";
      const container = containerRef?.current;
      if (container) container.scrollTo({ top: container.scrollTop + delta, behavior });
      else window.scrollTo({ top: window.scrollY + delta, behavior });
    },
    [containerRef, viewTop],
  );

  React.useImperativeHandle(apiRef, () => ({ scrollTo }), [scrollTo]);

  // Passive effect: by now a parent's containerRef is attached too.
  React.useEffect(() => {
    const root = rootRef.current;
    if (!root) return;
    const observer = new ResizeObserver(() => measure());
    observer.observe(root);
    cardsRef.current.forEach((element) => element && observer.observe(element));
    observerRef.current = observer;
    window.addEventListener("resize", measure);
    measure();
    return () => {
      observer.disconnect();
      observerRef.current = null;
      window.removeEventListener("resize", measure);
    };
  }, [measure]);

  useMotionValueEvent(scrollY, "change", update);

  const activeRef = React.useRef(0);
  useMotionValueEvent(position, "change", (value) => {
    const index = clamp(Math.round(value), 0, Math.max(count - 1, 0));
    if (index === activeRef.current) return;
    activeRef.current = index;
    onActiveChange?.(index);
  });

  const deck = React.useMemo<Deck>(
    () => ({ position, top, offsetStep, scaleTo, dimTo, depth, reduced, register, scrollTo }),
    [position, top, offsetStep, scaleTo, dimTo, depth, reduced, register, scrollTo],
  );

  return (
    <DeckContext.Provider value={deck}>
      <div ref={rootRef} role="list" className={cn("isolate flex flex-col gap-8", className)} {...props}>
        {cards.map((card, index) => (
          <IndexContext.Provider key={React.isValidElement(card) ? card.key : index} value={index}>
            {card}
          </IndexContext.Provider>
        ))}
        {/* Sticky cards stay pinned until the deck's content box ends. Padding
            doesn't extend it and a card's own margin counts against that card,
            so the hold is a spacer. */}
        {hold ? <div aria-hidden className="shrink-0" style={{ height: hold }} /> : null}
      </div>
    </DeckContext.Provider>
  );
}

/* ── StickyDeckCard ─────────────────────────────────────── */

// The card is a motion.div, whose drag and animation handlers differ from the DOM's.
export type StickyDeckCardProps = Omit<
  React.HTMLAttributes<HTMLDivElement>,
  "onDrag" | "onDragStart" | "onDragEnd" | "onAnimationStart" | "onAnimationEnd"
>;

/**
 * One card in the deck. Style it like any card: background, rounding, padding
 * and a fixed height. The dimming layer follows its rounded corners.
 */
export function StickyDeckCard({
  className,
  style,
  children,
  onClickCapture,
  onFocus,
  onPointerEnter,
  onPointerMove,
  onPointerLeave,
  ...props
}: StickyDeckCardProps) {
  const deck = useDeck();
  const index = React.useContext(IndexContext);
  const ref = React.useRef<HTMLDivElement>(null);
  const { position, top, offsetStep, scaleTo, dimTo, depth: layers, reduced, register, scrollTo } = deck;

  React.useLayoutEffect(() => register(index, ref.current), [register, index]);

  const progress = useTransform(position, (p) => clamp(p - index + 1, 0, 1));
  const depth = useTransform(position, (p) => Math.max(0, p - index));
  // 0 → 1 while a mouse is over the card's peeking edge. Sinks back as the
  // card comes to the front again.
  const lift = useSpring(0, LIFT_SPRING);
  // Only an edge the pointer meets while the card is buried lifts. A resting
  // pointer that the deck scrolls under would otherwise nudge every card it
  // passes.
  const raise = (event: React.PointerEvent) => {
    if (event.pointerType === "mouse" && depth.get() >= DECK.buried) lift.set(1);
  };

  const transform = useTransform([depth, lift], ([d, l]: number[]) => {
    if (reduced || (d === 0 && l === 0)) return "none";
    const rise = (Math.min(d, layers) + l * Math.min(d, 1) * DECK.lift) * offsetStep;
    const scale = scaleTo ** Math.min(d, layers + 1);
    return `translateY(${-rise}px) scale(${scale})`;
  });
  const opacity = useTransform(depth, (d) => clamp(layers + 1 - d, 0, 1));
  const pointerEvents = useTransform(opacity, (o) => (o > 0 ? "auto" : "none"));
  const shade = useTransform(depth, (d) => 1 - dimTo ** Math.min(d, layers + 1));

  // A buried card's peeking edge is a handle back to it.
  useMotionValueEvent(depth, "change", (d) => {
    const element = ref.current;
    const buried = d >= DECK.buried && d < layers + 1;
    if (element && element.hasAttribute("data-buried") !== buried) {
      element.toggleAttribute("data-buried", buried);
    }
  });

  const card = React.useMemo<Card>(() => ({ index, progress, depth }), [index, progress, depth]);

  return (
    <CardContext.Provider value={card}>
      <motion.div
        ref={ref}
        role="listitem"
        className={cn(
          "sticky origin-top will-change-transform data-buried:cursor-pointer",
          className,
        )}
        style={{ ...style, top, transform, opacity, pointerEvents }}
        onClickCapture={(event) => {
          // A real click (not Enter on a focused link) on a buried card brings it back.
          if (event.detail > 0 && depth.get() >= DECK.buried) {
            event.preventDefault();
            event.stopPropagation();
            scrollTo(index);
          }
          onClickCapture?.(event);
        }}
        onFocus={(event) => {
          // Tabbing into a card the deck hides, or hasn't dealt yet, brings it forward.
          if (event.target.matches(":focus-visible") && Math.abs(position.get() - index) > 0.02) {
            scrollTo(index);
          }
          onFocus?.(event);
        }}
        onPointerEnter={(event) => {
          raise(event);
          onPointerEnter?.(event);
        }}
        onPointerMove={(event) => {
          raise(event);
          onPointerMove?.(event);
        }}
        onPointerLeave={(event) => {
          lift.set(0);
          onPointerLeave?.(event);
        }}
        {...props}
      >
        {children}
        <motion.span
          aria-hidden
          className="pointer-events-none absolute inset-0 z-10 m-0 block rounded-[inherit] bg-black"
          style={{ opacity: shade }}
        />
      </motion.div>
    </CardContext.Provider>
  );
}

/* ── useStickyDeckCard ──────────────────────────────────── */

/**
 * The card a component sits in, for effects inside it: `progress` runs 0 → 1
 * as the card travels into place, and `depth` counts the cards covering it.
 */
export function useStickyDeckCard() {
  const card = React.useContext(CardContext);
  if (!card) throw new Error("useStickyDeckCard() must be called inside <StickyDeckCard>.");
  return card;
}

/* ── helpers ────────────────────────────────────────────── */

function clamp(value: number, min: number, max: number) {
  return Math.min(Math.max(value, min), max);
}

function px(value: string) {
  return parseFloat(value) || 0;
}