tiny-essentials 1.20.0 → 1.20.2

package/dist/v1/libs/TinyIframeEvents.cjs

@@ -261,7 +261,8 @@ class TinyIframeEvents {
    * @throws {TypeError} If the value is not a string.
    */
   set secretEventName(name) {
-    if (typeof name !== 'string') throw new TypeError('TinyIframeEvents: secretEventName must be a string.');
+    if (typeof name !== 'string')
+      throw new TypeError('TinyIframeEvents: secretEventName must be a string.');
     this.#secretEventName = name;
   }
 

package/dist/v1/libs/TinyNewWinEvents.cjs

@@ -253,7 +253,8 @@ class TinyNewWinEvents {
    * @throws {TypeError} If the value is not a string.
    */
   set readyEventName(name) {
-    if (typeof name !== 'string') throw new TypeError('TinyNewWinEvents: readyEventName must be a string.');
+    if (typeof name !== 'string')
+      throw new TypeError('TinyNewWinEvents: readyEventName must be a string.');
     this.#readyEventName = name;
   }
 
@@ -271,7 +272,8 @@ class TinyNewWinEvents {
    * @throws {TypeError} If the value is not a string.
    */
   set routeEventName(name) {
-    if (typeof name !== 'string') throw new TypeError('TinyNewWinEvents: routeEventName must be a string.');
+    if (typeof name !== 'string')
+      throw new TypeError('TinyNewWinEvents: routeEventName must be a string.');
     this.#routeEventName = name;
   }
 

package/docs/v1/basics/html.md

@@ -142,11 +142,11 @@ saveJsonFile('yasmin.json', data);
 
 ### 🌐 `fetchTemplate(...)`
 
-Loads data from a remote URL using Fetch API, with support for custom HTTP methods, retries, timeouts, headers, and even external abort controllers.
+Loads data from a remote URL using the Fetch API, with support for custom HTTP methods, retries, timeouts, headers, and even external abort controllers.
 
 #### 📥 Parameters
 
-* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
+* `url` *(string)*: The full URL to fetch from (must start with `http://`, `https://`, `/`, `./`, or `../`).
 * `options` *(object)* *(optional)*:
 
   * `signal` *(`AbortSignal` | `null`)*: Custom abort signal.
@@ -156,42 +156,88 @@ Loads data from a remote URL using Fetch API, with support for custom HTTP metho
   * `headers` *(object)*: Additional headers to include in the request.
   * `body` *(object)*: Request body. If the value is a plain object, it will be automatically stringified as JSON.
 
-#### `fetchJson(url, options?): Promise<any[] | Record<string | number | symbol, unknown>>`
+#### `fetchJson(url, options?)`
 
-Loads and parses a JSON.
+Loads and parses a remote JSON file.
 
-* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
-* `options` *(object)* *(optional)*:
+* **Parameters**:
 
-#### `fetchBlob(url, options?): Promise<any[] | Record<string | number | symbol, unknown>>`
+  * `url` *(string)*: URL to fetch the JSON from.
+  * `options` *(object)* *(optional)*: Same structure as `fetchTemplate`.
 
-Loads a remote file as a Blob.
+* **Returns**:
+  `Promise<any[] | Record<string | number | symbol, unknown>>` — The parsed JSON data.
 
-* `url` *(string)*: The full URL to fetch JSON from (must start with `http://`, `https://`, `/`, `./`, or `../`).
-* `allowedMimeTypes` Optional list of accepted MIME types (e.g., ['image/jpeg']).
-* `options` *(object)* *(optional)*:
+* **Throws**:
 
-##### `signal` (`AbortSignal` | `null`) — *optional*
+  * `Error` if the fetch fails, times out, or returns invalid JSON.
+  * `Error` if the `Content-Type` is not `application/json`.
 
-Custom abort signal. If set:
+---
 
-* The internal timeout mechanism is **disabled**
-* Retry logic is **disabled**
-* Abortion is handled externally
+#### `fetchBlob(url, allowedMimeTypes?, options?)`
 
-#### 📤 Returns
+Loads a remote file as a Blob object.
+
+* **Parameters**:
+
+  * `url` *(string)*: URL of the remote file.
+  * `allowedMimeTypes` *(string\[])* *(optional)*: List of accepted MIME types.
+  * `options` *(object)* *(optional)*: Same structure as `fetchTemplate`.
+
+* **Returns**:
+  `Promise<Blob>`
+
+* **Throws**:
+
+  * `Error` if fetch fails or the MIME type is not allowed.
+  * `Error` if the response is not OK.
+
+---
+
+#### `fetchText(url, allowedMimeTypes?, options?)`
+
+Loads a remote file as **plain text** using the Fetch API.
+
+* **Parameters**:
+
+  * `url` *(string)*: Full URL of the file to fetch.
+  * `allowedMimeTypes` *(string\[])* *(optional)*: List of accepted MIME types (e.g., `['text/plain']`).
+  * `options` *(object)* *(optional)*: Same structure as `fetchTemplate`.
+
+* **Returns**:
+  `Promise<string>` — The content of the file as a text string.
+
+* **Throws**:
 
-* `Promise<any>`: Resolves with the parsed JSON data.
+  * `Error` if the fetch fails or the response is not OK.
+  * `Error` if the MIME type is not in the allowed list (when provided).
+
+---
+
+#### 📤 Returns (for all helpers)
+
+* `Promise<any>` — Depends on the function:
+
+  * `fetchJson`: Parsed JSON
+  * `fetchBlob`: File as a Blob
+  * `fetchText`: File as plain text
+
+---
 
 #### ⚠️ Throws
 
-* `Error` if the fetch fails or exceeds the timeout
-* `Error` if the response is not `application/json`
-* `Error` if the result is not a plain JSON object
+All functions may throw the following:
+
+* `Error` if the request fails or the response times out.
+* `Error` if `Content-Type` does not match expected type (JSON, Blob, Text, etc).
+* `Error` if response is malformed or rejected by MIME type filter.
+
+---
 
 #### 🧠 Tip
 
-If you pass your own `signal`, this disables both `timeout` and `retries`. Use it when you're managing cancellation manually (e.g. in UI components or async workflows).
+Using a custom `signal` disables both `timeout` and `retries`. This is useful when you want to handle cancellation yourself, like in user interfaces or abortable workflows.
 
 #### 🧪 Example
 
@@ -210,6 +256,16 @@ const data = await fetchJson('https://api.example.com/data', {
 });
 ```
 
+```js
+const text = await fetchText('/example.txt', ['text/plain'], {
+  timeout: 3000,
+});
+```
+
+```js
+const blob = await fetchBlob('/image.jpg', ['image/jpeg']);
+```
+
 ---
 
 ### 📦 `HtmlElBoxSides` Type

package/docs/v1/basics/simpleMath.md

@@ -36,19 +36,37 @@ ruleOfThree(2, 6, 3, true); // → 4
 
 ### 💯 `getSimplePerc(price, percentage)`
 
-**Calculates the percentage of a given base value.**
+**Calculates the actual value that corresponds to a percentage of a base number.**
 
-- **`price`**: The base value (for example, the original price of an item).
-- **`percentage`**: The percentage to calculate from the base value.
+Unlike `getPercentage`, which tells how much something represents in percent,  
+this function tells how much a given percentage *is worth* in actual value.
 
-#### Example:
+- **`price`**: The base number to apply the percentage to.  
+- **`percentage`**: The percentage to calculate from the base.
 
+#### Example:
 ```js
 getSimplePerc(200, 15); // → 30
 ```
 
 ---
 
+### 📊 `getPercentage(part, total)`
+
+**Calculates how much percent a partial value represents of the total value.**
+
+This function is useful when you want to know what fraction of the total a value is, in percentage form.
+
+- **`part`**: The partial value to compare.  
+- **`total`**: The total or maximum value.
+
+#### Example:
+```js
+getPercentage(5, 100); // → 5
+```
+
+---
+
 ### 🎂 `getAge(timeData, now)`
 
 **Calculates the age based on a birthdate.**

package/docs/v1/libs/TinyHtml.md

@@ -310,6 +310,40 @@ HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | HTMLOptionElement
 
 ---
 
+## 🔨 Element Creation
+
+### `TinyHtml.createFrom(tagName, attrs?)`
+
+Creates a new `TinyHtml` element from a given tag name and optional attributes.
+
+* **Parameters**:
+
+  * `tagName` *(string)* — The HTML tag name (e.g., `'div'`, `'span'`, `'button'`).
+  * `attrs` *(object)* — *(optional)* Key-value pairs representing HTML attributes.
+
+* **Returns**: `TinyHtml` — A new `TinyHtml` instance representing the created element.
+
+* **Throws**:
+
+  * `TypeError` — If `tagName` is not a string.
+  * `TypeError` — If `attrs` is defined but not a plain object.
+
+### 💡 Example
+
+```js
+const div = TinyHtml.createFrom('div', { class: 'container' });
+const span = TinyHtml.createFrom('span', { id: 'my-span', title: null });
+```
+
+The method can also be aliased for convenience:
+
+```js
+const createElement = TinyHtml.createFrom;
+const button = createElement('button', { type: 'submit', class: 'btn' });
+```
+
+---
+
 ## 🔎 Static DOM Selectors
 
 These methods wrap native DOM query methods and return results as `TinyHtml` instances for consistency.
@@ -377,7 +411,7 @@ Finds the first element by CSS selector.
 ### `TinyHtml.queryAll(selector)`
 Finds all elements by CSS selector.
 
-- **Returns**: `TinyHtml[]`
+- **Returns**: `TinyHtml`
 
 ---
 
@@ -393,38 +427,204 @@ Selects an element by ID.
 ### `TinyHtml.getByClassName(selector)`
 Finds elements by class name.
 
-- **Returns**: `TinyHtml[]`
+- **Returns**: `TinyHtml`
 
 ---
 
 ### `TinyHtml.getByName(selector)`
 Finds elements by `name` attribute.
 
-- **Returns**: `TinyHtml[]`
+- **Returns**: `TinyHtml`
 
 ---
 
 ### `TinyHtml.getByTagNameNS(localName, namespaceURI?)`
 Finds elements by tag name in a namespace (defaults to XHTML).
 
-- **Returns**: `TinyHtml[]`
+- **Returns**: `TinyHtml`
+
+---
+
+## 📑 HTML Parser
+
+### Type Definition
+
+A parsed HTML element represented as an array:
+
+```ts
+type HtmlParsed = [
+  tagName: string,                 // e.g., 'div', 'span', 'img'
+  attributes: Record<string, string>, // Key-value map of all element attributes
+  ...children: (string | HtmlParsed)[] // Nested elements or text content
+];
+```
+
+---
+
+### `fetchHtmlFile(url, ops?)`
+
+Fetches an HTML file from a URL and parses it into a JSON-like structure.
+
+```ts
+static async fetchHtmlFile(url: string | URL | Request, ops?: RequestInit): Promise<HtmlParsed[]>
+```
+
+* **url**: The URL of the HTML file.
+* **ops**: (Optional) `fetch()` options (method, headers, etc).
+* **Returns**: Promise of parsed JSON structure (`HtmlParsed[]`).
+* Throws if content-type is not `text/html`.
+
+---
+
+### `fetchHtmlNodes(url, ops?)`
+
+Fetches an HTML file and returns it as DOM nodes.
+
+```ts
+static async fetchHtmlNodes(url: string, ops?: RequestInit): Promise<(HTMLElement | Text)[]>
+```
+
+* **Returns**: Array of real DOM nodes (`HTMLElement | Text`).
+
+---
+
+### `fetchHtmlTinyElems(url, ops?)`
+
+Fetches HTML and converts it into an array of `TinyHtml` instances.
+
+```ts
+static async fetchHtmlTinyElems(url: string, ops?: RequestInit): Promise<TinyHtml[]>
+```
+
+* **Returns**: `TinyHtml[]` (custom wrapper elements).
+
+---
+
+### `templateToJson(template)`
+
+Converts the contents of a `<template>` to JSON format.
+
+```ts
+static templateToJson(template: HTMLTemplateElement): HtmlParsed[]
+```
+
+* **Returns**: Structured JSON representation (`HtmlParsed[]`).
+
+---
+
+### `templateToNodes(template)`
+
+Converts `<template>` content into real DOM nodes.
+
+```ts
+static templateToNodes(template: HTMLTemplateElement): (Element | Text)[]
+```
+
+* **Returns**: Cloned nodes excluding comments.
+* Throws error if unexpected node types are encountered.
+
+---
+
+### `templateToTinyElems(template)`
+
+Converts a `<template>` into `TinyHtml` instances.
+
+```ts
+static templateToTinyElems(template: HTMLTemplateElement): TinyHtml[]
+```
+
+* **Returns**: Array of `TinyHtml` objects.
+
+---
+
+### `htmlToJson(htmlString)`
+
+Parses an HTML string into structured JSON (`HtmlParsed[]`).
+
+```ts
+static htmlToJson(htmlString: string): HtmlParsed[]
+```
+
+* **Returns**: Parsed representation as an array of `[tag, attributes, ...children]`.
+
+---
+
+### `jsonToNodes(jsonArray)`
+
+Converts parsed JSON back into actual DOM nodes.
+
+```ts
+static jsonToNodes(jsonArray: HtmlParsed[]): (HTMLElement | Text)[]
+```
+
+* **Returns**: Array of DOM elements/text nodes.
+* Skips comments.
+
+---
+
+### `jsonToTinyElems(jsonArray)`
+
+Converts parsed JSON back into `TinyHtml` instances.
+
+```ts
+static jsonToTinyElems(jsonArray: HtmlParsed[]): TinyHtml[]
+```
+
+* **Returns**: TinyHtml-wrapped elements.
+
+---
+
+💡 **Tip**: All conversion methods rely on a consistent internal format (`HtmlParsed[]`). That means you can seamlessly switch between representations (JSON ⇄ DOM ⇄ TinyHtml)!
 
 ---
 
 ## 🧩 Internal Element Access
 
-### `get()`
+### `exists(index)`
+Checks whether the element exists at the given index.
+
+- **Returns**: `boolean`
+
+---
+
+### `get(index)`
 Returns the raw DOM element associated with this instance.
 
 - **Returns**: `ConstructorElValues`
 
 ---
 
-### `_getElement(where)`
+### `size`
+Returns the number of elements currently stored in the internal element list.
+
+- **Returns**: `number`
+
+---
+
+### `extract(index)`
+Extracts a single DOM element from the internal list at the specified index.
+
+- **Returns**: `TinyHtml`
+
+---
+
+### `getAll()`
+Returns the current targets held by this instance.
+
+- **Returns**: `ConstructorElValues[]`
+
+---
+
+### `_getElement(where, index)`
 Safely returns the element with error checking.
 
 ---
 
+### `_getElements(where)`
+Returns the current Elements held by this instance.
+
+---
+
 ## 🛠️ Static Pre-Validation Utilities
 
 These methods normalize, validate, and prepare elements/nodes before operations. They're internal and mainly used inside the class.
@@ -1719,6 +1919,68 @@ TinyHtml.hasScroll(element);
 
 ---
 
+## 🧠 Property Name Normalization
+
+The object `TinyHtml.propFix` maps HTML attribute names (as strings) to their corresponding JavaScript DOM property names. This works similarly to jQuery’s `propFix`.
+
+```js
+TinyHtml.propFix['for'];   // "htmlFor"
+TinyHtml.propFix['class']; // "className"
+```
+
+⚠️ **Do not modify** the internal `#propFix` object directly. Instead, use `TinyHtml.propFix` (the public proxy) to ensure the reverse mapping in `TinyHtml.attrFix` stays in sync.
+
+### ✍️ Adding a New Property Mapping
+
+To add a new property normalization:
+
+```js
+TinyHtml.propFix['readonly'] = 'readOnly';
+```
+
+This will automatically make this available:
+
+```js
+TinyHtml.attrFix['readOnly']; // "readonly"
+```
+
+---
+
+## 🔁 Attribute ↔ Property Mapping
+
+### 🧭 `TinyHtml.getPropName(name)`
+
+Normalizes an HTML attribute name to its corresponding DOM property name.
+
+```js
+TinyHtml.getPropName('for');   // "htmlFor"
+TinyHtml.getPropName('class'); // "className"
+TinyHtml.getPropName('title'); // "title" (not mapped, returns input)
+```
+
+Useful when setting DOM properties programmatically.
+
+### 🧭 `TinyHtml.getAttrName(name)`
+
+Converts a DOM property name back to its equivalent HTML attribute name.
+
+```js
+TinyHtml.getAttrName('htmlFor');   // "for"
+TinyHtml.getAttrName('className'); // "class"
+TinyHtml.getAttrName('title');     // "title" (not mapped, returns input)
+```
+
+Useful when serializing an element back to HTML or attributes.
+
+### 🔄 Behind the Scenes
+
+* `TinyHtml.propFix` (public) is a proxy of the internal `#propFix` object.
+* `TinyHtml.attrFix` is auto-generated from `#propFix`, mapping values back in reverse.
+
+These mappings are kept **in sync automatically** whenever you assign a new property to `TinyHtml.propFix`.
+
+---
+
 ## 🎨 CSS Property Aliases (`cssPropAliases`)
 
 TinyHtml provides automatic conversion between `camelCase` and `kebab-case` style properties to simplify working with inline styles in HTML elements.

package/package.json

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