Scroll reveal

1
/**
2
 * scroll-reveal: scroll triggered reveals driven by data attributes. Put them on
3
 * any element, text or not; no wrapper.
4
 *
5
 *   <link rel="stylesheet" href="/styles/scroll-reveal.css">  <!-- in the head -->
6
 *   <div data-reveal="fade-up">A card that fades up</div>
7
 *   <img data-reveal="zoom-in" src="..." alt="..." width="800" height="600">
8
 *   <h2 data-reveal="mask-up">Wiped in from the bottom edge, no GSAP</h2>
9
 *   <h2 data-reveal="mask-up" data-reveal-split="lines">Each line slides up behind its own mask</h2>
10
 *   <p data-reveal="fade-up" data-reveal-split="words">Words fade up in turn</p>
11
 *   <h2 data-reveal="scatter">Letters appear one by one, in a random order</h2>
12
 *   <script type="module">import "/scripts/scroll-reveal.ts";</script>
13
 *
14
 * Two paths behind one API:
15
 *   - Whole element (no split): CSS transitions in scroll-reveal.css, toggled by
16
 *     IntersectionObserver. GSAP is never loaded for these, masks included.
17
 *   - Split (data-reveal-split): GSAP SplitText and a timeline, loaded on
18
 *     demand from scroll-reveal-split.ts.
19
 *
20
 * By default a reveal replays in both scroll directions: it plays when the
21
 * element scrolls in from below or above, and resets only once it is fully off
22
 * screen, so the reset is never seen.
23
 *
24
 * Attributes:
25
 *   data-reveal            Effect. A base (fade, zoom-in, zoom-out, blur) plus an
26
 *                          optional direction (up, down, left, right, up-left,
27
 *                          up-right, down-left, down-right). Default fade-up.
28
 *                          Also scale, the mask-up / mask-down clip wipes, and
29
 *                          two letter effects that split into chars on their own:
30
 *                          scatter (letters appear in a random order) and flicker
31
 *                          (they blink on in a random order).
32
 *   data-reveal-split      lines, words or chars. Masks slide each piece behind
33
 *                          its own clip; without it a mask wipes the whole element.
34
 *   data-reveal-duration   Seconds. Default 0.8 (masks 1).
35
 *   data-reveal-delay      Seconds. Default 0.
36
 *   data-reveal-stagger    Seconds between pieces. Default lines 0.1, words 0.04, chars 0.015.
37
 *   data-reveal-order      Which piece goes first: start (default), end, center, edges, random.
38
 *   data-reveal-ease       Named easing, ease-out-quint by default (masks ease-out-expo).
39
 *                          The names work on both paths. A raw GSAP ease such as
40
 *                          "back.out(1.7)" also works, on the split path only.
41
 *   data-reveal-start      Percent of the viewport, from the bottom, before it plays. Default 15.
42
 *   data-reveal-once       Play once and never reset.
43
 *   data-reveal-id         Names the element in its events: scroll-reveal:in:<id>.
44
 *
45
 * Custom properties (beat the matching attribute): --reveal-distance,
46
 * --reveal-duration, --reveal-delay, --reveal-blur, --reveal-scale,
47
 * --reveal-zoom-in, --reveal-zoom-out, and --reveal-ease on the whole element path.
48
 *
49
 * Events, dispatched on the element and bubbling to document:
50
 *   scroll-reveal:in        the reveal played
51
 *   scroll-reveal:out       it reset, having scrolled fully off screen
52
 *   scroll-reveal:in:<id>   the same, for an element with data-reveal-id
53
 *
54
 * Elements added to the page later are picked up by a MutationObserver, so a
55
 * router, a CMS embed or a "load more" button needs no extra call. Everything
56
 * is set up on load and on astro:page-load, and torn down on astro:before-swap.
57
 * Honours prefers-reduced-motion: nothing is hidden or split.
58
 */
59

60
import { parseRevealOptions, wantsSplit, type RevealOptions } from "./scroll-reveal-effects";
61

