motion-advanced

Motion Avanzado

Patrones de animación complejos, interactivos y basados en física. Requiere tener configurado motion-foundations primero. Úsalos cuando motion-patterns no sea suficiente.

Cuándo activarlo

• Construir hojas deslizables para descartar, gestos de deslizamiento o listas reordenables
• Animar texto palabra por palabra, carácter por carácter o como un contador en vivo
• Dibujar rutas SVG, transformar iconos o animar progreso circular
• Escribir un hook de animación personalizado (useScrollReveal, botón magnético, seguidor de cursor)
• Secuenciar animaciones de varios pasos de manera imperativa con useAnimate
• Construir spinners, esqueletos shimmer, indicadores de pulso o estados de botón de carga

Resultados

Esta skill produce:

• Interacciones de arrastre: tarjetas arrastrables, hojas deslizables para descartar, listas Reorder.Group
• Hooks de gestos: detección de deslizamiento, presión larga, contorno de pellizco
• Componentes de animación de texto: revelación de palabras, máquina de escribir de caracteres, contador numérico
• Animación SVG: dibujo de rutas, transformación de iconos, anillo de progreso de trazo
• Hooks personalizados: useScrollReveal, useHoverScale, useNavigationDirection, useInViewOnce
• Secuencias imperativas mediante useAnimate con async/await seguro ante interrupciones
• Componentes de carga: spinner, shimmer, punto de pulso, barra de progreso, estado de carga de botón

Principios

• El movimiento basado en física (useSpring, springs.*) siempre se siente más natural que el basado en duración para manipulación directa.
• useMotionValue + useTransform calcula valores derivados sin provocar re-renderizados.
• Las secuencias de useAnimate son imperativas y seguras ante interrupciones: llamar a animate() en medio del vuelo cancela automáticamente la animación anterior.
• Los valores de movimiento (useMotionValue, useSpring) son seguros para SSR y no causan errores de hidratación.

Reglas

1. Las interacciones de arrastre deben probarse en dispositivos táctiles, no solo con el ratón. La propiedad drag funciona en ambos, pero la sensación y el umbral difieren.
2. Las animaciones infinitas deben pausarse cuando document.visibilityState === "hidden". Las pestañas en segundo plano no deben consumir GPU/CPU.
3. El umbral de deslizamiento debe ser explícito. Nunca inferir la intención solo a partir de la velocidad; combinar comprobaciones de offset + velocity.
4. El ref de ámbito de useAnimate debe estar adjunto a un elemento DOM montado. Llamar a animate() antes del montaje lanza un error silencioso.
5. Los valores de movimiento no deben recrearse en cada renderizado. useMotionValue(0) dentro del cuerpo de un componente es correcto; new MotionValue(0) en un renderizado no lo es.
6. Todos los valores de token se importan de motion-foundations. Sin números inline.
7. Los hooks personalizados deben manejar la limpieza. Cada window.addEventListener necesita un removeEventListener correspondiente en el retorno del useEffect.
8. La transformación de SVG requiere igual número de comandos de ruta. Las rutas con diferentes estructuras de comandos saltan en lugar de interpolarse.

Guía de decisión

Elegir la API avanzada correcta

Escenario	API
Arrastre con física al soltar	drag + dragTransition: springs.release
Lista ordenada arrastrable	Reorder.Group + Reorder.Item
Descartar al arrastrar	drag="y" + comprobación de offset en onDragEnd
Deslizar izquierda/derecha	drag="x" + comprobación de offset en onDragEnd
Presión larga	Hook useLongPress
Valor suavizado en el tiempo	useSpring
Valor derivado de otro	useTransform
Secuencia de varios pasos	useAnimate con async/await
Animación imperativa única	animate() de motion
Texto que aparece palabra por palabra	Escalonamiento en spans inline-block
Dibujo de SVG	pathLength 0 → 1
Transformación de SVG	Interpolación del atributo d (mismos comandos)
Progreso circular	Interpolación de strokeDashoffset

Cuándo usar useSpring frente a una transición spring

	useSpring	transition: springs.*
Úsalo para	Seguidor de cursor, valores rastreados por puntero	Cambios de estado discretos
Actualizaciones	Continuas, en cada fotograma	Activadas por cambio de estado
Interrupción	Suave: la física retoma desde la velocidad	Se reinicia desde el valor actual

Conceptos clave

useMotionValue + useTransform

Cómputo reactivo sin re-renderizados:

const x = useMotionValue(0)
const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0])
// la opacidad se actualiza en cada fotograma a medida que x cambia — sin setState, sin re-renderizado

useAnimate

Devuelve [scope, animate]. El ref de ámbito debe estar adjunto a un elemento DOM. Las llamadas a animate() son seguras ante interrupciones: llamar en medio del vuelo cancela la ejecución anterior.

const [scope, animate] = useAnimate()

