@cosmictraveler002/anim-kit 1.0.0

package/src/core/split.ts

@@ -0,0 +1,145 @@
+/**
+ * Text splitting utilities.
+ *
+ * anim-kit prefers GSAP's SplitText when it is available (it ships with the
+ * free GSAP package), but keeps a dependency-free fallback so the library
+ * still works if SplitText is ever tree-shaken out or unavailable.
+ */
+import { gsap, SplitText, initGSAP } from "./gsap.js";
+
+export type SplitType = "chars" | "words" | "lines";
+
+export interface SplitResult {
+  /** The elements that were produced (chars, words or lines). */
+  elements: HTMLElement[];
+  /** Undo the split and restore the original markup. */
+  revert: () => void;
+}
+
+export interface SplitOptions {
+  type: SplitType | Array<SplitType>;
+  /** Wrap each line in an overflow-hidden mask so it can slide up. */
+  mask?: boolean;
+  /** Class template for generated elements — `++` becomes the index. */
+  linesClass?: string;
+  wordsClass?: string;
+  charsClass?: string;
+  /** Ignore lines shorter than this fraction of the container. @default 0.05 */
+  lineThreshold?: number;
+}
+
+/**
+ * Split an element's text into chars/words/lines.
+ * Always returns a `revert()` that restores the original DOM.
+ */
+export function split(target: Element | string, options: SplitOptions): SplitResult {
+  initGSAP();
+
+  const el =
+    typeof target === "string"
+      ? (document.querySelector<HTMLElement>(target) ?? null)
+      : (target as HTMLElement);
+
+  if (!el) return { elements: [], revert: () => {} };
+
+  // Prefer SplitText: it handles nested markup, <br> and font metrics properly.
+  if (typeof SplitText !== "undefined" && SplitText?.create) {
+    try {
+      const st = SplitText.create(el, {
+        type: options.type,
+        mask: options.mask ? "lines" : undefined,
+        linesClass: options.linesClass ?? "ak-line++",
+        wordsClass: options.wordsClass ?? "ak-word++",
+        charsClass: options.charsClass ?? "ak-char++",
+        lineThreshold: options.lineThreshold ?? 0.05,
+      } as ConstructorParameters<typeof SplitText>[1]);
+
+      const elements = collect(st, options.type);
+      return {
+        elements,
+        revert: () => {
+          try {
+            st.revert();
+          } catch {
+            /* already reverted */
+          }
+        },
+      };
+    } catch {
+      /* fall through to the manual splitter */
+    }
+  }
+
+  return manualSplit(el, options);
+}
+
+function collect(st: SplitText, type: SplitType | SplitType[]): HTMLElement[] {
+  const wanted = Array.isArray(type) ? type : [type];
+  const out: HTMLElement[] = [];
+  if (wanted.includes("lines") && st.lines) out.push(...(st.lines as HTMLElement[]));
+  else if (wanted.includes("words") && st.words) out.push(...(st.words as HTMLElement[]));
+  else if (wanted.includes("chars") && st.chars) out.push(...(st.chars as HTMLElement[]));
+  return out;
+}
+
+/* ------------------------------------------------------------------ */
+/* Fallback: char / word splitting only (line detection is best-effort) */
+/* ------------------------------------------------------------------ */
+
+function manualSplit(el: HTMLElement, options: SplitOptions): SplitResult {
+  const original = el.innerHTML;
+  const type = Array.isArray(options.type) ? options.type[0] : options.type;
+  const nodes = Array.from(el.childNodes);
+
+  const generated: HTMLElement[] = [];
+
+  const wrap = (text: string, cls: string, i: number) => {
+    const span = document.createElement("span");
+    span.className = cls.replace("++", String(i));
+    span.textContent = text;
+    generated.push(span);
+    return span;
+  };
+
+  const frag = document.createDocumentFragment();
+  let index = 0;
+
+  for (const node of nodes) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      const text = node.textContent ?? "";
+      if (type === "chars") {
+        for (const ch of text) {
+          frag.appendChild(
+            ch === " "
+              ? document.createTextNode(" ")
+              : wrap(ch, options.charsClass ?? "ak-char++", index++),
+          );
+        }
+      } else {
+        const parts = text.split(/(\s+)/);
+        for (const part of parts) {
+          if (!part) continue;
+          if (/^\s+$/.test(part)) frag.appendChild(document.createTextNode(part));
+          else frag.appendChild(wrap(part, options.wordsClass ?? "ak-word++", index++));
+        }
+      }
+    } else if (node.nodeType === Node.ELEMENT_NODE) {
+      frag.appendChild(node.cloneNode(true));
+    }
+  }
+
+  el.innerHTML = "";
+  el.appendChild(frag);
+
+  if (options.mask) {
+    gsap.set(generated, { display: "inline-block" });
+  }
+
+  return {
+    elements: generated,
+    revert: () => {
+      el.innerHTML = original;
+      generated.length = 0;
+    },
+  };
+}

