tiny-essentials 1.17.0 → 1.18.0

package/dist/v1/TinyEssentials.js

@@ -2887,6 +2887,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
   ColorSafeStringify: () => (/* reexport */ libs_ColorSafeStringify),
   TinyAfterScrollWatcher: () => (/* reexport */ libs_TinyAfterScrollWatcher),
+  TinyClipboard: () => (/* reexport */ libs_TinyClipboard),
   TinyDomReadyManager: () => (/* reexport */ libs_TinyDomReadyManager),
   TinyDragDropDetector: () => (/* reexport */ libs_TinyDragDropDetector),
   TinyDragger: () => (/* reexport */ libs_TinyDragger),
@@ -2897,6 +2898,7 @@ __webpack_require__.d(__webpack_exports__, {
   TinyPromiseQueue: () => (/* reexport */ libs_TinyPromiseQueue),
   TinyRateLimiter: () => (/* reexport */ libs_TinyRateLimiter),
   TinySmartScroller: () => (/* reexport */ libs_TinySmartScroller),
+  TinyTextRangeEditor: () => (/* reexport */ libs_TinyTextRangeEditor),
   TinyToastNotify: () => (/* reexport */ libs_TinyToastNotify),
   UltraRandomMsgGen: () => (/* reexport */ libs_UltraRandomMsgGen),
   addAiMarkerShortcut: () => (/* reexport */ addAiMarkerShortcut),
@@ -7041,6 +7043,19 @@ const {
   areElsCollRight: TinyHtml_areElsCollRight,
 } = collision_namespaceObject;
 
+/**
+ * Callback invoked on each animation frame with the current scroll position,
+ * normalized animation time (`0` to `1`), and a completion flag.
+ *
+ * @typedef {(progress: { x: number, y: number, isComplete: boolean, time: number }) => void} OnScrollAnimation
+ */
+
+/**
+ * A list of supported easing function names for smooth animations.
+ *
+ * @typedef {'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic'} Easings
+ */
+
 /**
  * Represents a raw Node element or an instance of TinyHtml.
  * This type is used to abstract interactions with both plain elements
@@ -7111,6 +7126,21 @@ const {
  * @typedef {Element|Window|Document} ElementAndWinAndDoc
  */
 
+/**
+ * Represents a raw DOM element with document or an instance of TinyHtml.
+ * This type is used to abstract interactions with both plain elements
+ * and wrapped elements via the TinyHtml class.
+ *
+ * @typedef {ElementWithDoc|TinyHtml} TinyElementWithDoc
+ */
+
+/**
+ * Represents a value that can be either a DOM Element, or the document object.
+ * Useful for functions that operate generically on measurable targets.
+ *
+ * @typedef {Element|Document} ElementWithDoc
+ */
+
 /**
  * A parameter type used for filtering or matching elements.
  * It can be:
@@ -7130,12 +7160,6 @@ const {
  * @typedef {Window|Element|Document|Text} ConstructorElValues
  */
 
-/**
- * The handler function used in event listeners.
- *
- * @typedef {(e: Event) => any} EventRegistryHandle
- */
-
 /**
  * Options passed to `addEventListener` or `removeEventListener`.
  * Can be a boolean or an object of type `AddEventListenerOptions`.
@@ -7147,7 +7171,7 @@ const {
  * Structure describing a registered event callback and its options.
  *
  * @typedef {Object} EventRegistryItem
- * @property {EventRegistryHandle} handler - The function to be executed when the event is triggered.
+ * @property {EventListenerOrEventListenerObject|null} handler - The function to be executed when the event is triggered.
  * @property {EventRegistryOptions} [options] - Optional configuration passed to the listener.
  */
 
@@ -7706,9 +7730,9 @@ class TinyHtml_TinyHtml {
    * Ensures the input is returned as an array.
    * Useful to normalize operations across multiple or single element/window/document elements.
    *
-   * @param {TinyElementAndWinAndDoc|TinyElementAndWinAndDoc[]} elems - A single element/window element or array of html elements.
+   * @param {TinyElementAndWinAndDoc|TinyElementAndWinAndDoc[]} elems - A single element/document/window element or array of html elements.
    * @param {string} where - The method or context name where validation is being called.
-   * @returns {ElementAndWindow[]} - Always returns an array of element/window elements.
+   * @returns {ElementAndWindow[]} - Always returns an array of element/document/window elements.
    * @readonly
    */
   static _preElemsAndWinAndDoc(elems, where) {
@@ -7725,9 +7749,9 @@ class TinyHtml_TinyHtml {
    * Ensures the input is returned as an single element/window/document element.
    * Useful to normalize operations across multiple or single element/window/document elements.
    *
-   * @param {TinyElementAndWinAndDoc|TinyElementAndWinAndDoc[]} elems - A single element/window element or array of html elements.
+   * @param {TinyElementAndWinAndDoc|TinyElementAndWinAndDoc[]} elems - A single element/document/window element or array of html elements.
    * @param {string} where - The method or context name where validation is being called.
-   * @returns {ElementAndWindow} - Always returns an single element/window element.
+   * @returns {ElementAndWindow} - Always returns an single element/document/window element.
    * @readonly
    */
   static _preElemAndWinAndDoc(elems, where) {
@@ -7741,6 +7765,32 @@ class TinyHtml_TinyHtml {
     return result;
   }
 
+  /**
+   * Ensures the input is returned as an array.
+   * Useful to normalize operations across multiple or single element with document elements.
+   *
+   * @param {TinyElementWithDoc|TinyElementWithDoc[]} elems - A single element with document element or array of html elements.
+   * @param {string} where - The method or context name where validation is being called.
+   * @returns {ElementWithDoc[]} - Always returns an array of element with document elements.
+   * @readonly
+   */
+  static _preElemsWithDoc(elems, where) {
+    return TinyHtml_TinyHtml._preElemsTemplate(elems, where, [Element, Document], ['Element', 'Document']);
+  }
+
+  /**
+   * Ensures the input is returned as an single element with document element.
+   * Useful to normalize operations across multiple or single element with document elements.
+   *
+   * @param {TinyElementWithDoc|TinyElementWithDoc[]} elems - A single element/window element or array of html elements.
+   * @param {string} where - The method or context name where validation is being called.
+   * @returns {ElementWithDoc} - Always returns an single element/window element.
+   * @readonly
+   */
+  static _preElemWithDoc(elems, where) {
+    return TinyHtml_TinyHtml._preElemTemplate(elems, where, [Element, Document], ['Element', 'Document']);
+  }
+
   /**
    * Normalizes and converts one or more DOM elements (or TinyHtml instances)
    * into an array of `TinyHtml` instances.
@@ -9449,7 +9499,7 @@ class TinyHtml_TinyHtml {
    */
   static setWinScrollTop(value) {
     if (typeof value !== 'number') throw new TypeError('The value must be a number.');
-    window.scrollTo({ top: value });
+    TinyHtml_TinyHtml.setScrollTop(window, value);
   }
 
   /**
@@ -9458,7 +9508,7 @@ class TinyHtml_TinyHtml {
    */
   static setWinScrollLeft(value) {
     if (typeof value !== 'number') throw new TypeError('The value must be a number.');
-    window.scrollTo({ left: value });
+    TinyHtml_TinyHtml.setScrollLeft(window, value);
   }
 
   /**
@@ -9775,6 +9825,30 @@ class TinyHtml_TinyHtml {
 
   //////////////////////////////////////////////////
 
+  /**
+   * Applies an animation to one or multiple TinyElement instances.
+   *
+   * @param {TinyElement|TinyElement[]} el - A single TinyElement or an array of TinyElements to animate.
+   * @param {Keyframe[] | PropertyIndexedKeyframes | null} keyframes - The keyframes used to define the animation.
+   * @param {number | KeyframeAnimationOptions} [ops] - Timing or configuration options for the animation.
+   * @returns {TinyElement|TinyElement[]}
+   */
+  static animate(el, keyframes, ops) {
+    TinyHtml_TinyHtml._preElems(el, 'animate').forEach((elem) => elem.animate(keyframes, ops));
+    return el;
+  }
+
+  /**
+   * Applies an animation to one or multiple TinyElement instances.
+   *
+   * @param {Keyframe[] | PropertyIndexedKeyframes | null} keyframes - The keyframes used to define the animation.
+   * @param {number | KeyframeAnimationOptions} [ops] - Timing or configuration options for the animation.
+   * @returns {TinyElement|TinyElement[]}
+   */
+  animate(keyframes, ops) {
+    return TinyHtml_TinyHtml.animate(this, keyframes, ops);
+  }
+
   /**
    * Gets the offset of the element relative to the document.
    * @param {TinyElement} el - Target element.
@@ -9930,26 +10004,147 @@ class TinyHtml_TinyHtml {
   }
 
   /**
-   * Sets the vertical scroll position.
-   * @param {TinyElementAndWindow|TinyElementAndWindow[]} el - Element or window.
-   * @param {number} value - Scroll top value.
-   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
+   * Collection of easing functions used for scroll and animation calculations.
+   * Each function receives a normalized time value (`t` from 0 to 1) and returns the eased progress.
+   *
+   * @type {Record<string, (t: number) => number>}
    */
-  static setScrollTop(el, value) {
-    if (typeof value !== 'number') throw new TypeError('ScrollTop value must be a number.');
-    TinyHtml_TinyHtml._preElemsAndWindow(el, 'setScrollTop').forEach((elem) => {
-      if (TinyHtml_TinyHtml.isWindow(elem)) {
-        elem.scrollTo(elem.pageXOffset, value);
+  static easings = {
+    linear: (t) => t,
+    easeInQuad: (t) => t * t,
+    easeOutQuad: (t) => t * (2 - t),
+    easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+    easeInCubic: (t) => t * t * t,
+    easeOutCubic: (t) => --t * t * t + 1,
+    easeInOutCubic: (t) => (t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1),
+  };
+
+  /**
+   * Smoothly scrolls one or more elements (or the window) to the specified X and Y coordinates
+   * using a custom duration and easing function.
+   *
+   * If `duration` or a valid `easing` is not provided, the scroll will be performed immediately.
+   *
+   * @param {TinyElementAndWindow | TinyElementAndWindow[]} el - A single element, array of elements, or the window to scroll.
+   * @param {Object} [settings={}] - Configuration object for the scroll animation.
+   * @param {number} [settings.targetX] - The horizontal scroll target in pixels.
+   * @param {number} [settings.targetY] - The vertical scroll target in pixels.
+   * @param {number} [settings.duration] - The duration of the animation in milliseconds.
+   * @param {Easings} [settings.easing] - The easing function name to use for the scroll animation.
+   * @param {OnScrollAnimation} [settings.onAnimation] - Optional callback invoked on each animation
+   *   frame with the current scroll position, normalized animation time (`0` to `1`), and a completion flag.
+   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
+   * @throws {TypeError} If `el` is not a valid element, array, or window.
+   * @throws {TypeError} If `targetX` or `targetY` is defined but not a number.
+   * @throws {TypeError} If `duration` is defined but not a number.
+   * @throws {TypeError} If `easing` is defined but not a valid easing function name.
+   * @throws {TypeError} If `onAnimation` is defined but not a function.
+   */
+  static scrollToXY(el, { targetX, targetY, duration, easing, onAnimation } = {}) {
+    if (targetX !== undefined && typeof targetX !== 'number')
+      throw new TypeError('`targetX` must be a number if provided.');
+    if (targetY !== undefined && typeof targetY !== 'number')
+      throw new TypeError('`targetY` must be a number if provided.');
+    if (duration !== undefined && typeof duration !== 'number')
+      throw new TypeError('`duration` must be a number if provided.');
+    if (easing !== undefined && typeof easing !== 'string')
+      throw new TypeError('`easing` must be a string if provided.');
+    if (easing !== undefined && typeof TinyHtml_TinyHtml.easings[easing] !== 'function')
+      throw new TypeError(`Unknown easing function: "${easing}".`);
+    if (onAnimation !== undefined && typeof onAnimation !== 'function')
+      throw new TypeError('`onAnimation` must be a function if provided.');
+
+    /**
+     * Performs an instant scroll to the given coordinates.
+     *
+     * @param {ElementAndWindow} elem - The element or window to scroll.
+     * @param {number} newX - The final horizontal scroll position.
+     * @param {number} newY - The final vertical scroll position.
+     * @param {number} time - Normalized progress value.
+     */
+    const executeScroll = (elem, newX, newY, time) => {
+      if (elem instanceof Window) {
+        window.scrollTo(newX, newY);
       } else if (elem.nodeType === 9) {
         // @ts-ignore
-        elem.defaultView.scrollTo(elem.defaultView.pageXOffset, value);
+        elem.defaultView.scrollTo(newX, newY);
       } else {
-        elem.scrollTop = value;
+        const startX = elem instanceof Window ? window.scrollX : elem.scrollLeft;
+        const startY = elem instanceof Window ? window.scrollY : elem.scrollTop;
+        if (startX !== newX) elem.scrollLeft = newX;
+        if (startY !== newY) elem.scrollTop = newY;
       }
+      if (typeof onAnimation === 'function')
+        onAnimation({ x: newX, y: newY, isComplete: time >= 1, time });
+    };
+
+    TinyHtml_TinyHtml._preElemsAndWindow(el, 'scrollToXY').forEach((elem) => {
+      const startX = elem instanceof Window ? window.scrollX : elem.scrollLeft;
+      const startY = elem instanceof Window ? window.scrollY : elem.scrollTop;
+      const targX = targetX ?? startX;
+      const targY = targetY ?? startY;
+
+      const changeX = targX - startX;
+      const changeY = targY - startY;
+
+      const ease = (typeof easing === 'string' && TinyHtml_TinyHtml.easings[easing]) || null;
+      if (typeof duration !== 'number' || typeof ease !== 'function')
+        return executeScroll(elem, targX, targY, 1);
+      const startTime = performance.now();
+      const dur = duration ?? 0;
+
+      /**
+       * Animates the scroll position based on easing and time.
+       *
+       * @param {number} currentTime - Timestamp provided by requestAnimationFrame.
+       */
+      function animateScroll(currentTime) {
+        if (typeof ease !== 'function') return;
+        const time = Math.min(1, (currentTime - startTime) / dur);
+        const easedTime = ease(time);
+
+        const newX = startX + changeX * easedTime;
+        const newY = startY + changeY * easedTime;
+        executeScroll(elem, newX, newY, time);
+
+        if (time < 1) requestAnimationFrame(animateScroll);
+      }
+
+      requestAnimationFrame(animateScroll);
     });
     return el;
   }
 
+  /**
+   * Smoothly scrolls one or more elements (or the window) to the specified X and Y coordinates
+   * using a custom duration and easing function.
+   *
+   * If `duration` or a valid `easing` is not provided, the scroll will be performed immediately.
+   *
+   * @param {Object} [settings={}] - Configuration object for the scroll animation.
+   * @param {number} [settings.targetX] - The horizontal scroll target in pixels.
+   * @param {number} [settings.targetY] - The vertical scroll target in pixels.
+   * @param {number} [settings.duration] - The duration of the animation in milliseconds.
+   * @param {Easings} [settings.easing] - The easing function name to use for the scroll animation.
+   * @param {OnScrollAnimation} [settings.onAnimation] - Optional callback invoked on each animation
+   *   frame with the current scroll position, normalized animation time (`0` to `1`), and a completion flag.
+   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
+   */
+  scrollToXY({ targetX, targetY, duration, easing, onAnimation } = {}) {
+    return TinyHtml_TinyHtml.scrollToXY(this, { targetX, targetY, duration, easing, onAnimation });
+  }
+
+  /**
+   * Sets the vertical scroll position.
+   * @param {TinyElementAndWindow|TinyElementAndWindow[]} el - Element or window.
+   * @param {number} value - Scroll top value.
+   * @returns {TinyElementAndWindow|TinyElementAndWindow[]}
+   */
+  static setScrollTop(el, value) {
+    if (typeof value !== 'number') throw new TypeError('ScrollTop value must be a number.');
+    return TinyHtml_TinyHtml.scrollToXY(el, { targetY: value });
+  }
+
   /**
    * Sets the vertical scroll position.
    * @param {number} value - Scroll top value.
@@ -9967,17 +10162,7 @@ class TinyHtml_TinyHtml {
    */
   static setScrollLeft(el, value) {
     if (typeof value !== 'number') throw new TypeError('ScrollLeft value must be a number.');
-    TinyHtml_TinyHtml._preElemsAndWindow(el, 'setScrollLeft').forEach((elem) => {
-      if (TinyHtml_TinyHtml.isWindow(elem)) {
-        elem.scrollTo(value, elem.pageYOffset);
-      } else if (elem.nodeType === 9) {
-        // @ts-ignore
-        elem.defaultView.scrollTo(value, elem.defaultView.pageYOffset);
-      } else {
-        elem.scrollLeft = value;
-      }
-    });
-    return el;
+    return TinyHtml_TinyHtml.scrollToXY(el, { targetX: value });
   }
 
   /**
@@ -10865,12 +11050,120 @@ class TinyHtml_TinyHtml {
 
   ////////////////////////////////////////////
 
+  /**
+   * Registers a listener for the "paste" event to extract files and text from the clipboard (e.g., when the user presses Ctrl+V).
+   *
+   * This method allows reacting to pasted content by providing separate callbacks for files and plain text.
+   * Useful for building file upload areas, rich-text editors, or input enhancements.
+   *
+   * @param {TinyElementWithDoc|TinyElementWithDoc[]} el - The target element(s) where the "paste" event will be listened.
+   * @param {Object} [settings={}] - Optional callbacks to handle clipboard content.
+   * @param {(data: DataTransferItem, file: File) => void} [settings.onFilePaste] - Called for each file pasted from the clipboard (e.g., images).
+   * @param {(data: DataTransferItem, text: string) => void} [settings.onTextPaste] - Called when plain text is pasted from the clipboard.
+   * @returns {EventListenerOrEventListenerObject} The internal "paste" event handler used.
+   */
+  static listenForPaste(el, { onFilePaste, onTextPaste } = {}) {
+    if (typeof onFilePaste !== 'undefined' && typeof onFilePaste !== 'function')
+      throw new TypeError('onFilePaste must be a function.');
+    if (typeof onTextPaste !== 'undefined' && typeof onTextPaste !== 'function')
+      throw new TypeError('onTextPaste must be a function.');
+
+    /** @type {EventListenerOrEventListenerObject} */
+    const pasteEvent = (event) => {
+      if (!(event instanceof ClipboardEvent)) return;
+      const items = event.clipboardData?.items || [];
+      for (const item of items) {
+        if (item.kind === 'file') {
+          if (typeof onFilePaste === 'function') {
+            const file = item.getAsFile();
+            if (file) onFilePaste(item, file);
+          }
+        } else if (item.kind === 'string') {
+          if (typeof onTextPaste === 'function')
+            item.getAsString((text) => onTextPaste(item, text));
+        }
+      }
+    };
+
+    TinyHtml_TinyHtml._preElemsWithDoc(el, 'listenForPaste').forEach((elem) =>
+      TinyHtml_TinyHtml.on(elem, 'paste', pasteEvent),
+    );
+    return pasteEvent;
+  }
+
+  /**
+   * Registers a listener for the "paste" event to extract files and text from the clipboard (e.g., when the user presses Ctrl+V).
+   *
+   * This method allows reacting to pasted content by providing separate callbacks for files and plain text.
+   * Useful for building file upload areas, rich-text editors, or input enhancements.
+   *
+   * @param {Object} [settings={}] - Optional callbacks to handle clipboard content.
+   * @param {(data: DataTransferItem, file: File) => void} [settings.onFilePaste] - Called for each file pasted from the clipboard (e.g., images).
+   * @param {(data: DataTransferItem, text: string) => void} [settings.onTextPaste] - Called when plain text is pasted from the clipboard.
+   * @returns {EventListenerOrEventListenerObject} The internal "paste" event handler used.
+   */
+  listenForPaste({ onFilePaste, onTextPaste } = {}) {
+    return TinyHtml_TinyHtml.listenForPaste(this, { onFilePaste, onTextPaste });
+  }
+
+  /**
+   * Checks if the element has a listener for a specific event.
+   *
+   * @param {TinyEventTarget} el - The element to check.
+   * @param {string} event - The event name to check.
+   * @returns {boolean}
+   */
+  static hasEventListener(el, event) {
+    const elem = TinyHtml_TinyHtml._preEventTargetElem(el, 'hasEventListener');
+    if (!__eventRegistry.has(elem)) return false;
+    const events = __eventRegistry.get(elem);
+    return !!(events && Array.isArray(events[event]) && events[event].length > 0);
+  }
+
+  /**
+   * Checks if the element has a listener for a specific event.
+   *
+   * @param {string} event - The event name to check.
+   * @returns {boolean}
+   */
+  hasEventListener(event) {
+    return TinyHtml_TinyHtml.hasEventListener(this, event);
+  }
+
+  /**
+   * Checks if the element has the exact handler registered for a specific event.
+   *
+   * @param {TinyEventTarget} el - The element to check.
+   * @param {string} event - The event name to check.
+   * @param {EventListenerOrEventListenerObject} handler - The handler function to check.
+   * @returns {boolean}
+   */
+  static hasExactEventListener(el, event, handler) {
+    const elem = TinyHtml_TinyHtml._preEventTargetElem(el, 'hasExactEventListener');
+    if (typeof handler !== 'function') throw new TypeError('The "handler" must be a function.');
+    if (!__eventRegistry.has(elem)) return false;
+    const events = __eventRegistry.get(elem);
+    if (!events || !Array.isArray(events[event])) return false;
+    return events[event].some((item) => item.handler === handler);
+  }
+
+  /**
+   * Checks if the element has the exact handler registered for a specific event.
+   *
+   * @param {string} event - The event name to check.
+   * @param {EventListenerOrEventListenerObject} handler - The handler function to check.
+   * @returns {boolean}
+   */
+  hasExactEventListener(event, handler) {
+    return TinyHtml_TinyHtml.hasExactEventListener(this, event, handler);
+  }
+
   /**
    * Registers an event listener on the specified element.
    *
    * @param {TinyEventTarget|TinyEventTarget[]} el - The target to listen on.
    * @param {string} event - The event type (e.g. 'click', 'keydown').
-   * @param {EventRegistryHandle} handler - The callback function to run on event.
+   * @param {EventListenerOrEventListenerObject|null} handler - The callback function to run on event.
    * @param {EventRegistryOptions} [options] - Optional event listener options.
    * @returns {TinyEventTarget|TinyEventTarget[]}
    */
@@ -10892,7 +11185,7 @@ class TinyHtml_TinyHtml {
    * Registers an event listener on the specified element.
    *
    * @param {string} event - The event type (e.g. 'click', 'keydown').
-   * @param {EventRegistryHandle} handler - The callback function to run on event.
+   * @param {EventListenerOrEventListenerObject|null} handler - The callback function to run on event.
    * @param {EventRegistryOptions} [options] - Optional event listener options.
    * @returns {TinyEventTarget|TinyEventTarget[]}
    */
@@ -10905,17 +11198,17 @@ class TinyHtml_TinyHtml {
    *
    * @param {TinyEventTarget|TinyEventTarget[]} el - The target to listen on.
    * @param {string} event - The event type (e.g. 'click', 'keydown').
-   * @param {EventRegistryHandle} handler - The callback function to run on event.
+   * @param {EventListenerOrEventListenerObject} handler - The callback function to run on event.
    * @param {EventRegistryOptions} [options={}] - Optional event listener options.
    * @returns {TinyEventTarget|TinyEventTarget[]}
    */
   static once(el, event, handler, options = {}) {
     if (typeof event !== 'string') throw new TypeError('The event name must be a string.');
     TinyHtml_TinyHtml._preEventTargetElems(el, 'once').forEach((elem) => {
-      /** @type {EventRegistryHandle} e */
+      /** @type {EventListenerOrEventListenerObject} */
       const wrapped = (e) => {
         TinyHtml_TinyHtml.off(elem, event, wrapped);
-        handler(e);
+        if (typeof handler === 'function') handler(e);
       };
 
       TinyHtml_TinyHtml.on(
@@ -10932,7 +11225,7 @@ class TinyHtml_TinyHtml {
    * Registers an event listener that runs only once, then is removed.
    *
    * @param {string} event - The event type (e.g. 'click', 'keydown').
-   * @param {EventRegistryHandle} handler - The callback function to run on event.
+   * @param {EventListenerOrEventListenerObject} handler - The callback function to run on event.
    * @param {EventRegistryOptions} [options={}] - Optional event listener options.
    * @returns {TinyEventTarget|TinyEventTarget[]}
    */
@@ -10945,7 +11238,7 @@ class TinyHtml_TinyHtml {
    *
    * @param {TinyEventTarget|TinyEventTarget[]} el - The target element.
    * @param {string} event - The event type.
-   * @param {EventRegistryHandle} handler - The function originally bound to the event.
+   * @param {EventListenerOrEventListenerObject|null} handler - The function originally bound to the event.
    * @param {boolean|EventListenerOptions} [options] - Optional listener options.
    * @returns {TinyEventTarget|TinyEventTarget[]}
    */
@@ -10967,7 +11260,7 @@ class TinyHtml_TinyHtml {
    * Removes a specific event listener from an element.
    *
    * @param {string} event - The event type.
-   * @param {EventRegistryHandle} handler - The function originally bound to the event.
+   * @param {EventListenerOrEventListenerObject|null} handler - The function originally bound to the event.
    * @param {boolean|EventListenerOptions} [options] - Optional listener options.
    * @returns {TinyEventTarget|TinyEventTarget[]}
    */
@@ -11010,7 +11303,7 @@ class TinyHtml_TinyHtml {
    * Removes all event listeners of all types from the element.
    *
    * @param {TinyEventTarget|TinyEventTarget[]} el - The target element.
-   * @param {((handler: EventListenerOrEventListenerObject, event: string) => boolean)|null} [filterFn=null] -
+   * @param {((handler: EventListenerOrEventListenerObject|null, event: string) => boolean)|null} [filterFn=null] -
    *        Optional filter function to selectively remove specific handlers.
    * @returns {TinyEventTarget|TinyEventTarget[]}
    */
@@ -11037,7 +11330,7 @@ class TinyHtml_TinyHtml {
   /**
    * Removes all event listeners of all types from the element.
    *
-   * @param {((handler: EventListenerOrEventListenerObject, event: string) => boolean)|null} [filterFn=null] -
+   * @param {((handler: EventListenerOrEventListenerObject|null, event: string) => boolean)|null} [filterFn=null] -
    *        Optional filter function to selectively remove specific handlers.
    * @returns {TinyEventTarget|TinyEventTarget[]}
    */
@@ -16373,6 +16666,884 @@ class TinySmartScroller {
 
 /* harmony default export */ const libs_TinySmartScroller = (TinySmartScroller);
 
+;// ./src/v1/libs/TinyTextRangeEditor.mjs
+/**
+ * A full-featured text range editor for `<input>` and `<textarea>` elements,
+ * including advanced utilities for BBCode or similar tag-based markup editing.
+ */
+class TinyTextRangeEditor {
+  /** @type {HTMLInputElement | HTMLTextAreaElement} */
+  #el;
+
+  /** @type {string} */
+  #openTag;
+
+  /** @type {string} */
+  #closeTag;
+
+  /**
+   * @param {HTMLInputElement | HTMLTextAreaElement} elem - The target editable input or textarea element.
+   * @param {Object} [settings={}] - Optional tag symbol customization.
+   * @param {string} [settings.openTag='['] - The character or symbol used to start a tag (e.g., `'['`).
+   * @param {string} [settings.closeTag=']'] - The character or symbol used to end a tag (e.g., `']'`).
+   */
+  constructor(elem, { openTag = '[', closeTag = ']' } = {}) {
+    if (!(elem instanceof HTMLInputElement || elem instanceof HTMLTextAreaElement))
+      throw new TypeError('Element must be an input or textarea.');
+    if (typeof openTag !== 'string') throw new TypeError('openTag must be a string.');
+    if (typeof closeTag !== 'string') throw new TypeError('closeTag must be a string.');
+    this.#el = elem;
+    this.#openTag = openTag;
+    this.#closeTag = closeTag;
+  }
+
+  /** @returns {string} The current open tag symbol. */
+  getOpenTag() {
+    return this.#openTag;
+  }
+
+  /** @returns {string} The current close tag symbol. */
+  getCloseTag() {
+    return this.#closeTag;
+  }
+
+  /** @param {string} tag - New open tag symbol to use (e.g., `'['`). */
+  setOpenTag(tag) {
+    if (typeof tag !== 'string') throw new TypeError('Open tag must be a string.');
+    this.#openTag = tag;
+  }
+
+  /** @param {string} tag - New close tag symbol to use (e.g., `']'`). */
+  setCloseTag(tag) {
+    if (typeof tag !== 'string') throw new TypeError('Close tag must be a string.');
+    this.#closeTag = tag;
+  }
+
+  /**
+   * Ensures the element has focus.
+   * @returns {TinyTextRangeEditor}
+   */
+  ensureFocus() {
+    if (document.activeElement !== this.#el) this.#el.focus();
+    return this;
+  }
+
+  /**
+   * Focus the element.
+   * @returns {TinyTextRangeEditor}
+   */
+  focus() {
+    this.#el.focus();
+    return this;
+  }
+
+  /** @returns {{ start: number, end: number }} The current selection range. */
+  getSelectionRange() {
+    return {
+      start: this.#el.selectionStart ?? NaN,
+      end: this.#el.selectionEnd ?? NaN,
+    };
+  }
+
+  /**
+   * Sets the current selection range.
+   * @param {number} start - Start index.
+   * @param {number} end - End index.
+   * @param {boolean} [preserveScroll=true] - Whether to preserve scroll position.
+   * @returns {TinyTextRangeEditor}
+   */
+  setSelectionRange(start, end, preserveScroll = true) {
+    if (typeof start !== 'number' || typeof end !== 'number')
+      throw new TypeError('start and end must be numbers.');
+    if (typeof preserveScroll !== 'boolean')
+      throw new TypeError('preserveScroll must be a boolean.');
+    const scrollTop = this.#el.scrollTop;
+    const scrollLeft = this.#el.scrollLeft;
+    this.#el.setSelectionRange(start, end);
+    if (preserveScroll) {
+      this.#el.scrollTop = scrollTop;
+      this.#el.scrollLeft = scrollLeft;
+    }
+    return this;
+  }
+
+  /** @returns {string} The full current text value. */
+  getValue() {
+    return this.#el.value;
+  }
+
+  /**
+   * Sets the full value of the element.
+   * @param {string} value - The new value to assign.
+   * @returns {TinyTextRangeEditor}
+   */
+  setValue(value) {
+    if (typeof value !== 'string') throw new TypeError('Value must be a string.');
+    this.#el.value = value;
+    return this;
+  }
+
+  /** @returns {string} The currently selected text. */
+  getSelectedText() {
+    const { start, end } = this.getSelectionRange();
+    return this.#el.value.slice(start, end);
+  }
+
+  /**
+   * Inserts text at the current selection, replacing any selected content.
+   * @param {string} text - The text to insert.
+   * @param {Object} [settings={}] - Optional auto-spacing behavior.
+   * @param {'start' | 'end' | 'preserve'} [settings.newCursor='end'] - Controls caret position after insertion.
+   * @param {boolean} [settings.autoSpacing=false]
+   * @param {boolean} [settings.autoSpaceLeft=false]
+   * @param {boolean} [settings.autoSpaceRight=false]
+   * @returns {TinyTextRangeEditor}
+   */
+  insertText(
+    text,
+    {
+      newCursor = 'end',
+      autoSpacing = false,
+      autoSpaceLeft = autoSpacing,
+      autoSpaceRight = autoSpacing,
+    } = {},
+  ) {
+    if (typeof text !== 'string') throw new TypeError('Text must be a string.');
+    if (!['start', 'end', 'preserve'].includes(newCursor))
+      throw new TypeError("newCursor must be one of 'start', 'end', or 'preserve'.");
+    if (typeof autoSpacing !== 'boolean') throw new TypeError('autoSpacing must be a boolean.');
+    if (typeof autoSpaceLeft !== 'boolean') throw new TypeError('autoSpaceLeft must be a boolean.');
+    if (typeof autoSpaceRight !== 'boolean')
+      throw new TypeError('autoSpaceRight must be a boolean.');
+
+    const { start, end } = this.getSelectionRange();
+    const value = this.#el.value;
+
+    const leftChar = value[start - 1] || '';
+    const rightChar = value[end] || '';
+
+    const addLeft = autoSpaceLeft && leftChar && !/\s/.test(leftChar);
+    const addRight = autoSpaceRight && rightChar && !/\s/.test(rightChar);
+
+    const finalText = `${addLeft ? ' ' : ''}${text}${addRight ? ' ' : ''}`;
+
+    const newValue = value.slice(0, start) + finalText + value.slice(end);
+    this.setValue(newValue);
+
+    let cursorPos = start;
+    if (newCursor === 'end') cursorPos = start + finalText.length;
+    else if (newCursor === 'preserve') cursorPos = start;
+
+    this.setSelectionRange(cursorPos, cursorPos);
+    return this;
+  }
+
+  /**
+   * Deletes the currently selected text.
+   * @returns {TinyTextRangeEditor}
+   */
+  deleteSelection() {
+    this.insertText('');
+    return this;
+  }
+
+  /**
+   * Replaces the selection using a transformation function.
+   * @param {(selected: string) => string} transformer - Function that modifies the selected text.
+   * @returns {TinyTextRangeEditor}
+   */
+  transformSelection(transformer) {
+    if (typeof transformer !== 'function') throw new TypeError('transformer must be a function.');
+    const { start } = this.getSelectionRange();
+    const selected = this.getSelectedText();
+    const transformed = transformer(selected);
+    this.insertText(transformed);
+    this.setSelectionRange(start, start + transformed.length);
+    return this;
+  }
+
+  /**
+   * Surrounds current selection with prefix and suffix.
+   * @param {string} prefix - Text to insert before.
+   * @param {string} suffix - Text to insert after.
+   * @returns {TinyTextRangeEditor}
+   */
+  surroundSelection(prefix, suffix) {
+    if (typeof prefix !== 'string' || typeof suffix !== 'string')
+      throw new TypeError('prefix and suffix must be strings.');
+    const selected = this.getSelectedText();
+    this.insertText(`${prefix}${selected}${suffix}`);
+    return this;
+  }
+
+  /**
+   * Moves the caret by a given offset.
+   * @param {number} offset - Characters to move.
+   * @returns {TinyTextRangeEditor}
+   */
+  moveCaret(offset) {
+    if (typeof offset !== 'number') throw new TypeError('offset must be a number.');
+    const { start } = this.getSelectionRange();
+    const pos = Math.max(0, start + offset);
+    this.setSelectionRange(pos, pos);
+    return this;
+  }
+
+  /**
+   * Selects all content in the field.
+   * @returns {TinyTextRangeEditor}
+   */
+  selectAll() {
+    this.setSelectionRange(0, this.#el.value.length);
+    return this;
+  }
+
+  /**
+   * Expands the current selection by character amounts.
+   * @param {number} before - Characters to expand to the left.
+   * @param {number} after - Characters to expand to the right.
+   * @returns {TinyTextRangeEditor}
+   */
+  expandSelection(before, after) {
+    if (typeof before !== 'number' || typeof after !== 'number')
+      throw new TypeError('before and after must be numbers.');
+    const { start, end } = this.getSelectionRange();
+    const newStart = Math.max(0, start - before);
+    const newEnd = Math.min(this.#el.value.length, end + after);
+    this.setSelectionRange(newStart, newEnd);
+    return this;
+  }
+
+  /**
+   * Replaces all regex matches in the content.
+   * @param {RegExp} regex - Regex to match.
+   * @param {(match: string) => string} replacer - Replacement function.
+   * @returns {TinyTextRangeEditor}
+   */
+  replaceAll(regex, replacer) {
+    if (!(regex instanceof RegExp)) throw new TypeError('regex must be a RegExp.');
+    if (typeof replacer !== 'function') throw new TypeError('replacer must be a function.');
+    const newValue = this.#el.value.replace(regex, replacer);
+    this.setValue(newValue);
+    return this;
+  }
+
+  /**
+   * Replaces all regex matches within the currently selected text.
+   *
+   * @param {RegExp} regex - Regular expression to match inside selection.
+   * @param {(match: string) => string} replacer - Function to replace each match.
+   * @returns {TinyTextRangeEditor}
+   */
+  replaceInSelection(regex, replacer) {
+    if (!(regex instanceof RegExp)) throw new TypeError('regex must be a RegExp.');
+    if (typeof replacer !== 'function') throw new TypeError('replacer must be a function.');
+
+    const { start, end } = this.getSelectionRange();
+    const original = this.#el.value;
+    const selected = original.slice(start, end);
+
+    const replaced = selected.replace(regex, replacer);
+
+    const updated = original.slice(0, start) + replaced + original.slice(end);
+
+    this.setValue(updated);
+    this.setSelectionRange(start, start + replaced.length);
+    return this;
+  }
+
+  /**
+   * Toggles a code around the current selection.
+   * If it's already wrapped, unwraps it.
+   * @param {string} codeName - The code to toggle.
+   * @returns {TinyTextRangeEditor}
+   */
+  toggleCode(codeName) {
+    if (typeof codeName !== 'string') throw new TypeError('codeName must be a string.');
+    const selected = this.getSelectedText();
+    if (selected.startsWith(codeName) && selected.endsWith(codeName)) {
+      const unwrapped = selected.slice(codeName.length, selected.length - codeName.length);
+      this.insertText(unwrapped);
+    } else {
+      this.insertText(`${codeName}${selected}${codeName}`);
+    }
+    return this;
+  }
+
+  /**
+   * Converts a list of attributes into a string suitable for tag insertion.
+   *
+   * This method supports both standard key-value attribute objects (e.g., `{ key: "value" }`)
+   * and boolean-style attribute arrays (e.g., `[ "disabled", "autofocus" ]`).
+   *
+   * - Attributes passed as an array will render as boolean attributes (e.g., `disabled autofocus`)
+   * - Attributes passed as an object will render as `key="value"` pairs (or just `key` if the value is an empty string)
+   *
+   * @param {Record<string, string> | string[]} attributes - The attributes to serialize into a tag string.
+   *   - If an array: treated as a list of boolean-style attributes.
+   *   - If an object: treated as key-value pairs.
+   *
+   * @throws {TypeError} If the array contains non-strings, or the object contains non-string values.
+   * @returns {string} A string of serialized attributes for use inside a tag.
+   *
+   * @example
+   * // Using object attributes
+   * _insertAttr({ size: "12", color: "red" });
+   * // Returns: 'size="12" color="red"'
+   *
+   * @example
+   * // Using boolean attributes
+   * _insertAttr(["disabled", "autofocus"]);
+   * // Returns: 'disabled autofocus'
+   *
+   * @example
+   * // Using mixed/empty object values
+   * _insertAttr({ checked: "", class: "btn" });
+   * // Returns: 'checked class="btn"'
+   */
+  _insertAttr(attributes) {
+    // Reuse attribute logic
+    let attrStr = '';
+
+    if (Array.isArray(attributes)) {
+      // string[]
+      if (!attributes.every((attr) => typeof attr === 'string'))
+        throw new TypeError('All entries in attributes array must be strings.');
+      attrStr = attributes.map((attr) => `${attr}`).join(' ');
+    } else if (typeof attributes === 'object' && attributes !== null) {
+      // Record<string, string>
+      attrStr = Object.entries(attributes)
+        .map(([key, val]) => {
+          if (typeof val !== 'string')
+            throw new TypeError('All entries in attributes object must be strings.');
+          return `${key}${val.length > 0 ? `="${val}"` : ''}`;
+        })
+        .join(' ');
+    } else {
+      throw new TypeError('attributes must be an object or an array of strings.');
+    }
+
+    return attrStr;
+  }
+
+  /**
+   * Wraps the current selection with a tag, optionally including attributes.
+   *
+   * @param {string} tagName - The tag name (e.g., `b`, `color`, etc.).
+   * @param {Record<string,string> | string[]} [attributes={}] - Optional attributes for the opening tag.
+   *   - If an object: key-value pairs (e.g., `{ color: "red" }` → `color="red"`).
+   *   - If an array: boolean attributes (e.g., `["disabled", "readonly"]`).
+   *
+   * @returns {TinyTextRangeEditor}
+   */
+  wrapWithTag(tagName, attributes = {}) {
+    if (typeof tagName !== 'string') throw new TypeError('tagName must be a string.');
+    const attrStr = this._insertAttr(attributes);
+    const openTag = attrStr
+      ? `${this.#openTag}${tagName} ${attrStr}${this.#closeTag}`
+      : `${this.#openTag}${tagName}${this.#closeTag}`;
+    const closeTag = `${this.#openTag}/${tagName}${this.#closeTag}`;
+    this.surroundSelection(openTag, closeTag);
+    return this;
+  }
+
+  /**
+   * Inserts a tag with optional inner content.
+   * @param {string} tagName - The tag to insert.
+   * @param {string} [content=''] - Optional content between tags.
+   * @param {Record<string,string> | string[]} [attributes={}] - Optional attributes or list of empty attributes.
+   * @returns {TinyTextRangeEditor}
+   */
+  insertTag(tagName, content = '', attributes = {}) {
+    if (typeof tagName !== 'string') throw new TypeError('tagName must be a string.');
+    if (typeof content !== 'string') throw new TypeError('content must be a string.');
+
+    const attrStr = this._insertAttr(attributes);
+    const open = attrStr
+      ? `${this.#openTag}${tagName} ${attrStr}${this.#closeTag}`
+      : `${this.#openTag}${tagName}${this.#closeTag}`;
+    const close = `${this.#openTag}/${tagName}${this.#closeTag}`;
+
+    this.insertText(`${open}${content}${close}`);
+    return this;
+  }
+
+  /**
+   * Inserts a self-closing tag.
+   * @param {string} tagName - The tag name.
+   * @param {Record<string,string> | string[]} [attributes={}] - Optional attributes or list of empty attributes.
+   * @returns {TinyTextRangeEditor}
+   */
+  insertSelfClosingTag(tagName, attributes = {}) {
+    if (typeof tagName !== 'string') throw new TypeError('tagName must be a string.');
+
+    const attrStr = this._insertAttr(attributes);
+    const tag = attrStr
+      ? `${this.#openTag}${tagName} ${attrStr}${this.#closeTag}`
+      : `${this.#openTag}${tagName}${this.#closeTag}`;
+
+    this.insertText(tag);
+    return this;
+  }
+
+  /**
+   * Toggles a tag around the current selection.
+   * Supports tags with attributes. If already wrapped, it unwraps.
+   * @param {string} tagName - The tag to toggle.
+   * @param {Record<string,string> | string[]} [attributes={}] - Optional attributes to apply when wrapping.
+   * @returns {TinyTextRangeEditor}
+   */
+  toggleTag(tagName, attributes = {}) {
+    if (typeof tagName !== 'string') throw new TypeError('tagName must be a string.');
+    const selected = this.getSelectedText();
+
+    // Regex: opening tag with optional attributes, and closing tag
+    const openRegex = new RegExp(`^\\[${tagName}(\\s+[^\\]]*)?\\]`);
+    const closeRegex = new RegExp(`\\[/${tagName}\\]$`);
+
+    const hasOpen = openRegex.test(selected);
+    const hasClose = closeRegex.test(selected);
+
+    if (hasOpen && hasClose) {
+      const unwrapped = selected
+        .replace(openRegex, '') // remove opening tag
+        .replace(closeRegex, ''); // remove closing tag
+      this.insertText(unwrapped);
+    } else {
+      const attrStr = this._insertAttr(attributes);
+      const open = attrStr
+        ? `${this.#openTag}${tagName} ${attrStr}${this.#closeTag}`
+        : `${this.#openTag}${tagName}${this.#closeTag}`;
+      const close = `${this.#openTag}/${tagName}${this.#closeTag}`;
+      this.insertText(`${open}${selected}${close}`);
+    }
+
+    return this;
+  }
+}
+
+/* harmony default export */ const libs_TinyTextRangeEditor = (TinyTextRangeEditor);
+
+;// ./src/v1/libs/TinyClipboard.mjs
+/**
+ * Utility class to handle clipboard operations for text and blob data.
+ * Supports modern Clipboard API, custom platform, and legacy execCommand fallback.
+ */
+class TinyClipboard {
+  /**
+   * Indicates whether the legacy `document.execCommand()` API is available.
+   * Used as a fallback for clipboard operations when modern APIs are not supported.
+   *
+   * @type {boolean}
+   */
+  #existExecCommand = false;
+
+  /**
+   * Indicates whether the modern Clipboard API (`navigator.clipboard`) is available.
+   *
+   * @type {boolean}
+   */
+  #existNavigator = false;
+
+  /**
+   * Function used to copy plain text to the clipboard.
+   * Can be overridden using `setCopyText()`.
+   *
+   * @type {((text: string) => Promise<void>) | null}
+   */
+  #copyText = null;
+
+  /**
+   * Function used to copy a Blob (binary data) to the clipboard.
+   * Can be overridden using `setCopyBlob()`.
+   *
+   * @type {((blob: Blob) => Promise<void>) | null}
+   */
+  #copyBlob = null;
+
+  /**
+   * Constructs a new TinyClipboard instance.
+   * Automatically detects and configures available clipboard APIs.
+   */
+  constructor() {
+    // Whether the Clipboard API is available.
+    if (typeof navigator.clipboard !== 'undefined' && navigator.clipboard !== null) {
+      this.#existNavigator = true;
+      this.#copyText = (text) => navigator.clipboard.writeText(text);
+      this.#copyBlob = (blob) =>
+        navigator.clipboard.write([
+          new ClipboardItem({
+            [blob.type]: blob,
+          }),
+        ]);
+    }
+
+    /**
+     * @type {boolean}
+     * Whether the legacy execCommand API is available.
+     */
+    this.#existExecCommand =
+      typeof document.execCommand !== 'undefined' && document.execCommand !== null;
+  }
+
+  /**
+   * Override the default text copy behavior.
+   * This allows you to provide your own clipboard implementation or
+   * integrate with external systems like Capacitor or Electron.
+   *
+   * @param {(text: string) => Promise<void>} callback - The function to use for copying text.
+   * @throws {TypeError} If the callback is not a function.
+   */
+  setCopyText(callback) {
+    if (typeof callback !== 'function')
+      throw new TypeError('setCopyText expected a function that returns Promise<void>.');
+    this.#copyText = callback;
+  }
+
+  /**
+   * Override the default blob copy behavior.
+   * This allows you to provide a custom clipboard handling method for blob data.
+   *
+   * @param {(blob: Blob) => Promise<void>} callback - The function to use for copying blob data.
+   * @throws {TypeError} If the callback is not a function.
+   */
+  setCopyBlob(callback) {
+    if (typeof callback !== 'function')
+      throw new TypeError('setCopyBlob expected a function that returns Promise<void>.');
+    this.#copyBlob = callback;
+  }
+
+  /**
+   * Copy a plain text string to the clipboard.
+   * Uses modern or legacy fallback.
+   *
+   * @param {string} text - The text string to be copied.
+   * @returns {Promise<void>} A promise resolving when the text is copied or boolean for legacy.
+   */
+  copyText(text) {
+    if (typeof text !== 'string') throw new TypeError('copyText expected a string.');
+    // Clipboard API
+    if (this.#copyText) return this.#copyText(text);
+    // Classic API
+    else if (this.#existExecCommand) {
+      const host = document.body;
+      const copyInput = document.createElement('input');
+      copyInput.style.position = 'fixed';
+      copyInput.style.opacity = '0';
+      copyInput.value = text;
+      host.append(copyInput);
+
+      copyInput.select();
+      copyInput.setSelectionRange(0, 99999);
+      document.execCommand('Copy');
+      copyInput.remove();
+      return new Promise((resolve) => resolve(undefined));
+    }
+    throw new Error('Clipboard API not found!');
+  }
+
+  /**
+   * Copy a Blob (binary data) to the clipboard.
+   *
+   * @param {Blob} blob - The blob object to copy.
+   * @returns {Promise<void>} A promise that resolves when the blob is copied or null on fallback.
+   */
+  copyBlob(blob) {
+    if (!(blob instanceof Blob)) throw new TypeError('copyBlob expected a Blob instance.');
+    return new Promise((resolve, reject) => {
+      if (this.#copyBlob) {
+        return this.#copyBlob(blob).then(resolve).catch(reject);
+      }
+      throw new Error('Clipboard API not found!');
+    });
+  }
+
+  /**
+   * Internal: Handle getting blob data from a clipboard item.
+   *
+   * @private
+   * @param {string} type - The MIME type to fetch.
+   * @param {ClipboardItem} clipboardItem - Clipboard item instance.
+   * @returns {Promise<Blob>} A promise that resolves with the Blob.
+   */
+  _handleBlob(type, clipboardItem) {
+    return clipboardItem.getType(type);
+  }
+
+  /**
+   * Internal: Handle getting plain text from a clipboard item.
+   *
+   * @private
+   * @param {string} type - The MIME type (should be 'text/plain').
+   * @param {ClipboardItem} clipboardItem - Clipboard item instance.
+   * @returns {Promise<string>} A promise that resolves with the text content.
+   */
+  _handleText(type, clipboardItem) {
+    return this._handleBlob(type, clipboardItem).then((blob) => blob.text());
+  }
+
+  /**
+   * Read clipboard data based on filters like type, mime, index.
+   *
+   * @param {number|null} [index=0] - Item index or null for all.
+   * @param {'text'|'custom'|null} [type=null] - Data type to filter.
+   * @param {string|null} [mimeFormat=null] - MIME type or prefix.
+   * @param {boolean} [fixValue=false] - If true, exact match on MIME type.
+   * @returns {Promise<Blob|string|Array<Blob|string>|null>} A promise resolving with matching data.
+   */
+  _readData(index = 0, type = null, mimeFormat = null, fixValue = false) {
+    return new Promise((resolve, reject) => {
+      this._read(index)
+        .then((items) => {
+          if (!items) return resolve(null);
+          /** @type {Array<Blob|string>} */
+          const finalResult = [];
+
+          // Complete task
+          let continueLoop = true;
+
+          /**
+           * @param {string} mimeType
+           * @param {ClipboardItem} item
+           */
+          const completeTask = async (mimeType, item) => {
+            if (!continueLoop) return;
+            // Custom
+            if (
+              (type === null || type === 'custom') &&
+              typeof mimeFormat === 'string' &&
+              ((!fixValue && mimeType.startsWith(mimeFormat)) ||
+                (fixValue && mimeType === mimeFormat))
+            ) {
+              continueLoop = false;
+              const result = await this._handleBlob(mimeType, item);
+              if (result) finalResult.push(result);
+            }
+
+            // Text
+            else if ((type === null || type === 'text') && mimeType === 'text/plain') {
+              continueLoop = false;
+              const result = await this._handleText(mimeType, item);
+              if (result) finalResult.push(result);
+            }
+
+            // Blob
+            else if (type === null) {
+              continueLoop = false;
+              const result = await this._handleBlob(mimeType, item);
+              if (result) finalResult.push(result);
+            }
+          };
+
+          /** @type {Promise<void>[]} */
+          const promises = [];
+
+          /**
+           * Read Item
+           * @param {ClipboardItem | ClipboardItems} item
+           */
+          const readItem = (item) => {
+            if (!(item instanceof ClipboardItem))
+              throw new Error('Expected ClipboardItem when reading data.');
+            for (const tIndex in item.types) promises.push(completeTask(item.types[tIndex], item));
+          };
+
+          // Specific Item
+          if (
+            typeof index === 'number' &&
+            !Number.isNaN(index) &&
+            Number.isFinite(index) &&
+            index > -1
+          ) {
+            readItem(items);
+            Promise.all(promises)
+              .then(() => {
+                if (finalResult[0]) resolve(finalResult[0]);
+                else resolve(null);
+              })
+              .catch(reject);
+          }
+
+          // All
+          else if (Array.isArray(items)) {
+            for (const tIndex in items) readItem(items[tIndex]);
+            Promise.all(promises)
+              .then(() => resolve(finalResult))
+              .catch(reject);
+          }
+        })
+        // Fail
+        .catch(reject);
+    });
+  }
+
+  /**
+   * Read plain text from the clipboard (single item by index).
+   *
+   * @param {number} [index=0] - The index of the clipboard item to read.
+   * @returns {Promise<string|null>} A promise that resolves to the clipboard text or null.
+   */
+  async readText(index = 0) {
+    const value = await this._readData(index, 'text');
+    if (typeof value !== 'string') throw new Error('Failed to read text: expected string result.');
+    return value;
+  }
+
+  /**
+   * Read custom clipboard data based on MIME type from a specific index.
+   *
+   * @param {string|null} [mimeFormat=null] - MIME prefix to match (e.g., "image/").
+   * @param {boolean} [fixValue=false] - If true, matches exact MIME instead of prefix.
+   * @param {number} [index=0] - Clipboard item index.
+   * @returns {Promise<Blob|null>} A promise resolving with a blob or null.
+   */
+  async readCustom(mimeFormat = null, fixValue = false, index = 0) {
+    const value = await this._readData(index, 'custom', mimeFormat, fixValue);
+    if (!(value instanceof Blob)) throw new Error('Failed to read custom data: expected Blob.');
+    return value;
+  }
+
+  /**
+   * Read all available plain text entries from the clipboard.
+   *
+   * @returns {Promise<string[]>} A promise resolving to an array of strings or null.
+   */
+  async readAllTexts() {
+    const values = await this._readData(null, 'text');
+    if (!Array.isArray(values))
+      throw new Error('Expected array of strings when reading all texts.');
+    if (!values.every((value) => typeof value === 'string'))
+      throw new Error('Some values returned were not strings.');
+    return values;
+  }
+
+  /**
+   * Read all clipboard data matching a specific custom MIME type.
+   *
+   * @param {string|null} [mimeFormat=null] - MIME prefix or exact type.
+   * @param {boolean} [fixValue=false] - Match prefix or exact MIME.
+   * @returns {Promise<Blob[]>} A promise resolving with array of Blobs or null.
+   */
+  async readAllCustom(mimeFormat = null, fixValue = false) {
+    const values = await this._readData(null, 'custom', mimeFormat, fixValue);
+    if (!Array.isArray(values))
+      throw new Error('Expected array of blobs when reading all custom items.');
+    if (!values.every((value) => value instanceof Blob))
+      throw new Error('Some values returned were not Blob instances.');
+    return values;
+  }
+
+  /**
+   * Read all clipboard data as Blob or text depending on type.
+   *
+   * @param {'text'|'custom'|null} [type=null] - The type of data to retrieve.
+   * @param {string|null} [mimeFormat=null] - The MIME type or prefix to match.
+   * @returns {Promise<Array<Blob|string>>} A promise resolving with matching data array.
+   */
+  async readAllData(type = null, mimeFormat = null) {
+    const value = await this._readData(null, type, mimeFormat);
+    if (!Array.isArray(value)) throw new Error('Expected array result when reading all data.');
+    return value;
+  }
+
+  /**
+   * Read clipboard data at a specific index or all if null.
+   *
+   * @param {number|null} index - Index of the item to retrieve or null to get all.
+   * @returns {Promise<ClipboardItem|ClipboardItems|null>} A promise resolving with a clipboard item or array of items.
+   */
+  _read(index) {
+    return new Promise((resolve, reject) => {
+      if (!this.#existNavigator) reject(new Error('Clipboard API not found!'));
+      navigator.clipboard
+        .read()
+        .then((items) => {
+          // Index is number
+          if (typeof index === 'number') {
+            if (Number.isNaN(index) || !Number.isFinite(index) || index < 0)
+              throw new Error(`Invalid index value: ${index}`);
+            if (items[index]) resolve(items[index]);
+            // Not found
+            else resolve(null);
+          }
+          // Get All
+          resolve(items);
+        })
+        .catch(reject);
+    });
+  }
+
+  /**
+   * Read clipboard data at a specific index.
+   *
+   * @param {number} index - Index of the item to retrieve
+   * @returns {Promise<ClipboardItem|null>} A promise resolving with a clipboard item.
+   */
+  async readIndex(index) {
+    const value = await this._read(index);
+    if (value !== null && !(value instanceof ClipboardItem))
+      throw new Error(`Value at index ${index} is not a ClipboardItem.`);
+    return value;
+  }
+
+  /**
+   * Read all clipboard content without any filters.
+   *
+   * @returns {Promise<ClipboardItems>} A promise resolving with all clipboard items.
+   */
+  async readAll() {
+    const value = await this._read(null);
+    if (!Array.isArray(value)) throw new Error('Expected array result from clipboard read.');
+    for (const item of value) {
+      if (!(item instanceof ClipboardItem))
+        throw new Error('Invalid item type found in clipboard result.');
+    }
+    return value;
+  }
+
+  /**
+   * Returns whether the legacy `document.execCommand()` API is available.
+   * This can be used to determine if a fallback clipboard method is usable.
+   *
+   * @returns {boolean} True if `document.execCommand` is available.
+   */
+  isExecCommandAvailable() {
+    return this.#existExecCommand;
+  }
+
+  /**
+   * Returns whether the modern Clipboard API (`navigator.clipboard`) is available.
+   * Useful to know if full clipboard features can be accessed.
+   *
+   * @returns {boolean} True if `navigator.clipboard` is available.
+   */
+  isNavigatorClipboardAvailable() {
+    return this.#existNavigator;
+  }
+
+  /**
+   * Returns the function used to copy plain text to the clipboard.
+   * This function may be built-in or set manually via `setCopyText`.
+   *
+   * @returns {((text: string) => Promise<void>) | null} The current text copy function or null if unavailable.
+   */
+  getCopyTextFunc() {
+    return this.#copyText;
+  }
+
+  /**
+   * Returns the function used to copy Blob (binary data) to the clipboard.
+   * This function may be built-in or set manually via `setCopyBlob`.
+   *
+   * @returns {((blob: Blob) => Promise<void>) | null} The current blob copy function or null if unavailable.
+   */
+  getCopyBlobFunc() {
+    return this.#copyBlob;
+  }
+}
+
+/* harmony default export */ const libs_TinyClipboard = (TinyClipboard);
+
 ;// ./src/v1/index.mjs
 
 
@@ -16404,6 +17575,8 @@ class TinySmartScroller {
 
 
 
+
+