@occluze/umber 0.2.0 → 0.3.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 (84) hide show
  1. package/LICENSE.md +21 -0
  2. package/README.md +78 -48
  3. package/dist/chunks/badge.js +2 -0
  4. package/dist/chunks/basis.js +2 -0
  5. package/dist/chunks/basis_transcoder.js +2 -0
  6. package/dist/chunks/basis_transcoder.wasm +0 -0
  7. package/dist/chunks/capture.js +2 -2
  8. package/dist/chunks/covers.js +2 -2
  9. package/dist/chunks/curves.js +2 -0
  10. package/dist/chunks/flip.js +2 -2
  11. package/dist/chunks/fx.js +2 -102
  12. package/dist/chunks/gl.js +2 -180
  13. package/dist/chunks/glsl.js +2 -239
  14. package/dist/chunks/inspect.js +2 -6
  15. package/dist/chunks/instances.js +2 -93
  16. package/dist/chunks/layers.js +2 -21
  17. package/dist/chunks/licence.js +2 -2
  18. package/dist/chunks/morph.js +2 -2
  19. package/dist/chunks/patch.js +2 -0
  20. package/dist/chunks/prepared.js +2 -0
  21. package/dist/chunks/profiler.js +2 -0
  22. package/dist/chunks/restore.js +2 -2
  23. package/dist/chunks/shapes.js +2 -2
  24. package/dist/chunks/sim.js +2 -22
  25. package/dist/chunks/text.js +2 -52
  26. package/dist/chunks/video.js +2 -2
  27. package/dist/chunks/views.js +2 -2
  28. package/dist/chunks/vocabulary.js +2 -0
  29. package/dist/chunks/warm.js +2 -2
  30. package/dist/frameworks/astro.mjs +2 -0
  31. package/dist/frameworks/react.mjs +2 -0
  32. package/dist/frameworks/svelte.mjs +2 -0
  33. package/dist/frameworks/vue.mjs +2 -0
  34. package/dist/modules/debug.js +2 -36
  35. package/dist/modules/debug.mjs +2 -36
  36. package/dist/modules/handoff.js +2 -2
  37. package/dist/modules/handoff.mjs +2 -2
  38. package/dist/modules/input.js +2 -2
  39. package/dist/modules/input.mjs +2 -2
  40. package/dist/modules/router-swap.js +2 -13
  41. package/dist/modules/router.js +2 -2
  42. package/dist/modules/router.mjs +2 -2
  43. package/dist/modules/scroll-more.js +2 -0
  44. package/dist/modules/scroll-touch.js +2 -0
  45. package/dist/modules/scroll.js +2 -2
  46. package/dist/modules/scroll.mjs +2 -2
  47. package/dist/modules/scrollfx.js +2 -0
  48. package/dist/modules/scrollfx.mjs +2 -0
  49. package/dist/modules/scrub.js +2 -8
  50. package/dist/modules/scrub.mjs +2 -8
  51. package/dist/modules/three.js +2 -0
  52. package/dist/modules/three.mjs +2 -0
  53. package/dist/node/assets.mjs +9 -0
  54. package/dist/node/astro.mjs +47 -0
  55. package/dist/node/cli.mjs +109 -0
  56. package/dist/node/shared-3Q24RNIF.mjs +602 -0
  57. package/dist/node/shared-4FIU6DYP.mjs +200 -0
  58. package/dist/node/vite.mjs +10 -0
  59. package/dist/umber.css +2 -2
  60. package/dist/umber.js +2 -2
  61. package/dist/umber.mjs +2 -2
  62. package/docs/AI-quick.md +240 -0
  63. package/docs/AI.md +3130 -0
  64. package/docs/npm.md +37 -26
  65. package/package.json +183 -12
  66. package/types/assets.d.ts +87 -0
  67. package/types/astro.d.ts +43 -0
  68. package/types/debug.d.ts +17 -16
  69. package/types/esm.d.ts +12 -12
  70. package/types/global.d.ts +17 -0
  71. package/types/handoff.d.ts +26 -25
  72. package/types/input.d.ts +63 -55
  73. package/types/loop.d.ts +75 -0
  74. package/types/module.d.ts +108 -0
  75. package/types/react.d.ts +15 -0
  76. package/types/router.d.ts +87 -45
  77. package/types/scroll.d.ts +96 -38
  78. package/types/scrollfx.d.ts +80 -0
  79. package/types/scrub.d.ts +33 -32
  80. package/types/svelte.d.ts +16 -0
  81. package/types/three.d.ts +226 -0
  82. package/types/umber.d.ts +633 -357
  83. package/types/vite.d.ts +33 -0
  84. package/types/vue.d.ts +14 -0
