nanosplash 3.0.7 → 3.0.9

package/src/style/ns.sass

@@ -1,95 +1,125 @@
+// Spinner animations:
+@keyframes ns-rotate
+	100%
+		transform: rotate(360deg)
+
+@keyframes ns-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
+
+@keyframes ns-fade
+	from
+		opacity: 0
+	to
+		opacity: 1
+
+@keyframes ns-ascend
+	from
+		opacity: 0
+		transform: translateY(13px)
+	to
+		opacity: 1
+		transform: translateY(0)
+
+:root
+	--ns-top: 0px
+
 %maximize
-    width: 100%
-    height: 100%
+	width: 100%
+	height: 100%
 
-%upper-left
-    top: 0
-    left: 0
+%bottom-left
+	bottom: 0
+	right: 0
 
 %flex-center-xy
-    display: flex
-    justify-content: center
-    align-items: center
+	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)
+	--color: DarkSlateGray
+	--size: 20px
+	--relSize: calc(var(--size) * 0.9)
+	--font: 'Helvetica', 'Arial', sans-serif
+	--weight: 400
+	--bg: #{ rgba(White, 0.9) }
+	--zIdx: 999999999
+	--blur: blur(5px)
 
 // 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
+	position: relative
+	z-index: var(--zIdx)
+	&::before // The backdrop
+		@extend %maximize
+		@extend %bottom-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
+	&, &::before
+		@extend %maximize
+		position: fixed
+		top: var(--ns-top)
+		left: 0
 
 // Nanosplash (main element)
 .ns
-    @extend %maximize
-    @extend %upper-left
-    @extend %flex-center-xy
-    position: absolute
-    z-index: calc(var(--zIdx) + 2)
+	@extend %maximize
+	@extend %bottom-left
+	@extend %flex-center-xy
+	position: absolute
+	z-index: calc(var(--zIdx) + 2)
+	animation: ns-fade 2s
 
 // Nanosplash container
 .nsc
