Card Stack Deck

1"use client";
2 
3import * as React from "react";
4 
5import { cn } from "@/lib/utils";
6import { useControllableState, useReducedMotion, useVisibilityPause } from "@/lib/motiq";
7 
8/* -------------------------------------------------------------------------- */
9/* Types                                                                      */
10/* -------------------------------------------------------------------------- */
11 
12export interface CardStackDeckItem {
13  /** Stable key. */
14  id: string;
15  /** Front-face content. Ignored when `renderItem` is supplied. */
16  content?: React.ReactNode;
17  /** Announced politely when this card reaches the front. Falls back to the id. */
18  label?: string;
19}
20 
21export interface CardStackDeckItemState {
22  /** Index in `items`. */
23  index: number;
24  /** 0 = front of the deck. */
25  slot: number;
26  isFront: boolean;
27}
28 
29export interface CardStackDeckProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
30  /** The cards, front to back at rest. */
31  items: CardStackDeckItem[];
32  /** Render override for the front face. */
33  renderItem?: (item: CardStackDeckItem, state: CardStackDeckItemState) => React.ReactNode;
34  /** Shown mid-flip on the card's back. Defaults to a patterned back. */
35  cardBack?: React.ReactNode;
36  /** Rest-fan geometry per slot: y offset, z depth, rotateZ. */
37  fan?: { y?: number; z?: number; rotate?: number };
38  /** Peak sideways travel of the sent card, in px. */
39  arcWidth?: number;
40  /** Peak z-lift of the sent card, in px. */
41  lift?: number;
42  /** Slot spring for send + ripple. */
43  spring?: { stiffness?: number; damping?: number };
44  /** Drag/tap the front card to shuffle. */
45  dragToShuffle?: boolean;
46  /** Render the prev/next buttons. */
47  showControls?: boolean;
48  /** Scene height in px (leaves room for the fan above the card). */
49  height?: number;
50  /** Card height in px. */
51  cardHeight?: number;
52  /** Controlled front-card index. */
53  topIndex?: number;
54  /** Uncontrolled initial front-card index. */
55  defaultTopIndex?: number;
56  /** Fires with the new front-card index. */
57  onTopChange?: (index: number) => void;
58  /** Accessible name for the deck group. */
59  label?: string;
60  /** Park the loop while scrolled offscreen or the tab is hidden. */
61  pauseWhenHidden?: boolean;
62  /** Force instant, motion-free reordering regardless of system preference. */
63  reducedMotion?: boolean;
64}
65 
66/* -------------------------------------------------------------------------- */
67// … truncated