toolbox-x 1.0.0

package/dist/dom.cjs

@@ -0,0 +1,461 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primitives = require('./primitives-B26uZolQ.cjs');
+const require_specials = require('./specials-DzLr1ZgU.cjs');
+const require_guards = require('./guards-Efhp1mNy.cjs');
+const require_objectify = require('./objectify-DIJ-OBmo.cjs');
+const require_utils = require('./utils-DLFRgXUC.cjs');
+
+//#region src/dom/query.ts
+/**
+* * Utility to generate query parameters from an object.
+*
+* @param params - Object containing query parameters.
+* @returns A query string as a URL-encoded string, e.g., `?key1=value1&key2=value2`.
+*
+* @example
+* generateQueryParams({ key1: 'value1', key2: 42 }); // "?key1=value1&key2=42"
+* generateQueryParams({ key1: ['value1', 'value2'], key2: 42 }); // "?key1=value1&key1=value2&key2=42"
+* generateQueryParams({ key1: '', key2: null }); // ""
+* generateQueryParams({ key1: true, key2: false }); // "?key1=true&key2=false"
+* generateQueryParams({ filters: { category: 'laptop', price: 1000 } }); // "?category=laptop&price=1000"
+*/
+function generateQueryParams(params = {}) {
+	const flattenedParams = require_objectify.flattenObjectKeyValue(params);
+	const queryParams = Object.entries(flattenedParams)?.filter(([_, value]) => value != null && !(require_primitives.isString(value) && value?.trim() === ""))?.flatMap(([key, value]) => Array.isArray(value) ? value?.filter((v) => v != null && !(require_primitives.isString(v) && v.trim() === ""))?.map((v) => `${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`) : `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`).join("&");
+	return queryParams ? `?${queryParams}` : "";
+}
+/**
+* * Get query params as standard `JavaScript` Object `Record<string, string>`. You can define the type by passing a type argument.
+*
+* - **Note:** *Extracts query parameters from the current URL (window.location.search).*
+*
+* @returns Query string as key-value paired object. `Record<string, string>`.
+*/
+function getQueryParams() {
+	return Object.fromEntries(new URLSearchParams(window?.location?.search));
+}
+/**
+* * Update query params in the browser URL with given key and value.
+* @param key Key for the query to update.
+* @param value Value to updated against the given key.
+*/
+function updateQueryParam(key, value) {
+	const url = new URL(window.location.href);
+	url.searchParams.set(key, value);
+	window.history.replaceState({}, "", url?.toString());
+}
+/**
+* Parses a query string (with optional `?` prefix) into an object.
+* Supports multiple values for the same key by returning arrays.
+* Optionally parses primitive string values into actual types (e.g., "1" → 1, "true" → true).
+*
+* @remarks This utility is designed to parse generic string, for literal use, try {@link parseQueryStringLiteral}.
+*
+* - **Note:** *This function does **not** access or depend on `current URL` a.k.a `window.location.search`.*
+*
+* @param query - The query string to parse.
+* @param parsePrimitives - Whether to convert stringified primitives into real values (default: true).
+* @returns An object where keys are strings and values can be string, array, number, boolean, or null/undefined.
+*/
+function parseQueryString(query, parsePrimitives = true) {
+	const params = new URLSearchParams(query.startsWith("?") ? query.slice(1) : query);
+	const entries = {};
+	for (const [key, value] of params.entries()) if (key in entries) {
+		const current = entries[key];
+		const array = Array.isArray(current) ? [...current, value] : [current, value];
+		entries[key] = parsePrimitives ? require_utils.deepParsePrimitives(array) : array;
+	} else entries[key] = value;
+	return parsePrimitives ? require_objectify.parseObjectValues(entries) : entries;
+}
+/**
+* Parses a query string (with optional `?` prefix) into an object.
+* Supports multiple values for the same key by returning arrays.
+* It returns properly typed object.
+*
+* @remarks This utility is designed to parse literal string, for generic use, try {@link parseQueryString}.
+*
+* - **Note:** *This function does **not** access or depend on `current URL` a.k.a `window.location.search`.*
+*
+* @param query - The literal query string to parse.
+* @returns An object where keys are strings and values can be string, array, or null/undefined.
+*/
+function parseQueryStringLiteral(query) {
+	const params = new URLSearchParams(query.startsWith("?") ? query.slice(1) : query);
+	const entries = {};
+	for (const [key, value] of params.entries()) if (key in entries) {
+		const current = entries[key];
+		entries[key] = Array.isArray(current) ? [...current, value] : [current, value];
+	} else entries[key] = value;
+	return entries;
+}
+
+//#endregion
+//#region src/dom/storage.ts
+/**
+* * Get item from local storage.
+*
+* @param key - Key to get item from local storage.
+* @param deserialize - Optional deserializer function to convert the stored value back to type `T`. Defaults to `JSON.parse`.
+* @returns Returns saved item from local storage if it exists with that key.
+*/
+function getFromLocalStorage(key, deserialize) {
+	const deserializer = deserialize ?? JSON.parse;
+	try {
+		const item = localStorage.getItem(key);
+		return item ? deserializer(item) : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* * Save item in local storage.
+*
+* @param key - Key to save an item.
+* @param value - The item/value to save.
+* @param serialize - Optional serializer function to convert the value of type `T` to a string. Defaults to `JSON.stringify`.
+*/
+function saveToLocalStorage(key, value, serialize) {
+	const serializer = serialize ?? JSON.stringify;
+	try {
+		localStorage.setItem(key, serializer(value));
+	} catch (error) {
+		console.error(`Error saving item with key "${key}" in local storage:`, error);
+	}
+}
+/**
+* * Remove item from local storage.
+*
+* @param key - Key to delete item from local storage.
+*/
+function removeFromLocalStorage(key) {
+	try {
+		localStorage.removeItem(key);
+	} catch (error) {
+		console.error(`Error removing item with key "${key}" from local storage:`, error);
+	}
+}
+/**
+* * Get item from session storage.
+*
+* @param key - Key to get item from session storage.
+* @param deserialize - Optional deserializer function to convert the stored value back to type `T`. Defaults to `JSON.parse`.
+* @returns Returns saved item from session storage if it exists with that key.
+*/
+function getFromSessionStorage(key, deserialize) {
+	const deserializer = deserialize ?? JSON.parse;
+	try {
+		const item = sessionStorage.getItem(key);
+		return item ? deserializer(item) : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* * Save item in session storage.
+*
+* @param key - Key to save an item.
+* @param value - The item/value to save.
+* @param serialize - Optional serializer function to convert the value of type `T` to a string. Defaults to `JSON.stringify`.
+*/
+function saveToSessionStorage(key, value, serialize) {
+	const serializer = serialize ?? JSON.stringify;
+	try {
+		sessionStorage.setItem(key, serializer(value));
+	} catch (error) {
+		console.error(`Error saving item with key "${key}" in session storage:`, error);
+	}
+}
+/**
+* * Remove item from session storage.
+*
+* @param key - Key to delete item from session storage.
+*/
+function removeFromSessionStorage(key) {
+	try {
+		sessionStorage.removeItem(key);
+	} catch (error) {
+		console.error(`Error removing item with key "${key}" from session storage:`, error);
+	}
+}
+
+//#endregion
+//#region src/dom/utils.ts
+/**
+* * Scrolls smoothly to the given element with an optional vertical offset.
+* @param element The target element to scroll to.
+* @param offset Additional vertical offset in pixels (positive moves down, negative moves up).
+*/
+function smoothScrollTo(element, offset = 0) {
+	element.scrollIntoView({
+		behavior: "smooth",
+		block: "start"
+	});
+	if (offset !== 0) setTimeout(() => {
+		window.scrollBy({
+			top: offset,
+			behavior: "smooth"
+		});
+	}, 300);
+}
+/**
+* * Toggles full-screen mode for a given element (or the `document` by default).
+* @param element The element to toggle fullscreen mode for (default: document root).
+*/
+function toggleFullScreen(element = document.documentElement) {
+	const doc = document;
+	const elem = element;
+	if (!doc.fullscreenElement && !doc.webkitFullscreenElement) {
+		if (elem.requestFullscreen) elem.requestFullscreen();
+		else if (elem.webkitRequestFullscreen) elem.webkitRequestFullscreen();
+	} else if (doc.exitFullscreen) doc.exitFullscreen();
+	else if (doc.webkitExitFullscreen) doc.webkitExitFullscreen();
+}
+/**
+* * Copies text to the clipboard, falling back to legacy methods if needed.
+* @param text - The text to copy.
+* @returns A promise that resolves when the text is copied.
+*/
+async function copyToClipboard(text) {
+	try {
+		if (navigator?.clipboard?.writeText) await navigator.clipboard.writeText(text);
+		else {
+			const textArea = document.createElement("textarea");
+			textArea.value = text;
+			textArea.style.position = "fixed";
+			textArea.style.opacity = "0";
+			document.body.appendChild(textArea);
+			textArea.select();
+			textArea.setSelectionRange(0, textArea.value?.length);
+			const success = document.execCommand("copy");
+			document.body.removeChild(textArea);
+			if (!success) throw new Error("Cannot execute command in this environment!");
+		}
+	} catch (error) {
+		console.error("Failed to copy text:", error);
+		throw error;
+	} finally {
+		const textArea = document.querySelector("textarea[style*=\"fixed\"]");
+		if (textArea) document.body.removeChild(textArea);
+	}
+}
+
+//#endregion
+//#region src/form/convert.ts
+/**
+* * Utility to convert object into FormData in a controlled way.
+* - **N.B.** Be cautious when using this in SSR (Server-Side Rendering) environments (such as `Next.js` Server Components), as it may not work as expected.
+*
+* @param data - The source object to control and convert to FormData.
+* @param configs - Configuration options to control the formData.
+* @returns `FormData` instance containing the sanitized and transformed data.
+*/
+const createControlledFormData = (data, configs) => {
+	const formData = new FormData();
+	const { stringifyNested = "*" } = configs || {};
+	/** - Helper to check if a key should be lowercase */
+	const _shouldLowercaseKeys = (key) => {
+		return Array.isArray(configs?.lowerCaseKeys) ? configs?.lowerCaseKeys?.some((path) => key === path || key.startsWith(`${path}.`)) : configs?.lowerCaseKeys === "*";
+	};
+	/** - Helper to check if a key should be lowercase */
+	const _shouldLowercaseValue = (key) => {
+		return Array.isArray(configs?.lowerCaseValues) ? configs.lowerCaseValues?.some((path) => key === path || key?.startsWith(`${path}.`)) : configs?.lowerCaseValues === "*";
+	};
+	/** - Transforms key to lowercase if needed */
+	const _transformKey = (key) => {
+		return _shouldLowercaseKeys(key) ? key.toLowerCase() : key;
+	};
+	/** - Helper function to check if a key matches a breakArray key. */
+	const _isRequiredKey = (key) => {
+		const transformedKey = _transformKey(key);
+		return Array.isArray(configs?.requiredKeys) ? configs?.requiredKeys?.some((path) => transformedKey === path || transformedKey?.startsWith(`${path}.`)) : configs?.requiredKeys === "*";
+	};
+	/** - Helper function to check if a key matches a dotNotation path to preserve. */
+	const _shouldDotNotate = (key) => {
+		const transformedKey = _transformKey(key);
+		return Array.isArray(configs?.dotNotateNested) ? configs.dotNotateNested.includes(transformedKey) : configs?.dotNotateNested === "*";
+	};
+	/** - Helper function to check if a key matches a stringifyNested key. */
+	const _shouldStringify = (key) => {
+		const transformedKey = _transformKey(key);
+		return Array.isArray(stringifyNested) ? stringifyNested.includes(transformedKey) : stringifyNested === "*";
+	};
+	/** - Helper function to check if a key matches a breakArray key. */
+	const _shouldBreakArray = (key) => {
+		const transformedKey = _transformKey(key);
+		return Array.isArray(configs?.breakArray) ? configs.breakArray.includes(transformedKey) : configs?.breakArray === "*";
+	};
+	/** - Helper to clean object by removing null/undefined/empty values while respecting required keys */
+	const _cleanObject = (obj, parentKey = "") => {
+		return Object.entries(obj).reduce((acc, [key, value]) => {
+			const transformedKey = _transformKey(key);
+			const fullKey = parentKey ? `${parentKey}.${transformedKey}` : transformedKey;
+			if (configs?.ignoreKeys?.includes(fullKey)) return acc;
+			if (value != null && value !== "" || _isRequiredKey(fullKey) || require_primitives.isNonEmptyString(value) || require_specials.isValidArray(value) || require_specials.isNotEmptyObject(value)) if (require_specials.isNotEmptyObject(value)) if (require_guards.isDateLike(value)) acc[transformedKey] = value;
+			else {
+				const cleaned = _cleanObject(value, fullKey);
+				if (_isRequiredKey(fullKey) || require_specials.isNotEmptyObject(cleaned)) acc[transformedKey] = cleaned;
+			}
+			else if (require_primitives.isString(value)) if (require_primitives.isNonEmptyString(value)) {
+				let cleanString = value;
+				if (configs?.trimStrings) cleanString = cleanString?.trim();
+				if (_shouldLowercaseValue(fullKey)) cleanString = cleanString?.toLowerCase();
+				acc[transformedKey] = cleanString;
+			} else acc[transformedKey] = value;
+			else if (Array.isArray(value)) {
+				if (_isRequiredKey(fullKey) || require_specials.isValidArray(value)) acc[transformedKey] = value;
+			} else if (require_specials.isEmptyObject(value)) {
+				if (_isRequiredKey(fullKey)) acc[transformedKey] = value;
+			} else acc[transformedKey] = value;
+			return acc;
+		}, {});
+	};
+	/** * Helper function to add values to formData */
+	const _addToFormData = (key, value) => {
+		const transformedKey = _transformKey(key);
+		if (require_objectify.isCustomFileArray(value)) value?.forEach((file) => formData.append(transformedKey, file?.originFileObj));
+		else if (require_objectify.isFileUpload(value)) {
+			if (value?.fileList) value?.fileList.forEach((file) => formData.append(transformedKey, file?.originFileObj));
+			else if (value?.file) if (require_objectify.isCustomFile(value?.file)) formData.append(transformedKey, value?.file?.originFileObj);
+			else formData.append(transformedKey, value?.file);
+		} else if (require_objectify.isFileOrBlob(value)) formData.append(transformedKey, value);
+		else if (require_objectify.isFileList(value)) for (let i = 0; i < value?.length; i++) formData.append(transformedKey, value.item(i));
+		else if (Array.isArray(value)) {
+			if (require_objectify.isFileArray(value)) if (_shouldBreakArray(key)) value?.forEach((item, index) => {
+				_addToFormData(`${transformedKey}[${index}]`, item);
+			});
+			else value?.forEach((item) => {
+				formData.append(transformedKey, item);
+			});
+			else if (require_specials.isValidArray(value)) if (_shouldBreakArray(key)) value?.forEach((item, index) => {
+				_addToFormData(`${transformedKey}[${index}]`, item);
+			});
+			else formData.append(transformedKey, JSON.stringify(value));
+			else if (_isRequiredKey(key)) formData.append(transformedKey, JSON.stringify(value));
+		} else if (require_guards.isDateLike(value)) formData.append(transformedKey, JSON.parse(JSON.stringify(value)));
+		else if (require_specials.isNotEmptyObject(value)) if (_shouldStringify(key) && !_shouldDotNotate(key)) {
+			const cleanedValue = _cleanObject(value, key);
+			if (require_specials.isNotEmptyObject(cleanedValue) || _isRequiredKey(key)) formData.append(transformedKey, JSON.stringify(cleanedValue));
+		} else Object.entries(value).forEach(([nestedKey, nestedValue]) => {
+			_addToFormData(`${key}.${nestedKey}`, nestedValue);
+		});
+		else if (value != null && value !== "" || _isRequiredKey(key)) if (require_primitives.isString(value) && _shouldLowercaseValue(key)) formData.append(transformedKey, value?.toLowerCase());
+		else formData.append(transformedKey, value);
+	};
+	/** - Helper to process object */
+	const _processObject = (obj, parentKey = "") => {
+		Object.entries(obj).forEach(([key, value]) => {
+			const transformedKey = _transformKey(key);
+			const fullKey = parentKey ? `${parentKey}.${transformedKey}` : transformedKey;
+			if (configs?.ignoreKeys?.includes(fullKey)) return;
+			if (configs?.trimStrings && require_primitives.isNonEmptyString(value)) value = value?.trim();
+			if (_shouldDotNotate(fullKey)) _addToFormData(fullKey, value);
+			else if (require_specials.isNotEmptyObject(value) && !_shouldStringify(fullKey)) if (require_guards.isDateLike(value)) _addToFormData(key, JSON.parse(JSON.stringify(value)));
+			else _processObject(value, key);
+			else if (require_objectify.isFileOrBlob(value)) _addToFormData(key, value);
+			else if (require_guards.isDateLike(value)) _addToFormData(key, JSON.parse(JSON.stringify(value)));
+			else if (require_specials.isEmptyObject(value)) {
+				if (_isRequiredKey(fullKey)) _addToFormData(key, JSON.stringify(value));
+			} else _addToFormData(key, value);
+		});
+	};
+	if (require_specials.isNotEmptyObject(data)) _processObject(data);
+	return formData;
+};
+
+//#endregion
+//#region src/form/transform.ts
+/**
+* * Serialize form data into an object or a query string.
+* - **N.B.** Be cautious when using this in SSR (Server-Side Rendering) environments (such as `Next.js` Server Components), as it may not work as expected.
+*
+* @param form - The form element to serialize.
+* @param toQueryString - Whether to return the result as a query string. If false, returns an object.
+* @returns The serialized form data as an object or query string.
+*/
+function serializeForm(form, toQueryString = false) {
+	const formData = new FormData(form);
+	const data = {};
+	formData?.forEach((value, key) => {
+		if (data[key]) data[key] = Array.isArray(data[key]) ? [...data[key], value.toString()] : [data[key], value.toString()];
+		else data[key] = value.toString();
+	});
+	if (toQueryString) return generateQueryParams(data);
+	return data;
+}
+/**
+* * Parse form data from a `FormData` object or query string into a structured object format.
+*
+* @param data - The `FormData` object or query string to parse.
+* @param parsePrimitives - Whether to parse string values into primitive types (e.g., boolean, number, array, object). Defaults to `true`.
+* @returns The parsed form data as an object.
+*/
+function parseFormData(data, parsePrimitives = true) {
+	const parsed = {};
+	if (require_primitives.isString(data)) new URLSearchParams(data)?.forEach((value, key) => {
+		const existing = parsed[key];
+		if (require_primitives.isString(existing)) parsed[key] = [existing, value];
+		else if (Array.isArray(existing)) parsed[key] = [...existing, value];
+		else parsed[key] = value;
+	});
+	else data?.forEach((value, key) => {
+		const existing = parsed[key];
+		if (value instanceof File) if (Array.isArray(existing)) parsed[key] = [...existing, value];
+		else if (existing instanceof File) parsed[key] = [existing, value];
+		else parsed[key] = value;
+		else if (require_primitives.isString(existing)) parsed[key] = [existing, value];
+		else if (Array.isArray(existing)) parsed[key] = [...existing, value];
+		else parsed[key] = value;
+	});
+	if (parsePrimitives) return require_objectify.parseObjectValues(parsed);
+	else return parsed;
+}
+
+//#endregion
+exports.convertIntoFormData = createControlledFormData;
+exports.copyToClipboard = copyToClipboard;
+exports.createControlledFormData = createControlledFormData;
+exports.createFormData = createControlledFormData;
+exports.createQueryParams = generateQueryParams;
+exports.formatQueryParams = generateQueryParams;
+exports.generateQueryParams = generateQueryParams;
+exports.getFromLocalStorage = getFromLocalStorage;
+exports.getFromSessionStorage = getFromSessionStorage;
+exports.getQueryParams = getQueryParams;
+exports.getQueryStringAsObject = parseQueryString;
+exports.isCustomFile = require_objectify.isCustomFile;
+exports.isCustomFileArray = require_objectify.isCustomFileArray;
+exports.isFileArray = require_objectify.isFileArray;
+exports.isFileList = require_objectify.isFileList;
+exports.isFileOrBlob = require_objectify.isFileOrBlob;
+exports.isFileUpload = require_objectify.isFileUpload;
+exports.isOriginFileObj = require_objectify.isOriginFileObj;
+exports.isValidFormData = require_objectify.isValidFormData;
+exports.literalQueryStringToObject = parseQueryStringLiteral;
+exports.parseFormData = parseFormData;
+exports.parseQueryString = parseQueryString;
+exports.parseQueryStringLiteral = parseQueryStringLiteral;
+exports.queryStringToObject = parseQueryString;
+exports.removeFromLocalStorage = removeFromLocalStorage;
+exports.removeFromSessionStorage = removeFromSessionStorage;
+exports.saveToLocalStorage = saveToLocalStorage;
+exports.saveToSessionStorage = saveToSessionStorage;
+exports.serializeForm = serializeForm;
+exports.smoothScrollTo = smoothScrollTo;
+exports.toggleFullScreen = toggleFullScreen;
+exports.updateQueryParam = updateQueryParam;