Focus Cards

1"use client";
2 
3import {
4  type ComponentPropsWithoutRef,
5  type ReactNode,
6  useCallback,
7  useState,
8} from "react";
9 
10// @interlace/focus-cards v1.2.0 — Interlace design system.
11// Docs, props and live preview: https://ds.interlace.tools/c/focus-cards
12// What changed since: https://ds.interlace.tools/c/focus-cards#history
13// Generated banner — keep it, the upgrade diff reads this version.
14 
15/**
16 * @interlace/ui — FocusCards + FocusCard
17 *
18 * A grid that spotlights one card at a time: pointing at or keyboard-focusing
19 * a card keeps it sharp while every sibling dims and blurs. Real list
20 * semantics — `ul` › `li` › `article` — and a controlled or uncontrolled
21 * active index.
22 *
23 * The media is whatever node you pass: image, `next/image`, video, canvas.
24 * Nothing here assumes an `<img>`.
25 *
26 * ## Provenance
27 *
28 * Our reimplementation of the Aceternity UI "Focus Cards" pattern. What is
29 * ours: focus, not just hover, drives the active state (so the grid works from
30 * the keyboard); the active index is controllable and reports why it changed;
31 * the card is a `renderItem` + `caption` composition rather than a fixed
32 * `{src, title}` shape; and all colour comes from tokens.
33 *
34 * ## Anatomy
35 *
36 *   FocusCards                       (ul — data-slot="focus-cards")
37 *     └─ li                          (data-slot="focus-cards-item",
38 *                                     group/focus-item, data-active/data-dimmed,
39 *                                     owns the pointer + focus handlers)
40 *         └─ FocusCard               (article — data-slot="focus-card")
41 *             ├─ div                 (data-slot="focus-card-media")
42 *             └─ div                 (data-slot="focus-card-caption")
43 *
44 * The active/dim state travels down as `group-data-[active]/focus-item` and
45 * `group-data-[dimmed]/focus-item` CSS, so `renderItem` never forwards a prop
46 * for it. `FocusCard`'s own `active` / `dimmed` props exist only for composing
47 * a card outside the grid.
48 *
49 * ## Motion
50 *
51 * Tailwind transitions, JS-gated. `FocusCard` calls `useReducedMotion()` and
52 * omits three class groups when it returns true: the
53 * `transition-[filter,transform,opacity] duration-300` on the card, the
54 * `scale-[0.98] blur-sm` / `scale-100 blur-none` pair, and the caption's
55 * `transition-opacity`. What survives under `prefers-reduced-motion: reduce`
56 * is the part that carries the meaning — `opacity-60` on the receding cards
57// … truncated