@redwilly/anima 0.1.0

package/dist/mobjects/Mobject.js

@@ -0,0 +1,343 @@
+import { Matrix3x3 } from '../core/math/matrix/Matrix3x3';
+import { Vector2 } from '../core/math/Vector2/Vector2';
+import { Animation } from '../core/animations/Animation';
+import { FadeIn, FadeOut } from '../core/animations/fade';
+import { MoveTo, Rotate, Scale } from '../core/animations/transform';
+import { Parallel, Sequence } from '../core/animations/composition';
+import { isPrebuilt } from '../core/animations/types';
+/**
+ * Manages a queue of animations for fluent chaining.
+ * This is an internal implementation detail of Mobject's fluent API.
+ */
+class AnimationQueue {
+    target;
+    queue = [];
+    constructor(target) {
+        this.target = target;
+    }
+    enqueueAnimation(animation) {
+        this.queue.push({ animation });
+    }
+    setLastDuration(seconds) {
+        if (seconds <= 0) {
+            throw new Error('Duration must be positive');
+        }
+        const last = this.queue[this.queue.length - 1];
+        if (!last)
+            return;
+        if (isPrebuilt(last)) {
+            last.animation.duration(seconds);
+        }
+        else {
+            last.config.durationSeconds = seconds;
+        }
+    }
+    setLastEasing(easing) {
+        const last = this.queue[this.queue.length - 1];
+        if (!last)
+            return;
+        if (isPrebuilt(last)) {
+            last.animation.ease(easing);
+        }
+        else {
+            last.config.easing = easing;
+        }
+    }
+    isEmpty() {
+        return this.queue.length === 0;
+    }
+    popLastAnimation() {
+        const last = this.queue.pop();
+        if (!last)
+            return null;
+        if (isPrebuilt(last)) {
+            return last.animation;
+        }
+        const anim = last.factory(this.target);
+        anim.duration(last.config.durationSeconds);
+        if (last.config.easing) {
+            anim.ease(last.config.easing);
+        }
+        if (last.config.delaySeconds !== undefined) {
+            anim.delay(last.config.delaySeconds);
+        }
+        return anim;
+    }
+    toAnimation() {
+        if (this.queue.length === 0) {
+            throw new Error('toAnimation() called with an empty animation queue.');
+        }
+        const animations = [];
+        for (const entry of this.queue) {
+            if (isPrebuilt(entry)) {
+                animations.push(entry.animation);
+            }
+            else {
+                const anim = entry.factory(this.target);
+                anim.duration(entry.config.durationSeconds);
+                if (entry.config.easing) {
+                    anim.ease(entry.config.easing);
+                }
+                if (entry.config.delaySeconds !== undefined) {
+                    anim.delay(entry.config.delaySeconds);
+                }
+                animations.push(anim);
+            }
+        }
+        this.queue.length = 0;
+        if (animations.length === 1 && animations[0]) {
+            return animations[0];
+        }
+        return new Sequence(animations);
+    }
+    getTotalDuration() {
+        let total = 0;
+        for (const entry of this.queue) {
+            if (isPrebuilt(entry)) {
+                total += entry.animation.getDuration() + entry.animation.getDelay();
+            }
+            else {
+                total += entry.config.durationSeconds;
+                if (entry.config.delaySeconds !== undefined) {
+                    total += entry.config.delaySeconds;
+                }
+            }
+        }
+        return total;
+    }
+}
+/**
+ * Base class for all mathematical objects.
+ * Manages position, rotation, scale, and opacity via a local transformation matrix.
+ * Includes fluent animation API for chainable animations.
+ */
+export class Mobject {
+    localMatrix;
+    opacityValue;
+    animQueue = null;
+    savedStates = [];
+    parent = null;
+    constructor() {
+        this.localMatrix = Matrix3x3.identity();
+        this.opacityValue = 0;
+    }
+    getQueue() {
+        if (!this.animQueue) {
+            this.animQueue = new AnimationQueue(this);
+        }
+        return this.animQueue;
+    }
+    // ========== Transform Properties ==========
+    get matrix() {
+        return this.localMatrix;
+    }
+    getWorldMatrix() {
+        if (this.parent === null) {
+            return this.localMatrix;
+        }
+        return this.parent.getWorldMatrix().multiply(this.localMatrix);
+    }
+    get position() {
+        const m = this.localMatrix.values;
+        return new Vector2(m[2], m[5]);
+    }
+    get rotation() {
+        const m = this.localMatrix.values;
+        return Math.atan2(m[3], m[0]);
+    }
+    get scale() {
+        const m = this.localMatrix.values;
+        const sx = Math.sqrt(m[0] * m[0] + m[3] * m[3]);
+        const sy = Math.sqrt(m[1] * m[1] + m[4] * m[4]);
+        return new Vector2(sx, sy);
+    }
+    get opacity() {
+        return this.opacityValue;
+    }
+    // ========== Immediate State Setters ==========
+    pos(x, y) {
+        const newValues = new Float32Array(this.localMatrix.values);
+        newValues[2] = x;
+        newValues[5] = y;
+        this.localMatrix = new Matrix3x3(newValues);
+        return this;
+    }
+    show() {
+        this.opacityValue = 1;
+        return this;
+    }
+    hide() {
+        this.opacityValue = 0;
+        return this;
+    }
+    setOpacity(value) {
+        this.opacityValue = Math.max(0, Math.min(1, value));
+        return this;
+    }
+    setRotation(angle) {
+        const m = this.localMatrix.values;
+        const posX = m[2];
+        const posY = m[5];
+        const currentScale = this.scale;
+        const cos = Math.cos(angle);
+        const sin = Math.sin(angle);
+        const newValues = new Float32Array(9);
+        newValues[0] = cos * currentScale.x;
+        newValues[1] = -sin * currentScale.y;
+        newValues[2] = posX;
+        newValues[3] = sin * currentScale.x;
+        newValues[4] = cos * currentScale.y;
+        newValues[5] = posY;
+        newValues[8] = 1;
+        this.localMatrix = new Matrix3x3(newValues);
+        return this;
+    }
+    setScale(sx, sy) {
+        const m = this.localMatrix.values;
+        const posX = m[2];
+        const posY = m[5];
+        const currentRotation = this.rotation;
+        const cos = Math.cos(currentRotation);
+        const sin = Math.sin(currentRotation);
+        const newValues = new Float32Array(9);
+        newValues[0] = cos * sx;
+        newValues[1] = -sin * sy;
+        newValues[2] = posX;
+        newValues[3] = sin * sx;
+        newValues[4] = cos * sy;
+        newValues[5] = posY;
+        newValues[8] = 1;
+        this.localMatrix = new Matrix3x3(newValues);
+        return this;
+    }
+    applyMatrix(m) {
+        this.localMatrix = m.multiply(this.localMatrix);
+        return this;
+    }
+    // ========== State Save/Restore ==========
+    saveState() {
+        const pos = this.position;
+        const scl = this.scale;
+        this.savedStates.push({
+            position: new Vector2(pos.x, pos.y),
+            scale: new Vector2(scl.x, scl.y),
+            rotation: this.rotation,
+        });
+        return this;
+    }
+    getSavedState() {
+        return this.savedStates[this.savedStates.length - 1];
+    }
+    clearSavedStates() {
+        this.savedStates = [];
+        return this;
+    }
+    /**
+     * Animates back to the last saved state.
+     * Pops the saved state from the stack.
+     * @throws Error if no state was previously saved
+     */
+    restore(durationSeconds) {
+        const state = this.savedStates.pop();
+        if (!state) {
+            throw new Error('restore() called but no state was saved. Call saveState() first.');
+        }
+        const moveAnim = new MoveTo(this, state.position.x, state.position.y);
+        const scaleAnim = new Scale(this, state.scale.x, state.scale.y);
+        const rotateAnim = new Rotate(this, state.rotation - this.rotation);
+        if (durationSeconds !== undefined) {
+            moveAnim.duration(durationSeconds);
+            scaleAnim.duration(durationSeconds);
+            rotateAnim.duration(durationSeconds);
+        }
+        const parallelAnim = new Parallel([moveAnim, scaleAnim, rotateAnim]);
+        this.getQueue().enqueueAnimation(parallelAnim);
+        return this;
+    }
+    // ========== Fluent Animation API ==========
+    createAnimation(animation, durationSeconds) {
+        if (durationSeconds !== undefined) {
+            animation.duration(durationSeconds);
+        }
+        return animation;
+    }
+    // ========== Unified Fluent Animation API ==========
+    // These methods work for both sequential chaining AND parallel usage
+    fadeIn(durationSeconds) {
+        const animation = this.createAnimation(new FadeIn(this), durationSeconds);
+        this.getQueue().enqueueAnimation(animation);
+        return this;
+    }
+    fadeOut(durationSeconds) {
+        const animation = this.createAnimation(new FadeOut(this), durationSeconds);
+        this.getQueue().enqueueAnimation(animation);
+        return this;
+    }
+    moveTo(x, y, durationSeconds) {
+        const animation = this.createAnimation(new MoveTo(this, x, y), durationSeconds);
+        this.getQueue().enqueueAnimation(animation);
+        return this;
+    }
+    rotate(angle, durationSeconds) {
+        const animation = this.createAnimation(new Rotate(this, angle), durationSeconds);
+        this.getQueue().enqueueAnimation(animation);
+        return this;
+    }
+    scaleTo(factor, durationSeconds) {
+        const animation = this.createAnimation(new Scale(this, factor), durationSeconds);
+        this.getQueue().enqueueAnimation(animation);
+        return this;
+    }
+    scaleToXY(factorX, factorY, durationSeconds) {
+        const animation = this.createAnimation(new Scale(this, factorX, factorY), durationSeconds);
+        this.getQueue().enqueueAnimation(animation);
+        return this;
+    }
+    duration(seconds) {
+        this.getQueue().setLastDuration(seconds);
+        return this;
+    }
+    ease(easing) {
+        this.getQueue().setLastEasing(easing);
+        return this;
+    }
+    toAnimation() {
+        return this.getQueue().toAnimation();
+    }
+    getQueuedDuration() {
+        return this.getQueue().getTotalDuration();
+    }
+    hasQueuedAnimations() {
+        return !this.getQueue().isEmpty();
+    }
+    /**
+     * Queues multiple animations to run in parallel (simultaneously).
+     * Automatically handles both Animation objects and mobject method calls.
+     * @example
+     * circle.fadeIn(1).parallel(
+     *     circle.moveTo(100, 50),
+     *     circle.rotate(Math.PI)
+     * ).fadeOut(1);
+     */
+    parallel(...items) {
+        if (items.length === 0) {
+            return this;
+        }
+        // Convert any mobjects to animations by extracting and removing their last queued animation
+        const animations = items.map(item => {
+            if (item instanceof Animation) {
+                return item;
+            }
+            else {
+                // item is a Mobject - pop its last queued animation (removes it to avoid double-counting)
+                const anim = item.getQueue().popLastAnimation();
+                if (!anim) {
+                    throw new Error('No animation found on mobject for parallel execution');
+                }
+                return anim;
+            }
+        });
+        this.getQueue().enqueueAnimation(new Parallel(animations));
+        return this;
+    }
+}

