@efxlab/motion-canvas-2d 4.0.0

package/src/lib/components/__tests__/clone.test.tsx

@@ -0,0 +1,126 @@
+import {Vector2, createSignal, range} from '@efxlab/motion-canvas-core';
+import {describe, expect, it} from 'vitest';
+import {Circle} from '../Circle';
+import {Node} from '../Node';
+import {mockScene2D} from './mockScene2D';
+
+describe('clone', () => {
+  mockScene2D();
+
+  it('Normal clone', () => {
+    const signal = createSignal(45);
+    const template = (
+      <Circle lineWidth={8} startAngle={signal} end={0.5} />
+    ) as Circle;
+    const clone = template.clone({end: 0});
+
+    expect(clone.lineWidth()).toBe(8);
+    expect(clone.startAngle()).toBe(45);
+    expect(clone.end()).toBe(0);
+    expect(clone.startArrow.context.isInitial()).toBe(true);
+
+    signal(90);
+
+    expect(clone.startAngle()).toBe(90);
+  });
+
+  it('Reactive clone', () => {
+    const signal = createSignal(45);
+    const template = (
+      <Circle lineWidth={8} startAngle={signal} end={0.5} />
+    ) as Circle;
+    const clone = template.reactiveClone({end: 0});
+
+    expect(clone.lineWidth()).toBe(8);
+    expect(clone.startAngle()).toBe(45);
+    expect(clone.end()).toBe(0);
+    expect(clone.startArrow.context.isInitial()).toBe(false);
+
+    template.lineWidth(16);
+    template.startArrow(true);
+    template.end(0.25);
+    signal(90);
+
+    expect(clone.lineWidth()).toBe(16);
+    expect(clone.startAngle()).toBe(90);
+    expect(clone.startArrow()).toBe(true);
+    expect(clone.end()).toBe(0);
+  });
+
+  it('Snapshot clone', () => {
+    const signal = createSignal(45);
+    const template = (
+      <Circle lineWidth={8} startAngle={signal} end={0.5} />
+    ) as Circle;
+    const clone = template.snapshotClone({end: 0});
+
+    expect(clone.lineWidth()).toBe(8);
+    expect(clone.startAngle()).toBe(45);
+    expect(clone.end()).toBe(0);
+    expect(clone.startArrow.context.isInitial()).toBe(true);
+
+    template.lineWidth(16);
+    template.startArrow(true);
+    signal(90);
+
+    expect(clone.lineWidth()).toBe(8);
+    expect(clone.startAngle()).toBe(45);
+    expect(clone.startArrow()).toBe(false);
+  });
+
+  it('Clone compound signal', () => {
+    const signal = Vector2.createSignal(200);
+    const template = (<Circle offset={1} position={signal} />) as Circle;
+    const clone = template.clone({x: 100, offsetY: -1});
+
+    expect(clone.x()).toBe(100);
+    expect(clone.y()).toBe(200);
+    expect(clone.offset.x()).toBe(1);
+    expect(clone.offset.y()).toBe(-1);
+
+    signal([300, 400]);
+
+    expect(clone.x()).toBe(100);
+    expect(clone.y()).toBe(400);
+  });
+
+  it('Clone children', () => {
+    const signal = createSignal(45);
+    const template = (
+      <Node>
+        <Circle lineWidth={8} startAngle={signal} />
+      </Node>
+    );
+    const clone = template.clone();
+
+    expect(clone.children().length).toBe(1);
+    expect(clone.childAs(0)).not.toBe(template.childAs(0));
+    expect(clone.childAs<Circle>(0)!.lineWidth()).toBe(8);
+    expect(clone.childAs<Circle>(0)!.startAngle()).toBe(45);
+
+    signal(90);
+
+    expect(clone.childAs<Circle>(0)!.startAngle()).toBe(90);
+  });
+
+  it('Clone spawner', () => {
+    const count = createSignal(3);
+    const template = (
+      <Node>
+        {() =>
+          range(count()).map(() => (
+            <Circle lineWidth={8} startAngle={count} end={0.5} />
+          ))
+        }
+      </Node>
+    );
+    const clone = template.clone();
+
+    expect(clone.children().length).toBe(3);
+    expect(clone.childAs(0)).not.toBe(template.childAs(0));
+
+    count(5);
+
+    expect(clone.children().length).toBe(5);
+  });
+});

package/src/lib/components/__tests__/generatorTest.ts