-    @extend %flex-center-xy
-    filter: drop-shadow(0 0 0.1rem #{ rgba(LightGray, 0.5) })
+	@extend %flex-center-xy
+	filter: drop-shadow(0 0 0.07rem #{ rgba(Black, 0.25) })
 
 // 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) }
+	color: var(--color)
+	font-size: var(--size)
+	font-family: var(--font)
+	font-weight: var(--weight)
+	font-optical-sizing: auto
+	max-width: 80dvw
+	white-space: nowrap
+	text-overflow: ellipsis
+	overflow: hidden
+	margin-right: var(--relSize)
+	text-shadow: 0 0 0.06rem #{ rgba(DarkSlateGray, .25) }
+	animation: ns-ascend 500ms
 
 // 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
+	display: block
+	width: var(--relSize)
+	height: var(--relSize)
+	animation: ns-ascend 500ms
+	& > svg
+		animation: ns-rotate 2s linear infinite
+		position: relative
+		width: inherit
+		height: inherit
+		stroke-width: 8
+	& .path
+		stroke: var(--color)
+		stroke-linecap: round
+		animation: ns-dash 1.5s ease-in-out infinite

package/src/ts/Nanosplash.ts

@@ -0,0 +1,219 @@
+// @ts-strict
+import style from '../style/ns.sass?inline'
+import { NanosplashInterface } from './types/NanosplashInterface'
+import {
+	DOMSelector,
+	ElementReference,
+	NSElement,
+	ScopedSelectors,
+} from './types/Types'
+import { version } from '../../package.json'
+
+const StyleID: string = 'nscss'
+
+/**
+ *
+ * @param node Node to query.
+ * @returns An object containing two, slightly different functions that
+ * retrieves elements from the DOM.
+ */
+const scope = (node: ParentNode): ScopedSelectors => {
+	const all = (ref: string) => Array.from(node.querySelectorAll(ref))
+	return {
+		all,
+		first: (ref: string) => all(ref)[0] ?? null,
+	}
+}
+
+/**
+ * # Get all
+ * @param selector CSS selector used to match nodes in the DOM.
+ * @returns An array of Element nodes.
+ */
+const getAll = (selector: DOMSelector): Element[] =>
+	scope(document).all(selector)
+
+/**
+ * # Get
+ * @param selector CSS selector used to match nodes in the DOM.
+ * @returns Firs Element node from the DOM matching the selector.
+ */
+const get = (selector: DOMSelector): Element | null =>
+	scope(document).first(selector)
+
+/**
+ * # Get All NS
+ * @returns An array of all Nanosplash elements in the DOM.
+ */
+const getAllNS = (): NSElement[] => getAll('.ns') as NSElement[]
+
+/**
+ * # Parse Ref
+ * @param ref Element reference which could be a selector or an Element.
+ * @returns The Element node or null.
+ */
+const parseRef = (ref: ElementReference): Element => {
+	if (ref instanceof Element) return ref
+	const element = get(ref)
+	if (!element) throw new Error(`Selector (${ref}) returned null`)
+	return element
+}
+
+/**
+ * # Div
+ * @param className Optional string containing class names.
+ * @param children Optional list of Nodes or strings.
+ * @returns The newly created HTMLDivElement.
+ */
+const div = (
+	className?: string,
+	...children: (Node | string)[]
+): HTMLDivElement => {
+	const el = document.createElement('div')
+	if (className) el.classList.add(className)
+	el.append(...children)
+	return el
+}
+
+/**
+ * # Parse
+ * @param html HTML string.
+ * @returns Parsed node.
+ */
+const parse = (html: string): Node => {
+	const el: HTMLDivElement = div()
+	el.innerHTML = html
+	return el.firstChild as Node
+}
+
+/**
+ * # Create NS
+ * TODO: Investigate the possibility of inheritence.
+ * @returns Nanpslash DOM element.
+ */
+const createNS = (): NSElement => {
+	const circle: string = '<circle class=path cx=25 cy=25 r=20 fill=none />'
+	const svg = parse(`<svg viewBox="0 0 50 50">${circle}</svg>`) as Element
+	const el = div('ns', div('nsc', div('nst'), div('nss', svg))) as NSElement
+	el.nsId = Date.now()
+	return el
+}
+
+/**
+ * # Peek
+ * Collect all Nanosplash elements in the DOM, sort them by their NS ID
+ * in ascending order, and return the first element.
+ * @returns The front of the queue.
+ */
+const peek = (): NSElement | null =>
+	getAllNS().sort((a: NSElement, b: NSElement) => a.nsId - b.nsId)[0] ?? null
+
+/**
+ * # Set NS Text
+ * Replace the text node to trigger the animation which in turn is invoked
+ * by the connected callback in the DOM.
+ * @param ns Nanosplash element.
+ * @param text Text to display adjacent to spinner.
+ */
+const setNSText = (ns: NSElement, text: string): void => {
+	const nsScope = scope(ns)
+	const oldNst = nsScope.first('.nst') as Element | null
+	if (!text) return oldNst?.remove()
+	const newNst = div('nst', text)
+	if (oldNst) {
+		oldNst.replaceWith(newNst)
+	} else {
+		const nsc = nsScope.first('.nsc') as Element
+		nsc.insertBefore(newNst, nsc.firstChild)
+	}
+}
+
+/**
+ * # Set NS Parent
+ * Define where inside the DOM to spawn the Nansoplash.
+ * @param ns Nanosplash element.
+ * @param parent NS element's parent to be.
+ */
+const setNSParent = (ns: NSElement, parent: Element): void => {
+	const child = parent.firstElementChild
+	if (child) {
+		parent.insertBefore(ns, child)
+	}
+	parent.append(ns)
+	parent.classList.add('nsh')
+}
+
+/**
+ * # Show
+ * @param text Text to display adjacent to spinner.
+ * @param inside Selector or element in which the NS element will be spawned.
+ * @returns The ID if the NS element — which is a UTC integer.
+ */
+const show = (text?: string, inside?: string | Element): number | null => {
+	const parent: Element = inside ? parseRef(inside) : document.body
+	let ns: NSElement
+	const recycledNs = scope(parent).first('& > .ns')
+	if (recycledNs) {
+		ns = recycledNs as NSElement
+	} else {
+		ns = createNS()
+		setNSParent(ns, parent as Element)
+	}
+	setNSText(ns, text ?? '')
+	const top: string = window.scrollY + 'px'
+	window.document.body.style.setProperty('--ns-top', top)
+	return ns.nsId
+}
+
+/**
+ * # Delete NS
+ * @param ns Nanosplash elememnt.
+ */
+const deleteNS = (ns?: Element | null): void => {
+	ns?.parentElement?.classList.remove('nsh')
+	ns?.remove()
+}
+
+/**
+ * # Find NS
+ * @param id The UTC integer returned from the `show` function.
+ * @returns Null or the corresponding Nanosplash element.
+ */
+const findNS = (id: number) => getAllNS().find(v => v.nsId === id) ?? null
+
+/**
+ * # Hide
+ * @param id Optional ID of a Nanosplash element.
+ */
+const hide = (id?: number): void => {
+	const ns: NSElement | null = id ? findNS(id) : peek()
+	deleteNS(ns)
+}
+
+/**
+ * # Hide All
+ */
+const hideAll = (): void => getAll('.ns').forEach(deleteNS)
+
+/**
+ * # Add style
+ */
+const addStyle = (): void => {
+	get('#nscss')?.remove()
+	const html: string = `<style id=${StyleID}>${style}</style>`
+	document.body.append(parse(html))
+}
+
+/**
+ * # Use NS
+ * @returns Nanosplash API.
+ */
+export const useNs = (): NanosplashInterface => {
+	addStyle()
+	return (window.ns = Object.freeze({
+		show,
+		hide,
+		hideAll,
+		version,
+	}))
+}

package/src/ts/main.ts

@@ -1,9 +1,3 @@
 // @ts-strict
-
-import { Service } from './core/Service'
-
-try {
-	Service.start()
-} catch (e) {
-	console.warn(e)
-}
+import { useNs } from './Nanosplash'
+useNs() // Attach API to global scope (Window)

package/src/ts/types/NanosplashInterface.ts

@@ -0,0 +1,7 @@
+import { DOMSelector, UTCInteger } from './Types'
+
+export interface NanosplashInterface {
+	show(text?: string, inside?: DOMSelector | HTMLElement): UTCInteger | null
+	hide(id?: UTCInteger): void
+	hideAll(): void
+}

package/src/ts/types/Types.ts

@@ -1,3 +1,28 @@
-export type GUIDString = string
-export type CSSSelector = string
-export type Reference = CSSSelector | Element
+import { NanosplashInterface } from './NanosplashInterface'
+
+export type UTCInteger = number
+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,35 @@
+import { describe, it, test, expect, beforeEach } from 'vitest'
+import { useNs } from '../src/ts/Nanosplash'
+import { JSDOM } from 'jsdom'
+
+let ns
+
+beforeEach(() => {
+	const dom = new JSDOM()
+	// @ts-ignore
+	globalThis.window = dom.window
+	globalThis.document = window.document
+	globalThis.window.ns = 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 "hideAll" method', () => {
+		expect(window.ns.hideAll).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
-}