/*!
* ========================================================================
*  @rzl-zone/utils-js
* ------------------------------------------------------------------------
*  Version: `3.15.0`
*  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.
*
* ---
* @default
* ```ts
* "on_processing"
* ```
*
* ---
* @param {string} [className="on_processing"] - The CSS class to add, defaults to `"on_processing"`.
*
* ---
* @throws **{@link TypeError | `TypeError`}** if `className` is not a string.
*
* ---
* @returns {void} Does not return anything (void).
*
* ---
* @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.
*
* ---
* @default
* ```ts
* "on_processing"
* ```
*
* ---
* @param {string} [className="on_processing"] - The CSS class to remove, defaults to `"on_processing"`.
*
* ---
* @throws **{@link TypeError | `TypeError`}** if `className` is not a string.
*
* ---
* @returns {void} Does not return anything (void).
*
* ---
* @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
* ```ts
* removeElementFocus();
* // ➔ Removes focus from the currently active element
* ```
*/
declare const removeElementFocus: () => void;
/**
* ***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
*
* 1. #### Default behavior:
*    ```ts
*    scrollToTop();
*    // ➔ Scroll smoothly to the top after 1ms delay
*    ```
*    ---
* 2. #### Instant scroll:
*    ```ts
*    scrollToTop({
*      behavior: "instant"
*    });
*    // ➔ Jump instantly to the top
*    ```
*    ---
* 3. #### Custom timeout:
*    ```ts
*    scrollToTop({
*      timeout: 500
*    });
*    // ➔ Scroll smoothly to the top after 500ms
*    ```
*    ---
* 4. #### Invalid options with fallback values:
*    ```ts
*    scrollToTop({
*      behavior: "fly",
*      timeout: -100
*    });
*    // ➔ Fallback: behavior="smooth", timeout=1
*    ```
*    ---
* 5. #### Invalid behavior with decimal timeout:
*    ```ts
*    scrollToTop({
*      behavior: "fly",
*      timeout: 123.55
*    });
*    // ➔ Fallback: behavior="smooth", timeout=123
*    ```
*/
declare const scrollToTop: (options?: ScrollToTopOptions) => void;
export { disableUserInteraction, enableUserInteraction, removeElementFocus, scrollToTop };