nanosplash 3.0.8 → 3.1.0

package/src/ts/types/Types.ts

@@ -1,3 +1,29 @@
-export type GUIDString = string
-export type CSSSelector = string
-export type Reference = CSSSelector | Element
+import { NanosplashInterface } from './NanosplashInterface'
+
+export type Integer = number
+export type UTCInteger = Integer
+export type DOMSelector = string
+export type ElementReference = DOMSelector | Element
+
+export interface ScopedSelectors {
+	/**
+	 * @param selector Selector to match with a DOM element.
+	 * @returns An array of elements matching with the selector.
+	 */
+	all: (selector: DOMSelector) => Element[]
+	/**
+	 * @param selector Selector to match with a DOM element.
+	 * @returns Null or the first element in the DOM to match the selector.
+	 */
+	first: (selector: DOMSelector) => Element | null
+}
+
+export interface NSElement extends HTMLDivElement {
+	nsId: number
+}
+
+declare global {
+	interface Window {
+		ns: NanosplashInterface
+	}
+}

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

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

package/tests/Nanosplash.spec.ts

@@ -0,0 +1,33 @@
+import { describe, it, test, expect, beforeEach } from 'vitest'
+import { useNs } from '../src/ts/Nanosplash'
+import { JSDOM } from 'jsdom'
+import { NanosplashInterface } from '../src/ts/types/NanosplashInterface'
+
+let document: Document | null = null
+let ns: NanosplashInterface | null = null
+
+beforeEach(() => {
+	const dom = new JSDOM()
+	// @ts-ignore
+	globalThis.window = dom.window
+	document = globalThis.document = dom.window.document
+	ns = globalThis.window.ns = useNs()
+})
+
+describe('Nanosplash API', () => {
+	it('should be defined', () => {
+		expect(window.ns).toBeDefined()
+	})
+
+	it('should have the "show" method', () => {
+		expect(window.ns.show).toBeDefined()
+	})
+
+	it('should have the "hide" method', () => {
+		expect(window.ns.hide).toBeDefined()
+	})
+
+	it('should have the global instance', () => {
+		expect(window.ns).toBe(ns)
+	})
+})

package/.prettierignore

@@ -1 +0,0 @@
-*.sass

package/src/ts/core/DomUtilities.ts