package/dist/mobjects/VGroup/VGroup.d.ts

@@ -0,0 +1,51 @@
+import { VMobject } from '../VMobject';
+import { Color } from '../../core/math/color/Color';
+import type { CornerPosition, Direction, Edge } from './layout';
+/**
+ * A collection of VMobjects that can be manipulated as a single unit.
+ * Uses Scene Graph hierarchy: transforms on parent are inherited by children
+ * via getWorldMatrix() calculation, not by mutating child matrices.
+ */
+export declare class VGroup extends VMobject {
+    protected children: VMobject[];
+    constructor(...mobjects: VMobject[]);
+    get length(): number;
+    add(...mobjects: VMobject[]): this;
+    remove(mobject: VMobject): this;
+    clear(): this;
+    getChildren(): VMobject[];
+    get(index: number): VMobject | undefined;
+    pos(x: number, y: number): this;
+    show(): this;
+    hide(): this;
+    /**
+     * Sets the opacity for this VGroup and all children.
+     * @param value - The opacity value (0-1).
+     * @returns this for chaining.
+     */
+    setOpacity(value: number): this;
+    /**
+     * Sets the stroke color and width for this VGroup and all children.
+     * @param color - The stroke color.
+     * @param width - The stroke width. Default is 2.
+     * @returns this for chaining.
+     */
+    stroke(color: Color, width?: number): this;
+    /**
+     * Sets the fill color and opacity for this VGroup and all children.
+     * @param color - The fill color.
+     * @param opacity - The fill opacity. Default is 1 (fully opaque).
+     * @returns this for chaining.
+     */
+    fill(color: Color, opacity?: number): this;
+    getBoundingBox(): {
+        minX: number;
+        maxX: number;
+        minY: number;
+        maxY: number;
+    };
+    center(): this;
+    toCorner(corner: CornerPosition, buff?: number): this;
+    arrange(direction?: Direction, buff?: number, shouldCenter?: boolean): this;
+    alignTo(target: VMobject, edge: Edge): this;
+}

