nanosplash 3.0.0 → 3.0.2

package/docs/.vitepress/theme/css/style.css

@@ -0,0 +1,157 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ * 
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+:root {
+	--vp-c-default-1: var(--vp-c-gray-1);
+	--vp-c-default-2: var(--vp-c-gray-2);
+	--vp-c-default-3: var(--vp-c-gray-3);
+	--vp-c-default-soft: var(--vp-c-gray-soft);
+
+	--vp-c-brand-1: var(--vp-c-indigo-1);
+	--vp-c-brand-2: var(--vp-c-indigo-2);
+	--vp-c-brand-3: var(--vp-c-indigo-3);
+	--vp-c-brand-soft: var(--vp-c-indigo-soft);
+
+	--vp-c-tip-1: var(--vp-c-brand-1);
+	--vp-c-tip-2: var(--vp-c-brand-2);
+	--vp-c-tip-3: var(--vp-c-brand-3);
+	--vp-c-tip-soft: var(--vp-c-brand-soft);
+
+	--vp-c-warning-1: var(--vp-c-yellow-1);
+	--vp-c-warning-2: var(--vp-c-yellow-2);
+	--vp-c-warning-3: var(--vp-c-yellow-3);
+	--vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+	--vp-c-danger-1: var(--vp-c-red-1);
+	--vp-c-danger-2: var(--vp-c-red-2);
+	--vp-c-danger-3: var(--vp-c-red-3);
+	--vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+	--vp-button-brand-border: transparent;
+	--vp-button-brand-text: var(--vp-c-white);
+	--vp-button-brand-bg: var(--vp-c-brand-3);
+	--vp-button-brand-hover-border: transparent;
+	--vp-button-brand-hover-text: var(--vp-c-white);
+	--vp-button-brand-hover-bg: var(--vp-c-brand-2);
+	--vp-button-brand-active-border: transparent;
+	--vp-button-brand-active-text: var(--vp-c-white);
+	--vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+	--vp-home-hero-name-color: transparent;
+	--vp-home-hero-name-background: -webkit-linear-gradient(
+		120deg,
+		#bd34fe 30%,
+		#41d1ff
+	);
+
+	--vp-home-hero-image-background-image: linear-gradient(
+		-45deg,
+		#bd34fe 50%,
+		#47caff 50%
+	);
+	--vp-home-hero-image-filter: blur(40px);
+}
+
+@media (min-width: 640px) {
+	:root {
+		--vp-home-hero-image-filter: blur(56px);
+	}
+}
+
+@media (min-width: 960px) {
+	:root {
+		--vp-home-hero-image-filter: blur(72px);
+	}
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+	--vp-custom-block-tip-border: transparent;
+	--vp-custom-block-tip-text: var(--vp-c-text-1);
+	--vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+	--vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+	--docsearch-primary-color: var(--vp-c-brand-1) !important;
+}
+
+.vp-doc [class*='language-'] code .highlighted {
+	background-color: transparent;
+}
+
+.vp-doc [class*='language-'] .has-highlighted-lines .line {
+	transition: filter 0.35s, opacity 0.35s;
+}
+.vp-doc [class*='language-'] .has-highlighted-lines .line:not(.highlighted) {
+	filter: blur(1px);
+	opacity: 0.5;
+}
+.vp-doc
+	[class*='language-']
+	.has-highlighted-lines:hover
+	.line:not(.highlighted) {
+	filter: blur(0);
+	opacity: 1;
+}

package/docs/.vitepress/theme/index.ts

@@ -0,0 +1,16 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import Theme from 'vitepress/theme'
+import './css/style.css'
+
+export default {
+	extends: Theme,
+	Layout: () => {
+		return h(Theme.Layout, null, {
+			// https://vitepress.dev/guide/extending-default-theme#layout-slots
+		})
+	},
+	enhanceApp({ app, router, siteData }) {
+		// ...
+	},
+}

package/docs/.vitepress/theme/vue/Card.vue

@@ -0,0 +1,31 @@
+<script setup>
+import { useAttrs } from 'vue'
+const attrs = useAttrs()
+</script>
+
+<template>
+	<div class="card">
+		<div v-if="attrs.id" class="id">#{{ attrs.id }}</div>
+		<slot></slot>
+	</div>
+</template>
+
+<style lang="sass" scoped>
+.card
+    color: White
+    line-height: 1
+    position: relative
+    padding: 30px
+    border-radius: 5px
+    background-color: rgba(White, 0.2)
+    backdrop-filter: blur(5px)
+    -webkit-backdrop-filter: blur(5px)
+    border: 1px solid rgba(White, 0.2)
+    .id
+        position: absolute
+        top: 5px
+        left: 5px
+        font-size: 10px
+        color: rgba(White, 0.7)
+        letter-spacing: 0.1em
+</style>

package/docs/.vitepress/theme/vue/CardGrid.vue