@@ -1,161 +0,0 @@
-import { Reference } 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>
- */
-
-/**
- * # Render
- * @param html HTML string to render.
- * @returns Rendered HTML element.
- */
-export function render(html: string): HTMLElement {
-	return (div =>
-		// @ts-ignore
-		(() => div.firstChild as HTMLElement)((div.innerHTML = html)))(
-		document.createElement('div')
-	)
-}
-
-/**
- * # Create Element
- * Return the main Nanosplash element.
- */
-export function createElement(): HTMLDivElement {
-	return render(
-		'<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>'
-	) 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)
-	}
-}
-
-/**
- * # Add NS Host Class
- * Add the `nsHostClassName` class to the `element`.
- * @param element Element to which the `nsHostClassName` class will be added.
- * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/classList
- * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/add
- */
-export function addNSHostClass(element: Element | null): void {
-	element?.classList.add(Splash.NSHostClass)
-}
-
-/**
- * # Remove NS Host Class
- * Remove the `nsHostClassName` class from the `element`.
- * @param element Element from which the `nsHostClassName` class will be removed.
- * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/classList
- * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/remove
- */
-export function removeNSHostClass(element: Element | null): void {
-	element?.classList.remove(Splash.NSHostClass)
-}
-
-/**
- * # 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 {
-	switch (typeof ref) {
-		case 'object':
-			const isBody = ref === document.body
-			const isElement = ref instanceof Element
-			if (isBody || isElement) {
-				return ref
-			}
-			throw new Error(
-				'Reference is an object but not an Element instance.'
-			)
-		case 'string':
-			return document.querySelector(ref)
-		default:
-			throw new Error('Reference is not an object or a string.')
-	}
-}
-
-/**
- * # 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.
-	removeNSHostClass(element.parentElement)
-	// Assign new NS host element.
-	addNSHostClass(targetElement)
-	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 getRecycledSplash(targetElement: Element): Splash | null {
-	const children = Array.from(targetElement.children || [])
-	const nss = Service.getInstance()
-	let splash: Splash | null = null
-	const n = children.length
-	for (let i = 0; i < n; i++) {
-		const child = children[i]
-		if (child.classList.contains(Splash.NSClass)) {
-			splash = nss.nsQueue.get(child.id) ?? null
-			break
-		}
-	}
-	return splash
-}

package/src/ts/core/Service.ts

@@ -1,211 +0,0 @@
-import { version } from '../../../package.json'
-
-import { Reference, GUIDString } from '../types/Types'
-import {
-	getRecycledSplash,
-	move,
-	elementFrom,
-	render,
-	removeNSHostClass,
-} from './DomUtilities'
-import { ServiceInterface } from './ServiceInterface'
-import { Splash } from './Splash'
-import css from '../../style/ns.sass?inline'
-import { SplashQueue } from './SplashQueue'
-
-/**
- * # 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 nsQueue: SplashQueue
-
-	/**
-	 * # Constructor
-	 * Private constructor to prevent multiple instances.
-	 * @private
-	 */
-	private constructor() {
-		this.version = version
-		this.nsQueue = new SplashQueue()
-		Service.addStyle()
-	}
-
-	/**e
-	 * # Add Style
-	 * Add Nanosplash CSS to the DOM.
-	 */
-	private static addStyle(): void {
-		const style = render(`<style>${css}</style>`) as HTMLStyleElement
-		document.body.append(style)
-	}
-
-	/**
-	 * # 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 {
-		const nss = window[Service.WindowAccessorKey]
-		if (!nss) {
-			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().setText(text || '')
-		this.nsQueue.enqueue(ns)
-		return ns
-	}
-
-	/**
-	 * # Clean And Remove From DOM
-	 * Remove Nanosplash from DOM and clean its parent.
-	 * @param ns Nanosplash instance.
-	 * @returns True if Nanosplash was removed from DOM.
-	 * @private
-	 */
-	private cleanAndRemoveFromDOM(ns: Splash | null): boolean {
-		if (ns) {
-			removeNSHostClass(ns.getElement()?.parentElement ?? null)
-			return ns.delete()
-		}
-		return false
-	}
-
-	/**
-	 * # Delete NS
-	 * Remove Nanosplash instance from both the stack and the
-	 * @param guid Nanosplash ID.
-	 * @returns True if Nanosplash was removed from DOM.
-	 * @private
-	 */
-	private deleteNS(guid: GUIDString): boolean {
-		return this.cleanAndRemoveFromDOM(this.nsQueue.delete(guid) ?? null)
-	}
-
-	/**
-	 * @inheritdoc
-	 */
-	public show(text?: string): GUIDString | null {
-		return this.showInside(document.body, text)
-	}
-
-	/**
-	 * @inheritdoc
-	 */
-	public showInside(ref: Reference, text?: string): GUIDString | null {
-		try {
-			const destinationNode = elementFrom(ref) as Element
-			const ns = getRecycledSplash(destinationNode) ?? this.createNS()
-			move(ns.getElement() as Element, destinationNode)
-			const parsedText = text ? String(text) : ''
-			return ns.setText(parsedText).getId()
-		} catch (e) {
-			console.error(e)
-			return null
-		}
-	}
-
-	/**
-	 * @inheritdoc
-	 */
-	public hide(): GUIDString | null {
-		const ns = this.nsQueue.dequeue()
-		if (!ns) return null
-		this.cleanAndRemoveFromDOM(ns)
-		return ns.getId()
-	}
-
-	/**
-	 * @inheritdoc
-	 */
-	public hideAll(): void {
-		let ns = this.nsQueue.dequeue()
-		while (ns) {
-			this.cleanAndRemoveFromDOM(ns)
-			ns = this.nsQueue.dequeue()
-		}
-	}
-
-	/**
-	 * @inheritdoc
-	 */
-	public hideId(id: GUIDString): GUIDString | null {
-		return this.deleteNS(id) ? id : null
-	}
-
-	/**
-	 * @inheritdoc
-	 */
-	public hideInside(ref: Reference): GUIDString | null {
-		try {
-			const ns = getRecycledSplash(elementFrom(ref) as Element)
-			const guid = ns?.getId() ?? ''
-			return this.deleteNS(guid ?? '') ? guid : null
-		} catch (e) {
-			console.error(e)
-			return null
-		}
-	}
-}
-
-export default { Service }

package/src/ts/core/ServiceInterface.ts

@@ -1,58 +0,0 @@
-import { GUIDString, Reference } from '../types/Types'
-import { SplashQueue } from './SplashQueue'
-
-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 nsQueue: SplashQueue
-
-	/**
-	 * # Show
-	 * Present a Nanosplash in the browser window displaying the given text.
-	 * @param text Text to display.
-	 * @returns {GUIDString | null} Nanosplash ID.
-	 */
-	show(text?: string): GUIDString | null
-
-	/**
-	 * # 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 oldest 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

@@ -1,121 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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
-}