@medyll/idae-dom-events 0.5.1

package/README.md

@@ -0,0 +1,251 @@
+
+# dom-events Library
+
+dom-events is a powerful library for observing and reacting to DOM changes in web applications. It provides two main classes: cssDom and htmlDom.
+
+## Installation
+
+```bash
+npm install @medyll/idae-dom-events
+```
+
+## Usage
+
+```javascript
+import { cssDom, htmlDom } from "@medyll/idae-dom-events";
+```
+
+## CssObserver
+
+CssObserver allows you to track CSS changes and animations on specified elements to trigger custom actions or updates.
+
+### Key Features:
+- Track new elements matching a selector
+- Observe attribute changes
+- Monitor child list modifications
+- Track element resizing
+
+### Basic Usage:
+
+```javascript
+cssDom('#myElement').each((element) => {
+  console.log('Element changed:', element);
+});
+```
+
+### Advanced Usage:
+
+```javascript
+cssDom('#myElement', {
+  onlyNew: true,
+  trackChildList: true,
+  trackAttributes: ['class', 'style'],
+  trackResize: true
+}).each((element) => {
+  console.log('Element updated:', element);
+});
+```
+
+## HtmluDomLib (htmlDom)
+
+HtmluDomLib provides a more detailed way to observe DOM mutations.
+
+### Key Features:
+- Singleton instance for global use
+- Flexible mutation tracking
+- Support for multiple selectors and mutation types
+
+### Basic Usage:
+
+```javascript
+htmlDom.track('#myElement', ['class'], {
+  onAttributesChange: (element, mutation, observer) => {
+    console.log('Attribute changed:', mutation);
+  }
+});
+```
+
+### Advanced Usage:
+
+```javascript
+htmlDom.attach({
+  selectors: [{ element: '#myElement', mutations: { attributes: ['class'] } }],
+  selectorCallback: (mutations, observer) => ({
+    attributes: (mutation, observer) => {
+      console.log('Attribute mutation:', mutation);
+    },
+    childList: (mutation, observer) => {
+      console.log('Child list mutation:', mutation);
+    }
+  }),
+  observerParameters: {
+    subtree: true,
+    childList: true
+  }
+});
+```
+
+## Detailed Usage Guide
+
+### CssObserver (cssDom)
+
+The CssObserver class, accessed via the `cssDom` function, provides a powerful way to track CSS changes and animations on specified elements.
+
+#### Basic Usage:
+
+```javascript
+import { cssDom } from "@medyll/htmludom";
+
+cssDom('#myElement').each((element) => {
+  console.log('Element changed:', element);
+});
+```
+
+#### Advanced Features:
+
+1. **Track Only New Elements:**
+   ```javascript
+   cssDom('#myElement', { onlyNew: true }).each((element , changes) => {
+     console.log('New element added:', element);
+   });
+   ```
+
+2. **Observe Child List Changes:**
+   ```javascript
+   cssDom('#myElement', { trackChildList: true }).each((element , changes) => {
+     console.log('Child list changed for:', element);
+   });
+   ```
+
+3. **Monitor Specific Attributes:**
+   ```javascript
+   cssDom('#myElement', { trackAttributes: ['class', 'style'] }).each((element , changes) => {
+     console.log('Tracked attribute changed for:', element);
+   });
+   ```
+
+4. **Track Resize Events:**
+   ```javascript
+   cssDom('#myElement', { trackResize: true }).each((element , changes) => {
+     console.log('Element resized:', element);
+   });
+   ```
+
+5. **Get Summary of Changes:**
+   ```javascript
+   cssDom('#myElement').summary((changedElements) => {
+     console.log('Elements changed:', changedElements);
+   });
+   ```
+ 
+
+#### Basic Usage:
+
+```javascript
+import { htmlDom } from "@medyll/htmludom";
+
+htmlDom.track('#myElement', ['class'], {
+  onAttributesChange: (element, mutation, observer) => {
+    console.log('Class attribute changed:', element, mutation);
+  }
+});
+```
+
+#### Advanced Features:
+
+1. **Observe Multiple Mutation Types:**
+   ```javascript
+   htmlDom.track('#myElement', {
+     onAttributesChange: (element, mutation, observer) => {
+       console.log('Attribute changed:', mutation.attributeName);
+     },
+     onChildListChange: (element, mutation, observer) => {
+       console.log('Child nodes changed');
+     },
+     onCharacterDataChange: (element, mutation, observer) => {
+       console.log('Text content changed');
+     }
+   });
+   ```
+
+2. **Use Complex Selectors:**
+   ```javascript
+   htmlDom.track(['#myElement', '.myClass'], ['style', 'class'], {
+     onAttributesChange: (element, mutation, observer) => {
+       console.log('Style or class changed for:', element);
+     }
+   });
+   ```
+
+3. **Attach Multiple Observers:**
+   ```javascript
+   htmlDom.attach([
+     {
+       selectors: [{ element: '#element1', mutations: { attributes: ['class'] } }],
+       selectorCallback: (mutations, observer) => ({
+         attributes: (mutation, observer) => console.log('Class changed for element1')
+       }),
+       observerParameters: { subtree: true }
+     },
+     {
+       selectors: [{ element: '#element2', mutations: { childList: true } }],
+       selectorCallback: (mutations, observer) => ({
+         childList: (mutation, observer) => console.log('Children changed for element2')
+       }),
+       observerParameters: { childList: true }
+     }
+   ]);
+   ```
+
+4. **Detach Observers:**
+   ```javascript
+   // Detach all observers
+   htmlDom.detach();
+
+   // Detach observer for specific selector
+   htmlDom.detach('#myElement');
+   ```
+
+### The why and how of using cssEvents and domChange together in web applications. 
+
+Using cssEvents and domChange offers a balanced approach to tracking DOM changes and CSS-related events in web applications. This combination provides several advantages:
+
+1. Efficiency: cssEvents leverages CSS animations to detect new elements, which is more performant than constantly querying the DOM.
+
+2. Flexibility: domChange uses MutationObserver, allowing for precise tracking of various DOM mutations, including attribute changes and child node modifications.
+
+3. Comprehensive coverage: Together, these methods can capture a wide range of changes, from style updates to structural DOM alterations.
+
+4. Browser compatibility: This approach works well across modern browsers, providing a consistent experience.
+
+5. Reduced overhead: By focusing on specific changes, you can minimize unnecessary processing and improve overall application performance.
+
+6. Ease of use: The API for both methods is designed to be developer-friendly, making it simple to implement and maintain.
+
+7. Scalability: This solution is suitable for both small projects and large-scale applications, adapting well to different complexity levels.  
+By combining cssEvents for style-related changes and domChange for structural modifications, developers can create responsive, efficient, and robust web applications that react seamlessly to various types of DOM and CSS updates.  
+
+8. Resume  
+dom-events is a TypeScript library designed to simplify the use of the MutationObserver API, making manipulation of the Document Object Model (DOM) more intuitive and suitable for different use cases. This library is particularly useful for web applications that require dynamic DOM management, such as tracking attribute changes, observing changes in the child list of an element, and detecting character data changes.
+
+     The versatility of dom-events allows it to be used in a wide range of web applications, from simple to complex. It is ideal for situations where dynamic DOM monitoring is required, such as tracking attribute changes, observing changes in the child list of an element, or detecting character data changes.
+### Performance Considerations
+
+- Use specific selectors when possible to limit the scope of observation.
+- When tracking attributes, specify only the attributes you need to observe.
+- For frequently changing elements, consider using debounce techniques in your callback functions.
+- Detach observers when they are no longer needed to free up resources.
+
+### Browser Compatibility
+
+dom-events uses modern browser features such as MutationObserver and ResizeObserver. Ensure your target browsers support these APIs. For older browsers, consider using polyfills or fallback mechanisms.
+ 
+
+## Browser Compatibility
+
+dom-events uses modern browser features.  
+Ensure your target browsers support MutationObserver and other required APIs.
+
+## License
+
+[MIT License](LICENSE)

