3d-spinner 0.9.0

package/dist/motion/transitions.js

@@ -0,0 +1,60 @@
+const DEFAULT_DISTANCE = 3.5;
+function add(a, b) {
+    return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+}
+function scaleVector(v, factor) {
+    return { x: v.x * factor, y: v.y * factor, z: v.z * factor };
+}
+function vectorLength(v) {
+    return Math.hypot(v.x, v.y, v.z);
+}
+function normalizeVector(v) {
+    const length = vectorLength(v);
+    if (length < 1e-6)
+        return { x: 1, y: 0, z: 0 };
+    return scaleVector(v, 1 / length);
+}
+function resolveDirection(input, fallback) {
+    return normalizeVector(fallback ?? input.direction ?? input.velocity ?? { x: 1, y: 0, z: 0 });
+}
+function easeOutBack(delta) {
+    const c = 1.70158;
+    const u = delta - 1;
+    return 1 + (c + 1) * u * u * u + c * u * u;
+}
+/**
+ * Constant velocity the fly-in/out travels at. When the path supplies a real
+ * velocity at the handoff (and the caller has not forced a custom `direction`),
+ * we match it exactly so the transition joins the motion with no speed jump.
+ * Only when no useful velocity is available do we fall back to covering
+ * `distance` over the duration along the resolved direction.
+ */
+function joinVelocity(input, options, durationMs) {
+    const inputSpeed = input.velocity ? vectorLength(input.velocity) : 0;
+    if (input.velocity && inputSpeed > 1e-6 && !options.direction) {
+        return input.velocity;
+    }
+    const distance = options.distance ?? DEFAULT_DISTANCE;
+    return scaleVector(resolveDirection(input, options.direction), distance / durationMs);
+}
+export function enterFromObjectDirection(options = {}) {
+    return (input) => {
+        const durationMs = Math.max(1, input.durationMs);
+        const velocity = joinVelocity(input, options, durationMs);
+        const remaining = durationMs - input.elapsedMs;
+        return { position: add(input.position, scaleVector(velocity, -remaining)) };
+    };
+}
+export function leaveInObjectDirection(options = {}) {
+    return (input) => {
+        const durationMs = Math.max(1, input.durationMs);
+        const velocity = joinVelocity(input, options, durationMs);
+        return { position: add(input.position, scaleVector(velocity, input.elapsedMs)) };
+    };
+}
+export function grow() {
+    return (input) => ({ size: (input.size ?? 1) * easeOutBack(input.delta) });
+}
+export function shrink() {
+    return (input) => ({ size: (input.size ?? 1) * (1 - input.delta * input.delta) });
+}

package/dist/motion/wander.d.ts

@@ -0,0 +1,22 @@
+import type { MotionController } from "./controller.js";
+/** Half-extents of the box the wander stays within, in scene units. */
+export interface WanderBounds {
+    x?: number;
+    y?: number;
+    z?: number;
+}
+/** Options for {@link wanderMotion}. */
+export interface WanderMotionOptions {
+    /** Half-extents of the box the object stays within. Default `{ x: 1.4, y: 1.0, z: 0.6 }`. */
+    bounds?: WanderBounds;
+    /** Base drift period in ms; larger is slower. Default `9000`. */
+    periodMs?: number;
+    /** Seed for the random direction pattern. Omit for a different wander each time. */
+    seed?: number;
+}
+/**
+ * Drifts smoothly in random directions, changing heading organically, while
+ * staying inside the frame. The path is bounded by construction (a weighted sum
+ * of sines), so it never wanders off-screen. Pass a `seed` for a repeatable path.
+ */
+export declare function wanderMotion(options?: WanderMotionOptions): MotionController;

package/dist/motion/wander.js

@@ -0,0 +1,50 @@
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Builds a per-axis position function as a weighted sum of sines with
+ * incommensurate frequencies. The output never exceeds `bound`, so the object
+ * is guaranteed to stay inside the frame while drifting and turning smoothly.
+ */
+function axisDrift(rnd, omega, bound) {
+    const components = [0, 1, 2].map(() => ({
+        freq: 0.5 + rnd() * 1.4,
+        phase: rnd() * Math.PI * 2,
+        weight: 0.5 + rnd(),
+    }));
+    const total = components.reduce((sum, c) => sum + c.weight, 0);
+    return (t) => {
+        let value = 0;
+        for (const c of components)
+            value += c.weight * Math.sin(omega * c.freq * t + c.phase);
+        return (value / total) * bound;
+    };
+}
+/**
+ * Drifts smoothly in random directions, changing heading organically, while
+ * staying inside the frame. The path is bounded by construction (a weighted sum
+ * of sines), so it never wanders off-screen. Pass a `seed` for a repeatable path.
+ */
+export function wanderMotion(options = {}) {
+    const boundX = options.bounds?.x ?? 1.4;
+    const boundY = options.bounds?.y ?? 1.0;
+    const boundZ = options.bounds?.z ?? 0.6;
+    const periodMs = options.periodMs ?? 9000;
+    const seed = options.seed ?? (Math.random() * 1e9) | 0;
+    const rnd = mulberry32(seed);
+    const omega = (2 * Math.PI) / periodMs;
+    const driftX = axisDrift(rnd, omega, boundX);
+    const driftY = axisDrift(rnd, omega, boundY);
+    const driftZ = axisDrift(rnd, omega, boundZ);
+    return {
+        positionAt(t) {
+            return { x: driftX(t), y: driftY(t), z: driftZ(t) };
+        },
+    };
+}

