etro 0.9.1 → 0.10.0

package/src/event.ts

@@ -4,6 +4,32 @@
 
 import EtroObject from './object'
 
+class DeprecatedEvent {
+  replacement: string
+  message: string
+
+  constructor (replacement: string, message: string = undefined) {
+    this.replacement = replacement
+    this.message = message
+  }
+
+  toString () {
+    let str = ''
+
+    if (this.replacement) {
+      str += `Use ${this.replacement} instead.`
+    }
+
+    if (this.message) {
+      str += ` ${this.message}`
+    }
+
+    return str
+  }
+}
+
+const deprecatedEvents: Record<string, DeprecatedEvent> = {}
+
 export interface Event {
   target: EtroObject
   type: string
@@ -21,12 +47,15 @@ class TypeId {
   }
 
   contains (other) {
-    if (other._parts.length > this._parts.length)
+    if (other._parts.length > this._parts.length) {
       return false
+    }
 
-    for (let i = 0; i < other._parts.length; i++)
-      if (other._parts[i] !== this._parts[i])
+    for (let i = 0; i < other._parts.length; i++) {
+      if (other._parts[i] !== this._parts[i]) {
         return false
+      }
+    }
 
     return true
   }
@@ -36,27 +65,60 @@ class TypeId {
   }
 }
 
+export function deprecate (type: string, newType: string, message: string = undefined): void {
+  deprecatedEvents[type] = new DeprecatedEvent(newType, message)
+}
+
+function subscribeOnce (target: EtroObject, type: string, listener: <T extends Event>(T) => void): void {
+  const wrapped = event => {
+    unsubscribe(target, wrapped)
+    listener(event)
+  }
+  subscribe(target, type, wrapped)
+}
+
+function subscribeMany (target: EtroObject, type: string, listener: <T extends Event>(T) => void): void {
+  if (!listeners.has(target)) {
+    listeners.set(target, [])
+  }
+
+  listeners.get(target).push(
+    { type: new TypeId(type), listener }
+  )
+}
+
 /**
- * Listen for an event or category of events
+ * Listen for an event or category of events.
  *
- * @param target - a etro object
+ * @param target - an etro object
  * @param type - the id of the type (can contain subtypes, such as
  * "type.subtype")
  * @param listener
+ * @param options - options
+ * @param options.once - if true, the listener will only be called once
  */
