nanosplash 3.0.0 → 3.0.1

package/src/ts/core/Service.ts

@@ -0,0 +1,235 @@
+// @ts-strict
+
+import { version } from '../../../package.json'
+import '../../sass/ns.sass'
+
+import { NSFinder, GUIDString, Reference } from '../types/Types'
+import { cleanNSParentOf, getRecycledNS, move, elementFrom } from './Dom'
+import { ServiceInterface } from './ServiceInterface'
+import { Splash } from './Splash'
+
+/**
+ * # Service
+ * A service class that handles Nanosplash instances.
+ * It's a singleton class and its instance resides in the Window object and
+ * serves the public API of the Nanosplash library.
+ * @see Splash
+ * @author Isak K. Hauge <isakhauge@icloud.com>
+ */
+export class Service implements ServiceInterface {
+	/**
+	 * # Window Accessor Key
+	 * Key to access NanosplashService instance in the Window object.
+	 */
+	public static readonly WindowAccessorKey = 'ns'
+
+	/**
+	 * # Instance
+	 * Singleton instance of NanosplashService.
+	 * @private
+	 */
+	private static instance: Service
+
+	/**
+	 * # Version
+	 */
+	public readonly version: string
+
+	/**
+	 * @inheritdoc
+	 */
+	public readonly nsStack: Splash[]
+
+	/**
+	 * # Constructor
+	 * Private constructor to prevent multiple instances.
+	 * @private
+	 */
+	private constructor() {
+		this.version = version
+		this.nsStack = []
+	}
+
+	/**
+	 * # Find Index
+	 * Find Nanosplash stack index by callback.
+	 * @param callback Callback function that returns a boolean.
+	 * @returns {number} Index of Nanosplash instance in the stack or -1.
+	 * @private
+	 */
+	private findIndex(callback: NSFinder): number | -1 {
+		return this.nsStack.findIndex(callback)
+	}
+
+	/**
+	 * # Find
+	 * Find Nanosplash in the stack by callback.
+	 * @param callback Callback function that returns a boolean.
+	 * @returns {Splash | undefined} Nanosplash instance or undefined
+	 * @private
+	 */
+	private find(callback: NSFinder): Splash | undefined {
+		return this.nsStack.find(callback)
+	}
+
+	/**
+	 * # Get Instance
+	 * Singleton instance accessor
+	 * @returns {Service} NanosplashService instance
+	 */
+	public static getInstance(): Service {
+		if (!Service.instance) {
+			Service.instance = new Service()
+		}
+		return Service.instance
+	}
+
+	/**
+	 * # Assign To Window
+	 * Assign a NanosplashService instance to the Window object.
+	 * The NanosplashService instance can be accessed in the window object
+	 * using the key window accessor key.
+	 * @see WindowAccessorKey
+	 * @private
+	 */
+	private static assignToWindow(): void {
+		Object.defineProperty(window, Service.WindowAccessorKey, {
+			value: Service.getInstance(),
+			writable: false,
+		})
+	}
+
+	/**
+	 * # Start
+	 * Initialize and attach a Nanosplash Service instance to the Window object.
+	 */
+	public static start(): void {
+		Service.assignToWindow()
+		window.addEventListener('load', () => {
+			const nss = window[Service.WindowAccessorKey]
+			const nssAssigned = nss instanceof Service
+			if (!nssAssigned) {
+				Service.assignToWindow()
+			}
+		})
+	}
+
+	/**
+	 * # Create Nanosplash
+	 * Return new Nanosplash instance and push it to the stack.
+	 * @param text Text to display.
+	 * @returns {Splash} Nanosplash instance.
+	 * @private
+	 */
+	private createNS(text?: string): Splash {
+		const ns = new Splash()
+		ns.setText(text || '')
+		this.nsStack.push(ns)
+		return ns
+	}
+
+	/**
+	 * # Clean And Remove
+	 * Remove Nanosplash from DOM and clean its parent.
+	 * @param ns Nanosplash instance.
+	 * @returns {GUIDString} Nanosplash ID.
+	 * @private
+	 */
+	private cleanAndRemove(ns: Splash): GUIDString {
+		cleanNSParentOf(ns)
+		return ns.remove().getId()
+	}
+
+	/**
+	 * # Stack Delete
+	 * Remove Nanosplash instance from the stack.
+	 * @param ns Nanosplash instance.
+	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
+	 * @private
+	 */
+	private stackDelete(ns: Splash): GUIDString | null {
+		let index = this.findIndex((o: Splash) => o.getId() === ns.getId())
+		if (index < 0) return null
+		this.nsStack.splice(index, 1)
+		return ns.getId()
+	}
+
+	/**
+	 * # Delete NS
+	 * Remove Nanosplash instance from both the stack and the
+	 * @param callback Callback function.
+	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
+	 * @private
+	 */
+	private deleteNS(callback: NSFinder): GUIDString | null {
+		const ns = this.find(callback)
+		if (ns) {
+			this.cleanAndRemove(ns)
+			return this.stackDelete(ns)
+		}
+		return null
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public show(text?: string): GUIDString {
+		let ns = getRecycledNS(document.body)
+		if (!ns) {
+			ns = this.createNS()
+			move(ns.getNSElement(), document.body)
+		}
+		return ns.setText(text || '').getId()
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public showInside(ref: Reference, text?: string): GUIDString | null {
+		const destinationNode: Element | null = elementFrom(ref)
+		if (destinationNode) {
+			let ns = getRecycledNS(destinationNode)
+			if (!ns) {
+				ns = this.createNS()
+			}
+			move(ns.getNSElement(), <Element>destinationNode)
+			return ns.setText(text || '').getId()
+		}
+
+		return null
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public hide(): GUIDString | null {
+		const ns = this.nsStack.pop()
+		return ns ? this.cleanAndRemove(ns) : null
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public hideAll(): void {
+		this.nsStack.forEach(this.cleanAndRemove)
+		this.nsStack.splice(0, this.nsStack.length)
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public hideId(id: GUIDString): GUIDString | null {
+		return this.deleteNS((ns: Splash) => ns.getId() === id)
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public hideInside(ref: Reference): GUIDString | null {
+		const node = elementFrom(ref)
+		const cb = (ns: Splash) => ns.getNSElement().parentElement === node
+		return node ? this.deleteNS(cb) : null
+	}
+}
+
+export default { Service }

package/src/ts/core/{Nanosplash/interfaces/NanosplashAPI.ts → ServiceInterface.ts}

@@ -1,7 +1,17 @@
-import { GUIDString } from '../../../types/Alias'
-import { Destination } from '../../../types/Nanosplash'
+// @ts-strict
+
+import { GUIDString, Reference } from '../types/Types'
+import { Splash } from './Splash'
+
+export interface ServiceInterface {
+	/**
+	 * # Nanosplash Stack
+	 * For each Nanosplash instance created, it's pushed to the stack.
+	 * When a Nanosplash instance is removed, it's removed from the stack.
+	 * @see Splash
+	 */
+	readonly nsStack: Splash[]
 
-export interface NanosplashAPI {
 	/**
 	 * # Show
 	 * Present a Nanosplash in the browser window displaying the given text.
@@ -13,11 +23,11 @@ export interface NanosplashAPI {
 	/**
 	 * # Show Inside
 	 * Present a Nanosplash over the given element displaying the given text.
-	 * @param destination Target element.
+	 * @param ref Reference an element.
 	 * @param text Text to display.
 	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
 	 */
-	showInside(destination: Destination, text?: string): GUIDString | null
+	showInside(ref: Reference, text?: string): GUIDString | null
 
 	/**
 	 * # Hide
@@ -43,8 +53,8 @@ export interface NanosplashAPI {
 	/**
 	 * # Hide Inside
 	 * Hide Nanosplash inside the given element if it exists.
-	 * @param destination Target element.
+	 * @param ref Reference an element.
 	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
 	 */
-	hideInside(destination: Destination): GUIDString | null
+	hideInside(ref: Reference): GUIDString | null
 }

package/src/ts/core/Splash.ts

@@ -0,0 +1,124 @@
+// @ts-strict
+
+import { GUIDString } from '../types/Types'
+import { createElement, showElement, hideElement } from './Dom'
+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 readonly id: GUIDString
+
+	/**
+	 * # Element
+	 * The root element of the Nanosplash component.
+	 */
+	private element?: HTMLDivElement
+
+	/**
+	 * # 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 getNSContentElement(): HTMLDivElement {
+		return <HTMLDivElement>this.getNSElement().firstElementChild
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public getNSTextElement(): HTMLDivElement {
+		return <HTMLDivElement>this.getNSContentElement().firstElementChild
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public getId(): GUIDString {
+		return this.id
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public getNSElement(): HTMLDivElement {
+		return <HTMLDivElement>this.element
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public setText(text: string): Splash {
+		this.getNSTextElement().innerText = text
+		text.length > 0 ? this.showText() : this.hideText()
+		return this
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public showText(): Splash {
+		showElement(this.getNSTextElement())
+		return this
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public hideText(): Splash {
+		hideElement(this.getNSTextElement())
+		return this
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public remove(): Splash {
+		if (this.element) {
+			this.element.parentElement?.removeChild(this.element)
+			delete this.element
+		}
+		return this
+	}
+}

package/src/ts/core/SplashInterface.ts

@@ -0,0 +1,54 @@
+// @ts-strict
+
+import { GUIDString } from '../types/Types'
+import { Splash } from './Splash'
+
+export interface SplashInterface {
+	/**
+	 * # Get NS Content Element
+	 * Returns the content element of the Nanosplash.
+	 */
+	getNSContentElement(): HTMLDivElement
+
+	/**
+	 * # Get NS Text Element
+	 * Returns the text element of the Nanosplash.
+	 */
+	getNSTextElement(): HTMLDivElement
+
+	/**
+	 * # Get ID
+	 * Return Nanosplash instance GUID.
+	 */
+	getId(): GUIDString
+
+	/**
+	 * # Get NS Element
+	 * Return Nanosplash instance HTMLDivElement.
+	 */
+	getNSElement(): HTMLDivElement
+
+	/**
+	 * # 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
+
+	/**
+	 * # Remove
+	 * Delete all
+	 */
+	remove(): Splash
+}

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,12 @@
+import { Splash } from '../core/Splash'
+
+export type GUIDString = string
+export type CSSSelector = string
+export type FindCallback<T> = (item: T, index: number) => boolean
+export type NSFinder = FindCallback<Splash>
+export type Reference = CSSSelector | Element
+
+export enum ClassListAction {
+	Add = 'add',
+	Remove = 'remove',
+}

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/Dom.spec.ts

@@ -0,0 +1,127 @@
+// @ts-strict
+
+import { JSDOM } from 'jsdom'
+import { beforeEach, describe, expect, it } from 'vitest'
+import {
+	createElement,
+	injectAsFirstChild,
+	prepareParentOf,
+	cleanNSParentOf,
+	showElement,
+	hideElement,
+	setNSHostClass,
+	move,
+	elementFrom,
+	elementIsNS,
+	getRecycledNS,
+} from '../src/ts/core/Dom'
+import { Splash } from '../src/ts/core/Splash'
+import { Service } from '../src/ts/core/Service'
+import { ClassListAction } from '../src/ts/types/Types'
+
+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.getNSElement())
+		prepareParentOf(ns)
+		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.getNSElement())
+		parent.classList.add(Splash.NSClass)
+		cleanNSParentOf(ns)
+		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 check if an element is a Nanosplash element', () => {
+		const elementA = new Splash().getNSElement()
+		const elementB = document.createElement('div')
+		expect(elementIsNS(elementA)).toBe(true)
+		expect(elementIsNS(elementB)).toBe(false)
+	})
+
+	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 = getRecycledNS(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')
+		setNSHostClass(div, ClassListAction.Add)
+		expect(div.classList.contains(Splash.NSHostClass)).toBe(true)
+		setNSHostClass(div, ClassListAction.Remove)
+		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.getNSElement(), destination)
+		expect(destination.firstElementChild).toBe(ns.getNSElement())
+	})
+})

package/tests/Guid.spec.ts

@@ -1,6 +1,6 @@
 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'
 
 describe('Guid', () => {
 	// Reset the DOM before each test
@@ -15,7 +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()
+		const value = new Splash().getId()
 		expect(value).toMatch(guidRegex)
 	})
 })