@duckafire/lazy-loading-js 2.0.2-1

package/LICENSE

@@ -0,0 +1,19 @@
+Zlib License
+
+Copyright (C) 2025 DuckAfire <duckafire.github.io/nest>
+  
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+  
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required. 
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.

package/README.md

@@ -0,0 +1,157 @@
+<a href="https://github.com/sponsors/duckafire" title="GitHub Sponsors"><img align="right" src="https://img.shields.io/badge/Buy%20me%20a%20coffee-E5DB2F?&logo=buy-me-a-coffee&style=flat-square&logoColor=000"></a>
+
+## Lazy loading
+
+Small and simple JS API, developed to easily the application of the Lazy Loading
+tecnique to images, in order to optimize website pages.
+
+### Index
+
+* [Usage](#usage)
+	* [Import the API](#import-the-api)
+	* [Set the properties](#set-the-properties)
+	* [Choose a class](#choose-a-class)
+	* [Start the API](#start-the-api)
+* [API Methods](#api-methods)
+	* [Constructor](#constructor)
+	* [`start`](#start)
+	* [`disconnectFromObserver`](#disconnectfromobserver)
+* [Incompatibility browsers](#incompatibility-browsers)
+
+### Usage
+
+#### Import the API
+
+Import the API in your HTML code:
+
+``` html
+<script src="https://cdn.jsdelivr.net/npm/@duckafire/lazy-loading-js@2.0.2-1/lib/LazyLoadingImage.min.js"></script>
+```
+
+[source]: https://github.com/duckafire/lazy-loading-js/tree/main/src/ "Lazy loading API source code"
+
+> Or download the file(s), from [here][source].
+
+#### Set the properties
+
+Choose which `img` will use the API, then set the properties below:
+
+* `data-src`: contains the original image - high quality. It will be used when
+the `img` is visible.
+
+* `data-placeholder`: contains an low quality image that will be used when image
+is not visible. Used for avoid the breaking of the page layout.
+
+``` html
+<img data-src="./foo.png" data-placeholder="./foo-placeholder.png"/>
+```
+
+#### Choose a class
+
+Attribute a specific class to all elements whose visibility will be controlled
+by the API.
+
+``` html
+<img class="foo" data-src="./foo.png" data-placeholder="./foo-placeholder.png"/>
+```
+
+#### Start the API
+
+Instance a object using the class (choosed in the last step) as first argument and enjoy!
+
+
+``` html
+<img class="foo" data-src="./foo.png" data-placeholder="./foo-placeholder.png"/>
+
+<script>
+	new LazyLoadingImage(".foo");
+
+	// OR:
+	// const api_unit = new LazyLoadingImage(".foo");
+</script>
+```
+
+### API methods
+
+#### Constructor
+
+Instance the object and it validate the HTML elements that were obtained by
+the query specificed.
+
+| Parameters   | Type    | Default   | Description                                   |
+| :--          | :--     | :--       | :--                                           |
+| query        | string  | undefined | CSS query to get specific HTML elements.      |
+| startWarning | boolean | false     | it allows console warning and error messages. |
+| awaitToStart | boolean | false     | set that the API will be started manually.    |
+
+> [!IMPORTANT]
+> Parameters that have `undefined` as default value they are mandatory.
+
+##### Exceptions
+
+* None element was found with the specified query.
+* Element type (`img`, `div`, ...) invalid - only `img` is allow.
+
+##### Console
+
+###### Warnings
+
+* All [`start`](#start) warnings.
+
+###### Errors
+
+* All [`start`](#start) errors.
+
+#### `start`
+
+Used to start the API manually.
+
+| Parameters | Type    | Default   | Description                                     |
+| :--        | :--     | :--       | :--                                             |
+| warning    | boolean | false     | it allows console warning and error messages. |
+
+##### Exceptions
+
+* *None.*
+
+##### Console
+
+###### Warnings
+
+* The API already was started.
+
+###### Errors
+
+* The browser do not have support to *Intersection Observer API* (API from JS
+standard, use as base to this project).
+
+#### `disconnectFromObserver`
+
+Used to end API work.
+
+> [!NOTE]
+> This method is declared inside `#connectToObserver` (*private* method).
+
+| Parameters | Type    | Default   | Description |
+| :--        | :--     | :--       | :--         |
+| *None*     | | | |
+
+##### Exceptions
+
+* *None.*
+
+##### Console
+
+###### Warnings
+
+* *None.*
+
+###### Errors
+
+* *None.*
+
+### Incompatibility browsers
+
+This API is based in other API, from JS Standard, named *Intersection Observer
+API*. If the user's browser do not have support to this Standard API, the
+`data-src` image will load without lazy loading.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@duckafire/lazy-loading-js",
+  "author": "duckafire",
+  "version": "2.0.2-1",
+  "license": "Zlib",
+  "description": "Simple lazy loading algorithm for websites front-end.",
+  "keywords": ["client", "html", "images", "web", "front-end", "optimization", "lazy", "loading", "lazy-loading"],
+  "devDependencies": {
+    "terser": "^5.43.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/duckafire/lazy-loading-js.git"
+  },
+  "scripts": {
+    "compress": "for file in ./src/*; do npx terser \"$file\" -o \"./lib/$(basename -- \"${file%.js}\").min.js\" --compress --mangle; done"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "src"
+  ],
+  "custom-fields": {
+    "cloud-repostories": [
+      "https://github.com/duckafire/lazy-loading-js.git",
+      "https://gitlab.com/duckafire/lazy-loading-js.git",
+      "https://npmjs.com/package/@duckafire/lazy-loading-js.git"
+    ]
+  }
+}

package/src/LazyLoadingImage.js

@@ -0,0 +1,177 @@
+/*
+Zlib License
+
+Copyright (C) 2025 DuckAfire <duckafire.github.io/nest>
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.
+*/
+
+class LazyLoadingImage {
+	#items; #hasSupport;
+
+	#started = false;
+
+	#ELEMENT_INSTANCE = HTMLImageElement;
+
+	#HIDED    = "-1";
+	#AWAITING =  "0";
+	#SHOWED   =  "1";
+
+	constructor(query, startWarning, awaitToStart) {
+		this.#items = document.querySelectorAll(query);
+
+		if(this.#items.length == 0)
+			throw new Error(`None was found. Query: "${query}"`);
+
+		this.#items.forEach(item => {
+			if(!(item instanceof this.#ELEMENT_INSTANCE))
+				throw new Error(`Invalid instance. Expected "${this.constructor.name}" instead "${item.constructor.name}".` );
+
+			if(item instanceof HTMLImageElement)
+				item.loading = "lazy";
+		});
+
+		if(!awaitToStart)
+			this.start(startWarning);
+	}
+
+	start(warning) {
+		if(this.#started){
+			if(warning){
+				console.warn(
+					(this.hasSupport)
+					? "This instance already was started."
+					: "This browser do not support the Intersection Observer API."
+				);
+			}
+
+			return;
+		}
+
+		this.#started = true;
+		this.#hasSupport = ("IntersectionObserver" in window)
+
+		if(this.#hasSupport){
+			this.#items.forEach(item => {
+				this.#awaitToWorking(item);
+				this.#connectToObserver(item);
+			});
+			return;
+		}
+
+		this.#showAllWithoutObserver();
+
+		if(warning){
+			console.error(
+				"This browser do not suppor the Intersection Observer API - from JavaScript. " +
+				"So the resources that depend of it it will be loaded without optimizations of loading."
+			);
+		}
+	}
+
+	#showAllWithoutObserver(){
+		this.#items.forEach(item => {
+			this.#showSource(item);
+		});
+	}
+
+	#checkItemPosition(pos0, pos1, isWidth){
+		const max = window["inner" + (isWidth ? "Width" : "Height")];
+
+		return (pos0 >= 0 && pos0 <= max) || (pos1 >= 0 && pos1 <= max);
+	}
+
+	#awaitToWorking(item){
+		this.#setItemProperties(item);
+
+		item.onload = () => {
+			let loader = new Image();
+			loader.src = item.dataset.src;
+
+			loader.onload = () => {
+				loader = null; // "throw" in the collect garbage
+				item.dataset.awaiting = "no";
+
+				// hitbox
+				const hb = item.getBoundingClientRect();
+
+				// if the screen was maintened stopped, after page (re)load,
+				// the Intersection... will not update
+				if(this.#checkItemPosition(hb.top, hb.bottom) || this.#checkItemPosition(hb.left, hb.right, true))
+					this.#showSource(item, this.#SHOWED);
+			}
+		}
+	}
+
+	#setItemProperties(item){
+		item.src = item.dataset.placeholder;
+		item.dataset.currentSrc = item.dataset.placeholder;
+		item.dataset.state    = this.#AWAITING;
+		item.dataset.awaiting = "yes";
+	}
+
+	#connectToObserver(item){
+		const api = new IntersectionObserver(entities => {
+			entities.forEach(entity => {
+				if(entity.target.dataset.awaiting == "yes")
+					return;
+
+				if(entity.isIntersecting)
+					this.#showSource(entity.target, this.#SHOWED);
+
+				else
+					this.#hideSource(entity.target, this.#HIDED);
+			});
+		});
+
+		api.observe(item);
+
+		if(this.disconnectFromObserver == undefined){
+			this.disconnectFromObserver = () => {
+				this.#started = false;
+
+				this.#items.forEach(item => {
+					api.unobserve(item);
+					entity.target.dataset.state = this.#AWAITING;
+				});
+			}
+		}
+	}
+
+	#updateSource(item, state, dataProperty){
+		if(item.dataset[dataProperty] != undefined){
+			// avoid unnecessary reload
+			if((item.dataset.state != state || item.dataset.state == this.#AWAITING) && item.dataset.currentSrc != item.dataset[dataProperty]){
+				item.dataset.state = state;
+				item.src = item.dataset[dataProperty];
+				item.dataset.currentSrc = item.dataset[dataProperty];
+			}
+
+			return;
+		}
+
+		throw new Error(`Data property "data-${dataProperty}" not found.`);
+	}
+
+	#showSource(item, state){
+		this.#updateSource(item, state, "src");
+	}
+
+	#hideSource(item, state){
+		this.#updateSource(item, state, "placeholder");
+	}
+}