nanosplash 4.0.2 → 4.0.4

package/package.json

@@ -1,90 +1,76 @@
 {
-	"name": "nanosplash",
-	"version": "4.0.2",
-	"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.30",
-		"@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.3",
-		"typescript-eslint": "^7.3.1",
-		"vite": "^5.2.6",
-		"vitepress": "1.0.1",
-		"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,
-	"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"
-	},
-	"source": "./src/main.ts",
-	"type": "module",
-	"types": "./src/ts/types/global.d.ts",
-	"unpkg": "./dist/iife/ns.iife.js"
+  "name": "nanosplash",
+  "private": false,
+  "version": "4.0.4",
+  "type": "module",
+  "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"
+  },
+  "description": "The tiny loading screen for web artisans",
+  "homepage": "https://github.com/isakhauge/nanosplash",
+  "keywords": [
+    "loading",
+    "loader",
+    "screen",
+    "splash",
+    "nano",
+    "nanosplash",
+    "small",
+    "tiny",
+    "es",
+    "esm",
+    "ts",
+    "typescript",
+    "iife",
+    "cdn",
+    "vite"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "bun run build:es && bun run build:cjs && bun run build:iife",
+    "build:es": "tsc && cross-env entry=./src/composables/ns.ts format=es vite build -m production --outDir dist/es",
+    "build:cjs": "tsc && cross-env entry=./src/composables/ns.ts format=cjs vite build -m production --outDir dist/cjs",
+    "build:iife": "tsc && cross-env entry=./src/iife.ts format=iife vite build -m production --outDir dist/iife",
+    "preview": "vite preview",
+    "lint": "eslint . --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"vite.config.ts\"",
+    "test": "bun run vitest"
+  },
+  "types": "./src/types/global.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/types/global.d.ts",
+      "import": "./dist/es/ns.es.js",
+      "require": "./dist/cjs/ns.cjs.js",
+      "default": "./dist/es/ns.es.js"
+    }
+  },
+  "source": "./src/composables/ns.ts",
+  "unpkg": "./dist/iife/ns.iife.js",
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "@types/node": "^22.15.29",
+    "@typescript-eslint/eslint-plugin": "^8.33.0",
+    "@typescript-eslint/parser": "^8.33.0",
+    "@vitest/coverage-v8": "3.1.4",
+    "cross-env": "^7.0.3",
+    "dotenv": "^16.5.0",
+    "eslint": "^9.28.0",
+    "eslint-config-prettier": "^10.1.5",
+    "globals": "^16.2.0",
+    "jsdom": "^26.1.0",
+    "prettier": "3.5.3",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.33.0",
+    "vite": "^6.3.5"
+  },
+  "dependencies": {
+    "vitest": "^3.1.4"
+  }
 }

package/src/composables/ns.ts

