tiny-essentials 1.20.1 → 1.20.2

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

@@ -49,21 +49,31 @@ export function saveJsonFile(filename: string, data: any, spaces?: number): void
  * Loads and parses a JSON from a remote URL using Fetch API.
  *
  * @param {string} url - The full URL to fetch JSON from.
- * @param {Object} [options] - Optional settings.
+ * @param {FetchTemplateOptions} [options] - Optional settings.
  * @returns {Promise<any[] | Record<string | number | symbol, unknown>>} Parsed JSON object.
  * @throws {Error} Throws if fetch fails, times out, or returns invalid JSON.
  */
-export function fetchJson(url: string, options?: Object): Promise<any[] | Record<string | number | symbol, unknown>>;
+export function fetchJson(url: string, options?: FetchTemplateOptions): Promise<any[] | Record<string | number | symbol, unknown>>;
 /**
  * Loads a remote file as a Blob using Fetch API.
  *
  * @param {string} url - The full URL to fetch the file from.
- * @param {Object} [options] - Optional fetch options.
+ * @param {FetchTemplateOptions} [options] - Optional fetch options.
  * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
  * @returns {Promise<Blob>} - The fetched file as a Blob.
  * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
  */
-export function fetchBlob(url: string, allowedMimeTypes?: string[], options?: Object): Promise<Blob>;
+export function fetchBlob(url: string, allowedMimeTypes?: string[], options?: FetchTemplateOptions): Promise<Blob>;
+/**
+ * Loads a remote file as a text using Fetch API.
+ *
+ * @param {string} url - The full URL to fetch the file from.
+ * @param {FetchTemplateOptions} [options] - Optional fetch options.
+ * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @returns {Promise<string>} - The fetched file as a text.
+ * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
+ */
+export function fetchText(url: string, allowedMimeTypes?: string[], options?: FetchTemplateOptions): Promise<string>;
 /**
  * Installs a script that toggles CSS classes on a given element
  * based on the page's visibility or focus state, and optionally

package/dist/v1/basics/html.mjs

@@ -188,7 +188,7 @@ async function fetchTemplate(url, { method = 'GET', body, timeout = 0, retries =
  * Loads and parses a JSON from a remote URL using Fetch API.
  *
  * @param {string} url - The full URL to fetch JSON from.
- * @param {Object} [options] - Optional settings.
+ * @param {FetchTemplateOptions} [options] - Optional settings.
  * @returns {Promise<any[] | Record<string | number | symbol, unknown>>} Parsed JSON object.
  * @throws {Error} Throws if fetch fails, times out, or returns invalid JSON.
  */
@@ -211,7 +211,7 @@ export async function fetchJson(url, options) {
  * Loads a remote file as a Blob using Fetch API.
  *
  * @param {string} url - The full URL to fetch the file from.
- * @param {Object} [options] - Optional fetch options.
+ * @param {FetchTemplateOptions} [options] - Optional fetch options.
  * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
  * @returns {Promise<Blob>} - The fetched file as a Blob.
  * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
@@ -232,6 +232,31 @@ export async function fetchBlob(url, allowedMimeTypes, options) {
             .catch(reject);
     });
 }
