Travis/flow common web updates (#14)

* Add Hover element to build script

* Update inline documentation for Player

* Add generic timeline class

This class is for reference, and is not yet used by any generated files from Flow

* Update filename

Co-authored-by: Travis <[email protected]>

Author: traviskirton

Sources/FlowCommonWebFiles/Timeline.js

@@ -0,0 +1,146 @@
+/**
+* A Timeline represents a set of animations that can be applied to a DOM element.
+* The general structure of the Timeline class is a pattern that represents a generic way of referencing elements and resources.
+* This class provides placeholder methods, ince an element can have any number and structure of subelements, each of which may or may not be animated.
+* 
+* TODO: If necessary, convert this class to define functions as part of its prototype, then have generated timelines inherit from this class
+*/
+
+class Timeline {
+    /**
+    * @constructor
+    *
+    * @param {HTMLElement} rootElement
+    *   Root Element of the DOM containing the elements that will be animated in this timeline.
+    *
+    * @param {String} resourcesPath
+    *   The path pointing to the root of the Timeline folder.
+    */
+    constructor(rootElement, elementID, resourcesPath) {
+        this.rootElement = rootElement;
+        this.elementID = elementID;
+        this.resourcesPath = resourcesPath;
+        this.imagesFolderPath = resourcesPath + "/img";
+        this.loadFillImages();
+    }
+
+    /**
+    * Returns the timeline's duration in milliseconds.
+    */
+    get duration() { 
+      return 0 
+    }
+
+    /**
+    * Loads fill images for shapes
+    */
+    loadFillImages() {
+      // Any images used as fills on shapes should be created here
+      // For example:
+      // let pattern = this.rootElement.getElementById("shapeID-fillImage")
+      // pattern.innerHTML = `<image ... href="${this.imagesFolderPath}/image.png" />`
+      // pattern.setAttribute(...);
+    }
+  
+    /**
+     * Loads all animations for svgs in the current timeline 
+     */
+    loadSVGAnimations() {
+        this.loadSVGShapeAnimations()
+        this.loadSVGShapeMaskAnimations()
+    }
+
+    /**
+    * Loads all shape animations
+    */
+    loadSVGShapeAnimations() {
+        // Path defs, and animations should be created here
+        // For example:
+        // let path = this.rootElement.getElementById("pathID")
+        // path.d = "M0,...zM0"
+        // path.innerHTML = `<animate .../>`
+
+        // Gradient defs should be created here
+        // let defs = this.rootElement.getElementById("fillID")
+        // defs.innerHTML = `<stop ... /> <animate .../>`
+    } 
+
+    /**
+    * Loads all shape mask animations
+    */
+    loadSVGShapeMaskAnimations() {
+        // Insert SVG animations for mask paths here
+        // For example:
+        // this.rootElement.querySelector("#shape-maskID").innerHTML = `<path ...><animate .../></path>`
+    }
+
+    /**
+    * @return
+    * Returns the list of svg shapes that are animated in this timeline.
+    */
+    get allShapes() {
+        return [
+            //this.rootElement.querySelector(`#shapeID .shape-svg`),
+        ]
+    }
+
+    /**
+     * A simple, visually unnoticable animation to fix a rendering bug with Safari
+     */
+    artboardAnimation() {
+        // Workaround for Safari bug
+        return this.rootElement.querySelector(`${this.elementID}.flow-artboard`).animate({
+        backgroundPosition: ['0px', '1px'],
+        }, {
+            delay: 0,
+            duration: 1000,
+        });
+    }
+
+    /**
+    * Property track animations should be added here.
+    * 
+    * Track animations are keyframe animations that represent the entire state of an element's property throughout the entire timeline.
+    * Animations should be normalized from 0 to 1.
+    * 
+    * shapeWidthTrack() {
+    *   const element = this.rootElement.querySelector(`#shapeID .shape`);
+    *   return element.animate({
+    *     width: ['100px', '200px'],
+    *     easing: ["ease-in-out"],
+    *     offset: [0, 1],
+    *   }, {
+    *     duration: this.duration,
+    *     composite: 'replace',
+    *     fill: 'forwards'
+    *   })
+    * }
+    * 
+    * In the case of animations that do not start at 0, or end at 1, there should be values at 0 and 1, for example
+    * 
+    * shapeWidthTrack() {
+    *   const element = this.rootElement.querySelector(`#shapeID .shape`);
+    *   return element.animate({
+    *     width: ['100px', '100px', '200px', '200px'],
+    *     easing: ["linear","ease-in-out","linear"],
+    *     offset: [0, 0.25, 0.75, 1],
+    *   }, {
+    *     duration: this.duration,
+    *     composite: 'replace',
+    *     fill: 'forwards'
+    *   })
+    * }
+    */
+
+    /**
+    * Creates and returns all animations for this timeline.
+    */
+    createAllAnimations() {
+        return [
+            this.artboardAnimation(),
+            // this.shapeWidthTrack()
+        ].flat()
+    }
+}
+
+Object.freeze(Timeline)

Sources/FlowCommonWebFiles/player.js

@@ -1,5 +1,5 @@
 /**
- * Class used for driving animations.
+ * The Player is a generic class for handling the loading, unloading, and playback of a `Timeline` to be associated with a DOM element. A player must be able to construct a timer – using an existing DOM element or ID – which handles timing and the execution of a callback on completion.
  */
 class Player {
   /**
@@ -9,13 +9,13 @@ class Player {
    *  Animation played when the transition is triggered.
    *
    * @param {String} timer
-   *  The HTML Element or the HTML Element ID for the Timer.
+   *  The HTML Element or the HTML Element ID to be used for handling the timer (i.e. timing animation) of `self`.
    *
    * @param {Boolean} loop
-   *  True if the animation should restart upon completion false otherwise.
+   *  This property specifies that the animation should repeat upon completion.
    *
    * @param {Boolean} delay
-   *  The time in milliseconds before the animation starts.
+   *  The number of milliseconds to delay the start of playback.
    *
    * @param {function: () -> Void} callback
    * A callback function passed to the player that runs upon animation completion.
@@ -36,45 +36,51 @@ class Player {
 
   /**
    * @return {Timeline}
-   * Returns the value of timeline for `self`.
+   * Returns the current timeline for `self`.
    */
   get timeline() {
     return this._timeline;
   }
 
   /**
    * @set
-   * Sets the timeline of self to timeline, pauses the playback and sets the current time to zero.
+   * Sets the timeline of `self` to `timeline`. When this variable is set, the player pauses playback then sets the new value. If the new value is `null` the current timing animation is removed, and default values are set in anticipation of a new timeline. If the new value is not `null` the timeline is prepped for playback.
    *
    * @param {Timeline} timeline
-   * Animation to be played.
+   * The timeline to be controlled by `self`.
    *
    */
   set timeline(timeline) {
     // Work around for Safari bug. More detail provided in the
-    // comment above the cancelAnimations function in this file.
+    // comment above the `cancelAnimations` function in this file.
     this.cancelAnimations();
 
+    // Pause the current timeline, if it exists
     if (this._timeline != null) {
       this.pause();
     }
+
     this._timeline = timeline;
-    this._timeline.loadFillImages();
 
+    // Prepare `self` to receive a new timeline, or initiate playback.
     if (this._timeline === null) {
       this.timingAnimation = null;
       this.currentTime = 0;
       this.shouldPlay = false;
     } else {
+      //Set up the timing animation, which is used to track the current playback time
       this.timingAnimation = this.timer.animate(
         {},
         this.timeline.duration + this.delay);
-
-      this.timeline.loadSVGAnimations();
       this.timingAnimation.currentTime = 0;
       this.timingAnimation.pause();
 
+      //Load all images, shapes, animations
+      this.timeline.loadFillImages();
+      this.timeline.loadSVGAnimations();
       this.animations = this.timeline.createAllAnimations();
+
+      //Prepare for playback
       this.shouldPlay = true;
       this.pause();
       this.setOnFinishCallback();
@@ -83,40 +89,44 @@ class Player {
 
   /**
    * @return {Number}
-   * Returns the duration of the timeline of self, or 0 if timeline is null.
+   * Returns the duration of the `timeline` of `self`, or `0` if timeline is `null`.
    */
   get duration() {
     return this.timeline === null ? 0 : this.timeline.duration;
   }
 
   /**
    * @return {Number}
-   * Returns the currentTime of self, or null if timeline is null.
+   * Returns the current playback time of `self`, or `0` if `timeline` is `null`.
    */
   get currentTime() {
     return this.timingAnimation === null ? 0 : this.timingAnimation.currentTime;
   }
 
   /**
    * @set
-   * Sets the currentTime of self.
+   * Sets the current playback time (in milliseconds) of `self`. This value is propagated to all animations in the current timeline.
    *
    * @param {Number} time
    * A numeric value representing time in milliseconds.
    */
   set currentTime(time) {
+    // There should always be both a timeline and a timing animation, if not do nothing
     if (this.timeline === null || this.timingAnimation === null) {
       return;
     }
 
+    // Set the time for all animations in the timeline
     this.animations.forEach((animation) => {
       animation.currentTime = time;
     });
 
+    // Set the time for all shapes (SVG/SMIL) in the timeline
     this.timeline.allShapes.forEach((shape) => {
       shape.setCurrentTime(time / 1000);
     });
 
+    // Set the time for the timing animation
     this.timingAnimation.currentTime = time;
   }
 
@@ -136,8 +146,7 @@ class Player {
   }
 
   /**
-   * Plays the animation if the timeline that belongs to `self` is not null
-   * and the animation is not currently playing.
+   * Plays the current timeline for `self`. If the player is currently playing, or the current timeline is `null` this function does nothing.
    */
   play() {
     if (this.timeline == null || this.isPlaying() === true) {
@@ -148,6 +157,8 @@ class Player {
     this.animations.forEach((animation) => {
       animation.play();
     });
+
+
     this.timeline.allShapes.forEach((shape) => {
       const t = shape.getCurrentTime() % this.timeline.duration;
       shape.setCurrentTime(t);

minify.rb

@@ -5,8 +5,9 @@
 flowCommonWebDir = "#{__dir__}/Sources/FlowCommonWebFiles"
 waapi = "web-animations.min.js"
 flowCommonWebFiles = [
-    "player.js",
-    "ToggleButton.js"
+    "Player.js",
+    "ToggleButton.js",
+    "HoverElement.js"
 ]
 
 outputDir = "#{__dir__}/generated"

package.json

@@ -2,7 +2,7 @@
   "name": "flowcommonweb",
   "version": "1.0.0",
   "description": "**When you export a Flow project to HTML, React, or anything Web-related, Flow includes a set of helper classes and extensions that help manage and control your animations. This page provides and overview and a link to each of these files.**",
-  "main": "player.js",
+  "main": "Player.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },