npm - tiny-essentials - Versions diffs - 1.13.1 → 1.14.0 - Mend

tiny-essentials 1.13.1 → 1.14.0

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 (32) hide show

package/dist/v1/TinyBasicsEs.js +256 -15
package/dist/v1/TinyBasicsEs.min.js +1 -1
package/dist/v1/TinyDragger.js +210 -15
package/dist/v1/TinyEssentials.js +496 -15
package/dist/v1/TinyEssentials.min.js +1 -1
package/dist/v1/TinyNotifications.js +408 -0
package/dist/v1/TinyNotifications.min.js +1 -0
package/dist/v1/TinyUploadClicker.js +211 -15
package/dist/v1/basics/html.cjs +213 -15
package/dist/v1/basics/html.d.mts +59 -5
package/dist/v1/basics/html.mjs +192 -13
package/dist/v1/basics/index.cjs +4 -0
package/dist/v1/basics/index.d.mts +5 -1
package/dist/v1/basics/index.mjs +3 -3
package/dist/v1/basics/text.cjs +43 -0
package/dist/v1/basics/text.d.mts +16 -0
package/dist/v1/basics/text.mjs +37 -0
package/dist/v1/build/TinyNotifications.cjs +7 -0
package/dist/v1/build/TinyNotifications.d.mts +3 -0
package/dist/v1/build/TinyNotifications.mjs +2 -0
package/dist/v1/index.cjs +6 -0
package/dist/v1/index.d.mts +6 -1
package/dist/v1/index.mjs +4 -3
package/dist/v1/libs/TinyNotifications.cjs +238 -0
package/dist/v1/libs/TinyNotifications.d.mts +106 -0
package/dist/v1/libs/TinyNotifications.mjs +211 -0
package/docs/v1/README.md +4 -3
package/docs/v1/basics/array.md +16 -43
package/docs/v1/basics/html.md +199 -33
package/docs/v1/basics/text.md +44 -14
package/docs/v1/libs/TinyNotifications.md +189 -0
package/package.json +1 -1

package/dist/v1/TinyNotifications.js ADDED Viewed

