@wave3d/element 0.1.0 → 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.
- package/README.md +16 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js.map +1 -1
- package/package.json +10 -4
package/README.md
CHANGED
|
@@ -7,10 +7,10 @@ Poster-first and lazy: it shows a poster immediately, then upgrades to live WebG
|
|
|
7
7
|
## Install
|
|
8
8
|
|
|
9
9
|
```sh
|
|
10
|
-
pnpm add @wave3d/element
|
|
10
|
+
pnpm add @wave3d/element three
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
`@wave3d/core`
|
|
13
|
+
`three` is a peer dependency; `@wave3d/core` is bundled in.
|
|
14
14
|
|
|
15
15
|
## Usage
|
|
16
16
|
|
|
@@ -43,6 +43,20 @@ Also a `config` **property** (merged last, over the attributes) and a read-only
|
|
|
43
43
|
- `wave3d-ready` — `detail` is the live `WaveRenderer`.
|
|
44
44
|
- `wave3d-fallback` — `detail` is the fallback reason.
|
|
45
45
|
|
|
46
|
+
## Capture a poster
|
|
47
|
+
|
|
48
|
+
Grab the live frame as an image once the wave is running — e.g. to generate the `poster` that reduced-motion, no-WebGL, and Save-Data visitors see:
|
|
49
|
+
|
|
50
|
+
```js
|
|
51
|
+
const wave = document.querySelector("wave-3d");
|
|
52
|
+
wave.addEventListener("wave3d-ready", async () => {
|
|
53
|
+
const blob = await wave.handle.snapshot(); // WebP of the current frame, transparent
|
|
54
|
+
// host / cache `blob`, then use it as the poster
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`handle.snapshot(options?)` resolves `null` until the wave is running. Options: `type` (default `"image/webp"`), `quality`, `transparent` (default `true`).
|
|
59
|
+
|
|
46
60
|
## Custom tag name
|
|
47
61
|
|
|
48
62
|
```ts
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { FallbackReason, StudioConfig, StudioConfig as StudioConfig$1, WaveHandle, WaveHandle as WaveHandle$1, WaveRenderer } from "@wave3d/core";
|
|
1
|
+
import { FallbackReason, SnapshotOptions, StudioConfig, StudioConfig as StudioConfig$1, WaveHandle, WaveHandle as WaveHandle$1, WaveRenderer } from "@wave3d/core";
|
|
2
2
|
|
|
3
3
|
//#region src/index.d.ts
|
|
4
4
|
declare const ElementBase: typeof HTMLElement;
|
|
@@ -23,5 +23,5 @@ declare class Wave3DElement extends ElementBase {
|
|
|
23
23
|
/** Define the element (idempotent, SSR/Node-import-safe). */
|
|
24
24
|
declare function register(tag?: string): void;
|
|
25
25
|
//#endregion
|
|
26
|
-
export { type FallbackReason, type StudioConfig, Wave3DElement, type WaveHandle, type WaveRenderer, register };
|
|
26
|
+
export { type FallbackReason, type SnapshotOptions, type StudioConfig, Wave3DElement, type WaveHandle, type WaveRenderer, register };
|
|
27
27
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","names":["#handle","#config","#scheduleUpdate","#mount","#debounce","#boolAttr","#buildConfig","#update"],"sources":["../src/index.ts"],"sourcesContent":["import { createWave } from \"@wave3d/core\";\nimport type {\n StudioConfig,\n WaveHandle,\n WaveOptions,\n WaveRenderer,\n FallbackReason,\n} from \"@wave3d/core\";\n\nconst OBSERVED = [\"config\", \"src\", \"preset\", \"poster\", \"paused\", \"lazy\", \"webgl\"] as const;\n\n// SSR-safe base: `class extends HTMLElement` evaluates HTMLElement at import time, which throws\n// under Node. Fall back to a dummy base there — the element is never instantiated server-side\n// (register() is guarded), so the missing DOM methods are never called.\nconst ElementBase: typeof HTMLElement =\n typeof HTMLElement !== \"undefined\"\n ? HTMLElement\n : (function Wave3DElementBase() {} as unknown as typeof HTMLElement);\n\n/**\n * `<wave-3d>` — the framework-agnostic drop-in (Vue/Svelte/plain HTML). Light DOM, `display:block`.\n * Attributes: `config` (JSON), `src` (URL to a config JSON), `preset` (name), `poster`, `paused`,\n * `lazy`, `webgl`. Also a `config` property and a read-only `handle` getter. Emits `wave3d-ready`\n * (detail = renderer) and `wave3d-fallback` (detail = reason) events.\n */\nexport class Wave3DElement extends ElementBase {\n static get observedAttributes(): string[] {\n return [...OBSERVED];\n }\n\n #handle: WaveHandle | null = null;\n #config: Partial<StudioConfig> = {};\n #debounce?: ReturnType<typeof setTimeout>;\n\n /** The live shell handle (null before connect / after disconnect). */\n get handle(): WaveHandle | null {\n return this.#handle;\n }\n\n /** Programmatic config, merged last (over the `preset`/`src`/`config` attributes). */\n get config(): Partial<StudioConfig> {\n return this.#config;\n }\n set config(value: Partial<StudioConfig>) {\n this.#config = value ?? {};\n this.#scheduleUpdate();\n }\n\n connectedCallback(): void {\n if (!this.style.display) this.style.display = \"block\";\n void this.#mount();\n }\n\n disconnectedCallback(): void {\n clearTimeout(this.#debounce);\n this.#handle?.destroy();\n this.#handle = null;\n }\n\n attributeChangedCallback(name: string): void {\n if (!this.#handle) return;\n if (name === \"paused\") {\n if (this.#boolAttr(\"paused\")) this.#handle.pause();\n else this.#handle.play();\n } else {\n this.#scheduleUpdate();\n }\n }\n\n async #mount(): Promise<void> {\n const config = await this.#buildConfig();\n if (!this.isConnected) return; // disconnected while the config resolved\n const options: WaveOptions = {\n poster: this.getAttribute(\"poster\") ?? undefined,\n lazy: this.#boolAttr(\"lazy\"),\n webgl: (this.getAttribute(\"webgl\") as WaveOptions[\"webgl\"]) ?? undefined,\n paused: this.#boolAttr(\"paused\"),\n onReady: (renderer: WaveRenderer) =>\n this.dispatchEvent(new CustomEvent(\"wave3d-ready\", { detail: renderer })),\n onFallback: (reason: FallbackReason) =>\n this.dispatchEvent(new CustomEvent(\"wave3d-fallback\", { detail: reason })),\n };\n this.#handle = createWave(this, config, options);\n }\n\n /** default ← preset ← src JSON ← config attribute ← config property. */\n async #buildConfig(): Promise<Partial<StudioConfig>> {\n let base: Partial<StudioConfig> = {};\n const presetName = this.getAttribute(\"preset\");\n if (presetName) {\n const { PRESETS } = await import(\"@wave3d/core/presets\");\n base = PRESETS[presetName]?.() ?? {};\n }\n const src = this.getAttribute(\"src\");\n if (src) {\n try {\n base = { ...base, ...(await fetch(src).then((r) => r.json())) };\n } catch {\n // ignore a failed/invalid config fetch — fall through to whatever we have\n }\n }\n base = { ...base, ...parseJson(this.getAttribute(\"config\")), ...this.#config };\n return base;\n }\n\n #scheduleUpdate(): void {\n clearTimeout(this.#debounce);\n this.#debounce = setTimeout(() => {\n void this.#update();\n }, 50);\n }\n\n async #update(): Promise<void> {\n const handle = this.#handle;\n if (!handle) return;\n handle.set(await this.#buildConfig());\n }\n\n /** Presence = true; `\"false\"`/`\"0\"` = false; absent = undefined (shell default). */\n #boolAttr(name: string): boolean | undefined {\n if (!this.hasAttribute(name)) return undefined;\n const value = this.getAttribute(name);\n return value !== \"false\" && value !== \"0\";\n }\n}\n\nfunction parseJson(json: string | null): Partial<StudioConfig> {\n if (!json) return {};\n try {\n return JSON.parse(json) as Partial<StudioConfig>;\n } catch {\n return {};\n }\n}\n\n/** Define the element (idempotent, SSR/Node-import-safe). */\nexport function register(tag = \"wave-3d\"): void {\n if (typeof window === \"undefined\" || typeof customElements === \"undefined\") return;\n if (!customElements.get(tag)) customElements.define(tag, Wave3DElement);\n}\n\n// Self-register on import so a bare `import \"@wave3d/element\"` makes <wave-3d> work. Guarded so\n// importing under Node (SSR) is a no-op rather than a ReferenceError.\nregister();\n\nexport type {
|
|
1
|
+
{"version":3,"file":"index.js","names":["#handle","#config","#scheduleUpdate","#mount","#debounce","#boolAttr","#buildConfig","#update"],"sources":["../src/index.ts"],"sourcesContent":["import { createWave } from \"@wave3d/core\";\nimport type {\n StudioConfig,\n WaveHandle,\n WaveOptions,\n WaveRenderer,\n FallbackReason,\n} from \"@wave3d/core\";\n\nconst OBSERVED = [\"config\", \"src\", \"preset\", \"poster\", \"paused\", \"lazy\", \"webgl\"] as const;\n\n// SSR-safe base: `class extends HTMLElement` evaluates HTMLElement at import time, which throws\n// under Node. Fall back to a dummy base there — the element is never instantiated server-side\n// (register() is guarded), so the missing DOM methods are never called.\nconst ElementBase: typeof HTMLElement =\n typeof HTMLElement !== \"undefined\"\n ? HTMLElement\n : (function Wave3DElementBase() {} as unknown as typeof HTMLElement);\n\n/**\n * `<wave-3d>` — the framework-agnostic drop-in (Vue/Svelte/plain HTML). Light DOM, `display:block`.\n * Attributes: `config` (JSON), `src` (URL to a config JSON), `preset` (name), `poster`, `paused`,\n * `lazy`, `webgl`. Also a `config` property and a read-only `handle` getter. Emits `wave3d-ready`\n * (detail = renderer) and `wave3d-fallback` (detail = reason) events.\n */\nexport class Wave3DElement extends ElementBase {\n static get observedAttributes(): string[] {\n return [...OBSERVED];\n }\n\n #handle: WaveHandle | null = null;\n #config: Partial<StudioConfig> = {};\n #debounce?: ReturnType<typeof setTimeout>;\n\n /** The live shell handle (null before connect / after disconnect). */\n get handle(): WaveHandle | null {\n return this.#handle;\n }\n\n /** Programmatic config, merged last (over the `preset`/`src`/`config` attributes). */\n get config(): Partial<StudioConfig> {\n return this.#config;\n }\n set config(value: Partial<StudioConfig>) {\n this.#config = value ?? {};\n this.#scheduleUpdate();\n }\n\n connectedCallback(): void {\n if (!this.style.display) this.style.display = \"block\";\n void this.#mount();\n }\n\n disconnectedCallback(): void {\n clearTimeout(this.#debounce);\n this.#handle?.destroy();\n this.#handle = null;\n }\n\n attributeChangedCallback(name: string): void {\n if (!this.#handle) return;\n if (name === \"paused\") {\n if (this.#boolAttr(\"paused\")) this.#handle.pause();\n else this.#handle.play();\n } else {\n this.#scheduleUpdate();\n }\n }\n\n async #mount(): Promise<void> {\n const config = await this.#buildConfig();\n if (!this.isConnected) return; // disconnected while the config resolved\n const options: WaveOptions = {\n poster: this.getAttribute(\"poster\") ?? undefined,\n lazy: this.#boolAttr(\"lazy\"),\n webgl: (this.getAttribute(\"webgl\") as WaveOptions[\"webgl\"]) ?? undefined,\n paused: this.#boolAttr(\"paused\"),\n onReady: (renderer: WaveRenderer) =>\n this.dispatchEvent(new CustomEvent(\"wave3d-ready\", { detail: renderer })),\n onFallback: (reason: FallbackReason) =>\n this.dispatchEvent(new CustomEvent(\"wave3d-fallback\", { detail: reason })),\n };\n this.#handle = createWave(this, config, options);\n }\n\n /** default ← preset ← src JSON ← config attribute ← config property. */\n async #buildConfig(): Promise<Partial<StudioConfig>> {\n let base: Partial<StudioConfig> = {};\n const presetName = this.getAttribute(\"preset\");\n if (presetName) {\n const { PRESETS } = await import(\"@wave3d/core/presets\");\n base = PRESETS[presetName]?.() ?? {};\n }\n const src = this.getAttribute(\"src\");\n if (src) {\n try {\n base = { ...base, ...(await fetch(src).then((r) => r.json())) };\n } catch {\n // ignore a failed/invalid config fetch — fall through to whatever we have\n }\n }\n base = { ...base, ...parseJson(this.getAttribute(\"config\")), ...this.#config };\n return base;\n }\n\n #scheduleUpdate(): void {\n clearTimeout(this.#debounce);\n this.#debounce = setTimeout(() => {\n void this.#update();\n }, 50);\n }\n\n async #update(): Promise<void> {\n const handle = this.#handle;\n if (!handle) return;\n handle.set(await this.#buildConfig());\n }\n\n /** Presence = true; `\"false\"`/`\"0\"` = false; absent = undefined (shell default). */\n #boolAttr(name: string): boolean | undefined {\n if (!this.hasAttribute(name)) return undefined;\n const value = this.getAttribute(name);\n return value !== \"false\" && value !== \"0\";\n }\n}\n\nfunction parseJson(json: string | null): Partial<StudioConfig> {\n if (!json) return {};\n try {\n return JSON.parse(json) as Partial<StudioConfig>;\n } catch {\n return {};\n }\n}\n\n/** Define the element (idempotent, SSR/Node-import-safe). */\nexport function register(tag = \"wave-3d\"): void {\n if (typeof window === \"undefined\" || typeof customElements === \"undefined\") return;\n if (!customElements.get(tag)) customElements.define(tag, Wave3DElement);\n}\n\n// Self-register on import so a bare `import \"@wave3d/element\"` makes <wave-3d> work. Guarded so\n// importing under Node (SSR) is a no-op rather than a ReferenceError.\nregister();\n\nexport type {\n StudioConfig,\n WaveHandle,\n WaveRenderer,\n FallbackReason,\n SnapshotOptions,\n} from \"@wave3d/core\";\n"],"mappings":";;AASA,MAAM,WAAW;CAAC;CAAU;CAAO;CAAU;CAAU;CAAU;CAAQ;AAAO;AAKhF,MAAM,cACJ,OAAO,gBAAgB,cACnB,cACC,SAAS,oBAAoB,CAAC;;;;;;;AAQrC,IAAa,gBAAb,cAAmC,YAAY;CAC7C,WAAW,qBAA+B;EACxC,OAAO,CAAC,GAAG,QAAQ;CACrB;CAEA,UAA6B;CAC7B,UAAiC,CAAC;CAClC;;CAGA,IAAI,SAA4B;EAC9B,OAAO,KAAKA;CACd;;CAGA,IAAI,SAAgC;EAClC,OAAO,KAAKC;CACd;CACA,IAAI,OAAO,OAA8B;EACvC,KAAKA,UAAU,SAAS,CAAC;EACzB,KAAKC,gBAAgB;CACvB;CAEA,oBAA0B;EACxB,IAAI,CAAC,KAAK,MAAM,SAAS,KAAK,MAAM,UAAU;EAC9C,KAAUC,OAAO;CACnB;CAEA,uBAA6B;EAC3B,aAAa,KAAKC,SAAS;EAC3B,KAAKJ,SAAS,QAAQ;EACtB,KAAKA,UAAU;CACjB;CAEA,yBAAyB,MAAoB;EAC3C,IAAI,CAAC,KAAKA,SAAS;EACnB,IAAI,SAAS,UACX,IAAI,KAAKK,UAAU,QAAQ,GAAG,KAAKL,QAAQ,MAAM;OAC5C,KAAKA,QAAQ,KAAK;OAEvB,KAAKE,gBAAgB;CAEzB;CAEA,MAAMC,SAAwB;EAC5B,MAAM,SAAS,MAAM,KAAKG,aAAa;EACvC,IAAI,CAAC,KAAK,aAAa;EACvB,MAAM,UAAuB;GAC3B,QAAQ,KAAK,aAAa,QAAQ,KAAK,KAAA;GACvC,MAAM,KAAKD,UAAU,MAAM;GAC3B,OAAQ,KAAK,aAAa,OAAO,KAA8B,KAAA;GAC/D,QAAQ,KAAKA,UAAU,QAAQ;GAC/B,UAAU,aACR,KAAK,cAAc,IAAI,YAAY,gBAAgB,EAAE,QAAQ,SAAS,CAAC,CAAC;GAC1E,aAAa,WACX,KAAK,cAAc,IAAI,YAAY,mBAAmB,EAAE,QAAQ,OAAO,CAAC,CAAC;EAC7E;EACA,KAAKL,UAAU,WAAW,MAAM,QAAQ,OAAO;CACjD;;CAGA,MAAMM,eAA+C;EACnD,IAAI,OAA8B,CAAC;EACnC,MAAM,aAAa,KAAK,aAAa,QAAQ;EAC7C,IAAI,YAAY;GACd,MAAM,EAAE,YAAY,MAAM,OAAO;GACjC,OAAO,QAAQ,WAAW,GAAG,KAAK,CAAC;EACrC;EACA,MAAM,MAAM,KAAK,aAAa,KAAK;EACnC,IAAI,KACF,IAAI;GACF,OAAO;IAAE,GAAG;IAAM,GAAI,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,MAAM,EAAE,KAAK,CAAC;GAAG;EAChE,QAAQ,CAER;EAEF,OAAO;GAAE,GAAG;GAAM,GAAG,UAAU,KAAK,aAAa,QAAQ,CAAC;GAAG,GAAG,KAAKL;EAAQ;EAC7E,OAAO;CACT;CAEA,kBAAwB;EACtB,aAAa,KAAKG,SAAS;EAC3B,KAAKA,YAAY,iBAAiB;GAChC,KAAUG,QAAQ;EACpB,GAAG,EAAE;CACP;CAEA,MAAMA,UAAyB;EAC7B,MAAM,SAAS,KAAKP;EACpB,IAAI,CAAC,QAAQ;EACb,OAAO,IAAI,MAAM,KAAKM,aAAa,CAAC;CACtC;;CAGA,UAAU,MAAmC;EAC3C,IAAI,CAAC,KAAK,aAAa,IAAI,GAAG,OAAO,KAAA;EACrC,MAAM,QAAQ,KAAK,aAAa,IAAI;EACpC,OAAO,UAAU,WAAW,UAAU;CACxC;AACF;AAEA,SAAS,UAAU,MAA4C;CAC7D,IAAI,CAAC,MAAM,OAAO,CAAC;CACnB,IAAI;EACF,OAAO,KAAK,MAAM,IAAI;CACxB,QAAQ;EACN,OAAO,CAAC;CACV;AACF;;AAGA,SAAgB,SAAS,MAAM,WAAiB;CAC9C,IAAI,OAAO,WAAW,eAAe,OAAO,mBAAmB,aAAa;CAC5E,IAAI,CAAC,eAAe,IAAI,GAAG,GAAG,eAAe,OAAO,KAAK,aAAa;AACxE;AAIA,SAAS"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wave3d/element",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "<wave-3d> custom element for @wave3d — a framework-agnostic drop-in animated gradient wave (the Vue/Svelte/plain-HTML story)",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"background",
|
|
@@ -39,11 +39,17 @@
|
|
|
39
39
|
"publishConfig": {
|
|
40
40
|
"access": "public"
|
|
41
41
|
},
|
|
42
|
-
"
|
|
43
|
-
"@wave3d/core": "0.
|
|
42
|
+
"dependencies": {
|
|
43
|
+
"@wave3d/core": "^0.2.0"
|
|
44
44
|
},
|
|
45
45
|
"peerDependencies": {
|
|
46
|
-
"@
|
|
46
|
+
"@types/three": ">=0.180",
|
|
47
|
+
"three": ">=0.180 <1"
|
|
48
|
+
},
|
|
49
|
+
"peerDependenciesMeta": {
|
|
50
|
+
"@types/three": {
|
|
51
|
+
"optional": true
|
|
52
|
+
}
|
|
47
53
|
},
|
|
48
54
|
"scripts": {
|
|
49
55
|
"typecheck": "tsc --noEmit",
|