@cosmictraveler002/anim-kit 1.0.0

package/src/effects/drag-strip.ts

@@ -0,0 +1,228 @@
+/**
+ * Drag strip — the grabbable, infinitely looping image carousel.
+ *
+ * Built on GSAP Draggable. Why it is shaped this way (audit notes):
+ *
+ * - **Single writer.** Draggable owns the track's X transform; the loop is a
+ *   `liveSnap` function Draggable itself calls on every move (and every frame
+ *   of an inertia throw). Nothing else writes X — the first version let a
+ *   0.5s `quickTo` fight Draggable's own transform, which stuttered between
+ *   wrapped and unwrapped positions. (Note: Draggable has no `modifiers`
+ *   option; `liveSnap` is the supported hook.)
+ * - **Seamless loop.** Folding positions is only invisible when the content
+ *   tiles: with `clone: true` (default) the strip duplicates itself until one
+ *   tile is at least as wide as the viewport, and the fold distance is always
+ *   a whole multiple of the tile width — the same trick `marquee()` uses.
+ *   Without cloning there is nothing to fold against, so the strip clamps at
+ *   the content edges instead (finite, but never a gap).
+ * - **Rotation on pull.** Children tilt against pointer *speed* (normalised to
+ *   a 60fps frame so mouse and touch event rates feel identical) and spring
+ *   back to 0 on release. Pointer movement is used rather than Draggable's
+ *   `deltaX`, because deltaX jumps by a full loop at the seam.
+ * - **Fidelity.** `destroy()` kills the Draggable and both rotation tweens,
+ *   removes cloned tiles (original markup back) and restores the inline
+ *   cursor/user-select/touch-action the effect had overwritten.
+ *
+ *   dragStrip(".ak-drag-track", { maxRotation: 60 })
+ *
+ * CSS: viewport `overflow: hidden`; track `display: flex; width: max-content;
+ * gap: 1rem; cursor: grab; user-select: none; touch-action: pan-y`.
+ */
+import { gsap, Draggable, 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 DragStripOptions extends CommonOptions {
+  /** Max rotation at full drag speed, degrees. @default 100 */
+  maxRotation?: number;
+  /** Rotation response — divisor on the normalised drag speed. @default 100 */
+  rotationScale?: number;
+  /** Spring-back duration on release, seconds. @default 1 */
+  settleDuration?: number;
+  /** Enable inertia after release (requires GSAP InertiaPlugin). @default false */
+  inertia?: boolean;
+  /** Duplicate content so the loop is seamless; `false` clamps instead. @default true */
+  clone?: boolean;
+  /** Items inside the strip that rotate. @default ":scope > *" */
+  item?: string;
+}
+
+export function dragStrip(target: TargetLike, options: DragStripOptions = {}): Destroy {
+  initGSAP();
+
+  const track = one<HTMLElement>(target);
+  if (!track) return () => {};
+
+  const {
+    maxRotation = 100,
+    rotationScale = 100,
+    settleDuration = 1,
+    inertia = false,
+    clone = true,
+    item = ":scope > *",
+  } = options;
+
+  return guard(options, () => {
+    const viewport = track.parentElement;
+    const prevStyle = {
+      cursor: track.style.cursor,
+      userSelect: track.style.userSelect,
+      touchAction: track.style.touchAction,
+    };
+
+    /* ---------------- tiling (seamless infinite) ---------------- */
+
+    const originalCount = track.children.length;
+    const originalNodes = Array.from(track.children);
+    const trackWidth = () => Math.max(track.scrollWidth, track.clientWidth);
+
+    let tile = originalCount > 0 ? trackWidth() : 0; // width of one copy
+    let viewportW = 1; // width of the scroll viewport (the parent)
+    let loop = 0; // fold distance — whole tiles, or 0 when nothing to fold
+    let pointerDown = false;
+    let throwing = false;
+
+    /** Clone a tile, stripping ids so duplicated markup stays valid. */
+    const cloneTile = () =>
+      originalNodes.map((node) => {
+        const copy = node.cloneNode(true);
+        if (copy instanceof Element) {
+          if (copy.id) copy.removeAttribute("id");
+          copy.querySelectorAll("[id]").forEach((el) => el.removeAttribute("id"));
+        }
+        return copy;
+      });
+
+    const measure = () => {
+      viewportW = Math.max(1, viewport?.clientWidth || track.clientWidth || 1);
+      if (tile > 0 && clone) {
+        // One tile must be ≥ the viewport, with a spare tile to fold into.
+        for (let i = 8; i > 0 && trackWidth() - tile < viewportW; i--) {
+          track.append(...cloneTile());
+        }
+      }
+      if (tile <= 0) {
+        loop = 0; // unmeasurable (hidden / jsdom) — drag without folding
+      } else if (clone) {
+        // Largest multiple of `tile` that still leaves room for the viewport.
+        loop = Math.max(0, Math.floor((trackWidth() - viewportW) / tile)) * tile;
+      } else {
+        // Finite mode: keep the content aligned, never an empty gap.
+        loop = Math.max(0, trackWidth() - viewportW);
+      }
+    };
+
+    const fold = (value: number) => {
+      if (loop <= 0) return value;
+      return clone
+        ? gsap.utils.wrap(-loop, 0, value)
+        : Math.max(-loop, Math.min(0, value));
+    };
+
+    /**
+     * Handed to Draggable as `liveSnap.x`. Folds while Draggable is driving
+     * the value (pointer down, or a throw in progress). InertiaPlugin parses
+     * its *end target* with both flags false — that value stays raw so the
+     * throw keeps its direction; syncXY folds every frame of the throw instead.
+     */
+    const foldWhenDriven = (value: number) =>
+      pointerDown || throwing ? fold(value) : value;
+
+    measure();
+
+    /* ---------------- rotation on pull ---------------- */
+
+    const items = toArray<HTMLElement>(item, track); // after cloning: tiles tilt too
+    gsap.set(items, { transformOrigin: "50% 100%" });
+
+    const followRotation = gsap.quickTo(items, "rotation", {
+      duration: 0.12,
+      ease: "power2.out",
+    });
+    const settleRotation = gsap.quickTo(items, "rotation", {
+      duration: settleDuration,
+      ease: "power3.out",
+    });
+
+    let lastPointerX = 0;
+    let lastMoveTime = 0;
+
+    /* ---------------- drag ---------------- */
+
+    track.style.cursor = "grab";
+    track.style.userSelect = "none";
+    track.style.touchAction = "pan-y";
+
+    const draggable = Draggable.create(track, {
+      type: "x",
+      dragClickables: true,
+      inertia,
+      liveSnap: { x: foldWhenDriven },
+      onPress() {
+        pointerDown = true;
+        throwing = false;
+        // A spring from the previous release has had its chance — start fresh.
+        if (settleRotation.tween.isActive()) settleRotation.tween.totalProgress(1);
+        lastPointerX = this.pointerX || 0;
+        lastMoveTime = performance.now();
+        track.style.cursor = "grabbing";
+      },
+      onDrag() {
+        const now = performance.now();
+        const dt = Math.min(64, Math.max(8, now - lastMoveTime));
+        const pointerX = this.pointerX || 0;
+        const dx = pointerX - lastPointerX;
+        lastPointerX = pointerX;
+        lastMoveTime = now;
+        // Pointer speed normalised to a 60fps frame → same feel for every
+        // event rate (mouse vs touch), unlike a raw per-event delta.
+        const speed = (dx / dt) * 16.667;
+        const rotation = gsap.utils.clamp(
+          -maxRotation,
+          maxRotation,
+          -(speed / rotationScale) * 100,
+        );
+        followRotation(rotation);
+      },
+      onRelease() {
+        pointerDown = false;
+        track.style.cursor = prevStyle.cursor || "grab";
+        // Hold the last tilt, then spring it back over settleDuration.
+        if (followRotation.tween.isActive()) followRotation.tween.totalProgress(1);
+        settleRotation(0);
+      },
+      onThrowUpdate: () => {
+        throwing = true; // from here on, liveSnap folds each frame
+      },
+      onThrowComplete: () => {
+        throwing = false;
+      },
+      // (throw interruption resets `throwing` on the next press)
+    })[0];
+
+    /* ---------------- resize ---------------- */
+
+    const onResize = () => {
+      const x = parseFloat(String(gsap.getProperty(track, "x") ?? 0)) || 0;
+      measure(); // widen if the viewport grew; never removes tiles
+      gsap.set(track, { x: fold(x) }); // re-fold into the new range
+    };
+    window.addEventListener("resize", onResize);
+
+    return () => {
+      window.removeEventListener("resize", onResize);
+      followRotation.tween.kill();
+      settleRotation.tween.kill();
+      draggable.kill();
+      // Restore the exact inline styles we overwrote (not clearProps:"all",
+      // which would also wipe the consumer's own inline styles).
+      track.style.cursor = prevStyle.cursor;
+      track.style.userSelect = prevStyle.userSelect;
+      track.style.touchAction = prevStyle.touchAction;
+      // Original markup back: drop cloned tiles, then clear our transforms.
+      while (track.children.length > originalCount) track.removeChild(track.lastElementChild!);
+      gsap.set([track, ...track.children], { clearProps: "transform,transformOrigin" });
+    };
+  });
+}

package/src/effects/hero-shrink.ts

@@ -0,0 +1,69 @@
+/**
+ * Hero shrink — the showreel video that scales down as you scroll away.
+ *
+ *   fromTo(el, { scale: 1, x: 0, y: 0 },
+ *              { x: 0, y: "49vh", scale: 0.23, force3D: true,
+ *                scrollTrigger: { trigger: el, start: "top top",
+ *                                 end: "bottom top", scrub: 1 } })
+ *
+ * The video stays full-bleed at the top of the page and shrinks toward the
+ * bottom-centre as the section scrolls past, with `scrub: 1` giving it that
+ * heavy, lagging feel.
+ */
+import { gsap, ScrollTrigger, initGSAP } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { one } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface HeroShrinkOptions extends CommonOptions {
+  /** How far down the element drifts, as a CSS length. @default "49vh" */
+  offsetY?: string;
+  /** Final scale. @default 0.23 */
+  scale?: number;
+  /** Scrub smoothing — higher = laggier. @default 1 */
+  scrub?: number;
+  start?: string;
+  end?: string;
+  /** Shift on X at the end. @default 0 */
+  offsetX?: string;
+}
+
+export function heroShrink(target: TargetLike, options: HeroShrinkOptions = {}): Destroy {
+  initGSAP();
+
+  const el = one<HTMLElement>(target);
+  if (!el) return () => {};
+
+  const {
+    offsetY = "49vh",
+    offsetX = "0px",
+    scale = 0.23,
+    scrub = 1,
+    start = "top top",
+    end = "bottom top",
+  } = options;
+
+  return guard(options, () => {
+    const tween = gsap.fromTo(
+      el,
+      { scale: 1, x: 0, y: 0 },
+      {
+        x: offsetX,
+        y: offsetY,
+        scale,
+        force3D: true,
+        ease: "none",
+        scrollTrigger: { trigger: el, start, end, scrub },
+      },
+    );
+
+    ScrollTrigger.refresh();
+
+    return () => {
+      tween.scrollTrigger?.kill();
+      tween.kill();
+      gsap.set(el, { clearProps: "transform" });
+      ScrollTrigger.refresh();
+    };
+  });
+}

package/src/effects/horizontal-scroll.ts

@@ -0,0 +1,123 @@
+/**
+ * Pinned horizontal scroll — the "our work" gallery.
+ *
+ * A tall section is pinned while an inner track slides left; images inside
+ * each panel get a secondary parallax driven by `containerAnimation`, so they
+ * settle as they cross the viewport *horizontally* rather than vertically.
+ *
+ *   horizontalScroll(section, track, { panelImage: "img" })
+ *
+ * DOM contract:
+ *   <section>            ← pinned (trigger)
+ *     <div class="track">← translated on X (track)
+ *       <div class="panel">…<img>…</div> × N
+ */
+import { gsap, ScrollTrigger, initGSAP } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { one } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface HorizontalScrollOptions extends CommonOptions {
+  /** Pinned section (trigger). Defaults to the first argument's parent. */
+  section?: TargetLike;
+  /** Selector for images inside panels that get extra parallax. */
+  panelImage?: string | null;
+  /** Scrub smoothing for the horizontal movement. @default 0.5 */
+  scrub?: number;
+  /** Scrub smoothing for the image parallax. @default 0.2 */
+  imageScrub?: number;
+  /** Final X for the track; defaults to `track.scrollWidth - innerWidth`. */
+  travel?: () => number;
+  /** Kill ScrollTriggers created for the images. @default true */
+  imageParallax?: boolean;
+}
+
+export function horizontalScroll(
+  target: TargetLike,
+  options: HorizontalScrollOptions = {},
+): Destroy {
+  initGSAP();
+
+  const track = one<HTMLElement>(target);
+  if (!track) return () => {};
+
+  const section =
+    (options.section ? one<HTMLElement>(options.section) : null) ??
+    (track.closest("section") as HTMLElement | null) ??
+    track;
+
+  const {
+    scrub = 0.5,
+    imageScrub = 0.2,
+    panelImage = "img",
+    imageParallax = true,
+  } = options;
+
+  return guard(options, () => {
+    const travel = () =>
+      options.travel
+        ? options.travel()
+        : Math.max(0, track.scrollWidth - window.innerWidth);
+
+    const tweens: gsap.core.Tween[] = [];
+    const triggers: ScrollTrigger[] = [];
+
+    const main = gsap.to(track, {
+      x: () => -travel(),
+      ease: "none",
+      scrollTrigger: {
+        trigger: section,
+        pin: true,
+        scrub,
+        end: () => "+=" + travel(),
+        invalidateOnRefresh: true,
+        anticipatePin: 1,
+      },
+    });
+    tweens.push(main);
+    if (main.scrollTrigger) triggers.push(main.scrollTrigger);
+
+    if (imageParallax && panelImage) {
+      const images = gsap.utils.toArray<HTMLElement>(panelImage, track);
+      images.forEach((img) => {
+        const t = gsap.fromTo(
+          img,
+          { scale: 0.9, yPercent: 30 },
+          {
+            scale: 1,
+            yPercent: 0,
+            ease: "power4.out",
+            scrollTrigger: {
+              trigger: img,
+              containerAnimation: main,
+              start: "left 100%",
+              end: "left 20%",
+              scrub: imageScrub,
+            },
+          },
+        );
+        tweens.push(t);
+        if (t.scrollTrigger) triggers.push(t.scrollTrigger);
+      });
+    }
+
+    // Late-loading images change track width — refresh once they land.
+    const onLoad = () => ScrollTrigger.refresh();
+    const imgs = Array.from(track.querySelectorAll("img"));
+    imgs.forEach((img) => {
+      if (!img.complete) img.addEventListener("load", onLoad, { once: true });
+    });
+    window.addEventListener("load", onLoad);
+
+    ScrollTrigger.refresh();
+
+    return () => {
+      window.removeEventListener("load", onLoad);
+      imgs.forEach((img) => img.removeEventListener("load", onLoad));
+      triggers.forEach((t) => t.kill());
+      tweens.forEach((t) => t.kill());
+      gsap.set(track, { clearProps: "transform" });
+      ScrollTrigger.refresh();
+    };
+  });
+}

package/src/effects/line-reveal.ts

@@ -0,0 +1,109 @@
+/**
+ * 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%`.
+ *
+ * Two modes:
+ *   mode: "scroll"   → plays when the element enters the viewport and reverses
+ *                      when it leaves (`toggleActions: "play reverse play reverse"`,
+ *                      start `top 90%` / end `bottom 10%`) — their default.
+ *   mode: "immediate"→ plays right away (used above the fold with
+ *                      `animateOnScroll: false`).
+ */
+import { gsap, ScrollTrigger, initGSAP, EASES } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { split, type SplitResult } from "../core/split.js";
+import { toArray } from "../core/util.js";
+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 */
+  stagger?: number;
+  /** Animation duration, seconds. @default 1 */
+  duration?: number;
+  /** GSAP ease name. @default "power4.out" */
+  ease?: string;
+  /** Delay before playing, seconds. @default 0 */
+  delay?: number;
+  /** ScrollTrigger start position. @default "top 90%" */
+  start?: string;
+  /** ScrollTrigger end position. @default "bottom 10%" */
+  end?: string;
+}
+
+export function lineReveal(target: TargetLike, options: LineRevealOptions = {}): Destroy {
+  initGSAP();
+
+  const {
+    mode = "scroll",
+    stagger = 0.1,
+    duration = 1,
+    ease = "power4.out",
+    delay = 0,
+    start = "top 90%",
+    end = "bottom 10%",
+  } = options;
+
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  return guard(options, run);
+
+  function run(): Destroy {
+    const splits: SplitResult[] = [];
+    const tweens: gsap.core.Tween[] = [];
+
+    els.forEach((el) => {
+      const res = split(el, {
+        type: "lines",
+        mask: true,
+        linesClass: "ak-line++",
+        lineThreshold: 0.05,
+      });
+      splits.push(res);
+
+      // SplitText copies aria-labels onto the fragments; drop them for a11y.
+      el.querySelectorAll("[aria-label]").forEach((n) => n.removeAttribute("aria-label"));
+
+      if (!res.elements.length) return;
+
+      gsap.set(res.elements, { y: "100%" });
+
+      const vars: gsap.TweenVars = {
+        y: "0%",
+        duration,
+        stagger,
+        ease,
+        delay,
+        overwrite: "auto",
+      };
+
+      if (mode === "scroll") {
+        vars.scrollTrigger = {
+          trigger: el,
+          start,
+          end,
+          toggleActions: "play reverse play reverse",
+        };
+      }
+
+      tweens.push(gsap.to(res.elements, vars));
+    });
+
+    ScrollTrigger.refresh();
+
+    return () => {
+      tweens.forEach((t) => {
+        t.scrollTrigger?.kill();
+        t.kill();
+      });
+      splits.forEach((s) => s.revert());
+      ScrollTrigger.refresh();
+    };
+  }
+}
+
+export { EASES };

