sinapse-ai 9.3.0 → 9.5.0

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

@@ -1,710 +0,0 @@
-# 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