tiny-essentials 1.13.2 → 1.15.0

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

@@ -7,12 +7,56 @@
  */
 export function areHtmlElsColliding(elem1: Element, elem2: Element): boolean;
 /**
- * Reads and parses a JSON data using FileReader.
- * Throws an error if the content is not valid JSON.
- * @param {File} file
- * @returns {Promise<any>}
+ * Checks if two DOM elements are colliding on the screen, and locks the collision
+ * until the element exits through the same side it entered.
+ *
+ * @param {Element} elem1 - First DOM element (e.g. draggable or moving element).
+ * @param {Element} elem2 - Second DOM element (e.g. a container or boundary element).
+ * @param {'top'|'bottom'|'left'|'right'} lockDirection - Direction that must be respected to unlock the collision.
+ * @param {WeakMap<Element, string>} stateMap - A shared WeakMap to track persistent entry direction per element.
+ * @returns {boolean} True if collision is still active.
+ */
+export function areHtmlElsCollidingWithLock(elem1: Element, elem2: Element, lockDirection: "top" | "bottom" | "left" | "right", stateMap: WeakMap<Element, string>): boolean;
+/**
+ * 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.
+ */
+export function readFileBlob(file: File, method: "readAsArrayBuffer" | "readAsDataURL" | "readAsText" | "readAsBinaryString"): Promise<any>;
+/**
+ * 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.
+ */
+export function readBase64Blob(file: File, isDataUrl?: boolean | string): Promise<string>;
+/**
+ * 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.
  */
-export function readJsonBlob(file: File): Promise<any>;
+export function readJsonBlob(file: File): Promise<Record<string | number | symbol, any> | any[]>;
 /**
  * Saves a JSON object as a downloadable file.
  * @param {string} filename
@@ -44,19 +88,39 @@ export function fetchJson(url: string, { method, body, timeout, retries, headers
 }): Promise<any>;
 /**
  * Installs a script that toggles CSS classes on a given element
- * based on the page's visibility or focus state.
+ * 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.
  */
