tiny-essentials 1.13.1 → 1.14.0

package/dist/v1/TinyEssentials.js

@@ -2890,6 +2890,7 @@ __webpack_require__.d(__webpack_exports__, {
   TinyDragDropDetector: () => (/* reexport */ libs_TinyDragDropDetector),
   TinyDragger: () => (/* reexport */ libs_TinyDragger),
   TinyLevelUp: () => (/* reexport */ userLevel),
+  TinyNotifications: () => (/* reexport */ libs_TinyNotifications),
   TinyNotifyCenter: () => (/* reexport */ libs_TinyNotifyCenter),
   TinyPromiseQueue: () => (/* reexport */ libs_TinyPromiseQueue),
   TinyRateLimiter: () => (/* reexport */ libs_TinyRateLimiter),
@@ -2929,6 +2930,7 @@ __webpack_require__.d(__webpack_exports__, {
   getLatestBackupPath: () => (/* reexport */ normalFuncs_getLatestBackupPath),
   getSimplePerc: () => (/* reexport */ getSimplePerc),
   getTimeDuration: () => (/* reexport */ getTimeDuration),
+  installWindowHiddenScript: () => (/* reexport */ installWindowHiddenScript),
   isDirEmpty: () => (/* reexport */ isDirEmpty),
   isDirEmptyAsync: () => (/* reexport */ isDirEmptyAsync),
   isFullScreenMode: () => (/* reexport */ isFullScreenMode),
@@ -2941,6 +2943,8 @@ __webpack_require__.d(__webpack_exports__, {
   objType: () => (/* reexport */ objType),
   offFullScreenChange: () => (/* reexport */ offFullScreenChange),
   onFullScreenChange: () => (/* reexport */ onFullScreenChange),
+  readBase64Blob: () => (/* reexport */ readBase64Blob),
+  readFileBlob: () => (/* reexport */ readFileBlob),
   readJsonBlob: () => (/* reexport */ readJsonBlob),
   readJsonFile: () => (/* reexport */ readJsonFile),
   renameFileAddPrefixSuffix: () => (/* reexport */ renameFileAddPrefixSuffix),
@@ -2952,6 +2956,7 @@ __webpack_require__.d(__webpack_exports__, {
   requestFullScreen: () => (/* reexport */ requestFullScreen),
   restoreLatestBackup: () => (/* reexport */ restoreLatestBackup),
   ruleOfThree: () => (/* reexport */ ruleOfThree),
+  safeTextTrim: () => (/* reexport */ safeTextTrim),
   saveJsonFile: () => (/* reexport */ saveJsonFile),
   shuffleArray: () => (/* reexport */ shuffleArray),
   toTitleCase: () => (/* reexport */ toTitleCase),
@@ -4235,6 +4240,48 @@ function addAiMarkerShortcut(key = 'a') {
   });
 }
 
+/**
+ * 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";
 
@@ -6165,34 +6212,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
@@ -6295,7 +6413,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) {
@@ -6395,6 +6514,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;
+}
+
 ;// ./src/v1/libs/TinyDragDropDetector.mjs
 /**
  * @typedef {Object} DragAndDropOptions
@@ -8413,6 +8655,244 @@ class TinyDomReadyManager {
 
 /* harmony default export */ const libs_TinyDomReadyManager = (TinyDomReadyManager);
 
+;// ./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/index.mjs
 
 
@@ -8438,6 +8918,7 @@ class TinyDomReadyManager {
 
 
 
+
 
 
 })();