nanosplash 2.4.0 → 2.5.2

package/src/Core/Nanosplash.ts

@@ -1,20 +1,31 @@
 import '../style.sass'
+import {get} from "../Utilities/dom";
 import {SplashInstance} from "./SplashInstance";
-import {InstanceIterationCallback, NanosplashOptions, SplashJob} from "../types";
 import {ShowInterface} from "../Interfaces/ShowInterface";
 import {NanosplashFactory} from "../Factory/NanosplashFactory";
 import {NanosplashInterface} from "../Interfaces/NanosplashInterface";
-import {ContextualAPIInterface} from "../Interfaces/ContextualAPIInterface";
+import {
+    ContextualAPIObject,
+    Destination,
+    InstanceIterationCallback,
+    NanosplashOptions,
+    SplashJob,
+} from "../types";
+import Exception from "../Exceptions/Exception";
+import IllegalArgumentException from "../Exceptions/IllegalArgumentException";
 
 /**
  * # Nanosplash
  * @author Isak K. Hauge <isakhauge@gmail.com>
  */
-export class Nanosplash implements NanosplashInterface {
+class Nanosplash implements NanosplashInterface {
     public static APP_NAME = 'Nanosplash'
-    public imgSrc: string | undefined
-    public showSpinner: boolean
-    public fontSize: string
+    private static SPINNER_DEFAULT_VISIBILITY = true
+    private static DEBUG = true
+    public debug: boolean
+    private imgSrc: string | undefined
+    private spinner: boolean
+    private fontSize: string
     public readonly instances: Map<string, SplashInstance>
 
     /**
@@ -22,33 +33,92 @@ export class Nanosplash implements NanosplashInterface {
      * @param {NanosplashOptions | undefined} options Nanosplash options object.
      */
     public constructor(options?: NanosplashOptions) {
-        this.imgSrc = options?.imgSrc ?? undefined
-        this.showSpinner = options?.spinner ?? false
+        this.debug = ((options?.debug === undefined)
+            ? Nanosplash.DEBUG
+            : options.spinner) as boolean
+        this.imgSrc = options?.imgSrc
+        this.spinner = (options?.spinner === undefined)
+            ? Nanosplash.SPINNER_DEFAULT_VISIBILITY
+            : options.spinner
         this.fontSize = options?.fontSize ?? '18px'
         this.instances = new Map<string, SplashInstance>()
     }
 
+    /**
+     * # Set Image Source
+     * Set the value as undefined to display no image.
+     * @param {string | undefined} value
+     * @return Nanosplash
+     */
+    public setImgSrc(value: string | undefined): Nanosplash {
+        this.imgSrc = value
+        return this
+    }
+
+    /**
+     * # Set Spinner
+     * Control spinner visibility.
+     * @param {boolean} value
+     * @return Nanosplash
+     */
+    public showSpinner(value: boolean): Nanosplash {
+        this.spinner = value
+        return this
+    }
+
+    /**
+     * # Set Font Size
+     * @param {string} value Use CSS compatible values.
+     * @return Nanosplash
+     */
+    public setFontSize(value: string): Nanosplash {
+        this.fontSize = value
+        return this
+    }
+
+    /**
+     * # Get Image Source
+     * @return string | undefined
+     */
+    public getImgSrc(): string | undefined {
+        return this.imgSrc
+    }
+
+    /**
+     * # Spinner Is Visible
+     * @return boolean
+     */
+    public spinnerIsVisible(): boolean {
+        return this.spinner
+    }
+
+    /**
+     * # Get Font Size
+     * @return string
+     */
+    public getFontSize(): string {
+        return this.fontSize
+    }
+
     /**
      * # Show
      * @param {string} text
      */
-    public show(text: string): ContextualAPIInterface {
+    public show(text: string): ContextualAPIObject {
         return NanosplashFactory.createShowFunction(this, new SplashInstance(this, text, this.imgSrc))(text)
     }
 
     /**
      * # Progress
      * @param {SplashJob[]} jobs An array or list of Splash jobs.
-     * @return ContextualAPIInterface
      */
-    public progress(...jobs: SplashJob[]): ContextualAPIInterface {
+    public progress(...jobs: SplashJob[]): ContextualAPIObject {
         return NanosplashFactory.createProgressFunction(this, new SplashInstance(this, '', this.imgSrc))(...jobs)
     }
 
     /**
      * # While
      * @param {Promise<any>} asyncTask An asynchronous function or Promise.
-     * @return ContextualAPIInterface
      */
     public while(asyncTask: Promise<any>): ShowInterface {
         return NanosplashFactory.createWhileFunction(this, new SplashInstance(this, '', this.imgSrc))(asyncTask)
@@ -65,11 +135,6 @@ export class Nanosplash implements NanosplashInterface {
         const n = this.instances.size
         const instances = Array.from(this.instances.values())
         for (let i = n - 1; i >= 0; i--) {
-            console.log({
-                size: n,
-                lastIdx: n - 1,
-                currentIdx: i
-            })
             const instance = instances[i]
             const id = instance.getId()
             if (!callback(id, instance, i)) {
@@ -97,39 +162,96 @@ export class Nanosplash implements NanosplashInterface {
 
     /**
      * # Hide
-     * Delete specific Splash instance or the latest one.
-     * @param id
+     * Delete specific Splash instance or the latest one. There are three different ways of using this function.
+     *
+     * ## Use SplashInstance IDs
+     * Every new splash instance is given a unique, randomized ID. This ID is easily retrieved by using the getId
+     * method.
+     * <br>
+     * <code>
+     *     const splashInstance = ns.show('Loading');<br>
+     *     ns.hide(splashInstance.getId());
+     * </code>
+     * <br>
+     *
+     * ## Use CSS Selector
+     * Pass the selector referring to the element in which the splash instance resides.
+     * <br>
+     * <code>
+     *     ns.show('Loading').inside('#my-div');<br>
+     *     ns.hide('#my-div');
+     * </code>
+     * <br>
+     *
+     * ## Pass no argument
+     * When calling the hide method without passing arguments, it will delete the latest splash instance added to the
+     * DOM, in other words, in a LIFO fashion.<br>
+     * <code>
+     *     ns.show('Loading');<br>
+     *     ns.hide();
+     * </code>
+     * <br>
+     * @param ref This can either be a SplashInstance ID or a CSS selector referring to the element in which
+     * the instance is residing.
      */
-    public hide(id?: string): void {
-        if (id) {
-            const splashInstance = this.instances.get(id)
-            if (splashInstance) {
-                splashInstance.delete()
+    public hide(ref?: Destination): void {
+        try {
+            if (ref) {
+                const isString = typeof ref === 'string'
+                const isNode = ref instanceof Node
+                const deleteInstancesWhereDestination = (destination: Destination) => {
+                    Array.from(this.instances.values())
+                        .filter((v: SplashInstance) => v.getDestination() === destination)
+                        .forEach((v: SplashInstance) => v.delete())
+                }
+
+                if (isString) {
+                    const splashInstance = this.instances.get(ref)
+                    if (splashInstance) {
+                        splashInstance.delete()
+                        return
+                    } else {
+                        const element = get<HTMLElement>(ref)
+                        if (element) {
+                            deleteInstancesWhereDestination(element)
+                        }
+                        throw new Exception(`The CSS selector (${ref}) points to a non-existing DOM element.`)
+                    }
+                } else if (isNode) {
+                    deleteInstancesWhereDestination(ref)
+                } else {
+                    throw new IllegalArgumentException(
+                        'The ref argument must be either a string or Node',
+                        ref
+                    )
+                }
             } else {
-                throw new Error(
-                    `Could not find element with id: ${id}`
-                )
+                const n = this.instances.size
+                this.lifoIterate((_: string, splashInstance: SplashInstance, i: number) => {
+                    const remove = i === n - 1
+                    if (remove) {
+                        splashInstance.delete()
+                    }
+                    return remove
+                })
+            }
+        } catch (e) {
+            if (this.debug) {
+                console.warn(e)
             }
-        } else {
-            const n = this.instances.size
-            this.lifoIterate((_: string, splashInstance: SplashInstance, i: number) => {
-                const remove = i === n - 1
-                if (remove) {
-                    splashInstance.delete()
-                }
-                return remove
-            })
         }
     }
 
     /**
-     * # Get Splashes With Destination Node
+     * # Get From Destination Node
      * Returns Splash instances having the given destination node.
      * @param {HTMLElement} node
      */
-    public getSplashesWithDestinationNode(node: HTMLElement): SplashInstance[]
+    public getFromDestinationNode(node: HTMLElement): SplashInstance[]
     {
         const fnSameDestinationNode = (v: SplashInstance) => v.getDestination() === node
         return Array.from(this.instances.values()).filter(fnSameDestinationNode)
     }
 }
+
+export default Nanosplash

package/src/Core/SplashInstance.ts

@@ -1,8 +1,8 @@
 import {Destination} from "../types";
-import {Nanosplash} from "./Nanosplash";
-import {addClass, mk, move, setAttr} from "../utilities/dom";
+import Nanosplash from "./Nanosplash";
+import {addClass, mk, move, setAttr} from "../Utilities/dom";
 import {IdentityInterface} from "../Interfaces/IdentityInterface";
-import {NanosplashRepository} from "../repositories/NanosplashRepository";
+import {NanosplashRepository} from "../Repositories/NanosplashRepository";
 
 /**
  * SplashInstance
@@ -36,8 +36,8 @@ export class SplashInstance implements IdentityInterface {
         this.nsImageElement.src = this.imgSrc ?? ''
         this.nsImageElement.alt = Nanosplash.APP_NAME
 
-        this.nsRootElement.style.fontSize = ns.fontSize
-        this.nsSpinnerElement.style.display = ns.showSpinner ? 'flex' : 'none'
+        this.nsRootElement.style.fontSize = ns.getFontSize()
+        this.nsSpinnerElement.style.display = ns.spinnerIsVisible() ? 'flex' : 'none'
 
         this.assembleNSComponent()
         this.setImgSrc(imgSrc)
@@ -169,7 +169,7 @@ export class SplashInstance implements IdentityInterface {
     }
 
     /**
-     * # Move with Regular Strategy
+     * # Move With Regular Strategy
      * Moves the Nanosplash root element to the target node's position and essentially wraps the target node with the
      * Nanosplash root element.
      * @param {Node} targetNode
@@ -206,7 +206,7 @@ export class SplashInstance implements IdentityInterface {
     {
         const fnNotSameInstance = (v: SplashInstance) => v.getId() !== this.getId()
         const fnDelete = (v: SplashInstance) => v.delete()
-        this.nsInstance.getSplashesWithDestinationNode(destinationNode).filter(fnNotSameInstance).forEach(fnDelete)
+        this.nsInstance.getFromDestinationNode(destinationNode).filter(fnNotSameInstance).forEach(fnDelete)
     }
 
     /**
@@ -216,28 +216,34 @@ export class SplashInstance implements IdentityInterface {
      */
     public moveTo(destination: Destination): void
     {
-        // Clean up and restore previous location if any.
-        this.cleanAndRestore()
+        try {
+            // Clean up and restore previous location if any.
+            this.cleanAndRestore()
 
-        // Convert the destination into a DOM Node
-        this.destinationNode = NanosplashRepository.destinationToNode(destination)
+            // Convert the destination into a DOM Node
+            this.destinationNode = NanosplashRepository.destinationToNode(destination)
 
-        // Replace splash instances having the same destination node
-        this.replaceSplashInstancesHavingSameDestination(this.destinationNode)
+            // Replace splash instances having the same destination node
+            this.replaceSplashInstancesHavingSameDestination(this.destinationNode)
 
-        // Assess whether the destination node is the Document body or not
-        const targetIsBody = this.destinationNode === document.body
+            // Assess whether the destination node is the Document body or not
+            const targetIsBody = this.destinationNode === document.body
 
+            if (targetIsBody) {
+                this.moveWithFullscreenStrategy()
+            } else {
+                this.resetFullscreenAttributes()
+                this.moveWithRegularStrategy(this.destinationNode)
+            }
 
-        if (targetIsBody) {
-            this.moveWithFullscreenStrategy()
-        } else {
-            this.resetFullscreenAttributes()
-            this.moveWithRegularStrategy(this.destinationNode)
+            // Assemble the Nanosplash component
+            this.assembleNSComponent()
+        } catch (e) {
+            this.delete()
+            if (this.nsInstance.debug) {
+                console.warn(e)
+            }
         }
-
-        // Assemble the Nanosplash component
-        this.assembleNSComponent()
     }
 
     /**

package/src/Exceptions/DestinationException.ts

@@ -0,0 +1,13 @@
+import Exception from "./Exception";
+import {Destination} from "../types";
+
+class DestinationException extends Exception {
+    public destination: Destination
+    public constructor(message: string, destination: Destination, cause: Exception) {
+        super(message);
+        this.destination = destination
+        this.cause = cause
+    }
+}
+
+export default DestinationException

package/src/Exceptions/Exception.ts

@@ -0,0 +1,9 @@
+class Exception extends Error {
+    public constructor(message?: string, cause?: Exception) {
+        super(message);
+        this.name = this.constructor.name
+        this.cause = cause
+    }
+}
+
+export default Exception

package/src/Exceptions/IllegalArgumentException.ts

@@ -0,0 +1,11 @@
+import Exception from "./Exception";
+
+class IllegalArgumentException extends Exception {
+    public argument: any
+    public constructor(message: string, argument: any) {
+        super(message);
+        this.argument = argument
+    }
+}
+
+export default IllegalArgumentException

package/src/Factory/NanosplashFactory.ts

@@ -1,9 +1,23 @@
-import {ProgressFunction, ShowFunction, SplashJob, WhileFunction} from "../types";
-import {Nanosplash} from "../Core/Nanosplash";
+import Nanosplash from "../Core/Nanosplash";
 import {SplashInstance} from "../Core/SplashInstance";
-import {NanosplashRepository} from "../repositories/NanosplashRepository";
+import {NanosplashRepository} from "../Repositories/NanosplashRepository";
+import {ContextualAPIObject, ProgressFunction, ShowFunction, SplashJob, WhileFunction} from "../types";
+import {ShowInterface} from "../Interfaces/ShowInterface";
 
+/**
+ * # Nanosplash Factory
+ * @author Isak K. Hauge
+ */
 export class NanosplashFactory {
+    /**
+     * # Ensure Instance
+     * Returns and modifies the splash instance, or creates a new one.
+     * @param {SplashInstance | null} splash Splash instance
+     * @param {Nanosplash} ns Nanosplash instance
+     * @param {string} text Splash text
+     * @param {string | undefined} imgSrc Splash image URL
+     * @private
+     */
     private static ensureInstance(
         splash: SplashInstance | null,
         ns: Nanosplash,
@@ -17,9 +31,15 @@ export class NanosplashFactory {
         return splash.setText(text).setImgSrc(splash.getImgSrc() ?? imgSrc)
     }
 
+    /**
+     * # Create Show Function
+     * @param ns
+     * @param splash
+     * @return {ShowFunction} A curried function made for a specific splash instance.
+     */
     public static createShowFunction(ns: Nanosplash, splash: SplashInstance | null): ShowFunction
     {
-        return (text: string) => {
+        return (text: string): ContextualAPIObject => {
             splash = NanosplashFactory.ensureInstance(splash, ns, text)
             ns.instances.set(splash.getId(), splash)
             splash.moveTo(document.body)
@@ -27,6 +47,12 @@ export class NanosplashFactory {
         }
     }
 
+    /**
+     * # Create Progress Function
+     * @param ns
+     * @param splash
+     * @return {ProgressFunction} A curried API function made for a specific splash instance.
+     */
     public static createProgressFunction(ns: Nanosplash, splash: SplashInstance | null): ProgressFunction
     {
         return (...jobs: SplashJob[]) => {
@@ -43,9 +69,15 @@ export class NanosplashFactory {
         }
     }
 
+    /**
+     * # Create While Function
+     * @param ns
+     * @param splash
+     * @return {ProgressFunction} A curried API function made for a specific splash instance.
+     */
     public static createWhileFunction(ns: Nanosplash, splash: SplashInstance): WhileFunction
     {
-        return (asyncTask: Promise<any>) => {
+        return (asyncTask: Promise<any>): ShowInterface => {
             splash = NanosplashFactory.ensureInstance(splash, ns, '')
             return {
                 show(text: string) {

package/src/Interfaces/NanosplashInterface.ts

@@ -1,3 +1,8 @@
 import {StrategyObject} from "../types";
+import {SplashInstance} from "../Core/SplashInstance";
 
-export interface NanosplashInterface extends StrategyObject {}
+export interface NanosplashInterface extends StrategyObject {
+    delete(splashInstance: SplashInstance): void
+    hideAll(): void
+    hide(id?: string): void
+}

package/src/{repositories → Repositories}/NanosplashRepository.ts

@@ -1,22 +1,49 @@
-import {addClass, get, mk} from "../utilities/dom";
+import Exception from "../Exceptions/Exception";
+import {addClass, get, mk} from "../Utilities/dom";
 import {SplashInstance} from "../Core/SplashInstance";
 import {ContextualAPIObject, Destination} from "../types";
+import DestinationException from "../Exceptions/DestinationException";
+import IllegalArgumentException from "../Exceptions/IllegalArgumentException";
 
 export class NanosplashRepository {
+    /**
+     * # Destination To Node
+     * Converts a Destination type into an HTMLElement.
+     * @param {Destination} destination Either a node or a CSS selector.
+     * @throws DestinationException
+     * @throws IllegalArgumentException
+     */
     public static destinationToNode(destination: Destination): HTMLElement
     {
         if (typeof destination === 'string') {
-            const element = get<HTMLElement>(destination)
-            if (!element) {
-                throw new Error(`No match with ${destination}`)
+            try {
+                const element = get<HTMLElement>(destination)
+                if (!element) {
+                    throw new Exception(`No DOM match with ${destination}`)
+                }
+                return element
+            } catch (e) {
+                throw new DestinationException(
+                    `Destination (${destination}) is either invalid or non-existing in DOM`,
+                    destination,
+                    e as Exception
+                )
             }
-            return element
         } else if (destination instanceof Node) {
             return destination as HTMLElement
         }
-        throw new Error('Destination argument must string or Node')
+
+        throw new IllegalArgumentException(
+            `Destination (${destination}) must be either a Node or a CSS selector`,
+            destination
+        )
     }
 
+    /**
+     * # Create Contextual API Object
+     * Creates an object containing props that adhere to the ns API.
+     * @param {SplashInstance} splash
+     */
     public static createContextualApiObject(splash: SplashInstance): ContextualAPIObject
     {
         const ctx = {
@@ -37,6 +64,10 @@ export class NanosplashRepository {
         }
     }
 
+    /**
+     * # Create Nanosplash Spinner Element
+     * Returns a DIV element wrapping an SVG element.
+     */
     public static createNanosplashSpinnerElement(): HTMLDivElement
     {
         const div = mk('div') as HTMLDivElement

package/src/{utilities → Tests}/dom.spec.ts

@@ -1,8 +1,9 @@
-import {addClass, get, mk, move, setAttr} from "./dom";
+import {test} from "vitest"
+import {addClass, get, mk, move, setAttr} from "../Utilities/dom"
 
 const resetDOM = () => document.body.innerHTML = ''
 
-test('Single DOM get function', () => {
+test('Get DOM element function', () => {
 	const element = document.createElement('div')
 	element.id = 'a'
 	element.classList.add('b')
@@ -48,9 +49,10 @@ test('Move Element from origin to destination', () => {
 })
 
 test('Make HTML Element', () => {
-	document.body.appendChild(mk('span'))
-	const span = document.body.children.item(0) as Node
-	expect(span instanceof HTMLSpanElement).toBe(true)
+	const span = mk('span')
+	document.body.appendChild(span)
+	const spanFromDom = document.body.children.item(0) as Node
+	expect(spanFromDom instanceof HTMLSpanElement).toBe(true)
 	resetDOM()
 })
 

package/src/{utilities → Utilities}/dom.ts

@@ -1,9 +1,21 @@
 import {ElementTag} from "../types";
 
+/**
+ * # Get
+ * Helper function to get Elements from the DOM using CSS selector.
+ * @param {string} selector CSS Selector.
+ */
 export function get<T>(selector: string): HTMLElement | T | null {
     return document.querySelector(selector) as HTMLElement | T | null
 }
 
+/**
+ * # Move
+ * Helper function that can move a node inside another node.
+ * @param {Node} source The node to be moved.
+ * @param {Node} destination The destination node.
+ * @param {boolean} asFirstChild Append or prepend the new node inside the child list.
+ */
 export function move(source: Node, destination: Node, asFirstChild: boolean = false): void
 {
     if (source && destination) {
@@ -13,8 +25,19 @@ export function move(source: Node, destination: Node, asFirstChild: boolean = fa
     }
 }
 
+/**
+ * # Make
+ * Short hand helper function that creates Nodes.
+ * @param {ElementTag} tag
+ */
 export const mk = (tag: ElementTag) => document.createElement(tag)
 
+/**
+ * # Add Class
+ * Helper class that easily adds classes to an element.
+ * @param {HTMLElement} node The node
+ * @param {...string[]} classes
+ */
 export function addClass(node: HTMLElement, ...classes: string[]): void
 {
     node.classList.add(...classes)

package/src/main.ts

@@ -1,8 +1,5 @@
-import {Nanosplash} from "./Core/Nanosplash";
-import {NanosplashOptions} from "./types";
+import Nanosplash from "./Core/Nanosplash";
 window.addEventListener('load', () => {
     window.Nanosplash = Nanosplash
-    window.installNanosplash = (options?: NanosplashOptions) => {
-        window.ns = new Nanosplash(options)
-    }
+    window.ns = new Nanosplash()
 })