@efxlab/motion-canvas-2d 4.0.0

package/src/lib/components/Video.ts

@@ -0,0 +1,368 @@
+import {
+  BBox,
+  DependencyContext,
+  PlaybackState,
+  SerializedVector2,
+  SignalValue,
+  SimpleSignal,
+  clamp,
+  isReactive,
+  useLogger,
+  useThread,
+} from '@efxlab/motion-canvas-core';
+import {computed, initial, nodeName, signal} from '../decorators';
+import {DesiredLength} from '../partials';
+import {drawImage} from '../utils';
+import {Rect, RectProps} from './Rect';
+import reactivePlaybackRate from './__logs__/reactive-playback-rate.md';
+
+export interface VideoProps extends RectProps {
+  /**
+   * {@inheritDoc Video.src}
+   */
+  src?: SignalValue<string>;
+  /**
+   * {@inheritDoc Video.alpha}
+   */
+  alpha?: SignalValue<number>;
+  /**
+   * {@inheritDoc Video.smoothing}
+   */
+  smoothing?: SignalValue<boolean>;
+  /**
+   * {@inheritDoc Video.loop}
+   */
+  loop?: SignalValue<boolean>;
+  /**
+   * {@inheritDoc Video.playbackRate}
+   */
+  playbackRate?: number;
+  /**
+   * The starting time for this video in seconds.
+   */
+  time?: SignalValue<number>;
+  play?: boolean;
+}
+
+@nodeName('Video')
+export class Video extends Rect {
+  private static readonly pool: Record<string, HTMLVideoElement> = {};
+
+  /**
+   * The source of this video.
+   *
+   * @example
+   * Using a local video:
+   * ```tsx
+   * import video from './example.mp4';
+   * // ...
+   * view.add(<Video src={video} />)
+   * ```
+   * Loading an image from the internet:
+   * ```tsx
+   * view.add(<Video src="https://example.com/video.mp4" />)
+   * ```
+   */
+  @signal()
+  declare public readonly src: SimpleSignal<string, this>;
+
+  /**
+   * The alpha value of this video.
+   *
+   * @remarks
+   * Unlike opacity, the alpha value affects only the video itself, leaving the
+   * fill, stroke, and children intact.
+   */
+  @initial(1)
+  @signal()
+  declare public readonly alpha: SimpleSignal<number, this>;
+
+  /**
+   * Whether the video should be smoothed.
+   *
+   * @remarks
+   * When disabled, the video will be scaled using the nearest neighbor
+   * interpolation with no smoothing. The resulting video will appear pixelated.
+   *
+   * @defaultValue true
+   */
+  @initial(true)
+  @signal()
+  declare public readonly smoothing: SimpleSignal<boolean, this>;
+
+  /**
+   * Whether this video should loop upon reaching the end.
+   */
+  @initial(false)
+  @signal()
+  declare public readonly loop: SimpleSignal<boolean, this>;
+
+  /**
+   * The rate at which the video plays, as multiples of the normal speed.
+   *
+   * @defaultValue 1
+   */
+  @initial(1)
+  @signal()
+  declare public readonly playbackRate: SimpleSignal<number, this>;
+
+  @initial(0)
+  @signal()
+  declare protected readonly time: SimpleSignal<number, this>;
+
+  @initial(false)
+  @signal()
+  declare protected readonly playing: SimpleSignal<boolean, this>;
+
+  private lastTime = -1;
+
+  public constructor({play, ...props}: VideoProps) {
+    super(props);
+    if (play) {
+      this.play();
+    }
+  }
+
+  /**
+   * {@inheritDoc Curve.completion}
+   */
+  public curveCompletion(): number {
+    return super.completion();
+  }
+
+  public isPlaying(): boolean {
+    return this.playing();
+  }
+
+  public getCurrentTime(): number {
+    return this.clampTime(this.time());
+  }
+
+  public getDuration(): number {
+    return this.video().duration;
+  }
+
+  protected override desiredSize(): SerializedVector2<DesiredLength> {
+    const custom = super.desiredSize();
+    if (custom.x === null && custom.y === null) {
+      const image = this.video();
+      return {
+        x: image.videoWidth,
+        y: image.videoHeight,
+      };
+    }
+
+    return custom;
+  }
+
+  /**
+   * The completion of this video in the range from 0 to 1.
+   *
+   * @remarks
+   * To get the percentage of the stroke that's currently visible, use
+   * {@link Video.curveCompletion} instead.
+   */
+  @computed()
+  public override completion(): number {
+    return this.clampTime(this.time()) / this.video().duration;
+  }
+
+  @computed()
+  protected video(): HTMLVideoElement {
+    const src = this.src();
+    const key = `${this.key}/${src}`;
+    let video = Video.pool[key];
+    if (!video) {
+      video = document.createElement('video');
+      video.src = src;
+      Video.pool[key] = video;
+    }
+
+    if (video.readyState < 2) {
+      DependencyContext.collectPromise(
+        new Promise<void>(resolve => {
+          const listener = () => {
+            resolve();
+            video.removeEventListener('canplay', listener);
+          };
+          video.addEventListener('canplay', listener);
+        }),
+      );
+    }
+
+    return video;
+  }
+
+  @computed()
+  protected seekedVideo(): HTMLVideoElement {
+    const video = this.video();
+    const time = this.clampTime(this.time());
+
+    video.playbackRate = this.playbackRate();
+
+    if (!video.paused) {
+      video.pause();
+    }
+
+    if (this.lastTime === time) {
+      return video;
+    }
+
+    this.setCurrentTime(time);
+
+    return video;
+  }
+
+  @computed()
+  protected fastSeekedVideo(): HTMLVideoElement {
+    const video = this.video();
+    const time = this.clampTime(this.time());
+
+    video.playbackRate = this.playbackRate();
+
+    if (this.lastTime === time) {
+      return video;
+    }
+
+    const playing =
+      this.playing() && time < video.duration && video.playbackRate > 0;
+    if (playing) {
+      if (video.paused) {
+        DependencyContext.collectPromise(video.play());
+      }
+    } else {
+      if (!video.paused) {
+        video.pause();
+      }
+    }
+
+    if (Math.abs(video.currentTime - time) > 0.2) {
+      this.setCurrentTime(time);
+    } else if (!playing) {
+      video.currentTime = time;
+    }
+
+    return video;
+  }
+
+  protected override draw(context: CanvasRenderingContext2D) {
+    this.drawShape(context);
+    const alpha = this.alpha();
+    if (alpha > 0) {
+      const playbackState = this.view().playbackState();
+      const video =
+        playbackState === PlaybackState.Playing ||
+        playbackState === PlaybackState.Presenting
+          ? this.fastSeekedVideo()
+          : this.seekedVideo();
+
+      const box = BBox.fromSizeCentered(this.computedSize());
+      context.save();
+      context.clip(this.getPath());
+      if (alpha < 1) {
+        context.globalAlpha *= alpha;
+      }
+      context.imageSmoothingEnabled = this.smoothing();
+      drawImage(context, video, box);
+      context.restore();
+    }
+
+    if (this.clip()) {
+      context.clip(this.getPath());
+    }
+
+    this.drawChildren(context);
+  }
+
+  protected override applyFlex() {
+    super.applyFlex();
+    const video = this.video();
+    this.element.style.aspectRatio = (
+      this.ratio() ?? video.videoWidth / video.videoHeight
+    ).toString();
+  }
+
+  protected setCurrentTime(value: number) {
+    const video = this.video();
+    if (video.readyState < 2) return;
+
+    video.currentTime = value;
+    this.lastTime = value;
+    if (video.seeking) {
+      DependencyContext.collectPromise(
+        new Promise<void>(resolve => {
+          const listener = () => {
+            resolve();
+            video.removeEventListener('seeked', listener);
+          };
+          video.addEventListener('seeked', listener);
+        }),
+      );
+    }
+  }
+
+  protected setPlaybackRate(playbackRate: number) {
+    let value: number;
+    if (isReactive(playbackRate)) {
+      value = playbackRate();
+      useLogger().warn({
+        message: 'Invalid value set as the playback rate',
+        remarks: reactivePlaybackRate,
+        inspect: this.key,
+        stack: new Error().stack,
+      });
+    } else {
+      value = playbackRate;
+    }
+    this.playbackRate.context.setter(value);
+
+    if (this.playing()) {
+      if (value === 0) {
+        this.pause();
+      } else {
+        const time = useThread().time;
+        const start = time();
+        const offset = this.time();
+        this.time(() => this.clampTime(offset + (time() - start) * value));
+      }
+    }
+  }
+
+  public play() {
+    const time = useThread().time;
+    const start = time();
+    const offset = this.time();
+    const playbackRate = this.playbackRate();
+    this.playing(true);
+    this.time(() => this.clampTime(offset + (time() - start) * playbackRate));
+  }
+
+  public pause() {
+    this.playing(false);
+    this.time.save();
+    this.video().pause();
+  }
+
+  public seek(time: number) {
+    const playing = this.playing();
+    this.time(this.clampTime(time));
+    if (playing) {
+      this.play();
+    } else {
+      this.pause();
+    }
+  }
+
+  public clampTime(time: number): number {
+    const duration = this.video().duration;
+    if (this.loop()) {
+      time %= duration;
+    }
+    return clamp(0, duration, time);
+  }
+
+  protected override collectAsyncResources() {
+    super.collectAsyncResources();
+    this.seekedVideo();
+  }
+}

