Animated Counter

"use client";

import * as React from "react";

export type CounterEasing = "linear" | "easeOut" | "easeInOut" | "expo";

export interface AnimatedCounterProps extends Omit<React.ComponentPropsWithoutRef<"span">, "children"> {
  /** The number to count up (or down) to. */
  value: number;
  /** Where the count starts on first play. */
  from?: number;
  /** Fixed number of fraction digits. */
  decimals?: number;
  /** Text rendered before the number, e.g. "$". */
  prefix?: string;
  /** Text rendered after the number, e.g. "%" or "+". */
  suffix?: string;
  /** Start when the counter scrolls into view (once) or immediately on mount. */
  trigger?: "view" | "mount";
  /** Animation length in milliseconds. */
  duration?: number;
  easing?: CounterEasing;
  /** BCP 47 locale for grouping and decimal separators. */
  locale?: string;
  /** Use locale grouping separators (1,234 vs 1234). */
  grouping?: boolean;
}

const EASINGS: Record<CounterEasing, (t: number) => number> = {
  linear: (t) => t,
  easeOut: (t) => 1 - Math.pow(1 - t, 3),
  easeInOut: (t) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2),
  expo: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)),
};

function subscribeReducedMotion(callback: () => void) {
  const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
  mq.addEventListener("change", callback);
  return () => mq.removeEventListener("change", callback);
}

function usePrefersReducedMotion() {
  return React.useSyncExternalStore(
    subscribeReducedMotion,
    () => window.matchMedia("(prefers-reduced-motion: reduce)").matches,
    () => false,
  );
}

/**
 * A number that counts to its value once it is seen. Frames are written straight to the DOM
 * (no React re-render per frame), the final value is always available to assistive technology,
 * and an invisible copy of the start and end values reserves width so nothing shifts.
 */
export function AnimatedCounter({
  value,
  from = 0,
  decimals = 0,
  prefix = "",
  suffix = "",
  trigger = "view",
  duration = 2000,
  easing = "easeOut",
  locale = "en-US",
  grouping = true,
  className = "",
  ...props
}: AnimatedCounterProps) {
  const reduceMotion = usePrefersReducedMotion();
  const rootRef = React.useRef<HTMLSpanElement>(null);
  const numberRef = React.useRef<HTMLSpanElement>(null);
  // The number currently on screen — new targets animate from here, never from zero.
  const currentRef = React.useRef(from);
  const [inView, setInView] = React.useState(false);

  const formatter = React.useMemo(() => {
    const digits = Math.max(0, Math.min(20, Math.round(decimals)));
    try {
      return new Intl.NumberFormat(locale, {
        minimumFractionDigits: digits,
        maximumFractionDigits: digits,
        useGrouping: grouping,
      });
    } catch {
      // Invalid locale strings fall back to the runtime default.
      return new Intl.NumberFormat(undefined, {
        minimumFractionDigits: digits,
        maximumFractionDigits: digits,
        useGrouping: grouping,
      });
    }
  }, [locale, decimals, grouping]);

  // Observe visibility once; the counter only ever plays forward.
  React.useEffect(() => {
    if (trigger !== "view" || inView) return;
    const node = rootRef.current;
    if (!node) return;
    if (typeof IntersectionObserver === "undefined") {
      const id = requestAnimationFrame(() => setInView(true));
      return () => cancelAnimationFrame(id);
    }
    const observer = new IntersectionObserver(
      (entries) => {
        if (entries.some((e) => e.isIntersecting)) {
          setInView(true);
          observer.disconnect();
        }
      },
      { threshold: 0.4 },
    );
    observer.observe(node);
    return () => observer.disconnect();
  }, [trigger, inView]);

  const active = trigger === "mount" || inView;

  React.useEffect(() => {
    const node = numberRef.current;
    if (!node || !active) return;
    const start = currentRef.current;
    const end = value;
    if (reduceMotion || duration <= 0 || start === end) {
      currentRef.current = end;
      node.textContent = formatter.format(end);
      return;
    }
    const ease = EASINGS[easing] ?? EASINGS.easeOut;
    let frame = 0;
    let startedAt: number | null = null;
    const tick = (now: number) => {
      if (startedAt === null) startedAt = now;
      const progress = Math.min(1, (now - startedAt) / duration);
      const next = progress === 1 ? end : start + (end - start) * ease(progress);
      currentRef.current = next;
      node.textContent = formatter.format(next);
      if (progress < 1) frame = requestAnimationFrame(tick);
    };
    frame = requestAnimationFrame(tick);
    return () => cancelAnimationFrame(frame);
    // `from` is listed so a re-render that resets the start text is immediately corrected.
  }, [active, value, from, duration, easing, reduceMotion, formatter]);

  const finalText = formatter.format(value);
  const startText = formatter.format(from);

  return (
    <span
      ref={rootRef}
      className={`inline-flex items-baseline whitespace-nowrap tabular-nums ${className}`}
      {...props}
    >
      {/* Visual layer: hidden from assistive technology, which reads the final value below. */}
      <span aria-hidden="true" className="inline-flex items-baseline">
        {prefix ? <span>{prefix}</span> : null}
        <span className="inline-grid justify-items-end">
          {/* Invisible copies reserve the widest of the start and end values. */}
          <span className="invisible [grid-area:1/1]">{finalText}</span>
          <span className="invisible [grid-area:1/1]">{startText}</span>
          <span ref={numberRef} className="[grid-area:1/1]" suppressHydrationWarning>
            {startText}
          </span>
        </span>
        {suffix ? <span>{suffix}</span> : null}
      </span>
      <span className="sr-only">{`${prefix}${finalText}${suffix}`}</span>
    </span>
  );
}