@rzl-zone/utils-js
Version:
A modern, lightweight set of JavaScript utility functions with TypeScript support for everyday development, crafted to enhance code readability and maintainability.
179 lines (174 loc) • 7.78 kB
TypeScript
/*!
* ====================================================
* Rzl Utils-JS.
* ----------------------------------------------------
* Version: 3.11.0.
* Author: Rizalvin Dwiky.
* Repository: https://github.com/rzl-zone/utils-js.
* ====================================================
*/
/** ----------------------------------------------------------
* * ***Utility: `disableUserInteraction`.***
* ----------------------------------------------------------
* **Disables user interaction by adding a CSS class to the `<html>` element.**
* - **Key points**:
* - Works **only in browser environments**.
* - Safely adds the specified CSS class to `<html>`.
* - Prevents multiple additions of the same class.
* - Useful to indicate that a process is ongoing
* (e.g., loading or processing state).
* - **Using custom CSS classes:**
* - You can pass any class name that exists in your CSS.
* - Example: if you have `.loading` in your styles, passing `"loading"`
* will add it and disable interactions accordingly.
* - **Validation:**
* - Throws `TypeError` if the `className` parameter is not a string.
* @defaultValue `"on_processing"`
* @param {string} [className="on_processing"] - The CSS class to add, defaults to `"on_processing"`.
* @returns {void} Does not return anything (void).
* @throws **{@link TypeError | `TypeError`}** if `className` is not a string.
* @example
* * ***Example in your code:***
* ```ts
* disableUserInteraction(); // ➔ Adds "on_processing" class
* disableUserInteraction("loading"); // ➔ Adds "loading" class
* // ❌ Invalid value:
* disableUserInteraction(123); // ➔ Throws TypeError
* ```
* * ***Example in your css file (with defaultValue `className` props [on_processing]):***
* ```css
* .on_processing {
* cursor: wait;
* touch-action: none;
* user-select: none;
* }
*
* .on_processing > * {
* pointer-events: none;
* touch-action: none;
* user-select: none;
* }
* ```
*/
declare const disableUserInteraction: (className?: string) => void;
/** ----------------------------------------------------------
* * ***Utility: `enableUserInteraction`.***
* ----------------------------------------------------------
* **Enables user interaction by removing a CSS class from the `<html>` element.**
* - **Key points**:
* - Works **only in browser environments**.
* - Safely removes the specified CSS class from `<html>`.
* - Does nothing if the class is not present.
* - Useful to re-enable user interactions after a process
* (e.g., loading or processing) completes.
* - **Using custom CSS classes:**
* - You can pass any class name that exists in your CSS.
* - Example: if you have `.loading` in your styles, passing `"loading"`
* will remove it and re-enable interactions.
* - **Validation:**
* - Throws `TypeError` if the `className` parameter is not a string.
* @defaultValue `"on_processing"`
* @param {string} [className="on_processing"] - The CSS class to remove, defaults to `"on_processing"`.
* @returns {void} Does not return anything (void).
* @throws **{@link TypeError | `TypeError`}** if `className` is not a string.
* @example
* * ***Example in your code:***
* ```ts
* enableUserInteraction(); // ➔ Removes "on_processing" class
* enableUserInteraction("loading"); // ➔ Removes "loading" class
* // ❌ Invalid value:
* enableUserInteraction(123); // ➔ Throws TypeError
* ```
* * ***Example in your css file (with defaultValue `className` props [on_processing]):***
* ```css
* .on_processing {
* cursor: wait;
* touch-action: none;
* user-select: none;
* }
*
* .on_processing > * {
* pointer-events: none;
* touch-action: none;
* user-select: none;
* }
* ```
*/
declare const enableUserInteraction: (className?: string) => void;
/** ----------------------------------------------------------
* * ***Utility: `removeElementFocus`.***
* ----------------------------------------------------------
* **Removes focus from the currently active element in the document.**
* - **Features**:
* - This function works **only in browser environments** ***(safely no-ops in server environments)***.
* - If an element is focused, it will lose focus by calling `HTMLElement.blur()`.
* - If no element is focused or the active element is not an `HTMLElement`, nothing happens.
* @returns {void} Does not return anything (void).
* @example
* removeElementFocus(); // ➔ Removes focus from the currently active element
*/
declare const removeElementFocus: () => void;
/** @private ***Types options for {@link scrollToTop | `scrollToTop`}.*** */
type ScrollToTopOptions = {
/** ----------------------------------------------------------
* * ***Scroll animation type.***
* ----------------------------------------------------------
* - ***Behavior:***
* - Valid values: `"auto"`, `"instant"`, `"smooth"`.
* - Default force to `"smooth"` if missing or invalid.
*
* @default "smooth"
*/
behavior?: ScrollBehavior | undefined;
/** ----------------------------------------------------------
* * ***Delay before scrolling (in milliseconds).***
* ----------------------------------------------------------
* - ***Behavior:***
* - Default value is `1`.
* - Valid values: any number `≥` `1`.
* - Non-integer number are truncated to an integer.
* - Force to `2147483647` if number is larger than `2147483647`.
* - Default force to `1` if `missing`, `NaN`, `invalid-type`, or `less-than` `1`.
*
* @default 1
*/
timeout?: number | undefined;
};
/** ----------------------------------------------------------
* * ***Utility: `scrollToTop`.***
* ----------------------------------------------------------
* **Scrolls the page to the top with optional smooth animation and delay.**
* - **Features**:
* - This function works **only in browser environments** (no effect on server-side).
* - It leverages the native `window.scrollTo()` API with support for smooth scrolling
* and an optional timeout delay before executing the scroll.
* - Each option has strict valid values.
* - If an invalid value is provided, the function **automatically falls back to its default**.
* @param {ScrollToTopOptions} [options] - Optional settings for scroll behavior.
* @param {ScrollToTopOptions["behavior"]} [options.behavior="smooth"] - Scroll animation type.
* - Valid values: `"auto"`, `"instant"`, `"smooth"`.
* - Default force to `"smooth"` if missing or invalid.
* @param {ScrollToTopOptions["timeout"]} [options.timeout=1] - Delay before scrolling (in milliseconds).
* - Default value is `1`.
* - Valid values: any number `≥` `1`.
* - Non-integer number are truncated to an integer.
* - Force to `2147483647` if number is larger than `2147483647`.
* - Default force to `1` if `missing`, `NaN`, `invalid`, or `less-than` `1`.
* @returns {void} Does not return anything, only scrolling to top (void).
* @example
* // ✅ Valid options value:
* scrollToTop();
* // ➔ Scroll smoothly to the top after 1ms delay
* scrollToTop({ behavior: "instant" });
* // ➔ Jump instantly to the top
* scrollToTop({ timeout: 500 });
* // ➔ Scroll smoothly to the top after 500ms
*
* // ❌ Invalid options value:
* scrollToTop({ behavior: "fly", timeout: -100 });
* // ➔ Fallback: behavior="smooth", timeout=1
* scrollToTop({ behavior: "fly", timeout: 123.55 });
* // ➔ Fallback: behavior="smooth", timeout=123
*/
declare const scrollToTop: (options?: ScrollToTopOptions) => void;
export { disableUserInteraction, enableUserInteraction, removeElementFocus, scrollToTop };