Backdrop List

npm install motion clsx tailwind-merge

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

/* tailwind-merge must know the site's type scale (globals.css) is a font size, not a text color — otherwise
   cn("text-h6 text-muted-foreground") drops text-h6. */
const twMerge = extendTailwindMerge({
  extend: { classGroups: { "font-size": [{ text: ["display", "h1", "h2", "h3", "h4", "h5", "h6"] }] } },
});

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

"use client";

import * as React from "react";
import { cn } from "@/lib/utils";

/*
 * Backdrop List — a list of titles over full-bleed photos (from the Catchup Home hero). Pointing at a title makes its
 * photo the backdrop, and it stays chosen when the pointer leaves; the chosen title is at full opacity and the others
 * step back. Every change is a cut — no fade, no zoom, as in Catchup — and `fade` gives a cross-fade instead.
 *
 * A device without hover (a phone, a tablet) cannot point, so there the list moves on by itself every 6 s and loops. That
 * is `(hover: none)`, asked in an effect and never while rendering, because the server cannot know it. It waits while
 * the block is out of view or a title has focus, and it never starts for a visitor who asked for reduced motion. Focus
 * chooses a title the way a pointer does, so a keyboard reaches every photo (Catchup has no keyboard path).
 *
 * It is not index-list, whose panel sits beside the names and opens by height: here the media is a layer behind the whole
 * block and the list sits on it. Every item's media is in the page at once, stacked, so a cut shows the next photo
 * at once and a search engine sees them all.
 *
 * Contrast: the titles are white over the photos, under a black veil, 55% by default (Catchup's is 30%, on dark photos). The
 * step back (0.65) is the library's rule for a flat background. Over a photograph nothing can be decided in advance (axe
 * cannot see through an image): measure the pixels under the titles with the list hidden, on your own photos. On four
 * ordinary photographs the dimmed titles needed a veil of about 0.55 to reach 3:1, which large text asks for; 0.3 left
 * some of them under 2:1. Lower `veil` for darker photos, raise it for paler ones.
 */

export type BackdropListItem = {
  value: string;
  /** The title in the list: large text. */
  title: React.ReactNode;
  /** Where the title goes. Without it the title is a button that chooses it. */
  href?: string;
  /** The photo (or video) that fills the backdrop while this title is chosen. It is stretched and cropped to fit, and it is decoration: give an image an empty alt. */
  media: React.ReactNode;
};

export type BackdropListProps = {
  items: BackdropListItem[];
  value?: string;
  /** The title that starts chosen; the first by default. */
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  /** Accessible name of the list. */
  label: string;
  /** Milliseconds between titles on a device without hover; 0 turns that off. */
  interval?: number;
  /** Opacity of the titles that are not chosen. */
  dim?: number;
  /** Opacity of the black layer over the media, which keeps the white titles readable (Catchup: 0.3 on dark photos). 0 removes it. */
  veil?: number;
  /** Seconds of cross-fade between photos; 0 is a cut. Reduced motion always cuts. */
  fade?: number;
  /** Classes for the block: its height, padding, and the layout of what is inside it (it is a flex column that ends at the bottom). */
  className?: string;
  /** Classes for the list: where it sits in the block, its gap. */
  listClassName?: string;
  /** Classes for every title: its size, weight. The chosen one has aria-current. */
  titleClassName?: string;
  /** Anything else on the backdrop (a headline, buttons), before the list. */
  children?: React.ReactNode;
};

function useMedia(query: string) {
  const subscribe = React.useCallback(
    (onChange: () => void) => {
      const list = window.matchMedia(query);
      list.addEventListener("change", onChange);
      return () => list.removeEventListener("change", onChange);
    },
    [query],
  );
  return React.useSyncExternalStore(
    subscribe,
    () => window.matchMedia(query).matches,
    () => false,
  );
}