+/**
+ * Loads a remote file as a text using Fetch API.
+ *
+ * @param {string} url - The full URL to fetch the file from.
+ * @param {FetchTemplateOptions} [options] - Optional fetch options.
+ * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
+ * @returns {Promise<string>} - The fetched file as a text.
+ * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
+ */
+export async function fetchText(url, allowedMimeTypes, options) {
+    return new Promise((resolve, reject) => {
+        fetchTemplate(url, options)
+            .then(async (res) => {
+            const contentType = res.headers.get('content-type') || '';
+            if (Array.isArray(allowedMimeTypes) &&
+                allowedMimeTypes.length > 0 &&
+                !allowedMimeTypes.some((type) => contentType.includes(type))) {
+                throw new Error(`Blocked MIME type: ${contentType}`);
+            }
+            const data = await res.text();
+            return resolve(data);
+        })
+            .catch(reject);
+    });
+}
 ///////////////////////////////////////////////////////////////////////////////
 /**
  * Installs a script that toggles CSS classes on a given element

package/dist/v1/basics/index.cjs

@@ -23,6 +23,7 @@ exports.formatDayTimer = clock.formatDayTimer;
 exports.formatTimer = clock.formatTimer;
 exports.getTimeDuration = clock.getTimeDuration;
 exports.fetchJson = html.fetchJson;
+exports.fetchText = html.fetchText;
 exports.installWindowHiddenScript = html.installWindowHiddenScript;
 exports.readBase64Blob = html.readBase64Blob;
 exports.readFileBlob = html.readFileBlob;
@@ -51,6 +52,7 @@ exports.requestFullScreen = fullScreen.requestFullScreen;
 exports.formatBytes = simpleMath.formatBytes;
 exports.genFibonacciSeq = simpleMath.genFibonacciSeq;
 exports.getAge = simpleMath.getAge;
+exports.getPercentage = simpleMath.getPercentage;
 exports.getSimplePerc = simpleMath.getSimplePerc;
 exports.ruleOfThree = simpleMath.ruleOfThree;
 exports.addAiMarkerShortcut = text.addAiMarkerShortcut;

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

@@ -1,3 +1,4 @@
+import { getPercentage } from './simpleMath.mjs';
 import { areElsCollTop } from './collision.mjs';
 import { areElsCollBottom } from './collision.mjs';
 import { areElsCollLeft } from './collision.mjs';
@@ -26,6 +27,7 @@ import { getHtmlElBordersWidth } from './html_deprecated.mjs';
 import { getHtmlElMargin } from './html_deprecated.mjs';
 import { getHtmlElPadding } from './html_deprecated.mjs';
 import { fetchJson } from './html.mjs';
+import { fetchText } from './html.mjs';
 import { readJsonBlob } from './html.mjs';
 import { readFileBlob } from './html.mjs';
 import { readBase64Blob } from './html.mjs';
@@ -58,5 +60,5 @@ import { getTimeDuration } from './clock.mjs';
 import { shuffleArray } from './array.mjs';
 import { toTitleCase } from './text.mjs';
 import { toTitleCaseLowerFirst } from './text.mjs';
-export { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, isInViewport, isScrolledIntoView, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, fetchJson, readJsonBlob, readFileBlob, readBase64Blob, 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 { getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, isInViewport, isScrolledIntoView, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, 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,12 +2,12 @@ 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 { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, } from './html.mjs';
+import { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, fetchText, } from './html.mjs';
 import { areHtmlElsColliding, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, isInViewport, isScrolledIntoView, } from './html_deprecated.mjs';
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType } from './objFilter.mjs';
 import { countObj, isJsonObject } from './objChecker.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, } from './fullScreen.mjs';
-import { formatBytes, genFibonacciSeq, getAge, getSimplePerc, ruleOfThree } from './simpleMath.mjs';
+import { formatBytes, genFibonacciSeq, getAge, getPercentage, getSimplePerc, ruleOfThree } from './simpleMath.mjs';
 import { addAiMarkerShortcut, safeTextTrim, toTitleCase, toTitleCaseLowerFirst } from './text.mjs';
 import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, } from './collision.mjs';
-export { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, isInViewport, isScrolledIntoView, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, fetchJson, readJsonBlob, readFileBlob, readBase64Blob, 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 { getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, isInViewport, isScrolledIntoView, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, 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/basics/simpleMath.cjs

@@ -40,10 +40,13 @@ function ruleOfThree(val1, val2, val3, inverse = false) {
 }
 
 /**
- * Calculates a percentage of a given base value.
- * @param {number} price - The base value.
- * @param {number} percentage - The percentage to apply.
- * @returns {number} The result of the percentage calculation.
+ * Calculates the actual value that corresponds to a percentage of a base number.
+ * Unlike `getPercentage`, which tells how much something represents in percent,
+ * this function tells how much a given percentage *is worth* in value.
+ *
+ * @param {number} price - The base number to apply the percentage to.
+ * @param {number} percentage - The percentage to calculate from the base.
+ * @returns {number} The resulting value of the percentage.
  *
  * @example
  * getSimplePerc(200, 15); // 30
@@ -52,6 +55,21 @@ function getSimplePerc(price, percentage) {
   return price * (percentage / 100);
 }
 
+/**
+ * Calculates how much percent a partial value represents of the total value.
+ *
+ * @param {number} part - The partial value to compare.
+ * @param {number} total - The total or maximum value.
+ * @returns {number} The percentage that 'part' represents of 'total'.
+ *
+ * @example
+ * getPercentage(5, 100); // 5
+ */
+function getPercentage(part, total) {
+  if (total === 0) return 0;
+  return (part / total) * 100;
+}
+
 /**
  * Calculates the age based on the given date.
  *
@@ -166,5 +184,6 @@ function genFibonacciSeq({
 exports.formatBytes = formatBytes;
 exports.genFibonacciSeq = genFibonacciSeq;
 exports.getAge = getAge;
+exports.getPercentage = getPercentage;
 exports.getSimplePerc = getSimplePerc;
 exports.ruleOfThree = ruleOfThree;

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

@@ -35,15 +35,29 @@
  */
 export function ruleOfThree(val1: number, val2: number, val3: number, inverse?: boolean): number;
 /**
- * Calculates a percentage of a given base value.
- * @param {number} price - The base value.
- * @param {number} percentage - The percentage to apply.
- * @returns {number} The result of the percentage calculation.
+ * Calculates the actual value that corresponds to a percentage of a base number.
+ * Unlike `getPercentage`, which tells how much something represents in percent,
+ * this function tells how much a given percentage *is worth* in value.
+ *
+ * @param {number} price - The base number to apply the percentage to.
+ * @param {number} percentage - The percentage to calculate from the base.
+ * @returns {number} The resulting value of the percentage.
  *
  * @example
  * getSimplePerc(200, 15); // 30
  */
 export function getSimplePerc(price: number, percentage: number): number;
