@cosmictraveler002/anim-kit 1.0.0 → 1.2.0

package/src/effects/flip-words.ts

@@ -0,0 +1,148 @@
+/**
+ * Flip word transfer — words glide from one layout into another (FLIP).
+ *
+ * The source block holds the words; `to` is the block they land in. Both
+ * blocks should share one grid cell so the page never reflows when the
+ * words move:
+ *
+ *     .flip-stage     { display: grid; }
+ *     .flip-stage > div { grid-area: 1 / 1; }  // source + destination overlap
+ *
+ * On trigger every word is measured where it stands, moved into the
+ * destination, and animated from its old position (the classic FLIP
+ * technique), with a mid-flight squash so the words pop as they travel.
+ * Because the measurement happens up front, the words *look* like they are
+ * still in the source at scroll progress 0 even though they already live in
+ * the destination — so a scrubbed transfer reverses perfectly.
+ *
+ *   flipWords("[data-flip-from]", { to: "[data-flip-to]", scrub: 1 });
+ *
+ * destroy() kills the timeline, puts every word back in its original
+ * parent (in the original order) and restores its inline transform.
+ */
+import { gsap, Flip, ScrollTrigger, initGSAP, killTweens } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { one, toArray } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface FlipWordsOptions extends CommonOptions {
+  /** Destination block — every word is moved into it. */
+  to: TargetLike;
+  /**
+   * The words inside the source.
+   * @default `[data-flip-word]` matches, else the source's element children
+   */
+  words?: TargetLike;
+  /** Seconds for one word's travel. @default 1.4 */
+  duration?: number;
+  /** GSAP ease. @default "power4.inOut" */
+  ease?: string;
+  /** Seconds between word starts. @default 0.2 */
+  stagger?: number;
+  /** Mid-flight scale a word squashes to (0 disables the squash). @default 0.2 */
+  scale?: number;
+  /** "scroll" plays on enter (reverses on leave-back), "immediate" plays now. @default "scroll" */
+  mode?: "scroll" | "immediate";
+  /**
+   * Bind the transfer to scroll progress instead of playing it on enter —
+   * number = scrub smoothing seconds, `true` = immediate. unset = one-shot.
+   */
+  scrub?: number | boolean;
+  /** ScrollTrigger start. @default "top 75%" */
+  start?: string;
+  /** ScrollTrigger end (scrub mode). @default "bottom 45%" */
+  end?: string;
+}
+
+export function flipWords(from: TargetLike, options: FlipWordsOptions): Destroy {
+  initGSAP();
+
+  const src = one<HTMLElement>(from);
+  const dest = one<HTMLElement>(options?.to);
+  if (!src || !dest) return () => {};
+
+  const {
+    words,
+    duration = 1.4,
+    ease = "power4.inOut",
+    stagger = 0.2,
+    scale = 0.2,
+    mode = "scroll",
+    scrub,
+    start = "top 75%",
+    end = "bottom 45%",
+  } = options;
+
+  const marked = toArray<HTMLElement>(src.querySelectorAll("[data-flip-word]"));
+  const wordEls = words
+    ? toArray<HTMLElement>(words, src)
+    : marked.length
+      ? marked
+      : [...src.children] as HTMLElement[];
+  if (!wordEls.length) return () => {};
+
+  return guard(options, () => {
+    // Remember each word's home so destroy() can put everything back in order.
+    const home = wordEls.map((w) => ({ parent: w.parentNode, next: w.nextSibling }));
+    const prevTransform = wordEls.map((w) => w.style.transform);
+
+    // Measure in the source, move into the destination, then animate from
+    // the measurement — the FLIP. The wrapper timeline owns the flight so
+    // ScrollTrigger can scrub it and the scale accents can share its clock.
+    const state = Flip.getState(wordEls);
+    wordEls.forEach((w) => dest.appendChild(w));
+
+    const tl = gsap.timeline({ paused: true });
+    // The wrapper is paused, and `add` is synchronous, so the Flip child
+    // never renders on the global timeline before the wrapper owns it.
+    tl.add(Flip.from(state, { duration, ease, stagger: { each: stagger } }), 0);
+
+    if (scale > 0) {
+      wordEls.forEach((w, i) => {
+        const at = i * stagger;
+        tl.to(w, { scale, duration: duration * 0.5, ease }, at);
+        tl.to(w, { scale: 1, duration: duration * 0.5, ease }, at + duration * 0.5);
+      });
+    }
+
+    let st: ScrollTrigger | undefined;
+    if (mode === "immediate") {
+      tl.play(0);
+    } else if (scrub !== undefined) {
+      st = ScrollTrigger.create({
+        trigger: src,
+        start,
+        end,
+        scrub: scrub === true ? true : scrub,
+        animation: tl,
+      });
+    } else {
+      st = ScrollTrigger.create({
+        trigger: src,
+        start,
+        animation: tl,
+        toggleActions: "play none none reverse",
+      });
+    }
+    ScrollTrigger.refresh();
+
+    return () => {
+      st?.kill();
+      tl.kill();
+      killTweens(wordEls);
+      // Reparent home. A stored `next` sibling that has moved with the words
+      // is not in the parent anymore — fall back to appending in order.
+      wordEls.forEach((w, i) => {
+        const h = home[i];
+        if (!h.parent) return;
+        const ref = h.next && h.next.parentNode === h.parent ? h.next : null;
+        h.parent.insertBefore(w, ref);
+      });
+      gsap.set(wordEls, { clearProps: "transform" });
+      wordEls.forEach((w, i) => {
+        w.style.transform = prevTransform[i];
+      });
+      ScrollTrigger.refresh();
+    };
+  });
+}

