tiny-essentials 1.17.0 → 1.18.0

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` |
 
 ---
 
@@ -747,6 +761,102 @@ Normalizes and converts input (elements, arrays, or strings) into appendable DOM
 
 ---
 
+## 🧮 Easing Functions
+
+### `TinyHtml.easings`
+
+A collection of predefined easing functions used for scroll and animation calculations.
+Each easing function takes a normalized time (`t` from 0 to 1) and returns a transformed progress value.
+
+| Name             | Description                           |
+| ---------------- | ------------------------------------- |
+| `linear`         | Constant speed, no easing.            |
+| `easeInQuad`     | Accelerates from zero velocity.       |
+| `easeOutQuad`    | Decelerates to zero velocity.         |
+| `easeInOutQuad`  | Accelerates, then decelerates.        |
+| `easeInCubic`    | Starts slow, speeds up sharply.       |
+| `easeOutCubic`   | Starts fast, slows down gradually.    |
+| `easeInOutCubic` | Smooth acceleration and deceleration. |
+
+```ts
+type Easings =
+  | 'linear'
+  | 'easeInQuad'
+  | 'easeOutQuad'
+  | 'easeInOutQuad'
+  | 'easeInCubic'
+  | 'easeOutCubic'
+  | 'easeInOutCubic';
+```
+
+```ts
+TinyHtml.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),
+};
+```
+
+---
+
+## 🧭 Smooth Scrolling
+
+### `TinyHtml.scrollToXY(el, settings)`
+
+Smoothly scrolls one or more elements (or `window`) to a target position using a custom duration and easing.
+
+If no `duration` or invalid `easing` is provided, the scroll happens instantly.
+
+```ts
+TinyHtml.scrollToXY(el, {
+  targetX?: number,
+  targetY?: number,
+  duration?: number,
+  easing?: Easings,
+});
+```
+
+| Parameter            | Type                                             | Description                                                                                                                                        |
+| -------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `el`                 | `TinyElementAndWindow \| TinyElementAndWindow[]` | One or more elements or the `window` to scroll.                                                                                                    |
+| `settings`           | `Object`                                         | Scroll configuration.                                                                                                                              |
+| `targetX`            | `number` *(optional)*                            | Final horizontal scroll position.                                                                                                                  |
+| `targetY`            | `number` *(optional)*                            | Final vertical scroll position.                                                                                                                    |
+| `duration`           | `number` *(optional)*                            | Duration of the scroll animation in milliseconds.                                                                                                  |
+| `easing`             | `Easings` *(optional)*                           | Name of easing function to control animation curve.                                                                                                |
+| `onAnimation`        | `OnScrollAnimation` *(optional)*                 | Optional callback invoked on each animation frame with the current scroll position, normalized animation time (`0` to `1`), and a completion flag. |
+
+---
+
+## ⚙️ Internal Scroll Mechanism
+
+When called, `scrollToXY()` performs:
+
+1. **Start Position Detection** – Gets current scroll positions.
+2. **Delta Calculation** – Calculates the distance to scroll.
+3. **Easing Evaluation** – Determines the easing curve to use.
+4. **Scroll Loop** – Uses `requestAnimationFrame` to animate over time.
+5. **Instant Scroll Fallback** – If no easing/duration is defined, scrolls instantly.
+
+```ts
+function executeScroll(elem, newX, newY) {
+  if (elem instanceof Window) {
+    window.scrollTo(newX, newY);
+  } else if (elem.nodeType === 9) {
+    elem.defaultView.scrollTo(newX, newY); // For documents
+  } else {
+    if (elem.scrollLeft !== newX) elem.scrollLeft = newX;
+    if (elem.scrollTop !== newY) elem.scrollTop = newY;
+  }
+}
+```
+
+---
+
 ## 📏 Dimensions (Size API)
 
 TinyHtml provides methods to **read** and **set** an element's dimensions, similar to jQuery’s width/height API, with support for box models: `content`, `padding`, `border`, and `margin`.
@@ -823,6 +933,9 @@ This API set focuses on **measuring element offsets**, **scroll positions**, and
 
 ### 📍 Element Positioning
 
+#### `.animate(keyframes, ops?)` / `TinyHtml.animate(el, keyframes, ops?)`
+Applies an animation to one or more TinyElement instances using the Web Animations API.
+
 #### `.offset()` / `TinyHtml.offset(el)`
 Returns the coordinates `{ top, left }` of the element **relative to the document**.
 
@@ -1137,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.0",
+  "version": "1.18.0",
   "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",