sticky-scroll-trigger 0.13.0 → 0.14.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.
package/README.md CHANGED
@@ -40,7 +40,7 @@ npm install gsap sticky-scroll-trigger
40
40
  For plain `<script>` usage without a bundler, an IIFE build is also published, exposing `window.StickyScrollTrigger`:
41
41
 
42
42
  ```html
43
- <script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.13.0/dist/StickyScrollTrigger.global.min.js"></script>
43
+ <script src="https://cdn.jsdelivr.net/npm/sticky-scroll-trigger@0.14.0/dist/StickyScrollTrigger.global.min.js"></script>
44
44
  ```
45
45
 
46
46
  Consumers should only rely on the exports of `sticky-scroll-trigger` (or `window.StickyScrollTrigger` for the global build). The internal modules under `src/` are not part of the public API.
@@ -504,6 +504,13 @@ The table above is the whole accepted grammar. GSAP's `clamp()` wrapper (`start:
504
504
 
505
505
  GSAP passes the `ScrollTrigger` instance to its own function-valued `start`/`end` (`start: (self) => ...`), and this module doesn't, so a function declaring that parameter is a TypeScript error. There is nothing to pass: this module's `refresh()` resolves these functions, and it runs whether or not the returned `ScrollTrigger.Vars` was ever handed to `ScrollTrigger.create()`. `self.start`/`self.end` would be circular anyway, since the freeze window they report is what `refresh()` is in the middle of computing.
506
506
 
