Kinetic Emphasis

1"use client";
2 
3import * as React from "react";
4import { animate } from "motion/mini";
5import type { AnimationPlaybackControls } from "motion";
6 
7import { cn } from "@/lib/utils";
8 
9type PlayMode = "in-view" | "mount" | "controlled";
10type Speed = "slow" | "normal" | "fast";
11type EmphasisStyle = "underline" | "none";
12 
13export interface KineticEmphasisProps extends React.HTMLAttributes<HTMLElement> {
14  /**
15   * The sentence, with emphasis authored as real `<em>` / `<strong>` children:
16   * `<KineticEmphasis>Motion that <em>understands emphasis</em>.</KineticEmphasis>`
17   */
18  children: React.ReactNode;
19  /** Element tag to render. */
20  as?: "h1" | "h2" | "h3" | "h4" | "p" | "span";
21  /** When the sweep plays. `controlled` plays on each rising edge of `active`. */
22  play?: PlayMode;
23  /** For `play="controlled"`. */
24  active?: boolean;
25  /** Stagger/duration preset. */
26  speed?: Speed;
27  /** 0–1 intensity of the decaying activation trace behind the front. */
28  trail?: number;
29  /** Persistent treatment for emphasized phrases after ignition. */
30  emphasisStyle?: EmphasisStyle;
31  /** Force reduced motion (e.g. from a preview toggle). Defaults to the user's OS preference. */
32  reducedMotion?: boolean;
33  /** Fires once per completed sweep. */
34  onComplete?: () => void;
35}
36 
37interface Seg {
38  text: string;
39  em: boolean;
40}
41 
42const SPEEDS: Record<Speed, { stagger: number; duration: number }> = {
43  slow: { stagger: 0.11, duration: 0.6 },
44  normal: { stagger: 0.08, duration: 0.5 },
45  fast: { stagger: 0.055, duration: 0.38 },
46};
47 
48const EASE_OUT: [number, number, number, number] = [0.22, 1, 0.36, 1];
49const SOFT_WORD_CAP = 40;
50 
51/** Accent used AS text — resolves to a contrast-safe token (≥4.5:1 at body sizes). */
52const ACCENT_TEXT = "var(--ke-accent, var(--color-accent-text, var(--color-accent, #5648ee)))";
53/** Accent used decoratively (underline wash, traces) — may stay vivid. */
54const ACCENT_DECOR = "var(--ke-accent, var(--color-accent, #695cff))";
55 
56/** Flatten string content of an em/strong element. */
57function textOf(node: React.ReactNode): string {
58  if (typeof node === "string" || typeof node === "number") return String(node);
59  if (Array.isArray(node)) return node.map(textOf).join("");
60  return "";
61}
62 
63function segment(children: React.ReactNode): { segs: Seg[]; unsupported: boolean } {
64  const segs: Seg[] = [];
65  let unsupported = false;
66  // Punctuation touching a boundary (e.g. `<em>emphasis</em>,`) must attach to
67// … truncated