@mehshekari/gsap-motion 4.3.0 → 4.5.0

package/skill/template/useScrollScene.ts

@@ -1,126 +1,126 @@
-"use client";
-
-import { useGSAP } from "@gsap/react";
-import gsap from "gsap";
-import { ScrollTrigger } from "gsap/ScrollTrigger";
-import { useRef } from "react";
-
-/**
- * Starting point for a scroll-driven scene.
- *
- * The shape here is the lesson: one trigger owning one timeline, a genuinely
- * different strategy on mobile rather than a smaller one, and `ease: "none"`
- * throughout because the scrollbar — not an ease curve — is the playhead.
- *
- * Copy it, rename it, replace the beats. Typechecked for the same reason as
- * the sibling template.
- */
-gsap.registerPlugin(useGSAP, ScrollTrigger);
-
-/** Scroll distance the pinned sequence is spread across, in pixels. */
-const SCROLL_LENGTH = 2400;
-
-export function useScrollScene() {
-  const rootRef = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      const root = rootRef.current;
-      if (!root) return;
-
-      const mm = gsap.matchMedia();
-
-      mm.add(
-        {
-          desktop: "(min-width: 768px) and (prefers-reduced-motion: no-preference)",
-          mobile: "(max-width: 767px) and (prefers-reduced-motion: no-preference)",
-          reduced: "(prefers-reduced-motion: reduce)",
-        },
-        (context) => {
-          const { desktop, reduced } = context.conditions as Record<
-            string,
-            boolean
-          >;
-
-          /**
-           * Scroll-scrubbed pinning is a textbook vestibular trigger: the
-           * content moves while the page does not. Under `reduce` the beats
-           * simply exist, composed, with no pin and no scrub.
-           */
-          if (reduced) {
-            gsap.set("[data-beat]", { autoAlpha: 1, y: 0 });
-            return;
-          }
-
-          /**
-           * Not the desktop sequence scaled down. A 2400px pin on a phone is a
-           * long time to be stuck, and pinning fights the address bar
-           * collapsing — so each beat becomes an ordinary in-view reveal
-           * instead. Same content, different strategy.
-           */
-          if (!desktop) {
-            gsap.utils.toArray<HTMLElement>("[data-beat]").forEach((beat) => {
-              gsap.from(beat, {
-                autoAlpha: 0,
-                y: 24,
-                duration: 0.6,
-                ease: "power3.out",
-                scrollTrigger: { trigger: beat, start: "top 78%" },
-              });
-            });
-            return;
-          }
-
-          gsap
-            .timeline({
-              /**
-               * `ease: "none"` on every child. Easing inside a scrubbed
-               * timeline fights the visitor's own scrolling and reads as lag —
-               * `scrub` is where the smoothing belongs.
-               */
-              defaults: { ease: "none" },
-              scrollTrigger: {
-                trigger: root,
-                start: "top top",
-                end: `+=${SCROLL_LENGTH}`,
-                pin: true,
-                scrub: 1,
-                /** Reduces the flicker when the pin engages at speed. */
-                anticipatePin: 1,
-                /** Recomputes measured start values after a resize. */
-                invalidateOnRefresh: true,
-                markers: process.env.NODE_ENV === "development",
-              },
-            })
-            /**
-             * Labels rather than offsets. A scrubbed sequence gets retimed
-             * many times, and two children sharing a label stay together when
-             * the beat before them changes length.
-             */
-            .addLabel("open")
-            .from("[data-beat='1']", { autoAlpha: 0, y: 24, duration: 0.4 }, "open")
-
-            .addLabel("detail")
-            .to("[data-beat='1']", { autoAlpha: 0, duration: 0.3 }, "detail")
-            .from("[data-beat='2']", { autoAlpha: 0, y: 24, duration: 0.4 }, "detail+=0.3")
-
-            /**
-             * Placed at position 0 with the timeline's full span, so it tracks
-             * overall progress regardless of what else is happening.
-             */
-            .to("[data-progress]", { scaleX: 1, transformOrigin: "0% 50%" }, 0);
-        },
-      );
-
-      /**
-       * ScrollTriggers and the `matchMedia` above are both reverted with the
-       * context — each registers itself when constructed inside one. Only
-       * things GSAP never sees (timers, raw listeners, observers) need a
-       * cleanup returned from here.
-       */
-    },
-    { scope: rootRef },
-  );
-
-  return rootRef;
-}
+"use client";
+
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { useRef } from "react";
+
+/**
+ * Starting point for a scroll-driven scene.
+ *
+ * The shape here is the lesson: one trigger owning one timeline, a genuinely
+ * different strategy on mobile rather than a smaller one, and `ease: "none"`
+ * throughout because the scrollbar — not an ease curve — is the playhead.
+ *
+ * Copy it, rename it, replace the beats. Typechecked for the same reason as
+ * the sibling template.
+ */
+gsap.registerPlugin(useGSAP, ScrollTrigger);
+
+/** Scroll distance the pinned sequence is spread across, in pixels. */
+const SCROLL_LENGTH = 2400;
+
+export function useScrollScene() {
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const root = rootRef.current;
+      if (!root) return;
+
+      const mm = gsap.matchMedia();
+
+      mm.add(
+        {
+          desktop: "(min-width: 768px) and (prefers-reduced-motion: no-preference)",
+          mobile: "(max-width: 767px) and (prefers-reduced-motion: no-preference)",
+          reduced: "(prefers-reduced-motion: reduce)",
+        },
+        (context) => {
+          const { desktop, reduced } = context.conditions as Record<
+            string,
+            boolean
+          >;
+
+          /**
+           * Scroll-scrubbed pinning is a textbook vestibular trigger: the
+           * content moves while the page does not. Under `reduce` the beats
+           * simply exist, composed, with no pin and no scrub.
+           */
+          if (reduced) {
+            gsap.set("[data-beat]", { autoAlpha: 1, y: 0 });
+            return;
+          }
+
+          /**
+           * Not the desktop sequence scaled down. A 2400px pin on a phone is a
+           * long time to be stuck, and pinning fights the address bar
+           * collapsing — so each beat becomes an ordinary in-view reveal
+           * instead. Same content, different strategy.
+           */
+          if (!desktop) {
+            gsap.utils.toArray<HTMLElement>("[data-beat]").forEach((beat) => {
+              gsap.from(beat, {
+                autoAlpha: 0,
+                y: 24,
+                duration: 0.6,
+                ease: "power3.out",
+                scrollTrigger: { trigger: beat, start: "top 78%" },
+              });
+            });
+            return;
+          }
+
+          gsap
+            .timeline({
+              /**
+               * `ease: "none"` on every child. Easing inside a scrubbed
+               * timeline fights the visitor's own scrolling and reads as lag —
+               * `scrub` is where the smoothing belongs.
+               */
+              defaults: { ease: "none" },
+              scrollTrigger: {
+                trigger: root,
+                start: "top top",
+                end: `+=${SCROLL_LENGTH}`,
+                pin: true,
+                scrub: 1,
+                /** Reduces the flicker when the pin engages at speed. */
+                anticipatePin: 1,
+                /** Recomputes measured start values after a resize. */
+                invalidateOnRefresh: true,
+                markers: process.env.NODE_ENV === "development",
+              },
+            })
+            /**
+             * Labels rather than offsets. A scrubbed sequence gets retimed
+             * many times, and two children sharing a label stay together when
+             * the beat before them changes length.
+             */
+            .addLabel("open")
+            .from("[data-beat='1']", { autoAlpha: 0, y: 24, duration: 0.4 }, "open")
+
+            .addLabel("detail")
+            .to("[data-beat='1']", { autoAlpha: 0, duration: 0.3 }, "detail")
+            .from("[data-beat='2']", { autoAlpha: 0, y: 24, duration: 0.4 }, "detail+=0.3")
+
+            /**
+             * Placed at position 0 with the timeline's full span, so it tracks
+             * overall progress regardless of what else is happening.
+             */
+            .to("[data-progress]", { scaleX: 1, transformOrigin: "0% 50%" }, 0);
+        },
+      );
+
+      /**
+       * ScrollTriggers and the `matchMedia` above are both reverted with the
+       * context — each registers itself when constructed inside one. Only
+       * things GSAP never sees (timers, raw listeners, observers) need a
+       * cleanup returned from here.
+       */
+    },
+    { scope: rootRef },
+  );
+
+  return rootRef;
+}

