@mehshekari/gsap-motion 2.1.0

package/skill/preset/magnetic.md

@@ -0,0 +1,155 @@
+# Magnetic
+
+An element that leans toward the cursor while it is near and eases back when it
+leaves. Says "this is interactive" more convincingly than any hover state,
+because the response starts before the pointer arrives.
+
+Mechanics and the `quickTo` rule are in
+[interaction.md](../reference/interaction.md); this is the tuned recipe.
+
+## The hook
+
+```ts
+"use client";
+
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { useRef } from "react";
+
+gsap.registerPlugin(useGSAP);
+
+/** Fraction of the cursor's offset the element travels. Above ~0.4 it outruns
+ *  the pointer and stops feeling attached. */
+const PULL = 0.32;
+/** How much further the inner label travels, so the button has some depth. */
+const LABEL_PULL = 0.5;
+
+export function useMagnetic() {
+  const zoneRef = useRef<HTMLDivElement>(null);
+  const targetRef = useRef<HTMLElement>(null);
+  const labelRef = useRef<HTMLElement>(null);
+
+  useGSAP(
+    () => {
+      const zone = zoneRef.current;
+      const target = targetRef.current;
+      if (!zone || !target) return;
+
+      const mm = gsap.matchMedia();
+
+      /**
+       * Gated on a real cursor. On touch there is no hover to leave, so the
+       * element would stick wherever the last tap put it. Reduced motion keeps
+       * the affordance and drops the travel.
+       */
+      mm.add(
+        "(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)",
+        () => {
+          const to = (el: HTMLElement, axis: "x" | "y") =>
+            gsap.quickTo(el, axis, { duration: 0.6, ease: "power3" });
+
+          const move = { x: to(target, "x"), y: to(target, "y") };
+          const label = labelRef.current
+            ? { x: to(labelRef.current, "x"), y: to(labelRef.current, "y") }
+            : null;
+
+          const onMove = (event: PointerEvent) => {
+            /** Measured per move: scroll and layout both shift the rect. */
+            const rect = target.getBoundingClientRect();
+            const dx = event.clientX - (rect.left + rect.width / 2);
+            const dy = event.clientY - (rect.top + rect.height / 2);
+
+            move.x(dx * PULL);
+            move.y(dy * PULL);
+            label?.x(dx * PULL * LABEL_PULL);
+            label?.y(dy * PULL * LABEL_PULL);
+          };
+
+          const onLeave = () => {
+            move.x(0);
+            move.y(0);
+            label?.x(0);
+            label?.y(0);
+          };
+
+          zone.addEventListener("pointermove", onMove);
+          zone.addEventListener("pointerleave", onLeave);
+
+          return () => {
+            zone.removeEventListener("pointermove", onMove);
+            zone.removeEventListener("pointerleave", onLeave);
+          };
+        },
+      );
+
+      /* The context reverts `mm` itself; the listeners are ours. */
+    },
+    { scope: zoneRef },
+  );
+
+  return { zoneRef, targetRef, labelRef };
+}
+```
+
+## The markup
+
+The listening zone is larger than the element. That is what turns a hover state
+into a field — the pull begins before the cursor arrives.
+
+```tsx
+<div ref={zoneRef} className="inline-flex p-6">
+  <button ref={targetRef} className="rounded-full px-6 py-3">
+    <span ref={labelRef} className="inline-block">Get in touch</span>
+  </button>
+</div>
+```
+
+The padding is the field radius. 24–40px is usually right; larger and the
+element starts moving for pointers that were never coming.
+
+## Values
+
+| Value | Range | Note |
+|---|---|---|
+| `PULL` | 0.2–0.4 | above 0.4 it detaches from the cursor |
+| duration | 0.4–0.8 | shorter feels twitchy, longer feels like lag |
+| ease | `power3` | `power2` is softer; avoid `elastic` here |
+| zone padding | 24–40px | the field radius |
+| `LABEL_PULL` | 0.4–0.6 | the parallax that gives it depth |
+
+## Variations
+
+**Scale on enter** — one paused timeline, played and reversed, so the return
+matches without a second definition:
+
+```ts
+const hover = gsap.timeline({ paused: true })
+  .to(target, { scale: 1.05, duration: 0.3, ease: "power2.out" });
+```
+
+**Rotation instead of translation** — a subtle `rotation: dx * 0.02` reads as
+the element tilting to face the cursor. Good for cards, wrong for buttons.
+
+**Magnetic cursor, static button** — invert it: the follower is captured by the
+button's centre on enter. See [cursor.md](cursor.md).
+
+## Accessibility
+
+The pull is decoration and a keyboard never sees it, so **the focus state must
+carry the whole affordance on its own** — the same visual change the hover
+implies, not a fallback. And the transform must not move the element out from
+under its focus ring.
+
+Both gates in the `matchMedia` query above are load-bearing: without
+`(hover: hover)` the element sticks after a tap on touch; without the
+reduced-motion clause it moves for someone who asked it not to.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Janky | a tween per event instead of `quickTo` |
+| Drifts and never returns | `pointerleave` on the element, not the zone |
+| Wrong offset after scrolling | rect cached instead of measured |
+| Stuck after a tap on mobile | missing `(hover: hover)` gate |
+| Feels detached | `PULL` too high |

