tiny-essentials 1.13.2 → 1.14.0

package/dist/v1/libs/TinyNotifications.mjs

@@ -0,0 +1,211 @@
+import { safeTextTrim } from '../basics/text.mjs';
+/**
+ * A utility class to manage browser notifications with sound and custom behavior.
+ * Useful for triggering system notifications with optional sound, avatar icon, body truncation, and click actions.
+ *
+ * @class
+ */
+class TinyNotifications {
+    /** @type {boolean} Whether notifications are currently allowed by the user. */
+    #allowed = false;
+    /** @type {boolean} Indicates whether the user has already requested permission at least once. */
+    #permissionRequested = false;
+    /** @type {HTMLAudioElement|null} Audio element to play when a notification is triggered. */
+    #audio = null;
+    /** @type {number} Maximum number of characters in the notification body. */
+    #bodyLimit = 100;
+    /** @type {string|null} Default avatar icon URL for notifications. */
+    #defaultIcon = null;
+    /** @type {(this: Notification, evt: Event) => any} Default handler when a notification is clicked. */
+    #defaultOnClick;
+    /**
+     * Constructs a new instance of TinyNotifications.
+     *
+     * @param {Object} [settings={}] - Optional settings to initialize the notification manager.
+     * @param {string|HTMLAudioElement|null} [settings.audio] - Path or URL to the audio file for notification sounds.
+     * @param {string|null} [settings.defaultIcon] - Default icon URL to be used in notifications.
+     * @param {number} [settings.bodyLimit=100] - Maximum number of characters allowed in the notification body.
+     * @param {(this: Notification, evt: Event) => any} [settings.defaultOnClick] - Default function to execute when a notification is clicked.
+     * @throws {TypeError} If any of the parameters are of an invalid type.
+     */
+    constructor({ audio = null, defaultIcon = null, bodyLimit = 100, defaultOnClick = function (event) {
+        event.preventDefault();
+        if (window.focus)
+            window.focus();
+        this.close();
+    }, } = {}) {
+        if (!(audio instanceof HTMLAudioElement) && typeof audio !== 'string' && audio !== null)
+            throw new TypeError('audio must be an instance of HTMLAudioElement or null.');
+        if (defaultIcon !== null && typeof defaultIcon !== 'string')
+            throw new TypeError('defaultIcon must be a string or null.');
+        if (!Number.isFinite(bodyLimit) || bodyLimit < 0)
+            throw new TypeError('bodyLimit must be a non-negative number.');
+        if (typeof defaultOnClick !== 'function')
+            throw new TypeError('defaultOnClick must be a function.');
+        this.#audio = typeof audio !== 'string' ? audio : new Audio(audio);
+        this.#defaultIcon = defaultIcon;
+        this.#bodyLimit = bodyLimit;
+        this.#defaultOnClick = defaultOnClick;
+    }
+    /**
+     * Requests permission from the user to show notifications.
+     * Updates the internal `#allowed` flag.
+     *
+     * @returns {Promise<boolean>} Resolves to `true` if permission is granted, otherwise `false`.
+     */
+    requestPerm() {
+        const tinyThis = this;
+        return new Promise((resolve, reject) => {
+            if (tinyThis.isCompatible()) {
+                if (Notification.permission === 'default') {
+                    Notification.requestPermission()
+                        .then((permission) => {
+                        this.#permissionRequested = true;
+                        tinyThis.#allowed = permission === 'granted';
+                        resolve(tinyThis.#allowed);
+                    })
+                        .catch(reject);
+                }
+                else {
+                    this.#permissionRequested = true;
+                    tinyThis.#allowed = Notification.permission === 'granted';
+                    resolve(tinyThis.#allowed);
+                }
+            }
+            else {
+                this.#permissionRequested = true;
+                tinyThis.#allowed = false;
+                resolve(false);
+            }
+        });
+    }
+    /**
+     * Checks if the Notification API is supported by the current browser.
+     *
+     * @returns {boolean} Returns `true` if notifications are supported, otherwise `false`.
+     */
+    isCompatible() {
+        return 'Notification' in window;
+    }
+    /**
+     * Sends a browser notification with the provided title and configuration.
+     * Truncates the body if necessary and plays a sound if configured.
+     *
+     * @param {string} title - The title of the notification.
+     * @param {NotificationOptions & { vibrate?: number[] }} [config={}] - Optional configuration for the notification.
+     * @returns {Notification|null} The created `Notification` instance, or `null` if permission is not granted.
+     * @throws {TypeError} If the title is not a string or config is not a valid object.
+     */
+    send(title, config = {}) {
+        if (!this.#permissionRequested)
+            throw new Error('You must call requestPerm() before sending a notification.');
+        if (typeof title !== 'string')
+            throw new TypeError('title must be a string.');
+        if (typeof config !== 'object' || config === null)
+            throw new TypeError('config must be a non-null object.');
+        if (!this.#allowed)
+            return null;
+        const { icon = this.#defaultIcon || undefined, vibrate = [200, 100, 200] } = config;
+        const options = { ...config };
+        if (typeof icon === 'string')
+            options.icon = icon;
+        if (Array.isArray(vibrate))
+            options.vibrate = vibrate;
+        if (typeof options.body === 'string')
+            options.body = safeTextTrim(options.body, this.#bodyLimit);
+        const notification = new Notification(title, options);
+        notification.addEventListener('show', () => {
+            if (!(this.#audio instanceof HTMLAudioElement))
+                return;
+            this.#audio.currentTime = 0;
+            this.#audio.play().catch((err) => console.error(err));
+        });
+        if (typeof this.#defaultOnClick === 'function')
+            notification.addEventListener('click', this.#defaultOnClick);
+        return notification;
+    }
+    // === Getters and Setters ===
+    /**
+     * Whether the requestPerm() method was already called.
+     * @returns {boolean}
+     */
+    wasPermissionRequested() {
+        return this.#permissionRequested;
+    }
+    /**
+     * Returns the current permission status.
+     * @returns {boolean} `true` if permission was granted, otherwise `false`.
+     */
+    isAllowed() {
+        return this.#allowed;
+    }
+    /**
+     * Gets the current notification audio.
+     * @returns {HTMLAudioElement|null} The sound element, or `null` if not set.
+     */
+    getAudio() {
+        return this.#audio;
+    }
+    /**
+     * Sets the audio element used for notification sounds.
+     * @param {HTMLAudioElement|string|null} value - A valid `HTMLAudioElement` or `null` to disable sound.
+     * @throws {TypeError} If the value is not an `HTMLAudioElement` or `null`.
+     */
+    setAudio(value) {
+        if (!(value instanceof HTMLAudioElement) && typeof value !== 'string' && value !== null)
+            throw new TypeError('sound must be an instance of HTMLAudioElement or null.');
+        this.#audio = typeof value !== 'string' ? value : new Audio(value);
+    }
+    /**
+     * Gets the maximum length of the notification body text.
+     * @returns {number} Number of characters allowed.
+     */
+    getBodyLimit() {
+        return this.#bodyLimit;
+    }
+    /**
+     * Sets the maximum number of characters allowed in the notification body.
+     * @param {number} value - A non-negative integer.
+     * @throws {TypeError} If the value is not a valid non-negative number.
+     */
+    setBodyLimit(value) {
+        if (!Number.isFinite(value) || value < 0)
+            throw new TypeError('bodyLimit must be a non-negative number.');
+        this.#bodyLimit = value;
+    }
+    /**
+     * Gets the default avatar icon URL.
+     * @returns {string|null} The URL string or `null`.
+     */
+    getDefaultAvatar() {
+        return this.#defaultIcon;
+    }
+    /**
+     * Sets the default avatar icon URL.
+     * @param {string|null} value - A string URL or `null` to disable default icon.
+     * @throws {TypeError} If the value is not a string or `null`.
+     */
+    setDefaultAvatar(value) {
+        if (!(typeof value === 'string' || value === null))
+            throw new TypeError('defaultIcon must be a string or null.');
+        this.#defaultIcon = value;
+    }
+    /**
+     * Gets the default click event handler for notifications.
+     * @returns {(this: Notification, evt: Event) => any} The current click handler function.
+     */
+    getDefaultOnClick() {
+        return this.#defaultOnClick;
+    }
+    /**
+     * Sets the default click event handler for notifications.
+     * @param {(this: Notification, evt: Event) => any} value - A function to handle the notification click event.
+     * @throws {TypeError} If the value is not a function.
+     */
+    setDefaultOnClick(value) {
+        if (typeof value !== 'function')
+            throw new TypeError('defaultOnClick must be a function.');
+        this.#defaultOnClick = value;
+    }
+}
+export default TinyNotifications;

package/docs/v1/README.md

@@ -29,9 +29,10 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🔔 **[TinyNotifyCenter](./libs/TinyNotifyCenter.md)** — A dynamic notification center class to display, manage, and interact with notifications, supporting avatars, clickable items, HTML/text modes, and clean UI controls.
 - 🍞 **[TinyToastNotify](./libs/TinyToastNotify.md)** — A lightweight toast notification system supporting positioning, timing customization, avatars, click actions, and fade-out animations.
 - 📥 **[TinyDragDropDetector](./libs/TinyDragDropDetector.md)** — A lightweight drag-and-drop detector for files, handling the full drag lifecycle (`enter`, `over`, `leave`, `drop`) with CSS hover management and safe event handling on any DOM element or the full page.
-* 📂 **[TinyUploadClicker](./libs/TinyUploadClicker.md)** — A minimal utility to bind any clickable element to a hidden file input, offering full control over styling, behavior, and upload event hooks.
-* 🧲 **[TinyDragger](./libs/TinyDragger.md)** — A flexible drag-and-drop manager with collision detection, jail constraints, vibration feedback, visual proxies, revert-on-drop, and full custom event support.
-* 🕒 **[TinyDomReadyManager](./libs/TinyDomReadyManager.md)** — A readiness manager for DOM and async conditions, supporting prioritized callbacks, custom filters, and event-based or promise-based bootstrapping.
+- 📂 **[TinyUploadClicker](./libs/TinyUploadClicker.md)** — A minimal utility to bind any clickable element to a hidden file input, offering full control over styling, behavior, and upload event hooks.
+- 🧲 **[TinyDragger](./libs/TinyDragger.md)** — A flexible drag-and-drop manager with collision detection, jail constraints, vibration feedback, visual proxies, revert-on-drop, and full custom event support.
+- 🕒 **[TinyDomReadyManager](./libs/TinyDomReadyManager.md)** — A readiness manager for DOM and async conditions, supporting prioritized callbacks, custom filters, and event-based or promise-based bootstrapping.
+- 📣 **[TinyNotifications](./libs/TinyNotifications.md)** — A browser notification utility with sound support, permission management, truncation logic, default icons, and enforced validation to ensure safe and predictable usage.
 
 ### 3. **`fileManager/`**
 * 📁 **[main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.

package/docs/v1/basics/array.md

@@ -1,16 +1,18 @@
 # 📦 array.mjs
 
-A tiny utility for shuffling arrays using the good old Fisher–Yates algorithm. Simple, efficient, and perfectly random (as far as JavaScript's `Math.random()` allows, anyway).
+A minimal and handy module offering a couple of focused utilities for working with arrays — from shuffling items randomly to generating smart sort functions for object arrays. Ideal for quick scripting or modular use in larger projects.
 
-## ✨ Features
+---
+
+## `shuffleArray(items: string[]): string[]`
 
-- 📚 Uses the classic **Fisher–Yates** algorithm
-- 🔄 Shuffles arrays **in-place**
-- 🎯 Guarantees **uniform distribution** of permutations
-- 🔍 Well-documented and easy to read
-- 🧪 No dependencies — just plug and play
+🔄 A tiny utility for shuffling arrays using the good old Fisher–Yates algorithm. Simple, efficient, and perfectly random (as far as JavaScript's `Math.random()` allows, anyway).
 
-## 🚀 Usage
+- **items** — An array of strings to shuffle.
+- **Returns** — The same array instance, but now shuffled.
+
+
+### 🚀 Usage
 
 ```js
 import { shuffleArray } from './array.mjs';
@@ -23,54 +25,29 @@ console.log(fruits); // ['banana', 'cherry', 'apple', 'date'] (order will vary)
 
 > Note: The original array is shuffled in place. If you want to preserve the original order, make a copy before shuffling.
 
-## 🧠 How It Works
-
-This function implements the **Fisher–Yates shuffle** (also known as the Knuth shuffle), which runs in linear time and guarantees uniform randomness:
-
-```js
-while (currentIndex !== 0) {
-  randomIndex = Math.floor(Math.random() * currentIndex);
-  currentIndex--;
-  [items[currentIndex], items[randomIndex]] = [items[randomIndex], items[currentIndex]];
-}
-```
-
 You can find the original discussion here:  
 🔗 https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array
 
-## 📁 API
-
-### `shuffleArray(items: string[]): string[]`
-
-- **items** — An array of strings to shuffle.
-- **Returns** — The same array instance, but now shuffled.
-
 ---
 
-# 📦 `arraySortPositions`
+## 📦 `arraySortPositions`
 
 🔧 **Generates a comparator function** to sort an array of objects by a specified key, with optional reverse order.
 
----
-
-## 📌 Function Signature
+### 📌 Function Signature
 
 ```js
 arraySortPositions(item: string, isReverse?: boolean): (a: Object<string|number, *>, b: Object<string|number, *>) => number
 ```
 
----
-
-## 🧠 Parameters
+### 🧠 Parameters
 
 | Name        | Type      | Default | Description                                                |
 | ----------- | --------- | ------- | ---------------------------------------------------------- |
 | `item`      | `string`  | —       | 🔑 The key to sort the objects by.                         |
 | `isReverse` | `boolean` | `false` | 🔄 If `true`, the sorting will be in **descending** order. |
 
----
-
-## 🎯 Returns
+### 🎯 Returns
 
 🧩 A **comparator function** compatible with `Array.prototype.sort()`:
 
@@ -80,9 +57,7 @@ arraySortPositions(item: string, isReverse?: boolean): (a: Object<string|number,
 
 It compares two objects based on the specified `item` key.
 
----
-
-## 💡 Examples
+### 💡 Examples
 
 ```js
 const arr = [{ pos: 2 }, { pos: 1 }, { pos: 3 }];
@@ -96,9 +71,7 @@ arr.sort(arraySortPositions('pos', true));
 // 🔽 Descending: [{ pos: 3 }, { pos: 2 }, { pos: 1 }]
 ```
 
----
-
-## 🛠️ Use Case
+### 🛠️ Use Case
 
 Great for situations where you need to **dynamically sort objects** by one of their keys, such as:
 

package/docs/v1/basics/html.md

@@ -11,16 +11,12 @@ It compares the bounding rectangles of both elements:
 * ✅ Checks if **rect1** is NOT entirely to the left, right, above, or below **rect2**.
 * ✅ If none of these are true, then the elements are overlapping.
 
----
-
 #### 🧠 Syntax
 
 ```javascript
 areHtmlElsColliding(elem1, elem2);
 ```
 
----
-
 #### 🎯 Parameters
 
 | Parameter | Type      | Description             |
@@ -28,16 +24,12 @@ areHtmlElsColliding(elem1, elem2);
 | `elem1`   | `Element` | The first DOM element.  |
 | `elem2`   | `Element` | The second DOM element. |
 
----
-
 #### 🔁 Return
 
 | Type      | Description                                                        |
 | --------- | ------------------------------------------------------------------ |
 | `boolean` | ✅ `true` if elements are colliding. <br>❌ `false` if they are not. |
 
----
-
 #### 📦 Example
 
 ```javascript
@@ -51,8 +43,6 @@ if (areHtmlElsColliding(box1, box2)) {
 }
 ```
 
----
-
 #### 🚧 Limitations
 
 * Only works with **axis-aligned elements** (rectangular shapes).
@@ -60,6 +50,90 @@ if (areHtmlElsColliding(box1, box2)) {
 
 ---
 
+### 📖 `readBase64Blob(file: File, isDataUrl?: boolean | string): Promise<string>`
+
+Reads a file and returns its Base64 content using the FileReader API, with optional formatting as a full Data URL.
+
+#### 📥 Parameters
+
+* `file` *(File)*: The file object selected by the user (e.g., from an `<input type="file">` element).
+* `isDataUrl` *(boolean | string, optional)*:
+
+  * If `false` *(default)*: returns only the Base64 portion.
+  * If `true`: returns the original Data URL string from `FileReader`.
+  * If a string: treated as a custom MIME type for building a new Data URL.
+
+#### 📤 Returns
+
+* `Promise<string>`: Resolves with either the Base64 string or a complete Data URL, depending on `isDataUrl`.
+
+#### ⚠️ Throws
+
+* `TypeError` if:
+
+  * The result is not a string.
+  * The `isDataUrl` argument is not a boolean or a string.
+* `Error` if:
+
+  * The string is not a valid Base64 or Data URL format.
+  * The MIME string format is invalid.
+* `DOMException` if the file cannot be read by `FileReader`.
+
+#### 🧪 Example
+
+```js
+const input = document.querySelector('input[type="file"]');
+input.addEventListener('change', async () => {
+  try {
+    const base64 = await readBase64Blob(input.files[0], false);
+    console.log(base64); // Logs only the Base64 string
+  } catch (err) {
+    console.error('Error reading file:', err.message);
+  }
+});
+```
+
+---
+
+### 📖 `readFileBlob(file: File, method: 'readAsArrayBuffer' | 'readAsDataURL' | 'readAsText' | 'readAsBinaryString'): Promise<any>`
+
+Reads the contents of a file using a specified FileReader method.
+
+#### 📥 Parameters
+
+* `file` *(File)*: The file object selected by the user (e.g., from an `<input type="file">` element).
+* `method` *(string)*: The FileReader method to use:
+
+  * `'readAsArrayBuffer'` — for binary buffers
+  * `'readAsDataURL'` — for Base64 encoded data URLs
+  * `'readAsText'` — for plain text
+  * `'readAsBinaryString'` — for legacy binary string output
+
+#### 📤 Returns
+
+* `Promise<any>`: Resolves with the file content, depending on the method used.
+
+#### ⚠️ Throws
+
+* `Error` if an unexpected error occurs while resolving the result.
+* `DOMException` if `FileReader` encounters a failure during the read process.
+
+#### 🧪 Example
+
+```js
+const input = document.querySelector('input[type="file"]');
+input.addEventListener('change', async () => {
+  try {
+    const text = await readFileBlob(input.files[0], 'readAsText');
+    console.log(text); // Logs the file content as plain text
+  } catch (err) {
+    console.error('Error reading file:', err.message);
+  }
+});
+```
+
+---
+
 ### 📖 `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.
@@ -250,17 +324,14 @@ Automatically toggles CSS classes on a given element based on the browser window
 
 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
+* ✅ Allows custom **callbacks** for visibility changes (`onVisible`, `onHidden`)
 * ✅ Returns a cleanup function to remove all listeners
 
----
-
 #### 🧪 Usage
 
 ```js
@@ -270,14 +341,14 @@ const uninstall = installWindowHiddenScript({
   element: document.getElementById('app'),
   hiddenClass: 'is-hidden',
   visibleClass: 'is-visible',
+  onVisible: () => console.log('Window is now visible'),
+  onHidden: () => console.log('Window is now hidden'),
 });
 
 // To remove all listeners later
 uninstall();
 ```
 
----
-
 #### ⚙️ Options
 
 | Option         | Type          | Default           | Description                                                       |
@@ -285,8 +356,8 @@ uninstall();
 | `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**     |
-
----
+| `onVisible`    | `() => void`  | `undefined`       | Optional callback fired when the window becomes visible           |
+| `onHidden`     | `() => void`  | `undefined`       | Optional callback fired when the window becomes hidden            |
 
 #### 🔄 Return Value
 
@@ -299,8 +370,6 @@ 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:
@@ -310,13 +379,9 @@ The script handles multiple events depending on browser support:
 * `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**.
-
----
+Immediately after installation, the script simulates a `focus` or `blur` event based on the current visibility state to **ensure the classes and callbacks are applied from the start**.
 
 #### 🧯 Uninstalling
 
@@ -327,8 +392,6 @@ const stopWatching = installWindowHiddenScript(...);
 stopWatching(); // later
 ```
 
----
-
 #### 🎨 CSS Example
 
 ```css

package/docs/v1/basics/text.md

@@ -43,32 +43,24 @@ toTitleCaseLowerFirst('hello world'); // → "hello World"
 
 Enables a keyboard shortcut (`Ctrl + Alt + [key]`) that toggles a CSS class on the `<body>` element. Useful for marking or highlighting AI-generated content dynamically.
 
----
-
 ### 🔤 Syntax
 
 ```js
 addAiMarkerShortcut(key)
 ```
 
----
-
 ### 🧾 Parameters
 
 | Name  | Type     | Default | Description                                                                  |
 | ----- | -------- | ------- | ---------------------------------------------------------------------------- |
 | `key` | `string` | `'a'`   | The character key to use in combination with `Ctrl + Alt`. Case-insensitive. |
 
----
-
 ### ⚙️ Behavior
 
 * ⌨️ When the user presses `Ctrl + Alt + [key]`, the function toggles the CSS class `detect-made-by-ai` on the `<body>` element.
 * 🧠 The shortcut only works in environments where the DOM is available (e.g., browsers).
 * 🚫 If `document.body` is not available when the shortcut is used (e.g., if the DOM hasn't finished loading), a warning is logged and nothing happens.
 
----
-
 ### ❗ Error Handling
 
 Two types of errors are handled:
@@ -85,8 +77,6 @@ Two types of errors are handled:
    [AiMarkerShortcut] <body> element not found. Cannot toggle class. Ensure the DOM is fully loaded when using the shortcut.
    ```
 
----
-
 ### 🧪 Example
 
 ```js
@@ -94,8 +84,6 @@ addAiMarkerShortcut(); // Uses default key 'a'
 // Pressing Ctrl + Alt + A toggles the class "detect-made-by-ai" on <body>
 ```
 
----
-
 ### 🎨 CSS Integration Example
 
 Define the class in your stylesheet to make the toggle visually meaningful:
@@ -107,8 +95,6 @@ body.detect-made-by-ai .ai-content {
 }
 ```
 
----
-
 ### 💡 Tip
 
 To avoid the `<body>` warning, make sure you only call the function after the DOM is ready:
@@ -127,3 +113,47 @@ You can use a pre-built CSS template for the `detect-made-by-ai` class, availabl
 * `/dist/v1/css/aiMarker.css` – The non-minified version for easier readability and customization.
 
 Simply include the appropriate file in your project to style the elements marked with the `detect-made-by-ai` class.
+
+---
+
+## 🎯 `safeTextTrim(text, limit, safeCutZone = 0.6)`
+
+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 a fraction controlled by `safeCutZone`), the cut is made at that space; otherwise, the text is hard-cut at the limit. If the input text is shorter than or equal to the limit, it is returned unchanged.
+
+### 🔤 Syntax
+
+```js
+safeTextTrim(text, limit, safeCutZone = 0.6)
+```
+
+### 🧾 Parameters
+
+| Name          | Type     | Default | Description                                                                                                     |
+| ------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
+| `text`        | `string` | —       | The input text to be trimmed. Must be a string.                                                                 |
+| `limit`       | `number` | —       | The maximum number of characters allowed. Must be a positive integer.                                           |
+| `safeCutZone` | `number` | `0.6`   | A decimal between 0 and 1 representing the minimal acceptable position (fraction of `limit`) to cut at a space. |
+
+### ⚙️ Behavior
+
+* If `text` length is less than or equal to `limit`, returns `text` unchanged.
+* Attempts to cut at the last space character before `limit` but only if it’s within the `safeCutZone` (e.g., at least 60% of the `limit`).
+* If no suitable space is found within the zone, the text is cut strictly at the `limit`.
+* The resulting trimmed text ends with an ellipsis (`"..."`) if it was cut.
+* Leading and trailing whitespace on input is trimmed before processing.
+
+### ❗ Error Handling
+
+Throws a `TypeError` in these cases:
+
+* If `text` is not a string.
+* If `limit` is not a positive integer.
+* If `safeCutZone` is not a number between 0 and 1 (inclusive).
+
+### 🧪 Example
+
+```js
+const longText = "This is a sample sentence that will be trimmed properly.";
+console.log(safeTextTrim(longText, 30));
+// Output: "This is a sample sentence that..."
+```