package/types/router.d.ts CHANGED
@@ -1,33 +1,30 @@
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. */
1
+ /**
2
+ * Types for the router module (@occluze/umber/router).
3
+ *
4
+ * Page changes without full page loads, with transitions of your own or presets:
5
+ *
6
+ * import { Router } from "@occluze/umber/router";
7
+ * umber.use(Router, { transition: "fade" }); // or createUmber({ modules: [Router] })
8
+ * <script src=".../umber@x.y.z/modules/router.js"></script> (registers itself)
9
+ *
10
+ * umber.router.transition({ name: "to-work", to: "work", leave, enter });
11
+ * umber.router.on("after", ({ next }) => gtag("event", "page_view", { page_location: next.url }));
12
+ * await umber.router.go("/work");
13
+ */
14
+
15
+ import type { Umber, UmberModule } from "./umber.js";
16
+
17
+ /** A page name (data-umber-page), a path ("/work/*"), a RegExp on the path, a function of the page, or a list of them. */
18
18
  export type RouterMatch =
19
- | string
20
- | RegExp
21
- | ((page: RouterPage) => boolean)
22
- | Array<string | RegExp | ((page: RouterPage) => boolean)>;
19
+ string | RegExp | ((page: RouterPage) => boolean) | (string | RegExp | ((page: RouterPage) => boolean))[];
23
20
 
24
21
  /** One side of a page change. */
