nanosplash 3.0.0 → 3.0.2

package/src/ts/core/Splash.ts

@@ -0,0 +1,121 @@
+import { GUIDString } from '../types/Types'
+import { createElement, showElement, hideElement } from './DomUtilities'
+import { SplashInterface } from './SplashInterface'
+
+/**
+ * # Splash
+ * Small splash screen that can be used to indicate that a process
+ * is running.
+ * @author Isak K. Hauge <isakhauge@icloud.com>
+ */
+export class Splash implements SplashInterface {
+	/**
+	 * # CSS Class Name
+	 * The main CSS class name of the root element of a Nanosplash component.
+	 */
+	public static readonly NSClass = 'ns'
+
+	/**
+	 * # Host CSS Class Name
+	 * The CSS class name of the host element of a Nanosplash component.
+	 * The host element is the element that the Nanosplash is attached to.
+	 */
+	public static readonly NSHostClass = 'nsh'
+
+	/**
+	 * # ID
+	 * Each Nanosplash instance is given a unique GUID.
+	 */
+	private id: GUIDString | null
+
+	/**
+	 * # Element
+	 * The root element of the Nanosplash component.
+	 */
+	private element: HTMLDivElement | null
+
+	/**
+	 * # Generate GUID
+	 * @returns {GUIDString} A GUID string.
+	 * @private
+	 */
+	private static generateGUID(): GUIDString {
+		return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+			const r = (Math.random() * 16) | 0
+			const v = c === 'x' ? r : (r & 0x3) | 0x8
+			return v.toString(16)
+		})
+	}
+
+	/**
+	 * # Constructor
+	 * Creates a new Nanosplash instance.
+	 */
+	public constructor() {
+		this.element = createElement()
+		this.element.id = this.id = Splash.generateGUID()
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public getId(): GUIDString | null {
+		return this.id
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public getElement(): HTMLDivElement | null {
+		return <HTMLDivElement>this.element
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public getTextElement(): HTMLDivElement {
+		return (
+			<HTMLDivElement>(
+				this.getElement()?.firstElementChild?.firstElementChild
+			) ?? null
+		)
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public setText(text: string): Splash {
+		this.getTextElement().innerText = text
+		text.length > 0 ? this.showText() : this.hideText()
+		return this
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public showText(): Splash {
+		showElement(this.getTextElement())
+		return this
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public hideText(): Splash {
+		hideElement(this.getTextElement())
+		return this
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public delete(): boolean {
+		this.id = null
+		if (this.element !== null) {
+			this.element.innerHTML = ''
+			this.element.remove()
+			this.element = null
+		}
+		return this.element === null
+	}
+}

package/src/ts/core/SplashInterface.ts

@@ -0,0 +1,46 @@
+import { GUIDString } from '../types/Types'
+import { Splash } from './Splash'
+
+export interface SplashInterface {
+	/**
+	 * # Get ID
+	 * Return Nanosplash instance GUID.
+	 */
+	getId(): GUIDString | null
+
+	/**
+	 * # Get Element
+	 * Return Nanosplash instance HTMLDivElement.
+	 */
+	getElement(): HTMLDivElement | null
+
+	/**
+	 * # Get Text Element
+	 * Returns the text element of the Nanosplash.
+	 */
+	getTextElement(): HTMLDivElement | null
+
+	/**
+	 * # Set Text
+	 * @param text The text that will be visible inside the splash.
+	 */
+	setText(text: string): Splash
+
+	/**
+	 * # Show Text
+	 * Display text element.
+	 */
+	showText(): Splash
+
+	/**
+	 * # Hide Text
+	 * Hide the text element.
+	 */
+	hideText(): Splash
+
+	/**
+	 * # Delete
+	 * Remove from DOM and delete internal data.
+	 */
+	delete(): boolean
+}

package/src/ts/core/SplashQueue.ts

@@ -0,0 +1,49 @@
+import { GUIDString } from '../types/Types'
+import { Splash } from './Splash'
+
+export class SplashQueue {
+	public queue: Array<Splash>
+
+	constructor() {
+		this.queue = []
+	}
+
+	/**
+	 * # Enqueue
+	 * Add a new item to the queue.
+	 * @param item The item to add to the queue.
+	 */
+	public enqueue(item: Splash): SplashQueue {
+		this.queue.push(item)
+		return this
+	}
+
+	/**
+	 * # Dequeue
+	 * Remove the first item from the queue.
+	 * @returns The first item from the queue.
+	 */
+	public dequeue(): Splash | undefined {
+		return this.queue.shift()
+	}
+
+	/**
+	 * # Get
+	 * @param id The GUID of the Nanosplash to get.
+	 * @returns The Nanosplash with the given GUID.
+	 */
+	public get(id: GUIDString): Splash | undefined {
+		return this.queue.find(item => item.getId() === id)
+	}
+
+	/**
+	 * # Delete
+	 * @param id The GUID of the Nanosplash to delete.
+	 * @returns The deleted Nanosplash.
+	 */
+	public delete(id: GUIDString): Splash | undefined {
+		const index = this.queue.findIndex(item => item.getId() === id)
+		if (index === -1) return undefined
+		return this.queue.splice(index, 1)[0]
+	}
+}

package/src/ts/main.ts

@@ -0,0 +1,9 @@
+// @ts-strict
+
+import { Service } from './core/Service'
+
+try {
+	Service.start()
+} catch (e) {
+	console.warn(e)
+}

package/src/ts/types/Types.ts

@@ -0,0 +1,3 @@
+export type GUIDString = string
+export type CSSSelector = string
+export type Reference = CSSSelector | Element

package/src/ts/types/global.d.ts

@@ -0,0 +1,14 @@
+import NS from '../core/Service'
+import { ServiceInterface } from '../core/ServiceInterface'
+
+export class Service extends NS.Service {}
+
+declare global {
+	export const ns: ServiceInterface
+	export interface Window {
+		ns: ServiceInterface
+	}
+	export interface window {
+		ns: ServiceInterface
+	}
+}

package/src/vite-env.d.ts

@@ -1,9 +1 @@
 /// <reference types="vite/client" />
-
-import Nanosplash from "./ts/core/Nanosplash/Nanosplash";
-
-declare global {
-	interface Window {
-		ns2: Nanosplash
-	}
-}

package/tests/DomUtilities.spec.ts

@@ -0,0 +1,117 @@
+// @ts-strict
+
+import { JSDOM } from 'jsdom'
+import { beforeEach, describe, expect, it } from 'vitest'
+import {
+	createElement,
+	injectAsFirstChild,
+	showElement,
+	hideElement,
+	move,
+	elementFrom,
+	getRecycledSplash,
+	addNSHostClass,
+	removeNSHostClass,
+} from '../src/ts/core/DomUtilities'
+import { Splash } from '../src/ts/core/Splash'
+import { Service } from '../src/ts/core/Service'
+
+describe('DOMUtilities', () => {
+	// Reset the DOM before each test
+	beforeEach(() => {
+		const dom = new JSDOM()
+		// @ts-ignore
+		globalThis.window = dom.window
+		globalThis.document = dom.window.document
+		globalThis.DOMParser = dom.window.DOMParser
+		globalThis.Element = dom.window.Element
+	})
+
+	it('Should be able to create a Nanosplash component', () => {
+		const getClass = (element: Element) => element.classList[0]
+		const element = createElement()
+		const contentElement = <Element>element.firstElementChild
+		const textElement = <Element>contentElement.firstElementChild
+		const spinnerElement = <Element>textElement.nextElementSibling
+
+		expect(getClass(element)).toBe('ns')
+		expect(getClass(contentElement)).toBe('nsc')
+		expect(getClass(textElement)).toBe('nst')
+		expect(getClass(spinnerElement)).toBe('nss')
+	})
+
+	it('Should be able to inject a Nanosplash component', () => {
+		const elementA = createElement()
+		const elementB = createElement()
+		const destinationElement = document.createElement('div')
+		injectAsFirstChild(elementA, destinationElement)
+		expect(destinationElement.firstElementChild).toBe(elementA)
+		injectAsFirstChild(elementB, destinationElement)
+		expect(destinationElement.firstElementChild).toBe(elementB)
+	})
+
+	it('Should be able to prepare the parent of a Nanosplash component', () => {
+		const ns = new Splash()
+		const parent = document.createElement('div')
+		parent.appendChild(ns.getElement() as Element)
+		addNSHostClass(parent)
+		expect(parent.classList.contains(Splash.NSHostClass)).toBe(true)
+	})
+
+	it('Should be able to clean the parent of a Nanosplash component', () => {
+		const ns = new Splash()
+		const parent = document.createElement('div')
+		parent.appendChild(ns.getElement() as Element)
+		parent.classList.add(Splash.NSClass)
+		removeNSHostClass(parent)
+		expect(parent.classList.contains(Splash.NSHostClass)).toBe(false)
+	})
+
+	it('Should be able to convert an element reference to an element', () => {
+		const element = document.createElement('div')
+		document.body.appendChild(element)
+		element.id = 'test-id'
+		element.classList.add('test-class')
+		element.setAttribute('data-test', 'test')
+		expect(elementFrom('#test-id')).toBe(element)
+		expect(elementFrom('.test-class')).toBe(element)
+		expect(elementFrom('div[data-test="test"]')).toBe(element)
+		expect(elementFrom(element)).toBe(element)
+	})
+
+	it('Should be able to recycle a Nanosplash component', () => {
+		const destination = document.createElement('div')
+		document.body.appendChild(destination)
+		const nss = Service.getInstance()
+		const id = nss.showInside(destination, 'Hello World!')
+		const recycled = getRecycledSplash(destination)
+		expect(recycled?.getId()).toBe(id)
+	})
+
+	it('Should be able to show an element', () => {
+		const element = document.createElement('div')
+		showElement(element)
+		expect(element.style.display).toBe('flex')
+	})
+
+	it('Should be able to hide an element', () => {
+		const element = document.createElement('div')
+		hideElement(element)
+		expect(element.style.display).toBe('none')
+	})
+
+	it('Should be able to alter the class of a Nanosplash host', () => {
+		const div = document.createElement('div')
+		addNSHostClass(div)
+		expect(div.classList.contains(Splash.NSHostClass)).toBe(true)
+		removeNSHostClass(div)
+		expect(div.classList.contains(Splash.NSHostClass)).toBe(false)
+	})
+
+	it('Should be able to move a Nanosplash component', () => {
+		const ns = new Splash()
+		const destination = document.createElement('div')
+		move(ns.getElement() as Element, destination)
+		expect(destination.firstElementChild).toBe(ns.getElement())
+	})
+})

package/tests/Guid.spec.ts

@@ -1,6 +1,8 @@
 import { beforeEach, describe, expect, it } from 'vitest'
-import Nanosplash from '../src/ts/core/Nanosplash/Nanosplash'
 import { JSDOM } from 'jsdom'
+import { Splash } from '../src/ts/core/Splash'
+
+const rgx = /^[{]?[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}[}]?$/
 
 describe('Guid', () => {
 	// Reset the DOM before each test
@@ -13,9 +15,7 @@ describe('Guid', () => {
 	})
 
 	it('Should generate a valid GUID', () => {
-		const guidRegex =
-			/^[{]?[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}[}]?$/
-		const value = new Nanosplash().getId()
-		expect(value).toMatch(guidRegex)
+		const value = new Splash().getId()
+		expect(value).toMatch(rgx)
 	})
 })

package/tests/Service.spec.ts

@@ -0,0 +1,198 @@
+import { beforeEach, expect, describe, it } from 'vitest'
+import { Service } from '../src/ts/core/Service'
+import { Splash } from '../src/ts/core/Splash'
+import { GUIDString } from '../src/ts/types/Types'
+import { ExpectedParsedValues, div, resetDOM } from './TestUtilities'
+
+resetDOM()
+
+declare global {
+	interface Window {
+		ns: Service
+	}
+}
+
+describe('NanosplashService', () => {
+	// Reset the DOM before each test
+	beforeEach(() => {
+		resetDOM()
+	})
+
+	it('Should be able to create an instance', () => {
+		const nss = Service.getInstance()
+		expect(nss).toBeInstanceOf(Service)
+	})
+
+	it('Should be a valid singleton instance', () => {
+		const nss1 = Service.getInstance()
+		const nss2 = Service.getInstance()
+		expect(nss1).toBe(nss2)
+	})
+
+	it('Should be able to start the service and attach it to Window', () => {
+		Service.start()
+		const nss = Service.getInstance()
+		expect(nss).toBe(window.ns)
+	})
+
+	it('Should be able to show a Nanosplash in the browser window', () => {
+		const text = 'Hello World!'
+		const nss = Service.getInstance()
+		const nsId = <GUIDString>nss.show(text)
+
+		// Compare the elements:
+		const element = document.getElementById(nsId)
+		const splash = nss.nsQueue.get(nsId)
+		expect(element).toBe(splash?.getElement())
+
+		// Compare the text:
+		const nsText = splash?.getTextElement().innerText
+		expect(nsText).toBe(text)
+	})
+
+	it('Should be able to show a Nanosplash over a given element', () => {
+		const id = 'test-id'
+		const text = 'Hello World!'
+		const destination = document.createElement('div')
+
+		// Assign ID and append to DOM
+		destination.id = id
+		document.body.appendChild(destination)
+
+		const nss = Service.getInstance()
+
+		// Show Splash inside element
+		const nsId = nss.showInside(`#${id}`, text)
+
+		// Get element from DOM with the same ID
+		const element = document.getElementById(<string>nsId)
+
+		// Get Splash instance from NS Service with the same ID
+		const ns = nss.nsQueue.get(<string>nsId)
+
+		// Compare the two
+		expect(element).toBe(ns?.getElement())
+
+		// Compare the text
+		const nsText = ns?.getTextElement().innerText
+		expect(nsText).toBe(text)
+	})
+
+	it('Should be able to hide a Splash', () => {
+		const nss = Service.getInstance()
+		const nsId = <GUIDString>nss.show()
+		nss.hide()
+		const splash = nss.nsQueue.get(nsId)
+		expect(splash).toBeUndefined()
+	})
+
+	it('Should be able to hide multiple Splashes in FIFO-order', () => {
+		document.body.append(div('a'), div('b'), div('c'))
+
+		const nss = Service.getInstance()
+		const a = nss.showInside('#a', 'A')
+		const b = nss.showInside('#b', 'B')
+		const c = nss.showInside('#c', 'C')
+
+		expect(nss.nsQueue.queue.length).toBe(3)
+
+		nss.hide()
+		expect(nss.nsQueue.queue.length).toBe(2)
+		expect(nss.nsQueue.get(a as string)).toBeUndefined()
+		expect(nss.nsQueue.get(b as string)).toBeInstanceOf(Splash)
+		expect(nss.nsQueue.get(c as string)).toBeInstanceOf(Splash)
+
+		nss.hide()
+		expect(nss.nsQueue.queue.length).toBe(1)
+		expect(nss.nsQueue.get(a as string)).toBeUndefined()
+		expect(nss.nsQueue.get(b as string)).toBeUndefined()
+		expect(nss.nsQueue.get(c as string)).toBeInstanceOf(Splash)
+
+		nss.hide()
+		expect(nss.nsQueue.queue.length).toBe(0)
+		expect(nss.nsQueue.get(a as string)).toBeUndefined()
+		expect(nss.nsQueue.get(b as string)).toBeUndefined()
+		expect(nss.nsQueue.get(c as string)).toBeUndefined()
+	})
+
+	it('Should be able to hide all Nanosplashes', () => {
+		document.body.append(div('a'), div('b'), div('c'))
+
+		const nss = Service.getInstance()
+
+		nss.hideAll() // Reset the queue
+		expect(nss.nsQueue.queue.length).toBe(0)
+
+		// Add three Nanosplashes to the queue
+		nss.showInside('#a', 'A')
+		nss.showInside('#b', 'B')
+		nss.showInside('#c', 'C')
+
+		// Expect the queue to have three items
+		expect(nss.nsQueue.queue.length).toBe(3)
+
+		// Hide all Nanosplashes
+		nss.hideAll()
+
+		// Expect the queue to be empty
+		expect(nss.nsQueue.queue.length).toBe(0)
+	})
+
+	it('Should be able to hide a Nanosplash based on its ID', () => {
+		const nss = Service.getInstance()
+		const nsId = <GUIDString>nss.show()
+		nss.hideId(nsId)
+		const splash = nss.nsQueue.get(nsId)
+		expect(splash).toBeUndefined()
+	})
+
+	it('Should be able to hide a Nanosplash residing inside a given element', () => {
+		const id = 'test-id'
+		const parent = document.createElement('div')
+		parent.id = id
+		document.body.appendChild(parent)
+
+		const nss = Service.getInstance()
+		const nsId = <GUIDString>nss.showInside(`#${id}`)
+
+		// Confirm existence.
+		const element = document.getElementById(<string>nsId)
+		expect(element?.parentElement).toBe(parent)
+
+		// Hide using API.
+		nss.hideInside(`#${id}`)
+
+		// Confirm non-existence.
+		expect(element?.isConnected).toBe(false)
+		expect(nss.nsQueue.get(nsId)).toBeUndefined()
+	})
+
+	it('Should take any argument as text without breaking', () => {
+		const nss = Service.getInstance()
+
+		// Destructure the expected values
+		const {
+			numValues,
+			arrValues,
+			objValues,
+			boolValues,
+			nullValues,
+			undefValues,
+		} = ExpectedParsedValues
+
+		// Create functions to test the values
+		const testValues = (raw: any, parsed: any) => {
+			const id = <GUIDString>nss.show(raw)
+			const value = nss.nsQueue.get(id)?.getTextElement().innerText
+			expect(value).toBe(parsed)
+		}
+
+		// Test the values
+		testValues(numValues.raw, numValues.parsed)
+		testValues(arrValues.raw, arrValues.parsed)
+		testValues(objValues.raw, objValues.parsed)
+		testValues(boolValues.raw, boolValues.parsed)
+		testValues(nullValues.raw, nullValues.parsed)
+		testValues(undefValues.raw, undefValues.parsed)
+	})
+})

package/tests/Splash.spec.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { Splash } from '../src/ts/core/Splash'
+import { resetDOM } from './TestUtilities'
+
+resetDOM()
+
+describe('Splash', () => {
+	// Reset the DOM before each test
+	beforeEach(() => {
+		resetDOM()
+	})
+
+	it('Should be a valid Splash element', () => {
+		const ns = new Splash()
+		const element = ns.getElement() as HTMLElement
+
+		// The element should be a valid HTMLDivElement
+		expect(element).not.toBeUndefined()
+		expect(element).toBeInstanceOf(HTMLDivElement)
+
+		// The element and the splash instance should have the same ID
+		expect(element.id).toBe(ns.getId())
+
+		// The element should have the main Nanosplash CSS class
+		expect(element.classList.contains(Splash.NSClass)).toBe(true)
+
+		// The element should have the correct, inner structure
+		const textSelector = '.nsc > .nst'
+		const spinnerSelector = '.nsc > .nss'
+		const textElement = element.querySelector(textSelector)
+		const spinnerElement = element.querySelector(spinnerSelector)
+		expect(textElement).not.toBeNull()
+		expect(spinnerElement).not.toBeNull()
+	})
+
+	it('Should be able to set text', () => {
+		const ns = new Splash()
+		const text = 'Hello World!'
+		ns.setText(text)
+		expect(ns.getTextElement().innerText).toBe(text)
+	})
+
+	it('Should be able to hide text', () => {
+		const ns = new Splash()
+		ns.hideText()
+		expect(ns.getTextElement().style.display).toBe('none')
+	})
+
+	it('Should be able to show text', () => {
+		const ns = new Splash()
+		ns.setText('Hello World!')
+		ns.hideText()
+		ns.showText()
+		expect(ns.getTextElement().style.display).toBe('flex')
+	})
+
+	it('Should be able to remove itself from DOM', () => {
+		const ns = new Splash()
+		const deleteResult = ns.delete()
+		const element = ns.getElement()
+		expect(deleteResult).toBe(true)
+		expect(element).toBeNull()
+	})
+})