[assets] Document functions and variables:

- Use expressive names for variables.
- Add docblocks for each function.
- Add ESLint rules for comments.
This commit is contained in:
Fabien Basmaison 2021-04-06 16:17:20 +02:00
parent 5d3d00f694
commit 52d2f0e331
3 changed files with 132 additions and 37 deletions

View file

@ -29,7 +29,25 @@ module.exports = {
// Stylistic Issues // Stylistic Issues
"arrow-spacing": "error", "arrow-spacing": "error",
"capitalized-comments": [
"warn",
"always",
{
"ignoreConsecutiveComments": true
},
],
"keyword-spacing": "error", "keyword-spacing": "error",
"lines-around-comment": [
"error",
{
"beforeBlockComment": true,
"beforeLineComment": true,
"allowBlockStart": true,
"allowClassStart": true,
"allowObjectStart": true,
"allowArrayStart": true,
},
],
"no-multiple-empty-lines": [ "no-multiple-empty-lines": [
"error", "error",
{ {

View file

@ -49,13 +49,28 @@ let BookWyrm = new class {
.forEach(liveArea => this.polling(liveArea)); .forEach(liveArea => this.polling(liveArea));
} }
back(e) { /**
e.preventDefault(); * Go back in browser history.
*
* @param {Event} event
*
* @return {undefined}
*/
back(event) {
event.preventDefault();
history.back(); history.back();
} }
/**
* Update a counter with recurring requests to the API
*
* @param {Object} counter - DOM node
* @param {int} delay - frequency for polling in ms
*
* @return {undefined}
*/
polling(counter, delay) { polling(counter, delay) {
let poller = this; const bookwyrm = this;
delay = delay || 10000; delay = delay || 10000;
delay += (Math.random() * 1000); delay += (Math.random() * 1000);
@ -63,27 +78,51 @@ let BookWyrm = new class {
setTimeout(function() { setTimeout(function() {
fetch('/api/updates/' + counter.dataset.poll) fetch('/api/updates/' + counter.dataset.poll)
.then(response => response.json()) .then(response => response.json())
.then(data => poller.updateCountElement(counter, data)); .then(data => bookwyrm.updateCountElement(counter, data));
poller.polling(counter, delay * 1.25);
bookwyrm.polling(counter, delay * 1.25);
}, delay, counter); }, delay, counter);
} }
updateCountElement(el, data) { /**
const currentCount = el.innerText; * Update a counter.
*
* @param {object} counter - DOM node
* @param {object} data - json formatted response from a fetch
*
* @return {undefined}
*/
updateCountElement(counter, data) {
const currentCount = counter.innerText;
const count = data.count; const count = data.count;
if (count != currentCount) { if (count != currentCount) {
this.addRemoveClass(el.closest('[data-poll-wrapper]'), 'hidden', count < 1); this.addRemoveClass(counter.closest('[data-poll-wrapper]'), 'hidden', count < 1);
el.innerText = count; counter.innerText = count;
} }
} }
revealForm(e) { /**
let hidden = e.currentTarget.closest('.hidden-form').getElementsByClassName('hidden')[0]; * Toggle form.
*
* @param {Event} event
*
* @return {undefined}
*/
revealForm(event) {
let trigger = event.currentTarget;
let hidden = trigger.closest('.hidden-form').querySelectorAll('.hidden')[0];
this.addRemoveClass(hidden, 'hidden', !hidden); this.addRemoveClass(hidden, 'hidden', !hidden);
} }
/**
* Execute actions on targets based on triggers.
*
* @param {Event} event
*
* @return {undefined}
*/
toggleAction(event) { toggleAction(event) {
let trigger = event.currentTarget; let trigger = event.currentTarget;
let pressed = trigger.getAttribute('aria-pressed') == 'false'; let pressed = trigger.getAttribute('aria-pressed') == 'false';
@ -103,21 +142,21 @@ let BookWyrm = new class {
this.addRemoveClass(target, 'is-active', pressed); this.addRemoveClass(target, 'is-active', pressed);
} }
// show/hide container // Show/hide container.
let container = document.getElementById('hide-' + targetId); let container = document.getElementById('hide-' + targetId);
if (container) { if (container) {
this.addRemoveClass(container, 'hidden', pressed); this.addRemoveClass(container, 'hidden', pressed);
} }
// set checkbox, if appropriate // Check checkbox, if appropriate.
let checkbox = trigger.dataset['controls-checkbox']; let checkbox = trigger.dataset['controls-checkbox'];
if (checkbox) { if (checkbox) {
document.getElementById(checkbox).checked = !!pressed; document.getElementById(checkbox).checked = !!pressed;
} }
// set focus, if appropriate // Set focus, if appropriate.
let focus = trigger.dataset['focus-target']; let focus = trigger.dataset['focus-target'];
if (focus) { if (focus) {
@ -128,25 +167,45 @@ let BookWyrm = new class {
} }
} }
// @todo Only update status if the promise is successful. /**
interact(e) { * Make a request and update the UI accordingly.
e.preventDefault(); * This function is used for boosts and favourites.
*
* @todo Only update status if the promise is successful.
*
* @param {Event} event
*
* @return {undefined}
*/
interact(event) {
event.preventDefault();
let identifier = e.target.dataset.id; this.ajaxPost(event.target);
this.ajaxPost(e.target);
// @todo This probably should be done with IDs. // @todo This probably should be done with IDs.
document.querySelectorAll(`.${identifier}`) document.querySelectorAll(`.${event.target.dataset.id}`)
.forEach(t => this.addRemoveClass(t, 'hidden', t.className.indexOf('hidden') == -1)); .forEach(node => this.addRemoveClass(
node,
'hidden',
node.className.indexOf('hidden') == -1
));
} }
toggleMenu(e) { /**
let el = e.currentTarget; * Handle ARIA states on toggled menus.
let expanded = el.getAttribute('aria-expanded') == 'false'; *
let targetId = el.dataset.controls; * @note This function seems to be redundant and conflicts with toggleAction.
*
* @param {Event} event
*
* @return {undefined}
*/
toggleMenu(event) {
let trigger = event.currentTarget;
let expanded = trigger.getAttribute('aria-expanded') == 'false';
let targetId = trigger.dataset.controls;
el.setAttribute('aria-expanded', expanded); trigger.setAttribute('aria-expanded', expanded);
if (targetId) { if (targetId) {
let target = document.getElementById(targetId); let target = document.getElementById(targetId);
@ -155,6 +214,13 @@ let BookWyrm = new class {
} }
} }
/**
* Submit a form using POST.
*
* @param {object} form - Form to be submitted
*
* @return {undefined}
*/
ajaxPost(form) { ajaxPost(form) {
fetch(form.action, { fetch(form.action, {
method : "POST", method : "POST",

View file

@ -3,32 +3,43 @@
let LocalStorageTools = new class { let LocalStorageTools = new class {
constructor() { constructor() {
// display based on localstorage vars
document.querySelectorAll('[data-hide]') document.querySelectorAll('[data-hide]')
.forEach(t => this.setDisplay(t)); .forEach(t => this.setDisplay(t));
// update localstorage
document.querySelectorAll('.set-display') document.querySelectorAll('.set-display')
.forEach(t => t.addEventListener('click', this.updateDisplay.bind(this))); .forEach(t => t.addEventListener('click', this.updateDisplay.bind(this)));
} }
// set javascript listeners /**
updateDisplay(e) { * Update localStorage, then display content based on keys in localStorage.
*
* @param {Event} event
*
* @return {undefined}
*/
updateDisplay(event) {
// used in set reading goal // used in set reading goal
let key = e.target.dataset.id; let key = event.target.dataset.id;
let value = e.target.dataset.value; let value = event.target.dataset.value;
window.localStorage.setItem(key, value); window.localStorage.setItem(key, value);
document.querySelectorAll('[data-hide="' + key + '"]') document.querySelectorAll('[data-hide="' + key + '"]')
.forEach(t => this.setDisplay(t)); .forEach(node => this.setDisplay(node));
} }
setDisplay(el) { /**
* Toggle display of a DOM node based on its value in the localStorage.
*
* @param {object} node - DOM node to toggle.
*
* @return {undefined}
*/
setDisplay(node) {
// used in set reading goal // used in set reading goal
let key = el.dataset.hide; let key = node.dataset.hide;
let value = window.localStorage.getItem(key); let value = window.localStorage.getItem(key);
BookWyrm.addRemoveClass(el, 'hidden', value); BookWyrm.addRemoveClass(node, 'hidden', value);
} }
} }