@medyll/idae-be 1.28.0 → 1.30.0

package/README.md

@@ -1,377 +1,377 @@
-# @medyll/idae-be
-
-A DOM walk and manipulation library with a callback-based approach for precise element targeting.
-
-## Installation
-
-```bash
-npm install @medyll/idae-be
-```
-
-## Key Features
-
-- Root object persistence for consistent chaining
-- Callback-based element manipulation for precise targeting
-- Comprehensive DOM traversal and manipulation
-- Event handling, style management, and attribute control
-- Timer integration for dynamic operations
-- HTTP content loading and insertion
-
-## Unique Approach
-
-Unlike jQuery and other chained libraries, `@medyll/idae-be` always returns the root object. This approach allows for consistent chaining while using callbacks to manipulate targeted elements. This design provides more control and clarity in complex DOM operations.
-
----
-
-## Basic Usage
-
-### Example 1: DOM Manipulation with Callbacks
-
-```javascript
-import { be, toBe } from '@medyll/idae-be';
-
-// Select the container element
-be('#container')
-    .append(toBe('<div>New content</div>'), ({ be }) => {
-        be.addClass('highlight')
-            .on('click', () => console.log('Clicked!'))
-            .append(toBe('<span>Nested content</span>'), ({ be }) => {
-                be.addClass('nested').on('mouseover', () => console.log('Hovered!'));
-            });
-    })
-    .prepend(toBe('<h1>Title</h1>'), ({ be }) => {
-        be.addClass('title').children(({ be }) => {
-            be.setStyle({ color: 'blue' });
-        });
-    });
-```
-
----
-
-### Example 2: Event Handling and Traversal
-
-```javascript
-import { be } from '@medyll/idae-be';
-
-// Add a click event to all buttons inside the container
-be('#container button').on('click', ({ target }) => {
-    be(target)
-        .toggleClass('active')
-        .siblings(({ be }) => {
-            be.removeClass('active').on('mouseover', () => console.log('Sibling hovered!'));
-        });
-});
-
-// Fire a custom event and handle it
-be('#container').fire('customEvent', { detailKey: 'detailValue' }, ({ be }) => {
-    be.children(({ be }) => {
-        be.addClass('custom-event-handled');
-    });
-});
-```
-
----
-
-### Example 3: Styling and Attributes
-
-```javascript
-import { be } from '@medyll/idae-be';
-
-// Select an element and update its styles and attributes
-be('#element')
-    .setStyle({ backgroundColor: 'yellow', fontSize: '16px' }, ({ be }) => {
-        be.setAttr('data-role', 'admin').children(({ be }) => {
-            be.setStyle({ color: 'red' }).setAttr('data-child', 'true');
-        });
-    })
-    .addClass('styled-element', ({ be }) => {
-        be.siblings(({ be }) => {
-            be.setStyle({ opacity: '0.5' });
-        });
-    });
-```
-#### `unwrap(callback?: HandlerCallBackFn): Be`
-Removes the parent element of the selected element(s), keeping the selected element(s) in the DOM.
-
-**Example:**
-```javascript
-// HTML: <div id="wrapper"><span id="child">Content</span></div>
-be('#child').unwrap();
-// Result: <span id="child">Content</span>
----
-
-### Example 4: Timers
-
-```javascript
-import { be } from '@medyll/idae-be';
-
-// Set a timeout to execute a callback after 100ms
-be('#test').timeout(100, ({ be }) => {
-    be.setStyle({ backgroundColor: 'yellow' }).append('<span>Timeout executed</span>');
-});
-
-// Set an interval to execute a callback every 400ms
-const intervalInstance = be('#test').interval(400, ({ be }) => {
-    be.toggleClass('highlight');
-});
-
-// Clear the interval after 600ms
-setTimeout(() => {
-    intervalInstance.clearInterval();
-}, 600);
-```
-
----
-
-### Example 5: Walk
-
-```javascript
-import { be } from '@medyll/idae-be';
-
-// Traverse up the DOM tree to find the parent element
-be('#child').up('#parent', ({ be: parent }) => {
-    parent.addClass('highlight')
-        .children(({ be: child }) => {
-            child.setStyle({ color: 'blue' });
-        });
-});
-
-// Find all siblings of an element and add a class
-be('#target').siblings(({ be: siblings }) => {
-    siblings.addClass('sibling-class').children(({ be }) => {
-        be.setStyle({ fontWeight: 'bold' });
-    });
-});
-
-// Find the closest ancestor matching a selector
-be('#child').closest('.ancestor', ({ be: closest }) => {
-    closest.setStyle({ border: '2px solid red' }).children(({ be }) => {
-        be.addClass('ancestor-child');
-    });
-});
-```
-
----
-
-### Example 6: HTTP Content Loading and Insertion
-
-```javascript
-import { be } from '@medyll/idae-be';
-
-// Load content from a URL and update the element
-be('#test').updateHttp('/content.html', ({ be }) => {
-    console.log('Content loaded:', be.html);
-});
-
-// Load content and insert it at a specific position
-be('#test').insertHttp('/content.html', 'afterbegin', ({ be }) => {
-    console.log('Content inserted:', be.html);
-});
-```
-
----
-
-## API Reference
-
-### Core Methods
-
-#### `be(selector: string | HTMLElement | HTMLElement[]): Be`
-Create a new Be instance.
-
-**Example:**
-```javascript
-const instance = be('#test');
-```
-
-#### `toBe(str: string | HTMLElement, options?: { tag?: string }): Be`
-Convert a string or HTMLElement to a Be instance.
-
-**Example:**
-```javascript
-const newElement = toBe('<div>Content</div>');
-```
-
-#### `createBe(tagOrHtml: string, options?: Object): Be`
-Create a new Be element.
-
-**Example:**
-```javascript
-const newElement = createBe('div', { className: 'my-class' });
-```
-
----
-
-### HTTP Methods
-
-#### `updateHttp(url: string, callback?: HandlerCallBackFn): Be`
-Loads content from a URL and updates the element's content.
-
-**Example:**
-```javascript
-be('#test').updateHttp('/content.html', ({ be }) => {
-    console.log(be.html);
-});
-```
-
-#### `insertHttp(url: string, mode?: 'afterbegin' | 'afterend' | 'beforebegin' | 'beforeend', callback?: HandlerCallBackFn): Be`
-Loads content from a URL and inserts it into the element at a specified position.
-
-**Example:**
-```javascript
-be('#test').insertHttp('/content.html', 'afterbegin', ({ be }) => {
-    console.log(be.html);
-});
-```
-
----
-
-### Timers
-
-#### `timeout(delay: number, callback: HandlerCallBackFn): Be`
-Set a timeout for an element.
-
-**Example:**
-```javascript
-be('#test').timeout(1000, () => console.log('Timeout executed'));
-```
-
-#### `interval(delay: number, callback: HandlerCallBackFn): Be`
-Set an interval for an element.
-
-**Example:**
-```javascript
-be('#test').interval(500, () => console.log('Interval executed'));
-```
-
-#### `clearTimeout(): Be`
-Clear a timeout.
-
-**Example:**
-```javascript
-const timeoutInstance = be('#test').timeout(1000, () => console.log('Timeout executed'));
-timeoutInstance.clearTimeout();
-```
-
-#### `clearInterval(): Be`
-Clear an interval.
-
-**Example:**
-```javascript
-const intervalInstance = be('#test').interval(500, () => console.log('Interval executed'));
-intervalInstance.clearInterval();
-```
-
----
-
-### Traversal
-
-#### `up(selector?: string, callback?: HandlerCallBackFn): Be`
-Traverse up the DOM tree.
-
-**Example:**
-```javascript
-be('#child').up();
-```
-
-#### `next(selector?: string, callback?: HandlerCallBackFn): Be`
-Traverse to the next sibling.
-
-**Example:**
-```javascript
-be('#sibling1').next();
-```
-
-#### `previous(selector?: string, callback?: HandlerCallBackFn): Be`
-Traverse to the previous sibling.
-
-**Example:**
-```javascript
-be('#sibling2').previous();
-```
-
-#### `siblings(selector?: string, callback?: HandlerCallBackFn): Be`
-Find all sibling elements.
-
-**Example:**
-```javascript
-be('#child').siblings();
-```
-
-#### `children(selector?: string, callback?: HandlerCallBackFn): Be`
-Find all child elements.
-
-**Example:**
-```javascript
-be('#parent').children();
-```
-
-#### `closest(selector: string, callback?: HandlerCallBackFn): Be`
-Find the closest ancestor matching a selector.
-
-**Example:**
-```javascript
-be('#child').closest('#ancestor');
-```
-
----
-
-### Styling
-
-#### `setStyle(styles: Record<string, string>): Be`
-Set CSS styles for an element.
-
-**Example:**
-```javascript
-be('#test').setStyle({ color: 'red', fontSize: '16px' });
-```
-
-#### `getStyle(property: string): string | null`
-Get the value of a CSS property.
-
-**Example:**
-```javascript
-const color = be('#test').getStyle('color');
-console.log(color); // Output: "red"
-```
-
-#### `unsetStyle(property: string): Be`
-Remove a CSS property from an element.
-
-**Example:**
-```javascript
-be('#test').unsetStyle('color');
-```
-
----
-
-### Events
-
-#### `on(eventName: string, handler: EventListener): Be`
-Add an event listener to an element.
-
-**Example:**
-```javascript
-be('#test').on('click', () => console.log('Clicked!'));
-```
-
-#### `off(eventName: string, handler: EventListener): Be`
-Remove an event listener from an element.
-
-**Example:**
-```javascript
-be('#test').off('click', handler);
-```
-
-#### `fire(eventName: string, detail?: any): Be`
-Dispatch a custom event.
-
-**Example:**
-```javascript
-be('#test').fire('customEvent', { key: 'value' });
-```
-
----
-
-## License
-
-This project is licensed under the MIT License.
+# @medyll/idae-be
+
+A DOM walk and manipulation library with a callback-based approach for precise element targeting.
+
+## Installation
+
+```bash
+npm install @medyll/idae-be
+```
+
+## Key Features
+
+- Root object persistence for consistent chaining
+- Callback-based element manipulation for precise targeting
+- Comprehensive DOM traversal and manipulation
+- Event handling, style management, and attribute control
+- Timer integration for dynamic operations
+- HTTP content loading and insertion
+
+## Unique Approach
+
+Unlike jQuery and other chained libraries, `@medyll/idae-be` always returns the root object. This approach allows for consistent chaining while using callbacks to manipulate targeted elements. This design provides more control and clarity in complex DOM operations.
+
+---
+
+## Basic Usage
+
+### Example 1: DOM Manipulation with Callbacks
+
+```javascript
+import { be, toBe } from '@medyll/idae-be';
+
+// Select the container element
+be('#container')
+    .append(toBe('<div>New content</div>'), ({ be }) => {
+        be.addClass('highlight')
+            .on('click', () => console.log('Clicked!'))
+            .append(toBe('<span>Nested content</span>'), ({ be }) => {
+                be.addClass('nested').on('mouseover', () => console.log('Hovered!'));
+            });
+    })
+    .prepend(toBe('<h1>Title</h1>'), ({ be }) => {
+        be.addClass('title').children(({ be }) => {
+            be.setStyle({ color: 'blue' });
+        });
+    });
+```
+
+---
+
+### Example 2: Event Handling and Traversal
+
+```javascript
+import { be } from '@medyll/idae-be';
+
+// Add a click event to all buttons inside the container
+be('#container button').on('click', ({ target }) => {
+    be(target)
+        .toggleClass('active')
+        .siblings(({ be }) => {
+            be.removeClass('active').on('mouseover', () => console.log('Sibling hovered!'));
+        });
+});
+
+// Fire a custom event and handle it
+be('#container').fire('customEvent', { detailKey: 'detailValue' }, ({ be }) => {
+    be.children(({ be }) => {
+        be.addClass('custom-event-handled');
+    });
+});
+```
+
+---
+
+### Example 3: Styling and Attributes
+
+```javascript
+import { be } from '@medyll/idae-be';
+
+// Select an element and update its styles and attributes
+be('#element')
+    .setStyle({ backgroundColor: 'yellow', fontSize: '16px' }, ({ be }) => {
+        be.setAttr('data-role', 'admin').children(({ be }) => {
+            be.setStyle({ color: 'red' }).setAttr('data-child', 'true');
+        });
+    })
+    .addClass('styled-element', ({ be }) => {
+        be.siblings(({ be }) => {
+            be.setStyle({ opacity: '0.5' });
+        });
+    });
+```
+#### `unwrap(callback?: HandlerCallBackFn): Be`
+Removes the parent element of the selected element(s), keeping the selected element(s) in the DOM.
+
+**Example:**
+```javascript
+// HTML: <div id="wrapper"><span id="child">Content</span></div>
+be('#child').unwrap();
+// Result: <span id="child">Content</span>
+---
+
+### Example 4: Timers
+
+```javascript
+import { be } from '@medyll/idae-be';
+
+// Set a timeout to execute a callback after 100ms
+be('#test').timeout(100, ({ be }) => {
+    be.setStyle({ backgroundColor: 'yellow' }).append('<span>Timeout executed</span>');
+});
+
+// Set an interval to execute a callback every 400ms
+const intervalInstance = be('#test').interval(400, ({ be }) => {
+    be.toggleClass('highlight');
+});
+
+// Clear the interval after 600ms
+setTimeout(() => {
+    intervalInstance.clearInterval();
+}, 600);
+```
+
+---
+
+### Example 5: Walk
+
+```javascript
+import { be } from '@medyll/idae-be';
+
+// Traverse up the DOM tree to find the parent element
+be('#child').up('#parent', ({ be: parent }) => {
+    parent.addClass('highlight')
+        .children(({ be: child }) => {
+            child.setStyle({ color: 'blue' });
+        });
+});
+
+// Find all siblings of an element and add a class
+be('#target').siblings(({ be: siblings }) => {
+    siblings.addClass('sibling-class').children(({ be }) => {
+        be.setStyle({ fontWeight: 'bold' });
+    });
+});
+
+// Find the closest ancestor matching a selector
+be('#child').closest('.ancestor', ({ be: closest }) => {
+    closest.setStyle({ border: '2px solid red' }).children(({ be }) => {
+        be.addClass('ancestor-child');
+    });
+});
+```
+
+---
+
+### Example 6: HTTP Content Loading and Insertion
+
+```javascript
+import { be } from '@medyll/idae-be';
+
+// Load content from a URL and update the element
+be('#test').updateHttp('/content.html', ({ be }) => {
+    console.log('Content loaded:', be.html);
+});
+
+// Load content and insert it at a specific position
+be('#test').insertHttp('/content.html', 'afterbegin', ({ be }) => {
+    console.log('Content inserted:', be.html);
+});
+```
+
+---
+
+## API Reference
+
+### Core Methods
+
+#### `be(selector: string | HTMLElement | HTMLElement[]): Be`
+Create a new Be instance.
+
+**Example:**
+```javascript
+const instance = be('#test');
+```
+
+#### `toBe(str: string | HTMLElement, options?: { tag?: string }): Be`
+Convert a string or HTMLElement to a Be instance.
+
+**Example:**
+```javascript
+const newElement = toBe('<div>Content</div>');
+```
+
+#### `createBe(tagOrHtml: string, options?: Object): Be`
+Create a new Be element.
+
+**Example:**
+```javascript
+const newElement = createBe('div', { className: 'my-class' });
+```
+
+---
+
+### HTTP Methods
+
+#### `updateHttp(url: string, callback?: HandlerCallBackFn): Be`
+Loads content from a URL and updates the element's content.
+
+**Example:**
+```javascript
+be('#test').updateHttp('/content.html', ({ be }) => {
+    console.log(be.html);
+});
+```
+
+#### `insertHttp(url: string, mode?: 'afterbegin' | 'afterend' | 'beforebegin' | 'beforeend', callback?: HandlerCallBackFn): Be`
+Loads content from a URL and inserts it into the element at a specified position.
+
+**Example:**
+```javascript
+be('#test').insertHttp('/content.html', 'afterbegin', ({ be }) => {
+    console.log(be.html);
+});
+```
+
+---
+
+### Timers
+
+#### `timeout(delay: number, callback: HandlerCallBackFn): Be`
+Set a timeout for an element.
+
+**Example:**
+```javascript
+be('#test').timeout(1000, () => console.log('Timeout executed'));
+```
+
+#### `interval(delay: number, callback: HandlerCallBackFn): Be`
+Set an interval for an element.
+
+**Example:**
+```javascript
+be('#test').interval(500, () => console.log('Interval executed'));
+```
+
+#### `clearTimeout(): Be`
+Clear a timeout.
+
+**Example:**
+```javascript
+const timeoutInstance = be('#test').timeout(1000, () => console.log('Timeout executed'));
+timeoutInstance.clearTimeout();
+```
+
+#### `clearInterval(): Be`
+Clear an interval.
+
+**Example:**
+```javascript
+const intervalInstance = be('#test').interval(500, () => console.log('Interval executed'));
+intervalInstance.clearInterval();
+```
+
+---
+
+### Traversal
+
+#### `up(selector?: string, callback?: HandlerCallBackFn): Be`
+Traverse up the DOM tree.
+
+**Example:**
+```javascript
+be('#child').up();
+```
+
+#### `next(selector?: string, callback?: HandlerCallBackFn): Be`
+Traverse to the next sibling.
+
+**Example:**
+```javascript
+be('#sibling1').next();
+```
+
+#### `previous(selector?: string, callback?: HandlerCallBackFn): Be`
+Traverse to the previous sibling.
+
+**Example:**
+```javascript
+be('#sibling2').previous();
+```
+
+#### `siblings(selector?: string, callback?: HandlerCallBackFn): Be`
+Find all sibling elements.
+
+**Example:**
+```javascript
+be('#child').siblings();
+```
+
+#### `children(selector?: string, callback?: HandlerCallBackFn): Be`
+Find all child elements.
+
+**Example:**
+```javascript
+be('#parent').children();
+```
+
+#### `closest(selector: string, callback?: HandlerCallBackFn): Be`
+Find the closest ancestor matching a selector.
+
+**Example:**
+```javascript
+be('#child').closest('#ancestor');
+```
+
+---
+
+### Styling
+
+#### `setStyle(styles: Record<string, string>): Be`
+Set CSS styles for an element.
+
+**Example:**
+```javascript
+be('#test').setStyle({ color: 'red', fontSize: '16px' });
+```
+
+#### `getStyle(property: string): string | null`
+Get the value of a CSS property.
+
+**Example:**
+```javascript
+const color = be('#test').getStyle('color');
+console.log(color); // Output: "red"
+```
+
+#### `unsetStyle(property: string): Be`
+Remove a CSS property from an element.
+
+**Example:**
+```javascript
+be('#test').unsetStyle('color');
+```
+
+---
+
+### Events
+
+#### `on(eventName: string, handler: EventListener): Be`
+Add an event listener to an element.
+
+**Example:**
+```javascript
+be('#test').on('click', () => console.log('Clicked!'));
+```
+
+#### `off(eventName: string, handler: EventListener): Be`
+Remove an event listener from an element.
+
+**Example:**
+```javascript
+be('#test').off('click', handler);
+```
+
+#### `fire(eventName: string, detail?: any): Be`
+Dispatch a custom event.
+
+**Example:**
+```javascript
+be('#test').fire('customEvent', { key: 'value' });
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@medyll/idae-be",
 	"scope": "@medyll",
-	"version": "1.28.0",
+	"version": "1.30.0",
 	"description": "A modern, lightweight, and extensible DOM manipulation library built with TypeScript. Designed for precise element targeting and manipulation using a callback-based approach. Features include advanced DOM traversal, event handling, style management, attribute control, HTTP content loading, timers, and more. Ideal for developers seeking a modular and consistent API for dynamic web applications.",
 	"keywords": [
 		"DOM",