async function play() {
  await animate(".step-1", { opacity: 1 }, { duration: 0.3 })
  await animate(".step-2", { x: 0 },       { duration: 0.4 })
        animate(".step-3", { scale: 1 },    { duration: 0.25 })  // dispara y olvida
}

return <div ref={scope}>...</div>

Ejemplos de código

Tarjeta arrastrable

"use client"
import { motion } from "motion/react"
import { springs, motionTokens } from "@/lib/motion-tokens"

<motion.div
  drag
  dragConstraints={{ left: -100, right: 100, top: -100, bottom: 100 }}
  dragElastic={0.1}
  whileDrag={{
    scale: motionTokens.scale.pop,
    boxShadow: "0 16px 40px rgba(0,0,0,0.2)",
  }}
  dragTransition={springs.release}
/>

Hoja deslizable para descartar

"use client"
import { motion, useMotionValue, useTransform } from "motion/react"

export function BottomSheet({ onClose }: { onClose: () => void }) {
  const y = useMotionValue(0)
  const opacity = useTransform(y, [0, 200], [1, 0])

  return (
    <motion.div
      drag="y"
      dragConstraints={{ top: 0 }}
      style={{ y, opacity }}
      onDragEnd={(_, info) => {
        // Regla 3: combinar offset + velocity
        if (info.offset.y > 120 || info.velocity.y > 500) onClose()
      }}
    />
  )
}

Lista reordenable

"use client"
import { Reorder } from "motion/react"

export function SortableList() {
  const [items, setItems] = useState(initialItems)
  return (
    <Reorder.Group axis="y" values={items} onReorder={setItems}>
      {items.map((item) => (
        <Reorder.Item key={item.id} value={item}>
          {item.label}
        </Reorder.Item>
      ))}
    </Reorder.Group>
  )
}

Detección de deslizamiento

"use client"
import { motion } from "motion/react"

const OFFSET_THRESHOLD  = 50
const VELOCITY_THRESHOLD = 300

<motion.div
  drag="x"
  dragConstraints={{ left: 0, right: 0 }}
  onDragEnd={(_, info) => {
    const swipedRight = info.offset.x > OFFSET_THRESHOLD  || info.velocity.x > VELOCITY_THRESHOLD
    const swipedLeft  = info.offset.x < -OFFSET_THRESHOLD || info.velocity.x < -VELOCITY_THRESHOLD
    if (swipedRight) onSwipeRight()
    if (swipedLeft)  onSwipeLeft()
  }}
/>

Hook de presión larga

import { useRef } from "react"

export function useLongPress(callback: () => void, ms = 600) {
  const timerRef = useRef<ReturnType<typeof setTimeout>>()
  return {
    onPointerDown:  () => { timerRef.current = setTimeout(callback, ms) },
    onPointerUp:    () => clearTimeout(timerRef.current),
    onPointerLeave: () => clearTimeout(timerRef.current),
  }
}

Revelación palabra por palabra

"use client"
import { motion } from "motion/react"
import { springs } from "@/lib/motion-tokens"

export function AnimatedText({ text }: { text: string }) {
  return (
    <motion.p
      variants={{ visible: { transition: { staggerChildren: 0.05 } } }}
      initial="hidden"
      animate="visible"
    >
      {text.split(" ").map((word, i) => (
        <motion.span
          key={i}
          className="inline-block mr-1"
          variants={{
            hidden:  { opacity: 0, y: 12 },
            visible: { opacity: 1, y: 0, transition: springs.gentle },
          }}
        >
          {word}
        </motion.span>
      ))}
    </motion.p>
  )
}

Contador numérico

"use client"
import { useRef, useEffect } from "react"
import { animate } from "motion"
import { motionTokens } from "@/lib/motion-tokens"

export function Counter({ to }: { to: number }) {
  const nodeRef = useRef<HTMLSpanElement>(null)

  useEffect(() => {
    const controls = animate(0, to, {
      duration: motionTokens.duration.crawl,
      ease: motionTokens.easing.smooth,
      onUpdate: (v) => {
        if (nodeRef.current) nodeRef.current.textContent = Math.round(v).toString()
      },
    })
    return controls.stop   // Regla 7: limpieza
  }, [to])

  return <span ref={nodeRef} />
}

Dibujo de ruta SVG

"use client"
import { motion } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"

<motion.path
  d="M 0 100 Q 50 0 100 100"
  initial={{ pathLength: 0, opacity: 0 }}
  animate={{ pathLength: 1, opacity: 1 }}
  transition={{ duration: motionTokens.duration.slow, ease: motionTokens.easing.smooth }}
/>

Anillo de progreso de trazo

"use client"
import { motion } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"

const CIRCUMFERENCE = 2 * Math.PI * 40   // r=40

