nanosplash 2.5.3 → 3.0.1

package/src/sass/ns.sass

@@ -0,0 +1,95 @@
+%maximize
+	width: 100%
+	height: 100%
+
+%upper-left
+	top: 0
+	left: 0
+
+%flex-center-xy
+	display: flex
+	justify-content: center
+	align-items: center
+
+// Nanosplash host scoped varibles
+.nsh
+	--color: DarkSlateGray
+	--size: 20px
+	--relSize: calc(var(--size) * 0.9)
+	--font: 'Helvetica', 'Arial', sans-serif
+	--weight: 400
+	--bg: #{ rgba(White, 0.8) }
+	--zIdx: 999999999
+	--blur: blur(10px)
+
+// Nanosplash host
+.nsh
+	position: relative
+	z-index: var(--zIdx)
+	&::before
+		@extend %maximize
+		@extend %upper-left
+		position: absolute
+		background-color: var(--bg)
+		content: ''
+		backdrop-filter: var(--blur)
+		-webkit-backdrop-filter: var(--blur)
+		z-index: calc(var(--zIdx) + 1)
+		border-radius: inherit
+
+// When Nanosplash host is the document body
+body.nsh
+	height: 100vh
+
+// Nanosplash (main element)
+.ns
+	@extend %maximize
+	@extend %upper-left
+	@extend %flex-center-xy
+	position: absolute
+	z-index: calc(var(--zIdx) + 2)
+
+// Nanosplash container
+.nsc
+	@extend %flex-center-xy
+	filter: drop-shadow(0 0 0.1rem #{ rgba(LightGray, 0.5) })
+
+// Nanosplash text
+.nst
+	color: var(--color)
+	font-size: var(--size)
+	font-family: var(--font)
+	font-weight: var(--weight)
+	margin-right: var(--relSize)
+	text-shadow: 0 0 0.06rem #{ rgba(DarkSlateGray, .25) }
+
+// Nanosplash spinner
+.nss
+	display: block
+	width: var(--relSize)
+	height: var(--relSize)
+	& > svg
+		animation: Rotate 2s linear infinite
+		position: relative
+		width: inherit
+		height: inherit
+		stroke-width: 8
+	& .path
+		stroke: var(--color)
+		stroke-linecap: round
+		animation: Dash 1.5s ease-in-out infinite
+
+// Spinner animations:
+@keyframes Rotate
+	100%
+		transform: rotate(360deg)
+@keyframes Dash
+	0%
+		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/ts/core/Dom.ts

@@ -0,0 +1,160 @@
+// @ts-strict
+
+import { Reference, GUIDString, ClassListAction } from '../types/Types'
+import { Service } from './Service'
+import { Splash } from './Splash'
+
+/**
+ * # DOM Utilities
+ * A collection of functions that are used by the Nanosplash classes.
+ * @see Splash
+ * @see Service
+ * @author Isak K. Hauge <isakhauge@icloud.com>
+ */
+
+/**
+ * # Create Element
+ * Return the main Nanosplash element.
+ */
+export function createElement(): HTMLDivElement {
+	return new DOMParser().parseFromString(
+		'<div class=ns><div class=nsc><div class=nst></div><div class=nss><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 element into the target element as its first child.
+ * @param element Element to inject.
+ * @param targetElement Element in which the first element is to be injected.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Document/children
+ * @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(
+	element: Element,
+	targetElement: Element
+): void {
+	const targetHasChild = targetElement.children.length > 0
+	if (targetHasChild) {
+		targetElement.insertBefore(element, targetElement.children.item(0))
+	} else {
+		targetElement.append(element)
+	}
+}
+
+/**
+ * # 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').
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/classList
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/add
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/remove
+ */
+export function setNSHostClass(
+	element: Element | null,
+	action: ClassListAction
+): void {
+	element?.classList[action](Splash.NSHostClass)
+}
+
+/**
+ * # Prepare Parent Of
+ * 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
+ */
+export function prepareParentOf(ns: Splash): void {
+	setNSHostClass(ns.getNSElement().parentElement, ClassListAction.Add)
+}
+
+/**
+ * # Clean NS Parent Of
+ * 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
+ */
+export function cleanNSParentOf(ns: Splash): void {
+	setNSHostClass(ns.getNSElement().parentElement, ClassListAction.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'
+}
+
+/**
+ * # Element From
+ * Convert the element reference to an element.
+ * @param ref Reference to an element.
+ * @returns { Element | null } Element or null.
+ * @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 elementFrom(ref: Reference): Element | null {
+	return ref instanceof Element ? ref : document.querySelector(ref || '')
+}
+
+/**
+ * # Element Is NS
+ * Check if the element is a 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(Splash.NSClass) ?? false
+}
+
+/**
+ * # Move
+ * Move an Element to another Element.
+ * @param element Element to move
+ * @param targetElement Target element
+ */
+export function move(element: Element, targetElement: Element): void {
+	// Clean the current NS host element.
+	setNSHostClass(element.parentElement, ClassListAction.Remove)
+	// Assign new NS host element.
+	setNSHostClass(targetElement, ClassListAction.Add)
+	injectAsFirstChild(element, targetElement)
+}
+
+/**
+ * # Get Recycled NS
+ * Return the Nanosplash instance inside the target element if it exists.
+ * @param targetElement Element wherein the Nanosplash instance is to reside.
+ * @returns { Nanosplash | null } Nanosplash instance or null.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Document/firstElementChild
+ */
+export function getRecycledNS(targetElement: Element): Splash | null {
+	const firstChild = targetElement.firstElementChild
+	const hasChild = firstChild !== null
+	const targetAlreadyHasNS = hasChild && elementIsNS(firstChild)
+	if (targetAlreadyHasNS) {
+		const id: GUIDString = firstChild.id
+		const nss = Service.getInstance()
+		return nss.nsStack.find((ns: Splash) => ns.getId() === id) ?? null
+	}
+
+	return null
+}

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/ServiceInterface.ts

@@ -0,0 +1,60 @@
+// @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[]
+
+	/**
+	 * # Show
+	 * Present a Nanosplash in the browser window displaying the given text.
+	 * @param text Text to display.
+	 * @returns {GUIDString} Nanosplash ID.
+	 */
+	show(text?: string): GUIDString
+
+	/**
+	 * # Show Inside
+	 * Present a Nanosplash over the given element displaying the given text.
+	 * @param ref Reference an element.
+	 * @param text Text to display.
+	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
+	 */
+	showInside(ref: Reference, text?: string): GUIDString | null
+
+	/**
+	 * # Hide
+	 * Hide the last created Nanosplash.
+	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
+	 */
+	hide(): GUIDString | null
+
+	/**
+	 * # Hide All
+	 * Hide all Nanosplashes.
+	 */
+	hideAll(): void
+
+	/**
+	 * # Hide ID
+	 * Hide Nanosplash by its ID.
+	 * @param id Nanosplash ID.
+	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
+	 */
+	hideId(id: GUIDString): GUIDString | null
+
+	/**
+	 * # Hide Inside
+	 * Hide Nanosplash inside the given element if it exists.
+	 * @param ref Reference an element.
+	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
+	 */
+	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
+	}
+}