From 8755ee26ba544ba6361ae2804ca2466f4137cc5a Mon Sep 17 00:00:00 2001 From: Kamran Ahmed Date: Sun, 4 Mar 2018 21:08:28 +0100 Subject: [PATCH] Add docs and refactor --- assets/scripts/src/element.js | 16 ++++++-- assets/scripts/src/overlay.js | 67 +++++++++++++++++++++++++++------- assets/scripts/src/position.js | 17 +++++++-- assets/scripts/src/sholo.js | 29 ++++++++++++++- index.html | 18 +-------- 5 files changed, 109 insertions(+), 38 deletions(-) diff --git a/assets/scripts/src/element.js b/assets/scripts/src/element.js index 81ba138..4d2df3f 100644 --- a/assets/scripts/src/element.js +++ b/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, diff --git a/assets/scripts/src/overlay.js b/assets/scripts/src/overlay.js index cb10753..154f060 100644 --- a/assets/scripts/src/overlay.js +++ b/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(); diff --git a/assets/scripts/src/position.js b/assets/scripts/src/position.js index 43e16e4..5e178e2 100644 --- a/assets/scripts/src/position.js +++ b/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) && diff --git a/assets/scripts/src/sholo.js b/assets/scripts/src/sholo.js index 66d140d..94fdc12 100644 --- a/assets/scripts/src/sholo.js +++ b/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; diff --git a/index.html b/index.html index b40fb11..800878d 100644 --- a/index.html +++ b/index.html @@ -44,22 +44,8 @@ \ No newline at end of file -- GitLab