package/skill/preset/marquee.md

@@ -0,0 +1,177 @@
+# Marquee and ambient
+
+Continuous motion. The engineering problem is the seam: a loop whose restart is
+visible is worse than no loop at all.
+
+## Seamless marquee
+
+Duplicate the content, translate by exactly one copy's width, reset. Because the
+two copies are identical, the reset is a jump between identical frames.
+
+```tsx
+<div className="overflow-hidden">
+  <div ref={trackRef} className="flex w-max">
+    <div data-copy className="flex shrink-0">{items}</div>
+    <div data-copy className="flex shrink-0" aria-hidden="true">{items}</div>
+  </div>
+</div>
+```
+
+```ts
+useGSAP(() => {
+  const copy = trackRef.current?.querySelector<HTMLElement>("[data-copy]");
+  if (!copy) return;
+
+  const loop = gsap.to(trackRef.current, {
+    x: () => -copy.offsetWidth,
+    duration: copy.offsetWidth / 60,     // px per second, not a fixed time
+    ease: "none",
+    repeat: -1,
+  });
+
+  /** Re-reads the width after a resize or a font load. */
+  const ro = new ResizeObserver(() => loop.invalidate());
+  ro.observe(copy);
+
+  return () => ro.disconnect();
+}, { scope: trackRef });
+```
+
+Three things that are all load-bearing:
+
+- **`ease: "none"`.** Any other ease decelerates into the restart and the seam
+  becomes visible.
+- **`x` as a function.** It is re-evaluated on `invalidate()`, which is what
+  survives a resize. A fixed number goes wrong the moment the layout changes.
+- **Duration derived from width.** A fixed duration means a long list scrolls
+  fast and a short one crawls. Pick a speed in px/sec and divide.
+
+The second copy is `aria-hidden` — a screen reader should hear the list once.
+
+### RTL
+
+A marquee has a handedness, so a right-to-left page needs a decision. Either
+mirror it, or pin the direction deliberately and say why:
+
+```ts
+const isRtl = document.documentElement.dir === "rtl";
+x: () => (isRtl ? copy.offsetWidth : -copy.offsetWidth);
+```
+
+Logos and product shots usually read better pinned to one direction in both
+locales. If the project lints for logical CSS, that pin needs its waiver
+comment, carrying the reason — see [project-rules.md](../reference/project-rules.md).
+
+### Pausing
+
+WCAG 2.2.2: anything moving for more than five seconds needs a way to stop it.
+Pause on hover and on focus-within:
+
+```ts
+el.addEventListener("pointerenter", () => loop.timeScale(0.2));
+el.addEventListener("pointerleave", () => loop.timeScale(1));
+el.addEventListener("focusin", () => loop.pause());
+el.addEventListener("focusout", () => loop.resume());
+```
+
+Slowing rather than stopping on hover keeps it alive while making a logo
+readable. Focus must actually stop it — a keyboard user cannot chase a moving
+link.
+
+## Scroll-reactive speed
+
+Ties the marquee to the page and costs almost nothing:
+
+```ts
+ScrollTrigger.create({
+  onUpdate: (self) => {
+    loop.timeScale(gsap.utils.clamp(0.4, 3, 1 + Math.abs(self.getVelocity()) / 1500));
+    // Direction follows the scroll:
+    loop.reversed(self.direction === -1);
+  },
+});
+```
+
+Clamp it — unclamped velocity produces absurd values on a flick.
+
+## Ambient float
+
+Background motion under static content. The rule is **irregularity**: identical
+periods read as mechanical.
+
+```ts
+gsap.utils.toArray<HTMLElement>("[data-float]").forEach((el, i) => {
+  gsap.to(el, {
+    y: gsap.utils.random(-14, -26),
+    x: gsap.utils.random(-8, 8),
+    duration: gsap.utils.random(3.5, 6),
+    repeat: -1,
+    yoyo: true,
+    ease: "sine.inOut",
+    delay: i * 0.3,
+  });
+});
+```
+
+`sine.inOut` is the breath ease — it has no hard stop at either end.
+`yoyo: true` reverses rather than resetting, so there is no seam to hide.
+
+Keep the distance small. Ambient motion is felt, not watched; if the visitor can
+track it, it is too much.
+
+## Orbit
+
+An element circling a point. Rotating a wrapper is cheaper than a motion path
+when the route is a circle:
+
+```tsx
+<div data-orbit className="absolute inset-0">
+  <div className="absolute start-1/2 top-0 size-2 rounded-full" />
+</div>
+```
+
+```ts
+gsap.to("[data-orbit]", { rotation: 360, duration: 8, ease: "none", repeat: -1 });
+```
+
+Use MotionPath only when the route is not a circle — see
+[svg.md](../reference/svg.md).
+
+## Breathing
+
+```ts
+gsap.to("[data-pulse]", {
+  scale: 1.04,
+  autoAlpha: 0.85,
+  duration: 2.2,
+  repeat: -1,
+  yoyo: true,
+  ease: "sine.inOut",
+});
+```
+
+Two seconds is roughly resting breath and reads as calm. Under a second reads as
+urgency — correct for a recording indicator, wrong for a background.
+
+## Cost
+
+Continuous animation never stops, so it is the one category where cost
+compounds. Only `transform` and `opacity`. Pause anything off-screen:
+
+```ts
+ScrollTrigger.create({
+  trigger: section,
+  onToggle: (self) => (self.isActive ? loop.resume() : loop.pause()),
+});
+```
+
+A dozen paused timelines cost nothing; a dozen running ones on a phone do.
+
+## Reduced motion
+
+Ambient motion is unrequested and continuous — exactly what the preference is
+for. Stop it entirely and leave the composition static; nothing is lost, because
+ambient motion carries no information by definition.
+
+A marquee is different: it may be the only way to see the whole list. Keep the
+content reachable — make it a scrollable row rather than a moving one.

