letter-cascade

1"use client";
2 
3import { cn } from "@workspace/ui/lib/utils";
4import {
5    type AnimationOptions,
6    motion,
7    stagger,
8    useAnimate,
9} from "framer-motion";
10import { useCallback, useState } from "react";
11 
12interface LetterCascadeProps {
13    /** The text to animate */
14    text: string;
15    /** Additional CSS classes for the container */
16    className?: string;
17    /** CSS classes applied to each individual letter */
18    letterClassName?: string;
19    /** Stagger delay between each letter in seconds */
20    staggerDuration?: number;
21    /** Where the stagger wave originates */
22    staggerFrom?: "first" | "last" | "center" | number;
23    /** Spring stiffness — higher = snappier */
24    stiffness?: number;
25    /** Spring damping — lower = bouncier */
26    damping?: number;
27    /** Trigger the animation on click instead of hover */
28    triggerOnClick?: boolean;
29    /** Callback when the full animation cycle completes */
30    onComplete?: () => void;
31}
32 
33export function LetterCascade({
34    text,
35    className,
36    letterClassName,
37    staggerDuration = 0.04,
38    staggerFrom = "first",
39    stiffness = 220,
40    damping = 16,
41    triggerOnClick = false,
42    onComplete,
43}: LetterCascadeProps) {
44    const [scope, animate] = useAnimate();
45    const [blocked, setBlocked] = useState(false);
46 
47    const trigger = useCallback(() => {
48        if (blocked) return;
49        setBlocked(true);
50 
51        const merge = (base: AnimationOptions): AnimationOptions => ({
52            ...base,
53            delay: stagger(staggerDuration, { from: staggerFrom }),
54        });
55 
56        const spring: AnimationOptions = {
57            type: "spring",
58            stiffness,
59            damping,
60        };
61 
62        // ── Phase 1: front tilts back, echo flips in from below ──
63        animate(
64            ".cascade-front",
65            {
66                rotateX: 90,
67                opacity: 0,
68                y: -6,
69                filter: "blur(4px)",
70            },
71            merge(spring)
72        ).then(() => {
73            // Instantly reset front
74            animate(
75                ".cascade-front",
76                { rotateX: 0, opacity: 1, y: 0, filter: "blur(0px)" },
77                { duration: 0 }
78            ).then(() => {
79                setBlocked(false);
80                onComplete?.();
81            });
82        });
83 
84        animate(
85            ".cascade-echo",
86            {
87                rotateX: 0,
88                opacity: 1,
89                y: 0,
90                scale: 1,
91// … truncated