@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.
Files changed (140) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +672 -0
  3. package/bin/tinyfly.mjs +59 -0
  4. package/lib/addons/adapters.js +756 -0
  5. package/lib/addons/dom-adapter-ChrbtkLC.js +243 -0
  6. package/lib/addons/drivers.js +72 -0
  7. package/lib/addons/export.js +1169 -0
  8. package/lib/addons/gsap-compat.js +2576 -0
  9. package/lib/addons/interaction.js +225 -0
  10. package/lib/addons/smooth-scroll-DaSacemU.js +671 -0
  11. package/lib/addons/teach.js +215 -0
  12. package/lib/browser/tinyfly.iife.js +2 -0
  13. package/lib/browser/tinyfly.js +6372 -0
  14. package/lib/browser/tinyfly.umd.js +2 -0
  15. package/lib/cli/tools.js +2325 -0
  16. package/lib/embed/tinyfly-embed.iife.js +18 -0
  17. package/lib/embed/tinyfly-embed.js +2316 -0
  18. package/lib/engine/tinyfly-engine.js +1972 -0
  19. package/lib/engine/tinyfly-engine.umd.cjs +2 -0
  20. package/lib/frameworks/react.js +32 -0
  21. package/lib/frameworks/solid.js +27 -0
  22. package/lib/frameworks/svelte.js +15 -0
  23. package/lib/frameworks/vue.js +29 -0
  24. package/lib/player/tinyfly-player.es.js +2306 -0
  25. package/lib/player/tinyfly-player.iife.js +2 -0
  26. package/lib/player/tinyfly-player.umd.js +2 -0
  27. package/lib/types/adapters/canvas/canvas-adapter.d.ts +238 -0
  28. package/lib/types/adapters/canvas/index.d.ts +1 -0
  29. package/lib/types/adapters/dom/dom-adapter.d.ts +50 -0
  30. package/lib/types/adapters/dom/flip.d.ts +60 -0
  31. package/lib/types/adapters/dom/index.d.ts +2 -0
  32. package/lib/types/adapters/filter-utils.d.ts +32 -0
  33. package/lib/types/adapters/index.d.ts +5 -0
  34. package/lib/types/adapters/shine-utils.d.ts +26 -0
  35. package/lib/types/adapters/svg/index.d.ts +1 -0
  36. package/lib/types/adapters/svg/svg-adapter.d.ts +47 -0
  37. package/lib/types/adapters/svg-transform-box.d.ts +13 -0
  38. package/lib/types/adapters/text-content.d.ts +11 -0
  39. package/lib/types/adapters/webgl/index.d.ts +1 -0
  40. package/lib/types/adapters/webgl/webgl-adapter.d.ts +69 -0
  41. package/lib/types/browser/index.d.ts +41 -0
  42. package/lib/types/compat/gsap/custom-eases.d.ts +28 -0
  43. package/lib/types/compat/gsap/defaults.d.ts +19 -0
  44. package/lib/types/compat/gsap/draw-svg-vars.d.ts +36 -0
  45. package/lib/types/compat/gsap/ease-map.d.ts +51 -0
  46. package/lib/types/compat/gsap/image-sequence.d.ts +61 -0
  47. package/lib/types/compat/gsap/index.d.ts +65 -0
  48. package/lib/types/compat/gsap/inertia-vars.d.ts +39 -0
  49. package/lib/types/compat/gsap/keyframes-vars.d.ts +8 -0
  50. package/lib/types/compat/gsap/layout.d.ts +6 -0
  51. package/lib/types/compat/gsap/live-context.d.ts +87 -0
  52. package/lib/types/compat/gsap/live-draggable.d.ts +75 -0
  53. package/lib/types/compat/gsap/live-flip.d.ts +73 -0
  54. package/lib/types/compat/gsap/live-morph.d.ts +18 -0
  55. package/lib/types/compat/gsap/live-motion-path.d.ts +33 -0
  56. package/lib/types/compat/gsap/live-scroll-to.d.ts +52 -0
  57. package/lib/types/compat/gsap/live-scroll.d.ts +108 -0
  58. package/lib/types/compat/gsap/live-transition.d.ts +40 -0
  59. package/lib/types/compat/gsap/live.d.ts +341 -0
  60. package/lib/types/compat/gsap/morph-vars.d.ts +21 -0
  61. package/lib/types/compat/gsap/motion-path-vars.d.ts +38 -0
  62. package/lib/types/compat/gsap/playhead-crossings.d.ts +47 -0
  63. package/lib/types/compat/gsap/position.d.ts +37 -0
  64. package/lib/types/compat/gsap/quick-play.d.ts +38 -0
  65. package/lib/types/compat/gsap/split-text.d.ts +66 -0
  66. package/lib/types/compat/gsap/spring-vars.d.ts +34 -0
  67. package/lib/types/compat/gsap/stage.d.ts +182 -0
  68. package/lib/types/compat/gsap/stagger-grid.d.ts +30 -0
  69. package/lib/types/compat/gsap/text-vars.d.ts +39 -0
  70. package/lib/types/compat/gsap/timeline.d.ts +161 -0
  71. package/lib/types/compat/gsap/utils.d.ts +60 -0
  72. package/lib/types/compat/gsap/vars.d.ts +79 -0
  73. package/lib/types/drivers/index.d.ts +8 -0
  74. package/lib/types/drivers/scroll-driver.d.ts +218 -0
  75. package/lib/types/drivers/scroll-markers.d.ts +41 -0
  76. package/lib/types/drivers/scroll-math.d.ts +87 -0
  77. package/lib/types/drivers/scroll-pin.d.ts +45 -0
  78. package/lib/types/drivers/scroll-snap.d.ts +47 -0
  79. package/lib/types/drivers/smooth-scroll.d.ts +118 -0
  80. package/lib/types/drivers/types.d.ts +23 -0
  81. package/lib/types/drivers/visibility-driver.d.ts +56 -0
  82. package/lib/types/embed/controls.d.ts +46 -0
  83. package/lib/types/embed/index.d.ts +17 -0
  84. package/lib/types/embed/mount.d.ts +41 -0
  85. package/lib/types/embed/tools.d.ts +33 -0
  86. package/lib/types/engine/authoring/custom-ease.d.ts +49 -0
  87. package/lib/types/engine/authoring/index.d.ts +3 -0
  88. package/lib/types/engine/authoring/random.d.ts +38 -0
  89. package/lib/types/engine/authoring/resolve-values.d.ts +57 -0
  90. package/lib/types/engine/core/bake.d.ts +66 -0
  91. package/lib/types/engine/core/clock.d.ts +44 -0
  92. package/lib/types/engine/core/index.d.ts +8 -0
  93. package/lib/types/engine/core/inertia.d.ts +30 -0
  94. package/lib/types/engine/core/playhead-crossings.d.ts +47 -0
  95. package/lib/types/engine/core/spring.d.ts +132 -0
  96. package/lib/types/engine/core/stagger.d.ts +40 -0
  97. package/lib/types/engine/core/timeline.d.ts +203 -0
  98. package/lib/types/engine/core/track.d.ts +90 -0
  99. package/lib/types/engine/export/byte-writer.d.ts +36 -0
  100. package/lib/types/engine/export/css.d.ts +31 -0
  101. package/lib/types/engine/export/gif-decode.test-helper.d.ts +24 -0
  102. package/lib/types/engine/export/gif.d.ts +134 -0
  103. package/lib/types/engine/export/index.d.ts +9 -0
  104. package/lib/types/engine/export/lottie.d.ts +104 -0
  105. package/lib/types/engine/export/mp4.d.ts +64 -0
  106. package/lib/types/engine/export/quantize.d.ts +56 -0
  107. package/lib/types/engine/export/sprite-sheet.d.ts +46 -0
  108. package/lib/types/engine/export/video.d.ts +99 -0
  109. package/lib/types/engine/export/webp.d.ts +82 -0
  110. package/lib/types/engine/index.d.ts +7 -0
  111. package/lib/types/engine/interpolation/easing.d.ts +65 -0
  112. package/lib/types/engine/interpolation/index.d.ts +2 -0
  113. package/lib/types/engine/interpolation/interpolators.d.ts +25 -0
  114. package/lib/types/engine/path/index.d.ts +11 -0
  115. package/lib/types/engine/path/motion-path.d.ts +24 -0
  116. package/lib/types/engine/path/path-builders.d.ts +38 -0
  117. package/lib/types/engine/path/path-morph.d.ts +47 -0
  118. package/lib/types/engine/path/path-utils.d.ts +73 -0
  119. package/lib/types/engine/serialization/index.d.ts +1 -0
  120. package/lib/types/engine/serialization/json.d.ts +30 -0
  121. package/lib/types/engine/text/index.d.ts +2 -0
  122. package/lib/types/engine/text/text-value.d.ts +16 -0
  123. package/lib/types/engine/types.d.ts +401 -0
  124. package/lib/types/frameworks/react.d.ts +35 -0
  125. package/lib/types/frameworks/solid.d.ts +16 -0
  126. package/lib/types/frameworks/svelte.d.ts +19 -0
  127. package/lib/types/frameworks/vue.d.ts +27 -0
  128. package/lib/types/interaction/draggable.d.ts +133 -0
  129. package/lib/types/interaction/index.d.ts +3 -0
  130. package/lib/types/interaction/observer.d.ts +80 -0
  131. package/lib/types/interaction/snap.d.ts +30 -0
  132. package/lib/types/player/index.d.ts +7 -0
  133. package/lib/types/player/media-sync.d.ts +60 -0
  134. package/lib/types/player/player.d.ts +238 -0
  135. package/lib/types/player/sequence-types.d.ts +68 -0
  136. package/lib/types/player/sequencer.d.ts +91 -0
  137. package/lib/types/teach/diagrams.d.ts +137 -0
  138. package/lib/types/teach/index.d.ts +11 -0
  139. package/lib/types/teach/lesson.d.ts +55 -0
  140. package/package.json +170 -0
