Kinetic Headline

/**
 * VibeBox Motion · Kinetic Headline
 * Copyright (c) 2026 VibeBox. Licensed under the VibeBox Motion Free License:
 * https://motion.vibeboxph.com/license
 * Use it in unlimited personal, commercial and client projects.
 * Do not sell or redistribute it as a component, kit, template or builder.
 */
import { Fragment, type CSSProperties, type ReactNode } from "react";
import { cn } from "@/lib/utils";
import { KineticTrigger } from "./kinetic-headline.client";

/*
 * A headline that rises into place word by word behind a mask. "mount" runs on CSS alone, so an
 * above-the-fold heading animates before hydration; "view" plays once, when the heading scrolls
 * in. The words are real text the whole time, for search engines and screen readers.
 */

export type KineticSegment =
  | string
  | { text: string; variant?: "serif" | "spectrum"; nowrap?: boolean }
  | { br: true; desktopOnly?: boolean };

type Word = { text: string; variant?: "serif" | "spectrum" } | { br: true; desktopOnly?: boolean };

const KEYFRAMES = `
@keyframes vb-kh-rise { from { transform: translate3d(0, 108%, 0) rotate(2deg); } to { transform: none; } }
@media (prefers-reduced-motion: no-preference) {
  [data-vb="kinetic-headline"][data-mode="mount"] [data-vb-kh-word],
  [data-vb="kinetic-headline"][data-state="in"] [data-vb-kh-word] {
    animation: vb-kh-rise calc(var(--vb-duration-section, 520ms) * 1.8) var(--ease-expo-out, cubic-bezier(0.16, 1, 0.3, 1)) both;
    animation-delay: var(--vb-kh-delay, 0ms);
  }
  [data-vb="kinetic-headline"][data-state="armed"] [data-vb-kh-word] { transform: translate3d(0, 108%, 0) rotate(2deg); }
}
`;

export type KineticHeadlineProps = {
  /** The heading text: plain strings, styled phrases, and line breaks. */
  segments: readonly KineticSegment[];
  /** The element to render. */
  as?: "h1" | "h2" | "h3" | "h4" | "p";
  /** "mount" plays on load with CSS alone; "view" plays once when the heading scrolls into view. */
  mode?: "mount" | "view";
  /** Seconds before the first word rises. */
  delay?: number;
  /** Seconds between words. */
  stagger?: number;
  /** Element id, for a section's aria-labelledby. */
  id?: string;
  className?: string;
};

function toWords(segments: readonly KineticSegment[]): Word[] {
  const words: Word[] = [];
  const split = (text: string, variant?: "serif" | "spectrum") =>
    text
      .split(/\s+/)
      .filter(Boolean)
      .forEach((part) => words.push({ text: part, variant }));
  for (const segment of segments) {
    if (typeof segment === "string") split(segment);
    else if ("br" in segment) words.push(segment);
    // One unit keeps a spectrum gradient continuous, or keeps a phrase on one line.
    else if (segment.variant === "spectrum" || segment.nowrap) words.push({ text: segment.text, variant: segment.variant });
    else split(segment.text, segment.variant);
  }
  return words;
}

export function KineticHeadline({ segments, as: Tag = "h2", mode = "mount", delay = 0, stagger = 0.06, id, className }: KineticHeadlineProps) {
  const words = toWords(segments);
  let order = 0;
  const content: ReactNode[] = words.map((word, index) => {
    if ("br" in word) return <br key={`br-${index}`} className={word.desktopOnly ? "hidden md:inline" : undefined} />;
    const wait = Math.round((delay + order++ * stagger) * 1000);
    const next = words[index + 1];
    // A desktop-only break is hidden on small screens, so the words still need a space.
    const space = next && (!("br" in next) || next.desktopOnly) ? " " : "";
    return (
      <Fragment key={`${word.text}-${index}`}>
        <span className="-mt-[0.04em] -mr-[0.06em] -mb-[0.14em] inline-block overflow-hidden pt-[0.04em] pr-[0.06em] pb-[0.14em] align-top whitespace-nowrap">
          <span
            data-vb-kh-word=""
            className={cn(
              "inline-block",
              word.variant === "serif" && "pr-[0.08em] font-serif font-normal tracking-[-0.02em] italic",
              word.variant === "spectrum" && "text-spectrum",
            )}
            style={{ "--vb-kh-delay": `${wait}ms` } as CSSProperties}
          >
            {word.text}
          </span>
        </span>
        {space}
      </Fragment>
    );
  });
  return (
    <Tag id={id} data-vb="kinetic-headline" data-mode={mode} data-state={mode === "view" ? "idle" : undefined} className={cn("block text-balance", className)}>
      <style href="vb-kinetic-headline" precedence="vb">
        {KEYFRAMES}
      </style>
      {content}
      {mode === "view" && <KineticTrigger />}
    </Tag>
  );
}

/**
 * VibeBox Motion · Kinetic Headline
 * Copyright (c) 2026 VibeBox. Licensed under the VibeBox Motion Free License:
 * https://motion.vibeboxph.com/license
 * Use it in unlimited personal, commercial and client projects.
 * Do not sell or redistribute it as a component, kit, template or builder.
 */
"use client";

import { useEffect, useRef } from "react";

/**
 * "view" mode: hides the words only if the heading starts below the fold (so nothing on screen
 * ever flickers), then lets them rise once when it scrolls in. Without JavaScript, or with
 * reduced motion, the words simply stay put.
 */
export function KineticTrigger() {
  const ref = useRef<HTMLSpanElement>(null);
  useEffect(() => {
    const root = ref.current?.closest<HTMLElement>('[data-vb="kinetic-headline"]');
    if (!root || window.matchMedia("(prefers-reduced-motion: reduce)").matches) return;
    const box = root.getBoundingClientRect();
    if (box.top < window.innerHeight && box.bottom > 0) return;
    root.dataset.state = "armed";
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (!entry?.isIntersecting) return;
        root.dataset.state = "in";
        observer.disconnect();
      },
      { threshold: 0.35 },
    );
    observer.observe(root);
    return () => observer.disconnect();
  }, []);
  return <span ref={ref} hidden />;
}