package/src/core/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared types for anim-kit.
+ *
+ * Every effect in this library follows the same contract:
+ *   effect(target, options) => destroy
+ * so effects can be composed, torn down and re-created safely.
+ */
+
+/** Anything that can be resolved to a list of elements. */
+export type TargetLike =
+  | string
+  | Element
+  | Element[]
+  | NodeListOf<Element>
+  | null
+  | undefined;
+
+/** Dispose function returned by every effect. */
+export type Destroy = () => void;
+
+export interface CommonOptions {
+  /**
+   * Run the effect even when the user has `prefers-reduced-motion: reduce`.
+   * @default false
+   */
+  force?: boolean;
+}
+
+/** The animation state an effect should snap to when motion is reduced. */
+export type ReducedState = Record<string, string | number>;

package/src/core/util.ts

@@ -0,0 +1,79 @@
+import type { Destroy, TargetLike } from "./types.js";
+
+/**
+ * Resolve a selector / element / list into a real array of elements.
+ *
+ * When `scope` is given, string targets are queried inside it — this is what
+ * lets effects take both `".card"` and `".card" within container`.
+ */
+export function toArray<T extends Element = HTMLElement>(
+  target: TargetLike,
+  scope?: ParentNode | null,
+): T[] {
+  if (!target) return [];
+  if (typeof target === "string") {
+    const root: ParentNode = scope ?? document;
+    return Array.from(root.querySelectorAll<T>(target));
+  }
+  if (target instanceof Element) return [target as T];
+  if (target instanceof NodeList || Array.isArray(target)) {
+    return Array.from(target) as T[];
+  }
+  return [];
+}
+
+/** Resolve to a single element, or null. */
+export function one<T extends Element = HTMLElement>(
+  target: TargetLike,
+  scope?: ParentNode | null,
+): T | null {
+  return toArray<T>(target, scope)[0] ?? null;
+}
+
+/** Run `fn` once the DOM is ready (no-op if it is already interactive/complete). */
+export function onReady(fn: () => void): void {
+  if (typeof document === "undefined") return;
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", fn, { once: true });
+  } else {
+    fn();
+  }
+}
+
+/** Compose several destroy functions into one. */
+export function compose(...fns: Array<Destroy | undefined | null>): Destroy {
+  return () => {
+    for (let i = fns.length - 1; i >= 0; i--) {
+      try {
+        fns[i]?.();
+      } catch {
+        /* destroying twice must never throw */
+      }
+    }
+  };
+}
+
+/** Schedule a callback on the next animation frame; returns a cancel fn. */
+export function raf(fn: () => void): () => void {
+  let id = 0;
+  let pending = false;
+  const run = () => {
+    pending = false;
+    fn();
+  };
+  const schedule = () => {
+    if (pending) return;
+    pending = true;
+    id = requestAnimationFrame(run);
+  };
+  schedule();
+  return () => cancelAnimationFrame(id);
+}
+
+/** Read the user's motion preference (safe outside the browser). */
+export function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return false;
+  }
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}

package/src/effects/counter.ts