507
+ A [`createStickyTrigger`](#createstickytriggeroptions) `end` function can read the layout, as a GSAP pin's can: where an element sits, or the page's height. GSAP calls a pin's `end` with the spacers of the pins before it in place and those after it taken out. So when the function returns a dwell or an absolute position, `refresh()` calls it again in that layout: the dwell of the instance's earlier layers in place right after their triggers, and the dwell of its own layers and of every instance further down the page taken out. Page order stands in for GSAP's creation order, so this matches pins created top to bottom. What differs from GSAP:
508
+
509
+ - The function runs once or twice more per `refresh()` (at most six times more). Meanwhile the page is shorter and holds an empty `div` after each earlier trigger, which a `MutationObserver` sees. If the shorter page cut the scroll back, `refresh()` scrolls back. Firefox and Safari can fire one `scroll` event during such a `refresh()`, with the scroll where it was
510
+ - That `div` is a box of its own, where GSAP's pin-spacer takes the trigger's place. A position below it comes out later by the trigger's bottom margin when that margin collapses with the next element's top margin, or by the gap in a grid or flex layout
511
+ - [`resolveScrollPosition`](#resolvescrollpositionelement-position) called from the function measures the page `refresh()` left, as anywhere else, so a function built on it returns what it did before
512
+ - From the first `onRefreshInit` of any instance's layer or pin handed to `ScrollTrigger.create()` on, a `ScrollTrigger.refresh()` from the function measures the page and the scroll `refresh()` left, and what the function returns counts as it would without that call. A `refreshInit` callback GSAP calls before that one sees the function's layout and the scroll as that layout left it. With no layer or pin of any instance handed over, GSAP measures every ScrollTrigger in that layout and runs their callbacks at the scroll that layout left
513
+
507
514
  ### Absolute scroll position
508
515
 
509
516
  GSAP treats a value as an absolute scroll position rather than a clause whenever it's just a number: a plain JS number, or a string `Number()` converts on its own with no keyword, second token, or `%`/`px` suffix, `'-50'` and `'1e3'` included. It ignores the reference element entirely in that case (`ScrollTrigger.js`'s `_parsePosition`: `isNaN(value) || (value = +value)`). This module follows the same rule for `start` and `end`, and for [`createStickyPin`](#createstickypinoptions)'s `end`, [`createResolvedTrigger`](#createresolvedtriggeroptions)'s `start`/`end`, and [`resolveScrollPosition`](#resolvescrollpositionelement-position)'s `position`.
@@ -597,15 +604,17 @@ sticky.createOverlapScroll({
597
604
  - Every option, including ScrollTrigger options passed through, is meant to come from the page's own code. If some come from a configuration other people can edit, build the options object from values you allow instead of passing the configuration through: selectors reach the whole document, callbacks and function-valued `start`/`end` run in the page, and `scrollMarginTargets` writes to every element it matches on each `refresh()`
598
605
  - ScrollTrigger's `pin`/`pinSpacing`/`anticipatePin` can't be used (pinning is handled by sticky; these are already excluded at the type level)
599
606
  - GSAP's `clamp()` position wrapper isn't accepted, and a function-valued `start`/`end` is called with no arguments rather than with the `ScrollTrigger` instance GSAP passes (see [Position syntax](#position-syntax))
607
+ - A function-valued `start`/`end` of `createStickyTrigger`, `createOverlapScroll` or `createStickyPin` runs inside `refresh()` and may call `refresh()`, `ScrollTrigger.refresh()`, a ScrollTrigger's `kill()`, `destroy()` or a `create*` method. A `refresh()` of the same instance from there makes the outermost `refresh()` measure once more before it returns. A `ScrollTrigger.refresh()` from these functions may not measure the instance again: when the outermost `refresh()` runs outside a GSAP refresh, GSAP can miss a change the function makes until a `ScrollTrigger.refresh()` after the outermost `refresh()` returns, though the page itself ends up right. A function that registers a new layer and calls `refresh()` or `ScrollTrigger.refresh()` on every call never settles: the page hangs, and with `refresh()` it ends in a stack overflow. Prefer changing the layout outside these functions, then calling `ScrollTrigger.refresh()` (see [Calling refresh](#calling-refresh))
600
608
  - A `createStickyTrigger` Scene layer can't point `endTrigger` at a registered layer later in DOM order; `createOverlapScroll`'s cover layer can (see [End syntax](#end-syntax))
601
609
  - If a Scene layer's `end` uses a position clause, don't set `endTrigger` to an element that gets pushed down by that same scene's own dwell; the value won't converge
602
610
  - `end: 'max'` throws on `createStickyTrigger` and `createStickyPin` (see [End syntax](#end-syntax)). End a Scene layer on a dwell distance and a pin on a position clause against `endTrigger` instead, or use `createOverlapScroll`, which takes `'max'`
603
611
  - If Scene layers' `endTrigger`s depend on each other in a way that never settles, or only settles by counting each other's dwell or in a way no creation order gives, the layers resolve the way GSAP's pins would in one creation order (see [End syntax](#end-syntax)). `refresh()` throws only if that order doesn't settle either
604
612
  - A few rare layouts with nested Scene layers still resolve to window lengths no creation order of GSAP's pins gives; writing the affected `end` as a dwell avoids it (see [End syntax](#end-syntax))
605
- - Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls throws
613
+ - Using the same element as the `trigger` of two different `createStickyTrigger`/`createOverlapScroll`/`createStickyPin` calls on one instance throws. Nothing checks this across instances, so give each element to one instance: `createStickyPin` on one element from two instances nests one instance's wrapper inside the other's, and once the outer one's pin (the one whose `refresh()` wrapped the element first) is killed, the inner one's range is wrong
606
614
  - You must call `refresh()` once manually after registration. Window resize/load recomputation is automatically wired to GSAP's own `refreshInit`, but for layout changes that don't involve those (e.g. content height changes), call `ScrollTrigger.refresh()` yourself (see [Calling refresh](#calling-refresh))
607
615
  - Resizes from mobile browsers showing/hiding their address bar are absorbed automatically (see the repository's `ARCHITECTURE.md`, "Two-pass position measurement"), but other causes like `visualViewport` zoom are not handled
608
616
  - `refresh()` writes an inline `scroll-margin-top` on every element matching `scrollMarginTargets` inside the shared container, and, on engines that drive the correction's ramps in CSS, adopts one stylesheet of its own per instance. That sheet is a constructed one, so a Content Security Policy needs no `style-src` exception for it. Both are undone by `destroy()`, and when the instance's last layer or pin is killed. Pass `scrollMarginTargets: null` to opt out (see [Same-page links](#same-page-links))
617
+ - A ScrollTrigger of your own that pins with GSAP (its `pin` option) outside the shared container leaves what this module measured stale when the pin's spacing changes in a GSAP refresh (a resize with an `end` in `%` of the viewport, say), because GSAP sizes its pins after the `refreshInit` in which this module measures: below the pin, a layer's window opens early or late by the change, and what reads the document's height, such as a cover's `'max'` end, misses the new height. One more `ScrollTrigger.refresh()` puts it right. To avoid the gap, pin that section with `createStickyTrigger` instead, as a layer of the instance it leaves stale, inside that instance's shared container. `createStickyPin` can't replace it, since, unlike GSAP's pin spacing, it adds no scroll distance
609
618
  - Don't nest one `StickyScrollTrigger` instance's shared container inside another's. The inner instance's layers don't count the outer one's dwell, so their windows open too early by however much of that dwell comes before them, and a `refresh()` run while an outer layer is stuck shifts them again by a different amount. For a target inside both, [`getScrollTop`](#stickyscrolltriggergetscrolltopelement-instances)'s ownership check also picks whichever instance is listed first. Give each instance its own part of the page instead
610
619
  - Use one instance with layers per shared container at a time. Each instance counts only its own Scene layers' dwell: with two on one container, layers lower on the page open early by the other instance's dwell above them, whichever was created first, and if the two instances' layers alternate down the page, all dwell is lost. A new instance in each `gsap.matchMedia()` setup is fine when every layer and pin goes to `ScrollTrigger.create()`, since the setup's revert kills the previous instance's layers and hands the container back (see [`destroy()`](#destroy))
611
620
 
@@ -1,6 +1,6 @@
1
1
  /*!
2
2
  * @license
3
- * StickyScrollTrigger v0.13.0
3
+ * StickyScrollTrigger v0.14.0
4
4
  * Copyright (c) 2026 Kuninori Ogino
5
5
  * Released under the MIT License
6
6
  * https://github.com/kuninori-ogino/sticky-scroll-trigger