package/src/effects/liquid-button.ts

@@ -0,0 +1,75 @@
+/**
+ * Liquid button — the SVG wave that floods a button from the bottom on hover.
+ *
+ * Pure CSS/SVG geometry + a transition, exactly as the studio does it: an
+ * oversized (`160%`) SVG sits below the button and translates up on hover with
+ * a curved top edge, so the fill looks like liquid rising rather than a flat
+ * rectangle. Text colour cross-fades on top of it.
+ *
+ * Usage:
+ *   <button class="ak-liquid" data-ak-liquid>
+ *     <svg class="ak-liquid__wave" viewBox="0 0 100 100" preserveAspectRatio="none">
+ *       <path d="M0,30 Q50,-5 100,30 L100,100 L0,100 Z"/>
+ *     </svg>
+ *     <span class="ak-liquid__label">Lets Talk</span>
+ *   </button>
+ *
+ * This module just wires the custom properties (`--ak-liquid-duration`,
+ * `--ak-liquid-fill`) from JS options onto the markup, so a single stylesheet
+ * drives every instance.
+ */
+import { toArray } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface LiquidButtonOptions extends CommonOptions {
+  /** Wave travel time in ms. @default 900 */
+  duration?: number;
+  /** CSS colour for the wave fill. @default "var(--ak-primary, #6c5ce7)" */
+  fill?: string;
+  /** Which edge the liquid rises from. @default "up" */
+  direction?: "up" | "down";
+  /** Colour the label turns on hover. @default "#fff" */
+  labelColor?: string;
+}
+
+export function liquidButton(
+  target: TargetLike,
+  options: LiquidButtonOptions = {},
+): Destroy {
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  const {
+    duration = 900,
+    fill = "var(--ak-primary, #6c5ce7)",
+    direction = "up",
+    labelColor = "#fff",
+  } = options;
+
+  els.forEach((el) => {
+    el.dataset.akLiquid = direction;
+    el.style.setProperty("--ak-liquid-duration", `${duration}ms`);
+    el.style.setProperty("--ak-liquid-fill", fill);
+    el.style.setProperty("--ak-liquid-label", labelColor);
+  });
+
+  return () => {
+    els.forEach((el) => {
+      delete el.dataset.akLiquid;
+      el.style.removeProperty("--ak-liquid-duration");
+      el.style.removeProperty("--ak-liquid-fill");
+      el.style.removeProperty("--ak-liquid-label");
+    });
+  };
+}
+
+/**
+ * Underline sweep — the `after:` pseudo-element that wipes left→right on
+ * hover. Applied as a class so it works with zero JS; this helper exists so
+ * the same behaviour can be scoped programmatically.
+ */
+export function underlineLink(target: TargetLike): Destroy {
+  const els = toArray<HTMLElement>(target);
+  els.forEach((el) => el.classList.add("ak-underline"));
+  return () => els.forEach((el) => el.classList.remove("ak-underline"));
+}

