sticky-scroll-trigger 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,694 @@
1
+ /*!
2
+ * @license
3
+ * StickyScrollTrigger v0.2.0
4
+ * Copyright (c) 2026 Kuninori Ogino
5
+ * Released under the MIT License
6
+ * https://github.com/kuninori-ogino/sticky-scroll-trigger
7
+ */
8
+ const resolveRoot = (root) => {
9
+ const el = typeof root === "string" ? document.querySelector(root) : root;
10
+ if (!el) {
11
+ const description = typeof root === "string" ? `"${root}"` : String(root);
12
+ throw new Error(`StickyScrollTrigger: root ${description} not found`);
13
+ }
14
+ return el;
15
+ };
16
+ const resolveElement = (value, context) => {
17
+ const el = typeof value === "string" ? document.querySelector(value) : value;
18
+ if (!el) {
19
+ const description = typeof value === "string" ? `"${value}"` : String(value);
20
+ throw new Error(`${context}: element ${description} not found`);
21
+ }
22
+ return el;
23
+ };
24
+ const resolveEndTrigger = (trigger, endTriggerInput, context) => endTriggerInput === void 0 ? trigger : resolveElement(endTriggerInput, context);
25
+ const describeElement = (el) => {
26
+ const id = el.id ? `#${el.id}` : "";
27
+ const cls = el.classList.length > 0 ? `.${Array.from(el.classList).join(".")}` : "";
28
+ return `<${el.tagName.toLowerCase()}${id}${cls}>`;
29
+ };
30
+ const documentTop = (el) => {
31
+ let top = 0;
32
+ let node = el;
33
+ while (node) {
34
+ top += node.offsetTop;
35
+ const parent = node.offsetParent;
36
+ if (parent) top += parent.clientTop;
37
+ node = parent;
38
+ }
39
+ return top;
40
+ };
41
+ const measureViewportHeight = () => {
42
+ const probe = document.createElement("div");
43
+ probe.style.height = "100vh";
44
+ probe.style.position = "absolute";
45
+ document.body.appendChild(probe);
46
+ const height = probe.offsetHeight || window.innerHeight;
47
+ probe.remove();
48
+ return height;
49
+ };
50
+ const measureDocumentMaxScroll = (viewportHeight) => {
51
+ const doc = document.documentElement;
52
+ return Math.max(0, (doc.scrollHeight || document.body.scrollHeight) - viewportHeight);
53
+ };
54
+ const compareDocumentOrder = (a, b) => {
55
+ const position = a.compareDocumentPosition(b);
56
+ if (position & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
57
+ if (position & Node.DOCUMENT_POSITION_PRECEDING) return 1;
58
+ return 0;
59
+ };
60
+ const resetStickyPosition = (el) => {
61
+ el.style.position = "";
62
+ el.style.top = "";
63
+ };
64
+ const applyStickyPosition = (el, topPx) => {
65
+ el.style.position = "sticky";
66
+ el.style.top = `${topPx}px`;
67
+ };
68
+ const wrapScene = (inner) => {
69
+ if (!inner.parentNode) throw new Error(`StickyScrollTrigger: ${describeElement(inner)} is not attached to the document`);
70
+ const container = document.createElement("div");
71
+ const wrapper = document.createElement("div");
72
+ const padding = document.createElement("div");
73
+ padding.setAttribute("aria-hidden", "true");
74
+ padding.style.pointerEvents = "none";
75
+ inner.parentNode.insertBefore(container, inner);
76
+ container.appendChild(wrapper);
77
+ wrapper.appendChild(inner);
78
+ container.appendChild(padding);
79
+ return {
80
+ container,
81
+ wrapper,
82
+ padding
83
+ };
84
+ };
85
+ const wrapCover = (trigger) => {
86
+ const parent = trigger.parentNode;
87
+ if (!parent) throw new Error(`createOverlapScroll: trigger ${describeElement(trigger)} is not attached to the document`);
88
+ const wrapper = document.createElement("div");
89
+ parent.insertBefore(wrapper, parent.firstChild);
90
+ while (wrapper.nextSibling) {
91
+ const node = wrapper.nextSibling;
92
+ wrapper.appendChild(node);
93
+ if (node === trigger) break;
94
+ }
95
+ return wrapper;
96
+ };
97
+ const unwrapCover = (wrapper) => {
98
+ const parent = wrapper.parentNode;
99
+ if (!parent) return;
100
+ while (wrapper.firstChild) parent.insertBefore(wrapper.firstChild, wrapper);
101
+ wrapper.remove();
102
+ };
103
+ const wrapPin = (trigger) => {
104
+ if (!trigger.parentNode) throw new Error(`createStickyPin: trigger ${describeElement(trigger)} is not attached to the document`);
105
+ const outer = document.createElement("div");
106
+ const inner = document.createElement("div");
107
+ outer.style.height = "0";
108
+ outer.style.contain = "layout";
109
+ trigger.parentNode.insertBefore(outer, trigger);
110
+ outer.appendChild(inner);
111
+ inner.appendChild(trigger);
112
+ return {
113
+ outer,
114
+ inner
115
+ };
116
+ };
117
+ const unwrapPin = (outer, trigger) => {
118
+ const parent = outer.parentNode;
119
+ resetStickyPosition(trigger);
120
+ if (parent) parent.insertBefore(trigger, outer);
121
+ outer.remove();
122
+ };
123
+ const liftStates = new WeakMap();
124
+ const liftAboveStickyWrapper = (cover) => {
125
+ const lifted = [];
126
+ for (let node = cover; node; node = node.nextElementSibling) {
127
+ if (!(node instanceof HTMLElement)) continue;
128
+ const existing = liftStates.get(node);
129
+ if (existing) existing.count += 1;
130
+ else {
131
+ const computed = getComputedStyle(node);
132
+ const state = {
133
+ count: 1,
134
+ position: node.style.position,
135
+ zIndex: node.style.zIndex
136
+ };
137
+ if (computed.position === "static") node.style.position = "relative";
138
+ if (computed.zIndex === "auto") node.style.zIndex = "1";
139
+ liftStates.set(node, state);
140
+ }
141
+ lifted.push(node);
142
+ }
143
+ return () => {
144
+ lifted.forEach((el) => {
145
+ const state = liftStates.get(el);
146
+ if (!state) return;
147
+ state.count -= 1;
148
+ if (state.count > 0) return;
149
+ el.style.position = state.position;
150
+ el.style.zIndex = state.zIndex;
151
+ liftStates.delete(el);
152
+ });
153
+ lifted.length = 0;
154
+ };
155
+ };
156
+ const isDomOrderStale = (layers) => {
157
+ for (let i = 1; i < layers.length; i += 1) if (compareDocumentOrder(layers[i - 1].trigger, layers[i].trigger) > 0) return true;
158
+ return false;
159
+ };
160
+ const buildStructure = (rootElement, layers) => {
161
+ layers.sort((a, b) => compareDocumentOrder(a.trigger, b.trigger));
162
+ for (const layer of layers) {
163
+ if (layer.kind !== "cover") continue;
164
+ layer.wrapper = wrapCover(layer.trigger);
165
+ }
166
+ let inner = rootElement;
167
+ let outermost = null;
168
+ for (const layer of layers) {
169
+ if (layer.kind !== "scene") continue;
170
+ const wrapped = wrapScene(inner);
171
+ layer.container = wrapped.container;
172
+ layer.wrapper = wrapped.wrapper;
173
+ layer.padding = wrapped.padding;
174
+ inner = wrapped.container;
175
+ outermost = wrapped.container;
176
+ }
177
+ return outermost;
178
+ };
179
+ const unbuildStructure = (rootElement, layers, outermostContainer) => {
180
+ if (outermostContainer) {
181
+ outermostContainer.parentNode?.insertBefore(rootElement, outermostContainer);
182
+ outermostContainer.remove();
183
+ }
184
+ for (let i = layers.length - 1; i >= 0; i -= 1) {
185
+ const layer = layers[i];
186
+ if (layer.kind === "cover" && layer.wrapper) unwrapCover(layer.wrapper);
187
+ }
188
+ layers.forEach((layer) => {
189
+ layer.wrapper = null;
190
+ if (layer.kind === "scene") {
191
+ layer.container = null;
192
+ layer.padding = null;
193
+ }
194
+ });
195
+ };
196
+ const resolveMaybeFn = (value) => typeof value === "function" ? value() : value;
197
+ const KEYWORD_FRACTIONS = {
198
+ top: 0,
199
+ center: .5,
200
+ bottom: 1
201
+ };
202
+ const signedPx = (sign, value, unit, refSize) => {
203
+ const magnitude = unit === "%" ? parseFloat(value) / 100 * refSize : parseFloat(value);
204
+ return sign?.startsWith("-") ? -magnitude : magnitude;
205
+ };
206
+ const CLAUSE_TOKEN_RE = /^(top|center|bottom|(?:\d+\.?\d*|\.\d+))?(%|px)?(?:([+-]=?)(\d+\.?\d*|\.\d+)(%|px)?)?$/;
207
+ const parseClauseToken = (token, refSize) => {
208
+ const match = CLAUSE_TOKEN_RE.exec(token);
209
+ if (!match || !match[1] && !match[3]) throw new Error(`StickyScrollTrigger: unsupported position clause "${token}"`);
210
+ const [, base, baseUnit, sign, offsetValue, offsetUnit] = match;
211
+ if (base !== void 0 && sign && !sign.includes("=")) {
212
+ const suggestion = `${base}${baseUnit ?? ""}${sign}=${offsetValue}${offsetUnit ?? ""}`;
213
+ throw new Error(`StickyScrollTrigger: unsupported position clause "${token}": a signed offset needs an explicit '=' when it follows a keyword or number (GSAP itself requires this too, to tell "${base}" and the offset apart). Did you mean "${suggestion}"?`);
214
+ }
215
+ const isKeyword = base !== void 0 && base in KEYWORD_FRACTIONS;
216
+ const basePercent = baseUnit === "%";
217
+ return {
218
+ fraction: isKeyword ? KEYWORD_FRACTIONS[base] : basePercent ? parseFloat(base) / 100 : 0,
219
+ offsetPx: (!isKeyword && !basePercent && base !== void 0 ? parseFloat(base) : 0) + (sign ? signedPx(sign, offsetValue, offsetUnit, refSize) : 0)
220
+ };
221
+ };
222
+ const isAbsoluteFormat = (resolved) => {
223
+ if (typeof resolved === "number") return true;
224
+ return resolved.trim() !== "" && !Number.isNaN(Number(resolved));
225
+ };
226
+ const resolveAbsolute = (resolved) => typeof resolved === "number" ? resolved : Number(resolved);
227
+ const resolveAnchorTop = (position, elementHeight, viewportHeight) => {
228
+ const [elementToken, viewportToken = "top"] = position.trim().split(/\s+/);
229
+ const elementClause = parseClauseToken(elementToken, elementHeight);
230
+ const viewportClause = parseClauseToken(viewportToken, viewportHeight);
231
+ return viewportHeight * viewportClause.fraction + viewportClause.offsetPx - (elementHeight * elementClause.fraction + elementClause.offsetPx);
232
+ };
233
+ const DWELL_RELATIVE_RE = /^\+=(\d+\.?\d*|\.\d+)(%|px)?$/;
234
+ const isDwellFormat = (resolved) => typeof resolved === "string" && DWELL_RELATIVE_RE.test(resolved.trim());
235
+ const resolveDwell = (resolved, viewportHeight) => {
236
+ const match = DWELL_RELATIVE_RE.exec(String(resolved).trim());
237
+ if (!match) throw new Error(`StickyScrollTrigger: unsupported end format "${resolved}"`);
238
+ const [, value, unit] = match;
239
+ return signedPx(void 0, value, unit, viewportHeight);
240
+ };
241
+ const MAX_TOKEN_RE = /^max(?:([+-]=)(\d+\.?\d*|\.\d+)(%|px)?)?$/;
242
+ const isMaxFormat = (resolved) => typeof resolved === "string" && MAX_TOKEN_RE.test(resolved.trim());
243
+ const resolveMaxOffset = (resolved, viewportHeight) => {
244
+ const match = MAX_TOKEN_RE.exec(resolved.trim());
245
+ if (!match) throw new Error(`StickyScrollTrigger: unsupported max-position format "${resolved}"`);
246
+ const [, sign, value, unit] = match;
247
+ return sign ? signedPx(sign, value, unit, viewportHeight) : 0;
248
+ };
249
+ const gapsBeforeRawPosition = (measurements, paddingHeightsSoFar, previous, rawPosition, ownIndex) => {
250
+ let total = 0;
251
+ measurements.forEach((measurement, i) => {
252
+ if (i === ownIndex || measurement.triggerTop >= rawPosition) return;
253
+ const paddingHeight = paddingHeightsSoFar[i] !== void 0 ? paddingHeightsSoFar[i] : previous ? previous.paddings[i] : null;
254
+ if (paddingHeight !== null && paddingHeight !== void 0) total += paddingHeight;
255
+ });
256
+ return total;
257
+ };
258
+ const runPass = (measurements, { viewportHeight, structureTop, documentMaxScroll, measureLiveEndTriggerTop }, previous) => {
259
+ const naturalTops = [];
260
+ const paddingHeightsSoFar = [];
261
+ let precedingGaps = 0;
262
+ return {
263
+ plans: measurements.map((measurement, index) => {
264
+ const naturalAbsoluteTop = measurement.triggerTop + precedingGaps;
265
+ const freezeStart = measurement.start.mode === "absolute" ? measurement.start.value : naturalAbsoluteTop - measurement.start.anchorOffset;
266
+ let freezeEnd;
267
+ switch (measurement.end.mode) {
268
+ case "auto":
269
+ if (measurement.start.mode !== "clause") throw new Error("StickyScrollTrigger: internal error: an absolute start reached 'auto' end mode, which resolveStartSpec should have already rejected.");
270
+ freezeEnd = freezeStart + Math.max(0, measurement.start.anchorOffset + (measurement.coverTop - measurement.triggerTop));
271
+ break;
272
+ case "dwell":
273
+ freezeEnd = freezeStart + measurement.end.distancePx;
274
+ break;
275
+ case "absolute":
276
+ freezeEnd = Math.max(freezeStart, measurement.end.value);
277
+ break;
278
+ case "max":
279
+ freezeEnd = Math.max(freezeStart, documentMaxScroll + measurement.end.offsetPx);
280
+ break;
281
+ case "clause": {
282
+ let endTop;
283
+ if (measurement.endTriggerIsSelf) endTop = naturalAbsoluteTop;
284
+ else {
285
+ const known = measurement.endTriggerIndex === null ? void 0 : naturalTops[measurement.endTriggerIndex] !== void 0 ? naturalTops[measurement.endTriggerIndex] : previous ? previous.naturalTops[measurement.endTriggerIndex] : void 0;
286
+ if (known !== void 0) endTop = known;
287
+ else if (measurement.end.measureLive) endTop = measureLiveEndTriggerTop(index);
288
+ else endTop = measurement.end.rawTop === null ? 0 : measurement.end.rawTop + gapsBeforeRawPosition(measurements, paddingHeightsSoFar, previous, measurement.end.rawTop, index);
289
+ }
290
+ const anchorOffsetEnd = resolveAnchorTop(measurement.end.clause, measurement.endTriggerHeight, viewportHeight);
291
+ freezeEnd = Math.max(freezeStart, endTop - anchorOffsetEnd);
292
+ break;
293
+ }
294
+ }
295
+ let plan;
296
+ if (measurement.kind === "cover") {
297
+ if (measurement.start.mode !== "clause") throw new Error("StickyScrollTrigger: internal error: a cover layer measurement carries an absolute start, which resolveStartSpec should have already rejected.");
298
+ plan = {
299
+ freezeStart,
300
+ freezeEnd,
301
+ stickyTop: measurement.start.anchorOffset - (measurement.triggerTop - measurement.wrapperTop),
302
+ paddingHeight: null
303
+ };
304
+ } else plan = {
305
+ freezeStart,
306
+ freezeEnd,
307
+ stickyTop: structureTop - freezeStart,
308
+ paddingHeight: Math.max(0, freezeEnd - freezeStart)
309
+ };
310
+ if (plan.paddingHeight !== null) precedingGaps += plan.paddingHeight;
311
+ naturalTops[index] = naturalAbsoluteTop;
312
+ paddingHeightsSoFar[index] = plan.paddingHeight;
313
+ return plan;
314
+ }),
315
+ naturalTops
316
+ };
317
+ };
318
+ const planLayers = (measurements, deps) => {
319
+ const needsConvergence = measurements.some((measurement, index) => {
320
+ if (measurement.end.mode !== "clause" || measurement.endTriggerIsSelf) return false;
321
+ return measurement.endTriggerIndex === null ? measurement.end.rawTop !== null : measurement.endTriggerIndex >= index;
322
+ });
323
+ const liveTopCache = new Map();
324
+ const passDeps = {
325
+ ...deps,
326
+ measureLiveEndTriggerTop: (index) => {
327
+ const cached = liveTopCache.get(index);
328
+ if (cached !== void 0) return cached;
329
+ const value = deps.measureLiveEndTriggerTop(index);
330
+ liveTopCache.set(index, value);
331
+ return value;
332
+ }
333
+ };
334
+ let { plans, naturalTops } = runPass(measurements, passDeps, null);
335
+ if (needsConvergence) for (let pass = 0; pass < measurements.length; pass += 1) {
336
+ const previous = {
337
+ paddings: plans.map((plan) => plan.paddingHeight),
338
+ naturalTops
339
+ };
340
+ const next = runPass(measurements, passDeps, previous);
341
+ const stable = next.plans.every((plan, i) => plan.paddingHeight === plans[i].paddingHeight);
342
+ plans = next.plans;
343
+ naturalTops = next.naturalTops;
344
+ if (stable) break;
345
+ if (pass === measurements.length - 1) throw new Error("StickyScrollTrigger: could not resolve endTrigger positions: some Scene layers' endTrigger references form a circular structural dependency (either two or more triggers reference each other's endTrigger, or an unregistered endTrigger's dwell depends on a layer whose own end depends back on it). Point each endTrigger at a layer that doesn't depend on it.");
346
+ }
347
+ plans.forEach((plan, index) => deps.onPlanned(index, plan));
348
+ return plans;
349
+ };
350
+ const resolveEndSpec = (rootElement, viewportHeight, layer, endResolved, ownIndex, endTriggerIndex) => {
351
+ if (endResolved === null) return { mode: "auto" };
352
+ if (isDwellFormat(endResolved)) return {
353
+ mode: "dwell",
354
+ distancePx: Math.max(0, resolveDwell(endResolved, viewportHeight))
355
+ };
356
+ if (isAbsoluteFormat(endResolved)) return {
357
+ mode: "absolute",
358
+ value: resolveAbsolute(endResolved)
359
+ };
360
+ if (isMaxFormat(endResolved)) {
361
+ if (layer.kind !== "cover") throw new Error(`StickyScrollTrigger: createStickyTrigger's trigger ${describeElement(layer.trigger)} has end "${endResolved}", which uses GSAP's 'max' keyword. This isn't supported here (a Scene layer's own dwell padding contributes to the document's max scroll position, so the freeze window would depend on itself and never converge). Use createOverlapScroll instead (cover layers never add padding), or a dwell distance such as '+=500'.`);
362
+ return {
363
+ mode: "max",
364
+ offsetPx: resolveMaxOffset(endResolved, viewportHeight)
365
+ };
366
+ }
367
+ if (layer.kind !== "cover" && endTriggerIndex !== null && endTriggerIndex > ownIndex) throw new Error(`StickyScrollTrigger: createStickyTrigger's trigger ${describeElement(layer.trigger)}'s endTrigger (${describeElement(layer.endTrigger)}) refers to a layer positioned later in DOM order. This isn't supported (the layer's own dwell padding always precedes and pushes down that later layer's position, so the freeze window would depend on its own dwell and never converge). Point endTrigger at a layer registered earlier in DOM order, or use a dwell distance such as '+=500' instead.`);
368
+ const unregistered = endTriggerIndex === null;
369
+ const insideRoot = rootElement.contains(layer.endTrigger);
370
+ if (unregistered && !insideRoot && layer.kind !== "cover") throw new Error(`StickyScrollTrigger: createStickyTrigger's trigger ${describeElement(layer.trigger)} has an endTrigger (${describeElement(layer.endTrigger)}) outside the shared container (the layer's own dwell would push it away, so the freeze window never converges). Point endTrigger at an element inside the container, or use a dwell distance such as '+=500'.`);
371
+ return {
372
+ mode: "clause",
373
+ clause: endResolved,
374
+ rawTop: unregistered && insideRoot ? documentTop(layer.endTrigger) : null,
375
+ measureLive: unregistered && !insideRoot
376
+ };
377
+ };
378
+ const resolveStartSpec = (layer, startResolved, elementHeight, viewportHeight) => {
379
+ if (!isAbsoluteFormat(startResolved)) return {
380
+ mode: "clause",
381
+ anchorOffset: resolveAnchorTop(startResolved, elementHeight, viewportHeight)
382
+ };
383
+ if (layer.kind === "cover") throw new Error(`StickyScrollTrigger: createOverlapScroll's trigger ${describeElement(layer.trigger)} has start "${startResolved}", an absolute scroll position (GSAP treats any bare-number start this way). This isn't supported here: a cover layer's sticky position is always computed relative to its own wrapper, which needs start to be a position clause (e.g. 'bottom bottom'), not an absolute scroll position.`);
384
+ return {
385
+ mode: "absolute",
386
+ value: resolveAbsolute(startResolved)
387
+ };
388
+ };
389
+ const measureLayer = (rootElement, viewportHeight, layer, ownIndex, indexByTrigger) => {
390
+ const startResolved = resolveMaybeFn(layer.start);
391
+ const endResolved = layer.end === null ? null : resolveMaybeFn(layer.end);
392
+ const elementHeight = layer.trigger.offsetHeight;
393
+ const endTriggerIsSelf = layer.endTrigger === layer.trigger;
394
+ const endTriggerIndex = indexByTrigger.get(layer.endTrigger) ?? null;
395
+ const end = resolveEndSpec(rootElement, viewportHeight, layer, endResolved, ownIndex, endTriggerIndex);
396
+ const start = resolveStartSpec(layer, startResolved, elementHeight, viewportHeight);
397
+ return {
398
+ kind: layer.kind,
399
+ start,
400
+ triggerTop: documentTop(layer.trigger),
401
+ wrapperTop: layer.wrapper ? documentTop(layer.wrapper) : 0,
402
+ coverTop: layer.kind === "cover" ? documentTop(layer.cover) : 0,
403
+ end,
404
+ endTriggerIsSelf,
405
+ endTriggerIndex,
406
+ endTriggerHeight: end.mode === "clause" ? layer.endTrigger.offsetHeight : 0
407
+ };
408
+ };
409
+ const hasDuplicateTrigger = (list, trigger) => list.some((existing) => existing.trigger === trigger);
410
+ var StickyScrollTrigger = class {
411
+ #rootElement;
412
+ #layers = [];
413
+ #builtLayers = [];
414
+ #coverRestoreByLayer = new WeakMap();
415
+ #built = false;
416
+ #dirty = false;
417
+ #outermostContainer = null;
418
+ #destroyed = false;
419
+ #rebuildScheduled = false;
420
+ #scrollTriggerClass = null;
421
+ #pinLayers = [];
422
+ constructor(root) {
423
+ this.#rootElement = resolveRoot(root);
424
+ }
425
+ #unbuild() {
426
+ if (!this.#built) return;
427
+ unbuildStructure(this.#rootElement, this.#builtLayers, this.#outermostContainer);
428
+ this.#outermostContainer = null;
429
+ this.#built = false;
430
+ }
431
+ #build() {
432
+ this.#outermostContainer = buildStructure(this.#rootElement, this.#layers);
433
+ this.#builtLayers = [...this.#layers];
434
+ this.#built = true;
435
+ this.#dirty = false;
436
+ }
437
+ #scheduleRebuild() {
438
+ if (this.#rebuildScheduled || this.#destroyed) return;
439
+ this.#rebuildScheduled = true;
440
+ queueMicrotask(() => {
441
+ this.#rebuildScheduled = false;
442
+ if (this.#destroyed) return;
443
+ this.refresh();
444
+ if (typeof this.#scrollTriggerClass?.refresh === "function") this.#scrollTriggerClass.refresh();
445
+ });
446
+ }
447
+ #captureScrollTriggerClass(self) {
448
+ this.#scrollTriggerClass = self.constructor;
449
+ }
450
+ #createAutoRefreshHandler(list, entry, userOnRefreshInit) {
451
+ return (self) => {
452
+ this.#captureScrollTriggerClass(self);
453
+ if (list[0] === entry) this.refresh();
454
+ userOnRefreshInit?.(self);
455
+ };
456
+ }
457
+ #wrapUnwrappedPins() {
458
+ this.#pinLayers.forEach((layer) => {
459
+ if (layer.outer) return;
460
+ const wrapped = wrapPin(layer.trigger);
461
+ layer.outer = wrapped.outer;
462
+ layer.inner = wrapped.inner;
463
+ });
464
+ }
465
+ #resetSceneCoverStickyState() {
466
+ const wrapperSnapshots = this.#layers.map((layer) => layer.wrapper).filter((wrapper) => wrapper !== null).map((wrapper) => ({
467
+ wrapper,
468
+ position: wrapper.style.position,
469
+ top: wrapper.style.top
470
+ }));
471
+ wrapperSnapshots.forEach(({ wrapper }) => resetStickyPosition(wrapper));
472
+ return () => {
473
+ wrapperSnapshots.forEach(({ wrapper, position, top }) => {
474
+ wrapper.style.position = position;
475
+ wrapper.style.top = top;
476
+ });
477
+ };
478
+ }
479
+ #refreshPins(viewportHeight) {
480
+ if (!this.#pinLayers.length) return;
481
+ const restoreSceneCoverStickyState = this.#resetSceneCoverStickyState();
482
+ this.#pinLayers.forEach((layer) => {
483
+ resetStickyPosition(layer.trigger);
484
+ if (layer.inner) layer.inner.style.height = "";
485
+ });
486
+ this.#pinLayers.forEach((layer) => {
487
+ if (!layer.inner) return;
488
+ const resolvedEnd = resolveMaybeFn(layer.end);
489
+ if (isMaxFormat(resolvedEnd)) throw new Error(`StickyScrollTrigger: createStickyPin's end "${resolvedEnd}" uses GSAP's 'max' keyword, which isn't supported here (the pin's own spacer height contributes to the document's max scroll position, so the spacer height would depend on itself and never converge). Use a plain position clause such as 'top top' against endTrigger instead.`);
490
+ const topPx = resolveMaybeFn(layer.top);
491
+ const triggerTop = documentTop(layer.trigger);
492
+ const triggerHeight = layer.trigger.offsetHeight;
493
+ const height = (isAbsoluteFormat(resolvedEnd) ? resolveAbsolute(resolvedEnd) : documentTop(layer.endTrigger) - resolveAnchorTop(resolvedEnd, layer.endTrigger.offsetHeight, viewportHeight)) - triggerTop + topPx + triggerHeight;
494
+ applyStickyPosition(layer.trigger, topPx);
495
+ layer.inner.style.height = `${Math.max(0, height)}px`;
496
+ });
497
+ restoreSceneCoverStickyState();
498
+ }
499
+ #refreshScenesAndCovers(viewportHeight) {
500
+ if (!this.#layers.length) return;
501
+ const active = [];
502
+ this.#layers.forEach((layer) => {
503
+ if (!layer.wrapper) return;
504
+ resetStickyPosition(layer.wrapper);
505
+ active.push(layer);
506
+ });
507
+ if (!active.length) return;
508
+ const structureTop = this.#outermostContainer ? documentTop(this.#outermostContainer) : 0;
509
+ const indexByTrigger = new Map();
510
+ active.forEach((layer, index) => {
511
+ indexByTrigger.set(layer.trigger, index);
512
+ });
513
+ const measured = active.map((layer, ownIndex) => measureLayer(this.#rootElement, viewportHeight, layer, ownIndex, indexByTrigger));
514
+ let documentMaxScroll = 0;
515
+ const applyLayers = () => planLayers(measured, {
516
+ viewportHeight,
517
+ structureTop,
518
+ documentMaxScroll,
519
+ measureLiveEndTriggerTop: (index) => documentTop(active[index].endTrigger),
520
+ onPlanned: (index, plan) => {
521
+ const layer = active[index];
522
+ layer.freezeStart = plan.freezeStart;
523
+ layer.freezeEnd = plan.freezeEnd;
524
+ if (!layer.wrapper) return;
525
+ applyStickyPosition(layer.wrapper, plan.stickyTop);
526
+ if (layer.kind === "scene" && layer.padding && plan.paddingHeight !== null) layer.padding.style.height = `${plan.paddingHeight}px`;
527
+ }
528
+ });
529
+ applyLayers();
530
+ const needsLiveRemeasure = measured.some((measurement) => measurement.end.mode === "clause" && measurement.end.measureLive);
531
+ const needsMaxRemeasure = measured.some((measurement) => measurement.end.mode === "max");
532
+ if (needsMaxRemeasure) documentMaxScroll = measureDocumentMaxScroll(viewportHeight);
533
+ if (needsLiveRemeasure || needsMaxRemeasure) applyLayers();
534
+ }
535
+ refresh() {
536
+ if (this.#destroyed) return;
537
+ if (this.#dirty || !this.#built || isDomOrderStale(this.#layers)) {
538
+ this.#unbuild();
539
+ this.#build();
540
+ }
541
+ this.#wrapUnwrappedPins();
542
+ const viewportHeight = this.#layers.length || this.#pinLayers.length ? measureViewportHeight() : 0;
543
+ this.#refreshScenesAndCovers(viewportHeight);
544
+ this.#refreshPins(viewportHeight);
545
+ }
546
+ #assertTriggerAvailable(list, trigger, message) {
547
+ if (hasDuplicateTrigger(list, trigger)) throw new Error(message);
548
+ }
549
+ #registerLayer(layer, onKill, rest) {
550
+ if (this.#destroyed) throw new Error("StickyScrollTrigger: cannot register a new layer after destroy() has been called.");
551
+ this.#assertTriggerAvailable(this.#layers, layer.trigger, `StickyScrollTrigger: ${describeElement(layer.trigger)} is already registered as a trigger for another layer. Each element can only be used once across createStickyTrigger/createOverlapScroll calls in the same controller instance (reusing it makes endTrigger resolution ambiguous).`);
552
+ this.#assertTriggerAvailable(this.#pinLayers, layer.trigger, `StickyScrollTrigger: ${describeElement(layer.trigger)} is already registered as a pin trigger (createStickyPin). Using the same element as both a Scene/Cover trigger and a pin trigger wraps it twice and produces conflicting position:sticky behavior.`);
553
+ this.#layers.push(layer);
554
+ this.#dirty = true;
555
+ return {
556
+ ...rest,
557
+ trigger: layer.trigger,
558
+ start: () => layer.freezeStart,
559
+ end: () => layer.freezeEnd || .001,
560
+ invalidateOnRefresh: rest.invalidateOnRefresh ?? true,
561
+ onKill: (self) => {
562
+ this.#captureScrollTriggerClass(self);
563
+ const index = this.#layers.indexOf(layer);
564
+ if (index !== -1) this.#layers.splice(index, 1);
565
+ this.#dirty = true;
566
+ this.#scheduleRebuild();
567
+ onKill?.(self);
568
+ },
569
+ onRefreshInit: this.#createAutoRefreshHandler(this.#layers, layer, rest.onRefreshInit)
570
+ };
571
+ }
572
+ createStickyTrigger({ trigger: triggerInput, start = "0 0", end = "100% 0", endTrigger: endTriggerInput, onKill, ...rest }) {
573
+ const trigger = resolveElement(triggerInput, "createStickyTrigger");
574
+ const endTrigger = resolveEndTrigger(trigger, endTriggerInput, "createStickyTrigger");
575
+ return this.#registerLayer({
576
+ kind: "scene",
577
+ trigger,
578
+ endTrigger,
579
+ container: null,
580
+ wrapper: null,
581
+ padding: null,
582
+ start,
583
+ end,
584
+ freezeStart: 0,
585
+ freezeEnd: 0
586
+ }, onKill, rest);
587
+ }
588
+ createOverlapScroll({ trigger: triggerInput, cover, start = "bottom bottom", end = null, endTrigger: endTriggerInput, onKill, ...rest }) {
589
+ const trigger = resolveElement(triggerInput, "createOverlapScroll");
590
+ const endTrigger = resolveEndTrigger(trigger, endTriggerInput, "createOverlapScroll");
591
+ const coverElement = cover === void 0 ? trigger.nextElementSibling : resolveElement(cover, "createOverlapScroll");
592
+ if (!(coverElement instanceof HTMLElement)) throw new Error(`createOverlapScroll: cover element (trigger.nextElementSibling) not found for trigger ${describeElement(trigger)}`);
593
+ if (coverElement.parentNode !== trigger.parentNode) throw new Error(`createOverlapScroll: cover ${describeElement(coverElement)} must be a sibling of trigger ` + describeElement(trigger));
594
+ const layer = {
595
+ kind: "cover",
596
+ trigger,
597
+ endTrigger,
598
+ cover: coverElement,
599
+ wrapper: null,
600
+ start,
601
+ end,
602
+ freezeStart: 0,
603
+ freezeEnd: 0
604
+ };
605
+ const vars = this.#registerLayer(layer, (self) => {
606
+ restoreCoverStyles();
607
+ onKill?.(self);
608
+ }, rest);
609
+ const restoreCoverStyles = liftAboveStickyWrapper(coverElement);
610
+ this.#coverRestoreByLayer.set(layer, restoreCoverStyles);
611
+ return vars;
612
+ }
613
+ createStickyPin({ trigger: triggerInput, top = 0, endTrigger: endTriggerInput, end = "top top", onKill, ...rest }) {
614
+ if (this.#destroyed) throw new Error("StickyScrollTrigger: cannot register a new pin after destroy() has been called.");
615
+ const trigger = resolveElement(triggerInput, "createStickyPin");
616
+ const endTrigger = resolveElement(endTriggerInput, "createStickyPin");
617
+ this.#assertTriggerAvailable(this.#pinLayers, trigger, `StickyScrollTrigger: ${describeElement(trigger)} is already registered as a pin trigger.`);
618
+ this.#assertTriggerAvailable(this.#layers, trigger, `StickyScrollTrigger: ${describeElement(trigger)} is already registered as a trigger for another layer (createStickyTrigger/createOverlapScroll). Using the same element as both a Scene/Cover trigger and a pin trigger wraps it twice and produces conflicting position:sticky behavior.`);
619
+ const layer = {
620
+ trigger,
621
+ outer: null,
622
+ inner: null,
623
+ top,
624
+ endTrigger,
625
+ end
626
+ };
627
+ this.#pinLayers.push(layer);
628
+ return {
629
+ ...rest,
630
+ trigger,
631
+ onKill: (self) => {
632
+ this.#captureScrollTriggerClass(self);
633
+ const index = this.#pinLayers.indexOf(layer);
634
+ if (index !== -1) this.#pinLayers.splice(index, 1);
635
+ if (layer.outer) {
636
+ unwrapPin(layer.outer, layer.trigger);
637
+ layer.outer = null;
638
+ layer.inner = null;
639
+ }
640
+ onKill?.(self);
641
+ },
642
+ onRefreshInit: this.#createAutoRefreshHandler(this.#pinLayers, layer, rest.onRefreshInit)
643
+ };
644
+ }
645
+ resolveScrollPosition(elementInput, position) {
646
+ const element = resolveElement(elementInput, "resolveScrollPosition");
647
+ const resolved = resolveMaybeFn(position);
648
+ const viewportHeight = measureViewportHeight();
649
+ if (isMaxFormat(resolved)) return measureDocumentMaxScroll(viewportHeight) + resolveMaxOffset(resolved, viewportHeight);
650
+ if (isAbsoluteFormat(resolved)) return resolveAbsolute(resolved);
651
+ let gap = 0;
652
+ this.#layers.forEach((layer) => {
653
+ if (layer.kind !== "scene") return;
654
+ if (compareDocumentOrder(layer.trigger, element) >= 0) return;
655
+ gap += layer.freezeEnd - layer.freezeStart;
656
+ });
657
+ const anchorOffset = resolveAnchorTop(resolved, element.offsetHeight, viewportHeight);
658
+ const restoreSceneCoverStickyState = this.#resetSceneCoverStickyState();
659
+ const result = documentTop(element) + gap - anchorOffset;
660
+ restoreSceneCoverStickyState();
661
+ return result;
662
+ }
663
+ static getScrollTop(elementInput, instances) {
664
+ const element = resolveElement(elementInput, "StickyScrollTrigger.getScrollTop");
665
+ const owner = instances.find((instance) => instance.#rootElement.contains(element));
666
+ if (owner) return owner.resolveScrollPosition(element, "top top");
667
+ return documentTop(element);
668
+ }
669
+ createResolvedTrigger({ trigger: triggerInput, start, end, endTrigger: endTriggerInput, ...rest }) {
670
+ const trigger = resolveElement(triggerInput, "createResolvedTrigger");
671
+ const endTrigger = resolveEndTrigger(trigger, endTriggerInput, "createResolvedTrigger");
672
+ return {
673
+ ...rest,
674
+ trigger,
675
+ start: () => this.resolveScrollPosition(trigger, start),
676
+ end: () => this.resolveScrollPosition(endTrigger, end)
677
+ };
678
+ }
679
+ destroy() {
680
+ if (this.#destroyed) return;
681
+ this.#destroyed = true;
682
+ this.#layers.forEach((layer) => {
683
+ if (layer.kind === "cover") this.#coverRestoreByLayer.get(layer)?.();
684
+ });
685
+ this.#unbuild();
686
+ this.#layers.length = 0;
687
+ this.#builtLayers = [];
688
+ this.#pinLayers.forEach((layer) => {
689
+ if (layer.outer) unwrapPin(layer.outer, layer.trigger);
690
+ });
691
+ this.#pinLayers.length = 0;
692
+ }
693
+ };
694
+ export { StickyScrollTrigger as default };