Flip Words

1"use client";
2 
3import {
4  type ComponentPropsWithoutRef,
5  useCallback,
6  useEffect,
7  useId,
8  useMemo,
9  useState,
10} from "react";
11 
12// @interlace/flip-words v1.1.0 — Interlace design system.
13// Docs, props and live preview: https://ds.interlace.tools/c/flip-words
14// What changed since: https://ds.interlace.tools/c/flip-words#history
15// Generated banner — keep it, the upgrade diff reads this version.
16 
17/**
18 * @interlace/ui — FlipWords
19 *
20 * A headline word that flips through a list. Each replacement enters
21 * letter-by-letter out of an 8px blur while the outgoing one drifts up, blurs
22 * and scales away.
23 *
24 * It runs itself on a `duration` dwell timer (3000ms by default), or you hand
25 * it `index` + `onIndexChange` and drive it yourself.
26 *
27 * ## Provenance
28 *
29 * Our reimplementation of the Aceternity UI `FlipWords`. What is ours: a
30 * numeric index with a controlled mode — upstream is uncontrolled-only and
31 * derives its position from `words.indexOf(currentWord)`, which misbehaves the
32 * moment the list contains a duplicate; `currentColor` instead of a hard-coded
33 * `text-neutral-900 dark:text-neutral-100` pair; `pauseOnHover`; and the
34 * reduced-motion branch below.
35 *
36 * ## Anatomy
37 *
38 *   FlipWords                        (span — data-slot="flip-words")
39 *     ├─ span.sr-only aria-live=polite   (the announced text)
40 *     └─ span[data-slot=flip-words-static]  (under reduce)
41 *        | motion.span[data-slot=flip-words-word]
42 *            └─ span per word
43 *                └─ motion.span per letter
44 *
45 * The visible word is `aria-hidden` in BOTH branches. Everything a screen
46 * reader gets comes from the polite live region, so the letter-by-letter
47 * staging is never spelled out.
48 *
49 * ## Motion
50 *
51 * JS-driven — `motion/react` enter/exit variants plus a `setTimeout` cycle —
52 * so the CSS reset in `styles/preflight.css` reaches none of it. It is gated
53 * in JS, at both levels: `cyclingPaused` includes `reducedMotion`, so the
54 * timer never fires, and the render swaps the entire `AnimatePresence` subtree
55 * for a plain `<span>` carrying the active word. Under
56 * `prefers-reduced-motion: reduce` you get one stable, readable word and no
57 * animation object is ever constructed.
58 *
59 * `pauseOnHover` is documented as a no-op under reduce for the same reason:
60 * there is nothing left to pause.
61 *
62 * ## Layout
63 *
64 * The outgoing word animates to `position: absolute`, so the span does not
65// … truncated