npm - @rzl-zone/utils-js - Versions diffs - 3.12.1-beta.0 → 3.12.1-beta.1 - Mend

@rzl-zone/utils-js 3.12.1-beta.0 → 3.12.1-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (239) hide show

package/dist/events/index.d.cts CHANGED Viewed

@@ -2,173 +2,175 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.12.1-beta.0`
+*  Version: `3.12.1-beta.1`
 *  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/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;
- * }
- * ```
- */
+* * ***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;
- * }
- * ```
- */
+* * ***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
- */
+* * ***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`}.*** */
+/**
+* ***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"
-   */
+  * * ***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
-   */
+  * * ***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
- */
+* * ***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 };