tiny-essentials 1.13.1 → 1.13.2

package/dist/v1/basics/html.cjs

@@ -252,11 +252,112 @@ 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.
+ *
+ * @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.
+ * @returns {() => void} Function that removes all installed event listeners.
+ */
+function installWindowHiddenScript({
+  element = document.body,
+  hiddenClass = 'windowHidden',
+  visibleClass = 'windowVisible',
+} = {}) {
+  const removeClass = () => {
+    element.classList.remove(hiddenClass);
+    element.classList.remove(visibleClass);
+  };
+
+  /** @type {string|null} */
+  let hiddenProp = null;
+  /** @type {(this: any, evt: Event) => void} */
+  let handler;
+
+  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;
+    }
+  }
+
+  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);
+    } else if (hiddenEvents.includes(type)) {
+      element.classList.add(hiddenClass);
+    } else {
+      element.classList.add(isHidden ? hiddenClass : visibleClass);
+    }
+  };
+
+  /** @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();
+    };
+  }
+
+  // @ts-ignore
+  const simulatedEvent = new Event(hiddenProp && document[hiddenProp] ? 'blur' : 'focus');
+  handler(simulatedEvent);
+
+  return uninstall;
+}
+
 exports.areHtmlElsColliding = areHtmlElsColliding;
 exports.fetchJson = fetchJson;
 exports.getHtmlElBorders = getHtmlElBorders;
 exports.getHtmlElBordersWidth = getHtmlElBordersWidth;
 exports.getHtmlElMargin = getHtmlElMargin;
 exports.getHtmlElPadding = getHtmlElPadding;
+exports.installWindowHiddenScript = installWindowHiddenScript;
 exports.readJsonBlob = readJsonBlob;
 exports.saveJsonFile = saveJsonFile;

package/dist/v1/basics/html.d.mts

@@ -42,6 +42,21 @@ export function fetchJson(url: string, { method, body, timeout, retries, headers
     headers?: Headers | Record<string, any> | undefined;
     signal?: AbortSignal | null | undefined;
 }): Promise<any>;
+/**
+ * Installs a script that toggles CSS classes on a given element
+ * based on the page's visibility or focus state.
+ *
+ * @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.
+ * @returns {() => void} Function that removes all installed event listeners.
+ */
+export function installWindowHiddenScript({ element, hiddenClass, visibleClass, }?: {
+    element?: HTMLElement | undefined;
+    hiddenClass?: string | undefined;
+    visibleClass?: string | undefined;
+}): () => void;
 export function getHtmlElBordersWidth(el: Element): HtmlElBoxSides;
 export function getHtmlElBorders(el: Element): HtmlElBoxSides;
 export function getHtmlElMargin(el: Element): HtmlElBoxSides;

package/dist/v1/basics/html.mjs