@@ -0,0 +1,17 @@
+<template>
+	<div class="card-grid">
+		<slot></slot>
+	</div>
+</template>
+
+<style lang="sass" scoped>
+.card-grid
+	display: grid
+	grid-template-columns: repeat(auto-fill, minmax(300px, 1fr))
+	grid-gap: 25px
+	background-image: url(https://9to5mac.com/wp-content/uploads/sites/6/2022/06/macOS-Ventura-wallpaper-1-1.jpg?quality=82&strip=all)
+	background-size: cover
+	background-position-y: bottom
+	padding: 25px
+	border-radius: 5px
+</style>

package/docs/.vitepress/theme/vue/Exe.vue

@@ -0,0 +1,86 @@
+<script setup>
+import { ref, defineProps } from 'vue'
+import { Service } from '../../../../dist/es/ns'
+Service.start()
+
+const props = defineProps({
+	commands: Array,
+})
+
+const rCommandString = ref('')
+
+const wait = ms => new Promise(r => setTimeout(r, ms))
+
+function onClickExe() {
+	const str = rCommandString.value
+	let executable = null
+	if (str.startsWith('ns.show(')) {
+		const text = /ns\.show\(['"](.+)['"]\)/.exec(str)[1]
+		executable = async () => {
+			const id = eval(str)
+			let ms = 4000
+			while (ms > 0) {
+				await wait(1000)
+				ms -= 1000
+				ns.show(`${text} (${ms / 1000})`)
+			}
+			ns.hideId(id)
+		}
+	} else {
+		executable = new Function(rCommandString.value)
+	}
+	executable()
+}
+</script>
+
+<template>
+	<div class="container">
+		<select class="select" v-model="rCommandString">
+			<option value="" selected disabled>Click and select</option>
+			<option
+				v-for="(command, i) in props.commands"
+				:key="i"
+				:value="command"
+			>
+				{{ command }}
+			</option>
+		</select>
+		<div class="exe" @click="onClickExe">Run</div>
+	</div>
+</template>
+
+<style lang="sass" scoped>
+@use "sass:color"
+
+$border-radius: 5px
+.container
+	position: relative
+	display: flex
+	border-radius: $border-radius
+	z-index: 1
+	& > *
+		padding: 10px 20px
+
+.select
+	position: relative
+	display: flex
+	flex-grow: 1
+	font-family: monospace
+	font-size: 14px
+	background-color: var(--vp-c-bg-alt)
+	border-radius: $border-radius 0 0 $border-radius
+	border: 1px solid rgba(Black, 0.1)
+	cursor: pointer
+
+$btn-bg: RoyalBlue
+.exe
+	position: relative
+	display: inline-flex
+	color: White
+	background-color: $btn-bg
+	cursor: pointer
+	border-radius: 0 $border-radius $border-radius 0
+	border: 1px solid rgba(Black, 0.1)
+	&:hover
+		background-color: darken($btn-bg, 10%)
+</style>

package/docs/.vitepress/theme/vue/PlayGround.vue

@@ -0,0 +1,50 @@
+<script setup>
+import CardGrid from './CardGrid.vue'
+import Card from './Card.vue'
+import Exe from './Exe.vue'
+
+const commands = [
+	'ns.showInside("#a", "Loading A")',
+	'ns.showInside("#b", "Loading B")',
+	'ns.showInside("#c", "Loading C")',
+	'ns.showInside("#d", "Loading D")',
+	'ns.showInside("#wrapper", "Loading Wrapper")',
+	'ns.show("Loading window")',
+	'ns.hide()',
+	'ns.hideInside("#b")',
+	'ns.hideAll()',
+]
+</script>
+
+<template>
+	<div class="playground">
+		<CardGrid id="wrapper">
+			<Card id="a">
+				Lorem ipsum dolor sit amet consectetur adipiscing elit ut
+				aliquam
+			</Card>
+			<Card id="b">
+				Lorem ipsum dolor sit amet consectetur adipiscing elit ut
+				aliquam
+			</Card>
+			<Card id="c">
+				Lorem ipsum dolor sit amet consectetur adipiscing elit ut
+				aliquam
+			</Card>
+			<Card id="d">
+				Lorem ipsum dolor sit amet consectetur adipiscing elit ut
+				aliquam
+			</Card>
+		</CardGrid>
+		<Exe :commands="commands"></Exe>
+	</div>
+</template>
+
+<style lang="sass" scoped>
+.playground
+	display: flex
+	flex-direction: column
+	row-gap: 20px
+	& > *
+		box-shadow: 0 2px 10px rgba(Black, 0.1)
+</style>

package/docs/api/doc/hide.md

@@ -0,0 +1,69 @@
+# Hide Nanosplash
+
+## Hide
+
+Hides the oldest loading screen (FIFO) and returns the GUID of the loading screen that was removed, or `null` if no loading screen was found.
+
+```ts
+ns.hide(): GUIDString | null
+```
+
+```js
+ns.show('a')
+ns.show('b')
+ns.show('c')
+ns.hide() // Hides 'a'
+ns.hide() // Hides 'b'
+ns.hide() // Hides 'c'
+```
+
+::: tip
+If you have multiple loading screens open at the same time, I would recommend that you hide specific elements based on their GUID or host element. See [`hideId`](#hide-by-id) and [`hideInside`](#hide-inside) for more information.
+:::
+
+## Hide by ID
+
+Hides the Nanosplash loading screen with the given GUID. If a loading screen matching the GUID is found, it will be removed and the same GUID will be returned. If no loading screen is found, `null` will be returned.
+
+```ts
+ns.hideId(guid: GUIDString): GUIDString | null
+```
+
+The show methods always retrun a GUID. This identifier can be used to hide specific loading screens.
+
+```js
+const id = ns.show('Loading')
+ns.hideId(id)
+```
+
+## Hide inside
+
+Hides the Nanosplash loading screen inside another element — if any — that corresponds with the given element reference. Returns the GUID string of the loading screen that was hidden, or `null` if no loading screen was found inside.
+
+```ts
+ns.hideInside(ref: Reference): GUIDString | null
+```
+
+This method works almost the same way as `hideId`, but instead of using the GUID string as the identifier, it uses the host element as the identifier.
+
+```js
+const selector = '#my-table'
+ns.showInside(selector, 'Loading')
+ns.hideInside(selector)
+```
+
+You can also use the `Element` type as the reference.
+
+```js
+const element = document.getElementById('my-table')
+ns.showInside(element, 'Loading')
+ns.hideInside(element)
+```
+
+## Hide all
+
+Hides all Nanosplash loading screens.
+
+```ts
+ns.hideAll(): void
+```

package/docs/api/doc/show.md

@@ -0,0 +1,47 @@
+# Show Nanosplash
+
+## Show
+
+This method displays a fullscreen loading screen and returns a GUID string.
+
+```ts
+ns.show(text?: string): GUIDString
+```
+
+If you enter no text, it will display the spinning wheel only.
+
+```js
+ns.show()
+```
+
+If you enter text, it will display the spinning wheel adjacent to the text.
+
+```js
+ns.show('Loading')
+```
+
+## Show inside
+
+This method displays a loading screen inside an element and returns a GUID
+string. The `Reference` type is a union type of `string | Element`. A reference
+can be both a CSS selector `string` or an `Element`.
+
+```ts
+ns.showInside(ref: Reference, text?: string): GUIDString | null
+```
+
+```js
+// CSS selector
+const selector = '#my-table'
+ns.showInside(selector, 'Loading')
+
+// Element
+const element = document.getElementById('my-table')
+ns.showInside(element, 'Loading')
+```
+
+::: tip
+A host element can only contain one Nanosplash element at a time. If
+you try to show a splash inside an element that already contains a splash,
+the existing splash will be overwritten.
+:::

package/docs/api/start/features.md

@@ -0,0 +1,17 @@
+# Features
+
+## Small bundle size
+
+The Nanosplash bundle is merely 3KB 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
+
+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.
+
+## Spawning
+
+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
+
+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

@@ -0,0 +1,53 @@
+<script setup>
+import Card from '../../.vitepress/theme/vue/Card.vue'
+</script>
+
+# Installation
+
+Nanosplash can be installed either via CDN or NPM. Installing via CDN is easier and requires less configuration, but installing via NPM is more flexible and allows you to controll the imports and initialization of the Nanosplash service running in your application.
+
+## CSS
+
+Since version 3.0.2, CSS is included inside the JS bundle. 🎉
+
+## Install via CDN
+
+Add the following script tag to the `<head>` of your HTML document:
+
+```html
+<script src="https://unpkg.com/nanosplash@3.0.2/dist/iife/ns.iife.js"></script>
+```
+
+```html{5}
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<title>My awesome application 🚀</title>
+		<script src="https://unpkg.com/nanosplash@3.0.2/dist/iife/ns.iife.js"></script>
+	</head>
+	...
+</html>
+```
+
+Now you can easily start using Nanosplash by simply calling `ns.show`.
+
+```ts
+ns.show('It works!')
+```
+
+## Install via NPM
+
+Install Nanosplash via NPM by running the following command:
+
+```bash
+yarn add nanosplash
+```
+
+To import and start the Nanosplash service in your application, you need to import the Service class and start it.
+
+```js{2}
+import { Service } from 'nanosplash'
+Service.start()
+```
+
+The service will inject an instance of itself inside the global `window` object. You can now start using Nanosplash by simply calling `ns.show`.

package/docs/api/start/playground.md

@@ -0,0 +1,11 @@
+<script setup>
+import PlayGround from '../../.vitepress/theme/vue/PlayGround.vue'
+</script>
+
+# Playground
+
+Here you can play around with Nanosplash and see how it works.
+
+<PlayGround></PlayGround>
+
+Select a method from the dropdown menu above and click "Run" to see it in action.

package/docs/api/start/usage.md

@@ -0,0 +1,25 @@
+# Usage
+
+```js{2,5,8,11,14,18,21}
+// Fullscreen spinning wheel
+ns.show()
+
+// Fullscreen spinning wheel with text
+ns.show('Loading')
+
+// Display inside an element
+ns.showInside('#my-table', 'Fetching data')
+
+// 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)
+
+// Hide all loading screens
+ns.hideAll()
+```

package/docs/index.md

@@ -0,0 +1,30 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+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: API Documentation
+          link: /api/doc/show.md
+
+features:
+    - title: 📦 Tiny
+      details: Only 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
+---