nanosplash 3.0.8 → 3.1.0

package/docs/api/start/usage.md

@@ -1,6 +1,6 @@
 # Usage
 
-```js{2,5,8,11,14,18,21}
+```js{2,5,8,11,15,18}
 // Fullscreen spinning wheel
 ns.show()
 
@@ -8,18 +8,15 @@ ns.show()
 ns.show('Loading')
 
 // Display inside an element
-ns.showInside('#my-table', 'Fetching data')
+ns.show('Fetching data', '#my-table')
 
 // Hide the first created loading screen (FIFO)
 ns.hide()
 
-// Hide loading screen inside an element
-ns.hideInside('#my-table')
-
 // 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

@@ -3,31 +3,31 @@
 layout: home
 
 hero:
-    name: 'Nanosplash'
-    text: ''
-    tagline: The tiny loading screen for web artisans
-    actions:
-        - theme: brand
-          text: Get started
-          link: /api/start/install.md
-        - theme: alt
-          text: Playground
-          link: /api/start/playground.md
-        - theme: alt
-          text: API Documentation
-          link: /api/doc/show.md
+  name: 'Nanosplash'
+  text: ''
+  tagline: The tiny loading screen for web artisans
+  actions:
+    - theme: brand
+      text: Get started
+      link: /api/start/install.md
+    - theme: alt
+      text: Playground
+      link: /api/start/playground.md
+    - theme: alt
+      text: API Documentation
+      link: /api/doc/show.md
 
 features:
-    - title: 📦 Tiny
-      details: Less than 3KB minified and gzipped.
-      link: /api/start/features#small-bundle-size
-    - title: 🍼 Simple API
-      details: Start using Nanosplash in seconds.
-      link: /api/start/features#simple-api
-    - title: 🧚 Spawning
-      details: Spawn a splash element anywhere in your DOM.
-      link: /api/start/features#spawning
-    - title: ♻️ Element recycling
-      details: Nanosplash will recycle existing elements.
-      link: /api/start/features#element-recycling
+  - title: ✨ Tiny
+    details: Less than 2KB minified and gzipped.
+    link: /api/start/features#small-bundle-size
+  - title: ✌️ 2 Function API
+    details: Start using Nanosplash in seconds.
+    link: /api/start/features#simple-api
+  - title: 🪴 Spawning
+    details: Spawn a splash element anywhere in your DOM.
+    link: /api/start/features#spawning
+  - title: 🚀 Node recycling
+    details: Nanosplash will recycle existing elements.
+    link: /api/start/features#element-recycling
 ---

package/eslint.config.js

@@ -0,0 +1,9 @@
+// @ts-check
+
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+);

package/package.json

@@ -1,41 +1,37 @@
 {
 	"name": "nanosplash",
-	"description": "The tiny loading screen for web artisans",
-	"private": false,
-	"version": "3.0.8",
-	"type": "module",
+	"version": "3.1.0",
 	"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"
+		"url": "git+https://github.com/isakhauge/nanosplash.git"
 	},
-	"license": "MIT",
 	"main": "./dist/es/ns.js",
 	"module": "./dist/es/ns.js",
-	"source": "./src/main.ts",
-	"unpkg": "./dist/iife/ns.iife.js",
+	"devDependencies": {
+		"@types/jsdom": "^21.1.6",
+		"@types/node": "^20.11.28",
+		"@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",
+		"terser": "^5.29.2",
+		"typescript": "5.4.2",
+		"typescript-eslint": "^7.2.0",
+		"vite": "^5.1.6",
+		"vitepress": "1.0.0-rc.45",
+		"vitest": "^1.4.0"
+	},
 	"exports": {
 		".": {
 			"types": {
@@ -52,35 +48,45 @@
 			}
 		}
 	},
-	"types": "./src/ts/types/global.d.ts",
+	"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": "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: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": "vitepress dev docs",
-		"docs:build": "vitepress build docs",
-		"docs:preview": "vitepress preview docs"
+		"docs:dev": "bun x vitepress dev docs",
+		"docs:build": "bun x vitepress build docs",
+		"docs:preview": "bun x vitepress preview docs"
 	},
