motion-advanced

Motion Avanzado

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

Cuándo Activar

• Construir paneles que se descartan deslizando hacia abajo (drag-to-dismiss), 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, hacer morphing de 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 imperativamente con useAnimate
• Construir spinners, esqueletos shimmer, indicadores de pulso o estados de carga en botones

Salidas

Este skill produce:

• Interacciones de arrastre: tarjetas arrastrables, paneles que se descartan deslizando, listas Reorder.Group
• Hooks de gestos: detección de deslizamiento, pulsación larga, contorno de pellizco
• Componentes de animación de texto: revelación de palabras, máquina de escribir, contador numérico
• Animación SVG: dibujo de rutas, morphing 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 loader: 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() a mitad de camino cancela la animación anterior automáticamente.
• 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 prop 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 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 falla silenciosamente.
5. Los valores de movimiento no deben recrearse en cada render. useMotionValue(0) dentro del cuerpo de un componente es correcto; new MotionValue(0) en un render 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. El morphing SVG requiere recuentos iguales de comandos de ruta. Las rutas con diferentes estructuras de comando saltan en lugar de interpolar.

Guía de Decisión

Elegir la API avanzada correcta

Escenario	API
Arrastre con física al soltar	drag + dragTransition: springs.release
Lista ordenada arrastrando para reordenar	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
Pulsació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 de un solo uso	animate() de motion
Texto que entra palabra por palabra	Escalonamiento en spans inline-block
Dibujado de SVG	pathLength 0 → 1
Morphing SVG	Interpolación del atributo d (comandos iguales)
Progreso circular	Interpolación de strokeDashoffset

Cuándo usar useSpring vs una transición spring

	useSpring	transition: springs.*
Úsalo para	Seguidor de cursor, valores seguidos por el puntero	Cambios de estado discretos
Actualizaciones	Continuas, en cada frame	Desencadenadas 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 frame a medida que x cambia — sin setState, sin re-render

useAnimate

Devuelve [scope, animate]. El ref de ámbito debe estar adjunto a un elemento DOM. Las llamadas a animate() son seguras ante interrupciones — llamar a mitad de camino 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}
/>

Panel que se descarta deslizando

"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 pulsació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} />
}

Dibujado 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
      animate={controls}
      className="inline-block w-2 h-2 bg-indigo-500 rounded-full"
    />
  )
}