@cosmictraveler002/anim-kit 1.1.0 → 1.3.0

package/src/effects/drag-rail.ts

@@ -0,0 +1,236 @@
+/**
+ * Drag rail — the bounded, inertia-driven horizontal rail.
+ *
+ * A grab-and-throw rail with real physics, extracted from the drag-driven
+ * portfolio rail pattern: pointer drag, wheel and trackpad all feed one
+ * *intent* value, and the track follows it with a per-frame lerp. Why it is
+ * shaped this way (audit notes):
+ *
+ * - **Two values, not one.** `intent` is where the rail wants to be (drag
+ *   delta, wheel delta, throw momentum); `pos` is what is rendered. The tick
+ *   lerps intent → pos (`lerp * deltaRatio`), which is what gives the
+ *   buttery catch-up after a hard throw. Writing the transform directly from
+ *   pointermove (v1) felt like dragging a brick.
+ * - **tanh rubber-band.** Past either end, intent is squashed through
+ *   `edge * tanh(overshoot / edge)` — the further you pull, the less each
+ *   pixel buys you, but it never hard-stops. On release a restore force pulls
+ *   the overscrolled intent back inside the bounds while the lerp chases it,
+ *   producing the settle. This is the same soft-edge maths as the original
+ *   rail's `a.t = a.a + tanh(l / t) * t`.
+ * - **Release throw.** Velocity is sampled as a smoothed per-frame pointer
+ *   delta (0.7 smoothing) and multiplied by `throwScale` into intent — a flick
+ *   coasts, a slow release barely moves. No InertiaPlugin dependency; the
+ *   ticker *is* the inertia.
+ * - **Wheel coexistence.** While the rail can still move in the wheel's
+ *   direction the event is consumed (`preventDefault` + `stopPropagation` —
+ *   the stop matters: Lenis listens above us and would scroll the page in
+ *   parallel). Once overscrolled a full `edge`, the wheel passes through to
+ *   the page again, so the section never traps the reader.
+ * - **Velocity-reactive items.** `tilt` rotates children proportionally to the
+ *   rendered per-frame velocity (the cards lean into motion and spring flat at
+ *   rest); `onTick` exposes pos/velocity for WebGL or custom consumers.
+ * - **Fidelity.** `destroy()` removes every listener + the ticker, kills the
+ *   tilt state and restores the inline cursor/user-select/touch-action the
+ *   effect had overwritten.
+ *
+ *   dragRail(".ak-rail-track", { tilt: 0.05 })
+ *
+ * CSS: viewport `overflow: hidden`; track `display: flex; width: max-content;
+ * gap: 1rem; cursor: grab; user-select: none; touch-action: pan-y`.
+ */
+import { gsap, initGSAP } 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 DragRailOptions extends CommonOptions {
+  /** Scroll viewport around the track — defaults to `track.parentElement`. */
+  viewport?: TargetLike;
+  /** Children that tilt with velocity. @default `":scope > *"` */
+  item?: string;
+  /** Follow speed toward the intent, per 60fps frame (0..1). @default 0.1 */
+  lerp?: number;
+  /** Rubber-band resistance distance past the ends, px. @default 140 */
+  edge?: number;
+  /** Momentum multiplier on release (px of coast per px/frame of flick). @default 14 */
+  throwScale?: number;
+  /** Wheel / trackpad drives the rail (consumed while it can still move). @default true */
+  wheel?: boolean;
+  /** Degrees of tilt per px/frame of velocity — `0` disables. @default 0 */
+  tilt?: number;
+  /** Tilt clamp, degrees. @default 8 */
+  tiltMax?: number;
+  /** `(pos, velocity) => {}` called every rendered frame while mounted. */
+  onTick?: (pos: number, velocity: number) => void;
+}
+
+export function dragRail(target: TargetLike, options: DragRailOptions = {}): Destroy {
+  initGSAP();
+
+  const track = one<HTMLElement>(target);
+  if (!track) return () => {};
+
+  const {
+    viewport,
+    item = ":scope > *",
+    lerp = 0.1,
+    edge = 140,
+    throwScale = 14,
+    wheel = true,
+    tilt = 0,
+    tiltMax = 8,
+    onTick,
+  } = options;
+
+  return guard(options, () => {
+    const vp = one<HTMLElement>(viewport) ?? track.parentElement ?? track;
+    const prevStyle = {
+      cursor: track.style.cursor,
+      userSelect: track.style.userSelect,
+      touchAction: track.style.touchAction,
+    };
+
+    /* ---------------- bounds ---------------- */
+
+    let min = 0; // most-negative resting x (content overflows left)
+    let max = 0; // start of the rail
+    let pos = 0; // rendered x
+    let intent = 0; // wanted x (drag/wheel/throw feed this)
+
+    const measure = () => {
+      const overflow = Math.max(0, track.scrollWidth - vp.clientWidth);
+      min = -overflow;
+      max = 0;
+      // Fold an out-of-range position back through the soft edge (no jump).
+      intent = soft(intent);
+      pos = soft(pos);
+    };
+
+    /** tanh soft-edge: unbounded input, saturating output around [min, max]. */
+    function soft(v: number): number {
+      if (v > max) return max + edge * Math.tanh((v - max) / edge);
+      if (v < min) return min + edge * Math.tanh((v - min) / edge);
+      return v;
+    }
+
+    /* ---------------- pointer drag ---------------- */
+
+    let dragging = false;
+    let lastX = 0;
+    let velocity = 0; // smoothed pointer delta (px/frame-ish)
+    let renderedVel = 0; // rendered per-frame velocity (drives tilt/onTick)
+
+    const onPointerDown = (e: PointerEvent) => {
+      if (e.pointerType === "mouse" && e.button !== 0) return;
+      dragging = true;
+      lastX = e.clientX;
+      velocity = 0;
+      try {
+        vp.setPointerCapture(e.pointerId);
+      } catch {
+        /* capture is best-effort — moves still land while the pointer is down */
+      }
+      track.style.cursor = "grabbing";
+    };
+
+    const onPointerMove = (e: PointerEvent) => {
+      if (!dragging) return;
+      const dx = e.clientX - lastX;
+      lastX = e.clientX;
+      velocity = velocity * 0.7 + dx * 0.3; // smooth out event-rate jitter
+      intent = soft(intent + dx);
+    };
+
+    const endDrag = (e?: PointerEvent) => {
+      if (!dragging) return;
+      dragging = false;
+      track.style.cursor = prevStyle.cursor || "grab";
+      if (e) {
+        try {
+          vp.releasePointerCapture(e.pointerId);
+        } catch {
+          /* already released */
+        }
+      }
+      // A flick coasts on its sampled momentum, then the soft edge reclaims it.
+      intent = soft(intent + velocity * throwScale);
+    };
+
+    const onPointerUp = (e: PointerEvent) => endDrag(e);
+    const onPointerCancel = (e: PointerEvent) => endDrag(e);
+    const onDragStart = (e: Event) => e.preventDefault(); // no native img drag
+
+    /* ---------------- wheel / trackpad ---------------- */
+
+    const onWheel = (e: WheelEvent) => {
+      if (!wheel) return;
+      const delta = Math.abs(e.deltaX) > Math.abs(e.deltaY) ? e.deltaX : e.deltaY;
+      const bound = delta > 0 ? max : min;
+      const outward = (intent - bound) * (delta > 0 ? 1 : -1);
+      if (outward > edge) return; // over-extended — hand the scroll back to the page
+      e.preventDefault();
+      e.stopPropagation(); // Lenis listens above us; it must not scroll in parallel
+      intent = soft(intent + delta);
+    };
+
+    /* ---------------- tick ---------------- */
+
+    const items = tilt ? toArray<HTMLElement>(item, track) : [];
+    if (items.length) gsap.set(items, { transformOrigin: "50% 50%" });
+
+    const tick = () => {
+      const ratio = gsap.ticker.deltaRatio(60); // frames since last tick, clamped
+      // Release restore: once input stops, overscrolled intent springs home.
+      if (!dragging) {
+        const bound = intent < min ? min : intent > max ? max : null;
+        if (bound !== null) intent += (bound - intent) * Math.min(1, 0.18 * ratio);
+      }
+      const prev = pos;
+      pos += (intent - pos) * Math.min(1, lerp * ratio);
+      renderedVel = pos - prev;
+      if (renderedVel === 0 && pos === intent) return; // idle: skip the write
+      gsap.set(track, { x: pos });
+      if (items.length) {
+        gsap.set(items, {
+          rotation: gsap.utils.clamp(-tiltMax, tiltMax, renderedVel * tilt),
+        });
+      }
+      onTick?.(pos, renderedVel);
+    };
+
+    /* ---------------- wiring ---------------- */
+
+    measure();
+    track.dataset.akRail = "true";
+    track.style.cursor = "grab";
+    track.style.userSelect = "none";
+    track.style.touchAction = "pan-y";
+
+    vp.addEventListener("pointerdown", onPointerDown);
+    vp.addEventListener("pointermove", onPointerMove);
+    vp.addEventListener("pointerup", onPointerUp);
+    vp.addEventListener("pointercancel", onPointerCancel);
+    vp.addEventListener("wheel", onWheel, { passive: false });
+    track.addEventListener("dragstart", onDragStart);
+    const onResize = () => measure();
+    window.addEventListener("resize", onResize);
+    gsap.ticker.add(tick);
+
+    return () => {
+      window.removeEventListener("resize", onResize);
+      vp.removeEventListener("pointerdown", onPointerDown);
+      vp.removeEventListener("pointermove", onPointerMove);
+      vp.removeEventListener("pointerup", onPointerUp);
+      vp.removeEventListener("pointercancel", onPointerCancel);
+      vp.removeEventListener("wheel", onWheel);
+      track.removeEventListener("dragstart", onDragStart);
+      gsap.ticker.remove(tick);
+      delete track.dataset.akRail;
+      track.style.cursor = prevStyle.cursor;
+      track.style.userSelect = prevStyle.userSelect;
+      track.style.touchAction = prevStyle.touchAction;
+      gsap.set(track, { clearProps: "transform" });
+      if (items.length) gsap.set(items, { clearProps: "rotation,transformOrigin" });
+    };
+  });
+}

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/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

@@ -7,6 +7,7 @@
  *
  *   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.
  */
@@ -34,6 +35,8 @@ export interface MediaSettleOptions extends CommonOptions {
   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.
@@ -54,6 +57,7 @@ export function mediaSettle(target: TargetLike, options: MediaSettleOptions = {}
     mode = "scroll",
     start = "top 75%",
     end = "bottom top",
+    replay = false,
     scrub,
   } = options;
 
@@ -79,7 +83,9 @@ export function mediaSettle(target: TargetLike, options: MediaSettleOptions = {}
       vars.duration = duration;
       vars.ease = ease;
       if (mode === "scroll") {
-        vars.scrollTrigger = { trigger: els[0], start, once: true };
+        vars.scrollTrigger = replay
+          ? { trigger: els[0], start, toggleActions: "play reverse play reverse" }
+          : { trigger: els[0], start, once: true };
       }
     }
 

package/src/effects/preloader.ts

@@ -1,5 +1,5 @@
 /**
- * Preloader — the full-screen intro from dzinrstudio.com.
+ * Preloader — the full-screen intro from kalakritico.in.
  *
  * What it does on the real site:
  *   1. A big number counts 0 → 100 in the bottom-left corner (steps of 5,