@cosmictraveler002/anim-kit 1.2.0 → 1.3.0

package/src/effects/reel-text.ts

@@ -0,0 +1,212 @@
+/**
+ * Reel text — the per-character odometer roll.
+ *
+ * Every character gets its own overflow-hidden mask and a vertical strip of
+ * ghost glyphs stacked under the final one; the strips roll upward (staggered
+ * left→right) and land on the real text. This is the DOM twin of a shader
+ * slot-reel: character cells spun per glyph (`u_roll`/`u_spin` style), ported
+ * to plain GSAP so it needs no canvas. Why it is shaped this way:
+ *
+ * - **Built eagerly, rolled on trigger.** The masks exist as soon as the
+ *   effect mounts (so layout is stable and tests can see the structure); the
+ *   roll plays immediately or on scroll-enter. On completion the original
+ *   `innerHTML` is restored — screen readers and copy/paste see clean text —
+ *   and a `replay` re-entry re-splits from scratch. The ScrollTrigger is
+ *   registered **once per element**, outside the rebuild path, so replay
+ *   never stacks triggers.
+ * - **Width probed, never guessed.** Each wrapper's width is measured from
+ *   the *final* glyph (hidden probe in the body) so ghost frames of a
+ *   different width can't jitter the line while it spins. jsdom reports 0 —
+ *   the wrapper then shrink-wraps, which is why the unit smoke still passes.
+ * - **Same-case ghosts.** Uppercase rolls through the uppercase alphabet,
+ *   lowercase through lowercase, digits through digits — the line never
+ *   changes colour/shape mid-roll the way mixed-case ghosts would. Spaces and
+ *   punctuation stay as plain text (they don't spin).
+ * - **Fidelity.** `destroy()` kills the timeline + trigger, clears the stamp
+ *   and puts the original `innerHTML` back byte for byte.
+ *
+ *   reelText("[data-reel]", { mode: "scroll", frames: 4 })
+ *
+ * CSS: nothing required — masks, strip and frame heights are inline. Give the
+ * target the `line-height` you want the cells to inherit.
+ */
+import { gsap, ScrollTrigger, 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 ReelTextOptions extends CommonOptions {
+  /** `'immediate'` rolls on mount; `'scroll'` rolls on viewport enter. @default `"immediate"` */
+  mode?: "immediate" | "scroll";
+  /** ScrollTrigger start (only with `mode: "scroll"`). @default `"top 85%"` */
+  start?: string;
+  /** Ghost frames per character before the final glyph. @default 4 */
+  frames?: number;
+  /** Roll duration per character, seconds. @default 0.8 */
+  duration?: number;
+  /** Stagger between characters, seconds. @default 0.05 */
+  stagger?: number;
+  /** GSAP ease for the roll. @default `"power4.out"` */
+  ease?: string;
+  /** Re-arm on every scroll re-entry instead of playing once. @default false */
+  replay?: boolean;
+}
+
+interface Cell {
+  el: HTMLElement;
+  original: string;
+}
+
+const UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
+const DIGITS = "0123456789";
+
+/** Only alphanumerics get a reel; spaces/punctuation pass through untouched. */
+const spins = (ch: string) => /[A-Za-z0-9]/.test(ch);
+
+const ghostsFor = (ch: string, count: number): string => {
+  const pool = /[A-Z]/.test(ch) ? UPPERCASE : /[a-z]/.test(ch) ? LOWERCASE : DIGITS;
+  let out = "";
+  for (let i = 0; i < count; i++) out += pool[Math.floor(Math.random() * pool.length)];
+  return out;
+};
+
+/** Width of a glyph — 0 in jsdom, where wrappers may shrink-wrap instead. */
+const measureGlyph = (ch: string, sample: HTMLElement): number => {
+  const doc = sample.ownerDocument;
+  if (!doc.body) return 0;
+  const probe = doc.createElement("span");
+  probe.style.cssText = "position:absolute;visibility:hidden;white-space:pre;";
+  probe.textContent = ch;
+  doc.body.appendChild(probe);
+  const w = probe.getBoundingClientRect().width;
+  probe.remove();
+  return Math.round(w);
+};
+
+export function reelText(target: TargetLike, options: ReelTextOptions = {}): Destroy {
+  initGSAP();
+
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  const {
+    mode = "immediate",
+    start = "top 85%",
+    frames = 4,
+    duration = 0.8,
+    stagger = 0.05,
+    ease = "power4.out",
+    replay = false,
+  } = options;
+
+  return guard(options, () => {
+    const cells: Cell[] = [];
+    const timelines = new Map<HTMLElement, gsap.core.Timeline>();
+    const triggers: ScrollTrigger[] = [];
+
+    /** Unwind to the original markup (on completion and on destroy). */
+    const restore = (el: HTMLElement) => {
+      const i = cells.findIndex((c) => c.el === el);
+      if (i < 0) return;
+      el.innerHTML = cells[i].original;
+      delete el.dataset.akReel;
+      cells.splice(i, 1);
+    };
+
+    /**
+     * Split one element into masks + a paused roll timeline.
+     * Returns the timeline; the caller decides when (and whether) it plays.
+     */
+    const build = (el: HTMLElement): gsap.core.Timeline | null => {
+      const text = el.textContent ?? "";
+      if (!text.trim()) return null;
+
+      timelines.get(el)?.kill(); // a finished roll from a previous entry
+      // Keep the FIRST original: a second build must not snapshot masked HTML.
+      if (!cells.some((c) => c.el === el)) cells.push({ el, original: el.innerHTML });
+
+      const lineHeight =
+        parseFloat(getComputedStyle(el).lineHeight) || el.getBoundingClientRect().height || 16;
+
+      // Original markup → per-char segments (the element must be plain text).
+      el.textContent = "";
+      const strips: HTMLElement[] = [];
+      const ends: number[] = [];
+
+      for (const ch of [...text]) {
+        if (!spins(ch)) {
+          el.appendChild(el.ownerDocument.createTextNode(ch));
+          continue;
+        }
+        const wrapper = el.ownerDocument.createElement("span");
+        wrapper.className = "ak-reel__ch";
+        wrapper.style.cssText = `display:inline-block;overflow:hidden;vertical-align:top;height:${lineHeight}px;`;
+
+        const width = measureGlyph(ch, el);
+        if (width > 0) wrapper.style.width = `${width}px`;
+
+        const strip = el.ownerDocument.createElement("span");
+        strip.className = "ak-reel__strip";
+        strip.style.cssText = "display:flex;flex-direction:column;will-change:transform;";
+
+        for (const frame of ghostsFor(ch, frames) + ch) {
+          const frameEl = el.ownerDocument.createElement("span");
+          frameEl.style.cssText = `display:flex;align-items:center;justify-content:center;height:${lineHeight}px;flex:none;`;
+          frameEl.textContent = frame;
+          strip.appendChild(frameEl);
+        }
+
+        wrapper.appendChild(strip);
+        el.appendChild(wrapper);
+        strips.push(strip);
+        ends.push(-frames * lineHeight);
+      }
+
+      el.dataset.akReel = "true";
+
+      const tl = gsap.timeline({ paused: true, onComplete: () => restore(el) });
+      strips.forEach((strip, i) => {
+        tl.to(strip, { y: ends[i], duration, ease }, i * stagger);
+      });
+      timelines.set(el, tl);
+      return tl;
+    };
+
+    els.forEach((el) => {
+      const tl = build(el);
+      if (!tl) return;
+
+      if (mode === "immediate") {
+        tl.play(0);
+        return;
+      }
+
+      // Registered once per element — rebuilds on replay reuse this trigger.
+      triggers.push(
+        ScrollTrigger.create({
+          trigger: el,
+          start,
+          once: !replay,
+          onEnter: () => {
+            // Restored after the last roll (or never started) → rebuild first.
+            const active = el.dataset.akReel === "true" ? timelines.get(el) : build(el);
+            active?.play(0);
+          },
+        }),
+      );
+    });
+
+    return () => {
+      triggers.forEach((st) => st.kill());
+      triggers.length = 0;
+      timelines.forEach((tl) => tl.kill());
+      timelines.clear();
+      cells.slice().forEach((cell) => {
+        cell.el.innerHTML = cell.original;
+        delete cell.el.dataset.akReel;
+      });
+      cells.length = 0;
+    };
+  });
+}

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * anim-kit — modular animation library extracted from dzinrstudio.com.
+ * anim-kit — modular animation library by kalakritico.in.
  *
  * Core:
  *   smoothScroll()   Lenis + ScrollTrigger bridge (lerp 0.08)
@@ -24,10 +24,12 @@
  * Infinite / loops:
  *   marquee()        dual-row constant-speed marquee
  *   dragStrip()      infinite draggable carousel with rotation
+ *   dragRail()       bounded drag rail — inertia, tanh rubber-band, wheel
  *   rollText()       rolling word rotator (seamless row loop)
  *
  * Text extras:
  *   scrambleText()   decode / cipher reveal per character
+ *   reelText()       per-character odometer roll (masked reel strips)
  *   flipWords()      words that glide between two layouts (FLIP)
  *
  * Micro-interactions:
@@ -96,9 +98,15 @@ export type { MarqueeOptions } from "./effects/marquee.js";
 export { rollText } from "./effects/roll-text.js";
 export type { RollTextOptions } from "./effects/roll-text.js";
 
+export { reelText } from "./effects/reel-text.js";
+export type { ReelTextOptions } from "./effects/reel-text.js";
+
 export { dragStrip } from "./effects/drag-strip.js";
 export type { DragStripOptions } from "./effects/drag-strip.js";
 
+export { dragRail } from "./effects/drag-rail.js";
+export type { DragRailOptions } from "./effects/drag-rail.js";
+
 /* ---- text extras ---- */
 export { scrambleText } from "./effects/scramble-text.js";
 export type { ScrambleTextOptions } from "./effects/scramble-text.js";

package/src/three/index.ts

@@ -0,0 +1,12 @@
+/**
+ * `@cosmictraveler002/anim-kit/three` — the WebGL entry.
+ *
+ * Everything here renders media through **three.js**, which is an *optional
+ * peer dependency*: install `three` alongside anim-kit to use this subpath.
+ * The core barrel (`@cosmictraveler002/anim-kit`) never imports three, so
+ * plain DOM/scroll users keep a gsap+lenis-only dependency tree.
+ *
+ *   import { webglMedia } from "@cosmictraveler002/anim-kit/three";
+ */
+export { webglMedia } from "./webgl-media.js";
+export type { WebglMediaOptions } from "./webgl-media.js";

package/src/three/webgl-media.ts

@@ -0,0 +1,325 @@
+/**
+ * WebGL media — the shader card: a DOM `<img>` re-rendered as a rounded,
+ * hover-reactive GL plane.
+ *
+ * The image keeps owning layout and alt text; the effect paints it onto a
+ * canvas that covers the wrapper, so the card can do what CSS can't: press a
+ * *dent* into the picture on hover (sample squeeze + fake dome lighting),
+ * split its channels (chroma), and wipe in on reveal — all inside one
+ * fragment shader. This is the media-card pattern from three.js portfolios,
+ * kept dependency-honest:
+ *
+ * - **Optional peer.** Lives behind the `@cosmictraveler002/anim-kit/three`
+ *   subpath; the core barrel stays gsap+lenis only. `three` is an optional
+ *   peer — install it to use this entry, the core never imports it.
+ * - **Silent no-op ladder.** Missing target → no-op. No
+ *   `WebGLRenderingContext` (jsdom, SSR, WebGL-disabled browsers) → no-op
+ *   *before* a context is ever requested (a probe call would itself log).
+ *   Renderer construction throws → no-op. Texture 404s → the plain `<img>`
+ *   stays visible. Under `prefers-reduced-motion` the canvas never mounts.
+ * - **Cover crop in-shader.** The texture is sampled with `object-fit: cover`
+ *   maths (`scale = uRes / uTexSize`, windowed around the centre), so any
+ *   source aspect fills the card without letterboxing.
+ * - **Rounded corners are shader-true.** A rounded-box SDF with a 1px smooth
+ *   edge — not `border-radius` on the canvas — so the dent/chroma never bleed
+ *   into the corner.
+ * - **Fidelity.** `destroy()` kills ticker + tweens + observers/listeners,
+ *   disposes geometry/material/texture/renderer, removes the canvas and
+ *   restores the `<img>` opacity and wrapper position it changed.
+ *
+ *   webglMedia("[data-gl]", { corner: 18, dent: 70, chroma: 2 })
+ *
+ * Markup: a wrapper element containing `<img>` (or pass `src` explicitly):
+ *
+ *   <figure class="gl-card" data-gl><img src="photo.jpg" alt="" /></figure>
+ */
+import * as THREE from "three";
+import { gsap, 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 WebglMediaOptions extends CommonOptions {
+  /** Image source — defaults to the wrapper's first `<img>`. */
+  src?: string;
+  /** Corner radius, px. @default 16 */
+  corner?: number;
+  /** Dent depth pressed into the card on hover, px. @default 70 */
+  dent?: number;
+  /** Chromatic split at full hover, px. @default 2 */
+  chroma?: number;
+  /** Wipe the card in when its texture loads. @default true */
+  reveal?: boolean;
+  /** Reveal duration, seconds. @default 1.1 */
+  revealDuration?: number;
+  /** Hover response duration, seconds. @default 0.6 */
+  hoverDuration?: number;
+  /** Device-pixel-ratio cap. @default 2 */
+  dpr?: number;
+}
+
+const VERT = /* glsl */ `
+varying vec2 vUv;
+uniform float uHover;
+uniform float uDent;
+uniform float uTime;
+
+void main() {
+  vUv = uv;
+  vec3 p = position;
+  float dome = max(cos(uv.x * 3.14159265) * cos(uv.y * 3.14159265), 0.0);
+  dome *= 0.94 + 0.06 * sin(uTime * 1.6);
+  // Pressed-in curvature while hovered — the fragment does the visible work.
+  p.z -= uHover * uDent * dome;
+  gl_Position = projectionMatrix * modelViewMatrix * vec4(p, 1.0);
+}
+`;
+
+const FRAG = /* glsl */ `
+precision highp float;
+varying vec2 vUv;
+uniform sampler2D uTex;
+uniform vec2 uRes;
+uniform vec2 uTexSize;
+uniform float uCorner;
+uniform float uHover;
+uniform float uDent;
+uniform float uChroma;
+uniform float uProgress;
+uniform float uTime;
+
+float sdRoundBox(vec2 p, vec2 b, float r) {
+  vec2 q = abs(p) - b + r;
+  return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - r;
+}
+
+void main() {
+  vec2 px = (vUv - 0.5) * uRes;
+  float d = sdRoundBox(px, uRes * 0.5, uCorner);
+  float alpha = 1.0 - smoothstep(-1.0, 1.0, d); // 1px-ish AA on the corner
+
+  // Entrance wipe: grows from the bottom with a soft leading edge.
+  if (uProgress < 1.0) {
+    alpha *= 1.0 - smoothstep(uProgress - 0.05, uProgress, vUv.y);
+  }
+  if (alpha < 0.003) discard;
+
+  // object-fit: cover — window the texture around its centre.
+  vec2 scale = uRes / max(uTexSize, vec2(1.0));
+  vec2 cover = (vUv - 0.5) * (scale / max(scale.x, scale.y)) + 0.5;
+
+  // Hover dent: squeeze the sample toward the centre (breathing slightly).
+  vec2 c = cover - 0.5;
+  float dome = max(cos(vUv.x * 3.14159265) * cos(vUv.y * 3.14159265), 0.0);
+  dome *= 0.94 + 0.06 * sin(uTime * 1.6);
+  vec2 suv = 0.5 + c * (1.0 - uHover * uDent * 0.0016 * dome);
+
+  float chroma = uChroma * uHover * dome / max(uRes.x, 1.0);
+  vec3 col;
+  col.r = texture2D(uTex, suv + vec2(chroma, 0.0)).r;
+  col.g = texture2D(uTex, suv).g;
+  col.b = texture2D(uTex, suv - vec2(chroma, 0.0)).b;
+
+  // Fake lighting off the dome slope: sheen at the crest, shade at the rim.
+  float light = dome * uHover;
+  col += light * 0.12;
+  col *= 1.0 - 0.12 * uHover * (1.0 - dome);
+
+  gl_FragColor = vec4(col, alpha);
+}
+`;
+
+export function webglMedia(target: TargetLike, options: WebglMediaOptions = {}): Destroy {
+  initGSAP();
+
+  const host = one<HTMLElement>(target);
+  if (!host) return () => {};
+
+  const {
+    src,
+    corner = 16,
+    dent = 70,
+    chroma = 2,
+    reveal = true,
+    revealDuration = 1.1,
+    hoverDuration = 0.6,
+    dpr = 2,
+  } = options;
+
+  return guard(options, () => {
+    /* ---------------- availability ladder (silent, no probes) ---------------- */
+    if (typeof window === "undefined" || !("WebGLRenderingContext" in window)) return () => {};
+
+    let renderer: THREE.WebGLRenderer;
+    try {
+      renderer = new THREE.WebGLRenderer({ alpha: true, antialias: true });
+    } catch {
+      return () => {}; // context refused (disabled/blacklisted) — plain img stays
+    }
+
+    const img =
+      host.tagName === "IMG" ? null : (host.querySelector("img") as HTMLImageElement | null);
+    const textureSrc = src || img?.currentSrc || img?.src;
+    if (!textureSrc) {
+      renderer.dispose();
+      return () => {};
+    }
+
+    /* ---------------- layout + styles we must restore ---------------- */
+
+    const prevPosition = host.style.position;
+    if (!prevPosition && getComputedStyle(host).position === "static") {
+      host.style.position = "relative";
+    }
+    const prevImgOpacity = img?.style.opacity ?? "";
+    host.dataset.akGl = "true";
+
+    const w = Math.max(1, host.clientWidth);
+    const h = Math.max(1, host.clientHeight);
+
+    renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, dpr));
+    renderer.setSize(w, h, false);
+    const canvas = renderer.domElement;
+    canvas.style.cssText =
+      "position:absolute;inset:0;width:100%;height:100%;display:block;pointer-events:none;";
+
+    const scene = new THREE.Scene();
+    const camera = new THREE.OrthographicCamera(-w / 2, w / 2, h / 2, -h / 2, -100, 100);
+    camera.position.z = 10;
+
+    const geometry = new THREE.PlaneGeometry(1, 1, 1, 1);
+    const uniforms = {
+      uTex: { value: null as THREE.Texture | null },
+      uRes: { value: new THREE.Vector2(w, h) },
+      uTexSize: { value: new THREE.Vector2(1, 1) },
+      uCorner: { value: corner },
+      uHover: { value: 0 },
+      uDent: { value: dent },
+      uChroma: { value: chroma },
+      uProgress: { value: reveal ? 0 : 1 },
+      uTime: { value: 0 },
+    };
+    const material = new THREE.ShaderMaterial({
+      vertexShader: VERT,
+      fragmentShader: FRAG,
+      uniforms,
+      transparent: true,
+    });
+    const mesh = new THREE.Mesh(geometry, material);
+    mesh.scale.set(w, h, 1);
+    mesh.visible = false;
+    scene.add(mesh);
+    host.appendChild(canvas);
+
+    /* ---------------- texture ---------------- */
+
+    let disposed = false;
+    const loader = new THREE.TextureLoader();
+    let revealTween: gsap.core.Tween | null = null;
+
+    loader.load(
+      textureSrc,
+      (texture) => {
+        if (disposed) {
+          texture.dispose();
+          return;
+        }
+        texture.minFilter = THREE.LinearFilter;
+        texture.magFilter = THREE.LinearFilter;
+        // No sRGB decode: the raw shader passes sampled values through, so the
+        // texture must stay an ordinary RGBA8 upload (built-in colorSpace
+        // conversion only happens inside three's own material chunks).
+        uniforms.uTex.value = texture;
+        uniforms.uTexSize.value.set(texture.image.width || 1, texture.image.height || 1);
+        mesh.visible = true;
+        if (img) img.style.opacity = "0"; // canvas owns the pixels from here
+        if (reveal) {
+          revealTween = gsap.fromTo(
+            uniforms.uProgress,
+            { value: 0 },
+            { value: 1, duration: revealDuration, ease: "power2.inOut" },
+          );
+        }
+      },
+      undefined,
+      () => {
+        /* 404 / decode failure — the plain <img> was never hidden. */
+      },
+    );
+
+    /* ---------------- hover ---------------- */
+
+    let hoverTween: gsap.core.Tween | null = null;
+    const hoverTo = (value: number) => {
+      hoverTween = gsap.to(uniforms.uHover, {
+        value,
+        duration: hoverDuration,
+        ease: "power3.out",
+        overwrite: "auto",
+      });
+    };
+    const onEnter = () => hoverTo(1);
+    const onLeave = () => hoverTo(0);
+    host.addEventListener("pointerenter", onEnter);
+    host.addEventListener("pointerleave", onLeave);
+
+    /* ---------------- loop / observers ---------------- */
+
+    let visible = true;
+    let io: IntersectionObserver | null = null;
+    if (typeof IntersectionObserver === "function") {
+      io = new IntersectionObserver(([entry]) => (visible = entry.isIntersecting), {
+        rootMargin: "120px",
+      });
+      io.observe(host);
+    }
+
+    let ro: ResizeObserver | null = null;
+    const resize = () => {
+      const rw = Math.max(1, host.clientWidth);
+      const rh = Math.max(1, host.clientHeight);
+      renderer.setSize(rw, rh, false);
+      camera.left = -rw / 2;
+      camera.right = rw / 2;
+      camera.top = rh / 2;
+      camera.bottom = -rh / 2;
+      camera.updateProjectionMatrix();
+      mesh.scale.set(rw, rh, 1);
+      uniforms.uRes.value.set(rw, rh);
+    };
+    if (typeof ResizeObserver === "function") {
+      ro = new ResizeObserver(resize);
+      ro.observe(host);
+    }
+
+    const render = () => {
+      if (!visible || !mesh.visible) return;
+      uniforms.uTime.value = gsap.ticker.time;
+      renderer.render(scene, camera);
+    };
+    gsap.ticker.add(render);
+
+    /* ---------------- teardown ---------------- */
+
+    return () => {
+      disposed = true;
+      gsap.ticker.remove(render);
+      hoverTween?.kill();
+      revealTween?.kill();
+      gsap.killTweensOf(uniforms.uHover);
+      gsap.killTweensOf(uniforms.uProgress);
+      host.removeEventListener("pointerenter", onEnter);
+      host.removeEventListener("pointerleave", onLeave);
+      io?.disconnect();
+      ro?.disconnect();
+      uniforms.uTex.value?.dispose();
+      geometry.dispose();
+      material.dispose();
+      renderer.dispose();
+      canvas.remove();
+      delete host.dataset.akGl;
+      host.style.position = prevPosition;
+      if (img) img.style.opacity = prevImgOpacity;
+    };
+  });
+}