CycleText

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

/*!
 * CycleText, a DesignPass.dev component by Ernest Liu (ernestliu.com)
 * Docs & live playground: https://designpass.dev/components/cycle-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, {
  forwardRef,
  useEffect,
  useImperativeHandle,
  useMemo,
  useRef,
  type CSSProperties,
} from "react";

export interface CycleTextHandle {
  next: () => void;
  previous: () => void;
  jumpTo: (index: number) => void;
  reset: () => void;
}

export interface CycleTextProps {
  /** Phrases to cycle through. */
  texts: string[];
  /** Ms each phrase holds before the next transition. */
  interval?: number;
  /** Ms for each character's enter/exit. */
  duration?: number;
  /** Gap (ms) between consecutive characters in the stagger wave. */
  stagger?: number;
  /** Where the stagger wave starts. */
  staggerFrom?: "start" | "center" | "end" | "random";
  /** Split each phrase into characters or words. */
  splitBy?: "chars" | "words";
  /** Vertical travel (%) for enter/exit. */
  distance?: number;
  /** Loop back to the first phrase after the last. */
  loop?: boolean;
  /** Auto-advance on a timer. */
  auto?: boolean;
  /** Pause auto-advance while the pointer is over the text. */
  pauseOnHover?: boolean;
  onChange?: (index: number, text: string) => void;
  className?: string;
  style?: CSSProperties;
}

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

/** Extra px so italic / tracking overhang isn't clipped by overflow:hidden. */
const WIDTH_PAD = 4;

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 unitsFor(text: string, splitBy: "chars" | "words"): string[] {
  const words = text.split(/\s+/).filter(Boolean);
  if (splitBy === "words") {
    const parts: string[] = [];
    words.forEach((word, i) => {
      parts.push(word);
      if (i < words.length - 1) parts.push(" ");
    });
    return parts;
  }
  const chars: string[] = [];
  words.forEach((word, i) => {
    chars.push(...splitGraphemes(word));
    if (i < words.length - 1) chars.push(" ");
  });
  return chars;
}

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

/**
 * Phrases that rotate in place with a staggered character or word swap,
 * easing line width between phrases so surrounding layout breathes instead
 * of snapping. Auto-advance can pause on hover; next, previous, jumpTo, and
 * reset via ref. Zero dependencies; honors prefers-reduced-motion.
 */
