@cosmictraveler002/anim-kit 1.0.0

package/src/effects/preloader.ts

@@ -0,0 +1,187 @@
+/**
+ * Preloader — the full-screen intro from dzinrstudio.com.
+ *
+ * What it does on the real site:
+ *   1. A big number counts 0 → 100 in the bottom-left corner (steps of 5,
+ *      every 200ms — i.e. a 4s counter), sliding in from x:-100px.
+ *   2. An SVG "!" glyph is revealed bottom-up via `clip-path: inset(N% 0 0 0)`
+ *      driven by the same progress.
+ *   3. When the count hits 100 the glyph scales to 35x and fades out with the
+ *      `ak-preload-out` ease (delay 5s), then the backdrop fades (delay 5.5s).
+ *   4. The whole overlay unmounts ~1s later. A `sessionStorage` flag skips the
+ *      preloader on subsequent visits within the session.
+ */
+import { gsap, initGSAP, EASES, killTweens } from "../core/gsap.js";
+import { guard } from "../core/guard.js";
+import { one, prefersReducedMotion } from "../core/util.js";
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+
+export interface PreloaderOptions extends CommonOptions {
+  /** Root overlay element. */
+  root: string | HTMLElement;
+  /** The SVG glyph that fills up. Defaults to the first svg inside `root`. */
+  glyph?: string | HTMLElement;
+  /** Element receiving the 0→100 number. Defaults to first element with `[data-counter]`. */
+  counter?: string | HTMLElement;
+  /** Solid backdrop behind the glyph. Defaults to `[data-backdrop]`. */
+  backdrop?: string | HTMLElement;
+  /** Total counter duration in seconds. @default 4 */
+  duration?: number;
+  /** Counter increment per tick. @default 5 */
+  step?: number;
+  /** Interval between ticks in ms. @default 200 */
+  interval?: number;
+  /** Hide when already shown this session. @default true */
+  sessionGuard?: boolean;
+  /** sessionStorage key. @default "ak-preloader-shown" */
+  storageKey?: string;
+  /** Called once the overlay has finished and should be removed. */
+  onComplete?: () => void;
+}
+
+/**
+ * Intro preloader — 0→100 counter, glyph `inset()` fill, scale-out exit.
+ *
+ * Accepts the library's standard positional form **or** an options object:
+ *   preloader("#preloader", { duration: 4 })
+ *   preloader({ root: "#preloader", duration: 4 })
+ */
+export function preloader(options: PreloaderOptions): Destroy;
+export function preloader(target: TargetLike, options?: Partial<PreloaderOptions>): Destroy;
+export function preloader(
+  targetOrOptions: PreloaderOptions | TargetLike,
+  maybeOptions: Partial<PreloaderOptions> = {},
+): Destroy {
+  initGSAP();
+
+  const options: PreloaderOptions = isTargetArg(targetOrOptions)
+    ? { ...maybeOptions, root: (targetOrOptions ?? maybeOptions.root) as PreloaderOptions["root"] }
+    : targetOrOptions;
+
+  const {
+    duration = 4,
+    step = 5,
+    interval = 200,
+    sessionGuard = true,
+    storageKey = "ak-preloader-shown",
+    onComplete,
+  } = options;
+
+  const root = one(options.root);
+  if (!root) return () => {};
+  const overlay: HTMLElement = root;
+
+  const glyph = options.glyph ? one(options.glyph) : root.querySelector("svg");
+  const counterEl = options.counter
+    ? one(options.counter)
+    : root.querySelector<HTMLElement>("[data-counter]");
+  const backdrop = options.backdrop
+    ? one(options.backdrop)
+    : root.querySelector<HTMLElement>("[data-backdrop]");
+
+  if (sessionGuard && sessionStorage.getItem(storageKey)) {
+    overlay.style.display = "none";
+    onComplete?.();
+    return () => {};
+  }
+
+  // Reduced motion: never block the page behind a counting intro.
+  if (prefersReducedMotion() && !options.force) {
+    overlay.style.display = "none";
+    onComplete?.();
+    return () => {};
+  }
+
+  return guard(options, () => run());
+
+  function run(): Destroy {
+    const timers: number[] = [];
+    let value = 0;
+    let done = false;
+
+    // Entrance: number slides in from the left.
+    if (counterEl) {
+      gsap.fromTo(
+        counterEl,
+        { opacity: 0, x: -100 },
+        { opacity: 1, x: 0, duration: 0.5, ease: "power2.out" },
+      );
+    }
+
+    // Glyph fills bottom → top, tied to the counter.
+    if (glyph) {
+      gsap.set(glyph, { clipPath: "inset(100% 0px 0px 0px)" });
+      gsap.to(glyph, {
+        clipPath: "inset(0% 0px 0px 0px)",
+        duration,
+        ease: "power1.inOut",
+      });
+    }
+
+    const tick = () => {
+      value = Math.min(100, value + step);
+      if (counterEl) counterEl.textContent = String(value);
+      if (value >= 100) {
+        finish();
+        return;
+      }
+      timers.push(window.setTimeout(tick, interval));
+    };
+    timers.push(window.setTimeout(tick, interval));
+
+    function finish() {
+      if (done) return;
+      done = true;
+
+      const tl = gsap.timeline({
+        onComplete: () => {
+          sessionStorage.setItem(storageKey, "true");
+          overlay.style.display = "none";
+          onComplete?.();
+        },
+      });
+
+      // Glyph blows up and dissolves…
+      if (glyph) {
+        tl.to(
+          glyph,
+          {
+            scale: 35,
+            opacity: 0,
+            duration: 0.6,
+            ease: EASES.preloadOut,
+            transformOrigin: "center 50%",
+          },
+          1,
+        );
+      }
+      // …the number exits, …
+      if (counterEl) {
+        tl.to(counterEl, { opacity: 0, x: -40, duration: 0.35, ease: "power2.in" }, 1.15);
+      }
+      // …then the backdrop fades to reveal the page.
+      if (backdrop) {
+        tl.to(backdrop, { opacity: 0, duration: 0.5, ease: "power2.out" }, 1.5);
+      } else {
+        tl.to(root, { opacity: 0, duration: 0.5 }, 1.5);
+      }
+      tl.set(root, { pointerEvents: "none" }, 1.6);
+      tl.call(() => onComplete?.(), undefined, ">-0.1");
+    }
+
+    return () => {
+      timers.forEach(clearTimeout);
+      killTweens([root, glyph, counterEl, backdrop]);
+    };
+  }
+}
+
+/** Distinguish a positional DOM target from an options object. */
+function isTargetArg(v: PreloaderOptions | TargetLike): v is TargetLike {
+  if (typeof v === "string" || v == null) return true;
+  if (typeof v !== "object") return false;
+  if (Array.isArray(v)) return true;
+  const rec = v as unknown as Record<string, unknown>;
+  if ("nodeType" in rec) return true; // Element / Node
+  return typeof rec.length === "number" && "item" in rec; // NodeList
+}