package/dist/mobjects/VGroup/VGroup.js

@@ -0,0 +1,142 @@
+import { VMobject } from '../VMobject';
+import { centerGroup, toCorner, arrangeChildren, alignToTarget } from './layout';
+/**
+ * A collection of VMobjects that can be manipulated as a single unit.
+ * Uses Scene Graph hierarchy: transforms on parent are inherited by children
+ * via getWorldMatrix() calculation, not by mutating child matrices.
+ */
+export class VGroup extends VMobject {
+    children = [];
+    constructor(...mobjects) {
+        super();
+        this.add(...mobjects);
+    }
+    get length() {
+        return this.children.length;
+    }
+    add(...mobjects) {
+        for (const mob of mobjects) {
+            if (!this.children.includes(mob)) {
+                mob.parent = this;
+                this.children.push(mob);
+            }
+        }
+        return this;
+    }
+    remove(mobject) {
+        const index = this.children.indexOf(mobject);
+        if (index > -1) {
+            mobject.parent = null;
+            this.children.splice(index, 1);
+        }
+        return this;
+    }
+    clear() {
+        for (const child of this.children) {
+            child.parent = null;
+        }
+        this.children = [];
+        return this;
+    }
+    getChildren() {
+        return [...this.children];
+    }
+    get(index) {
+        return this.children[index];
+    }
+    // Note: applyMatrix is NOT overridden - transforms stay on this group's local matrix.
+    // Children inherit via getWorldMatrix() during rendering.
+    pos(x, y) {
+        // Directly set position on local matrix, don't propagate to children
+        return super.pos(x, y);
+    }
+    show() {
+        super.show();
+        for (const child of this.children) {
+            child.show();
+        }
+        return this;
+    }
+    hide() {
+        super.hide();
+        for (const child of this.children) {
+            child.hide();
+        }
+        return this;
+    }
+    /**
+     * Sets the opacity for this VGroup and all children.
+     * @param value - The opacity value (0-1).
+     * @returns this for chaining.
+     */
+    setOpacity(value) {
+        super.setOpacity(value);
+        for (const child of this.children) {
+            child.setOpacity(value);
+        }
+        return this;
+    }
+    /**
+     * Sets the stroke color and width for this VGroup and all children.
+     * @param color - The stroke color.
+     * @param width - The stroke width. Default is 2.
+     * @returns this for chaining.
+     */
+    stroke(color, width = 2) {
+        super.stroke(color, width);
+        for (const child of this.children) {
+            child.stroke(color, width);
+        }
+        return this;
+    }
+    /**
+     * Sets the fill color and opacity for this VGroup and all children.
+     * @param color - The fill color.
+     * @param opacity - The fill opacity. Default is 1 (fully opaque).
+     * @returns this for chaining.
+     */
+    fill(color, opacity = 1) {
+        super.fill(color, opacity);
+        for (const child of this.children) {
+            child.fill(color, opacity);
+        }
+        return this;
+    }
+    getBoundingBox() {
+        if (this.children.length === 0) {
+            return super.getBoundingBox();
+        }
+        let minX = Infinity;
+        let maxX = -Infinity;
+        let minY = Infinity;
+        let maxY = -Infinity;
+        for (const child of this.children) {
+            const bounds = child.getBoundingBox();
+            if (bounds.minX < minX)
+                minX = bounds.minX;
+            if (bounds.maxX > maxX)
+                maxX = bounds.maxX;
+            if (bounds.minY < minY)
+                minY = bounds.minY;
+            if (bounds.maxY > maxY)
+                maxY = bounds.maxY;
+        }
+        return { minX, maxX, minY, maxY };
+    }
+    center() {
+        centerGroup(this);
+        return this;
+    }
+    toCorner(corner, buff = 0.0) {
+        toCorner(this, corner, buff);
+        return this;
+    }
+    arrange(direction = 'RIGHT', buff = 0.25, shouldCenter = true) {
+        arrangeChildren(this, direction, buff, shouldCenter);
+        return this;
+    }
+    alignTo(target, edge) {
+        alignToTarget(this, target, edge);
+        return this;
+    }
+}

