@wave3d/element 0.1.0 → 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 +26 -12
- package/dist/index.d.ts +2 -2
- package/dist/index.js.map +1 -1
- package/package.json +11 -5
package/README.md
CHANGED
|
@@ -1,20 +1,20 @@
|
|
|
1
1
|
# @wave3d/element
|
|
2
2
|
|
|
3
|
-
The `<wave-3d>` custom element
|
|
3
|
+
The `<wave-3d>` custom element: a drop-in animated **3D gradient wave** for Vue, Svelte, or plain HTML. Design one in [Wave Studio](https://wave-studio.pages.dev), export the snippet for your framework, paste it in.
|
|
4
4
|
|
|
5
|
-
Poster-first
|
|
5
|
+
Poster-first: it shows a poster immediately, then upgrades to live WebGL only when the browser can run it. It falls back to the poster on no-WebGL, Save-Data, reduced motion, or a lost context, with `three.js` code-split out of the initial load.
|
|
6
6
|
|
|
7
|
-
## Install
|
|
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
|
|
|
17
|
-
Importing the package registers `<wave-3d>`
|
|
17
|
+
Importing the package registers `<wave-3d>` for you:
|
|
18
18
|
|
|
19
19
|
```html
|
|
20
20
|
<script type="module">
|
|
@@ -31,17 +31,31 @@ Importing the package registers `<wave-3d>` automatically:
|
|
|
31
31
|
| `preset` | a built-in preset name (lazy-loads the presets chunk) |
|
|
32
32
|
| `config` | an inline JSON config |
|
|
33
33
|
| `src` | URL to a config JSON to fetch |
|
|
34
|
-
| `poster` | poster image shown before
|
|
35
|
-
| `paused` | pause
|
|
34
|
+
| `poster` | poster image shown before or instead of WebGL |
|
|
35
|
+
| `paused` | pause or resume the animation |
|
|
36
36
|
| `lazy` | defer the upgrade until visible |
|
|
37
37
|
| `webgl` | `auto` \| `force` \| `off` |
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
There's also a `config` **property** (merged last, over the attributes) and a read-only `handle` getter. Precedence: **default → `preset` → `src` → `config` attribute → `config` property**.
|
|
40
40
|
|
|
41
41
|
## Events
|
|
42
42
|
|
|
43
|
-
- `wave3d-ready
|
|
44
|
-
- `wave3d-fallback
|
|
43
|
+
- `wave3d-ready`: `detail` is the live `WaveRenderer`.
|
|
44
|
+
- `wave3d-fallback`: `detail` is the fallback reason.
|
|
45
|
+
|
|
46
|
+
## Capture a poster
|
|
47
|
+
|
|
48
|
+
Grab the live frame 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 or 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`).
|
|
45
59
|
|
|
46
60
|
## Custom tag name
|
|
47
61
|
|
|
@@ -52,7 +66,7 @@ register("my-wave"); // instead of the default <wave-3d>
|
|
|
52
66
|
|
|
53
67
|
## Credits
|
|
54
68
|
|
|
55
|
-
|
|
69
|
+
Built by [Amir Abushanab](https://github.com/Amir-Abushanab).
|
|
56
70
|
|
|
57
71
|
## License
|
|
58
72
|
|
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":"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"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wave3d/element",
|
|
3
|
-
"version": "0.1
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"description": "Drop-in animated 3D gradient wave for Vue, Svelte, or plain HTML: the <wave-3d> custom element",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"background",
|
|
7
7
|
"custom-elements",
|
|
@@ -39,11 +39,17 @@
|
|
|
39
39
|
"publishConfig": {
|
|
40
40
|
"access": "public"
|
|
41
41
|
},
|
|
42
|
-
"
|
|
43
|
-
"@wave3d/core": "0.1
|
|
42
|
+
"dependencies": {
|
|
43
|
+
"@wave3d/core": "^0.2.1"
|
|
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",
|