62
export { registerRevealBase, registerRevealEffect, resolveEase } from "./scroll-reveal-effects";
63

64
type Cleanup = () => void;
65
type RevealState = "in" | "out";
66

67
const SELECTOR = "[data-reveal]";
68
const active = new Map<HTMLElement, Cleanup>();
69

70
let splitModule: Promise<typeof import("./scroll-reveal-split")> | undefined;
71

72
/* --------------------------------------------
73
Events
74
-------------------------------------------- */
75

76
const ids = new WeakMap<Element, string>();
77

78
/**
79
 * Dispatched on the element rather than on document, so a component can listen
80
 * to its own reveal. Bubbling means a document level listener still works.
81
 */
82
function notify(element: Element, state: RevealState) {
83
  const id = ids.get(element) ?? null;
84
  const detail = { id, element };
85
  const options = { detail, bubbles: true };
86

87
  element.dispatchEvent(new CustomEvent(`scroll-reveal:${state}`, options));
88
  if (id) element.dispatchEvent(new CustomEvent(`scroll-reveal:${state}:${id}`, options));
89
}
90

91
/* --------------------------------------------
92
Whole element path: shared observers
93
-------------------------------------------- */
94

95
const playObservers = new Map<number, IntersectionObserver>();
96
const onceElements = new WeakSet<Element>();
97
let resetObserver: IntersectionObserver | undefined;
98

99
function play(element: Element) {
100
  element.setAttribute("data-reveal-state", "in");
101
  if (onceElements.has(element)) unobserve(element);
102
  notify(element, "in");
103
}
104

105
/** One play observer per start value, so elements with the same trigger share it. */
106
function playObserver(start: number) {
107
  let observer = playObservers.get(start);
108
  if (!observer) {
109
    observer = new IntersectionObserver(
110
      (entries) => {
111
        for (const entry of entries) if (entry.isIntersecting) play(entry.target);
112
      },
113
      { rootMargin: `0px 0px -${start}% 0px` },
114
    );
115
    playObservers.set(start, observer);
116
  }
117
  return observer;
118
}
119

120
/** Resets only when fully outside the viewport, so the snap back is never visible. */
121
function getResetObserver() {
122
  resetObserver ??= new IntersectionObserver((entries) => {
123
    for (const entry of entries) {
124
      if (entry.isIntersecting) continue;
125
      // Only a reveal that actually played has something to reset, and only a
126
      // played one should announce itself.
127
      if (entry.target.getAttribute("data-reveal-state") !== "in") continue;
128
      entry.target.setAttribute("data-reveal-state", "out");
129
      notify(entry.target, "out");
130
    }
131
  });
132
  return resetObserver;
133
}
134

135
function unobserve(element: Element) {
136
  for (const observer of playObservers.values()) observer.unobserve(element);
137
  resetObserver?.unobserve(element);
138
}
139

140
function setupCss(element: HTMLElement, options: RevealOptions): Cleanup {
141
  // Attributes become private properties; scroll-reveal.css reads the public ones first.
142
  const { revealDuration, revealDelay } = element.dataset;
143
  if (revealDuration) element.style.setProperty("--_reveal-duration", `${options.duration}s`);
144
  if (revealDelay) element.style.setProperty("--_reveal-delay", `${options.delay}s`);
145

146
  // "out" is the hidden state without a transition, and ends the CSS failsafe.
147
  element.setAttribute("data-reveal-state", "out");
148
  if (options.once) onceElements.add(element);
149
  playObserver(options.start).observe(element);
150
  if (!options.once) getResetObserver().observe(element);
151

152
  return () => {
153
    unobserve(element);
154
    onceElements.delete(element);
155
    element.style.removeProperty("--_reveal-duration");
156
    element.style.removeProperty("--_reveal-delay");
157
    element.removeAttribute("data-reveal-state");
158
  };
159
}
160

161
/* --------------------------------------------
162
Split path: GSAP, loaded on first use
163
-------------------------------------------- */
164