package/dist/progress-animation.d.ts

@@ -0,0 +1,55 @@
+export interface ProgressAnimationOptions {
+    /** Pop-in / pop-out duration in milliseconds. Default `500`. */
+    popDurationMs?: number;
+    /** Scale overshoot fraction during pop. Default `0.2` (20%). */
+    overextend?: number;
+    /** Share of pop duration used for the fast overshoot snap. Default `0.2`. */
+    startSnapRatio?: number;
+    /** Label while loading; `false` hides it. Default `"loading"`. */
+    loadingText?: string | false;
+    /** Label when complete. Default `"done"`. */
+    doneText?: string;
+    /** Fade-out duration for the done label in milliseconds. Default `2000`. */
+    doneFadeDurationMs?: number;
+    /** Remove all overlay content after the done fade finishes. Default `false`. */
+    removeOnComplete?: boolean;
+}
+export interface ProgressAnimationVisual {
+    /** Uniform scale multiplier (0 = invisible). */
+    scale: number;
+    /** Overlay label, or `null` when hidden. */
+    text: string | null;
+    /** Label opacity in the range 0..1. */
+    textOpacity: number;
+    /** When true, hide the entire animation (mesh and text). */
+    hidden: boolean;
+}
+/**
+ * Lifecycle visual for a progress spinner: an intro pop ({@link enter}), an
+ * active phase whose scale tracks progress, and an outro pop ({@link exit})
+ * that fades to a done label. The owner triggers `enter`/`exit`; this class
+ * does not infer them from the progress value.
+ *
+ * Lifecycle stages:
+ * - `idle`: waiting for {@link enter}; nothing is visible.
+ * - `startPop`: the object pops in and settles at the current progress scale.
+ * - `active`: the object scale tracks progress.
+ * - `endPop`: the object pops out after {@link exit}.
+ * - `done`: the object is gone while the done label fades.
+ * - `finished`: all visuals are complete and {@link isFinished} returns true.
+ */
+export declare class ProgressAnimation {
+    private readonly options;
+    private phase;
+    private phaseStart;
+    private activeProgress;
+    private popTarget;
+    private doneFadeStart;
+    constructor(options?: ProgressAnimationOptions);
+    /** Begin the intro pop. Ignored unless idle. */
+    enter(now: number): void;
+    /** Begin the outro pop. Ignored unless mid-intro or active. */
+    exit(now: number): void;
+    isFinished(): boolean;
+    update(now: number, progress: number, targetProgress?: number): ProgressAnimationVisual;
+}

package/dist/progress-animation.js

