tiny-essentials 1.22.1 → 1.22.2

package/dist/v1/basics/index.mjs

@@ -7,6 +7,6 @@ import { extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType } from '
 import { countObj, isJsonObject } from './objChecker.mjs';
 import { documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, } from './fullScreen.mjs';
 import { calculateMarketcap, compareMarketcap, formatBytes, genFibonacciSeq, getAge, getPercentage, getSimplePerc, ruleOfThree, } from './simpleMath.mjs';
-import { addAiMarkerShortcut, diffStrings, safeTextTrim, toTitleCase, toTitleCaseLowerFirst } from './text.mjs';
+import { addAiMarkerShortcut, diffStrings, safeTextTrim, toTitleCase, toTitleCaseLowerFirst, } from './text.mjs';
 import { areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, } from './collision.mjs';
 export { diffStrings, diffArrayList, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/libs/TinyHtml.cjs

@@ -3768,6 +3768,7 @@ class TinyHtml {
     slideUp: 'slideDown',
     fadeIn: 'fadeOut',
     fadeOut: 'fadeIn',
+    fadeTo: 'fadeIn',
   };
 
   /**
@@ -4441,6 +4442,78 @@ class TinyHtml {
     return TinyHtml.fadeToggle(this, ops);
   }
 
+  /**
+   * Animate the opacity of elements to a target value.
+   * If the element is hidden (display:none), it will be made visible first
+   * so the fade animation can occur.
+   *
+   * @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.
+   * @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) {
+    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 &&
+      !(
+        typeof ops === 'number' ||
+        typeof ops === 'string' ||
+        (typeof ops === 'object' && ops !== null)
+      )
+    ) {
+      throw new TypeError(
+        'fadeTo: ops must be a number, string, KeyframeAnimationOptions, or undefined.',
+      );
+    }
+
+    /** @type {StyleFxResult} */
+    const results = new Map();
+    TinyHtml._preHtmlElems(el, 'fadeTo').forEach((elem) => {
+      const style = getComputedStyle(elem);
+      const isHidden = !(el instanceof Element)
+        ? true
+        : !(el.offsetWidth || el.offsetHeight || el.getClientRects().length);
+
+      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';
+      }
+
+      /** @type {AnimationSfxData} */
+      const keyframes = {
+        opacity: [style.opacity, opacity],
+      };
+
+      // Build keyframe objects for Web Animations
+      const kf = keyframes.opacity.map((val) => ({ opacity: val }));
+
+      results.set(elem, TinyHtml.animate(elem, kf, ops, 'fadeTo')[0]);
+    });
+
+    return results;
+  }
+
+  /**
+   * Animate the opacity of elements to a target value.
+   * If the element is hidden (display:none), it will be made visible first
+   * so the fade animation can occur.
+   *
+   * @param {number} opacity - Final opacity value (between 0 and 1).
+   * @param {number | KeyframeAnimationOptions | string} [ops] - Duration or animation options.
+   * @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);
+  }
+
   ///////////////////////////////////////////////////////////////
 
   // TITLE: DOM Positions

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

@@ -1698,6 +1698,19 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
      * @returns {StyleFxResult}
      */
     static fadeToggle(el: TinyHtmlElement | TinyHtmlElement[], ops?: number | KeyframeAnimationOptions | string): StyleFxResult;
+    /**
+     * Animate the opacity of elements to a target value.
+     * If the element is hidden (display:none), it will be made visible first
+     * so the fade animation can occur.
+     *
+     * @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.
+     * @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;
     /**
      * Gets the offset of the element relative to the document.
      * @param {TinyElement} el - Target element.
@@ -3070,6 +3083,18 @@ declare class TinyHtml<TinyHtmlT extends ConstructorElValues | ConstructorElValu
      * @returns {StyleFxResult}
      */
     fadeToggle(ops?: number | KeyframeAnimationOptions | string): StyleFxResult;
+    /**
+     * Animate the opacity of elements to a target value.
+     * If the element is hidden (display:none), it will be made visible first
+     * so the fade animation can occur.
+     *
+     * @param {number} opacity - Final opacity value (between 0 and 1).
+     * @param {number | KeyframeAnimationOptions | string} [ops] - Duration or animation options.
+     * @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;
     /**
      * Gets the offset of the element relative to the document.
      * @returns {{top: number, left: number}}

package/dist/v1/libs/TinyHtml.mjs

@@ -3362,6 +3362,7 @@ class TinyHtml {
         slideUp: 'slideDown',
         fadeIn: 'fadeOut',
         fadeOut: 'fadeIn',
+        fadeTo: 'fadeIn',
     };
     /**
      * Get a cloned copy of style inverse values.
@@ -3969,6 +3970,63 @@ class TinyHtml {
     fadeToggle(ops) {
         return TinyHtml.fadeToggle(this, ops);
     }
+    /**
+     * Animate the opacity of elements to a target value.
+     * If the element is hidden (display:none), it will be made visible first
+     * so the fade animation can occur.
+     *
+     * @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.
+     * @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) {
+        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 &&
+            !(typeof ops === 'number' ||
+                typeof ops === 'string' ||
+                (typeof ops === 'object' && ops !== null))) {
+            throw new TypeError('fadeTo: ops must be a number, string, KeyframeAnimationOptions, or undefined.');
+        }
+        /** @type {StyleFxResult} */
+        const results = new Map();
+        TinyHtml._preHtmlElems(el, 'fadeTo').forEach((elem) => {
+            const style = getComputedStyle(elem);
+            const isHidden = !(el instanceof Element)
+                ? true
+                : !(el.offsetWidth || el.offsetHeight || el.getClientRects().length);
+            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';
+            }
+            /** @type {AnimationSfxData} */
+            const keyframes = {
+                opacity: [style.opacity, opacity],
+            };
+            // Build keyframe objects for Web Animations
+            const kf = keyframes.opacity.map((val) => ({ opacity: val }));
+            results.set(elem, TinyHtml.animate(elem, kf, ops, 'fadeTo')[0]);
+        });
+        return results;
+    }
+    /**
+     * Animate the opacity of elements to a target value.
+     * If the element is hidden (display:none), it will be made visible first
+     * so the fade animation can occur.
+     *
+     * @param {number} opacity - Final opacity value (between 0 and 1).
+     * @param {number | KeyframeAnimationOptions | string} [ops] - Duration or animation options.
+     * @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);
+    }
     ///////////////////////////////////////////////////////////////
     // TITLE: DOM Positions
     /**

package/docs/v1/libs/TinyHtml.md

@@ -3141,6 +3141,32 @@ Instance method version.
 
 ---
 
+### `static fadeTo(el, opacity, ops?): StyleFxResult`
+
+Animate the opacity of elements to a target value.
+If the element is hidden (`display: none`), it will first be made visible before applying the fade animation.
+
+```js
+TinyHtml.fadeTo(el, 0.5, 400);     // Fade element to 50% opacity in 400ms
+TinyHtml.fadeTo(el, 1, "fast");    // Fade element to full opacity using predefined speed
+```
+
+* `el`: The target element(s) to animate.
+* `opacity`: The final opacity value (between `0` and `1`).
+* `ops`: Optional duration, animation options, or a predefined speed name.
+
+Returns a `StyleFxResult` mapping each element to its animation instance.
+
+### `fadeTo(opacity, ops?): StyleFxResult`
+
+Instance method version.
+
+```js
+element.fadeTo(0.3, { duration: 800, easing: "ease-in" });
+```
+
+---
+
 ## 🖱️ Focus & Blur
 
 TinyHtml provides utility methods to programmatically focus or blur HTML elements.

package/package.json

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