@rzl-zone/utils-js 3.13.1 → 3.14.0-beta.0

package/dist/events/index.cjs

@@ -2,20 +2,21 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.13.1`
+*  Version: `3.14.0-beta.0`
 *  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
 *  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
 * ========================================================================
 */
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_assertIsBoolean = require('../assertIsBoolean-D41HrTB_.cjs');
-const require_assertIsString = require('../assertIsString-DUrVt82d.cjs');
-const require_isServer = require('../isServer-DmycqWsF.cjs');
+const require_logger = require('../logger-CUacYy3D.cjs');
+const require_isNumber = require('../isNumber-BkzwAe50.cjs');
+const require_assertIsString = require('../assertIsString-CjE9kbQ_.cjs');
+const require_isServer = require('../isServer-DhFaedeT.cjs');
 const disableUserInteraction = (className = "on_processing") => {
 	if (require_isServer.isServer()) return;
 	require_assertIsString.assertIsString(className, { message({ validType, currentType }) {
-		return `First parameter \`className\` must be of type \`${validType}\`, but received: \`${currentType}\`.`;
+		return require_logger.createMessage("disableUserInteraction", `First parameter \`className\` must be of type \`${validType}\`, but received: \`${currentType}\`.`);
 	} });
 	const { documentElement } = document;
 	if (documentElement && !documentElement.classList.contains(className)) documentElement.classList.add(className);
