tiny-essentials 1.22.13 → 1.22.14

package/dist/v1/libs/TinyHtml.cjs

@@ -871,6 +871,17 @@ class TinyHtml {
     return new TinyHtml(elems);
   }
 
+  /**
+   * Creates an HTMLElement or TextNode from an HTML string.
+   * Supports both elements and plain text.
+   *
+   * @param {string} htmlString - The HTML string to convert.
+   * @returns {TinyHtml<Element>} - A single HTMLElement or TextNode.
+   */
+  static createFromHtml(htmlString) {
+    return TinyHtml.createFromHTML(htmlString);
+  }
+
   ///////////////////////////////////////////////////
   // TITLE: Query Script
 
@@ -3723,6 +3734,48 @@ class TinyHtml {
 
   // TITLE: Animate DOM (Data)
 
+  /** @type {string} */
+  #mainDisplay = 'block';
+
+/**
+ * Gets the current display value.
+ * @returns {string}
+ */
+  get mainDisplay() {
+    return this.#mainDisplay;
+  }
+
+/**
+ * Sets the display value.
+ * @param {string} value
+ * @throws {TypeError} If the value is not a string.
+ */
+  set mainDisplay(value) {
+    if (typeof value !== 'string') throw new TypeError('mainDisplay must be a string.');
+    this.#mainDisplay = value;
+  }
+
+  /** @type {string} */
+  static #defaultDisplay = 'block';
+
+/**
+ * Gets the default display value.
+ * @returns {string}
+ */
+  static get defaultDisplay() {
+    return TinyHtml.#defaultDisplay;
+  }
+
+/**
+ * Sets the default display value.
+ * @param {string} value
+ * @throws {TypeError} If the value is not a string.
+ */
+  static set defaultDisplay(value) {
+    if (typeof value !== 'string') throw new TypeError('defaultDisplay must be a string.');
+    TinyHtml.#defaultDisplay = value;
+  }
+
   /**
    * Retrieves stored animation data for a given element and key.
    * If no data exists yet, initializes storage for that element.
@@ -4696,11 +4749,12 @@ class TinyHtml {
    * @param {TinyHtmlElement|TinyHtmlElement[]} el - Target element(s) to fade.
    * @param {number} opacity - Final opacity value (between 0 and 1).
    * @param {number | KeyframeAnimationOptions | string} [ops] - Duration or animation options.
+   * @param {string} [mainDisplay=TinyHtml.#defaultDisplay] - Sets the main display value.
    * @returns {StyleFxResult}
    * @throws {TypeError} If opacity is not a number between 0 and 1.
    * @throws {TypeError} If ops is not number|string|object when provided.
    */
-  static fadeTo(el, opacity, ops) {
+  static fadeTo(el, opacity, ops, mainDisplay = TinyHtml.#defaultDisplay) {
     if (typeof opacity !== 'number' || isNaN(opacity) || opacity < 0 || opacity > 1)
       throw new TypeError('fadeTo: opacity must be a number between 0 and 1.');
 
@@ -4728,7 +4782,7 @@ class TinyHtml {
       if (isHidden) {
         // Ensure element is visible (like jQuery does before fading)
         const display = TinyHtml.getAnimateData(elem, `origdisplay`);
-        elem.style.display = typeof display === 'string' ? display : 'block';
+        elem.style.display = typeof display === 'string' ? display : mainDisplay;
       }
 
       /** @type {AnimationSfxData} */
@@ -4752,12 +4806,13 @@ class TinyHtml {
    *
    * @param {number} opacity - Final opacity value (between 0 and 1).
    * @param {number | KeyframeAnimationOptions | string} [ops] - Duration or animation options.
+   * @param {string} [mainDisplay=this.#mainDisplay] - Sets the main display value.
    * @returns {StyleFxResult}
    * @throws {TypeError} If opacity is not a number between 0 and 1.
    * @throws {TypeError} If ops is not number|string|object when provided.
    */
-  fadeTo(opacity, ops) {
-    return TinyHtml.fadeTo(this, opacity, ops);
+  fadeTo(opacity, ops, mainDisplay = this.#mainDisplay) {
+    return TinyHtml.fadeTo(this, opacity, ops, mainDisplay);
   }
 
   ///////////////////////////////////////////////////////////////

package/dist/v1/libs/TinyHtml.d.mts

@@ -510,6 +510,14 @@ declare class TinyHtml<TinyHtmlT extends TinyHtmlConstructor> {
      * @returns {TinyHtml<Element>} - A single HTMLElement or TextNode.
      */
     static createFromHTML(htmlString: string): TinyHtml<Element>;
+    /**
+     * Creates an HTMLElement or TextNode from an HTML string.
+     * Supports both elements and plain text.
+     *
+     * @param {string} htmlString - The HTML string to convert.
+     * @returns {TinyHtml<Element>} - A single HTMLElement or TextNode.
+     */
+    static createFromHtml(htmlString: string): TinyHtml<Element>;
     /**
      * Queries the document for the first element matching the CSS selector and wraps it in a TinyHtml instance.
      *
@@ -1442,6 +1450,19 @@ declare class TinyHtml<TinyHtmlT extends TinyHtmlConstructor> {
      * @returns {number}
      */
     static outerWidth(el: TinyElementAndWinAndDoc, includeMargin?: boolean): number;
+    /** @type {string} */
+    static "__#8@#defaultDisplay": string;
+    /**
+     * Sets the default display value.
+     * @param {string} value
+     * @throws {TypeError} If the value is not a string.
+     */
+    static set defaultDisplay(value: string);
+    /**
+     * Gets the default display value.
+     * @returns {string}
+     */
+    static get defaultDisplay(): string;
     /**
      * Retrieves stored animation data for a given element and key.
      * If no data exists yet, initializes storage for that element.
@@ -1815,11 +1836,12 @@ declare class TinyHtml<TinyHtmlT extends TinyHtmlConstructor> {
      * @param {TinyHtmlElement|TinyHtmlElement[]} el - Target element(s) to fade.
      * @param {number} opacity - Final opacity value (between 0 and 1).
      * @param {number | KeyframeAnimationOptions | string} [ops] - Duration or animation options.
+     * @param {string} [mainDisplay=TinyHtml.#defaultDisplay] - Sets the main display value.
      * @returns {StyleFxResult}
      * @throws {TypeError} If opacity is not a number between 0 and 1.
      * @throws {TypeError} If ops is not number|string|object when provided.
      */
-    static fadeTo(el: TinyHtmlElement | TinyHtmlElement[], opacity: number, ops?: number | KeyframeAnimationOptions | string): StyleFxResult;
+    static fadeTo(el: TinyHtmlElement | TinyHtmlElement[], opacity: number, ops?: number | KeyframeAnimationOptions | string, mainDisplay?: string): StyleFxResult;
     /**
      * Gets the offset of the element relative to the document.
      * @param {TinyElement} el - Target element.
@@ -3272,6 +3294,17 @@ declare class TinyHtml<TinyHtmlT extends TinyHtmlConstructor> {
      * @returns {number}
      */
     outerWidth(includeMargin?: boolean): number;
+    /**
+     * Sets the display value.
+     * @param {string} value
+     * @throws {TypeError} If the value is not a string.
+     */
+    set mainDisplay(value: string);
+    /**
+     * Gets the current display value.
+     * @returns {string}
+     */
+    get mainDisplay(): string;
     /**
      * Applies style-based effects (slide, fade) to one or more elements.
      * Converts abstract effect definitions (e.g., `{ height: "show" }`)
@@ -3345,11 +3378,12 @@ declare class TinyHtml<TinyHtmlT extends TinyHtmlConstructor> {
      *
      * @param {number} opacity - Final opacity value (between 0 and 1).
      * @param {number | KeyframeAnimationOptions | string} [ops] - Duration or animation options.
+     * @param {string} [mainDisplay=this.#mainDisplay] - Sets the main display value.
      * @returns {StyleFxResult}
      * @throws {TypeError} If opacity is not a number between 0 and 1.
      * @throws {TypeError} If ops is not number|string|object when provided.
      */
-    fadeTo(opacity: number, ops?: number | KeyframeAnimationOptions | string): StyleFxResult;
+    fadeTo(opacity: number, ops?: number | KeyframeAnimationOptions | string, mainDisplay?: string): StyleFxResult;
     /**
      * Gets the offset of the element relative to the document.
      * @returns {{top: number, left: number}}

package/dist/v1/libs/TinyHtml.mjs

@@ -752,6 +752,16 @@ class TinyHtml {
             throw new Error('The HTML string must contain a valid HTML element.');
         return new TinyHtml(elems);
     }
+    /**
+     * Creates an HTMLElement or TextNode from an HTML string.
+     * Supports both elements and plain text.
+     *
+     * @param {string} htmlString - The HTML string to convert.
+     * @returns {TinyHtml<Element>} - A single HTMLElement or TextNode.
+     */
+    static createFromHtml(htmlString) {
+        return TinyHtml.createFromHTML(htmlString);
+    }
     ///////////////////////////////////////////////////
     // TITLE: Query Script
     /**
@@ -3329,6 +3339,44 @@ class TinyHtml {
     }
     //////////////////////////////////////////////////
     // TITLE: Animate DOM (Data)
+    /** @type {string} */
+    #mainDisplay = 'block';
+    /**
+     * Gets the current display value.
+     * @returns {string}
+     */
+    get mainDisplay() {
+        return this.#mainDisplay;
+    }
+    /**
+     * Sets the display value.
+     * @param {string} value
+     * @throws {TypeError} If the value is not a string.
+     */
+    set mainDisplay(value) {
+        if (typeof value !== 'string')
+            throw new TypeError('mainDisplay must be a string.');
+        this.#mainDisplay = value;
+    }
+    /** @type {string} */
+    static #defaultDisplay = 'block';
+    /**
+     * Gets the default display value.
+     * @returns {string}
+     */
+    static get defaultDisplay() {
+        return TinyHtml.#defaultDisplay;
+    }
+    /**
+     * Sets the default display value.
+     * @param {string} value
+     * @throws {TypeError} If the value is not a string.
+     */
+    static set defaultDisplay(value) {
+        if (typeof value !== 'string')
+            throw new TypeError('defaultDisplay must be a string.');
+        TinyHtml.#defaultDisplay = value;
+    }
     /**
      * Retrieves stored animation data for a given element and key.
      * If no data exists yet, initializes storage for that element.
@@ -4217,11 +4265,12 @@ class TinyHtml {
      * @param {TinyHtmlElement|TinyHtmlElement[]} el - Target element(s) to fade.
      * @param {number} opacity - Final opacity value (between 0 and 1).
      * @param {number | KeyframeAnimationOptions | string} [ops] - Duration or animation options.
+     * @param {string} [mainDisplay=TinyHtml.#defaultDisplay] - Sets the main display value.
      * @returns {StyleFxResult}
      * @throws {TypeError} If opacity is not a number between 0 and 1.
      * @throws {TypeError} If ops is not number|string|object when provided.
      */
-    static fadeTo(el, opacity, ops) {
+    static fadeTo(el, opacity, ops, mainDisplay = TinyHtml.#defaultDisplay) {
         if (typeof opacity !== 'number' || isNaN(opacity) || opacity < 0 || opacity > 1)
             throw new TypeError('fadeTo: opacity must be a number between 0 and 1.');
         if (ops !== undefined &&
@@ -4240,7 +4289,7 @@ class TinyHtml {
             if (isHidden) {
                 // Ensure element is visible (like jQuery does before fading)
                 const display = TinyHtml.getAnimateData(elem, `origdisplay`);
-                elem.style.display = typeof display === 'string' ? display : 'block';
+                elem.style.display = typeof display === 'string' ? display : mainDisplay;
             }
             /** @type {AnimationSfxData} */
             const keyframes = {
@@ -4259,12 +4308,13 @@ class TinyHtml {
      *
      * @param {number} opacity - Final opacity value (between 0 and 1).
      * @param {number | KeyframeAnimationOptions | string} [ops] - Duration or animation options.
+     * @param {string} [mainDisplay=this.#mainDisplay] - Sets the main display value.
      * @returns {StyleFxResult}
      * @throws {TypeError} If opacity is not a number between 0 and 1.
      * @throws {TypeError} If ops is not number|string|object when provided.
      */
-    fadeTo(opacity, ops) {
-        return TinyHtml.fadeTo(this, opacity, ops);
+    fadeTo(opacity, ops, mainDisplay = this.#mainDisplay) {
+        return TinyHtml.fadeTo(this, opacity, ops, mainDisplay);
     }
     ///////////////////////////////////////////////////////////////
     // TITLE: DOM Positions

package/docs/v1/README.md

@@ -64,6 +64,14 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 
 ---
 
+## 📚 Tip Directories
+
+### 1. **`libs/`** 
+
+- 🧱 **[TinyHtml](./libs/TinyHtmlTips.md)** — Usage examples and practical tips.
+
+---
+
 ## 🚀 Usage
 
 To get started, navigate to the appropriate directory and explore the files listed. Each script includes detailed documentation on how to use the respective functionality.

package/docs/v1/libs/TinyHtmlTips.md

@@ -0,0 +1,140 @@
+# 🔧 TinyHtml Shortcuts & Aliases
+
+One of the coolest things about **TinyHtml** is that you can give its static methods **custom names (aliases)** 🎉.
+This allows you to mimic the style of jQuery, native browser functions, or even create your own conventions for working with the DOM.
+
+---
+
+## 🎭 Mimic jQuery Style
+
+If you’re a fan of jQuery’s `$` syntax, you can directly alias TinyHtml methods:
+
+```js
+// Select multiple elements (like jQuery's $)
+const $ = TinyHtml.queryAll;
+
+// Usage
+$('.my-class').forEach(el => console.log(el));
+```
+
+---
+
+## 💎 Super jQuery-like Style
+
+If you want TinyHtml to feel **almost exactly like jQuery**, you can define `$` as a **function wrapper** that automatically instantiates a `TinyHtml` object from a CSS selector.
+
+```js
+// jQuery-style $ function
+const $ = (queryString) => new TinyHtml(queryString);
+
+// Usage
+$('#my-id').addClass('highlight');
+$('.btn').on('click', () => alert('Clicked!'));
+```
+
+---
+
+## 🌐 Mimic Native Browser Querying
+
+If you prefer the style of the **native browser query** functions (`querySelector` and `querySelectorAll`), you can do:
+
+```js
+// Select single element (like document.querySelector)
+const $ = TinyHtml.query;
+
+// Select multiple elements (like document.querySelectorAll)
+const $$ = TinyHtml.queryAll;
+
+// Usage
+const button = $('#my-button');
+const divs = $$('.container');
+```
+
+---
+
+## 🛠️ Extra: Element Creation Shortcut
+
+TinyHtml also supports element creation. You can alias this too for faster coding:
+
+```js
+// Create elements from plain strings
+const $$$ = TinyHtml.createFrom;
+
+// OR, if you want it more explicit:
+const $$$ = TinyHtml.createFromHtml;
+
+// Usage
+const newDiv = $$$('<div class="box">Hello!</div>');
+```
+
+---
+
+## 🚀 Why Aliases?
+
+Aliases are especially handy when:
+
+* You want **shorter code** ✨
+* You’re working on **personal projects** with a custom coding style
+* You want to **simulate familiar APIs** like jQuery or browser query functions
+
+---
+
+👉 In summary, **TinyHtml is flexible**: you can stick to its original method names for clarity, or create **shortcuts** to match your own workflow.
+
+---
+
+# 📦 Creating a TinyHtml Shortcuts Module
+
+Instead of redefining your shortcuts (`$`, `$$`, `$$$`) in every file, you can create a **dedicated module** that exports them.
+This makes your setup **cleaner, reusable, and consistent** across the whole project.
+
+---
+
+## 🛠️ Example: shortcuts.js
+
+```js
+// Enable debugging mode
+TinyHtml.elemDebug = true;
+
+// jQuery-style single element selector
+export const $ = (queryString) => new TinyHtml(queryString);
+
+// Create elements from HTML objects
+export const $$ = TinyHtml.createFrom;
+
+// Create elements from HTML strings
+export const $$$ = TinyHtml.createFromHTML;
+
+// Export TinyHtml’s observer utility
+export const mainObserver = TinyHtml.tinyObserver;
+
+// Set TinyHtml’s default display css
+TinyHtml.defaultDisplay = 'block';
+```
+
+---
+
+## 🚀 Usage in Your Project
+
+Now you can simply import the shortcuts wherever you need them:
+
+```js
+import { $, $$, $$$ } from './shortcuts.js';
+
+// Select a button
+const btn = $('#submit');
+
+// Create and append an element
+const newBox = $$('div', { class: 'box' });
+
+// Set element's default display css
+newBox.mainDisplay = 'block';
+
+// Create an element
+const newBox2 = $$$('<div class="box">Hello!</div>');
+$('body').append(newBox);
+```
+
+---
+
+👉 With this setup, you end up with your own **personalized DOM toolkit**, powered by TinyHtml but feeling **as smooth as jQuery**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.22.13",
+  "version": "1.22.14",
   "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",