nanosplash 2.3.2 → 2.5.0

package/src/Core/SplashInstance.ts

@@ -1,20 +1,32 @@
 import {Destination} from "../types";
-import {Nanosplash} from "./Nanosplash";
+import Nanosplash from "./Nanosplash";
 import {addClass, mk, move, setAttr} from "../utilities/dom";
-import {NanosplashRepository} from "../repositories/NanosplashRepository";
 import {IdentityInterface} from "../Interfaces/IdentityInterface";
+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
     private readonly nsInstance: Nanosplash
+    private destinationNode: HTMLElement | undefined
     private readonly nsRootElement: HTMLDivElement = mk('div') as HTMLDivElement
-    private readonly nsWrapperElement: 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
-    private readonly nsTextElement: HTMLDivElement = mk('div') as HTMLDivElement
 
+    /**
+     * @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
@@ -24,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')
@@ -52,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 ?? ''
@@ -80,7 +135,21 @@ export class SplashInstance implements IdentityInterface {
         return this
     }
 
-    private cleanup(): void
+    /**
+     * # 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
         if (currentParent) {
@@ -88,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
@@ -104,40 +185,92 @@ 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.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
     {
-        this.cleanup()
-        const targetNode = NanosplashRepository.destinationToNode(destination)
-        const targetIsBody = targetNode === document.body
+        // Clean up and restore previous location if any.
+        this.cleanAndRestore()
+
+        // Convert the destination into a DOM Node
+        this.destinationNode = NanosplashRepository.destinationToNode(destination)
+
+        // 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
+
         if (targetIsBody) {
             this.moveWithFullscreenStrategy()
         } else {
             this.resetFullscreenAttributes()
-            this.moveWithRegularStrategy(targetNode)
+            this.moveWithRegularStrategy(this.destinationNode)
         }
+
+        // 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,
@@ -146,8 +279,12 @@ export class SplashInstance implements IdentityInterface {
         ].forEach(v => v.remove())
     }
 
+    /**
+     * # Delete
+     * Gracefully delete Splash instance and connected elements from DOM.
+     */
     public delete(): void {
-        this.cleanup()
+        this.cleanAndRestore()
         this.removeElementsFromDOM()
         this.nsInstance.delete(this)
     }

package/src/Factory/NanosplashFactory.ts

@@ -1,9 +1,22 @@
-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 {ProgressFunction, ShowFunction, SplashJob, WhileFunction} from "../types";
 