package/src/effects/line-reveal.ts

@@ -2,7 +2,9 @@
  * Line reveal — the masked, staggered text reveal used all over DZ!NR.
  *
  * Text is split into lines, each line gets an `overflow:hidden` mask, and the
- * inner line slides up from `y:100%` to `y:0%`.
+ * inner line slides up from `y:100%` to `y:0%`. `split: "chars"` runs the
+ * same masked rise per character (`.ak-char-mask > .ak-char`) with a tighter
+ * default stagger — the per-letter headline reveal.
  *
  * Two modes:
  *   mode: "scroll"   → plays when the element enters the viewport and reverses
@@ -20,7 +22,9 @@ import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
 export interface LineRevealOptions extends CommonOptions {
   /** "scroll" plays on enter/reverse on leave; "immediate" plays at once. */
   mode?: "scroll" | "immediate";
-  /** Stagger between lines, seconds. @default 0.1 */
+  /** Split granularity — masked lines, or masked per-character stagger. @default "lines" */
+  split?: "lines" | "chars";
+  /** Stagger between lines/chars, seconds. @default 0.1 (0.03 for chars) */
   stagger?: number;
   /** Animation duration, seconds. @default 1 */
   duration?: number;
@@ -39,13 +43,15 @@ export function lineReveal(target: TargetLike, options: LineRevealOptions = {}):
 
   const {
     mode = "scroll",
-    stagger = 0.1,
+    split: splitType = "lines",
+    stagger,
     duration = 1,
     ease = "power4.out",
     delay = 0,
     start = "top 90%",
     end = "bottom 10%",
   } = options;
+  const stag = stagger ?? (splitType === "chars" ? 0.03 : 0.1);
 
   const els = toArray<HTMLElement>(target);
   if (!els.length) return () => {};
@@ -58,9 +64,10 @@ export function lineReveal(target: TargetLike, options: LineRevealOptions = {}):
 
     els.forEach((el) => {
       const res = split(el, {
-        type: "lines",
+        type: splitType,
         mask: true,
         linesClass: "ak-line++",
+        charsClass: "ak-char++",
         lineThreshold: 0.05,
       });
       splits.push(res);
@@ -75,7 +82,7 @@ export function lineReveal(target: TargetLike, options: LineRevealOptions = {}):
       const vars: gsap.TweenVars = {
         y: "0%",
         duration,
-        stagger,
+        stagger: stag,
         ease,
         delay,
         overwrite: "auto",

package/src/effects/magnetic.ts

@@ -0,0 +1,87 @@
+/**
+ * Magnetic hover — buttons and links that pull toward the pointer.
+ *
+ * While the pointer is over the element it follows the cursor (a fraction
+ * of its own box), tilts toward the pull, and optionally grows a touch.
+ * On leave it springs back to rest with an elastic snap:
+ *
+ *   magnetic("[data-magnet]", { strength: 0.5, rotation: 10 });
+ *
+ * Attach it to individual buttons/links (or a container's children — pass
+ * the list). destroy() removes the listeners, kills in-flight tweens and
+ * restores the inline transform.
+ */
+import { gsap, initGSAP, killTweens } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { toArray } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface MagneticOptions extends CommonOptions {
+  /** How far the element follows the pointer — fraction of its own box. @default 0.4 */
+  strength?: number;
+  /** Max tilt in degrees at full pull (0 disables rotation). @default 8 */
+  rotation?: number;
+  /** Scale held while the pointer is over the element (1 = none). @default 1 */
+  scale?: number;
+  /** Spring-back duration, seconds. @default 1.2 */
+  duration?: number;
+  /** Spring-back ease. @default "elastic.out(1, 0.35)" */
+  ease?: string;
+}
+
+export function magnetic(target: TargetLike, options: MagneticOptions = {}): Destroy {
+  initGSAP();
+
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  const {
+    strength = 0.4,
+    rotation = 8,
+    scale = 1,
+    duration = 1.2,
+    ease = "elastic.out(1, 0.35)",
+  } = options;
+
+  return guard(options, () => {
+    const prevTransform = els.map((el) => el.style.transform);
+    const listeners: Array<{ el: HTMLElement; type: string; fn: EventListener }> = [];
+
+    els.forEach((el) => {
+      const onMove = (e: Event) => {
+        const ptr = e as PointerEvent;
+        const r = el.getBoundingClientRect();
+        const dx = ptr.clientX - (r.left + r.width / 2);
+        const dy = ptr.clientY - (r.top + r.height / 2);
+        const nx = r.width ? dx / (r.width / 2) : 0; // -1 … 1 across the box
+        gsap.to(el, {
+          x: dx * strength,
+          y: dy * strength,
+          rotation: rotation ? nx * rotation : 0,
+          scale,
+          duration: 0.4,
+          ease: "power3.out",
+          overwrite: "auto",
+        });
+      };
+      const onLeave = () => {
+        gsap.to(el, { x: 0, y: 0, rotation: 0, scale: 1, duration, ease, overwrite: "auto" });
+      };
+
+      el.addEventListener("pointermove", onMove);
+      el.addEventListener("pointerleave", onLeave);
+      listeners.push(
+        { el, type: "pointermove", fn: onMove },
+        { el, type: "pointerleave", fn: onLeave },
+      );
+    });
+
+    return () => {
+      listeners.forEach(({ el, type, fn }) => el.removeEventListener(type, fn));
+      killTweens(els);
+      els.forEach((el, i) => {
+        el.style.transform = prevTransform[i];
+      });
+    };
+  });
+}

package/src/effects/media-settle.ts

@@ -0,0 +1,106 @@
+/**
+ * Media settle — images that arrive slightly oversized and settle to size.
+ *
+ * The classic entrance for grids and heroes: media enters at `scale > 1`
+ * and eases down to 1 as the section arrives (or across the scroll range in
+ * `scrub` mode), so content lands instead of popping in.
+ *
+ *   mediaSettle("[data-settle]", { from: 1.3 });            // on enter
+ *   mediaSettle("[data-settle]", { scrub: 0.5 });           // scroll-bound
+ *   mediaSettle("[data-settle]", { replay: true });         // reverse on leave-back, replay on re-enter
+ *
+ * destroy() kills the tween and restores the original scale.
+ */
+import { gsap, ScrollTrigger, initGSAP } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { toArray } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface MediaSettleOptions extends CommonOptions {
+  /** Starting scale — settles down to 1. @default 1.15 */
+  from?: number;
+  /** Animation duration, seconds (enter mode). @default 1.5 */
+  duration?: number;
+  /** GSAP ease. @default "power2.out" */
+  ease?: string;
+  /** transformOrigin. @default "center" */
+  origin?: string;
+  /** Stagger between targets, seconds. @default 0.06 */
+  stagger?: number;
+  /** Delay before playing, seconds. @default 0 */
+  delay?: number;
+  /** "scroll" plays on enter, "immediate" plays at once. @default "scroll" */
+  mode?: "scroll" | "immediate";
+  /** ScrollTrigger start position. @default "top 75%" */
+  start?: string;
+  /** ScrollTrigger end position (scrub mode). @default "bottom top" */
+  end?: string;
+  /** Re-settle when leaving / re-entering the viewport (enter mode). @default false */
+  replay?: boolean;
+  /**
+   * Bind the settle to scroll progress instead of playing it on enter —
+   * number = scrub smoothing seconds, `true` = immediate. unset = one-shot.
+   */
+  scrub?: number | boolean;
+}
+
+export function mediaSettle(target: TargetLike, options: MediaSettleOptions = {}): Destroy {
+  initGSAP();
+
+  const {
+    from = 1.15,
+    duration = 1.5,
+    ease = "power2.out",
+    origin = "center",
+    stagger = 0.06,
+    delay = 0,
+    mode = "scroll",
+    start = "top 75%",
+    end = "bottom top",
+    replay = false,
+    scrub,
+  } = options;
+
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  return guard(options, run);
+
+  function run(): Destroy {
+    gsap.set(els, { scale: from, transformOrigin: origin });
+
+    const vars: gsap.TweenVars = { scale: 1, stagger, delay, overwrite: "auto" };
+
+    if (scrub !== undefined) {
+      vars.ease = "none";
+      vars.scrollTrigger = {
+        trigger: els[0],
+        start,
+        end,
+        scrub: scrub === true ? true : scrub,
+      };
+    } else {
+      vars.duration = duration;
+      vars.ease = ease;
+      if (mode === "scroll") {
+        vars.scrollTrigger = replay
+          ? { trigger: els[0], start, toggleActions: "play reverse play reverse" }
+          : { trigger: els[0], start, once: true };
+      }
+    }
+
+    const tween = gsap.fromTo(
+      els,
+      { scale: from, transformOrigin: origin },
+      { ...vars, immediateRender: true },
+    );
+    ScrollTrigger.refresh();
+
+    return () => {
+      tween.scrollTrigger?.kill();
+      tween.kill();
+      gsap.set(els, { clearProps: "transform,transformOrigin" });
+      ScrollTrigger.refresh();
+    };
+  }
+}

package/src/effects/roll-text.ts

@@ -0,0 +1,118 @@
+/**
+ * Roll text — the rolling word rotator.
+ *
+ * The target holds two or more rows; they are stacked into a hidden overflow
+ * box one row tall, and the box rolls to the next row on an interval — the
+ * first row is cloned at the end so the wrap is seamless (same trick as
+ * `marquee()`).
+ *
+ *   <span class="ak-roll" data-roll>
+ *     <span>Design</span><span>Code</span><span>Motion</span>
+ *   </span>
+ *
+ * destroy() unwraps the rows, removes the clone and restores every inline
+ * style it touched — markup comes back byte-identical.
+ */
+import { gsap, initGSAP, killTweens } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { toArray } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface RollTextOptions extends CommonOptions {
+  /** Seconds each row is shown (including the roll). @default 2.2 */
+  interval?: number;
+  /** Roll duration, seconds. @default 0.6 */
+  duration?: number;
+  /** GSAP ease for the roll. @default "power4.inOut" */
+  ease?: string;
+  /** "up" rolls rows upward, "down" walks them in reverse. @default "up" */
+  direction?: "up" | "down";
+}
+
+export function rollText(target: TargetLike, options: RollTextOptions = {}): Destroy {
+  initGSAP();
+
+  const { interval = 2.2, duration = 0.6, ease = "power4.inOut", direction = "up" } = options;
+
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  return guard(options, () => {
+    const setups: Array<{
+      el: HTMLElement;
+      inner: HTMLElement;
+      rows: HTMLElement[];
+      snapshots: Array<{ el: HTMLElement; cssText: string }>;
+      timeline: gsap.core.Timeline | null;
+    }> = [];
+
+    els.forEach((el) => {
+      const rows = Array.from(el.children).filter(
+        (n): n is HTMLElement => n instanceof HTMLElement,
+      );
+      if (rows.length < 2) return;
+
+      // Snapshot inline styles BEFORE touching them (restored on destroy).
+      const snapshots: Array<{ el: HTMLElement; cssText: string }> = [
+        { el, cssText: el.style.cssText },
+        ...rows.map((r) => ({ el: r, cssText: r.style.cssText })),
+      ];
+
+      // Rows must stack as blocks for the box to measure one row.
+      rows.forEach((r) => (r.style.display = "block"));
+      if (window.getComputedStyle(el).display === "inline") el.style.display = "inline-block";
+
+      const inner = document.createElement("div");
+      inner.className = "ak-roll__inner";
+      el.insertBefore(inner, rows[0]);
+      rows.forEach((r) => inner.appendChild(r));
+      const clone = rows[0].cloneNode(true) as HTMLElement;
+      clone.setAttribute("data-ak-roll-clone", "");
+      inner.appendChild(clone);
+
+      const rowH = rows[0].getBoundingClientRect().height;
+      el.style.overflow = "hidden";
+      el.style.height = `${rowH}px`;
+      el.dataset.akRoll = String(rows.length);
+
+      let timeline: gsap.core.Timeline | null = null;
+      if (rowH > 0) {
+        const n = rows.length;
+        const hold = Math.max(0.01, interval - duration);
+        const tl = gsap.timeline({ repeat: -1, defaults: { ease } });
+        if (direction === "up") {
+          gsap.set(inner, { y: 0 });
+          for (let i = 1; i <= n; i++) {
+            tl.to(inner, { y: -i * rowH, duration });
+            tl.to({}, { duration: hold });
+          }
+          tl.set(inner, { y: 0 });
+        } else {
+          gsap.set(inner, { y: -n * rowH });
+          for (let i = n - 1; i >= 0; i--) {
+            tl.to(inner, { y: -i * rowH, duration });
+            tl.to({}, { duration: hold });
+          }
+          tl.set(inner, { y: -n * rowH });
+        }
+        timeline = tl;
+      }
+
+      setups.push({ el, inner, rows, snapshots, timeline });
+      // Clone lives inside inner — remember it for teardown via the attribute.
+    });
+
+    return () => {
+      setups.forEach(({ el, inner, rows, snapshots, timeline }) => {
+        timeline?.kill();
+        // Unwrap: rows home first, then drop the (now empty) inner box.
+        rows.forEach((r) => el.appendChild(r));
+        inner.remove();
+        killTweens(inner);
+        snapshots.forEach(({ el: node, cssText }) => (node.style.cssText = cssText));
+        delete el.dataset.akRoll;
+      });
+      setups.length = 0;
+    };
+  });
+}

package/src/effects/scramble-text.ts

@@ -0,0 +1,122 @@
+/**
+ * Scramble text — the decode / cipher reveal.
+ *
+ * Each character churns through the charset and settles on its final glyph,
+ * left to right; letters scramble, everything else (digits, punctuation,
+ * spaces) stays put, and case is preserved. Three triggers:
+ *
+ *   mode: "scroll"    → plays once when the element enters the viewport.
+ *   mode: "immediate" → plays at once (above the fold).
+ *   mode: "hover"     → re-scrambles on every pointer enter.
+ *
+ * The element's textContent is restored exactly on destroy.
+ */
+import { gsap, ScrollTrigger, initGSAP } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { toArray } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface ScrambleTextOptions extends CommonOptions {
+  /** "scroll" plays on enter, "immediate" now, "hover" on pointerenter. @default "scroll" */
+  mode?: "scroll" | "immediate" | "hover";
+  /** Glyphs each letter churns through. @default "abcdefghijklmnopqrstuvwxyz" */
+  charset?: string;
+  /** Seconds each character spends scrambling. @default 0.18 */
+  durationPerChar?: number;
+  /** Delay between character starts, seconds. @default 0.04 */
+  stagger?: number;
+  /** Delay before the timeline starts, seconds. @default 0 */
+  delay?: number;
+  /** ScrollTrigger start position (mode: "scroll"). @default "top 80%" */
+  start?: string;
+}
+
+export function scrambleText(target: TargetLike, options: ScrambleTextOptions = {}): Destroy {
+  initGSAP();
+
+  const {
+    mode = "scroll",
+    charset = "abcdefghijklmnopqrstuvwxyz",
+    durationPerChar = 0.18,
+    stagger = 0.04,
+    delay = 0,
+    start = "top 80%",
+  } = options;
+
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  return guard(options, () => {
+    const originals = new Map<HTMLElement, string>();
+    const timelines: gsap.core.Timeline[] = [];
+    const cleanups: Array<() => void> = [];
+
+    /** Fill a timeline with one eased scramble tween per letter. */
+    const fill = (el: HTMLElement, original: string, tl: gsap.core.Timeline) => {
+      Array.from(original).forEach((ch, i) => {
+        if (!/[a-z]/i.test(ch)) return; // digits / punctuation / spaces stay put
+        const upper = ch === ch.toUpperCase();
+        const state = { p: 0 };
+        tl.to(
+          state,
+          {
+            p: 1,
+            duration: durationPerChar,
+            ease: "power3.out",
+            onUpdate: () => {
+              if (state.p >= 1) return;
+              const glyph = charset[Math.floor(Math.random() * charset.length)];
+              el.textContent =
+                original.slice(0, i) + (upper ? glyph.toUpperCase() : glyph) + original.slice(i + 1);
+            },
+          },
+          i * stagger,
+        );
+      });
+      tl.eventCallback("onComplete", () => (el.textContent = original));
+    };
+
+    els.forEach((el) => {
+      const original = el.textContent ?? "";
+      if (!original) return;
+      originals.set(el, original);
+      el.dataset.akScramble = "true";
+
+      if (mode === "scroll") {
+        const tl = gsap.timeline({
+          delay,
+          scrollTrigger: { trigger: el, start, once: true },
+        });
+        fill(el, original, tl);
+        timelines.push(tl);
+      } else if (mode === "immediate") {
+        const tl = gsap.timeline({ delay });
+        fill(el, original, tl);
+        timelines.push(tl);
+      } else {
+        const tl = gsap.timeline({ delay, paused: true });
+        fill(el, original, tl);
+        timelines.push(tl);
+        const onEnter = () => tl.restart();
+        el.addEventListener("pointerenter", onEnter);
+        cleanups.push(() => el.removeEventListener("pointerenter", onEnter));
+      }
+    });
+
+    ScrollTrigger.refresh();
+
+    return () => {
+      cleanups.forEach((fn) => fn());
+      timelines.forEach((tl) => {
+        tl.scrollTrigger?.kill();
+        tl.kill();
+      });
+      originals.forEach((text, el) => {
+        el.textContent = text;
+        delete el.dataset.akScramble;
+      });
+      originals.clear();
+      ScrollTrigger.refresh();
+    };
+  });
+}