@mehshekari/gsap-motion 2.1.0

package/skill/preset/card-stack.md

@@ -0,0 +1,175 @@
+# Card stack
+
+Cards that arrive from a pile, stack as you scroll, or reflow on filter. Three
+different stories — pick the one the content actually tells.
+
+## Deal in
+
+A pile that spreads into place. Says "these belong together" before showing what
+they are.
+
+```ts
+gsap.timeline({
+  defaults: { duration: 0.8, ease: "power3.out" },
+  scrollTrigger: { trigger: grid, start: "top 70%" },
+})
+  .from("[data-card]", {
+    y: 60,
+    scale: 0.92,
+    rotation: () => gsap.utils.random(-6, 6),
+    autoAlpha: 0,
+    stagger: { amount: 0.5, from: "center" },
+  });
+```
+
+`rotation` as a function is evaluated per element, so each card gets its own
+angle. `stagger: { amount }` keeps twelve cards inside half a second —
+`each: 0.08` would take nearly a second of nothing happening.
+
+Keep the rotation under ~8°. Beyond that it reads as a mess rather than a
+shuffle.
+
+## Stacking on scroll
+
+Cards pin and pile up as the visitor scrolls — one shared trigger, each card
+offset. This is the "Apple pricing page" pattern.
+
+```ts
+const cards = gsap.utils.toArray<HTMLElement>("[data-card]");
+
+cards.forEach((card, i) => {
+  gsap.to(card, {
+    scale: 1 - (cards.length - i) * 0.03,
+    y: i * 12,
+    ease: "none",
+    scrollTrigger: {
+      trigger: card,
+      start: "top 20%",
+      end: "bottom 20%",
+      scrub: 1,
+      pin: true,
+      pinSpacing: false,
+      invalidateOnRefresh: true,
+    },
+  });
+});
+
+// The card itself must stick:
+// .card { position: sticky; top: 5vh; }
+```
+
+`pinSpacing: false` is what lets the cards overlap instead of each reserving its
+own scroll height. This is the rare case where **one trigger per card is
+correct** — each pins independently.
+
+The scale is what creates depth: the card behind must read as further away, or
+the stack looks like a rendering bug.
+
+## Explode out
+
+Reverse of deal-in, for an exit or a filter change.
+
+```ts
+gsap.to("[data-card]", {
+  y: () => gsap.utils.random(-120, 120),
+  x: () => gsap.utils.random(-80, 80),
+  rotation: () => gsap.utils.random(-25, 25),
+  autoAlpha: 0,
+  scale: 0.85,
+  duration: 0.6,
+  ease: "power2.in",
+  stagger: { amount: 0.25, from: "center" },
+});
+```
+
+`power2.in` for an exit — it gathers speed as it leaves, where `out` would make
+it drift.
+
+## Reflow on filter
+
+Use Flip. Hand-computing positions here is exactly the work Flip exists to
+remove — see [flip.md](../reference/flip.md).
+
+```ts
+const state = Flip.getState(cards);
+cards.forEach((el) => {
+  el.style.display = matches(el) ? "" : "none";
+});
+Flip.from(state, {
+  duration: 0.5,
+  scale: true,
+  absolute: true,
+  ease: "power2.inOut",
+  stagger: 0.03,
+  onEnter: (els) => gsap.fromTo(els, { autoAlpha: 0, scale: 0.9 },
+                                      { autoAlpha: 1, scale: 1 }),
+  onLeave: (els) => gsap.to(els, { autoAlpha: 0, scale: 0.9 }),
+});
+```
+
+`absolute: true` or the surviving cards jitter as the grid reflows under them.
+
+## Hover lift
+
+Small and immediate. The shadow is what sells the lift — a card that moves
+without its shadow changing looks like it slid, not rose.
+
+```ts
+const lift = gsap.timeline({ paused: true })
+  .to(card, { y: -6, duration: 0.3, ease: "power2.out" })
+  .to(card, { boxShadow: "var(--shadow-lifted)", duration: 0.3 }, "<");
+```
+
+`box-shadow` repaints. For a grid of many cards, cross-fade two stacked shadow
+layers with `opacity` instead.
+
+## Tilt
+
+Pointer-driven rotation on the card's own axes:
+
+```ts
+const rx = gsap.quickTo(card, "rotationX", { duration: 0.5, ease: "power3" });
+const ry = gsap.quickTo(card, "rotationY", { duration: 0.5, ease: "power3" });
+
+const onMove = (e: PointerEvent) => {
+  const r = card.getBoundingClientRect();
+  rx((0.5 - (e.clientY - r.top) / r.height) * 12);
+  ry(((e.clientX - r.left) / r.width - 0.5) * 12);
+};
+```
+
+Needs `perspective` on the parent, or the rotation is a flat squash:
+
+```css
+.grid { perspective: 1000px; }
+.card { transform-style: preserve-3d; }
+```
+
+Keep it under ~15°. Gate on `(hover: hover)` — see
+[interaction.md](../reference/interaction.md).
+
+## Reduced motion
+
+Set the end state and keep the hover affordances as instant state changes:
+
+```ts
+if (reduced) {
+  gsap.set("[data-card]", { autoAlpha: 1, y: 0, scale: 1, rotation: 0 });
+  return;
+}
+```
+
+For the stacking variant, drop the pin entirely — pinned scroll-scrubbing is
+precisely the vestibular trigger. Let the cards flow normally.
+
+## Choosing
+
+| Content | Pattern |
+|---|---|
+| A set that arrives together | deal in |
+| A sequence the visitor walks through | stacking on scroll |
+| A filterable collection | Flip reflow |
+| A gallery | reveal + hover lift |
+
+If the cards are a list of links, none of this. A list of links wants a fast
+stagger and nothing else.

