nanosplash 2.5.2 → 3.0.0

package/src/ts/core/Nanosplash/repositories/NanosplashRepository.ts

@@ -0,0 +1,178 @@
+// @ts-strict
+
+/**
+ * # Nanosplash Repository
+ * A repository of functions that are used by the Nanosplash classes.
+ * @see Nanosplash
+ * @see NanosplashService
+ * @author Isak K. Hauge <isakhauge@icloud.com>
+ */
+
+import { GUIDString } from '../../../types/Alias'
+import type { Destination, DestinationNode } from '../../../types/Nanosplash'
+import Nanosplash from '../Nanosplash'
+import NanosplashService from '../services/NanosplashService'
+
+/**
+ * # Create
+ * Return the main Nanosplash element.
+ */
+export function createElement(): HTMLDivElement {
+	return new DOMParser().parseFromString(
+		'<div class=ns><div class=ns-content><div class=ns-text></div><div class=ns-spinner><svg viewBox="0 0 50 50"><circle class=path cx=25 cy=25 r=20 fill=none></circle></svg></div></div></div>',
+		'text/html'
+	).body.firstChild as HTMLDivElement
+}
+
+/**
+ * # Inject	as First Child
+ * Insert the `node` into the `destinationNode` as its first child.
+ * @param node Node to inject.
+ * @param destinationNode Node in which the first node is to be injected.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Node/childNodes
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Node/insertBefore
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild
+ * @see https://developer.mozilla.org/docs/Web/API/NodeList/item
+ */
+export function injectAsFirstChild(
+	node: Element,
+	destinationNode: Element
+): void {
+	const destinationNodeHasChildren = destinationNode.children.length > 0
+	if (destinationNodeHasChildren) {
+		destinationNode.insertBefore(node, destinationNode.children.item(0))
+	} else {
+		destinationNode.append(node)
+	}
+}
+
+/**
+ * # Set NS Host Class
+ * Add or remove the `nsHostClassName` class to the `element`.
+ * @param element Element to which the `nsHostClassName` class will be added or removed.
+ * @param action Action to perform ('add' or 'remove').
+ */
+export function setNSHostClass(
+	element: Element | null,
+	action: 'add' | 'remove'
+): void {
+	element?.classList[action](Nanosplash.nsHostClassName)
+}
+
+/**
+ * # Prepare Parent
+ * Add the `nsHostClassName` class to the parent of the `ns` element.
+ * @param ns Nanosplash instance.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/parentElement
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/add
+ */
+export function prepareParentOf(ns: Nanosplash): void {
+	setNSHostClass(ns.getNSElement().parentElement, 'add')
+}
+
+/**
+ * # Clean Parent
+ * Remove the `nsHostClassName` class from the parent of the `ns` element.
+ * @param ns Nanosplash instance.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/parentElement
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/remove
+ */
+export function cleanNSParentOf(ns: Nanosplash): void {
+	setNSHostClass(ns.getNSElement().parentElement, 'remove')
+}
+
+/**
+ * # Show Element
+ * Set the `display` property of the `element` to `flex`.
+ * @param element Element to show.
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display
+ */
+export function showElement(element: HTMLElement): void {
+	element.style.display = 'flex'
+}
+
+/**
+ * # Hide Element
+ * Set the `display` property of the `element` to `none`.
+ * @param element Element to hide.
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/display
+ */
+export function hideElement(element: HTMLElement): void {
+	element.style.display = 'none'
+}
+
+/**
+ * # Node From
+ * Convert the `destination` to a HTMLElement, Element, Node or null.
+ * @param destination Destination of the node.
+ * @returns Node from the `destination`.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Element
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Node
+ */
+export function nodeFrom(destination: Destination): DestinationNode | null {
+	let elem: HTMLElement | null
+
+	if (typeof destination === 'string') {
+		elem = document.querySelector(destination)
+	} else if (destination instanceof Node) {
+		return destination
+	} else if (typeof destination === 'function') {
+		elem = <HTMLElement>destination()
+		if (!(elem instanceof Node)) {
+			return null
+		}
+	} else {
+		elem = null
+	}
+
+	return elem
+}
+
+/**
+ * # Element Is NS
+ * Check if the element is Nanosplash element.
+ * This is determined by the presence of the `ns` class on the element.
+ * @param element Element to check.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/contains
+ */
+export function elementIsNS(element: Element): boolean {
+	return element?.classList?.contains('ns')
+}
+
+/**
+ * # Move
+ * Move an Element to another Element.
+ * @param element Element to move
+ * @param destinationElement Target element
+ */
+export function move(element: Element, destinationElement: Element): void {
+	// Clean the current NS host element.
+	setNSHostClass(element.parentElement, 'remove')
+	// Assign new NS host element.
+	setNSHostClass(destinationElement, 'add')
+	injectAsFirstChild(element, destinationElement)
+}
+
+/**
+ * # Get Recycled NS
+ * Return the Nanosplash instance inside the `destination` if it exists.
+ * @param destination Destination of the Nanosplash instance.
+ * @returns { Nanosplash | null } Nanosplash instance or null.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Node/firstChild
+ */
+export function getRecycledNS(destination: Destination): Nanosplash | null {
+	const destinationNode = nodeFrom(destination)
+	if (!destinationNode) return null
+	const firstChild = <Element>destinationNode.firstChild
+	const hasChild = firstChild !== null
+	const destinationAlreadyHasNS = hasChild && elementIsNS(firstChild)
+
+	if (destinationAlreadyHasNS) {
+		const id: GUIDString = firstChild.id
+		const nss = NanosplashService.getInstance()
+		return nss.nsStack.items.find((ns: Nanosplash) => ns.getId() === id) ?? null
+	}
+
+	return null
+}

