Liquid Fill Headline

1"use client";
2 
3import * as React from "react";
4 
5import { cn } from "@/lib/utils";
6import { useReducedMotion, useVisibilityPause } from "@/lib/motiq";
7 
8/* -------------------------------------------------------------------------- */
9/* Types                                                                      */
10/* -------------------------------------------------------------------------- */
11 
12/** `inview` runs the pour timeline on screen; `manual` waits for `level`/replay. */
13export type LiquidFillTrigger = "inview" | "manual";
14 
15export interface LiquidFillHeadlineProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
16  /** The real string. Rendered readable on the server and to screen readers. */
17  text: string;
18  /** Rise duration in ms. */
19  fillMs?: number;
20  /** How long the full headline is held before draining, in ms. */
21  holdMs?: number;
22  /** Drain duration in ms. */
23  drainMs?: number;
24  /** Wave height at full slosh, in % of the headline box. */
25  amplitude?: number;
26  /** Two or more CSS colors for the liquid gradient (top → bottom). */
27  gradient?: string[];
28  /** The coral shimmer sweep at the moment the headline fills. */
29  shimmer?: boolean;
30  /** Keep pouring / draining on a loop. */
31  loop?: boolean;
32  /** Controlled fill level, 0–1. Setting it takes the timeline out of the picture. */
33  level?: number;
34  /** What starts the pour. */
35  trigger?: LiquidFillTrigger;
36  /** Restart the pour on pointer down anywhere on the headline. */
37  replayOnPointer?: boolean;
38  /** Element tag for the rendered headline. */
39  as?: "h1" | "h2" | "h3" | "p" | "span" | "div";
40  /** Force the static variant: a fully filled gradient headline, no motion. */
41  reducedMotion?: boolean;
42  /** Fires each time the headline reaches full. */
43  onFilled?: () => void;
44}
45 
46/* -------------------------------------------------------------------------- */
47/* Constants                                                                  */
48/* -------------------------------------------------------------------------- */
49 
50/** Polygon resolution — 24 points is smooth at headline scale and cheap. */
51const POINTS = 24;
52/** Timeline segments not exposed as props (seconds). */
53const SETTLE_S = 0.8;
54const SHIMMER_S = 1.0;
55const GAP_S = 0.8;
56/** Level (% of the box) at empty and at full — full overshoots the cap slightly. */
57const LEVEL_EMPTY = 108;
58const LEVEL_FULL = -6;
59/** The back layer rides higher and out of phase, which reads as depth. */
60// … truncated