export function BackdropList({
  items,
  value,
  defaultValue,
  onValueChange,
  label,
  interval = 6000,
  dim = 0.65,
  veil = 0.55,
  fade = 0,
  className,
  listClassName,
  titleClassName,
  children,
}: BackdropListProps) {
  const [internal, setInternal] = React.useState(defaultValue ?? items[0]?.value);
  const active = value ?? internal;
  const root = React.useRef<HTMLDivElement>(null);
  const [inView, setInView] = React.useState(false);
  const [focused, setFocused] = React.useState(false);
  const touch = useMedia("(hover: none)");
  const calm = useMedia("(prefers-reduced-motion: reduce)");

  function choose(next: string) {
    if (next === active) return;
    if (value === undefined) setInternal(next);
    onValueChange?.(next);
  }

  /* The timer reads the latest items and choose when it fires, so it is not rebuilt every time the caller renders with a new array. */
  const latest = React.useRef({ items, choose });
  React.useEffect(() => {
    latest.current = { items, choose };
  });

  const empty = items.length === 0;
  React.useEffect(() => {
    const element = root.current;
    if (!element) return;
    const observer = new IntersectionObserver(([entry]) => setInView(entry.isIntersecting), { threshold: 0.3 });
    observer.observe(element);
    return () => observer.disconnect();
  }, [empty]);

  /* Without hover the list moves on by itself, one title every `interval`, and the timer starts over whenever a title is chosen. */
  const count = items.length;
  React.useEffect(() => {
    if (!touch || calm || !inView || focused || interval <= 0 || count < 2) return;
    const timer = window.setTimeout(() => {
      const { items, choose } = latest.current;
      const current = Math.max(0, items.findIndex((item) => item.value === active));
      choose(items[(current + 1) % items.length].value);
    }, interval);
    return () => window.clearTimeout(timer);
  }, [active, touch, calm, inView, focused, interval, count]);

  if (empty) return null;

  return (
    <div
      ref={root}
      style={{ ["--fade" as string]: `${fade}s` }}
      className={cn("relative isolate flex min-h-80 flex-col justify-end gap-8 overflow-hidden bg-black p-6 text-white sm:p-10", className)}
    >
      {/* Behind everything: every photo stacked, the chosen one on top (the others only leave once it has faded in), then the veil. */}
      <div aria-hidden className="absolute inset-0 -z-10">
        {items.map((item) => {
          const chosen = item.value === active;
          return (
            <div
              key={item.value}
              className={cn(
                "absolute inset-0 transition-opacity duration-0 [&>*]:size-full [&>*]:object-cover",
                chosen ? "z-1 opacity-100 motion-safe:duration-(--fade)" : "z-0 opacity-0 motion-safe:delay-(--fade)",
              )}
            >
              {item.media}
            </div>
          );
        })}
        <div className="absolute inset-0 z-2 bg-black" style={{ opacity: veil }} />
      </div>

      {children}

      <ul
        aria-label={label}
        onFocus={() => setFocused(true)}
        onBlur={(event) => {
          if (!event.currentTarget.contains(event.relatedTarget)) setFocused(false);
        }}
        className={cn("flex flex-col items-start gap-2.5 sm:gap-4", listClassName)}
      >
        {items.map((item) => {
          const chosen = item.value === active;
          const shared = {
            "aria-current": chosen ? ("true" as const) : undefined,
            onPointerEnter: (event: React.PointerEvent) => {
              if (event.pointerType !== "touch") choose(item.value);
            },
            onFocus: () => choose(item.value),
            className: cn(
              "cursor-pointer rounded-md text-left text-3xl font-semibold tracking-tight outline-none focus-visible:ring-2 focus-visible:ring-white focus-visible:ring-offset-2 focus-visible:ring-offset-black/70 sm:text-4xl",
              titleClassName,
            ),
          };
          const title = (
            <span style={{ opacity: chosen ? 1 : dim }} className="block motion-safe:transition-opacity motion-safe:duration-(--fade)">
              {item.title}
            </span>
          );
          return (
            <li key={item.value} className="flex">
              {item.href ? (
                <a href={item.href} {...shared}>
                  {title}
                </a>
              ) : (
                <button type="button" onClick={() => choose(item.value)} {...shared}>
                  {title}
                </button>
              )}
            </li>
          );
        })}
      </ul>
    </div>
  );
}