@@ -0,0 +1,192 @@
+/**
+ * Counter — the big tabular-nums number that ticks up.
+ *
+ * Drives an element's `textContent` from `from` to `to` with an easing curve,
+ * optionally triggered by ScrollTrigger. Uses integer stepping so there is no
+ * fractional flicker, and pairs with `tabular-nums` for stable layout.
+ *
+ *   counter("[data-count]", { to: 100, duration: 4, ease: "power1.inOut" })
+ */
+import { gsap, ScrollTrigger, 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 CounterOptions extends CommonOptions {
+  /** Start value. @default 0 */
+  from?: number;
+  /** End value. @default 100 */
+  to?: number;
+  /** Duration in seconds. @default 4 */
+  duration?: number;
+  /** GSAP ease. @default "power1.inOut" */
+  ease?: string;
+  /** Pad with leading zeros to this width. @default 0 (no padding) */
+  pad?: number;
+  /** Suffix appended to the number, e.g. "+". @default "" */
+  suffix?: string;
+  /** Animate when scrolled into view instead of immediately. @default false */
+  onScroll?: boolean;
+  start?: string;
+  onComplete?: (value: number) => void;
+}
+
+export function counter(target: TargetLike, options: CounterOptions = {}): Destroy {
+  initGSAP();
+
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  const {
+    from = 0,
+    to = 100,
+    duration = 4,
+    ease = "power1.inOut",
+    pad = 0,
+    suffix = "",
+    onScroll = false,
+    start = "top 90%",
+    onComplete,
+  } = options;
+
+  return guard(options, run);
+
+  function run(): Destroy {
+    const tweens: gsap.core.Tween[] = [];
+
+    els.forEach((el) => {
+      const state = { v: from };
+      const render = () => {
+        const n = Math.round(state.v);
+        el.textContent = (pad ? String(n).padStart(pad, "0") : String(n)) + suffix;
+      };
+      render();
+
+      const vars: gsap.TweenVars = {
+        v: to,
+        duration,
+        ease,
+        onUpdate: render,
+        onComplete: () => {
+          render();
+          onComplete?.(Math.round(state.v));
+        },
+      };
+
+      if (onScroll) {
+        vars.scrollTrigger = { trigger: el, start, once: true };
+      }
+
+      tweens.push(gsap.to(state, vars));
+    });
+
+    if (onScroll) ScrollTrigger.refresh();
+
+    return () => {
+      tweens.forEach((t) => {
+        t.scrollTrigger?.kill();
+        t.kill();
+      });
+    };
+  }
+}
+
+/**
+ * Audio bars — the 5-bar equaliser inside the background-music button.
+ *
+ * Heights re-randomise on an interval and each bar springs to its new height,
+ * giving that loose, twitchy look. `stop()` collapses the bars back down.
+ *
+ *   const eq = audioBars(".ak-eq");
+ *   eq.start();          // on play
+ *   eq.stop();           // on pause
+ */
+export interface AudioBarsOptions extends CommonOptions {
+  /** Bars inside the container. @default ":scope > *" */
+  bar?: string;
+  /** Re-randomise interval in ms. @default 100 */
+  interval?: number;
+  /** Min bar height px. @default 4 */
+  minHeight?: number;
+  /** Max bar height px. @default 14 */
+  maxHeight?: number;
+  /**
+   * Spring feel, 0..1. Higher = bouncier. Used to pick the overshoot ease.
+   * @default 0.75
+   */
+  bounce?: number;
+}
+
+export interface AudioBarsHandle {
+  start: () => void;
+  stop: () => void;
+  destroy: Destroy;
+}
+
+export function audioBars(
+  target: TargetLike,
+  options: AudioBarsOptions = {},
+): AudioBarsHandle {
+  initGSAP();
+
+  const inert: AudioBarsHandle = { start: () => {}, stop: () => {}, destroy: () => {} };
+  const root = toArray<HTMLElement>(target)[0];
+  if (!root) return inert;
+
+  const {
+    bar = ":scope > *",
+    interval = 100,
+    minHeight = 4,
+    maxHeight = 14,
+    bounce = 0.75,
+  } = options;
+
+  const bars = toArray<HTMLElement>(bar, root);
+  if (!bars.length) return inert;
+
+  let timer = 0;
+
+  const start = () => {
+    if (timer) return;
+    randomise();
+    timer = window.setInterval(randomise, interval);
+  };
+
+  const stop = () => {
+    if (timer) window.clearInterval(timer);
+    timer = 0;
+    bars.forEach((b) =>
+      gsap.to(b, { height: minHeight, duration: 0.4, ease: "power2.out", overwrite: "auto" }),
+    );
+  };
+
+  const destroy = guard(options, () => {
+    gsap.set(bars, { height: minHeight, force3D: true });
+    start();
+    return () => {
+      if (timer) window.clearInterval(timer); // match window.setInterval in start()
+      timer = 0;
+      // Kill in-flight bar tweens first — otherwise their next frame would
+      // rewrite `height` *after* clearProps, mutating the DOM post-destroy.
+      // killTweens() (not killTweensOf) also catches batches created since
+      // the last ticker frame — those are still lazy and survive killTweensOf.
+      killTweens(bars);
+      gsap.set(bars, { clearProps: "height" });
+    };
+  });
+
+  return { start, stop, destroy };
+
+  function randomise() {
+    bars.forEach((b) => {
+      const v = Math.random() * 0.8 + 0.2;
+      gsap.to(b, {
+        height: Math.max(minHeight, maxHeight * v),
+        duration: 0.45,
+        // Underdamped springs overshoot; map the bounce option onto back.out.
+        ease: `back.out(${(bounce * 1.8).toFixed(2)})`,
+        overwrite: "auto",
+      });
+    });
+  }
+}

package/src/effects/cursor-follower.ts

@@ -0,0 +1,104 @@
+/**
+ * Cursor follower — the "Play Showreel" tag that trails the pointer.
+ *
+ * Two springs drive X and Y independently (mass 0.1, as on the site), and the
+ * whole thing fades/blurs in when the pointer enters the hot zone. The label
+ * uses `mix-blend-mode: exclusion` so it inverts over any background.
+ *
+ *   cursorFollower(zone, { follower: ".ak-cursor" })
+ */
+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 CursorFollowerOptions extends CommonOptions {
+  /** The floating element. Defaults to the first `[data-cursor]` in the document. */
+  follower?: TargetLike;
+  /** Offset added to the pointer position, px. @default 14 */
+  offset?: number;
+  /** Spring config for the follower. @default { mass: 0.1, stiffness: 120 } */
+  spring?: { mass?: number; stiffness?: number; damping?: number };
+  /** Blend mode applied to the follower. @default "exclusion" */
+  blendMode?: string;
+  /** Fade the follower in/out with the pointer. @default true */
+  fade?: boolean;
+}
+
+export function cursorFollower(
+  zone: TargetLike,
+  options: CursorFollowerOptions = {},
+): Destroy {
+  initGSAP();
+
+  const el =
+    (options.follower ? one<HTMLElement>(options.follower) : null) ??
+    document.querySelector<HTMLElement>("[data-cursor]");
+  const area = one<HTMLElement>(zone);
+
+  if (!el || !area) return () => {};
+
+  const { offset = 14, spring = { mass: 0.1, stiffness: 120 }, blendMode = "exclusion", fade = true } =
+    options;
+
+  return guard(options, () => {
+    const prevStyle = {
+      mixBlendMode: el.style.mixBlendMode,
+      position: el.style.position,
+      left: el.style.left,
+      top: el.style.top,
+      pointerEvents: el.style.pointerEvents,
+    };
+
+    el.style.mixBlendMode = blendMode as never;
+    el.style.position = "absolute";
+    el.style.left = "0";
+    el.style.top = "0";
+    el.style.pointerEvents = "none";
+
+    gsap.set(el, { opacity: fade ? 0 : 1, x: 0, y: 0 });
+
+    const xTo = gsap.quickTo(el, "x", { ...spring, duration: 0.4, ease: "power3" });
+    const yTo = gsap.quickTo(el, "y", { ...spring, duration: 0.4, ease: "power3" });
+
+    const onMove = (e: PointerEvent) => {
+      const r = area.getBoundingClientRect();
+      xTo(e.clientX - r.left + offset);
+      yTo(e.clientY - r.top + offset);
+      if (fade) gsap.to(el, { opacity: 1, duration: 0.25, overwrite: "auto" });
+    };
+
+    const onLeave = () => {
+      if (fade) gsap.to(el, { opacity: 0, duration: 0.25, overwrite: "auto" });
+    };
+
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Enter" || e.key === " ") {
+        /* host app handles activation; keep zone keyboard-reachable */
+      }
+    };
+
+    area.addEventListener("pointermove", onMove);
+    area.addEventListener("pointerleave", onLeave);
+    area.addEventListener("keydown", onKey);
+
+    return () => {
+      area.removeEventListener("pointermove", onMove);
+      area.removeEventListener("pointerleave", onLeave);
+      area.removeEventListener("keydown", onKey);
+      // quickTo tweens are paused at creation and would otherwise sit on the
+      // global timeline forever; fade tweens may still be in flight.
+      xTo.tween.kill();
+      yTo.tween.kill();
+      killTweens(el);
+      // Restore the inline styles we overwrote, clear only what gsap set
+      // (the old clearProps:"all" also wiped the consumer's own styles).
+      el.style.mixBlendMode = prevStyle.mixBlendMode;
+      el.style.position = prevStyle.position;
+      el.style.left = prevStyle.left;
+      el.style.top = prevStyle.top;
+      el.style.pointerEvents = prevStyle.pointerEvents;
+      gsap.set(el, { clearProps: "opacity,transform" });
+    };
+  });
+}