@@ -0,0 +1,154 @@
+import style from '@/style/ns.css?raw'
+import type { INanosplash } from '@/interfaces/INanosplash.ts'
+import type { Func } from '@/types/generic/function.ts'
+import type { INSElement } from '@/interfaces/INSElement.ts'
+import {
+  all,
+  bod,
+  div,
+  doc,
+  first,
+  parseHtml,
+  parseRef,
+  toArray,
+} from '@/utils/dom-utils.ts'
+import { ClassNames, Selectors } from '@/constants/ns.ts'
+import type { HTMLString } from '@/types/semantic/string.ts'
+import type { ElementRef } from '@/types/dom.ts'
+import type { int } from '@/types/semantic/number.ts'
+import { version } from '@/../package.json'
+
+export const useNs: Func<INanosplash> = (): INanosplash => {
+  /**
+   * Retrieve all NS elements from the DOM
+   */
+  const getAllNs: Func<INSElement[]> = () =>
+    all(doc(), Selectors.ns) as INSElement[]
+
+  /**
+   * Create an NS element
+   */
+  const makeNs: Func<INSElement> = () => {
+    const circle: HTMLString =
+      '<circle class=path cx=25 cy=25 r=20 fill=none />'
+    const svg = parseHtml(`<svg viewBox="0 0 50 50">${circle}</svg>`) as Element
+    const node = div(
+      ClassNames.ns,
+      div(ClassNames.nsText),
+      div(ClassNames.nsSpinner, svg)
+    ) as INSElement
+    node.nsId = Date.now()
+    return node
+  }
+
+  /**
+   * Get all NS elements from DOM in a FIFO sequence
+   */
+  const nsQueue: Func<INSElement[]> = () =>
+    getAllNs().sort((a, b) => a.nsId - b.nsId)
+
+  /**
+   * Peek at the first NS element in the queue
+   */
+  const peekNsQueue: Func<INSElement | null> = () => nsQueue()[0] ?? null
+
+  /**
+   * Set the text of the NS element.
+   * @param ns Nanosplash element.
+   * @param text The text to display adjacent to the spinner.
+   */
+  const setNsText = (ns: INSElement, text?: string): void => {
+    first(ns, Selectors.nsText)?.remove()
+    if (!text) return
+    const newNsText: Element = div(ClassNames.nsText, text)
+    ns.insertBefore(newNsText, ns.firstChild)
+  }
+
+  /**
+   * Set the parent element of the NS element.
+   * @param ns Nanosplash element.
+   * @param parent An element to be a parent of the Nanosplash element.
+   */
+  const setNsParent = (ns: INSElement, parent: Element): void => {
+    const child = parent.firstElementChild
+    if (child) parent.insertBefore(ns, child)
+    parent.append(ns)
+    parent.classList.add(ClassNames.nsHost)
+  }
+
+  const getNsInside = (parent: Element): INSElement | undefined => {
+    const children = toArray(parent.children) as INSElement[]
+    return children.find((v: Element): boolean =>
+      v.classList.contains(ClassNames.ns)
+    )
+  }
+
+  /**
+   * Show the Nanosplash in the window
+   * @param text The text that will appear adjacent to the spinner. Enter false to only show the spinner.
+   * @param inside Element or selector to an element wherein the Nanosplash element should reside.
+   */
+  const show = (text?: string, inside?: ElementRef): int | null => {
+    const parent: Element = inside ? (parseRef(inside) ?? bod()) : bod()
+    let ns: INSElement
+    const recycled = getNsInside(parent)
+    if (recycled) {
+      ns = recycled as INSElement
+    } else {
+      ns = makeNs()
+      setNsParent(ns, parent)
+    }
+    setNsText(ns, text ?? '')
+    if (parent === bod()) {
+      const top: string = scrollY + 'px'
+      bod().style.setProperty('--ns-top', top)
+    }
+    return ns.nsId
+  }
+
+  /**
+   * Remove a Nanosplash element from the DOM
+   * @param ns The Nanosplash element
+   */
+  const removeNs = (ns?: Element | INSElement | null): void => {
+    ns?.parentElement?.classList.remove(ClassNames.nsHost)
+    ns?.remove()
+  }
+
+  /**
+   * Find a Nanosplash element with a given ID
+   * @param id The Nanosplash ID
+   */
+  const findNs = (id: int): INSElement | null =>
+    getAllNs().find(x => x.nsId === id) ?? null
+
+  /**
+   * Hide agnostically in FIFO order, specifically by ID, or all, by the asterisk symbol.
+   * The latter will delete all Nanosplash elements in the DOM.
+   * @param id Optional ID of a Nanosplash element or '*'.
+   */
+  const hide = (id?: int | '*'): void => {
+    const selectAll = id === '*'
+    if (selectAll) getAllNs().forEach(removeNs)
+    else removeNs(typeof id === 'number' ? findNs(id) : peekNsQueue())
+  }
+
+  /**
+   * Remove old Nanosplash styles and insert new ones.
+   */
+  const injectStyle = () => {
+    first(doc(), '#ns')?.remove()
+    const styleElement: HTMLStyleElement = parseHtml(
+      `<style id="ns">${style}</style>`
+    )
+    bod().append(styleElement)
+  }
+
+  injectStyle() // Run everytime the hook is invoked.
+
+  return {
+    show,
+    hide,
+    version,
+  }
+}

package/src/constants/ns.ts

