@algorisys/tinyfly 0.64.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/LICENSE +21 -0
- package/README.md +672 -0
- package/bin/tinyfly.mjs +59 -0
- package/lib/addons/adapters.js +756 -0
- package/lib/addons/dom-adapter-ChrbtkLC.js +243 -0
- package/lib/addons/drivers.js +72 -0
- package/lib/addons/export.js +1169 -0
- package/lib/addons/gsap-compat.js +2576 -0
- package/lib/addons/interaction.js +225 -0
- package/lib/addons/smooth-scroll-DaSacemU.js +671 -0
- package/lib/addons/teach.js +215 -0
- package/lib/browser/tinyfly.iife.js +2 -0
- package/lib/browser/tinyfly.js +6372 -0
- package/lib/browser/tinyfly.umd.js +2 -0
- package/lib/cli/tools.js +2325 -0
- package/lib/embed/tinyfly-embed.iife.js +18 -0
- package/lib/embed/tinyfly-embed.js +2316 -0
- package/lib/engine/tinyfly-engine.js +1972 -0
- package/lib/engine/tinyfly-engine.umd.cjs +2 -0
- package/lib/frameworks/react.js +32 -0
- package/lib/frameworks/solid.js +27 -0
- package/lib/frameworks/svelte.js +15 -0
- package/lib/frameworks/vue.js +29 -0
- package/lib/player/tinyfly-player.es.js +2306 -0
- package/lib/player/tinyfly-player.iife.js +2 -0
- package/lib/player/tinyfly-player.umd.js +2 -0
- package/lib/types/adapters/canvas/canvas-adapter.d.ts +238 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/adapters/dom/dom-adapter.d.ts +50 -0
- package/lib/types/adapters/dom/flip.d.ts +60 -0
- package/lib/types/adapters/dom/index.d.ts +2 -0
- package/lib/types/adapters/filter-utils.d.ts +32 -0
- package/lib/types/adapters/index.d.ts +5 -0
- package/lib/types/adapters/shine-utils.d.ts +26 -0
- package/lib/types/adapters/svg/index.d.ts +1 -0
- package/lib/types/adapters/svg/svg-adapter.d.ts +47 -0
- package/lib/types/adapters/svg-transform-box.d.ts +13 -0
- package/lib/types/adapters/text-content.d.ts +11 -0
- package/lib/types/adapters/webgl/index.d.ts +1 -0
- package/lib/types/adapters/webgl/webgl-adapter.d.ts +69 -0
- package/lib/types/browser/index.d.ts +41 -0
- package/lib/types/compat/gsap/custom-eases.d.ts +28 -0
- package/lib/types/compat/gsap/defaults.d.ts +19 -0
- package/lib/types/compat/gsap/draw-svg-vars.d.ts +36 -0
- package/lib/types/compat/gsap/ease-map.d.ts +51 -0
- package/lib/types/compat/gsap/image-sequence.d.ts +61 -0
- package/lib/types/compat/gsap/index.d.ts +65 -0
- package/lib/types/compat/gsap/inertia-vars.d.ts +39 -0
- package/lib/types/compat/gsap/keyframes-vars.d.ts +8 -0
- package/lib/types/compat/gsap/layout.d.ts +6 -0
- package/lib/types/compat/gsap/live-context.d.ts +87 -0
- package/lib/types/compat/gsap/live-draggable.d.ts +75 -0
- package/lib/types/compat/gsap/live-flip.d.ts +73 -0
- package/lib/types/compat/gsap/live-morph.d.ts +18 -0
- package/lib/types/compat/gsap/live-motion-path.d.ts +33 -0
- package/lib/types/compat/gsap/live-scroll-to.d.ts +52 -0
- package/lib/types/compat/gsap/live-scroll.d.ts +108 -0
- package/lib/types/compat/gsap/live-transition.d.ts +40 -0
- package/lib/types/compat/gsap/live.d.ts +341 -0
- package/lib/types/compat/gsap/morph-vars.d.ts +21 -0
- package/lib/types/compat/gsap/motion-path-vars.d.ts +38 -0
- package/lib/types/compat/gsap/playhead-crossings.d.ts +47 -0
- package/lib/types/compat/gsap/position.d.ts +37 -0
- package/lib/types/compat/gsap/quick-play.d.ts +38 -0
- package/lib/types/compat/gsap/split-text.d.ts +66 -0
- package/lib/types/compat/gsap/spring-vars.d.ts +34 -0
- package/lib/types/compat/gsap/stage.d.ts +182 -0
- package/lib/types/compat/gsap/stagger-grid.d.ts +30 -0
- package/lib/types/compat/gsap/text-vars.d.ts +39 -0
- package/lib/types/compat/gsap/timeline.d.ts +161 -0
- package/lib/types/compat/gsap/utils.d.ts +60 -0
- package/lib/types/compat/gsap/vars.d.ts +79 -0
- package/lib/types/drivers/index.d.ts +8 -0
- package/lib/types/drivers/scroll-driver.d.ts +218 -0
- package/lib/types/drivers/scroll-markers.d.ts +41 -0
- package/lib/types/drivers/scroll-math.d.ts +87 -0
- package/lib/types/drivers/scroll-pin.d.ts +45 -0
- package/lib/types/drivers/scroll-snap.d.ts +47 -0
- package/lib/types/drivers/smooth-scroll.d.ts +118 -0
- package/lib/types/drivers/types.d.ts +23 -0
- package/lib/types/drivers/visibility-driver.d.ts +56 -0
- package/lib/types/embed/controls.d.ts +46 -0
- package/lib/types/embed/index.d.ts +17 -0
- package/lib/types/embed/mount.d.ts +41 -0
- package/lib/types/embed/tools.d.ts +33 -0
- package/lib/types/engine/authoring/custom-ease.d.ts +49 -0
- package/lib/types/engine/authoring/index.d.ts +3 -0
- package/lib/types/engine/authoring/random.d.ts +38 -0
- package/lib/types/engine/authoring/resolve-values.d.ts +57 -0
- package/lib/types/engine/core/bake.d.ts +66 -0
- package/lib/types/engine/core/clock.d.ts +44 -0
- package/lib/types/engine/core/index.d.ts +8 -0
- package/lib/types/engine/core/inertia.d.ts +30 -0
- package/lib/types/engine/core/playhead-crossings.d.ts +47 -0
- package/lib/types/engine/core/spring.d.ts +132 -0
- package/lib/types/engine/core/stagger.d.ts +40 -0
- package/lib/types/engine/core/timeline.d.ts +203 -0
- package/lib/types/engine/core/track.d.ts +90 -0
- package/lib/types/engine/export/byte-writer.d.ts +36 -0
- package/lib/types/engine/export/css.d.ts +31 -0
- package/lib/types/engine/export/gif-decode.test-helper.d.ts +24 -0
- package/lib/types/engine/export/gif.d.ts +134 -0
- package/lib/types/engine/export/index.d.ts +9 -0
- package/lib/types/engine/export/lottie.d.ts +104 -0
- package/lib/types/engine/export/mp4.d.ts +64 -0
- package/lib/types/engine/export/quantize.d.ts +56 -0
- package/lib/types/engine/export/sprite-sheet.d.ts +46 -0
- package/lib/types/engine/export/video.d.ts +99 -0
- package/lib/types/engine/export/webp.d.ts +82 -0
- package/lib/types/engine/index.d.ts +7 -0
- package/lib/types/engine/interpolation/easing.d.ts +65 -0
- package/lib/types/engine/interpolation/index.d.ts +2 -0
- package/lib/types/engine/interpolation/interpolators.d.ts +25 -0
- package/lib/types/engine/path/index.d.ts +11 -0
- package/lib/types/engine/path/motion-path.d.ts +24 -0
- package/lib/types/engine/path/path-builders.d.ts +38 -0
- package/lib/types/engine/path/path-morph.d.ts +47 -0
- package/lib/types/engine/path/path-utils.d.ts +73 -0
- package/lib/types/engine/serialization/index.d.ts +1 -0
- package/lib/types/engine/serialization/json.d.ts +30 -0
- package/lib/types/engine/text/index.d.ts +2 -0
- package/lib/types/engine/text/text-value.d.ts +16 -0
- package/lib/types/engine/types.d.ts +401 -0
- package/lib/types/frameworks/react.d.ts +35 -0
- package/lib/types/frameworks/solid.d.ts +16 -0
- package/lib/types/frameworks/svelte.d.ts +19 -0
- package/lib/types/frameworks/vue.d.ts +27 -0
- package/lib/types/interaction/draggable.d.ts +133 -0
- package/lib/types/interaction/index.d.ts +3 -0
- package/lib/types/interaction/observer.d.ts +80 -0
- package/lib/types/interaction/snap.d.ts +30 -0
- package/lib/types/player/index.d.ts +7 -0
- package/lib/types/player/media-sync.d.ts +60 -0
- package/lib/types/player/player.d.ts +238 -0
- package/lib/types/player/sequence-types.d.ts +68 -0
- package/lib/types/player/sequencer.d.ts +91 -0
- package/lib/types/teach/diagrams.d.ts +137 -0
- package/lib/types/teach/index.d.ts +11 -0
- package/lib/types/teach/lesson.d.ts +55 -0
- package/package.json +170 -0
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
import type { Timeline } from '../engine';
|
|
2
|
+
import type { Driver } from './types';
|
|
3
|
+
import { type TriggerPosition } from './scroll-math';
|
|
4
|
+
import { type SnapOption } from './scroll-snap';
|
|
5
|
+
import { type MarkerOptions } from './scroll-markers';
|
|
6
|
+
/**
|
|
7
|
+
* Ties a timeline's playhead to scroll position ("scrubbing"), optionally
|
|
8
|
+
* pinning an element while it does.
|
|
9
|
+
*
|
|
10
|
+
* All the geometry lives in `scroll-math.ts`; this class is the DOM shell. It is
|
|
11
|
+
* built so scrolling costs almost nothing:
|
|
12
|
+
*
|
|
13
|
+
* - **Layout is read on refresh, not on scroll.** Start and end are resolved to
|
|
14
|
+
* absolute scroll offsets when the driver starts and when the window resizes.
|
|
15
|
+
* A scroll event then reads one number — the scroll offset — and does no
|
|
16
|
+
* layout work at all.
|
|
17
|
+
* - **Smoothing runs only while it has somewhere to go.** With `scrub: <seconds>`
|
|
18
|
+
* a frame loop eases the playhead toward the scroll position and stops once it
|
|
19
|
+
* arrives; the next scroll starts it again.
|
|
20
|
+
* - **Pinning uses the browser's sticky positioning** (see `scroll-pin.ts`), so
|
|
21
|
+
* nothing is written per frame to hold an element in place.
|
|
22
|
+
*
|
|
23
|
+
* The engine is untouched — from its point of view this is just a caller of
|
|
24
|
+
* `seek()`. Without a `timeline` the driver only reports progress and fires its
|
|
25
|
+
* callbacks, for callers that decide what scrolling does.
|
|
26
|
+
*/
|
|
27
|
+
export interface ScrollDriverOptions {
|
|
28
|
+
/** The timeline to scrub. Optional: without one, only progress and callbacks. */
|
|
29
|
+
timeline?: Timeline;
|
|
30
|
+
/** Element whose position defines the range */
|
|
31
|
+
trigger: Element;
|
|
32
|
+
/**
|
|
33
|
+
* Where the range begins, as `"<element edge> <viewport edge>"`
|
|
34
|
+
* (default: `'top bottom'` — when the element's top reaches the viewport's bottom).
|
|
35
|
+
*/
|
|
36
|
+
start?: TriggerPosition | (() => TriggerPosition);
|
|
37
|
+
/**
|
|
38
|
+
* Where it ends (default: `'bottom top'`). `'+=600'` means 600px of scrolling
|
|
39
|
+
* after the start, and `'+=150%'` one and a half viewport heights. A function
|
|
40
|
+
* (for either) is called again on every refresh, so it can depend on layout.
|
|
41
|
+
*/
|
|
42
|
+
end?: TriggerPosition | (() => TriggerPosition);
|
|
43
|
+
/**
|
|
44
|
+
* `true` maps scroll position to time exactly (snappy, frame-accurate).
|
|
45
|
+
* A number smooths the playhead toward its target over that many seconds.
|
|
46
|
+
*/
|
|
47
|
+
scrub?: boolean | number;
|
|
48
|
+
/**
|
|
49
|
+
* Hold an element in place while scrolling through the range: `true` pins the
|
|
50
|
+
* trigger. Content after it is pushed down by the pinned distance.
|
|
51
|
+
*/
|
|
52
|
+
pin?: boolean | Element;
|
|
53
|
+
/**
|
|
54
|
+
* `false` pins without pushing the content after the pin down, so it scrolls up
|
|
55
|
+
* underneath (GSAP's `pinSpacing: false`). Default `true`.
|
|
56
|
+
*/
|
|
57
|
+
pinSpacing?: boolean;
|
|
58
|
+
/** Scroll container (default: the window) */
|
|
59
|
+
scroller?: HTMLElement | null;
|
|
60
|
+
/**
|
|
61
|
+
* The scroller scrolls sideways: positions use `left` / `right` edges, progress
|
|
62
|
+
* follows `scrollLeft`, and pins hold horizontally. Default `false`.
|
|
63
|
+
*/
|
|
64
|
+
horizontal?: boolean;
|
|
65
|
+
/**
|
|
66
|
+
* After scrolling stops inside the range, scroll on to the nearest point: a
|
|
67
|
+
* progress step (`0.25`), a list of progress points, a function, or
|
|
68
|
+
* `{ snapTo, duration, delay, ease }`.
|
|
69
|
+
*/
|
|
70
|
+
snap?: SnapOption;
|
|
71
|
+
/** Show start and end markers while developing */
|
|
72
|
+
markers?: boolean | MarkerOptions;
|
|
73
|
+
/**
|
|
74
|
+
* For a trigger inside a horizontally moving container (a pinned section whose
|
|
75
|
+
* track slides sideways): the container's scroll range, its current progress, and
|
|
76
|
+
* how far it has moved the trigger along x at a progress. Start and end then use
|
|
77
|
+
* horizontal edges (`'left right'`, the defaults, to `'right left'`).
|
|
78
|
+
*/
|
|
79
|
+
container?: ContainerAxis;
|
|
80
|
+
/**
|
|
81
|
+
* Called when progress (0..1) or velocity changes. Velocity is the scroll speed
|
|
82
|
+
* in pixels per second, positive scrolling down; it drops back to 0 shortly
|
|
83
|
+
* after scrolling stops, with one last call.
|
|
84
|
+
*/
|
|
85
|
+
onUpdate?: (progress: number, velocity: number) => void;
|
|
86
|
+
/**
|
|
87
|
+
* Called at the start of every refresh after the first, before anything is
|
|
88
|
+
* measured — where an animation rebuilds for the new layout.
|
|
89
|
+
*/
|
|
90
|
+
onRefresh?: () => void;
|
|
91
|
+
/** Scrolled into the active range, going down */
|
|
92
|
+
onEnter?: () => void;
|
|
93
|
+
/** Scrolled out of the active range, going down */
|
|
94
|
+
onLeave?: () => void;
|
|
95
|
+
/** Scrolled back into the active range, going up */
|
|
96
|
+
onEnterBack?: () => void;
|
|
97
|
+
/** Scrolled back out of the active range, going up */
|
|
98
|
+
onLeaveBack?: () => void;
|
|
99
|
+
}
|
|
100
|
+
export interface ContainerAxis {
|
|
101
|
+
range(): {
|
|
102
|
+
start: number;
|
|
103
|
+
end: number;
|
|
104
|
+
};
|
|
105
|
+
progress(): number;
|
|
106
|
+
shiftAt(progress: number): number;
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* Things that move elements by scroll position (a smooth scroller's parallax
|
|
110
|
+
* layers) and so must stand still while ranges are measured, then measure again
|
|
111
|
+
* once pins have changed the layout.
|
|
112
|
+
*/
|
|
113
|
+
export interface ScrollRefreshListener {
|
|
114
|
+
beforeRefresh(): void;
|
|
115
|
+
afterRefresh(): void;
|
|
116
|
+
}
|
|
117
|
+
export declare class ScrollDriver implements Driver {
|
|
118
|
+
private readonly timeline?;
|
|
119
|
+
private readonly options;
|
|
120
|
+
private running;
|
|
121
|
+
private pin;
|
|
122
|
+
/** The range, as absolute scroll offsets. */
|
|
123
|
+
private startPx;
|
|
124
|
+
private endPx;
|
|
125
|
+
/** Progress the page is actually at */
|
|
126
|
+
private targetProgress;
|
|
127
|
+
/** Progress the playhead is showing (differs from target only while smoothing) */
|
|
128
|
+
private displayProgress;
|
|
129
|
+
private zone;
|
|
130
|
+
/** Until the first measurement, smoothing starts at the page's position rather than easing from 0. */
|
|
131
|
+
private measured;
|
|
132
|
+
private lastScroll;
|
|
133
|
+
private lastScrollTime;
|
|
134
|
+
private velocityPxPerSecond;
|
|
135
|
+
private idleTimer;
|
|
136
|
+
private lastEmitted;
|
|
137
|
+
private rafId;
|
|
138
|
+
private lastFrameTime;
|
|
139
|
+
private readonly onScroll;
|
|
140
|
+
/** Speed when scrolling last stopped, for choosing a snap point */
|
|
141
|
+
private releaseVelocity;
|
|
142
|
+
private readonly snapper;
|
|
143
|
+
private snapTimer;
|
|
144
|
+
private markers;
|
|
145
|
+
private markerGeometry;
|
|
146
|
+
constructor(options: ScrollDriverOptions);
|
|
147
|
+
start(): void;
|
|
148
|
+
stop(): void;
|
|
149
|
+
/** Stop, and remove any pin spacer. */
|
|
150
|
+
destroy(): void;
|
|
151
|
+
/** The range's start and end, as scroll offsets. */
|
|
152
|
+
get startOffset(): number;
|
|
153
|
+
get endOffset(): number;
|
|
154
|
+
/**
|
|
155
|
+
* Re-measure every started driver, in the order they started. Call after a
|
|
156
|
+
* layout change a resize would not catch (images or fonts loading).
|
|
157
|
+
*/
|
|
158
|
+
static refreshAll(): void;
|
|
159
|
+
/** Be told around every re-measure; returns a function that stops it. */
|
|
160
|
+
static onRefresh(listener: ScrollRefreshListener): () => void;
|
|
161
|
+
/** Current scroll progress, 0..1. */
|
|
162
|
+
get progress(): number;
|
|
163
|
+
/** Scroll speed in pixels per second (0 once scrolling has stopped). */
|
|
164
|
+
get velocity(): number;
|
|
165
|
+
/**
|
|
166
|
+
* Measure the page again and update. Resizes do this automatically (for every
|
|
167
|
+
* driver, in the order they started, so a pin above pushes the ones below);
|
|
168
|
+
* call it after changing layout yourself — images or fonts loading, content
|
|
169
|
+
* added above the trigger.
|
|
170
|
+
*/
|
|
171
|
+
refresh(): void;
|
|
172
|
+
/** Same as `refresh()`. */
|
|
173
|
+
sample(): void;
|
|
174
|
+
/**
|
|
175
|
+
* Update from the current scroll position, or from `scrollPosition` when a
|
|
176
|
+
* smooth-scrolling library (or anything else) owns the scroll value. Costs no
|
|
177
|
+
* layout reads.
|
|
178
|
+
*/
|
|
179
|
+
update(scrollPosition?: number): void;
|
|
180
|
+
private updateFrom;
|
|
181
|
+
/** Seconds of smoothing, or 0 for exact tracking. */
|
|
182
|
+
private smoothing;
|
|
183
|
+
private resolveEnd;
|
|
184
|
+
private applyProgress;
|
|
185
|
+
private emitUpdate;
|
|
186
|
+
private trackVelocity;
|
|
187
|
+
/**
|
|
188
|
+
* Emit enter/leave callbacks as the scroll position moves between zones. A jump
|
|
189
|
+
* straight across the range (a fast flick, or loading the page scrolled past
|
|
190
|
+
* it) fires both edges in order.
|
|
191
|
+
*/
|
|
192
|
+
private fireBoundaryCallbacks;
|
|
193
|
+
/** Scrolling has stopped: settle on the nearest snap point, if there is one. */
|
|
194
|
+
private scheduleSnap;
|
|
195
|
+
private scrollTo;
|
|
196
|
+
/**
|
|
197
|
+
* Resolve start and end for a trigger inside a horizontally moving container:
|
|
198
|
+
* find the container progress where each horizontal position fires, and turn
|
|
199
|
+
* it into the container's scroll offsets.
|
|
200
|
+
*/
|
|
201
|
+
private measureInContainer;
|
|
202
|
+
/** Where the markers go: the element points on the page, and the viewport lines they meet. */
|
|
203
|
+
private markersFor;
|
|
204
|
+
private startSmoothing;
|
|
205
|
+
private stopSmoothing;
|
|
206
|
+
private scrollTarget;
|
|
207
|
+
private scrollPosition;
|
|
208
|
+
private triggerRect;
|
|
209
|
+
/**
|
|
210
|
+
* A viewport rect along the scroll axis, relative to the scroll container when
|
|
211
|
+
* there is one. Horizontal scrolling reports left / right / width as top / bottom / height.
|
|
212
|
+
*/
|
|
213
|
+
private relativeRect;
|
|
214
|
+
/** The viewport's size along the scroll axis. */
|
|
215
|
+
private viewportHeight;
|
|
216
|
+
}
|
|
217
|
+
/** Convenience wrapper: create a started ScrollDriver. */
|
|
218
|
+
export declare function scrubOnScroll(options: ScrollDriverOptions): ScrollDriver;
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Development markers for a scroll driver: where its range starts and ends.
|
|
3
|
+
*
|
|
4
|
+
* Two lines are fixed to the viewport (the scroller's start and end lines: "the
|
|
5
|
+
* trigger fires when the element point reaches here"), and two sit on the page
|
|
6
|
+
* where the element points are (start and end). The range is active while
|
|
7
|
+
* each page marker is past its viewport line. Turn them off before shipping.
|
|
8
|
+
*/
|
|
9
|
+
export interface MarkerOptions {
|
|
10
|
+
startColor?: string;
|
|
11
|
+
endColor?: string;
|
|
12
|
+
fontSize?: string;
|
|
13
|
+
/** Pixels from the right edge, so several drivers' markers can sit side by side */
|
|
14
|
+
indent?: number;
|
|
15
|
+
/** Prefix for the labels, e.g. the section's name */
|
|
16
|
+
id?: string;
|
|
17
|
+
}
|
|
18
|
+
/** Geometry the driver hands over on each refresh. */
|
|
19
|
+
export interface MarkerGeometry {
|
|
20
|
+
/** Page offsets (document pixels) of the element points at the start and end */
|
|
21
|
+
startPage: number;
|
|
22
|
+
endPage: number;
|
|
23
|
+
/** Offsets within the viewport (or scroller) where those points fire */
|
|
24
|
+
startViewport: number;
|
|
25
|
+
endViewport: number;
|
|
26
|
+
}
|
|
27
|
+
export declare class ScrollMarkers {
|
|
28
|
+
private readonly options;
|
|
29
|
+
private readonly scroller;
|
|
30
|
+
private readonly nodes;
|
|
31
|
+
private readonly scrollerStart;
|
|
32
|
+
private readonly scrollerEnd;
|
|
33
|
+
private readonly start;
|
|
34
|
+
private readonly end;
|
|
35
|
+
constructor(doc: Document, scroller: HTMLElement | null, options: MarkerOptions | true);
|
|
36
|
+
/** Place the markers for the latest measurement. */
|
|
37
|
+
place(geometry: MarkerGeometry, scrollOffset: number): void;
|
|
38
|
+
/** Keep the viewport lines in place inside a scrolling element. */
|
|
39
|
+
follow(geometry: MarkerGeometry, scrollOffset: number): void;
|
|
40
|
+
destroy(): void;
|
|
41
|
+
}
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure scroll-position maths.
|
|
3
|
+
*
|
|
4
|
+
* Every DOM read lives in `scroll-driver.ts`; this module takes plain rectangles
|
|
5
|
+
* and returns numbers, so the tricky part — resolving GSAP-style trigger strings
|
|
6
|
+
* into pixel offsets — is unit-testable without a browser.
|
|
7
|
+
*/
|
|
8
|
+
/** A rectangle in viewport coordinates, matching the fields of a DOMRect. */
|
|
9
|
+
export interface Rect {
|
|
10
|
+
top: number;
|
|
11
|
+
bottom: number;
|
|
12
|
+
height: number;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Where a trigger fires, as `"<element edge> <viewport edge>"`.
|
|
16
|
+
*
|
|
17
|
+
* `"top bottom"` means "when the element's top reaches the viewport's bottom".
|
|
18
|
+
* Also accepts a bare percentage (`"50%"` of the element), a bare number
|
|
19
|
+
* (pixels from the element's top), or a relative offset appended to either
|
|
20
|
+
* (`"top bottom+=100"`).
|
|
21
|
+
*/
|
|
22
|
+
export type TriggerPosition = string | number;
|
|
23
|
+
/** Parse one edge token into a 0..1 fraction. Accepts keywords and percentages. */
|
|
24
|
+
export declare function parseEdge(token: string): number | undefined;
|
|
25
|
+
/** A parsed trigger position, before it is resolved against real geometry. */
|
|
26
|
+
export interface ParsedTrigger {
|
|
27
|
+
/** Fraction down the element (0 = its top, 1 = its bottom) */
|
|
28
|
+
elementFraction: number;
|
|
29
|
+
/** Fraction down the viewport (0 = its top, 1 = its bottom) */
|
|
30
|
+
viewportFraction: number;
|
|
31
|
+
/** Extra pixels added after both fractions resolve */
|
|
32
|
+
offsetPx: number;
|
|
33
|
+
/** Absolute pixel offset from the element's top, when given as a bare number */
|
|
34
|
+
absolutePx?: number;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Parse a trigger string into its parts.
|
|
38
|
+
*
|
|
39
|
+
* Grammar: `<elementEdge> <viewportEdge>` with an optional `+=n` / `-=n` on
|
|
40
|
+
* either token. A single token is read as the element edge with the viewport
|
|
41
|
+
* edge defaulting to `top`, which matches ScrollTrigger's shorthand.
|
|
42
|
+
*/
|
|
43
|
+
export declare function parseTrigger(position: TriggerPosition): ParsedTrigger;
|
|
44
|
+
/**
|
|
45
|
+
* Scroll distance from where the page is now to where the trigger fires.
|
|
46
|
+
*
|
|
47
|
+
* Positive means the trigger is still ahead (below the fold). This is expressed
|
|
48
|
+
* relative to the current scroll position, so the caller never has to know the
|
|
49
|
+
* document's absolute geometry.
|
|
50
|
+
*/
|
|
51
|
+
export declare function triggerDistance(rect: Rect, viewportHeight: number, position: TriggerPosition): number;
|
|
52
|
+
/**
|
|
53
|
+
* How far between `start` and `end` the page has scrolled, as 0..1.
|
|
54
|
+
*
|
|
55
|
+
* Returns 0 before the start trigger and 1 after the end trigger, so a driver
|
|
56
|
+
* can hold the timeline at either extreme without special-casing.
|
|
57
|
+
*/
|
|
58
|
+
export declare function scrollProgress(rect: Rect, viewportHeight: number, start: TriggerPosition, end: TriggerPosition): number;
|
|
59
|
+
/**
|
|
60
|
+
* Clamp a number into 0..1.
|
|
61
|
+
*
|
|
62
|
+
* Normalises -0 to 0: dividing a zero numerator by a positive span yields -0,
|
|
63
|
+
* which compares equal to 0 but prints differently and survives into serialized
|
|
64
|
+
* output, so it is easiest to remove at the source.
|
|
65
|
+
*/
|
|
66
|
+
export declare function clamp01(value: number): number;
|
|
67
|
+
/**
|
|
68
|
+
* Move `current` toward `target` by a fixed time constant — the smoothing
|
|
69
|
+
* behind `scrub: <seconds>`.
|
|
70
|
+
*
|
|
71
|
+
* Exponential approach rather than a fixed step, so the result is stable across
|
|
72
|
+
* frame rates. Note it is still frame-rate *dependent* in the sense that it
|
|
73
|
+
* depends on elapsed time; `scrub: true` (no smoothing) is the exact path.
|
|
74
|
+
*/
|
|
75
|
+
export declare function smoothToward(current: number, target: number, smoothingSeconds: number, deltaMs: number): number;
|
|
76
|
+
/**
|
|
77
|
+
* For a trigger inside a horizontally moving container (a pinned section whose
|
|
78
|
+
* track slides sideways as the page scrolls): the container progress at which a
|
|
79
|
+
* horizontal trigger position fires.
|
|
80
|
+
*
|
|
81
|
+
* `left` and `width` are the trigger's box at container progress 0, `shiftAt(p)`
|
|
82
|
+
* is how far the container has moved it along x at progress p (usually negative
|
|
83
|
+
* and decreasing), and `viewportWidth` is the visible width. Positions use the
|
|
84
|
+
* same grammar as vertical ones, with `left` / `center` / `right` edges.
|
|
85
|
+
* Solved by bisection, so the container's motion only needs to be monotonic.
|
|
86
|
+
*/
|
|
87
|
+
export declare function containerProgressAt(left: number, width: number, viewportWidth: number, position: TriggerPosition, shiftAt: (progress: number) => number): number;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pinning: hold an element in place while the page scrolls through a range.
|
|
3
|
+
*
|
|
4
|
+
* This automates the `position: sticky` recipe rather than repositioning the
|
|
5
|
+
* element on every scroll event:
|
|
6
|
+
*
|
|
7
|
+
* <div class="pin-spacer" style="height: <element height + pin distance>">
|
|
8
|
+
* <section style="position: sticky; top: <where it pins>">…</section>
|
|
9
|
+
* </div>
|
|
10
|
+
*
|
|
11
|
+
* The spacer takes the element's place in the layout and is exactly as tall as
|
|
12
|
+
* the element plus the distance it stays pinned, so the content after it is
|
|
13
|
+
* pushed down by that distance (GSAP's pin spacing), and the browser's own
|
|
14
|
+
* sticky positioning does the holding — nothing is written while scrolling.
|
|
15
|
+
*
|
|
16
|
+
* The usual sticky caveat applies: an ancestor between the element and the
|
|
17
|
+
* scroller with `overflow: hidden`/`auto` stops it sticking.
|
|
18
|
+
*/
|
|
19
|
+
export interface ScrollPinOptions {
|
|
20
|
+
/** `'x'` pins in a sideways-scrolling container (sticky `left`). Default `'y'`. */
|
|
21
|
+
axis?: 'x' | 'y';
|
|
22
|
+
/**
|
|
23
|
+
* `false`: the spacer gives back the pinned distance with a negative margin, so
|
|
24
|
+
* content after the pin scrolls up underneath it instead of waiting. Default `true`.
|
|
25
|
+
*/
|
|
26
|
+
spacing?: boolean;
|
|
27
|
+
}
|
|
28
|
+
export declare class ScrollPin {
|
|
29
|
+
readonly element: HTMLElement;
|
|
30
|
+
readonly spacer: HTMLElement;
|
|
31
|
+
private readonly saved;
|
|
32
|
+
private readonly axis;
|
|
33
|
+
private readonly spacing;
|
|
34
|
+
constructor(element: HTMLElement, options?: ScrollPinOptions);
|
|
35
|
+
/**
|
|
36
|
+
* Put the element back in the flow for measuring: unstuck, at the top of its
|
|
37
|
+
* spacer, which is where it sits without pinning. The spacer keeps its height,
|
|
38
|
+
* so the page does not change length and the scroll position is not clamped.
|
|
39
|
+
*/
|
|
40
|
+
release(): void;
|
|
41
|
+
/** Stick at `topPx` from the scroller's top for `distancePx` of scrolling. */
|
|
42
|
+
apply(topPx: number, distancePx: number): void;
|
|
43
|
+
/** Remove the spacer and restore the element's own styles. */
|
|
44
|
+
destroy(): void;
|
|
45
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { type EasingFunction } from '../engine';
|
|
2
|
+
/**
|
|
3
|
+
* Snapping: once scrolling stops inside a trigger's range, scroll on to the
|
|
4
|
+
* nearest snap point — a section boundary, a label, a step.
|
|
5
|
+
*
|
|
6
|
+
* The choice is pure maths (`snapProgress`). The scrolling is the one place a
|
|
7
|
+
* driver writes to the page, so it is kept small and polite: it animates the
|
|
8
|
+
* scroll offset for a short time and stops the moment the person scrolls,
|
|
9
|
+
* touches, clicks or presses a key.
|
|
10
|
+
*/
|
|
11
|
+
/** Where to snap: a step (`0.25`), the points themselves, or a function choosing one. */
|
|
12
|
+
export type SnapTo = number | number[] | ((progress: number) => number);
|
|
13
|
+
export interface SnapConfig {
|
|
14
|
+
snapTo: SnapTo;
|
|
15
|
+
/** Seconds, or a range scaled by distance (default `{ min: 0.2, max: 0.8 }`) */
|
|
16
|
+
duration?: number | {
|
|
17
|
+
min: number;
|
|
18
|
+
max: number;
|
|
19
|
+
};
|
|
20
|
+
/** Seconds to wait after scrolling stops (default 0) */
|
|
21
|
+
delay?: number;
|
|
22
|
+
/** Default ease-in-out */
|
|
23
|
+
ease?: EasingFunction;
|
|
24
|
+
}
|
|
25
|
+
export type SnapOption = SnapTo | SnapConfig;
|
|
26
|
+
export declare function snapConfig(option: SnapOption): SnapConfig;
|
|
27
|
+
/**
|
|
28
|
+
* The progress to settle at, from where scrolling stopped. `velocity` is progress
|
|
29
|
+
* per second as scrolling slowed down: a flick carries on toward the next point
|
|
30
|
+
* rather than falling back to the one it left.
|
|
31
|
+
*/
|
|
32
|
+
export declare function snapProgress(progress: number, velocity: number, snapTo: SnapTo): number;
|
|
33
|
+
/** Seconds to spend covering `distancePx`: longer for longer distances, within the range. */
|
|
34
|
+
export declare function snapDuration(config: SnapConfig, distancePx: number, viewportPx: number): number;
|
|
35
|
+
/** Animates a scroll offset, and gives way to the person scrolling. */
|
|
36
|
+
export declare class ScrollAnimator {
|
|
37
|
+
private rafId;
|
|
38
|
+
private readonly cancelEvents;
|
|
39
|
+
private readonly onInterrupt;
|
|
40
|
+
private readonly write;
|
|
41
|
+
private readonly eventTarget;
|
|
42
|
+
constructor(write: (offset: number) => void, eventTarget: EventTarget | null);
|
|
43
|
+
get active(): boolean;
|
|
44
|
+
animate(from: number, to: number, seconds: number, ease?: EasingFunction, onDone?: () => void): void;
|
|
45
|
+
cancel(): void;
|
|
46
|
+
private detach;
|
|
47
|
+
}
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Smooth scrolling without moving the page into a transformed wrapper.
|
|
3
|
+
*
|
|
4
|
+
* Wheel scrolling is intercepted and eased toward its destination, but the
|
|
5
|
+
* browser's own scroll position is what moves — `window.scrollY` (or the
|
|
6
|
+
* scroller's `scrollTop`) follows the eased value each frame. So everything that
|
|
7
|
+
* reads the scroll position keeps working unchanged: `ScrollDriver` ranges,
|
|
8
|
+
* sticky pins, `position: fixed`, anchor links, find-in-page and scroll
|
|
9
|
+
* restoration. Touch, keyboard and scrollbar scrolling stay native; when they move
|
|
10
|
+
* the page, smoothing picks up from wherever it is.
|
|
11
|
+
*
|
|
12
|
+
* const smooth = new SmoothScroll({ smooth: 1, effects: true })
|
|
13
|
+
* smooth.start()
|
|
14
|
+
* smooth.scrollTo('#contact')
|
|
15
|
+
*
|
|
16
|
+
* **Effects.** Elements with `data-speed` scroll at that fraction of the page's
|
|
17
|
+
* speed (`0.5` half, `1.5` faster), sitting at their natural place when centred in
|
|
18
|
+
* the viewport. Elements with `data-lag` (seconds) catch up with the page after
|
|
19
|
+
* it moves. Both are written to the CSS `translate` property, so they compose
|
|
20
|
+
* with animated `transform`s on the same element.
|
|
21
|
+
*
|
|
22
|
+
* With `prefers-reduced-motion: reduce` there is no smoothing and no effects.
|
|
23
|
+
*/
|
|
24
|
+
import { type EasingFunction } from '../engine';
|
|
25
|
+
export interface SmoothScrollFrames {
|
|
26
|
+
request(callback: (timestamp: number) => void): number;
|
|
27
|
+
cancel(id: number): void;
|
|
28
|
+
}
|
|
29
|
+
export interface SmoothScrollOptions {
|
|
30
|
+
/** Scrolling element (default: the window) */
|
|
31
|
+
scroller?: HTMLElement | null;
|
|
32
|
+
/** Seconds to catch up with the wheel — larger is smoother and later. Default 0.8; 0 turns smoothing off. */
|
|
33
|
+
smooth?: number;
|
|
34
|
+
/** Multiplies wheel distance. Default 1. */
|
|
35
|
+
wheelMultiplier?: number;
|
|
36
|
+
/** Parallax effects: `true` for `[data-speed], [data-lag]`, or your own selector. Default false. */
|
|
37
|
+
effects?: boolean | string;
|
|
38
|
+
/** Force reduced motion on or off; by default `prefers-reduced-motion` is asked. */
|
|
39
|
+
reducedMotion?: boolean;
|
|
40
|
+
/** After each frame the position changed */
|
|
41
|
+
onUpdate?: (self: SmoothScrollState) => void;
|
|
42
|
+
/** Frame scheduling (default requestAnimationFrame); tests pass a manual one. */
|
|
43
|
+
frames?: SmoothScrollFrames;
|
|
44
|
+
}
|
|
45
|
+
export interface SmoothScrollState {
|
|
46
|
+
/** Scroll offset the page shows, px */
|
|
47
|
+
scroll: number;
|
|
48
|
+
/** Where smoothing is heading, px */
|
|
49
|
+
target: number;
|
|
50
|
+
/** 0..1 through the scrollable length */
|
|
51
|
+
progress: number;
|
|
52
|
+
/** px/s, positive scrolling down */
|
|
53
|
+
velocity: number;
|
|
54
|
+
}
|
|
55
|
+
export interface ScrollToOptions {
|
|
56
|
+
/** Seconds for the trip (default: from distance, 0.4–1.2s). 0 jumps. */
|
|
57
|
+
duration?: number;
|
|
58
|
+
/** Added to the destination, px (e.g. `-80` for a fixed header) */
|
|
59
|
+
offset?: number;
|
|
60
|
+
ease?: EasingFunction;
|
|
61
|
+
}
|
|
62
|
+
export declare class SmoothScroll {
|
|
63
|
+
private readonly options;
|
|
64
|
+
private readonly frames;
|
|
65
|
+
private running;
|
|
66
|
+
private reduced;
|
|
67
|
+
private current;
|
|
68
|
+
private target;
|
|
69
|
+
private written;
|
|
70
|
+
private velocityPxPerSecond;
|
|
71
|
+
private frameId;
|
|
72
|
+
private lastTime;
|
|
73
|
+
private journey;
|
|
74
|
+
private pausedState;
|
|
75
|
+
private effects;
|
|
76
|
+
private readonly onWheel;
|
|
77
|
+
private readonly onScroll;
|
|
78
|
+
private readonly onResize;
|
|
79
|
+
private readonly onLoad;
|
|
80
|
+
/** Scroll triggers measure with effect layers at rest, and effects measure after pins. */
|
|
81
|
+
private stopListening;
|
|
82
|
+
constructor(options?: SmoothScrollOptions);
|
|
83
|
+
start(): this;
|
|
84
|
+
/** Re-measure every started smoother, after layout changes a resize would not catch. */
|
|
85
|
+
static refreshAll(): void;
|
|
86
|
+
stop(): this;
|
|
87
|
+
/** Stop, and put every effect element back where it was. */
|
|
88
|
+
destroy(): void;
|
|
89
|
+
/** GSAP's name for `destroy()`. */
|
|
90
|
+
kill(): void;
|
|
91
|
+
get state(): SmoothScrollState;
|
|
92
|
+
/** Stop responding to the wheel (e.g. while a modal is open); `paused(false)` resumes. */
|
|
93
|
+
paused(value?: boolean): boolean;
|
|
94
|
+
/**
|
|
95
|
+
* Scroll to an offset, an element or a selector, eased. Wheel input during the
|
|
96
|
+
* trip takes over from wherever it has got to.
|
|
97
|
+
*/
|
|
98
|
+
scrollTo(destination: number | string | Element, options?: ScrollToOptions): void;
|
|
99
|
+
/** Re-measure the scrollable length and every effect element (resizes do this). */
|
|
100
|
+
refresh(): void;
|
|
101
|
+
/** Put effect elements at their natural place, for measuring. */
|
|
102
|
+
private rest;
|
|
103
|
+
private wheel;
|
|
104
|
+
/** A scroll that this smoother did not write: follow it. */
|
|
105
|
+
private nativeScroll;
|
|
106
|
+
private nestedScrollerTakes;
|
|
107
|
+
private requestFrame;
|
|
108
|
+
private cancelFrame;
|
|
109
|
+
private frame;
|
|
110
|
+
/** Position every effect for the current scroll; true while a lag is still catching up. */
|
|
111
|
+
private applyEffects;
|
|
112
|
+
private write;
|
|
113
|
+
private position;
|
|
114
|
+
private viewportHeight;
|
|
115
|
+
private limit;
|
|
116
|
+
private clamp;
|
|
117
|
+
private resolve;
|
|
118
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { Timeline } from '../engine';
|
|
2
|
+
/**
|
|
3
|
+
* A driver decides *when* a timeline advances and *to what time*.
|
|
4
|
+
*
|
|
5
|
+
* The engine is a pure function of time; drivers are the boundary where
|
|
6
|
+
* real-world input (a clock, a scroll position, a pointer) becomes a time. They
|
|
7
|
+
* may touch the DOM — the engine must never import one.
|
|
8
|
+
*/
|
|
9
|
+
export interface Driver {
|
|
10
|
+
/** Begin observing. Safe to call twice. */
|
|
11
|
+
start(): void;
|
|
12
|
+
/** Stop observing and release listeners. Safe to call twice. */
|
|
13
|
+
stop(): void;
|
|
14
|
+
/** Stop, and drop every reference. The driver cannot be restarted. */
|
|
15
|
+
destroy(): void;
|
|
16
|
+
}
|
|
17
|
+
/** Options shared by drivers that advance a timeline. */
|
|
18
|
+
export interface DriverOptions {
|
|
19
|
+
/** The timeline to drive */
|
|
20
|
+
timeline: Timeline;
|
|
21
|
+
/** Called after each advance, so the host can render */
|
|
22
|
+
onUpdate?: (timeline: Timeline) => void;
|
|
23
|
+
}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import type { Timeline } from '../engine';
|
|
2
|
+
import type { Driver } from './types';
|
|
3
|
+
/**
|
|
4
|
+
* Plays a timeline when its trigger element scrolls into view.
|
|
5
|
+
*
|
|
6
|
+
* This covers the single most common scroll-related request — "animate it when
|
|
7
|
+
* it appears" — without any of the geometry that scrubbing needs. If you want
|
|
8
|
+
* the animation tied to scroll *position*, use `ScrollDriver` instead.
|
|
9
|
+
*/
|
|
10
|
+
export type VisibilityBehaviour =
|
|
11
|
+
/** Play the first time it appears, then never again (default) */
|
|
12
|
+
'once'
|
|
13
|
+
/** Play every time it appears */
|
|
14
|
+
| 'repeat'
|
|
15
|
+
/** Play on appear, and rewind to the start when it leaves */
|
|
16
|
+
| 'reset';
|
|
17
|
+
export interface VisibilityDriverOptions {
|
|
18
|
+
/** The timeline to play */
|
|
19
|
+
timeline: Timeline;
|
|
20
|
+
/** Element whose visibility gates playback */
|
|
21
|
+
trigger: Element;
|
|
22
|
+
/** What to do on each appearance (default: 'once') */
|
|
23
|
+
behaviour?: VisibilityBehaviour;
|
|
24
|
+
/**
|
|
25
|
+
* Fraction of the element that must be visible to count as "in view", 0..1
|
|
26
|
+
* (default: 0.15). Passed straight to IntersectionObserver.
|
|
27
|
+
*/
|
|
28
|
+
threshold?: number;
|
|
29
|
+
/** Margin around the viewport, in CSS margin syntax (e.g. '0px 0px -10% 0px') */
|
|
30
|
+
rootMargin?: string;
|
|
31
|
+
/** Scroll container, when not the viewport */
|
|
32
|
+
root?: Element | null;
|
|
33
|
+
/** Called whenever the trigger enters the viewport */
|
|
34
|
+
onEnter?: () => void;
|
|
35
|
+
/** Called whenever the trigger leaves the viewport */
|
|
36
|
+
onLeave?: () => void;
|
|
37
|
+
}
|
|
38
|
+
export declare class VisibilityDriver implements Driver {
|
|
39
|
+
private timeline;
|
|
40
|
+
private trigger;
|
|
41
|
+
private behaviour;
|
|
42
|
+
private options;
|
|
43
|
+
private observer;
|
|
44
|
+
private hasPlayed;
|
|
45
|
+
private running;
|
|
46
|
+
constructor(options: VisibilityDriverOptions);
|
|
47
|
+
start(): void;
|
|
48
|
+
stop(): void;
|
|
49
|
+
destroy(): void;
|
|
50
|
+
/** Forget that the animation has played, so 'once' can fire again. */
|
|
51
|
+
reset(): void;
|
|
52
|
+
private enter;
|
|
53
|
+
private leave;
|
|
54
|
+
}
|
|
55
|
+
/** Convenience wrapper: create a started VisibilityDriver. */
|
|
56
|
+
export declare function playWhenVisible(options: VisibilityDriverOptions): VisibilityDriver;
|