package/src/effects/scatter-text.ts

@@ -0,0 +1,129 @@
+/**
+ * Scatter text — the giant "So, are you ready to Stand out?" band.
+ *
+ * The line is split into per-character spans, then pinned and scrolled
+ * horizontally. Every character carries a random initial `yPercent` (±60) and
+ * `rotation` (±15) and settles to zero as it crosses the viewport, driven by
+ * `containerAnimation` so the settle is tied to the *horizontal* scroll.
+ */
+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 ScatterTextOptions extends CommonOptions {
+  /** Element that holds the text and gets translated on X. */
+  line?: TargetLike;
+  /** Element pinned while the band scrolls. */
+  pinTarget?: TargetLike;
+  /** Split by "chars" (default) or "words". @default "chars" */
+  granularity?: "chars" | "words";
+  /** Max random vertical offset, in percent of the line height. @default 60 */
+  scatterY?: number;
+  /** Max random rotation, degrees. @default 15 */
+  scatterRotation?: number;
+  /** Scrub smoothing. @default 0.5 */
+  scrub?: number;
+  /** Per-character settle start/end as a fraction of the container. */
+  settleStart?: string;
+  settleEnd?: string;
+}
+
+export function scatterText(
+  target: TargetLike,
+  options: ScatterTextOptions = {},
+): Destroy {
+  initGSAP();
+
+  const wrap = one<HTMLElement>(target);
+  const line = (options.line ? one<HTMLElement>(options.line) : null) ?? wrap;
+  if (!wrap || !line) return () => {};
+
+  const pinTarget =
+    (options.pinTarget ? one<HTMLElement>(options.pinTarget) : null) ??
+    (wrap.querySelector<HTMLElement>("[data-pin]") ?? wrap);
+
+  const {
+    granularity = "chars",
+    scatterY = 60,
+    scatterRotation = 15,
+    scrub = 0.5,
+    settleStart = "left 100%",
+    settleEnd = "left 15%",
+  } = options;
+
+  return guard(options, () => {
+    const tweens: gsap.core.Tween[] = [];
+    const triggers: ScrollTrigger[] = [];
+    const text = line.textContent || "";
+
+    const build = () => {
+      // Split manually: spaces need a fixed-size slot so the band keeps flowing.
+      line.innerHTML = text
+        .split("")
+        .map((ch) =>
+          ch === " "
+            ? `<span class="ak-space"> </span>`
+            : granularity === "chars"
+              ? `<span class="ak-char">${ch}</span>`
+              : `<span class="ak-char">${ch}</span>`,
+        )
+        .join("");
+
+      const travel = () => Math.max(0, line.scrollWidth - window.innerWidth);
+
+      const master = gsap.to(line, {
+        x: () => -travel(),
+        ease: "none",
+        scrollTrigger: {
+          trigger: wrap,
+          pin: pinTarget,
+          scrub,
+          end: () => "+=" + travel(),
+          invalidateOnRefresh: true,
+          anticipatePin: 1,
+        },
+      });
+      tweens.push(master);
+      if (master.scrollTrigger) triggers.push(master.scrollTrigger);
+
+      const pieces = Array.from(line.querySelectorAll<HTMLElement>(".ak-char"));
+      pieces.forEach((piece) => {
+        const y = (Math.random() - 0.5) * scatterY;
+        const r = (Math.random() - 0.5) * scatterRotation;
+        const t = gsap.fromTo(
+          piece,
+          { yPercent: y, rotation: r },
+          {
+            yPercent: 0,
+            rotation: 0,
+            ease: "power2.out",
+            scrollTrigger: {
+              trigger: piece,
+              containerAnimation: master,
+              start: settleStart,
+              end: settleEnd,
+              scrub: 0.5,
+            },
+          },
+        );
+        tweens.push(t);
+        if (t.scrollTrigger) triggers.push(t.scrollTrigger);
+      });
+
+      ScrollTrigger.refresh();
+    };
+
+    // Measure only after webfonts land, or the travel distance is wrong.
+    if (document.fonts?.ready) document.fonts.ready.then(build).catch(build);
+    else build();
+
+    return () => {
+      triggers.forEach((t) => t.kill());
+      tweens.forEach((t) => t.kill());
+      line.textContent = text;
+      gsap.set(line, { clearProps: "transform" });
+      ScrollTrigger.refresh();
+    };
+  });
+}

