Update documentation

This commit is contained in:
Jeremy Likness 2019-11-25 11:34:32 -08:00
parent 99131b7f0a
commit bff4f64d57
6 changed files with 89 additions and 34 deletions

View File

@ -2,23 +2,32 @@
/** /**
* Handles animations and transitions * Handles animations and transitions
* @property {boolean} _transitioning True when animation in effect
* @property {string} _begin The beginning animation class
* @property {string} _end The ending animation class
*/ */
export class Animator { export class Animator {
/** /**
* Create an instance of the animation helper * Create an instance of the animation helper
*/ */
constructor() { constructor() {
/**
* True when an animation is in effect
* @type {boolean}
*/
this._transitioning = false; this._transitioning = false;
/**
* The name of the beginning animation
* @type {string}
*/
this._begin = null; this._begin = null;
/**
* The name of the ending animation
* @type {string}
*/
this._end = null; this._end = null;
} }
/** /**
* True when animation in effect * True when animation is in effect
* @returns {boolean} * @returns {boolean} True if animation is happening
*/ */
get transitioning() { get transitioning() {
return this._transitioning; return this._transitioning;
@ -26,7 +35,7 @@ export class Animator {
/** /**
* True when ready to complete second part of animation * True when ready to complete second part of animation
* @returns {boolean} * @returns {boolean} True if there is a second animation to fire
*/ */
get animationReady() { get animationReady() {
return !!this._end; return !!this._end;

13
js/controls.js vendored
View File

@ -13,6 +13,7 @@ import { Navigator } from "./navigator.js"
/** /**
* Custom element that renders controls to navigate the deck * Custom element that renders controls to navigate the deck
* @extends {HTMLElement}
*/ */
export class Controls extends HTMLElement { export class Controls extends HTMLElement {
@ -21,9 +22,15 @@ export class Controls extends HTMLElement {
*/ */
constructor() { constructor() {
super(); super();
/** @type {CustomRef} */ /**
* The internal reference list of controls
* @type {CustomRef}
*/
this._controlRef = null; this._controlRef = null;
/** @type {Navigator} */ /**
* The related Navigator instance (deck) to control
* @type {Navigator}
*/
this._deck = null; this._deck = null;
} }
@ -53,7 +60,7 @@ export class Controls extends HTMLElement {
/** /**
* Get the list of attributes to watch * Get the list of attributes to watch
* @returns {string[]} * @returns {string[]} List of observable attributes
*/ */
static get observedAttributes() { static get observedAttributes() {
return ["deck"]; return ["deck"];

View File

@ -4,6 +4,7 @@ import { Navigator } from "./navigator.js"
/** /**
* Custom element to handle key press * Custom element to handle key press
* @extends {HTMLElement}
*/ */
export class KeyHandler extends HTMLElement { export class KeyHandler extends HTMLElement {
@ -12,8 +13,8 @@ export class KeyHandler extends HTMLElement {
*/ */
constructor() { constructor() {
super(); super();
/** /**
* The related Navigator element * The related Navigator instance (deck) to handle key press events for
* @type {Navigator} * @type {Navigator}
*/ */
this._deck = null; this._deck = null;

View File

@ -7,10 +7,7 @@ import { Animator } from "./animator.js"
/** /**
* The main class that handles rendering the slide decks * The main class that handles rendering the slide decks
* @property {Animator} _animator Animation helper * @extends {HTMLElement}
* @property {Router} _router Routing helper
* @property {string} _route The current route
* @property {CustomEvent} slidesChangedEvent Event fired when slide changes
*/ */
export class Navigator extends HTMLElement { export class Navigator extends HTMLElement {
@ -19,9 +16,25 @@ export class Navigator extends HTMLElement {
*/ */
constructor() { constructor() {
super(); super();
/**
* The related animation control
* @type {Animator}
*/
this._animator = new Animator(); this._animator = new Animator();
/**
* The related router control
* @type {Router}
*/
this._router = new Router(); this._router = new Router();
/**
* The last known route
* @type {string}
*/
this._route = this._router.getRoute(); this._route = this._router.getRoute();
/**
* Custom event raised when the current slide changes
* @type {CustomEvent}
*/
this.slidesChangedEvent = new CustomEvent("slideschanged", { this.slidesChangedEvent = new CustomEvent("slideschanged", {
bubbles: true, bubbles: true,
cancelable: false cancelable: false
@ -39,7 +52,7 @@ export class Navigator extends HTMLElement {
/** /**
* Get the list of observed attributes * Get the list of observed attributes
* @returns {string[]} * @returns {string[]} The list of attributes to watch
*/ */
static get observedAttributes() { static get observedAttributes() {
return ["start"]; return ["start"];
@ -68,7 +81,7 @@ export class Navigator extends HTMLElement {
/** /**
* Current slide index * Current slide index
* @returns {number} * @returns {number} The current slide index
*/ */
get currentIndex() { get currentIndex() {
return this._currentIndex; return this._currentIndex;
@ -76,7 +89,7 @@ export class Navigator extends HTMLElement {
/** /**
* Current slide * Current slide
* @returns {Slide} * @returns {Slide} The current slide
*/ */
get currentSlide() { get currentSlide() {
return this._slides ? this._slides[this._currentIndex] : null; return this._slides ? this._slides[this._currentIndex] : null;
@ -84,7 +97,7 @@ export class Navigator extends HTMLElement {
/** /**
* Total number of slides * Total number of slides
* @returns {number} * @returns {number} The total slide count
*/ */
get totalSlides() { get totalSlides() {
return this._slides ? this._slides.length : 0; return this._slides ? this._slides.length : 0;
@ -92,7 +105,7 @@ export class Navigator extends HTMLElement {
/** /**
* True if a previous slide exists * True if a previous slide exists
* @returns {boolean} * @returns {boolean} True if a previous slide exists
*/ */
get hasPrevious() { get hasPrevious() {
return this._currentIndex > 0; return this._currentIndex > 0;
@ -100,7 +113,7 @@ export class Navigator extends HTMLElement {
/** /**
* True if a next slide exists * True if a next slide exists
* @returns {boolean} * @returns {boolean} True if a subsequent slide exists
*/ */
get hasNext() { get hasNext() {
return this._currentIndex < (this.totalSlides - 1); return this._currentIndex < (this.totalSlides - 1);
@ -108,7 +121,7 @@ export class Navigator extends HTMLElement {
/** /**
* Main slide navigation: jump to specific slide * Main slide navigation: jump to specific slide
* @param {number} slideIdx * @param {number} slideIdx The index of the slide to navigate to
*/ */
jumpTo(slideIdx) { jumpTo(slideIdx) {
if (this._animator.transitioning) { if (this._animator.transitioning) {

View File

@ -5,20 +5,26 @@
*/ */
export class Router { export class Router {
/**
* Create a new Router instance
*/
constructor() { constructor() {
/** /**
* @property {HTMLDivElement} _eventSource Arbitrary DIV used to generate events * Arbitrary element to source events
* @type {HTMLDivElement}
*/ */
this._eventSource = document.createElement("div"); this._eventSource = document.createElement("div");
/** /**
* @property {CustomEvent} _routeChanged Custom event raised when the route changes * Custom event raised when the route changes
* @type {CustomEvent}
*/ */
this._routeChanged = new CustomEvent("routechanged", { this._routeChanged = new CustomEvent("routechanged", {
bubbles: true, bubbles: true,
cancelable: false cancelable: false
}); });
/** /**
* @property {string} _route The current route * The current route
* @type {string}
*/ */
this._route = null; this._route = null;
window.addEventListener("popstate", () => { window.addEventListener("popstate", () => {

View File

@ -1,5 +1,7 @@
// @ts-check // @ts-check
/** Represents a slide */ /**
* Represents a slide
* */
export class Slide { export class Slide {
/** /**
@ -7,16 +9,29 @@ export class Slide {
* @param {string} text - The content of the slide * @param {string} text - The content of the slide
*/ */
constructor(text) { constructor(text) {
/** @property {string} _text - internal text representation */ /**
* Internal text representation of the slide
* @type {string}
*/
this._text = text; this._text = text;
/** @property {HTMLDivElement} _html - host div */ /**
* The HTML DOM hosting the slide contents
* @type {HTMLDivElement}
*/
this._html = document.createElement('div'); this._html = document.createElement('div');
this._html.innerHTML = text; this._html.innerHTML = text;
/** @property {string} _title - title of the slide */ /**
* The title of the slide
* @type {string}
*/
this._title = this._html.querySelectorAll("title")[0].innerText; this._title = this._html.querySelectorAll("title")[0].innerText;
/** @type{NodeListOf<HTMLElement>} */ /** @type{NodeListOf<HTMLElement>} */
const transition = (this._html.querySelectorAll("transition")); const transition = (this._html.querySelectorAll("transition"));
if (transition.length) { if (transition.length) {
/**
* The name of the animation to use for transitions
* @type {string}
*/
this._transition = transition[0].innerText; this._transition = transition[0].innerText;
} }
else { else {
@ -25,6 +40,10 @@ export class Slide {
/** @type{NodeListOf<HTMLElement>} */ /** @type{NodeListOf<HTMLElement>} */
const hasNext = this._html.querySelectorAll("nextslide"); const hasNext = this._html.querySelectorAll("nextslide");
if (hasNext.length > 0) { if (hasNext.length > 0) {
/**
* The name of the next slide to load
* @type {string}
*/
this._nextSlideName = hasNext[0].innerText; this._nextSlideName = hasNext[0].innerText;
} }
else { else {
@ -34,7 +53,7 @@ export class Slide {
/** /**
* The slide transition * The slide transition
* @return{string} The transition name * @returns {string} The transition name
*/ */
get transition() { get transition() {
return this._transition; return this._transition;
@ -42,7 +61,7 @@ export class Slide {
/** /**
* The slide title * The slide title
* @return{string} The slide title * @returns {string} The slide title
*/ */
get title() { get title() {
return this._title; return this._title;
@ -50,7 +69,7 @@ export class Slide {
/** /**
* The HTML DOM node for the slide * The HTML DOM node for the slide
* @return{HTMLDivElement} The HTML content * @returns {HTMLDivElement} The HTML content
*/ */
get html() { get html() {
return this._html; return this._html;
@ -58,7 +77,7 @@ export class Slide {
/** /**
* The name of the next slide (filename without the .html extension) * The name of the next slide (filename without the .html extension)
* @return{string} The name of the next slide * @returns {string} The name of the next slide
*/ */
get nextSlide() { get nextSlide() {
return this._nextSlideName; return this._nextSlideName;