+/**
+ * Calculates how much percent a partial value represents of the total value.
+ *
+ * @param {number} part - The partial value to compare.
+ * @param {number} total - The total or maximum value.
+ * @returns {number} The percentage that 'part' represents of 'total'.
+ *
+ * @example
+ * getPercentage(5, 100); // 5
+ */
+export function getPercentage(part: number, total: number): number;
 /**
  * Calculates the age based on the given date.
  *

package/dist/v1/basics/simpleMath.mjs

@@ -37,10 +37,13 @@ export function ruleOfThree(val1, val2, val3, inverse = false) {
     return inverse ? Number(val1 * val2) / val3 : Number(val3 * val2) / val1;
 }
 /**
- * Calculates a percentage of a given base value.
- * @param {number} price - The base value.
- * @param {number} percentage - The percentage to apply.
- * @returns {number} The result of the percentage calculation.
+ * Calculates the actual value that corresponds to a percentage of a base number.
+ * Unlike `getPercentage`, which tells how much something represents in percent,
+ * this function tells how much a given percentage *is worth* in value.
+ *
+ * @param {number} price - The base number to apply the percentage to.
+ * @param {number} percentage - The percentage to calculate from the base.
+ * @returns {number} The resulting value of the percentage.
  *
  * @example
  * getSimplePerc(200, 15); // 30
@@ -48,6 +51,21 @@ export function ruleOfThree(val1, val2, val3, inverse = false) {
 export function getSimplePerc(price, percentage) {
     return price * (percentage / 100);
 }
+/**
+ * Calculates how much percent a partial value represents of the total value.
+ *
+ * @param {number} part - The partial value to compare.
+ * @param {number} total - The total or maximum value.
+ * @returns {number} The percentage that 'part' represents of 'total'.
+ *
+ * @example
+ * getPercentage(5, 100); // 5
+ */
+export function getPercentage(part, total) {
+    if (total === 0)
+        return 0;
+    return (part / total) * 100;
+}
 /**
  * Calculates the age based on the given date.
  *

package/dist/v1/index.cjs

@@ -64,6 +64,7 @@ exports.requestFullScreen = fullScreen.requestFullScreen;
 exports.formatBytes = simpleMath.formatBytes;
 exports.genFibonacciSeq = simpleMath.genFibonacciSeq;
 exports.getAge = simpleMath.getAge;
+exports.getPercentage = simpleMath.getPercentage;
 exports.getSimplePerc = simpleMath.getSimplePerc;
 exports.ruleOfThree = simpleMath.ruleOfThree;
 exports.addAiMarkerShortcut = text.addAiMarkerShortcut;
@@ -76,6 +77,7 @@ exports.TinyRateLimiter = TinyRateLimiter;
 exports.TinyNotifyCenter = TinyNotifyCenter;
 exports.TinyToastNotify = TinyToastNotify;
 exports.fetchJson = html.fetchJson;
+exports.fetchText = html.fetchText;
 exports.installWindowHiddenScript = html.installWindowHiddenScript;
 exports.readBase64Blob = html.readBase64Blob;
 exports.readFileBlob = html.readFileBlob;

package/dist/v1/index.d.mts

@@ -20,6 +20,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 { getPercentage } from './basics/simpleMath.mjs';
 import { areElsCollTop } from './basics/collision.mjs';
 import { areElsCollBottom } from './basics/collision.mjs';
 import { areElsCollLeft } from './basics/collision.mjs';
@@ -54,6 +55,7 @@ import { getHtmlElMargin } from './basics/html_deprecated.mjs';
 import { getHtmlElPadding } from './basics/html_deprecated.mjs';
 import { getLatestBackupPath } from './fileManager/normalFuncs.mjs';
 import { fetchJson } from './basics/html.mjs';
+import { fetchText } from './basics/html.mjs';
 import { readJsonBlob } from './basics/html.mjs';
 import { readFileBlob } from './basics/html.mjs';
 import { readBase64Blob } from './basics/html.mjs';
@@ -109,5 +111,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 { TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, isInViewport, isScrolledIntoView, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, getLatestBackupPath, fetchJson, readJsonBlob, readFileBlob, readBase64Blob, 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 { TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, isInViewport, isScrolledIntoView, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, 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

@@ -6,14 +6,14 @@ import { formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, } from
 import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, checkObj, } from './basics/objFilter.mjs';
 import { countObj, isJsonObject } from './basics/objChecker.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, } from './basics/fullScreen.mjs';
-import { formatBytes, genFibonacciSeq, getAge, getSimplePerc, ruleOfThree, } from './basics/simpleMath.mjs';
+import { formatBytes, genFibonacciSeq, getAge, getPercentage, getSimplePerc, ruleOfThree, } from './basics/simpleMath.mjs';
 import { addAiMarkerShortcut, safeTextTrim, toTitleCase, toTitleCaseLowerFirst, } from './basics/text.mjs';
 import ColorSafeStringify from './libs/ColorSafeStringify.mjs';
 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 { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, } from './basics/html.mjs';
+import { readJsonBlob, saveJsonFile, fetchJson, installWindowHiddenScript, readFileBlob, readBase64Blob, fetchText, } from './basics/html.mjs';
 import { getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, areHtmlElsColliding, isInViewport, isScrolledIntoView, } from './basics/html_deprecated.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';
@@ -34,4 +34,4 @@ import TinyEvents from './libs/TinyEvents.mjs';
 import TinyLocalStorage from './libs/TinyLocalStorage.mjs';
 import TinyIframeEvents from './libs/TinyIframeEvents.mjs';
 import TinyNewWinEvents from './libs/TinyNewWinEvents.mjs';
-export { TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, isInViewport, isScrolledIntoView, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, getLatestBackupPath, fetchJson, readJsonBlob, readFileBlob, readBase64Blob, 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 { TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, isInViewport, isScrolledIntoView, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, 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/dist/v1/libs/TinyHtml.cjs

@@ -225,6 +225,16 @@ const __elemCollision = {
  * @typedef {HTMLInputElement|HTMLSelectElement|HTMLTextAreaElement|HTMLOptionElement} InputElement
  */
 
