nanosplash 2.3.3 → 2.5.1

package/src/Core/SplashInstance.ts

@@ -1,9 +1,13 @@
 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
+ * @author Isak K. Hauge <isakhauge@gmail.com>
+ */
 export class SplashInstance implements IdentityInterface {
     private readonly id: string
     private imgSrc: string | undefined
@@ -11,11 +15,18 @@ export class SplashInstance implements IdentityInterface {
     private destinationNode: HTMLElement | undefined
     private readonly nsRootElement: HTMLDivElement = mk('div') as HTMLDivElement
     private readonly nsTextElement: HTMLDivElement = mk('div') as HTMLDivElement
+    private readonly nsTextContainerElement: HTMLDivElement = mk('div') as HTMLDivElement
+    private readonly nsSpinnerElement: HTMLDivElement = NanosplashRepository.createNanosplashSpinnerElement()
     private readonly nsWindowElement: HTMLDivElement = mk('div') as HTMLDivElement
     private readonly nsWrapperElement: HTMLDivElement = mk('div') as HTMLDivElement
     private readonly nsContentElement: HTMLDivElement = mk('div') as HTMLDivElement
     private readonly nsImageElement: HTMLImageElement = mk('img') as HTMLImageElement
 
+    /**
+     * @param {Nanosplash} ns Nanosplash instance
+     * @param {string} text Text
+     * @param {string|undefined} imgSrc Image source URL
+     */
     public constructor(ns: Nanosplash, text: string, imgSrc?: string) {
         this.id = Math.random().toString(36).substring(2)
         this.nsInstance = ns
@@ -25,27 +36,48 @@ export class SplashInstance implements IdentityInterface {
         this.nsImageElement.src = this.imgSrc ?? ''
         this.nsImageElement.alt = Nanosplash.APP_NAME
 
+        this.nsRootElement.style.fontSize = ns.getFontSize()
+        this.nsSpinnerElement.style.display = ns.spinnerIsVisible() ? 'flex' : 'none'
+
         this.assembleNSComponent()
         this.setImgSrc(imgSrc)
     }
 
+    /**
+     * # Assign CSS Classes
+     * Assigns CSS class names to all elements connected to this splash instance.
+     * @private
+     */
     private assignCSSClasses(): void
     {
         addClass(this.nsContentElement, 'ns-container')
         addClass(this.nsWrapperElement, 'ns-blur')
         addClass(this.nsImageElement, 'ns-img')
         addClass(this.nsTextElement, 'ns-text')
+        addClass(this.nsTextContainerElement, 'ns-text-container')
+        addClass(this.nsSpinnerElement, 'ns-spinner')
         addClass(this.nsWindowElement, 'ns', 'ns-window')
         addClass(this.nsRootElement, 'ns-wrapper')
     }
 
+    /**
+     * # Assemble Element Structure
+     * Assembles all elements connected to this splash instance in a fixed structure.
+     * @private
+     */
     private assembleElementStructure(): void
     {
-        this.nsContentElement.append(this.nsImageElement, this.nsTextElement)
+        this.nsTextContainerElement.append(this.nsTextElement, this.nsSpinnerElement)
+        this.nsContentElement.append(this.nsImageElement, this.nsTextContainerElement)
         this.nsWindowElement.append(this.nsContentElement)
         this.nsRootElement.append(this.nsWrapperElement, this.nsWindowElement)
     }
 
+    /**
+     * # Assemble Nanosplash Component
+     * Assembles all elements into one component that represents the Nanosplash component.
+     * @private
+     */
     private assembleNSComponent(): void {
         this.nsRootElement.id = this.getId()
         setAttr(this.nsRootElement, 'data-ctx', 'nanosplash')
@@ -53,26 +85,48 @@ export class SplashInstance implements IdentityInterface {
         this.assignCSSClasses()
     }
 
+    /**
+     * # Get ID
+     * @return string
+     */
     public getId(): string
     {
         return this.id
     }
 
+    /**
+     * Get Text
+     * @return string
+     */
     public getText(): string
     {
         return this.nsTextElement.innerText
     }
 
+    /**
+     * # Set Text
+     * @param {string} text Text
+     * @return SplashInstance
+     */
     public setText(text: string): SplashInstance {
         this.nsTextElement.innerText = text
         return this
     }
 
+    /**
+     * # Get Image Source
+     * @return string | undefined
+     */
     public getImgSrc(): string | undefined
     {
         return this.imgSrc
     }
 
+    /**
+     * # Set Image Source
+     * @param {string|undefined} src Source URL
+     * @return SplashInstance
+     */
     public setImgSrc(src?: string): SplashInstance
     {
         this.nsImageElement.src = src ?? ''
@@ -81,11 +135,20 @@ export class SplashInstance implements IdentityInterface {
         return this
     }
 
+    /**
+     * # Get Destination
+     * @return HTMLElement | undefined
+     */
     public getDestination(): HTMLElement | undefined
     {
         return this.destinationNode
     }
 
+    /**
+     * # Clean And Restore
+     * Cleans and restore the DOM structure.
+     * @private
+     */
     private cleanAndRestore(): void
     {
         const currentParent = this.nsRootElement.parentElement
@@ -94,12 +157,24 @@ export class SplashInstance implements IdentityInterface {
         }
     }
 
+    /**
+     * # Reset Fullscreen Attributes
+     * Removes the fullscreen attributes and CSS class names.
+     * @private
+     */
     private resetFullscreenAttributes(): void
     {
         setAttr(this.nsRootElement, 'style', '')
         this.nsRootElement.classList.remove('ns-fs')
     }
 
+    /**
+     * # 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
+     * @private
+     */
     private moveWithRegularStrategy(targetNode: Node): void
     {
         const targetParentNode = targetNode.parentNode
@@ -110,59 +185,96 @@ export class SplashInstance implements IdentityInterface {
         }
     }
 
+    /**
+     * # Move With Fullscreen Strategy
+     * Moves the Nanosplash root element inside the body element.
+     * @private
+     */
     private moveWithFullscreenStrategy(): void
     {
         this.nsRootElement.classList.add('ns-fs')
         move(this.nsRootElement, document.body, true)
     }
 
+    /**
+     * # Replace Splash Instances Having Same Destination
+     * Delete all Splash instances residing inside the same destination node.
+     * @param {HTMLElement} destinationNode
+     * @private
+     */
     private replaceSplashInstancesHavingSameDestination(destinationNode: HTMLElement): void
     {
         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)
     }
 
+    /**
+     * # Move To
+     * This function moves the Nanosplash root element to a destination.
+     * @param {Destination} destination
+     */
     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) {
+            console.warn(e)
         }
-
-        // Assemble the Nanosplash component
-        this.assembleNSComponent()
     }
 
+    /**
+     * # For Each Wrapped Node
+     * Invokes a callback for each wrapped node.
+     * @param {(node: Node) => void} callback
+     * @private
+     */
     private forEachWrappedNode(callback: (node: Node) => void): void
     {
         Array.from(this.nsWrapperElement.childNodes).forEach(callback)
     }
 
+    /**
+     * # Restore DOM Structure
+     * Undo the node wrapping and restore the wrapped nodes' original DOM position.
+     * @param {Node} parentNode
+     * @private
+     */
     private restoreDOMStructure(parentNode: Node): void
     {
         this.forEachWrappedNode((child: Node) => parentNode.insertBefore(child, this.nsRootElement))
     }
 
+    /**
+     * # Remove Elements From DOM
+     * @private
+     */
     private removeElementsFromDOM(): void
     {
         [
             this.nsTextElement,
+            this.nsSpinnerElement,
+            this.nsTextContainerElement,
             this.nsImageElement,
             this.nsContentElement,
             this.nsWrapperElement,
@@ -171,6 +283,10 @@ export class SplashInstance implements IdentityInterface {
         ].forEach(v => v.remove())
     }
 
+    /**
+     * # Delete
+     * Gracefully delete Splash instance and connected elements from DOM.
+     */
     public delete(): void {
         this.cleanAndRestore()
         this.removeElementsFromDOM()

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 {ImgFunction, 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,21 +31,15 @@ export class NanosplashFactory {
         return splash.setText(text).setImgSrc(splash.getImgSrc() ?? imgSrc)
     }
 
-    public static createImgFunction(ns: Nanosplash, splash: SplashInstance | null): ImgFunction
-    {
-        return (src: string) => {
-            splash = NanosplashFactory.ensureInstance(splash, ns, '', src)
-            return {
-                show: NanosplashFactory.createShowFunction(ns, splash),
-                progress: NanosplashFactory.createProgressFunction(ns, splash),
-                while: NanosplashFactory.createWhileFunction(ns, splash)
-            }
-        }
-    }
-
+    /**
+     * # 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)
@@ -39,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[]) => {
@@ -55,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,4 +1,8 @@
 import {StrategyObject} from "../types";
-import {ImageInterface} from "./ImageInterface";
+import {SplashInstance} from "../Core/SplashInstance";
 
-export interface NanosplashInterface extends StrategyObject, ImageInterface {}
+export interface NanosplashInterface extends StrategyObject {
+    delete(splashInstance: SplashInstance): void
+    hideAll(): void
+    hide(id?: string): void
+}

package/src/Repositories/NanosplashRepository.ts

@@ -0,0 +1,82 @@
+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') {
+            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
+                )
+            }
+        } else if (destination instanceof Node) {
+            return destination as HTMLElement
+        }
+
+        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 = {
+            getId: () => splash.getId(),
+            remove: () => splash.delete(),
+            moveTo: (selector: string) => splash.moveTo(selector),
+            getText: () => splash.getText(),
+            setText: (text: string) => splash.setText(text),
+            getImgSrc: () => splash.getImgSrc(),
+            setImgSrc: (src?: string) => splash.setImgSrc(src)
+        }
+        return {
+            ...ctx,
+            inside: (selector: string) => {
+                splash.moveTo(selector)
+                return ctx
+            },
+        }
+    }
+
+    /**
+     * # Create Nanosplash Spinner Element
+     * Returns a DIV element wrapping an SVG element.
+     */
+    public static createNanosplashSpinnerElement(): HTMLDivElement
+    {
+        const div = mk('div') as HTMLDivElement
+        addClass(div, 'ns-spinner')
+        div.innerHTML = `
+            <svg viewBox="0 0 50 50">
+                <circle class="path" cx="25" cy="25" r="20" fill="none"></circle>
+            </svg>
+        `
+        return div
+    }
+}

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/dom.ts

@@ -0,0 +1,49 @@
+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) {
+        (destination.hasChildNodes() && asFirstChild)
+            ? destination.insertBefore(source, destination.firstChild)
+            : destination.appendChild(source)
+    }
+}
+
+/**
+ * # 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)
+}
+
+export function setAttr(node: HTMLElement, attribute: string, value: string): void
+{
+    node.setAttribute(attribute, value)
+}

package/src/main.ts

@@ -1,2 +1,5 @@
-import {Nanosplash} from "./Core/Nanosplash";
-window.addEventListener('load', () => window.ns = new Nanosplash())
+import Nanosplash from "./Core/Nanosplash";
+window.addEventListener('load', () => {
+    window.Nanosplash = Nanosplash
+    window.ns = new Nanosplash()
+})