nanosplash 2.4.0 → 2.5.0

package/index.html

@@ -15,6 +15,21 @@
 		<div class="w-100 min-h-screen flex flex-col justify-center items-center">
 			<div class="text-4xl text-slate-900 drop-shadow-lg">Nanosplash</div>
 			<div class="text-pink-500 mt-3 font-mono text-sm">ns.show('text').inside('#id')</div>
+			<div class="flex gap-5">
+				<div
+						id="demo"
+						class="bg-pink-500 text-pink-200 p-3 cursor-pointer hover:text-white rounded-xl shadow-xl mt-8"
+				>
+					<i class="lni lni-play"></i>
+					Display demo
+				</div>
+				<a
+						href="#example"
+						class="bg-slate-500 text-slate-200 p-3 cursor-pointer hover:text-white rounded-xl shadow-xl mt-8"
+				>
+					Show examples
+				</a>
+			</div>
 			<div class="flex flex-col space-y-2 my-10">
 				<div class="flex space-x-2 justify-center">
 					<img src="https://badgen.net/npm/v/nanosplash" />
@@ -38,9 +53,9 @@
 				<a href="https://www.npmjs.com/package/nanosplash" target="_blank"><i class="lni lni-npm text-4xl hover:text-pink-500 px-5"></i></a>
 				<a href="https://github.com/isakhauge/nanosplash" target="_blank"><i class="lni lni-github-original text-2xl hover:text-pink-500 px-5"></i></a>
 			</div>
-			<a class="mt-10 text-pink-300 hover:text-pink-500" href="/typedoc">API Reference Documentation</a>
+			<a class="mt-10 text-pink-300 hover:text-pink-500" href="https://rawcdn.githack.com/isakhauge/nanosplash/0a6cdef58b0e47c0cad911952b1a329df58d2c24/docs/typedoc/index.html">API Reference Documentation</a>
 		</div>
-		<div class="grid grid-cols-1 xl:grid-cols-2 gap-1">
+		<div id="example" class="grid grid-cols-1 xl:grid-cols-2 gap-1">
 			<div id="a" class="p-20 bg-slate-100 flex flex-col items-center">
 				<div class="text-xl mb-10">Give user progress feedback</div>
 				<div class="text-white bg-slate-800 p-5 rounded-xl shadow-2xl font-mono text-sm break-all">
@@ -60,9 +75,7 @@
 			<div id="c" class="p-20 bg-slate-100 flex flex-col items-center">
 				<div class="text-xl mb-10">Display fullscreen</div>
 				<div class="text-white bg-slate-800 p-5 rounded-xl shadow-2xl font-mono text-sm break-all">
-					const splash = ns.show('Fullscreen text')<br>
-					splash.moveTo('#myDiv')<br>
-					splash.remove()
+					ns.show('Fullscreen text')
 				</div>
 			</div>
 			<div id="d" class="p-20 bg-slate-100 flex flex-col items-center">
@@ -70,26 +83,43 @@
 				<div class="text-white bg-slate-800 p-5 rounded-xl shadow-2xl font-mono text-sm break-all">
 					ns.show('Loading component A').inside('#a')<br>
 					ns.show('Loading component B').inside('#b')<br>
-					ns.show('Loading component C').inside('#c')<br>
-					<br><br>
-					ns.hide() // Removes instances in a LIFO manner.<br>
-					ns.hideAll() // Removes all instances.
+					ns.show('Loading component C').inside('#c')
+				</div>
+			</div>
+			<div id="e" class="p-20 bg-slate-100 flex flex-col items-center">
+				<div class="text-xl mb-10">Move splash instance to another destination</div>
+				<div class="text-white bg-slate-800 p-5 rounded-xl shadow-2xl font-mono text-sm break-all">
+					const splash = ns.show('Loading').inside('#a')<br>
+					splash.moveTo('#b')
+				</div>
+			</div>
+			<div id="f" class="p-20 bg-slate-100 flex flex-col items-center">
+				<div class="text-xl mb-10">Hide splash instances</div>
+				<div class="text-white bg-slate-800 p-5 rounded-xl shadow-2xl font-mono text-sm break-all">
+					// Hides one instance at a time, in a LIFO-fashion.<br>
+					ns.hide()<br><br>
+					// Hides all instances.<br>
+					ns.hideAll()
 				</div>
 			</div>
 		</div>
 		<footer>
 			<script type="module" src="/src/main.ts"></script>
 			<script>
+				document.getElementById('demo').onclick = function () {
+					const wait = ms => new Promise(r => setTimeout(r, ms))
+					window.ns.progress(
+						[wait(2000), 'Loading data from API'],
+						[wait(4000), 'Restructuring'],
+						[wait(6000), 'Indexing'],
+						[wait(8000), 'Give this repo a star']
+					)
+				}
 				document.getElementById('copy').onclick = function () {
 					const text = document.querySelector('[data-copy]').innerText
 					navigator.clipboard.writeText(text)
 					alert('Copied to clipboard!')
 				}