package/src/ts/core/Nanosplash/services/NanosplashService.ts

@@ -0,0 +1,222 @@
+// @ts-strict
+
+import Nanosplash from '../Nanosplash'
+import Stack from '../../../util/Stack'
+import {
+	cleanNSParentOf,
+	getRecycledNS,
+	move,
+	nodeFrom,
+} from '../repositories/NanosplashRepository'
+import type { Destination, DestinationNode } from '../../../types/Nanosplash'
+import type { GUIDString } from '../../../types/Alias'
+import { FindCallback } from '../../../types/NanosplashService'
+import { NanosplashAPI } from '../interfaces/NanosplashAPI'
+
+/**
+ * # Nanosplash Service
+ * A service class that handles Nanosplash instances.
+ * It's a singleton class and it's instance resides in the Window object and
+ * serves the public API of the Nanosplash library.
+ * @see Nanosplash
+ * @author Isak K. Hauge <isakhauge@icloud.com>
+ */
+class NanosplashService implements NanosplashAPI {
+	private static readonly WindowAccessorKey = 'ns'
+	private static instance: NanosplashService
+
+	public readonly nsStack: Stack<Nanosplash>
+
+	/**
+	 * # Constructor
+	 * Private constructor to prevent multiple instances.
+	 * @private
+	 */
+	private constructor() {
+		this.nsStack = new Stack<Nanosplash>()
+	}
+
+	/**
+	 * # 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 findIndex(callback: FindCallback): number | -1 {
+		return this.nsStack.items.findIndex(callback)
+	}
+
+	/**
+	 * # Find
+	 * Find Nanosplash in the stack by callback.
+	 * @param callback Callback function that returns a boolean.
+	 * @returns {Nanosplash | undefined} Nanosplash instance or undefined
+	 */
+	private find(callback: FindCallback): Nanosplash | undefined {
+		return this.nsStack.items.find(callback)
+	}
+
+	/**
+	 * # Get Instance
+	 * Singleton instance accessor
+	 * @returns {NanosplashService} NanosplashService instance
+	 */
+	public static getInstance(): NanosplashService {
+		if (!NanosplashService.instance) {
+			NanosplashService.instance = new NanosplashService()
+		}
+		return NanosplashService.instance
+	}
+
+	/**
+	 * # Assign To Window
+	 * Assign Nanosplash service instance to Window object.
+	 * The NanosplashService instance can be accessed in the window object
+	 * using the key window accessor key.
+	 * @see WindowAccessorKey
+	 */
+	private static assignToWindow(): void {
+		Object.defineProperty(window, NanosplashService.WindowAccessorKey, {
+			value: NanosplashService.getInstance(),
+			writable: false,
+		})
+	}
+
+	/**
+	 * # Start
+	 * Initialize Nanosplash Service instance in Window when it's loaded.
+	 */
+	public static start(): void {
+		NanosplashService.assignToWindow()
+		window.addEventListener('load', () => {
+			const nss = window[NanosplashService.WindowAccessorKey]
+			const nssAssigned = nss instanceof NanosplashService
+			if (!nssAssigned) {
+				NanosplashService.assignToWindow()
+			}
+		})
+	}
+
+	/**
+	 * # Create Nanosplash
+	 * Return new Nanosplash instance and push it to the stack.
+	 * @param text Text to display.
+	 * @returns {Nanosplash} Nanosplash instance.
+	 */
+	private createNS(text?: string): Nanosplash {
+		const ns = new Nanosplash()
+		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 cleanAndRemove(ns: Nanosplash): GUIDString {
+		cleanNSParentOf(ns)
+		ns.remove()
+		return ns.getId()
+	}
+
+	/**
+	 * # Stack Delete At
+	 * Remove Nanosplash instance from the stack.
+	 * @param ns Nanosplash instance.
+	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
+	 */
+	private stackDelete(ns: Nanosplash): GUIDString | null {
+		let index = this.findIndex((o: Nanosplash) => o.getId() === ns.getId())
+		if (index < 0) return null
+		this.nsStack.items.splice(index, 1)
+		return ns.getId()
+	}
+
+	/**
+	 * # Delete NS
+	 * Remove Nanosplash instance from both the stack and the DOM.
+	 * @param callback Callback function.
+	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
+	 */
+	private deleteNS(callback: FindCallback): 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)
+		}
+		ns.setText(text || '')
+		return ns.getId()
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public showInside(
+		destination: Destination,
+		text?: string
+	): GUIDString | null {
+		const destinationNode: DestinationNode | null = nodeFrom(destination)
+		if (destinationNode) {
+			let ns = getRecycledNS(destinationNode)
+			if (!ns) {
+				ns = this.createNS()
+			}
+			ns.setText(text || '')
+			move(ns.getNSElement(), <Element>destinationNode)
+			return ns.getId()
+		}
+
+		return null
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public hideAll(): void {
+		this.nsStack.items.forEach((ns: Nanosplash) => {
+			this.cleanAndRemove(ns)
+		})
+		this.nsStack.clear()
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public hide(): GUIDString | null {
+		const ns = this.nsStack.pop()
+		return ns ? this.cleanAndRemove(ns) : null
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public hideId(id: GUIDString): GUIDString | null {
+		return this.deleteNS((ns: Nanosplash) => ns.getId() === id)
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public hideInside(destination: Destination): GUIDString | null {
+		const node = nodeFrom(destination)
+		const cb = (ns: Nanosplash) => ns.getNSElement().parentElement === node
+		return node ? this.deleteNS(cb) : null
+	}
+}
+
+export default NanosplashService

package/src/ts/types/Alias.d.ts

@@ -0,0 +1 @@
+export type GUIDString = string

package/src/ts/types/Nanosplash.d.ts

@@ -0,0 +1,18 @@
+export type DestinationSelector = string
+
+export type DestinationNode = Node | Element | HTMLElement
+
+export type DestinationCallback = () =>
+	| DestinationNode
+	| Promise<DestinationNode>
+
+export type Destination =
+	| DestinationSelector
+	| DestinationNode
+	| DestinationCallback
+
+declare global {
+	interface Window {
+		ns: NanosplashService
+	}
+}

package/src/ts/types/NanosplashService.d.ts

@@ -0,0 +1 @@
+export type FindCallback = (ns: Nanosplash, index: number) => boolean

package/src/ts/util/Guid.ts

@@ -0,0 +1,13 @@
+import { GUIDString } from '../types/Alias'
+
+/**
+ * # GUID
+ * @returns {GUIDString} A GUID string.
+ */
+export function guid(): 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)
+	})
+}