@@ -0,0 +1,27 @@
+import {ThreadGeneratorFactory, threads} from '@efxlab/motion-canvas-core';
+import {useScene2D} from '../../scenes';
+import {View2D} from '../View2D';
+
+/**
+ * Turn a generator factory into a test function.
+ *
+ * @example
+ * ```ts
+ * it(
+ *   'Example test',
+ *   generatorTest(function* () {
+ *     yield* waitFor(1);
+ *     expect(useTime()).toBe(1);
+ *   }),
+ * );
+ * ```
+ *
+ * @param factory - The generator factory to test.
+ */
+export function generatorTest(factory: ThreadGeneratorFactory<View2D>) {
+  return () => {
+    const view = useScene2D().getView();
+    const tasks = threads(() => factory(view));
+    [...tasks];
+  };
+}

package/src/lib/components/__tests__/mockScene2D.ts

@@ -0,0 +1,50 @@
+import {
+  FullSceneDescription,
+  PlaybackManager,
+  PlaybackStatus,
+  ThreadGeneratorFactory,
+  ValueDispatcher,
+  Vector2,
+  endPlayback,
+  endScene,
+  startPlayback,
+  startScene,
+} from '@efxlab/motion-canvas-core';
+import {ReadOnlyTimeEvents} from '@efxlab/motion-canvas-core/lib/scenes/timeEvents';
+import {afterAll, beforeAll, beforeEach} from 'vitest';
+import {Scene2D, makeScene2D} from '../../scenes';
+import {View2D} from '../View2D';
+
+/**
+ * Set up the test environment to support creating nodes.
+ *
+ * @remarks
+ * Should be called inside a `describe()` block.
+ * Due to js-dom limitations, layouts are not correctly computed.
+ */
+export function mockScene2D() {
+  const playback = new PlaybackManager();
+  const status = new PlaybackStatus(playback);
+  const description = {
+    ...makeScene2D(function* () {
+      // do nothing
+    }),
+    name: 'test',
+    size: new Vector2(1920, 1080),
+    resolutionScale: 1,
+    timeEventsClass: ReadOnlyTimeEvents,
+    playback: status,
+  } as unknown as FullSceneDescription<ThreadGeneratorFactory<View2D>>;
+  description.onReplaced = new ValueDispatcher(description);
+  const scene = new Scene2D(description);
+
+  beforeAll(() => {
+    startScene(scene);
+    startPlayback(status);
+  });
+  afterAll(() => {
+    endPlayback(status);
+    endScene(scene);
+  });
+  beforeEach(() => scene.reset());
+}

package/src/lib/components/__tests__/query.test.tsx

@@ -0,0 +1,122 @@
+import {createRef, createRefArray} from '@efxlab/motion-canvas-core';
+import {describe, expect, it} from 'vitest';
+import {useScene2D} from '../../scenes';
+import {is} from '../../utils';
+import {Circle} from '../Circle';
+import {Rect} from '../Rect';
+import {mockScene2D} from './mockScene2D';
+
+describe('query', () => {
+  mockScene2D();
+
+  it('Query items based on their type', () => {
+    const view = useScene2D().getView();
+    const circles = createRefArray<Circle>();
+    view.add(
+      <>
+        <Rect />
+        <Circle ref={circles} />
+        <Rect />
+        <Circle ref={circles} />
+        <Rect />
+      </>,
+    );
+
+    const query = view.findAll(is(Circle));
+    expect(query.length).toBe(2);
+    expect(query).toEqual([...circles]);
+  });
+
+  it('Query items based on a custom predicate', () => {
+    const view = useScene2D().getView();
+    const nodes = createRefArray<Node>();
+    view.add(
+      <>
+        <Rect ref={nodes} scale={2} />
+        <Rect />
+        <Circle />
+        <Circle ref={nodes} scale={2} />
+      </>,
+    );
+
+    const query = view.findAll(node => node.scale.x() === 2);
+    expect(query.length).toBe(2);
+    expect(query).toEqual([...nodes]);
+  });
+
+  it('Query the first matching child', () => {
+    const view = useScene2D().getView();
+    const match = createRef<Circle>();
+    view.add(
+      <>
+        <Rect />
+        <Rect>
+          <Rect />
+          <Circle ref={match} />
+        </Rect>
+        <Circle />
+        <Rect />
+      </>,
+    );
+
+    const query = view.findFirst(is(Circle));
+    expect(query).toBe(match());
+  });
+
+  it('Query the last matching child', () => {
+    const view = useScene2D().getView();
+    const match = createRef<Circle>();
+    view.add(
+      <>
+        <Rect />
+        <Circle />
+        <Circle>
+          <Circle />
+          <Rect />
+          <Circle ref={match} />
+        </Circle>
+        <Rect />
+      </>,
+    );
+
+    const query = view.findLast(is(Circle));
+    expect(query?.key).toBe(match().key);
+  });
+
+  it('Query the first matching ancestor', () => {
+    const view = useScene2D().getView();
+    const child = createRef<Circle>();
+    const match = createRef<Circle>();
+    view.add(
+      <Circle>
+        <Circle ref={match}>
+          <Rect>
+            <Circle />
+            <Circle ref={child} />
+            <Circle />
+          </Rect>
+        </Circle>
+      </Circle>,
+    );
+
+    const query = child().findAncestor(is(Circle));
+    expect(query).toBe(match());
+  });
+
+  it('Retrieve a node by its key', () => {
+    const view = useScene2D().getView();
+    const match = createRef<Circle>();
+    view.add(
+      <>
+        <Circle>
+          <Rect />
+          <Circle ref={match} key="test-key" />
+        </Circle>
+        <Rect />
+      </>,
+    );
+
+    const query = view.findKey('test-key');
+    expect(query).toBe(match());
+  });
+});

