@cosmictraveler002/anim-kit 1.0.0 → 1.2.0

package/src/effects/unfold-reveal.ts

@@ -0,0 +1,92 @@
+/**
+ * Unfold reveal — blocks that grow open from an edge.
+ *
+ * `scaleY: 0 → 1` from the top (or bottom) edge for a vertical unfold,
+ * `scaleX: 0 → 1` from the left for a horizontal one — the staggered block
+ * grow-in used for labels, headings and buttons as a section enters.
+ *
+ *   unfoldReveal("[data-unfold]", { axis: "y", origin: "top" });
+ *   unfoldReveal("[data-unfold-x]", { axis: "x", origin: "left" });
+ *
+ * Targets stagger together off the first match's trigger. destroy() kills the
+ * tween and clears the transform, so elements rest exactly as authored.
+ */
+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 UnfoldRevealOptions extends CommonOptions {
+  /** Which axis grows open. @default "y" */
+  axis?: "y" | "x";
+  /** transformOrigin — defaults to "top" (y) / "left" (x). */
+  origin?: string;
+  /** Animation duration, seconds. @default 0.7 */
+  duration?: number;
+  /** GSAP ease. @default "power3.out" */
+  ease?: string;
+  /** Stagger between targets, seconds. @default 0.08 */
+  stagger?: number;
+  /** Delay before playing, seconds. @default 0 */
+  delay?: number;
+  /** "scroll" plays on enter, "immediate" plays at once. @default "scroll" */
+  mode?: "scroll" | "immediate";
+  /** ScrollTrigger start position. @default "top 85%" */
+  start?: string;
+  /** Re-unfold when leaving / re-entering the viewport. @default false */
+  replay?: boolean;
+}
+
+export function unfoldReveal(target: TargetLike, options: UnfoldRevealOptions = {}): Destroy {
+  initGSAP();
+
+  const {
+    axis = "y",
+    origin,
+    duration = 0.7,
+    ease = "power3.out",
+    stagger = 0.08,
+    delay = 0,
+    mode = "scroll",
+    start = "top 85%",
+    replay = false,
+  } = options;
+
+  const els = toArray<HTMLElement>(target);
+  if (!els.length) return () => {};
+
+  return guard(options, run);
+
+  function run(): Destroy {
+    const prop = axis === "x" ? "scaleX" : "scaleY";
+    const from = origin ?? (axis === "x" ? "left" : "top");
+
+    gsap.set(els, { [prop]: 0, transformOrigin: from });
+
+    const vars: gsap.TweenVars = {
+      [prop]: 1,
+      duration,
+      ease,
+      stagger,
+      delay,
+      overwrite: "auto",
+    };
+    if (mode === "scroll") {
+      vars.scrollTrigger = {
+        trigger: els[0],
+        start,
+        toggleActions: replay ? "play reverse play reverse" : "play none none none",
+      };
+    }
+
+    const tween = gsap.to(els, vars);
+    ScrollTrigger.refresh();
+
+    return () => {
+      tween.scrollTrigger?.kill();
+      tween.kill();
+      gsap.set(els, { clearProps: "transform,transformOrigin" });
+      ScrollTrigger.refresh();
+    };
+  }
+}

package/src/index.ts

@@ -7,26 +7,35 @@
  *   split()          text splitting with mask support
  *
  * Scroll effects:
- *   lineReveal()     masked staggered text reveal
+ *   lineReveal()     masked staggered text reveal (lines or chars)
  *   maskReveal()     inline overflow-hidden heading reveal
  *   revealRule()     line that draws to full width
+ *   unfoldReveal()   blocks that scale open from an edge
+ *   clipWipe()       clip-path inset wipe reveal
  *   parallax()       data-speed parallax
  *   horizontalScroll()   pinned horizontal gallery
  *   stackedCards() / stackedCardsPinned()   pinned card deck
  *   scatterText()    pinned horizontal band with per-char settle
  *   heroShrink()     media that scales down as it scrolls away
+ *   mediaSettle()    media that settles from a larger entrance scale
  *   navHide()        header that hides on scroll-down
  *   logoReveal()     SVG wordmark assembling letter by letter
  *
  * Infinite / loops:
  *   marquee()        dual-row constant-speed marquee
  *   dragStrip()      infinite draggable carousel with rotation
