Index 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 { motion, useReducedMotion, type Transition } from "motion/react";
import { cn } from "@/lib/utils";

/*
 * Index List — a list of names where one is chosen and the rest step back; what belongs to the chosen one shows beside
 * the list, or under its name when there is little room (from the Tustel Services and the Portfolio "List" view).
 * Pointing at a name chooses it and it stays chosen when the pointer leaves; a click or Enter chooses it too, on any
 * device. There is always one chosen name.
 *
 * Framer's spring for the names and the narrow accordion: bounce 0.2, 0.4s (a slight overshoot). When the panel is
 * beside the list it changes at once, with no cross-fade, as in Tustel; otherwise the chosen name opens its panel under
 * it by height.
 *
 * The layout follows the width of the list, not of the window (a container query, 576px): Tustel's breakpoints are
 * the window's, which broke as soon as the list sat in a sidebar or a card. Each panel is in the page once, inside its
 * own list item. When there is room the list becomes a grid and every panel is placed in the same cell beside the
 * names, so the content is not duplicated for the two layouts (a copy would repeat ids and state). The names space out
 * if a panel is taller than the list.
 *
 * Improvement over Tustel: its names fall to 30% opacity, which is 2.1:1 against white; the library steps them back to
 * 65% (6.3:1 in the default theme, 8:1 in dark, and 5.1:1 or better in all four Blocks sample themes, light and dark; 60%
 * was 4.4 in "soft"). Its accent colour on the chosen name is left out — callers colour it
 * with `aria-expanded:` classes through `nameClassName`. Reduced motion is a zero-duration transition (opacity and
 * height are not transforms, so MotionConfig would not skip them); the markup never depends on it.
 */

const soft: Transition = { type: "spring", bounce: 0.2, duration: 0.4 };

export type IndexListItem = {
  value: string;
  /** The name: large text, one line. */
  title: React.ReactNode;
  /** Before the name: a number, say. */
  marker?: React.ReactNode;
  /** What shows while this name is chosen: beside the list when it is at least 576px wide, under the name below. */
  panel: React.ReactNode;
};

export type IndexListProps = {
  items: IndexListItem[];
  value?: string;
  /** The name that starts chosen; the first by default. */
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  /** Accessible name of the list. */
  label: string;
  /** "hover": pointing at a name with a mouse chooses it, while the panel is beside the list. "click": only a click or Enter does. */
  trigger?: "hover" | "click";
  /** Opacity of the names that are not chosen. */
  dimmed?: number;
  /** Width of the panel when it is beside the list, in px (never more than 55% of the list). */
  panelWidth?: number;
  /** Classes for every name button; the chosen one has aria-expanded="true". */
  nameClassName?: string;
  className?: string;
};

export function IndexList({
  items,
  value,
  defaultValue,
  onValueChange,
  label,
  trigger = "hover",
  dimmed = 0.65,
  panelWidth = 360,
  nameClassName,
  className,
}: IndexListProps) {
  const [internal, setInternal] = React.useState(defaultValue ?? items[0]?.value);
  const active = value ?? internal;
  const reduce = Boolean(useReducedMotion());
  const list = React.useRef<HTMLUListElement>(null);
  const id = React.useId();
  const transition = reduce ? { duration: 0 } : soft;

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

  /* Whether the panel is beside the list is CSS (a container query), so ask the list, when the pointer arrives and never
     while rendering: the server cannot know it. */
  function point(event: React.PointerEvent, next: string) {
    if (trigger !== "hover" || event.pointerType !== "mouse" || !list.current || getComputedStyle(list.current).display !== "grid") return;
    choose(next);
  }

  return (
    <div className={cn("@container w-full", className)}>
      <ul
        ref={list}
        aria-label={label}
        style={{ ["--index-panel" as string]: `${panelWidth}px`, ["--index-rows" as string]: items.length }}
        className="flex w-full flex-col gap-6 @xl:grid @xl:grid-cols-[minmax(0,1fr)_minmax(0,min(var(--index-panel),55%))] @xl:gap-x-12"
      >
        {items.map((item, index) => {
          const open = item.value === active;
          const buttonId = `${id}-${index}-name`;
          const panelId = `${id}-${index}-panel`;
          return (
            <li key={item.value} className="flex flex-col @xl:contents">
              <motion.button
                id={buttonId}
                type="button"
                aria-expanded={open}
                aria-controls={panelId}
                onClick={() => choose(item.value)}
                onPointerEnter={(event) => point(event, item.value)}
                initial={false}
                animate={{ opacity: open ? 1 : dimmed }}
                transition={transition}
                className={cn(
                  "cursor-pointer self-start rounded-md text-left text-2xl font-semibold tracking-tight outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 @xl:col-start-1 @xl:text-3xl",
                  nameClassName,
                )}
              >
                {item.marker && <span className="mr-3 font-normal tabular-nums">{item.marker}</span>}
                {item.title}
              </motion.button>

              {/* Narrow: the panel opens under its name by height. Wide: only the chosen one shows, in the shared cell. */}
              <motion.div
                id={panelId}
                role="region"
                aria-labelledby={buttonId}
                data-state={open ? "open" : "closed"}
                inert={!open}
                initial={false}
                animate={{ height: open ? "auto" : 0 }}
                transition={transition}
                style={{ gridRow: "1 / span var(--index-rows)" }}
                className="overflow-hidden @xl:col-start-2 @xl:h-auto! @xl:self-center @xl:overflow-visible @xl:data-[state=closed]:hidden"
              >
                <div className="pt-4 text-sm text-muted-foreground @xl:pt-0">{item.panel}</div>
              </motion.div>
            </li>
          );
        })}
      </ul>
    </div>
  );
}