package/src/effects/stacked-cards.ts

@@ -0,0 +1,154 @@
+/**
+ * Stacked cards — the pinned "services" deck.
+ *
+ * A tall wrapper scrolls normally while a sticky viewport holds still; cards
+ * inside are pre-offset below centre (`yPercent:50, y:innerHeight/2`) and a
+ * scrubbed timeline marches them up past centre with a stagger and the
+ * studio's `ak-card-stack` bezier.
+ *
+ * DOM contract:
+ *   <div class="ak-stack-wrap">      ← trigger, height e.g. 500vh
+ *     <div class="ak-stack-viewport">← pinned (pinSpacing:false)
+ *       <div class="ak-stack-cards"> ← the row of cards
+ *         …cards…
+ */
+import { gsap, ScrollTrigger, initGSAP, EASES } 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 StackedCardsOptions extends CommonOptions {
+  /** Tall scroll wrapper (trigger). */
+  wrap?: TargetLike;
+  /** Element that stays on screen. Defaults to `wrap`'s first child. */
+  viewport?: TargetLike;
+  /** Card selector scoped to the viewport. @default ".ak-card" */
+  card?: string;
+  /** Scrub smoothing. @default 0.5 */
+  scrub?: number;
+  /** Delay between cards, seconds. @default 0.12 */
+  stagger?: number;
+  /** The cascading ease. @default EASES.cardStack */
+  ease?: string;
+}
+
+export function stackedCards(
+  target: TargetLike,
+  options: StackedCardsOptions = {},
+): Destroy {
+  initGSAP();
+
+  const wrap = one<HTMLElement>(target);
+  if (!wrap) return () => {};
+
+  const viewport =
+    (options.viewport ? one<HTMLElement>(options.viewport) : null) ??
+    (wrap.firstElementChild as HTMLElement | null) ??
+    wrap;
+
+  const { scrub = 0.5, stagger = 0.12, card = ".ak-card", ease = EASES.cardStack } = options;
+
+  return guard(options, () => {
+    const cards = toArray<HTMLElement>(card, viewport);
+    if (!cards.length) return () => {};
+
+    const offset = () => window.innerHeight / 2;
+
+    // Cards start stacked below centre…
+    gsap.set(cards, { yPercent: 50, y: offset() });
+
+    const tl = gsap.timeline({
+      scrollTrigger: {
+        trigger: wrap,
+        start: "top top",
+        end: "bottom bottom",
+        scrub,
+        invalidateOnRefresh: true,
+      },
+    });
+
+    // …and are marched up past centre, one after another.
+    tl.to(
+      cards,
+      { yPercent: -50, y: () => -offset(), duration: 1, stagger, ease },
+      "step",
+    );
+
+    const st = tl.scrollTrigger;
+
+    ScrollTrigger.refresh();
+
+    return () => {
+      st?.kill();
+      tl.kill();
+      gsap.set(cards, { clearProps: "all" });
+      ScrollTrigger.refresh();
+    };
+  });
+}
+
+/**
+ * Variant used when the sticky viewport is a sibling rather than a child —
+ * pins `viewport` with `pinSpacing:false` over `wrap`'s scroll length.
+ */
+export function stackedCardsPinned(
+  wrapTarget: TargetLike,
+  options: StackedCardsOptions & { viewport: TargetLike } = { viewport: "" },
+): Destroy {
+  initGSAP();
+
+  const wrap = one<HTMLElement>(wrapTarget);
+  const viewport = one<HTMLElement>(options.viewport);
+  if (!wrap || !viewport) return () => {};
+
+  const { scrub = true, stagger = 0.1, card = ".ak-card", ease = EASES.cardStack } = options;
+
+  return guard(options, () => {
+    const cards = toArray<HTMLElement>(card, viewport);
+    if (!cards.length) return () => {};
+
+    gsap.set(cards, { yPercent: 50, y: window.innerHeight / 2 });
+
+    const pin = ScrollTrigger.create({
+      trigger: wrap,
+      start: "top top",
+      end: "bottom bottom",
+      pin: viewport,
+      pinSpacing: false,
+      anticipatePin: 1,
+      invalidateOnRefresh: true,
+    });
+
+    const tl = gsap.timeline({
+      scrollTrigger: {
+        trigger: wrap,
+        start: "top top",
+        end: "bottom bottom",
+        scrub,
+        invalidateOnRefresh: true,
+      },
+    });
+
+    tl.to(
+      cards,
+      {
+        yPercent: -50,
+        y: () => -window.innerHeight / 2,
+        duration: 1,
+        stagger,
+        ease,
+      },
+      0,
+    );
+
+    ScrollTrigger.refresh();
+
+    return () => {
+      pin.kill();
+      tl.scrollTrigger?.kill();
+      tl.kill();
+      gsap.set(cards, { clearProps: "all" });
+      ScrollTrigger.refresh();
+    };
+  });
+}

