3d-spinner 0.9.2 → 0.9.4

package/README.md

@@ -2,6 +2,7 @@
 
 [![tests](https://img.shields.io/github/actions/workflow/status/runelaang/3d-spinner/ci.yml?label=tests&logo=github)](https://github.com/runelaang/3d-spinner/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/3d-spinner?logo=npm)](https://www.npmjs.com/package/3d-spinner)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/3d-spinner)](https://bundlephobia.com/package/3d-spinner)
 [![license](https://img.shields.io/github/license/runelaang/3d-spinner)](LICENSE)
 
 A zero-dependency 3D spinner, loader, and progress indicator for the browser. It renders to a
@@ -9,6 +10,16 @@ canvas and ships primarily as ES modules split across separate import paths, so
 only the animation, motion path, and rendering backend they actually use - nothing else is pulled
 in. CommonJS and a browser-global build are also published; see [Module formats](#module-formats).
 
+## Screenshots
+
+| `starSwarm` with custom HTML | `pulsingStarfield` | `chargedOrb` at 74% |
+| --- | --- | --- |
+| ![starSwarm prefab with a custom HTML label](screenshots/shot1.png) | ![pulsingStarfield prefab with a Preparing launch label](screenshots/shot2.png) | ![chargedOrb progress prefab at 74 percent](screenshots/shot3.png) |
+
+| `ghostTrain` progress prefab | `ParticlesAnimation` with glow texture |
+| --- | --- |
+| ![ghostTrain progress prefab on a tilted track](screenshots/shot4.png) | ![particle loader with a Just a sec label](screenshots/shot5.png) |
+
 ## Install
 
 ```sh
@@ -64,7 +75,7 @@ new SpinAnimation({ shape: tetrahedron(), color: "#3b82f6" });
 ```
 
 Shapes exported from `3d-spinner/engines/little-3d-engine` include `cube`, `tetrahedron`,
-`octahedron`, `pyramid`, and several spheres (`uvSphere`, `icosphere`, `octaSphere`,
+`octahedron`, `pyramid`, `quad`, and several spheres (`uvSphere`, `icosphere`, `octaSphere`,
 `cubeSphere`).
 
 ## How it fits together
@@ -84,8 +95,8 @@ others:
 - **Motion controller** (for `ObjectMotionAnimation`) is a small, separate object that decides
   *how* a thing moves - a circle, square, figure-8, or wander. Swap the controller to change the
   path without changing the animation.
-- **Transition** (for `ObjectMotionAnimation`) is the optional intro/outro effect - grow or shrink
-  in place, or fly in and out along the path.
+- **Transition** (for `ObjectMotionAnimation`) is the intro/outro effect - by default the object
+  flies in and out along the path; grow or shrink in place is available as an option.
 - **The 3D engine** is the renderer underneath: a small, dependency-free engine that draws shapes
   and meshes to a canvas, with swappable Canvas 2D, WebGL, and WebGPU backends.
 
@@ -97,12 +108,63 @@ Each animation is imported from its own subpath, so you only pull in the one you
 | --- | --- | --- |
 | `3d-spinner/animations/spin` | `SpinAnimation` | A spinning 3D shape, a cube by default. |
 | `3d-spinner/animations/object-motion` | `ObjectMotionAnimation` | A mesh that follows a motion path, with an intro/outro you choose. |
+| `3d-spinner/animations/particles` | `ParticlesAnimation` | A stream of camera-facing billboard particles: a burst, a fountain, snow, confetti. |
+
+## Prefabs
+
+Prefabs provide complete indeterminate spinner options, including layered animation. They need
+no configuration and accept an optional override object.
+
+```js
+import { createSpinner } from "3d-spinner";
+import { planeStarTrail } from "3d-spinner/prefabs";
+
+const spinner = createSpinner(document.getElementById("app"), planeStarTrail());
+```
+
+Common overrides include `backend`, `label`, `fadeLabel`, and `periodMs`. Labels fade with the
+intro and outro by default; set `fadeLabel: false` to keep one fully visible. Motion prefabs also accept
+`object` and `particles` option objects. A label can be text or any `HTMLElement`.
+
+```js
+const message = document.createElement("div");
+message.innerHTML = "<strong>Preparing preview</strong>";
+
+createSpinner(document.getElementById("app"), planeStarTrail({
+  label: message,
+  particles: { rate: 48 },
+}));
+```
 
 `ObjectMotionAnimation` takes a motion controller from `3d-spinner/motion` (`circleMotion`,
 `squareMotion`, `figureEightMotion`, `wanderMotion`) and optional entrance/exit transitions from
 `3d-spinner/motion/transitions` (`grow`, `shrink`, `enterFromObjectDirection`,
 `leaveInObjectDirection`) - for example a figure-8 path with a fly-in and fly-out.
 
+`ParticlesAnimation` emits fading billboard quads from the center. The emission options shape the
+effect: `direction` and `spread` aim it, `gravity` bends it, and `rate`, `lifeMs`, `speed`,
+`size`, `spin`, and `colors` style it. The stream is deterministic for a given `seed`. Emission
+starts on enter and stops on exit; the live particles fading out is the outro.
+
+A `texture` option (an image URL or a drawable element such as a canvas) puts an image on every
+particle, tinted by the particle color, with the image's alpha shaping the particle. Textures
+render through a backend-specific textured renderer fetched on demand for Canvas 2D, WebGL, or
+WebGPU. Canvas 2D texture mapping is limited to planar four-vertex billboards.
+
+```js
+import { createSpinner } from "3d-spinner";
+import { ParticlesAnimation } from "3d-spinner/animations/particles";
+
+const spinner = createSpinner(document.getElementById("app"), {
+  type: "indeterminate",
+  animation: new ParticlesAnimation({
+    direction: { x: 0, y: 1, z: 0 },
+    gravity: { x: 0, y: -1.6, z: 0 },
+    speed: 1.5,
+  }),
+});
+```
+
 ## API
 
 ### `createSpinner(target, options)`
@@ -210,7 +272,7 @@ bundles the whole public API onto one `window.Spinner3D` object:
 npm install
 npm run build   # compile src/ to dist/ (ESM + type declarations, CJS, and a browser-global build)
 npm test        # build, then run the unit tests
-npm run dev     # serve this folder; open /examples/index.html
+npm run dev     # serve this folder; open /examples/ or /examples/prefabs.html
 ```
 
 ## License

package/dist/animation-label.d.ts

@@ -0,0 +1,8 @@
+import type { AnimationLabel } from "./animation.js";
+export interface MountedAnimationLabel {
+    readonly container: HTMLDivElement;
+    setText(value: string): void;
+    setOpacity(value: number): void;
+}
+export declare function animationLabelOpacity(now: number, enterAt: number, introDurationMs: number, exitAt: number, outroDurationMs: number): number;
+export declare function mountAnimationLabel(target: HTMLElement, content: AnimationLabel | undefined): MountedAnimationLabel;

package/dist/animation-label.js

@@ -0,0 +1,47 @@
+const LABEL_STYLE = [
+    "position:absolute",
+    "inset:0",
+    "display:flex",
+    "align-items:center",
+    "justify-content:center",
+    "pointer-events:none",
+    "font:700 1.6rem/1 system-ui,sans-serif",
+    "letter-spacing:0.02em",
+    "color:rgba(255,255,255,0.9)",
+    "text-shadow:0 1px 10px rgba(0,0,0,0.6)",
+    "z-index:1",
+].join(";");
+export function animationLabelOpacity(now, enterAt, introDurationMs, exitAt, outroDurationMs) {
+    if (enterAt === Infinity)
+        return 0;
+    const intro = introDurationMs <= 0 ? 1 : Math.max(0, Math.min(1, (now - enterAt) / introDurationMs));
+    const outro = exitAt === Infinity
+        ? 1
+        : outroDurationMs <= 0
+            ? 0
+            : Math.max(0, Math.min(1, 1 - (now - exitAt) / outroDurationMs));
+    return Math.min(intro, outro);
+}
+export function mountAnimationLabel(target, content) {
+    var _a;
+    const container = document.createElement("div");
+    container.style.cssText = LABEL_STYLE;
+    container.setAttribute("role", "status");
+    if (typeof content === "string")
+        container.textContent = content;
+    else if (content) {
+        (_a = content.style).pointerEvents || (_a.pointerEvents = "auto");
+        container.appendChild(content);
+    }
+    target.appendChild(container);
+    return {
+        container,
+        setText(value) {
+            if (typeof content !== "object")
+                container.textContent = value;
+        },
+        setOpacity(value) {
+            container.style.opacity = String(value);
+        },
+    };
+}

package/dist/animation.d.ts

@@ -10,6 +10,8 @@ export interface AnimationFrame {
     /** True when the spinner is indeterminate (progress is a synthetic loop). */
     readonly indeterminate: boolean;
 }
+/** Text or custom HTML displayed over an animation. */
+export type AnimationLabel = string | HTMLElement;
 /**
  * A reusable visual: a cube spin, a flying plane, a progress bar. The animation
  * owns its intro/loop/outro visuals but does not decide *when* to play them -

package/dist/animations/charged-orb.d.ts

@@ -0,0 +1,55 @@
+import type { AnimationFrame, SpinnerAnimation } from "../animation.js";
+import type { MotionController } from "../motion/controller.js";
+import { type Backend } from "../engines/little-3d-engine/little-3d-engine.js";
+export interface ChargedOrbOptions {
+    /** Milliseconds for one satellite revolution around the center orb. Default `6000`. */
+    orbitPeriodMs?: number;
+    /** Rendering backend. Default `"canvas2d"`. */
+    backend?: Backend;
+}
+/**
+ * A progress story around a charging orb: the translucent-looking center orb
+ * pops straight to full size, then every 10% of progress a mini orb pops out
+ * of it and joins an evenly spread ring of satellites (the tenth at 100%). At
+ * completion the satellites take one extra lap around the center, dive back
+ * into the big orb one after another, and the orb pops away. Satellite motion
+ * is time-blended per orb, so progress jumps in either direction stay smooth.
+ * {@link satelliteEmitter} exposes the satellites to a particle layer, one
+ * stream per orb.
+ */
+export declare class ChargedOrbAnimation implements SpinnerAnimation {
+    private engine?;
+    private center?;
+    private readonly minis;
+    private readonly blends;
+    private readonly offsets;
+    private readonly orbitPeriodMs;
+    private readonly backend?;
+    private enterAt;
+    private exitAt;
+    private allOutAt;
+    private lastNow;
+    private finished;
+    constructor(options?: ChargedOrbOptions);
+    mount(target: HTMLElement): void;
+    enter(now: number): void;
+    exit(now: number): void;
+    isFinished(): boolean;
+    /** Milliseconds after {@link exit} during which the satellites are still flying. */
+    get outroEmitMs(): number;
+    /**
+     * A {@link MotionController} that cycles across the live satellites, one
+     * spawn slot per orb, so a particle layer emits one stream per satellite.
+     * `spawnGapMs` must match the particle layer's emission gap (`1000 / rate`).
+     */
+    satelliteEmitter(spawnGapMs: number): MotionController;
+    render(now: number, frame: AnimationFrame): void;
+    destroy(): void;
+    private updateBlends;
+    private updateSpread;
+    private slotAngle;
+    private baseAngleAt;
+    private reenterStart;
+    private miniSample;
+    private centerScale;
+}

package/dist/animations/charged-orb.js

@@ -0,0 +1,229 @@
+import { Little3dEngine, icosphere, } from "../engines/little-3d-engine/little-3d-engine.js";
+import { easeInCubic, easeInOutCubic, easeInQuad, easeOutBack, easeOutCubic, easeOutQuad, } from "../engines/little-tween-engine/core/tweens.js";
+const MINIS = 10;
+const CAMERA_Z = 3;
+const CENTER_SCALE = 0.76;
+const MINI_SCALE = 0.36;
+const MINI_TRANSPARENCY = { mode: "two-sided", frontOpacity: 0.68, backOpacity: 0.87 };
+const ORBIT_RADIUS = 1.2;
+const TILT = 0.8;
+const TWO_PI = Math.PI * 2;
+const CENTER_POP_MS = 500;
+const LAUNCH_MS = 550;
+const EXIT_HURRY = 2.5;
+const SPREAD_TAU_MS = 250;
+const EXTRA_PAUSE_MS = 250;
+const EXTRA_SPIN_MS = 1300;
+const REENTER_MS = 600;
+const REENTER_STAGGER_MS = 45;
+const CENTER_POP_OUT_AT = REENTER_MS + (MINIS - 1) * REENTER_STAGGER_MS + 150;
+const CENTER_POP_OUT_MS = 420;
+const PARKED = { x: 0, y: 0, z: 50 };
+const CENTER_COLORS = ["#67e8f9", "#22d3ee", "#0ea5e9", "#38bdf8", "#7dd3fc"];
+const MINI_COLORS = [
+    ["#e0f2fe", "#bae6fd", "#7dd3fc"],
+    ["#c7d2fe", "#a5b4fc", "#818cf8"],
+    ["#a5f3fc", "#67e8f9", "#22d3ee"],
+];
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+/**
+ * A progress story around a charging orb: the translucent-looking center orb
+ * pops straight to full size, then every 10% of progress a mini orb pops out
+ * of it and joins an evenly spread ring of satellites (the tenth at 100%). At
+ * completion the satellites take one extra lap around the center, dive back
+ * into the big orb one after another, and the orb pops away. Satellite motion
+ * is time-blended per orb, so progress jumps in either direction stay smooth.
+ * {@link satelliteEmitter} exposes the satellites to a particle layer, one
+ * stream per orb.
+ */
+export class ChargedOrbAnimation {
+    constructor(options = {}) {
+        this.minis = [];
+        this.blends = new Array(MINIS).fill(0);
+        this.offsets = new Array(MINIS).fill(0);
+        this.enterAt = Infinity;
+        this.exitAt = Infinity;
+        this.allOutAt = Infinity;
+        this.lastNow = 0;
+        this.finished = false;
+        this.orbitPeriodMs = options.orbitPeriodMs ?? 6000;
+        this.backend = options.backend;
+    }
+    mount(target) {
+        if (!target.style.position)
+            target.style.position = "relative";
+        const engine = new Little3dEngine({
+            backend: this.backend,
+            camera: { position: { x: 0, y: 0, z: CAMERA_Z } },
+        });
+        this.center = engine.add(icosphere(1, 2, CENTER_COLORS), { scale: 0 });
+        for (let i = 0; i < MINIS; i++) {
+            const mesh = icosphere(1, 1, MINI_COLORS[i % MINI_COLORS.length]);
+            this.minis.push(engine.add(mesh, { scale: 0, transparency: { ...MINI_TRANSPARENCY } }));
+        }
+        this.engine = engine;
+        engine.mount(target).catch((error) => {
+            target.textContent = error instanceof Error ? error.message : String(error);
+        });
+    }
+    enter(now) {
+        if (this.enterAt === Infinity)
+            this.enterAt = now;
+    }
+    exit(now) {
+        if (this.exitAt === Infinity)
+            this.exitAt = now;
+    }
+    isFinished() {
+        return this.finished;
+    }
+    /** Milliseconds after {@link exit} during which the satellites are still flying. */
+    get outroEmitMs() {
+        return EXTRA_PAUSE_MS + EXTRA_SPIN_MS + CENTER_POP_OUT_AT;
+    }
+    /**
+     * A {@link MotionController} that cycles across the live satellites, one
+     * spawn slot per orb, so a particle layer emits one stream per satellite.
+     * `spawnGapMs` must match the particle layer's emission gap (`1000 / rate`).
+     */
+    satelliteEmitter(spawnGapMs) {
+        return {
+            positionAt: (t) => {
+                const live = [];
+                for (let i = 0; i < MINIS; i++) {
+                    const sample = this.miniSample(i, t);
+                    if (sample)
+                        live.push(sample.position);
+                }
+                if (live.length === 0)
+                    return PARKED;
+                const slot = Math.abs(Math.floor(t / spawnGapMs)) % live.length;
+                return live[slot];
+            },
+        };
+    }
+    render(now, frame) {
+        if (!this.engine || !this.center)
+            return;
+        if (this.enterAt === Infinity) {
+            this.center.transform.scale = 0;
+            for (const mini of this.minis)
+                mini.transform.scale = 0;
+            this.engine.render();
+            return;
+        }
+        const dt = this.lastNow === 0 ? 16 : Math.min(50, now - this.lastNow);
+        this.lastNow = now;
+        this.updateBlends(dt, frame.progress, now);
+        this.updateSpread(dt);
+        const t = now - this.enterAt;
+        this.center.transform.scale = this.centerScale(now, t);
+        this.center.transform.rotation.x = t * 0.0002;
+        this.center.transform.rotation.y = t * 0.0005;
+        for (let i = 0; i < MINIS; i++) {
+            const transform = this.minis[i].transform;
+            const sample = this.miniSample(i, now);
+            if (!sample) {
+                transform.scale = 0;
+                continue;
+            }
+            transform.position.x = sample.position.x;
+            transform.position.y = sample.position.y;
+            transform.position.z = sample.position.z;
+            transform.scale = sample.scale;
+            transform.rotation.y = t * 0.0012;
+        }
+        this.engine.render();
+    }
+    destroy() {
+        this.engine?.destroy();
+        this.engine = undefined;
+        this.center = undefined;
+        this.minis.length = 0;
+    }
+    updateBlends(dt, progress, now) {
+        const exiting = this.exitAt !== Infinity;
+        const want = exiting ? MINIS : Math.min(MINIS, Math.floor(progress * MINIS + 1e-9));
+        const rate = (dt / LAUNCH_MS) * (exiting ? EXIT_HURRY : 1);
+        for (let i = 0; i < MINIS; i++) {
+            const target = i < want ? 1 : 0;
+            const blend = this.blends[i];
+            if (target > blend && (i === 0 || this.blends[i - 1] >= 0.6)) {
+                this.blends[i] = Math.min(1, blend + rate);
+                if (blend === 0)
+                    this.offsets[i] = this.slotAngle(i);
+            }
+            else if (target < blend && (i === MINIS - 1 || this.blends[i + 1] <= 0.4)) {
+                this.blends[i] = Math.max(0, blend - rate);
+            }
+        }
+        if (exiting && this.allOutAt === Infinity && this.blends.every((blend) => blend >= 1)) {
+            this.allOutAt = now;
+        }
+    }
+    updateSpread(dt) {
+        const ease = 1 - Math.exp(-dt / SPREAD_TAU_MS);
+        for (let i = 0; i < MINIS; i++) {
+            if (this.blends[i] <= 0)
+                continue;
+            this.offsets[i] += (this.slotAngle(i) - this.offsets[i]) * ease;
+        }
+    }
+    slotAngle(index) {
+        const launched = Math.max(1, this.blends.filter((blend) => blend > 0).length);
+        return (TWO_PI * Math.min(index, launched - 1)) / launched;
+    }
+    baseAngleAt(t) {
+        let angle = (-TWO_PI * (t - this.enterAt)) / this.orbitPeriodMs;
+        if (this.allOutAt !== Infinity) {
+            const u = clamp01((t - this.allOutAt - EXTRA_PAUSE_MS) / EXTRA_SPIN_MS);
+            angle -= TWO_PI * easeInOutCubic(u);
+        }
+        return angle;
+    }
+    reenterStart() {
+        return this.allOutAt + EXTRA_PAUSE_MS + EXTRA_SPIN_MS;
+    }
+    miniSample(index, t) {
+        const blend = this.blends[index];
+        if (blend <= 0)
+            return undefined;
+        let radial = easeOutCubic(blend);
+        let scale = MINI_SCALE * easeOutBack(blend);
+        if (this.allOutAt !== Infinity) {
+            const start = this.reenterStart() + index * REENTER_STAGGER_MS;
+            const pull = easeInCubic(clamp01((t - start) / REENTER_MS));
+            if (pull >= 1)
+                return undefined;
+            radial *= 1 - pull;
+            scale *= 1 - pull;
+        }
+        const angle = this.baseAngleAt(t) + this.offsets[index];
+        const flat = Math.sin(angle) * ORBIT_RADIUS * radial;
+        return {
+            position: {
+                x: Math.cos(angle) * ORBIT_RADIUS * radial,
+                y: flat * Math.cos(TILT),
+                z: flat * Math.sin(TILT),
+            },
+            scale,
+        };
+    }
+    centerScale(now, t) {
+        if (this.allOutAt !== Infinity) {
+            const w = clamp01((now - this.reenterStart() - CENTER_POP_OUT_AT) / CENTER_POP_OUT_MS);
+            if (w >= 1) {
+                this.finished = true;
+                return 0;
+            }
+            if (w > 0) {
+                return CENTER_SCALE * (w < 0.35
+                    ? 1 + 0.18 * easeOutQuad(w / 0.35)
+                    : 1.18 * (1 - easeInQuad((w - 0.35) / 0.65)));
+            }
+        }
+        return CENTER_SCALE * easeOutBack(clamp01(t / CENTER_POP_MS));
+    }
+}

package/dist/animations/ghost-train.d.ts

@@ -0,0 +1,72 @@
+import type { AnimationFrame, AnimationLabel, SpinnerAnimation } from "../animation.js";
+import { type Backend } from "../engines/little-3d-engine/little-3d-engine.js";
+import type { MotionController } from "../motion/controller.js";
+export interface GhostTrainOptions {
+    /** How the convoy moves. Default a tilted square track. */
+    motion?: MotionController;
+    /** Uniform car size in scene units. Default `0.3`. */
+    size?: number;
+    /** Rendering backend. Default `"canvas2d"`. */
+    backend?: Backend;
+    /** Overlay label; progress mode shows a percentage. */
+    label?: AnimationLabel;
+    /** Fade the label with the story's beginning and end. Default `true`. */
+    fadeLabel?: boolean;
+}
+/**
+ * A progress story: a translucent train of ice cubes runs laps around a tilted
+ * square track, cars turning smoothly through the corners as if seen from above.
+ * Every 2% of progress attaches one more car, popping it into existence at the
+ * tail. At 100% the lead car keeps going in its current direction of travel and
+ * every following car funnels through that same exit point along the exact same
+ * path, the convoy accelerating clear of the view within four seconds. Car
+ * count follows the
+ * reported progress, so scrubbing in either direction stays smooth.
+ * {@link trailEmitter} exposes the lead car to a particle layer for the star trail.
+ */
+export declare class GhostTrainAnimation implements SpinnerAnimation {
+    private engine?;
+    private label?;
+    private observer?;
+    private readonly cars;
+    private readonly appear;
+    private readonly headings;
+    private readonly motion;
+    private readonly size;
+    private readonly backend?;
+    private readonly labelContent?;
+    private readonly fadeLabel;
+    private aspect;
+    private enterAt;
+    private outroAt;
+    private carsAtOutro;
+    private exitPathTime;
+    private exitPoint;
+    private exitDir;
+    private exitSpeed;
+    private lastNow;
+    private finished;
+    constructor(options?: GhostTrainOptions);
+    mount(target: HTMLElement): void;
+    enter(now: number): void;
+    exit(now: number): void;
+    isFinished(): boolean;
+    /** Milliseconds the lead car keeps moving into the outro; feed a trail layer's `outroMs`. */
+    get outroDurationMs(): number;
+    /**
+     * A {@link MotionController} following the lead car's actual position, through
+     * laps and the accelerating escape. Feed it to a particle layer's `emitter`
+     * so the star trail stays behind the train.
+     */
+    trailEmitter(): MotionController;
+    render(now: number, frame: AnimationFrame): void;
+    destroy(): void;
+    /** Extra path-time every car has accelerated forward by, `now` ms into the outro. */
+    private warp;
+    /**
+     * The single trajectory every car rides, sampled at path-time `p`: the track
+     * up to the exit switch point, then a straight escape outward. Because the
+     * switch point and direction are shared, all cars follow the exact same path.
+     */
+    private pathPosition;
+}