package/skill/template/useTimeline.ts

@@ -1,110 +1,110 @@
-"use client";
-
-import { useGSAP } from "@gsap/react";
-import gsap from "gsap";
-import { useCallback, useRef } from "react";
-
-/**
- * Starting point for a component-scoped GSAP timeline.
- *
- * Copy it into the project's hooks folder or next to the component that owns
- * it, rename it, and replace the timeline body. The structure is the part worth
- * keeping: plugin registration at module scope, a scoped `useGSAP`, a
- * `matchMedia` branch that treats reduced motion as a design rather than an off
- * switch, and an explicit teardown for the things the GSAP context does not
- * own.
- *
- * Worth typechecking where the skill is installed: add the skill's `template/`
- * folder to `tsconfig.json`'s `include`. TypeScript's globs skip dot-directories
- * such as `.claude/`, and an example that has quietly stopped compiling is worse
- * than none.
- */
-gsap.registerPlugin(useGSAP);
-
-/** One place for the numbers, so retiming is not a hunt through the body. */
-const TIMING = {
-  enter: 0.8,
-  stagger: 0.08,
-  hold: 0.4,
-} as const;
-
-export function useTimeline() {
-  const rootRef = useRef<HTMLDivElement>(null);
-
-  /**
-   * Kept on a ref rather than returned directly: the timeline is built inside
-   * the effect, and a caller that wants to replay it needs a stable handle that
-   * does not exist until then.
-   */
-  const timelineRef = useRef<gsap.core.Timeline | null>(null);
-
-  useGSAP(
-    () => {
-      /**
-       * `matchMedia` rather than a one-off query, because a visitor can change
-       * the preference or the viewport while the component is mounted. GSAP
-       * reverts the losing branch and builds the other one; a plain `if` leaves
-       * the first animation running forever.
-       */
-      const mm = gsap.matchMedia();
-
-      mm.add(
-        {
-          motion: "(prefers-reduced-motion: no-preference)",
-          reduced: "(prefers-reduced-motion: reduce)",
-        },
-        (context) => {
-          const { reduced } = context.conditions as Record<string, boolean>;
-
-          /**
-           * The reduced branch must set the END state, not merely skip the
-           * tween. A `from` that never runs leaves its target at the authored
-           * start — which hides the content rather than calming it. This is the
-           * most common reduced-motion bug there is.
-           */
-          if (reduced) {
-            gsap.set("[data-item]", { autoAlpha: 1, y: 0 });
-            return;
-          }
-
-          timelineRef.current = gsap
-            .timeline({ defaults: { ease: "power3.out" } })
-            .from("[data-item]", {
-              y: 32,
-              autoAlpha: 0,
-              duration: TIMING.enter,
-              stagger: TIMING.stagger,
-            })
-            /**
-             * Positions, not delays. `<` starts a child with the previous one
-             * and survives a duration change upstream, where `-=0.3` silently
-             * drifts.
-             */
-            .to("[data-accent]", { scaleX: 1, duration: 0.5 }, "<0.2");
-        },
-      );
-
-      /**
-       * Nothing is returned, and that is deliberate. `matchMedia` registers
-       * itself with whatever GSAP context is active when it is constructed, so
-       * this one is reverted along with every tween above — as are Observer,
-       * Draggable, SplitText and ScrollTrigger when built in here.
-       *
-       * What a context never sees is the rest: timers, raw `addEventListener`,
-       * ResizeObserver, Three.js disposal. Return a cleanup for those.
-       */
-    },
-    { scope: rootRef },
-  );
-
-  /**
-   * Playing a timeline that already exists creates nothing, so this needs no
-   * `contextSafe` — the context already owns it. Wrapping it would also be a
-   * lint error, because `contextSafe` runs during render and reading a ref
-   * there is what React forbids. Reserve `contextSafe` for a handler that
-   * *creates* a tween.
-   */
-  const replay = useCallback(() => timelineRef.current?.restart(), []);
-
-  return { rootRef, replay };
-}
+"use client";
+
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { useCallback, useRef } from "react";
+
+/**
+ * Starting point for a component-scoped GSAP timeline.
+ *
+ * Copy it into the project's hooks folder or next to the component that owns
+ * it, rename it, and replace the timeline body. The structure is the part worth
+ * keeping: plugin registration at module scope, a scoped `useGSAP`, a
+ * `matchMedia` branch that treats reduced motion as a design rather than an off
+ * switch, and an explicit teardown for the things the GSAP context does not
+ * own.
+ *
+ * Worth typechecking where the skill is installed: add the skill's `template/`
+ * folder to `tsconfig.json`'s `include`. TypeScript's globs skip dot-directories
+ * such as `.claude/`, and an example that has quietly stopped compiling is worse
+ * than none.
+ */
+gsap.registerPlugin(useGSAP);
+
+/** One place for the numbers, so retiming is not a hunt through the body. */
+const TIMING = {
+  enter: 0.8,
+  stagger: 0.08,
+  hold: 0.4,
+} as const;
+
+export function useTimeline() {
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  /**
+   * Kept on a ref rather than returned directly: the timeline is built inside
+   * the effect, and a caller that wants to replay it needs a stable handle that
+   * does not exist until then.
+   */
+  const timelineRef = useRef<gsap.core.Timeline | null>(null);
+
+  useGSAP(
+    () => {
+      /**
+       * `matchMedia` rather than a one-off query, because a visitor can change
+       * the preference or the viewport while the component is mounted. GSAP
+       * reverts the losing branch and builds the other one; a plain `if` leaves
+       * the first animation running forever.
+       */
+      const mm = gsap.matchMedia();
+
+      mm.add(
+        {
+          motion: "(prefers-reduced-motion: no-preference)",
+          reduced: "(prefers-reduced-motion: reduce)",
+        },
+        (context) => {
+          const { reduced } = context.conditions as Record<string, boolean>;
+
+          /**
+           * The reduced branch must set the END state, not merely skip the
+           * tween. A `from` that never runs leaves its target at the authored
+           * start — which hides the content rather than calming it. This is the
+           * most common reduced-motion bug there is.
+           */
+          if (reduced) {
+            gsap.set("[data-item]", { autoAlpha: 1, y: 0 });
+            return;
+          }
+
+          timelineRef.current = gsap
+            .timeline({ defaults: { ease: "power3.out" } })
+            .from("[data-item]", {
+              y: 32,
+              autoAlpha: 0,
+              duration: TIMING.enter,
+              stagger: TIMING.stagger,
+            })
+            /**
+             * Positions, not delays. `<` starts a child with the previous one
+             * and survives a duration change upstream, where `-=0.3` silently
+             * drifts.
+             */
+            .to("[data-accent]", { scaleX: 1, duration: 0.5 }, "<0.2");
+        },
+      );
+
+      /**
+       * Nothing is returned, and that is deliberate. `matchMedia` registers
+       * itself with whatever GSAP context is active when it is constructed, so
+       * this one is reverted along with every tween above — as are Observer,
+       * Draggable, SplitText and ScrollTrigger when built in here.
+       *
+       * What a context never sees is the rest: timers, raw `addEventListener`,
+       * ResizeObserver, Three.js disposal. Return a cleanup for those.
+       */
+    },
+    { scope: rootRef },
+  );
+
+  /**
+   * Playing a timeline that already exists creates nothing, so this needs no
+   * `contextSafe` — the context already owns it. Wrapping it would also be a
+   * lint error, because `contextSafe` runs during render and reading a ref
+   * there is what React forbids. Reserve `contextSafe` for a handler that
+   * *creates* a tween.
+   */
+  const replay = useCallback(() => timelineRef.current?.restart(), []);
+
+  return { rootRef, replay };
+}