package/skill/preset/cinematic.md

@@ -0,0 +1,140 @@
+# Cinematic
+
+"Make it feel cinematic" is a request about **pacing**, not about effects. The
+techniques below are ordinary; what makes them cinematic is that one thing
+happens at a time, each beat is given room, and nothing is rushed.
+
+A worked example, with the code that matters:
+[example/cinematic-intro.md](../example/cinematic-intro.md).
+
+## What the word means
+
+| Cinematic | Not cinematic |
+|---|---|
+| one thing moving at a time | six things arriving together |
+| 0.8–1.6s beats | 300ms beats |
+| `power3.inOut`, `expo.out` | `back.out`, `elastic` |
+| holds between beats | continuous motion |
+| slow reveal of one subject | a grid of cards staggering in |
+| dark, contrasty, generous space | busy layout |
+
+The most common failure is treating it as "add more motion". Cinematic is
+usually **less** motion, held longer.
+
+## Structure
+
+Three acts, and the hold is not optional — it is where the weight comes from.
+
+```text
+establish → the subject arrives alone, slowly
+develop   → supporting elements enter, each given its own beat
+hold      → everything settles; nothing moves for 300–600ms
+release   → the interface returns, or the scene hands over
+```
+
+## Site intro
+
+```ts
+const tl = gsap.timeline({
+  defaults: { ease: "power3.out" },
+  onComplete: finish,
+});
+
+tl.addLabel("establish")
+  .fromTo("[data-mark-outline]", { drawSVG: "0%" },
+          { drawSVG: "100%", duration: 1.2, stagger: 0.14, ease: "power2.inOut" })
+  .to("[data-mark-fill]", { autoAlpha: 1, duration: 0.5 }, "-=0.5")
+  .to("[data-mark-outline]", { autoAlpha: 0, duration: 0.35 }, "<0.15")
+
+  .addLabel("develop")
+  .from("[data-word-line]", { yPercent: 110, duration: 0.9, stagger: 0.08 }, "develop")
+
+  .addLabel("hold")
+  .to({}, { duration: 0.5 })
+
+  .addLabel("release")
+  .to("[data-curtain]", { yPercent: -100, duration: 0.9, ease: "power4.inOut" });
+```
+
+Labels rather than offsets: a cinematic sequence gets retimed many times, and
+labels are what survive that.
+
+## Curtain lift
+
+The release beat. A wipe reads more deliberate than a fade.
+
+```ts
+.to(curtain, { yPercent: -100, duration: 0.9, ease: "power4.inOut" })
+.from(content, { yPercent: 8, autoAlpha: 0, duration: 0.9 }, "<0.15");
+```
+
+The content lagging slightly behind the curtain is what makes it feel revealed
+rather than switched.
+
+## Letterbox
+
+Two bars closing in, then opening. Cheap and unmistakably filmic — but it is a
+strong gesture, so once per site.
+
+```ts
+gsap.from("[data-bar]", { scaleY: 0, transformOrigin: "top", duration: 0.6 });
+```
+
+## Camera language
+
+Real depth comes from layers moving at different rates. The subject barely
+moves; the background does.
+
+```ts
+tl.from("[data-bg]",      { scale: 1.15, duration: 2.4, ease: "power2.out" })
+  .from("[data-mid]",     { scale: 1.08, duration: 2.4, ease: "power2.out" }, "<")
+  .from("[data-subject]", { scale: 1.02, autoAlpha: 0, duration: 1.6 }, "<0.3");
+```
+
+Same direction, different magnitudes. A slow push-in on the background under a
+still subject is the single most effective cinematic device available in CSS.
+
+## Ceiling
+
+An unskippable intro must have a hard time limit, and dismissal must be a
+**race** rather than a sequence:
+
+```ts
+let done = false;
+const finish = () => { if (done) return; done = true; onDone(); };
+const ceiling = window.setTimeout(finish, 4200);
+return () => window.clearTimeout(ceiling);
+```
+
+Keep the total under ~3s. Play it once per session, not once per route — an
+intro on every navigation is an obstacle. Render the page underneath the whole
+time so a JavaScript failure cannot trap the visitor behind a curtain.
+
+## Reduced motion
+
+Cinematic motion is the most likely thing on a page to cause discomfort: large
+travel, scaling, unrequested, unskippable. Give the composed final frame and a
+shorter hold.
+
+```ts
+if (reduced) {
+  gsap.set("[data-mark-outline]", { autoAlpha: 0 });
+  gsap.set(["[data-mark-fill]", "[data-word-line]"], { autoAlpha: 1, yPercent: 0 });
+  gsap.delayedCall(0.9, finish);
+  return;
+}
+```
+
+Note the second `gsap.set`: a `from` tween that never runs leaves its target at
+the authored start — invisible. The reduced branch must set the end state, not
+just skip the motion.
+
+## Tuning
+
+| Feels | Change |
+|---|---|
+| rushed | lengthen the holds before lengthening the beats |
+| sluggish | overlap more; keep the durations |
+| cheap | `power3.inOut` instead of `power1`; remove any overshoot |
+| busy | cut elements until one carries each beat |
+| like a slideshow | overlap at 60–70%, and add the hold |

