Add docs and refactor

assets/scripts/src/element.js

@@ -1,12 +1,19 @@
 import Position from './position';
 
 export default class Element {
+  /**
+   * DOM element object
+   * @param node
+   */
   constructor(node) {
     this.element = node;
     this.document = document;
   }
 
-  // Gets the screen co-ordinates for the current dom element
+  /**
+   * Gets the screen co-ordinates (x,y) for the current dom element
+   * @returns {{x: number, y: number}}
+   */
   getScreenCoordinates() {
     let tempNode = this.element;
 
@@ -23,8 +30,11 @@ export default class Element {
     return { x, y };
   }
 
-  // Gets the calculated position on screen
-  getPosition() {
+  /**
+   * Gets the calculated position on screen, around which
+   * we need to draw
+   */
+  getCalculatedPosition() {
     const coordinates = this.getScreenCoordinates();
     const position = new Position({
       left: Number.MAX_VALUE,

assets/scripts/src/overlay.js

@@ -5,6 +5,11 @@ import Position from './position';
  * cutting out the visible part, animating between the sections etc
  */
 export default class Overlay {
+  /**
+   * @param opacity number
+   * @param padding number
+   * @param animate bool
+   */
   constructor({
     opacity = 0.75,
     padding = 10,
@@ -29,7 +34,9 @@ export default class Overlay {
     this.setSize();
   }
 
-  // Prepares the overlay
+  /**
+   * Prepares the overlay
+   */
   prepareContext() {
     const overlay = this.document.createElement('canvas');
 
@@ -44,14 +51,18 @@ export default class Overlay {
     this.overlay.style.zIndex = '999999999';
   }
 
-  // Highlights the dom element on the screen
+  /**
+   * Highlights the dom element on the screen
+   * @param element Element
+   * @param animate bool
+   */
   highlight(element, animate = true) {
     if (!element) {
       return;
     }
 
     // get the position of element around which we need to draw
-    const position = element.getPosition();
+    const position = element.getCalculatedPosition();
     if (!position.canHighlight()) {
       return;
     }
@@ -68,6 +79,9 @@ export default class Overlay {
     this.draw();
   }
 
+  /**
+   * Removes the overlay and cancel any listeners
+   */
   clear() {
     this.positionToHighlight = new Position();
     this.highlightedElement = null;
@@ -81,9 +95,9 @@ export default class Overlay {
   }
 
   /**
-   * `draw` is called for in requestAnimationFrame. Here is what it does
-   * - Puts back the filled overlay on body (i.e. while clearing existing highlight if any)
-   * - Slowly eases towards the item to be selected
+   * `draw` is called for in requestAnimationFrame. Puts back the
+   * filled overlay on body (i.e. while removing existing highlight if any) and
+   * Slowly eases towards the item to be selected.
    */
   draw() {
     // Cache the response of this for re-use below
@@ -99,7 +113,7 @@ export default class Overlay {
       const isFadingIn = this.overlayAlpha < 0.1;
 
       if (isFadingIn) {
-        // Ignore the animation, just highlight the item
+        // Ignore the animation, just highlight the item at its current position
         this.highlightedPosition = this.positionToHighlight;
       } else {
         // Slowly move towards the position to highlight
@@ -110,7 +124,7 @@ export default class Overlay {
       }
     }
 
-    // Remove the cloak from the position to highlight
+    // Cut the chunk of overlay that is over the highlighted item
     this.removeCloak({
       posX: this.highlightedPosition.left - window.scrollX - this.padding,
       posY: this.highlightedPosition.top - window.scrollY - this.padding,
@@ -118,8 +132,8 @@ export default class Overlay {
       height: (this.highlightedPosition.bottom - this.highlightedPosition.top) + (this.padding * 2),
     });
 
+    // Fade the overlay in if we can highlight
     if (canHighlight) {
-      // Fade the overlay in if we can highlight
       if (!this.animate) {
         this.overlayAlpha = this.opacity;
       } else {
@@ -154,7 +168,16 @@ export default class Overlay {
     }
   }
 
-  // Removes the patch of given width and height from the given position (x,y)
+  /**
+   * Removes the cloak from the given position
+   * i.e. cuts the chunk of layout which is over the element
+   * to be highlighted
+   *
+   * @param posX number
+   * @param posY number
+   * @param width number
+   * @param height number
+   */
   removeCloak({
     posX = 0,
     posY = 0,
@@ -164,7 +187,15 @@ export default class Overlay {
     this.context.clearRect(posX, posY, width, height);
   }
 
-  // Adds the cloak i.e. covers the given position with dark overlay
+  /**
+   * Adds the overlay i.e. to cover the given
+   * position with dark overlay
+   *
+   * @param posX number
+   * @param posY number
+   * @param width number
+   * @param height number
+   */
   addCloak({
     posX = 0,
     posY = 0,
@@ -175,6 +206,12 @@ export default class Overlay {
     this.context.fillRect(posX, posY, width, height);
   }
 
+  /**
+   * Sets the size for the overlay
+   *
+   * @param width number
+   * @param height number
+   */
   setSize(width = null, height = null) {
     // By default it is going to cover the whole page and then we will
     // cut out a chunk for the element to be visible out of it
@@ -182,8 +219,12 @@ export default class Overlay {
     this.overlay.height = height || this.window.innerHeight;
   }
 
-  // Refreshes the overlay i.e. sets the size according to current window size
-  // And moves the highlight around if necessary
+  /**
+   * Refreshes the overlay i.e. sets the size according to current window size
+   * And moves the highlight around if necessary
+   *
+   * @param animate bool
+   */
   refresh(animate = true) {
     this.setSize();
 

assets/scripts/src/position.js

@@ -4,10 +4,10 @@
  */
 export default class Position {
   /**
-   * @param left
-   * @param top
-   * @param right
-   * @param bottom
+   * @param left number
+   * @param top number
+   * @param right number
+   * @param bottom number
    */
   constructor({
     left = 0,
@@ -21,10 +21,19 @@ export default class Position {
     this.bottom = bottom;
   }
 
+  /**
+   * Checks if the position is valid to be highlighted
+   * @returns {boolean}
+   */
   canHighlight() {
     return this.left < this.right && this.top < this.bottom;
   }
 
+  /**
+   * Checks if the given position is equal to the passed position
+   * @param position Position
+   * @returns {boolean}
+   */
   equals(position) {
     return this.left.toFixed(3) === position.left.toFixed(3) &&
       this.right.toFixed(3) === position.right.toFixed(3) &&

assets/scripts/src/sholo.js

@@ -6,6 +6,11 @@ import './polyfill';
  * Plugin class that drives the plugin
  */
 export default class Sholo {
+  /**
+   * @param opacity number
+   * @param padding number
+   * @param animate boolean
+   */
   constructor({
     opacity = 0.75,
     padding = 10,
@@ -28,30 +33,50 @@ export default class Sholo {
     this.bind();
   }
 
+  /**
+   * Binds any DOM events listeners
+   * @todo: add throttling in all the listeners
+   */
   bind() {
-    // @todo: add throttling in all the listeners
     this.document.addEventListener('scroll', this.onScroll, false);
     this.document.addEventListener('DOMMouseScroll', this.onScroll, false);
     this.window.addEventListener('resize', this.onResize, false);
     this.window.addEventListener('keyup', this.onKeyUp, false);
   }
 
+  /**
+   * Handler for the onScroll event on document
+   * Refreshes without animation on scroll to make sure
+   * that the highlighted part travels with the scroll
+   */
   onScroll() {
-    // Refresh without animation on scroll
     this.overlay.refresh(false);
   }
 
+  /**
+   * Handler for the onResize DOM event
+   * Refreshes with animation on scroll to make sure that
+   * the highlighted part travels with the width change of window
+   */
   onResize() {
     // Refresh with animation
     this.overlay.refresh(true);
   }
 
+  /**
+   * Clears the overlay on escape key process
+   * @param event
+   */
   onKeyUp(event) {
     if (event.keyCode === 27) {
       this.overlay.clear();
     }
   }
 
+  /**
+   * Highlights the given selector
+   * @param selector
+   */
   highlight(selector) {
     let domElement;
 

index.html

@@ -44,22 +44,8 @@
 
 <script src="./assets/scripts/dist/sholo.js"></script>
 <script>
-  const nodesToSelect = [
-    '.section__header',
-    '.section__how',
-    '.section__examples'
-  ];
-
-  const sholo = new Sholo({
-    padding: 10,
-    animate: true
-  });
-
-  nodesToSelect.forEach((nodeToSelect, index) => {
-    window.setTimeout(() => {
-      sholo.highlight(nodeToSelect);
-    }, index * 1000);
-  });
+  const sholo = new Sholo();
+  sholo.highlight('.section__header');
 </script>
 </body>
 </html>