tiny-essentials 1.16.0 → 1.16.2

package/dist/v1/libs/TinyHtml.mjs

@@ -1468,6 +1468,475 @@ class TinyHtml {
         return TinyHtml.cssFloats(this, prop);
     }
     //////////////////////////////////////////////////////////////////////
+    /**
+     * Stores camelCase to kebab-case CSS property aliases.
+     *
+     * Used to normalize property names when interacting with `element.style` or `getComputedStyle`.
+     *
+     * ⚠️ This object should not be modified directly. Use `TinyHtml.cssPropAliases` instead to ensure reverse mappings stay in sync.
+     *
+     * Example of how to add a new alias:
+     *
+     * ```js
+     * TinyHtml.cssPropAliases.tinyPudding = 'tiny-pudding';
+     * ```
+     *
+     * This will automatically update `TinyHtml.cssPropRevAliases['tiny-pudding']` with `'tinyPudding'`.
+     *
+     * @type {Record<string | symbol, string>}
+     */
+    static #cssPropAliases = {
+        alignContent: 'align-content',
+        alignItems: 'align-items',
+        alignSelf: 'align-self',
+        animationDelay: 'animation-delay',
+        animationDirection: 'animation-direction',
+        animationDuration: 'animation-duration',
+        animationFillMode: 'animation-fill-mode',
+        animationIterationCount: 'animation-iteration-count',
+        animationName: 'animation-name',
+        animationPlayState: 'animation-play-state',
+        animationTimingFunction: 'animation-timing-function',
+        backfaceVisibility: 'backface-visibility',
+        backgroundAttachment: 'background-attachment',
+        backgroundBlendMode: 'background-blend-mode',
+        backgroundClip: 'background-clip',
+        backgroundColor: 'background-color',
+        backgroundImage: 'background-image',
+        backgroundOrigin: 'background-origin',
+        backgroundPosition: 'background-position',
+        backgroundRepeat: 'background-repeat',
+        backgroundSize: 'background-size',
+        borderBottom: 'border-bottom',
+        borderBottomColor: 'border-bottom-color',
+        borderBottomLeftRadius: 'border-bottom-left-radius',
+        borderBottomRightRadius: 'border-bottom-right-radius',
+        borderBottomStyle: 'border-bottom-style',
+        borderBottomWidth: 'border-bottom-width',
+        borderCollapse: 'border-collapse',
+        borderColor: 'border-color',
+        borderImage: 'border-image',
+        borderImageOutset: 'border-image-outset',
+        borderImageRepeat: 'border-image-repeat',
+        borderImageSlice: 'border-image-slice',
+        borderImageSource: 'border-image-source',
+        borderImageWidth: 'border-image-width',
+        borderLeft: 'border-left',
+        borderLeftColor: 'border-left-color',
+        borderLeftStyle: 'border-left-style',
+        borderLeftWidth: 'border-left-width',
+        borderRadius: 'border-radius',
+        borderRight: 'border-right',
+        borderRightColor: 'border-right-color',
+        borderRightStyle: 'border-right-style',
+        borderRightWidth: 'border-right-width',
+        borderSpacing: 'border-spacing',
+        borderStyle: 'border-style',
+        borderTop: 'border-top',
+        borderTopColor: 'border-top-color',
+        borderTopLeftRadius: 'border-top-left-radius',
+        borderTopRightRadius: 'border-top-right-radius',
+        borderTopStyle: 'border-top-style',
+        borderTopWidth: 'border-top-width',
+        borderWidth: 'border-width',
+        boxDecorationBreak: 'box-decoration-break',
+        boxShadow: 'box-shadow',
+        boxSizing: 'box-sizing',
+        breakAfter: 'break-after',
+        breakBefore: 'break-before',
+        breakInside: 'break-inside',
+        captionSide: 'caption-side',
+        caretColor: 'caret-color',
+        clipPath: 'clip-path',
+        columnCount: 'column-count',
+        columnFill: 'column-fill',
+        columnGap: 'column-gap',
+        columnRule: 'column-rule',
+        columnRuleColor: 'column-rule-color',
+        columnRuleStyle: 'column-rule-style',
+        columnRuleWidth: 'column-rule-width',
+        columnSpan: 'column-span',
+        columnWidth: 'column-width',
+        counterIncrement: 'counter-increment',
+        counterReset: 'counter-reset',
+        emptyCells: 'empty-cells',
+        flexBasis: 'flex-basis',
+        flexDirection: 'flex-direction',
+        flexFlow: 'flex-flow',
+        flexGrow: 'flex-grow',
+        flexShrink: 'flex-shrink',
+        flexWrap: 'flex-wrap',
+        fontFamily: 'font-family',
+        fontFeatureSettings: 'font-feature-settings',
+        fontKerning: 'font-kerning',
+        fontLanguageOverride: 'font-language-override',
+        fontSize: 'font-size',
+        fontSizeAdjust: 'font-size-adjust',
+        fontStretch: 'font-stretch',
+        fontStyle: 'font-style',
+        fontSynthesis: 'font-synthesis',
+        fontVariant: 'font-variant',
+        fontVariantAlternates: 'font-variant-alternates',
+        fontVariantCaps: 'font-variant-caps',
+        fontVariantEastAsian: 'font-variant-east-asian',
+        fontVariantLigatures: 'font-variant-ligatures',
+        fontVariantNumeric: 'font-variant-numeric',
+        fontVariantPosition: 'font-variant-position',
+        fontWeight: 'font-weight',
+        gridArea: 'grid-area',
+        gridAutoColumns: 'grid-auto-columns',
+        gridAutoFlow: 'grid-auto-flow',
+        gridAutoRows: 'grid-auto-rows',
+        gridColumn: 'grid-column',
+        gridColumnEnd: 'grid-column-end',
+        gridColumnGap: 'grid-column-gap',
+        gridColumnStart: 'grid-column-start',
+        gridGap: 'grid-gap',
+        gridRow: 'grid-row',
+        gridRowEnd: 'grid-row-end',
+        gridRowGap: 'grid-row-gap',
+        gridRowStart: 'grid-row-start',
+        gridTemplate: 'grid-template',
+        gridTemplateAreas: 'grid-template-areas',
+        gridTemplateColumns: 'grid-template-columns',
+        gridTemplateRows: 'grid-template-rows',
+        imageRendering: 'image-rendering',
+        justifyContent: 'justify-content',
+        letterSpacing: 'letter-spacing',
+        lineBreak: 'line-break',
+        lineHeight: 'line-height',
+        listStyle: 'list-style',
+        listStyleImage: 'list-style-image',
+        listStylePosition: 'list-style-position',
+        listStyleType: 'list-style-type',
+        marginBottom: 'margin-bottom',
+        marginLeft: 'margin-left',
+        marginRight: 'margin-right',
+        marginTop: 'margin-top',
+        maskClip: 'mask-clip',
+        maskComposite: 'mask-composite',
+        maskImage: 'mask-image',
+        maskMode: 'mask-mode',
+        maskOrigin: 'mask-origin',
+        maskPosition: 'mask-position',
+        maskRepeat: 'mask-repeat',
+        maskSize: 'mask-size',
+        maskType: 'mask-type',
+        maxHeight: 'max-height',
+        maxWidth: 'max-width',
+        minHeight: 'min-height',
+        minWidth: 'min-width',
+        mixBlendMode: 'mix-blend-mode',
+        objectFit: 'object-fit',
+        objectPosition: 'object-position',
+        offsetAnchor: 'offset-anchor',
+        offsetDistance: 'offset-distance',
+        offsetPath: 'offset-path',
+        offsetRotate: 'offset-rotate',
+        outlineColor: 'outline-color',
+        outlineOffset: 'outline-offset',
+        outlineStyle: 'outline-style',
+        outlineWidth: 'outline-width',
+        overflowAnchor: 'overflow-anchor',
+        overflowWrap: 'overflow-wrap',
+        overflowX: 'overflow-x',
+        overflowY: 'overflow-y',
+        paddingBottom: 'padding-bottom',
+        paddingLeft: 'padding-left',
+        paddingRight: 'padding-right',
+        paddingTop: 'padding-top',
+        pageBreakAfter: 'page-break-after',
+        pageBreakBefore: 'page-break-before',
+        pageBreakInside: 'page-break-inside',
+        perspectiveOrigin: 'perspective-origin',
+        placeContent: 'place-content',
+        placeItems: 'place-items',
+        placeSelf: 'place-self',
+        pointerEvents: 'pointer-events',
+        rowGap: 'row-gap',
+        scrollBehavior: 'scroll-behavior',
+        scrollMargin: 'scroll-margin',
+        scrollMarginBlock: 'scroll-margin-block',
+        scrollMarginBlockEnd: 'scroll-margin-block-end',
+        scrollMarginBlockStart: 'scroll-margin-block-start',
+        scrollMarginBottom: 'scroll-margin-bottom',
+        scrollMarginInline: 'scroll-margin-inline',
+        scrollMarginInlineEnd: 'scroll-margin-inline-end',
+        scrollMarginInlineStart: 'scroll-margin-inline-start',
+        scrollMarginLeft: 'scroll-margin-left',
+        scrollMarginRight: 'scroll-margin-right',
+        scrollMarginTop: 'scroll-margin-top',
+        scrollPadding: 'scroll-padding',
+        scrollPaddingBlock: 'scroll-padding-block',
+        scrollPaddingBlockEnd: 'scroll-padding-block-end',
+        scrollPaddingBlockStart: 'scroll-padding-block-start',
+        scrollPaddingBottom: 'scroll-padding-bottom',
+        scrollPaddingInline: 'scroll-padding-inline',
+        scrollPaddingInlineEnd: 'scroll-padding-inline-end',
+        scrollPaddingInlineStart: 'scroll-padding-inline-start',
+        scrollPaddingLeft: 'scroll-padding-left',
+        scrollPaddingRight: 'scroll-padding-right',
+        scrollPaddingTop: 'scroll-padding-top',
+        scrollSnapAlign: 'scroll-snap-align',
+        scrollSnapStop: 'scroll-snap-stop',
+        scrollSnapType: 'scroll-snap-type',
+        shapeImageThreshold: 'shape-image-threshold',
+        shapeMargin: 'shape-margin',
+        shapeOutside: 'shape-outside',
+        tabSize: 'tab-size',
+        tableLayout: 'table-layout',
+        textAlign: 'text-align',
+        textAlignLast: 'text-align-last',
+        textCombineUpright: 'text-combine-upright',
+        textDecoration: 'text-decoration',
+        textDecorationColor: 'text-decoration-color',
+        textDecorationLine: 'text-decoration-line',
+        textDecorationStyle: 'text-decoration-style',
+        textIndent: 'text-indent',
+        textJustify: 'text-justify',
+        textOrientation: 'text-orientation',
+        textOverflow: 'text-overflow',
+        textShadow: 'text-shadow',
+        textTransform: 'text-transform',
+        transformBox: 'transform-box',
+        transformOrigin: 'transform-origin',
+        transformStyle: 'transform-style',
+        transitionDelay: 'transition-delay',
+        transitionDuration: 'transition-duration',
+        transitionProperty: 'transition-property',
+        transitionTimingFunction: 'transition-timing-function',
+        unicodeBidi: 'unicode-bidi',
+        userSelect: 'user-select',
+        verticalAlign: 'vertical-align',
+        whiteSpace: 'white-space',
+        willChange: 'will-change',
+        wordBreak: 'word-break',
+        wordSpacing: 'word-spacing',
+        wordWrap: 'word-wrap',
+        writingMode: 'writing-mode',
+        zIndex: 'z-index',
+        WebkitTransform: '-webkit-transform',
+        WebkitTransition: '-webkit-transition',
+        WebkitBoxShadow: '-webkit-box-shadow',
+        MozBoxShadow: '-moz-box-shadow',
+        MozTransform: '-moz-transform',
+        MozTransition: '-moz-transition',
+        msTransform: '-ms-transform',
+        msTransition: '-ms-transition',
+    };
+    /** @type {Record<string | symbol, string>} */
+    static cssPropAliases = new Proxy(TinyHtml.#cssPropAliases, {
+        set(target, camelCaseKey, kebabValue) {
+            target[camelCaseKey] = kebabValue;
+            // @ts-ignore
+            TinyHtml.cssPropRevAliases[kebabValue] = camelCaseKey;
+            return true;
+        },
+    });
+    /** @type {Record<string | symbol, string>} */
+    static cssPropRevAliases = Object.fromEntries(Object.entries(TinyHtml.#cssPropAliases).map(([camel, kebab]) => [kebab, camel]));
+    /**
+     * Converts a camelCase string to kebab-case
+     * @param {string} str
+     * @returns {string}
+     */
+    static toStyleKc(str) {
+        if (typeof TinyHtml.cssPropAliases[str] === 'string')
+            return TinyHtml.cssPropAliases[str];
+        return str;
+    }
+    /**
+     * Converts a kebab-case string to camelCase
+     * @param {string} str
+     * @returns {string}
+     */
+    static toStyleCc(str) {
+        if (typeof TinyHtml.cssPropRevAliases[str] === 'string')
+            return TinyHtml.cssPropRevAliases[str];
+        return str;
+    }
+    /**
+     * Sets one or more CSS inline style properties on the given element(s).
+     *
+     * - If `prop` is a string, the `value` will be applied to that property.
+     * - If `prop` is an object, each key-value pair will be applied as a CSS property and value.
+     *
+     * @param {TinyHtmlElement|TinyHtmlElement[]} el - The element to inspect.
+     * @param {string|Object} prop - The property name or an object with key-value pairs
+     * @param {string|null} [value=null] - The value to set (if `prop` is a string)
+     */
+    static setStyle(el, prop, value = null) {
+        TinyHtml._preHtmlElems(el, 'setStyle').forEach((elem) => {
+            if (typeof prop === 'object') {
+                for (const [k, v] of Object.entries(prop)) {
+                    elem.style.setProperty(TinyHtml.toStyleKc(k), typeof v === 'string' ? v : typeof v === 'number' ? `${v}px` : String(v));
+                }
+            }
+            else
+                elem.style.setProperty(TinyHtml.toStyleKc(prop), value);
+        });
+    }
+    /**
+     * Sets one or more CSS inline style properties on the given element(s).
+     *
+     * - If `prop` is a string, the `value` will be applied to that property.
+     * - If `prop` is an object, each key-value pair will be applied as a CSS property and value.
+     *
+     * @param {string|Object} prop - The property name or an object with key-value pairs
+     * @param {string|null} [value=null] - The value to set (if `prop` is a string)
+     */
+    setStyle(prop, value) {
+        return TinyHtml.setStyle(this, prop, value);
+    }
+    /**
+     * Gets the value of a specific inline style property.
+     *
+     * Returns only the value set directly via the `style` attribute.
+     *
+     * @param {TinyHtmlElement|TinyHtmlElement[]} el - A single element to inspect.
+     * @param {string} prop - The style property name to retrieve.
+     * @returns {string} The style value of the specified property.
+     */
+    static getStyle(el, prop) {
+        return TinyHtml._preHtmlElem(el, 'getStyle').style.getPropertyValue(TinyHtml.toStyleKc(prop));
+    }
+    /**
+     * Gets the value of a specific inline style property.
+     *
+     * Returns only the value set directly via the `style` attribute.
+     *
+     * @param {string} prop - The style property name to retrieve.
+     * @returns {string} The style value of the specified property.
+     */
+    getStyle(prop) {
+        return TinyHtml.getStyle(this, prop);
+    }
+    /**
+     * Gets all inline styles defined directly on the element (`style` attribute).
+     *
+     * Returns an object with all property-value pairs in kebab-case format.
+     *
+     * @param {TinyHtmlElement|TinyHtmlElement[]} el - A single element to inspect.
+     * @param {Object} [settings={}] - Optional configuration settings.
+     * @param {boolean} [settings.camelCase=false] - If `true`, the property names will be converted to camelCase.
+     * @param {boolean} [settings.rawAttr=false] - If `true`, reads the style string from the `style` attribute instead of using the style object.
+     * @returns {Record<string, string>} All inline styles as an object.
+     *
+     * @throws {TypeError} If `camelCase` or `rawAttr` is not a boolean.
+     */
+    static style(el, { camelCase = false, rawAttr = false } = {}) {
+        if (typeof camelCase !== 'boolean')
+            throw new TypeError(`"camelCase" must be a boolean. Received: ${typeof camelCase}`);
+        if (typeof rawAttr !== 'boolean')
+            throw new TypeError(`"rawAttr" must be a boolean. Received: ${typeof rawAttr}`);
+        const elem = TinyHtml._preHtmlElem(el, 'style');
+        /** @type {Record<string, string>} */
+        const result = {};
+        if (rawAttr) {
+            const raw = elem.getAttribute('style') || '';
+            const entries = raw.split(';');
+            for (const entry of entries) {
+                const [rawProp, rawVal] = entry.split(':');
+                if (!rawProp || !rawVal)
+                    continue;
+                const prop = rawProp.trim();
+                const value = rawVal.trim();
+                result[camelCase ? TinyHtml.toStyleCc(prop) : prop] = value;
+            }
+        }
+        else {
+            const styles = elem.style;
+            for (let i = 0; i < styles.length; i++) {
+                const prop = styles[i]; // Already in kebab-case
+                const value = styles.getPropertyValue(prop);
+                result[camelCase ? TinyHtml.toStyleCc(prop) : prop] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Gets all inline styles defined directly on the element (`style` attribute).
+     *
+     * Returns an object with all property-value pairs in kebab-case format.
+     *
+     * @param {Object} [settings={}] - Optional configuration settings.
+     * @param {boolean} [settings.camelCase=false] - If `true`, the property names will be converted to camelCase.
+     * @param {boolean} [settings.rawAttr=false] - If `true`, reads the style string from the `style` attribute instead of using the style object.
+     * @returns {Record<string, string>} All inline styles as an object.
+     */
+    style(settings) {
+        return TinyHtml.style(this, settings);
+    }
+    /**
+     * Removes one or more inline CSS properties from the given element(s).
+     *
+     * @param {TinyHtmlElement|TinyHtmlElement[]} el - A single element or an array of elements.
+     * @param {string|string[]} prop - A property name or an array of property names to remove.
+     */
+    static removeStyle(el, prop) {
+        TinyHtml._preHtmlElems(el, 'removeStyle').forEach((elem) => {
+            if (Array.isArray(prop)) {
+                for (const p of prop) {
+                    elem.style.removeProperty(TinyHtml.toStyleKc(p));
+                }
+            }
+            else
+                elem.style.removeProperty(TinyHtml.toStyleKc(prop));
+        });
+    }
+    /**
+     * Removes one or more inline CSS properties from the given element(s).
+     *
+     * @param {string|string[]} prop - A property name or an array of property names to remove.
+     */
+    removeStyle(prop) {
+        return TinyHtml.removeStyle(this, prop);
+    }
+    /**
+     * Toggles a CSS property value between two given values.
+     *
+     * The current computed value is compared to `val1`. If it matches, the property is set to `val2`. Otherwise, it is set to `val1`.
+     *
+     * @param {TinyHtmlElement|TinyHtmlElement[]} el - A single element or an array of elements.
+     * @param {string} prop - The CSS property to toggle.
+     * @param {string} val1 - The first value (used as "current" check).
+     * @param {string} val2 - The second value (used as the "alternative").
+     */
+    static toggleStyle(el, prop, val1, val2) {
+        TinyHtml._preHtmlElems(el, 'toggleStyle').forEach((elem) => {
+            const current = TinyHtml.getStyle(elem, prop).trim();
+            const newVal = current === TinyHtml.toStyleKc(val1) ? val2 : val1;
+            TinyHtml.setStyle(elem, prop, newVal);
+        });
+    }
+    /**
+     * Toggles a CSS property value between two given values.
+     *
+     * The current computed value is compared to `val1`. If it matches, the property is set to `val2`. Otherwise, it is set to `val1`.
+     *
+     * @param {string} prop - The CSS property to toggle.
+     * @param {string} val1 - The first value (used as "current" check).
+     * @param {string} val2 - The second value (used as the "alternative").
+     */
+    toggleStyle(prop, val1, val2) {
+        return TinyHtml.toggleStyle(this, prop, val1, val2);
+    }
+    /**
+     * Removes all inline styles (`style` attribute) from the given element(s).
+     *
+     * @param {TinyElement|TinyElement[]} el - A single element or an array of elements.
+     */
+    static clearStyle(el) {
+        TinyHtml._preElems(el, 'clearStyle').forEach((elem) => elem.removeAttribute('style'));
+    }
+    /**
+     * Removes all inline styles (`style` attribute) from the given element(s).
+     *
+     */
+    clearStyle() {
+        return TinyHtml.clearStyle(this);
+    }
+    //////////////////////////////////////////////////////////////////////
     /**
      * Focus the element.
      *

package/dist/v1/libs/TinyUploadClicker.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var objFilter = require('../basics/objFilter.cjs');
+require('./TinyHtml.cjs');
 require('fs');
 require('path');
 require('fs/promises');

package/docs/v1/README.md

@@ -12,15 +12,15 @@ Here, you can navigate through different sections of the project. Below are the
 
 This folder contains the core scripts we have worked on so far. Each file is a module focused on specific functionality.
 
-- 📦 **[array](./basics/array.md)** — A tiny utility for shuffling arrays using the Fisher–Yates algorithm.
-- ⏰ **[clock](./basics/clock.md)** — A versatile time utility module for calculating and formatting time durations.
-- 🧠 **[objFilter](./basics/objFilter.md)** — Type detection, extension, and analysis made easy with simple and extensible type validation.
-- 🔢 **[simpleMath](./basics/simpleMath.md)** — A collection of simple math utilities for calculations like the Rule of Three and percentages.
-- ✍️ **[text](./basics/text.md)** — A utility for transforming text into title case formats, with multiple options for capitalization.
-- 🔄 **[asyncReplace](./basics/asyncReplace.md)** — Asynchronously replaces matches in a string using a regex and an async function.
-- 🖼️ **[html](./basics/html.md)** — Utilities for handling DOM element interactions like collision detection and basic element manipulation.
-- 📺 **[fullScreen](./basics/fullScreen.md)** — A complete fullscreen API manager with detection, event handling, and cross-browser compatibility.
-- 🧱 **[collision](./basics/collision.md)** — Full-featured rectangle collision detection system with directional analysis, depth calculation, and center offset metrics.
+- 📦 **[Array](./basics/array.md)** — A tiny utility for shuffling arrays using the Fisher–Yates algorithm.
+- ⏰ **[Clock](./basics/clock.md)** — A versatile time utility module for calculating and formatting time durations.
+- 🧠 **[ObjFilter](./basics/objFilter.md)** — Type detection, extension, and analysis made easy with simple and extensible type validation.
+- 🔢 **[SimpleMath](./basics/simpleMath.md)** — A collection of simple math utilities for calculations like the Rule of Three and percentages.
+- ✍️ **[Text](./basics/text.md)** — A utility for transforming text into title case formats, with multiple options for capitalization.
+- 🔄 **[AsyncReplace](./basics/asyncReplace.md)** — Asynchronously replaces matches in a string using a regex and an async function.
+- 🖼️ **[Html](./basics/html.md)** — Utilities for handling DOM element interactions like collision detection and basic element manipulation.
+- 📺 **[FullScreen](./basics/fullScreen.md)** — A complete fullscreen API manager with detection, event handling, and cross-browser compatibility.
+- 🧱 **[Collision](./basics/collision.md)** — Full-featured rectangle collision detection system with directional analysis, depth calculation, and center offset metrics.
 
 ### 2. **`libs/`**
 - 🗂️ **[TinyPromiseQueue](./libs/TinyPromiseQueue.md)** — A class that allows sequential execution of asynchronous tasks, supporting task delays, cancellation, and queue management.
@@ -37,7 +37,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🧱 **[TinyHtml](./libs/TinyHtml.md)** — A minimalist DOM utility class that offers jQuery-like methods in pure JavaScript for querying, styling, traversing, event handling, collision detection, and visibility logic — all in a lightweight and chainable interface.
 
 ### 3. **`fileManager/`**
-* 📁 **[main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.
+* 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.
 
 ---