+/**
+ * Represents a parsed HTML element in JSON-like array form.
+ *
+ * @typedef {[
+ *   tagName: string, // The tag name of the element (e.g., 'div', 'img')
+ *   attributes: Record<string, string>, // All element attributes as key-value pairs
+ *   ...children: (string | HtmlParsed)[] // Text or nested elements
+ * ]} HtmlParsed
+ */
+
 /**
  * TinyHtml is a utility class that provides static and instance-level methods
  * for precise dimension and position computations on HTML elements.
@@ -240,6 +250,188 @@ class TinyHtml {
 
   static Utils = { ...collision };
 
+  /**
+   * Fetches an HTML file from the given URL, parses it to JSON.
+   *
+   * @param {string | URL | globalThis.Request} url - The URL of the HTML file.
+   * @param {RequestInit} [ops] - Optional fetch configuration (e.g., method, headers, cache, etc).
+   * @returns {Promise<HtmlParsed[]>} A promise that resolves with the parsed JSON representation of the HTML structure.
+   */
+  static async fetchHtmlFile(url, ops = { method: 'GET' }) {
+    const res = await fetch(url, ops);
+
+    const contentType = res.headers.get('Content-Type') || '';
+    if (!res.ok) throw new Error(`Failed to fetch: ${res.status} ${res.statusText}`);
+
+    // Only accept HTML responses
+    if (!contentType.includes('text/html')) {
+      throw new Error(`Invalid content type: ${contentType} (expected text/html)`);
+    }
+
+    const html = await res.text();
+    return TinyHtml.htmlToJson(html);
+  }
+
+  /**
+   * Fetches an HTML file from the given URL, parses it to JSON, then converts it to DOM nodes.
+   *
+   * @param {string} url - The URL of the HTML file.
+   * @param {RequestInit} [ops] - Optional fetch configuration (e.g., method, headers, cache, etc).
+   * @returns {Promise<(HTMLElement|Text)[]>} A promise that resolves with the DOM nodes.
+   */
+  static async fetchHtmlNodes(url, ops) {
+    const json = await TinyHtml.fetchHtmlFile(url, ops);
+    return TinyHtml.jsonToNodes(json);
+  }
+
+  /**
+   * Fetches an HTML file from the given URL, parses it to JSON, then converts it to TinyHtml instances.
+   *
+   * @param {string} url - The URL of the HTML file.
+   * @param {RequestInit} [ops] - Optional fetch configuration (e.g., method, headers, cache, etc).
+   * @returns {Promise<TinyHtml[]>} A promise that resolves with the TinyHtml instances.
+   */
+  static async fetchHtmlTinyElems(url, ops) {
+    const nodes = await TinyHtml.fetchHtmlNodes(url, ops);
+    return TinyHtml.toTinyElm(nodes);
+  }
+
+  /**
+   * Converts the content of a <template> to an array of HtmlParsed.
+   *
+   * @param {HTMLTemplateElement} nodes
+   * @returns {HtmlParsed[]}
+   */
+  static templateToJson(nodes) {
+    return TinyHtml.htmlToJson(
+      [...nodes.content.childNodes]
+        .map((node) =>
+          node instanceof Element ? node.getHTML() : node instanceof Text ? node.textContent : '',
+        )
+        .join(''),
+    );
+  }
+
+  /**
+   * Converts the content of a <template> to real DOM nodes.
+   *
+   * @param {HTMLTemplateElement} nodes
+   * @returns {(Element|Text)[]}
+   */
+  static templateToNodes(nodes) {
+    /** @type {(Element|Text)[]} */
+    const result = [];
+    [...nodes.content.cloneNode(true).childNodes].map((node) => {
+      if (!(node instanceof Element) && !(node instanceof Text) && !(node instanceof Comment))
+        throw new Error(
+          `Expected only Element nodes in <template>, but found: ${node.constructor.name}`,
+        );
+      if (!(node instanceof Comment)) result.push(node);
+    });
+    return result;
+  }
+
+  /**
+   * Converts the content of a <template> to an array of TinyHtml elements.
+   *
+   * @param {HTMLTemplateElement} nodes
+   * @returns {TinyHtml[]}
+   */
+  static templateToTinyElems(nodes) {
+    return TinyHtml.toTinyElm(TinyHtml.templateToNodes(nodes));
+  }
+
+  /**
+   * Parses a full HTML string into a JSON-like structure.
+   *
+   * @param {string} htmlString - Full HTML markup as a string.
+   * @returns {HtmlParsed[]} An array of parsed HTML elements in structured format.
+   */
+  static htmlToJson(htmlString) {
+    const container = document.createElement('div');
+    container.innerHTML = htmlString.trim();
+
+    const result = [];
+
+    /**
+     * @param {Node} el
+     * @returns {*}
+     */
+    const parseElement = (el) => {
+      if (el instanceof Comment) return null;
+      if (el instanceof Text) {
+        const text = el.textContent?.trim();
+        return text ? text : null;
+      }
+
+      if (!(el instanceof Element)) return null;
+      const tag = el.tagName.toLowerCase();
+
+      /** @type {Record<string, string>} */
+      const props = {};
+      for (const attr of el.attributes) {
+        props[TinyHtml.getPropName(attr.name)] = attr.value;
+      }
+
+      const children = Array.from(el.childNodes).map(parseElement).filter(Boolean);
+      return children.length > 0 ? [tag, props, ...children] : [tag, props];
+    };
+
+    for (const child of container.childNodes) {
+      const parsed = parseElement(child);
+      if (parsed) result.push(parsed);
+    }
+
+    container.innerHTML = '';
+    return result;
+  }
+
+  /**
+   * Converts a JSON-like HTML structure back to DOM Elements.
+   *
+   * @param {HtmlParsed[]} jsonArray - Parsed JSON format of HTML.
+   * @returns {(HTMLElement|Text)[]} List of DOM nodes.
+   */
+  static jsonToNodes(jsonArray) {
+    /**
+     * @param {HtmlParsed|string} nodeData
+     * @returns {HTMLElement|Text}
+     */
+    const createElement = (nodeData) => {
+      if (typeof nodeData === 'string') {
+        return document.createTextNode(nodeData);
+      }
+
+      if (!Array.isArray(nodeData)) return document.createTextNode('');
+      const [tag, props, ...children] = nodeData;
+      const el = document.createElement(tag);
+
+      for (const [key, value] of Object.entries(props)) {
+        el.setAttribute(TinyHtml.getAttrName(key), value);
+      }
+
+      for (const child of children) {
+        const childEl = createElement(child);
+        if (childEl instanceof Comment) continue;
+        el.appendChild(childEl);
+      }
+
+      return el;
+    };
+
+    return jsonArray.map(createElement).filter((node) => !(node instanceof Comment));
+  }
+
+  /**
+   * Converts a JSON-like HTML structure back to TinyHtml instances.
+   *
+   * @param {HtmlParsed[]} jsonArray - Parsed JSON format of HTML.
+   * @returns {TinyHtml[]} List of TinyHtml instances.
+   */
+  static jsonToTinyElems(jsonArray) {
+    return TinyHtml.toTinyElm(TinyHtml.jsonToNodes(jsonArray));
+  }
+
   /**
    * Creates a new TinyHtml element from a tag name and optional attributes.
    *
@@ -498,7 +690,8 @@ class TinyHtml {
     if (
       !(this.#el[index] instanceof Element) &&
       !(this.#el[index] instanceof Window) &&
-      !(this.#el[index] instanceof Document)
+      !(this.#el[index] instanceof Document) &&
+      !(this.#el[index] instanceof Text)
     )
       throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
     return this.#el[index];
@@ -514,7 +707,11 @@ class TinyHtml {
   _getElements(where) {
     if (
       !this.#el.every(
-        (el) => el instanceof Element || el instanceof Window || el instanceof Document,
+        (el) =>
+          el instanceof Element ||
+          el instanceof Window ||
+          el instanceof Document ||
+          el instanceof Text,
       )
     )
       throw new Error(`[TinyHtml] Invalid Element in ${where}().`);
@@ -866,11 +1063,11 @@ class TinyHtml {
    * This ensures consistent access to methods of the `TinyHtml` class regardless
    * of the input form.
    *
-   * @param {TinyElement|TinyElement[]} elems - A single element or an array of elements (DOM or TinyHtml).
+   * @param {TinyElement|Text|(TinyElement|Text)[]} elems - A single element or an array of elements (DOM or TinyHtml).
    * @returns {TinyHtml[]} An array of TinyHtml instances corresponding to the input elements.
    */
   static toTinyElm(elems) {
-    /** @param {TinyElement[]} item */
+    /** @param {(TinyElement|Text)[]} item */
     const checkElement = (item) =>
       item.map((elem) => (!(elem instanceof TinyHtml) ? new TinyHtml(elem) : elem));
     if (!Array.isArray(elems)) return checkElement([elems]);
@@ -1832,6 +2029,15 @@ class TinyHtml {
    */
   #el;
 
+  /**
+   * Returns the number of elements currently stored in the internal element list.
+   *
+   * @returns {number} The total count of elements.
+   */
+  get size() {
+    return this.#el.length;
+  }
+
   /**
    * Creates an instance of TinyHtml for a specific Element.
    * Useful when you want to operate repeatedly on the same element using instance methods.