-	"devDependencies": {
-		"@types/jsdom": "^21.1.4",
-		"@types/node": "^20.8.7",
-		"@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.4",
-		"terser": "^5.22.0",
-		"typescript": "^5.2.2",
-		"vite": "^4.5.0",
-		"vitepress": "1.0.0-rc.22",
-		"vitest": "^0.34.6"
-	}
+	"source": "./src/main.ts",
+	"type": "module",
+	"types": "./src/ts/types/global.d.ts",
+	"unpkg": "./dist/iife/ns.iife.js"
 }

package/src/style/ns.sass

@@ -1,95 +1,120 @@
+// Spinner animations:
+@keyframes nsRotate
+	100%
+		transform: rotate(360deg)
+
+@keyframes nsDash
+	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 nsFade
+	from
+		opacity: 0
+	to
+		opacity: 1
+
+@keyframes nsAscend
+	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)
-
-// Nanosplash container
-.nsc
-    @extend %flex-center-xy
-    filter: drop-shadow(0 0 0.1rem #{ rgba(LightGray, 0.5) })
+	@extend %maximize
+	@extend %bottom-left
+	@extend %flex-center-xy
+	position: absolute
+	z-index: calc(var(--zIdx) + 2)
+	animation: nsFade 2s
+	gap: var(--relSize)
 
 // 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)
+	max-width: 80dvw
+	white-space: nowrap
+	text-overflow: ellipsis
+	overflow: hidden
+	text-shadow: 0 0 0.06rem #{ rgba(DarkSlateGray, .25) }
+	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)
-    & > 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: nsAscend 0.5s
+	& > svg
+		animation: nsRotate 2s linear infinite
+		position: relative
+		width: inherit
+		height: inherit
+		stroke-width: 8
+	& .path
+		stroke: var(--color)
+		stroke-linecap: round
+		animation: nsDash 1.5s ease-in-out infinite

package/src/ts/Nanosplash.ts

@@ -0,0 +1,209 @@
+// @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'
+const b = () => document.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 =>
+	(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)
+
+/**
+ * # 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 | null =>
+	ref instanceof Element ? ref : get(ref)
+
+/**
+ * # 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: HTMLDivElement = 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
+ * @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('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 {
+		ns.insertBefore(newNst, ns.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 | null = (
+		inside ? parseRef(inside) : b
+	) as Element | null
+	let ns: NSElement
+	const recycledNs = scope(parent ?? b()).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'
+	b().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
+ * 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 => {
+	if (id === '*') getAll('.ns').forEach(deleteNS)
+	else deleteNS(typeof id === 'number' ? findNS(id) : peek())
+}
+
+/**
+ * # Add style
+ */
+const addStyle = (): void => {
+	get('#nscss')?.remove()
+	b().append(parse(`<style id=${StyleID}>${style}</style>`))
+}
+
+/**
+ * # Use NS
+ * @returns Nanosplash API.
+ */
+export const useNs = (): NanosplashInterface =>
+	!!new Promise(addStyle) &&
+	(window.ns = {
+		show,
+		hide,
+		version: 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,26 @@
+import { DOMSelector, UTCInteger } from './Types'
+
+export interface NanosplashInterface {
+	/**
+	 * # Show
+	 * Display Nanosplash inside the window.
+	 * @param {string | undefined} text Optional text
+	 * @param {string | Element | undefined} inside Optional element reference
+	 * @returns {number | null} The internal ID of the created Nanosplash.
+	 */
+	show(text?: string, inside?: DOMSelector | HTMLElement): UTCInteger | null
+	/**
+	 * # Hide
+	 * Remove Nanosplash in multiple ways depending on the passed argument.
+	 * - Pass ID: Remove specific.
+	 * - Pass '*': Remove all in window.
+	 * - Pass nothing: Remove in FIFO order.
+	 * @param id The internal ID, an asterisk, or nothing.
+	 */
+	hide(id?: UTCInteger | '*'): void
+	/**
+	 * # Version
+	 * The current version of Nanosplash.
+	 */
+	version: string
+}