tiny-essentials 1.17.1 → 1.18.1

package/dist/v1/TinyUploadClicker.js

@@ -2912,9 +2912,55 @@ __webpack_require__.d(collision_namespaceObject, {
 
 // EXTERNAL MODULE: ./node_modules/buffer/index.js
 var buffer = __webpack_require__(287);
+;// ./src/v1/basics/objChecker.mjs
+/**
+ * Counts the number of elements in an array or the number of properties in an object.
+ *
+ * @param {Array<*>|Record<string | number | symbol, any>} obj - The array or object to count.
+ * @returns {number} - The count of items (array elements or object keys), or `0` if the input is neither an array nor an object.
+ *
+ * @example
+ * countObj([1, 2, 3]); // 3
+ * countObj({ a: 1, b: 2 }); // 2
+ * countObj('not an object'); // 0
+ */
+function countObj(obj) {
+  // Is Array
+  if (Array.isArray(obj)) return obj.length;
+  // Object
+  if (isJsonObject(obj)) return Object.keys(obj).length;
+  // Nothing
+  return 0;
+}
+
+/**
+ * Determines whether a given value is a pure JSON object (plain object).
+ *
+ * A pure object satisfies the following:
+ * - It is not null.
+ * - Its type is "object".
+ * - Its internal [[Class]] is "[object Object]".
+ * - It is not an instance of built-in types like Array, Date, Map, Set, etc.
+ *
+ * This function is useful for strict data validation when you want to ensure
+ * a value is a clean JSON-compatible object, free of class instances or special types.
+ *
+ * @param {unknown} value - The value to test.
+ * @returns {value is Record<string | number | symbol, unknown>} Returns true if the value is a pure object.
+ */
+function isJsonObject(value) {
+  if (value === null || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return false;
+  if (Object.prototype.toString.call(value) !== '[object Object]') return false;
+  return true;
+}
+
 ;// ./src/v1/basics/objFilter.mjs
 
 
+
+
+
 const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
 
 /**
@@ -3107,48 +3153,6 @@ function getCheckObj() {
   return Object.fromEntries(Object.entries(typeValidator.items).map(([key, fn]) => [key, fn]));
 }
 
-/**
- * Counts the number of elements in an array or the number of properties in an object.
- *
- * @param {Array<*>|Record<string|number, any>} obj - The array or object to count.
- * @returns {number} - The count of items (array elements or object keys), or `0` if the input is neither an array nor an object.
- *
- * @example
- * countObj([1, 2, 3]); // 3
- * countObj({ a: 1, b: 2 }); // 2
- * countObj('not an object'); // 0
- */
-function countObj(obj) {
-  // Is Array
-  if (Array.isArray(obj)) return obj.length;
-  // Object
-  if (objType(obj, 'object')) return Object.keys(obj).length;
-  // Nothing
-  return 0;
-}
-
-/**
- * Determines whether a given value is a pure JSON object (plain object).
- *
- * A pure object satisfies the following:
- * - It is not null.
- * - Its type is "object".
- * - Its internal [[Class]] is "[object Object]".
- * - It is not an instance of built-in types like Array, Date, Map, Set, etc.
- *
- * This function is useful for strict data validation when you want to ensure
- * a value is a clean JSON-compatible object, free of class instances or special types.
- *
- * @param {unknown} value - The value to test.
- * @returns {value is Record<string | number | symbol, unknown>} Returns true if the value is a pure object.
- */
-function objFilter_isJsonObject(value) {
-  if (value === null || typeof value !== 'object') return false;
-  if (Array.isArray(value)) return false;
-  if (Object.prototype.toString.call(value) !== '[object Object]') return false;
-  return true;
-}
-
 // Insert obj types
 
 extendObjType([
@@ -3271,7 +3275,7 @@ extendObjType([
   [
     'object',
     /** @param {*} val @returns {val is Record<string | number | symbol, unknown>} */
-    (val) => objFilter_isJsonObject(val),
+    (val) => isJsonObject(val),
   ],
 ]);
 
@@ -3471,404 +3475,6 @@ class ColorSafeStringify {
 
 /* harmony default export */ const libs_ColorSafeStringify = ((/* unused pure expression or super */ null && (ColorSafeStringify)));
 
-;// ./src/v1/basics/html.mjs
-
-
-/////////////////////////////////////////////////////////////////
-
-/**
- * Reads the contents of a file using the specified FileReader method.
- *
- * @param {File} file - The file to be read.
- * @param {'readAsArrayBuffer'|'readAsDataURL'|'readAsText'|'readAsBinaryString'} method -
- *   The FileReader method to use for reading the file.
- * @returns {Promise<any>} - A promise that resolves with the file content, according to the chosen method.
- * @throws {Error} - If an unexpected error occurs while handling the result.
- * @throws {DOMException} - If the FileReader encounters an error while reading the file.
- */
-function readFileBlob(file, method) {
-  return new Promise((resolve, reject) => {
-    const reader = new FileReader();
-    reader.onload = () => {
-      try {
-        resolve(reader.result);
-      } catch (error) {
-        reject(error);
-      }
-    };
-    reader.onerror = () => {
-      reject(reader.error);
-    };
-    reader[method](file);
-  });
-}
-
-/**
- * Reads a file as a Base64 string using FileReader, and optionally formats it as a full data URL.
- *
- * Performs strict validation to ensure the result is a valid Base64 string or a proper data URL.
- *
- * @param {File} file - The file to be read.
- * @param {boolean|string} [isDataUrl=false] - If true, returns a full data URL; if false, returns only the Base64 string;
- *   if a string is passed, it is used as the MIME type in the data URL.
- * @returns {Promise<string>} - A promise that resolves with the Base64 string or data URL.
- *
- * @throws {TypeError} - If the result is not a string or if `isDataUrl` is not a valid type.
- * @throws {Error} - If the result does not match the expected data URL format or Base64 structure.
- * @throws {DOMException} - If the FileReader fails to read the file.
- */
-function readBase64Blob(file, isDataUrl = false) {
-  return new Promise((resolve, reject) => {
-    if (typeof isDataUrl !== 'string' && typeof isDataUrl !== 'boolean')
-      reject(new TypeError('The isDataUrl parameter must be a boolean or a string.'));
-    readFileBlob(file, 'readAsDataURL')
-      .then(
-        /**
-         * Ensure that the URL format is correct in the required pattern
-         * @param {string} base64Data
-         */ (base64Data) => {
-          if (typeof base64Data !== 'string')
-            throw new TypeError('Expected file content to be a string.');
-
-          const match = base64Data.match(/^data:(.+);base64,(.*)$/);
-          if (!match || !match[2])
-            throw new Error('Invalid data URL format or missing Base64 content.');
-          const [, mimeType, base64] = match;
-          if (!/^[\w/+]+=*$/.test(base64)) throw new Error('Base64 content is malformed.');
-
-          if (typeof isDataUrl === 'boolean') return resolve(isDataUrl ? base64Data : base64);
-          if (!/^[\w-]+\/[\w.+-]+$/.test(isDataUrl))
-            throw new Error(`Invalid MIME type string: ${isDataUrl}`);
-
-          return resolve(`data:${isDataUrl};base64,${base64}`);
-        },
-      )
-      .catch(reject);
-  });
-}
-
-/**
- * Reads a file and strictly validates its content as proper JSON using FileReader.
- *
- * Performs several checks to ensure the file contains valid, parsable JSON data.
- *
- * @param {File} file - The file to be read. It must contain valid JSON as plain text.
- * @returns {Promise<Record<string|number|symbol, any>|any[]>} - A promise that resolves with the parsed JSON object.
- *
- * @throws {SyntaxError} - If the file content is not valid JSON syntax.
- * @throws {TypeError} - If the result is not a string or does not represent a JSON value.
- * @throws {Error} - If the result is empty or structurally invalid as JSON.
- * @throws {DOMException} - If the FileReader fails to read the file.
- */
-function readJsonBlob(file) {
-  return new Promise((resolve, reject) =>
-    readFileBlob(file, 'readAsText')
-      .then((data) => {
-        if (typeof data !== 'string') throw new TypeError('Expected file content to be a string.');
-        const trimmed = data.trim();
-        if (trimmed.length === 0) throw new Error('File is empty or contains only whitespace.');
-        const parsed = JSON.parse(trimmed);
-        if (typeof parsed !== 'object' || parsed === null)
-          throw new Error('Parsed content is not a valid JSON object or array.');
-        resolve(parsed);
-      })
-      .catch(reject),
-  );
-}
-
-/**
- * Saves a JSON object as a downloadable file.
- * @param {string} filename
- * @param {any} data
- * @param {number} [spaces=2]
- */
-function saveJsonFile(filename, data, spaces = 2) {
-  const json = JSON.stringify(data, null, spaces);
-  const blob = new Blob([json], { type: 'application/json' });
-  const url = URL.createObjectURL(blob);
-
-  const link = document.createElement('a');
-  link.href = url;
-  link.download = filename;
-
-  document.body.appendChild(link);
-  link.click();
-  document.body.removeChild(link);
-
-  URL.revokeObjectURL(url);
-}
-
-/**
- * @typedef {Object} FetchTemplateOptions
- * @property {string} [method="GET"] - HTTP method to use (GET, POST, etc.).
- * @property {any} [body] - Request body (only for methods like POST, PUT).
- * @property {number} [timeout=0] - Timeout in milliseconds (ignored if signal is provided).
- * @property {number} [retries=0] - Number of retry attempts (ignored if signal is provided).
- * @property {Headers|Record<string, *>} [headers={}] - Additional headers.
- * @property {AbortSignal|null} [signal] - External AbortSignal; disables timeout and retries.
- */
-
-/**
- * @param {string} url - The full URL to fetch data from.
- * @param {FetchTemplateOptions} [options] - Optional settings.
- * @returns {Promise<Response>} Result data.
- * @throws {Error} Throws if fetch fails, times out.
- */
-async function fetchTemplate(
-  url,
-  { method = 'GET', body, timeout = 0, retries = 0, headers = {}, signal = null } = {},
-) {
-  if (
-    typeof url !== 'string' ||
-    (!url.startsWith('../') &&
-      !url.startsWith('./') &&
-      !url.startsWith('/') &&
-      !url.startsWith('https://') &&
-      !url.startsWith('http://'))
-  )
-    throw new Error('Invalid URL: must be a valid http or https address.');
-
-  if (typeof method !== 'string' || !method.trim())
-    throw new Error('Invalid method: must be a non-empty string.');
-
-  if (!signal) {
-    if (
-      typeof timeout !== 'number' ||
-      !Number.isFinite(timeout) ||
-      Number.isNaN(timeout) ||
-      timeout < 0
-    )
-      throw new Error('Invalid timeout: must be a positive number.');
-
-    if (
-      typeof retries !== 'number' ||
-      !Number.isFinite(retries) ||
-      Number.isNaN(retries) ||
-      retries < 0
-    )
-      throw new Error('Invalid retries: must be a positive number.');
-  }
-
-  const attempts = signal ? 1 : retries + 1;
-  /** @type {Error|null} */
-  let lastError = null;
-
-  for (let attempt = 0; attempt < attempts; attempt++) {
-    const controller = signal ? null : new AbortController();
-    const localSignal = signal || (controller?.signal ?? null);
-    const timer =
-      !signal && timeout && controller ? setTimeout(() => controller.abort(), timeout) : null;
-
-    try {
-      const response = await fetch(url, {
-        method: method.toUpperCase(),
-        headers: {
-          Accept: 'application/json',
-          ...headers,
-        },
-        body: body !== undefined ? (isJsonObject(body) ? JSON.stringify(body) : body) : undefined,
-        signal: localSignal,
-      });
-
-      if (timer) clearTimeout(timer);
-
-      if (!response.ok) throw new Error(`HTTP error: ${response.status} ${response.statusText}`);
-      return response;
-    } catch (err) {
-      lastError = /** @type {Error} */ (err);
-      if (signal) break; // if an external signal came, it does not retry
-      if (attempt < retries)
-        await new Promise((resolve) => setTimeout(resolve, 300 * (attempt + 1)));
-    }
-  }
-
-  throw new Error(
-    `Failed to fetch JSON from "${url}"${lastError ? `: ${lastError.message}` : '.'}`,
-  );
-}
-
-/**
- * Loads and parses a JSON from a remote URL using Fetch API.
- *
- * @param {string} url - The full URL to fetch JSON from.
- * @param {Object} [options] - Optional settings.
- * @returns {Promise<any[] | Record<string | number | symbol, unknown>>} Parsed JSON object.
- * @throws {Error} Throws if fetch fails, times out, or returns invalid JSON.
- */
-async function fetchJson(url, options) {
-  return new Promise((resolve, reject) => {
-    fetchTemplate(url, options)
-      .then(async (res) => {
-        const contentType = res.headers.get('content-type') || '';
-        if (!contentType.includes('application/json'))
-          throw new Error(`Unexpected content-type: ${contentType}`);
-
-        const data = await res.json();
-
-        if (!Array.isArray(data) && !isJsonObject(data))
-          throw new Error('Received invalid data instead of valid JSON.');
-
-        return resolve(data);
-      })
-      .catch(reject);
-  });
-}
-
-/**
- * Loads a remote file as a Blob using Fetch API.
- *
- * @param {string} url - The full URL to fetch the file from.
- * @param {Object} [options] - Optional fetch options.
- * @param {string[]} [allowedMimeTypes] - Optional list of accepted MIME types (e.g., ['image/jpeg']).
- * @returns {Promise<Blob>} - The fetched file as a Blob.
- * @throws {Error} Throws if fetch fails, response is not ok, or MIME type is not allowed.
- */
-async function fetchBlob(url, allowedMimeTypes, options) {
-  return new Promise((resolve, reject) => {
-    fetchTemplate(url, options)
-      .then(async (res) => {
-        const contentType = res.headers.get('content-type') || '';
-
-        if (
-          Array.isArray(allowedMimeTypes) &&
-          allowedMimeTypes.length > 0 &&
-          !allowedMimeTypes.some((type) => contentType.includes(type))
-        ) {
-          throw new Error(`Blocked MIME type: ${contentType}`);
-        }
-
-        const data = await res.blob();
-        return resolve(data);
-      })
-      .catch(reject);
-  });
-}
-
-///////////////////////////////////////////////////////////////////////////////
-
-/**
- * Installs a script that toggles CSS classes on a given element
- * based on the page's visibility or focus state, and optionally
- * triggers callbacks on visibility changes.
- *
- * @param {Object} [settings={}]
- * @param {Element} [settings.element=document.body] - The element to receive visibility classes.
- * @param {string} [settings.hiddenClass='windowHidden'] - CSS class applied when the page is hidden.
- * @param {string} [settings.visibleClass='windowVisible'] - CSS class applied when the page is visible.
- * @param {() => void} [settings.onVisible] - Callback called when page becomes visible.
- * @param {() => void} [settings.onHidden] - Callback called when page becomes hidden.
- * @returns {() => void} Function that removes all installed event listeners.
- * @throws {TypeError} If any provided setting is invalid.
- */
-function installWindowHiddenScript({
-  element = document.body,
-  hiddenClass = 'windowHidden',
-  visibleClass = 'windowVisible',
-  onVisible,
-  onHidden,
-} = {}) {
-  if (!(element instanceof Element))
-    throw new TypeError(`"element" must be an instance of Element.`);
-  if (typeof hiddenClass !== 'string') throw new TypeError(`"hiddenClass" must be a string.`);
-  if (typeof visibleClass !== 'string') throw new TypeError(`"visibleClass" must be a string.`);
-  if (onVisible !== undefined && typeof onVisible !== 'function')
-    throw new TypeError(`"onVisible" must be a function if provided.`);
-  if (onHidden !== undefined && typeof onHidden !== 'function')
-    throw new TypeError(`"onHidden" must be a function if provided.`);
-
-  const removeClass = () => {
-    element.classList.remove(hiddenClass);
-    element.classList.remove(visibleClass);
-  };
-
-  /** @type {string|null} */
-  let hiddenProp = null;
-
-  const visibilityEvents = [
-    'visibilitychange',
-    'mozvisibilitychange',
-    'webkitvisibilitychange',
-    'msvisibilitychange',
-  ];
-
-  const visibilityProps = ['hidden', 'mozHidden', 'webkitHidden', 'msHidden'];
-
-  for (let i = 0; i < visibilityProps.length; i++) {
-    if (visibilityProps[i] in document) {
-      hiddenProp = visibilityProps[i];
-      break;
-    }
-  }
-
-  /** @type {(this: any, evt: Event) => void} */
-  const handler = function (evt) {
-    removeClass();
-
-    const type = evt?.type;
-    // @ts-ignore
-    const isHidden = hiddenProp && document[hiddenProp];
-
-    const visibleEvents = ['focus', 'focusin', 'pageshow'];
-    const hiddenEvents = ['blur', 'focusout', 'pagehide'];
-
-    if (visibleEvents.includes(type)) {
-      element.classList.add(visibleClass);
-      onVisible?.();
-    } else if (hiddenEvents.includes(type)) {
-      element.classList.add(hiddenClass);
-      onHidden?.();
-    } else {
-      if (isHidden) {
-        element.classList.add(hiddenClass);
-        onHidden?.();
-      } else {
-        element.classList.add(visibleClass);
-        onVisible?.();
-      }
-    }
-  };
-
-  /** @type {() => void} */
-  let uninstall = () => {};
-
-  if (hiddenProp) {
-    const eventType = visibilityEvents[visibilityProps.indexOf(hiddenProp)];
-    document.addEventListener(eventType, handler);
-    window.addEventListener('focus', handler);
-    window.addEventListener('blur', handler);
-
-    uninstall = () => {
-      document.removeEventListener(eventType, handler);
-      window.removeEventListener('focus', handler);
-      window.removeEventListener('blur', handler);
-      removeClass();
-    };
-  } else if ('onfocusin' in document) {
-    // Fallback for IE9 and older
-    // @ts-ignore
-    document.onfocusin = document.onfocusout = handler;
-    uninstall = () => {
-      // @ts-ignore
-      document.onfocusin = document.onfocusout = null;
-      removeClass();
-    };
-  } else {
-    // Last resort fallback
-    window.onpageshow = window.onpagehide = window.onfocus = window.onblur = handler;
-    uninstall = () => {
-      window.onpageshow = window.onpagehide = window.onfocus = window.onblur = null;
-      removeClass();
-    };
-  }
-
-  // Trigger initial state
-  // @ts-ignore
-  const simulatedEvent = new Event(hiddenProp && document[hiddenProp] ? 'blur' : 'focus');
-  handler(simulatedEvent);
-
-  return uninstall;
-}
-
 ;// ./src/v1/basics/collision.mjs
 /**
  * A direction relative to a rectangle.
@@ -4358,6 +3964,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:
@@ -4377,12 +3998,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`.
@@ -4394,7 +4009,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.
  */
 
@@ -4953,9 +4568,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) {
@@ -4972,9 +4587,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) {
@@ -4988,6 +4603,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.
@@ -8247,12 +7888,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[]}
    */
@@ -8274,7 +8023,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[]}
    */
@@ -8287,17 +8036,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(
@@ -8314,7 +8063,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[]}
    */
@@ -8327,7 +8076,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[]}
    */
@@ -8349,7 +8098,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[]}
    */
@@ -8392,7 +8141,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[]}
    */
@@ -8419,7 +8168,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[]}
    */
