tiny-essentials 1.17.1 → 1.18.1

package/docs/v1/libs/TinyClipboard.md

@@ -0,0 +1,213 @@
+# 📋 TinyClipboard Documentation
+
+A lightweight utility class for clipboard interactions with support for modern Clipboard API, custom overrides, and legacy fallback methods like `execCommand`.
+
+## 🚀 Features
+
+* ✅ Supports copying and reading **plain text**
+* ✅ Supports copying and reading **binary data (Blob)**
+* ✅ Automatically detects support for modern Clipboard API
+* ✅ Fallback for legacy `document.execCommand()`
+* ✅ Allows **custom clipboard handler overrides** for Electron, Capacitor, etc.
+
+---
+
+## 🏗️ Class: `TinyClipboard`
+
+### 🔧 Constructor
+
+```ts
+new TinyClipboard()
+```
+
+Initializes the clipboard utility and detects available clipboard APIs.
+
+---
+
+## ✍️ Copy Methods
+
+### 📄 `copyText(text: string): Promise<void>`
+
+Copies a plain text string to the clipboard.
+
+#### Parameters:
+
+* `text` – The string to copy.
+
+#### Throws:
+
+* `TypeError` if the input is not a string.
+* `Error` if no clipboard method is available.
+
+---
+
+### 🧩 `copyBlob(blob: Blob): Promise<void>`
+
+Copies binary data (e.g., images, files) to the clipboard.
+
+#### Parameters:
+
+* `blob` – The Blob object to copy.
+
+#### Throws:
+
+* `TypeError` if the input is not a Blob.
+* `Error` if clipboard API is unavailable.
+
+---
+
+## 🧠 Override Methods
+
+### 🛠️ `setCopyText(callback: (text: string) => Promise<void>)`
+
+Overrides the default text copy handler (e.g., for Electron or Capacitor).
+
+#### Throws:
+
+* `TypeError` if the callback is not a function.
+
+---
+
+### 🛠️ `setCopyBlob(callback: (blob: Blob) => Promise<void>)`
+
+Overrides the default Blob copy handler.
+
+#### Throws:
+
+* `TypeError` if the callback is not a function.
+
+---
+
+## 📥 Read Methods
+
+### 🧾 `readText(index?: number = 0): Promise<string|null>`
+
+Reads plain text from a specific clipboard index.
+
+#### Throws:
+
+* `Error` if the result is not a string.
+
+---
+
+### 🖼️ `readCustom(mimeFormat?: string, fixValue?: boolean, index?: number): Promise<Blob|null>`
+
+Reads a custom MIME-type item from the clipboard.
+
+#### Parameters:
+
+* `mimeFormat` – MIME type or prefix (e.g., `"image/"`)
+* `fixValue` – Whether to match the MIME type exactly
+* `index` – The clipboard item index
+
+#### Throws:
+
+* `Error` if the result is not a Blob.
+
+---
+
+### 📚 `readAllTexts(): Promise<string[]>`
+
+Reads all plain text entries from the clipboard.
+
+#### Throws:
+
+* `Error` if any entry is not a string.
+
+---
+
+### 🧳 `readAllCustom(mimeFormat?: string, fixValue?: boolean): Promise<Blob[]>`
+
+Reads all custom MIME-type items from the clipboard.
+
+#### Throws:
+
+* `Error` if any entry is not a Blob.
+
+---
+
+### 🔎 `readAllData(type?: 'text' | 'custom', mimeFormat?: string): Promise<Array<string | Blob>>`
+
+Reads all clipboard content filtered by type or MIME.
+
+#### Returns:
+
+* An array of strings or Blobs.
+
+---
+
+### 🔢 `readIndex(index: number): Promise<ClipboardItem|null>`
+
+Reads a single clipboard item by index.
+
+---
+
+### 🗃️ `readAll(): Promise<ClipboardItem[]>`
+
+Reads all clipboard items.
+
+#### Throws:
+
+* `Error` if the returned items are not all valid `ClipboardItem` instances.
+
+---
+
+## 🧪 Internal (Private) Helpers
+
+> These methods are not intended for external use.
+
+* `_handleBlob(type: string, item: ClipboardItem): Promise<Blob>`
+* `_handleText(type: string, item: ClipboardItem): Promise<string>`
+* `_read(index: number|null): Promise<ClipboardItem|ClipboardItem[]>`
+* `_readData(...)`: Internal filter mechanism used by public `read*` methods.
+
+---
+
+## ✅ Getters
+
+### 📎 `isExecCommandAvailable(): boolean`
+
+Returns `true` if legacy `document.execCommand()` is available.
+
+---
+
+### 📎 `isNavigatorClipboardAvailable(): boolean`
+
+Returns `true` if modern `navigator.clipboard` is available.
+
+---
+
+### 🧪 `getCopyTextFunc(): ((text: string) => Promise<void>) | null`
+
+Gets the current function used for copying text.
+
+---
+
+### 🧪 `getCopyBlobFunc(): ((blob: Blob) => Promise<void>) | null`
+
+Gets the current function used for copying blobs.
+
+---
+
+## 🧠 Usage Example
+
+```ts
+import TinyClipboard from './TinyClipboard.js';
+
+const clipboard = new TinyClipboard();
+
+// Copy text
+await clipboard.copyText("Hello world!");
+
+// Read text
+const value = await clipboard.readText();
+console.log(value);
+```
+
+---
+
+## 🔒 Notes
+
+* Browser permission is required to access the clipboard.
+* Clipboard access may be restricted to user interactions (e.g., click events).
+* This utility is designed for use in environments with **Clipboard API** support or suitable **fallbacks**.

