sinapse-ai 9.2.0 → 9.3.0

package/squads/squad-animations/knowledge-base/framer-motion-complete-reference.md

@@ -0,0 +1,710 @@
+# Framer Motion — Complete Reference
+
+> Guia definitivo de Framer Motion para animacoes React de nivel producao.
+> Framer Motion e a biblioteca de animacao mais adotada em React/Next.js (23K+ stars).
+> Ideal para produtos, SaaS, e micro-interactions. GSAP e melhor para scroll storytelling complexo.
+
+---
+
+## Decision: Quando usar Framer Motion vs GSAP
+
+| Situacao | Use |
+|----------|-----|
+| Produto React/Next.js (SaaS, app) | Framer Motion |
+| Website criativo/portfolio/agencia | GSAP + Lenis |
+| Micro-interactions em componentes | Framer Motion |
+| Timeline complexo, scroll pinning | GSAP |
+| Shared element transitions | Framer Motion (layout prop) |
+| SVG morph/draw complexo | GSAP (DrawSVG, MorphSVG) |
+| Physics-based UI | Framer Motion (spring) |
+| 60fps animacao em 1000+ elementos | GSAP (mais performatico) |
+
+---
+
+## Setup
+
+```bash
+npm install framer-motion
+```
+
+### Bundle size (importante para decisao)
+- `framer-motion` completo: ~32KB gzip
+- `motion` (alias moderno): ~32KB gzip
+- Importacoes seletivas: usar `m` em vez de `motion` para menor bundle
+
+```tsx
+// Tree-shakeable — menor bundle
+import { m, LazyMotion, domAnimation } from 'framer-motion';
+
+function App() {
+  return (
+    <LazyMotion features={domAnimation}>
+      <m.div animate={{ opacity: 1 }} />
+    </LazyMotion>
+  );
+}
+```
+
+---
+
+## Fundamentos: motion.* Components
+
+O `motion.div` e um wrapper que adiciona capacidades de animacao a qualquer elemento HTML/SVG.
+
+```tsx
+import { motion } from 'framer-motion';
+
+// Animacao simples de entrada
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.5, ease: [0.16, 1, 0.3, 1] }}
+/>
+
+// Com saida
+<motion.div
+  initial={{ opacity: 0 }}
+  animate={{ opacity: 1 }}
+  exit={{ opacity: 0, y: -20 }}
+/>
+```
+
+### Propriedades principais
+
+| Prop | Tipo | Descricao |
+|------|------|-----------|
+| `initial` | TargetAndTransition | Estado inicial (antes de animar) |
+| `animate` | TargetAndTransition | Estado animado (alvo) |
+| `exit` | TargetAndTransition | Estado de saida (requer AnimatePresence) |
+| `transition` | Transition | Configuracao de timing/easing/spring |
+| `whileHover` | TargetAndTransition | Estado durante hover |
+| `whileTap` | TargetAndTransition | Estado durante press/tap |
+| `whileDrag` | TargetAndTransition | Estado durante drag |
+| `whileInView` | TargetAndTransition | Estado quando visivel no viewport |
+| `variants` | Variants | Sistema de estados nomeados |
+| `layout` | boolean/string | Ativar FLIP layout animations |
+| `layoutId` | string | Shared element transitions |
+| `drag` | boolean/string | Tornar draggable |
+| `style` | MotionStyle | Motion values em style |
+
+---
+
+## Variants — Sistema de Estados
+
+Variants permitem definir estados nomeados e coordenar animacoes entre pai e filhos.
+
+```tsx
+// Container + filhos com stagger
+const containerVariants = {
+  hidden: { opacity: 0 },
+  visible: {
+    opacity: 1,
+    transition: {
+      staggerChildren: 0.1,      // Delay entre cada filho
+      delayChildren: 0.2,        // Delay inicial antes do primeiro filho
+      when: 'beforeChildren',    // Container anima ANTES dos filhos
+    },
+  },
+  exit: {
+    opacity: 0,
+    transition: { staggerChildren: 0.05, staggerDirection: -1 }
+  }
+};
+
+const itemVariants = {
+  hidden: { opacity: 0, y: 30, scale: 0.95 },
+  visible: {
+    opacity: 1,
+    y: 0,
+    scale: 1,
+    transition: {
+      duration: 0.5,
+      ease: [0.16, 1, 0.3, 1],
+    },
+  },
+  exit: { opacity: 0, y: -20 }
+};
+
+function AnimatedList({ items }) {
+  return (
+    <motion.ul
+      variants={containerVariants}
+      initial="hidden"
+      animate="visible"
+      exit="exit"
+    >
+      {items.map(item => (
+        <motion.li key={item.id} variants={itemVariants}>
+          {item.name}
+        </motion.li>
+      ))}
+    </motion.ul>
+  );
+}
+```
+
+### Variantes de stagger patterns
+
+```tsx
+// Stagger from center
+const staggerFromCenter = {
+  visible: {
+    opacity: 1,
+    transition: {
+      staggerChildren: 0.08,
+      // Usando custom origin via index passado nas variants
+    },
+  },
+};
+
+// Stagger com velocidades diferentes por nivel
+const parentVariants = {
+  visible: { transition: { staggerChildren: 0.1 } }
+};
+
+const childVariants = {
+  visible: { transition: { staggerChildren: 0.05 } }
+};
+```
+
+---
+
+## AnimatePresence — Animacoes de Saida
+
+Sem `AnimatePresence`, animacoes de saida (exit) sao ignoradas. Ele monitora a arvore e permite que componentes se animem antes de ser removidos do DOM.
+
+```tsx
+import { AnimatePresence, motion } from 'framer-motion';
+
+// Modal com entrada e saida animada
+function Modal({ isOpen, onClose, children }) {
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <>
+          {/* Overlay */}
+          <motion.div
+            className="fixed inset-0 bg-black/50"
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            onClick={onClose}
+          />
+
+          {/* Modal */}
+          <motion.div
+            className="fixed inset-x-4 top-1/2 -translate-y-1/2 bg-white rounded-2xl p-6"
+            initial={{ opacity: 0, scale: 0.95, y: 20 }}
+            animate={{ opacity: 1, scale: 1, y: 0 }}
+            exit={{ opacity: 0, scale: 0.95, y: 20 }}
+            transition={{ type: 'spring', damping: 25, stiffness: 300 }}
+          >
+            {children}
+          </motion.div>
+        </>
+      )}
+    </AnimatePresence>
+  );
+}
+```
+
+### mode prop do AnimatePresence
+
+```tsx
+// "sync" (default) — entrada e saida simultaneous
+// "wait" — aguarda saida antes de iniciar entrada
+// "popLayout" — remove elemento do layout durante animacao de saida
+
+<AnimatePresence mode="wait">
+  {key && <motion.div key={key} />}
+</AnimatePresence>
+```
+
+### Page transitions com Next.js
+
+```tsx
+// app/layout.tsx
+'use client';
+import { AnimatePresence, motion } from 'framer-motion';
+import { usePathname } from 'next/navigation';
+
+const pageVariants = {
+  initial: { opacity: 0, y: 20 },
+  in: { opacity: 1, y: 0 },
+  out: { opacity: 0, y: -20 },
+};
+
+const pageTransition = {
+  duration: 0.3,
+  ease: [0.16, 1, 0.3, 1],
+};
+
+export function PageTransitionLayout({ children }) {
+  const pathname = usePathname();
+
+  return (
+    <AnimatePresence mode="wait">
+      <motion.div
+        key={pathname}
+        variants={pageVariants}
+        initial="initial"
+        animate="in"
+        exit="out"
+        transition={pageTransition}
+      >
+        {children}
+      </motion.div>
+    </AnimatePresence>
+  );
+}
+```
+
+---
+
+## Layout Animations (FLIP)
+
+`layout` prop ativa animacao automatica quando o layout muda — Framer Motion usa o algoritmo FLIP internamente para performance.
+
+```tsx
+// Reordenamento animado de lista
+function SortableList({ items }) {
+  return (
+    <motion.ul layout>
+      {items.map(item => (
+        <motion.li
+          key={item.id}
+          layout                          // Anima mudancas de posicao
+          initial={{ opacity: 0, scale: 0.8 }}
+          animate={{ opacity: 1, scale: 1 }}
+          exit={{ opacity: 0, scale: 0.8 }}
+          transition={{ type: 'spring', stiffness: 300, damping: 25 }}
+        >
+          {item.name}
+        </motion.li>
+      ))}
+    </motion.ul>
+  );
+}
+
+// Expandir/colapsar card com layout animation
+function ExpandableCard({ title, content }) {
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  return (
+    <motion.div
+      layout
+      className="card"
+      onClick={() => setIsExpanded(!isExpanded)}
+    >
+      <motion.h3 layout="position">{title}</motion.h3>
+      <AnimatePresence>
+        {isExpanded && (
+          <motion.p
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+          >
+            {content}
+          </motion.p>
+        )}
+      </AnimatePresence>
+    </motion.div>
+  );
+}
+```
+
+### Shared Element Transitions (layoutId)
+
+```tsx
+// Galeria com elemento compartilhado entre estados
+function Gallery({ images }) {
+  const [selectedId, setSelectedId] = useState(null);
+
+  return (
+    <>
+      {images.map(image => (
+        <motion.img
+          key={image.id}
+          layoutId={`image-${image.id}`}  // ID unico para o par
+          src={image.src}
+          className="thumbnail"
+          onClick={() => setSelectedId(image.id)}
+          style={{ cursor: 'pointer' }}
+        />
+      ))}
+
+      <AnimatePresence>
+        {selectedId && (
+          <motion.div className="overlay" onClick={() => setSelectedId(null)}>
+            <motion.img
+              layoutId={`image-${selectedId}`}  // Mesmo ID = elemento compartilhado
+              src={images.find(i => i.id === selectedId).src}
+              className="fullscreen"
+            />
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </>
+  );
+}
+```
+
+---
+
+## Gestures
+
+```tsx
+// Drag com constraints
+function DraggableCard() {
+  const constraintsRef = useRef(null);
+
+  return (
+    <div ref={constraintsRef} className="drag-area">
+      <motion.div
+        drag                                    // Drag em ambas as direcoes
+        dragConstraints={constraintsRef}        // Limitar ao container
+        dragElastic={0.1}                       // Elasticidade ao bater nos limites
+        dragMomentum={true}                     // Momentum apos soltar
+        whileDrag={{ scale: 1.1, rotate: 5 }}
+        onDragEnd={(event, info) => {
+          console.log(info.offset.x, info.velocity.x);
+        }}
+      >
+        Drag me
+      </motion.div>
+    </div>
+  );
+}
+
+// Swipe para dispensar (mobile pattern)
+function SwipeToDismiss({ onDismiss, children }) {
+  return (
+    <motion.div
+      drag="x"
+      dragConstraints={{ left: 0, right: 0 }}
+      dragElastic={1}
+      onDragEnd={(_, info) => {
+        if (Math.abs(info.offset.x) > 100) onDismiss();
+      }}
+      animate={{ x: 0 }}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+// Hover + tap combinados
+function InteractiveCard() {
+  return (
+    <motion.div
+      whileHover={{ y: -8, scale: 1.02 }}
+      whileTap={{ scale: 0.98 }}
+      transition={{ type: 'spring', stiffness: 400, damping: 17 }}
+      style={{ cursor: 'pointer' }}
+    >
+      Card content
+    </motion.div>
+  );
+}
+```
+
+---
+
+## useAnimation — Controle Imperativo
+
+```tsx
+import { useAnimation } from 'framer-motion';
+
+function ControlledAnimation() {
+  const controls = useAnimation();
+
+  const sequence = async () => {
+    await controls.start({ x: 100, transition: { duration: 0.3 } });
+    await controls.start({ y: 100, transition: { duration: 0.3 } });
+    await controls.start({ x: 0, y: 0, transition: { duration: 0.5 } });
+  };
+
+  return (
+    <>
+      <motion.div animate={controls} />
+      <button onClick={sequence}>Start sequence</button>
+    </>
+  );
+}
+```
+
+---
+
+## useMotionValue + useTransform — Motion Values Reativas
+
+```tsx
+import { motion, useMotionValue, useTransform, useSpring } from 'framer-motion';
+
+function TiltCard() {
+  const x = useMotionValue(0);
+  const y = useMotionValue(0);
+
+  // Transformar posicao do mouse em rotacao
+  const rotateX = useTransform(y, [-100, 100], [15, -15]);
+  const rotateY = useTransform(x, [-100, 100], [-15, 15]);
+
+  // Adicionar spring para suavizar
+  const springConfig = { stiffness: 150, damping: 20 };
+  const smoothRotateX = useSpring(rotateX, springConfig);
+  const smoothRotateY = useSpring(rotateY, springConfig);
+
+  function handleMouseMove(e) {
+    const rect = e.currentTarget.getBoundingClientRect();
+    x.set(e.clientX - rect.left - rect.width / 2);
+    y.set(e.clientY - rect.top - rect.height / 2);
+  }
+
+  function handleMouseLeave() {
+    x.set(0);
+    y.set(0);
+  }
+
+  return (
+    <motion.div
+      onMouseMove={handleMouseMove}
+      onMouseLeave={handleMouseLeave}
+      style={{ rotateX: smoothRotateX, rotateY: smoothRotateY, perspective: 1000 }}
+    >
+      Tilt card content
+    </motion.div>
+  );
+}
+
+// Scroll progress indicator
+import { useScroll } from 'framer-motion';
+
+function ScrollProgress() {
+  const { scrollYProgress } = useScroll();
+  const scaleX = useSpring(scrollYProgress, { stiffness: 100, damping: 30 });
+
+  return (
+    <motion.div
+      className="fixed top-0 left-0 right-0 h-1 bg-blue-500"
+      style={{ scaleX, transformOrigin: '0%' }}
+    />
+  );
+}
+```
+
+---
+
+## whileInView — Scroll Reveals
+
+```tsx
+// Reveal simples com viewport
+function ScrollReveal({ children }) {
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 50 }}
+      whileInView={{ opacity: 1, y: 0 }}
+      viewport={{
+        once: true,       // Anima apenas uma vez
+        margin: '-100px', // Triggeriza 100px antes de entrar
+        amount: 0.3,      // 30% visivel para triggerizar
+      }}
+      transition={{ duration: 0.6, ease: [0.16, 1, 0.3, 1] }}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+// Reveal de texto caractere a caractere
+function TextReveal({ text }) {
+  return (
+    <motion.span>
+      {text.split('').map((char, i) => (
+        <motion.span
+          key={i}
+          initial={{ opacity: 0, y: 20 }}
+          whileInView={{ opacity: 1, y: 0 }}
+          viewport={{ once: true }}
+          transition={{ delay: i * 0.03, duration: 0.4 }}
+          style={{ display: 'inline-block' }}
+        >
+          {char === ' ' ? '\u00A0' : char}
+        </motion.span>
+      ))}
+    </motion.span>
+  );
+}
+```
+
+---
+
+## Spring Physics — Referencia Rapida
+
+```tsx
+// Presets de spring para situacoes comuns
+const springs = {
+  snappy:  { type: 'spring', stiffness: 400, damping: 30 },   // Botoes, inputs
+  gentle:  { type: 'spring', stiffness: 100, damping: 15 },   // Cards, panels
+  bouncy:  { type: 'spring', stiffness: 200, damping: 10 },   // Notificacoes, badges
+  heavy:   { type: 'spring', stiffness: 200, damping: 25, mass: 3 }, // Drawers, modais grandes
+  wobbly:  { type: 'spring', stiffness: 150, damping: 8 },    // Playful, games
+};
+
+// Uso
+<motion.div transition={springs.snappy} whileTap={{ scale: 0.95 }} />
+```
+
+---
+
+## SVG Morphing com Framer Motion
+
+```tsx
+// Toggle icon (hamburger -> X)
+function MenuIcon({ isOpen }) {
+  return (
+    <svg viewBox="0 0 24 24" width={24} height={24}>
+      <motion.path
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={2}
+        strokeLinecap="round"
+        animate={{
+          d: isOpen
+            ? 'M6 18L18 6M6 6l12 12'    // X icon
+            : 'M4 6h16M4 12h16M4 18h16' // Hamburger
+        }}
+        transition={{ duration: 0.3, ease: [0.16, 1, 0.3, 1] }}
+      />
+    </svg>
+  );
+}
+
+// Progresso circular animado
+function CircularProgress({ progress }) {
+  const circumference = 2 * Math.PI * 45; // raio 45
+  const strokeDashoffset = circumference * (1 - progress);
+
+  return (
+    <svg viewBox="0 0 100 100" width={100} height={100}>
+      <circle cx="50" cy="50" r="45" fill="none" stroke="#eee" strokeWidth="8" />
+      <motion.circle
+        cx="50" cy="50" r="45"
+        fill="none"
+        stroke="#0066ff"
+        strokeWidth="8"
+        strokeLinecap="round"
+        strokeDasharray={circumference}
+        animate={{ strokeDashoffset }}
+        transition={{ duration: 0.5, ease: 'easeOut' }}
+        style={{ rotate: -90, transformOrigin: 'center' }}
+      />
+    </svg>
+  );
+}
+```
+
+---
+
+## Patterns Avancados
+
+### Botao com ripple effect
+
+```tsx
+function RippleButton({ children, onClick }) {
+  return (
+    <motion.button
+      whileHover={{ scale: 1.02, y: -2 }}
+      whileTap={{ scale: 0.98 }}
+      transition={springs.snappy}
+      onClick={onClick}
+      className="relative overflow-hidden"
+    >
+      {children}
+      <motion.span
+        className="absolute inset-0 bg-white/20 rounded-full"
+        initial={{ scale: 0, opacity: 1 }}
+        whileTap={{ scale: 4, opacity: 0 }}
+        transition={{ duration: 0.6 }}
+      />
+    </motion.button>
+  );
+}
+```
+
+### Loading skeleton com shimmer
+
+```tsx
+function Skeleton({ className }) {
+  return (
+    <motion.div
+      className={`rounded-md bg-gray-200 overflow-hidden ${className}`}
+      animate={{ opacity: [0.5, 1, 0.5] }}
+      transition={{ duration: 1.5, repeat: Infinity, ease: 'easeInOut' }}
+    />
+  );
+}
+```
+
+### Counter animado
+
+```tsx
+import { useMotionValue, useSpring, useEffect } from 'framer-motion';
+
+function AnimatedCounter({ to, duration = 2 }) {
+  const count = useMotionValue(0);
+  const rounded = useTransform(count, Math.round);
+  const spring = useSpring(count, { duration: duration * 1000 });
+
+  useEffect(() => {
+    spring.set(to);
+  }, [to]);
+
+  return <motion.span>{rounded}</motion.span>;
+}
+```
+
+---
+
+## Acessibilidade
+
+```tsx
+// prefers-reduced-motion
+import { useReducedMotion } from 'framer-motion';
+
+function AccessibleAnimation({ children }) {
+  const shouldReduceMotion = useReducedMotion();
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: shouldReduceMotion ? 0 : 30 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: shouldReduceMotion ? 0.01 : 0.5 }}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+// Hook personalizado para aplicar em toda a app
+function useMotionSafe() {
+  const shouldReduceMotion = useReducedMotion();
+
+  return {
+    transition: shouldReduceMotion
+      ? { duration: 0.01 }
+      : { duration: 0.5, ease: [0.16, 1, 0.3, 1] },
+    initial: shouldReduceMotion ? {} : { opacity: 0, y: 20 },
+    animate: { opacity: 1, y: 0 },
+  };
+}
+```
+
+---
+
+## Performance Tips
+
+1. **Evitar animar `width`/`height`** — usar `scaleX`/`scaleY` + `transformOrigin`
+2. **`layout` prop e pesada** — usar apenas quando necessario (FLIP tem custo)
+3. **`LazyMotion`** — carregar features sob demanda para menor bundle
+4. **`will-change`** — Framer Motion ja aplica automaticamente quando necessario
+5. **Evitar re-renders** — `useMotionValue` nao triggeriza re-render (diferente de `useState`)
+6. **`frameloop="demand"`** em Canvas R3F quando integrado com Framer Motion