@@ -10080,7 +9829,7 @@ class TinyDragger {
     if (
       options.vibration !== undefined &&
       options.vibration !== false &&
-      !objFilter_isJsonObject(options.vibration)
+      !isJsonObject(options.vibration)
     )
       throw new Error('The "vibration" option must be an object or false.');
 
@@ -10124,7 +9873,7 @@ class TinyDragger {
     const vibrationTemplate = { start: false, end: false, collide: false, move: false };
     this.#vibration = Object.assign(
       vibrationTemplate,
-      objFilter_isJsonObject(options.vibration) ? options.vibration : {},
+      isJsonObject(options.vibration) ? options.vibration : {},
     );
 
     if (typeof options.classDragging === 'string') this.#classDragging = options.classDragging;
@@ -11969,6 +11718,9 @@ class TinySmartScroller {
 
 
 
+
+
+
 
 
 
@@ -12048,7 +11800,7 @@ class TinyUploadClicker {
    * @throws {TypeError} If the config is invalid or required options are missing.
    */
   constructor(options) {
-    if (!objFilter_isJsonObject(options))
+    if (!isJsonObject(options))
       throw new TypeError('TinyUploadClicker: "options" must be a valid object.');
 
     this.#config = {
@@ -12114,10 +11866,10 @@ class TinyUploadClicker {
     )
       throw new TypeError('TinyUploadClicker: "onFileLoad" must be a function or null.');
 
-    if (options.inputAttributes !== undefined && !objFilter_isJsonObject(options.inputAttributes))
+    if (options.inputAttributes !== undefined && !isJsonObject(options.inputAttributes))
       throw new TypeError('TinyUploadClicker: "inputAttributes" must be an object.');
 
-    if (options.inputStyles !== undefined && !objFilter_isJsonObject(options.inputStyles))
+    if (options.inputStyles !== undefined && !isJsonObject(options.inputStyles))
       throw new TypeError('TinyUploadClicker: "inputStyles" must be an object.');
 
     this.#boundClick = this.#handleClick.bind(this);