-export function subscribe (target: EtroObject, type: string, listener: <T extends Event>(T) => void): void {
-  if (!listeners.has(target))
-    listeners.set(target, [])
+export function subscribe (
+  target: EtroObject,
+  type: string,
+  listener: <T extends Event>(T) => void,
+  options: { once?: boolean } = {}
+): void {
+  // Check if this event is deprecated.
+  if (Object.keys(deprecatedEvents).includes(type)) {
+    console.warn(`Event ${type} is deprecated. ${deprecatedEvents[type]}`)
+  }
 
-  listeners.get(target).push(
-    { type: new TypeId(type), listener }
-  )
+  if (options.once) {
+    subscribeOnce(target, type, listener)
+  } else {
+    subscribeMany(target, type, listener)
+  }
 }
 
 /**
  * Remove an event listener
  *
- * @param target - a etro object
+ * @param target - an etro object
  * @param type - the id of the type (can contain subtypes, such as
  * "type.subtype")
  * @param listener
@@ -64,8 +126,9 @@ export function subscribe (target: EtroObject, type: string, listener: <T extend
 export function unsubscribe (target: EtroObject, listener: <T extends Event>(T) => void): void {
   // Make sure `listener` has been added with `subscribe`.
   if (!listeners.has(target) ||
-  !listeners.get(target).map(pair => pair.listener).includes(listener))
+  !listeners.get(target).map(pair => pair.listener).includes(listener)) {
     throw new Error('No matching event listener to remove')
+  }
 
   const removed = listeners.get(target)
     .filter(pair => pair.listener !== listener)
@@ -73,29 +136,31 @@ export function unsubscribe (target: EtroObject, listener: <T extends Event>(T)
 }
 
 /**
- * Emits an event to all listeners
+ * Publish an event to all listeners without checking if it is deprecated.
  *
- * @param target - a etro object
- * @param type - the id of the type (can contain subtypes, such as
- * "type.subtype")
- * @param event - any additional event data
+ * @param target
+ * @param type
+ * @param event
+ * @returns
  */
-export function publish (target: EtroObject, type: string, event: Record<string, unknown>): Event {
+function _publish (target: EtroObject, type: string, event: Record<string, unknown>): Event {
   (event as unknown as Event).target = target; // could be a proxy
   (event as unknown as Event).type = type
 
   const t = new TypeId(type)
 
-  if (!listeners.has(target))
+  if (!listeners.has(target)) {
     // No event fired
     return null
+  }
 
   // Call event listeners for this event.
   const listenersForType = []
   for (let i = 0; i < listeners.get(target).length; i++) {
     const item = listeners.get(target)[i]
-    if (t.contains(item.type))
+    if (t.contains(item.type)) {
       listenersForType.push(item.listener)
+    }
   }
 
   for (let i = 0; i < listenersForType.length; i++) {
@@ -106,6 +171,31 @@ export function publish (target: EtroObject, type: string, event: Record<string,
   return event as unknown as Event
 }
 
+/**
+ * Emits an event to all listeners
+ *
+ * @param target - an etro object
+ * @param type - the id of the type (can contain subtypes, such as
+ * "type.subtype")
+ * @param event - any additional event data
+ */
+export function publish (target: EtroObject, type: string, event: Record<string, unknown>): Event {
+  // Check if this event is deprecated only if it can be replaced.
+  if (Object.keys(deprecatedEvents).includes(type) && deprecatedEvents[type].replacement) {
+    throw new Error(`Event ${type} is deprecated. ${deprecatedEvents[type]}`)
+  }
+
+  // Check for deprecated events that this event replaces.
+  for (const deprecated in deprecatedEvents) {
+    const deprecatedEvent = deprecatedEvents[deprecated]
+    if (type === deprecatedEvent.replacement) {
+      _publish(target, deprecated, { ...event })
+    }
+  }
+
+  return _publish(target, type, event)
+}
+
 const listeners: WeakMap<EtroObject, {
   type: TypeId,
   listener: (Event) => void

package/src/layer/audio-source.ts

@@ -6,19 +6,24 @@ import { Base, BaseOptions } from './base'
 type Constructor<T> = new (...args: unknown[]) => T
 
 interface AudioSource extends Base {
-  readonly source: HTMLMediaElement
+  /** HTML media element (an audio or video element) */
+  readonly source: HTMLAudioElement
+  /** Audio source node for the media */
   readonly audioNode: AudioNode
   playbackRate: number
-  /** The audio source node for the media */
+  /** Seconds to skip ahead by */
   sourceStartTime: number
 }
 
-interface AudioSourceOptions extends BaseOptions {
+interface AudioSourceOptions extends Omit<BaseOptions, 'duration'> {
+  duration?: number
+  /** HTML media element (an audio or video element) */
   source: HTMLMediaElement
+  /** Seconds to skip ahead by */
   sourceStartTime?: number
   muted?: boolean
   volume?: number
-  playbackRate: number
+  playbackRate?: number
   onload?: (source: HTMLMediaElement, options: AudioSourceOptions) => void
 }
 
@@ -59,18 +64,31 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
      * @param [options.playbackRate=1]
      */
     constructor (options: MixedAudioSourceOptions) {
+      if (!options.source) {
+        throw new Error('Property "source" is required in options')
+      }
+
       const onload = options.onload
       // Don't set as instance property
       delete options.onload
-      super(options)
+
+      super({
+        ...options,
+
+        // Set a default duration so that the super constructor doesn't throw an
+        // error
+        duration: options.duration ?? 0
+      })
+
       this._initialized = false
       this._sourceStartTime = options.sourceStartTime || 0
       applyOptions(options, this)
 
       const load = () => {
         // TODO:              && ?
-        if ((options.duration || (this.source.duration - this.sourceStartTime)) < 0)
+        if ((options.duration || (this.source.duration - this.sourceStartTime)) < 0) {
           throw new Error('Invalid options.duration or options.sourceStartTime')
+        }
 
         this._unstretchedDuration = options.duration || (this.source.duration - this.sourceStartTime)
         this.duration = this._unstretchedDuration / (this.playbackRate)
@@ -78,31 +96,34 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
         // super()
         onload && onload.bind(this)(this.source, options)
       }
-      if (this.source.readyState >= 2)
+      if (this.source.readyState >= 2) {
         // this frame's data is available now
         load()
-      else
+      } else {
         // when this frame's data is available
         this.source.addEventListener('loadedmetadata', load)
+      }
 
       this.source.addEventListener('durationchange', () => {
         this.duration = options.duration || (this.source.duration - this.sourceStartTime)
       })
     }
 
+    async whenReady (): Promise<void> {
+      await super.whenReady()
+      if (this.source.readyState < 4) {
+        await new Promise(resolve => {
+          this.source.addEventListener('canplaythrough', resolve)
+        })
+      }
+    }
+
     attach (movie: Movie) {
       super.attach(movie)
 
-      subscribe(movie, 'movie.seek', () => {
-        if (this.currentTime < 0 || this.currentTime >= this.duration)
-          return
-
-        this.source.currentTime = this.currentTime + this.sourceStartTime
-      })
-
       // TODO: on unattach?
-      subscribe(movie, 'movie.audiodestinationupdate', event => {
-        // Connect to new destination if immeidately connected to the existing
+      subscribe(movie, 'audiodestinationupdate', event => {
+        // Connect to new destination if immediately connected to the existing
         // destination.
         if (this._connectedToDestination) {
           this.audioNode.disconnect(movie.actx.destination)
@@ -123,8 +144,9 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
       const oldDisconnect = this._audioNode.disconnect.bind(this.audioNode)
       this._audioNode.disconnect = <T extends AudioDestinationNode>(destination?: T | number, output?: number, input?: number): AudioNode => {
         if (this._connectedToDestination &&
-        destination === movie.actx.destination)
+        destination === movie.actx.destination) {
           this._connectedToDestination = false
+        }
 
         return oldDisconnect(destination, output, input)
       }
@@ -145,6 +167,12 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
       this.source.play()
     }
 
+    seek (time: number): void {
+      super.seek(time)
+
+      this.source.currentTime = this.currentTime + this.sourceStartTime
+    }
+
     render () {
       super.render()
       // TODO: implement Issue: Create built-in audio node to support built-in
@@ -155,6 +183,8 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
     }
 
     stop () {
+      super.stop()
+
       this.source.pause()
     }
 
@@ -171,8 +201,9 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
 
     set playbackRate (value) {
       this._playbackRate = value
-      if (this._unstretchedDuration !== undefined)
+      if (this._unstretchedDuration !== undefined) {
         this.duration = this._unstretchedDuration / value
+      }
     }
 
     get startTime () {
@@ -202,7 +233,16 @@ function AudioSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Co
       return this._sourceStartTime
     }
 
-    getDefaultOptions (): MixedAudioSourceOptions {
+    get ready (): boolean {
+      // Typescript doesn't support `super.ready` when targeting es5
+      const superReady = Object.getOwnPropertyDescriptor(superclass.prototype, 'ready').get.call(this)
+      return superReady && this.source.readyState === 4
+    }
+
+    /**
+     * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+     */
+    getDefaultOptions () {
       return {
         ...superclass.prototype.getDefaultOptions(),
         source: undefined, // required

package/src/layer/audio.ts

@@ -3,22 +3,44 @@
 import { Base, BaseOptions } from './base'
 import { AudioSourceMixin, AudioSourceOptions } from './audio-source'
 
-type AudioOptions = AudioSourceOptions
+interface AudioOptions extends Omit<AudioSourceOptions, 'source'> {
+  /**
+   * The raw html `<audio>` element
+   */
+  source: string | HTMLAudioElement
+}
 
 /**
+ * Layer for an HTML audio element
  * @extends AudioSource
  */
 class Audio extends AudioSourceMixin<BaseOptions>(Base) {
+  /**
+   * The raw html `<audio>` element
+   */
+  source: HTMLAudioElement
+
   /**
    * Creates an audio layer
    */
   constructor (options: AudioOptions) {
+    if (typeof options.source === 'string') {
+      const audio = document.createElement('audio')
+      audio.src = options.source
+      options.source = audio
+    }
+
     super(options)
-    if (this.duration === undefined)
+
+    if (this.duration === undefined) {
       this.duration = (this).source.duration - this.sourceStartTime
+    }
   }
 
-  getDefaultOptions (): AudioOptions {
+  /**
+   * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+   */
+  getDefaultOptions () {
     return {
       ...Object.getPrototypeOf(this).getDefaultOptions(),
       /**

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,15 +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
@@ -156,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

@@ -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,6 +122,9 @@ class Text extends Visual {
         return metrics;
     } */
 
+  /**
+   * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+   */
   getDefaultOptions (): TextOptions {
     return {
       ...Visual.prototype.getDefaultOptions(),