{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"flip-words","type":"registry:ui","title":"FlipWords","description":"Cycling word animation with per-letter fade-in and blur effects","author":"fancy-ui <https://fancy-ui.rama.app>","categories":["text"],"registryDependencies":["https://fancy-ui.rama.app/r/internals-dom.json","https://fancy-ui.rama.app/r/utils.json"],"files":[{"path":"react/src/components/flip-words/FlipWords.tsx","content":"\"use client\";\n\nimport { useEffect, useRef, useState } from \"react\";\nimport { cn } from \"../../utils\";\nimport { useLiveRef } from \"../../internals/dom/use-live-ref\";\nimport \"./flip-words.css\";\n\n/**\n * FlipWords - Cycling word animation\n *\n * Cycles through an array of words with per-letter fade-in animation.\n * Each word fades in letter-by-letter, stays visible for `duration` ms,\n * then scales/blurs out before the next word appears.\n */\nexport interface FlipWordsProps {\n\t/** Array of words to cycle through */\n\twords: string[];\n\t/** Time each word stays visible (ms) */\n\tduration?: number;\n\t/** Additional CSS classes */\n\tclassName?: string;\n}\n\nconst EXIT_MS = 600;\n\nexport function FlipWords({ words, duration = 3000, className }: FlipWordsProps) {\n\tconst [currentIndex, setCurrentIndex] = useState(0);\n\tconst [isExiting, setIsExiting] = useState(false);\n\tconst timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\tconst exitTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\tconst currentWord = words[currentIndex] ?? \"\";\n\tconst splitWords = currentWord.split(\" \").map((word) => ({\n\t\tword,\n\t\tletters: word.split(\"\"),\n\t}));\n\n\t// The pending timeouts read the CURRENT list, the way the source's closures\n\t// read the reactive `words` prop at fire time.\n\tconst wordsRef = useLiveRef(words);\n\n\t// `words.length`, never `words` itself. The array is an identity that a call\n\t// site like `words={[\"Hello\", \"World\"]}` re-allocates on every parent render;\n\t// keying the schedule on it would clear the pending timeout and re-arm a fresh\n\t// `duration` wait each time, so a parent re-rendering faster than `duration`\n\t// would stop the words flipping altogether. The source re-schedules only when\n\t// a tracked value actually changes, and `wordCount` is what its `< 2` guard\n\t// reads.\n\tconst wordCount = words.length;\n\n\tuseEffect(() => {\n\t\t// Re-schedule whenever a new word becomes active (not during exit).\n\t\tif (isExiting) return;\n\t\tif (wordCount < 2) return;\n\t\tif (timeoutRef.current) clearTimeout(timeoutRef.current);\n\t\ttimeoutRef.current = setTimeout(() => {\n\t\t\tif (wordsRef.current.length < 2) return;\n\t\t\tsetIsExiting(true);\n\t\t\tif (exitTimeoutRef.current) clearTimeout(exitTimeoutRef.current);\n\t\t\texitTimeoutRef.current = setTimeout(() => {\n\t\t\t\tsetIsExiting(false);\n\t\t\t\t// `words` can shrink to empty while this exit animation is in\n\t\t\t\t// flight (a parent clearing/reloading the list). Re-check the\n\t\t\t\t// CURRENT length here rather than trusting the length captured\n\t\t\t\t// when the timeout was armed: `% 0` is NaN, and once NaN lands\n\t\t\t\t// in state every future `(index + 1) % length` is NaN too — the\n\t\t\t\t// component would stay blank forever, even after `words` is\n\t\t\t\t// repopulated. Deferring to index 0 lets it resume normally.\n\t\t\t\tconst length = wordsRef.current.length;\n\t\t\t\tsetCurrentIndex((index) => (length === 0 ? 0 : (index + 1) % length));\n\t\t\t}, EXIT_MS);\n\t\t}, duration);\n\t}, [currentIndex, duration, isExiting, wordCount, wordsRef]);\n\n\tuseEffect(() => {\n\t\treturn () => {\n\t\t\tif (timeoutRef.current) clearTimeout(timeoutRef.current);\n\t\t\tif (exitTimeoutRef.current) clearTimeout(exitTimeoutRef.current);\n\t\t};\n\t}, []);\n\n\treturn (\n\t\t<div className=\"flip-words relative inline-block px-2\">\n\t\t\t<div\n\t\t\t\tkey={currentIndex}\n\t\t\t\tclassName={cn(\n\t\t\t\t\t\"relative z-10 inline-block text-left text-neutral-900 dark:text-neutral-100\",\n\t\t\t\t\tisExiting ? \"flip-words-exit\" : \"flip-words-enter\",\n\t\t\t\t\tclassName\n\t\t\t\t)}\n\t\t\t>\n\t\t\t\t{splitWords.map((wordObj, wordIndex) => (\n\t\t\t\t\t<span\n\t\t\t\t\t\tkey={wordObj.word + wordIndex}\n\t\t\t\t\t\tclassName=\"flip-words-word inline-block whitespace-nowrap opacity-0\"\n\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\tanimation: \"flipFadeInWord 0.3s ease forwards\",\n\t\t\t\t\t\t\tanimationDelay: `${wordIndex * 0.3}s`,\n\t\t\t\t\t\t}}\n\t\t\t\t\t>\n\t\t\t\t\t\t{wordObj.letters.map((letter, letterIndex) => (\n\t\t\t\t\t\t\t<span\n\t\t\t\t\t\t\t\tkey={wordObj.word + letterIndex}\n\t\t\t\t\t\t\t\tclassName=\"inline-block opacity-0\"\n\t\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\t\tanimation: \"flipFadeInLetter 0.2s ease forwards\",\n\t\t\t\t\t\t\t\t\tanimationDelay: `${wordIndex * 0.3 + letterIndex * 0.05}s`,\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t{letter}\n\t\t\t\t\t\t\t</span>\n\t\t\t\t\t\t))}\n\t\t\t\t\t\t{/* Explicit space: the source markup carries a collapsible space between\n\t\t\t\t\t\t    the letters and the trailing non-breaking space, and JSX drops the\n\t\t\t\t\t\t    newline-bearing whitespace that would otherwise stand in for it. */}\n\t\t\t\t\t\t{\" \"}\n\t\t\t\t\t\t<span className=\"inline-block\">&nbsp;</span>\n\t\t\t\t\t</span>\n\t\t\t\t))}\n\t\t\t</div>\n\t\t</div>\n\t);\n}\n","type":"registry:ui","target":"@ui/fancy/components/flip-words/FlipWords.tsx"},{"path":"react/src/components/flip-words/flip-words.css","content":"/* Keyframe names are part of the visual contract (referenced by inline\n   style attributes) — keep them identical to the source. */\n@keyframes flipFadeInWord {\n\t0% {\n\t\topacity: 0;\n\t\ttransform: translateY(10px);\n\t\tfilter: blur(8px);\n\t}\n\t100% {\n\t\topacity: 1;\n\t\ttransform: translateY(0);\n\t\tfilter: blur(0);\n\t}\n}\n\n@keyframes flipFadeInLetter {\n\t0% {\n\t\topacity: 0;\n\t\ttransform: translateY(10px);\n\t\tfilter: blur(8px);\n\t}\n\t100% {\n\t\topacity: 1;\n\t\ttransform: translateY(0);\n\t\tfilter: blur(0);\n\t}\n}\n\n@keyframes flipEnterWord {\n\t0% {\n\t\topacity: 0;\n\t\ttransform: translateY(10px);\n\t}\n\t100% {\n\t\topacity: 1;\n\t\ttransform: translateY(0);\n\t}\n}\n\n@keyframes flipExitWord {\n\t0% {\n\t\topacity: 1;\n\t\ttransform: translateY(0);\n\t\tfilter: blur(0);\n\t}\n\t100% {\n\t\topacity: 0;\n\t\ttransform: translateY(-10px);\n\t\tfilter: blur(8px);\n\t}\n}\n\n.flip-words {\n\t--flip-words-ms: 0.6s;\n}\n\n/* Rules anchored on the .flip-words root class (compiler scoping in the\n   source; plain CSS is global). */\n.flip-words .flip-words-enter {\n\tanimation: flipEnterWord var(--flip-words-ms) ease-in-out forwards;\n}\n\n.flip-words .flip-words-exit {\n\tanimation: flipExitWord var(--flip-words-ms) ease-in-out forwards;\n}\n","type":"registry:ui","target":"@ui/fancy/components/flip-words/flip-words.css"},{"path":"react/src/components/flip-words/index.ts","content":"\"use client\";\n\nexport { FlipWords } from \"./FlipWords\";\nexport type { FlipWordsProps } from \"./FlipWords\";\n","type":"registry:ui","target":"@ui/fancy/components/flip-words/index.ts"}],"meta":{"license":"MIT","package":"fancy-ui-react","version":"0.7.0","source":"https://fancy-ui.rama.app/docs/components/flip-words?framework=react"}}