@@ -23,7 +24,7 @@ const disableUserInteraction = (className = "on_processing") => {
 const enableUserInteraction = (className = "on_processing") => {
 	if (require_isServer.isServer()) return;
 	require_assertIsString.assertIsString(className, { message({ validType, currentType }) {
-		return `First parameter \`className\` must be of type \`${validType}\`, but received: \`${currentType}\`.`;
+		return require_logger.createMessage("enableUserInteraction", `First parameter \`className\` must be of type \`${validType}\`, but received: \`${currentType}\`.`);
 	} });
 	const { documentElement } = document;
 	if (documentElement && documentElement.classList.contains(className)) documentElement.classList.remove(className);
@@ -35,13 +36,13 @@ const removeElementFocus = () => {
 };
 const scrollToTop = (options) => {
 	if (require_isServer.isServer()) return;
-	if (!require_assertIsBoolean.isPlainObject(options)) options = {};
-	const behavior = require_assertIsBoolean.hasOwnProp(options, "behavior") && require_assertIsBoolean.isNonEmptyString(options.behavior) && [
+	if (!require_logger.isPlainObject(options)) options = {};
+	const behavior = options.behavior && require_logger.isNonEmptyString(options.behavior) && [
 		"auto",
 		"instant",
 		"smooth"
 	].includes(options.behavior) ? options.behavior : "smooth";
-	let timeout = require_assertIsBoolean.hasOwnProp(options, "timeout") && require_assertIsBoolean.isNumber(options.timeout) && options.timeout >= 1 ? options.timeout : 1;
+	let timeout = options.timeout && require_isNumber.isNumber(options.timeout) && options.timeout >= 1 ? options.timeout : 1;
 	timeout = timeout > 2147483647 ? 2147483647 : timeout;
 	setTimeout(() => window.scrollTo({
 		top: 0,

package/dist/events/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["isServer","isServer","isServer","isServer","isPlainObject","hasOwnProp","isNonEmptyString","isNumber"],"sources":["../../src/events/actions/disableUserInteraction.ts","../../src/events/actions/enableUserInteraction.ts","../../src/events/actions/removeElementFocus.ts","../../src/events/actions/scrollToTop.ts"],"sourcesContent":["import { isServer } from \"@/predicates/is/isServer\";\nimport { assertIsString } from \"@/assertions/strings/assertIsString\";\n\n/** ----------------------------------------------------------\n * * ***Utility: `disableUserInteraction`.***\n * ----------------------------------------------------------\n * **Disables user interaction by adding a CSS class to the `<html>` element.**\n * - **Key points**:\n *    - Works **only in browser environments**.\n *    - Safely adds the specified CSS class to `<html>`.\n *    - Prevents multiple additions of the same class.\n *    - Useful to indicate that a process is ongoing\n *   (e.g., loading or processing state).\n * - **Using custom CSS classes:**\n *    - You can pass any class name that exists in your CSS.\n *    - Example: if you have `.loading` in your styles, passing `\"loading\"`\n *   will add it and disable interactions accordingly.\n * - **Validation:**\n *    - Throws `TypeError` if the `className` parameter is not a string.\n * @defaultValue `\"on_processing\"`\n * @param {string} [className=\"on_processing\"] - The CSS class to add, defaults to `\"on_processing\"`.\n * @returns {void} Does not return anything (void).\n * @throws **{@link TypeError | `TypeError`}** if `className` is not a string.\n * @example\n * * ***Example in your code:***\n * ```ts\n * disableUserInteraction();          // ➔ Adds \"on_processing\" class\n * disableUserInteraction(\"loading\"); // ➔ Adds \"loading\" class\n * // ❌ Invalid value:\n * disableUserInteraction(123);       // ➔ Throws TypeError\n * ```\n * * ***Example in your css file (with defaultValue `className` props [on_processing]):***\n * ```css\n * .on_processing {\n *   cursor: wait;\n *   touch-action: none;\n *   user-select: none;\n * }\n *\n * .on_processing > * {\n *   pointer-events: none;\n *   touch-action: none;\n *   user-select: none;\n * }\n * ```\n */\nexport const disableUserInteraction = (\n  className: string = \"on_processing\"\n): void => {\n  // Ensure function runs only in the browser\n  if (isServer()) return;\n\n  assertIsString(className, {\n    message({ validType, currentType }) {\n      return `First parameter \\`className\\` must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`;\n    }\n  });\n\n  const { documentElement } = document;\n\n  if (documentElement && !documentElement.classList.contains(className)) {\n    documentElement.classList.add(className);\n  }\n};\n","import { isServer } from \"@/predicates/is/isServer\";\nimport { assertIsString } from \"@/assertions/strings/assertIsString\";\n\n/** ----------------------------------------------------------\n * * ***Utility: `enableUserInteraction`.***\n * ----------------------------------------------------------\n * **Enables user interaction by removing a CSS class from the `<html>` element.**\n * - **Key points**:\n *    - Works **only in browser environments**.\n *    - Safely removes the specified CSS class from `<html>`.\n *    - Does nothing if the class is not present.\n *    - Useful to re-enable user interactions after a process\n *   (e.g., loading or processing) completes.\n * - **Using custom CSS classes:**\n *    - You can pass any class name that exists in your CSS.\n *    - Example: if you have `.loading` in your styles, passing `\"loading\"`\n *   will remove it and re-enable interactions.\n * - **Validation:**\n *    - Throws `TypeError` if the `className` parameter is not a string.\n * @defaultValue `\"on_processing\"`\n * @param {string} [className=\"on_processing\"] - The CSS class to remove, defaults to `\"on_processing\"`.\n * @returns {void} Does not return anything (void).\n * @throws **{@link TypeError | `TypeError`}** if `className` is not a string.\n * @example\n * * ***Example in your code:***\n * ```ts\n * enableUserInteraction();          // ➔ Removes \"on_processing\" class\n * enableUserInteraction(\"loading\"); // ➔ Removes \"loading\" class\n * // ❌ Invalid value:\n * enableUserInteraction(123);       // ➔ Throws TypeError\n * ```\n * * ***Example in your css file (with defaultValue `className` props [on_processing]):***\n * ```css\n * .on_processing {\n *   cursor: wait;\n *   touch-action: none;\n *   user-select: none;\n * }\n *\n * .on_processing > * {\n *   pointer-events: none;\n *   touch-action: none;\n *   user-select: none;\n * }\n * ```\n */\nexport const enableUserInteraction = (\n  className: string = \"on_processing\"\n): void => {\n  // Ensure function runs only in the browser\n  if (isServer()) return;\n\n  assertIsString(className, {\n    message({ validType, currentType }) {\n      return `First parameter \\`className\\` must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`;\n    }\n  });\n\n  const { documentElement } = document;\n\n  if (documentElement && documentElement.classList.contains(className)) {\n    documentElement.classList.remove(className);\n  }\n};\n","import { isServer } from \"@/predicates/is/isServer\";\n\n/** ----------------------------------------------------------\n * * ***Utility: `removeElementFocus`.***\n * ----------------------------------------------------------\n * **Removes focus from the currently active element in the document.**\n * - **Features**:\n *    - This function works **only in browser environments** ***(safely no-ops in server environments)***.\n *    - If an element is focused, it will lose focus by calling `HTMLElement.blur()`.\n *    - If no element is focused or the active element is not an `HTMLElement`, nothing happens.\n * @returns {void} Does not return anything (void).\n * @example\n * removeElementFocus(); // ➔ Removes focus from the currently active element\n */\nexport const removeElementFocus = (): void => {\n  // Ensure function runs only in the browser\n  if (isServer()) return;\n\n  const activeElement = document.activeElement;\n\n  if (activeElement instanceof HTMLElement) {\n    activeElement.blur();\n  } else {\n    // not-support, currently we nothing to do...\n    // console.warn(\"removeElementFocus: No active element to blur or unsupported element type.\");\n  }\n};\n","import { isNumber } from \"@/predicates/is/isNumber\";\nimport { hasOwnProp } from \"@/predicates/has/hasOwnProp\";\nimport { isServer } from \"@/predicates/is/isServer\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { isNonEmptyString } from \"@/predicates/is/isNonEmptyString\";\n\n/**\n * ***Types options for {@link scrollToTop | `scrollToTop`}.***\n */\ntype ScrollToTopOptions = {\n  /** ----------------------------------------------------------\n   * * ***Scroll animation type.***\n   * ----------------------------------------------------------\n   * - ***Behavior:***\n   *    - Valid values: `\"auto\"`, `\"instant\"`, `\"smooth\"`.\n   *    - Default force to `\"smooth\"` if missing or invalid.\n   *\n   * @default \"smooth\"\n   */\n  behavior?: ScrollBehavior | undefined;\n  /** ----------------------------------------------------------\n   * * ***Delay before scrolling (in milliseconds).***\n   * ----------------------------------------------------------\n   * - ***Behavior:***\n   *    - Default value is `1`.\n   *    - Valid values: any number `≥` `1`.\n   *    - Non-integer number are truncated to an integer.\n   *    - Force to `2147483647` if number is larger than `2147483647`.\n   *    - Default force to `1` if `missing`, `NaN`, `invalid-type`, or `less-than` `1`.\n   *\n   * @default 1\n   */\n  timeout?: number | undefined;\n};\n\n/** ----------------------------------------------------------\n * * ***Utility: `scrollToTop`.***\n * ----------------------------------------------------------\n * **Scrolls the page to the top with optional smooth animation and delay.**\n * - **Features**:\n *    - This function works **only in browser environments** (no effect on server-side).\n *    - It leverages the native `window.scrollTo()` API with support for smooth scrolling\n * and an optional timeout delay before executing the scroll.\n * - Each option has strict valid values.\n *    - If an invalid value is provided, the function **automatically falls back to its default**.\n * @param {ScrollToTopOptions} [options] - Optional settings for scroll behavior.\n * @param {ScrollToTopOptions[\"behavior\"]} [options.behavior=\"smooth\"] - Scroll animation type.\n *   - Valid values: `\"auto\"`, `\"instant\"`, `\"smooth\"`.\n *   - Default force to `\"smooth\"` if missing or invalid.\n * @param {ScrollToTopOptions[\"timeout\"]} [options.timeout=1] - Delay before scrolling (in milliseconds).\n *   - Default value is `1`.\n *   - Valid values: any number `≥` `1`.\n *   - Non-integer number are truncated to an integer.\n *   - Force to `2147483647` if number is larger than `2147483647`.\n *   - Default force to `1` if `missing`, `NaN`, `invalid`, or `less-than` `1`.\n * @returns {void} Does not return anything, only scrolling to top (void).\n * @example\n * // ✅ Valid options value:\n * scrollToTop();\n * // ➔ Scroll smoothly to the top after 1ms delay\n * scrollToTop({ behavior: \"instant\" });\n * // ➔ Jump instantly to the top\n * scrollToTop({ timeout: 500 });\n * // ➔ Scroll smoothly to the top after 500ms\n *\n * // ❌ Invalid options value:\n * scrollToTop({ behavior: \"fly\", timeout: -100 });\n * // ➔ Fallback: behavior=\"smooth\", timeout=1\n * scrollToTop({ behavior: \"fly\", timeout: 123.55 });\n * // ➔ Fallback: behavior=\"smooth\", timeout=123\n */\nexport const scrollToTop = (options?: ScrollToTopOptions): void => {\n  // Ensure function runs only in the browser\n  if (isServer()) return;\n\n  // Ensure options is an object and Defensive options check\n  if (!isPlainObject(options)) {\n    options = {};\n  }\n\n  const behavior: ScrollBehavior =\n    hasOwnProp(options, \"behavior\") &&\n    isNonEmptyString(options.behavior) &&\n    [\"auto\", \"instant\", \"smooth\"].includes(options.behavior)\n      ? options.behavior\n      : \"smooth\";\n  let timeout =\n    hasOwnProp(options, \"timeout\") &&\n    isNumber(options.timeout) &&\n    options.timeout >= 1\n      ? options.timeout\n      : 1;\n\n  timeout = timeout > 2147483647 ? 2147483647 : timeout;\n\n  setTimeout(() => window.scrollTo({ top: 0, left: 0, behavior }), timeout);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,MAAa,0BACX,YAAoB,oBACX;CAET,IAAIA,0BAAS,GAAG;CAEhB,sCAAe,WAAW,EACxB,QAAQ,EAAE,WAAW,eAAe;EAClC,OAAO,mDAAmD,UAAU,sBAAsB,YAAY;CACxG,EACF,CAAC;CAED,MAAM,EAAE,oBAAoB;CAE5B,IAAI,mBAAmB,CAAC,gBAAgB,UAAU,SAAS,SAAS,GAClE,gBAAgB,UAAU,IAAI,SAAS;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACjBA,MAAa,yBACX,YAAoB,oBACX;CAET,IAAIC,0BAAS,GAAG;CAEhB,sCAAe,WAAW,EACxB,QAAQ,EAAE,WAAW,eAAe;EAClC,OAAO,mDAAmD,UAAU,sBAAsB,YAAY;CACxG,EACF,CAAC;CAED,MAAM,EAAE,oBAAoB;CAE5B,IAAI,mBAAmB,gBAAgB,UAAU,SAAS,SAAS,GACjE,gBAAgB,UAAU,OAAO,SAAS;AAE9C;;;;;;;;;;;;;;;;ACjDA,MAAa,2BAAiC;CAE5C,IAAIC,0BAAS,GAAG;CAEhB,MAAM,gBAAgB,SAAS;CAE/B,IAAI,yBAAyB,aAC3B,cAAc,KAAK;AAKvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC6CA,MAAa,eAAe,YAAuC;CAEjE,IAAIC,0BAAS,GAAG;CAGhB,IAAI,CAACC,sCAAc,OAAO,GACxB,UAAU,CAAC;CAGb,MAAM,WACJC,mCAAW,SAAS,UAAU,KAC9BC,yCAAiB,QAAQ,QAAQ,KACjC;EAAC;EAAQ;EAAW;CAAQ,EAAE,SAAS,QAAQ,QAAQ,IACnD,QAAQ,WACR;CACN,IAAI,UACFD,mCAAW,SAAS,SAAS,KAC7BE,iCAAS,QAAQ,OAAO,KACxB,QAAQ,WAAW,IACf,QAAQ,UACR;CAEN,UAAU,UAAU,aAAa,aAAa;CAE9C,iBAAiB,OAAO,SAAS;EAAE,KAAK;EAAG,MAAM;EAAG;CAAS,CAAC,GAAG,OAAO;AAC1E"}
+{"version":3,"file":"index.cjs","names":["isServer","createMessage","isServer","createMessage","isServer","isServer","isPlainObject","isNonEmptyString","isNumber"],"sources":["../../src/events/actions/disableUserInteraction.ts","../../src/events/actions/enableUserInteraction.ts","../../src/events/actions/removeElementFocus.ts","../../src/events/actions/scrollToTop.ts"],"sourcesContent":["import { createMessage } from \"@/_private/logger\";\n\nimport { isServer } from \"@/predicates/is/isServer\";\nimport { assertIsString } from \"@/assertions/strings/assertIsString\";\n\n/** ----------------------------------------------------------\n * * ***Utility: `disableUserInteraction`.***\n * -----------------------------------------------------------\n * **Disables user interaction by adding a CSS class to the `<html>` element.**\n *\n * ---\n * - **Key points**:\n *     - Works **only in browser environments**.\n *     - Safely adds the specified CSS class to `<html>`.\n *     - Prevents multiple additions of the same class.\n *     - Useful to indicate that a process is ongoing\n *       (e.g., loading or processing state).\n * - **Using custom CSS classes:**\n *     - You can pass any class name that exists in your CSS.\n *     - Example: if you have `.loading` in your styles, passing `\"loading\"`\n *       will add it and disable interactions accordingly.\n * - **Validation:**\n *     - Throws `TypeError` if the `className` parameter is not a string.\n *\n * ---\n * @default\n * ```ts\n * \"on_processing\"\n * ```\n *\n * ---\n * @param {string} [className=\"on_processing\"] - The CSS class to add, defaults to `\"on_processing\"`.\n *\n * ---\n * @throws **{@link TypeError | `TypeError`}** if `className` is not a string.\n *\n * ---\n * @returns {void} Does not return anything (void).\n *\n * ---\n * @example\n * - ***Example in your code:***\n *      ```ts\n *      disableUserInteraction();\n *      // ➔ Adds \"on_processing\" class\n *      disableUserInteraction(\"loading\");\n *      // ➔ Adds \"loading\" class\n *\n *      // ❌ Invalid value:\n *      disableUserInteraction(123);\n *      // ➔ Throws TypeError\n *      ```\n * - ***Example in your css file (with defaultValue `className` props [on_processing]):***\n *      ```css\n *      .on_processing {\n *        cursor: wait;\n *        touch-action: none;\n *        user-select: none;\n *      }\n *\n *      .on_processing > * {\n *        pointer-events: none;\n *        touch-action: none;\n *        user-select: none;\n *      }\n *      ```\n */\nexport const disableUserInteraction = (\n  className: string = \"on_processing\"\n): void => {\n  // Ensure function runs only in the browser\n  if (isServer()) return;\n\n  assertIsString(className, {\n    message({ validType, currentType }) {\n      return createMessage(\n        \"disableUserInteraction\",\n        `First parameter \\`className\\` must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`\n      );\n    }\n  });\n\n  const { documentElement } = document;\n\n  if (documentElement && !documentElement.classList.contains(className)) {\n    documentElement.classList.add(className);\n  }\n};\n","import { createMessage } from \"@/_private/logger\";\n\nimport { isServer } from \"@/predicates/is/isServer\";\nimport { assertIsString } from \"@/assertions/strings/assertIsString\";\n\n/** ----------------------------------------------------------\n * * ***Utility: `enableUserInteraction`.***\n * -----------------------------------------------------------\n * **Enables user interaction by removing a CSS class from the `<html>` element.**\n *\n * ---\n * - **Key points**:\n *     - Works **only in browser environments**.\n *     - Safely removes the specified CSS class from `<html>`.\n *     - Does nothing if the class is not present.\n *     - Useful to re-enable user interactions after a process\n *       (e.g., loading or processing) completes.\n * - **Using custom CSS classes:**\n *     - You can pass any class name that exists in your CSS.\n *     - Example: if you have `.loading` in your styles, passing `\"loading\"`\n *       will remove it and re-enable interactions.\n * - **Validation:**\n *     - Throws `TypeError` if the `className` parameter is not a string.\n *\n * ---\n * @default\n * ```ts\n * \"on_processing\"\n * ```\n *\n * ---\n * @param {string} [className=\"on_processing\"] - The CSS class to remove, defaults to `\"on_processing\"`.\n *\n * ---\n * @throws **{@link TypeError | `TypeError`}** if `className` is not a string.\n *\n * ---\n * @returns {void} Does not return anything (void).\n *\n * ---\n * @example\n * - ***Example in your code:***\n *      ```ts\n *      enableUserInteraction();\n *      // ➔ Removes \"on_processing\" class\n *      enableUserInteraction(\"loading\");\n *      // ➔ Removes \"loading\" class\n *\n *      // ❌ Invalid value:\n *      enableUserInteraction(123);\n *      // ➔ Throws TypeError\n *      ```\n *\n * - ***Example in your css file (with defaultValue `className` props [on_processing]):***\n *      ```css\n *      .on_processing {\n *        cursor: wait;\n *        touch-action: none;\n *        user-select: none;\n *      }\n *\n *      .on_processing > * {\n *        pointer-events: none;\n *        touch-action: none;\n *        user-select: none;\n *      }\n *      ```\n */\nexport const enableUserInteraction = (\n  className: string = \"on_processing\"\n): void => {\n  // Ensure function runs only in the browser\n  if (isServer()) return;\n\n  assertIsString(className, {\n    message({ validType, currentType }) {\n      return createMessage(\n        \"enableUserInteraction\",\n        `First parameter \\`className\\` must be of type \\`${validType}\\`, but received: \\`${currentType}\\`.`\n      );\n    }\n  });\n\n  const { documentElement } = document;\n\n  if (documentElement && documentElement.classList.contains(className)) {\n    documentElement.classList.remove(className);\n  }\n};\n","import { isServer } from \"@/predicates/is/isServer\";\n\n/** ----------------------------------------------------------\n * * ***Utility: `removeElementFocus`.***\n * -----------------------------------------------------------\n * **Removes focus from the currently active element in the document.**\n *\n * ---\n * - **Features**:\n *     - This function works **only in browser environments** ***(safely no-ops in server environments)***.\n *     - If an element is focused, it will lose focus by calling `HTMLElement.blur()`.\n *     - If no element is focused or the active element is not an `HTMLElement`, nothing happens.\n *\n * ---\n * @returns {void} Does not return anything (void).\n *\n * ---\n * @example\n * ```ts\n * removeElementFocus();\n * // ➔ Removes focus from the currently active element\n * ```\n */\nexport const removeElementFocus = (): void => {\n  // Ensure function runs only in the browser\n  if (isServer()) return;\n\n  const activeElement = document.activeElement;\n\n  if (activeElement instanceof HTMLElement) {\n    activeElement.blur();\n  } else {\n    // not-support, currently we nothing to do...\n    // console.warn(\"removeElementFocus: No active element to blur or unsupported element type.\");\n  }\n};\n","import { isNumber } from \"@/predicates/is/isNumber\";\nimport { isServer } from \"@/predicates/is/isServer\";\nimport { isPlainObject } from \"@/predicates/is/isPlainObject\";\nimport { isNonEmptyString } from \"@/predicates/is/isNonEmptyString\";\n\n/**\n * ***Types options for {@link scrollToTop | `scrollToTop`}.***\n */\ntype ScrollToTopOptions = {\n  /** ----------------------------------------------------------\n   * * ***Scroll animation type.***\n   * -----------------------------------------------------------\n   * - ***Behavior:***\n   *      - Valid values: `\"auto\"`, `\"instant\"`, `\"smooth\"`.\n   *      - Default force to `\"smooth\"` if missing or invalid.\n   *\n   * ---\n   * @default \"smooth\"\n   */\n  behavior?: ScrollBehavior | undefined;\n\n  /** ----------------------------------------------------------\n   * * ***Delay before scrolling (in milliseconds).***\n   * -----------------------------------------------------------\n   * - ***Behavior:***\n   *      - Default value is `1`.\n   *      - Valid values: any number `≥` `1`.\n   *      - Non-integer number are truncated to an integer.\n   *      - Force to `2147483647` if number is larger than `2147483647`.\n   *      - Default force to `1` if `missing`, `NaN`, `invalid-type`, or `less-than` `1`.\n   *\n   * ---\n   * @default 1\n   */\n  timeout?: number | undefined;\n};\n\n/** ----------------------------------------------------------\n * * ***Utility: `scrollToTop`.***\n * -----------------------------------------------------------\n * **Scrolls the page to the top with optional smooth animation and delay.**\n *\n * ---\n * - **Features**:\n *     - This function works **only in browser environments** (no effect on server-side).\n *     - It leverages the native `window.scrollTo()` API with support for smooth scrolling\n *       and an optional timeout delay before executing the scroll.\n *     - Each option has strict valid values:\n *         - If an invalid value is provided, the function **automatically falls back to its default**.\n *\n * ---\n * @param {ScrollToTopOptions} [options] - Optional settings for scroll behavior.\n * @param {ScrollToTopOptions[\"behavior\"]} [options.behavior=\"smooth\"] - Scroll animation type.\n *   - Valid values: `\"auto\"`, `\"instant\"`, `\"smooth\"`.\n *   - Default force to `\"smooth\"` if missing or invalid.\n * @param {ScrollToTopOptions[\"timeout\"]} [options.timeout=1] - Delay before scrolling (in milliseconds).\n *   - Default value is `1`.\n *   - Valid values: any number `≥` `1`.\n *   - Non-integer number are truncated to an integer.\n *   - Force to `2147483647` if number is larger than `2147483647`.\n *   - Default force to `1` if `missing`, `NaN`, `invalid`, or `less-than` `1`.\n *\n * ---\n * @returns {void} Does not return anything, only scrolling to top (void).\n *\n * ---\n * @example\n *\n * 1. #### Default behavior:\n *    ```ts\n *    scrollToTop();\n *    // ➔ Scroll smoothly to the top after 1ms delay\n *    ```\n *    ---\n * 2. #### Instant scroll:\n *    ```ts\n *    scrollToTop({\n *      behavior: \"instant\"\n *    });\n *    // ➔ Jump instantly to the top\n *    ```\n *    ---\n * 3. #### Custom timeout:\n *    ```ts\n *    scrollToTop({\n *      timeout: 500\n *    });\n *    // ➔ Scroll smoothly to the top after 500ms\n *    ```\n *    ---\n * 4. #### Invalid options with fallback values:\n *    ```ts\n *    scrollToTop({\n *      behavior: \"fly\",\n *      timeout: -100\n *    });\n *    // ➔ Fallback: behavior=\"smooth\", timeout=1\n *    ```\n *    ---\n * 5. #### Invalid behavior with decimal timeout:\n *    ```ts\n *    scrollToTop({\n *      behavior: \"fly\",\n *      timeout: 123.55\n *    });\n *    // ➔ Fallback: behavior=\"smooth\", timeout=123\n *    ```\n */\nexport const scrollToTop = (options?: ScrollToTopOptions): void => {\n  // Ensure function runs only in the browser\n  if (isServer()) return;\n\n  // Ensure options is an object and Defensive options check\n  if (!isPlainObject(options)) options = {};\n\n  const behavior: ScrollBehavior =\n    options.behavior &&\n    isNonEmptyString(options.behavior) &&\n    [\"auto\", \"instant\", \"smooth\"].includes(options.behavior)\n      ? options.behavior\n      : \"smooth\";\n  let timeout =\n    options.timeout && isNumber(options.timeout) && options.timeout >= 1\n      ? options.timeout\n      : 1;\n\n  timeout = timeout > 2147483647 ? 2147483647 : timeout;\n\n  setTimeout(() => window.scrollTo({ top: 0, left: 0, behavior }), timeout);\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,MAAa,0BACX,YAAoB,oBACX;CAET,IAAIA,0BAAS,GAAG;CAEhB,sCAAe,WAAW,EACxB,QAAQ,EAAE,WAAW,eAAe;EAClC,OAAOC,6BACL,0BACA,mDAAmD,UAAU,sBAAsB,YAAY,IACjG;CACF,EACF,CAAC;CAED,MAAM,EAAE,oBAAoB;CAE5B,IAAI,mBAAmB,CAAC,gBAAgB,UAAU,SAAS,SAAS,GAClE,gBAAgB,UAAU,IAAI,SAAS;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACnBA,MAAa,yBACX,YAAoB,oBACX;CAET,IAAIC,0BAAS,GAAG;CAEhB,sCAAe,WAAW,EACxB,QAAQ,EAAE,WAAW,eAAe;EAClC,OAAOC,6BACL,yBACA,mDAAmD,UAAU,sBAAsB,YAAY,IACjG;CACF,EACF,CAAC;CAED,MAAM,EAAE,oBAAoB;CAE5B,IAAI,mBAAmB,gBAAgB,UAAU,SAAS,SAAS,GACjE,gBAAgB,UAAU,OAAO,SAAS;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;ACjEA,MAAa,2BAAiC;CAE5C,IAAIC,0BAAS,GAAG;CAEhB,MAAM,gBAAgB,SAAS;CAE/B,IAAI,yBAAyB,aAC3B,cAAc,KAAK;AAKvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACyEA,MAAa,eAAe,YAAuC;CAEjE,IAAIC,0BAAS,GAAG;CAGhB,IAAI,CAACC,6BAAc,OAAO,GAAG,UAAU,CAAC;CAExC,MAAM,WACJ,QAAQ,YACRC,gCAAiB,QAAQ,QAAQ,KACjC;EAAC;EAAQ;EAAW;CAAQ,EAAE,SAAS,QAAQ,QAAQ,IACnD,QAAQ,WACR;CACN,IAAI,UACF,QAAQ,WAAWC,0BAAS,QAAQ,OAAO,KAAK,QAAQ,WAAW,IAC/D,QAAQ,UACR;CAEN,UAAU,UAAU,aAAa,aAAa;CAE9C,iBAAiB,OAAO,SAAS;EAAE,KAAK;EAAG,MAAM;EAAG;CAAS,CAAC,GAAG,OAAO;AAC1E"}

package/dist/events/index.d.cts

@@ -2,110 +2,158 @@
 * ========================================================================
 *  @rzl-zone/utils-js
 * ------------------------------------------------------------------------
-*  Version: `3.13.1`
+*  Version: `3.14.0-beta.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).
+*     - 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.
+*     - 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"`
+*     - 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"`.
-* @returns {void} Does not return anything (void).
+*
+* ---
 * @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;
-* }
-* ```
+* - ***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.
+*     - 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.
+*     - 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"`
+*     - 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"`.
-* @returns {void} Does not return anything (void).
+*
+* ---
 * @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;
-* }
-* ```
+* - ***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.
+*     - 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
+* ```ts
+* removeElementFocus();
+* // ➔ Removes focus from the currently active element
+* ```
 */
 declare const removeElementFocus: () => void;
 /**
@@ -114,38 +162,44 @@ declare const removeElementFocus: () => void;
 type ScrollToTopOptions = {
   /** ----------------------------------------------------------
   * * ***Scroll animation type.***
-  * ----------------------------------------------------------
+  * -----------------------------------------------------------
   * - ***Behavior:***
-  *    - Valid values: `"auto"`, `"instant"`, `"smooth"`.
-  *    - Default force to `"smooth"` if missing or invalid.
+  *      - 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 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**.
+*     - 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"`.
@@ -156,21 +210,52 @@ type ScrollToTopOptions = {
 *   - 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
+*
+* 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 };