package/skill/preset/page-transition.md

@@ -0,0 +1,151 @@
+# Page and modal transitions
+
+The App Router unmounts the old tree before the new one paints, so an exit
+animation has nowhere to play. Every approach below is a way around that fact.
+
+## Pick the cheapest that works
+
+| Approach | Cost | Use when |
+|---|---|---|
+| Entrance only | trivial | almost always — this is what most sites want |
+| Overlay in the layout | moderate | you need a real cover between pages |
+| Shared element (Flip) | high | continuity is the point: a thumbnail becoming a hero |
+| Intercepted navigation | high, breaks back-button feel | rarely |
+
+Start at the top. A 400ms entrance keyed off the pathname is indistinguishable
+from a "real" transition for most content, and costs nothing in complexity.
+
+## Entrance only
+
+```tsx
+"use client";
+
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { usePathname } from "next/navigation";
+import { useRef } from "react";
+
+export function PageEnter({ children }: Readonly<{ children: React.ReactNode }>) {
+  const root = useRef<HTMLDivElement>(null);
+  const pathname = usePathname();
+
+  useGSAP(
+    () => {
+      gsap.from(root.current, {
+        autoAlpha: 0,
+        y: 12,
+        duration: 0.5,
+        ease: "power2.out",
+      });
+    },
+    { scope: root, dependencies: [pathname] },
+  );
+
+  return <div ref={root}>{children}</div>;
+}
+```
+
+`dependencies: [pathname]` re-runs it per navigation. Keep the travel small —
+the visitor asked for this page and is waiting.
+
+## Overlay in the layout
+
+Mounted in the layout so the navigation does not unmount it. It covers, the
+route changes underneath, it uncovers.
+
+```tsx
+// In the locale layout, above {children}
+<RouteCurtain />
+```
+
+```ts
+const pathname = usePathname();
+
+useGSAP(() => {
+  gsap.timeline()
+    .set(curtain, { yPercent: 100 })
+    .to(curtain, { yPercent: 0, duration: 0.45, ease: "power3.in" })
+    .to(curtain, { yPercent: -100, duration: 0.55, ease: "power3.out" }, "+=0.05");
+}, { dependencies: [pathname] });
+```
+
+This covers *after* the new route has rendered, which is a compromise — it reads
+as a wipe rather than a true out-and-in. Honest and robust. `pointer-events:
+none` on the curtain except while it covers, and `aria-hidden` throughout.
+
+## Shared element
+
+Use Flip. The element must be identifiable in both trees via `data-flip-id` —
+see [flip.md](../reference/flip.md).
+
+```ts
+// Before navigating, from the grid:
+const state = Flip.getState("[data-flip-id]");
+sessionStorage.setItem("flip", JSON.stringify(state));  // survives the route
+
+// On the detail page, in a layout effect:
+Flip.from(state, { duration: 0.6, absolute: true, ease: "power3.inOut" });
+```
+
+In practice this is fragile across a real route change — the image must be
+loaded in both places, and a cache miss produces a jump. It works reliably
+inside a single route (a grid expanding into a panel) and is worth the cost
+there.
+
+## Modal
+
+The common case, and simpler because nothing unmounts unexpectedly.
+
+```ts
+const open = gsap.timeline({ paused: true })
+  .set(overlay, { autoAlpha: 0 })
+  .to(overlay, { autoAlpha: 1, duration: 0.25 })
+  .from(panel, { yPercent: 4, scale: 0.98, autoAlpha: 0,
+                 duration: 0.35, ease: "power3.out" }, "<0.05");
+
+// Open:  open.play()
+// Close: open.reverse()   — same easing backwards, no second definition
+```
+
+Exits run faster than entrances — the visitor has already decided. If you write
+the close by hand rather than reversing, make it ~65% of the open duration.
+
+Accessibility is the bigger half of a modal:
+
+- Move focus into the panel on open, restore it to the trigger on close.
+- Trap focus while open; `inert` on the rest of the document.
+- `Escape` closes.
+- `role="dialog"` and `aria-modal="true"` with an accessible name.
+
+Animation must not delay any of that. Set focus immediately, not in
+`onComplete` — a 350ms wait for a keyboard user is a bug.
+
+## Reduced motion
+
+```ts
+if (reduced) {
+  gsap.set(panel, { autoAlpha: 1, yPercent: 0, scale: 1 });
+  gsap.set(overlay, { autoAlpha: 1 });
+  return;
+}
+```
+
+The state change still happens; only the travel goes. For a page transition
+under `reduce`, skip the curtain entirely — a full-screen wipe on every
+navigation is exactly the unrequested movement the preference exists to stop.
+
+## After navigating
+
+`ScrollTrigger.refresh()` once the new layout has settled, or every trigger on
+the new page measures against the old one.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Exit animation never plays | the route unmounted the tree — use an overlay |
+| Curtain traps clicks | `pointer-events` not cleared |
+| Flip jumps on the detail page | the image was not loaded when measured |
+| Triggers wrong after navigation | no `ScrollTrigger.refresh()` |
+| Focus lost after a modal closes | not restored to the trigger |
+| Transition replays on every render | missing `dependencies`, or the wrong one |