-export function installWindowHiddenScript({ element, hiddenClass, visibleClass, }?: {
+export function installWindowHiddenScript({ element, hiddenClass, visibleClass, onVisible, onHidden, }?: {
     element?: HTMLElement | undefined;
     hiddenClass?: string | undefined;
     visibleClass?: string | undefined;
+    onVisible?: (() => void) | undefined;
+    onHidden?: (() => void) | undefined;
 }): () => void;
+/**
+ * Checks if the given element is at least partially visible in the viewport.
+ *
+ * @param {HTMLElement} element - The DOM element to check.
+ * @returns {boolean} True if the element is partially in the viewport, false otherwise.
+ */
+export function isInViewport(element: HTMLElement): boolean;
+/**
+ * Checks if the given element is fully visible in the viewport (top and bottom).
+ *
+ * @param {HTMLElement} element - The DOM element to check.
+ * @returns {boolean} True if the element is fully visible in the viewport, false otherwise.
+ */
+export function isScrolledIntoView(element: HTMLElement): boolean;
 export function getHtmlElBordersWidth(el: Element): HtmlElBoxSides;
 export function getHtmlElBorders(el: Element): HtmlElBoxSides;
 export function getHtmlElMargin(el: Element): HtmlElBoxSides;

package/dist/v1/basics/html.mjs

@@ -1,4 +1,5 @@
 import { isJsonObject } from './objFilter.mjs';
+import { areElsColliding, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, } from './collision.mjs';
 /**
  * Checks if two DOM elements are colliding on the screen.
  *
@@ -9,37 +10,150 @@ import { isJsonObject } from './objFilter.mjs';
 export function areHtmlElsColliding(elem1, elem2) {
     const rect1 = elem1.getBoundingClientRect();
     const rect2 = elem2.getBoundingClientRect();
-    return !(rect1.right < rect2.left ||
-        rect1.left > rect2.right ||
-        rect1.bottom < rect2.top ||
-        rect1.top > rect2.bottom);
+    return areElsColliding(rect1, rect2);
 }
 /**
- * Reads and parses a JSON data using FileReader.
- * Throws an error if the content is not valid JSON.
- * @param {File} file
- * @returns {Promise<any>}
+ * Checks if two DOM elements are colliding on the screen, and locks the collision
+ * until the element exits through the same side it entered.
+ *
+ * @param {Element} elem1 - First DOM element (e.g. draggable or moving element).
+ * @param {Element} elem2 - Second DOM element (e.g. a container or boundary element).
+ * @param {'top'|'bottom'|'left'|'right'} lockDirection - Direction that must be respected to unlock the collision.
+ * @param {WeakMap<Element, string>} stateMap - A shared WeakMap to track persistent entry direction per element.
+ * @returns {boolean} True if collision is still active.
  */
-export function readJsonBlob(file) {
+export function areHtmlElsCollidingWithLock(elem1, elem2, lockDirection, stateMap) {
+    const rect1 = elem1.getBoundingClientRect();
+    const rect2 = elem2.getBoundingClientRect();
+    const isColliding = areElsColliding(rect1, rect2);
+    if (isColliding) {
+        // Save entry direction
+        if (!stateMap.has(elem1)) {
+            stateMap.set(elem1, lockDirection);
+        }
+        return true;
+    }
+    // Handle unlock logic
+    if (stateMap.has(elem1)) {
+        const lastDirection = stateMap.get(elem1);
+        switch (lastDirection) {
+            case 'top':
+                if (areElsCollTop(rect1, rect2))
+                    stateMap.delete(elem1); // exited from top
+                break;
+            case 'bottom':
+                if (areElsCollBottom(rect1, rect2))
+                    stateMap.delete(elem1); // exited from bottom
+                break;
+            case 'left':
+                if (areElsCollLeft(rect1, rect2))
+                    stateMap.delete(elem1); // exited from left
+                break;
+            case 'right':
+                if (areElsCollRight(rect1, rect2))
+                    stateMap.delete(elem1); // exited from right
+                break;
+        }
+        return stateMap.has(elem1); // still colliding (locked)
+    }
+    return false;
+}
+/**
+ * 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.
+ */
+export 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.readAsText(file);
+        reader[method](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.
+ */
+export 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.
+ */
+export 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
@@ -119,7 +233,7 @@ export async function fetchJson(url, { method = 'GET', body, timeout = 0, retrie
             if (!contentType.includes('application/json'))
                 throw new Error(`Unexpected content-type: ${contentType}`);
             const data = await response.json();
-            if (!isJsonObject(data))
+            if (!Array.isArray(data) && !isJsonObject(data))
                 throw new Error('Received invalid data instead of valid JSON.');
             return data;
         }
@@ -208,23 +322,35 @@ export const getHtmlElPadding = (el) => {
 };
 /**
  * Installs a script that toggles CSS classes on a given element
- * based on the page's visibility or focus state.
+ * 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.
  */
-export function installWindowHiddenScript({ element = document.body, hiddenClass = 'windowHidden', visibleClass = 'windowVisible', } = {}) {
+export 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;
-    /** @type {(this: any, evt: Event) => void} */
-    let handler;
     const visibilityEvents = [
         'visibilitychange',
         'mozvisibilitychange',
@@ -238,7 +364,8 @@ export function installWindowHiddenScript({ element = document.body, hiddenClass
             break;
         }
     }
-    handler = function (evt) {
+    /** @type {(this: any, evt: Event) => void} */
+    const handler = function (evt) {
         removeClass();
         const type = evt?.type;
         // @ts-ignore
@@ -247,12 +374,21 @@ export function installWindowHiddenScript({ element = document.body, hiddenClass
         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 {
-            element.classList.add(isHidden ? hiddenClass : visibleClass);
+            if (isHidden) {
+                element.classList.add(hiddenClass);
+                onHidden?.();
+            }
+            else {
+                element.classList.add(visibleClass);
+                onVisible?.();
+            }
         }
     };
     /** @type {() => void} */
@@ -287,8 +423,35 @@ export function installWindowHiddenScript({ element = document.body, hiddenClass
             removeClass();
         };
     }
+    // Trigger initial state
     // @ts-ignore
     const simulatedEvent = new Event(hiddenProp && document[hiddenProp] ? 'blur' : 'focus');
     handler(simulatedEvent);
     return uninstall;
 }
+/**
+ * Checks if the given element is at least partially visible in the viewport.
+ *
+ * @param {HTMLElement} element - The DOM element to check.
+ * @returns {boolean} True if the element is partially in the viewport, false otherwise.
+ */
+export function isInViewport(element) {
+    const elementTop = element.offsetTop;
+    const elementBottom = elementTop + element.offsetHeight;
+    const viewportTop = window.scrollY;
+    const viewportBottom = viewportTop + window.innerHeight;
+    return elementBottom > viewportTop && elementTop < viewportBottom;
+}
+/**
+ * Checks if the given element is fully visible in the viewport (top and bottom).
+ *
+ * @param {HTMLElement} element - The DOM element to check.
+ * @returns {boolean} True if the element is fully visible in the viewport, false otherwise.
+ */
+export function isScrolledIntoView(element) {
+    const viewportTop = window.scrollY;
+    const viewportBottom = viewportTop + window.innerHeight;
+    const elemTop = element.offsetTop;
+    const elemBottom = elemTop + element.offsetHeight;
+    return elemBottom <= viewportBottom && elemTop >= viewportTop;
+}

package/dist/v1/basics/index.cjs

@@ -9,6 +9,7 @@ var objFilter = require('./objFilter.cjs');
 var fullScreen = require('./fullScreen.cjs');
 var simpleMath = require('./simpleMath.cjs');
 var text = require('./text.cjs');
+var collision = require('./collision.cjs');
 
 
 
@@ -26,6 +27,10 @@ exports.getHtmlElBordersWidth = html.getHtmlElBordersWidth;
 exports.getHtmlElMargin = html.getHtmlElMargin;
 exports.getHtmlElPadding = html.getHtmlElPadding;
 exports.installWindowHiddenScript = html.installWindowHiddenScript;
+exports.isInViewport = html.isInViewport;
+exports.isScrolledIntoView = html.isScrolledIntoView;
+exports.readBase64Blob = html.readBase64Blob;
+exports.readFileBlob = html.readFileBlob;
 exports.readJsonBlob = html.readJsonBlob;
 exports.saveJsonFile = html.saveJsonFile;
 exports.cloneObjTypeOrder = objFilter.cloneObjTypeOrder;
@@ -47,5 +52,24 @@ exports.getAge = simpleMath.getAge;
 exports.getSimplePerc = simpleMath.getSimplePerc;
 exports.ruleOfThree = simpleMath.ruleOfThree;
 exports.addAiMarkerShortcut = text.addAiMarkerShortcut;
+exports.safeTextTrim = text.safeTextTrim;
 exports.toTitleCase = text.toTitleCase;
 exports.toTitleCaseLowerFirst = text.toTitleCaseLowerFirst;
+exports.areElsCollBottom = collision.areElsCollBottom;
+exports.areElsCollLeft = collision.areElsCollLeft;
+exports.areElsCollPerfBottom = collision.areElsCollPerfBottom;
+exports.areElsCollPerfLeft = collision.areElsCollPerfLeft;
+exports.areElsCollPerfRight = collision.areElsCollPerfRight;
+exports.areElsCollPerfTop = collision.areElsCollPerfTop;
+exports.areElsCollRight = collision.areElsCollRight;
+exports.areElsCollTop = collision.areElsCollTop;
+exports.areElsColliding = collision.areElsColliding;
+exports.areElsPerfColliding = collision.areElsPerfColliding;
+exports.getElsCollDetails = collision.getElsCollDetails;
+exports.getElsCollDirDepth = collision.getElsCollDirDepth;
+exports.getElsCollOverlap = collision.getElsCollOverlap;
+exports.getElsCollOverlapPos = collision.getElsCollOverlapPos;
+exports.getElsColliding = collision.getElsColliding;
+exports.getElsPerfColliding = collision.getElsPerfColliding;
+exports.getElsRelativeCenterOffset = collision.getElsRelativeCenterOffset;
+exports.getRectCenter = collision.getRectCenter;

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

@@ -1,3 +1,24 @@
+import { areElsCollTop } from './collision.mjs';
+import { areElsCollBottom } from './collision.mjs';
+import { areElsCollLeft } from './collision.mjs';
+import { areElsCollRight } from './collision.mjs';
+import { areElsCollPerfTop } from './collision.mjs';
+import { areElsCollPerfBottom } from './collision.mjs';
+import { areElsCollPerfLeft } from './collision.mjs';
+import { areElsCollPerfRight } from './collision.mjs';
+import { areElsColliding } from './collision.mjs';
+import { areElsPerfColliding } from './collision.mjs';
+import { getElsColliding } from './collision.mjs';
+import { getElsPerfColliding } from './collision.mjs';
+import { getElsCollOverlap } from './collision.mjs';
+import { getElsCollOverlapPos } from './collision.mjs';
+import { getRectCenter } from './collision.mjs';
+import { getElsRelativeCenterOffset } from './collision.mjs';
+import { getElsCollDirDepth } from './collision.mjs';
+import { getElsCollDetails } from './collision.mjs';
+import { isInViewport } from './html.mjs';
+import { isScrolledIntoView } from './html.mjs';
+import { safeTextTrim } from './text.mjs';
 import { installWindowHiddenScript } from './html.mjs';
 import { genFibonacciSeq } from './simpleMath.mjs';
 import { getHtmlElBorders } from './html.mjs';
@@ -6,6 +27,8 @@ import { getHtmlElMargin } from './html.mjs';
 import { getHtmlElPadding } from './html.mjs';
 import { fetchJson } from './html.mjs';
 import { readJsonBlob } from './html.mjs';
+import { readFileBlob } from './html.mjs';
+import { readBase64Blob } from './html.mjs';
 import { saveJsonFile } from './html.mjs';
 import { documentIsFullScreen } from './fullScreen.mjs';
 import { isScreenFilled } from './fullScreen.mjs';
@@ -35,5 +58,5 @@ import { getTimeDuration } from './clock.mjs';
 import { shuffleArray } from './array.mjs';
 import { toTitleCase } from './text.mjs';
 import { toTitleCaseLowerFirst } from './text.mjs';
-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 };
+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 };
 //# sourceMappingURL=index.d.mts.map

package/dist/v1/basics/index.mjs

@@ -2,9 +2,10 @@ 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, installWindowHiddenScript, } from './html.mjs';
+import { areHtmlElsColliding, readJsonBlob, saveJsonFile, fetchJson, getHtmlElBorders, getHtmlElBordersWidth, getHtmlElMargin, getHtmlElPadding, installWindowHiddenScript, readFileBlob, readBase64Blob, isInViewport, isScrolledIntoView, } 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 { 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, };
+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, };

package/dist/v1/basics/text.cjs

@@ -64,6 +64,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";
 
@@ -89,5 +131,6 @@ export default KeyPressHandler;
 */
 
 exports.addAiMarkerShortcut = addAiMarkerShortcut;
+exports.safeTextTrim = safeTextTrim;
 exports.toTitleCase = toTitleCase;
 exports.toTitleCaseLowerFirst = toTitleCaseLowerFirst;

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

@@ -32,4 +32,20 @@ export function toTitleCaseLowerFirst(str: string): string;
  * @param {string} [key='a'] - The lowercase character key to be used in combination with Ctrl and Alt.
  */
 export function addAiMarkerShortcut(key?: string): void;
+/**
+ * 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).
+ */
+export function safeTextTrim(text: string, limit: number, safeCutZone?: number): string;
 //# sourceMappingURL=text.d.mts.map

package/dist/v1/basics/text.mjs

@@ -52,6 +52,43 @@ export 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).
+ */
+export 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";
 

package/dist/v1/build/TinyNotifications.cjs

@@ -0,0 +1,7 @@
+'use strict';
+
+var TinyNotifications = require('../libs/TinyNotifications.cjs');
+
+
+
+exports.TinyNotifications = TinyNotifications;

package/dist/v1/build/TinyNotifications.d.mts

@@ -0,0 +1,3 @@
+export { TinyNotifications };
+import TinyNotifications from '../libs/TinyNotifications.mjs';
+//# sourceMappingURL=TinyNotifications.d.mts.map

package/dist/v1/build/TinyNotifications.mjs

@@ -0,0 +1,2 @@
+import TinyNotifications from '../libs/TinyNotifications.mjs';
+export { TinyNotifications };