nanosplash 3.0.0 → 3.0.2

package/package.json

@@ -1,67 +1,87 @@
 {
-  "name": "nanosplash",
-  "description": "The tiny loading screen for web artisans",
-  "private": false,
-  "version": "3.0.0",
-  "type": "module",
-  "author": {
-    "name": "Isak K. Hauge",
-    "email": "isakhauge@icloud.com",
-    "url": "https://no.linkedin.com/in/isakhauge"
-  },
-  "keywords": [
-    "loading",
-    "loader",
-    "screen",
-    "splash",
-    "nano",
-    "nanosplash",
-    "small",
-    "tiny",
-    "es",
-    "esm",
-    "ts",
-    "typescript",
-    "iife",
-    "cdn",
-    "vite"
-  ],
-  "homepage": "https://isakhauge.github.io/nanosplash",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/isakhauge/nanosplash.git"
-  },
-  "license": "MIT",
-  "main": "./dist/ns.js",
-  "module": "./dist/ns.es.js",
-  "source": "./src/Nanosplash.ts",
-  "unpkg": "./dist/ns.iife.js",
-  "style": "./dist/main.css",
-  "exports": {
-    ".": {
-      "import": "./dist/ns.es.js",
-      "require": "./dist/ns.cjs.js",
-      "default": "./dist/ns.es.js"
-    }
-  },
-  "types": "./src/ts/types",
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
-    "preview": "vite preview",
-    "test": "vitest",
-    "test:ui": "vitest --ui",
-    "coverage": "vitest run --coverage"
-  },
-  "devDependencies": {
-    "@types/jsdom": "^21.1.1",
-    "@vitest/coverage-c8": "^0.31.4",
-    "@vitest/ui": "^0.31.4",
-    "jsdom": "^22.1.0",
-    "sass": "^1.62.1",
-    "terser": "^5.17.7",
-    "typescript": "^5.0.4",
-    "vite": "^4.3.9",
-    "vitest": "^0.31.4"
-  }
-}
+	"name": "nanosplash",
+	"description": "The tiny loading screen for web artisans",
+	"private": false,
+	"version": "3.0.2",
+	"type": "module",
+	"author": {
+		"name": "Isak K. Hauge",
+		"email": "isakhauge@icloud.com",
+		"url": "https://no.linkedin.com/in/isakhauge"
+	},
+	"keywords": [
+		"loading",
+		"loader",
+		"screen",
+		"splash",
+		"nano",
+		"nanosplash",
+		"small",
+		"tiny",
+		"es",
+		"esm",
+		"ts",
+		"typescript",
+		"iife",
+		"cdn",
+		"vite"
+	],
+	"homepage": "https://isakhauge.github.io/nanosplash",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/isakhauge/nanosplash.git"
+	},
+	"license": "MIT",
+	"main": "./dist/latest/es/ns.js",
+	"module": "./dist/latest/es/ns.js",
+	"source": "./src/main.ts",
+	"unpkg": "./dist/latest/iife/ns.iife.js",
+	"style": "./dist/latest/es/style.css",
+	"exports": {
+		".": {
+			"types": {
+				"require": "./src/ts/types/global.d.ts",
+				"default": "./src/ts/types/global.d.ts"
+			},
+			"browser": {
+				"require": "./dist/latest/cjs/ns.cjs",
+				"default": "./dist/latest/es/ns.js"
+			},
+			"default": {
+				"require": "./dist/latest/cjs/ns.cjs",
+				"default": "./dist/latest/es/ns.js"
+			}
+		}
+	},
+	"types": "./src/ts/types/global.d.ts",
+	"scripts": {
+		"build": "bun build:all && bun build:docs",
+		"build:es": "tsc && cross-env entry=./src/ts/core/Service.ts format=es bun vite build -m production --c vite.config.ts",
+		"build:cjs": "tsc && cross-env entry=./src/ts/core/Service.ts format=cjs bun vite build -m production --c vite.config.ts",
+		"build:iife": "tsc && cross-env entry=./src/ts/main.ts format=iife bun vite build -m production --c vite.config.ts",
+		"build:all": "bun build:es && bun build:cjs && bun build:iife",
+		"build:docs": "bun docs:build",
+		"preview": "vite preview",
+		"test": "vitest",
+		"test:ui": "vitest --ui",
+		"coverage": "vitest --coverage",
+		"docs:dev": "vitepress dev docs",
+		"docs:build": "vitepress build docs",
+		"docs:preview": "vitepress preview docs"
+	},
+	"devDependencies": {
+		"@types/jsdom": "^21.1.3",
+		"@types/node": "^20.8.6",
+		"@types/rollup": "^0.54.0",
+		"@vitest/coverage-v8": "^0.34.6",
+		"@vitest/ui": "^0.34.6",
+		"cross-env": "^7.0.3",
+		"jsdom": "^22.1.0",
+		"sass": "^1.69.3",
+		"terser": "^5.22.0",
+		"typescript": "^5.2.2",
+		"vite": "^4.4.11",
+		"vitepress": "1.0.0-rc.22",
+		"vitest": "^0.34.6"
+	}
+}

package/src/style/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/DomUtilities.ts

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

@@ -0,0 +1,211 @@
+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/{Nanosplash/interfaces/NanosplashAPI.ts → ServiceInterface.ts}

@@ -1,27 +1,35 @@
-import { GUIDString } from '../../../types/Alias'
-import { Destination } from '../../../types/Nanosplash'
+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
 
-export interface NanosplashAPI {
 	/**
 	 * # Show
 	 * Present a Nanosplash in the browser window displaying the given text.
 	 * @param text Text to display.
-	 * @returns {GUIDString} Nanosplash ID.
+	 * @returns {GUIDString | null} Nanosplash ID.
 	 */
-	show(text?: string): GUIDString
+	show(text?: string): GUIDString | null
 
 	/**
 	 * # 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
-	 * Hide the last created Nanosplash.
+	 * Hide the oldest Nanosplash.
 	 * @returns {GUIDString | null} Nanosplash ID or null if it doesn't exist.
 	 */
 	hide(): GUIDString | null
@@ -43,8 +51,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
 }