@occluze/umber 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +64 -2
  2. package/dist/chunks/capture.js +2 -0
  3. package/dist/chunks/covers.js +2 -0
  4. package/dist/chunks/flip.js +2 -0
  5. package/dist/chunks/fx.js +102 -0
  6. package/dist/chunks/gl.js +180 -0
  7. package/dist/chunks/glsl.js +239 -0
  8. package/dist/chunks/inspect.js +6 -0
  9. package/dist/chunks/instances.js +93 -0
  10. package/dist/chunks/layers.js +21 -0
  11. package/dist/chunks/licence.js +2 -0
  12. package/dist/chunks/morph.js +2 -0
  13. package/dist/chunks/restore.js +2 -0
  14. package/dist/chunks/shapes.js +2 -0
  15. package/dist/chunks/sim.js +22 -0
  16. package/dist/chunks/text.js +52 -0
  17. package/dist/chunks/video.js +2 -0
  18. package/dist/chunks/views.js +2 -0
  19. package/dist/chunks/warm.js +2 -0
  20. package/dist/modules/debug.js +36 -0
  21. package/dist/modules/debug.mjs +36 -0
  22. package/dist/modules/handoff.js +2 -0
  23. package/dist/modules/handoff.mjs +2 -0
  24. package/dist/modules/input.js +2 -0
  25. package/dist/modules/input.mjs +2 -0
  26. package/dist/modules/router-swap.js +13 -0
  27. package/dist/modules/router.js +2 -0
  28. package/dist/modules/router.mjs +2 -0
  29. package/dist/modules/scroll.js +2 -0
  30. package/dist/modules/scroll.mjs +2 -0
  31. package/dist/modules/scrub.js +8 -0
  32. package/dist/modules/scrub.mjs +8 -0
  33. package/dist/umber.css +2 -0
  34. package/dist/umber.js +2 -0
  35. package/dist/umber.mjs +2 -0
  36. package/docs/npm.md +69 -0
  37. package/package.json +118 -4
  38. package/types/debug.d.ts +27 -0
  39. package/types/esm.d.ts +33 -0
  40. package/types/handoff.d.ts +116 -0
  41. package/types/input.d.ts +235 -0
  42. package/types/router.d.ts +181 -0
  43. package/types/scroll.d.ts +132 -0
  44. package/types/scrub.d.ts +74 -0
  45. package/types/umber.d.ts +1532 -0
