tiny-essentials 1.20.0 → 1.20.1

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,64 @@ 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`
 
 ---
 
 ## 🧩 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)`
+### `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 +1779,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.1",
   "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",

package/dist/v1/ColorSafeStringify.js

@@ -1,235 +0,0 @@
-/******/ (() => { // webpackBootstrap
-/******/ 	"use strict";
-/******/ 	// The require scope
-/******/ 	var __webpack_require__ = {};
-/******/ 	
-/************************************************************************/
-/******/ 	/* webpack/runtime/define property getters */
-/******/ 	(() => {
-/******/ 		// define getter functions for harmony exports
-/******/ 		__webpack_require__.d = (exports, definition) => {
-/******/ 			for(var key in definition) {
-/******/ 				if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {
-/******/ 					Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });
-/******/ 				}
-/******/ 			}
-/******/ 		};
-/******/ 	})();
-/******/ 	
-/******/ 	/* webpack/runtime/hasOwnProperty shorthand */
-/******/ 	(() => {
-/******/ 		__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))
-/******/ 	})();
-/******/ 	
-/************************************************************************/
-var __webpack_exports__ = {};
-
-// EXPORTS
-__webpack_require__.d(__webpack_exports__, {
-  ColorSafeStringify: () => (/* reexport */ libs_ColorSafeStringify)
-});
-
-;// ./src/v1/libs/ColorSafeStringify.mjs
-/**
- * @typedef {Record<string, string>} ColorsList
- * Represents a mapping of color keys to ANSI escape codes.
- */
-
-class ColorSafeStringify {
-  /**
-   * Currently active color configuration.
-   * @type {ColorsList}
-   */
-  #colors;
-
-  /**
-   * Preset collections (internal and user-defined).
-   * @type {Record<string, ColorsList>}
-   * @static
-   */
-  static #PRESETS = {
-    default: {
-      reset: '\x1b[0m',
-      key: '\x1b[36m', // Cyan (object keys)
-      string: '\x1b[32m', // Green (regular strings)
-      string_url: '\x1b[34m', // Blue (URLs)
-      string_bool: '\x1b[35m', // Magenta (boolean/null in string form)
-      string_number: '\x1b[33m', // Yellow (numbers in string form)
-      number: '\x1b[33m', // Yellow (raw numbers)
-      boolean: '\x1b[35m', // Magenta (true/false)
-      null: '\x1b[1;30m', // Gray (null)
-      special: '\x1b[31m', // Red (e.g., [Circular], [undefined])
-      func: '\x1b[90m', // Dim (function string representations)
-    },
-    solarized: {
-      reset: '\x1b[0m',
-      key: '\x1b[38;5;37m',
-      string: '\x1b[38;5;136m',
-      string_url: '\x1b[38;5;33m',
-      string_bool: '\x1b[38;5;166m',
-      string_number: '\x1b[38;5;136m',
-      number: '\x1b[38;5;136m',
-      boolean: '\x1b[38;5;166m',
-      null: '\x1b[38;5;241m',
-      special: '\x1b[38;5;160m',
-      func: '\x1b[38;5;244m',
-    },
-    monokai: {
-      reset: '\x1b[0m',
-      key: '\x1b[38;5;81m',
-      string: '\x1b[38;5;114m',
-      string_url: '\x1b[38;5;75m',
-      string_bool: '\x1b[38;5;204m',
-      string_number: '\x1b[38;5;221m',
-      number: '\x1b[38;5;221m',
-      boolean: '\x1b[38;5;204m',
-      null: '\x1b[38;5;241m',
-      special: '\x1b[38;5;160m',
-      func: '\x1b[38;5;102m',
-    },
-  };
-
-  /**
-   * Constructs a new instance with an optional base preset or custom override.
-   * @param {ColorsList} [defaultColors] - Optional override for the default color scheme.
-   */
-  constructor(defaultColors = {}) {
-    this.#colors = { ...ColorSafeStringify.#PRESETS.default, ...defaultColors };
-  }
-
-  /**
-   * Internal method to apply ANSI color codes to different parts of a JSON string.
-   * @param {string} str - Raw JSON string to be colorized.
-   * @param {ColorsList} colors - ANSI color mapping to be applied to each JSON element type.
-   * @returns {string} Colorized JSON string.
-   */
-  #colorizeJSON(str, colors) {
-    /** @type {{ marker: string, key: string }[]} */
-    const keyMatches = [];
-
-    // Colorize numeric values
-    str = str.replace(
-      /(?<!")\b(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)\b(?!")/g,
-      `${colors.number}$1${colors.reset}`,
-    );
-
-    // Replace keys with temporary markers for later colorization
-    str = str.replace(/"([^"]+)":/g, (_, key) => {
-      const marker = `___KEY${keyMatches.length}___`;
-      keyMatches.push({ marker, key });
-      return `${marker}:`; // Keep the colon for valid syntax
-    });
-
-    // Replace strings and apply specific colors based on their content
-    str = str.replace(/"(?:\\.|[^"\\])*?"/g, (match) => {
-      const val = match.slice(1, -1); // Remove surrounding quotes
-
-      if (/^(https?|ftp):\/\/[^\s]+$/i.test(val)) {
-        return `${colors.string_url}${match}${colors.reset}`;
-      }
-
-      if (/^(true|false|null)$/.test(val)) {
-        return `${colors.string_bool}${match}${colors.reset}`;
-      }
-
-      if (/^-?\d+(\.\d+)?([eE][+-]?\d+)?$/.test(val)) {
-        return `${colors.string_number}${match}${colors.reset}`;
-      }
-
-      return `${colors.string}${match}${colors.reset}`;
-    });
-
-    // Replace markers with colorized keys
-    for (const { marker, key } of keyMatches) {
-      const regex = new RegExp(marker, 'g');
-      str = str.replace(regex, `${colors.key}"${key}"${colors.reset}`);
-    }
-
-    // Colorize boolean values
-    str = str.replace(/(?<!")\b(true|false)\b(?!")/g, `${colors.boolean}$1${colors.reset}`);
-
-    // Colorize null values
-    str = str.replace(/(?<!")\bnull\b(?!")/g, `${colors.null}null${colors.reset}`);
-
-    // Highlight special placeholder values
-    str = str.replace(/\[Circular\]/g, `${colors.special}[Circular]${colors.reset}`);
-    str = str.replace(/\[undefined\]/g, `${colors.special}[undefined]${colors.reset}`);
-
-    // Colorize function string representations
-    str = str.replace(/"function.*?[^\\]"/gs, `${colors.func}$&${colors.reset}`);
-    return str;
-  }
-
-  /**
-   * Colorizes a JSON string using the active or optionally overridden color set.
-   * @param {string} json - The JSON string to format.
-   * @param {ColorsList} [customColors] - Optional temporary color override.
-   * @returns {string}
-   */
-  colorize(json, customColors = {}) {
-    const colors = { ...this.#colors, ...customColors };
-    return this.#colorizeJSON(json, colors);
-  }
-
-  /**
-   * Returns the currently active color scheme.
-   * @returns {ColorsList}
-   */
-  getColors() {
-    return { ...this.#colors };
-  }
-
-  /**
-   * Updates the current color scheme with a partial override.
-   * @param {Partial<ColorsList>} newColors
-   */
-  updateColors(newColors) {
-    Object.assign(this.#colors, newColors);
-  }
-
-  /**
-   * Resets the current color scheme to the default preset.
-   */
-  resetColors() {
-    this.#colors = { ...ColorSafeStringify.#PRESETS.default };
-  }
-
-  /**
-   * Loads a color preset by name.
-   * @param {string} presetName - Name of the preset to load.
-   * @throws Will throw if the preset doesn't exist.
-   */
-  loadColorPreset(presetName) {
-    const preset = ColorSafeStringify.#PRESETS[presetName];
-    if (!preset) throw new Error(`Preset "${presetName}" not found.`);
-    this.#colors = { ...preset };
-  }
-
-  /**
-   * Saves a new custom color preset.
-   * @param {string} name - Name of the new preset.
-   * @param {ColorsList} colors - ANSI color map to save.
-   */
-  saveColorPreset(name, colors) {
-    ColorSafeStringify.#PRESETS[name] = { ...colors };
-  }
-
-  /**
-   * Returns a list of all available color preset names.
-   * @returns {string[]}
-   */
-  getAvailablePresets() {
-    return Object.keys(ColorSafeStringify.#PRESETS);
-  }
-}
-
-/* harmony default export */ const libs_ColorSafeStringify = (ColorSafeStringify);
-
-;// ./src/v1/build/ColorSafeStringify.mjs
-
-
-
-
-window.ColorSafeStringify = __webpack_exports__.ColorSafeStringify;
-/******/ })()
-;

package/dist/v1/TinyAfterScrollWatcher.js

@@ -1,219 +0,0 @@
-/******/ (() => { // webpackBootstrap
-/******/ 	"use strict";
-/******/ 	// The require scope
-/******/ 	var __webpack_require__ = {};
-/******/ 	
-/************************************************************************/
-/******/ 	/* webpack/runtime/define property getters */
-/******/ 	(() => {
-/******/ 		// define getter functions for harmony exports
-/******/ 		__webpack_require__.d = (exports, definition) => {
-/******/ 			for(var key in definition) {
-/******/ 				if(__webpack_require__.o(definition, key) && !__webpack_require__.o(exports, key)) {
-/******/ 					Object.defineProperty(exports, key, { enumerable: true, get: definition[key] });
-/******/ 				}
-/******/ 			}
-/******/ 		};
-/******/ 	})();
-/******/ 	
-/******/ 	/* webpack/runtime/hasOwnProperty shorthand */
-/******/ 	(() => {
-/******/ 		__webpack_require__.o = (obj, prop) => (Object.prototype.hasOwnProperty.call(obj, prop))
-/******/ 	})();
-/******/ 	
-/************************************************************************/
-var __webpack_exports__ = {};
-
-// EXPORTS
-__webpack_require__.d(__webpack_exports__, {
-  TinyAfterScrollWatcher: () => (/* reexport */ libs_TinyAfterScrollWatcher)
-});
-
-;// ./src/v1/libs/TinyAfterScrollWatcher.mjs
-/**
- * @typedef {(() => void)} FnData - Function with no arguments and no return value
- */
-
-/**
- * A function that handles a scroll event.
- * It receives a standard `Event` object when a scroll occurs.
- *
- * @typedef {(ev: Event) => void} OnScrollFunc
- */
-
-/**
- * A scroll tracker that queues functions to be executed
- * after the user stops scrolling a specific element or the window.
- */
-class TinyAfterScrollWatcher {
-  /** @type {Element|Window} */
-  #scrollTarget;
-
-  /** @type {null|NodeJS.Timeout} */
-  #lastScrollTime = null;
-
-  /** @type {FnData[]} */
-  #afterScrollQueue = [];
-
-  /** @type {number} */
-  #inactivityTime = 100;
-
-  /** @type {Set<OnScrollFunc>} */
-  #externalScrollListeners = new Set();
-
-  /** @type {Set<FnData>} */
-  #onStopListeners = new Set();
-
-  /** @type {boolean} */
-  #destroyed = false;
-
-  /**
-   * @param {Element|Window} scrollTarget - The element or window to track scrolling on
-   * @param {number} [inactivityTime=100] - Time in milliseconds to wait after scroll ends before executing the queue
-   * @throws {TypeError} If scrollTarget is not a valid Element or Window
-   * @throws {TypeError} If inactivityTime is not a positive number
-   */
-  constructor(scrollTarget = window, inactivityTime = 100) {
-    if (!(scrollTarget instanceof Element) && !(scrollTarget instanceof Window))
-      throw new TypeError('scrollTarget must be an Element or the Window object.');
-    this.#scrollTarget = scrollTarget;
-    this._checkTimer = this._checkTimer.bind(this);
-
-    this.#scrollTarget.addEventListener('scroll', this._checkTimer);
-    this.#inactivityTime = inactivityTime;
-  }
-
-  _checkTimer = () => {
-    if (this.#lastScrollTime) clearTimeout(this.#lastScrollTime);
-    this.#lastScrollTime = setTimeout(() => {
-      this.#lastScrollTime = null;
-      this.#checkQueue();
-    }, this.#inactivityTime);
-  };
-
-  /**
-   * Gets the current inactivity time in milliseconds.
-   * @returns {number}
-   */
-  get inactivityTime() {
-    return this.#inactivityTime;
-  }
-
-  /**
-   * Sets a new inactivity time.
-   * Must be a positive number (in milliseconds).
-   * @param {number} value
-   * @throws {Error} If value is not a positive number
-   */
-  set inactivityTime(value) {
-    if (typeof value !== 'number' || value <= 0 || !Number.isFinite(value))
-      throw new Error('inactivityTime must be a positive number in milliseconds.');
-    this.#inactivityTime = value;
-  }
-
-  /**
-   * Continuously checks whether the user has stopped scrolling,
-   * and if so, runs all queued functions.
-   */
-  #checkQueue() {
-    if (this.#destroyed) return;
-    // Runs all onStop first listeners
-    for (const fn of this.#onStopListeners) {
-      if (typeof fn === 'function') fn();
-    }
-
-    // Then execute the queue afterScrollQueue
-    while (this.#afterScrollQueue.length) {
-      const fn = this.#afterScrollQueue.pop();
-      if (typeof fn === 'function') fn();
-    }
-  }
-
-  /**
-   * Adds a function to be executed after scroll has stopped.
-   * The scroll is considered "stopped" after the configured inactivity time.
-   *
-   * @param {() => void} fn - A function to execute once scrolling has stopped.
-   * @throws {TypeError} If the argument is not a function.
-   */
-  doAfterScroll(fn) {
-    if (typeof fn !== 'function') throw new TypeError('Argument must be a function.');
-    this.lastScrollTime = Date.now();
-    this.#afterScrollQueue.push(fn);
-  }
-
-  /**
-   * Registers a function to run once after scrolling has stopped,
-   * before any afterScrollQueue functions.
-   *
-   * @param {FnData} fn - A function to execute after scroll stop.
-   * @throws {TypeError} If the argument is not a function.
-   */
-  onStop(fn) {
-    if (typeof fn !== 'function') throw new TypeError('Argument must be a function.');
-    this.#onStopListeners.add(fn);
-  }
-
-  /**
-   * Removes a previously registered onStop function.
-   *
-   * @param {FnData} fn - The function to remove.
-   * @throws {TypeError} If the argument is not a function.
-   */
-  offStop(fn) {
-    if (typeof fn !== 'function') throw new TypeError('Argument must be a function.');
-    this.#onStopListeners.delete(fn);
-  }
-
-  /**
-   * Registers an external scroll listener on the tracked element.
-   *
-   * @param {OnScrollFunc} fn - The scroll listener to add
-   * @throws {TypeError} If the argument is not a function.
-   */
-  onScroll(fn) {
-    if (typeof fn !== 'function') throw new TypeError('Argument must be a function.');
-    this.#scrollTarget.addEventListener('scroll', fn);
-    this.#externalScrollListeners.add(fn);
-  }
-
-  /**
-   * Removes a previously registered scroll listener from the tracked element.
-   *
-   * @param {OnScrollFunc} fn - The scroll listener to remove
-   * @throws {TypeError} If the argument is not a function.
-   */
-  offScroll(fn) {
-    if (typeof fn !== 'function') throw new TypeError('Argument must be a function.');
-    if (this.#externalScrollListeners.has(fn)) {
-      this.#scrollTarget.removeEventListener('scroll', fn);
-      this.#externalScrollListeners.delete(fn);
-    }
-  }
-
-  /**
-   * Destroys the watcher by removing internal listeners and clearing data.
-   */
-  destroy() {
-    if (this.#destroyed) return;
-    this.#destroyed = true;
-
-    this.#scrollTarget.removeEventListener('scroll', this._checkTimer);
-    for (const fn of this.#externalScrollListeners)
-      this.#scrollTarget.removeEventListener('scroll', fn);
-
-    this.#externalScrollListeners.clear();
-    this.#onStopListeners.clear();
-  }
-}
-
-/* harmony default export */ const libs_TinyAfterScrollWatcher = (TinyAfterScrollWatcher);
-
-;// ./src/v1/build/TinyAfterScrollWatcher.mjs
-
-
-
-
-window.TinyAfterScrollWatcher = __webpack_exports__.TinyAfterScrollWatcher;
-/******/ })()
-;