tiny-essentials 1.16.0 → 1.16.1

package/dist/v1/TinyDragger.js

@@ -4218,6 +4218,494 @@ class TinyHtml {
 
   //////////////////////////////////////////////////////////////////////
 
+  /**
+   * 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.
    *