@mirawision/domino
Version:
Lightweight DOM utilities for Chrome Extension content scripts
119 lines (118 loc) • 5.57 kB
TypeScript
import { ElementTarget, ObserverOptions, Dispose, SelectorHandlers, ElementChangeInfo } from './types';
/**
* Watches for elements being added to the DOM that match the specified target.
*
* @param target - A selector string, Element, or predicate function to match elements against
* @param onAdd - Callback function called when a matching element is added
* @param options - Configuration options for the observer
* @param options.root - The root element to observe (defaults to document)
* @param options.subtree - Whether to observe the entire subtree (defaults to true)
* @param options.debounce - Optional debounce time in milliseconds
* @param options.throttle - Optional throttle time in milliseconds
* @param options.once - Whether to stop observing after the first match (defaults to false)
* @param options.signal - Optional AbortSignal to stop the observer
* @returns A function to dispose of the observer
*
* @example
* ```typescript
* const dispose = watchAdded('.my-class', (element) => {
* console.log('Element added:', element);
* }, {
* debounce: 100,
* once: true
* });
*
* // Later: stop observing
* dispose();
* ```
*/
export declare function watchAdded(target: ElementTarget, onAdd: (el: Element) => void, options?: ObserverOptions): Dispose;
/**
* Watches for elements being removed from the DOM that match the specified target.
*
* @param target - A selector string, Element, or predicate function to match elements against
* @param onRemove - Callback function called when a matching element is removed
* @param options - Configuration options for the observer
* @param options.root - The root element to observe (defaults to document)
* @param options.subtree - Whether to observe the entire subtree (defaults to true)
* @param options.debounce - Optional debounce time in milliseconds
* @param options.throttle - Optional throttle time in milliseconds
* @param options.once - Whether to stop observing after the first match (defaults to false)
* @param options.signal - Optional AbortSignal to stop the observer
* @returns A function to dispose of the observer
*
* @example
* ```typescript
* const dispose = watchRemoved('.my-class', (element) => {
* console.log('Element removed:', element);
* }, {
* throttle: 100
* });
* ```
*/
export declare function watchRemoved(target: ElementTarget, onRemove: (el: Element) => void, options?: ObserverOptions): Dispose;
/**
* Watches for modifications to elements that match the specified target.
* This includes attribute changes, text content changes, and child element changes.
*
* @param target - A selector string, Element, or predicate function to match elements against
* @param onChange - Callback function called when a matching element is modified
* @param options - Configuration options for the observer
* @param options.root - The root element to observe (defaults to document)
* @param options.subtree - Whether to observe the entire subtree (defaults to true)
* @param options.attributes - Whether to watch for attribute changes or an array of specific attributes to watch
* @param options.characterData - Whether to watch for text content changes (defaults to true)
* @param options.childList - Whether to watch for child element changes (defaults to true)
* @param options.debounce - Optional debounce time in milliseconds
* @param options.throttle - Optional throttle time in milliseconds
* @param options.once - Whether to stop observing after the first change (defaults to false)
* @param options.signal - Optional AbortSignal to stop the observer
* @returns A function to dispose of the observer
*
* @example
* ```typescript
* const dispose = watchModified('.my-class', (element, change) => {
* if (change.attrs) {
* console.log('Attributes changed:', Array.from(change.attrs));
* }
* if (change.text) {
* console.log('Text content changed');
* }
* if (change.childList) {
* console.log('Child elements changed');
* }
* }, {
* attributes: ['class', 'style'],
* characterData: true
* });
* ```
*/
export declare function watchModified(target: ElementTarget, onChange: (el: Element, change: ElementChangeInfo) => void, options?: ObserverOptions): Dispose;
/**
* A high-level function that combines watchAdded, watchRemoved, and watchModified into a single observer.
* This is useful when you need to track multiple types of changes to elements matching a selector.
*
* @param target - A selector string, Element, or predicate function to match elements against
* @param handlers - Object containing callback functions for different types of changes
* @param handlers.onEnter - Optional callback for when elements are added
* @param handlers.onExit - Optional callback for when elements are removed
* @param handlers.onChange - Optional callback for when elements are modified
* @param options - Configuration options passed to all observers
* @returns A function to dispose of all observers
*
* @example
* ```typescript
* const dispose = watchSelector('.my-class', {
* onEnter: (element) => console.log('Element added:', element),
* onExit: (element) => console.log('Element removed:', element),
* onChange: (element, change) => console.log('Element modified:', element, change)
* }, {
* debounce: 100,
* attributes: ['class', 'data-status']
* });
*
* // Later: stop all observers
* dispose();
* ```
*/
export declare function watchSelector(target: ElementTarget, handlers: SelectorHandlers, options?: ObserverOptions): Dispose;