Text Reveal

npx shadcn@latest add https://ui.zyeon.ai/r/text-reveal.json

Build a React + TypeScript + Tailwind "TextReveal" component.

Contract
- Shared primitive: use-prefers-reduced-motion (installed automatically via
  registryDependencies) — usePrefersReducedMotion() decides whether the
  IntersectionObserver is created at all. If rebuilding without it: a
  useSyncExternalStore over matchMedia("(prefers-reduced-motion: reduce)")
  with a "change" listener and a server snapshot of false.
- Export a forwardRef span extending React.HTMLAttributes<HTMLSpanElement>.
- Props: text (string), by = "word" | "char" (default "word"), stagger
  (ms of animation-delay added per unit, default 40), duration (ms,
  entrance animation length shared by every unit, default 500), once
  (boolean, default true — play once and stop observing; false resets
  and replays every time the element re-enters the viewport).

Behavior
- Split `text` into units at mount: "word" splits on a capturing
  whitespace regex so the whitespace runs stay in the array untouched
  (natural line wrapping, no animation, no stagger index consumed);
  "char" splits on Unicode code points (Array.from) and treats space
  characters the same way as the whitespace runs in word mode. Only
  non-whitespace units get a sequential index used for the stagger delay.
- Attach ONE IntersectionObserver to the root span (threshold 0.3). On
  the first intersecting entry, set visible = true; when once is true,
  disconnect the observer right there. When once is false, also flip
  visible back to false on an entry that leaves the viewport, so the
  next entry replays the entrance from scratch. Disconnect on unmount.
- Reset visible to false when text or by change, using the
  adjust-state-during-render pattern (compare a previous key, no effect).
- Each unit is inline-block and starts hidden through
  motion-safe:[@media(scripting:enabled)]:opacity-0 — only where the
  entrance can actually run, so the server-rendered text stays legible
  with JavaScript off. Only once visible and motion is not reduced does a
  unit get an inline
  `animation: tr-in <duration>ms ease-out <index * stagger>ms both`,
  fading in while translating up 0.4em and un-blurring from 4px.
- Read prefers-reduced-motion via useSyncExternalStore on matchMedia
  (server snapshot false). When reduced, skip creating the observer
  entirely — the hidden start state is motion-safe only, so pure CSS shows
  every unit immediately and reduced-motion users never wait on JS. Keep
  the two conditions in one stacked variant: a separate
  motion-reduce:opacity-100 would lose to the arbitrary media variant,
  which Tailwind emits later.

Rendering & styling
- Semantic tokens only; the component sets no font-size or color of its
  own — it inherits typography from className / surrounding context.
- Ship the @keyframes via a React 19 hoisted <style href precedence> tag
  — no Tailwind config edits, dedupes by href.
- Accessibility: a <span className="sr-only">{text}</span> inside the
  root carries the whole sentence; the inner layer holding the split unit
  spans is aria-hidden, since mid-animation fragments are noise for screen
  readers. Do not put aria-label on the root instead: ARIA prohibits naming
  a role-less (generic) span, and NVDA / JAWS browse mode would skip it.

Customization levers
- Pace: stagger 20–30ms reads well for long paragraphs, 40–60ms suits
  short punchy headlines — bigger gaps make the reveal feel more
  deliberate.
- Direction: swap translateY(0.4em) for translateY(-0.4em) (drop from
  above) or a translateX for a sideways sweep.
- Intensity: raise or lower the 4px blur, or drop the filter entirely
  for a plain fade-and-rise.
- Replay: once=false to replay on every re-entry (good for demos/specs
  sections users scroll past repeatedly); pair with a lower threshold
  if the trigger should fire earlier.