package/skill/preset/reveal.md

@@ -0,0 +1,146 @@
+# Reveal
+
+Entrance and in-view reveals. The most common request and the easiest to make
+generic — the difference between a stock reveal and a good one is the mask and
+the rhythm, not the duration.
+
+## Distance over opacity
+
+A 60px slide reads as arrival; a 200px slide reads as a slideshow. Start small.
+
+```ts
+gsap.from("[data-item]", {
+  y: 32,
+  autoAlpha: 0,
+  duration: 0.7,
+  stagger: 0.06,
+  ease: "power3.out",
+});
+```
+
+`autoAlpha`, not `opacity`, so nothing invisible takes pointer events. For a
+`from` tween outside a layout effect, set the start state first or it flashes.
+
+## Mask reveal
+
+The upgrade that makes a reveal look authored. The element rises out of nothing
+instead of sliding in from somewhere.
+
+```tsx
+<span className="block overflow-hidden">
+  <span data-line className="block">Built in Iran.</span>
+</span>
+```
+
+```ts
+gsap.from("[data-line]", {
+  yPercent: 110,
+  duration: 0.8,
+  stagger: 0.08,
+  ease: "power3.out",
+});
+```
+
+`yPercent: 110` rather than `100` — a descender pokes below the box at exactly
+100.
+
+## Image reveal
+
+Clip the container, counter-move the image. The image appears to be uncovered
+rather than to slide, and the parallax inside the mask is what sells it.
+
+```tsx
+<div data-frame className="overflow-hidden">
+  <img data-img alt="" />
+</div>
+```
+
+```ts
+gsap.timeline({ defaults: { ease: "power3.inOut", duration: 1 } })
+  .from("[data-frame]", { clipPath: "inset(0 0 100% 0)" })
+  .from("[data-img]", { scale: 1.25 }, "<");
+```
+
+`clipPath` animates on the compositor in modern browsers. `scale` on the image
+must be a counter-move — if both travel the same way it just looks like a zoom.
+
+For RTL, a horizontal wipe direction must mirror: `inset(0 100% 0 0)` becomes
+`inset(0 0 0 100%)`.
+
+## In-view
+
+```ts
+gsap.from("[data-item]", {
+  y: 32,
+  autoAlpha: 0,
+  stagger: 0.06,
+  scrollTrigger: {
+    trigger: section,
+    start: "top 75%",
+    toggleActions: "play none none none",
+  },
+});
+```
+
+`"top 75%"` fires a quarter into the viewport — early enough that it is not
+already read, late enough that it is not missed. `play none none none` plays
+once; `play none none reverse` replays on scroll back, which is usually
+irritating on a long page.
+
+**One trigger for the group.** Forty cards is one trigger with a stagger, not
+forty triggers — see [scrolltrigger.md](../reference/scrolltrigger.md).
+
+## Stagger shapes
+
+```ts
+stagger: { amount: 0.5 }                       // 0.5s total, any count
+stagger: { each: 0.06, from: "center" }        // radiates outward
+stagger: { each: 0.05, from: "end" }           // reading order in RTL
+stagger: { amount: 0.6, grid: [4, 3], from: "start" }   // diagonal across a grid
+```
+
+`amount` over `each` for anything that can grow — twelve cards at `each: 0.1`
+take 1.2s of nothing happening.
+
+## Composed section entrance
+
+Hierarchy in time: the thing that matters arrives first.
+
+```ts
+gsap.timeline({
+  defaults: { ease: "power3.out", duration: 0.8 },
+  scrollTrigger: { trigger: section, start: "top 70%" },
+})
+  .from("[data-eyebrow]", { autoAlpha: 0, y: 12, duration: 0.5 })
+  .from("[data-heading-line]", { yPercent: 110, stagger: 0.08 }, "-=0.25")
+  .from("[data-body]", { autoAlpha: 0, y: 20 }, "-=0.5")
+  .from("[data-cta]", { autoAlpha: 0, y: 16, duration: 0.6 }, "-=0.45")
+  .from("[data-media]", { clipPath: "inset(0 0 100% 0)", duration: 1 }, "-=0.8");
+```
+
+The negative offsets overlap each beat into the one before at roughly 60–70%.
+Nothing waits for the previous thing to finish, which is what stops it reading
+as a list.
+
+## Reduced motion
+
+```ts
+if (reduced) {
+  gsap.set("[data-item]", { autoAlpha: 1, y: 0, clipPath: "none" });
+  return;
+}
+```
+
+**The reduced branch must set the end state.** A `from` that never runs leaves
+the element at its authored start — invisible. This hides content rather than
+skipping motion, and it is the most common bug in this preset.
+
+## Tuning
+
+| Feels | Change |
+|---|---|
+| like a slideshow | overlap the beats — `<` or negative offsets |
+| cheap | mask instead of fade; `power3.out` instead of `power1` |
+| slow | reduce distance before duration; overlap more |
+| chaotic | fewer things moving; one carries the emphasis |
+| janky | `y` not `top`; check the trigger count |