165
function setupSplit(element: HTMLElement): Cleanup {
166
  let cancelled = false;
167
  let teardown: Cleanup | undefined;
168

169
  splitModule ??= import("./scroll-reveal-split");
170
  splitModule
171
    .then((module) => {
172
      if (cancelled) return;
173

174
      // Read here, once GSAP has loaded, rather than at setup. Loading takes at
175
      // least a fetch, so by now every effect the page's scripts register with
176
      // registerRevealBase is in place, whatever order those scripts ran in.
177
      const options = readOptions(element);
178
      if (options.id) ids.set(element, options.id);
179
      teardown = module.createSplitReveal(element, options, () => cancelled, notify);
180
    })
181
    .catch((error: unknown) => {
182
      // Show the content rather than leave it hidden until the CSS failsafe.
183
      element.setAttribute("data-reveal-state", "off");
184
      console.error("scroll-reveal: could not load GSAP.", error);
185
    });
186

187
  return () => {
188
    cancelled = true;
189
    teardown?.();
190
    element.removeAttribute("data-reveal-state");
191
  };
192
}
193

194
/* --------------------------------------------
195
Setting one element up
196
-------------------------------------------- */
197

198
function readProperty(styles: CSSStyleDeclaration, name: string) {
199
  return styles.getPropertyValue(name).trim();
200
}
201

202
function readOptions(element: HTMLElement): RevealOptions {
203
  const styles = getComputedStyle(element);
204
  return parseRevealOptions(element.dataset, {
205
    distance: readProperty(styles, "--reveal-distance"),
206
    duration: readProperty(styles, "--reveal-duration"),
207
    delay: readProperty(styles, "--reveal-delay"),
208
    blur: readProperty(styles, "--reveal-blur"),
209
    scale: readProperty(styles, "--reveal-scale"),
210
    zoomIn: readProperty(styles, "--reveal-zoom-in"),
211
    zoomOut: readProperty(styles, "--reveal-zoom-out"),
212
  });
213
}
214

215
function setup(element: HTMLElement): Cleanup {
216
  let teardown: Cleanup;
217

218
  if (wantsSplit(element.dataset)) {
219
    // Options are read once GSAP loads; see setupSplit.
220
    teardown = setupSplit(element);
221
  } else {
222
    const options = readOptions(element);
223
    if (options.id) ids.set(element, options.id);
224
    teardown = setupCss(element, options);
225
  }
226

227
  return () => {
228
    teardown();
229
    ids.delete(element);
230
  };
231
}
232

233
/* --------------------------------------------
234
Public API
235
-------------------------------------------- */
236

237
/**
238
 * Sets up every [data-reveal] in `root`, including `root` itself. Elements
239
 * already set up are left alone. The returned cleanup tears down every reveal
240
 * found in `root`, whoever set it up, and restores the original markup.
241
 */
242
export function initScrollReveal(root: ParentNode = document): Cleanup {
243
  const elements = [...root.querySelectorAll<HTMLElement>(SELECTOR)];
244
  if (root instanceof HTMLElement && root.matches(SELECTOR)) elements.unshift(root);
245

246
  const reduced = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
247

248
  for (const element of elements) {
249
    if (active.has(element)) continue;
250
    if (reduced) {
251
      element.setAttribute("data-reveal-state", "off");
252
      active.set(element, () => element.removeAttribute("data-reveal-state"));
253
      continue;
254
    }
255
    active.set(element, setup(element));
256
  }
257

258
  return () => {
259
    for (const element of elements) {
260
      active.get(element)?.();
261
      active.delete(element);
262
    }
263
  };
264
}
265

266
/**
267
 * Sets up anything new and forgets anything that has left the document. Called
268
 * for you by the MutationObserver; worth calling by hand only if you turned that
269
 * off, or moved elements about without adding or removing any.
270
 */