package/src/lib/components/__tests__/state.test.tsx

@@ -0,0 +1,60 @@
+import {createSignal, join, waitFor} from '@efxlab/motion-canvas-core';
+import {describe, expect, it} from 'vitest';
+import {Circle} from '../Circle';
+import {generatorTest} from './generatorTest';
+import {mockScene2D} from './mockScene2D';
+
+describe('state', () => {
+  mockScene2D();
+
+  it('Restoring state', () => {
+    const signal = createSignal(45);
+    const circle = (
+      <Circle lineWidth={8} startAngle={signal} end={0.5} />
+    ) as Circle;
+    circle.save();
+
+    circle.lineWidth(16);
+    circle.startAngle(90);
+    circle.end(0.25);
+
+    circle.restore();
+
+    expect(circle.lineWidth()).toBe(8);
+    expect(circle.startAngle()).toBe(45);
+    expect(circle.end()).toBe(0.5);
+
+    signal(180);
+
+    expect(circle.startAngle()).toBe(45);
+    expect(circle.startArrow.context.isInitial()).toBe(true);
+  });
+
+  it(
+    'Tweening state',
+    generatorTest(function* () {
+      const signal = createSignal(20);
+      const circle = (
+        <Circle lineWidth={8} startAngle={signal} end={0.5} />
+      ) as Circle;
+      circle.save();
+
+      circle.lineWidth(16);
+      circle.startAngle(40);
+      circle.end(0.3);
+
+      const task = yield circle.restore(2);
+      yield* waitFor(1);
+
+      expect(circle.lineWidth()).closeTo(12, 0.0001);
+      expect(circle.startAngle()).closeTo(30, 0.0001);
+      expect(circle.end()).closeTo(0.4, 0.0001);
+
+      yield* join(task);
+
+      expect(circle.lineWidth()).toBe(8);
+      expect(circle.startAngle()).toBe(20);
+      expect(circle.end()).toBe(0.5);
+    }),
+  );
+});

package/src/lib/components/index.ts

@@ -0,0 +1,26 @@
+export * from './Bezier';
+export * from './Camera';
+export * from './Circle';
+export * from './Code';
+export * from './CubicBezier';
+export * from './Curve';
+export * from './Grid';
+export * from './Icon';
+export * from './Img';
+export * from './Knot';
+export * from './Latex';
+export * from './Layout';
+export * from './Line';
+export * from './Node';
+export * from './Path';
+export * from './Polygon';
+export * from './QuadBezier';
+export * from './Ray';
+export * from './Rect';
+export * from './Shape';
+export * from './Spline';
+export * from './SVG';
+export * from './Txt';
+export * from './types';
+export * from './Video';
+export * from './View2D';

package/src/lib/components/types.ts