@@ -206,3 +206,89 @@ export const getHtmlElPadding = (el) => {
     const y = top + bottom;
     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.
+ *
+ * @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.
+ * @returns {() => void} Function that removes all installed event listeners.
+ */
+export function installWindowHiddenScript({ element = document.body, hiddenClass = 'windowHidden', visibleClass = 'windowVisible', } = {}) {
+    const removeClass = () => {
+        element.classList.remove(hiddenClass);
+        element.classList.remove(visibleClass);
+    };
+    /** @type {string|null} */
+    let hiddenProp = null;
+    /** @type {(this: any, evt: Event) => void} */
+    let handler;
+    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;
+        }
+    }
+    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);
+        }
+        else if (hiddenEvents.includes(type)) {
+            element.classList.add(hiddenClass);
+        }
+        else {
+            element.classList.add(isHidden ? hiddenClass : visibleClass);
+        }
+    };
+    /** @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();
+        };
+    }
+    // @ts-ignore
+    const simulatedEvent = new Event(hiddenProp && document[hiddenProp] ? 'blur' : 'focus');
+    handler(simulatedEvent);
+    return uninstall;
+}

package/dist/v1/basics/index.cjs

@@ -25,6 +25,7 @@ exports.getHtmlElBorders = html.getHtmlElBorders;
 exports.getHtmlElBordersWidth = html.getHtmlElBordersWidth;
 exports.getHtmlElMargin = html.getHtmlElMargin;
 exports.getHtmlElPadding = html.getHtmlElPadding;
+exports.installWindowHiddenScript = html.installWindowHiddenScript;
 exports.readJsonBlob = html.readJsonBlob;
 exports.saveJsonFile = html.saveJsonFile;
 exports.cloneObjTypeOrder = objFilter.cloneObjTypeOrder;

package/dist/v1/basics/index.d.mts

@@ -1,3 +1,4 @@
+import { installWindowHiddenScript } from './html.mjs';
 import { genFibonacciSeq } from './simpleMath.mjs';
 import { getHtmlElBorders } from './html.mjs';
 import { getHtmlElBordersWidth } from './html.mjs';
@@ -34,5 +35,5 @@ import { getTimeDuration } from './clock.mjs';
 import { shuffleArray } from './array.mjs';
 import { toTitleCase } from './text.mjs';
 import { toTitleCaseLowerFirst } from './text.mjs';
-export { genFibonacciSeq, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, fetchJson, readJsonBlob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, areHtmlElsColliding, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+export { installWindowHiddenScript, genFibonacciSeq, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, fetchJson, readJsonBlob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, areHtmlElsColliding, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/basics/index.mjs

@@ -2,9 +2,9 @@ import arraySortPositions from '../../legacy/libs/arraySortPositions.mjs';
 import asyncReplace from '../../legacy/libs/replaceAsync.mjs';
 import { shuffleArray } from './array.mjs';
 import { formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration } from './clock.mjs';
-import { areHtmlElsColliding, readJsonBlob, saveJsonFile, fetchJson, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, } from './html.mjs';
+import { areHtmlElsColliding, readJsonBlob, saveJsonFile, fetchJson, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, installWindowHiddenScript, } from './html.mjs';
 import { countObj, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, isJsonObject, } from './objFilter.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, } from './fullScreen.mjs';
 import { formatBytes, genFibonacciSeq, getAge, getSimplePerc, ruleOfThree } from './simpleMath.mjs';
 import { addAiMarkerShortcut, toTitleCase, toTitleCaseLowerFirst } from './text.mjs';
-export { genFibonacciSeq, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, fetchJson, readJsonBlob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, areHtmlElsColliding, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+export { installWindowHiddenScript, genFibonacciSeq, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, fetchJson, readJsonBlob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, areHtmlElsColliding, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/index.cjs

@@ -64,6 +64,7 @@ exports.getHtmlElBorders = html.getHtmlElBorders;
 exports.getHtmlElBordersWidth = html.getHtmlElBordersWidth;
 exports.getHtmlElMargin = html.getHtmlElMargin;
 exports.getHtmlElPadding = html.getHtmlElPadding;
+exports.installWindowHiddenScript = html.installWindowHiddenScript;
 exports.readJsonBlob = html.readJsonBlob;
 exports.saveJsonFile = html.saveJsonFile;
 exports.TinyDragDropDetector = TinyDragDropDetector;

package/dist/v1/index.d.mts

@@ -7,6 +7,7 @@ import TinyRateLimiter from './libs/TinyRateLimiter.mjs';
 import ColorSafeStringify from './libs/ColorSafeStringify.mjs';
 import TinyPromiseQueue from './libs/TinyPromiseQueue.mjs';
 import TinyLevelUp from '../legacy/libs/userLevel.mjs';
+import { installWindowHiddenScript } from './basics/html.mjs';
 import { genFibonacciSeq } from './basics/simpleMath.mjs';
 import { isDirEmptyAsync } from './fileManager/asyncFuncs.mjs';
 import { fileSizeAsync } from './fileManager/asyncFuncs.mjs';
@@ -72,5 +73,5 @@ import { getTimeDuration } from './basics/clock.mjs';
 import { shuffleArray } from './basics/array.mjs';
 import { toTitleCase } from './basics/text.mjs';
 import { toTitleCaseLowerFirst } from './basics/text.mjs';
-export { TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, getLatestBackupPath, fetchJson, readJsonBlob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, areHtmlElsColliding, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+export { TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, getLatestBackupPath, fetchJson, readJsonBlob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, areHtmlElsColliding, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/index.mjs

@@ -12,10 +12,10 @@ import TinyPromiseQueue from './libs/TinyPromiseQueue.mjs';
 import TinyRateLimiter from './libs/TinyRateLimiter.mjs';
 import TinyNotifyCenter from './libs/TinyNotifyCenter.mjs';
 import TinyToastNotify from './libs/TinyToastNotify.mjs';
-import { areHtmlElsColliding, readJsonBlob, saveJsonFile, fetchJson, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, } from './basics/html.mjs';
+import { areHtmlElsColliding, readJsonBlob, saveJsonFile, fetchJson, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, installWindowHiddenScript, } from './basics/html.mjs';
 import TinyDragDropDetector from './libs/TinyDragDropDetector.mjs';
 import { readJsonFile, writeJsonFile, ensureDirectory, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, getLatestBackupPath, } from './fileManager/normalFuncs.mjs';
 import { listFilesAsync, listDirsAsync, clearDirectoryAsync, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, } from './fileManager/asyncFuncs.mjs';
 import TinyDragger from './libs/TinyDragger.mjs';
 import TinyDomReadyManager from './libs/TinyDomReadyManager.mjs';
-export { TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, getLatestBackupPath, fetchJson, readJsonBlob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, areHtmlElsColliding, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+export { TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, getLatestBackupPath, fetchJson, readJsonBlob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, areHtmlElsColliding, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/docs/v1/basics/html.md

@@ -1,4 +1,4 @@
-## 🚀 `areHtmlElsColliding()`
+### 🚀 `areHtmlElsColliding()`
 
 Check if two DOM elements are **colliding on the screen**! Perfect for games, draggable elements, UI interactions, and more.
 
@@ -13,7 +13,7 @@ It compares the bounding rectangles of both elements:
 
 ---
 
-## 🧠 Syntax
+#### 🧠 Syntax
 
 ```javascript
 areHtmlElsColliding(elem1, elem2);
@@ -21,7 +21,7 @@ areHtmlElsColliding(elem1, elem2);
 
 ---
 
-## 🎯 Parameters
+#### 🎯 Parameters
 
 | Parameter | Type      | Description             |
 | --------- | --------- | ----------------------- |
@@ -30,7 +30,7 @@ areHtmlElsColliding(elem1, elem2);
 
 ---
 
-## 🔁 Return
+#### 🔁 Return
 
 | Type      | Description                                                        |
 | --------- | ------------------------------------------------------------------ |
@@ -38,7 +38,7 @@ areHtmlElsColliding(elem1, elem2);
 
 ---
 
-## 📦 Example
+#### 📦 Example
 
 ```javascript
 const box1 = document.getElementById('box1');
@@ -53,31 +53,31 @@ if (areHtmlElsColliding(box1, box2)) {
 
 ---
 
-## 🚧 Limitations
+#### 🚧 Limitations
 
 * Only works with **axis-aligned elements** (rectangular shapes).
 * Does not handle rotated elements or complex shapes.
 
 ---
 
-## 📖 `readJsonBlob(file: File): Promise<any>`
+### 📖 `readJsonBlob(file: File): Promise<any>`
 
 Reads and parses a JSON file using the [`FileReader`](https://developer.mozilla.org/en-US/docs/Web/API/FileReader) API.
 
-### 📥 Parameters
+#### 📥 Parameters
 
 * `file` *(File)*: The file object selected by the user (e.g., from an `<input type="file">` element).
 
-### 📤 Returns
+#### 📤 Returns
 
 * `Promise<any>`: Resolves with the parsed JSON object, or rejects with an error if the content is invalid.
 
-### ⚠️ Throws
+#### ⚠️ Throws
 
 * An error if the content is not valid JSON.
 * An error if the file can't be read.
 
-### 🧪 Example
+#### 🧪 Example
 
 ```js
 const input = document.querySelector('input[type="file"]');
@@ -93,36 +93,36 @@ input.addEventListener('change', async () => {
 
 ---
 
-## 💾 `saveJsonFile(filename: string, data: any, spaces: number = 2): void`
+### 💾 `saveJsonFile(filename: string, data: any, spaces: number = 2): void`
 
 Converts a JavaScript object to JSON and triggers a download in the browser.
 
-### 📥 Parameters
+#### 📥 Parameters
 
 * `filename` *(string)*: The name of the file to save (e.g., `"data.json"`).
 * `data` *(any)*: The JavaScript object to convert to JSON.
 * `spaces` *(number)* *(optional)*: Indentation level for formatting the JSON string. Default is `2`.
 
-### 📤 Returns
+#### 📤 Returns
 
 * `void`
 
-### 📂 Behavior
+#### 📂 Behavior
 
 Creates a temporary `<a>` element, downloads the file, and cleans up the URL.
 
-### 🧪 Example
+#### 🧪 Example
 
 ```js
 const data = { name: 'Yasmin', type: 'dev' };
 saveJsonFile('yasmin.json', data);
 ```
 
-## 🌐 `fetchJson(url, options?): Promise<any>`
+### 🌐 `fetchJson(url, options?): Promise<any>`
 
 Loads and parses a JSON from a remote URL using the Fetch API, with support for custom HTTP methods, retries, timeouts, headers, and even external abort controllers.
 
-### 📥 Parameters
+#### 📥 Parameters
 
 * `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
 * `options` *(object)* *(optional)*:
@@ -134,7 +134,7 @@ Loads and parses a JSON from a remote URL using the Fetch API, with support for
   * `headers` *(object)*: Additional headers to include in the request.
   * `body` *(object)*: Request body. If the value is a plain object, it will be automatically stringified as JSON.
 
-#### `signal` (`AbortSignal` | `null`) — *optional*
+##### `signal` (`AbortSignal` | `null`) — *optional*
 
 Custom abort signal. If set:
 
@@ -142,21 +142,21 @@ Custom abort signal. If set:
 * Retry logic is **disabled**
 * Abortion is handled externally
 
-### 📤 Returns
+#### 📤 Returns
 
 * `Promise<any>`: Resolves with the parsed JSON data.
 
-### ⚠️ Throws
+#### ⚠️ Throws
 
 * `Error` if the fetch fails or exceeds the timeout
 * `Error` if the response is not `application/json`
 * `Error` if the result is not a plain JSON object
 
-## 🧠 Tip
+#### 🧠 Tip
 
 If you pass your own `signal`, this disables both `timeout` and `retries`. Use it when you're managing cancellation manually (e.g. in UI components or async workflows).
 
-### 🧪 Example
+#### 🧪 Example
 
 ```js
 const controller = new AbortController();
@@ -241,3 +241,106 @@ getHtmlElPadding(el: Element): HtmlElBoxSides
 
 * `el`: The target DOM element.
 * **Returns**: Padding values for all sides and summed horizontal (`x`) and vertical (`y`) values.
+
+---
+
+### 📄 `installWindowHiddenScript`
+
+Automatically toggles CSS classes on a given element based on the browser window or tab **visibility** and **focus** state.
+
+Perfect for UI states like dimming, pausing animations, or showing "away" statuses.
+
+---
+
+#### 🧠 Features
+
+* ✅ Adds or removes custom CSS classes depending on page visibility or focus
+* ✅ Supports modern and legacy browsers (including IE9)
+* ✅ Automatically dispatches an initial state check on load
+* ✅ Returns a cleanup function to remove all listeners
+
+---
+
+#### 🧪 Usage
+
+```js
+import { installWindowHiddenScript } from 'tiny-essentials';
+
+const uninstall = installWindowHiddenScript({
+  element: document.getElementById('app'),
+  hiddenClass: 'is-hidden',
+  visibleClass: 'is-visible',
+});
+
+// To remove all listeners later
+uninstall();
+```
+
+---
+
+#### ⚙️ Options
+
+| Option         | Type          | Default           | Description                                                       |
+| -------------- | ------------- | ----------------- | ----------------------------------------------------------------- |
+| `element`      | `HTMLElement` | `document.body`   | The element to which the visibility classes will be applied       |
+| `hiddenClass`  | `string`      | `'windowHidden'`  | Class name to apply when the window is **not visible or blurred** |
+| `visibleClass` | `string`      | `'windowVisible'` | Class name to apply when the window is **visible or focused**     |
+
+---
+
+#### 🔄 Return Value
+
+```ts
+() => void
+```
+
+Returns a function that, when called, will:
+
+* 🧹 Remove all attached event listeners
+* ❌ Remove both visibility classes from the target element
+
+---
+
+#### 🚦 Events Supported
+
+The script handles multiple events depending on browser support:
+
+* `visibilitychange`, `webkitvisibilitychange`, `mozvisibilitychange`, `msvisibilitychange`
+* `focus`, `blur`, `focusin`, `focusout`
+* `pageshow`, `pagehide`
+* IE fallback: `onfocusin`, `onfocusout`
+
+---
+
+#### 🔍 Initial Trigger
+
+Immediately after installation, the script simulates a `focus` or `blur` event based on the current visibility state to **ensure the classes are applied from the start**.
+
+---
+
+#### 🧯 Uninstalling
+
+Don’t forget to call the returned function if you dynamically load/unload components or scripts:
+
+```js
+const stopWatching = installWindowHiddenScript(...);
+stopWatching(); // later
+```
+
+---
+
+#### 🎨 CSS Example
+
+```css
+.windowVisible {
+  opacity: 1;
+  pointer-events: auto;
+  transition: opacity 0.3s ease;
+}
+
+.windowHidden {
+  opacity: 0.4;
+  pointer-events: none;
+  transition: opacity 0.3s ease;
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.13.1",
+  "version": "1.13.2",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",