+ *   rollText()       rolling word rotator (seamless row loop)
+ *
+ * Text extras:
+ *   scrambleText()   decode / cipher reveal per character
+ *   flipWords()      words that glide between two layouts (FLIP)
  *
  * Micro-interactions:
  *   liquidButton()   SVG wave flood on hover
  *   underlineLink()  underline wipe on hover
  *   cursorFollower() spring-follow cursor tag
- *   counter()        tabular number ticker
+ *   magnetic()       elements that pull toward the pointer and spring back
+ *   counter()        tabular number ticker (timed or scroll-progress)
  *   audioBars()      equaliser visualiser
  *   themeReveal()    View Transitions circular wipe
  *   menuOverlay()    clip-path curtain menu
@@ -50,6 +59,12 @@ export type { LineRevealOptions } from "./effects/line-reveal.js";
 export { maskReveal, revealRule } from "./effects/mask-reveal.js";
 export type { MaskRevealOptions } from "./effects/mask-reveal.js";
 
+export { unfoldReveal } from "./effects/unfold-reveal.js";
+export type { UnfoldRevealOptions } from "./effects/unfold-reveal.js";
+
+export { clipWipe } from "./effects/clip-wipe.js";
+export type { ClipWipeOptions, ClipWipeFrom } from "./effects/clip-wipe.js";
+
 export { parallax } from "./effects/parallax.js";
 export type { ParallaxOptions } from "./effects/parallax.js";
 
@@ -65,6 +80,9 @@ export type { ScatterTextOptions } from "./effects/scatter-text.js";
 export { heroShrink } from "./effects/hero-shrink.js";
 export type { HeroShrinkOptions } from "./effects/hero-shrink.js";
 
+export { mediaSettle } from "./effects/media-settle.js";
+export type { MediaSettleOptions } from "./effects/media-settle.js";
+
 export { navHide } from "./effects/nav-hide.js";
 export type { NavHideOptions } from "./effects/nav-hide.js";
 
@@ -75,9 +93,19 @@ export type { LogoRevealOptions } from "./effects/logo-reveal.js";
 export { marquee } from "./effects/marquee.js";
 export type { MarqueeOptions } from "./effects/marquee.js";
 
+export { rollText } from "./effects/roll-text.js";
+export type { RollTextOptions } from "./effects/roll-text.js";
+
 export { dragStrip } from "./effects/drag-strip.js";
 export type { DragStripOptions } from "./effects/drag-strip.js";
 
+/* ---- text extras ---- */
+export { scrambleText } from "./effects/scramble-text.js";
+export type { ScrambleTextOptions } from "./effects/scramble-text.js";
+
+export { flipWords } from "./effects/flip-words.js";
+export type { FlipWordsOptions } from "./effects/flip-words.js";
+
 /* ---- micro-interactions ---- */
 export { liquidButton, underlineLink } from "./effects/liquid-button.js";
 export type { LiquidButtonOptions } from "./effects/liquid-button.js";
@@ -85,6 +113,9 @@ export type { LiquidButtonOptions } from "./effects/liquid-button.js";
 export { cursorFollower } from "./effects/cursor-follower.js";
 export type { CursorFollowerOptions } from "./effects/cursor-follower.js";
 
+export { magnetic } from "./effects/magnetic.js";
+export type { MagneticOptions } from "./effects/magnetic.js";
+
 export { counter, audioBars } from "./effects/counter.js";
 export type { CounterOptions, AudioBarsOptions, AudioBarsHandle } from "./effects/counter.js";
 

package/src/styles/anim-kit.css

@@ -43,6 +43,13 @@
   will-change: transform;
 }
 
+/* Per-char masks produced by lineReveal({ split: "chars" }) / split(). */
+.ak-char-mask {
+  display: inline-block;
+  overflow: clip;
+  vertical-align: bottom;
+}
+
 .ak-space {
   display: inline-block;
   white-space: pre;
@@ -197,6 +204,21 @@
   background: linear-gradient(to left, var(--ak-background, #fff) 0%, transparent 100%);
 }
 
+/* ------------------------------------------------------------------ */
+/* Rolling text (rollText)                                             */
+/* ------------------------------------------------------------------ */
+
+/* The effect measures a row, then sets the box height + overflow inline so
+   teardown can restore authored styles exactly. This is the authored base. */
+.ak-roll {
+  display: inline-block;
+  vertical-align: bottom;
+}
+
+.ak-roll__inner {
+  will-change: transform;
+}
+
 /* ------------------------------------------------------------------ */
 /* Drag strip                                                          */
 /* ------------------------------------------------------------------ */