@@ -0,0 +1,35 @@
+import type {ReferenceReceiver} from '@efxlab/motion-canvas-core';
+import type {Node} from './Node';
+
+export type ComponentChild =
+  | Node
+  | object
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined;
+
+export type ComponentChildren = ComponentChild | ComponentChild[];
+export type NodeChildren = Node | Node[];
+
+export type PropsOf<T> =
+  T extends NodeConstructor<infer P>
+    ? P
+    : T extends FunctionComponent<infer P>
+      ? P
+      : never;
+
+export interface JSXProps {
+  children?: ComponentChildren;
+  ref?: ReferenceReceiver<Node>;
+}
+
+export interface FunctionComponent<T = any> {
+  (props: T): Node | null;
+}
+
+export interface NodeConstructor<TProps = any, TNode = Node> {
+  new (props: TProps): TNode;
+}

package/src/lib/curves/ArcSegment.ts

@@ -0,0 +1,155 @@
+import {
+  BBox,
+  DEG2RAD,
+  Matrix2D,
+  Vector2,
+  lazy,
+} from '@efxlab/motion-canvas-core';
+import {View2D} from '../components/View2D';
+import {CurvePoint} from './CurvePoint';
+import {Segment} from './Segment';
+
+export class ArcSegment extends Segment {
+  @lazy(() => {
+    const root = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    const el = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+    root.appendChild(el);
+    View2D.shadowRoot.appendChild(root);
+    return el;
+  })
+  private static el: SVGPathElement;
+  public readonly center: Vector2;
+  // angle in radian
+  public readonly startAngle: number;
+  public readonly deltaAngle: number;
+  public readonly xAxisRotation: number;
+  private xAxisRotationMatrix: DOMMatrix;
+  public override readonly points: Vector2[];
+  private length: number;
+
+  public constructor(
+    public readonly startPoint: Vector2,
+    public readonly radius: Vector2,
+    public readonly xAxisRotationDegree: number,
+    public readonly largeArcFlag: number,
+    public readonly sweepFlag: number,
+    public readonly endPoint: Vector2,
+  ) {
+    super();
+
+    this.xAxisRotation = this.xAxisRotationDegree * DEG2RAD;
+    this.radius = new Vector2(Math.abs(radius.x), Math.abs(radius.y));
+
+    const pAccent = startPoint
+      .sub(endPoint)
+      .div(2)
+      .transform(Matrix2D.fromRotation(-xAxisRotationDegree).domMatrix);
+
+    const L =
+      (pAccent.x * pAccent.x) / (radius.x * radius.x) +
+      (pAccent.y * pAccent.y) / (radius.y * radius.y);
+
+    if (L > 1) {
+      const Lsqrt = Math.sqrt(L);
+      radius.x = Lsqrt * radius.x;
+      radius.y = Lsqrt * radius.y;
+    }
+
+    const cAccent = new Vector2(
+      radius.ctg * pAccent.y,
+      radius.perpendicular.ctg * pAccent.x,
+    ).scale(
+      Math.sqrt(
+        1 /
+          ((pAccent.x * pAccent.x) / (radius.x * radius.x) +
+            (pAccent.y * pAccent.y) / (radius.y * radius.y)) -
+          1,
+      ) * (largeArcFlag === sweepFlag ? -1 : 1),
+    );
+
+    this.xAxisRotationMatrix =
+      Matrix2D.fromRotation(xAxisRotationDegree).domMatrix;
+    this.center = cAccent
+      .transform(this.xAxisRotationMatrix)
+      .add(startPoint.add(endPoint).div(2));
+
+    const q = pAccent.sub(cAccent).div(radius);
+    const s = pAccent.scale(-1).sub(cAccent).div(radius);
+    this.startAngle = q.radians;
+    this.deltaAngle = Vector2.angleBetween(q, s) % (Math.PI * 2);
+    if (this.sweepFlag === 0 && this.deltaAngle > 0) {
+      this.deltaAngle -= Math.PI * 2;
+    }
+    if (this.sweepFlag === 1 && this.deltaAngle < 0) {
+      this.deltaAngle += Math.PI * 2;
+    }
+
+    ArcSegment.el.setAttribute(
+      'd',
+      `M ${this.startPoint.x} ${this.startPoint.y} A ${this.radius.x} ${this.radius.y} ${this.xAxisRotationDegree} ${this.largeArcFlag} ${this.sweepFlag} ${this.endPoint.x} ${this.endPoint.y}`,
+    );
+    this.length = ArcSegment.el.getTotalLength();
+
+    const bbox = new BBox(ArcSegment.el.getBBox());
+    this.points = [bbox.topLeft, bbox.bottomRight];
+  }
+
+  public getAnglePosition(angle: number) {
+    return this.radius
+      .mul(Vector2.fromRadians(angle))
+      .transform(this.xAxisRotationMatrix)
+      .add(this.center);
+  }
+
+  public getAngleDerivative(angle: number) {
+    return new Vector2(
+      -this.radius.x * Math.sin(angle),
+      this.radius.y * Math.cos(angle),
+    ).transform(this.xAxisRotationMatrix);
+  }
+
+  public draw(
+    context: CanvasRenderingContext2D | Path2D,
+    start: number,
+    end: number,
+    move: boolean,
+  ): [CurvePoint, CurvePoint] {
+    const startAngle = this.startAngle + this.deltaAngle * start;
+    const endAngle = this.startAngle + this.deltaAngle * end;
+    const startPos = this.getPoint(start);
+    const endPos = this.getPoint(end);
+
+    if (move) context.moveTo(startPos.position.x, startPos.position.y);
+
+    context.ellipse(
+      this.center.x,
+      this.center.y,
+      this.radius.x,
+      this.radius.y,
+      this.xAxisRotation,
+      startAngle,
+      endAngle,
+      this.sweepFlag === 0,
+    );
+
+    return [startPos, endPos];
+  }
+
+  public getPoint(distance: number): CurvePoint {
+    const angle = this.startAngle + distance * this.deltaAngle;
+    const tangent = this.getAngleDerivative(angle).normalized;
+    return {
+      position:
+        distance === 0
+          ? this.startPoint
+          : distance === 1
+            ? this.endPoint
+            : this.getAnglePosition(angle),
+      tangent,
+      normal: tangent.perpendicular,
+    };
+  }
+  public get arcLength(): number {
+    return this.length;
+  }
+}