package/src/ts/util/Stack.ts

@@ -0,0 +1,73 @@
+// @ts-strict
+
+/**
+ * A stack data structure.
+ * @template T The type of item stored in the stack.
+ * @author Isak K. Hauge <isakhauge@icloud.com>
+ */
+class Stack<T> {
+	private _items: T[]
+
+	/**
+	 * Constructs a new stack.
+	 */
+	constructor() {
+		this._items = []
+	}
+
+	/**
+	 * Returns the items in the stack.
+	 */
+	public get items(): T[] {
+		return this._items
+	}
+
+	/**
+	 * Adds an item to the top of the stack.
+	 * @param item The item to add to the stack.
+	 */
+	public push(item: T): void {
+		this._items.push(item)
+	}
+
+	/**
+	 * Removes and returns the item at the top of the stack.
+	 * @returns The item at the top of the stack, or undefined if the stack is empty.
+	 */
+	public pop(): T | undefined {
+		return this._items.pop()
+	}
+
+	/**
+	 * Returns the item at the top of the stack without removing it.
+	 * @returns The item at the top of the stack, or undefined if the stack is empty.
+	 */
+	public peek(): T | undefined {
+		return this._items[this._items.length - 1]
+	}
+
+	/**
+	 * Returns true if the stack is empty, false otherwise.
+	 * @returns True if the stack is empty, false otherwise.
+	 */
+	public isEmpty(): boolean {
+		return this._items.length === 0
+	}
+
+	/**
+	 * Returns the number of items in the stack.
+	 * @returns The number of items in the stack.
+	 */
+	public size(): number {
+		return this._items.length
+	}
+
+	/**
+	 * Removes all items from the stack.
+	 */
+	public clear(): void {
+		this._items = []
+	}
+}
+
+export default Stack

package/src/vite-env.d.ts

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