package/dist/components/content.html

@@ -0,0 +1,44 @@
+<script lang="ts">
+	const id = 'aaa';
+	const red = new ResizeObserver((entries) => {
+		for (let entry of entries) {
+			console.log('Element:', entry.target);
+			console.log('Width:', entry.contentRect.width);
+			console.log('Height:', entry.contentRect.height);
+			console.log('Box:', entry.contentRect);
+			console.log('Padding:', entry.contentRect.padding);
+		}
+	});
+	red.observe(element);
+
+	let data;
+	data.onchange = () => console.log(element);
+</script>
+<content id="{id}">
+	<bind from="company.name"></bind>
+	<nav>
+		<loop
+			data-url="api/users"
+			collection="users"
+			filter="where:user.name=*jean*"
+			sort="name"
+			groupBy="field"
+			toggle=""
+		>
+			<h2 slot="title">title once</h2>
+			<div mdl="component/li-item" collection="users" data="" data-id="">inner content</div>
+			<be-item component>inner content</be-item>
+		</loop>
+	</nav>
+	<if>
+		<elseif>
+			<div>cond 1</div>
+		</elseif>
+		<else> cond 2 </else>
+	</if>
+	<slot> </slot>
+</content>
+<style>
+	#id {
+	}
+</style>

package/dist/cssDom.d.ts