package/src/lib/curves/CircleSegment.ts

@@ -0,0 +1,77 @@
+import {Vector2, clamp} from '@efxlab/motion-canvas-core';
+import {CurvePoint} from './CurvePoint';
+import {Segment} from './Segment';
+
+export class CircleSegment extends Segment {
+  private readonly length: number;
+  private readonly angle: number;
+  public override readonly points: Vector2[];
+
+  public constructor(
+    private center: Vector2,
+    private radius: number,
+    private from: Vector2,
+    private to: Vector2,
+    private counter: boolean,
+  ) {
+    super();
+    this.angle = Math.acos(clamp(-1, 1, from.dot(to)));
+    this.length = Math.abs(this.angle * radius);
+    const edgeVector = new Vector2(1, 1).scale(radius);
+    this.points = [center.sub(edgeVector), center.add(edgeVector)];
+  }
+
+  public get arcLength(): number {
+    return this.length;
+  }
+
+  public draw(
+    context: CanvasRenderingContext2D | Path2D,
+    from: number,
+    to: number,
+  ): [CurvePoint, CurvePoint] {
+    const counterFactor = this.counter ? -1 : 1;
+    const startAngle = this.from.radians + from * this.angle * counterFactor;
+    const endAngle = this.to.radians - (1 - to) * this.angle * counterFactor;
+
+    if (Math.abs(this.angle) > 0.0001) {
+      context.arc(
+        this.center.x,
+        this.center.y,
+        this.radius,
+        startAngle,
+        endAngle,
+        this.counter,
+      );
+    }
+
+    const startNormal = Vector2.fromRadians(startAngle);
+    const endNormal = Vector2.fromRadians(endAngle);
+
+    return [
+      {
+        position: this.center.add(startNormal.scale(this.radius)),
+        tangent: this.counter ? startNormal : startNormal.flipped,
+        normal: this.counter ? startNormal.flipped : startNormal,
+      },
+      {
+        position: this.center.add(endNormal.scale(this.radius)),
+        tangent: this.counter ? endNormal.flipped : endNormal,
+        normal: this.counter ? endNormal.flipped : endNormal,
+      },
+    ];
+  }
+
+  public getPoint(distance: number): CurvePoint {
+    const counterFactor = this.counter ? -1 : 1;
+    const angle = this.from.radians + distance * this.angle * counterFactor;
+
+    const normal = Vector2.fromRadians(angle);
+
+    return {
+      position: this.center.add(normal.scale(this.radius)),
+      tangent: this.counter ? normal : normal.flipped,
+      normal: this.counter ? normal : normal.flipped,
+    };
+  }
+}