@occluze/umber 0.0.1 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +62 -2
- package/dist/chunks/capture.js +2 -0
- package/dist/chunks/covers.js +2 -0
- package/dist/chunks/flip.js +2 -0
- package/dist/chunks/fx.js +102 -0
- package/dist/chunks/gl.js +180 -0
- package/dist/chunks/glsl.js +239 -0
- package/dist/chunks/inspect.js +6 -0
- package/dist/chunks/instances.js +93 -0
- package/dist/chunks/layers.js +21 -0
- package/dist/chunks/licence.js +2 -0
- package/dist/chunks/morph.js +2 -0
- package/dist/chunks/restore.js +2 -0
- package/dist/chunks/shapes.js +2 -0
- package/dist/chunks/sim.js +22 -0
- package/dist/chunks/text.js +52 -0
- package/dist/chunks/video.js +2 -0
- package/dist/chunks/views.js +2 -0
- package/dist/chunks/warm.js +2 -0
- package/dist/modules/debug.js +36 -0
- package/dist/modules/debug.mjs +36 -0
- package/dist/modules/handoff.js +2 -0
- package/dist/modules/handoff.mjs +2 -0
- package/dist/modules/input.js +2 -0
- package/dist/modules/input.mjs +2 -0
- package/dist/modules/router-swap.js +13 -0
- package/dist/modules/router.js +2 -0
- package/dist/modules/router.mjs +2 -0
- package/dist/modules/scroll.js +2 -0
- package/dist/modules/scroll.mjs +2 -0
- package/dist/modules/scrub.js +8 -0
- package/dist/modules/scrub.mjs +8 -0
- package/dist/umber.css +2 -0
- package/dist/umber.js +2 -0
- package/dist/umber.mjs +2 -0
- package/docs/AI-quick.md +178 -0
- package/docs/AI.md +2660 -0
- package/docs/npm.md +69 -0
- package/package.json +118 -8
- package/types/debug.d.ts +27 -0
- package/types/esm.d.ts +33 -0
- package/types/handoff.d.ts +116 -0
- package/types/input.d.ts +235 -0
- package/types/router.d.ts +181 -0
- package/types/scroll.d.ts +132 -0
- package/types/scrub.d.ts +74 -0
- package/types/umber.d.ts +1532 -0
- package/index.js +0 -2
package/docs/npm.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Umber as an npm package
|
|
2
|
+
|
|
3
|
+
For bundled sites (Astro, Vite, Next.js) Umber is also an npm package, `@occluze/umber`, on the public npm registry. It is the same engine as `umber.js`, built as an ES module (`dist/umber.mjs`). Webflow sites keep the `<script>` tag ([hosting.md](hosting.md)); nothing changes for them.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
Install the version you want, exactly:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @occluze/umber@x.y.z --save-exact
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
No token or `.npmrc` is needed. What licenses it is the domain list: Umber runs on the domains its developer listed under Umber in their occluze dashboard (and on `localhost` while you build), as [hosting.md](hosting.md) says.
|
|
14
|
+
|
|
15
|
+
## Use it
|
|
16
|
+
|
|
17
|
+
<!-- snippet:npm -->
|
|
18
|
+
```js
|
|
19
|
+
// npm install @occluze/umber@0.2.1 (docs/npm.md)
|
|
20
|
+
import { createGL } from "@occluze/umber";
|
|
21
|
+
import "@occluze/umber/umber.css";
|
|
22
|
+
import { Scrub } from "@occluze/umber/scrub"; // optional module
|
|
23
|
+
|
|
24
|
+
const gl = createGL({ modules: [Scrub] }); // client code only; on the server it does nothing
|
|
25
|
+
```
|
|
26
|
+
<!-- /snippet -->
|
|
27
|
+
|
|
28
|
+
```js
|
|
29
|
+
// src/site.js (runs in the browser). Your libraries stay yours: Umber never imports them.
|
|
30
|
+
import Lenis from "lenis";
|
|
31
|
+
import barba from "@barba/core";
|
|
32
|
+
import { createGL } from "@occluze/umber";
|
|
33
|
+
import { Debug } from "@occluze/umber/debug"; // while you build only
|
|
34
|
+
import { dissolve } from "./gl/effects.js"; // your own effects
|
|
35
|
+
|
|
36
|
+
const lenis = new Lenis({ autoRaf: true });
|
|
37
|
+
const gl = createGL({ scroll: lenis, modules: import.meta.env.DEV ? [Debug] : [] });
|
|
38
|
+
gl.effect("dissolve", dissolve);
|
|
39
|
+
barba.init({ /* your transitions */ });
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
- **Exports:** `.` (`createGL`, `version`, `math` and the maths as named exports: `rectToWorld`, `worldToRect`, `pxPerWorld`, `fitCamera`, `damp`, `clamp`, `lerp`, `mapRange`, `smoothstep`, `rectProgress`), `./scrub` (`Scrub`), `./debug` (`Debug`, `debug`), `./input` (`Input`, `input`), `./handoff` (`Handoff`, `handoff`; `Handoff.headSnippet`), `./scroll` (`Scroll`, `smoothScroll`), `./router` (`Router`, `router`; its second file, `dist/modules/router-swap.js`, is `import()`ed from it, so your bundler splits it off), `./umber.css`, `./umber.js` (the script build, sets `window.Umber`). Types are included for all of them (`import type { GL, GLOptions, EffectDef } from "@occluze/umber"`).
|
|
43
|
+
- **Nothing runs on import.** Importing in server-rendered files (Astro frontmatter, a Next.js component) is safe; on the server `createGL()` returns an engine that does nothing (`gl.enabled` false, `gl.reason` `"server"`). Call it from code that runs in the browser (Astro: a `<script>`; Next.js: `useEffect` or a client-only module).
|
|
44
|
+
- **One engine per page.** When a `umber.js` `<script>` already started an engine, `createGL()` returns that one (with a warning) instead of starting a second.
|
|
45
|
+
- **No effects ship in the package.** You write them with `gl.effect()` ("Writing effects" in [AI.md](AI.md)).
|
|
46
|
+
|
|
47
|
+
## The GL chunk still comes from the CDN
|
|
48
|
+
|
|
49
|
+
The GL runtime (`chunks/gl.js`) and its other chunks (`chunks/*.js`: shapes, text, layers, morph, video, fx, warm, views... each only when a page needs it) load on demand from the engine's CDN folder, at the exact version of the package:
|
|
50
|
+
|
|
51
|
+
- default: `https://umber.occluze.com/umber@<version>/`. There is no key: the files are served to anyone, and the licence check (`chunks/licence.js`, next to `chunks/gl.js`) decides whether GL starts on this domain.
|
|
52
|
+
- to load them from somewhere else (a staging copy of the engine, say):
|
|
53
|
+
|
|
54
|
+
```js
|
|
55
|
+
import { createGL } from "@occluze/umber";
|
|
56
|
+
createGL({ base: "https://umber.occluze.com/umber@x.y.z/" });
|
|
57
|
+
// or, before createGL() runs: window.UmberConfig = { base: "..." }
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Keep the version in that URL the same as the package version.
|
|
61
|
+
|
|
62
|
+
Self-hosting instead: copy `node_modules/@occluze/umber/dist/` to your public folder and set `base` to that folder.
|
|
63
|
+
|
|
64
|
+
## Honest limits
|
|
65
|
+
|
|
66
|
+
- **The code is public once a site uses it**, as with any front-end code: anyone can read the files a page loads. The domain list is what licenses Umber; the files ship minified, without source maps.
|
|
67
|
+
- **The chunks come from the CDN**: when they can't load, the GL runtime does not start (the console says `chunks/gl.js failed to load`) and the plain DOM shows. The engine facade, bundled into the site, keeps running.
|
|
68
|
+
- **Mixing versions:** the package version and the `base` URL version must match. A mismatch can load a GL chunk of another version.
|
|
69
|
+
- **Publishing** (engine owner, Ravi): `npm publish` sends it to the public npm registry (`publishConfig` in package.json), under the npm organisation **occluze**, which owns the `@occluze` scope. Only the built files in `files` ship: no source and no source maps.
|
package/package.json
CHANGED
|
@@ -1,12 +1,122 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@occluze/umber",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Umber
|
|
5
|
-
"type": "module",
|
|
6
|
-
"main": "index.js",
|
|
7
|
-
"files": ["index.js", "README.md"],
|
|
8
|
-
"homepage": "https://occluze.com",
|
|
9
|
-
"author": "R—K (Ravi Klaassens)",
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"description": "Umber: a DOM-to-WebGL engine that works next to Barba, Lenis and GSAP and controls none of them. Tag DOM elements; Umber draws them as GPU planes on one canvas, kept in line with the page.",
|
|
10
5
|
"license": "UNLICENSED",
|
|
11
|
-
"
|
|
6
|
+
"homepage": "https://github.com/ravi-klaassens/umber#readme",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/ravi-klaassens/umber.git"
|
|
10
|
+
},
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/ravi-klaassens/umber/issues"
|
|
13
|
+
},
|
|
14
|
+
"type": "module",
|
|
15
|
+
"main": "./dist/umber.mjs",
|
|
16
|
+
"module": "./dist/umber.mjs",
|
|
17
|
+
"types": "./types/esm.d.ts",
|
|
18
|
+
"exports": {
|
|
19
|
+
".": {
|
|
20
|
+
"types": "./types/esm.d.ts",
|
|
21
|
+
"import": "./dist/umber.mjs",
|
|
22
|
+
"default": "./dist/umber.mjs"
|
|
23
|
+
},
|
|
24
|
+
"./scrub": {
|
|
25
|
+
"types": "./types/scrub.d.ts",
|
|
26
|
+
"import": "./dist/modules/scrub.mjs",
|
|
27
|
+
"default": "./dist/modules/scrub.mjs"
|
|
28
|
+
},
|
|
29
|
+
"./debug": {
|
|
30
|
+
"types": "./types/debug.d.ts",
|
|
31
|
+
"import": "./dist/modules/debug.mjs",
|
|
32
|
+
"default": "./dist/modules/debug.mjs"
|
|
33
|
+
},
|
|
34
|
+
"./input": {
|
|
35
|
+
"types": "./types/input.d.ts",
|
|
36
|
+
"import": "./dist/modules/input.mjs",
|
|
37
|
+
"default": "./dist/modules/input.mjs"
|
|
38
|
+
},
|
|
39
|
+
"./handoff": {
|
|
40
|
+
"types": "./types/handoff.d.ts",
|
|
41
|
+
"import": "./dist/modules/handoff.mjs",
|
|
42
|
+
"default": "./dist/modules/handoff.mjs"
|
|
43
|
+
},
|
|
44
|
+
"./scroll": {
|
|
45
|
+
"types": "./types/scroll.d.ts",
|
|
46
|
+
"import": "./dist/modules/scroll.mjs",
|
|
47
|
+
"default": "./dist/modules/scroll.mjs"
|
|
48
|
+
},
|
|
49
|
+
"./router": {
|
|
50
|
+
"types": "./types/router.d.ts",
|
|
51
|
+
"import": "./dist/modules/router.mjs",
|
|
52
|
+
"default": "./dist/modules/router.mjs"
|
|
53
|
+
},
|
|
54
|
+
"./umber.css": "./dist/umber.css",
|
|
55
|
+
"./umber.js": "./dist/umber.js",
|
|
56
|
+
"./types": "./types/umber.d.ts",
|
|
57
|
+
"./package.json": "./package.json"
|
|
58
|
+
},
|
|
59
|
+
"files": [
|
|
60
|
+
"dist/umber.mjs",
|
|
61
|
+
"dist/umber.js",
|
|
62
|
+
"dist/umber.css",
|
|
63
|
+
"dist/chunks/*.js",
|
|
64
|
+
"dist/modules/*.js",
|
|
65
|
+
"dist/modules/*.mjs",
|
|
66
|
+
"types/umber.d.ts",
|
|
67
|
+
"types/esm.d.ts",
|
|
68
|
+
"types/scrub.d.ts",
|
|
69
|
+
"types/debug.d.ts",
|
|
70
|
+
"types/input.d.ts",
|
|
71
|
+
"types/handoff.d.ts",
|
|
72
|
+
"types/scroll.d.ts",
|
|
73
|
+
"types/router.d.ts",
|
|
74
|
+
"docs/npm.md",
|
|
75
|
+
"docs/AI.md",
|
|
76
|
+
"docs/AI-quick.md"
|
|
77
|
+
],
|
|
78
|
+
"sideEffects": [
|
|
79
|
+
"*.css",
|
|
80
|
+
"./dist/umber.js",
|
|
81
|
+
"./dist/modules/scrub.js",
|
|
82
|
+
"./dist/modules/debug.js",
|
|
83
|
+
"./dist/modules/input.js",
|
|
84
|
+
"./dist/modules/handoff.js",
|
|
85
|
+
"./dist/modules/scroll.js",
|
|
86
|
+
"./dist/modules/router.js"
|
|
87
|
+
],
|
|
88
|
+
"publishConfig": {
|
|
89
|
+
"registry": "https://registry.npmjs.org",
|
|
90
|
+
"access": "public"
|
|
91
|
+
},
|
|
92
|
+
"scripts": {
|
|
93
|
+
"build": "node scripts/build.mjs && node scripts/docs.mjs",
|
|
94
|
+
"dev": "node scripts/build.mjs --watch --serve",
|
|
95
|
+
"typecheck": "tsc --noEmit",
|
|
96
|
+
"test": "vitest run",
|
|
97
|
+
"check:browser": "node test/browser/all.mjs",
|
|
98
|
+
"check:oracle": "node test/browser/oracle.mjs",
|
|
99
|
+
"check:render": "node test/browser/render.mjs",
|
|
100
|
+
"check:idle": "node test/browser/idle.mjs",
|
|
101
|
+
"check:sync": "node test/browser/sync.mjs",
|
|
102
|
+
"check:size": "node test/browser/size.mjs",
|
|
103
|
+
"check:glsl": "node test/browser/glsl.mjs",
|
|
104
|
+
"check:stress": "node test/browser/stress.mjs",
|
|
105
|
+
"check:capture": "node test/browser/capture.mjs",
|
|
106
|
+
"check:router": "node test/browser/router.mjs",
|
|
107
|
+
"scrub": "node scripts/scrub.mjs",
|
|
108
|
+
"release": "node deploy/release.mjs",
|
|
109
|
+
"deploy": "cd deploy && wrangler pages deploy site --project-name umber --branch main",
|
|
110
|
+
"prepublishOnly": "npm run build"
|
|
111
|
+
},
|
|
112
|
+
"devDependencies": {
|
|
113
|
+
"esbuild": "0.25.10",
|
|
114
|
+
"happy-dom": "18.0.1",
|
|
115
|
+
"lenis": "1.3.23",
|
|
116
|
+
"pixelmatch": "7.2.0",
|
|
117
|
+
"playwright": "1.63.0",
|
|
118
|
+
"typescript": "5.9.3",
|
|
119
|
+
"vitest": "3.2.4",
|
|
120
|
+
"wrangler": "4.156.2"
|
|
121
|
+
}
|
|
12
122
|
}
|
package/types/debug.d.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
// -----------------------------------------
|
|
2
|
+
// UMBER MODULE: DEBUG, TYPES (@occluze/umber/debug)
|
|
3
|
+
// -----------------------------------------
|
|
4
|
+
|
|
5
|
+
// The HUD, plane outlines and scroll markers. Load it while you build:
|
|
6
|
+
//
|
|
7
|
+
// import { Debug } from "@occluze/umber/debug";
|
|
8
|
+
// gl.use(Debug, { outlines: true, markers: true });
|
|
9
|
+
//
|
|
10
|
+
// <script src=".../umber@x.y.z/modules/debug.js" data-outlines data-markers></script>
|
|
11
|
+
//
|
|
12
|
+
// ?umber-debug=hud,outlines,markers in the URL picks the parts too.
|
|
13
|
+
|
|
14
|
+
import type { DebugOptions, GL, UmberModule } from "./umber.js";
|
|
15
|
+
|
|
16
|
+
export type { DebugOptions };
|
|
17
|
+
|
|
18
|
+
/** gl.use(Debug, options), createGL({ modules: [Debug], debug: { outlines: true } }). */
|
|
19
|
+
export declare const Debug: UmberModule;
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* The same without gl.use(): mounts the parts for `engine` and returns destroy().
|
|
23
|
+
* @example const stop = debug(gl, { outlines: true }); stop();
|
|
24
|
+
*/
|
|
25
|
+
export declare function debug(engine: GL, options?: DebugOptions): () => void;
|
|
26
|
+
|
|
27
|
+
export default Debug;
|
package/types/esm.d.ts
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
// -----------------------------------------
|
|
2
|
+
// UMBER: TYPES FOR THE NPM PACKAGE
|
|
3
|
+
// -----------------------------------------
|
|
4
|
+
|
|
5
|
+
// What `import { createGL } from "@occluze/umber"` gives you (dist/umber.mjs,
|
|
6
|
+
// src/esm.ts). Every type comes from umber.d.ts (the same API as window.Umber).
|
|
7
|
+
//
|
|
8
|
+
// import { createGL } from "@occluze/umber";
|
|
9
|
+
// import type { GL, GLOptions, EffectDef } from "@occluze/umber";
|
|
10
|
+
|
|
11
|
+
import type { GL, GLOptions, UmberMath } from "./umber.js";
|
|
12
|
+
|
|
13
|
+
export * from "./umber.js";
|
|
14
|
+
|
|
15
|
+
export declare const version: string;
|
|
16
|
+
/** Start the engine (once per page; a second call returns the first engine). On the server it does nothing. */
|
|
17
|
+
export declare function createGL(options?: GLOptions): GL;
|
|
18
|
+
|
|
19
|
+
/** DOM <-> three.js maths (pure functions, no engine needed). */
|
|
20
|
+
export declare const pxPerWorld: UmberMath["pxPerWorld"];
|
|
21
|
+
export declare const fitCamera: UmberMath["fitCamera"];
|
|
22
|
+
export declare const rectToWorld: UmberMath["rectToWorld"];
|
|
23
|
+
export declare const worldToRect: UmberMath["worldToRect"];
|
|
24
|
+
export declare const damp: UmberMath["damp"];
|
|
25
|
+
export declare const clamp: UmberMath["clamp"];
|
|
26
|
+
export declare const lerp: UmberMath["lerp"];
|
|
27
|
+
export declare const mapRange: UmberMath["mapRange"];
|
|
28
|
+
export declare const smoothstep: UmberMath["smoothstep"];
|
|
29
|
+
export declare const rectProgress: UmberMath["rectProgress"];
|
|
30
|
+
export declare const math: UmberMath;
|
|
31
|
+
|
|
32
|
+
declare const Umber: { readonly version: string; createGL(options?: GLOptions): GL; readonly math: UmberMath };
|
|
33
|
+
export default Umber;
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
// -----------------------------------------
|
|
2
|
+
// UMBER MODULE: HANDOFF, TYPES (@occluze/umber/handoff)
|
|
3
|
+
// -----------------------------------------
|
|
4
|
+
|
|
5
|
+
// data-gl-id images that fly across full page loads (multi-page sites, no router), the
|
|
6
|
+
// canvas over cross-document View Transitions, a cover pass of your own shader, and the
|
|
7
|
+
// accessibility bits of a page change:
|
|
8
|
+
//
|
|
9
|
+
// import { Handoff } from "@occluze/umber/handoff";
|
|
10
|
+
// gl.use(Handoff, { cover: "ink" }); // or createGL({ modules: [Handoff] })
|
|
11
|
+
// <script src=".../umber@x.y.z/modules/handoff.js"></script> (registers itself)
|
|
12
|
+
//
|
|
13
|
+
// gl.handoff.arrived the record this page was opened with, or null
|
|
14
|
+
// gl.handoff.cover("ink", { phase: "cover" }) a router's leave hook
|
|
15
|
+
// gl.handoff.cover("ink", { phase: "reveal" }) ... and its enter hook
|
|
16
|
+
// gl.handoff.announce(); gl.handoff.focus(); after a router's swap
|
|
17
|
+
|
|
18
|
+
import type { GL, UmberModule } from "./umber.js";
|
|
19
|
+
|
|
20
|
+
export interface HandoffOptions {
|
|
21
|
+
/** ms a leave record stays good for the next page. @default 3000 */
|
|
22
|
+
maxAge?: number;
|
|
23
|
+
/** Lift the canvas over a cross-document View Transition (needs layer "over"). @default true */
|
|
24
|
+
vt?: boolean;
|
|
25
|
+
/** A gl.shader() name played (revealing, from the old page's click) on a page reached through a record. @default null */
|
|
26
|
+
cover?: string | null;
|
|
27
|
+
/** Seconds of that reveal. @default 0.8 */
|
|
28
|
+
coverDuration?: number;
|
|
29
|
+
/** Its Umber ease. @default "umber" */
|
|
30
|
+
coverEase?: string;
|
|
31
|
+
/** Where focus goes on a page reached from the keyboard (Enter on a link). false: the browser's own. @default "h1" */
|
|
32
|
+
focus?: string | false;
|
|
33
|
+
/** Announce the new page's title on arrival (a full load is announced by the screen reader already). @default false */
|
|
34
|
+
announce?: boolean;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export interface HandoffItem {
|
|
38
|
+
id: string;
|
|
39
|
+
/** The picture it showed (absolute URL). */
|
|
40
|
+
src: string;
|
|
41
|
+
/** Where it was: viewport CSS px [x, y, width, height]. */
|
|
42
|
+
rect: [number, number, number, number];
|
|
43
|
+
/** Its CSS border-radius. */
|
|
44
|
+
radius: string;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** What the old page left in sessionStorage ("umber:handoff"), read once by the next. */
|
|
48
|
+
export interface HandoffRecord {
|
|
49
|
+
v: number;
|
|
50
|
+
/** Date.now() when the old page left. */
|
|
51
|
+
at: number;
|
|
52
|
+
from: string;
|
|
53
|
+
to: string;
|
|
54
|
+
vw: number;
|
|
55
|
+
vh: number;
|
|
56
|
+
/** The click, 0..1 of the viewport (y down), or null. */
|
|
57
|
+
click: [number, number] | null;
|
|
58
|
+
/** Left from the keyboard. */
|
|
59
|
+
kb: boolean;
|
|
60
|
+
/** The old page drew GL over the page (layer "over"). */
|
|
61
|
+
over: boolean;
|
|
62
|
+
items: HandoffItem[];
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export interface CoverOptions {
|
|
66
|
+
/** "cover": the page goes under it (uCover 0 -> 1, it stays); "reveal": it lifts and goes (1 -> 0). @default "reveal" */
|
|
67
|
+
phase?: "cover" | "reveal";
|
|
68
|
+
/** Seconds. @default the module's coverDuration */
|
|
69
|
+
duration?: number;
|
|
70
|
+
/** Any Umber ease. @default the module's coverEase */
|
|
71
|
+
ease?: string;
|
|
72
|
+
/** Viewport px the pass grows from (uOrigin). @default the last click, else the centre */
|
|
73
|
+
origin?: [number, number] | null;
|
|
74
|
+
/** uDirection: 1 forward, -1 back. @default the navigation's */
|
|
75
|
+
direction?: 1 | -1;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** gl.handoff, once the module is in. */
|
|
79
|
+
export interface HandoffApi {
|
|
80
|
+
/** The record this page was opened with (this URL, fresh, not a reload), or null. */
|
|
81
|
+
readonly arrived: HandoffRecord | null;
|
|
82
|
+
/** The old page's click on arrival, or the last click here: viewport px, or null. */
|
|
83
|
+
readonly origin: [number, number] | null;
|
|
84
|
+
/** 1 forward, -1 back through history. */
|
|
85
|
+
readonly direction: 1 | -1;
|
|
86
|
+
/** The cross-document View Transition this page was revealed with (await its finished), or null. */
|
|
87
|
+
readonly viewTransition: { readonly finished: Promise<unknown> } | null;
|
|
88
|
+
/** The module's options, live: with the script build, set them right after createGL(). */
|
|
89
|
+
readonly options: Required<HandoffOptions>;
|
|
90
|
+
/**
|
|
91
|
+
* A full-screen pass of your own shader over the page. It sets uCover (0 shows the page,
|
|
92
|
+
* 1 covers it), uOrigin (0..1, y down) and uDirection (1 | -1) where the shader declares
|
|
93
|
+
* them. Resolves when it is done. Reduced motion: nothing plays.
|
|
94
|
+
* @example gl.shader("ink", { uniforms: { uCover: 0, uOrigin: [0.5, 0.5], uDirection: 1 }, fragment: "..." });
|
|
95
|
+
*/
|
|
96
|
+
cover(shader: string, options?: CoverOptions): Promise<void>;
|
|
97
|
+
/** Say text (default: document.title) in a polite live region. */
|
|
98
|
+
announce(text?: string): void;
|
|
99
|
+
/** Focus target (default: the first h1, else main) without scrolling. */
|
|
100
|
+
focus(target?: string | Element | null): boolean;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
declare module "./umber.js" {
|
|
104
|
+
interface GL {
|
|
105
|
+
/** The handoff module's API (types/handoff.d.ts). */
|
|
106
|
+
readonly handoff: HandoffApi;
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** gl.use(Handoff), createGL({ modules: [Handoff] }). headSnippet: the <script> to paste into <head>. */
|
|
111
|
+
export declare const Handoff: UmberModule & { readonly headSnippet: string };
|
|
112
|
+
|
|
113
|
+
/** The same without gl.use(): adds gl.handoff to `engine`. */
|
|
114
|
+
export declare function handoff(engine: GL, options?: HandoffOptions): HandoffApi;
|
|
115
|
+
|
|
116
|
+
export default Handoff;
|
package/types/input.d.ts
ADDED
|
@@ -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;
|