package/src/lib/components/View2D.ts

@@ -0,0 +1,85 @@
+import {PlaybackState, SimpleSignal, lazy} from '@efxlab/motion-canvas-core';
+import {initial, signal} from '../decorators';
+import {nodeName} from '../decorators/nodeName';
+import {useScene2D} from '../scenes/useScene2D';
+import type {Node} from './Node';
+import {Rect, RectProps} from './Rect';
+
+export interface View2DProps extends RectProps {
+  assetHash: string;
+}
+
+@nodeName('View2D')
+export class View2D extends Rect {
+  @lazy(() => {
+    const frameID = 'motion-canvas-2d-frame';
+    let frame = document.querySelector<HTMLDivElement>(`#${frameID}`);
+    if (!frame) {
+      frame = document.createElement('div');
+      frame.id = frameID;
+      frame.style.position = 'absolute';
+      frame.style.pointerEvents = 'none';
+      frame.style.top = '0';
+      frame.style.left = '0';
+      frame.style.opacity = '0';
+      frame.style.overflow = 'hidden';
+      document.body.prepend(frame);
+    }
+    return frame.shadowRoot ?? frame.attachShadow({mode: 'open'});
+  })
+  public static shadowRoot: ShadowRoot;
+
+  @initial(PlaybackState.Paused)
+  @signal()
+  declare public readonly playbackState: SimpleSignal<PlaybackState, this>;
+
+  @initial(0)
+  @signal()
+  declare public readonly globalTime: SimpleSignal<number, this>;
+
+  @signal()
+  declare public readonly assetHash: SimpleSignal<string, this>;
+
+  public constructor(props: View2DProps) {
+    super({
+      composite: true,
+      ...props,
+    });
+    this.view2D = this;
+
+    View2D.shadowRoot.append(this.element);
+    this.applyFlex();
+  }
+
+  public override dispose() {
+    this.removeChildren();
+    super.dispose();
+  }
+
+  public override render(context: CanvasRenderingContext2D) {
+    this.computedSize();
+    this.computedPosition();
+    super.render(context);
+  }
+
+  /**
+   * Find a node by its key.
+   *
+   * @param key - The key of the node.
+   */
+  public findKey<T extends Node = Node>(key: string): T | null {
+    return (useScene2D().getNode(key) as T) ?? null;
+  }
+
+  protected override requestLayoutUpdate() {
+    this.updateLayout();
+  }
+
+  protected override requestFontUpdate() {
+    this.applyFont();
+  }
+
+  public override view(): View2D {
+    return this;
+  }
+}