package/skill/preset/cursor.md

@@ -0,0 +1,184 @@
+# Cursor
+
+A custom pointer. High reward and high risk: done well it makes a site feel
+authored, done badly it makes it unusable.
+
+**Decide first whether to hide the native cursor.** Keeping it and adding a
+follower is almost always the better trade — you get the character without
+taking away the visitor's most reliable affordance.
+
+## Two layers, two speeds
+
+One element tracking instantly, one lagging. That difference is the whole
+effect; a single follower reads as a laggy cursor.
+
+```ts
+"use client";
+
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { useRef } from "react";
+
+gsap.registerPlugin(useGSAP);
+
+export function useCursor() {
+  const dotRef = useRef<HTMLDivElement>(null);
+  const ringRef = useRef<HTMLDivElement>(null);
+
+  useGSAP(() => {
+    const dot = dotRef.current;
+    const ring = ringRef.current;
+    if (!dot || !ring) return;
+
+    const mm = gsap.matchMedia();
+
+    /**
+     * A follower on a touch device is dead weight parked in a corner, and one
+     * that chases a pointer for someone who asked for reduced motion is the
+     * kind of unrequested movement the preference exists to stop.
+     */
+    mm.add(
+      "(hover: hover) and (pointer: fine) and (prefers-reduced-motion: no-preference)",
+      () => {
+        const to = (el: HTMLElement, axis: "x" | "y", duration: number) =>
+          gsap.quickTo(el, axis, { duration, ease: "power3" });
+
+        const dotX = to(dot, "x", 0.12);
+        const dotY = to(dot, "y", 0.12);
+        const ringX = to(ring, "x", 0.5);
+        const ringY = to(ring, "y", 0.5);
+
+        gsap.set([dot, ring], { xPercent: -50, yPercent: -50, autoAlpha: 0 });
+
+        let seen = false;
+        const onMove = (event: PointerEvent) => {
+          if (!seen) {
+            seen = true;
+            /** Revealed on first move, so it never paints in the corner. */
+            gsap.to([dot, ring], { autoAlpha: 1, duration: 0.3 });
+          }
+          dotX(event.clientX);
+          dotY(event.clientY);
+          ringX(event.clientX);
+          ringY(event.clientY);
+        };
+
+        /** Hidden when the pointer leaves the document entirely. */
+        const onOut = () => gsap.to([dot, ring], { autoAlpha: 0, duration: 0.2 });
+
+        window.addEventListener("pointermove", onMove);
+        document.addEventListener("pointerleave", onOut);
+
+        return () => {
+          window.removeEventListener("pointermove", onMove);
+          document.removeEventListener("pointerleave", onOut);
+        };
+      },
+    );
+
+    /* The context reverts `mm` itself; the listeners above are ours. */
+  });
+
+  return { dotRef, ringRef };
+}
+```
+
+`xPercent: -50, yPercent: -50` centres each layer on the pointer without knowing
+its size.
+
+## Markup
+
+```tsx
+<div ref={ringRef} aria-hidden="true"
+     className="pointer-events-none fixed start-0 top-0 z-200 size-9 rounded-full border" />
+<div ref={dotRef} aria-hidden="true"
+     className="pointer-events-none fixed start-0 top-0 z-200 size-1.5 rounded-full" />
+```
+
+`pointer-events: none` and `aria-hidden` on both, always. `fixed` positioning so
+the coordinates are viewport coordinates — no scroll maths.
+
+## Reacting to what is under it
+
+The character comes from the follower changing over different targets. Drive it
+from a data attribute rather than a list of selectors:
+
+```tsx
+<a data-cursor="expand">…</a>
+<video data-cursor="play">…</video>
+```
+
+```ts
+const onOver = (event: PointerEvent) => {
+  const hit = (event.target as Element).closest("[data-cursor]");
+  const mode = hit?.getAttribute("data-cursor");
+
+  gsap.to(ring, {
+    scale: mode === "expand" ? 2.4 : 1,
+    borderWidth: mode === "expand" ? 1 : 2,
+    duration: 0.4,
+    ease: "power3.out",
+    overwrite: "auto",
+  });
+};
+
+document.addEventListener("pointerover", onOver);
+```
+
+`overwrite: "auto"` matters here — moving quickly across several targets
+otherwise leaves the ring blended between two states.
+
+## Capture
+
+The ring sticks to an element's centre while the pointer is over it. This is the
+effect that makes navigation feel magnetic without moving the link itself:
+
+```ts
+const rect = hit.getBoundingClientRect();
+ringX(rect.left + rect.width / 2);
+ringY(rect.top + rect.height / 2);
+```
+
+Combine with [magnetic.md](magnetic.md) carefully — both moving at once reads as
+instability. Pick one.
+
+## Hiding the native cursor
+
+If you must:
+
+```css
+@media (hover: hover) and (pointer: fine) {
+  body { cursor: none; }
+}
+```
+
+Then the replacement must be at least as legible over every surface — dark,
+light, image, video — and must never apply over text inputs or textareas, where
+the I-beam carries real information:
+
+```css
+input, textarea, [contenteditable] { cursor: auto; }
+```
+
+Restore the cursor on any surface where your follower might not render: a
+`<canvas>`, an `<iframe>`, a native `<select>` popup.
+
+## Accessibility
+
+The follower is decoration. Nothing about it may carry information — a "click
+me" that only exists as a cursor state is invisible to a keyboard, to touch, and
+to a screen reader.
+
+The `(hover: hover)` and reduced-motion gates in the `matchMedia` query are not
+optional.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Sits in the corner on mobile | missing `(hover: hover)` gate |
+| Flashes at 0,0 on load | not hidden until the first move |
+| Blocks clicks | missing `pointer-events: none` |
+| Blends between hover states | missing `overwrite: "auto"` |
+| Offset by the scroll | `absolute` instead of `fixed` |
+| Survives navigation | listeners not removed |