package/docs/v1/libs/TinyHtml.md

@@ -90,8 +90,32 @@ ElementAndWinAndDoc | TinyHtml
 
 ---
 
+#### `TinyElementWithDoc`
+
+Accepts both raw DOM elements, the `document` object, or a `TinyHtml` wrapper.
+
+```ts
+ElementWithDoc | TinyHtml
+```
+
+Used to abstract interactions with either native elements or enhanced wrappers.
+
+---
+
 ### 🔀 Union Types
 
+#### `ElementWithDoc`
+
+A raw DOM `Element` or the `document` object.
+
+```ts
+Element | Document
+```
+
+Commonly used when the target might be either a single HTML element or the whole document, particularly in layout and measurement utilities.
+
+---
+
 #### `ElementAndWinAndDoc`
 
 Used for scrollable or measurable targets.
@@ -133,18 +157,6 @@ Window | Element | Document | Text
 
 ---
 
-### 🎯 Event System Types
-
-#### `EventRegistryHandle`
-
-A basic event listener handler function.
-
-```ts
-(e: Event) => any
-```
-
----
-
 #### `EventRegistryOptions`
 
 Options for `addEventListener` and `removeEventListener`.
@@ -161,7 +173,7 @@ Describes an individual event registration.
 
 ```ts
 {
-  handler: EventRegistryHandle,
+  handler: EventListenerOrEventListenerObject | null,
   options?: EventRegistryOptions
 }
 ```
@@ -446,8 +458,10 @@ Each method below ensures type and returns raw DOM objects:
 | `_preEventTargetElem(...)`    | `EventTarget`    | `EventTarget`  |
 | `_preElemsAndWindow(...)`     | `Element\|Window` | `ElementAndWindow[]` |
 | `_preElemAndWindow(...)`      | `Element\|Window` | `ElementAndWindow` |
-| `_preElemsAndWinAndDoc(...)`     | `Element\|Window\|Document` | `ElementAndWindow[]` |
-| `_preElemAndWinAndDoc(...)`      | `Element\|Window\|Document` | `ElementAndWindow` |
+| `_preElemsAndWinAndDoc(...)`  | `Element\|Window\|Document` | `ElementAndWindow[]` |
+| `_preElemAndWinAndDoc(...)`   | `Element\|Window\|Document` | `ElementAndWindow` |
+| `_preElemsWithDoc(...)`       | `Element\|Document` | `ElementWithDoc[]` |
+| `_preElemWithDoc(...)`        | `Element\|Document` | `ElementWithDoc` |
 
 ---
 