package/src/lib/components/__logs__/image-without-source.md

@@ -0,0 +1,17 @@
+The image won't be visible unless you specify a source:
+
+```tsx
+import myImage from './example.png';
+// ...
+<Img src={myImage} />;
+```
+
+If you did this intentionally, and don't want to see this warning, set the `src`
+property to `null`:
+
+```tsx
+<Img src={null} />
+```
+
+[Learn more](https://motioncanvas.io/docs/media#images) about working with
+images.

package/src/lib/components/__logs__/line-without-points.md

@@ -0,0 +1,30 @@
+The line won't be visible unless you specify at least two points:
+
+```tsx
+<Line
+  stroke="#fff"
+  lineWidth={8}
+  points={[
+    [100, 0],
+    [0, 0],
+    [0, 100],
+  ]}
+/>
+```
+
+Alternatively, you can define the points using the children:
+
+```tsx
+<Line stroke="#fff" lineWidth={8}>
+  <Node x={100} />
+  <Node />
+  <Node y={100} />
+</Line>
+```
+
+If you did this intentionally, and want to disable this message, set the
+`points` property to `null`:
+
+```tsx
+<Line stroke="#fff" lineWidth={8} points={null} />
+```

package/src/lib/components/__logs__/reactive-playback-rate.md

@@ -0,0 +1,21 @@
+The `playbackRate` of a `Video` cannot be reactive.
+
+Make sure to use a concrete value and not a function:
+
+```ts wrong
+video.playbackRate(() => 7);
+```
+
+```ts correct
+video.playbackRate(7);
+```
+
+If you're using a signal, extract its value before passing it to the property:
+
+```ts wrong
+video.playbackRate(mySignal);
+```
+
+```ts correct
+video.playbackRate(mySignal());
+```

package/src/lib/components/__logs__/spline-with-insufficient-knots.md

@@ -0,0 +1,24 @@
+The spline won't be visible unless you specify at least two knots:
+
+```tsx
+<Spline
+  stroke="#fff"
+  lineWidth={8}
+  points={[
+    [100, 0],
+    [0, 0],
+    [0, 100],
+  ]}
+/>
+```
+
+For more control over the knot handles, you can alternatively provide the knots
+as children to the spline using the `Knot` component:
+
+```tsx
+<Spline stroke="#fff" lineWidth={8}>
+  <Knot x={100} endHandle={[-50, 0]} />
+  <Knot />
+  <Knot y={100} startHandle={[-100, 50]} />
+</Spline>
+```

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

@@ -0,0 +1,142 @@
+import {createRef, createSignal, range} from '@efxlab/motion-canvas-core';
+import {describe, expect, it} from 'vitest';
+import {useScene2D} from '../../scenes';
+import {Node} from '../Node';
+import {mockScene2D} from './mockScene2D';
+
+describe('children', () => {
+  mockScene2D();
+
+  it('Append children', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const childA = createRef<Node>();
+    const childB = createRef<Node>();
+
+    view.add(
+      <Node ref={parent}>
+        <Node ref={childA} />
+        <Node ref={childB} />
+      </Node>,
+    );
+
+    expect(childA().parent()).toBe(parent());
+    expect(childB().parent()).toBe(parent());
+    expect(parent().children()).toEqual([childA(), childB()]);
+  });
+
+  it('Clear children', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const childA = createRef<Node>();
+    const childB = createRef<Node>();
+
+    view.add(
+      <Node ref={parent}>
+        <Node ref={childA} />
+        <Node ref={childB} />
+      </Node>,
+    );
+
+    parent().removeChildren();
+
+    expect(childA().parent()).toBe(null);
+    expect(childB().parent()).toBe(null);
+    expect(parent().children()).toEqual([]);
+  });
+
+  it('Replace children', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const childA = <Node />;
+    const childB = <Node />;
+
+    view.add(<Node ref={parent}>{childA}</Node>);
+
+    parent().children(childB);
+
+    expect(childA.parent()).toBe(null);
+    expect(childB.parent()).toBe(parent());
+    expect(parent().children()).toEqual([childB]);
+  });
+
+  it('Take a child from another node', () => {
+    const view = useScene2D().getView();
+    const parentA = createRef<Node>();
+    const parentB = createRef<Node>();
+    const child = createRef<Node>();
+
+    view.add(
+      <>
+        <Node ref={parentA}>
+          <Node ref={child} />
+        </Node>
+        <Node ref={parentB} />
+      </>,
+    );
+
+    expect(parentA().children()).toEqual([child()]);
+    expect(parentB().children()).toEqual([]);
+    expect(child().parent()).toBe(parentA());
+
+    parentB().children(child());
+
+    expect(parentA().children()).toEqual([]);
+    expect(parentB().children()).toEqual([child()]);
+    expect(child().parent()).toBe(parentB());
+  });
+
+  it('Append children conditionally', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const childA = <Node />;
+    const childB = <Node />;
+    const predicate = createSignal(false);
+
+    view.add(<Node ref={parent}>{() => (predicate() ? childA : childB)}</Node>);
+
+    expect(parent().children()).toEqual([childB]);
+    expect(childA.parent()).toBe(null);
+    expect(childB.parent()).toBe(parent());
+
+    predicate(true);
+
+    expect(parent().children()).toEqual([childA]);
+    expect(childA.parent()).toBe(parent());
+    expect(childB.parent()).toBe(null);
+  });
+
+  it('Spawn reactive children', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const count = createSignal(3);
+
+    view.add(
+      <Node ref={parent}>{() => range(count()).map(() => <Node />)}</Node>,
+    );
+
+    expect(parent().children().length).toBe(3);
+
+    count(5);
+
+    expect(parent().children().length).toBe(5);
+  });
+
+  it('Replace a spawner', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const childA = <Node />;
+    const childB = <Node />;
+
+    view.add(<Node ref={parent}>{() => childA}</Node>);
+
+    expect(parent().children()).toEqual([childA]);
+    expect(childA.parent()).toBe(parent());
+
+    parent().children(childB);
+
+    expect(childA.parent()).toBe(null);
+    expect(childB.parent()).toBe(parent());
+    expect(parent().children()).toEqual([childB]);
+  });
+});