+/**
+ * # 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,18 +30,12 @@ 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) => {
@@ -39,6 +46,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,6 +68,12 @@ 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>) => {

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/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()
+})

package/src/repositories/NanosplashRepository.ts

@@ -1,8 +1,13 @@
-import {get} from "../utilities/dom";
+import {addClass, get, mk} from "../utilities/dom";
 import {SplashInstance} from "../Core/SplashInstance";
 import {ContextualAPIObject, Destination} from "../types";
 
 export class NanosplashRepository {
+    /**
+     * # Destination To Node
+     * Converts a Destination type into an HTMLElement.
+     * @param {Destination} destination Either a node or a CSS selector.
+     */
     public static destinationToNode(destination: Destination): HTMLElement
     {
         if (typeof destination === 'string') {
@@ -17,7 +22,13 @@ export class NanosplashRepository {
         throw new Error('Destination argument must string or Node')
     }
 
-    public static createContextualApiObject(splash: SplashInstance): ContextualAPIObject {
+    /**
+     * # 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(),
@@ -35,4 +46,20 @@ 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
+        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/style.sass

@@ -1,14 +1,17 @@
 $z-index-regular: 1
 $z-index-fullscreen: 2
+$text-color: #5a6685
 $bg-color: rgba(White, 0.8)
 
 %blur
   overflow: hidden
   filter: blur(5px)
 
+// Wraps the content replaced by Nanosplash
 .ns-wrapper
   position: relative
 
+// Only active while in fullscreen mode
 .ns-fs
   top: 0
   left: 0
@@ -17,10 +20,11 @@ $bg-color: rgba(White, 0.8)
   min-height: 100vh
   z-index: $z-index-fullscreen
 
-// Fullscreen content blur
+// Blurs the wrapped content
 body .ns-fs ~ *, .ns-blur
   @extend %blur
 
+// Nanosplash window containing image and text
 .ns-window
   top: 0
   left: 0
@@ -33,26 +37,52 @@ body .ns-fs ~ *, .ns-blur
   z-index: $z-index-regular
   background-color: $bg-color
 
+// Image
 .ns-img
-  max-width: 9rem
+  width: 9rem
   max-height: 9rem
-  margin-bottom: 1rem
+  margin-bottom: 2em
 
+// Text container containing text and spinner
+.ns-text-container
+  display: flex
+  justify-content: center
+  align-items: center
+
+// Text node
 .ns-text
-  color: #333
   display: flex
-  text-align: center
-  &::after
-    margin-left: 0.25em
-    content: '\00a0\00a0\00a0'
-    animation: anim 1s infinite
+  justify-content: center
+  color: $text-color
+
+// Spinner node
+.ns-spinner
+  display: flex
+  margin-left: 1em
+  width: 1em
+  height: 1em
+  & > svg
+    animation: Rotate 2s linear infinite
+    position: relative
+    width: inherit
+    height: inherit
+    stroke-width: 8
+  & .path
+    stroke: $text-color
+    stroke-linecap: round
+    animation: Dash 1.5s ease-in-out infinite
 
-@keyframes anim
+// Spinner animations:
+@keyframes Rotate
+  100%
+    transform: rotate(360deg)
+@keyframes Dash
   0%
-    content: '\00a0\00a0\00a0'
-  30%
-    content: '.\00a0\00a0'
-  60%
-    content: '..\00a0'
-  90%
-    content: '...'
+    stroke-dasharray: 1, 150
+    stroke-dashoffset: 0
+  50%
+    stroke-dasharray: 90, 150
+    stroke-dashoffset: -35
+  100%
+    stroke-dasharray: 90, 150
+    stroke-dashoffset: -124

package/src/types.d.ts

@@ -1,39 +1,41 @@
-import {Nanosplash} from "./Core/Nanosplash";
-import {ShowInterface} from "./Interfaces/ShowInterface";
-import {InsideInterface} from "./Interfaces/InsideInterface";
+import Nanosplash from "./Core/Nanosplash";
 import {SplashInstance} from "./Core/SplashInstance";
+import {ShowInterface} from "./Interfaces/ShowInterface";
 import {ContextualAPIInterface} from "./Interfaces/ContextualAPIInterface";
+import {NanosplashInterface} from "./Interfaces/NanosplashInterface";
 
 declare global {
 	interface Window {
+		Nanosplash: typeof Nanosplash
+		installNanosplash: (options?: NanosplashOptions) => void
 		ns: Nanosplash
 	}
 }
 
-type Destination = Node | string
-type SplashJob = [Promise<any>, string]
+export type Destination = Node | string
+export type SplashJob = [Promise<any>, string]
 
 /**
  * @internal
  */
-export type HTMLElementTag = keyof HTMLElementTagNameMap
+export type ElementTag = keyof HTMLElementTagNameMap | keyof SVGElementTagNameMap
 
 /**
  * @internal
  */
 type CSSProperty = keyof CSSStyleDeclaration
 
-type ShowFunction = (text: string) => ContextualAPIInterface
-type ProgressFunction = (...[]: SplashJob[]) => ContextualAPIInterface
-type WhileFunction = (asyncTask: Promise<any>) => ShowInterface
-type StrategyObject = {
+export type ShowFunction = (text: string) => ContextualAPIInterface
+export type ProgressFunction = (...[]: SplashJob[]) => ContextualAPIInterface
+export type WhileFunction = (asyncTask: Promise<any>) => ShowInterface
+export type StrategyObject = {
     show: ShowFunction,
     progress: ProgressFunction,
     while: WhileFunction
 }
-type ImgFunction = (src: string) => StrategyObject
-type InsideFunction = (selector: string) => ContextualAPIInterface
-type ContextualAPIObject = {
+
+export type InsideFunction = (selector: string) => ContextualAPIInterface
+export type ContextualAPIObject = {
 	getId: () => string,
 	inside?: InsideFunction,
 	remove: () => void
@@ -44,7 +46,12 @@ type ContextualAPIObject = {
 	setImgSrc: (src?: string) => SplashInstance
 }
 
-declare module 'nanosplash' {
-	class Nanosplash {}
-	class SplashInstance {}
+export type InstanceIterationCallback = (id: string, splashInstance: SplashInstance, i: number) => boolean
+
+export type NanosplashOptions = {
+	imgSrc?: string,
+	spinner?: boolean,
+	fontSize?: string
 }
+
+export default Nanosplash

package/src/utilities/dom.spec.ts

@@ -2,7 +2,7 @@ import {addClass, get, mk, move, setAttr} from "./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 +48,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

@@ -1,9 +1,21 @@
-import {HTMLElementTag} from "../types";
+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
     }
 }
 
-export const mk = (tag: HTMLElementTag) => document.createElement(tag)
+/**
+ * # 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)