25
22
  export interface RouterPage {
26
23
  /** Its URL (with the #hash for the next page). */
27
24
  url: string;
28
- /** Its container's data-gl-page ("" when it has none). */
25
+ /** Its container's data-umber-page ("" when it has none). */
29
26
  page: string;
30
- /** Its [data-gl-router="container"] (null for the next page in "before"). */
27
+ /** Its [data-umber~=container]. The next page's is null until that page is in: in "before", and in a leave that starts before it is (its steps get it filled in once it is). */
31
28
  container: HTMLElement | null;
32
29
  /** The next page's parsed HTML. */
33
30
  document?: Document;
@@ -42,7 +39,7 @@ export interface RouterData {
42
39
  direction: "forward" | "back";
43
40
  /** Where the click was, viewport px; null from the keyboard, back / forward or go(). */
44
41
  origin: [number, number] | null;
45
- /** The visitor prefers reduced motion: the presets swap at once. */
42
+ /** The visitor prefers reduced motion: every preset is a 0.2 s cross-fade. */
46
43
  reducedMotion: boolean;
47
44
  /** The visitor's last input was a key (keyboard, or a screen reader activating the link): the new page gets keyboard
48
45
  * focus only then. A mouse, touch or pen click, or go() on its own, leaves focus where it was. */
@@ -53,19 +50,22 @@ export interface RouterData {
53
50
 
54
51
  type Step = (data: RouterData) => unknown;
55
52
 
56
- /** Options of the presets (and of the element that names one: data-gl-transition-duration="0.6"). */
53
+ /** Options of the presets (and of the element that names one: data-umber-transition-duration="0.6"). */
57
54
  export interface RouterPresetOptions {
58
- /** Seconds, each half. @default 0.45 (slide 0.8, cover 0.7) */
55
+ /** Seconds, each half. @default fade 0.4, slide 0.9, zoom 0.5 / 0.7, curtain and wipe 0.65, cover and dissolve 0.8 */
59
56
  duration?: number;
60
- /** A CSS easing (cover: any Umber ease). @default "cubic-bezier(0.625, 0.05, 0, 1)" */
57
+ /** A CSS easing (cover, dissolve: any Umber ease). @default per preset */
61
58
  ease?: string;
62
- /** curtain, wipe, cover: the panel's colour. @default "#111" */
59
+ /** curtain, wipe, cover, dissolve: the panel's colour. @default "#111" */
63
60
  color?: string;
64
- /** cover: a gl.shader() name with a uCover uniform. @default a disc of `color` that grows from the click */
61
+ /** cover: a umber.shader() name with a uCover uniform. @default a disc of `color` that grows from the click */
65
62
  shader?: string;
63
+ /** cover, dissolve: draw over everything, a fixed nav too (Umber's canvas lifted for the transition). @default false */
64
+ above?: boolean | string;
66
65
  }
67
66
 
68
- export type RouterPreset = "none" | "fade" | "slide" | "zoom" | "curtain" | "wipe" | "cover" | "dissolve";
67
+ /** native: the browser's View Transition (document.startViewTransition), fade where there is none. */
68
+ export type RouterPreset = "none" | "fade" | "slide" | "zoom" | "curtain" | "wipe" | "cover" | "dissolve" | "native";
69
69
 
70
70
  /**
71
71
  * A transition. Each condition it sets must hold; the most specific one wins (from 1, to 2,
@@ -84,6 +84,12 @@ export interface RouterTransition extends RouterPresetOptions {
84
84
  custom?: (data: RouterData) => boolean;
85
85
  /** Leave and enter at once, both containers in the page; the old one is pinned where it shows (position: fixed). */
86
86
  sync?: boolean;
87
+ /**
88
+ * Leave only once the next page is in (data.next has its container and document), for a
89
+ * leave of your own that reads the next page. Without it the leave starts at the click,
90
+ * while the next page loads. @default false
91
+ */
92
+ wait?: boolean;
87
93
  /** The first page load (from never matches): an intro. Plays wait for it. */
88
94
  once?: Step;
89
95
  beforeLeave?: Step;
@@ -116,27 +122,57 @@ export interface RouterOptions {
116
122
  head?: boolean;
117
123
  /** Re-initialise Webflow (interactions, forms) after each swap. @default true */
118
124
  webflow?: boolean;
119
- /** Return true to leave a link to the browser. */
125
+ /** Return true to leave a link (or a data-umber-router-form form) to the browser. */
120
126
  prevent?: ((link: Element, event?: Event) => boolean) | null;
127
+ /** Every transition leaves only once the next page is in (as transition.wait). @default false */
128
+ wait?: boolean;
129
+ /** Headers sent with every page the router fetches (X-Requested-With, so a server can answer with less). @default {} */
130
+ headers?: Record<string, string>;
131
+ }
132
+
133
+ /** umber.router.go()'s options. */
134
+ export interface RouterGoOptions {
135
+ transition?: string | RouterTransition;
136
+ trigger?: Element | string;
137
+ /** "replace": the new page takes the place of the history entry shown (data-umber-router-history="replace" on a link). @default "push" */
138
+ history?: "push" | "replace";
139
+ }
140
+
141
+ /** umber.router.on()'s options. */
142
+ export interface RouterHookOptions {
143
+ /** Run once, then remove itself. */
144
+ once?: boolean;
145
+ /** Lower starts first among the hooks of one moment. @default 0 */
146
+ order?: number;
147
+ }
148
+
149
+ /** umber.router.cache: the pages kept in memory (after a sign-in, or an edit made in the page, so the next visit fetches them again). */
150
+ export interface RouterCache {
151
+ /** Forget every page (one still loading is forgotten once it is in). */
152
+ clear(): void;
153
+ /** Forget one page; true when it was kept. */
154
+ delete(url: string): boolean;
155
+ has(url: string): boolean;
121
156
  }
122
157
 
123
- /** gl.router, once the module is in. */
158
+ /** umber.router, once the module is in. */
124
159
  export interface RouterApi {
125
- /** The module's options, live: with the script build, set them right after createGL(). */
160
+ /** The module's options, live: with the script build, set them right after createUmber(). */
126
161
  readonly options: Required<RouterOptions>;
127
162
  /** True while a page change runs. */
128
163
  readonly busy: boolean;
129
164
  /** The page shown: its URL without the #hash. */
130
165
  readonly url: string;
131
- /** The page shown: its data-gl-page. */
166
+ /** The page shown: its data-umber-page. */
132
167
  readonly page: string;
133
168
  /**
134
169
  * Change page. Resolves once the new page is in and its transition finished; rejects
135
170
  * (after starting a full page load of url) when the router can't.
136
171
  */
137
- go(url: string, options?: { transition?: string | RouterTransition; trigger?: Element | string }): Promise<void>;
138
- /** Fetch a page ahead (kept in the cache). Never rejects. */
172
+ go(url: string, options?: RouterGoOptions): Promise<void>;
173
+ /** Fetch a page ahead (kept in the cache), its GL got ready too (umber.preload()). Never rejects. */
139
174
  prefetch(url: string): Promise<void>;
175
+ readonly cache: RouterCache;
140
176
  /** Register a transition; returns its remover. */
141
177
  transition(def: RouterTransition): () => void;
142
178
  /**
@@ -145,19 +181,24 @@ export interface RouterApi {
145
181
  * afterEnter, after. All but after may return what the change waits for (a promise, a
146
182
  * GSAP tween or timeline, a Web Animation, a list of them).
147
183
  */
148
- on(name: RouterMoment, fn: Step): () => void;
149
- on(name: "error", fn: (e: { error: unknown; url: string }) => void): () => void;
184
+ on(name: RouterMoment, fn: Step, options?: RouterHookOptions): () => void;
185
+ on(
186
+ name: "error",
187
+ fn: (e: RouterData & { error: unknown; url: string }) => void,
188
+ options?: RouterHookOptions,
189
+ ): () => void;
150
190
  /**
151
- * One page's own code (its data-gl-page): beforeEnter / afterEnter as it comes in (the
191
+ * One page's own code (its data-umber-page): beforeEnter / afterEnter as it comes in (the
152
192
  * first load too), beforeLeave / afterLeave as it goes. Returns its remover.
153
193
  */
154
194
  view(page: string, view: RouterView): () => void;
155
195
  }
156
196
 
157
197
  /** The moments of a change: before, each step, after. */
158
- export type RouterMoment = "before" | "beforeLeave" | "leave" | "afterLeave" | "beforeEnter" | "enter" | "afterEnter" | "after";
198
+ export type RouterMoment =
199
+ "before" | "beforeLeave" | "leave" | "afterLeave" | "beforeEnter" | "enter" | "afterEnter" | "after";
159
200
 
160
- /** A page's set-up and take-down (gl.router.view()). */
201
+ /** A page's set-up and take-down (umber.router.view()). */
161
202
  export interface RouterView {
162
203
  beforeEnter?: Step;
163
204
  afterEnter?: Step;
@@ -166,16 +207,17 @@ export interface RouterView {
166
207
  }
167
208
 
168
209
  declare module "./umber.js" {
169
- interface GL {
210
+ interface Umber {
170
211
  /** The router module's API (types/router.d.ts). */
171
212
  readonly router: RouterApi;
172
213
  }
173
214
  }
174
215
 
175
- /** gl.use(Router, options), createGL({ modules: [Router] }). */
216
+ /** umber.use(Router, options), createUmber({ modules: [Router] }). */
176
217
  export declare const Router: UmberModule;
177
218
 
178
- /** The same without gl.use(): adds gl.router to `engine`. */
179
- export declare function router(engine: GL, options?: RouterOptions): RouterApi;
219
+ /** The same without umber.use(): adds umber.router to `engine`. */
220
+ export declare function router(engine: Umber, options?: RouterOptions): RouterApi;
180
221
 
222
+ /** @alias The same module as the named export, for `import Router from`. */
181
223
  export default Router;
package/types/scroll.d.ts CHANGED
@@ -1,30 +1,40 @@
1
- // -----------------------------------------
2
- // UMBER MODULE: SCROLL, TYPES (@occluze/umber/scroll)
3
- // -----------------------------------------
1
+ /**
2
+ * Types for the scroll module (@occluze/umber/scroll).
3
+ *
4
+ * Smooth scrolling on Umber's own loop: the wheel eases the real scroll position, written
5
+ * before the engine reads it each frame, so planes and the DOM move together (0 px apart)
6
+ * with no createUmber({ scroll }). Keys, the scrollbar, find-in-page, zoom, sideways swipes,
7
+ * touch (unless `touch: true`) and reduced motion stay native.
8
+ *
9
+ * import { Scroll } from "@occluze/umber/scroll";
10
+ * umber.use(Scroll, { lerp: 0.1 }); // or createUmber({ modules: [Scroll] })
11
+ * <script src=".../umber@x.y.z/modules/scroll.js"></script> (registers itself)
12
+ *
13
+ * umber.scroll.scrollTo("#work", { offset: -80 });
14
+ * umber.scroll.on("scroll", (s) => console.log(s.animatedScroll, s.velocity));
15
+ * umber.scroll.stop(); umber.scroll.start(); // a modal, a page change
16
+ *
17
+ * HTML: data-umber-scroll="off" | "touch", data-umber-scroll-lerp, data-umber-scroll-duration and
18
+ * data-umber-scroll-offset on <body> (or <html>); data-umber-scroll-offset on a #link or its
19
+ * target; data-umber-scroll-prevent on an element that scrolls natively; data-umber="scroller"
20
+ * on the element that scrolls instead of the window.
21
+ */
4
22
 
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";
23
+ import type { Umber, UmberModule } from "./umber.js";
24
24
 
25
25
  /** Where scrollTo() goes: px, a selector, an element, or "top" / "bottom" (also "#", "#top", "start", "end"). */
26
26
  export type ScrollTarget = number | string | Element | null | undefined;
27
27
 
28
+ /** What a scrollTo() carries for the "scroll" handlers while it runs (umber.scroll.userData). */
29
+ export type UserData = Record<string, unknown>;
30
+
31
+ /** A wheel or touch move as the module heard it (Lenis's virtual-scroll): px, + right / down. */
32
+ export interface VirtualScroll {
33
+ deltaX: number;
34
+ deltaY: number;
35
+ event: WheelEvent | TouchEvent;
36
+ }
37
+
28
38
  export interface ScrollToOptions {
29
39
  /** px added to the target's position (-80: stop 80 px above it, for a fixed header). @default 0 */
30
40
  offset?: number;
@@ -42,26 +52,43 @@ export interface ScrollToOptions {
42
52
  lock?: boolean;
43
53
  /** Animate also while stopped or locked (an immediate one always lands). @default false */
44
54
  force?: boolean;
55
+ /** As it starts. */
56
+ onStart?: (scroll: ScrollApi) => void;
45
57
  /** When it lands (not when something interrupts it). */
46
58
  onComplete?: (scroll: ScrollApi) => void;
59
+ /** umber.scroll.userData while this move runs (who asked for it: { initiator: "snap" }). @default {} */
60
+ userData?: UserData;
47
61
  }
48
62
 
63
+ /** Which way of a gesture moves the page: its up / down, its sideways, or whichever is larger. */
64
+ export type GestureOrientation = "vertical" | "horizontal" | "both";
65
+
49
66
  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 */
67
+ /** The way the page scrolls: "horizontal" scrolls it sideways (scrollLeft, widths). Read once, at umber.use(). @default "vertical" */
68
+ orientation?: "vertical" | "horizontal";
69
+ /** Which way of the wheel or a finger moves it: its up / down, its sideways, or whichever is larger ("both"). @default "vertical", "both" when horizontal */
70
+ gestureOrientation?: GestureOrientation;
71
+ /** How fast it eases, as Lenis's lerp: about this share of the way per 60 fps frame (exactly 1 - e^-lerp), the same at any refresh rate (1: at once). @default 0.1 */
51
72
  lerp?: number;
52
73
  /** Seconds a wheel move takes, with `easing`; 0 uses the lerp. @default 0 */
53
74
  duration?: number;
54
75
  /** For `duration`. @default an expo ease-out */
55
- easing?: (t: number) => number;
76
+ easing?: ((t: number) => number) | null;
56
77
  /** Wheel px times this. @default 1 */
57
78
  wheelMultiplier?: number;
58
79
  /** Smooth the wheel. false: the wheel scrolls natively (scrollTo() and anchors still animate). @default true */
59
80
  wheel?: boolean;
60
- /** Smooth touch too: follows the finger, eases its fling. Read once, at gl.use(). @default false (phones scroll natively) */
81
+ /** Smooth touch too: follows the finger, eases its fling. Read once, at umber.use(). @default false (phones scroll natively) */
61
82
  touch?: boolean;
62
83
  /** Finger px times this. @default 1 */
63
84
  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 */
85
+ /** A fling's lerp (Lenis's syncTouchLerp). @default about 0.05: a phone's own momentum (325 ms) */
86
+ touchLerp?: number | null;
87
+ /** A fling goes the finger's last px per frame to this power (Lenis's, which uses 1.7). null: speed x 325 ms, like a phone. @default null */
88
+ touchInertiaExponent?: number | null;
89
+ /** Sees every wheel and touch move first ({ deltaX, deltaY, event }); false leaves it to the browser (Lenis's virtualScroll). */
90
+ virtualScroll?: ((data: VirtualScroll) => boolean) | null;
91
+ /** What scrolls: the window (null) or an element (give it data-umber="scroller" so planes follow it). @default [data-umber~=scroller], else the window */
65
92
  wrapper?: Element | string | Window | null;
66
93
  /** What grows (watched for `limit`). @default the wrapper's first child, or <html> */
67
94
  content?: Element | string | null;
@@ -69,17 +96,23 @@ export interface ScrollOptions {
69
96
  anchors?: boolean | ScrollToOptions;
70
97
  /** Follow size changes (a ResizeObserver, resize). false: call resize() yourself. @default true */
71
98
  autoResize?: boolean;
72
- /** true for an element whose wheel / touch stays native (like data-gl-scroll-prevent). */
99
+ /** true for an element whose wheel / touch stays native (like data-umber-scroll-prevent). */
73
100
  prevent?: ((el: Element) => boolean) | null;
74
101
  /** An element under the pointer that scrolls by itself scrolls first, natively. @default true */
75
102
  nested?: boolean;
103
+ /** stop() / start() follow the scroller's own overflow: a modal library that hides it stops the module, and showing it starts it (Lenis's autoToggle). @default false */
104
+ autoToggle?: boolean;
105
+ /** Where the wheel (and touch) are heard: the scroller (null), or another element. @default null */
106
+ eventsTarget?: Element | string | Window | null;
107
+ /** Endless: past the end it goes on from the start, and back (the page repeats its first screen at its end, as for Lenis's). @default false */
108
+ infinite?: boolean;
76
109
  }
77
110
 
78
- /** gl.scroll: the shape scroll libraries share (scrollTo, animatedScroll, on("scroll")...). */
111
+ /** umber.scroll: the shape scroll libraries share (scrollTo, animatedScroll, on("scroll")...). */
79
112
  export interface ScrollApi {
80
- /** Where the page is drawn now (px). */
113
+ /** Where the page is drawn now (px; with `infinite`, it counts on past the end and below 0). */
81
114
  readonly animatedScroll: number;
82
- /** The same (the name some tools read). */
115
+ /** Where the page is drawn, 0..limit (animatedScroll; with `infinite`, wrapped). */
83
116
  readonly scroll: number;
84
117
  /** Where it is heading (px). */
85
118
  readonly targetScroll: number;
@@ -89,6 +122,10 @@ export interface ScrollApi {
89
122
  readonly limit: number;
90
123
  /** px per frame at 60 fps (+ down); 0 at rest. */
91
124
  readonly velocity: number;
125
+ /** The velocity before its last change. */
126
+ readonly lastVelocity: number;
127
+ /** The running scrollTo()'s userData; {} otherwise. */
128
+ readonly userData: UserData;
92
129
  /** 1 down, -1 up (the last move's); 0 before any. */
93
130
  readonly direction: 1 | -1 | 0;
94
131
  /** animatedScroll / limit, 0..1. */
@@ -99,34 +136,55 @@ export interface ScrollApi {
99
136
  readonly isLocked: boolean;
100
137
  /** The element that scrolls (<html> for the window). */
101
138
  readonly rootElement: Element;
139
+ /** It scrolls sideways (orientation: "horizontal"). */
140
+ readonly isHorizontal: boolean;
102
141
  /** 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 }) */
142
+ readonly options: ScrollOptions &
143
+ Required<
144
+ Pick<
145
+ ScrollOptions,
146
+ | "gestureOrientation"
147
+ | "lerp"
148
+ | "duration"
149
+ | "wheelMultiplier"
150
+ | "wheel"
151
+ | "touchMultiplier"
152
+ | "anchors"
153
+ | "autoResize"
154
+ | "nested"
155
+ >
156
+ >;
157
+ /** @example umber.scroll.scrollTo("#contact", { offset: -80, duration: 1.2 }) */
105
158
  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(). */
159
+ /** Hold the page (a modal, a page change): no wheel, touch, keys or scrollTo() (one with force or immediate still moves) until start(). */
107
160
  stop(): void;
108
161
  start(): void;
109
162
  /** Measure again now and take the real position (after a page swap). */
110
163
  resize(): void;
111
- /** "scroll": every frame it moves, and on native scrolls, with gl.scroll. Returns its off(). */
164
+ /** A smooth scroller of its own for an element inside the page (Lenis's nested instances; also data-umber="nested"): resolves with it, or null when there is no such element. */
165
+ nest(target: Element | string, options?: ScrollOptions): Promise<ScrollApi | null>;
166
+ /** "scroll": every frame it moves, and on native scrolls, with umber.scroll. "virtual-scroll": every wheel and touch move it hears. Returns its off(). */
112
167
  on(event: "scroll", fn: (scroll: ScrollApi) => void): () => void;
168
+ on(event: "virtual-scroll", fn: (data: VirtualScroll) => void): () => void;
113
169
  off(event: "scroll", fn: (scroll: ScrollApi) => void): void;
170
+ off(event: "virtual-scroll", fn: (data: VirtualScroll) => void): void;
114
171
  /** Step it from your own loop (ms). Never needed: Umber's loop runs it, and leaves it to you while you call this. */
115
172
  raf(time: number): void;
116
173
  destroy(): void;
117
174
  }
118
175
 
119
176
  declare module "./umber.js" {
120
- interface GL {
177
+ interface Umber {
121
178
  /** The scroll module's smooth scroller (types/scroll.d.ts). */
122
179
  readonly scroll: ScrollApi;
123
180
  }
124
181
  }
125
182
 
126
- /** gl.use(Scroll, options), createGL({ modules: [[Scroll, options]] }). */
183
+ /** umber.use(Scroll, options), createUmber({ modules: [[Scroll, options]] }). */
127
184
  export declare const Scroll: UmberModule;
128
185
 
129
- /** The same without gl.use(): adds gl.scroll to `engine`. */
130
- export declare function smoothScroll(engine: GL, options?: ScrollOptions): ScrollApi;
186
+ /** The same without umber.use(): adds umber.scroll to `engine`. */
187
+ export declare function smoothScroll(engine: Umber, options?: ScrollOptions): ScrollApi;
131
188
 
189
+ /** @alias The same module as the named export, for `import Scroll from`. */
132
190
  export default Scroll;
@@ -0,0 +1,80 @@
1
+ /**
2
+ * Types for the scroll effects module (@occluze/umber/scrollfx).
3
+ *
4
+ * Locomotive Scroll's attributes on Umber's one clock, for any element, with GL planes in
5
+ * step: in-view classes and calls, a scroll-progress CSS variable, parallax, lag,
6
+ * per-element velocity (CSS and GL uniforms), pinned and horizontal sections, and smooth
7
+ * snapping (with the scroll module).
8
+ *
9
+ * import { ScrollFx } from "@occluze/umber/scrollfx";
10
+ * umber.use(ScrollFx); // or createUmber({ modules: [ScrollFx] })
11
+ * <script src=".../umber@x.y.z/umber.js" data-umber-modules="scroll scrollfx"></script>
12
+ *
13
+ * HTML: data-umber="inview"[="class"] (+ -repeat, -start, -end), data-umber-call="event",
14
+ * data-umber-progress[="--var"] (+ -start, -end, -event), data-umber-speed="0.2" (+ -touch, -ignore-fold),
15
+ * data-umber-lag="0.1", data-umber-velocity[="0.12"], data-umber="pin"[="80px"], data-umber="horizontal",
16
+ * data-umber-snap[="start|center|end"].
17
+ */
18
+
19
+ import type { UmberModule } from "./umber.js";
20
+
21
+ export interface SnapOptions {
22
+ /** "proximity": only to a point within `distance` of where the scroll is heading; "mandatory": always to the nearest. @default "proximity" */
23
+ type?: "proximity" | "mandatory";
24
+ /** How near (px, or "50%" of a screen) a point must be for proximity snapping. @default "50%" */
25
+ distance?: number | string;
26
+ /** ms after the last wheel or touch move before it snaps. @default 150 */
27
+ debounce?: number;
28
+ /** This snap's lerp (else the scroll module's). */
29
+ lerp?: number;
30
+ /** Seconds, with `easing` (instead of the lerp). */
31
+ duration?: number;
32
+ easing?: (t: number) => number;
33
+ /** As it starts toward point `index` (in page order) at `value` px. */
34
+ onSnapStart?: (snap: { index: number; value: number }) => void;
35
+ /** When it landed there. */
36
+ onSnapComplete?: (snap: { index: number; value: number }) => void;
37
+ }
38
+
39
+ /** umber.scrollFx.snap: smooth snapping's controls. */
40
+ export interface SnapApi {
41
+ /** To the next or the previous snap point. */
42
+ next(): void;
43
+ previous(): void;
44
+ /** To snap point `index` (page order). */
45
+ goTo(index: number): void;
46
+ /** No snapping until start(). */
47
+ stop(): void;
48
+ start(): void;
49
+ }
50
+
51
+ export interface ScrollFxOptions {
52
+ /** Smooth snapping to [data-umber-snap] elements after a wheel or touch gesture (needs the scroll module); false: off. @default true */
53
+ snap?: boolean | SnapOptions;
54
+ /** The smoothing of data-umber-velocity when it gives none: the share of the way per 60 fps frame. @default 0.12 */
55
+ velocitySmooth?: number;
56
+ /** px per second that reads as 1 in --umber-velocity and uPlaneVelocity (clamped to -1..1). @default 3600 */
57
+ fullSpeed?: number;
58
+ }
59
+
60
+ /** umber.scrollFx. */
61
+ export interface ScrollFxApi {
62
+ /** Look for the attributes in `root` now (new content that no "added" event reports). */
63
+ scan(root?: ParentNode): void;
64
+ /** Smooth snapping's controls. */
65
+ readonly snap: SnapApi;
66
+ destroy(): void;
67
+ }
68
+
69
+ declare module "./umber.js" {
70
+ interface Umber {
71
+ /** The scroll effects module (types/scrollfx.d.ts). */
72
+ readonly scrollFx: ScrollFxApi;
73
+ }
74
+ }
75
+
76
+ /** umber.use(ScrollFx, options), createUmber({ modules: [[ScrollFx, options]] }). */
77
+ export declare const ScrollFx: UmberModule;
78
+
79
+ /** @alias The same module as the named export, for `import ScrollFx from`. */
80
+ export default ScrollFx;
package/types/scrub.d.ts CHANGED
@@ -1,39 +1,39 @@
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).
1
+ /**
2
+ * Types for the scrub module (@occluze/umber/scrub).
3
+ *
4
+ * Scroll-scrubbed video. Load the module, then mark a video:
5
+ *
6
+ * import { Scrub } from "@occluze/umber/scrub";
7
+ * const gl = createUmber({ modules: [Scrub] });
8
+ * <video data-umber="video" data-umber-scrub src="/scrub.mp4" poster="/scrub.jpg" muted playsinline preload="none">
9
+ *
10
+ * const s = umber.plane(el)?.scrub;
11
+ * if (s) s.progress = 0.4;
12
+ *
13
+ * Attributes (each also a CSS variable, --umber-scrub-start ...)
14
+ * data-umber-scrub "" (scroll drives it) | "manual"
15
+ * data-umber-scrub-start / -end "top bottom" / "bottom top" (element edge, viewport line; %, px)
16
+ * data-umber-scrub-track "parent" | "closest section" | a selector (default: the video)
17
+ * data-umber-scrub-smooth seconds to catch up (default 0.12; 0 with Lenis)
18
+ * data-umber-scrub-source auto | decoder | video | frames
19
+ * data-umber-scrub-src / -src-mobile the scrub MP4 (default: the video's src); -mobile on
20
+ * phones and weak GPUs (device tier not "high")
21
+ * data-umber-scrub-frames / -count image sequence "/seq/f_{0001}.webp" and its frame count
22
+ * data-umber-scrub-fps fps of a sequence or of the <video> tier (default: the MP4's when the decoder read it, else 30)
23
+ * data-umber-scrub-blend mix neighbouring frames (default true)
24
+ * data-umber-scrub-cache GPU frame cache, MB (default by GPU tier: 128 high, 48 mid
25
+ * (phones), 32 low (weak GPUs))
26
+ * data-umber-scrub-reduced "poster" (default) | "scrub", under prefers-reduced-motion
27
+ *
28
+ * Shader inputs on scrubbed planes: uScrubProgress (0..1), uScrubVelocity (progress / s).
29
+ */
30
30
 
31
31
  import type { UmberModule } from "./umber.js";
32
32
 
33
33
  export type ScrubTier = "decoder" | "video" | "frames" | "poster";
34
34
  export type ScrubEvent = "ready" | "tier" | "error";
35
35
 
36
- /** gl.plane(el)?.scrub */
36
+ /** umber.plane(el)?.scrub */
37
37
  export interface ScrubHandle {
38
38
  /** 0..1. Setting it hands the scrub to your code (drive becomes "manual"). */
39
39
  progress: number;
@@ -62,13 +62,14 @@ export interface ScrubModuleOptions {
62
62
  reducedMotion?: "poster" | "scrub";
63
63
  }
64
64
 
65
- // gl.plane(el)?.scrub on a plane the module drives.
65
+ // umber.plane(el)?.scrub on a plane the module drives.
66
66
  declare module "./umber.js" {
67
67
  interface Plane {
68
- /** The scrub handle (with the scrub module, on a data-gl-scrub video). */
68
+ /** The scrub handle (with the scrub module, on a data-umber-scrub video). */
69
69
  readonly scrub?: ScrubHandle;
70
70
  }
71
71
  }
72
72
 
73
73
  export declare const Scrub: UmberModule;
74
+ /** @alias The same module as the named export, for `import Scrub from`. */
74
75
  export default Scrub;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Types for @occluze/umber/svelte: a store of umber.scroll (Svelte's store contract).
3
+ *
4
+ * import { scroll } from "@occluze/umber/svelte";
5
+ * $: progress = $scroll?.progress ?? 0;
6
+ */
7
+
8
+ import type { ScrollApi } from "./scroll.js";
9
+
10
+ /** A readable store: umber.scroll, again every frame it moves (null without the scroll module). The engine: the one on the page, or `gl`. */
11
+ export declare function scrollStore(gl?: { readonly scroll?: ScrollApi } | null): {
12
+ subscribe(run: (scroll: ScrollApi | null) => void): () => void;
13
+ };
14
+
15
+ /** The store of the engine on the page. */
16
+ export declare const scroll: ReturnType<typeof scrollStore>;