package/skill/preset/loader.md

@@ -0,0 +1,172 @@
+# Loader
+
+A loader's job is to say "this is working" and, if possible, "for about this
+long". Everything else is decoration.
+
+Two rules that outrank craft: **it must never be able to hang**, and **it must
+show something under reduced motion** — a loader with nothing moving reads as a
+page that has crashed.
+
+A worked example, with the code that matters: [example/svg-loader.md](../example/svg-loader.md).
+
+## Travelling dash
+
+The one to reach for. No DOM churn, no layout, one property.
+
+```ts
+gsap.timeline({ repeat: -1 })
+  .fromTo("#ring", { drawSVG: "0% 0%" },
+                   { drawSVG: "0% 75%", duration: 0.9, ease: "power2.inOut" })
+  .to("#ring", { drawSVG: "100% 100%", duration: 0.9, ease: "power2.inOut" });
+
+gsap.to("#ring", {
+  rotation: 360, transformOrigin: "50% 50%",
+  repeat: -1, duration: 1.8, ease: "none",
+});
+```
+
+Two tweens because growing and shrinking have different origins — that
+difference is what reads as a pulse rather than a slide. The rotation runs
+separately so the dash never appears to stall at the seam.
+
+Needs a stroke. See [svg.md](../reference/svg.md).
+
+## Morph cycle
+
+```ts
+const tl = gsap.timeline({ repeat: -1 });
+
+for (const shape of ["#b", "#c", "#a"]) {
+  tl.to("#morph", {
+    morphSVG: { shape, type: "rotational" },
+    duration: 0.7,
+    ease: "power2.inOut",
+  }).to({}, { duration: 0.3 });     // hold, so each shape is legible
+}
+```
+
+The empty tween is a hold that is visible in the structure. Keep node counts
+within 3× or the morph smears.
+
+## Orbit
+
+```ts
+gsap.to("#dot", {
+  motionPath: { path: "#track", align: "#track",
+                alignOrigin: [0.5, 0.5], autoRotate: true },
+  duration: 2.4, repeat: -1, ease: "none",
+});
+```
+
+`ease: "none"` — anything else stutters at the loop seam. Several orbiters:
+`stagger: { each: duration / count, repeat: -1 }`.
+
+**The viewBox must contain the orbit, not just the artwork.** An orbit around a
+wide lockup is taller than it, and the dot is clipped for part of every lap.
+
+## Logo that draws itself
+
+A filled logo has no stroke for DrawSVG to animate. Two layers of the same
+geometry: a stroked copy draws, the filled version fades in under it, the
+outline fades out.
+
+```ts
+tl.fromTo("[data-outline]", { drawSVG: "0%" },
+          { drawSVG: "100%", duration: 1.2, stagger: 0.12, ease: "power2.inOut" })
+  .to("[data-fill]", { autoAlpha: 1, duration: 0.4 }, "-=0.5")
+  .to("[data-outline]", { autoAlpha: 0, duration: 0.3 }, "<0.15");
+```
+
+A useful side effect: with JavaScript unavailable the stroked layer is what
+renders, so the fallback is the mark in outline rather than an empty box.
+
+## Determinate progress
+
+When there is a real number, drive the timeline instead of looping it.
+
+```ts
+const tl = gsap.timeline({ paused: true });
+tl.fromTo("#ring", { drawSVG: "0%" }, { drawSVG: "100%", ease: "none" });
+
+gsap.to(tl, { progress, duration: 0.4, ease: "power2.out", overwrite: true });
+```
+
+Tween the progress rather than setting it — that is what smooths a value
+arriving as 0 → 40 → 100. `overwrite: true` stops two updates fighting.
+
+Never let a determinate bar sit at 100% while work continues. Cap the animated
+value at ~90% until the work actually completes.
+
+## Dismissal must be a race
+
+This is the part that breaks in production. A loader waiting on a signal can
+wait forever — a failed request, a missed event, a `load` that never fires
+because one image is stuck. The result is not a slow page; it is a page nobody
+can reach.
+
+```ts
+let done = false;
+const finish = () => { if (done) return; done = true; onDone(); };
+
+const ceiling = window.setTimeout(finish, MAX_VISIBLE_MS);
+tl.eventCallback("onComplete", finish);
+
+return () => window.clearTimeout(ceiling);
+```
+
+A timeline containing an infinitely repeating child **never completes**, so its
+`onComplete` never fires. Give the timeline a finite beat of its own to end on,
+or drive the handover from elsewhere.
+
+Render the real page underneath the whole time, so a visitor whose JavaScript
+fails gets the site rather than a permanent curtain.
+
+## Exit
+
+A loader that vanishes abruptly makes the page feel like it broke.
+
+```ts
+const exit = gsap.timeline({ paused: true })
+  .to("#ring", { drawSVG: "100% 100%", duration: 0.4, ease: "power2.in" })
+  .to(root, { autoAlpha: 0, duration: 0.3 }, "-=0.1");
+```
+
+## Accessibility
+
+- `role="status"` and an accessible name on the container. It announces
+  politely without stealing focus.
+- The artwork inside is `aria-hidden`. Never put an `sr-only` label inside an
+  `aria-hidden` container — it is never read.
+- Reduced motion: the artwork arrives already drawn, with a slow opacity pulse.
+  Keep *something* moving.
+
+```ts
+if (reduced) {
+  gsap.set("[data-outline]", { drawSVG: "100%" });
+  gsap.to("[data-pulse]", { autoAlpha: 0.35, duration: 1.1,
+                            repeat: -1, yoyo: true, ease: "sine.inOut" });
+  return;
+}
+```
+
+## Duration
+
+| Wait | Show |
+|---|---|
+| under 300ms | nothing — a flashed loader is worse than none |
+| 300ms–1s | a simple spinner |
+| 1–5s | a loader with character; a brand moment is affordable |
+| over 5s | determinate progress, or explain what is happening |
+
+Delay the loader's own appearance by ~300ms so fast responses never flash one.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Nothing moves, no error | `drawSVG` on a shape with no stroke |
+| Curtain never lifts | dismissal waits on a signal with no ceiling |
+| `onComplete` never fires | an infinitely repeating child |
+| Stutters once per loop | an ease other than `none` on a repeat |
+| Dot clipped mid-orbit | viewBox sized to the artwork, not the orbit |
+| Two loaders move as one | shared hardcoded ids in plugin config |