@@ -0,0 +1,87 @@
1
+ /**
2
+ * Scoped setup and cleanup for the live runtime — GSAP's `gsap.context()` and
3
+ * `gsap.matchMedia()`.
4
+ *
5
+ * const ctx = live.context(() => {
6
+ * live.from('.card', { y: 40, stagger: 0.1 })
7
+ * live.timeline({ scrollTrigger: { pin: true, … } }).to(…)
8
+ * }, section)
9
+ * ctx.revert() // kills it all, removes pins, restores the elements' styles
10
+ *
11
+ * const mm = live.matchMedia()
12
+ * mm.add({ desktop: '(min-width: 800px)', reduce: '(prefers-reduced-motion: reduce)' }, (ctx) => {
13
+ * if (ctx.conditions.reduce) return
14
+ * …
15
+ * })
16
+ *
17
+ * While a context's function runs, everything the live API creates registers
18
+ * with it: timelines and tweens (and so their scroll triggers and pins), split
19
+ * text, draggables, stand-alone scroll triggers and ticker callbacks. Anything
20
+ * created later — in an event handler — joins by running inside `ctx.add()`.
21
+ *
22
+ * Reverting kills what was created, newest first, then restores each element
23
+ * the context animated to the inline style (and SVG `d`) it had before, and
24
+ * makes the stage forget the values it applied, so a later setup starts clean.
25
+ */
26
+ /** Something a context can undo. */
27
+ export interface Revertible {
28
+ revert?(): unknown;
29
+ kill?(): unknown;
30
+ destroy?(): unknown;
31
+ }
32
+ /** What the live API reports to the context that is currently collecting. */
33
+ export interface ContextCollector {
34
+ /** Selectors resolve within this, when given */
35
+ readonly scope?: ParentNode;
36
+ track(item: Revertible): void;
37
+ /** Called before an element is first written to */
38
+ touch(element: Element, name: string): void;
39
+ }
40
+ /** How a context switches collection on and off, and forgets applied values. */
41
+ export interface ContextHost {
42
+ readonly collector: ContextCollector | undefined;
43
+ setCollector(collector: ContextCollector | undefined): void;
44
+ forget(name: string): void;
45
+ }
46
+ export declare class LiveContext implements ContextCollector {
47
+ /** For contexts made by matchMedia: which named queries match */
48
+ conditions: Record<string, boolean>;
49
+ readonly scope?: ParentNode;
50
+ private readonly host;
51
+ private readonly items;
52
+ private readonly snapshots;
53
+ constructor(host: ContextHost, scope?: ParentNode);
54
+ /**
55
+ * Run `fn` with this context collecting, and return what it returns. A function
56
+ * it returns is kept as cleanup and called on `revert()`.
57
+ */
58
+ add<T>(fn: () => T): T;
59
+ track(item: Revertible): void;
60
+ touch(element: Element, name: string): void;
61
+ /** Undo everything, newest first, and restore the elements this context animated. */
62
+ revert(): void;
63
+ /** Same as `revert()`: GSAP's name for dropping a context. */
64
+ kill(): void;
65
+ }
66
+ type Conditions = string | Record<string, string>;
67
+ /**
68
+ * Setups that apply while media queries match. Each `add()` runs its setup in a
69
+ * context when (any of) its queries match, reverts it when they stop matching,
70
+ * and runs it again for the new conditions when they change.
71
+ */
72
+ export declare class LiveMatchMedia {
73
+ private readonly host;
74
+ private readonly scope?;
75
+ private readonly entries;
76
+ private readonly listeners;
77
+ private scheduled;
78
+ constructor(host: ContextHost, scope?: ParentNode);
79
+ add(conditions: Conditions, setup: (context: LiveContext) => unknown): this;
80
+ /** Revert every active setup and stop listening. */
81
+ revert(): void;
82
+ kill(): void;
83
+ /** Several queries change on one resize; handle them together. */
84
+ private scheduleUpdate;
85
+ private update;
86
+ }
87
+ export {};
@@ -0,0 +1,75 @@
1
+ import { Draggable, type DragBounds } from '../../interaction/draggable';
2
+ import type { LiveApi } from './live';
3
+ import type { Stage, TargetInput } from './stage';
4
+ /**
5
+ * Drag an element, and optionally throw it with inertia on release — GSAP's
6
+ * Draggable with `inertia: true`.
7
+ *
8
+ * live.draggable('.card', { bounds: '.table', inertia: { end: slots } })
9
+ *
10
+ * Dragging writes the position straight to the stage (no timeline per move).
11
+ * Releasing builds an ordinary `inertia` tween from the drag's release velocity,
12
+ * so the throw itself is plain, serializable track data like anything else.
13
+ * Pressing again mid-throw stops it and picks the element up where it is.
14
+ */
15
+ export interface LiveThrowOptions {
16
+ /** Decay rate per second (default 4); higher stops sooner */
17
+ friction?: number;
18
+ /** GSAP-style resistance (100 ≈ friction 4); ignored if `friction` is set */
19
+ resistance?: number;
20
+ /**
21
+ * Where the element may come to rest: a grid increment, per-axis increments or
22
+ * values (`{ x: [0, 200], y: 50 }`), or a list of points — the one nearest to
23
+ * where the throw would naturally stop wins.
24
+ */
25
+ end?: number | Array<{
26
+ x: number;
27
+ y: number;
28
+ }> | {
29
+ x?: number | number[];
30
+ y?: number | number[];
31
+ };
32
+ }
33
+ export interface LiveDraggableOptions {
34
+ /** Which axes move: 'x', 'y' or 'x,y' (default); `'rotation'` spins it about its centre (knobs, dials) */
35
+ type?: 'x' | 'y' | 'x,y' | 'rotation';
36
+ /**
37
+ * Keep the element inside another element (selector or element), or explicit
38
+ * offsets; for rotation, `{ minRotation, maxRotation }` in degrees
39
+ */
40
+ bounds?: string | Element | DragBounds | RotationBounds;
41
+ /** Snap to a grid of this size, in pixels (degrees, for rotation), while dragging */
42
+ snap?: number;
43
+ /** Throw on release. `true` uses the defaults. */
44
+ inertia?: boolean | LiveThrowOptions;
45
+ onPress?: () => void;
46
+ onDrag?: (position: {
47
+ x: number;
48
+ y: number;
49
+ }) => void;
50
+ /** Called on release with the release velocity, in pixels per second */
51
+ onRelease?: (velocity: {
52
+ x: number;
53
+ y: number;
54
+ }) => void;
55
+ /** Called when a throw comes to rest */
56
+ onThrowComplete?: () => void;
57
+ }
58
+ export interface RotationBounds {
59
+ minRotation?: number;
60
+ maxRotation?: number;
61
+ }
62
+ export interface LiveDraggable {
63
+ /** The underlying interaction (undefined for `type: 'rotation'`, which tracks the pointer itself) */
64
+ readonly draggable: Draggable | undefined;
65
+ /** Where the element is now */
66
+ readonly position: {
67
+ x: number;
68
+ y: number;
69
+ };
70
+ /** Its rotation in degrees */
71
+ readonly rotation: number;
72
+ /** Stop listening and stop any throw in progress */
73
+ destroy(): void;
74
+ }
75
+ export declare function createLiveDraggable(live: LiveApi, stage: Stage, target: TargetInput, options?: LiveDraggableOptions): LiveDraggable;
@@ -0,0 +1,73 @@
1
+ import type { LiveTimeline, LiveTimelineOptions } from './live';
2
+ import type { Stage, TargetInput } from './stage';
3
+ import type { TweenVars } from './vars';
4
+ /**
5
+ * Flip for the live runtime: animate elements from where they were to where a
6
+ * layout change put them — GSAP's `Flip.getState` / `Flip.from`.
7
+ *
8
+ * const state = live.getFlipState('.item')
9
+ * grid.classList.toggle('compact') // any DOM or class change
10
+ * live.flipFrom(state, { duration: 0.6, ease: 'power2.inOut', stagger: 0.03 })
11
+ *
12
+ * Measurement is the only DOM work, and it happens once per call: where each
13
+ * element *appears* before the change (including any transform it is animating
14
+ * with, so interrupting a flip mid-way continues smoothly), and where it is
15
+ * *laid out* after (ignoring transforms). Each element then gets an ordinary
16
+ * `fromTo` tween from the offset back to rest, so the compiled result is plain
17
+ * track data like everything else.
18
+ *
19
+ * Offsets are measured between centres, because scale happens about an
20
+ * element's centre (the CSS default origin); measuring corners would leave a
21
+ * resized element off by half its change in size.
22
+ *
23
+ * Shared elements: elements with the same `data-flip-id` are treated as one
24
+ * thing. When an element appears that was not recorded, but something with its
25
+ * flip id was, it flips from where that other element was — a gallery thumbnail
26
+ * growing into the detail view's hero, which is a different element.
27
+ */
28
+ interface Box {
29
+ cx: number;
30
+ cy: number;
31
+ width: number;
32
+ height: number;
33
+ }
34
+ /** What `getFlipState` recorded: each element and where it appeared. */
35
+ export interface FlipState {
36
+ readonly elements: Element[];
37
+ readonly boxes: Map<Element, Box | null>;
38
+ /** Where each `data-flip-id` appeared, and which element showed it */
39
+ readonly ids: Map<string, {
40
+ element: Element;
41
+ box: Box;
42
+ }>;
43
+ }
44
+ export interface FlipVars {
45
+ duration?: number;
46
+ ease?: string;
47
+ /** Seconds between each element's start, in document order */
48
+ stagger?: number;
49
+ /** Animate size changes with scaleX/scaleY (default true). Off: position only. */
50
+ scale?: boolean;
51
+ /**
52
+ * Elements that may have appeared during the change and should animate in —
53
+ * a selector, element or list. Anything in it that was not visible before
54
+ * but is now gets the `enter` animation.
55
+ */
56
+ targets?: TargetInput;
57
+ /**
58
+ * Cross-fade shared elements: one that takes over another's flip id fades in
59
+ * while the element it replaces (if still shown) fades out. Default false.
60
+ */
61
+ fade?: boolean;
62
+ /**
63
+ * How newly visible elements come in: the values they start from (they end at
64
+ * their natural values), or `false` for no entrance. Default: fade and grow in.
65
+ */
66
+ enter?: TweenVars | false;
67
+ onComplete?: () => void;
68
+ }
69
+ export declare function getFlipState(stage: Stage, targets: TargetInput): FlipState;
70
+ export declare function flipFrom(stage: Stage, createTimeline: (options: LiveTimelineOptions) => LiveTimeline, state: FlipState, vars?: FlipVars): LiveTimeline;
71
+ /** The natural value each entrance property animates to. */
72
+ export declare function restValues(from: TweenVars): TweenVars;
73
+ export {};
@@ -0,0 +1,18 @@
1
+ /**
2
+ * The path data an element currently draws: its own geometry if it is a basic
3
+ * SVG shape, otherwise the first `<path>` inside it (which is what the DOM
4
+ * adapter animates for wrapper elements). Null when there is none.
5
+ */
6
+ export declare function pathDataOf(element: Element | null | undefined): string | null;
7
+ /** Resolve a `morphSVG` value (path data, selector, element, or `{ shape }`) to path data. */
8
+ export declare function resolveMorphShape(value: unknown, query: (selector: string) => Element | null, warn: (message: string) => void): string;
9
+ /**
10
+ * Replace basic SVG shapes (circle, ellipse, rect, line, polyline, polygon) with
11
+ * equivalent `<path>` elements, keeping every other attribute (class, fill,
12
+ * style…). A `<circle>` has no `d` to animate; after this it does. Paths and
13
+ * non-shapes are left alone. Returns the resulting elements, in order.
14
+ *
15
+ * This changes the document, so it is an explicit call — like GSAP's
16
+ * `MorphSVGPlugin.convertToPath`.
17
+ */
18
+ export declare function convertToPath(targets: string | Element | ArrayLike<Element>, root?: ParentNode): Element[];
@@ -0,0 +1,33 @@
1
+ import { type PathPoint } from '../../engine';
2
+ import type { MotionPathVars } from './motion-path-vars';
3
+ /**
4
+ * `motionPath` as the live runtime accepts it: everything the compiler accepts,
5
+ * plus a selector or element for the path, and GSAP's `align`.
6
+ *
7
+ * live.to('.plane', { motionPath: { path: '#route', align: '#route', autoRotate: true }, duration: 3 })
8
+ *
9
+ * This is the one place a motion path reads the DOM, and it does so once, when
10
+ * the tween is built: the path element's geometry becomes path data, and
11
+ * `align` becomes a matrix. What reaches the compiler is plain data.
12
+ */
13
+ export interface LiveMotionPathVars extends Omit<MotionPathVars, 'path'> {
14
+ /** Path data, points, or a selector / element for a path, circle, ellipse, rect, line, polyline or polygon */
15
+ path: string | Element | PathPoint[];
16
+ /**
17
+ * Lay the path over an element on the page, so the follower moves along it
18
+ * where it is drawn. `true` aligns to the path element itself. Without it,
19
+ * path coordinates are x/y offsets from where the follower already sits.
20
+ */
21
+ align?: boolean | string | Element;
22
+ /** The point of the follower that sits on the path, as fractions of its size (default [0.5, 0.5]) */
23
+ alignOrigin?: [number, number];
24
+ }
25
+ export interface LiveMotionPathContext {
26
+ /** Resolve a selector the way the stage does (scoped to its root) */
27
+ query(selector: string): Element | null;
28
+ /** The elements the tween animates; the first one's layout is measured for `align` */
29
+ targets: Element[];
30
+ warn(message: string): void;
31
+ }
32
+ /** Resolve a live `motionPath` value to the plain data the compiler accepts. */
33
+ export declare function resolveLiveMotionPath(value: unknown, context: LiveMotionPathContext): MotionPathVars;
@@ -0,0 +1,52 @@
1
+ import type { LiveApi, LiveTimeline } from './live';
2
+ import type { Stage } from './stage';
3
+ import { type ScrollTriggerVars } from './live-scroll';
4
+ import type { ScrollDriver } from '../../drivers';
5
+ /**
6
+ * Scrolling as an animation (GSAP's ScrollToPlugin), and grouped scroll reveals
7
+ * (GSAP's `ScrollTrigger.batch`).
8
+ *
9
+ * live.scrollTo('#pricing', { duration: 1, offset: 80 })
10
+ * live.to(window, { scrollTo: { y: '#pricing', offsetY: 80 }, duration: 1 })
11
+ *
12
+ * live.scrollBatch('.card', { onEnter: (cards) => live.from(cards, { y: 40, opacity: 0, stagger: 0.1 }) })
13
+ *
14
+ * `scrollTo` tweens a plain `{ x, y }` and writes it to the scroller each frame,
15
+ * so it is an ordinary live timeline: eased, killable, with callbacks. The
16
+ * destination is measured once, when it starts. Wheel, touch or key input stops
17
+ * it (`autoKill`), so it never fights the reader.
18
+ */
19
+ export type ScrollDestination = number | string | Element | {
20
+ x?: number | string | Element;
21
+ y?: number | string | Element;
22
+ };
23
+ export interface ScrollToVars {
24
+ /** Seconds (default 1) */
25
+ duration?: number;
26
+ /** Default 'power2.inOut' */
27
+ ease?: string;
28
+ /** Pixels to stop short of an element or selector, e.g. a fixed header's height */
29
+ offset?: number;
30
+ offsetX?: number;
31
+ offsetY?: number;
32
+ /** Scroll an element instead of the window */
33
+ scroller?: string | HTMLElement;
34
+ /** Stop when the reader scrolls (default true) */
35
+ autoKill?: boolean;
36
+ onStart?: () => void;
37
+ onUpdate?: () => void;
38
+ onComplete?: () => void;
39
+ }
40
+ export declare function scrollTo(live: LiveApi, stage: Stage, destination: ScrollDestination, vars?: ScrollToVars): LiveTimeline;
41
+ export interface ScrollBatchVars extends Omit<ScrollTriggerVars, 'trigger' | 'onEnter' | 'onLeave' | 'onEnterBack' | 'onLeaveBack' | 'onUpdate'> {
42
+ /** Seconds to collect elements that cross together (default 0.1) */
43
+ interval?: number;
44
+ /** Call as soon as this many have collected */
45
+ batchMax?: number;
46
+ onEnter?: (elements: Element[]) => void;
47
+ onLeave?: (elements: Element[]) => void;
48
+ onEnterBack?: (elements: Element[]) => void;
49
+ onLeaveBack?: (elements: Element[]) => void;
50
+ }
51
+ /** One trigger per element; elements crossing the same edge close together arrive in one call. */
52
+ export declare function scrollBatch(stage: Stage, targets: string | Element | ArrayLike<Element>, vars: ScrollBatchVars): ScrollDriver[];
@@ -0,0 +1,108 @@
1
+ import { ScrollDriver, type MarkerOptions, type TriggerPosition } from '../../drivers';
2
+ import { type Timeline } from '../../engine';
3
+ import type { Stage } from './stage';
4
+ /**
5
+ * `scrollTrigger` for the live runtime — GSAP's ScrollTrigger vars, built on
6
+ * `ScrollDriver`:
7
+ *
8
+ * live.timeline({ scrollTrigger: { trigger: '.panels', start: 'top top', end: '+=2000', scrub: 0.5, pin: true } })
9
+ * .to('.track', { x: -1600, ease: 'none' })
10
+ *
11
+ * live.from('.card', { y: 60, opacity: 0, scrollTrigger: { start: 'top 80%', toggleActions: 'play none none reverse' } })
12
+ *
13
+ * With `scrub`, scroll position is the playhead. Without it, crossing the range's
14
+ * edges plays, reverses, resets… the animation according to `toggleActions`.
15
+ */
16
+ export interface ScrollTriggerSelf {
17
+ /** 0..1 through the range */
18
+ progress: number;
19
+ /** Scroll speed in px/s, positive scrolling down; 0 shortly after scrolling stops */
20
+ velocity: number;
21
+ /** 1 scrolling down, -1 up */
22
+ direction: 1 | -1;
23
+ }
24
+ export interface ScrollTriggerVars {
25
+ /** Element (or selector) defining the range. Default: the animation's first target. */
26
+ trigger?: string | Element;
27
+ /** `"<element edge> <viewport edge>"`, default `'top bottom'`; a function is re-run on refresh */
28
+ start?: TriggerPosition | (() => TriggerPosition);
29
+ /** Default `'bottom top'`; `'+=600'` / `'+=150%'` measure from the start; a function is re-run on refresh */
30
+ end?: TriggerPosition | (() => TriggerPosition);
31
+ /**
32
+ * On every refresh (a resize), rebuild the animation so function values and
33
+ * start values are read again for the new layout.
34
+ */
35
+ invalidateOnRefresh?: boolean;
36
+ /** `true` ties progress to scroll exactly; a number smooths over that many seconds */
37
+ scrub?: boolean | number;
38
+ /** Hold the trigger (`true`) or another element in place through the range */
39
+ pin?: boolean | string | Element;
40
+ /** Scroll container (element or selector); default the window */
41
+ scroller?: string | HTMLElement;
42
+ /** The scroller scrolls sideways: `'left right'` positions, horizontal pins */
43
+ horizontal?: boolean;
44
+ /** `false`: content after the pin scrolls up underneath it instead of being pushed down */
45
+ pinSpacing?: boolean;
46
+ /**
47
+ * Without `scrub`: what to do on enter, leave, enter back, leave back — each one
48
+ * of play, pause, resume, reverse, restart, reset, complete, none.
49
+ * Default `'play none none none'`.
50
+ */
51
+ toggleActions?: string;
52
+ /** Stop watching after the first enter (the animation keeps playing) */
53
+ once?: boolean;
54
+ /**
55
+ * After scrolling stops inside the range, scroll on to the nearest point: a
56
+ * progress step (`1 / 3`), progress points, `'labels'` (the timeline's labels),
57
+ * a function, or `{ snapTo, duration, delay, ease }` with an ease name.
58
+ */
59
+ snap?: LiveSnap;
60
+ /** Show start and end markers while developing (`true`, or colours, indent, id) */
61
+ markers?: boolean | MarkerOptions;
62
+ /**
63
+ * The animation moving this trigger's container sideways (a pinned horizontal
64
+ * section's tween). Start and end are then horizontal: `'left right'` is when the
65
+ * trigger's left edge reaches the viewport's right edge.
66
+ */
67
+ containerAnimation?: ContainerAnimation;
68
+ onUpdate?: (self: ScrollTriggerSelf) => void;
69
+ onEnter?: () => void;
70
+ onLeave?: () => void;
71
+ onEnterBack?: () => void;
72
+ onLeaveBack?: () => void;
73
+ }
74
+ type SnapPoints = number | number[] | 'labels' | ((progress: number) => number);
75
+ export type LiveSnap = SnapPoints | {
76
+ snapTo: SnapPoints;
77
+ duration?: number | {
78
+ min: number;
79
+ max: number;
80
+ };
81
+ delay?: number;
82
+ ease?: string;
83
+ };
84
+ /** What `containerAnimation` needs from a live timeline. */
85
+ export interface ContainerAnimation {
86
+ readonly timeline: Timeline;
87
+ readonly scrollTrigger: ScrollDriver | undefined;
88
+ progress(value?: number): number;
89
+ }
90
+ /** What a scroll trigger controls: the parts of a live timeline it needs. */
91
+ export interface ScrollControlled {
92
+ play(): unknown;
93
+ pause(): unknown;
94
+ resume(): unknown;
95
+ reverse(): unknown;
96
+ restart(): unknown;
97
+ progress(value?: number): number;
98
+ reversed(): boolean;
99
+ invalidate?(): unknown;
100
+ /** Label times as progress (0..1), for `snap: 'labels'` */
101
+ labelProgresses?(): number[];
102
+ }
103
+ /**
104
+ * Create and start a scroll trigger. `animation` is what it controls, if
105
+ * anything; `fallbackTrigger` is used when the vars name no trigger.
106
+ */
107
+ export declare function createScrollTrigger(stage: Stage, vars: ScrollTriggerVars, animation?: ScrollControlled, fallbackTrigger?: Element, warn?: (message: string) => void): ScrollDriver | undefined;
108
+ export {};
@@ -0,0 +1,40 @@
1
+ import type { LiveApi, LiveTimeline, LiveTimelineOptions } from './live';
2
+ import type { Stage, TargetInput } from './stage';
3
+ import type { TweenVars } from './vars';
4
+ /**
5
+ * Page transitions for client-side routing: animate the old view out, swap the DOM,
6
+ * carry shared elements across, and animate the new view in.
7
+ *
8
+ * await live.pageTransition({
9
+ * from: '.page',
10
+ * update: () => router.render(nextRoute), // may return a promise
11
+ * to: '.page',
12
+ * shared: '[data-flip-id]',
13
+ * })
14
+ *
15
+ * Shared elements are matched by `data-flip-id`, as in Flip: a thumbnail on the old
16
+ * page and the hero on the new one can be different elements. With `native: true`,
17
+ * browsers that have the View Transitions API do the whole transition themselves
18
+ * (shared elements get `view-transition-name`s from their flip ids); others fall
19
+ * back to the tinyfly version, so the call works everywhere.
20
+ */
21
+ export interface PageTransitionOptions {
22
+ /** Change the page: swap views, render a route. May return a promise. */
23
+ update: () => void | Promise<void>;
24
+ /** The view leaving (animated out before `update`) */
25
+ from?: TargetInput;
26
+ /** The view arriving, resolved after `update` */
27
+ to?: TargetInput | (() => TargetInput);
28
+ /** Selector for elements carried across by `data-flip-id` */
29
+ shared?: string;
30
+ /** How the old view leaves: the values it animates to, or `false` (default: fade and lift) */
31
+ leave?: TweenVars | false;
32
+ /** How the new view arrives: the values it starts from, or `false` (default: fade and drop in) */
33
+ enter?: TweenVars | false;
34
+ /** Seconds for each phase (default 0.35) */
35
+ duration?: number;
36
+ ease?: string;
37
+ /** Use the browser's View Transitions API when it has one (default false) */
38
+ native?: boolean;
39
+ }
40
+ export declare function pageTransition(api: LiveApi, stage: Stage, createTimeline: (options: LiveTimelineOptions) => LiveTimeline, options: PageTransitionOptions): Promise<void>;