package/dist/mobjects/VGroup/index.d.ts

@@ -0,0 +1,3 @@
+export { VGroup } from './VGroup';
+export { centerGroup, toCorner, arrangeChildren, alignToTarget } from './layout';
+export type { CornerPosition, Direction, Edge } from './layout';

package/dist/mobjects/VGroup/index.js

@@ -0,0 +1,2 @@
+export { VGroup } from './VGroup';
+export { centerGroup, toCorner, arrangeChildren, alignToTarget } from './layout';

package/dist/mobjects/VGroup/layout.d.ts

@@ -0,0 +1,20 @@
+import { VGroup } from './VGroup';
+import { VMobject } from '../VMobject';
+import { Camera } from '../../core/camera';
+export type CornerPosition = 'TOP_LEFT' | 'TOP_RIGHT' | 'BOTTOM_LEFT' | 'BOTTOM_RIGHT';
+export type Direction = 'RIGHT' | 'LEFT' | 'UP' | 'DOWN';
+export type Edge = 'TOP' | 'BOTTOM' | 'LEFT' | 'RIGHT';
+/** Centers a VGroup's bounding box at the origin (0, 0). */
+export declare function centerGroup(group: VGroup): VGroup;
+/**
+ * Moves a VGroup's bounding box to a corner of the frame.
+ * @param group The VGroup to position
+ * @param corner Which corner to move to
+ * @param buff Buffer/margin from the corner
+ * @param camera Camera providing frame dimensions (defaults to 1920x1080)
+ */
+export declare function toCorner(group: VGroup, corner: CornerPosition, buff?: number, camera?: Camera): VGroup;
+/** Arranges children in a line along the specified direction. */
+export declare function arrangeChildren(group: VGroup, direction?: Direction, buff?: number, shouldCenter?: boolean): VGroup;
+/** Aligns a VGroup to a target VMobject's edge. */
+export declare function alignToTarget(group: VGroup, target: VMobject, edge: Edge): VGroup;