@@ -0,0 +1,408 @@
+/******/ (() => { // webpackBootstrap
+/******/ 	"use strict";
+/******/ 	// The require scope
+/******/ 	var __webpack_require__ = {};
+/******/
+/************************************************************************/
+/******/ 	/* webpack/runtime/define property getters */
+/******/ 	(() => {
+/******/ 		// define getter functions for harmony exports
+/******/ 		__webpack_require__.d = (exports, definition) => {
+/******/ 			for(var key in definition) {
+/******/ 				if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {
+/******/ 					Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });
+/******/ 				}
+/******/ 			}
+/******/ 		};
+/******/ 	})();
+/******/
+/******/ 	/* webpack/runtime/hasOwnProperty shorthand */
+/******/ 	(() => {
+/******/ 		__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))
+/******/ 	})();
+/******/
+/************************************************************************/
+var __webpack_exports__ = {};
+// EXPORTS
+__webpack_require__.d(__webpack_exports__, {
+  TinyNotifications: () => (/* reexport */ libs_TinyNotifications)
+});
+;// ./src/v1/basics/text.mjs
+/**
+ * Converts a string to title case where the first letter of each word is capitalized.
+ * All other letters are converted to lowercase.
+ *
+ * Example: "hello world" -> "Hello World"
+ *
+ * @param {string} str - The string to be converted to title case.
+ * @returns {string} The string converted to title case.
+ */
+function toTitleCase(str) {
+  return str.replace(/\w\S*/g, (txt) => txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase());
+}
+/**
+ * Converts a string to title case where the first letter of each word is capitalized,
+ * but the first letter of the entire string is left lowercase.
+ *
+ * Example: "hello world" -> "hello World"
+ *
+ * @param {string} str - The string to be converted to title case with the first letter in lowercase.
+ * @returns {string} The string converted to title case with the first letter in lowercase.
+ */
+function toTitleCaseLowerFirst(str) {
+  const titleCased = str.replace(
+    /\w\S*/g,
+    (txt) => txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase(),
+  );
+  return titleCased.charAt(0).toLowerCase() + titleCased.slice(1);
+}
+/**
+ * Enables a keyboard shortcut to toggle a CSS class on the document body.
+ *
+ * This function listens for a specific key combination: `Ctrl + Alt + [key]`.
+ * When triggered, it prevents the default behavior and toggles the
+ * `detect-made-by-ai` class on the `<body>`, which can be used to apply visual
+ * indicators or filters on AI-generated content.
+ *
+ * If executed outside of a browser environment (e.g., in Node.js), the function logs an error and exits.
+ * If the `<body>` is not available at the moment the shortcut is triggered, a warning is logged.
+ *
+ * @param {string} [key='a'] - The lowercase character key to be used in combination with Ctrl and Alt.
+ */
+function addAiMarkerShortcut(key = 'a') {
+  if (typeof HTMLElement === 'undefined') {
+    console.error(
+      '[AiMarkerShortcut] Environment does not support the DOM. This function must be run in a browser.',
+    );
+    return;
+  }
+  document.addEventListener('keydown', function (event) {
+    if (event.ctrlKey && event.altKey && event.key.toLowerCase() === key) {
+      event.preventDefault(); // Prevent any default behavior
+      if (!document.body) {
+        console.warn(
+          '[AiMarkerShortcut] <body> element not found. Cannot toggle class. Ensure the DOM is fully loaded when using the shortcut.',
+        );
+        return;
+      }
+      document.body.classList.toggle('detect-made-by-ai');
+    }
+  });
+}
+/**
+ * Trims a text string to a specified character limit, attempting to avoid cutting words in half.
+ * If a space is found before the limit and it's not too far from the limit (at least 60%),
+ * the cut is made at that space; otherwise, the text is hard-cut at the limit.
+ * If the input is shorter than the limit, it is returned unchanged.
+ *
+ * @param {string} text - The input text to be trimmed.
+ * @param {number} limit - The maximum number of characters allowed.
+ * @param {number} [safeCutZone=0.6] - A decimal between 0 and 1 representing the minimal acceptable position
+ *                                     (as a fraction of `limit`) to cut at a space. Defaults to 0.6.
+ * @returns {string} - The trimmed text, possibly ending with an ellipsis ("...").
+ * @throws {TypeError} - Throws if `text` is not a string.
+ * @throws {TypeError} - Throws if `limit` is not a positive integer.
+ * @throws {TypeError} - Throws if `safeCutZone` is not a number between 0 and 1 (inclusive).
+ */
+function safeTextTrim(text, limit, safeCutZone = 0.6) {
+  if (typeof text !== 'string')
+    throw new TypeError(`Expected a string for 'text', but received ${typeof text}`);
+  if (!Number.isInteger(limit) || limit <= 0)
+    throw new TypeError(`Expected 'limit' to be a positive integer, but received ${limit}`);
+  if (typeof safeCutZone !== 'number' || safeCutZone < 0 || safeCutZone > 1)
+    throw new TypeError(
+      `Expected 'safeCutZone' to be a number between 0 and 1, but received ${safeCutZone}`,
+    );
+  let result = text.trim();
+  if (result.length > limit) {
+    // Try to cut the string into a space before the limit
+    const safeCut = result.lastIndexOf(' ', limit);
+    if (safeCut > 0 && safeCut >= limit * safeCutZone) {
+      // Only cuts where there is a space, and if the cut is not too early
+      return `${result.substring(0, safeCut).trim()}...`;
+    } else {
+      // Emergency: Cuts straight to the limit and adds "...".
+      return `${result.substring(0, limit).trim()}...`;
+    }
+  }
+  return result;
+}
+/*
+import { useEffect } from "react";
+function KeyPressHandler() {
+    useEffect(() => {
+        const handleKeyDown = (event) => {
+            if (event.ctrlKey && event.altKey && event.key.toLowerCase() === "a") {
+                event.preventDefault();
+                document.body.classList.toggle("detect-made-by-ai");
+            }
+        };
+        document.addEventListener("keydown", handleKeyDown);
+        return () => {
+            document.removeEventListener("keydown", handleKeyDown);
+        };
+    }, []);
+    return null;
+}
+export default KeyPressHandler;
+*/
+;// ./src/v1/libs/TinyNotifications.mjs
+/**
+ * A utility class to manage browser notifications with sound and custom behavior.
+ * Useful for triggering system notifications with optional sound, avatar icon, body truncation, and click actions.
+ *
+ * @class
+ */
+class TinyNotifications {
+  /** @type {boolean} Whether notifications are currently allowed by the user. */
+  #allowed = false;
+  /** @type {boolean} Indicates whether the user has already requested permission at least once. */
+  #permissionRequested = false;
+  /** @type {HTMLAudioElement|null} Audio element to play when a notification is triggered. */
+  #audio = null;
+  /** @type {number} Maximum number of characters in the notification body. */
+  #bodyLimit = 100;
+  /** @type {string|null} Default avatar icon URL for notifications. */
+  #defaultIcon = null;
+  /** @type {(this: Notification, evt: Event) => any} Default handler when a notification is clicked. */
+  #defaultOnClick;
+  /**
+   * Constructs a new instance of TinyNotifications.
+   *
+   * @param {Object} [settings={}] - Optional settings to initialize the notification manager.
+   * @param {string|HTMLAudioElement|null} [settings.audio] - Path or URL to the audio file for notification sounds.
+   * @param {string|null} [settings.defaultIcon] - Default icon URL to be used in notifications.
+   * @param {number} [settings.bodyLimit=100] - Maximum number of characters allowed in the notification body.
+   * @param {(this: Notification, evt: Event) => any} [settings.defaultOnClick] - Default function to execute when a notification is clicked.
+   * @throws {TypeError} If any of the parameters are of an invalid type.
+   */
+  constructor({
+    audio = null,
+    defaultIcon = null,
+    bodyLimit = 100,
+    defaultOnClick = function (event) {
+      event.preventDefault();
+      if (window.focus) window.focus();
+      this.close();
+    },
+  } = {}) {
+    if (!(audio instanceof HTMLAudioElement) && typeof audio !== 'string' && audio !== null)
+      throw new TypeError('audio must be an instance of HTMLAudioElement or null.');
+    if (defaultIcon !== null && typeof defaultIcon !== 'string')
+      throw new TypeError('defaultIcon must be a string or null.');
+    if (!Number.isFinite(bodyLimit) || bodyLimit < 0)
+      throw new TypeError('bodyLimit must be a non-negative number.');
+    if (typeof defaultOnClick !== 'function')
+      throw new TypeError('defaultOnClick must be a function.');
+    this.#audio = typeof audio !== 'string' ? audio : new Audio(audio);
+    this.#defaultIcon = defaultIcon;
+    this.#bodyLimit = bodyLimit;
+    this.#defaultOnClick = defaultOnClick;
+  }
+  /**
+   * Requests permission from the user to show notifications.
+   * Updates the internal `#allowed` flag.
+   *
+   * @returns {Promise<boolean>} Resolves to `true` if permission is granted, otherwise `false`.
+   */
+  requestPerm() {
+    const tinyThis = this;
+    return new Promise((resolve, reject) => {
+      if (tinyThis.isCompatible()) {
+        if (Notification.permission === 'default') {
+          Notification.requestPermission()
+            .then((permission) => {
+              this.#permissionRequested = true;
+              tinyThis.#allowed = permission === 'granted';
+              resolve(tinyThis.#allowed);
+            })
+            .catch(reject);
+        } else {
+          this.#permissionRequested = true;
+          tinyThis.#allowed = Notification.permission === 'granted';
+          resolve(tinyThis.#allowed);
+        }
+      } else {
+        this.#permissionRequested = true;
+        tinyThis.#allowed = false;
+        resolve(false);
+      }
+    });
+  }
+  /**
+   * Checks if the Notification API is supported by the current browser.
+   *
+   * @returns {boolean} Returns `true` if notifications are supported, otherwise `false`.
+   */
+  isCompatible() {
+    return 'Notification' in window;
+  }
+  /**
+   * Sends a browser notification with the provided title and configuration.
+   * Truncates the body if necessary and plays a sound if configured.
+   *
+   * @param {string} title - The title of the notification.
+   * @param {NotificationOptions & { vibrate?: number[] }} [config={}] - Optional configuration for the notification.
+   * @returns {Notification|null} The created `Notification` instance, or `null` if permission is not granted.
+   * @throws {TypeError} If the title is not a string or config is not a valid object.
+   */
+  send(title, config = {}) {
+    if (!this.#permissionRequested)
+      throw new Error('You must call requestPerm() before sending a notification.');
+    if (typeof title !== 'string') throw new TypeError('title must be a string.');
+    if (typeof config !== 'object' || config === null)
+      throw new TypeError('config must be a non-null object.');
+    if (!this.#allowed) return null;
+    const { icon = this.#defaultIcon || undefined, vibrate = [200, 100, 200] } = config;
+    const options = { ...config };
+    if (typeof icon === 'string') options.icon = icon;
+    if (Array.isArray(vibrate)) options.vibrate = vibrate;
+    if (typeof options.body === 'string')
+      options.body = safeTextTrim(options.body, this.#bodyLimit);
+    const notification = new Notification(title, options);
+    notification.addEventListener('show', () => {
+      if (!(this.#audio instanceof HTMLAudioElement)) return;
+      this.#audio.currentTime = 0;
+      this.#audio.play().catch((err) => console.error(err));
+    });
+    if (typeof this.#defaultOnClick === 'function')
+      notification.addEventListener('click', this.#defaultOnClick);
+    return notification;
+  }
+  // === Getters and Setters ===
+  /**
+   * Whether the requestPerm() method was already called.
+   * @returns {boolean}
+   */
+  wasPermissionRequested() {
+    return this.#permissionRequested;
+  }
+  /**
+   * Returns the current permission status.
+   * @returns {boolean} `true` if permission was granted, otherwise `false`.
+   */
+  isAllowed() {
+    return this.#allowed;
+  }
+  /**
+   * Gets the current notification audio.
+   * @returns {HTMLAudioElement|null} The sound element, or `null` if not set.
+   */
+  getAudio() {
+    return this.#audio;
+  }
+  /**
+   * Sets the audio element used for notification sounds.
+   * @param {HTMLAudioElement|string|null} value - A valid `HTMLAudioElement` or `null` to disable sound.
+   * @throws {TypeError} If the value is not an `HTMLAudioElement` or `null`.
+   */
+  setAudio(value) {
+    if (!(value instanceof HTMLAudioElement) && typeof value !== 'string' && value !== null)
+      throw new TypeError('sound must be an instance of HTMLAudioElement or null.');
+    this.#audio = typeof value !== 'string' ? value : new Audio(value);
+  }
+  /**
+   * Gets the maximum length of the notification body text.
+   * @returns {number} Number of characters allowed.
+   */
+  getBodyLimit() {
+    return this.#bodyLimit;
+  }
+  /**
+   * Sets the maximum number of characters allowed in the notification body.
+   * @param {number} value - A non-negative integer.
+   * @throws {TypeError} If the value is not a valid non-negative number.
+   */
+  setBodyLimit(value) {
+    if (!Number.isFinite(value) || value < 0)
+      throw new TypeError('bodyLimit must be a non-negative number.');
+    this.#bodyLimit = value;
+  }
+  /**
+   * Gets the default avatar icon URL.
+   * @returns {string|null} The URL string or `null`.
+   */
+  getDefaultAvatar() {
+    return this.#defaultIcon;
+  }
+  /**
+   * Sets the default avatar icon URL.
+   * @param {string|null} value - A string URL or `null` to disable default icon.
+   * @throws {TypeError} If the value is not a string or `null`.
+   */
+  setDefaultAvatar(value) {
+    if (!(typeof value === 'string' || value === null))
+      throw new TypeError('defaultIcon must be a string or null.');
+    this.#defaultIcon = value;
+  }
+  /**
+   * Gets the default click event handler for notifications.
+   * @returns {(this: Notification, evt: Event) => any} The current click handler function.
+   */
+  getDefaultOnClick() {
+    return this.#defaultOnClick;
+  }
+  /**
+   * Sets the default click event handler for notifications.
+   * @param {(this: Notification, evt: Event) => any} value - A function to handle the notification click event.
+   * @throws {TypeError} If the value is not a function.
+   */
+  setDefaultOnClick(value) {
+    if (typeof value !== 'function') throw new TypeError('defaultOnClick must be a function.');
+    this.#defaultOnClick = value;
+  }
+}
+/* harmony default export */ const libs_TinyNotifications = (TinyNotifications);
+;// ./src/v1/build/TinyNotifications.mjs
+window.TinyNotifications = __webpack_exports__.TinyNotifications;
+/******/ })()
+;

package/dist/v1/TinyNotifications.min.js ADDED Viewed

@@ -0,0 +1 @@

+ (()=>{"use strict";var e={d:(t,i)=>{for(var n in i)e.o(i,n)&&!e.o(t,n)&&Object.defineProperty(t,n,{enumerable:!0,get:i[n]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t)},t={};e.d(t,{TinyNotifications:()=>i});const i=class{#e=!1;#t=!1;#i=null;#n=100;#o=null;#r;constructor({audio:e=null,defaultIcon:t=null,bodyLimit:i=100,defaultOnClick:n=function(e){e.preventDefault(),window.focus&&window.focus(),this.close()}}={}){if(!(e instanceof HTMLAudioElement)&&"string"!=typeof e&&null!==e)throw new TypeError("audio must be an instance of HTMLAudioElement or null.");if(null!==t&&"string"!=typeof t)throw new TypeError("defaultIcon must be a string or null.");if(!Number.isFinite(i)||i<0)throw new TypeError("bodyLimit must be a non-negative number.");if("function"!=typeof n)throw new TypeError("defaultOnClick must be a function.");this.#i="string"!=typeof e?e:new Audio(e),this.#o=t,this.#n=i,this.#r=n}requestPerm(){const e=this;return new Promise(((t,i)=>{e.isCompatible()?"default"===Notification.permission?Notification.requestPermission().then((i=>{this.#t=!0,e.#e="granted"===i,t(e.#e)})).catch(i):(this.#t=!0,e.#e="granted"===Notification.permission,t(e.#e)):(this.#t=!0,e.#e=!1,t(!1))}))}isCompatible(){return"Notification"in window}send(e,t={}){if(!this.#t)throw new Error("You must call requestPerm() before sending a notification.");if("string"!=typeof e)throw new TypeError("title must be a string.");if("object"!=typeof t||null===t)throw new TypeError("config must be a non-null object.");if(!this.#e)return null;const{icon:i=this.#o||void 0,vibrate:n=[200,100,200]}=t,o={...t};"string"==typeof i&&(o.icon=i),Array.isArray(n)&&(o.vibrate=n),"string"==typeof o.body&&(o.body=function(e,t,i=.6){if("string"!=typeof e)throw new TypeError("Expected a string for 'text', but received "+typeof e);if(!Number.isInteger(t)||t<=0)throw new TypeError(`Expected 'limit' to be a positive integer, but received ${t}`);if("number"!=typeof i||i<0||i>1)throw new TypeError(`Expected 'safeCutZone' to be a number between 0 and 1, but received ${i}`);let n=e.trim();if(n.length>t){const e=n.lastIndexOf(" ",t);return e>0&&e>=t*i?`${n.substring(0,e).trim()}...`:`${n.substring(0,t).trim()}...`}return n}(o.body,this.#n));const r=new Notification(e,o);return r.addEventListener("show",(()=>{this.#i instanceof HTMLAudioElement&&(this.#i.currentTime=0,this.#i.play().catch((e=>console.error(e))))})),"function"==typeof this.#r&&r.addEventListener("click",this.#r),r}wasPermissionRequested(){return this.#t}isAllowed(){return this.#e}getAudio(){return this.#i}setAudio(e){if(!(e instanceof HTMLAudioElement)&&"string"!=typeof e&&null!==e)throw new TypeError("sound must be an instance of HTMLAudioElement or null.");this.#i="string"!=typeof e?e:new Audio(e)}getBodyLimit(){return this.#n}setBodyLimit(e){if(!Number.isFinite(e)||e<0)throw new TypeError("bodyLimit must be a non-negative number.");this.#n=e}getDefaultAvatar(){return this.#o}setDefaultAvatar(e){if("string"!=typeof e&&null!==e)throw new TypeError("defaultIcon must be a string or null.");this.#o=e}getDefaultOnClick(){return this.#r}setDefaultOnClick(e){if("function"!=typeof e)throw new TypeError("defaultOnClick must be a function.");this.#r=e}};window.TinyNotifications=t.TinyNotifications})();

package/dist/v1/TinyUploadClicker.js CHANGED Viewed

@@ -3459,34 +3459,105 @@ function areHtmlElsColliding(elem1, elem2) {
 }
 /**
- * Reads and parses a JSON data using FileReader.
- * Throws an error if the content is not valid JSON.
- * @param {File} file
- * @returns {Promise<any>}
+ * Reads the contents of a file using the specified FileReader method.
+ *
+ * @param {File} file - The file to be read.
+ * @param {'readAsArrayBuffer'|'readAsDataURL'|'readAsText'|'readAsBinaryString'} method -
+ *   The FileReader method to use for reading the file.
+ * @returns {Promise<any>} - A promise that resolves with the file content, according to the chosen method.
+ * @throws {Error} - If an unexpected error occurs while handling the result.
+ * @throws {DOMException} - If the FileReader encounters an error while reading the file.
  */
-function readJsonBlob(file) {
+function readFileBlob(file, method) {
   return new Promise((resolve, reject) => {
     const reader = new FileReader();
     reader.onload = () => {
       try {
-        // @ts-ignore
-        const result = JSON.parse(reader.result);
-        resolve(result);
+        resolve(reader.result);
       } catch (error) {
-        // @ts-ignore
-        reject(new Error(`Invalid JSON in file: ${file.name}\n${error.message}`));
+        reject(error);
       }
     };
     reader.onerror = () => {
-      reject(new Error(`Error reading file: ${file.name}`));
+      reject(reader.error);
     };
+    reader[method](file);
+  });
+}
-    reader.readAsText(file);
+/**
+ * Reads a file as a Base64 string using FileReader, and optionally formats it as a full data URL.
+ *
+ * Performs strict validation to ensure the result is a valid Base64 string or a proper data URL.
+ *
+ * @param {File} file - The file to be read.
+ * @param {boolean|string} [isDataUrl=false] - If true, returns a full data URL; if false, returns only the Base64 string;
+ *   if a string is passed, it is used as the MIME type in the data URL.
+ * @returns {Promise<string>} - A promise that resolves with the Base64 string or data URL.
+ *
+ * @throws {TypeError} - If the result is not a string or if `isDataUrl` is not a valid type.
+ * @throws {Error} - If the result does not match the expected data URL format or Base64 structure.
+ * @throws {DOMException} - If the FileReader fails to read the file.
+ */
+function readBase64Blob(file, isDataUrl = false) {
+  return new Promise((resolve, reject) => {
+    if (typeof isDataUrl !== 'string' && typeof isDataUrl !== 'boolean')
+      reject(new TypeError('The isDataUrl parameter must be a boolean or a string.'));
+    readFileBlob(file, 'readAsDataURL')
+      .then(
+        /**
+         * Ensure that the URL format is correct in the required pattern
+         * @param {string} base64Data
+         */ (base64Data) => {
+          if (typeof base64Data !== 'string')
+            throw new TypeError('Expected file content to be a string.');
+          const match = base64Data.match(/^data:(.+);base64,(.*)$/);
+          if (!match || !match[2])
+            throw new Error('Invalid data URL format or missing Base64 content.');
+          const [, mimeType, base64] = match;
+          if (!/^[\w/+]+=*$/.test(base64)) throw new Error('Base64 content is malformed.');
+          if (typeof isDataUrl === 'boolean') return resolve(isDataUrl ? base64Data : base64);
+          if (!/^[\w-]+\/[\w.+-]+$/.test(isDataUrl))
+            throw new Error(`Invalid MIME type string: ${isDataUrl}`);
+          return resolve(`data:${isDataUrl};base64,${base64}`);
+        },
+      )
+      .catch(reject);
   });
 }
+/**
+ * Reads a file and strictly validates its content as proper JSON using FileReader.
+ *
+ * Performs several checks to ensure the file contains valid, parsable JSON data.
+ *
+ * @param {File} file - The file to be read. It must contain valid JSON as plain text.
+ * @returns {Promise<Record<string|number|symbol, any>|any[]>} - A promise that resolves with the parsed JSON object.
+ *
+ * @throws {SyntaxError} - If the file content is not valid JSON syntax.
+ * @throws {TypeError} - If the result is not a string or does not represent a JSON value.
+ * @throws {Error} - If the result is empty or structurally invalid as JSON.
+ * @throws {DOMException} - If the FileReader fails to read the file.
+ */
+function readJsonBlob(file) {
+  return new Promise((resolve, reject) =>
+    readFileBlob(file, 'readAsText')
+      .then((data) => {
+        if (typeof data !== 'string') throw new TypeError('Expected file content to be a string.');
+        const trimmed = data.trim();
+        if (trimmed.length === 0) throw new Error('File is empty or contains only whitespace.');
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed !== 'object' || parsed === null)
+          throw new Error('Parsed content is not a valid JSON object or array.');
+        resolve(parsed);
+      })
+      .catch(reject),
+  );
+}
 /**
  * Saves a JSON object as a downloadable file.
  * @param {string} filename
@@ -3589,7 +3660,8 @@ async function fetchJson(
       const data = await response.json();
-      if (!isJsonObject(data)) throw new Error('Received invalid data instead of valid JSON.');
+      if (!Array.isArray(data) && !isJsonObject(data))
+        throw new Error('Received invalid data instead of valid JSON.');
       return data;
     } catch (err) {
@@ -3689,6 +3761,129 @@ const getHtmlElPadding = (el) => {
   return { x, y, left, right, top, bottom };
 };
+/**
+ * Installs a script that toggles CSS classes on a given element
+ * based on the page's visibility or focus state, and optionally
+ * triggers callbacks on visibility changes.
+ *
+ * @param {Object} [settings={}]
+ * @param {HTMLElement} [settings.element=document.body] - The element to receive visibility classes.
+ * @param {string} [settings.hiddenClass='windowHidden'] - CSS class applied when the page is hidden.
+ * @param {string} [settings.visibleClass='windowVisible'] - CSS class applied when the page is visible.
+ * @param {() => void} [settings.onVisible] - Callback called when page becomes visible.
+ * @param {() => void} [settings.onHidden] - Callback called when page becomes hidden.
+ * @returns {() => void} Function that removes all installed event listeners.
+ * @throws {TypeError} If any provided setting is invalid.
+ */
+function installWindowHiddenScript({
+  element = document.body,
+  hiddenClass = 'windowHidden',
+  visibleClass = 'windowVisible',
+  onVisible,
+  onHidden,
+} = {}) {
+  if (!(element instanceof HTMLElement))
+    throw new TypeError(`"element" must be an instance of HTMLElement.`);
+  if (typeof hiddenClass !== 'string') throw new TypeError(`"hiddenClass" must be a string.`);
+  if (typeof visibleClass !== 'string') throw new TypeError(`"visibleClass" must be a string.`);
+  if (onVisible !== undefined && typeof onVisible !== 'function')
+    throw new TypeError(`"onVisible" must be a function if provided.`);
+  if (onHidden !== undefined && typeof onHidden !== 'function')
+    throw new TypeError(`"onHidden" must be a function if provided.`);
+  const removeClass = () => {
+    element.classList.remove(hiddenClass);
+    element.classList.remove(visibleClass);
+  };
+  /** @type {string|null} */
+  let hiddenProp = null;
+  const visibilityEvents = [
+    'visibilitychange',
+    'mozvisibilitychange',
+    'webkitvisibilitychange',
+    'msvisibilitychange',
+  ];
+  const visibilityProps = ['hidden', 'mozHidden', 'webkitHidden', 'msHidden'];
+  for (let i = 0; i < visibilityProps.length; i++) {
+    if (visibilityProps[i] in document) {
+      hiddenProp = visibilityProps[i];
+      break;
+    }
+  }
+  /** @type {(this: any, evt: Event) => void} */
+  const handler = function (evt) {
+    removeClass();
+    const type = evt?.type;
+    // @ts-ignore
+    const isHidden = hiddenProp && document[hiddenProp];
+    const visibleEvents = ['focus', 'focusin', 'pageshow'];
+    const hiddenEvents = ['blur', 'focusout', 'pagehide'];
+    if (visibleEvents.includes(type)) {
+      element.classList.add(visibleClass);
+      onVisible?.();
+    } else if (hiddenEvents.includes(type)) {
+      element.classList.add(hiddenClass);
+      onHidden?.();
+    } else {
+      if (isHidden) {
+        element.classList.add(hiddenClass);
+        onHidden?.();
+      } else {
+        element.classList.add(visibleClass);
+        onVisible?.();
+      }
+    }
+  };
+  /** @type {() => void} */
+  let uninstall = () => {};
+  if (hiddenProp) {
+    const eventType = visibilityEvents[visibilityProps.indexOf(hiddenProp)];
+    document.addEventListener(eventType, handler);
+    window.addEventListener('focus', handler);
+    window.addEventListener('blur', handler);
+    uninstall = () => {
+      document.removeEventListener(eventType, handler);
+      window.removeEventListener('focus', handler);
+      window.removeEventListener('blur', handler);
+      removeClass();
+    };
+  } else if ('onfocusin' in document) {
+    // Fallback for IE9 and older
+    // @ts-ignore
+    document.onfocusin = document.onfocusout = handler;
+    uninstall = () => {
+      // @ts-ignore
+      document.onfocusin = document.onfocusout = null;
+      removeClass();
+    };
+  } else {
+    // Last resort fallback
+    window.onpageshow = window.onpagehide = window.onfocus = window.onblur = handler;
+    uninstall = () => {
+      window.onpageshow = window.onpagehide = window.onfocus = window.onblur = null;
+      removeClass();
+    };
+  }
+  // Trigger initial state
+  // @ts-ignore
+  const simulatedEvent = new Event(hiddenProp && document[hiddenProp] ? 'blur' : 'focus');
+  handler(simulatedEvent);
+  return uninstall;
+}
 // EXTERNAL MODULE: fs (ignored)
 var fs_ignored_ = __webpack_require__(133);
 // EXTERNAL MODULE: ./node_modules/path-browserify/index.js
@@ -5290,6 +5485,7 @@ class TinyDragger {
 ;// ./src/v1/libs/TinyUploadClicker.mjs