const CycleText = forwardRef<CycleTextHandle, CycleTextProps>(function CycleText(
  {
    texts,
    interval = 2200,
    duration = 520,
    stagger = 28,
    staggerFrom = "center",
    splitBy = "chars",
    distance = 110,
    loop = true,
    auto = true,
    pauseOnHover = true,
    onChange,
    className = "",
    style,
  },
  ref,
) {
  const rootRef = useRef<HTMLSpanElement>(null);
  const measureRef = useRef<HTMLSpanElement>(null);
  const stageRef = useRef<HTMLSpanElement>(null);
  const liveRef = useRef<HTMLSpanElement>(null);
  const indexRef = useRef(0);
  const busyRef = useRef(false);
  const pausedRef = useRef(false);
  const visibleRef = useRef(true);
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const widthAnimRef = useRef<Animation | null>(null);
  const apiRef = useRef({
    go: (_delta: number) => {},
    jump: (_index: number) => {},
  });
  const onChangeRef = useRef(onChange);
  onChangeRef.current = onChange;

  const safeTexts = useMemo(() => (texts.length > 0 ? texts : [""]), [texts]);

  useImperativeHandle(
    ref,
    () => ({
      next: () => apiRef.current.go(1),
      previous: () => apiRef.current.go(-1),
      jumpTo: (index: number) => apiRef.current.jump(index),
      reset: () => apiRef.current.jump(0),
    }),
    [],
  );

  useEffect(() => {
    const root = rootRef.current;
    const stage = stageRef.current;
    const measure = measureRef.current;
    const live = liveRef.current;
    if (!root || !stage || !measure || !live) return;

    const clearTimer = () => {
      if (timerRef.current) {
        clearTimeout(timerRef.current);
        timerRef.current = null;
      }
    };

    const schedule = () => {
      clearTimer();
      if (!auto || pausedRef.current || !visibleRef.current || busyRef.current) return;
      timerRef.current = setTimeout(() => {
        void apiRef.current.go(1);
      }, interval);
    };

    const fillUnits = (host: HTMLElement, text: string, forStage: boolean) => {
      host.replaceChildren();
      const parts = unitsFor(text, splitBy);
      const nodes: HTMLElement[] = [];
      for (const part of parts) {
        const span = document.createElement("span");
        if (forStage) {
          span.dataset.cycleUnit = "";
          span.setAttribute("aria-hidden", "true");
          span.style.willChange = "transform, opacity";
        }
        span.style.display = "inline-block";
        span.style.whiteSpace = "pre";
        span.textContent = part === " " ? "\u00A0" : part;
        host.appendChild(span);
        nodes.push(span);
      }
      return nodes;
    };

    // Measure with the same per-unit inline-block structure as the stage so
    // letter-spacing / glyph boxes match what actually renders (plain
    // textContent width is shorter and clips the last character).
    const measureWidth = (text: string) => {
      fillUnits(measure, text, false);
      return Math.ceil(measure.scrollWidth) + WIDTH_PAD;
    };

    const setWidth = (px: number) => {
      widthAnimRef.current?.cancel();
      widthAnimRef.current = null;
      root.style.width = `${px}px`;
    };

    const easeWidth = (to: number, animDuration: number) => {
      widthAnimRef.current?.cancel();
      const from = root.getBoundingClientRect().width;
      if (!Number.isFinite(from) || Math.abs(from - to) < 0.5) {
        root.style.width = `${to}px`;
        widthAnimRef.current = null;
        return null;
      }
      // Lock the starting width so the animation has a concrete from-value
      // even if a previous forwards fill was still applied.
      root.style.width = `${from}px`;
      const animation = root.animate(
        [{ width: `${from}px` }, { width: `${to}px` }],
        {
          duration: Math.max(animDuration, 1),
          easing: "cubic-bezier(0.22, 1, 0.36, 1)",
          fill: "forwards",
        },
      );
      widthAnimRef.current = animation;
      animation.finished
        .then(() => {
          if (widthAnimRef.current === animation) {
            root.style.width = `${to}px`;
            animation.cancel();
            widthAnimRef.current = null;
          }
        })
        .catch(() => {});
      return animation;
    };

    const animateIn = (nodes: HTMLElement[]) => {
      const delays = staggerDelays(nodes.length, staggerFrom, stagger);
      return nodes.map((node, i) =>
        node.animate(
          [
            { opacity: 0, transform: `translate3d(0, ${distance}%, 0)` },
            { opacity: 1, transform: "translate3d(0, 0, 0)" },
          ],
          {
            duration,
            delay: delays[i],
            easing: "cubic-bezier(0.22, 1.35, 0.36, 1)",
            fill: "both",
          },
        ),
      );
    };

    const animateOut = (nodes: HTMLElement[]) => {
      const delays = staggerDelays(nodes.length, staggerFrom, stagger);
      return nodes.map((node, i) =>
        node.animate(
          [
            { opacity: 1, transform: "translate3d(0, 0, 0)" },
            { opacity: 0, transform: `translate3d(0, ${-distance}%, 0)` },
          ],
          {
            duration,
            delay: delays[i],
            easing: "cubic-bezier(0.4, 0, 0.7, 0.2)",
            fill: "both",
          },
        ),
      );
    };

    const transitionMs = (unitCount: number) => {
      const delays = staggerDelays(unitCount, staggerFrom, stagger);
      const maxDelay = delays.length > 0 ? Math.max(...delays) : 0;
      return duration + maxDelay;
    };

    const jump = async (nextIndex: number) => {
      const clamped = Math.max(0, Math.min(safeTexts.length - 1, nextIndex));
      if (clamped === indexRef.current && stage.childElementCount > 0) return;
      if (busyRef.current) return;

      const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
      busyRef.current = true;
      clearTimer();

      const nextText = safeTexts[clamped];
      const nextWidth = measureWidth(nextText);
      const current = Array.from(stage.querySelectorAll<HTMLElement>("[data-cycle-unit]"));
      // Width eases only after the outgoing phrase has left, timed to the
      // incoming stagger so the slot finishes settling as glyphs land.
      const widthDuration = Math.max(180, Math.round(transitionMs(unitsFor(nextText, splitBy).length) * 0.65));

      if (reduced) {
        setWidth(nextWidth);
        fillUnits(stage, nextText, true);
        indexRef.current = clamped;
        live.textContent = nextText;
        onChangeRef.current?.(clamped, nextText);
        busyRef.current = false;
        schedule();
        return;
      }

      if (current.length > 0) {
        await Promise.all(animateOut(current).map((a) => a.finished.catch(() => {})));
      }

      // Resize only once the previous text has fully exited, then bring the
      // next phrase in while the slot eases to its new width.
      easeWidth(nextWidth, widthDuration);

      const nodes = fillUnits(stage, nextText, true);
      indexRef.current = clamped;
      live.textContent = nextText;
      onChangeRef.current?.(clamped, nextText);

      if (nodes.length > 0) {
        await Promise.all(animateIn(nodes).map((a) => a.finished.catch(() => {})));
      }

      if (!widthAnimRef.current) setWidth(nextWidth);

      busyRef.current = false;
      schedule();
    };

    const go = async (delta: number) => {
      let next = indexRef.current + delta;
      if (loop) {
        next = ((next % safeTexts.length) + safeTexts.length) % safeTexts.length;
      } else {
        next = Math.max(0, Math.min(safeTexts.length - 1, next));
        if (next === indexRef.current) return;
      }
      await jump(next);
    };

    apiRef.current = { go, jump };

    const width = measureWidth(safeTexts[0]);
    setWidth(width);
    const nodes = fillUnits(stage, safeTexts[0], true);
    indexRef.current = 0;
    live.textContent = safeTexts[0];
    const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
    if (!reduced && nodes.length > 0) {
      busyRef.current = true;
      void Promise.all(animateIn(nodes).map((a) => a.finished.catch(() => {}))).then(() => {
        busyRef.current = false;
        schedule();
      });
    } else {
      schedule();
    }

    const io = new IntersectionObserver(
      ([entry]) => {
        visibleRef.current = entry.isIntersecting;
        if (entry.isIntersecting) schedule();
        else clearTimer();
      },
      { threshold: 0.2 },
    );
    io.observe(root);

    const onEnter = () => {
      if (!pauseOnHover) return;
      pausedRef.current = true;
      clearTimer();
    };
    const onLeave = () => {
      if (!pauseOnHover) return;
      pausedRef.current = false;
      schedule();
    };
    if (pauseOnHover) {
      root.addEventListener("pointerenter", onEnter);
      root.addEventListener("pointerleave", onLeave);
    }

    return () => {
      clearTimer();
      widthAnimRef.current?.cancel();
      widthAnimRef.current = null;
      io.disconnect();
      root.removeEventListener("pointerenter", onEnter);
      root.removeEventListener("pointerleave", onLeave);
      stage.replaceChildren();
      measure.replaceChildren();
      root.style.width = "";
    };
  }, [
    safeTexts,
    interval,
    duration,
    stagger,
    staggerFrom,
    splitBy,
    distance,
    loop,
    auto,
    pauseOnHover,
  ]);

  return (
    <span
      ref={rootRef}
      className={`relative inline-block overflow-hidden align-bottom whitespace-nowrap ${className}`}
      style={style}
    >
      {/*
        Fixed + offscreen so measurement isn't clamped by the root's locked
        width (an absolute child inside a sized overflow:hidden box can
        shrink-to-fit to that box and under-report longer phrases).
      */}
      <span
        ref={measureRef}
        aria-hidden="true"
        className="pointer-events-none invisible fixed top-0 left-0 -z-10 whitespace-nowrap"
      />
      <span ref={liveRef} className="sr-only" aria-live="polite">
        {safeTexts[0]}
      </span>
      <span ref={stageRef} aria-hidden="true" className="inline-block whitespace-nowrap" />
    </span>
  );
});

export default CycleText;