-				window.onload = () => {
-					setTimeout(() => {
-						window.installNanosplash({spinner: true})
-					}, 100)
-				}
 			</script>
 		</footer>
 		<style>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nanosplash",
   "description": "The simple, tiny loading screen",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "author": {
     "name": "Isak K. Hauge",
     "email": "isakhauge@gmail.com",

package/src/Core/Nanosplash.ts

@@ -1,20 +1,22 @@
 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 {InstanceIterationCallback, NanosplashOptions, SplashJob} from "../types";
 
 /**
  * # 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 imgSrc: string | undefined
+    private spinner: boolean
+    private fontSize: string
     public readonly instances: Map<string, SplashInstance>
 
     /**
@@ -22,12 +24,70 @@ 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.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
@@ -65,11 +125,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,18 +152,49 @@ 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 idOrSelector 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)
+    public hide(idOrSelector?: string): void {
+        if (idOrSelector) {
+            const splashInstance = this.instances.get(idOrSelector)
             if (splashInstance) {
                 splashInstance.delete()
             } else {
-                throw new Error(
-                    `Could not find element with id: ${id}`
-                )
+                Array.from(this.instances.values())
+                    .filter((splashInstance: SplashInstance) => {
+                        return splashInstance.getDestination() === get<HTMLElement>(idOrSelector)
+                    })
+                    .forEach((splashInstance: SplashInstance) => splashInstance.delete())
             }
         } else {
             const n = this.instances.size
@@ -123,13 +209,15 @@ export class Nanosplash implements NanosplashInterface {
     }
 
     /**
-     * # 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,5 +1,5 @@
 import {Destination} from "../types";
-import {Nanosplash} from "./Nanosplash";
+import Nanosplash from "./Nanosplash";
 import {addClass, mk, move, setAttr} from "../utilities/dom";
 import {IdentityInterface} from "../Interfaces/IdentityInterface";
 import {NanosplashRepository} from "../repositories/NanosplashRepository";
@@ -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)
     }
 
     /**
@@ -228,7 +228,6 @@ export class SplashInstance implements IdentityInterface {
         // Assess whether the destination node is the Document body or not
         const targetIsBody = this.destinationNode === document.body
 
-
         if (targetIsBody) {
             this.moveWithFullscreenStrategy()
         } else {

package/src/Factory/NanosplashFactory.ts

@@ -1,9 +1,22 @@
-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 {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,6 +30,12 @@ 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) => {
@@ -27,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[]) => {
@@ -43,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,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/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()
 })

package/src/repositories/NanosplashRepository.ts

@@ -3,6 +3,11 @@ 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,6 +22,11 @@ export class NanosplashRepository {
         throw new Error('Destination argument must string or Node')
     }
 
+    /**
+     * # 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 +47,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/types.d.ts

@@ -1,7 +1,8 @@
-import {Nanosplash} from "./Core/Nanosplash";
+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 {
@@ -11,8 +12,8 @@ declare global {
 	}
 }
 
-type Destination = Node | string
-type SplashJob = [Promise<any>, string]
+export type Destination = Node | string
+export type SplashJob = [Promise<any>, string]
 
 /**
  * @internal
@@ -24,17 +25,17 @@ export type ElementTag = keyof HTMLElementTagNameMap | keyof SVGElementTagNameMa
  */
 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,10 +45,13 @@ type ContextualAPIObject = {
 	getImgSrc: () => string | undefined,
 	setImgSrc: (src?: string) => SplashInstance
 }
-type InstanceIterationCallback = (id: string, splashInstance: SplashInstance, i: number) => boolean
 
-type NanosplashOptions = {
+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 {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/vite.mod.config.js

@@ -10,7 +10,7 @@ export default defineConfig({
 			formats: ['es', 'cjs'],
 		},
 		outDir: 'dist/module',
-		cssCodeSplit: true,
+		cssCodeSplit: false,
 		minify: 'terser',
 		terserOptions: {
 			parse: {
@@ -28,7 +28,10 @@ export default defineConfig({
 			mangle: {
 				toplevel: true,
 				// Reserved class names
-				reserved: [],
+				reserved: [
+					'Nanosplash',
+					'SplashInstance'
+				],
 				properties: {
 					reserved: [
 						'ns',
@@ -37,9 +40,12 @@ export default defineConfig({
 						'setText',
 						'getImgSrc',
 						'setImgSrc',
+						'showSpinner',
+						'setFontSize',
+						'getFontSize',
+						'spinnerIsVisible',
 						'moveTo',
 						'delete',
-						'img',
 						'show',
 						'inside',
 						'remove',
@@ -48,6 +54,8 @@ export default defineConfig({
 						'delete',
 						'hideAll',
 						'hide',
+						'getFromDestinationNode',
+						'getDestination'
 					],
 				}
 			},