@@ -0,0 +1,13 @@
+export const ClassNames = {
+  ns: 'ns',
+  nsHost: 'nsh',
+  nsText: 'nst',
+  nsSpinner: 'nss',
+}
+
+export const Selectors = {
+  ns: '.' + ClassNames.ns,
+  nsHost: '.' + ClassNames.nsHost,
+  nsText: '.' + ClassNames.nsText,
+  nsSpinner: '.' + ClassNames.nsSpinner,
+}

package/src/iife.ts

@@ -0,0 +1,5 @@
+import { useNs } from '@/composables/ns.ts'
+
+window.addEventListener('load', function () {
+  this.ns = useNs()
+})

package/src/interfaces/INSElement.ts

@@ -0,0 +1,5 @@
+import type { int } from '@/types/semantic/number.ts'
+
+export interface INSElement extends HTMLDivElement {
+  nsId: int
+}

package/src/interfaces/INanosplash.ts

@@ -0,0 +1,73 @@
+import type { ElementRef } from '@/types/dom.ts'
+import type { int } from '@/types/semantic/number.ts'
+
+/**
+ * # Nanosplash
+ * @author Isak Hauge <isakhauge@icloud.com>
+ */
+export interface INanosplash {
+  /**
+   * # Show
+   * Display Nanosplash inside the window.
+   * @param {string | null | undefined} text Optional text. Pass falsy to display spinner only.
+   * @param {string | Element | undefined} inside Optional element reference
+   * @returns {number | null} The internal ID of the created Nanosplash.
+   * @example
+   * // Show spinner only
+   * ns.show()
+   * @example
+   * // Show spinner and text
+   * ns.show('Loading ...')
+   * @example
+   * // Show spinner and text inside element
+   * const div = document.createElement('div')
+   * div.id = 'my-div'
+   * document.body.append(div)
+   *
+   * // Alternative 1: Using node
+   * ns.show('Loading ...', div)
+   *
+   * // Alternative 2: Using selector
+   * ns.show('Loading ...', '#my-div')
+   * @example
+   * // Show spinner only, inside element
+   * const div = document.createElement('div')
+   * div.id = 'my-div'
+   * document.body.append(div)
+   *
+   * // Alternative 1: Using node
+   * ns.show(null, div)
+   *
+   * // Alternative 2: Using selector
+   * ns.show(null, '#my-div')
+   */
+  show(
+    text?: string | null | undefined,
+    inside?: ElementRef | HTMLElement
+  ): int | 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.
+   * @example
+   * // Remove the first Nanosplash in the queue (FIFO)
+   * ns.hide()
+   * @example
+   * // Remove specific Nanosplash in case you have multiple
+   * const idA: number = ns.show(null, '#div-a') // 1700000000000
+   * const idB: number = ns.show(null, '#div-b') // 1800000000000
+   * ns.hide(idB) // Only hides Nanosplash inside the element with ID div-b
+   * @example
+   * // Hide all Nanosplash elements in the DOM
+   * ns.hide('*')
+   */
+  hide(id?: int | '*'): void
+  /**
+   * # Version
+   * The current version of Nanosplash.
+   */
+  version: string
+}

package/src/style/ns.css

