nanosplash 2.3.3 → 2.4.0

package/src/Core/SplashInstance.ts

@@ -4,6 +4,10 @@ import {addClass, mk, move, setAttr} from "../utilities/dom";
 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
@@ -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.fontSize
+        this.nsSpinnerElement.style.display = ns.showSpinner ? '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,12 +185,23 @@ 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()
@@ -123,6 +209,11 @@ export class SplashInstance implements IdentityInterface {
         this.nsInstance.getSplashesWithDestinationNode(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.
@@ -149,20 +240,38 @@ export class SplashInstance implements IdentityInterface {
         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 +280,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/Factory/NanosplashFactory.ts

@@ -1,4 +1,4 @@
-import {ImgFunction, ProgressFunction, ShowFunction, SplashJob, WhileFunction} from "../types";
+import {ProgressFunction, ShowFunction, SplashJob, WhileFunction} from "../types";
 import {Nanosplash} from "../Core/Nanosplash";
 import {SplashInstance} from "../Core/SplashInstance";
 import {NanosplashRepository} from "../repositories/NanosplashRepository";
@@ -17,18 +17,6 @@ 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)
-            }
-        }
-    }
-
     public static createShowFunction(ns: Nanosplash, splash: SplashInstance | null): ShowFunction
     {
         return (text: string) => {

package/src/Interfaces/NanosplashInterface.ts

@@ -1,4 +1,3 @@
 import {StrategyObject} from "../types";
-import {ImageInterface} from "./ImageInterface";
 
-export interface NanosplashInterface extends StrategyObject, ImageInterface {}
+export interface NanosplashInterface extends StrategyObject {}

package/src/main.ts

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

package/src/repositories/NanosplashRepository.ts

@@ -1,4 +1,4 @@
-import {get} from "../utilities/dom";
+import {addClass, get, mk} from "../utilities/dom";
 import {SplashInstance} from "../Core/SplashInstance";
 import {ContextualAPIObject, Destination} from "../types";
 
@@ -36,4 +36,16 @@ export class NanosplashRepository {
             },
         }
     }
+
+    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

@@ -5,6 +5,8 @@ import {ContextualAPIInterface} from "./Interfaces/ContextualAPIInterface";
 
 declare global {
 	interface Window {
+		Nanosplash: typeof Nanosplash
+		installNanosplash: (options?: NanosplashOptions) => void
 		ns: Nanosplash
 	}
 }
@@ -15,7 +17,7 @@ type SplashJob = [Promise<any>, string]
 /**
  * @internal
  */
-export type HTMLElementTag = keyof HTMLElementTagNameMap
+export type ElementTag = keyof HTMLElementTagNameMap | keyof SVGElementTagNameMap
 
 /**
  * @internal
@@ -42,8 +44,10 @@ type ContextualAPIObject = {
 	getImgSrc: () => string | undefined,
 	setImgSrc: (src?: string) => SplashInstance
 }
+type InstanceIterationCallback = (id: string, splashInstance: SplashInstance, i: number) => boolean
 
-declare module 'nanosplash' {
-	class Nanosplash {}
-	class SplashInstance {}
+type NanosplashOptions = {
+	imgSrc?: string,
+	spinner?: boolean,
+	fontSize?: string
 }

package/src/utilities/dom.ts

@@ -1,4 +1,4 @@
-import {HTMLElementTag} from "../types";
+import {ElementTag} from "../types";
 
 export function get<T>(selector: string): HTMLElement | T | null {
     return document.querySelector(selector) as HTMLElement | T | null
@@ -13,7 +13,7 @@ export function move(source: Node, destination: Node, asFirstChild: boolean = fa
     }
 }
 
-export const mk = (tag: HTMLElementTag) => document.createElement(tag)
+export const mk = (tag: ElementTag) => document.createElement(tag)
 
 export function addClass(node: HTMLElement, ...classes: string[]): void
 {

package/src/Interfaces/ImageInterface.ts

@@ -1,5 +0,0 @@
-import {ImgFunction} from "../types";
-
-export interface ImageInterface {
-    img: ImgFunction
-}