@polymorphism-tech/morph-spec 4.15.0 → 4.17.0

package/framework/standards/frontend/gsap/gsap-core.md

@@ -0,0 +1,463 @@
+---
+scope: frontend-nextjs-ui
+layer: 3
+keywords: gsap, animation, timeline, tween, useGSAP, greensock, transform
+load_when: gsap-animator active
+---
+
+# GSAP Core & React Integration
+
+Reference guide for implementing animations in Next.js projects using GSAP and the official @gsap/react bindings. Covers core APIs, React integration via useGSAP, timeline sequencing, utility functions, performance, accessibility, and the decision boundary with Framer Motion.
+
+---
+
+## Section 1: When to Use GSAP vs Framer Motion
+
+| Need | Use | Why |
+|---|---|---|
+| Simple enter/exit, layout animations, gestures | Framer Motion | Declarative, React-native, less boilerplate |
+| ScrollTrigger (pin, scrub, parallax) | GSAP | No Framer equivalent for scroll-linked progress |
+| SVG morphing, path drawing | GSAP | MorphSVG, DrawSVG plugins |
+| Complex multi-step timelines | GSAP | Position parameter, labels, nested timelines |
+| SplitText, scramble effects | GSAP | Premium plugins, no Framer equivalent |
+| Drag with physics/inertia | GSAP | Draggable + InertiaPlugin |
+| AnimatePresence (mount/unmount) | Framer Motion | GSAP has no declarative mount/unmount |
+
+**CRITICAL RULE:** Never animate the same DOM element with both GSAP and Framer Motion simultaneously. They will fight for control of inline styles. Choose one library per element and stick with it.
+
+---
+
+## Section 2: Installation
+
+```bash
+npm install gsap @gsap/react
+```
+
+GSAP 3.12+ includes Flip, Observer, and ScrollToPlugin for free. Premium plugins (SplitText, MorphSVG, DrawSVG, MotionPath, Draggable, InertiaPlugin) require a Club GreenSock license — install via `gsap@npm:@gsap/shockingly`.
+
+### Plugin Registration
+
+Register plugins **once** at app init (e.g., `providers.tsx` or `layout.tsx`), not inside individual components:
+
+```typescript
+'use client';
+import gsap from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+import { Flip } from 'gsap/Flip';
+
+gsap.registerPlugin(ScrollTrigger, Flip);
+```
+
+Registering inside components causes redundant calls on every mount and risks race conditions if multiple components register different plugins.
+
+---
+
+## Section 3: Core Animation APIs
+
+### Tween Methods
+
+```typescript
+'use client';
+import gsap from 'gsap';
+
+// Animate FROM current state TO target
+gsap.to('.box', { x: 200, opacity: 1, duration: 0.5 });
+
+// Animate FROM target TO current state
+gsap.from('.box', { x: -200, opacity: 0, duration: 0.5 });
+
+// Explicit start and end states
+gsap.fromTo('.box',
+  { x: -200, opacity: 0 },
+  { x: 200, opacity: 1, duration: 0.5 }
+);
+
+// Instantly set properties (no animation)
+gsap.set('.box', { x: 0, opacity: 1 });
+```
+
+### Transform Shorthand Aliases
+
+GSAP provides shorthand aliases that map directly to CSS transforms:
+
+| Alias | CSS Equivalent |
+|---|---|
+| `x`, `y` | `translateX()`, `translateY()` |
+| `xPercent`, `yPercent` | `translateX(%)`, `translateY(%)` |
+| `rotation` | `rotate()` |
+| `scale`, `scaleX`, `scaleY` | `scale()`, `scaleX()`, `scaleY()` |
+| `skewX`, `skewY` | `skewX()`, `skewY()` |
+
+### autoAlpha
+
+Use `autoAlpha` instead of `opacity`. It behaves identically to `opacity` but automatically sets `visibility: hidden` when the value reaches 0, removing the element from the accessibility tree and preventing invisible click targets.
+
+```typescript
+'use client';
+import gsap from 'gsap';
+
+// Element becomes visibility:hidden at autoAlpha:0
+gsap.to('.overlay', { autoAlpha: 0, duration: 0.3 });
+
+// Reveal: sets visibility:visible then animates opacity
+gsap.to('.overlay', { autoAlpha: 1, duration: 0.3 });
+```
+
+---
+
+## Section 4: React/Next.js Integration
+
+The `useGSAP()` hook from `@gsap/react` is the canonical pattern for GSAP in React. It replaces manual `useEffect` + `gsap.context()` cleanup.
+
+```typescript
+'use client';
+import { useRef } from 'react';
+import { useGSAP } from '@gsap/react';
+import gsap from 'gsap';
+
+function AnimatedComponent() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useGSAP(() => {
+    gsap.to('.box', { x: 100, rotation: 360, duration: 1 });
+  }, { scope: containerRef }); // scopes selectors to this container
+
+  return (
+    <div ref={containerRef}>
+      <div className="box">Animated</div>
+    </div>
+  );
+}
+```
+
+### Scope Refs
+
+**ALWAYS** pass `{ scope: containerRef }` to `useGSAP`. This scopes all string selectors (e.g., `'.box'`) to descendants of that container, preventing your animations from accidentally targeting elements in other components.
+
+### contextSafe for Event Handlers
+
+Animations created outside the `useGSAP` callback (e.g., in click handlers) must be wrapped with `contextSafe()` to ensure proper cleanup:
+
+```typescript
+'use client';
+import { useRef } from 'react';
+import { useGSAP } from '@gsap/react';
+import gsap from 'gsap';
+
+function ClickAnimated() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const { contextSafe } = useGSAP({ scope: containerRef });
+
+  const handleClick = contextSafe(() => {
+    gsap.to('.box', { rotation: '+=360', duration: 0.6 });
+  });
+
+  return (
+    <div ref={containerRef}>
+      <div className="box" onClick={handleClick}>Click me</div>
+    </div>
+  );
+}
+```
+
+### Dependencies Array
+
+Pass a dependencies array as the second element of the options to re-run the animation when values change:
+
+```typescript
+'use client';
+import { useState, useRef } from 'react';
+import { useGSAP } from '@gsap/react';
+import gsap from 'gsap';
+
+function ResponsiveAnimation() {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [isOpen, setIsOpen] = useState(false);
+
+  useGSAP(() => {
+    gsap.to('.panel', { height: isOpen ? 'auto' : 0, duration: 0.4 });
+  }, { scope: containerRef, dependencies: [isOpen] });
+
+  return (
+    <div ref={containerRef}>
+      <button onClick={() => setIsOpen(!isOpen)}>Toggle</button>
+      <div className="panel">Content</div>
+    </div>
+  );
+}
+```
+
+### Cleanup
+
+`useGSAP` handles cleanup automatically. When the component unmounts, all GSAP animations created inside the callback are reverted and killed. There is no need to manually call `.kill()` or `.revert()`.
+
+**CRITICAL:** All GSAP code MUST be in `'use client'` components. GSAP cannot run server-side — it depends on the DOM and `window` object.
+
+---
+
+## Section 5: Timeline Sequencing
+
+`gsap.timeline()` sequences multiple animations with precise timing control.
+
+### Position Parameter Syntax
+
+| Syntax | Meaning |
+|---|---|
+| `1` | At absolute time 1 second |
+| `"+=0.5"` | 0.5s after the end of the previous animation |
+| `"-=0.2"` | 0.2s before the end of the previous animation (overlap) |
+| `"reveal"` | At the label named "reveal" |
+| `"<"` | At the start of the previous animation |
+| `">"` | At the end of the previous animation |
+| `"<0.2"` | 0.2s after the start of the previous animation |
+
+### Complete Timeline Example
+
+```typescript
+'use client';
+import { useRef } from 'react';
+import { useGSAP } from '@gsap/react';
+import gsap from 'gsap';
+import { durations } from '@/lib/design-tokens';
+
+function HeroTimeline() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useGSAP(() => {
+    const tl = gsap.timeline({
+      defaults: { duration: durations.base, ease: 'power2.out' },
+    });
+
+    tl.from('.hero-bg', { autoAlpha: 0, scale: 1.1 })
+      .addLabel('reveal')
+      .from('.hero-title', { y: 40, autoAlpha: 0 }, 'reveal')
+      .from('.hero-subtitle', { y: 30, autoAlpha: 0 }, 'reveal+=0.15')
+      .from('.hero-cta', { y: 20, autoAlpha: 0 }, '>-0.1')
+      .from('.hero-badges', { autoAlpha: 0, stagger: 0.08 }, '<0.2');
+
+    // Nested timeline
+    const cardsTl = gsap.timeline({ defaults: { duration: durations.fast } });
+    cardsTl.from('.card', { y: 60, autoAlpha: 0, stagger: 0.1 });
+
+    tl.add(cardsTl, 'reveal+=0.4');
+  }, { scope: containerRef });
+
+  return (
+    <div ref={containerRef}>
+      <div className="hero-bg" />
+      <h1 className="hero-title">Title</h1>
+      <p className="hero-subtitle">Subtitle</p>
+      <button className="hero-cta">Get Started</button>
+      <div className="hero-badges">
+        <span className="card">A</span>
+        <span className="card">B</span>
+        <span className="card">C</span>
+      </div>
+    </div>
+  );
+}
+```
+
+### Playback Controls
+
+```typescript
+const tl = gsap.timeline({ paused: true });
+
+tl.play();           // play from current position
+tl.pause();          // pause at current position
+tl.reverse();        // play in reverse
+tl.restart();        // restart from beginning
+tl.progress(0.5);   // jump to 50%
+tl.seek('reveal');   // jump to label
+```
+
+---
+
+## Section 6: Utility Functions
+
+`gsap.utils` provides composable helper functions. Omitting the last value argument returns a reusable function.
+
+```typescript
+'use client';
+import gsap from 'gsap';
+
+// Convert NodeList/selector to array
+const items = gsap.utils.toArray<HTMLElement>('.items');
+
+// Clamp value between min and max
+gsap.utils.clamp(0, 100, 150);        // 100
+const clamp0to100 = gsap.utils.clamp(0, 100); // reusable
+clamp0to100(150);                      // 100
+
+// Map value from one range to another
+gsap.utils.mapRange(0, 1, 0, 100, 0.5);  // 50
+const normalize = gsap.utils.mapRange(0, 1, 0, 100); // reusable
+
+// Snap to nearest grid value
+gsap.utils.snap(10, 23);              // 20
+const snapTo5 = gsap.utils.snap(5);   // reusable
+
+// Interpolate between two values
+gsap.utils.interpolate(0, 100, 0.5);  // 50
+
+// Compose utility functions into a pipeline
+const process = gsap.utils.pipe(
+  gsap.utils.clamp(0, 100),
+  gsap.utils.snap(5)
+);
+process(103); // 100 (clamped), then 100 (snapped)
+
+// Scoped selector (useful in components)
+const q = gsap.utils.selector(containerRef.current);
+gsap.to(q('.title'), { y: -20 });
+```
+
+---
+
+## Section 7: Performance
+
+- **Animate ONLY transform properties** (`x`, `y`, `scale`, `rotation`) and `opacity` — these use the GPU compositor and skip layout/paint.
+- **AVOID layout-triggering properties** (`width`, `height`, `top`, `left`, `margin`, `padding`) — they cause full layout recalculation.
+- Apply `will-change: transform` ONLY on elements that are actively animating, and remove it after the animation completes.
+- Use `gsap.quickTo()` for high-frequency updates such as mouse followers and cursor tracking:
+
+```typescript
+'use client';
+import { useRef } from 'react';
+import { useGSAP } from '@gsap/react';
+import gsap from 'gsap';
+
+function CursorFollower() {
+  const cursorRef = useRef<HTMLDivElement>(null);
+
+  useGSAP(() => {
+    const xTo = gsap.quickTo(cursorRef.current, 'x', { duration: 0.3, ease: 'power3' });
+    const yTo = gsap.quickTo(cursorRef.current, 'y', { duration: 0.3, ease: 'power3' });
+
+    const handleMouseMove = (e: MouseEvent) => {
+      xTo(e.clientX);
+      yTo(e.clientY);
+    };
+
+    window.addEventListener('mousemove', handleMouseMove);
+    return () => window.removeEventListener('mousemove', handleMouseMove);
+  });
+
+  return <div ref={cursorRef} className="cursor-dot" />;
+}
+```
+
+- Use the `stagger` property instead of creating individual tweens for each element.
+- Batch DOM reads before writes to prevent layout thrashing.
+- Kill off-screen animations and debounce `ScrollTrigger.refresh()` on resize.
+
+---
+
+## Section 8: Accessibility
+
+**MANDATORY:** Every animated component must respect `prefers-reduced-motion`.
+
+```typescript
+'use client';
+import { useRef } from 'react';
+import { useGSAP } from '@gsap/react';
+import gsap from 'gsap';
+
+// Option A: gsap.matchMedia (recommended)
+function ScrollHero() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useGSAP(() => {
+    gsap.matchMedia().add('(prefers-reduced-motion: no-preference)', () => {
+      // Animations here are automatically reverted when media query stops matching
+      gsap.to('.hero', { y: -50, scrollTrigger: { scrub: true } });
+    });
+  }, { scope: containerRef });
+
+  return (
+    <div ref={containerRef}>
+      <div className="hero">Content</div>
+    </div>
+  );
+}
+
+// Option B: manual check
+function ManualCheckExample() {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useGSAP(() => {
+    const prefersReducedMotion = window.matchMedia(
+      '(prefers-reduced-motion: reduce)'
+    ).matches;
+
+    if (prefersReducedMotion) {
+      gsap.set('.hero', { opacity: 1 }); // skip to final state
+      return;
+    }
+
+    gsap.from('.hero', { y: 40, autoAlpha: 0, duration: 0.6 });
+  }, { scope: containerRef });
+
+  return (
+    <div ref={containerRef}>
+      <div className="hero">Content</div>
+    </div>
+  );
+}
+```
+
+When reduced motion is active:
+- Skip all transform animations (`x`, `y`, `scale`, `rotation`).
+- Keep opacity-only fades — they do not cause vestibular issues.
+- Use `gsap.set()` to jump to the final visual state so content is still visible.
+
+---
+
+## Section 9: Design Token Bridge
+
+Import from the same `@/lib/design-tokens` module that Framer Motion uses to maintain consistency across animation libraries:
+
+```typescript
+'use client';
+import gsap from 'gsap';
+import { durations, easings } from '@/lib/design-tokens';
+
+gsap.to('.element', {
+  duration: durations.base, // 0.3
+  ease: `cubic-bezier(${easings.standard.join(',')})`,
+});
+```
+
+Alternatively, use GSAP's built-in easing strings when the design token bridge is not needed:
+
+| GSAP Ease | Behavior |
+|---|---|
+| `"power2.out"` | Standard deceleration |
+| `"power2.inOut"` | Smooth start and end |
+| `"back.out(1.7)"` | Slight overshoot |
+| `"elastic.out(1, 0.3)"` | Spring-like bounce |
+| `"none"` | Linear (no easing) |
+
+> **Rule:** Never hardcode duration numbers. Import from `@/lib/design-tokens`.
+
+---
+
+## Section 10: Anti-patterns
+
+| Anti-pattern | Correct approach |
+|---|---|
+| Using useEffect instead of useGSAP | Always use `useGSAP()` from `@gsap/react` — handles cleanup automatically |
+| Forgetting scope ref | Always pass `{ scope: containerRef }` to useGSAP — prevents targeting elements in other components |
+| No cleanup | useGSAP handles this; for manual `gsap.context()`, call `ctx.revert()` in cleanup |
+| Animating width/height/top/left | Use `x`, `y`, `scale`, `rotation` (GPU-composited) |
+| No prefers-reduced-motion check | Wrap animations in `gsap.matchMedia()` or check manually |
+| Mixing GSAP + Framer Motion on same element | Choose one per element — they fight for inline styles |
+| Registering plugins inside components | Register once at app init (`layout.tsx` or `providers.tsx`) |
+| Using GSAP for simple enter/exit | Use Framer Motion — it is declarative and handles mount/unmount |
+| Hardcoded durations/easings | Import from `@/lib/design-tokens` |
+| Creating animations before DOM exists | useGSAP runs after mount — never animate in render body |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*