package/src/effects/theme-reveal.ts

@@ -0,0 +1,144 @@
+/**
+ * Theme reveal — circular clip-path wipe between light and dark.
+ *
+ * Uses the View Transitions API when available: `document.startViewTransition()`
+ * swaps the theme inside the callback while injected keyframes animate
+ * `::view-transition-new(root)` from `circle(0%)` to `circle(100%)`, centred on
+ * the button that was clicked. Falls back to an instant swap.
+ *
+ *   const theme = themeReveal({ toggle: "#theme-btn" });
+ *   theme.set("dark");      // wipes to dark
+ *   theme.toggle();         // flips and wipes
+ */
+import type { CommonOptions, Destroy, TargetLike } from "../core/types.js";
+import { one } from "../core/util.js";
+
+export type ThemeName = "light" | "dark";
+
+export interface ThemeRevealOptions extends CommonOptions {
+  /** Click target that triggers the wipe (usually the toggle button). */
+  toggle?: TargetLike;
+  /** Storage key for persistence. @default "ak-theme" */
+  storageKey?: string;
+  /** Initial theme; defaults to whatever is already on <html>. */
+  initial?: ThemeName;
+  /** Circle origin, e.g. "50% 50%" or an element to centre on. */
+  origin?: string | TargetLike;
+  /** Animation duration, seconds. @default 1 */
+  duration?: number;
+  onChange?: (theme: ThemeName) => void;
+}
+
+export interface ThemeRevealHandle {
+  set: (theme: ThemeName) => void;
+  toggle: () => void;
+  current: () => ThemeName;
+  destroy: Destroy;
+}
+
+const STYLE_ID = "ak-theme-reveal";
+
+export function themeReveal(options: ThemeRevealOptions = {}): ThemeRevealHandle {
+  const {
+    toggle,
+    storageKey = "ak-theme",
+    origin = "50% 50%",
+    duration = 1,
+    onChange,
+  } = options;
+
+  const root = document.documentElement;
+  const btn = toggle ? one<HTMLElement>(toggle) : null;
+
+  const stored = (() => {
+    try {
+      return sessionStorage.getItem(storageKey) as ThemeName | null;
+    } catch {
+      return null;
+    }
+  })();
+
+  let current: ThemeName =
+    options.initial ??
+    stored ??
+    ((root.classList.contains("dark") ? "dark" : "light") as ThemeName);
+
+  apply(current, false);
+
+  const onClick = () => set(current === "dark" ? "light" : "dark");
+  if (btn) btn.addEventListener("click", onClick);
+
+  function resolveOrigin(): string {
+    if (typeof origin === "string") return origin;
+    const el = origin ? one<HTMLElement>(origin) : btn;
+    if (!el) return "50% 50%";
+    const r = el.getBoundingClientRect();
+    return `${Math.round(r.left + r.width / 2)}px ${Math.round(r.top + r.height / 2)}px`;
+  }
+
+  function injectStyles(o: string) {
+    let style = document.getElementById(STYLE_ID);
+    if (!style) {
+      style = document.createElement("style");
+      style.id = STYLE_ID;
+      document.head.appendChild(style);
+    }
+    const t = `${duration}s`;
+    style.textContent = `
+      @supports (view-transition-name: root) {
+        ::view-transition-group(root) { animation-timing-function: cubic-bezier(0.76, 0, 0.24, 1); }
+        ::view-transition-old(root),
+        .dark::view-transition-old(root) { animation: none; z-index: -1; }
+        ::view-transition-new(root) {
+          animation: ak-theme-reveal ${t} cubic-bezier(0.76, 0, 0.24, 1);
+          clip-path: circle(0% at ${o});
+        }
+        @keyframes ak-theme-reveal {
+          from { clip-path: circle(0% at ${o}); }
+          to   { clip-path: circle(142% at ${o}); }
+        }
+      }`;
+  }
+
+  function apply(theme: ThemeName, animate: boolean) {
+    const commit = () => {
+      root.classList.toggle("dark", theme === "dark");
+      root.style.colorScheme = theme;
+      current = theme;
+      try {
+        sessionStorage.setItem(storageKey, theme);
+      } catch {
+        /* private mode */
+      }
+      onChange?.(theme);
+    };
+
+    const supported =
+      animate && !options.force && typeof document.startViewTransition === "function";
+
+    if (!supported) {
+      commit();
+      return;
+    }
+
+    injectStyles(resolveOrigin());
+    // startViewTransition returns a promise; ignore rejection on rapid toggles.
+    void document.startViewTransition(commit);
+  }
+
+  return {
+    set: (theme) => {
+      if (theme !== current) set(theme);
+    },
+    toggle: () => set(current === "dark" ? "light" : "dark"),
+    current: () => current,
+    destroy: () => {
+      if (btn) btn.removeEventListener("click", onClick);
+      document.getElementById(STYLE_ID)?.remove();
+    },
+  };
+
+  function set(theme: ThemeName) {
+    apply(theme, true);
+  }
+}