@@ -0,0 +1,128 @@
+import { easeOutCubic, easeOutExpo, easeOutQuad, easeInQuad, } from "./engines/little-tween-engine/core/tweens.js";
+function resolveOptions(options = {}) {
+    return {
+        popDurationMs: options.popDurationMs ?? 500,
+        overextend: options.overextend ?? 0.2,
+        startSnapRatio: options.startSnapRatio ?? 0.2,
+        loadingText: options.loadingText === undefined ? "loading" : options.loadingText,
+        doneText: options.doneText ?? "done",
+        doneFadeDurationMs: options.doneFadeDurationMs ?? 2000,
+        removeOnComplete: options.removeOnComplete ?? false,
+    };
+}
+function popPhaseT(now, phaseStart, durationMs) {
+    if (durationMs <= 0)
+        return 1;
+    return Math.min(1, Math.max(0, (now - phaseStart) / durationMs));
+}
+/**
+ * Lifecycle visual for a progress spinner: an intro pop ({@link enter}), an
+ * active phase whose scale tracks progress, and an outro pop ({@link exit})
+ * that fades to a done label. The owner triggers `enter`/`exit`; this class
+ * does not infer them from the progress value.
+ *
+ * Lifecycle stages:
+ * - `idle`: waiting for {@link enter}; nothing is visible.
+ * - `startPop`: the object pops in and settles at the current progress scale.
+ * - `active`: the object scale tracks progress.
+ * - `endPop`: the object pops out after {@link exit}.
+ * - `done`: the object is gone while the done label fades.
+ * - `finished`: all visuals are complete and {@link isFinished} returns true.
+ */
+export class ProgressAnimation {
+    constructor(options = {}) {
+        this.phase = "idle";
+        this.phaseStart = 0;
+        this.activeProgress = 0;
+        this.popTarget = 0;
+        this.doneFadeStart = 0;
+        this.options = resolveOptions(options);
+    }
+    /** Begin the intro pop. Ignored unless idle. */
+    enter(now) {
+        if (this.phase !== "idle")
+            return;
+        this.phase = "startPop";
+        this.phaseStart = now;
+        this.activeProgress = 0;
+        this.popTarget = 0;
+    }
+    /** Begin the outro pop. Ignored unless mid-intro or active. */
+    exit(now) {
+        if (this.phase !== "startPop" && this.phase !== "active")
+            return;
+        this.phase = "endPop";
+        this.phaseStart = now;
+    }
+    isFinished() {
+        return this.phase === "finished";
+    }
+    update(now, progress, targetProgress) {
+        const { popDurationMs, overextend, startSnapRatio, loadingText, doneText, doneFadeDurationMs, removeOnComplete, } = this.options;
+        const goal = targetProgress ?? progress;
+        if (this.phase === "startPop" || this.phase === "active") {
+            this.activeProgress = progress;
+            if (this.phase === "startPop")
+                this.popTarget = Math.max(this.popTarget, goal, progress);
+        }
+        let scale = 0;
+        let text = null;
+        let textOpacity = 0;
+        let hidden = false;
+        if (this.phase === "startPop") {
+            const t = popPhaseT(now, this.phaseStart, popDurationMs);
+            const peak = this.popTarget * (1 + overextend);
+            if (t < startSnapRatio) {
+                const snapT = startSnapRatio > 0 ? t / startSnapRatio : 1;
+                scale = peak * easeOutExpo(snapT);
+            }
+            else {
+                const settleT = startSnapRatio < 1 ? (t - startSnapRatio) / (1 - startSnapRatio) : 1;
+                scale = peak + (this.activeProgress - peak) * easeOutCubic(settleT);
+            }
+            if (t >= 1)
+                this.phase = "active";
+        }
+        else if (this.phase === "active") {
+            scale = this.activeProgress;
+        }
+        else if (this.phase === "endPop") {
+            const t = popPhaseT(now, this.phaseStart, popDurationMs);
+            const peak = 1 + overextend;
+            if (t < 0.5) {
+                scale = 1 + (peak - 1) * easeOutQuad(t * 2);
+            }
+            else {
+                scale = peak * (1 - easeInQuad((t - 0.5) * 2));
+            }
+            if (t >= 1) {
+                this.phase = "done";
+                this.doneFadeStart = now;
+                scale = 0;
+            }
+        }
+        if (this.phase === "startPop" || this.phase === "active") {
+            if (loadingText !== false) {
+                text = loadingText;
+                textOpacity = 0.65;
+            }
+        }
+        else if (this.phase === "endPop") {
+            text = doneText;
+            textOpacity = 0.65;
+        }
+        else if (this.phase === "done") {
+            const fadeT = popPhaseT(now, this.doneFadeStart, doneFadeDurationMs);
+            if (fadeT >= 1) {
+                if (removeOnComplete)
+                    hidden = true;
+                this.phase = "finished";
+            }
+            else {
+                text = doneText;
+                textOpacity = 0.65 * (1 - fadeT);
+            }
+        }
+        return { scale, text, textOpacity, hidden };
+    }
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "3d-spinner",
+  "version": "0.9.0",
+  "description": "A lightweight, zero-dependency 3D spinner, loader, and progress indicator for JavaScript.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./animations/spin": {
+      "types": "./dist/animations/spin.d.ts",
+      "import": "./dist/animations/spin.js"
+    },
+    "./animations/object-motion": {
+      "types": "./dist/animations/object-motion.d.ts",
+      "import": "./dist/animations/object-motion.js"
+    },
+    "./motion": {
+      "types": "./dist/motion/motion.d.ts",
+      "import": "./dist/motion/motion.js"
+    },
+    "./motion/transitions": {
+      "types": "./dist/motion/transitions.d.ts",
+      "import": "./dist/motion/transitions.js"
+    },
+    "./engines/little-3d-engine": {
+      "types": "./dist/engines/little-3d-engine/little-3d-engine.d.ts",
+      "import": "./dist/engines/little-3d-engine/little-3d-engine.js"
+    },
+    "./engines/little-3d-engine/loaders/obj": {
+      "types": "./dist/engines/little-3d-engine/loaders/obj.d.ts",
+      "import": "./dist/engines/little-3d-engine/loaders/obj.js"
+    },
+    "./engines/little-tween-engine": {
+      "types": "./dist/engines/little-tween-engine/little-tween-engine.d.ts",
+      "import": "./dist/engines/little-tween-engine/little-tween-engine.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc",
+    "dev": "npx serve .",
+    "pretest": "npm run build",
+    "test": "node --test tests/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "spinner",
+    "loader",
+    "loading",
+    "3d",
+    "progress"
+  ],
+  "author": "RuneL",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/runelaang/3d-spinner.git"
+  },
+  "homepage": "https://github.com/runelaang/3d-spinner#readme",
+  "bugs": {
+    "url": "https://github.com/runelaang/3d-spinner/issues"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}