nanosplash 3.0.9 → 3.1.1

package/docs/api/doc/show.md

@@ -32,11 +32,11 @@ ns.show(text?: string, ref?: Element | string): number | null
 ```js
 // DOM selector
 const selector: string = '#my-table'
-ns.showInside('Loading', selector)
+ns.show('Loading', selector)
 
 // Element
 const element: HTMLElement = document.getElementById('my-table')
-ns.showInside('Loading', element)
+ns.show('Loading', element)
 ```
 
 ::: tip

package/docs/api/start/customize.md

@@ -0,0 +1,30 @@
+# Customize
+
+Styling Nanosplash to your needs is easy!
+
+```css
+/* Backdrop */
+.nsh::before {
+	background-color: var(--your-bg);
+	backdrop-filter: var(--your-filter);
+}
+
+/* Main */
+.ns {
+	gap: var(--text-spinner-gap);
+}
+
+/* Text */
+.nst {
+	color: var(--color);
+	font-size: var(--size);
+	font-family: var(--font);
+	font-weight: var(--weight);
+}
+
+/* Spinner */
+.nss {
+	width: var(--spinner-width);
+	height: var(--spinner-height);
+}
+```

package/docs/api/start/features.md

@@ -4,7 +4,7 @@
 
 The Nanosplash bundle is less than 2KB minified and gzipped and will not add any significant weight to your application what so ever. Go to [Bundlephobia](https://bundlephobia.com/package/nanosplash) to see for yourself.
 
-## Simple API
+## Simple, 2 Function API
 
 Nanosplash was written from the ground up with simplicity in mind. The API is very simple and easy to use, and you can easily get started in seconds. Just install the package and start using `ns.show` and `ns.hide`. Go to [Getting started](/api/start/install.md) to see how.
 
@@ -12,6 +12,6 @@ Nanosplash was written from the ground up with simplicity in mind. The API is ve
 
 With Nanosplash you can spawn a splash element anywhere in your DOM. You can even spawn multiple splash elements if you want to. Go to the [API Documentation](/api/doc/show#show-inside) to see how.
 
-## Element recycling
+## Node recycling
 
 Instead of creating new elements all the time and exhausting DOM manipulations, we recycle and repurpose obsolete splash elements instead. For each time a splash element is created, we check for existing splash elements inside the parent element and use them instead of creating new ones.

package/docs/api/start/install.md

@@ -12,20 +12,22 @@ CSS is included inside the JS bundle. 🎉
 
 ## Install via CDN
 
-Add the following script tag to the `<head>` of your HTML document:
+Add the following script tag inside of the `<body>` tag:
 
 ```html
 <script src="https://unpkg.com/nanosplash/dist/iife/ns.iife.js"></script>
 ```
 
-```html{5}
+```html{7}
 <html>
 	<head>
 		<meta charset="UTF-8" />
 		<title>My awesome application 🚀</title>
-		<script src="https://unpkg.com/nanosplash/dist/iife/ns.iife.js"></script>
 	</head>
-	...
+	<body>
+		<script src="https://unpkg.com/nanosplash/dist/iife/ns.iife.js"></script>
+		...
+	</body>
 </html>
 ```
 

package/docs/api/start/usage.md

@@ -15,8 +15,8 @@ ns.hide()
 
 // Hide specific loading screen
 const id = ns.show('Loading')
-ns.hideId(id)
+ns.hide(id)
 
 // Hide all loading screens
-ns.hideAll()
+ns.hide('*')
 ```

package/docs/index.md

@@ -18,16 +18,16 @@ hero:
       link: /api/doc/show.md
 
 features:
-  - title: 📦 Tiny
+  - title: ✨ Tiny
     details: Less than 2KB minified and gzipped.
     link: /api/start/features#small-bundle-size
-  - title: 🍼 Simple API
+  - title: ✌️ 2 Function API
     details: Start using Nanosplash in seconds.
     link: /api/start/features#simple-api
-  - title: 🧚 Spawning
+  - title: 🪴 Spawning
     details: Spawn a splash element anywhere in your DOM.
     link: /api/start/features#spawning
-  - title: ♻️ Element recycling
+  - title: 🚀 Node recycling
     details: Nanosplash will recycle existing elements.
     link: /api/start/features#element-recycling
 ---

package/package.json

@@ -1,92 +1,91 @@
 {
-	"name": "nanosplash",
-	"version": "3.0.9",
-	"author": {
-		"name": "Isak K. Hauge",
-		"email": "isakhauge@icloud.com",
-		"url": "https://no.linkedin.com/in/isakhauge"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/isakhauge/nanosplash.git"
-	},
-	"main": "./dist/es/ns.js",
-	"module": "./dist/es/ns.js",
-	"devDependencies": {
-		"@types/jsdom": "^21.1.6",
-		"@types/node": "^20.11.25",
-		"@types/rollup": "^0.54.0",
-		"@vitest/coverage-v8": "^1.3.1",
-		"@vitest/ui": "^1.3.1",
-		"cross-env": "^7.0.3",
-		"eslint": "^8.57.0",
-		"eslint-config-prettier": "^9.1.0",
-		"eslint-plugin-prettier": "^5.1.3",
-		"jsdom": "^24.0.0",
-		"sass": "^1.71.1",
-		"stylelint-prettier": "^5.0.0",
-		"terser": "^5.29.1",
-		"typescript": "5.3.3",
-		"typescript-eslint": "^7.1.1",
-		"vite": "^5.1.5",
-		"vitepress": "1.0.0-rc.45",
-		"vitest": "^1.3.1"
-	},
-	"exports": {
-		".": {
-			"types": {
-				"require": "./src/ts/types/global.d.ts",
-				"default": "./src/ts/types/global.d.ts"
-			},
-			"browser": {
-				"require": "./dist/cjs/ns.cjs",
-				"default": "./dist/es/ns.js"
-			},
-			"default": {
-				"require": "./dist/cjs/ns.cjs",
-				"default": "./dist/es/ns.js"
-			}
-		}
-	},
-	"description": "The tiny loading screen for web artisans",
-	"homepage": "https://isakhauge.github.io/nanosplash",
-	"keywords": [
-		"loading",
-		"loader",
-		"screen",
-		"splash",
-		"nano",
-		"nanosplash",
-		"small",
-		"tiny",
-		"es",
-		"esm",
-		"ts",
-		"typescript",
-		"iife",
-		"cdn",
-		"vite"
-	],
-	"license": "MIT",
-	"private": false,
-	"scripts": {
-		"build": "bun build:all && bun build:docs",
-		"build:es": "bun x -b tsc && cross-env entry=./src/ts/Nanosplash.ts format=es bun run -b vite build -m production --c vite.config.ts",
-		"build:cjs": "bun x -b tsc && cross-env entry=./src/ts/Nanosplash.ts format=cjs bun run -b vite build -m production --c vite.config.ts",
-		"build:iife": "bun x -b tsc && cross-env entry=./src/ts/main.ts format=iife bun run -b 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",
-		"lint": "bunx eslint src/ts/**/*.ts --fix",
-		"coverage": "vitest --coverage",
-		"docs:dev": "bun x vitepress dev docs",
-		"docs:build": "bun x vitepress build docs",
-		"docs:preview": "bun x vitepress preview docs"
-	},
-	"source": "./src/main.ts",
-	"type": "module",
-	"types": "./src/ts/types/global.d.ts",
-	"unpkg": "./dist/iife/ns.iife.js"
-}
+  "name": "nanosplash",
+  "version": "3.1.1",
+  "author": {
+    "name": "Isak K. Hauge",
+    "email": "isakhauge@icloud.com",
+    "url": "https://no.linkedin.com/in/isakhauge"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/isakhauge/nanosplash.git"
+  },
+  "main": "./dist/es/ns.js",
+  "module": "./dist/es/ns.js",
+  "devDependencies": {
+    "@types/jsdom": "^21.1.6",
+    "@types/node": "^20.11.29",
+    "@types/rollup": "^0.54.0",
+    "@vitest/coverage-v8": "^1.4.0",
+    "@vitest/ui": "^1.4.0",
+    "cross-env": "^7.0.3",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "jsdom": "^24.0.0",
+    "sass": "^1.72.0",
+    "stylelint-prettier": "^5.0.0",
+    "typescript": "5.4.2",
+    "typescript-eslint": "^7.2.0",
+    "vite": "^5.1.6",
+    "vitepress": "",
+    "vitest": "^1.4.0"
+  },
+  "exports": {
+    ".": {
+      "types": {
+        "require": "./src/ts/types/global.d.ts",
+        "default": "./src/ts/types/global.d.ts"
+      },
+      "browser": {
+        "require": "./dist/cjs/ns.cjs",
+        "default": "./dist/es/ns.js"
+      },
+      "default": {
+        "require": "./dist/cjs/ns.cjs",
+        "default": "./dist/es/ns.js"
+      }
+    }
+  },
+  "description": "The tiny loading screen for web artisans",
+  "homepage": "https://isakhauge.github.io/nanosplash",
+  "keywords": [
+    "loading",
+    "loader",
+    "screen",
+    "splash",
+    "nano",
+    "nanosplash",
+    "small",
+    "tiny",
+    "es",
+    "esm",
+    "ts",
+    "typescript",
+    "iife",
+    "cdn",
+    "vite"
+  ],
+  "license": "MIT",
+  "private": false,
+  "source": "./src/main.ts",
+  "type": "module",
+  "types": "./src/ts/types/global.d.ts",
+  "unpkg": "./dist/iife/ns.iife.js",
+  "scripts": {
+    "build": "pnpm build:all && pnpm build:docs",
+    "build:es": "tsc && cross-env entry=./src/ts/Nanosplash.ts format=es vite build -m production --c vite.config.ts",
+    "build:cjs": "tsc && cross-env entry=./src/ts/Nanosplash.ts format=cjs vite build -m production --c vite.config.ts",
+    "build:iife": "tsc && cross-env entry=./src/ts/main.ts format=iife vite build -m production --c vite.config.ts",
+    "build:all": "pnpm build:es && pnpm build:cjs && pnpm build:iife",
+    "build:docs": "pnpm docs:build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "lint": "eslint src/ts/**/*.ts --fix",
+    "coverage": "vitest --coverage",
+    "docs:dev": "pnpm exec vitepress dev docs",
+    "docs:build": "pnpm exec vitepress build docs",
+    "docs:preview": "pnpm exec vitepress preview docs"
+  }
+}

package/src/style/ns.sass

@@ -1,9 +1,9 @@
 // Spinner animations:
-@keyframes ns-rotate
+@keyframes nsRotate
 	100%
 		transform: rotate(360deg)
 
-@keyframes ns-dash
+@keyframes nsDash
 	0%
 		stroke-dasharray: 1, 150
 		stroke-dashoffset: 0
@@ -14,13 +14,13 @@
 		stroke-dasharray: 90, 150
 		stroke-dashoffset: -124
 
-@keyframes ns-fade
+@keyframes nsFade
 	from
 		opacity: 0
 	to
 		opacity: 1
 
-@keyframes ns-ascend
+@keyframes nsAscend
 	from
 		opacity: 0
 		transform: translateY(13px)
@@ -85,12 +85,8 @@ body.nsh
 	@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.07rem #{ rgba(Black, 0.25) })
+	animation: nsFade 2s
+	gap: var(--relSize)
 
 // Nanosplash text
 .nst
@@ -98,23 +94,22 @@ body.nsh
 	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
+	filter: drop-shadow(0 0 0.07rem #{ rgba(Black, 0.25) })
+	animation: nsAscend 0.5s
 
 // Nanosplash spinner
 .nss
 	display: block
 	width: var(--relSize)
 	height: var(--relSize)
-	animation: ns-ascend 500ms
+	animation: nsAscend 0.5s
 	& > svg
-		animation: ns-rotate 2s linear infinite
+		animation: nsRotate 2s linear infinite
 		position: relative
 		width: inherit
 		height: inherit
@@ -122,4 +117,4 @@ body.nsh
 	& .path
 		stroke: var(--color)
 		stroke-linecap: round
-		animation: ns-dash 1.5s ease-in-out infinite
+		animation: nsDash 1.5s ease-in-out infinite

package/src/ts/Nanosplash.ts

@@ -9,29 +9,29 @@ import {
 } from './types/Types'
 import { version } from '../../package.json'
 
-const StyleID: string = 'nscss'
+const styleId: string = 'ns'
+const doc: Document = document
+const bod: HTMLElement = doc.body
 
 /**
- *
+ * # Scope
+ * Creates scoped selectors.
  * @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 {
+const scope = (node: ParentNode): ScopedSelectors =>
+	(all => ({
 		all,
 		first: (ref: string) => all(ref)[0] ?? null,
-	}
-}
+	}))((ref: string) => Array.from(node.querySelectorAll(ref)))
 
 /**
  * # 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)
+const getAll = (selector: DOMSelector): Element[] => scope(doc).all(selector)
 
 /**
  * # Get
@@ -39,28 +39,24 @@ const getAll = (selector: DOMSelector): Element[] =>
  * @returns Firs Element node from the DOM matching the selector.
  */
 const get = (selector: DOMSelector): Element | null =>
-	scope(document).first(selector)
+	scope(doc).first(selector)
 
 /**
- * # Get All NS
+ * # Get All Nanosplashes
  * @returns An array of all Nanosplash elements in the DOM.
  */
-const getAllNS = (): NSElement[] => getAll('.ns') as NSElement[]
+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
-}
+const parseRef = (ref: ElementReference): Element | null =>
+	ref instanceof Element ? ref : get(ref)
 
 /**
- * # Div
+ * # Create HTMLDivElement
  * @param className Optional string containing class names.
  * @param children Optional list of Nodes or strings.
  * @returns The newly created HTMLDivElement.
@@ -69,10 +65,10 @@ const div = (
 	className?: string,
 	...children: (Node | string)[]
 ): HTMLDivElement => {
-	const el = document.createElement('div')
-	if (className) el.classList.add(className)
-	el.append(...children)
-	return el
+	const node: HTMLDivElement = doc.createElement('div')
+	if (className) node.classList.add(className)
+	node.append(...children)
+	return node
 }
 
 /**
@@ -81,60 +77,57 @@ const div = (
  * @returns Parsed node.
  */
 const parse = (html: string): Node => {
-	const el: HTMLDivElement = div()
-	el.innerHTML = html
-	return el.firstChild as Node
+	const node: HTMLDivElement = div()
+	node.innerHTML = html
+	return node.firstChild as Node
 }
 
 /**
- * # Create NS
- * TODO: Investigate the possibility of inheritence.
+ * # Make Nanosplash Element
  * @returns Nanpslash DOM element.
  */
-const createNS = (): NSElement => {
+const makeNs = (): 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
+	const node = div('ns', div('nst'), div('nss', svg)) as NSElement
+	node.nsId = Date.now()
+	return node
 }
 
 /**
- * # Peek
+ * # Peek Nanosplash Queue
  * 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
+const peekNsQueue = (): NSElement | null =>
+	getAllNs().sort((a: NSElement, b: NSElement) => a.nsId - b.nsId)[0] ?? null
 
 /**
- * # Set NS Text
+ * # Set Nanosplash 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)
+const setNsText = (ns: NSElement, text: string): void => {
+	const oldNsText = scope(ns).first('.nst') as Element | null
+	if (!text) return oldNsText?.remove()
+	const newNsText = div('nst', text)
+	if (oldNsText) {
+		oldNsText.replaceWith(newNsText)
 	} else {
-		const nsc = nsScope.first('.nsc') as Element
-		nsc.insertBefore(newNst, nsc.firstChild)
+		ns.insertBefore(newNsText, ns.firstChild)
 	}
 }
 
 /**
- * # Set NS Parent
+ * # Set Nanosplash 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 setNsParent = (ns: NSElement, parent: Element): void => {
 	const child = parent.firstElementChild
 	if (child) {
 		parent.insertBefore(ns, child)
@@ -144,76 +137,73 @@ const setNSParent = (ns: NSElement, parent: Element): void => {
 }
 
 /**
- * # Show
+ * # Show Nanosplash
  * @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
+	const parent: Element | null = (
+		inside ? parseRef(inside) : bod
+	) as Element | null
 	let ns: NSElement
-	const recycledNs = scope(parent).first('& > .ns')
+	const recycledNs = scope(parent ?? bod).first('& > .ns')
 	if (recycledNs) {
 		ns = recycledNs as NSElement
 	} else {
-		ns = createNS()
-		setNSParent(ns, parent as Element)
+		ns = makeNs()
+		setNsParent(ns, parent as Element)
 	}
-	setNSText(ns, text ?? '')
-	const top: string = window.scrollY + 'px'
-	window.document.body.style.setProperty('--ns-top', top)
+	setNsText(ns, text ?? '')
+	const top: string = scrollY + 'px'
+	bod.style.setProperty('--ns-top', top)
 	return ns.nsId
 }
 
 /**
- * # Delete NS
+ * # Remove Nanosplash
  * @param ns Nanosplash elememnt.
  */
-const deleteNS = (ns?: Element | null): void => {
+const removeNs = (ns?: Element | null): void => {
 	ns?.parentElement?.classList.remove('nsh')
 	ns?.remove()
 }
 
 /**
- * # Find NS
+ * # Find Nanosplash
  * @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
+const findNs = (id: number) => getAllNs().find(v => v.nsId === id) ?? null
 
 /**
- * # Hide
- * @param id Optional ID of a Nanosplash element.
+ * # Hide Nanosplash
+ * Hide agnostically in FIFO order, specifically by ID, or all by the asterisk
+ * which will delete all Nanosplashes.
+ * @param id Optional ID of a Nanosplash element or '*' .
  */
-const hide = (id?: number): void => {
-	const ns: NSElement | null = id ? findNS(id) : peek()
-	deleteNS(ns)
+const hide = (id?: number | '*'): void => {
+	if (id === '*') getAll('.ns').forEach(removeNs)
+	else removeNs(typeof id === 'number' ? findNs(id) : peekNsQueue())
 }
 
 /**
- * # Hide All
- */
-const hideAll = (): void => getAll('.ns').forEach(deleteNS)
-
-/**
- * # Add style
+ * # Add CSS
  */
-const addStyle = (): void => {
-	get('#nscss')?.remove()
-	const html: string = `<style id=${StyleID}>${style}</style>`
-	document.body.append(parse(html))
+const addCssToBody = (): void => {
+	get('#' + styleId)?.remove()
+	bod.append(parse(`<style id=${styleId}>${style}</style>`))
 }
 
 /**
- * # Use NS
+ * # Use Nanosplash
  * @returns Nanosplash API.
  */
 export const useNs = (): NanosplashInterface => {
-	addStyle()
-	return (window.ns = Object.freeze({
+	addCssToBody()
+	return (window.ns = {
 		show,
 		hide,
-		hideAll,
 		version,
-	}))
+	})
 }