package/src/effects/logo-reveal.ts

@@ -0,0 +1,76 @@
+/**
+ * Logo reveal — the DZ!NR wordmark that assembles letter by letter.
+ *
+ * Every path inside the SVG gets class `svg-anim-path`, is pre-set to
+ * `y:-100%, opacity:0`, then slides down into place with a 0.05s stagger when
+ * the mark scrolls into view (reversing back out when it leaves).
+ *
+ *   logoReveal(".logo svg")            ← animates [data-logo-path] children
+ *   logoReveal(el, { path: ".my-class" })
+ */
+import { gsap, ScrollTrigger, 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 LogoRevealOptions extends CommonOptions {
+  /** Selector for the animatable paths inside the SVG. @default "[data-logo-path], .svg-anim-path" */
+  path?: string;
+  /** Stagger between paths, seconds. @default 0.05 */
+  stagger?: number;
+  duration?: number;
+  ease?: string;
+  start?: string;
+  end?: string;
+  /** Play once and never reverse. @default false */
+  once?: boolean;
+}
+
+export function logoReveal(target: TargetLike, options: LogoRevealOptions = {}): Destroy {
+  initGSAP();
+
+  const el = one<HTMLElement>(target);
+  if (!el) return () => {};
+
+  const {
+    path = "[data-logo-path], .svg-anim-path",
+    stagger = 0.05,
+    duration = 1,
+    ease = "power2.out",
+    start = "top 80%",
+    end = "bottom top",
+    once = false,
+  } = options;
+
+  return guard(options, () => {
+    const paths = toArray<Element>(path, el);
+    if (!paths.length) return () => {};
+
+    gsap.set(paths, { yPercent: -100, opacity: 0, willChange: "transform" });
+
+    const tween = gsap.to(paths, {
+      yPercent: 0,
+      opacity: 1,
+      duration,
+      delay: 0,
+      ease,
+      stagger,
+      scrollTrigger: {
+        trigger: el,
+        start,
+        end,
+        once,
+        toggleActions: once ? undefined : "play reverse play reverse",
+      },
+    });
+
+    ScrollTrigger.refresh();
+
+    return () => {
+      tween.scrollTrigger?.kill();
+      tween.kill();
+      gsap.set(paths, { clearProps: "all" });
+      ScrollTrigger.refresh();
+    };
+  });
+}