@cosmictraveler002/anim-kit 1.0.0

package/src/effects/marquee.ts

@@ -0,0 +1,157 @@
+/**
+ * Marquee — the infinite, dual-row client-logo band.
+ *
+ * Two rows scroll in opposite directions at a constant px/s using a single
+ * rAF loop. Each row's content is duplicated once; when the offset passes one
+ * copy's width it wraps by exactly that width, so the seam is invisible.
+ *
+ *   <div class="ak-marquee">
+ *     <div class="ak-marquee__viewport">
+ *       <div class="ak-marquee__track" data-dir="left">…items…</div>
+ *     </div>
+ *   </div>
+ *
+ * Call `marquee()` once per track, or pass a container with `[data-marquee]`.
+ */
+import { gsap, 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 MarqueeOptions extends CommonOptions {
+  /** Pixels per second. @default 40 (the studio's rate) */
+  speed?: number;
+  /** Force a direction for every track. Otherwise read `data-dir`. */
+  direction?: "left" | "right";
+  /** Duplicate the content automatically if it isn't already doubled. @default true */
+  clone?: boolean;
+  /** Pause the loop on pointer enter. @default false */
+  pauseOnHover?: boolean;
+}
+
+export function marquee(target: TargetLike, options: MarqueeOptions = {}): Destroy {
+  initGSAP();
+
+  const roots = toArray<HTMLElement>(target);
+  if (!roots.length) return () => {};
+
+  const { speed = 40, clone = true, pauseOnHover = false } = options;
+
+  return guard(options, () => {
+    const tracks: HTMLElement[] = [];
+    roots.forEach((root) => {
+      if (root.matches("[data-marquee-track]")) tracks.push(root);
+      else root.querySelectorAll<HTMLElement>("[data-marquee-track]").forEach((t) => tracks.push(t));
+    });
+
+    const states = tracks.map((track) => {
+      const originalCount = track.children.length;
+      if (clone) duplicateOnce(track);
+      const dir =
+        options.direction ?? (track.dataset.dir === "right" ? "right" : "left");
+      return {
+        track,
+        dir,
+        offset: 0,
+        width: 0,
+        hovering: false,
+        originalCount,
+        // Only OUR duplication gets removed on destroy — a consumer who
+        // pre-tiled the track (data-marquee-cloned) keeps their markup.
+        cloned: track.children.length > originalCount,
+      };
+    });
+
+    const measure = () => {
+      states.forEach((s) => {
+        s.width = measureCopy(s.track);
+        if (s.dir === "right" && s.offset === 0) s.offset = -s.width;
+      });
+    };
+
+    measure();
+
+    let last = performance.now();
+    let rafId = 0;
+    let running = true;
+
+    const loop = (now: number) => {
+      if (!running) return;
+      const dt = Math.min(64, now - last) / 1000;
+      last = now;
+
+      for (const s of states) {
+        if (!s.width) continue;
+        if (pauseOnHover && s.hovering) continue;
+        const delta = speed * dt * (s.dir === "right" ? 1 : -1);
+        s.offset += delta;
+        // Wrap by exactly one copy width — seamless.
+        if (s.offset <= -s.width) s.offset += s.width;
+        if (s.offset >= 0) s.offset -= s.width;
+        gsap.set(s.track, { x: s.offset });
+      }
+      rafId = requestAnimationFrame(loop);
+    };
+    rafId = requestAnimationFrame(loop);
+
+    const onResize = () => {
+      measure();
+    };
+    window.addEventListener("resize", onResize);
+
+    const cleanups: Array<() => void> = [];
+    if (pauseOnHover) {
+      states.forEach((s) => {
+        const enter = () => (s.hovering = true);
+        const leave = () => (s.hovering = false);
+        s.track.addEventListener("pointerenter", enter);
+        s.track.addEventListener("pointerleave", leave);
+        cleanups.push(() => {
+          s.track.removeEventListener("pointerenter", enter);
+          s.track.removeEventListener("pointerleave", leave);
+        });
+      });
+    }
+
+    return () => {
+      running = false;
+      cancelAnimationFrame(rafId);
+      window.removeEventListener("resize", onResize);
+      cleanups.forEach((fn) => fn());
+      states.forEach((s) => {
+        gsap.set(s.track, { clearProps: "transform" });
+        // Contract: destroy restores the original markup — drop our copy.
+        if (s.cloned) {
+          while (s.track.children.length > s.originalCount) {
+            s.track.removeChild(s.track.lastElementChild!);
+          }
+          delete s.track.dataset.marqueeCloned;
+        }
+      });
+    };
+  });
+}
+
+function duplicateOnce(track: HTMLElement): void {
+  if (track.dataset.marqueeCloned === "true") return;
+  const copy = track.innerHTML;
+  track.insertAdjacentHTML("beforeend", copy);
+  track.dataset.marqueeCloned = "true";
+}
+
+/** Width of a single copy of the track content, in px. */
+function measureCopy(track: HTMLElement): number {
+  if (track.dataset.marqueeCloned !== "true") return track.scrollWidth;
+  // Content was doubled, so one copy is half — but gaps can make it uneven,
+  // so measure the first half of the children instead.
+  const children = Array.from(track.children) as HTMLElement[];
+  if (!children.length) return track.scrollWidth / 2;
+  const half = Math.floor(children.length / 2);
+  let width = 0;
+  for (let i = 0; i < half; i++) {
+    const r = children[i].getBoundingClientRect();
+    const next = children[i + 1]?.getBoundingClientRect();
+    width += next ? next.left - r.left : r.width;
+  }
+  return width > 0 ? width : track.scrollWidth / 2;
+}

package/src/effects/mask-reveal.ts

@@ -0,0 +1,148 @@
+/**
+ * Mask reveal — the inline `overflow:hidden` + `y:100%` heading reveal.
+ *
+ * This is the studio's lighter alternative to `lineReveal`: you write
+ * `overflow-hidden` wrappers yourself and animate the inner spans.
+ *
+ *   <h1>
+ *     <span class="ak-mask"><span class="ak-mask__inner">Se</span></span>
+ *   </h1>
+ *
+ *   maskReveal("h1 .ak-mask__inner", { start: "top 90%" })
+ *
+ * On the site it runs at `duration:.5, ease:[.165,.84,.44,1]` (their `ak-reveal`)
+ * and the second line settles at `y:"-8%"` rather than 0 — configurable here.
+ */
+import { gsap, ScrollTrigger, initGSAP, EASES } 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 MaskRevealOptions extends CommonOptions {
+  /** Where the inner span starts. @default "100%" (fully below the mask) */
+  from?: string;
+  /** Where it settles. @default "0%" */
+  to?: string;
+  /** Duration, seconds. @default 0.5 */
+  duration?: number;
+  /** Ease name. @default EASES.reveal (".165,.84,.44,1") */
+  ease?: string;
+  /** Stagger across matched elements, seconds. @default 0.1 */
+  stagger?: number;
+  /** Delay before playing, seconds. @default 0 */
+  delay?: number;
+  /** ScrollTrigger start. @default "top 90%" */
+  start?: string;
+  /** ScrollTrigger end. @default "bottom 10%" */
+  end?: string;
+  /** "scroll" reverses on leave; "immediate" plays at once. @default "scroll" */
+  mode?: "scroll" | "immediate";
+}
+
+export function maskReveal(target: TargetLike, options: MaskRevealOptions = {}): Destroy {
+  initGSAP();
+
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  const {
+    from = "100%",
+    to = "0%",
+    duration = 0.5,
+    ease = EASES.reveal,
+    stagger = 0.1,
+    delay = 0,
+    start = "top 90%",
+    end = "bottom 10%",
+    mode = "scroll",
+  } = options;
+
+  return guard(options, run);
+
+  function run(): Destroy {
+    // Group by parent so siblings stagger together rather than individually.
+    const groups = new Map<Element, HTMLElement[]>();
+    els.forEach((el) => {
+      const parent = el.parentElement ?? el;
+      const list = groups.get(parent) ?? [];
+      list.push(el);
+      groups.set(parent, list);
+    });
+
+    const tweens: gsap.core.Tween[] = [];
+
+    gsap.set(els, { y: from });
+
+    groups.forEach((members) => {
+      const vars: gsap.TweenVars = {
+        y: to,
+        duration,
+        stagger,
+        delay,
+        ease,
+        overwrite: "auto",
+      };
+      if (mode === "scroll") {
+        vars.scrollTrigger = {
+          trigger: members[0].parentElement ?? members[0],
+          start,
+          end,
+          toggleActions: "play reverse play reverse",
+        };
+      }
+      tweens.push(gsap.to(members, vars));
+    });
+
+    ScrollTrigger.refresh();
+
+    return () => {
+      tweens.forEach((t) => {
+        t.scrollTrigger?.kill();
+        t.kill();
+      });
+      gsap.set(els, { clearProps: "transform" });
+      ScrollTrigger.refresh();
+    };
+  }
+}
+
+/**
+ * Rule reveal — the thin line that draws itself out to full width.
+ *
+ *   <div class="ak-rule"></div>
+ *   revealRule(".ak-rule")
+ *
+ * `initial:{width:0}` → `whileInView:{width:"100%"}`, duration 1s, same ease.
+ */
+export function revealRule(
+  target: TargetLike,
+  options: CommonOptions & { duration?: number; delay?: number; ease?: string } = {},
+): Destroy {
+  initGSAP();
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  const { duration = 1, delay = 0, ease = EASES.reveal } = options;
+
+  return guard(options, () => {
+    gsap.set(els, { width: 0 });
+    const tween = gsap.to(els, {
+      width: "100%",
+      duration,
+      delay,
+      ease,
+      stagger: 0.1,
+      scrollTrigger: {
+        trigger: els[0],
+        start: "top 92%",
+        toggleActions: "play none none reverse",
+      },
+    });
+
+    return () => {
+      tween.scrollTrigger?.kill();
+      tween.kill();
+      gsap.set(els, { clearProps: "width" });
+    };
+  });
+}

package/src/effects/menu-overlay.ts

@@ -0,0 +1,218 @@
+/**
+ * Menu overlay — the full-screen curtain menu.
+ *
+ * The panel is a `position:fixed` layer whose `clip-path` polygon animates
+ * between collapsed-at-bottom and fully-open, using the studio's `ak-curtain`
+ * ease (`.76,0,.2,1`). Menu links slide in/out of their own masks with a
+ * stagger, and the nav logo + toggle lift out of the way first.
+ *
+ *   menuOverlay({ overlay: ".menu-overlay", open: ".menu-toggle-open", close: … })
+ *
+ * Requires the markup contract in styles/anim-kit.css (`.menu-overlay`,
+ * `.menu-link`, `.menu-overlay-bar`).
+ */
+import { gsap, ScrollTrigger, initGSAP, EASES } from "../core/gsap.js";
+import { one, toArray, prefersReducedMotion } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface MenuOverlayOptions extends CommonOptions {
+  /** The fixed full-screen panel. */
+  overlay: TargetLike;
+  /** Element that opens the menu (or a boolean-ish toggle target). */
+  openTrigger?: TargetLike;
+  /** Element that closes the menu. */
+  closeTrigger?: TargetLike;
+  /** Nav bar that slides away while the menu is open. */
+  nav?: TargetLike;
+  /** Selector for the menu links inside `overlay`. @default ".menu-link a" */
+  link?: string;
+  /** Elements in the overlay chrome that rise into view. @default "[data-menu-chrome]" */
+  chrome?: string;
+  /** Duration of the curtain, seconds. @default 1 */
+  duration?: number;
+  /** Stagger between links, seconds. @default 0.1 */
+  stagger?: number;
+  /** Start open. @default false */
+  initialOpen?: boolean;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+
+export interface MenuOverlayHandle {
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  isOpen: () => boolean;
+  destroy: Destroy;
+}
+
+const COLLAPSED_BOTTOM = "polygon(0% 100%, 100% 100%, 100% 100%, 0% 100%)";
+const COLLAPSED_TOP = "polygon(0% 0%, 100% 0%, 100% 0%, 0% 0%)";
+const OPEN = "polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)";
+
+export function menuOverlay(
+  options: MenuOverlayOptions,
+): MenuOverlayHandle {
+  initGSAP();
+
+  const {
+    overlay: overlayTarget,
+    openTrigger,
+    closeTrigger,
+    nav: navTarget,
+    link = ".menu-link a",
+    chrome = "[data-menu-chrome]",
+    duration = 1,
+    stagger = 0.1,
+    initialOpen = false,
+    onOpen,
+    onClose,
+  } = options;
+
+  const noop = { open: () => {}, close: () => {}, toggle: () => {}, isOpen: () => false, destroy: () => {} };
+
+  const overlay = one<HTMLElement>(overlayTarget);
+  if (!overlay) return noop;
+
+  const nav = navTarget ? one<HTMLElement>(navTarget) : null;
+  const openBtns = toArray<HTMLElement>(openTrigger);
+  const closeBtns = toArray<HTMLElement>(closeTrigger);
+  const links = toArray<HTMLElement>(link, overlay);
+  const chromeEls = toArray<HTMLElement>(chrome, overlay);
+
+  // Reduced motion: leave the overlay collapsed and expose inert controls.
+  if (prefersReducedMotion() && !options.force) {
+    gsap.set(overlay, { clipPath: COLLAPSED_BOTTOM, pointerEvents: "none" });
+    return noop;
+  }
+
+  return setup();
+
+  function setup(): MenuOverlayHandle {
+    let open = initialOpen;
+    const ease = EASES.curtain;
+
+    // Initial state: curtain collapsed at the bottom edge, links waiting below.
+    gsap.set(overlay, {
+      clipPath: COLLAPSED_BOTTOM,
+      pointerEvents: "none",
+    });
+    if (links.length) gsap.set(links, { y: "100%" });
+    if (chromeEls.length) gsap.set(chromeEls, { y: 20 });
+
+    const tweens: gsap.core.Tween[] = [];
+
+    const openMenu = () => {
+      if (open) return;
+      open = true;
+      const tl = gsap.timeline({ onComplete: () => onOpen?.() });
+
+      // Curtain sweeps up to fill the viewport.
+      tl.to(overlay, {
+        clipPath: OPEN,
+        duration,
+        ease,
+        onStart: () => {
+          gsap.set(overlay, { pointerEvents: "all" });
+          if (nav) gsap.set(nav, { pointerEvents: "none" });
+        },
+      }, 0);
+
+      // Nav chrome lifts out of the way ahead of the curtain.
+      if (nav) {
+        const navBits = toArray<HTMLElement>("a, p", nav);
+        if (navBits.length) {
+          gsap.set(navBits, { y: 0 });
+          tl.to(navBits, { y: -20, duration, stagger, ease }, 0);
+        }
+      }
+
+      // Links slide up into place.
+      if (links.length) {
+        tl.fromTo(
+          links,
+          { y: "100%" },
+          { y: "0%", duration, stagger: stagger / 2, ease: "power3.out" },
+          duration * 0.5,
+        );
+      }
+      if (chromeEls.length) {
+        tl.to(chromeEls, { y: 0, duration, stagger, ease }, duration * 0.5);
+      }
+
+      tweens.push(tl as unknown as gsap.core.Tween);
+    };
+
+    const closeMenu = () => {
+      if (!open) return;
+      open = false;
+      const tl = gsap.timeline({ onComplete: () => onClose?.() });
+
+      if (chromeEls.length) {
+        tl.to(chromeEls, { y: -20, duration: duration * 0.75, stagger: stagger / 2, ease }, 0);
+      }
+      if (links.length) {
+        tl.to(links, {
+          y: "100%",
+          duration: duration * 0.75,
+          stagger: 0.05,
+          ease: "power4.in",
+        }, 0);
+      }
+
+      tl.to(
+        overlay,
+        {
+          clipPath: COLLAPSED_TOP,
+          duration,
+          delay: 0.5,
+          ease,
+          onComplete: () => {
+            gsap.set(overlay, { pointerEvents: "none" });
+            if (nav) gsap.set(nav, { pointerEvents: "all" });
+            // Reset for next open so the curtain always starts at the bottom.
+            gsap.set(overlay, { clipPath: COLLAPSED_BOTTOM });
+            if (links.length) gsap.set(links, { y: "100%" });
+            if (chromeEls.length) gsap.set(chromeEls, { y: 20 });
+          },
+        },
+        0,
+      );
+
+      if (nav) {
+        const navBits = toArray<HTMLElement>("a, p", nav);
+        if (navBits.length) tl.to(navBits, { y: 0, duration, stagger, ease }, duration * 0.5);
+      }
+
+      tweens.push(tl as unknown as gsap.core.Tween);
+    };
+
+    const toggle = () => (open ? closeMenu() : openMenu());
+
+    const listeners: Array<[HTMLElement, string, () => void]> = [];
+    openBtns.forEach((el) => {
+      el.addEventListener("click", openMenu);
+      listeners.push([el, "click", openMenu]);
+    });
+    closeBtns.forEach((el) => {
+      el.addEventListener("click", closeMenu);
+      listeners.push([el, "click", closeMenu]);
+    });
+
+    if (initialOpen) openMenu();
+
+    return {
+      open: openMenu,
+      close: closeMenu,
+      toggle,
+      isOpen: () => open,
+      destroy: () => {
+        listeners.forEach(([el, type, fn]) => el.removeEventListener(type, fn));
+        tweens.forEach((t) => t.kill());
+        gsap.set(overlay, { clearProps: "all" });
+        gsap.set([...links, ...chromeEls], { clearProps: "all" });
+        void ScrollTrigger;
+      },
+    };
+  }
+}

package/src/effects/nav-hide.ts

@@ -0,0 +1,90 @@
+/**
+ * Hide-on-scroll nav — the header that slides away when you scroll down and
+ * snaps back when you scroll up.
+ *
+ * Their exact rules:
+ *   - within `threshold` px of the top  → hide (slow, 1s power2.out)
+ *   - scrolling down                     → hide (fast, 0.3s)
+ *   - scrolling up                       → show  (fast, 0.3s)
+ * On viewports under 768px the nav is always visible.
+ */
+import { gsap, initGSAP, killTweens } 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 NavHideOptions extends CommonOptions {
+  /** Distance from the top under which the nav is hidden. @default 200 */
+  threshold?: number;
+  /** Hide offset in px. @default -100 */
+  hideY?: number;
+  /** Below this width the nav is pinned visible. @default 768 */
+  mobileBreakpoint?: number;
+  /** Start hidden. @default true */
+  startHidden?: boolean;
+}
+
+export function navHide(target: TargetLike, options: NavHideOptions = {}): Destroy {
+  initGSAP();
+
+  const nav = one<HTMLElement>(target);
+  if (!nav) return () => {};
+
+  const {
+    threshold = 200,
+    hideY = -100,
+    mobileBreakpoint = 768,
+    startHidden = true,
+  } = options;
+
+  return guard(options, () => {
+    let last = window.scrollY;
+    let visible = !startHidden;
+
+    const isMobile = () => window.innerWidth < mobileBreakpoint;
+
+    const setHidden = (hidden: boolean, duration: number) => {
+      if (hidden === !visible) return;
+      visible = !hidden;
+      gsap.to(nav, {
+        y: hidden ? hideY : 0,
+        duration,
+        ease: "power2.out",
+        overwrite: "auto",
+      });
+    };
+
+    // Initial placement — no animation, just the right resting state.
+    gsap.set(nav, { y: isMobile() || !startHidden ? 0 : hideY });
+    visible = !isMobile() && !startHidden ? true : startHidden ? false : true;
+
+    const onScroll = () => {
+      const y = window.scrollY;
+
+      if (isMobile()) {
+        setHidden(false, 0.3);
+      } else if (y <= threshold) {
+        // Near the top: park the nav out of the way.
+        if (visible) setHidden(true, 1);
+      } else if (y > last) {
+        setHidden(true, 0.3);
+      } else if (y < last) {
+        setHidden(false, 0.3);
+      }
+
+      last = y;
+    };
+
+    window.addEventListener("scroll", onScroll, { passive: true });
+    onScroll();
+
+    return () => {
+      window.removeEventListener("scroll", onScroll);
+      // A destroy() must not leave new work behind: kill any in-flight slide
+      // and drop the transform we own instead of tweening back (the old code
+      // started a fresh 0.3s tween *from* destroy, which also survived it).
+      killTweens(nav);
+      gsap.set(nav, { clearProps: "transform" });
+    };
+  });
+}

package/src/effects/parallax.ts

@@ -0,0 +1,68 @@
+/**
+ * Parallax — the studio's `data-speed` utility.
+ *
+ *   <img data-speed="-0.4" />
+ *
+ * Each matching element is tweened `yPercent: 50 * speed` across
+ * `start:"50% bottom"` → `end:"bottom top"` with `scrub:true`, so negative
+ * speeds drift up and positive speeds lag down. Pure `ease:"none"`.
+ */
+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 ParallaxOptions extends CommonOptions {
+  /** Attribute holding the speed multiplier. @default "data-speed" */
+  attribute?: string;
+  /** Multiplier applied to the attribute value. @default 50 */
+  scale?: number;
+  start?: string;
+  end?: string;
+}
+
+export function parallax(target: TargetLike, options: ParallaxOptions = {}): Destroy {
+  initGSAP();
+
+  const root = one<HTMLElement>(target);
+  if (!root) return () => {};
+
+  const {
+    attribute = "data-speed",
+    scale = 50,
+    start = "50% bottom",
+    end = "bottom top",
+  } = options;
+
+  return guard(options, () => {
+    const items: Array<{ el: HTMLElement; st?: ScrollTrigger }> = [];
+
+    root.querySelectorAll<HTMLElement>(`[${attribute}]`).forEach((el) => {
+      const raw = parseFloat(el.getAttribute(attribute) || "0");
+      if (Number.isNaN(raw)) return;
+      const speed = raw * scale;
+
+      const tw = gsap.to(el, {
+        yPercent: speed,
+        ease: "none",
+        scrollTrigger: { trigger: el, start, end, scrub: true },
+      });
+      items.push({ el, st: tw.scrollTrigger });
+      // Track tweens for cleanup via a WeakMap-free trick: kill through ST.
+      (el as unknown as Record<string, unknown>).__akParallax = tw;
+    });
+
+    ScrollTrigger.refresh();
+
+    return () => {
+      items.forEach(({ el, st }) => {
+        st?.kill();
+        const tw = (el as unknown as { __akParallax?: gsap.core.Tween }).__akParallax;
+        tw?.kill();
+        delete (el as unknown as Record<string, unknown>).__akParallax;
+        gsap.set(el, { clearProps: "transform" });
+      });
+      ScrollTrigger.refresh();
+    };
+  });
+}