@@ -1236,6 +1250,89 @@ All event listeners are tracked in a private registry for full control.
 
 ---
 
+### 📋 `listenForPaste()`
+
+Handling Pasted Files and Text
+
+```js
+element.listenForPaste({
+  onFilePaste(item, file) {
+    console.log("Pasted file:", file.name);
+  },
+  onTextPaste(item, text) {
+    console.log("Pasted text:", text);
+  },
+});
+```
+
+Registers a listener for the `"paste"` event to extract files or plain text directly from the clipboard.
+
+* `onFilePaste(item, file)` – Triggered once for each file pasted (e.g., images or documents).
+* `onTextPaste(item, text)` – Triggered when plain text is pasted.
+
+Use this to build file dropzones, rich editors, or custom paste behavior.
+You can also use the static version for multiple elements:
+
+```js
+TinyHtml.listenForPaste([el1, el2], {
+  onFilePaste(item, file) {
+    console.log("Pasted a file into multiple elements!");
+  }
+});
+```
+
+Returns the internal paste handler function.
+
+---
+
+### 📡 `hasEventListener()`
+
+Checking for Event Presence
+
+```js
+if (element.hasEventListener("click")) {
+  console.log("Click handler already registered.");
+}
+```
+
+Checks whether any handler is currently registered on `__eventRegistry` for the given event name on an element.
+
+* Returns `true` if any listener exists for the event, otherwise `false`.
+
+Also available as a static version:
+
+```js
+TinyHtml.hasEventListener(el, "paste");
+```
+
+---
+
+### 🎯 `hasExactEventListener()`
+
+Checking for a Specific Handler
+
+```js
+function onClick() {}
+element.on("click", onClick);
+
+if (element.hasExactEventListener("click", onClick)) {
+  console.log("The exact click handler is registered.");
+}
+```
+
+Checks whether an element has **that exact function** registered on `__eventRegistry` for the given event.
+
+* Returns `true` only if the same reference to the function is found.
+* Helps prevent duplicate listeners or for conditional removal logic.
+
+Also available as a static version:
+
+```js
+TinyHtml.hasExactEventListener(el, "click", onClick);
+```
+
+---
+
 ### 📥 `on()` / `once()`
 
 Registering Events

package/docs/v1/libs/TinyTextRangeEditor.md

