@lonik/oh-image 1.2.7 → 1.3.0

package/dist/plugin.js

@@ -1,11 +1,36 @@
 import { basename, dirname, extname, join, parse } from "node:path";
+import queryString from "query-string";
 import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import queryString from "query-string";
-import sharp from "sharp";
 import pLimit from "p-limit";
+import sharp from "sharp";
 
 //#region src/plugin/utils.ts
+function queryToOptions(processKey, uri) {
+	const [path, query] = uri.split("?");
+	if (!query || !path) return {
+		shouldProcess: false,
+		path: ""
+	};
+	const parsed = queryString.parse(query, {
+		parseBooleans: true,
+		parseNumbers: true,
+		arrayFormat: "comma",
+		types: { bps: "number[]" }
+	});
+	if (processKey in parsed) return {
+		shouldProcess: true,
+		options: parsed,
+		path
+	};
+	else return {
+		shouldProcess: false,
+		path
+	};
+}
+
+//#endregion
+//#region src/plugin/file-utils.ts
 async function getFileHash(filePath) {
 	const content = await readFile(filePath);
 	return createHash("sha256").update(content).digest("hex").slice(0, 16);
@@ -22,33 +47,84 @@ async function saveFileSafe(path, data) {
 	try {
 		await mkdir(dir, { recursive: true });
 		await writeFile(path, data);
-		console.log(`Successfully saved to ${path}`);
 	} catch (err) {
 		console.error("Failed to save file:", err);
 	}
 }
-function queryToOptions(processKey, uri) {
-	const [path, query] = uri.split("?");
-	if (!query || !path) return {
-		shouldProcess: false,
-		path: ""
-	};
-	const parsed = queryString.parse(query, {
-		parseBooleans: true,
-		parseNumbers: true,
-		arrayFormat: "comma",
-		types: { bps: "number[]" }
-	});
-	if (processKey in parsed) return {
-		shouldProcess: true,
-		options: parsed,
-		path
+
+//#endregion
+//#region src/plugin/image-identifier.ts
+function createId(name, format, prefix, hash, dirs) {
+	const uniqueFileId = `${prefix}-${hash}-${basename(name)}.${format}`;
+	if (!dirs.isBuild) return join(dirs.devDir, uniqueFileId);
+	return join(dirs.assetsDir, dirs.distDir, uniqueFileId);
+}
+function createImageIdentifier(name, hash, dirs) {
+	return {
+		main(format) {
+			return createId(name, format, "main", hash, dirs);
+		},
+		placeholder(format) {
+			return createId(name, format, "placeholder", hash, dirs);
+		},
+		srcSet(format, breakpoint) {
+			return createId(name, format, `breakpoint-${breakpoint}`, hash, dirs);
+		}
 	};
-	else return {
-		shouldProcess: false,
-		path
+}
+
+//#endregion
+//#region src/plugin/image-entries.ts
+const PLACEHOLDER_IMG_SIZE = 8;
+const PLACEHOLDER_BLUR_QUALITY = 70;
+function createImageEntries() {
+	const map = /* @__PURE__ */ new Map();
+	return {
+		get(key) {
+			return map.get(key);
+		},
+		set(key, entry) {
+			map.set(key, entry);
+		},
+		entries() {
+			return map.entries();
+		},
+		createMainEntry(identifier, entry) {
+			const mainEntry = {
+				width: entry.width,
+				height: entry.height,
+				format: entry.format,
+				origin: entry.origin
+			};
+			this.set(identifier, mainEntry);
+		},
+		createPlaceholderEntry(identifier, main) {
+			let placeholderHeight = 0;
+			let placeholderWidth = 0;
+			if (main.width >= main.height) {
+				placeholderWidth = PLACEHOLDER_IMG_SIZE;
+				placeholderHeight = Math.max(Math.round(main.height / main.width * PLACEHOLDER_IMG_SIZE), 10);
+			} else {
+				placeholderWidth = Math.max(Math.round(main.width / main.height * PLACEHOLDER_IMG_SIZE), 10);
+				placeholderHeight = PLACEHOLDER_IMG_SIZE;
+			}
+			const placeholderEntry = {
+				width: placeholderWidth,
+				height: placeholderHeight,
+				format: main.format,
+				blur: PLACEHOLDER_BLUR_QUALITY,
+				origin: main.origin
+			};
+			this.set(identifier, placeholderEntry);
+		},
+		createSrcSetEntry(identifier, entry) {
+			this.set(identifier, entry);
+		}
 	};
 }
+
+//#endregion
+//#region src/plugin/image-process.ts
 async function processImage(path, options) {
 	let processed = sharp(path);
 	if (options.width || options.height) processed = processed.resize({
@@ -63,8 +139,6 @@ async function processImage(path, options) {
 //#endregion
 //#region src/plugin/plugin.ts
 const DEFAULT_IMAGE_FORMAT = "webp";
-const PLACEHOLDER_IMG_SIZE = 8;
-const PLACEHOLDER_BLUR_QUALITY = 70;
 const DEFAULT_CONFIGS = {
 	distDir: "oh-images",
 	bps: [
@@ -91,24 +165,11 @@ function ohImage(options) {
 	let assetsDir;
 	let outDir;
 	let cacheDir;
-	const imageEntries = /* @__PURE__ */ new Map();
+	const imageEntries = createImageEntries();
 	const config = {
 		...DEFAULT_CONFIGS,
 		...options
 	};
-	/**
-	* used for dev server to match url to path
-	* @param url
-	*/
-	function urlToPath(url) {
-		const fileId = basename(url);
-		return join(cacheDir, fileId);
-	}
-	function genIdentifier(uri, format, prefix, hash) {
-		const uniqueFileId = `${prefix}-${hash}-${basename(uri)}.${format}`;
-		if (!isBuild) return join(DEV_DIR, uniqueFileId);
-		return join(assetsDir, config.distDir, uniqueFileId);
-	}
 	return {
 		name: "oh-image",
 		configResolved(viteConfig) {
@@ -122,14 +183,14 @@ function ohImage(options) {
 			server.middlewares.use(async (req, res, next) => {
 				const url = req.url;
 				if (!url?.includes(DEV_DIR) || !SUPPORTED_IMAGE_FORMATS.test(url)) return next();
-				const path = urlToPath(url);
+				const fileId = basename(url);
+				const path = join(cacheDir, fileId);
 				const ext = extname(url).slice(1);
 				const image = await readFileSafe(path);
 				const imageEntry = imageEntries.get(url);
 				if (!imageEntry) {
 					console.warn("Image entry not found with id: " + url);
-					next();
-					return;
+					return next();
 				}
 				if (image) {
 					res.setHeader("Content-Type", `image/${ext}`);
@@ -156,14 +217,20 @@ function ohImage(options) {
 						...config,
 						...parsed.options
 					};
-					const mainIdentifier = genIdentifier(name, mergedOptions.format ?? ext.slice(1), "main", hash);
-					const mainEntry = {
+					const format = mergedOptions.format ?? ext.slice(1);
+					const identifier = createImageIdentifier(name, hash, {
+						isBuild,
+						devDir: DEV_DIR,
+						assetsDir,
+						distDir: config.distDir
+					});
+					const mainIdentifier = identifier.main(format);
+					imageEntries.createMainEntry(mainIdentifier, {
 						width: mergedOptions.width,
 						height: mergedOptions.height,
 						format: mergedOptions.format,
 						origin
-					};
-					imageEntries.set(mainIdentifier, mainEntry);
+					});
 					const src = {
 						width: metadata.width,
 						height: metadata.height,
@@ -171,36 +238,24 @@ function ohImage(options) {
 						srcSets: ""
 					};
 					if (parsed.options?.placeholder) {
-						let placeholderHeight = 0;
-						let placeholderWidth = 0;
-						if (metadata.width >= metadata.height) {
-							placeholderWidth = PLACEHOLDER_IMG_SIZE;
-							placeholderHeight = Math.max(Math.round(metadata.height / metadata.width * PLACEHOLDER_IMG_SIZE), 1);
-						} else {
-							placeholderWidth = Math.max(Math.round(metadata.width / metadata.height * PLACEHOLDER_IMG_SIZE), 1);
-							placeholderHeight = PLACEHOLDER_IMG_SIZE;
-						}
-						const placeholderIdentifier = genIdentifier(name, DEFAULT_IMAGE_FORMAT, "placeholder", hash);
-						const placeholderEntry = {
-							width: placeholderWidth,
-							height: placeholderHeight,
+						const placeholderIdentifier = identifier.placeholder(DEFAULT_IMAGE_FORMAT);
+						imageEntries.createPlaceholderEntry(placeholderIdentifier, {
+							width: metadata.width,
+							height: metadata.height,
 							format: DEFAULT_IMAGE_FORMAT,
-							blur: PLACEHOLDER_BLUR_QUALITY,
 							origin
-						};
-						imageEntries.set(placeholderIdentifier, placeholderEntry);
+						});
 						src.placeholderUrl = placeholderIdentifier;
 					}
 					if (mergedOptions.bps) {
 						const srcSets = [];
 						for (const breakpoint of mergedOptions.bps) {
-							const srcSetIdentifier = genIdentifier(name, DEFAULT_IMAGE_FORMAT, `breakpoint-${breakpoint}`, hash);
-							const srcSetEntry = {
+							const srcSetIdentifier = identifier.srcSet(DEFAULT_IMAGE_FORMAT, breakpoint);
+							imageEntries.createSrcSetEntry(srcSetIdentifier, {
 								width: breakpoint,
 								format: DEFAULT_IMAGE_FORMAT,
 								origin
-							};
-							imageEntries.set(srcSetIdentifier, srcSetEntry);
+							});
 							srcSets.push(`${srcSetIdentifier} ${breakpoint}w`);
 						}
 						src.srcSets = srcSets.join(", ");
@@ -214,7 +269,7 @@ function ohImage(options) {
 		},
 		async writeBundle() {
 			const limit = pLimit(30);
-			const tasks = Array.from(imageEntries, ([key, value]) => limit(async () => {
+			const tasks = Array.from(imageEntries.entries(), ([key, value]) => limit(async () => {
 				const processed = await processImage(value.origin, value);
 				await saveFileSafe(join(outDir, key), processed);
 			}));

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import * as react_jsx_runtime0 from "react/jsx-runtime";
 import { ImgHTMLAttributes } from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/react/types.d.ts
 type ImageSrcType = string | ImageSrc;
@@ -22,4 +22,33 @@ interface ImageProps extends Partial<Pick<ImgHTMLAttributes<HTMLImageElement>, "
 //#region src/react/image.d.ts
 declare function Image(props: ImageProps): react_jsx_runtime0.JSX.Element;
 //#endregion
-export { Image, type ImageProps };
+//#region src/react/use-img-loaded.d.ts
+/**
+ * A hook that tracks whether an image element has finished loading.
+ *
+ * Handles all edge cases:
+ * - Image already cached/complete on mount
+ * - Normal load via event listener
+ * - Errors (resets to `false`)
+ * - `src` changes (resets to `false` until the new source loads)
+ * - Element unmount / ref set to `null`
+ *
+ * @returns `[ref, isLoaded]` — attach the ref callback to an `<img>` element.
+ *
+ * @example
+ * ```tsx
+ * function Avatar({ src }: { src: string }) {
+ *   const [imgRef, isLoaded] = useImgLoaded(src);
+ *   return (
+ *     <img
+ *       ref={imgRef}
+ *       src={src}
+ *       style={{ opacity: isLoaded ? 1 : 0 }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function useImgLoaded(src: string | undefined): [(img: HTMLImageElement | null) => void, boolean];
+//#endregion
+export { Image, type ImageProps, useImgLoaded };

package/dist/react.js

@@ -1,10 +1,92 @@
 import * as ReactDOM from "react-dom";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 
-//#region src/react/image.tsx
-const preload = "preload" in ReactDOM && typeof ReactDOM.preload === "function" ? ReactDOM.preload : null;
-function resolveOptions(props) {
-	const { src, ...rest } = props;
+//#region src/react/use-img-loaded.ts
+/**
+* A hook that tracks whether an image element has finished loading.
+*
+* Handles all edge cases:
+* - Image already cached/complete on mount
+* - Normal load via event listener
+* - Errors (resets to `false`)
+* - `src` changes (resets to `false` until the new source loads)
+* - Element unmount / ref set to `null`
+*
+* @returns `[ref, isLoaded]` — attach the ref callback to an `<img>` element.
+*
+* @example
+* ```tsx
+* function Avatar({ src }: { src: string }) {
+*   const [imgRef, isLoaded] = useImgLoaded(src);
+*   return (
+*     <img
+*       ref={imgRef}
+*       src={src}
+*       style={{ opacity: isLoaded ? 1 : 0 }}
+*     />
+*   );
+* }
+* ```
+*/
+function useImgLoaded(src) {
+	const [state, setState] = useState({
+		src,
+		loaded: false
+	});
+	let isLoaded = state.loaded;
+	if (state.src !== src) {
+		isLoaded = false;
+		setState({
+			src,
+			loaded: false
+		});
+	}
+	const imgRef = useRef(null);
+	const onLoad = useCallback(() => setState((prev) => ({
+		...prev,
+		loaded: true
+	})), []);
+	const onError = useCallback(() => setState((prev) => ({
+		...prev,
+		loaded: false
+	})), []);
+	const ref = useCallback((img) => {
+		const prev = imgRef.current;
+		if (prev) {
+			prev.removeEventListener("load", onLoad);
+			prev.removeEventListener("error", onError);
+		}
+		imgRef.current = img;
+		if (!img) return;
+		if (img.complete && img.naturalWidth > 0) setState((prev$1) => ({
+			...prev$1,
+			loaded: true
+		}));
+		img.addEventListener("load", onLoad);
+		img.addEventListener("error", onError);
+	}, [onLoad, onError]);
+	useEffect(() => {
+		return () => {
+			const img = imgRef.current;
+			if (img) {
+				img.removeEventListener("load", onLoad);
+				img.removeEventListener("error", onError);
+			}
+		};
+	}, [onLoad, onError]);
+	return [ref, isLoaded];
+}
+
+//#endregion
+//#region src/react/prop-resolvers.ts
+/**
+* RegExpr to determine whether a src in a srcset is using width descriptors.
+* Should match something like: "100w, 200w".
+*/
+const VALID_WIDTH_DESCRIPTOR_SRCSET = /^((\s*\d+w\s*(,|$)){1,})$/;
+function resolveOptions(prop) {
+	const { src, ...rest } = prop;
 	const resolved = { ...rest };
 	if (typeof src === "object") {
 		resolved.src = src.src;
@@ -13,18 +95,46 @@ function resolveOptions(props) {
 		resolved.srcSet ??= src.srcSets;
 		resolved.placeholderUrl ??= src.placeholderUrl;
 	} else resolved.src = src;
-	if (props.asap) {
+	if (prop.asap) {
 		resolved.decoding = "async";
 		resolved.loading = "eager";
 		resolved.fetchPriority = "high";
-		if (preload) preload(resolved.src, {
-			as: "image",
-			fetchPriority: "high"
-		});
 	}
-	if (props.fill) resolved.sizes ||= "100vw";
+	resolved.sizes = resolveSizes(prop);
+	resolved.loading = resolveLoading(prop);
 	return resolved;
 }
+function resolveLoading(prop) {
+	if (!prop.asap && prop.loading !== void 0) return prop.loading;
+	return prop.asap ? "eager" : "lazy";
+}
+function resolveSizes(prop) {
+	const loading = resolveLoading(prop);
+	let sizes = prop.sizes;
+	if (prop.fill) sizes ||= "100vw";
+	if (sizes) {
+		if (loading === "lazy") sizes = "auto, " + sizes;
+	} else if (prop.srcSet && VALID_WIDTH_DESCRIPTOR_SRCSET.test(prop.srcSet) && loading === "lazy") sizes = "auto, 100vw";
+	return sizes;
+}
+
+//#endregion
+//#region src/react/prop-asserts.ts
+function assertProps(prop) {
+	assertLoadingProp(prop);
+}
+function assert(assertion, message) {
+	if (import.meta.env.DEV) {
+		if (assertion()) throw new Error(message);
+	}
+}
+function assertLoadingProp(prop) {
+	assert(() => prop.loading && prop.asap, `Do not use \`loading\` on a asap image — asap images are always eagerly loaded.`);
+}
+
+//#endregion
+//#region src/react/image.tsx
+const preload = "preload" in ReactDOM && typeof ReactDOM.preload === "function" ? ReactDOM.preload : null;
 function getPlaceholderStyles(props) {
 	if (!props.placeholderUrl) return {};
 	return {
@@ -43,15 +153,22 @@ function getFillStyles(props) {
 	};
 }
 function Image(props) {
+	assertProps(props);
 	const options = resolveOptions(props);
-	const placeholderStyles = getPlaceholderStyles(options);
+	const [imgRef, isLoaded] = useImgLoaded(options.src);
+	const placeholderStyles = isLoaded ? {} : getPlaceholderStyles(options);
 	const fillStyles = getFillStyles(options);
 	const styles = {
 		...placeholderStyles,
 		...fillStyles,
 		...props.style
 	};
+	if (preload && options.asap) preload(options.src, {
+		as: "image",
+		fetchPriority: "high"
+	});
 	return /* @__PURE__ */ jsx("img", {
+		ref: imgRef,
 		className: props.className,
 		style: styles,
 		src: options.src,
@@ -67,4 +184,4 @@ function Image(props) {
 }
 
 //#endregion
-export { Image };
+export { Image, useImgLoaded };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lonik/oh-image",
   "type": "module",
-  "version": "1.2.7",
+  "version": "1.3.0",
   "description": "A React component library for optimized image handling.",
   "author": "Luka Onikadze <lukonik@gmail.com>",
   "license": "MIT",
@@ -51,29 +51,33 @@
     "sharp": ">=0.34.5"
   },
   "devDependencies": {
+    "@commitlint/config-conventional": "^20.4.1",
     "@eslint/js": "^9.39.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@tsconfig/strictest": "^2.0.8",
     "@types/node": "^25.0.3",
     "@types/react": "^18",
     "@types/react-dom": "^18",
     "@vitejs/plugin-react": "^5.1.2",
-    "@vitest/browser-playwright": "^4.0.16",
     "bumpp": "^10.3.2",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-react": "^7.37.5",
     "globals": "^17.3.0",
+    "happy-dom": "^20.6.0",
     "tsdown": "^0.18.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.54.0",
     "vite": "^7.3.0",
-    "vitest": "^4.0.16",
-    "vitest-browser-react": "^2.0.2",
-    "@commitlint/config-conventional": "^20.4.1"
+    "vitest": "^4.0.16"
   },
   "dependencies": {
+    "@types/supertest": "^6.0.3",
+    "memfs": "^4.56.10",
     "p-limit": "^7.3.0",
-    "query-string": "^9.3.1"
+    "query-string": "^9.3.1",
+    "supertest": "^7.2.2"
   },
   "keywords": [
     "react",