271
export function refreshScrollReveal() {
272
  // Elements removed without their cleanup running would otherwise sit in the
273
  // map for the life of the page, holding on to the detached node.
274
  for (const [element, cleanup] of active) {
275
    if (element.isConnected) continue;
276
    cleanup();
277
    active.delete(element);
278
  }
279

280
  initScrollReveal();
281
}
282

283
/** Tears every reveal down, wherever it was set up from. */
284
export function disableScrollReveal() {
285
  for (const [element, cleanup] of active) {
286
    cleanup();
287
    active.delete(element);
288
  }
289
}
290

291
/* --------------------------------------------
292
Page wiring
293
-------------------------------------------- */
294

295
if (typeof window !== "undefined") {
296
  let sweepHandle: number | undefined;
297
  let mutationObserver: MutationObserver | undefined;
298

299
  /**
300
   * One sweep per frame however many mutations arrive, so inserting a hundred
301
   * cards costs a single pass. Only childList is observed, so the attributes
302
   * and inline properties we set never trigger one.
303
   */
304
  const scheduleSweep = () => {
305
    if (sweepHandle !== undefined) return;
306
    sweepHandle = requestAnimationFrame(() => {
307
      sweepHandle = undefined;
308
      refreshScrollReveal();
309
    });
310
  };
311

312
  const start = () => {
313
    disableScrollReveal();
314
    initScrollReveal();
315

316
    mutationObserver ??= new MutationObserver(scheduleSweep);
317
    mutationObserver.observe(document.documentElement, { childList: true, subtree: true });
318
  };
319

320
  const stop = () => {
321
    if (sweepHandle !== undefined) cancelAnimationFrame(sweepHandle);
322
    sweepHandle = undefined;
323
    mutationObserver?.disconnect();
324
    disableScrollReveal();
325
  };
326

327
  if (document.readyState === "loading") {
328
    document.addEventListener("DOMContentLoaded", start, { once: true });
329
  } else {
330
    // A microtask, not a direct call. ES modules evaluate their imports first,
331
    // so a direct call would run before the module that imported this one. The
332
    // split path reads its effect later anyway, but choosing between the two
333
    // paths happens here, and a registered effect with its own `split` default
334
    // has to be known by then. The microtask runs once the import graph has
335
    // finished evaluating.
336
    queueMicrotask(start);
337
  }
338

339
  // Astro view transitions: the new page's elements need setting up, the old ones tearing down.
340
  document.addEventListener("astro:page-load", start);
341
  document.addEventListener("astro:before-swap", stop);
342
}

1
/**
2
 * The split path for scroll-reveal: GSAP SplitText and ScrollTrigger. Imported
3
 * on demand by scroll-reveal.ts, so pages with only whole element reveals never
4
 * download GSAP. Not meant to be imported directly.
5
 */
6

7
import { gsap } from "gsap";
8
import { ScrollTrigger } from "gsap/ScrollTrigger";
9
import { SplitText } from "gsap/SplitText";
10
import type { RevealOptions } from "./scroll-reveal-effects";
11

12
gsap.registerPlugin(ScrollTrigger, SplitText);
13

14
/*
15
 * The flicker effect's ease: on/off rather than a curve, so a piece blinks
16
 * three times, each blink longer than the last, then holds. Registered by name
17
 * so the effect table stays a plain string, and so data-reveal-ease="flicker"
18
 * works on any split effect. Each pair is when a blink starts and ends.
19
 */
20
const FLICKER: readonly (readonly [number, number])[] = [
21
  [0.08, 0.16],
22
  [0.3, 0.42],
23
  [0.56, 0.74],
24
  [0.86, 1],
25
];
26
gsap.registerEase("flicker", (progress) =>
27
  FLICKER.some(([on, off]) => progress >= on && progress <= off) ? 1 : 0,
28
);
29

30
/** Announces a reveal. Passed in by scroll-reveal.ts so both paths fire the same events. */
31
type Notify = (element: Element, state: "in" | "out") => void;
32

