motion-advanced

Motion Advanced

Padrões de animação complexos, interativos e baseados em física. Requer que motion-foundations seja configurado primeiro. Use estes quando motion-patterns não for suficiente.

Quando Ativar

• Construindo folhas descartáveis por arrasto, gestos de deslize ou listas reordenáveis
• Animando texto palavra por palavra, caractere por caractere ou como um contador ao vivo
• Desenhando caminhos SVG, transformando ícones ou animando progresso circular
• Escrevendo um hook de animação personalizado (useScrollReveal, botão magnético, seguidor de cursor)
• Sequenciando animações de múltiplas etapas imperativamente com useAnimate
• Construindo spinners, shimmer skeletons, indicadores de pulso ou estados de carregamento de botão

Saídas

Este skill produz:

• Interações de arrastar: cartões arrastáveis, folhas descartáveis por arrasto, listas Reorder.Group
• Hooks de gesto: detecção de deslize, pressão longa, esboço de pinça
• Componentes de animação de texto: revelação de palavras, máquina de escrever de caracteres, contador numérico
• Animação SVG: desenho de caminho, transformação de ícone, anel de progresso de traço
• Hooks personalizados: useScrollReveal, useHoverScale, useNavigationDirection, useInViewOnce
• Sequências imperativas via useAnimate com async/await seguro contra interrupção
• Componentes de loader: spinner, shimmer, ponto de pulso, barra de progresso, estado de carregamento de botão

Princípios

• Movimento baseado em física (useSpring, springs.*) sempre parece mais natural do que baseado em duração para manipulação direta.
• useMotionValue + useTransform calcula valores derivados sem disparar re-renderizações.
• Sequências useAnimate são imperativas e seguras contra interrupção — chamar animate() durante a execução cancela automaticamente a animação anterior.
• Valores de movimento (useMotionValue, useSpring) são seguros para SSR e não causam erros de hidratação.

Regras

1. Interações de arrastar devem ser testadas em dispositivos touch, não apenas com mouse. A prop drag funciona em ambos, mas a sensação e o limite diferem.
2. Animações infinitas devem pausar quando document.visibilityState === "hidden". Abas em segundo plano não devem consumir GPU/CPU.
3. O limite de deslize deve ser explícito. Nunca infira intenção apenas com velocidade; combine verificações de offset + velocity.
4. O ref de escopo useAnimate deve ser anexado a um elemento DOM montado. Chamar animate() antes da montagem lança um erro silencioso.
5. Valores de movimento não devem ser recriados na renderização. useMotionValue(0) dentro do corpo do componente está correto; new MotionValue(0) em uma renderização não está.
6. Todos os valores de token são importados de motion-foundations. Sem números inline.
7. Hooks personalizados devem lidar com a limpeza. Cada window.addEventListener precisa de um removeEventListener correspondente no retorno do useEffect.
8. A transformação de SVG requer contagens iguais de comandos de caminho. Caminhos com estruturas de comando diferentes saltam em vez de interpolar.

Orientação de Decisão

Escolhendo a API avançada correta

Cenário	API
Arrastar com física na soltura	drag + dragTransition: springs.release
Lista ordenada arrastável para reordenar	Reorder.Group + Reorder.Item
Descartar no deslocamento de arrasto	drag="y" + verificação de offset onDragEnd
Deslizar esquerda/direita	drag="x" + verificação de offset onDragEnd
Pressão longa	Hook useLongPress
Valor suavizado ao longo do tempo	useSpring
Valor derivado de outro	useTransform
Sequência de múltiplas etapas	useAnimate com async/await
Animação imperativa única	animate() de motion
Texto entrando palavra por palavra	Escalonamento em spans inline-block
Desenho de SVG	pathLength 0 → 1
Transformação de SVG	Interpolação do atributo d (comandos iguais)
Progresso circular	Interpolação de strokeDashoffset

Quando usar useSpring vs uma transição spring

	useSpring	transition: springs.*
Use para	Seguidor de cursor, valores rastreados por ponteiro	Mudanças de estado discretas
Atualizações	Contínuas, a cada quadro	Acionadas por mudança de estado
Interrupção	Suave — a física continua a partir da velocidade	Reinicia a partir do valor atual

Conceitos Principais

useMotionValue + useTransform

Computação reativa sem re-renderizações:

const x = useMotionValue(0)
const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0])
// opacity é atualizada a cada quadro à medida que x muda — sem setState, sem re-renderização

useAnimate

Retorna [scope, animate]. O ref de escopo deve ser anexado a um elemento DOM. Chamadas animate() são seguras contra interrupção — chamar durante a execução cancela a execução 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 e esquece
}

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

Exemplos de Código

Cartão arrastável

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

Folha descartável por arrasto

"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) => {
        // Regra 3: combinar offset + velocity
        if (info.offset.y > 120 || info.velocity.y > 500) onClose()
      }}
    />
  )
}

Lista reordenável

"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>
  )
}

Detecção de deslize

"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 pressão longa

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),
  }
}

Revelação palavra por palavra

"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   // Regra 7: limpeza
  }, [to])

  return <span ref={nodeRef} />
}

Desenho de caminho 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 }}
/>

Anel de progresso de traço

"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)   // Regra 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 }}
    />
  )
}

Shimmer skeleton

"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 carregamento de botão

"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>
  )
}

Animação infinita com pausa de visibilidade

"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 },
      })

    // Regra 2: pausar quando a aba estiver 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="w-3 h-3 rounded-full bg-indigo-500 block"
      animate={controls}
    />
  )
}

Posicionamento/sticky com scroll

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

export function ParallaxSection() {
  const ref = useRef(null)
  const { scrollYProgress } = useScroll({ target: ref, offset: ["start end", "end start"] })
  const y = useTransform(scrollYProgress, [0, 1], ["-30%", "30%"])

  return (
    <section ref={ref} className="relative overflow-hidden h-[60vh]">
      <motion.div
        className="absolute inset-0 bg-cover bg-center"
        style={{ backgroundImage: "url('/image.jpg')", y }}
      />
    </section>
  )
}

Animação de entrada em grade com escala

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

const container = {
  hidden: {},
  visible: {
    transition: { staggerChildren: 0.1, delayChildren: 0.3 },
  },
}

const item = {
  hidden: { opacity: 0, scale: 0.8 },
  visible: { opacity: 1, scale: 1, transition: springs.gentle },
}

export function StaggerGrid({ items }: { items: string[] }) {
  return (
    <motion.div
      className="grid grid-cols-3 gap-4"
      variants={container}
      initial="hidden"
      animate="visible"
    >
      {items.map((itemText, i) => (
        <motion.div key={i} className="bg-gray-100 p-4 rounded" variants={item}>
          {itemText}
        </motion.div>
      ))}
    </motion.div>
  )
}

Integração de Roteador e Performance no Next.js

• Componentes de Cliente: Todos os hooks de animação (useMotionValue, useAnimate, useScroll) requerem "use client".
• Rotas de Servidor: Páginas estáticas podem importar componentes animados sem marcar a página inteira como cliente. Mantenha os componentes de animação em arquivos separados com "use client".
• Pré-carregamento de Links do Next.js: Componentes animados em viewport são pré-carregados; cache de rota é preservado entre navegações, então estados de animação podem persistir ou redefinir conforme o design.
• Performance de Animação: Use useSpring para valores rastreados por ponteiro para evitar pular quadros. Prefira animações transform e opacity para ativar a aceleração de GPU.