tiny-essentials 1.13.2 → 1.15.0

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,9 +50,93 @@ 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.
+Reads and parses a JSON file using the FileReader API.
 
 #### 📥 Parameters
 
@@ -205,6 +279,32 @@ getHtmlElBordersWidth(el: Element): HtmlElBoxSides
 
 ---
 
+### 👁️ `isInViewport(element)`
+
+🔍 Checks if an element is **partially visible** in the current viewport.
+
+```js
+isInViewport(element: HTMLElement): boolean
+```
+
+* `element`: The DOM element to check.
+* **Returns**: `true` if the element is at least partially visible; `false` otherwise.
+
+---
+
+### ✅ `isScrolledIntoView(element)`
+
+📦 Checks if an element is **fully visible** (top and bottom) within the viewport.
+
+```js
+isScrolledIntoView(element: HTMLElement): boolean
+```
+
+* `element`: The DOM element to check.
+* **Returns**: `true` if the entire element is within the viewport; `false` otherwise.
+
+---
+
 ### 🔳 `getHtmlElBorders(el)`
 
 📐 Returns the total **border size** of an element using `border{Side}` shorthand values from computed styles.
@@ -250,17 +350,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 +367,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 +382,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 +396,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 +405,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 +418,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..."
+```

package/docs/v1/libs/TinyNotifications.md

@@ -0,0 +1,189 @@
+# 📣 TinyNotifications
+
+> A utility class to manage browser notifications with sound, custom icons, text truncation, and click behavior.
+
+---
+
+## 🚀 Features
+
+* ✅ Request and manage user permission for notifications
+* 🔔 Play a sound when a notification is shown
+* 🖼️ Support for default avatar/icon
+* ✂️ Automatic body text truncation
+* 💥 Strong validation with `TypeError` and runtime checks
+* ❗ Prevents use of `send()` before permission request
+
+---
+
+## 🏗️ Constructor
+
+```js
+new TinyNotifications(options?)
+```
+
+### Parameters
+
+| Name             | Type                                      | Default | Description                                        |
+| ---------------- | ----------------------------------------- | ------- | -------------------------------------------------- |
+| `audio`          | `string` \| `HTMLAudioElement` \| `null`  | `null`  | Sound to be played with the notification           |
+| `defaultIcon`    | `string` \| `null`                        | `null`  | Default icon to use in notifications               |
+| `bodyLimit`      | `number`                                  | `100`   | Maximum number of characters in body text          |
+| `defaultOnClick` | `(this: Notification, evt: Event) => any` | `fn`    | Function executed when the notification is clicked |
+
+### Throws
+
+* `TypeError` if any parameter is of invalid type.
+
+---
+
+## 🧠 Methods
+
+### 🔐 `requestPerm()`
+
+```js
+requestPerm(): Promise<boolean>
+```
+
+Requests permission from the browser to send notifications.
+
+* Sets internal `#allowed` and `#permissionRequested` flags.
+* Must be called before using `send()`.
+
+**Returns:** `Promise<boolean>` — `true` if permission was granted.
+
+---
+
+### ⚙️ `isCompatible()`
+
+```js
+isCompatible(): boolean
+```
+
+Checks if the current browser supports the Notification API.
+
+**Returns:** `true` or `false`
+
+---
+
+### 📤 `send(title, config?)`
+
+```js
+send(title: string, config?: NotificationOptions): Notification | null
+```
+
+Sends a notification to the user with optional configuration.
+Truncates long body texts and plays a sound if set.
+
+#### Parameters
+
+* `title`: *(string)* — Title of the notification
+* `config`: *(object)* — Optional notification settings (`body`, `icon`, `vibrate`, etc.)
+
+#### Throws
+
+* `Error` if `requestPerm()` was never called
+* `TypeError` if `title` is not a string or `config` is not an object
+
+#### Returns
+
+* `Notification` instance if allowed
+* `null` if permission was denied
+
+---
+
+## 📥 Getters & Setters
+
+### 📌 `wasPermissionRequested()`
+
+```js
+wasPermissionRequested(): boolean
+```
+
+Checks if `requestPerm()` was called.
+
+---
+
+### 🟢 `isAllowed()`
+
+```js
+isAllowed(): boolean
+```
+
+Checks if permission has been granted.
+
+---
+
+### 🔊 `getAudio()` / `setAudio(value)`
+
+```js
+getAudio(): HTMLAudioElement | null
+setAudio(value: HTMLAudioElement | string | null)
+```
+
+Set or retrieve the notification sound.
+**Throws:** `TypeError` if invalid type is used.
+
+---
+
+### 📏 `getBodyLimit()` / `setBodyLimit(value)`
+
+```js
+getBodyLimit(): number
+setBodyLimit(value: number)
+```
+
+Set or retrieve the maximum number of characters in the notification body.
+**Throws:** `TypeError` if value is not a non-negative number.
+
+---
+
+### 🖼️ `getDefaultAvatar()` / `setDefaultAvatar(value)`
+
+```js
+getDefaultAvatar(): string | null
+setDefaultAvatar(value: string | null)
+```
+
+Get or set the default icon for notifications.
+**Throws:** `TypeError` if value is not a string or `null`.
+
+---
+
+### 🖱️ `getDefaultOnClick()` / `setDefaultOnClick(value)`
+
+```js
+getDefaultOnClick(): (this: Notification, evt: Event) => any
+setDefaultOnClick(value: function)
+```
+
+Set or retrieve the default click handler for all notifications.
+**Throws:** `TypeError` if value is not a function.
+
+---
+
+## 📦 Example
+
+```js
+import TinyNotifications from './TinyNotifications.js';
+
+const notify = new TinyNotifications({
+  audio: '/sounds/ping.mp3',
+  defaultIcon: '/img/icon.png',
+  bodyLimit: 80
+});
+
+await notify.requestPerm();
+
+notify.send('Hello World!', {
+  body: 'This message will be truncated if too long.',
+  vibrate: [100, 50, 100]
+});
+```
+
+---
+
+## 🧪 Safety Notes
+
+* Always call `requestPerm()` **before** using `send()`
+* Invalid or unsafe inputs throw strong errors
+* Compatible with all modern browsers that support `Notification` API

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "tiny-essentials",
-  "version": "1.13.2",
+  "version": "1.15.0",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",
     "test:js": "npx babel-node test/index.js",
     "test:cjs": "node test/index.cjs",
     "test:mjs": "node test/index.mjs",
+    "test:mjs:web": "node test/express.mjs",
     "test:mjs:promisequeue": "node test/index.mjs promiseQueue",
     "test:mjs:objtype": "node test/index.mjs objType",
     "test:mjs:jsoncolor": "node test/index.mjs colorStringify",
@@ -97,11 +98,13 @@
     "byte-length": "^1.0.2",
     "clone": "^2.1.2",
     "compare-versions": "^6.1.1",
+    "esbuild": "^0.25.5",
     "express": "^5.1.0",
     "firebase": "^11.7.1",
     "firebase-functions": "^6.3.2",
     "latest-version": "^9.0.0",
     "lodash": "^4.17.21",
+    "marked": "^16.0.0",
     "md5": "^2.3.0",
     "moment": "^2.30.1",
     "moment-timezone": "^0.5.48",
@@ -113,7 +116,7 @@
     "rollup": "^4.40.0",
     "rollup-preserve-directives": "^1.1.3",
     "safe-stable-stringify": "^2.5.0",
-    "sass": "^1.87.0",
+    "sass": "^1.89.2",
     "tinycolor2": "^1.6.0",
     "tslib": "^2.8.1",
     "type-fest": "^4.40.0",