@@ -0,0 +1,190 @@
+export type CssObserverCommands = {
+    start: () => void;
+    pause: () => void;
+    destroy: () => void;
+};
+export type CssObserverCallBack = undefined | ((node: Node, mutation?: MutationRecord) => void);
+export type CssObserverCallBackSummary = (nodes: Node[]) => void;
+export type CssObserverOptions = {
+    strictlyNew: boolean;
+    eventDelay: number;
+    marquee: string;
+    legacyCssPrefix: 'Webkit' | 'Moz' | 'O' | 'ms' | '';
+    debounceDelay: number;
+};
+/**  QuerySelector */
+type QuerySelector = string;
+/**
+ * CssObserver class for tracking CSS changes and animations.
+ */
+export declare class CssObserver {
+    private selector;
+    private selectorId;
+    private activeAnimations;
+    private resizeObserver;
+    private loadedSelectors;
+    /**
+     * Default options for the CssObserver.
+     */
+    options: CssObserverOptions;
+    /**
+     * Creates a new instance of CssObserver.
+     * @param {QuerySelector} selector - The query selector for the instance.
+     */
+    constructor(selector?: QuerySelector);
+    setSelector(selector: QuerySelector): void;
+    /**
+     * Checks if the browser supports necessary features.
+     * @throws {Error} If the browser doesn't support required features.
+     */
+    private static checkBrowserSupport;
+    /**
+     * Removes special characters from a string.
+     * @param {string} str - The string to clean.
+     * @returns {string} The cleaned string.
+     */
+    private cleanSpecialChars;
+    /**
+     * Tracks animation events for the specified selector and invokes the callback function.
+     * @param {CssObserverCallBack} callback - The callback function to be invoked.
+     * @param {Object} opts - Optional settings.
+     * @param {boolean} [opts.onlyNew=false] - Whether to track only new elements.
+     * @param {boolean} [opts.trackChildList] - Whether to track child list changes.
+     * @param {boolean|string[]} [opts.trackAttributes] - Whether to track attribute changes or an array of specific attributes.
+     * @param {boolean} [opts.trackResize] - Whether to track resize events.
+     * @returns {Object} An object with methods to control the animation tracking.
+     */
+    track(callback: CssObserverCallBack, opts?: {
+        animationName?: string;
+        onlyNew?: boolean;
+        trackChildList?: boolean;
+        trackAttributes?: string[];
+        trackCharacterData?: boolean;
+        trackResize?: boolean;
+    }): CssObserverCommands;
+    /**
+     * Processes existing elements that match the selector.
+     * @param {CssObserverCallBack} callback - The callback function to be invoked for each element.
+     */
+    private processExistingElements;
+    /**
+     * Creates an event handler for animation events.
+     * @param {string} animationName - The name of the animation to track.
+     * @param {CssObserverCallBack} callback - The callback function to be invoked.
+     * @returns {Function} The event handler function.
+     */
+    private createEventHandler;
+    /**
+     * Calls the callback function for an element if it hasn't been processed before.
+     * @param {Element} element - The element to process.
+     * @param {CssObserverCallBack} callback - The callback function to be invoked.
+     * @param {MutationRecord} [mutation] - The mutation record associated with the change.
+     */
+    private callCallback;
+    /**
+     * Gets a summary of changes by grouping them under parent elements.
+     * @param {CssObserverCallBackSummary} callback - The callback function to be invoked with the summary.
+     * @param {Object} opts - Optional settings.
+     * @param {boolean} [opts.onlyNew=false] - Whether to track only new elements.
+     * @param {boolean} [opts.trackChildList] - Whether to track child list changes.
+     * @param {boolean|string[]} [opts.trackAttributes] - Whether to track attribute changes or an array of specific attributes.
+     * @param {boolean} [opts.trackResize] - Whether to track resize events.
+     * @returns {Object} An object with methods to control the summary tracking.
+     */
+    getSummary(callback: CssObserverCallBackSummary, opts?: {
+        onlyNew?: boolean;
+        trackChildList?: boolean;
+        trackAttributes?: boolean | string[];
+        trackResize?: boolean;
+    }): CssObserverCommands;
+    /**
+     * Sets options for the CssObserver instance.
+     * @param {CssObserverOptions} options - The options to be set.
+     */
+    static setOptions(options: CssObserverOptions): void;
+    /**
+     * Debounces a function to limit the number of times it gets called.
+     * @param {Function} func - The function to debounce.
+     * @param {number} delay - The delay in milliseconds.
+     * @returns {Function} A debounced version of the function.
+     */
+    private debounce;
+    /**
+     * Finds the nearest parent element with the tracking attribute.
+     * @param {Element} element - The starting element.
+     * @returns {Element | null} The nearest parent with the attribute, or null if not found.
+     */
+    private findParentWithAttribute;
+    /**
+     * Adds a tracking attribute to an element.
+     * @param {Element} element - The element to tag.
+     */
+    private doTag;
+    /**
+     * Checks if an element has the tracking attribute.
+     * @param {Element} element - The element to check.
+     * @returns {boolean} True if the element has the tracking attribute, false otherwise.
+     */
+    private hasTag;
+    /**
+     * Tags all elements in the given node and its descendants.
+     * @param {Node} element - The root node from which to start tagging.
+     */
+    tagAll(element: Node): void;
+    /**
+     * Adds an event listener for animation start events.
+     * @param {Function} eventHandler - The event handler function.
+     * @returns {number} The timeout ID.
+     */
+    private listenToAnimationEvent;
+    /**
+     * Removes an event listener for animation start events.
+     * @param {Function} eventHandler - The event handler function to remove.
+     */
+    private removeEvent;
+    /**
+     * Creates a style fragment with the specified selector and animation name.
+     * @param {string} selector - The CSS selector for the style fragment.
+     * @param {string} animationName - The name of the animation.
+     * @returns {CSSStyleSheet | HTMLStyleElement} The created style sheet or style element.
+     */
+    private createStyleFragment;
+    /**
+     * Adds a ResizeObserver to track size changes of elements matching the selector.
+     * @param {CssObserverCallBack} callback - The callback function to be invoked on resize.
+     */
+    private addResizeObserver;
+    /**
+     * Removes the ResizeObserver if it exists.
+     */
+    private removeResizeObserver;
+}
+/**
+ * Creates a selector object that allows querying the DOM using CSS selectors.
+ * @param {QuerySelector} selector - The CSS selector to query the DOM.
+ * @param {Object} [opts] - Optional options for the selector.
+ * @param {boolean} [opts.onlyNew] - Whether to observe only new elements.
+ * @param {boolean} [opts.trackChildList] - Whether to track child list changes.
+ * @param {boolean|string[]} [opts.trackAttributes] - Whether to track attribute changes or an array of specific attributes.
+ * @param {boolean} [opts.trackResize] - Whether to track resize events.
+ * @returns {Object} An object with methods to track changes.
+ */
+export declare function cssDom(selector: QuerySelector, opts?: {
+    onlyNew?: boolean;
+    trackChildList?: boolean;
+    trackAttributes?: boolean | string[];
+    trackResize?: boolean;
+}): {
+    each: (callback: CssObserverCallBack) => {
+        start: () => void;
+        pause: () => void;
+        destroy: () => void;
+    };
+    summary: (callback: CssObserverCallBackSummary) => {
+        start: () => void;
+        pause: () => void;
+        destroy: () => void;
+    };
+    onReady: (callback: () => void) => void;
+};
+export {};