@@ -0,0 +1,208 @@
+# 📦 `TinyTextRangeEditor` Documentation
+
+A lightweight but powerful text range utility class for `<input>` and `<textarea>` elements, ideal for building BBCode or other tag-based markup editors.
+
+---
+
+## 🛠 Constructor
+
+```js
+new TinyTextRangeEditor(element, options?)
+```
+
+### Parameters:
+
+* `element` **(HTMLInputElement | HTMLTextAreaElement)** – Target editable element.
+* `options` **(Object)** *(optional)* – Customize tag delimiters.
+
+  * `openTag` **(string)** – Default: `'['`
+  * `closeTag` **(string)** – Default: `']'`
+
+---
+
+## 🔧 Core Methods
+
+### `getOpenTag()` → `string`
+
+Returns the current **opening tag symbol**.
+
+### `getCloseTag()` → `string`
+
+Returns the current **closing tag symbol**.
+
+### `setOpenTag(tag: string)`
+
+Changes the **opening tag symbol**.
+
+### `setCloseTag(tag: string)`
+
+Changes the **closing tag symbol**.
+
+---
+
+## 🎯 Selection & Focus
+
+### `focus()` → `this`
+
+Focuses the target element.
+
+### `ensureFocus()` → `this`
+
+Focuses the element only if not already focused.
+
+### `getSelectionRange()` → `{ start: number, end: number }`
+
+Returns the current **text selection range**.
+
+### `setSelectionRange(start, end, preserveScroll = true)` → `this`
+
+Sets the selection range.
+
+---
+
+## 📜 Value Access
+
+### `getValue()` → `string`
+
+Returns the entire value of the field.
+
+### `setValue(value: string)` → `this`
+
+Sets the entire content.
+
+### `getSelectedText()` → `string`
+
+Returns the currently selected text.
+
+---
+
+## ✍️ Text Manipulation
+
+### `insertText(text, options?)` → `this`
+
+Inserts (and replaces) text at selection.
+
+#### Options:
+
+* `newCursor`: `"start" | "end" | "preserve"` *(default: `'end'`)*
+* `autoSpacing`: *(boolean)* Add space if needed on both sides.
+* `autoSpaceLeft` / `autoSpaceRight`: *(boolean)* Fine-grained spacing control.
+
+---
+
+### `deleteSelection()` → `this`
+
+Deletes selected text.
+
+### `transformSelection(fn)` → `this`
+
+Applies a transformation function to the selected text.
+
+### `surroundSelection(prefix, suffix)` → `this`
+
+Wraps selected text with custom strings.
+
+---
+
+## 🪄 Tag Operations
+
+### `wrapWithTag(tagName, attributes?)` → `this`
+
+Wraps the selection in a custom tag.
+
+```js
+editor.wrapWithTag("b");
+editor.wrapWithTag("color", { value: "red" });
+```
+
+### `insertTag(tagName, content?, attributes?)` → `this`
+
+Inserts an opening and closing tag with optional content.
+
+```js
+editor.insertTag("quote", "Hello!", { user: "Yasmin" });
+```
+
+### `insertSelfClosingTag(tagName, attributes?)` → `this`
+
+Inserts a self-closing tag.
+
+```js
+editor.insertSelfClosingTag("br");
+editor.insertSelfClosingTag("img", { src: "link.jpg", alt: "image" });
+```
+
+### `toggleTag(tagName, attributes?)` → `this`
+
+Wraps or **unwraps** the selection with a tag.
+
+```js
+editor.toggleTag("b");
+```
+
+### `toggleCode(codeName)` → `this`
+
+Wraps or **unwraps** the selection with a code.
+
+```js
+editor.toggleTag("**");
+```
+
+---
+
+## 🧠 Utility
+
+### `moveCaret(offset: number)` → `this`
+
+Moves the caret by an offset.
+
+### `selectAll()` → `this`
+
+Selects all the content.
+
+### `expandSelection(before, after)` → `this`
+
+Expands the selection range by the given number of characters.
+
+### `replaceAll(regex, replacerFn)` → `this`
+
+Performs regex replacement over the full text.
+
+---
+
+### `replaceInSelection(regex, replacerFn)`
+
+Replaces all matches of a regular expression **only within the currently selected text** in the editor.
+
+---
+
+## 🧩 Internal Attribute Helper
+
+### `_insertAttr(attributes)` → `string`
+
+Serializes tag attributes to string format. Supports:
+
+* ✅ Object: `{ color: "red" } → color="red"`
+* ✅ Array: `["checked", "readonly"] → checked readonly`
+
+---
+
+## 🧪 Example Use
+
+```js
+const textarea = document.querySelector('textarea');
+const editor = new TinyTextRangeEditor(textarea);
+
+editor.wrapWithTag("b");
+editor.insertTag("color", "red text", { color: "red" });
+editor.insertSelfClosingTag("br");
+```
+
+---
+
+## 📝 Notes
+
+* All methods are **chainable** (`return this`)
+* Throws detailed **TypeErrors** if used incorrectly
+* Does **not** depend on any external library
+* Useful for BBCode editors, markdown-like syntax, or custom in-text macros

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.17.1",
+  "version": "1.18.1",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",

package/dist/v1/TinyDragger.min.js.LICENSE.txt

@@ -1,8 +0,0 @@
-/*!
- * The buffer module from node.js, for the browser.
- *
- * @author   Feross Aboukhadijeh <https://feross.org>
- * @license  MIT
- */
-
-/*! ieee754. BSD-3-Clause License. Feross Aboukhadijeh <https://feross.org/opensource> */