toolbox-x 1.0.0

package/dist/dom.d.cts

@@ -0,0 +1,228 @@
+/**
+ * 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.
+ */
+
+import { A as ParsedQuery, G as Deserializer, M as QueryObject, ct as Serializer, j as ParsedQueryGeneric, y as GenericObject } from "./object-Blq0Amdv.cjs";
+import { P as QueryString } from "./string-CsNsm_65.cjs";
+import { a as OriginFileObj, i as FormDataConfigs, o as ParsedFormData, r as FileUpload, s as SerializedForm, t as CustomFile } from "./form-DRFbryvK.cjs";
+
+//#region src/dom/query.d.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"
+ */
+declare function generateQueryParams<T extends QueryObject>(params?: T): QueryString;
+/**
+ * * 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>`.
+ */
+declare function getQueryParams<QParams extends Record<string, string>>(): QParams;
+/**
+ * * 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.
+ */
+declare function updateQueryParam(key: string, value: string): void;
+/**
+ * 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.
+ */
+declare function parseQueryString<QParams extends ParsedQueryGeneric>(query: string, parsePrimitives?: boolean): QParams;
+/**
+ * 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.
+ */
+declare function parseQueryStringLiteral<Q extends string>(query: Q): ParsedQuery<Q>;
+//#endregion
+//#region src/dom/storage.d.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.
+ */
+declare function getFromLocalStorage<T>(key: string, deserialize?: Deserializer<T>): T | 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`.
+ */
+declare function saveToLocalStorage<T>(key: string, value: T, serialize?: Serializer<T>): void;
+/**
+ * * Remove item from local storage.
+ *
+ * @param key - Key to delete item from local storage.
+ */
+declare function removeFromLocalStorage(key: string): void;
+/**
+ * * 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.
+ */
+declare function getFromSessionStorage<T>(key: string, deserialize?: Deserializer<T>): T | 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`.
+ */
+declare function saveToSessionStorage<T>(key: string, value: T, serialize?: Serializer<T>): void;
+/**
+ * * Remove item from session storage.
+ *
+ * @param key - Key to delete item from session storage.
+ */
+declare function removeFromSessionStorage(key: string): void;
+//#endregion
+//#region src/dom/utils.d.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).
+ */
+declare function smoothScrollTo(element: HTMLElement, offset?: number): void;
+/**
+ * * 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).
+ */
+declare function toggleFullScreen(element?: HTMLElement): void;
+/**
+ * * 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.
+ */
+declare function copyToClipboard(text: string): Promise<void>;
+//#endregion
+//#region src/form/convert.d.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.
+ */
+declare const createControlledFormData: <T extends GenericObject>(data: T, configs?: FormDataConfigs<T>) => FormData;
+//#endregion
+//#region src/form/guards.d.ts
+/**
+ * * Checks if a given value is a valid `FormData` & it's not empty.
+ * - **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 value - The value to check.
+ * @returns `true` if the value is a valid `FormData` and not empty, otherwise `false`.
+ */
+declare function isValidFormData(value: unknown): value is FormData;
+/**
+ * * Checks if a given value is an `OriginFileObj`.
+ * - **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 value - The value to check.
+ * @returns `true` if the value is a valid `OriginFileObj`, otherwise `false`.
+ */
+declare function isOriginFileObj(value: unknown): value is OriginFileObj;
+/**
+ * * Checks if a given value is a `CustomFile`.
+ * - **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 value - The value to check.
+ * @returns `true` if the value is a valid `CustomFile`, otherwise `false`.
+ */
+declare function isCustomFile(value: unknown): value is CustomFile;
+/**
+ * * Checks if a given value is an array of `CustomFile` objects.
+ * - **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 value - The value to check.
+ * @returns `true` if the value is a valid `CustomFile[]`, otherwise `false`.
+ */
+declare function isCustomFileArray(value: unknown): value is CustomFile[];
+/**
+ * * Checks if a given value is an array of `File/Blob` objects.
+ * - **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 value - The value to check.
+ * @returns `true` if the value is a valid `File[]` or `Blob[]`, otherwise `false`.
+ */
+declare function isFileArray(value: unknown): value is File[] | Blob[];
+/**
+ * * Checks if a given value is an instance of `FileList`.
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid `FileList`, otherwise `false`.
+ */
+declare function isFileList(value: unknown): value is FileList;
+/**
+ * * Checks if a given value is an instance of `File` or `Blob`.
+ * @param value - The value to check.
+ * @returns `true` if the value is an instance of `File` or `Blob`, otherwise `false`.
+ */
+declare function isFileOrBlob(value: unknown): value is File | Blob;
+/**
+ * * Checks if a given value is a `FileUpload` object.
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid `FileUpload`, otherwise `false`.
+ */
+declare function isFileUpload(value: unknown): value is FileUpload;
+//#endregion
+//#region src/form/transform.d.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.
+ */
+declare function serializeForm<T extends boolean = false>(form: HTMLFormElement, toQueryString?: T): SerializedForm<T>;
+/**
+ * * 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.
+ */
+declare function parseFormData<T extends FormData | string>(data: T, parsePrimitives?: boolean): ParsedFormData<T>;
+//#endregion
+export { createControlledFormData as convertIntoFormData, createControlledFormData, createControlledFormData as createFormData, copyToClipboard, generateQueryParams as createQueryParams, generateQueryParams as formatQueryParams, generateQueryParams, getFromLocalStorage, getFromSessionStorage, getQueryParams, parseQueryString as getQueryStringAsObject, parseQueryString, parseQueryString as queryStringToObject, isCustomFile, isCustomFileArray, isFileArray, isFileList, isFileOrBlob, isFileUpload, isOriginFileObj, isValidFormData, parseQueryStringLiteral as literalQueryStringToObject, parseQueryStringLiteral, parseFormData, removeFromLocalStorage, removeFromSessionStorage, saveToLocalStorage, saveToSessionStorage, serializeForm, smoothScrollTo, toggleFullScreen, updateQueryParam };

