@mehshekari/gsap-motion 4.3.0 → 4.4.2

package/skill/preset/cursor.md

@@ -1,184 +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 |
+# 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/magnetic.md

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