@@ -0,0 +1,134 @@
+@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: 0;
+}
+
+/* Nanosplash host */
+.nsh {
+  --color: DarkSlateGray;
+  --size: 20px;
+  --relSize: calc(var(--size) * 0.9);
+  --font: 'Inter', 'Helvetica', 'Arial';
+  --weight: 400;
+  --bg: rgba(255, 255, 255, 0.9);
+  --zIdx: 9999999999;
+  --blur: blur(5px);
+
+  position: relative;
+  z-index: var(--zIdx);
+  &::before {
+    width: 100%;
+    height: 100%;
+    bottom: 0; /* Not sure why */
+    right: 0; /* Not sure why */
+    position: absolute;
+    content: '';
+    background-color: var(--bg);
+    backdrop-filter: var(--blur);
+    -webkit-backdrop-filter: var(--blur);
+    z-index: calc(var(--zIdx) + 1);
+    border-radius: var(--size);
+  }
+}
+
+/* For when the Nanosplash host is the document body */
+body.nsh {
+  &,
+  &::before {
+    width: 100%;
+    height: 100%;
+    position: fixed;
+    top: var(--ns-top);
+    left: 0;
+  }
+}
+
+/* Nanosplash main element */
+.ns {
+  width: 100%;
+  height: 100%;
+  bottom: 0; /* Not sure why */
+  right: 0; /* Not sure why */
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  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), sans-serif;
+  font-weight: var(--weight);
+  max-width: 80dvw;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  overflow: hidden;
+  text-shadow: 0 0 0.06rem rgba(0, 0, 0, 0.25);
+  filter: drop-shadow(0 0 0.07rem rgba(0, 0, 0, 0.25));
+  animation: nsAscend 0.5s;
+}
+
+/* Nanosplash spinner */
+.nss {
+  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/types/dom.d.ts

@@ -0,0 +1,3 @@
+import type { NodeSelector } from './semantic/string.ts'
+
+export type ElementRef = Element | NodeSelector

package/src/types/generic/function.d.ts

@@ -0,0 +1 @@
+export type Func<T> = (...args: unknown[]) => T

package/src/types/global.d.ts

@@ -0,0 +1,26 @@
+import type { INanosplash } from '../interfaces/INanosplash.ts'
+
+declare global {
+  interface Window {
+    ns: INanosplash
+  }
+}
+
+/**
+ * # Nanosplash
+ *
+ * **The tiny loading screen for web artisans**
+ *
+ * `useNs` is the main hook, which will inject the style into the DOM and return
+ * an instance of the Nanosplash API.
+ * We recommend that you add Nanosplash to the Window.
+ * @returns Instance of Nanosplash API
+ * @example The short and easy way.
+ * window.ns = useNs()
+ * @example The safe way.
+ * window.addEventListener('load', function() {
+ *     this.ns = useNs()
+ * })
+ * @author Isak Hauge <https://www.linkedin.com/in/isakhauge/>
+ */
+export const useNs: () => INanosplash

package/src/types/semantic/number.d.ts

@@ -0,0 +1 @@
+export type int = number

package/src/types/semantic/string.d.ts

@@ -0,0 +1,2 @@
+export type NodeSelector = string
+export type HTMLString = string

package/src/utils/dom-utils.ts

@@ -0,0 +1,68 @@
+import type { Func } from '@/types/generic/function.ts'
+import type { HTMLString, NodeSelector } from '@/types/semantic/string.ts'
+import type { ElementRef } from '@/types/dom.ts'
+
+/**
+ * Shortened Document getter
+ */
+export const doc: Func<Document> = (): Document => globalThis.document
+
+/**
+ * Shortened Body getter
+ */
+export const bod: Func<HTMLElement> = (): HTMLElement =>
+  globalThis.document.body
+
+/**
+ * Convert iterables and array-like structures into an array
+ * @param x
+ */
+export const toArray = <T>(x: Iterable<T> | ArrayLike<T>) => Array.from(x)
+
+/**
+ * Scoped node selector
+ * @param node Current scope
+ * @param ref Selector
+ */
+export const all = (node: ParentNode, ref: NodeSelector) =>
+  toArray(node.querySelectorAll(ref))
+
+/**
+ * Scoped node selector returning the first match
+ * @param node Current scope
+ * @param ref Selector
+ */
+export const first = (node: ParentNode, ref: NodeSelector): Element | null =>
+  all(node, ref)[0] ?? null
+
+/**
+ * Parse an ambiguous element reference into an actual element
+ * @param ref Element reference
+ */
+export const parseRef = <T extends Element>(ref: ElementRef): T | null =>
+  ref instanceof Element ? (ref as T) : (first(doc(), ref) as T)
+
+/**
+ * Create div
+ * @param className Optional CSS class name
+ * @param children Optional children
+ */
+export const div = (
+  className?: string,
+  ...children: (Node | HTMLString)[]
+): HTMLDivElement => {
+  const node: HTMLDivElement = doc().createElement('div')
+  if (className) node.classList.add(className)
+  node.append(...children)
+  return node
+}
+
+/**
+ * Parse HTML code into HTML elements
+ * @param html
+ */
+export const parseHtml = <T extends HTMLElement>(html: HTMLString): T => {
+  const node: HTMLDivElement = div()
+  node.innerHTML = html
+  return node.firstChild as T
+}