package/dist/dom.d.mts

@@ -0,0 +1,228 @@
+/**
+ * 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.
+ */
+
+import { A as ParsedQuery, G as Deserializer, M as QueryObject, ct as Serializer, j as ParsedQueryGeneric, y as GenericObject } from "./object-B0TV3eHx.mjs";
+import { P as QueryString } from "./string-CBAbxaG1.mjs";
+import { a as OriginFileObj, i as FormDataConfigs, o as ParsedFormData, r as FileUpload, s as SerializedForm, t as CustomFile } from "./form-BMFVGUrN.mjs";
+
+//#region src/dom/query.d.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"
+ */
+declare function generateQueryParams<T extends QueryObject>(params?: T): QueryString;
+/**
+ * * 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>`.
+ */
+declare function getQueryParams<QParams extends Record<string, string>>(): QParams;
+/**
+ * * 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.
+ */
+declare function updateQueryParam(key: string, value: string): void;
+/**
+ * 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.
+ */
+declare function parseQueryString<QParams extends ParsedQueryGeneric>(query: string, parsePrimitives?: boolean): QParams;
+/**
+ * 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.
+ */
+declare function parseQueryStringLiteral<Q extends string>(query: Q): ParsedQuery<Q>;
+//#endregion
+//#region src/dom/storage.d.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.
+ */
+declare function getFromLocalStorage<T>(key: string, deserialize?: Deserializer<T>): T | 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`.
+ */
+declare function saveToLocalStorage<T>(key: string, value: T, serialize?: Serializer<T>): void;
+/**
+ * * Remove item from local storage.
+ *
+ * @param key - Key to delete item from local storage.
+ */
+declare function removeFromLocalStorage(key: string): void;
+/**
+ * * 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.
+ */
+declare function getFromSessionStorage<T>(key: string, deserialize?: Deserializer<T>): T | 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`.
+ */
+declare function saveToSessionStorage<T>(key: string, value: T, serialize?: Serializer<T>): void;
+/**
+ * * Remove item from session storage.
+ *
+ * @param key - Key to delete item from session storage.
+ */
+declare function removeFromSessionStorage(key: string): void;
+//#endregion
+//#region src/dom/utils.d.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).
+ */
+declare function smoothScrollTo(element: HTMLElement, offset?: number): void;
+/**
+ * * 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).
+ */
+declare function toggleFullScreen(element?: HTMLElement): void;
+/**
+ * * 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.
+ */
+declare function copyToClipboard(text: string): Promise<void>;
+//#endregion
+//#region src/form/convert.d.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.
+ */
+declare const createControlledFormData: <T extends GenericObject>(data: T, configs?: FormDataConfigs<T>) => FormData;
+//#endregion
+//#region src/form/guards.d.ts
+/**
+ * * Checks if a given value is a valid `FormData` & it's not empty.
+ * - **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 value - The value to check.
+ * @returns `true` if the value is a valid `FormData` and not empty, otherwise `false`.
+ */
+declare function isValidFormData(value: unknown): value is FormData;
+/**
+ * * Checks if a given value is an `OriginFileObj`.
+ * - **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 value - The value to check.
+ * @returns `true` if the value is a valid `OriginFileObj`, otherwise `false`.
+ */
+declare function isOriginFileObj(value: unknown): value is OriginFileObj;
+/**
+ * * Checks if a given value is a `CustomFile`.
+ * - **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 value - The value to check.
+ * @returns `true` if the value is a valid `CustomFile`, otherwise `false`.
+ */
+declare function isCustomFile(value: unknown): value is CustomFile;
+/**
+ * * Checks if a given value is an array of `CustomFile` objects.
+ * - **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 value - The value to check.
+ * @returns `true` if the value is a valid `CustomFile[]`, otherwise `false`.
+ */
+declare function isCustomFileArray(value: unknown): value is CustomFile[];
+/**
+ * * Checks if a given value is an array of `File/Blob` objects.
+ * - **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 value - The value to check.
+ * @returns `true` if the value is a valid `File[]` or `Blob[]`, otherwise `false`.
+ */
+declare function isFileArray(value: unknown): value is File[] | Blob[];
+/**
+ * * Checks if a given value is an instance of `FileList`.
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid `FileList`, otherwise `false`.
+ */
+declare function isFileList(value: unknown): value is FileList;
+/**
+ * * Checks if a given value is an instance of `File` or `Blob`.
+ * @param value - The value to check.
+ * @returns `true` if the value is an instance of `File` or `Blob`, otherwise `false`.
+ */
+declare function isFileOrBlob(value: unknown): value is File | Blob;
+/**
+ * * Checks if a given value is a `FileUpload` object.
+ * @param value - The value to check.
+ * @returns `true` if the value is a valid `FileUpload`, otherwise `false`.
+ */
+declare function isFileUpload(value: unknown): value is FileUpload;
+//#endregion
+//#region src/form/transform.d.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.
+ */
+declare function serializeForm<T extends boolean = false>(form: HTMLFormElement, toQueryString?: T): SerializedForm<T>;
+/**
+ * * 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.
+ */
+declare function parseFormData<T extends FormData | string>(data: T, parsePrimitives?: boolean): ParsedFormData<T>;
+//#endregion
+export { createControlledFormData as convertIntoFormData, createControlledFormData, createControlledFormData as createFormData, copyToClipboard, generateQueryParams as createQueryParams, generateQueryParams as formatQueryParams, generateQueryParams, getFromLocalStorage, getFromSessionStorage, getQueryParams, parseQueryString as getQueryStringAsObject, parseQueryString, parseQueryString as queryStringToObject, isCustomFile, isCustomFileArray, isFileArray, isFileList, isFileOrBlob, isFileUpload, isOriginFileObj, isValidFormData, parseQueryStringLiteral as literalQueryStringToObject, parseQueryStringLiteral, parseFormData, removeFromLocalStorage, removeFromSessionStorage, saveToLocalStorage, saveToSessionStorage, serializeForm, smoothScrollTo, toggleFullScreen, updateQueryParam };