@algorisys/tinyfly 0.92.0 → 0.94.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 +7 -6
- package/bin/tinyfly.mjs +34 -1
- package/docs/2d-animation-roadmap.md +191 -0
- package/docs/3d-rotations.md +164 -0
- package/docs/3d-support-plan.md +628 -0
- package/docs/DEPLOYMENT.md +414 -0
- package/docs/acting.md +529 -0
- package/docs/api-reference.md +2353 -0
- package/docs/camera.md +94 -0
- package/docs/cartoon-hands.md +96 -0
- package/docs/character-system-m1.md +218 -0
- package/docs/character-system-plan.md +384 -0
- package/docs/dance.md +315 -0
- package/docs/editor-guide.md +1249 -0
- package/docs/examples.md +765 -0
- package/docs/extending.md +168 -0
- package/docs/file-format.md +690 -0
- package/docs/getting-started.md +314 -0
- package/docs/grid-and-snapping.md +64 -0
- package/docs/gsap-compat.md +1241 -0
- package/docs/llm-guide.md +131 -0
- package/docs/maps.md +116 -0
- package/docs/onion-skinning.md +41 -0
- package/docs/pen-tool.md +65 -0
- package/docs/polygon-star.md +44 -0
- package/docs/scene-3d.md +299 -0
- package/docs/scroll-animation.md +314 -0
- package/docs/shape-morph.md +61 -0
- package/docs/sprite-sheet-export.md +54 -0
- package/docs/symbols-and-library.md +137 -0
- package/docs/teaching.md +348 -0
- package/docs/video-rendering.md +728 -0
- package/lib/addons/adapters.js +22 -18
- package/lib/addons/characters.js +3045 -2024
- package/lib/addons/target-properties-BtN9skb-.js +142 -0
- package/lib/browser/tinyfly.iife.js +9 -4
- package/lib/browser/tinyfly.js +6968 -5817
- package/lib/browser/tinyfly.umd.js +9 -4
- package/lib/engine/tinyfly-engine.js +286 -258
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
- package/lib/types/characters/acting/beat-check.d.ts +102 -0
- package/lib/types/characters/acting/custom.d.ts +66 -0
- package/lib/types/characters/acting/gags.d.ts +10 -0
- package/lib/types/characters/acting/hand-path.d.ts +35 -0
- package/lib/types/characters/acting/index.d.ts +4 -0
- package/lib/types/characters/acting/persona.d.ts +93 -0
- package/lib/types/characters/acting/script.d.ts +75 -11
- package/lib/types/characters/capabilities.d.ts +61 -0
- package/lib/types/characters/code-panel.d.ts +201 -0
- package/lib/types/characters/figure-actions.d.ts +12 -0
- package/lib/types/characters/figure-props.d.ts +87 -0
- package/lib/types/characters/gaits.d.ts +8 -0
- package/lib/types/characters/index.d.ts +3 -0
- package/lib/types/characters/stick-figure.d.ts +9 -2
- package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
- package/lib/types/engine/authoring/index.d.ts +1 -0
- package/llms-full.txt +12631 -0
- package/llms.txt +57 -0
- package/package.json +6 -2
- package/skills/tinyfly/SKILL.md +67 -0
- package/lib/addons/camera-C7bZOWMB.js +0 -33
|
@@ -0,0 +1,1241 @@
|
|
|
1
|
+
# GSAP compatibility layer
|
|
2
|
+
|
|
3
|
+
`@algorisys/tinyfly/gsap-compat` gives GSAP-literate developers a syntax they recognise.
|
|
4
|
+
|
|
5
|
+
**It is familiar, not compatible.** GSAP code will not run unchanged against it,
|
|
6
|
+
and it is not a drop-in replacement. What it does is *desugar* a GSAP-shaped API
|
|
7
|
+
into ordinary tinyfly tracks: every call you make compiles to plain keyframe
|
|
8
|
+
data and is handed to a normal `Timeline`. Anything you author through it opens
|
|
9
|
+
in the editor, exports to JSON, and plays in the standard player.
|
|
10
|
+
|
|
11
|
+
If you want the full picture of what tinyfly can and cannot do relative to GSAP,
|
|
12
|
+
read ["What we deliberately don't do"](#what-we-deliberately-dont-do) at the
|
|
13
|
+
bottom — several of the gaps are principled choices, not missing work.
|
|
14
|
+
|
|
15
|
+
## Install and import
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { tf, timeline } from '@algorisys/tinyfly/gsap-compat'
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
The engine is a peer import, so you get one copy of `Timeline` whether you
|
|
22
|
+
import `tinyfly`, `@algorisys/tinyfly/gsap-compat`, or both.
|
|
23
|
+
|
|
24
|
+
## A first animation
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
import { timeline } from '@algorisys/tinyfly/gsap-compat'
|
|
28
|
+
import { quickPlay } from '@algorisys/tinyfly/gsap-compat'
|
|
29
|
+
|
|
30
|
+
const tl = timeline()
|
|
31
|
+
tl.fromTo('box', { x: 0, opacity: 0 }, { x: 200, opacity: 1, duration: 1, ease: 'power2.out' })
|
|
32
|
+
tl.to('box', { rotate: 180, duration: 0.5 }, '-=0.25')
|
|
33
|
+
|
|
34
|
+
quickPlay({ timeline: tl.timeline, targets: { box: '#my-box' } })
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`quickPlay` is worth knowing about on its own: it wires a timeline to the DOM
|
|
38
|
+
and runs the rAF loop, replacing the dozen lines of boilerplate every
|
|
39
|
+
hand-written tinyfly example starts with.
|
|
40
|
+
|
|
41
|
+
## Playing on real elements: `live`
|
|
42
|
+
|
|
43
|
+
> Thirty-three runnable demos are on the Examples page under **GSAP-style**
|
|
44
|
+
> (`/examples?category=gsap`), each with its code and **Copy code**: motion
|
|
45
|
+
> paths and orbits, shape and menu morphs, scrambled and typed text, dashboard
|
|
46
|
+
> stats, Flip layouts (shuffle, filter, layout switch, expand), draggable throws (slots, carousel, swipe cards), friction, stagger,
|
|
47
|
+
> labels, 3D card flips, composition, playback controls, baked eases, and
|
|
48
|
+
> interaction effects like a magnetic button, proximity grid, dock
|
|
49
|
+
> magnification, velocity skew, card stack, infinite marquee, split-text reveal
|
|
50
|
+
> and SVG line drawing.
|
|
51
|
+
>
|
|
52
|
+
> **Doing without `overwrite`.** Interactive effects start a new tween on every
|
|
53
|
+
> pointer move. Keep the returned timeline and `kill()` it before starting the
|
|
54
|
+
> next one on the same element (see *Proximity Grid*), so tweens never pile up.
|
|
55
|
+
|
|
56
|
+
`timeline()` and `tf` *compile*: targets are names, and playback is yours to
|
|
57
|
+
wire. `live` compiles the same way and then plays the result on the page:
|
|
58
|
+
|
|
59
|
+
```ts
|
|
60
|
+
import { live } from '@algorisys/tinyfly/gsap-compat'
|
|
61
|
+
|
|
62
|
+
live.to('.box', { x: 200, duration: 1, ease: 'power2.out' })
|
|
63
|
+
live.from('.card', { opacity: 0, y: 30, duration: 0.6, stagger: 0.1 })
|
|
64
|
+
|
|
65
|
+
const tl = live.timeline({ repeat: -1, yoyo: true })
|
|
66
|
+
.to('#a', { x: 120, duration: 0.5 })
|
|
67
|
+
.to('#b', { rotate: 180, duration: 0.5 }, '<')
|
|
68
|
+
|
|
69
|
+
tl.pause() // play, pause, resume, restart, reverse, seek, progress, timeScale, kill
|
|
70
|
+
tl.toDefinition() // the same plain JSON the compiler produces
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Without a build step, the all-in-one bundle exposes the same functions on a
|
|
74
|
+
global — `tinyfly.to()`, `tinyfly.timeline()` and so on:
|
|
75
|
+
|
|
76
|
+
```html
|
|
77
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.94.0/cdn/tinyfly.iife.js"></script>
|
|
78
|
+
<script>
|
|
79
|
+
tinyfly.to('.box', { x: 200, duration: 1 })
|
|
80
|
+
</script>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
What `live` adds, all of it runtime rather than compilation:
|
|
84
|
+
|
|
85
|
+
| | `timeline()` / `tf` | `live` |
|
|
86
|
+
|---|---|---|
|
|
87
|
+
| Targets | Names | CSS selectors, elements, node lists, or arrays of them |
|
|
88
|
+
| Many matches | — | A selector matching several elements animates all of them; `stagger` fans them out |
|
|
89
|
+
| Playback | You call `quickPlay` or drive `tick()` | Starts on the next microtask; `paused: true` opts out |
|
|
90
|
+
| Return value of `to()` etc. | A tween handle | The timeline, so calls chain |
|
|
91
|
+
| Tween-level `repeat`, `yoyo`, `onStart`, `onUpdate`, `onComplete` | On `timeline()` | Also accepted in `live.to(target, vars)` |
|
|
92
|
+
| Start value of a `to()` | Resolution chain | Resolution chain, with **the value tinyfly last applied to that element** inserted before `defaults` |
|
|
93
|
+
|
|
94
|
+
**Autoplay waits a microtask** so every tween chained synchronously onto a
|
|
95
|
+
timeline is in place before it starts. Calling `play`, `pause`, `seek` or
|
|
96
|
+
`progress` before then takes control, and autoplay is cancelled.
|
|
97
|
+
|
|
98
|
+
**Concurrent animations compose.** Every `live` animation shares one frame loop
|
|
99
|
+
and one DOM adapter, which merges values per element before writing. So
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
live.to('#box', { x: 200, duration: 1 })
|
|
103
|
+
live.to('#box', { rotate: 90, duration: 1 })
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
moves *and* turns the box. (Two separate `quickPlay` calls would each write a
|
|
107
|
+
`transform` missing the other's property.) When two animations drive the *same*
|
|
108
|
+
property at the same time, the one played most recently wins. A finished
|
|
109
|
+
animation's final values are kept, so later tweens compose with them and start
|
|
110
|
+
from them.
|
|
111
|
+
|
|
112
|
+
**Tweens read the DOM once, when they are built — never per frame.** The start
|
|
113
|
+
value `live` adds comes from what tinyfly last applied. Beyond that, a tween
|
|
114
|
+
reads the page only where GSAP's option names something on the page: a shape's
|
|
115
|
+
current path (`morphSVG`), an element's current text (`text`, `scrambleText`),
|
|
116
|
+
and a path's geometry and the follower's layout (`motionPath` with `align`).
|
|
117
|
+
Whatever it reads is written into the compiled tracks as plain values, so the
|
|
118
|
+
JSON still describes the animation completely. It never reads
|
|
119
|
+
`getComputedStyle`: an element styled by CSS alone starts numeric and colour
|
|
120
|
+
properties from the static defaults, so use `fromTo` for the first tween on
|
|
121
|
+
those.
|
|
122
|
+
|
|
123
|
+
Two features measure the page by design, outside that rule. [Flip](#flip)
|
|
124
|
+
measures layout once per `getFlipState` call and once per `flipFrom` call (which
|
|
125
|
+
`live.flip` makes one each of). `live.draggable` re-measures an element `bounds`
|
|
126
|
+
on each press and follows pointer events for the whole drag. Both still hand the
|
|
127
|
+
engine plain values: Flip compiles to ordinary tweens, and a throw is an ordinary
|
|
128
|
+
inertia tween.
|
|
129
|
+
|
|
130
|
+
**Plain objects are targets too.** Pass any JavaScript object and its
|
|
131
|
+
properties are tweened and assigned straight back onto it — no element, no
|
|
132
|
+
adapter. That is how a canvas, a Three.js scene or a shader uniform follows the
|
|
133
|
+
same timeline as the DOM:
|
|
134
|
+
|
|
135
|
+
```js
|
|
136
|
+
const scene = { radius: 30, color: '#4a9eff' }
|
|
137
|
+
live.to(scene, { radius: 90, color: '#ec4899', duration: 1.4, ease: 'expo.inOut' })
|
|
138
|
+
live.to(mesh.position, { x: 2, y: 1, duration: 1 }) // Three.js
|
|
139
|
+
live.to(material.uniforms.uProgress, { value: 1, duration: 2 })
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Each object starts from its own current values, read when the tween is built.
|
|
143
|
+
Numbers, colour strings and number arrays animate. Arrays and `NodeList`s are
|
|
144
|
+
lists of targets, not objects to animate. Objects and elements mix freely in one
|
|
145
|
+
timeline.
|
|
146
|
+
|
|
147
|
+
**The ticker** runs a callback every frame, after that frame's values are
|
|
148
|
+
applied, with GSAP's arguments — `time` in seconds since the ticker started,
|
|
149
|
+
`deltaTime` in milliseconds, and a `frame` counter:
|
|
150
|
+
|
|
151
|
+
```js
|
|
152
|
+
const render = (time, deltaTime, frame) => renderer.render(threeScene, camera)
|
|
153
|
+
live.ticker.add(render)
|
|
154
|
+
live.ticker.remove(render)
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
The frame loop keeps running while any callback is registered, even with no
|
|
158
|
+
animation playing, and stops when the last one is removed. In a script tag it is
|
|
159
|
+
`tinyfly.ticker`.
|
|
160
|
+
|
|
161
|
+
**Separate stages.** `createLive(new Stage())` gives an isolated loop and
|
|
162
|
+
adapter — useful for tests (pass a `scheduler`), or for a widget that should not
|
|
163
|
+
compose with the rest of the page. `new Stage({ root })` resolves selectors inside
|
|
164
|
+
`root` only. `stage.tick(ms)` drives it by hand.
|
|
165
|
+
|
|
166
|
+
**Warnings.** Mistakes that would otherwise do nothing quietly (a selector that
|
|
167
|
+
matches no elements, `drawSVG` on something that isn't a stroked shape, a `spring`
|
|
168
|
+
on a colour, which eases instead) are reported to `onWarning`. Give it to the stage
|
|
169
|
+
to hear about every `live` tween and timeline on it; a timeline's own `onWarning`
|
|
170
|
+
takes precedence:
|
|
171
|
+
|
|
172
|
+
```js
|
|
173
|
+
const live = createLive(new Stage({ onWarning: (message) => console.warn(message) }))
|
|
174
|
+
live.to('.missing', { x: 100 })
|
|
175
|
+
// gsap-compat: no elements found for target ".missing"
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Elements stay registered with the stage once animated. For long-lived single-page
|
|
179
|
+
apps that create and discard many elements, use a `Stage` per view and call
|
|
180
|
+
`stage.destroy()` when the view goes away. It stops everything on that stage,
|
|
181
|
+
releases its elements, and ignores any autoplay still queued.
|
|
182
|
+
|
|
183
|
+
## Mapping table
|
|
184
|
+
|
|
185
|
+
| GSAP | tinyfly/gsap-compat | Notes |
|
|
186
|
+
|---|---|---|
|
|
187
|
+
| `gsap.to(t, vars)` | `tl.to(t, vars)` | Start value resolved, not read from the DOM — see below |
|
|
188
|
+
| `gsap.from(t, vars)` | `tl.from(t, vars)` | |
|
|
189
|
+
| `gsap.fromTo(t, a, b)` | `tl.fromTo(t, a, b)` | The only form with no implicit start value |
|
|
190
|
+
| `gsap.set(t, vars)` | `tl.set(t, vars)` | Compiles to one held keyframe |
|
|
191
|
+
| `gsap.timeline()` | `timeline()` | |
|
|
192
|
+
| `tl.add(child, pos)` | `tl.add(child, pos)` | Flattened at compile time |
|
|
193
|
+
| `tl.addLabel(name)` | `tl.addLabel(name)` | |
|
|
194
|
+
| Position `"+=1"` / `"-=0.5"` | same | Seconds, relative to the timeline end |
|
|
195
|
+
| Position `"<"` / `">"` | same | Start / end of the previous tween |
|
|
196
|
+
| Position `"<0.2"` / `">+=0.2"` | same | Offset from the previous tween |
|
|
197
|
+
| Position `"label+=1"` | same | |
|
|
198
|
+
| `stagger: 0.1` | same | Compiles to one multi-target track |
|
|
199
|
+
| `stagger: { each, amount, from }` | same | `from`: start/end/center/edges/index |
|
|
200
|
+
| `stagger: { grid, from: 'random' \| [x, y], axis, ease }` | same | Worked out into explicit `stagger.offsets` in the JSON; `grid: 'auto'` reads rows from layout |
|
|
201
|
+
| `keyframes: [...]` / `{ '50%': {...} }` / `{ x: [...] }`, `easeEach` | same (`live`) | Consecutive segment tweens; with `stagger`, each target plays the whole sequence |
|
|
202
|
+
| `Draggable` `type: 'rotation'` | `live.draggable(el, { type: 'rotation' })` | |
|
|
203
|
+
| `ScrollTrigger.batch`, `ScrollToPlugin` | `live.scrollBatch`, `live.scrollTo` / `live.to(window, { scrollTo })` | |
|
|
204
|
+
| `repeat` / `yoyo` | `repeat` / `yoyo` on `timeline()` | → `loop` / `alternate` |
|
|
205
|
+
| `repeatDelay` | `repeatDelay` on `timeline()` | |
|
|
206
|
+
| `timeScale()` | `timeScale()` | → `config.speed` |
|
|
207
|
+
| `progress()` | `progress()` | |
|
|
208
|
+
| `seek(t)` / `seek('label')` | same | Seconds |
|
|
209
|
+
| `play/pause/reverse/restart/kill` | same | |
|
|
210
|
+
| `tl.call(fn, params, pos)` / `tl.addPause(pos, fn)` | same (`live`) | See [Callbacks and control](#callbacks-and-control) |
|
|
211
|
+
| `tl.tweenTo(pos)` / `tl.tweenFromTo(a, b)` | same (`live`) | |
|
|
212
|
+
| `onRepeat`, `onReverseComplete`, tween callbacks inside timelines | same (`live`) | |
|
|
213
|
+
| `gsap.delayedCall` / `gsap.killTweensOf` | `live.delayedCall` / `live.killTweensOf` | |
|
|
214
|
+
| `gsap.utils.*`, `gsap.getProperty` | `live.utils.*`, `live.getProperty` | Seeded random — see [Utilities](#utilities-random-values-and-repeatrefresh) |
|
|
215
|
+
| `"random(-100, 100, 5)"`, `repeatRefresh` | same (`live`) | |
|
|
216
|
+
| Tween `.kill()` | handle returned by `to()` etc. | Removes only that tween's tracks |
|
|
217
|
+
| `motionPath: { path, autoRotate, start, end }` | same | Compiles to a motion-path track — see [Motion paths](#motion-paths) |
|
|
218
|
+
| `motionPath: [{x, y}, …]` + `curviness` | same | Points become a smooth path at build time |
|
|
219
|
+
| `motionPath: { path: '#el', align: '#el', alignOrigin }` | `live` only | Element read once, when the tween is built |
|
|
220
|
+
| `morphSVG: 'M…'` | same | Compiles to a `d` track — see [Shape morphing](#shape-morphing) |
|
|
221
|
+
| `morphSVG: '#shape'` / element | `live` only | Target shape and each element's current shape read when built |
|
|
222
|
+
| `MorphSVGPlugin.convertToPath()` | `live.convertToPath()` | |
|
|
223
|
+
| `text: 'Hi'` / `{ value, rightToLeft }` (TextPlugin) | same | Compiles to a text track — see [Text](#text) |
|
|
224
|
+
| `scrambleText: 'Hi'` / `{ text, chars, revealDelay, speed, tweenLength, rightToLeft }` | same | Seeded, so it replays identically |
|
|
225
|
+
| `inertia: { x: { velocity, min, max, end, resistance } }` | same | Compiles to inertia tracks — see [Inertia](#inertia-and-dragging) |
|
|
226
|
+
| `Draggable.create(el, { inertia: true, bounds, snap })` | `live.draggable(el, { inertia, bounds, snap })` | Throw uses the release velocity |
|
|
227
|
+
| `Flip.getState(t)` / `Flip.from(state, vars)` | `live.getFlipState(t)` / `live.flipFrom(state, vars)` | See [Flip](#flip) |
|
|
228
|
+
| `Flip.fit`, `absolute`, `nested` | — | Not yet; see Flip limits |
|
|
229
|
+
| `rotation`, `rotationZ` / `rotationX` / `rotationY` | same | Become tinyfly's `rotate` / `rotateX` / `rotateY` — see [3D](#3d) |
|
|
230
|
+
| `transformPerspective` | same | The element's own perspective (tinyfly's `perspective`) |
|
|
231
|
+
| `perspective` (on a parent) | same | CSS `perspective` for its children (tinyfly's `childPerspective`) |
|
|
232
|
+
| `z`, `rotateX`, `rotateY`, `rotateZ` | same | tinyfly's names pass through unchanged |
|
|
233
|
+
| — | `quaternion: [x, y, z, w]` | A whole rotation, turned the short way (slerp); starts unrotated |
|
|
234
|
+
|
|
235
|
+
Units: the facade speaks **seconds**, like GSAP. Everything it stores is in
|
|
236
|
+
**milliseconds**, like the engine. The conversion happens at the boundary and
|
|
237
|
+
nowhere else.
|
|
238
|
+
|
|
239
|
+
## 3D
|
|
240
|
+
|
|
241
|
+
GSAP's transform names work, and so do tinyfly's. They compile to the same
|
|
242
|
+
tracks, so a 3D tween draws the same in the DOM, SVG, Canvas and WebGL (see
|
|
243
|
+
[3D transforms](3d-rotations.md)).
|
|
244
|
+
|
|
245
|
+
```js
|
|
246
|
+
live.set('.stage', { perspective: 800 }) // the parent's: children share a vanishing point
|
|
247
|
+
live.to('.card', { rotationY: 180, z: 40, duration: 1 }) // = rotateY, z
|
|
248
|
+
live.to('.chip', { rotationX: 60, transformPerspective: 500, duration: 0.6 }) // its own perspective
|
|
249
|
+
live.to('.cube', { quaternion: [0, 0.7071, 0, 0.7071], duration: 1 }) // a whole rotation, slerped
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
As in GSAP, `perspective` belongs on a parent (CSS `perspective`, DOM only),
|
|
253
|
+
and `transformPerspective` on the element itself. `quaternion` has no GSAP
|
|
254
|
+
equivalent: it turns from any orientation to any other the short way, without
|
|
255
|
+
gimbal lock, and starts unrotated unless `fromTo` says otherwise.
|
|
256
|
+
|
|
257
|
+
## Easing
|
|
258
|
+
|
|
259
|
+
Most GSAP eases map to an exact built-in or a close cubic-bezier:
|
|
260
|
+
|
|
261
|
+
| GSAP | Result |
|
|
262
|
+
|---|---|
|
|
263
|
+
| `none`, `linear` | `linear` |
|
|
264
|
+
| `power1.*`, `power2.*` | Exact built-ins: `power1` is quad, `power2` is cubic, as in GSAP |
|
|
265
|
+
| `power3.*`, `power4.*`, `sine.*`, `expo.*`, `circ.*`, `back.*` | Cubic-bezier |
|
|
266
|
+
| `elastic.*(amplitude, period)`, `bounce.*`, `back.*(overshoot)` | Parametric ease: `{ type: 'elastic', mode, amplitude, period }` … — exact, one keyframe |
|
|
267
|
+
| `steps(n)` | `{ type: 'steps', count: n + 1, position: 'none' }` — GSAP's n + 1 levels from 0 to 1 |
|
|
268
|
+
|
|
269
|
+
GSAP 2 spellings (`Power2.easeOut`) and bare families (`power2`, which defaults
|
|
270
|
+
to `.out`) are both accepted. An unrecognised name falls back to `ease-out`
|
|
271
|
+
rather than throwing.
|
|
272
|
+
|
|
273
|
+
### Custom eases
|
|
274
|
+
|
|
275
|
+
Build a curve once, name it, and use the name as an ease anywhere:
|
|
276
|
+
|
|
277
|
+
```js
|
|
278
|
+
import { CustomEase, CustomBounce, CustomWiggle } from '@algorisys/tinyfly/gsap-compat' // or live.customEase(...)
|
|
279
|
+
|
|
280
|
+
CustomEase.create('hop', 'M0,0 C0.25,0 0.3,1.35 0.55,1.15 C0.75,1 0.85,1 1,1')
|
|
281
|
+
CustomEase.create('snappy', [0.7, 0, 0.9, 0.4]) // bezier points
|
|
282
|
+
CustomBounce.create('drop', { strength: 0.65 })
|
|
283
|
+
CustomWiggle.create('shake', { wiggles: 7, type: 'easeOut' })
|
|
284
|
+
|
|
285
|
+
live.to('.ball', { y: 300, ease: 'drop' })
|
|
286
|
+
live.to('.bell', { rotate: 20, ease: 'shake' }) // swings ±20° and comes back
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
- **CustomEase** takes SVG path data or bezier points. Path data may be in any
|
|
290
|
+
coordinate space or y direction: x is scaled to run 0 → 1, and y to start at 0
|
|
291
|
+
and end at 1. So a curve copied out of a design tool works as is, and it may
|
|
292
|
+
overshoot.
|
|
293
|
+
- **CustomBounce** drops onto the end value and rebounds. Each bounce keeps part
|
|
294
|
+
of the height, timed like a real ball. `strength` (0–1) sets how lively it is.
|
|
295
|
+
- **CustomWiggle** oscillates around the start value and ends back there (unlike
|
|
296
|
+
other eases). `wiggles` sets the count, and `type` is `'easeOut'` (dying away),
|
|
297
|
+
`'easeInOut'` or `'uniform'`.
|
|
298
|
+
- **Serialization:** a curve that is one cubic-bezier stays an exact, serializable
|
|
299
|
+
easing. Anything else is always sampled into keyframes by the tween that uses
|
|
300
|
+
it, even without `bakeEases`, so the JSON plays without the curve. The generators
|
|
301
|
+
are pure functions in the engine (`customEase`, `customBounce`, `customWiggle`).
|
|
302
|
+
|
|
303
|
+
### Elastic, bounce, back and steps
|
|
304
|
+
|
|
305
|
+
These overshoot or jump, which no cubic-bezier can do. They compile to the
|
|
306
|
+
engine's **parametric eases** — small, exact JSON evaluated when played — so the
|
|
307
|
+
motion is GSAP's own curve and the keyframe stays editable in the studio:
|
|
308
|
+
|
|
309
|
+
```js
|
|
310
|
+
live.to('.ball', { y: 300, ease: 'bounce.out' })
|
|
311
|
+
live.to('.card', { scale: 1, ease: 'elastic.out(1.2, 0.4)' }) // → { type: 'elastic', mode: 'out', amplitude: 1.2, period: 0.4 }
|
|
312
|
+
live.to('.clock', { rotate: 360, ease: 'steps(12)' })
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
A plain `back.*` keeps its cubic-bezier (CSS can play that); `back.out(3)` with an
|
|
316
|
+
overshoot becomes parametric. CSS and Lottie exports sample parametric eases into
|
|
317
|
+
keyframes. For a player that predates them, `timeline({ bakeEases: true })` samples
|
|
318
|
+
them at build time instead.
|
|
319
|
+
|
|
320
|
+
For a real spring rather than an elastic *ease*, use a
|
|
321
|
+
[spring track](#springs) instead; it is one line of parameters rather than a
|
|
322
|
+
hundred baked keyframes.
|
|
323
|
+
|
|
324
|
+
## The implicit start value
|
|
325
|
+
|
|
326
|
+
This is the single biggest behavioural difference, and it is deliberate.
|
|
327
|
+
|
|
328
|
+
GSAP's `to()` reads the element's current computed style to find where to
|
|
329
|
+
animate *from*. tinyfly cannot: reading live DOM state would make the same
|
|
330
|
+
animation JSON play differently depending on the page's CSS, which breaks the
|
|
331
|
+
determinism the engine is built on.
|
|
332
|
+
|
|
333
|
+
So a start value is resolved in this order:
|
|
334
|
+
|
|
335
|
+
1. An explicit `from` (i.e. you used `fromTo`) — always wins.
|
|
336
|
+
2. The last value authored for that target+property on this timeline.
|
|
337
|
+
3. A `defaults` map passed to `timeline({ defaults })`.
|
|
338
|
+
4. The documented static default (`opacity: 1`, `x: 0`, `scale: 1`, …).
|
|
339
|
+
|
|
340
|
+
Reaching step 4 is where GSAP users get surprised, so the facade tells you:
|
|
341
|
+
|
|
342
|
+
```ts
|
|
343
|
+
const tl = timeline({ onWarning: (message) => console.warn(message) })
|
|
344
|
+
tl.to('box', { x: 100, duration: 1 })
|
|
345
|
+
// gsap-compat: no start value for "x" on "box" — using the static default 0.
|
|
346
|
+
// GSAP would read the live DOM here; tinyfly cannot, so pass an explicit
|
|
347
|
+
// fromTo() or a defaults map.
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
**Recommendation: use `fromTo` for the first tween on any property.** After
|
|
351
|
+
that, step 2 chains naturally and you can use `to` freely.
|
|
352
|
+
|
|
353
|
+
## What we deliberately don't do
|
|
354
|
+
|
|
355
|
+
These are not on a roadmap. Each conflicts with a principle the project is built
|
|
356
|
+
on, and the alternative given is the principled equivalent.
|
|
357
|
+
|
|
358
|
+
Several of these are now **reopened for consideration** in Phase 27 of
|
|
359
|
+
[todo.md](https://github.com/algorisys-oss/tinyfly/blob/main/todo.md), with designs that resolve values once at load rather than
|
|
360
|
+
per frame — which keeps the JSON a complete description of the animation. The
|
|
361
|
+
reasoning below is still the bar any such proposal has to clear.
|
|
362
|
+
|
|
363
|
+
| Not supported | Why | Instead |
|
|
364
|
+
|---|---|---|
|
|
365
|
+
| Per-frame function values (a value recomputed on every frame) | Cannot serialize; the JSON would not describe the animation | Function values and `"random(…)"` run when a tween is built (and again with `repeatRefresh`); for truly per-frame values use `quickTo` or `ticker.add` |
|
|
366
|
+
| Implicit `getComputedStyle` start values | Breaks determinism | The resolution chain above |
|
|
367
|
+
| `overwrite: 'auto'` | Needs live tween objects mutating each other | `timeline.removeTracks(filter)`, and `findConflicts()` to detect overlaps |
|
|
368
|
+
| Plugins (ScrollTrigger, Draggable, Flip, MorphSVG…) | A plugin system would let arbitrary code into the evaluation path | Built in as first-class features — see below |
|
|
369
|
+
| `quickSetter` | Writes outside the timeline, so nothing could serialize it | `live.quickTo`, which re-aims one real tween |
|
|
370
|
+
| Function eases | Cannot serialize | Named ease, or `{ type: 'cubic-bezier', points }` |
|
|
371
|
+
|
|
372
|
+
### The plugin equivalents
|
|
373
|
+
|
|
374
|
+
What GSAP sells as plugins, tinyfly ships as ordinary features:
|
|
375
|
+
|
|
376
|
+
| GSAP plugin | tinyfly |
|
|
377
|
+
|---|---|
|
|
378
|
+
| ScrollSmoother | `live.smoothScroll()` — eased wheel scrolling with `data-speed` / `data-lag` parallax, on the page's real scroll position — see [Smooth scrolling](#smooth-scrolling) |
|
|
379
|
+
| ScrollTrigger | `scrollTrigger` on `live` (scrub, pin, toggleActions) — see [Scroll triggers](#scroll-triggers); [`@algorisys/tinyfly/drivers`](./scroll-animation.md) underneath, plus a scroll-scrub preview in the editor |
|
|
380
|
+
| Draggable / Observer | `live.draggable()`, and `@algorisys/tinyfly/interaction` — `Draggable`, `Observer` |
|
|
381
|
+
| InertiaPlugin | The `inertia` tween option and inertia tracks — see [Inertia](#inertia-and-dragging) |
|
|
382
|
+
| Flip | `live.flip()` / `live.getFlipState()` + `live.flipFrom()` — see [Flip](#flip); `flip()` in the DOM adapter for authoring |
|
|
383
|
+
| MorphSVG | The `morphSVG` tween option — see [Shape morphing](#shape-morphing) |
|
|
384
|
+
| MotionPathPlugin | The `motionPath` tween option — see [Motion paths](#motion-paths) |
|
|
385
|
+
| DrawSVG | The `drawSVG` tween option — see [Line drawing](#line-drawing) |
|
|
386
|
+
| SplitText | `live.splitText()` — see [Split text](#split-text); text splitting in the editor |
|
|
387
|
+
| `gsap.ticker` | `live.ticker` — see [Playing on real elements](#playing-on-real-elements-live) |
|
|
388
|
+
| TextPlugin | The `text` tween option — see [Text](#text) |
|
|
389
|
+
| ScrambleTextPlugin | The `scrambleText` tween option — see [Text](#text) |
|
|
390
|
+
| Physics2D | [Spring](#springs) and [inertia](#inertia-and-dragging) tracks — deterministic and serializable |
|
|
391
|
+
|
|
392
|
+
## Motion paths
|
|
393
|
+
|
|
394
|
+
GSAP's `motionPath` option works on `timeline()`, `tf` and `live`:
|
|
395
|
+
|
|
396
|
+
```ts
|
|
397
|
+
live.to('.plane', {
|
|
398
|
+
motionPath: { path: '#route', align: '#route', autoRotate: true },
|
|
399
|
+
duration: 3,
|
|
400
|
+
ease: 'power1.inOut',
|
|
401
|
+
})
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
| Option | Meaning |
|
|
405
|
+
|---|---|
|
|
406
|
+
| `path` | SVG path data, an array of `{ x, y }` points, or (in `live`) a selector / element: `<path>`, `<circle>`, `<ellipse>`, `<rect>`, `<line>`, `<polyline>`, `<polygon>` |
|
|
407
|
+
| `curviness` | For points: `0` straight lines, `1` a natural curve (default), higher bows further |
|
|
408
|
+
| `autoRotate` | `true` to face along the path; a number also adds that many degrees |
|
|
409
|
+
| `start`, `end` | The part of the path to travel, 0–1 (defaults 0 and 1) |
|
|
410
|
+
| `align` | `live` only. Lay the path over an element — `true` for the path element itself — so the follower moves along it where it is drawn |
|
|
411
|
+
| `alignOrigin` | `live` only. The follower's point that sits on the path, as fractions of its size (default `[0.5, 0.5]`) |
|
|
412
|
+
|
|
413
|
+
**How it compiles.** One motion-path track, whose keyframes are progress along
|
|
414
|
+
the path (eased like any other tween, and baked for elastic/bounce when
|
|
415
|
+
`bakeEases` is on). Stagger fans several followers along the same path.
|
|
416
|
+
`from()` travels it backwards.
|
|
417
|
+
|
|
418
|
+
**Without `align`**, path coordinates are x/y offsets from where the follower is
|
|
419
|
+
laid out. **With `align`**, `live` measures once, when the tween is built: the
|
|
420
|
+
path element's position and scale on the page (its screen matrix) and the
|
|
421
|
+
follower's layout box (ignoring its own transform). The result is stored as a
|
|
422
|
+
`matrix` on the track, so the JSON still says exactly where the follower goes.
|
|
423
|
+
If the page re-flows later, build the tween again.
|
|
424
|
+
|
|
425
|
+
Rotation happens about the follower's CSS `transform-origin`. With a non-centre
|
|
426
|
+
`alignOrigin`, set `transform-origin` to match.
|
|
427
|
+
|
|
428
|
+
The parser handles what design tools export: every command, absolute or
|
|
429
|
+
relative, compact numbers (`10-20`, `.5.5`), exponents, and arc flags without
|
|
430
|
+
separators. Followers move at an even speed along curves.
|
|
431
|
+
|
|
432
|
+
## Shape morphing
|
|
433
|
+
|
|
434
|
+
GSAP's `morphSVG` option works on `timeline()`, `tf` and `live`:
|
|
435
|
+
|
|
436
|
+
```ts
|
|
437
|
+
const [shape] = live.convertToPath('#circle') // a <circle> has no `d` to animate
|
|
438
|
+
live
|
|
439
|
+
.timeline({ repeat: -1 })
|
|
440
|
+
.to(shape, { morphSVG: '#star', duration: 1 })
|
|
441
|
+
.to(shape, { morphSVG: '#heart', duration: 1 }, '+=0.5')
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
- **In `live`**, `morphSVG` takes a selector, an element (path or any basic shape)
|
|
445
|
+
or path data. Each element starts from the shape it currently draws, or the
|
|
446
|
+
shape tinyfly last gave it, so chained morphs follow on. Several elements each
|
|
447
|
+
morph from their own shape, and a numeric `stagger` is honoured.
|
|
448
|
+
- **In `timeline()` / `tf`**, `morphSVG` takes path data, and the start must be
|
|
449
|
+
known: `fromTo({ d: … }, { morphSVG: … })`, or an earlier morph on the same
|
|
450
|
+
target. Morphing from nothing throws, with a message saying so.
|
|
451
|
+
- **`live.convertToPath(targets)`** replaces circles, ellipses, rects, lines,
|
|
452
|
+
polylines and polygons with equivalent `<path>` elements, keeping class, fill and
|
|
453
|
+
other attributes. It changes the document, so it is an explicit call.
|
|
454
|
+
|
|
455
|
+
How the engine matches two shapes so the morph looks intentional:
|
|
456
|
+
|
|
457
|
+
| | |
|
|
458
|
+
|---|---|
|
|
459
|
+
| **Start point and direction** | For closed shapes, every rotation of the target's points and both windings are tried; the one that moves points least (about each shape's centre) wins. The equivalent of GSAP's `shapeIndex: "auto"`. |
|
|
460
|
+
| **Corners** | Samples always include every corner of both shapes, so star points and square corners stay sharp mid-morph. |
|
|
461
|
+
| **Holes** | Paths with the same number of subpaths morph subpath-to-subpath, so a letter's counter stays a hole. Otherwise the whole path is one run. |
|
|
462
|
+
| **Open paths** | Stay open; only both directions are tried. |
|
|
463
|
+
| **Ends** | At progress 0 and 1 the original path strings are returned exactly. |
|
|
464
|
+
|
|
465
|
+
Plans are cached per pair of shapes, so the matching runs once; each frame only
|
|
466
|
+
blends points.
|
|
467
|
+
|
|
468
|
+
## Line drawing
|
|
469
|
+
|
|
470
|
+
`drawSVG` animates how much of an SVG stroke is drawn:
|
|
471
|
+
|
|
472
|
+
```js
|
|
473
|
+
live.from('.line', { drawSVG: 0, duration: 1 }) // draw in
|
|
474
|
+
live.to('.line', { drawSVG: '40% 60%', duration: 0.6 }) // shrink to the middle
|
|
475
|
+
live.fromTo('path', { drawSVG: '50% 50%' }, { drawSVG: true, stagger: 0.1 }) // grow out from the centre
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
| Value | Drawn |
|
|
479
|
+
|---|---|
|
|
480
|
+
| `true` / `false` | All of it / none |
|
|
481
|
+
| `120` | The first 120px |
|
|
482
|
+
| `'60%'` | The first 60% |
|
|
483
|
+
| `'20% 80%'`, `'10 50%'` | From one point to the other (px and % mix) |
|
|
484
|
+
|
|
485
|
+
`live` measures each element's length once (`getTotalLength()`), so shapes of
|
|
486
|
+
different lengths draw over the same duration, and compiles the draw to two
|
|
487
|
+
ordinary tracks — `strokeDasharray` as `[visible, length]` and `strokeDashoffset`
|
|
488
|
+
as `-start`. A `to()` on a stroke tinyfly has not drawn starts fully drawn. It
|
|
489
|
+
works on anything with a stroke length: `path`, `line`, `polyline`, `polygon`,
|
|
490
|
+
`circle`, `ellipse`, `rect`. It replaces any dash pattern the element had, and
|
|
491
|
+
with `stroke-linecap: round` an empty segment still shows a dot.
|
|
492
|
+
|
|
493
|
+
`timeline()` / `tf` have no page to measure and throw on `drawSVG`; use
|
|
494
|
+
`drawSvgProperties(value, length)` to get the two values yourself.
|
|
495
|
+
|
|
496
|
+
## Text
|
|
497
|
+
|
|
498
|
+
GSAP's TextPlugin and ScrambleTextPlugin options work on `timeline()`, `tf` and `live`:
|
|
499
|
+
|
|
500
|
+
```ts
|
|
501
|
+
live.to('.title', { text: 'Hello world', duration: 1, ease: 'none' }) // types it
|
|
502
|
+
live.to('.title', { text: { value: '', rightToLeft: true }, duration: 0.4 }) // backspaces it
|
|
503
|
+
live.to('.code', { scrambleText: { text: 'granted', chars: 'numbers', revealDelay: 0.3 }, duration: 1 })
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
| `scrambleText` option | Meaning |
|
|
507
|
+
|---|---|
|
|
508
|
+
| `text` | The text to end on |
|
|
509
|
+
| `chars` | `upperCase` (default), `lowerCase`, `upperAndLowerCase`, `numbers`, or your own characters |
|
|
510
|
+
| `revealDelay` | Seconds before characters start to settle |
|
|
511
|
+
| `speed` | How fast random characters change; 1 = 20 per second |
|
|
512
|
+
| `tweenLength` | Grow or shrink the length over the tween (default `true`) |
|
|
513
|
+
| `rightToLeft` | Settle from the end |
|
|
514
|
+
| `seed` | Fix the random sequence (by default derived from the target and text) |
|
|
515
|
+
|
|
516
|
+
**Where the text starts.** In `live`, from the element's current text (or the
|
|
517
|
+
text tinyfly last set), so chains follow on and each of several elements starts
|
|
518
|
+
from its own. In `timeline()` / `tf`, from the text this timeline last set, or
|
|
519
|
+
empty; `fromTo({ text: … }, …)` sets it explicitly.
|
|
520
|
+
|
|
521
|
+
**Deterministic scramble.** The "random" characters are a hash of the seed, the
|
|
522
|
+
character's position and the refresh step — never `Math.random` — so scrubbing
|
|
523
|
+
backwards shows exactly what playing forwards did, and an exported animation
|
|
524
|
+
scrambles the same everywhere.
|
|
525
|
+
|
|
526
|
+
**How it compiles.** A text track: keyframes are eased progress (0–1), and the
|
|
527
|
+
track's `textConfig` holds the start and end text and the options. The timeline
|
|
528
|
+
turns progress into the string, and adapters set it as the element's text.
|
|
529
|
+
Spaces stay spaces while scrambling, so word shapes remain readable.
|
|
530
|
+
|
|
531
|
+
`text` replaces the element's text content. Markup inside it (spans, links) is
|
|
532
|
+
replaced too; animate an inner element if you need to keep the rest.
|
|
533
|
+
|
|
534
|
+
## Scroll triggers
|
|
535
|
+
|
|
536
|
+
`scrollTrigger` on `live.timeline()` or a single `live` tween ties it to
|
|
537
|
+
scrolling, with GSAP's option names. It is built on
|
|
538
|
+
[`ScrollDriver`](./scroll-animation.md), so scrolling does no layout reads.
|
|
539
|
+
|
|
540
|
+
```js
|
|
541
|
+
// Scrub: scroll position is the playhead. Pin the section while it plays.
|
|
542
|
+
live.timeline({
|
|
543
|
+
scrollTrigger: { trigger: '.panels', start: 'top top', end: '+=2000', scrub: 0.5, pin: true },
|
|
544
|
+
})
|
|
545
|
+
.to('.track', { x: -1600, ease: 'none' })
|
|
546
|
+
|
|
547
|
+
// Toggle: play when the card comes into view, reverse when scrolling back above it.
|
|
548
|
+
live.from('.card', {
|
|
549
|
+
y: 60, opacity: 0, duration: 0.8,
|
|
550
|
+
scrollTrigger: { start: 'top 80%', toggleActions: 'play none none reverse' },
|
|
551
|
+
})
|
|
552
|
+
|
|
553
|
+
// No animation: just callbacks, e.g. skew by scroll speed.
|
|
554
|
+
live.scrollTrigger({
|
|
555
|
+
trigger: '.gallery',
|
|
556
|
+
onUpdate: ({ velocity }) => live.to('.gallery img', { skewY: velocity / -300, duration: 0.4 }),
|
|
557
|
+
})
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
| Option | |
|
|
561
|
+
|---|---|
|
|
562
|
+
| `trigger` | Element or selector; default the animation's first target |
|
|
563
|
+
| `start`, `end` | `"<element edge> <viewport edge>"` as in [trigger positions](./scroll-animation.md#trigger-positions); `end: '+=600'` / `'+=150%'` is measured from the start. Defaults `'top bottom'`, `'bottom top'`. A function is called again on every refresh |
|
|
564
|
+
| `invalidateOnRefresh` | On every refresh (a resize), rebuild the animation so function values and start values are read again |
|
|
565
|
+
| `scrub` | `true`: progress follows scroll exactly. A number: smoothed over that many seconds |
|
|
566
|
+
| `pin` | `true` pins the trigger for the range, or an element / selector to pin instead (see [pinning](./scroll-animation.md#pinning)) |
|
|
567
|
+
| `scroller` | A scrolling element or selector instead of the window |
|
|
568
|
+
| `toggleActions` | Without `scrub`: actions on enter, leave, enter back, leave back — `play`, `pause`, `resume`, `reverse`, `restart`, `reset`, `complete` or `none`. Default `'play none none none'` |
|
|
569
|
+
| `once` | Stop watching after the first enter |
|
|
570
|
+
| `snap` | After scrolling stops inside the range, scroll on to the nearest point: a progress step (`1 / 3`), progress points (`[0, 0.4, 1]`), `'labels'`, a function, or `{ snapTo, duration, delay, ease }` |
|
|
571
|
+
| `markers` | Draw start / end lines while developing: `true`, or `{ startColor, endColor, fontSize, indent, id }` |
|
|
572
|
+
| `containerAnimation` | The animation sliding this trigger's row sideways; start and end become horizontal (`'left right'` → `'right left'`) |
|
|
573
|
+
| `onUpdate(self)` | `self` is `{ progress, velocity, direction }`; velocity in px/s, back to 0 when scrolling stops |
|
|
574
|
+
| `onEnter`, `onLeave`, `onEnterBack`, `onLeaveBack` | Edge callbacks |
|
|
575
|
+
|
|
576
|
+
A timeline with `scrollTrigger` does not autoplay, and without `scrub` it shows its
|
|
577
|
+
starting state straight away, so a `from()` reveal never flashes its end state.
|
|
578
|
+
The trigger attaches on the next microtask, after the tweens chained onto the
|
|
579
|
+
timeline. `tl.scrollTrigger` is the driver (`refresh()`, `progress`, `velocity`);
|
|
580
|
+
`tl.kill()` removes it and its pin, as does destroying the stage.
|
|
581
|
+
`live.refreshScroll()` re-measures every trigger after a layout change a resize
|
|
582
|
+
would not catch.
|
|
583
|
+
|
|
584
|
+
On touch devices, resizes that only change the height a little (the address bar
|
|
585
|
+
showing and hiding) do not refresh, so pins do not jump mid-scroll.
|
|
586
|
+
|
|
587
|
+
- **`pinSpacing: false`** pins without pushing later content down; it scrolls up
|
|
588
|
+
underneath the pinned element.
|
|
589
|
+
- **`horizontal: true`** is for a scroller that scrolls sideways. Positions use `left`
|
|
590
|
+
/ `right` (`start: 'left right'`), progress follows `scrollLeft`, and pins hold
|
|
591
|
+
horizontally. Markers are vertical only.
|
|
592
|
+
- **`anticipatePin` isn't needed.** Pins use `position: sticky`, so the browser holds
|
|
593
|
+
them on the compositor, with no hand-off frame where a pin could lag behind fast
|
|
594
|
+
scrolling.
|
|
595
|
+
|
|
596
|
+
### Batches and scrolling to a place
|
|
597
|
+
|
|
598
|
+
```js
|
|
599
|
+
// Cards that enter together animate together (GSAP's ScrollTrigger.batch).
|
|
600
|
+
live.scrollBatch('.card', {
|
|
601
|
+
start: 'top 85%',
|
|
602
|
+
interval: 0.1, // seconds to collect elements that cross together
|
|
603
|
+
batchMax: 6,
|
|
604
|
+
onEnter: (cards) => live.from(cards, { y: 40, opacity: 0, stagger: 0.08 }),
|
|
605
|
+
})
|
|
606
|
+
|
|
607
|
+
// Scroll as an animation (GSAP's ScrollToPlugin).
|
|
608
|
+
live.scrollTo('#pricing', { duration: 1, offset: 80, ease: 'power2.inOut' })
|
|
609
|
+
live.to(window, { scrollTo: { y: '#pricing', offsetY: 80 }, duration: 1 })
|
|
610
|
+
live.scrollTo('max') // the bottom
|
|
611
|
+
live.scrollTo({ x: 600 }, { scroller: '.gallery' })
|
|
612
|
+
```
|
|
613
|
+
|
|
614
|
+
`scrollTo` measures the destination once, at the start. It is an ordinary live
|
|
615
|
+
timeline, so it can be killed and takes callbacks. Wheel, touch or key input stops
|
|
616
|
+
it (`autoKill: false` to keep going). With `live.smoothScroll()` running,
|
|
617
|
+
`smoother.scrollTo()` does the same and keeps smoothing afterwards.
|
|
618
|
+
|
|
619
|
+
### Snapping, markers and horizontal sections
|
|
620
|
+
|
|
621
|
+
**Snap** runs after scrolling stops inside the range. It uses the speed scrolling
|
|
622
|
+
had just before stopping, so a flick carries on to the next point instead of
|
|
623
|
+
falling back. It then animates the scroll offset and gives way at once to a wheel,
|
|
624
|
+
touch, click or key. With `'labels'` it snaps to the timeline's labels, read at
|
|
625
|
+
snap time so a rebuilt timeline's labels count.
|
|
626
|
+
|
|
627
|
+
**Markers** show where a range starts and ends. Green and red lines are fixed to
|
|
628
|
+
the viewport where the element points fire, and matching markers sit on the page
|
|
629
|
+
at the element points. The range is active between the moments each page marker
|
|
630
|
+
crosses its line. Remove `markers` before shipping.
|
|
631
|
+
|
|
632
|
+
**`containerAnimation`** handles the classic pinned horizontal section, where
|
|
633
|
+
items inside the sliding row need their own triggers:
|
|
634
|
+
|
|
635
|
+
```js
|
|
636
|
+
const row = live
|
|
637
|
+
.timeline({ scrollTrigger: { trigger: '.work', start: 'top top', end: () => `+=${travel()}`, pin: true, scrub: true, snap: 1 / 3 } })
|
|
638
|
+
.to('.track', { x: () => -travel(), ease: 'none' })
|
|
639
|
+
|
|
640
|
+
document.querySelectorAll('.panel').forEach((panel) => {
|
|
641
|
+
live.from(panel.querySelector('h3'), {
|
|
642
|
+
y: 20, opacity: 0,
|
|
643
|
+
scrollTrigger: { trigger: panel, containerAnimation: row, start: 'left 80%', toggleActions: 'play none none reverse' },
|
|
644
|
+
})
|
|
645
|
+
})
|
|
646
|
+
```
|
|
647
|
+
|
|
648
|
+
The trigger's horizontal positions are solved against the row's own motion (the
|
|
649
|
+
`x` tracks moving its ancestors), and turned into the row's vertical scroll range.
|
|
650
|
+
Create the row's timeline first, keep its motion steady in one direction (an
|
|
651
|
+
`ease: 'none'` slide is the usual case), and don't pin inside it.
|
|
652
|
+
|
|
653
|
+
## Callbacks and control
|
|
654
|
+
|
|
655
|
+
Callbacks are runtime behaviour, like `onComplete`: they are not part of the JSON.
|
|
656
|
+
On `live` timelines they fire when the playhead **crosses** their time, whether it
|
|
657
|
+
is playing, looping, yoyoing or being scrubbed with `progress()` (so a scroll scrub
|
|
658
|
+
runs them). A `seek()` jumps without firing, as in GSAP.
|
|
659
|
+
|
|
660
|
+
```js
|
|
661
|
+
const tl = live.timeline({ onRepeat: () => …, onReverseComplete: () => … })
|
|
662
|
+
.to('.intro', { opacity: 1, onStart: () => …, onComplete: () => … })
|
|
663
|
+
.call(showMenu, [menu]) // at the end so far; any position works
|
|
664
|
+
.addPause('+=0.5', () => waitForClick()) // stops exactly there; tl.play() continues
|
|
665
|
+
.addLabel('details')
|
|
666
|
+
.to('.details', { y: 0 })
|
|
667
|
+
|
|
668
|
+
tl.tweenTo('details', { duration: 0.8, ease: 'power2.inOut' }) // animates the playhead
|
|
669
|
+
live.delayedCall(2, hideToast) // a call on the stage's clock; kill() cancels
|
|
670
|
+
live.killTweensOf('.card', 'x,y') // stop what moves these, in every timeline
|
|
671
|
+
```
|
|
672
|
+
|
|
673
|
+
- **Order.** Callbacks at the same time run in the order they were added. A frame
|
|
674
|
+
that crosses a loop runs the rest of that loop's callbacks, then `onRepeat`, then
|
|
675
|
+
the next loop's.
|
|
676
|
+
- **Tween callbacks** inside a timeline run at that tween's own start and end
|
|
677
|
+
(forward). `onUpdate` runs on every frame whose movement overlaps the tween.
|
|
678
|
+
- **`call` and `addPause`** take no time, but one placed after the last tween makes
|
|
679
|
+
the timeline long enough to reach it.
|
|
680
|
+
- **`onComplete` / `onReverseComplete`.** Arriving back at the start after
|
|
681
|
+
`reverse()` calls `onReverseComplete`, not `onComplete`.
|
|
682
|
+
- **`tweenTo` / `tweenFromTo`** pause the timeline and return the tween moving the
|
|
683
|
+
playhead. Its default duration is the distance at the timeline's own speed, with
|
|
684
|
+
`ease: 'none'`.
|
|
685
|
+
- **`killTweensOf`** removes only the matching properties when given. A staggered
|
|
686
|
+
tween on several elements is one track, so it stops for all of them.
|
|
687
|
+
- Callbacks run after the frame is applied, so they read this frame's values.
|
|
688
|
+
|
|
689
|
+
## Smooth scrolling
|
|
690
|
+
|
|
691
|
+
`live.smoothScroll()` eases wheel scrolling, like GSAP's ScrollSmoother, and adds
|
|
692
|
+
parallax layers:
|
|
693
|
+
|
|
694
|
+
```js
|
|
695
|
+
const smoother = live.smoothScroll({ smooth: 0.9, effects: true })
|
|
696
|
+
|
|
697
|
+
// <h2 data-speed="0.8"> scrolls at 80% of the page's speed
|
|
698
|
+
// <img data-lag="0.3"> catches up with the page 0.3s after it moves
|
|
699
|
+
|
|
700
|
+
smoother.scrollTo('#contact', { offset: -80 }) // anchor links, eased
|
|
701
|
+
smoother.paused(true) // e.g. while a modal is open
|
|
702
|
+
```
|
|
703
|
+
|
|
704
|
+
It does not move the page inside a transformed wrapper, as ScrollSmoother does.
|
|
705
|
+
Wheel input is eased, but the browser's **own scroll position** is what moves. So:
|
|
706
|
+
|
|
707
|
+
- scroll triggers, pins (`position: sticky`), `position: fixed`, anchor links,
|
|
708
|
+
find-in-page and scroll restoration all work unchanged;
|
|
709
|
+
- touch, keyboard and scrollbar scrolling stay native, and smoothing continues
|
|
710
|
+
from wherever they leave the page;
|
|
711
|
+
- pinch-zoom, sideways wheels and scrollable areas inside the page keep their own
|
|
712
|
+
scrolling (mark any other area `data-smooth-ignore`).
|
|
713
|
+
|
|
714
|
+
| Option | Default | |
|
|
715
|
+
|---|---|---|
|
|
716
|
+
| `smooth` | `0.8` | Seconds to catch up with the wheel; `0` turns smoothing off |
|
|
717
|
+
| `wheelMultiplier` | `1` | Scales wheel distance |
|
|
718
|
+
| `effects` | `false` | `true` for `[data-speed], [data-lag]`, or your own selector |
|
|
719
|
+
| `scroller` | the window | A scrolling element or selector |
|
|
720
|
+
| `reducedMotion` | the system setting | With reduced motion there is no smoothing and no effects |
|
|
721
|
+
| `onUpdate(state)` | — | `{ scroll, target, progress, velocity }` after each moving frame |
|
|
722
|
+
|
|
723
|
+
- **`data-speed`**: the element sits at its natural place when centred in the
|
|
724
|
+
viewport, and drifts by `(1 − speed)` of the scroll distance either side of it.
|
|
725
|
+
- **Effects** are written to the CSS `translate` property, so they combine with
|
|
726
|
+
tweens on `transform`. Don't put them on a scroll trigger's `trigger` element;
|
|
727
|
+
put them on a child.
|
|
728
|
+
- **Re-measuring**: effects are measured again whenever scroll triggers re-measure
|
|
729
|
+
(on resize and `live.refreshScroll()`), with the layers at rest while triggers
|
|
730
|
+
measure, and after pins have changed the layout.
|
|
731
|
+
- `smoother.state`, `smoother.refresh()`, and `smoother.kill()`. Contexts and
|
|
732
|
+
`matchMedia` kill it on revert.
|
|
733
|
+
|
|
734
|
+
The [Agency Landing Page showcase](../src/examples/showcases/agency-landing.js) turns
|
|
735
|
+
it on outside reduced motion, alongside its pinned sections.
|
|
736
|
+
|
|
737
|
+
## Values that change every event: `quickTo`
|
|
738
|
+
|
|
739
|
+
Pointer followers, magnetic buttons and scroll-velocity effects change a value on
|
|
740
|
+
every event. Creating a tween per event works, but it allocates on every move and
|
|
741
|
+
leaves overlapping tweens to compose. `live.quickTo` makes one reusable tween per
|
|
742
|
+
property instead:
|
|
743
|
+
|
|
744
|
+
```js
|
|
745
|
+
const moveX = live.quickTo('.cursor', 'x', { duration: 0.5, ease: 'power3.out' })
|
|
746
|
+
const moveY = live.quickTo('.cursor', 'y', { duration: 0.5, ease: 'power3.out' })
|
|
747
|
+
window.addEventListener('pointermove', (e) => { moveX(e.clientX); moveY(e.clientY) })
|
|
748
|
+
|
|
749
|
+
const pull = live.quickTo(button, 'x', { spring: 'snappy' }) // springs keep their momentum
|
|
750
|
+
```
|
|
751
|
+
|
|
752
|
+
- Each call re-targets the tween from the value on screen now, so there is no jump.
|
|
753
|
+
- Nothing is written until the next frame, so several calls in one frame cost
|
|
754
|
+
one write.
|
|
755
|
+
- With `spring`, each re-target carries the current velocity.
|
|
756
|
+
- The setter uses the first element the target matches. `moveX.tween` is the
|
|
757
|
+
reused timeline, and `moveX.kill()` stops it.
|
|
758
|
+
|
|
759
|
+
## Surviving resizes
|
|
760
|
+
|
|
761
|
+
Anything measured from the page — a pinned section's travel, a marquee's width —
|
|
762
|
+
changes when the window resizes or a phone rotates. Pass **functions** instead of
|
|
763
|
+
numbers and they are called again whenever the animation is rebuilt:
|
|
764
|
+
|
|
765
|
+
```js
|
|
766
|
+
const travel = () => track.scrollWidth - section.clientWidth
|
|
767
|
+
|
|
768
|
+
live.timeline({
|
|
769
|
+
scrollTrigger: { trigger: section, start: 'top top', end: () => `+=${travel()}`, pin: true, scrub: 0.5, invalidateOnRefresh: true },
|
|
770
|
+
})
|
|
771
|
+
.to(track, { x: () => -travel(), ease: 'none' })
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
- **Function values** in tween vars are called with `(index, target)` when the
|
|
775
|
+
tween is built. When they differ per target, each target gets its own tween.
|
|
776
|
+
- **`tl.invalidate()`** rebuilds a timeline from the same calls. It rewinds to
|
|
777
|
+
the start, so start values are read from elements before the timeline changed
|
|
778
|
+
them, re-runs every function value, and returns to the same progress. Call it
|
|
779
|
+
yourself for animations without a scroll trigger, e.g. on `resize`.
|
|
780
|
+
- **`invalidateOnRefresh: true`** does that on every scroll refresh, before start
|
|
781
|
+
and end are measured again.
|
|
782
|
+
|
|
783
|
+
## Responsive setups, reduced motion and cleanup
|
|
784
|
+
|
|
785
|
+
**`live.context(fn, scope?)`** collects everything the live API creates while `fn`
|
|
786
|
+
runs:
|
|
787
|
+
|
|
788
|
+
- timelines and tweens, with their scroll triggers and pins;
|
|
789
|
+
- split text and draggables;
|
|
790
|
+
- stand-alone scroll triggers and ticker callbacks;
|
|
791
|
+
- a cleanup function `fn` returns.
|
|
792
|
+
|
|
793
|
+
`ctx.revert()` undoes it all, newest first. Each element the context animated
|
|
794
|
+
gets its original inline style (and SVG `d`) back, and the stage forgets the
|
|
795
|
+
values it applied, so the next setup starts clean. Selectors inside resolve
|
|
796
|
+
within `scope`. That suits a component or a route: create the context on mount
|
|
797
|
+
and revert it on unmount.
|
|
798
|
+
|
|
799
|
+
```js
|
|
800
|
+
const ctx = live.context(() => {
|
|
801
|
+
live.from('.card', { y: 40, opacity: 0, stagger: 0.1 })
|
|
802
|
+
button.addEventListener('click', () => ctx.add(() => live.to('.card', { rotate: 5 })))
|
|
803
|
+
}, section)
|
|
804
|
+
|
|
805
|
+
ctx.revert()
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
Work created later, for example in an event handler, joins the context only when
|
|
809
|
+
it runs inside `ctx.add(fn)`.
|
|
810
|
+
|
|
811
|
+
**`live.matchMedia()`** runs setups while media queries match:
|
|
812
|
+
|
|
813
|
+
```js
|
|
814
|
+
const mm = live.matchMedia()
|
|
815
|
+
mm.add({ desktop: '(min-width: 800px)', reduce: '(prefers-reduced-motion: reduce)' }, (ctx) => {
|
|
816
|
+
const { desktop, reduce } = ctx.conditions
|
|
817
|
+
if (reduce) return live.set('.hero-title', { opacity: 1 }) // a real reduced-motion mode
|
|
818
|
+
live.timeline({ scrollTrigger: { pin: desktop, … } })
|
|
819
|
+
return () => { /* anything else to undo */ }
|
|
820
|
+
})
|
|
821
|
+
```
|
|
822
|
+
|
|
823
|
+
- Each setup runs in its own context while any of its queries match.
|
|
824
|
+
- It is reverted when they stop matching, and run again whenever the set of
|
|
825
|
+
matching conditions changes; `ctx.conditions` says which match.
|
|
826
|
+
- `mm.revert()` removes every setup and stops listening.
|
|
827
|
+
|
|
828
|
+
The [Agency Landing Page showcase](../src/examples/showcases/agency-landing.js)
|
|
829
|
+
wraps its whole page this way. Under reduced motion there is no pinning, parallax
|
|
830
|
+
or marquee, and values appear at their final state.
|
|
831
|
+
|
|
832
|
+
### Framework hooks
|
|
833
|
+
|
|
834
|
+
Each wrapper runs a setup inside `live.context()`, scoped to a component's element.
|
|
835
|
+
It reverts everything the setup made (tweens, scroll triggers and pins, split text,
|
|
836
|
+
draggables, smooth scrolling) when the component goes away:
|
|
837
|
+
|
|
838
|
+
```jsx
|
|
839
|
+
// React
|
|
840
|
+
import { useTinyfly } from '@algorisys/tinyfly/react'
|
|
841
|
+
const root = useRef(null)
|
|
842
|
+
const { contextSafe } = useTinyfly((live) => {
|
|
843
|
+
live.from('.title', { y: 40, opacity: 0 })
|
|
844
|
+
}, { scope: root, dependencies: [lang] }) // re-run (after reverting) when lang changes
|
|
845
|
+
const onClick = contextSafe(() => live.to('.cta', { scale: 1.1 })) // handlers join the context
|
|
846
|
+
```
|
|
847
|
+
|
|
848
|
+
```js
|
|
849
|
+
// Vue (<script setup>)
|
|
850
|
+
import { useTinyfly } from '@algorisys/tinyfly/vue'
|
|
851
|
+
const root = ref(null)
|
|
852
|
+
useTinyfly((live) => live.from('.title', { y: 40, opacity: 0 }), { scope: root, watch: [lang] })
|
|
853
|
+
```
|
|
854
|
+
|
|
855
|
+
```svelte
|
|
856
|
+
<!-- Svelte: an action, no import from svelte needed -->
|
|
857
|
+
<script>import { tinyfly } from '@algorisys/tinyfly/svelte'</script>
|
|
858
|
+
<section use:tinyfly={(live) => live.from('.title', { y: 40, opacity: 0 })}>…</section>
|
|
859
|
+
```
|
|
860
|
+
|
|
861
|
+
```jsx
|
|
862
|
+
// Solid
|
|
863
|
+
import { createTinyfly } from '@algorisys/tinyfly/solid'
|
|
864
|
+
let root
|
|
865
|
+
createTinyfly((live) => live.from('.title', { y: 40, opacity: 0 }), () => root)
|
|
866
|
+
```
|
|
867
|
+
|
|
868
|
+
The frameworks are optional peer dependencies, and each wrapper is under 1 KB. All
|
|
869
|
+
of them use the shared `live` from `@algorisys/tinyfly/gsap-compat`; pass `live` (the
|
|
870
|
+
`options.live` field, or the last argument for Svelte and Solid) to use a stage of
|
|
871
|
+
your own.
|
|
872
|
+
|
|
873
|
+
## Page transitions
|
|
874
|
+
|
|
875
|
+
`live.pageTransition` animates a client-side route change. It plays the old view
|
|
876
|
+
out, runs your `update` (render the next route; it may return a promise), carries
|
|
877
|
+
shared elements across by `data-flip-id`, and plays the new view in. It resolves
|
|
878
|
+
when everything has finished:
|
|
879
|
+
|
|
880
|
+
```js
|
|
881
|
+
router.onNavigate(async (next) => {
|
|
882
|
+
await live.pageTransition({
|
|
883
|
+
from: '.page',
|
|
884
|
+
to: '.page',
|
|
885
|
+
shared: '[data-flip-id]', // a thumbnail on one page, the hero on the next
|
|
886
|
+
update: () => render(next),
|
|
887
|
+
})
|
|
888
|
+
})
|
|
889
|
+
```
|
|
890
|
+
|
|
891
|
+
| Option | Default | |
|
|
892
|
+
|---|---|---|
|
|
893
|
+
| `update` | — | Change the page; may be async |
|
|
894
|
+
| `from`, `to` | — | The leaving and arriving views (`to` is resolved after `update`; a function is fine) |
|
|
895
|
+
| `shared` | — | Selector for elements matched across by `data-flip-id` |
|
|
896
|
+
| `leave`, `enter` | fade + 16px lift / drop | The values the old view goes to and the new view comes from, or `false` |
|
|
897
|
+
| `duration`, `ease` | `0.35`, `'power2.inOut'` | Per phase; shared elements take 1.4× the duration |
|
|
898
|
+
| `native` | `false` | Hand the change to the browser's View Transitions API when it has one |
|
|
899
|
+
|
|
900
|
+
- **Shared elements travel on their own.** When `shared` is given, `leave` and
|
|
901
|
+
`enter` animate the view's children that neither are nor contain a shared
|
|
902
|
+
element. Moving the whole view would drag the shared elements along.
|
|
903
|
+
- **Native mode.** Shared elements get `view-transition-name`s from their flip
|
|
904
|
+
ids and the browser runs the transition. Browsers without the API get the
|
|
905
|
+
tinyfly version, so the call works everywhere.
|
|
906
|
+
- **Scope.** It is for changes within one document, such as a client-side
|
|
907
|
+
router; a full page load starts a new document.
|
|
908
|
+
|
|
909
|
+
## Image sequences
|
|
910
|
+
|
|
911
|
+
`live.imageSequence` draws one frame of a numbered image sequence into a canvas.
|
|
912
|
+
Its `frame` is an ordinary number, so a tween or a scroll scrub turns the object:
|
|
913
|
+
|
|
914
|
+
```js
|
|
915
|
+
const phone = live.imageSequence('canvas.phone', {
|
|
916
|
+
frames: 120,
|
|
917
|
+
url: (i) => `/frames/phone_${String(i + 1).padStart(4, '0')}.webp`,
|
|
918
|
+
})
|
|
919
|
+
|
|
920
|
+
live.to(phone, {
|
|
921
|
+
frame: phone.frames - 1,
|
|
922
|
+
ease: 'none',
|
|
923
|
+
scrollTrigger: { trigger: '.product', start: 'top top', end: '+=2000', scrub: true, pin: true },
|
|
924
|
+
})
|
|
925
|
+
```
|
|
926
|
+
|
|
927
|
+
| Option | |
|
|
928
|
+
|---|---|
|
|
929
|
+
| `frames`, `url(index)` | How many frames, and where frame `index` (0-based) is |
|
|
930
|
+
| `fit` | `'cover'` (default) or `'contain'` |
|
|
931
|
+
| `concurrency` | Images loading at once (default 6) |
|
|
932
|
+
| `onProgress(loaded, total)` | Called as frames arrive |
|
|
933
|
+
|
|
934
|
+
- **Loading.** The first frame loads straight away. The rest load a few at a
|
|
935
|
+
time, nearest the frame on screen first. Until a frame arrives, the nearest
|
|
936
|
+
loaded one is drawn, so scrubbing ahead of the network never shows a blank
|
|
937
|
+
canvas.
|
|
938
|
+
- **Drawing.** Setting `frame` draws the nearest whole frame, and only when it
|
|
939
|
+
changes. The canvas is sized to its box at the device pixel ratio (capped at
|
|
940
|
+
2) and resized with the window.
|
|
941
|
+
- **Cleanup.** `sequence.destroy()` stops loading. Contexts and matchMedia
|
|
942
|
+
setups do this for you.
|
|
943
|
+
|
|
944
|
+
## Split text
|
|
945
|
+
|
|
946
|
+
`live.splitText` wraps text in spans so characters, words or lines can be
|
|
947
|
+
animated one after another (GSAP's SplitText):
|
|
948
|
+
|
|
949
|
+
```js
|
|
950
|
+
const split = live.splitText('.headline', { type: 'lines', mask: 'lines' })
|
|
951
|
+
live.fromTo(split.lines, { y: 40 }, { y: 0, duration: 0.9, ease: 'expo.out', stagger: 0.12 })
|
|
952
|
+
|
|
953
|
+
const title = live.splitText('.title', { type: 'words,chars' })
|
|
954
|
+
live.from(title.chars, { opacity: 0, y: 30, rotateX: -90, stagger: 0.03 })
|
|
955
|
+
|
|
956
|
+
split.revert() // the original markup
|
|
957
|
+
```
|
|
958
|
+
|
|
959
|
+
| Option | Default | |
|
|
960
|
+
|---|---|---|
|
|
961
|
+
| `type` | `'chars,words,lines'` | Which pieces to create, comma-separated |
|
|
962
|
+
| `mask` | — | `'lines'`, `'words'` or `'chars'`: wrap each in an `overflow: clip` span, for reveals from behind an edge. Masks leave 0.12em below the baseline (with a matching negative margin) so descenders aren't clipped |
|
|
963
|
+
| `charsClass`, `wordsClass`, `linesClass` | `char`, `word`, `line` | Class names (masks get `<class>-mask`) |
|
|
964
|
+
| `aria` | `true` | Put the text in the element's `aria-label` and hide the pieces from screen readers |
|
|
965
|
+
| `autoSplit` | `false` | Split again when an element's width changes or fonts load |
|
|
966
|
+
| `onSplit(self)` | — | Called after every split; return the animation built on the pieces |
|
|
967
|
+
|
|
968
|
+
It returns `{ elements, chars, words, lines, masks, revert() }`.
|
|
969
|
+
|
|
970
|
+
What it does to the markup:
|
|
971
|
+
|
|
972
|
+
- **Words** become inline-block spans, so they can move and never break in the
|
|
973
|
+
middle. Spaces stay as real text between them, so the text still wraps,
|
|
974
|
+
selects and copies normally. Words are wrapped even when you only ask for
|
|
975
|
+
`chars` or `lines` (they just aren't returned or classed).
|
|
976
|
+
- **Characters** are grapheme clusters, so an emoji or an accented letter stays in one piece.
|
|
977
|
+
- **Lines** are measured once, from where the browser wrapped the words. Inline
|
|
978
|
+
markup such as `<em>` or `<a>` is kept and cloned into each line it spans;
|
|
979
|
+
`<br>` ends a line. Lines depend on the element's width: with `autoSplit: true`
|
|
980
|
+
the text is split again when an element's width changes or web fonts finish
|
|
981
|
+
loading. Build the animation in `onSplit(self)` and return it, so it is killed
|
|
982
|
+
before the pieces it animated are replaced. `split.split()` re-splits by hand.
|
|
983
|
+
- `revert()` restores the saved HTML. Event listeners attached to elements
|
|
984
|
+
*inside* the split element are lost; attach them to the element itself.
|
|
985
|
+
|
|
986
|
+
## Flip
|
|
987
|
+
|
|
988
|
+
Animate elements from where they were to where a layout change put them:
|
|
989
|
+
|
|
990
|
+
```ts
|
|
991
|
+
live.flip('.item', () => grid.classList.toggle('compact'), { duration: 0.6, ease: 'power2.inOut', stagger: 0.03 })
|
|
992
|
+
|
|
993
|
+
// Or in two steps, when the change happens elsewhere:
|
|
994
|
+
const state = live.getFlipState('.item')
|
|
995
|
+
renderNewOrder()
|
|
996
|
+
live.flipFrom(state, { duration: 0.5, targets: '.item' })
|
|
997
|
+
```
|
|
998
|
+
|
|
999
|
+
| Option | Meaning |
|
|
1000
|
+
|---|---|
|
|
1001
|
+
| `duration`, `ease` | As for any tween (default 0.6s, `power2.inOut`) |
|
|
1002
|
+
| `stagger` | Seconds between elements, in document order |
|
|
1003
|
+
| `scale` | Animate size changes with scaleX/scaleY (default `true`); `false` moves only |
|
|
1004
|
+
| `targets` | Elements that may have appeared in the change (`live.flip` passes its own) |
|
|
1005
|
+
| `enter` | Start values for newly visible elements (default `{ opacity: 0, scale: 0.6 }`), or `false` |
|
|
1006
|
+
| `fade` | Cross-fade shared elements (below): the incoming one fades in, the one it replaces fades out if still shown |
|
|
1007
|
+
| `onComplete` | Called when it finishes |
|
|
1008
|
+
|
|
1009
|
+
Any change works: reorder the DOM, toggle classes, hide and show, resize.
|
|
1010
|
+
|
|
1011
|
+
**How it measures.** Before the change, where each element *appears*, including
|
|
1012
|
+
the transform it may be animating with. After, where it is *laid out*, ignoring
|
|
1013
|
+
transforms. Offsets are between centres, since scale happens about the centre.
|
|
1014
|
+
Each element then gets an ordinary `fromTo` back to rest, so the result is plain
|
|
1015
|
+
track data.
|
|
1016
|
+
|
|
1017
|
+
**Interrupting is smooth.** Starting a flip while another is running takes over
|
|
1018
|
+
each element from where it appears right now.
|
|
1019
|
+
|
|
1020
|
+
**Shared elements.** Give two different elements the same `data-flip-id` and
|
|
1021
|
+
they are treated as one thing: an element that was not recorded, but whose flip
|
|
1022
|
+
id was, flips from where the recorded element was. That is how a gallery
|
|
1023
|
+
thumbnail grows into a detail view's hero image, which is a separate element:
|
|
1024
|
+
|
|
1025
|
+
```js
|
|
1026
|
+
thumb.addEventListener('click', () => {
|
|
1027
|
+
const state = live.getFlipState(thumb) // record only what is leaving
|
|
1028
|
+
hero.dataset.flipId = thumb.dataset.flipId // same id → same "thing"
|
|
1029
|
+
detail.hidden = false
|
|
1030
|
+
live.flipFrom(state, { targets: hero, fade: true, duration: 0.6 })
|
|
1031
|
+
})
|
|
1032
|
+
|
|
1033
|
+
close.addEventListener('click', () => {
|
|
1034
|
+
const state = live.getFlipState(hero)
|
|
1035
|
+
detail.hidden = true
|
|
1036
|
+
live.flipFrom(state, { targets: thumb, fade: true })
|
|
1037
|
+
})
|
|
1038
|
+
```
|
|
1039
|
+
|
|
1040
|
+
Record only the element that is leaving: if both elements are in the state, each
|
|
1041
|
+
is matched to itself. Matching works within one document (a client-side route
|
|
1042
|
+
change counts; a full page load does not).
|
|
1043
|
+
|
|
1044
|
+
**Limits.** Size changes scale the element, so its content scales too during
|
|
1045
|
+
the animation (text looks stretched mid-flip). Elements that disappear are not
|
|
1046
|
+
animated out, because they are no longer rendered to see. There is no `absolute`
|
|
1047
|
+
or `nested` mode yet.
|
|
1048
|
+
|
|
1049
|
+
## Inertia and dragging
|
|
1050
|
+
|
|
1051
|
+
A throw that slows under friction and comes to rest — GSAP's InertiaPlugin:
|
|
1052
|
+
|
|
1053
|
+
```ts
|
|
1054
|
+
live.to('.puck', { inertia: { x: { velocity: 900, max: 400, end: 50 }, y: -300 } })
|
|
1055
|
+
```
|
|
1056
|
+
|
|
1057
|
+
| Per-property option | Meaning |
|
|
1058
|
+
|---|---|
|
|
1059
|
+
| `velocity` | Speed at release, units per second (a bare number means just this) |
|
|
1060
|
+
| `min`, `max` | Keep the resting place in bounds |
|
|
1061
|
+
| `end` | Snap: a grid increment, a list of values, or a function `(naturalEnd) => number` |
|
|
1062
|
+
| `friction` / `resistance` | How quickly it slows (friction 4 = resistance 100, the default) |
|
|
1063
|
+
|
|
1064
|
+
A throw decides its own duration, so `duration` is ignored for it, and the next
|
|
1065
|
+
tween on the timeline starts after it — from where it came to rest. An `end`
|
|
1066
|
+
function runs once, when the tween is built; the track stores the number.
|
|
1067
|
+
|
|
1068
|
+
**Dragging.** `live.draggable()` drags an element and throws it on release:
|
|
1069
|
+
|
|
1070
|
+
```ts
|
|
1071
|
+
const slots = [{ x: 0, y: 0 }, { x: 180, y: 0 }, { x: 0, y: 90 }]
|
|
1072
|
+
live.draggable('.card', { bounds: '.table', inertia: { end: slots, friction: 5 } })
|
|
1073
|
+
live.draggable('.strip', { type: 'x', bounds: { minX: -480, maxX: 0 }, inertia: { end: { x: 120 } } })
|
|
1074
|
+
```
|
|
1075
|
+
|
|
1076
|
+
| Option | Meaning |
|
|
1077
|
+
|---|---|
|
|
1078
|
+
| `type` | `'x'`, `'y'`, `'x,y'` (default), or `'rotation'` to spin it about its centre |
|
|
1079
|
+
| `bounds` | An element (selector or element) to stay inside, or `{ minX, maxX, minY, maxY }` offsets; for rotation `{ minRotation, maxRotation }` |
|
|
1080
|
+
| `snap` | Grid size while dragging (degrees, for rotation) |
|
|
1081
|
+
| `inertia` | `true`, or `{ friction, resistance, end }` — `end` as a grid size, per-axis `{ x, y }`, or `{x, y}` points (nearest in 2D wins) |
|
|
1082
|
+
| `onPress`, `onDrag`, `onRelease(velocity)`, `onThrowComplete` | Callbacks |
|
|
1083
|
+
|
|
1084
|
+
```ts
|
|
1085
|
+
// A volume knob: drag around it, 0–270°, snapping to 15°, and flick to spin on.
|
|
1086
|
+
live.draggable('.knob', { type: 'rotation', bounds: { minRotation: 0, maxRotation: 270 }, snap: 15, inertia: true })
|
|
1087
|
+
```
|
|
1088
|
+
|
|
1089
|
+
Rotation follows the pointer's angle about the element's centre. It keeps turning
|
|
1090
|
+
past ±180° without jumping, and `draggable.rotation` reads it.
|
|
1091
|
+
|
|
1092
|
+
Dragging writes positions straight to the stage; the throw is an ordinary
|
|
1093
|
+
inertia tween. Picking the element up mid-throw stops it where it is. Give
|
|
1094
|
+
draggable elements `touch-action: none` so touch drags are not taken by page
|
|
1095
|
+
scrolling.
|
|
1096
|
+
|
|
1097
|
+
**How it works.** Friction is exponential decay, which has an exact closed form,
|
|
1098
|
+
so the value at any time is computed directly — no simulation, identical when
|
|
1099
|
+
scrubbed backwards. Snapping aims the throw at the snap point while keeping its
|
|
1100
|
+
rate of deceleration, so it lands exactly there without looking steered.
|
|
1101
|
+
|
|
1102
|
+
## Springs
|
|
1103
|
+
|
|
1104
|
+
`spring` on a tween animates its numeric properties with spring physics instead
|
|
1105
|
+
of a duration and an ease:
|
|
1106
|
+
|
|
1107
|
+
```js
|
|
1108
|
+
live.to('.card', { x: 0, scale: 1, spring: 'bouncy' })
|
|
1109
|
+
live.to('.card', { y: 0, spring: { stiffness: 260, damping: 14, mass: 1 } })
|
|
1110
|
+
|
|
1111
|
+
// Release a drag into a spring, keeping the fling.
|
|
1112
|
+
live.draggable('.card', {
|
|
1113
|
+
onRelease: (velocity) => live.to('.card', { x: 0, y: 0, spring: { preset: 'wobbly', velocity } }),
|
|
1114
|
+
})
|
|
1115
|
+
```
|
|
1116
|
+
|
|
1117
|
+
| Value | |
|
|
1118
|
+
|---|---|
|
|
1119
|
+
| `true` | The default spring (stiffness 180, damping 12, mass 1) |
|
|
1120
|
+
| `'gentle'`, `'default'`, `'snappy'`, `'bouncy'`, `'wobbly'`, `'stiff'` | The presets the editor's spring inspector offers (`SPRING_PRESETS`) |
|
|
1121
|
+
| `{ preset?, stiffness?, damping?, mass?, velocity?, restDelta? }` | Parameters, optionally over a preset. `velocity` is units per second — one number, or per property (`{ x: 800, y: -200 }`) |
|
|
1122
|
+
|
|
1123
|
+
- Each numeric property compiles to a **spring track**, so the result is still
|
|
1124
|
+
deterministic, scrubbable and plain JSON. Properties that are not numbers (a
|
|
1125
|
+
colour) keep tweening with `duration` and `ease`.
|
|
1126
|
+
- A spring settles in its own time: `duration` and `ease` are ignored for the
|
|
1127
|
+
sprung properties, and the tween lasts as long as its slowest spring.
|
|
1128
|
+
- **Interruptions keep their momentum.** Without a `velocity`, `live` starts the
|
|
1129
|
+
spring at the speed the property is already moving — measured once from the
|
|
1130
|
+
animation it takes over — so re-targeting mid-motion does not stall.
|
|
1131
|
+
- All the sprung properties run on the shared frame loop, and each element is
|
|
1132
|
+
written once per frame however many there are.
|
|
1133
|
+
|
|
1134
|
+
The same spring as a track, without the GSAP-style API:
|
|
1135
|
+
|
|
1136
|
+
```ts
|
|
1137
|
+
import { Timeline } from '@algorisys/tinyfly'
|
|
1138
|
+
|
|
1139
|
+
const timeline = new Timeline({ id: 'springy' })
|
|
1140
|
+
timeline.addTrack({
|
|
1141
|
+
id: 'pop',
|
|
1142
|
+
target: 'box',
|
|
1143
|
+
property: 'scale',
|
|
1144
|
+
kind: 'spring',
|
|
1145
|
+
spring: { from: 0, to: 1, stiffness: 200, damping: 12 },
|
|
1146
|
+
})
|
|
1147
|
+
```
|
|
1148
|
+
|
|
1149
|
+
Spring tracks are integrated at a fixed timestep from t=0, so scrubbing
|
|
1150
|
+
backwards gives the same values as playing forwards and two runs are identical.
|
|
1151
|
+
The animation is the *parameters*, so it serializes like anything else.
|
|
1152
|
+
|
|
1153
|
+
## Utilities, random values and `repeatRefresh`
|
|
1154
|
+
|
|
1155
|
+
`live.utils` has GSAP's utility functions. Most return a reusable function when the
|
|
1156
|
+
last argument is left out:
|
|
1157
|
+
|
|
1158
|
+
```js
|
|
1159
|
+
const { clamp, mapRange, interpolate, wrap, snap, random, distribute, pipe } = live.utils
|
|
1160
|
+
|
|
1161
|
+
const toPercent = mapRange(0, innerWidth, 0, 100)
|
|
1162
|
+
const colour = interpolate('#c6ff3d', '#ec4899', 0.5)
|
|
1163
|
+
const lane = wrap(['left', 'middle', 'right']) // lane(4) → 'middle'
|
|
1164
|
+
const settle = pipe(clamp(0, 100), snap(5))
|
|
1165
|
+
|
|
1166
|
+
live.to('.dot', {
|
|
1167
|
+
x: 'random(-200, 200, 10)', // per element, as in GSAP
|
|
1168
|
+
y: () => random(-50, 50),
|
|
1169
|
+
scale: distribute({ base: 0.5, amount: 1, from: 'center' }),
|
|
1170
|
+
})
|
|
1171
|
+
|
|
1172
|
+
live.timeline({ repeat: -1, repeatRefresh: true }) // new random values every loop
|
|
1173
|
+
.to('.star', { x: 'random(-300, 300)', y: 'random(-200, 200)', duration: 1.2 })
|
|
1174
|
+
|
|
1175
|
+
live.getProperty('.card', 'x') // what tinyfly last applied
|
|
1176
|
+
```
|
|
1177
|
+
|
|
1178
|
+
- **Functions:**
|
|
1179
|
+
- maths: `clamp`, `mapRange`, `normalize`, `interpolate` (numbers, colours, arrays,
|
|
1180
|
+
objects);
|
|
1181
|
+
- cycling: `wrap` (ranges or arrays), `wrapYoyo`;
|
|
1182
|
+
- snapping and random: `snap` (increment, values, radius), `random` (range, snap, or
|
|
1183
|
+
array), `shuffle`;
|
|
1184
|
+
- composing: `distribute`, `pipe`;
|
|
1185
|
+
- parsing: `splitColor`, `getUnit`.
|
|
1186
|
+
- **Random is seeded.** `random`, `shuffle` and `"random(…)"` share one sequence per
|
|
1187
|
+
stage, starting from seed 1. A page builds the same "random" layout on every load,
|
|
1188
|
+
and a replay is identical. Call `live.utils.seed(Date.now())` if it should differ.
|
|
1189
|
+
- **Function values** are called with `(index, target, targets)` when the tween is
|
|
1190
|
+
built, and again by `invalidate()` and scroll refreshes.
|
|
1191
|
+
- **`repeatRefresh: true`** rebuilds the timeline at each repeat, so function and
|
|
1192
|
+
random values are drawn again. The rebuilt tweens start from where the previous loop
|
|
1193
|
+
left the values, as in GSAP.
|
|
1194
|
+
- **`getProperty`** returns the value tinyfly last applied, or a plain object's own
|
|
1195
|
+
value, falling back to the property's static default. It never reads computed styles.
|
|
1196
|
+
|
|
1197
|
+
## Compile-time values
|
|
1198
|
+
|
|
1199
|
+
`"+=100"` and `"random(-50, 50)"` are resolved when the timeline is built, and
|
|
1200
|
+
the concrete number is what lands in the JSON:
|
|
1201
|
+
|
|
1202
|
+
```ts
|
|
1203
|
+
import { ValueResolver } from '@algorisys/tinyfly'
|
|
1204
|
+
|
|
1205
|
+
const resolver = new ValueResolver(2024) // the seed
|
|
1206
|
+
resolver.resolveSequence([0, '+=100', 'random(-50, 50)'])
|
|
1207
|
+
// → [0, 100, -12.34] — same seed, same numbers, every time
|
|
1208
|
+
|
|
1209
|
+
resolver.seed // store this alongside the timeline to reproduce it
|
|
1210
|
+
```
|
|
1211
|
+
|
|
1212
|
+
## Full example
|
|
1213
|
+
|
|
1214
|
+
```ts
|
|
1215
|
+
import { timeline, quickPlay } from '@algorisys/tinyfly/gsap-compat'
|
|
1216
|
+
|
|
1217
|
+
const tl = timeline({
|
|
1218
|
+
repeat: -1,
|
|
1219
|
+
yoyo: true,
|
|
1220
|
+
repeatDelay: 0.5,
|
|
1221
|
+
onWarning: console.warn,
|
|
1222
|
+
})
|
|
1223
|
+
|
|
1224
|
+
tl.fromTo('title', { y: -40, opacity: 0 }, { y: 0, opacity: 1, duration: 0.8, ease: 'power3.out' })
|
|
1225
|
+
tl.addLabel('lettersIn')
|
|
1226
|
+
tl.fromTo(
|
|
1227
|
+
['l1', 'l2', 'l3', 'l4'],
|
|
1228
|
+
{ opacity: 0, y: 20 },
|
|
1229
|
+
{ opacity: 1, y: 0, duration: 0.5, stagger: { each: 0.08, from: 'center' } },
|
|
1230
|
+
'lettersIn'
|
|
1231
|
+
)
|
|
1232
|
+
tl.to('title', { scale: 1.05, duration: 0.3 }, '>')
|
|
1233
|
+
|
|
1234
|
+
// Inspect what it compiled to — it is ordinary tinyfly JSON.
|
|
1235
|
+
console.log(JSON.stringify(tl.toDefinition(), null, 2))
|
|
1236
|
+
|
|
1237
|
+
quickPlay({
|
|
1238
|
+
timeline: tl.timeline,
|
|
1239
|
+
targets: { title: '#title', l1: '#l1', l2: '#l2', l3: '#l3', l4: '#l4' },
|
|
1240
|
+
})
|
|
1241
|
+
```
|