33
export function createSplitReveal(
34
  element: HTMLElement,
35
  options: RevealOptions,
36
  isCancelled: () => boolean,
37
  notify: Notify,
38
) {
39
  let split: SplitText | undefined;
40
  let timeline: gsap.core.Timeline | undefined;
41
  let triggers: ScrollTrigger[] = [];
42

43
  // Lives outside build() so a re-split does not announce a reveal that already
44
  // played: ScrollTrigger fires onEnter again when it refreshes into view.
45
  let played = false;
46

47
  const killAnimation = () => {
48
    for (const trigger of triggers) trigger.kill();
49
    triggers = [];
50
    timeline?.kill();
51
    timeline = undefined;
52
  };
53

54
  const build = (pieces: Element[]) => {
55
    // A re-split (width change) rebuilds against the new pieces; keep where it was.
56
    const progress = timeline?.progress() ?? 0;
57
    killAnimation();
58

59
    timeline = gsap.timeline({ paused: true }).fromTo(
60
      pieces,
61
      // x and y claim the transform outright, so a CSS transform is never folded in.
62
      { ...options.from },
63
      {
64
        ...options.to,
65
        duration: options.duration,
66
        delay: options.delay,
67
        ease: options.ease,
68
        stagger: { each: options.stagger, from: options.order },
69
      },
70
    );
71
    timeline.progress(progress);
72

73
    const tl = timeline;
74
    const once = options.once;
75

76
    // ScrollTrigger can run onEnter while create() is still returning, so the
77
    // trigger may not be assigned yet. Missing the kill only leaves a played
78
    // timeline observed, which replays nothing.
79
    let play: ScrollTrigger | undefined;
80

81
    const enter = () => {
82
      tl.play();
83
      if (!played) {
84
        played = true;
85
        notify(element, "in");
86
      }
87
      if (once) play?.kill();
88
    };
89

90
    play = ScrollTrigger.create({
91
      trigger: element,
92
      start: `top ${100 - options.start}%`,
93
      end: "bottom top",
94
      onEnter: enter,
95
      onEnterBack: enter,
96
    });
97
    triggers.push(play);
98

99
    if (!once) {
100
      const leave = () => {
101
        tl.pause(0);
102
        if (played) {
103
          played = false;
104
          notify(element, "out");
105
        }
106
      };
107

108
      // Fully off screen in either direction, so the reset is never visible.
109
      triggers.push(
110
        ScrollTrigger.create({
111
          trigger: element,
112
          start: "top bottom",
113
          end: "bottom top",
114
          onLeave: leave,
115
          onLeaveBack: leave,
116
        }),
117
      );
118
    }
119

120
    // The pieces carry the hidden state now (fromTo renders immediately), so the element can show.
121
    element.setAttribute("data-reveal-state", "ready");
122
  };
123

124
  // Splitting before the web font lands measures the fallback and wraps lines wrongly.
125
  document.fonts.ready.then(() => {
126
    if (isCancelled() || !element.isConnected) return;
127

128
    const type =
129
      options.split === "chars" ? "words,chars" : options.split === "lines" ? "lines" : "words";
130

131
    split = SplitText.create(element, {
132
      type,
133
      // Chars stay grouped in words, so a word never breaks across lines.
134
      mask: options.mask ? (options.split ?? undefined) : undefined,
135
      linesClass: "reveal-line",
136
      wordsClass: "reveal-word",
137
      charsClass: "reveal-char",
138
      // Re-splits when line wrapping changes. The timeline is rebuilt in onSplit
139
      // rather than returned, because its ScrollTriggers are managed here.
140
      autoSplit: options.split === "lines",
141
      onSplit: (self) => {
142
        const pieces =
143
          options.split === "chars"
144
            ? self.chars
145
            : options.split === "lines"
146
              ? self.lines
147
              : self.words;
148
        build(pieces);
149
      },
150
    });
151
  });
152

153
  return () => {
154
    killAnimation();
155
    split?.revert();
156
    split = undefined;
157
  };
158
}