Kinetic Text Reveal

1"use client";
2 
3import { cn } from "@/lib/utils";
4import {
5  motion,
6  useReducedMotion,
7  type Transition,
8  type Variants,
9} from "framer-motion";
10import {
11  forwardRef,
12  useEffect,
13  useImperativeHandle,
14  useMemo,
15  useState,
16  type HTMLAttributes,
17} from "react";
18 
19type SplitMode = "words" | "characters" | "lines";
20type RevealDirection = "up" | "down" | "left" | "right";
21type StaggerOrigin = "start" | "end" | "center" | "edges" | "random" | number;
22 
23export interface KineticTextRevealRef {
24  /** Starts or replays the reveal animation. */
25  play: () => void;
26  /** Moves the text back to its hidden state. */
27  reset: () => void;
28}
29 
30interface KineticTextRevealProps extends Omit<
31  HTMLAttributes<HTMLSpanElement>,
32  "children"
33> {
34  /** Text content to reveal. */
35  text: string;
36  /** Additional CSS classes for the outer element. */
37  className?: string;
38  /** CSS classes applied to each animated text segment. */
39  segmentClassName?: string;
40  /** CSS classes applied to each clipping wrapper. */
41  maskClassName?: string;
42  /** How the text is segmented before animation. */
43  splitBy?: SplitMode;
44  /** Direction each segment travels from. */
45  direction?: RevealDirection;
46  /** Distance each segment travels in pixels. */
47  distance?: number;
48  /** Delay between animated segments in seconds. */
49  stagger?: number;
50  /** Where the stagger wave begins. */
51  staggerFrom?: StaggerOrigin;
52  /** Animation transition for each segment. */
53  transition?: Transition;
54  /** Adds blur while segments are hidden. */
55  blur?: boolean;
56  /** Starts automatically after mount. */
57  autoPlay?: boolean;
58  /** Optional delay before the automatic reveal begins, in seconds. */
59  delay?: number;
60  /** Called when the reveal begins. */
61  onRevealStart?: () => void;
62  /** Called after the last segment completes. */
63  onRevealComplete?: () => void;
64}
65 
66interface Segment {
67  value: string;
68  animated: boolean;
69  index: number;
70}
71 
72function splitIntoGraphemes(value: string): string[] {
73  if (typeof Intl !== "undefined" && "Segmenter" in Intl) {
74    const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
75    return Array.from(segmenter.segment(value), ({ segment }) => segment);
76  }
77 
78  return Array.from(value);
79}
80 
81function getSegments(text: string, splitBy: SplitMode): Segment[] {
82  let animatedIndex = 0;
83 
84  if (splitBy === "lines") {
85    return text.split("\n").map((line) => {
86      const animated = line.length > 0;
87      return {
88        value: line,
89        animated,
90// … truncated