@@ -0,0 +1,235 @@
1
+ // -----------------------------------------
2
+ // UMBER MODULE: INPUT, TYPES (@occluze/umber/input)
3
+ // -----------------------------------------
4
+
5
+ // Inputs as Signals: the speed of any Signal, a drag, the pointer's trail, presses and
6
+ // steps; and live textures: a canvas, video or numbers, the pointer's touch trail,
7
+ // element rects, an image's colour. Load the module, then use them from gl:
8
+ //
9
+ // import { Input } from "@occluze/umber/input";
10
+ // gl.use(Input); // or createGL({ modules: [Input] })
11
+ // <script src=".../umber@x.y.z/modules/input.js"></script> (registers itself)
12
+ //
13
+ // const d = gl.drag(".gallery", { axis: "x", bounds: { x: [-2400, 0] } });
14
+ // gl.effect("bend", { uniforms: { uDrag: d, uDragSpeed: d.velocity }, ... });
15
+ // const v = gl.velocityOf(gl.progress(".story")); // progress per second, 0 at rest
16
+ // const t = gl.trail(16); // t.points[i].value: [x, y]
17
+ // gl.effect("ripple", { uniforms: { uPress: gl.press }, ... }); // [x, y, time]
18
+ // const off = gl.step(80, (at) => stamp(at)); // every 80 px the pointer travels
19
+ // const mask = gl.texture(canvas); mask.update(); // uploaded only when you say it changed
20
+ // gl.effect("smear", { uniforms: { uTouch: gl.touch() }, ... }); // sample with screenUv()
21
+ //
22
+ // Each one asks for frames only while it still moves: at rest the loop sleeps.
23
+
24
+ import type { GL, Signal, UmberModule } from "./umber.js";
25
+
26
+ /** What gl.velocityOf() follows: anything with a numeric value (a number or [x, y...]). */
27
+ export interface Readable {
28
+ readonly value: number | ArrayLike<number>;
29
+ }
30
+
31
+ export interface VelocityOptions {
32
+ /** How fast it follows the real speed: a 60 fps lerp amount. @default 0.25 */
33
+ smooth?: number;
34
+ /** Below this (units per second, per axis) a resting value counts as stopped. @default 0.001 */
35
+ rest?: number;
36
+ }
37
+
38
+ /** gl.velocityOf(signal): units per second, smoothed; exactly 0 once the signal rests. */
39
+ export interface VelocitySignal<T = number | number[]> {
40
+ readonly value: T;
41
+ readonly destroyed: boolean;
42
+ destroy(): void;
43
+ }
44
+
45
+ export type DragEvent = "press" | "release" | "tap" | "change";
46
+
47
+ export interface DragBounds {
48
+ /** [min, max] offset in px. */
49
+ x?: [number, number];
50
+ y?: [number, number];
51
+ }
52
+
53
+ export interface DragOptions {
54
+ /** Which way it moves. @default "both" */
55
+ axis?: "x" | "y" | "both";
56
+ /** Limits for the offset, per axis. Change d.bounds any time. Or a function of the element bound now, run again on each rebind and resize. */
57
+ bounds?: DragBounds | ((el: Element) => DragBounds | null);
58
+ /** How much glide speed is kept per 60 fps frame after release (0: stops dead). @default 0.92 */
59
+ inertia?: number;
60
+ /** How far it gives past a bound while pressed (0: hard stop, 1: no resistance). @default 0.35 */
61
+ rubber?: number;
62
+ }
63
+
64
+ /**
65
+ * gl.drag(el): a drag as a Signal. Writes nothing to the DOM. Give the element
66
+ * touch-action: pan-y (axis "x"), pan-x (axis "y") or none in its CSS.
67
+ */
68
+ export interface DragSignal {
69
+ /** [x, y] offset in px. A vec2 uniform as it is. */
70
+ readonly value: [number, number];
71
+ /** [vx, vy] px per second, smoothed; exactly 0 at rest. A vec2 uniform as it is. */
72
+ readonly velocity: { readonly value: [number, number] };
73
+ /** A pointer is down on it. */
74
+ readonly pressed: boolean;
75
+ /** -1, 0 or 1 per axis: which way it last moved. */
76
+ readonly direction: [number, number];
77
+ bounds: DragBounds | null;
78
+ /** The element it is bound to now (a selector's: the match on a router's next page too; null while none ever matched). */
79
+ readonly el: Element | null;
80
+ /** The element the last press went down on (inside el): what a "tap" handler acts on. A tap's click reaches it too. */
81
+ readonly target: Element | null;
82
+ readonly destroyed: boolean;
83
+ /** Jump to an offset (stops a glide). */
84
+ set(x: number, y?: number): void;
85
+ on(event: DragEvent, fn: (d: DragSignal) => void): () => void;
86
+ off(event: DragEvent, fn: (d: DragSignal) => void): void;
87
+ /**
88
+ * Automatic when its gl.scope() reverts or the engine goes; for gl.drag(element), also when
89
+ * el leaves the page. A selector's waits for its next match instead, and a newer gl.drag()
90
+ * of the same selector replaces it.
91
+ */
92
+ destroy(): void;
93
+ revert(): void;
94
+ }
95
+
96
+ export interface TrailOptions {
97
+ /** How fast each point catches the one before it: a 60 fps lerp amount. @default 0.5 */
98
+ follow?: number;
99
+ }
100
+
101
+ /** gl.trail(count): points[0] is the pointer, each next one follows the one before. */
102
+ export interface Trail {
103
+ /** Each a vec2 Signal: uniforms: { uTail: trail.points[15] }. */
104
+ readonly points: ReadonlyArray<Readonly<Signal<[number, number]>>>;
105
+ readonly destroyed: boolean;
106
+ destroy(): void;
107
+ }
108
+
109
+ /** gl.press: the last press anywhere on the page. A vec3 uniform as it is. */
110
+ export interface PressSignal {
111
+ /** [x, y, time]: viewport px, and seconds in uTime's clock (-10000 before the first press). */
112
+ readonly value: [number, number, number];
113
+ /** The last 4 presses, newest first, each [x, y, time] (vec3 Signals). */
114
+ readonly recent: ReadonlyArray<Readonly<Signal<[number, number, number]>>>;
115
+ /** Presses so far. */
116
+ readonly count: number;
117
+ on(event: "press", fn: (p: PressSignal) => void): () => void;
118
+ off(event: "press", fn: (p: PressSignal) => void): void;
119
+ }
120
+
121
+ /** Numbers as a texture: data.length = width * height * channels (1, 2 or 4: R, RG, RGBA). */
122
+ export interface TextureData {
123
+ data: Uint8Array | Uint8ClampedArray | Float32Array;
124
+ width: number;
125
+ height: number;
126
+ }
127
+
128
+ export type TextureInput = TexImageSource | TextureData;
129
+
130
+ export interface TextureOptions {
131
+ /** "nearest" for crisp texels. Float data is always nearest. @default "linear" */
132
+ filter?: "linear" | "nearest";
133
+ /** "repeat" tiles it outside 0..1. @default "clamp" */
134
+ wrap?: "clamp" | "repeat";
135
+ }
136
+
137
+ /** A picture or numbers the page changes, as a sampler2D uniform (highp). */
138
+ export interface LiveTexture {
139
+ /** The GL texture, read by the engine to bind it (what changed is uploaded first); null before GL runs. */
140
+ readonly texture: WebGLTexture | null;
141
+ /** The source's size, px (texels). 0 until first uploaded. */
142
+ readonly width: number;
143
+ readonly height: number;
144
+ readonly source: TextureInput;
145
+ readonly destroyed: boolean;
146
+ /** It changed (or use `source` from now on): uploaded before the next draw that samples it. */
147
+ update(source?: TextureInput): void;
148
+ destroy(): void;
149
+ }
150
+
151
+ export interface TouchOptions {
152
+ /** Texture width, px (its height follows the screen's shape). @default 64 */
153
+ size?: number;
154
+ /** Dot radius, a share of the width. @default 0.08 */
155
+ radius?: number;
156
+ /** How much ink stays per 60 fps frame. @default 0.92 */
157
+ fade?: number;
158
+ }
159
+
160
+ /** gl.touch(): a = ink (0..1), rg = the way the pointer moved (rg * 2.0 - 1.0). Sample it with screenUv(). */
161
+ export interface TouchTexture extends LiveTexture {
162
+ readonly canvas: HTMLCanvasElement | OffscreenCanvas;
163
+ }
164
+
165
+ /** gl.rects(): N x 1 RGBA32F texels, each x, y, width, height in viewport px (like uRect). */
166
+ export interface RectsTexture extends LiveTexture {
167
+ readonly count: number;
168
+ /** The same numbers, 4 per element. */
169
+ readonly rects: Float32Array;
170
+ }
171
+
172
+ /** gl.imageColor(el): a vec4 Signal of the image's average colour, sRGB 0..1 ([0, 0, 0, 0] until known). */
173
+ export interface ImageColor {
174
+ readonly value: [number, number, number, number];
175
+ /** The most common colour (its pixels' average). */
176
+ readonly dominant: [number, number, number, number];
177
+ /** true once known; false when the image can't be read (no CORS, no image). */
178
+ readonly ready: Promise<boolean>;
179
+ }
180
+
181
+ /** What gl.use(Input) adds to gl. */
182
+ export interface InputMethods {
183
+ /**
184
+ * A <canvas>, ImageBitmap, <video>, <img>, ImageData or { data, width, height } as a
185
+ * sampler2D uniform, uploaded only after update() (a <video>: each new frame it shows).
186
+ * @example const mask = gl.texture(canvas); gl.effect("reveal", { uniforms: { uMask: mask }, ... }); mask.update();
187
+ */
188
+ texture(source: TextureInput, options?: TextureOptions): LiveTexture;
189
+ /**
190
+ * The pointer's fading trail, screen-sized: sample it with screenUv(). Sleeps when faded.
191
+ * @example gl.effect("smear", { uniforms: { uTouch: gl.touch() }, ... })
192
+ */
193
+ touch(options?: TouchOptions): TouchTexture;
194
+ /**
195
+ * The rects of these elements as an N x 1 texture (texelFetch(uCards, ivec2(i, 0), 0)).
196
+ * @example const cards = gl.rects(".card");
197
+ */
198
+ rects(target: string | ArrayLike<Element>): RectsTexture;
199
+ /**
200
+ * The average and dominant colour of el's image (data-gl-src or its <img>), once.
201
+ * @example plane.set("uBg", gl.imageColor(el))
202
+ */
203
+ imageColor(el: string | Element): ImageColor;
204
+ /**
205
+ * The speed of any Signal (gl.progress, gl.drag, a { get value() } over a slider's
206
+ * progress), sampled on every frame Umber runs. A value your code moves between frames
207
+ * wakes the loop with gl.wake().
208
+ * @example const v = gl.velocityOf(gl.progress(".story"), { smooth: 0.2 });
209
+ */
210
+ velocityOf<T extends number | ArrayLike<number>>(signal: { readonly value: T }, options?: VelocityOptions): VelocitySignal<T extends number ? number : number[]>;
211
+ /** @example const d = gl.drag(".slider", { axis: "x", bounds: { x: [-1200, 0] } }); */
212
+ drag(el: string | Element, options?: DragOptions): DragSignal;
213
+ /** @example const t = gl.trail(8, { follow: 0.35 }); */
214
+ trail(count?: number, options?: TrailOptions): Trail;
215
+ /** Made (one passive pointerdown listener) the first time it is read. */
216
+ readonly press: PressSignal;
217
+ /**
218
+ * fn(at, n) each time the pointer travelled another `every` px. Returns off().
219
+ * @example const off = gl.step(80, ([x, y]) => stamp(x, y));
220
+ */
221
+ step(every: number, fn: (at: [number, number], n: number) => void): () => void;
222
+ }
223
+
224
+ // gl.velocityOf, gl.drag, gl.trail, gl.press, gl.step, gl.texture, gl.touch, gl.rects and gl.imageColor, once the module is in.
225
+ declare module "./umber.js" {
226
+ interface GL extends InputMethods {}
227
+ }
228
+
229
+ /** gl.use(Input), createGL({ modules: [Input] }). */
230
+ export declare const Input: UmberModule;
231
+
232
+ /** The same without gl.use(): adds the methods to `engine`. */
233
+ export declare function input(engine: GL): void;
234
+
235
+ export default Input;
@@ -0,0 +1,181 @@
1
+ // -----------------------------------------
2
+ // UMBER MODULE: ROUTER, TYPES (@occluze/umber/router)
3
+ // -----------------------------------------
4
+
5
+ // Page changes without full page loads, with transitions of your own or presets:
6
+ //
7
+ // import { Router } from "@occluze/umber/router";
8
+ // gl.use(Router, { transition: "fade" }); // or createGL({ modules: [Router] })
9
+ // <script src=".../umber@x.y.z/modules/router.js"></script> (registers itself)
10
+ //
11
+ // gl.router.transition({ name: "to-work", to: "work", leave, enter });
12
+ // gl.router.on("after", ({ next }) => gtag("event", "page_view", { page_location: next.url }));
13
+ // await gl.router.go("/work");
14
+
15
+ import type { GL, UmberModule } from "./umber.js";
16
+
17
+ /** A page name (data-gl-page), a path ("/work/*"), a RegExp on the path, a function of the page, or a list of them. */
18
+ export type RouterMatch =
19
+ | string
20
+ | RegExp
21
+ | ((page: RouterPage) => boolean)
22
+ | Array<string | RegExp | ((page: RouterPage) => boolean)>;
23
+
24
+ /** One side of a page change. */
25
+ export interface RouterPage {
26
+ /** Its URL (with the #hash for the next page). */
27
+ url: string;
28
+ /** Its container's data-gl-page ("" when it has none). */
29
+ page: string;
30
+ /** Its [data-gl-router="container"] (null for the next page in "before"). */
31
+ container: HTMLElement | null;
32
+ /** The next page's parsed HTML. */
33
+ document?: Document;
34
+ }
35
+
36
+ /** What transitions and hooks get. */
37
+ export interface RouterData {
38
+ current: RouterPage;
39
+ next: RouterPage;
40
+ /** The link clicked, "popstate" (back / forward), "load" (once) or go()'s trigger ("go"). */
41
+ trigger: Element | string;
42
+ direction: "forward" | "back";
43
+ /** Where the click was, viewport px; null from the keyboard, back / forward or go(). */
44
+ origin: [number, number] | null;
45
+ /** The visitor prefers reduced motion: the presets swap at once. */
46
+ reducedMotion: boolean;
47
+ /** The visitor's last input was a key (keyboard, or a screen reader activating the link): the new page gets keyboard
48
+ * focus only then. A mouse, touch or pen click, or go() on its own, leaves focus where it was. */
49
+ keyboard: boolean;
50
+ /** The chosen transition's name ("" when it has none). */
51
+ transition: string;
52
+ }
53
+
54
+ type Step = (data: RouterData) => unknown;
55
+
56
+ /** Options of the presets (and of the element that names one: data-gl-transition-duration="0.6"). */
57
+ export interface RouterPresetOptions {
58
+ /** Seconds, each half. @default 0.45 (slide 0.8, cover 0.7) */
59
+ duration?: number;
60
+ /** A CSS easing (cover: any Umber ease). @default "cubic-bezier(0.625, 0.05, 0, 1)" */
61
+ ease?: string;
62
+ /** curtain, wipe, cover: the panel's colour. @default "#111" */
63
+ color?: string;
64
+ /** cover: a gl.shader() name with a uCover uniform. @default a disc of `color` that grows from the click */
65
+ shader?: string;
66
+ }
67
+
68
+ export type RouterPreset = "none" | "fade" | "slide" | "zoom" | "curtain" | "wipe" | "cover" | "dissolve";
69
+
70
+ /**
71
+ * A transition. Each condition it sets must hold; the most specific one wins (from 1, to 2,
72
+ * links 4, custom 8; a tie: the one registered last). One with no condition is the default.
73
+ * Every step may return a promise (or be async); a step that throws or takes longer than
74
+ * options.timeout loads the page in full instead.
75
+ */
76
+ export interface RouterTransition extends RouterPresetOptions {
77
+ name?: string;
78
+ /** Start from a preset: its steps, your options. Your own steps replace its. */
79
+ preset?: RouterPreset;
80
+ from?: RouterMatch;
81
+ to?: RouterMatch;
82
+ /** The link clicked matches this selector (or function). */
83
+ links?: string | ((link: Element) => boolean);
84
+ custom?: (data: RouterData) => boolean;
85
+ /** Leave and enter at once, both containers in the page; the old one is pinned where it shows (position: fixed). */
86
+ sync?: boolean;
87
+ /** The first page load (from never matches): an intro. Plays wait for it. */
88
+ once?: Step;
89
+ beforeLeave?: Step;
90
+ leave?: Step;
91
+ afterLeave?: Step;
92
+ /** The new container is in the page, its scripts have not run: set its first frame here. */
93
+ beforeEnter?: Step;
94
+ enter?: Step;
95
+ afterEnter?: Step;
96
+ }
97
+
98
+ export interface RouterOptions {
99
+ /** The transition when nothing else picks one: a preset or a registered name. @default "fade" */
100
+ transition?: RouterPreset | (string & {});
101
+ /** "hover": fetch a page as the pointer rests on its link, a touch starts or it gets focus; "viewport": also once a link scrolls into view; false: only on click. @default "hover" */
102
+ prefetch?: "hover" | "viewport" | false;
103
+ /** Pages kept in memory. 0: none. @default 10 */
104
+ cache?: number;
105
+ /** ms a fetch or any step may take before the page loads in full instead. @default 6000 */
106
+ timeout?: number;
107
+ /** Where focus goes in the new container (a selector; else the container). false: nowhere. @default "h1" */
108
+ focus?: string | false;
109
+ /** Say the new page's title in a polite live region. @default true */
110
+ announce?: boolean;
111
+ /** Scroll to the top, the #hash, or where that history entry was. @default true */
112
+ scroll?: boolean;
113
+ /** Run the new page's scripts. @default true */
114
+ scripts?: boolean;
115
+ /** Update title, meta, stylesheets, <html> and <body> classes. @default true */
116
+ head?: boolean;
117
+ /** Re-initialise Webflow (interactions, forms) after each swap. @default true */
118
+ webflow?: boolean;
119
+ /** Return true to leave a link to the browser. */
120
+ prevent?: ((link: Element, event?: Event) => boolean) | null;
121
+ }
122
+
123
+ /** gl.router, once the module is in. */
124
+ export interface RouterApi {
125
+ /** The module's options, live: with the script build, set them right after createGL(). */
126
+ readonly options: Required<RouterOptions>;
127
+ /** True while a page change runs. */
128
+ readonly busy: boolean;
129
+ /** The page shown: its URL without the #hash. */
130
+ readonly url: string;
131
+ /** The page shown: its data-gl-page. */
132
+ readonly page: string;
133
+ /**
134
+ * Change page. Resolves once the new page is in and its transition finished; rejects
135
+ * (after starting a full page load of url) when the router can't.
136
+ */
137
+ go(url: string, options?: { transition?: string | RouterTransition; trigger?: Element | string }): Promise<void>;
138
+ /** Fetch a page ahead (kept in the cache). Never rejects. */
139
+ prefetch(url: string): Promise<void>;
140
+ /** Register a transition; returns its remover. */
141
+ transition(def: RouterTransition): () => void;
142
+ /**
143
+ * A hook for every page change; returns its remover. Each step's hooks run with that step
144
+ * of the transition: before, beforeLeave, leave, afterLeave, beforeEnter, enter,
145
+ * afterEnter, after. All but after may return what the change waits for (a promise, a
146
+ * GSAP tween or timeline, a Web Animation, a list of them).
147
+ */
148
+ on(name: RouterMoment, fn: Step): () => void;
149
+ on(name: "error", fn: (e: { error: unknown; url: string }) => void): () => void;
150
+ /**
151
+ * One page's own code (its data-gl-page): beforeEnter / afterEnter as it comes in (the
152
+ * first load too), beforeLeave / afterLeave as it goes. Returns its remover.
153
+ */
154
+ view(page: string, view: RouterView): () => void;
155
+ }
156
+
157
+ /** The moments of a change: before, each step, after. */
158
+ export type RouterMoment = "before" | "beforeLeave" | "leave" | "afterLeave" | "beforeEnter" | "enter" | "afterEnter" | "after";
159
+
160
+ /** A page's set-up and take-down (gl.router.view()). */
161
+ export interface RouterView {
162
+ beforeEnter?: Step;
163
+ afterEnter?: Step;
164
+ beforeLeave?: Step;
165
+ afterLeave?: Step;
166
+ }
167
+
168
+ declare module "./umber.js" {
169
+ interface GL {
170
+ /** The router module's API (types/router.d.ts). */
171
+ readonly router: RouterApi;
172
+ }
173
+ }
174
+
175
+ /** gl.use(Router, options), createGL({ modules: [Router] }). */
176
+ export declare const Router: UmberModule;
177
+
178
+ /** The same without gl.use(): adds gl.router to `engine`. */
179
+ export declare function router(engine: GL, options?: RouterOptions): RouterApi;
180
+
181
+ export default Router;
@@ -0,0 +1,132 @@
1
+ // -----------------------------------------
2
+ // UMBER MODULE: SCROLL, TYPES (@occluze/umber/scroll)
3
+ // -----------------------------------------
4
+
5
+ // Smooth scrolling on Umber's own loop: the wheel eases the real scroll position, written
6
+ // before the engine reads it each frame, so planes and the DOM move together (0 px apart)
7
+ // with no createGL({ scroll }). Keys, the scrollbar, find-in-page, zoom, sideways swipes,
8
+ // touch (unless `touch: true`) and reduced motion stay native.
9
+ //
10
+ // import { Scroll } from "@occluze/umber/scroll";
11
+ // gl.use(Scroll, { lerp: 0.1 }); // or createGL({ modules: [Scroll] })
12
+ // <script src=".../umber@x.y.z/modules/scroll.js"></script> (registers itself)
13
+ //
14
+ // gl.scroll.scrollTo("#work", { offset: -80 });
15
+ // gl.scroll.on("scroll", (s) => console.log(s.animatedScroll, s.velocity));
16
+ // gl.scroll.stop(); gl.scroll.start(); // a modal, a page change
17
+ //
18
+ // HTML: data-gl-scroll="off" | "touch", data-gl-scroll-lerp, data-gl-scroll-duration and
19
+ // data-gl-scroll-offset on <body> (or <html>); data-gl-scroll-offset on a #link or its
20
+ // target; data-gl-scroll-prevent on an element that scrolls natively; data-gl-scroll-wrapper
21
+ // on the element that scrolls instead of the window.
22
+
23
+ import type { GL, UmberModule } from "./umber.js";
24
+
25
+ /** Where scrollTo() goes: px, a selector, an element, or "top" / "bottom" (also "#", "#top", "start", "end"). */
26
+ export type ScrollTarget = number | string | Element | null | undefined;
27
+
28
+ export interface ScrollToOptions {
29
+ /** px added to the target's position (-80: stop 80 px above it, for a fixed header). @default 0 */
30
+ offset?: number;
31
+ /** Land now, in this frame, with no animation. @default false */
32
+ immediate?: boolean;
33
+ /** Seconds, with `easing` (instead of the lerp). @default the module's duration (0: the lerp) */
34
+ duration?: number;
35
+ /** 0..1 -> 0..1, for `duration`. @default an expo ease-out */
36
+ easing?: (t: number) => number;
37
+ /** The lerp for this move. @default the module's lerp */
38
+ lerp?: number;
39
+ /** With immediate: a jump, not motion (no velocity, no direction): a page swap, a history step. Without it, an immediate move of a screen or more is a jump, a smaller one is motion. @default false */
40
+ jump?: boolean;
41
+ /** Ignore the wheel, touch, scroll keys and other scrollTo()s until it lands. @default false */
42
+ lock?: boolean;
43
+ /** Animate also while stopped or locked (an immediate one always lands). @default false */
44
+ force?: boolean;
45
+ /** When it lands (not when something interrupts it). */
46
+ onComplete?: (scroll: ScrollApi) => void;
47
+ }
48
+
49
+ export interface ScrollOptions {
50
+ /** The share of the way it moves per 60 fps frame, the same at any refresh rate (1: at once). @default 0.1 */
51
+ lerp?: number;
52
+ /** Seconds a wheel move takes, with `easing`; 0 uses the lerp. @default 0 */
53
+ duration?: number;
54
+ /** For `duration`. @default an expo ease-out */
55
+ easing?: (t: number) => number;
56
+ /** Wheel px times this. @default 1 */
57
+ wheelMultiplier?: number;
58
+ /** Smooth the wheel. false: the wheel scrolls natively (scrollTo() and anchors still animate). @default true */
59
+ wheel?: boolean;
60
+ /** Smooth touch too: follows the finger, eases its fling. Read once, at gl.use(). @default false (phones scroll natively) */
61
+ touch?: boolean;
62
+ /** Finger px times this. @default 1 */
63
+ touchMultiplier?: number;
64
+ /** What scrolls: the window (null) or an element (give it data-gl-scroll-wrapper so planes follow it). @default [data-gl-scroll-wrapper], else the window */
65
+ wrapper?: Element | string | Window | null;
66
+ /** What grows (watched for `limit`). @default the wrapper's first child, or <html> */
67
+ content?: Element | string | null;
68
+ /** In-page #id links scroll smoothly; an object: scrollTo() options for them (offset, duration...). @default true */
69
+ anchors?: boolean | ScrollToOptions;
70
+ /** Follow size changes (a ResizeObserver, resize). false: call resize() yourself. @default true */
71
+ autoResize?: boolean;
72
+ /** true for an element whose wheel / touch stays native (like data-gl-scroll-prevent). */
73
+ prevent?: ((el: Element) => boolean) | null;
74
+ /** An element under the pointer that scrolls by itself scrolls first, natively. @default true */
75
+ nested?: boolean;
76
+ }
77
+
78
+ /** gl.scroll: the shape scroll libraries share (scrollTo, animatedScroll, on("scroll")...). */
79
+ export interface ScrollApi {
80
+ /** Where the page is drawn now (px). */
81
+ readonly animatedScroll: number;
82
+ /** The same (the name some tools read). */
83
+ readonly scroll: number;
84
+ /** Where it is heading (px). */
85
+ readonly targetScroll: number;
86
+ /** The real scroll position (px). */
87
+ readonly actualScroll: number;
88
+ /** The largest scroll (px). */
89
+ readonly limit: number;
90
+ /** px per frame at 60 fps (+ down); 0 at rest. */
91
+ readonly velocity: number;
92
+ /** 1 down, -1 up (the last move's); 0 before any. */
93
+ readonly direction: 1 | -1 | 0;
94
+ /** animatedScroll / limit, 0..1. */
95
+ readonly progress: number;
96
+ /** "smooth" while it eases, "native" while the browser scrolls (keys, the scrollbar), else false. */
97
+ readonly isScrolling: false | "smooth" | "native";
98
+ readonly isStopped: boolean;
99
+ readonly isLocked: boolean;
100
+ /** The element that scrolls (<html> for the window). */
101
+ readonly rootElement: Element;
102
+ /** The options, live: lerp, wheelMultiplier, anchors, prevent... are read on each use. */
103
+ readonly options: Required<ScrollOptions>;
104
+ /** @example gl.scroll.scrollTo("#contact", { offset: -80, duration: 1.2 }) */
105
+ scrollTo(target: ScrollTarget, options?: ScrollToOptions): void;
106
+ /** Hold the page (a modal, a page change): no wheel, touch, keys or animated scrollTo() (unless force) until start(). */
107
+ stop(): void;
108
+ start(): void;
109
+ /** Measure again now and take the real position (after a page swap). */
110
+ resize(): void;
111
+ /** "scroll": every frame it moves, and on native scrolls, with gl.scroll. Returns its off(). */
112
+ on(event: "scroll", fn: (scroll: ScrollApi) => void): () => void;
113
+ off(event: "scroll", fn: (scroll: ScrollApi) => void): void;
114
+ /** Step it from your own loop (ms). Never needed: Umber's loop runs it, and leaves it to you while you call this. */
115
+ raf(time: number): void;
116
+ destroy(): void;
117
+ }
118
+
119
+ declare module "./umber.js" {
120
+ interface GL {
121
+ /** The scroll module's smooth scroller (types/scroll.d.ts). */
122
+ readonly scroll: ScrollApi;
123
+ }
124
+ }
125
+
126
+ /** gl.use(Scroll, options), createGL({ modules: [[Scroll, options]] }). */
127
+ export declare const Scroll: UmberModule;
128
+
129
+ /** The same without gl.use(): adds gl.scroll to `engine`. */
130
+ export declare function smoothScroll(engine: GL, options?: ScrollOptions): ScrollApi;
131
+
132
+ export default Scroll;
@@ -0,0 +1,74 @@
1
+ // -----------------------------------------
2
+ // UMBER MODULE: SCRUB, TYPES (@occluze/umber/scrub)
3
+ // -----------------------------------------
4
+
5
+ // Scroll-scrubbed video. Load the module, then mark a video:
6
+ //
7
+ // import { Scrub } from "@occluze/umber/scrub";
8
+ // const gl = createGL({ modules: [Scrub] });
9
+ // <video data-gl="video" data-gl-scrub src="/scrub.mp4" poster="/scrub.jpg" muted playsinline preload="none">
10
+ //
11
+ // const s = gl.plane(el)?.scrub;
12
+ // if (s) s.progress = 0.4;
13
+ //
14
+ // ATTRIBUTES (each also a CSS variable, --gl-scrub-start ...)
15
+ // data-gl-scrub "" (scroll drives it) | "manual"
16
+ // data-gl-scrub-start / -end "top bottom" / "bottom top" (element edge, viewport line; %, px)
17
+ // data-gl-scrub-track "parent" | "closest section" | a selector (default: the video)
18
+ // data-gl-scrub-smooth seconds to catch up (default 0.12; 0 with Lenis)
19
+ // data-gl-scrub-source auto | decoder | video | frames
20
+ // data-gl-scrub-src / -src-mobile the scrub MP4 (default: the video's src); -mobile on
21
+ // phones and weak GPUs (device tier not "high")
22
+ // data-gl-scrub-frames / -count image sequence "/seq/f_{0001}.webp" and its frame count
23
+ // data-gl-scrub-fps fps of a sequence or of the <video> tier (default: the MP4's when the decoder read it, else 30)
24
+ // data-gl-scrub-blend mix neighbouring frames (default true)
25
+ // data-gl-scrub-cache GPU frame cache, MB (default by GPU tier: 128 high, 48 mid
26
+ // (phones), 32 low (weak GPUs))
27
+ // data-gl-scrub-reduced "poster" (default) | "scrub", under prefers-reduced-motion
28
+ //
29
+ // Shader inputs on scrubbed planes: uScrubProgress (0..1), uScrubVelocity (progress / s).
30
+
31
+ import type { UmberModule } from "./umber.js";
32
+
33
+ export type ScrubTier = "decoder" | "video" | "frames" | "poster";
34
+ export type ScrubEvent = "ready" | "tier" | "error";
35
+
36
+ /** gl.plane(el)?.scrub */
37
+ export interface ScrubHandle {
38
+ /** 0..1. Setting it hands the scrub to your code (drive becomes "manual"). */
39
+ progress: number;
40
+ /** "scroll": the element's position drives it. "manual": progress is yours. */
41
+ drive: "scroll" | "manual";
42
+ /** Seconds into the clip (setting it sets progress). */
43
+ time: number;
44
+ /** The playhead in frames (fractional while two frames mix). */
45
+ readonly frame: number;
46
+ readonly frames: number;
47
+ readonly fps: number;
48
+ readonly duration: number;
49
+ readonly tier: ScrubTier | "loading";
50
+ /** true with the first frame; false when it fell back to the poster. */
51
+ readonly ready: Promise<boolean>;
52
+ on(event: ScrubEvent, fn: (scrub: ScrubHandle) => void): () => void;
53
+ off(event: ScrubEvent, fn: (scrub: ScrubHandle) => void): void;
54
+ /** Stop: the plane goes and the DOM video shows. */
55
+ destroy(): void;
56
+ }
57
+
58
+ export interface ScrubModuleOptions {
59
+ /** GPU frame cache per scrubbed video, MB. @default by GPU tier: 128 high, 48 mid (phones), 32 low (weak GPUs) */
60
+ cacheMB?: number;
61
+ /** Under prefers-reduced-motion. @default "poster" */
62
+ reducedMotion?: "poster" | "scrub";
63
+ }
64
+
65
+ // gl.plane(el)?.scrub on a plane the module drives.
66
+ declare module "./umber.js" {
67
+ interface Plane {
68
+ /** The scrub handle (with the scrub module, on a data-gl-scrub video). */
69
+ readonly scrub?: ScrubHandle;
70
+ }
71
+ }
72
+
73
+ export declare const Scrub: UmberModule;
74
+ export default Scrub;