export function ProgressRing({ progress }: { progress: number }) {
  return (
    <svg width="100" height="100" viewBox="0 0 100 100">
      <circle cx="50" cy="50" r="40" fill="none" stroke="#e5e7eb" strokeWidth="8" />
      <motion.circle
        cx="50" cy="50" r="40"
        fill="none" stroke="#6366f1" strokeWidth="8"
        strokeLinecap="round"
        strokeDasharray={CIRCUMFERENCE}
        animate={{ strokeDashoffset: CIRCUMFERENCE - (progress / 100) * CIRCUMFERENCE }}
        transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth }}
        style={{ rotate: -90, transformOrigin: "center" }}
      />
    </svg>
  )
}

Hook useScrollReveal

"use client"
import { useRef } from "react"
import { useScroll, useTransform } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"

export function useScrollReveal() {
  const ref = useRef(null)
  const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] })
  const opacity = useTransform(scrollYProgress, [0, 0.3], [0, 1])
  const y       = useTransform(scrollYProgress, [0, 0.3], [motionTokens.distance.lg, 0])
  return { ref, style: { opacity, y } }
}

// Uso
const { ref, style } = useScrollReveal()
<motion.section ref={ref} style={style} />

Seguidor de cursor

"use client"
import { useEffect } from "react"
import { motion, useMotionValue, useSpring } from "motion/react"
import { springs } from "@/lib/motion-tokens"

export function CursorFollower() {
  const x = useMotionValue(-100)
  const y = useMotionValue(-100)
  const sx = useSpring(x, springs.gentle)
  const sy = useSpring(y, springs.gentle)

  useEffect(() => {
    const move = (e: MouseEvent) => { x.set(e.clientX); y.set(e.clientY) }
    window.addEventListener("mousemove", move)
    return () => window.removeEventListener("mousemove", move)   // Regla 7
  }, [])

  return (
    <motion.div
      className="fixed top-0 left-0 w-6 h-6 rounded-full bg-indigo-500
                 pointer-events-none -translate-x-1/2 -translate-y-1/2 z-50"
      style={{ x: sx, y: sy }}
    />
  )
}

Esqueleto shimmer

"use client"
import { useEffect } from "react"
import { motion, useAnimation } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"

export function ShimmerSkeleton({ className = "" }: { className?: string }) {
  const controls = useAnimation()

  useEffect(() => {
    const play = () =>
      controls.start({
        x: ["-100%", "100%"],
        transition: {
          repeat: Infinity,
          duration: motionTokens.duration.crawl,
          ease: motionTokens.easing.linear,
        },
      })

    const handleVisibility = () => {
      if (document.visibilityState === "hidden") controls.stop()
      else void play()
    }

    void play()
    document.addEventListener("visibilitychange", handleVisibility)
    return () => {
      controls.stop()
      document.removeEventListener("visibilitychange", handleVisibility)
    }
  }, [controls])

  return (
    <div className={`relative overflow-hidden bg-gray-200 rounded ${className}`}>
      <motion.div
        className="absolute inset-0 bg-gradient-to-r from-transparent via-white/60 to-transparent"
        initial={{ x: "-100%" }}
        animate={controls}
      />
    </div>
  )
}

Estado de carga de botón

"use client"
import { motion, AnimatePresence } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"

export function LoadingButton({
  loading,
  label,
  onClick,
}: {
  loading: boolean
  label: string
  onClick: () => void
}) {
  return (
    <motion.button
      onClick={onClick}
      animate={{ opacity: loading ? 0.7 : 1 }}
      whileTap={loading ? {} : { scale: motionTokens.scale.press }}
      transition={springs.snappy}
      disabled={loading}
    >
      <AnimatePresence mode="wait">
        {loading ? (
          <motion.span
            key="loading"
            initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
            transition={{ duration: motionTokens.duration.fast }}
          >
            …
          </motion.span>
        ) : (
          <motion.span
            key="label"
            initial={{ opacity: 0 }} animate={{ opacity: 1 }} exit={{ opacity: 0 }}
            transition={{ duration: motionTokens.duration.fast }}
          >
            {label}
          </motion.span>
        )}
      </AnimatePresence>
    </motion.button>
  )
}

Animación infinita con pausa por visibilidad

"use client"
import { useEffect } from "react"
import { motion, useAnimation } from "motion/react"
import { motionTokens } from "@/lib/motion-tokens"

export function PulseDot() {
  const controls = useAnimation()

  useEffect(() => {
    const pulse = () =>
      controls.start({
        scale: [1, 1.4, 1],
        opacity: [1, 0.6, 1],
        transition: { repeat: Infinity, duration: motionTokens.duration.crawl },
      })

    // Regla 2: pausar cuando la pestaña está oculta
    const handleVisibility = () => {
      if (document.visibilityState === "hidden") controls.stop()
      else void pulse()
    }

    void pulse()
    document.addEventListener("visibilitychange", handleVisibility)
    return () => {
      controls.stop()
      document.removeEventListener("visibilitychange", handleVisibility)
    }
  }, [controls])

  return (
    <motion.span
      className="inline-block w-3 h-3 rounded-full bg-indigo-500"
      animate={controls}
    />
  )
}