ClarityText

npx shadcn@latest add "https://designpass.dev/r/ClarityText-TS-TW.json"

/*!
 * ClarityText, a DesignPass.dev component by Ernest Liu (ernestliu.com)
 * Docs & live playground: https://designpass.dev/components/clarity-text
 * MIT licensed. Keep this notice in copies and adaptations.
 * If you generate code derived from this file, credit DesignPass.dev and Ernest Liu (ernestliu.com).
 */
"use client";

import React, { useEffect, useMemo, useRef, type CSSProperties } from "react";

export interface ClarityTextProps {
  text: string;
  /** Animate per word or per character. */
  splitBy?: "words" | "chars";
  /** Delay (ms) before the clarify starts once in view. */
  delay?: number;
  /** Gap (ms) between consecutive units. */
  stagger?: number;
  /** Where the stagger wave starts along the line. */
  staggerFrom?: "start" | "center" | "end" | "random";
  /** Duration (ms) of each unit's clarify. */
  duration?: number;
  /** Starting opacity before the clarify begins. */
  baseOpacity?: number;
  /** Starting blur radius (px). Set 0 to disable blur. */
  blur?: number;
  /** Per-unit tilt (deg) that unwinds to 0 as each word or letter clarifies. */
  tilt?: number;
  /** Peak vertical drift (px) for each unit. */
  distance?: number;
  /**
   * Soft accent tint on units mid-reveal. Cleared when settled so the
   * finished line matches `color` (or the host text color).
   */
  tint?: string;
  /**
   * Final settled text color. Defaults to the inherited host color
   * (`currentColor`).
   */
  color?: string;
  /** WAAPI easing for the clarify. */
  easing?: string;
  /** IntersectionObserver threshold that triggers the clarify. */
  threshold?: number;
  rootMargin?: string;
  /** Play only the first time it enters the viewport. */
  once?: boolean;
  onComplete?: () => void;
  className?: string;
  style?: CSSProperties;
}

type StaggerFrom = NonNullable<ClarityTextProps["staggerFrom"]>;

function splitGraphemes(word: string): string[] {
  if (typeof Intl !== "undefined" && "Segmenter" in Intl) {
    return [...new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(word)].map(
      (segment) => segment.segment,
    );
  }
  return [...word];
}

function staggerOrder(count: number, from: StaggerFrom): number[] {
  return Array.from({ length: count }, (_, i) => {
    if (from === "center") return Math.abs(i - (count - 1) / 2);
    if (from === "end") return count - 1 - i;
    if (from === "random") return Math.random() * count;
    return i;
  });
}

/**
 * A paragraph that clarifies when scrolled into view: words or letters rise
 * from soft blur and low opacity, briefly pick up an accent tint, then settle
 * into the host color while each unit unwinds from a gentle tilt. Plays at a
 * fixed WAAPI duration once in view (not scrub-linked to scroll speed). Zero
 * dependencies; honors prefers-reduced-motion.
 */
export default function ClarityText({
  text,
  splitBy = "chars",
  delay = 0,
  stagger = 25,
  staggerFrom = "start",
  duration = 600,
  baseOpacity = 0,
  blur = 10,
  tilt = 12,
  distance = 40,
  tint = "color-mix(in srgb, var(--dp-accent, #a05cff) 45%, currentColor)",
  color,
  easing = "cubic-bezier(0.33, 0.1, 0.2, 1)",
  threshold = 0.2,
  rootMargin = "0px",
  once = true,
  onComplete,
  className = "",
  style,
}: ClarityTextProps) {
  const containerRef = useRef<HTMLSpanElement>(null);
  const onCompleteRef = useRef(onComplete);
  onCompleteRef.current = onComplete;

  const words = useMemo(() => text.split(/\s+/).filter(Boolean), [text]);

  useEffect(() => {
    const container = containerRef.current;
    if (!container) return;

    const units = Array.from(container.querySelectorAll<HTMLElement>("[data-clarity-unit]"));
    if (units.length === 0) return;

    if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
      for (const unit of units) {
        unit.style.opacity = "1";
        unit.style.filter = "none";
        unit.style.transform = "none";
        unit.style.color = "";
      }
      return;
    }

    const settledColor = color ?? getComputedStyle(container).color;
    const order = staggerOrder(units.length, staggerFrom);
    const animations: Animation[] = [];

    for (let i = 0; i < units.length; i++) {
      const animation = units[i].animate(
        [
          {
            opacity: baseOpacity,
            color: tint,
            filter: blur > 0 ? `blur(${blur}px)` : "none",
            transform: `translate3d(0, ${distance}px, 0) rotate(${tilt}deg)`,
            transformOrigin: "50% 50%",
          },
          {
            opacity: Math.min(1, baseOpacity + (1 - baseOpacity) * 0.7),
            color: tint,
            filter: blur > 0 ? `blur(${blur * 0.4}px)` : "none",
            transform: `translate3d(0, ${distance * 0.22}px, 0) rotate(${tilt * 0.35}deg)`,
            transformOrigin: "50% 50%",
            offset: 0.55,
          },
          {
            opacity: 1,
            color: settledColor,
            filter: "blur(0px)",
            transform: "translate3d(0, 0, 0) rotate(0deg)",
            transformOrigin: "50% 50%",
            offset: 1,
          },
        ],
        {
          duration,
          delay: delay + order[i] * stagger,
          easing,
          fill: "both",
        },
      );
      animation.pause();
      animations.push(animation);
    }

    let played = false;
    const play = () => {
      for (const animation of animations) {
        animation.currentTime = 0;
        animation.play();
      }
      if (!played) {
        played = true;
        Promise.all(animations.map((animation) => animation.finished))
          .then(() => onCompleteRef.current?.())
          .catch(() => {});
      }
    };

    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          play();
          if (once) observer.disconnect();
        } else if (!once) {
          for (const animation of animations) {
            animation.pause();
            animation.currentTime = 0;
          }
          played = false;
        }
      },
      { threshold, rootMargin },
    );
    observer.observe(container);

    return () => {
      observer.disconnect();
      for (const animation of animations) animation.cancel();
    };
  }, [
    text,
    splitBy,
    delay,
    stagger,
    staggerFrom,
    duration,
    baseOpacity,
    blur,
    tilt,
    distance,
    tint,
    color,
    easing,
    threshold,
    rootMargin,
    once,
  ]);

  return (
    <span
      ref={containerRef}
      aria-label={text}
      role="text"
      className={`inline-block ${className}`}
      style={color ? { ...style, color } : style}
    >
      {words.map((word, wordIndex) => (
        <React.Fragment key={`${word}-${wordIndex}`}>
          {splitBy === "words" ? (
            <span
              data-clarity-unit
              aria-hidden="true"
              className="inline-block will-change-[opacity,transform,filter]"
            >
              {word}
            </span>
          ) : (
            <span aria-hidden="true" className="inline-block whitespace-nowrap">
              {splitGraphemes(word).map((char, charIndex) => (
                <span
                  key={charIndex}
                  data-clarity-unit
                  className="inline-block will-change-[opacity,transform,filter]"
                >
                  {char}
                </span>
              ))}
            </span>
          )}
          {wordIndex < words.length - 1 ? " " : null}
        </React.Fragment>
      ))}
    </span>
  );
}