etro 0.9.0 → 0.10.0

package/src/layer/base.ts

@@ -1,6 +1,5 @@
 import EtroObject from '../object'
-import { publish, subscribe } from '../event'
-import { watchPublic, applyOptions } from '../util'
+import { applyOptions } from '../util'
 import { Movie } from '../movie'
 
 interface BaseOptions {
@@ -30,6 +29,7 @@ class Base implements EtroObject {
   private _occurrenceCount: number
   private _startTime: number
   private _duration: number
+  private _currentTime: number
   private _movie: Movie
 
   /**
@@ -42,67 +42,82 @@ class Base implements EtroObject {
    * movie's timeline
    */
   constructor (options: BaseOptions) {
+    if (options.duration === null || options.duration === undefined) {
+      throw new Error('Property "duration" is required in BaseOptions')
+    }
+
+    if (options.startTime === null || options.startTime === undefined) {
+      throw new Error('Property "startTime" is required in BaseOptions')
+    }
+
     // Set startTime and duration properties manually, because they are
     // readonly. applyOptions ignores readonly properties.
     this._startTime = options.startTime
     this._duration = options.duration
 
-    // Proxy that will be returned by constructor (for sending 'modified'
-    // events).
-    const newThis = watchPublic(this) as Base
-    // Don't send updates when initializing, so use this instead of newThis
     applyOptions(options, this)
 
     // Whether this layer is currently being rendered
     this.active = false
     this.enabled = true
 
-    this._occurrenceCount = 0 // no occurances in parent
+    this._occurrenceCount = 0 // no occurrences in parent
     this._movie = null
-
-    // Propogate up to target
-    subscribe(newThis, 'layer.change', event => {
-      const typeOfChange = event.type.substring(event.type.lastIndexOf('.') + 1)
-      const type = `movie.change.layer.${typeOfChange}`
-      publish(newThis._movie, type, { ...event, target: newThis._movie, type })
-    })
-
-    return newThis
   }
 
+  /**
+   * Wait until this layer is ready to render
+   */
+  async whenReady (): Promise<void> {} // eslint-disable-line @typescript-eslint/no-empty-function
+
   /**
    * Attaches this layer to `movie` if not already attached.
    * @ignore
    */
   tryAttach (movie: Movie): void {
-    if (this._occurrenceCount === 0)
+    if (this._occurrenceCount === 0) {
       this.attach(movie)
+    }
 
     this._occurrenceCount++
   }
 
+  /**
+   * Attaches this layer to `movie`
+   *
+   * Called when the layer is added to a movie's `layers` array.
+   *
+   * @param movie The movie to attach to
+   */
   attach (movie: Movie): void {
     this._movie = movie
   }
 
   /**
-   * Dettaches this layer from its movie if the number of times `tryDetach` has
+   * Detaches this layer from its movie if the number of times `tryDetach` has
    * been called (including this call) equals the number of times `tryAttach`
    * has been called.
    *
    * @ignore
    */
   tryDetach (): void {
-    if (this.movie === null)
+    if (this.movie === null) {
       throw new Error('No movie to detach from')
+    }
 
     this._occurrenceCount--
     // If this layer occurs in another place in a `layers` array, do not unset
     // _movie. (For calling `unshift` on the `layers` proxy)
-    if (this._occurrenceCount === 0)
+    if (this._occurrenceCount === 0) {
       this.detach()
+    }
   }
 
+  /**
+   * Detaches this layer from its movie
+   *
+   * Called when the layer is removed from a movie's `layers` array.
+   */
   detach (): void {
     this._movie = null
   }
@@ -112,15 +127,43 @@ class Base implements EtroObject {
    */
   start (): void {} // eslint-disable-line @typescript-eslint/no-empty-function
 
+  /**
+   * Update {@link currentTime} when seeking
+   *
+   * This method is called when the movie seeks to a new time at the request of
+   * the user. {@link progress} is called when the movie's `currentTime` is
+   * updated due to playback.
+   *
+   * @param time - The new time in the layer
+   */
+  seek (time: number): void {
+    this._currentTime = time
+  }
+
+  /**
+   * Update {@link currentTime} due to playback
+   *
+   * This method is called when the movie's `currentTime` is updated due to
+   * playback. {@link seek} is called when the movie seeks to a new time at the
+   * request of the user.
+   *
+   * @param time - The new time in the layer
+   */
+  progress (time: number): void {
+    this._currentTime = time
+  }
+
   /**
    * Called when the movie renders and the layer is active
    */
   render (): void {} // eslint-disable-line @typescript-eslint/no-empty-function
 
   /**
-  * Called when the layer is deactivated
+   * Called when the layer is deactivated
    */
-  stop (): void {} // eslint-disable-line @typescript-eslint/no-empty-function
+  stop (): void {
+    this._currentTime = undefined
+  }
 
   // TODO: is this needed?
   get parent (): Movie {
@@ -128,6 +171,7 @@ class Base implements EtroObject {
   }
 
   /**
+   * The time in the movie at which this layer starts (in seconds)
    */
   get startTime (): number {
     return this._startTime
@@ -138,14 +182,14 @@ class Base implements EtroObject {
   }
 
   /**
-   * The current time of the movie relative to this layer
+   * The current time of the movie relative to this layer (in seconds)
    */
   get currentTime (): number {
-    return this._movie ? this._movie.currentTime - this.startTime
-      : undefined
+    return this._currentTime
   }
 
   /**
+   * The duration of this layer (in seconds)
    */
   get duration (): number {
     return this._duration
@@ -155,10 +199,20 @@ class Base implements EtroObject {
     this._duration = val
   }
 
+  /**
+   * `true` if this layer is ready to be rendered, `false` otherwise
+   */
+  get ready (): boolean {
+    return true
+  }
+
   get movie (): Movie {
     return this._movie
   }
 
+  /**
+   * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+   */
   getDefaultOptions (): BaseOptions {
     return {
       startTime: undefined, // required

package/src/layer/image.ts

@@ -1,8 +1,32 @@
 import { Visual } from './visual'
 import { VisualSourceMixin, VisualSourceOptions } from './visual-source'
 
-type ImageOptions = VisualSourceOptions
+interface ImageOptions extends Omit<VisualSourceOptions, 'source'> {
+  /**
+   * The raw html `<img>` element
+   */
+  source: string | HTMLImageElement
+}
 
-class Image extends VisualSourceMixin(Visual) {}
+/**
+ * Layer for an HTML image element
+ * @extends VisualSource
+ */
+class Image extends VisualSourceMixin(Visual) {
+  /**
+   * The raw html `<img>` element
+   */
+  source: HTMLImageElement
+
+  constructor (options: ImageOptions) {
+    if (typeof (options.source) === 'string') {
+      const img = document.createElement('img')
+      img.src = options.source
+      options.source = img
+    }
+
+    super(options as VisualSourceOptions)
+  }
+}
 
 export { Image, ImageOptions }

package/src/layer/text.ts

@@ -1,10 +1,10 @@
-import { Dynamic, val, applyOptions } from '../util'
+import { Dynamic, val, applyOptions, Color, parseColor } from '../util'
 import { Visual, VisualOptions } from './visual'
 
 interface TextOptions extends VisualOptions {
   text: Dynamic<string>
   font?: Dynamic<string>
-  color?: Dynamic<string>
+  color?: Dynamic<Color>
   /** The text's horizontal offset from the layer */
   textX?: Dynamic<number>
   /** The text's vertical offset from the layer */
@@ -29,7 +29,7 @@ interface TextOptions extends VisualOptions {
 class Text extends Visual {
   text: Dynamic<string>
   font: Dynamic<string>
-  color: Dynamic<string>
+  color: Dynamic<Color>
   /** The text's horizontal offset from the layer */
   textX: Dynamic<number>
   /** The text's vertical offset from the layer */
@@ -61,6 +61,10 @@ class Text extends Visual {
   // TODO: is textX necessary? it seems inconsistent, because you can't define
   // width/height directly for a text layer
   constructor (options: TextOptions) {
+    if (!options.text) {
+      throw new Error('Property "text" is required in TextOptions')
+    }
+
     // Default to no (transparent) background
     super({ background: null, ...options })
     applyOptions(options, this)
@@ -118,13 +122,16 @@ class Text extends Visual {
         return metrics;
     } */
 
+  /**
+   * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+   */
   getDefaultOptions (): TextOptions {
     return {
       ...Visual.prototype.getDefaultOptions(),
       background: null,
       text: undefined, // required
       font: '10px sans-serif',
-      color: '#fff',
+      color: parseColor('#fff'),
       textX: 0,
       textY: 0,
       maxWidth: null,

package/src/layer/video.ts

@@ -2,14 +2,41 @@ import { Visual } from './visual'
 import { VisualSourceOptions, VisualSourceMixin } from './visual-source'
 import { AudioSourceOptions, AudioSourceMixin } from './audio-source'
 
-type VideoOptions = VisualSourceOptions & AudioSourceOptions
+interface VideoOptions extends Omit<AudioSourceOptions & VisualSourceOptions, 'duration'|'source'> {
+  duration?: number
+
+  /**
+   * The raw html `<video>` element
+   */
+  source: string | HTMLVideoElement
+}
 
-// Use mixins instead of `extend`ing two classes (which isn't supported by
-// JavaScript).
 /**
+ * Layer for an HTML video element
  * @extends AudioSource
  * @extends VisualSource
  */
-class Video extends AudioSourceMixin(VisualSourceMixin(Visual)) {}
+class Video extends AudioSourceMixin(VisualSourceMixin(Visual)) {
+  /**
+   * The raw html `<video>` element
+   */
+  source: HTMLVideoElement
+
+  constructor (options: VideoOptions) {
+    if (typeof (options.source) === 'string') {
+      const video = document.createElement('video')
+      video.src = options.source
+      options.source = video
+    }
+
+    super({
+      ...options,
+
+      // Set a default duration so that the super constructor doesn't throw an
+      // error
+      duration: options.duration ?? 0
+    } as (AudioSourceOptions & VisualSourceOptions))
+  }
+}
 
 export { Video, VideoOptions }

package/src/layer/visual-source.ts

@@ -1,11 +1,27 @@
 import { Dynamic, val, applyOptions } from '../util'
-import { Base, BaseOptions } from './base'
 import { Visual, VisualOptions } from './visual'
 
 type Constructor<T> = new (...args: unknown[]) => T
 
-interface VisualSource extends Base {
+interface VisualSource extends Visual {
   readonly source: HTMLImageElement | HTMLVideoElement
+
+  /** What part of {@link source} to render */
+  sourceX: Dynamic<number>
+  /** What part of {@link source} to render */
+  sourceY: Dynamic<number>
+  /** What part of {@link source} to render, or undefined for the entire width */
+  sourceWidth: Dynamic<number>
+  /** What part of {@link source} to render, or undefined for the entire height */
+  sourceHeight: Dynamic<number>
+  /** Where to render {@link source} onto the layer */
+  destX: Dynamic<number>
+  /** Where to render {@link source} onto the layer */
+  destY: Dynamic<number>
+  /** Where to render {@link source} onto the layer, or undefined to fill the layer's width */
+  destWidth: Dynamic<number>
+  /** Where to render {@link source} onto the layer, or undefined to fill the layer's height */
+  destHeight: Dynamic<number>
 }
 
 interface VisualSourceOptions extends VisualOptions {
@@ -32,7 +48,7 @@ interface VisualSourceOptions extends VisualOptions {
  * A layer that gets its image data from an HTML image or video element
  * @mixin VisualSourceMixin
  */
-function VisualSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Constructor<Visual>): Constructor<VisualSource> {
+function VisualSourceMixin<OptionsSuperclass extends VisualOptions> (superclass: Constructor<Visual>): Constructor<VisualSource> {
   type MixedVisualSourceOptions = OptionsSuperclass & VisualSourceOptions
 
   class MixedVisualSource extends superclass {
@@ -59,10 +75,40 @@ function VisualSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: C
     destHeight: Dynamic<number>
 
     constructor (options: MixedVisualSourceOptions) {
+      if (!options.source) {
+        throw new Error('Property "source" is required in options')
+      }
+
       super(options)
       applyOptions(options, this)
     }
 
+    async whenReady (): Promise<void> {
+      await super.whenReady()
+
+      await new Promise<void>(resolve => {
+        if (this.source instanceof HTMLImageElement) {
+          // The source is an image; wait for it to load
+          if (this.source.complete) {
+            resolve()
+          } else {
+            this.source.addEventListener('load', () => {
+              resolve()
+            })
+          }
+        } else {
+          // The source is a video; wait for the first frame to load
+          if (this.source.readyState === 4) {
+            resolve()
+          } else {
+            this.source.addEventListener('canplaythrough', () => {
+              resolve()
+            })
+          }
+        }
+      })
+    }
+
     doRender () {
       // Clear/fill background
       super.doRender()
@@ -70,7 +116,7 @@ function VisualSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: C
       /*
        * Source dimensions crop the image. Dest dimensions set the size that
        * the image will be rendered at *on the layer*. Note that this is
-       * different than the layer dimensions (`this.width` and `this.height`).
+       * different from the layer dimensions (`this.width` and `this.height`).
        * The main reason this distinction exists is so that an image layer can
        * be rotated without being cropped (see iss #46).
        */
@@ -84,6 +130,18 @@ function VisualSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: C
       )
     }
 
+    get ready (): boolean {
+      // Typescript doesn't support `super.ready` when targeting es5
+      const superReady = Object.getOwnPropertyDescriptor(superclass.prototype, 'ready').get.call(this)
+      const sourceReady = this.source instanceof HTMLImageElement
+        ? this.source.complete
+        : this.source.readyState === 4
+      return superReady && sourceReady
+    }
+
+    /**
+     * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+     */
     getDefaultOptions (): MixedVisualSourceOptions {
       return {
         ...superclass.prototype.getDefaultOptions(),
@@ -125,22 +183,26 @@ function VisualSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: C
       // instead. (TODO: fact check)
       /* eslint-disable eqeqeq */
       return destWidth != undefined
-        ? destWidth : val(this, 'sourceWidth', this.currentTime)
+        ? destWidth
+        : val(this, 'sourceWidth', this.currentTime)
     },
     destHeight: function (destHeight) {
       /* eslint-disable eqeqeq */
       return destHeight != undefined
-        ? destHeight : val(this, 'sourceHeight', this.currentTime)
+        ? destHeight
+        : val(this, 'sourceHeight', this.currentTime)
     },
     width: function (width) {
       /* eslint-disable eqeqeq */
       return width != undefined
-        ? width : val(this, 'destWidth', this.currentTime)
+        ? width
+        : val(this, 'destWidth', this.currentTime)
     },
     height: function (height) {
       /* eslint-disable eqeqeq */
       return height != undefined
-        ? height : val(this, 'destHeight', this.currentTime)
+        ? height
+        : val(this, 'destHeight', this.currentTime)
     }
   }
 

package/src/layer/visual.ts

@@ -1,15 +1,43 @@
-import { Dynamic, val, applyOptions } from '../util'
+import { CustomArray, CustomArrayListener } from '../custom-array'
+import { Dynamic, val, applyOptions, Color } from '../util'
 import { Base, BaseOptions } from './base'
 import { Visual as VisualEffect } from '../effect/visual'
 
+// eslint-disable-next-line no-use-before-define
+class VisualEffectsListener extends CustomArrayListener<VisualEffect> {
+  // eslint-disable-next-line no-use-before-define
+  private _layer: Visual
+
+  // eslint-disable-next-line no-use-before-define
+  constructor (layer: Visual) {
+    super()
+    this._layer = layer
+  }
+
+  onAdd (effect: VisualEffect) {
+    effect.tryAttach(this._layer)
+  }
+
+  onRemove (effect: VisualEffect) {
+    effect.tryDetach()
+  }
+}
+
+class VisualEffects extends CustomArray<VisualEffect> {
+  // eslint-disable-next-line no-use-before-define
+  constructor (target: VisualEffect[], layer: Visual) {
+    super(target, new VisualEffectsListener(layer))
+  }
+}
+
 interface VisualOptions extends BaseOptions {
   x?: Dynamic<number>
   y?: Dynamic<number>
   width?: Dynamic<number>
   height?: Dynamic<number>
-  background?: Dynamic<string>
+  background?: Dynamic<Color>
   border?: Dynamic<{
-    color: string
+    color: Color
     thickness?: number
   }>
 
@@ -22,9 +50,9 @@ class Visual extends Base {
   y: Dynamic<number>
   width: Dynamic<number>
   height: Dynamic<number>
-  background: Dynamic<string>
+  background: Dynamic<Color>
   border: Dynamic<{
-    color: string
+    color: Color
     thickness: number
   }>
 
@@ -43,40 +71,22 @@ class Visual extends Base {
   // readonly because it's a proxy
   readonly effects: VisualEffect[]
 
-  private _effectsBack: VisualEffect[]
-
   /**
    * Creates a visual layer
    */
   constructor (options: VisualOptions) {
     super(options)
-    // Only validate extra if not subclassed, because if subclcass, there will
-    // be extraneous options.
+
     applyOptions(options, this)
 
     this.canvas = document.createElement('canvas')
     this.cctx = this.canvas.getContext('2d')
+    this.effects = new VisualEffects([], this)
+  }
 
-    this._effectsBack = []
-    this.effects = new Proxy(this._effectsBack, {
-      deleteProperty: (target, property) => {
-        const value = target[property]
-        value.detach()
-        delete target[property]
-        return true
-      },
-      set: (target, property, value) => {
-        if (!isNaN(Number(property))) {
-          // The property is a number (index)
-          if (target[property])
-            target[property].detach()
-
-          value.attach(this)
-        }
-        target[property] = value
-        return true
-      }
-    })
+  async whenReady (): Promise<void> {
+    await super.whenReady()
+    await Promise.all(this.effects.map(effect => effect.whenReady()))
   }
 
   /**
@@ -86,8 +96,9 @@ class Visual extends Base {
     // Prevent empty canvas errors if the width or height is 0
     const width = val(this, 'width', this.currentTime)
     const height = val(this, 'height', this.currentTime)
-    if (width === 0 || height === 0)
+    if (width === 0 || height === 0) {
       return
+    }
 
     this.beginRender()
     this.doRender()
@@ -122,8 +133,9 @@ class Visual extends Base {
   endRender (): void {
     const w = val(this, 'width', this.currentTime) || val(this.movie, 'width', this.movie.currentTime)
     const h = val(this, 'height', this.currentTime) || val(this.movie, 'height', this.movie.currentTime)
-    if (w * h > 0)
+    if (w * h > 0) {
       this._applyEffects()
+    }
 
     // else InvalidStateError for drawing zero-area image in some effects, right?
   }
@@ -131,14 +143,15 @@ class Visual extends Base {
   _applyEffects (): void {
     for (let i = 0; i < this.effects.length; i++) {
       const effect = this.effects[i]
-      if (effect && effect.enabled)
+      if (effect && effect.enabled) {
         // Pass relative time
         effect.apply(this, this.movie.currentTime - this.startTime)
+      }
     }
   }
 
   /**
-   * Convienence method for <code>effects.push()</code>
+   * Convenience method for <code>effects.push()</code>
    * @param effect
    * @return the layer (for chaining)
    */
@@ -146,6 +159,15 @@ class Visual extends Base {
     this.effects.push(effect); return this
   }
 
+  get ready (): boolean {
+    // Typescript doesn't support `super.ready` when targeting es5
+    const superReady = Object.getOwnPropertyDescriptor(Base.prototype, 'ready').get.call(this)
+    return superReady && this.effects.every(effect => effect.ready)
+  }
+
+  /**
+   * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+   */
   getDefaultOptions (): VisualOptions {
     return {
       ...Base.prototype.getDefaultOptions(),
@@ -169,13 +191,13 @@ class Visual extends Base {
       height: null,
       /**
        * @name module:layer.Visual#background
-       * @desc The CSS color code for the background, or <code>null</code> for
+       * @desc The color code for the background, or <code>null</code> for
        * transparency
        */
       background: null,
       /**
        * @name module:layer.Visual#border
-       * @desc The CSS border style, or <code>null</code> for no border
+       * @desc The border style, or <code>null</code> for no border
        */
       border: null,
       /**

package/src/movie/effects.ts

@@ -0,0 +1,26 @@
+import { CustomArray, CustomArrayListener } from '../custom-array'
+import { Visual as VisualEffect } from '../effect/index'
+import { Movie } from './movie'
+
+class MovieEffectsListener extends CustomArrayListener<VisualEffect> {
+  private _movie: Movie
+
+  constructor (movie: Movie) {
+    super()
+    this._movie = movie
+  }
+
+  onAdd (effect: VisualEffect) {
+    effect.tryAttach(this._movie)
+  }
+
+  onRemove (effect: VisualEffect) {
+    effect.tryDetach()
+  }
+}
+
+export class MovieEffects extends CustomArray<VisualEffect> {
+  constructor (target: VisualEffect[], movie: Movie) {
+    super(target, new MovieEffectsListener(movie))
+  }
+}

package/src/movie/index.ts

@@ -0,0 +1 @@
+export * from './movie'