{"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,CAAC,CAAC,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"}