package/tests/Guid.spec.ts

@@ -0,0 +1,21 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import Nanosplash from '../src/ts/core/Nanosplash/Nanosplash'
+import { JSDOM } from 'jsdom'
+
+describe('Guid', () => {
+	// 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
+	})
+
+	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)
+	})
+})

package/tests/Nanosplash.spec.ts

@@ -0,0 +1,64 @@
+// @ts-strict
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import Nanosplash from '../src/ts/core/Nanosplash/Nanosplash'
+import { JSDOM } from 'jsdom'
+
+describe('Nanosplash', () => {
+	// 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
+	})
+
+	it('Should be a valid Nanosplash', () => {
+		const ns = new Nanosplash()
+		const element = ns.getNSElement()
+
+		expect(element).not.toBeUndefined()
+		expect(element.id).toBe(ns.getId())
+		expect(element.classList.contains(Nanosplash.nsClassName)).toBe(true)
+
+		const contentElement = ns.getNSContentElement()
+		expect(contentElement).not.toBeUndefined()
+
+		const textElement = ns.getNSTextElement()
+		expect(textElement).not.toBeUndefined()
+
+		const spinnerElement = <HTMLElement>textElement.nextElementSibling
+		expect(spinnerElement).not.toBeUndefined()
+
+		const spinnerSVGElement = <HTMLElement>spinnerElement.firstElementChild
+		expect(spinnerSVGElement).not.toBeUndefined()
+	})
+
+	it('Should be able to set text', () => {
+		const ns = new Nanosplash()
+		const text = 'Hello World!'
+		ns.setText(text)
+		expect(ns.getNSTextElement().innerText).toBe(text)
+	})
+
+	it('Should be able to hide text', () => {
+		const ns = new Nanosplash()
+		ns.hideText()
+		expect(ns.getNSTextElement().style.display).toBe('none')
+	})
+
+	it('Should be able to show text', () => {
+		const ns = new Nanosplash()
+		ns.setText('Hello World!')
+		ns.hideText()
+		ns.showText()
+		expect(ns.getNSTextElement().style.display).toBe('flex')
+	})
+
+	it('Should be able to remove itself from DOM', () => {
+		const ns = new Nanosplash()
+		ns.remove()
+		expect(ns.getNSElement()).toBeUndefined()
+	})
+})

package/tests/NanosplashRepository.spec.ts

@@ -0,0 +1,91 @@
+// @ts-strict
+
+import { JSDOM } from 'jsdom'
+import { beforeEach, describe, expect, it } from 'vitest'
+import Nanosplash from '../src/ts/core/Nanosplash/Nanosplash'
+import {
+	createElement,
+	injectAsFirstChild,
+	prepareParentOf,
+	cleanNSParentOf,
+	showElement,
+	hideElement,
+	setNSHostClass,
+	move,
+} from '../src/ts/core/Nanosplash/repositories/NanosplashRepository'
+
+describe('NanosplashRepository', () => {
+	// 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.Node = dom.window.Node
+	})
+
+	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('ns-content')
+		expect(getClass(textElement)).toBe('ns-text')
+		expect(getClass(spinnerElement)).toBe('ns-spinner')
+	})
+
+	it('Should be able to inject a Nanosplash component', () => {
+		const element = createElement()
+		const destinationElement = document.createElement('div')
+		injectAsFirstChild(element, destinationElement)
+		expect(destinationElement.firstElementChild).toBe(element)
+	})
+
+	it('Should be able to prepare the parent of a Nanosplash component', () => {
+		const ns = new Nanosplash()
+		const parent = document.createElement('div')
+		parent.appendChild(ns.getNSElement())
+		prepareParentOf(ns)
+		expect(parent.classList.contains(Nanosplash.nsHostClassName)).toBe(true)
+	})
+
+	it('Should be able to clean the parent of a Nanosplash component', () => {
+		const ns = new Nanosplash()
+		const parent = document.createElement('div')
+		parent.appendChild(ns.getNSElement())
+		parent.classList.add(Nanosplash.nsHostClassName)
+		cleanNSParentOf(ns)
+		expect(parent.classList.contains(Nanosplash.nsHostClassName)).toBe(false)
+	})
+
+	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, 'add')
+		expect(div.classList.contains(Nanosplash.nsHostClassName)).toBe(true)
+		setNSHostClass(div, 'remove')
+		expect(div.classList.contains(Nanosplash.nsHostClassName)).toBe(false)
+	})
+
+	it('Should be able to move a Nanosplash component', () => {
+		const ns = new Nanosplash()
+		const destination = document.createElement('div')
+		move(ns.getNSElement(), destination)
+		expect(destination.firstElementChild).toBe(ns.getNSElement())
+	})
+})