{
  "schemaVersion": 1,
  "target": "react",
  "name": "text-reveal",
  "version": "0.1.0",
  "category": "core",
  "title": "Text Reveal",
  "description": "Reveals text as a whole, by line, by word, or by character with a fade, a short rise, or a blur that comes into focus, on mount, in view, or on demand.",
  "tags": [
    "text",
    "typography",
    "reveal",
    "stagger",
    "blur",
    "motion"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {
    "motion": "^14.14.0"
  },
  "registryDependencies": [],
  "docsPath": "/components/text-reveal",
  "props": [
    {
      "name": "children",
      "type": "string",
      "description": "The text to reveal. Plain text, so it can be split."
    },
    {
      "name": "by",
      "type": "\"whole\" | \"line\" | \"word\" | \"character\"",
      "default": "\"word\"",
      "description": "The unit that appears together. Lines are measured from where the text wraps and re-measured on resize."
    },
    {
      "name": "effect",
      "type": "\"fade\" | \"rise\" | \"blur\"",
      "default": "\"rise\"",
      "description": "Opacity only, a short lift, or a blur that sharpens."
    },
    {
      "name": "trigger",
      "type": "\"mount\" | \"inView\" | \"manual\"",
      "default": "\"mount\"",
      "description": "When to reveal: on first render, once scrolled into view, or following show."
    },
    {
      "name": "show",
      "type": "boolean",
      "default": "true",
      "description": "With trigger=\"manual\", shows the text when true and hides it with a quick plain fade when false."
    },
    {
      "name": "stagger",
      "type": "number",
      "description": "Seconds between pieces. Defaults to 0.09 for lines, 0.04 for words and 0.016 for characters."
    },
    {
      "name": "maxSpread",
      "type": "number",
      "default": "1.2",
      "description": "The longest time in seconds between the first and last piece starting; long texts compress the stagger to fit."
    },
    {
      "name": "delay / duration",
      "type": "number",
      "description": "Seconds before the first piece, and seconds each piece takes."
    },
    {
      "name": "as",
      "type": "\"p\" | \"span\" | \"div\" | \"h1\" to \"h4\" | \"blockquote\" | \"figcaption\" | \"li\"",
      "default": "\"p\"",
      "description": "Element to render."
    },
    {
      "name": "onRevealComplete",
      "type": "() => void",
      "description": "Called once the last piece has appeared."
    }
  ],
  "accessibility": [
    "The full text sits once in the accessibility tree in a visually hidden span; the split pieces are aria-hidden, so screen readers never read it letter by letter.",
    "Headings keep their role and their accessible name is the full text.",
    "Characters of one word stay in one unbreakable group, and graphemes such as emoji are split with Intl.Segmenter so they never break apart.",
    "Hiding is a short fade without movement.",
    "With reduced motion preferred, the text appears at once with no movement, blur, or fade."
  ],
  "states": [
    "hidden",
    "revealing",
    "shown",
    "reduced motion"
  ],
  "files": [
    {
      "path": "ui/text-reveal.tsx",
      "content": "\"use client\";\n\nimport { motion, useInView, useReducedMotion, type Variants } from \"motion/react\";\nimport { type ComponentProps, type ElementType, useEffect, useLayoutEffect, useMemo, useRef, useState } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nexport type TextRevealBy = \"whole\" | \"line\" | \"word\" | \"character\";\nexport type TextRevealEffect = \"fade\" | \"rise\" | \"blur\";\nexport type TextRevealTrigger = \"mount\" | \"inView\" | \"manual\";\n\ntype RevealElement = \"p\" | \"span\" | \"div\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"blockquote\" | \"figcaption\" | \"li\";\n\nexport interface TextRevealProps extends Omit<ComponentProps<\"p\">, \"children\"> {\n  /** The text to reveal. Plain text only, so it can be split. */\n  children: string;\n  /** The unit that appears together: the whole block, each wrapped line, each word, or each character. */\n  by?: TextRevealBy;\n  /** `fade` changes opacity only, `rise` lifts each piece a little, `blur` brings each piece into focus. */\n  effect?: TextRevealEffect;\n  /** `mount` reveals on first render, `inView` when scrolled into view (once), `manual` follows `show`. */\n  trigger?: TextRevealTrigger;\n  /** With `trigger=\"manual\"`, shows the text when true and hides it when false. */\n  show?: boolean;\n  /** Seconds between pieces. Long texts compress it so the whole reveal stays under `maxSpread`. */\n  stagger?: number;\n  /** Seconds before the first piece starts. */\n  delay?: number;\n  /** Seconds each piece takes. Defaults depend on `by`. */\n  duration?: number;\n  /** The longest time, in seconds, between the first piece starting and the last one starting. */\n  maxSpread?: number;\n  /** Element to render. */\n  as?: RevealElement;\n  /** Called once the last piece has finished appearing. */\n  onRevealComplete?: () => void;\n}\n\nconst ease = [0.23, 1, 0.32, 1] as const;\n\n/** Reduced-motion preference, read only after hydration so server and client render the same markup first. */\nfunction useReducedMotionAfterMount() {\n  const reduce = useReducedMotion();\n  const [mounted, setMounted] = useState(false);\n  useEffect(() => setMounted(true), []);\n  return mounted && reduce === true;\n}\n\nconst defaults: Record<TextRevealBy, { stagger: number; duration: number }> = {\n  whole: { stagger: 0, duration: 0.6 },\n  line: { stagger: 0.09, duration: 0.6 },\n  word: { stagger: 0.04, duration: 0.5 },\n  character: { stagger: 0.016, duration: 0.42 },\n};\n\nconst hiddenState: Record<TextRevealEffect, Record<string, string | number>> = {\n  fade: { opacity: 0 },\n  rise: { opacity: 0, y: \"0.45em\" },\n  blur: { opacity: 0, y: \"0.1em\", filter: \"blur(8px)\" },\n};\n\nconst shownState: Record<TextRevealEffect, Record<string, string | number>> = {\n  fade: { opacity: 1 },\n  rise: { opacity: 1, y: \"0em\" },\n  blur: { opacity: 1, y: \"0em\", filter: \"blur(0px)\" },\n};\n\nfunction graphemes(word: string): string[] {\n  if (typeof Intl !== \"undefined\" && \"Segmenter\" in Intl) {\n    return Array.from(new Intl.Segmenter(undefined, { granularity: \"grapheme\" }).segment(word), (part) => part.segment);\n  }\n  return Array.from(word);\n}\n\ntype Token = { word: string; chars: string[]; index: number } | { space: string };\n\nfunction tokenize(text: string, by: TextRevealBy): Token[] {\n  const tokens: Token[] = [];\n  let index = 0;\n  for (const part of text.split(/(\\s+)/)) {\n    if (!part) continue;\n    if (/^\\s+$/.test(part)) tokens.push({ space: part });\n    else {\n      const chars = by === \"character\" ? graphemes(part) : [part];\n      tokens.push({ word: part, chars, index });\n      index += chars.length;\n    }\n  }\n  return tokens;\n}\n\n/**\n * Reveals text as a whole, by line, by word, or by character, with a fade, a short rise, or a\n * blur that comes into focus. Hiding is a quick plain fade, so leaving never competes with the\n * next thing on screen. The full text sits once in the accessibility tree; the animated pieces\n * are hidden from screen readers.\n */\nexport function TextReveal({\n  children: text,\n  by = \"word\",\n  effect = \"rise\",\n  trigger = \"mount\",\n  show = true,\n  stagger,\n  delay = 0,\n  duration,\n  maxSpread = 1.2,\n  as = \"p\",\n  onRevealComplete,\n  className,\n  ...props\n}: TextRevealProps) {\n  const Root = as as ElementType;\n  const rootRef = useRef<HTMLElement>(null);\n  const reduceMotion = useReducedMotionAfterMount();\n  const inView = useInView(rootRef, { once: true, amount: 0.35 });\n  const visible = trigger === \"manual\" ? show : trigger === \"inView\" ? inView : true;\n\n  const tokens = useMemo(() => tokenize(text, by), [text, by]);\n  const wordCount = tokens.filter((token) => \"word\" in token).length;\n  const pieceCount = by === \"character\" ? tokens.reduce((sum, token) => sum + (\"chars\" in token ? token.chars.length : 0), 0) : wordCount;\n\n  // Lines are found by measuring where each word wrapped, and measured again when the width changes.\n  const wordRefs = useRef<(HTMLSpanElement | null)[]>([]);\n  const [lines, setLines] = useState<number[] | null>(null);\n  useLayoutEffect(() => {\n    if (by !== \"line\") return;\n    const root = rootRef.current;\n    if (!root) return;\n    const measure = () => {\n      let line = -1;\n      let lastTop = Number.NEGATIVE_INFINITY;\n      const next = wordRefs.current.slice(0, wordCount).map((element) => {\n        const top = element?.offsetTop ?? lastTop;\n        if (top > lastTop + 2) {\n          line += 1;\n          lastTop = top;\n        }\n        return Math.max(line, 0);\n      });\n      setLines((previous) => (previous && previous.join() === next.join() ? previous : next));\n    };\n    measure();\n    const observer = new ResizeObserver(measure);\n    observer.observe(root);\n    return () => observer.disconnect();\n  }, [by, wordCount, text]);\n\n  const timing = defaults[by];\n  const pieceDuration = duration ?? timing.duration;\n  const steps = by === \"line\" ? Math.max(0, ...(lines ?? [])) : Math.max(pieceCount - 1, 0);\n  const baseStagger = stagger ?? timing.stagger;\n  const spread = steps > 0 ? Math.min(baseStagger, maxSpread / steps) : 0;\n\n  const variants: Variants = useMemo(\n    () => ({\n      hidden: { ...hiddenState[effect], transition: { duration: 0.16, ease: \"easeOut\" } },\n      shown: (order: number) => ({ ...shownState[effect], transition: { duration: pieceDuration, ease, delay: delay + order * spread } }),\n    }),\n    [effect, pieceDuration, delay, spread],\n  );\n\n  const ready = by !== \"line\" || lines !== null;\n  const animateTo = visible && ready ? \"shown\" : \"hidden\";\n  const lastOrder = by === \"whole\" ? 0 : steps;\n\n  function piece(content: string, order: number, key: string | number, ref?: (element: HTMLSpanElement | null) => void) {\n    if (reduceMotion) {\n      return (\n        <span key={key} ref={ref} className={cx(\"inline-block whitespace-pre\", !visible && \"opacity-0\")}>\n          {content}\n        </span>\n      );\n    }\n    return (\n      <motion.span\n        key={key}\n        ref={ref}\n        custom={order}\n        variants={variants}\n        initial=\"hidden\"\n        animate={animateTo}\n        onAnimationComplete={order === lastOrder ? (definition) => definition === \"shown\" && onRevealComplete?.() : undefined}\n        className=\"inline-block whitespace-pre\"\n      >\n        {content}\n      </motion.span>\n    );\n  }\n\n  let visual;\n  if (by === \"whole\") {\n    visual = reduceMotion ? (\n      <span className={cx(!visible && \"opacity-0\")}>{text}</span>\n    ) : (\n      <motion.span\n        custom={0}\n        variants={variants}\n        initial=\"hidden\"\n        animate={animateTo}\n        onAnimationComplete={(definition) => definition === \"shown\" && onRevealComplete?.()}\n        className=\"inline-block\"\n      >\n        {text}\n      </motion.span>\n    );\n  } else {\n    let wordIndex = -1;\n    visual = tokens.map((token, tokenIndex) => {\n      if (\"space\" in token) return token.space;\n      wordIndex += 1;\n      const current = wordIndex;\n      const setRef = (element: HTMLSpanElement | null) => {\n        wordRefs.current[current] = element;\n      };\n      if (by === \"character\") {\n        // Characters of one word stay together so a word never breaks mid-reveal.\n        return (\n          <span key={tokenIndex} ref={setRef} className=\"inline-block whitespace-nowrap\">\n            {token.chars.map((char, charIndex) => piece(char, token.index + charIndex, charIndex))}\n          </span>\n        );\n      }\n      const order = by === \"line\" ? (lines?.[current] ?? 0) : current;\n      return piece(token.word, order, tokenIndex, setRef);\n    });\n  }\n\n  return (\n    <Root ref={rootRef} className={className} {...props}>\n      <span className=\"sr-only select-none\">{text}</span>\n      <span aria-hidden=\"true\">{visual}</span>\n    </Root>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "import { TextReveal } from \"@/components/shaken/ui/text-reveal\";\n\nexport default function TextRevealExample() {\n  return (\n    <div className=\"grid w-full max-w-md gap-3\">\n      <TextReveal as=\"h2\" by=\"word\" effect=\"rise\" className=\"text-2xl font-semibold tracking-[-0.02em] text-zinc-950 dark:text-white\">\n        Your agents closed 14 tickets overnight\n      </TextReveal>\n      <TextReveal by=\"line\" effect=\"blur\" delay={0.25} className=\"text-sm leading-relaxed text-zinc-600 dark:text-zinc-400\">\n        Three pull requests are waiting for review, and one deploy is paused until you approve the database migration it needs. Everything\n        else shipped without a retry.\n      </TextReveal>\n    </div>\n  );\n}\n"
  }
}
