v0.9.2 — 🐛 types, ⚡ on.defer and other small ⚡ (#36)

* 🔤 ⚡ T now uses DocumentFragment * 🔤 * 🔤 ⚡ * 🐛 lint * ⚡ cleanup * ⚡ 🔤 lib download * ⚡ 🔤 ui * ⚡ reorganize files * ⚡ on.host * 🐛 on.* types * ⚡ 🔤 cdn * 🔤 converter * 🐛 signal.set(value, force) * ⚡ 🔤 * 🔤 ⚡ converter - convert also comments * ⚡ bs/build * 🔤 ui p14 * 🔤 * 🔤 Examples * 🔤 * 🐛 now only el(..., string|number) * 🐛 fixes #38 * 🔤 * ⚡ on.host → on.defer * 🔤 * 📺
2025-07-04 21:42:14 +02:00 · 2025-03-16 11:30:42 +01:00
parent 25d475ec04
commit f0dfdfde54
83 changed files with 4624 additions and 2919 deletions
--- a/src/dom-lib/common.js
+++ b/src/dom-lib/common.js
@ -0,0 +1,63 @@
+/**
+ * Environment configuration and globals for the library
+ * @typedef {Object} Environment
+ * @property {typeof setDeleteAttr} setDeleteAttr - Function to safely set or delete attributes
+ * @property {string} ssr - Server-side rendering flag
+ * @property {Document} D - Document global
+ * @property {typeof DocumentFragment} F - DocumentFragment constructor
+ * @property {typeof HTMLElement} H - HTMLElement constructor
+ * @property {typeof SVGElement} S - SVGElement constructor
+ * @property {typeof MutationObserver} M - MutationObserver constructor
+ * @property {Function} q - Promise wrapper for Promse queue feature
+ */
+export const enviroment= {
+	setDeleteAttr,
+	ssr: "",
+	D: globalThis.document,
+	N: globalThis.Node,
+	F: globalThis.DocumentFragment,
+	H: globalThis.HTMLElement,
+	S: globalThis.SVGElement,
+	M: globalThis.MutationObserver,
+	q: p=> p || Promise.resolve(),
+};
+import { isInstance, isUndef } from '../helpers.js';
+
+/**
+ * Handles attribute setting with special undefined handling
+ *
+ * @param {Object} obj - The object to set the property on
+ * @param {string} prop - The property name
+ * @param {any} val - The value to set
+ * @returns {void}
+ *
+ * Issue:
+ *   For some native attrs you can unset only to set empty string.
+ *   This can be confusing as it is seen in inspector `<… id=""`.
+ *   Options:
+ *     1. Leave it, as it is native behaviour
+ *     2. Sets as empty string and removes the corresponding attribute when also has empty string
+ *     3. (*) Sets as undefined and removes the corresponding attribute when "undefined" string discovered
+ *     4. Point 2. with checks for coincidence (e.g. use special string)
+ */
+function setDeleteAttr(obj, prop, val){
+	Reflect.set(obj, prop, val);
+	if(!isUndef(val)) return;
+	Reflect.deleteProperty(obj, prop);
+	if(isInstance(obj, enviroment.H) && obj.getAttribute(prop)==="undefined")
+		return obj.removeAttribute(prop);
+	if(Reflect.get(obj, prop)==="undefined")
+		return Reflect.set(obj, prop, "");
+}
+
+/** Property key for tracking lifecycle events */
+export const keyLTE= "__dde_lifecyclesToEvents"; //boolean
+
+/** Event name for connected lifecycle event */
+export const evc= "dde:connected";
+
+/** Event name for disconnected lifecycle event */
+export const evd= "dde:disconnected";
+
+/** Event name for attribute changed lifecycle event */
+export const eva= "dde:attributeChanged";
--- a/src/dom-lib/customElement.js
+++ b/src/dom-lib/customElement.js
@ -0,0 +1,112 @@
+import { keyLTE, evc, evd, eva } from "./common.js";
+import { scope } from "./scopes.js";
+import { c_ch_o } from "./events-observer.js";
+import { elementAttribute } from "./helpers.js";
+
+/**
+ * Simulates slot functionality for elements
+ *
+ * @param {HTMLElement} element - Parent element
+ * @param {HTMLElement} [root=element] - Root element containing slots
+ * @returns {HTMLElement} The root element
+ */
+export function simulateSlots(element, root= element){
+	const mark_e= "¹⁰", mark_s= "✓"; //NOTE: Markers to identify slots processed by this function. Also “prevents” native behavior as it is unlikely to use these in names. // editorconfig-checker-disable-line
+	const slots= Object.fromEntries(
+		Array.from(root.querySelectorAll("slot"))
+			.filter(s => !s.name.endsWith(mark_e))
+			.map(s => [(s.name += mark_e), s]));
+	element.append= new Proxy(element.append, {
+		apply(orig, _, els){
+			if(els[0]===root) return orig.apply(element, els);
+			for(const el of els){
+				const name= (el.slot||"")+mark_e;
+				try{ elementAttribute(el, "remove", "slot"); } catch(_error){}
+				const slot= slots[name];
+				if(!slot) return;
+				if(!slot.name.startsWith(mark_s)){
+					slot.childNodes.forEach(c=> c.remove());
+					slot.name= mark_s+name;
+				}
+				slot.append(el);
+				//TODO?: el.dispatchEvent(new CustomEvent("dde:slotchange", { detail: slot }));
+			}
+			element.append= orig; //TODO?: better memory management, but non-native behavior!
+			return element;
+		}
+	});
+	if(element!==root){
+		const els= Array.from(element.childNodes);
+		//TODO?: els.forEach(el=> el.remove());
+		element.append(...els);
+	}
+	return root;
+}
+
+/**
+ * Renders content into a custom element or shadow root
+ *
+ * @param {Element|ShadowRoot} target - The custom element or shadow root to render into
+ * @param {Function} render - The render function that returns content
+ * @param {Function|Object} [props= {}] - Props to pass to the render function
+ * @returns {Node} The rendered content
+ */
+export function customElementRender(target, render, props= {}){
+	const custom_element= target.host || target;
+	scope.push({
+		scope: custom_element,
+		host: (...c)=> c.length ? c.forEach(c=> c(custom_element)) : custom_element
+	});
+	if(typeof props==="function") props= props.call(custom_element, custom_element);
+	const is_lte= custom_element[keyLTE];
+	if(!is_lte) lifecyclesToEvents(custom_element);
+	const out= render.call(custom_element, props);
+	if(!is_lte) custom_element.dispatchEvent(new Event(evc));
+	if(target.nodeType===11 && typeof target.mode==="string") // is ShadowRoot
+		custom_element.addEventListener(evd, c_ch_o.observe(target), { once: true });
+	scope.pop();
+	return target.append(out);
+}
+
+/**
+ * Transforms custom element lifecycle callbacks into events
+ *
+ * @param {Function|Object} class_declaration - Custom element class or instance
+ * @returns {Function|Object} The modified class or instance
+ */
+export function lifecyclesToEvents(class_declaration){
+	wrapMethod(class_declaration.prototype, "connectedCallback", function(target, thisArg, detail){
+		target.apply(thisArg, detail);
+		thisArg.dispatchEvent(new Event(evc));
+	});
+	wrapMethod(class_declaration.prototype, "disconnectedCallback", function(target, thisArg, detail){
+		target.apply(thisArg, detail);
+		(globalThis.queueMicrotask || setTimeout)(
+			()=> !thisArg.isConnected && thisArg.dispatchEvent(new Event(evd))
+		);
+	});
+	wrapMethod(class_declaration.prototype, "attributeChangedCallback", function(target, thisArg, detail){
+		const [ attribute, , value ]= detail;
+		thisArg.dispatchEvent(new CustomEvent(eva, {
+			detail: [ attribute, value ]
+		}));
+		target.apply(thisArg, detail);
+	});
+	class_declaration.prototype[keyLTE]= true;
+	return class_declaration;
+}
+
+/** Public API */
+export { lifecyclesToEvents as customElementWithDDE };
+
+/**
+ * Wraps a method with a proxy to intercept calls
+ *
+ * @param {Object} obj - Object containing the method
+ * @param {string} method - Method name to wrap
+ * @param {Function} apply - Function to execute when method is called
+ * @private
+ */
+function wrapMethod(obj, method, apply){
+	obj[method]= new Proxy(obj[method] || (()=> {}), { apply });
+}
--- a/src/dom-lib/el.js
+++ b/src/dom-lib/el.js
@ -0,0 +1,257 @@
+import { signals } from "../signals-lib/common.js";
+import { enviroment as env } from './common.js';
+import { isInstance, isUndef, oAssign } from "../helpers.js";
+
+/**
+ * Queues a promise, this is helpful for crossplatform components (on server side we can wait for all registered
+ * promises to be resolved before rendering).
+ * @param {Promise} promise - Promise to process
+ * @returns {Promise} Processed promise
+ */
+export function queue(promise){ return env.q(promise); }
+
+/**
+ * Chainable append function for elements
+ * @private
+ */
+function append(...els){ this.appendOriginal(...els); return this; }
+
+/**
+ * Makes an element's append method chainable. NOTE: following chainableAppend implementation is OK as the
+ * ElementPrototype.append description already is { writable: true, enumerable: true, configurable: true }
+ * @param {Element} el - Element to modify
+ * @returns {Element} Modified element
+ */
+export function chainableAppend(el){
+	if(el.append===append) return el; el.appendOriginal= el.append; el.append= append; return el;
+}
+/** Current namespace for element creation */
+let namespace;
+
+import { scope } from "./scopes.js";
+/**
+ * Creates a DOM element with specified tag, attributes and addons
+ *
+ * @param {string|Function} tag - Element tag name or component function
+ * @param {Object|string|number} [attributes] - Element attributes
+ * @param {...Function} addons - Functions to call with the created element
+ * @returns {Element|DocumentFragment} Created element
+ */
+export function createElement(tag, attributes, ...addons){
+	/* jshint maxcomplexity: 16 */
+	const s= signals(this);
+	let scoped= 0;
+	let el, el_host;
+	const att_type= typeof attributes;
+	if(att_type==="string" || att_type==="number" || s.isSignal(attributes))
+		attributes= { textContent: attributes };
+	switch(true){
+		case typeof tag==="function": {
+			scoped= 1;
+			const host= (...c)=> !c.length ? el_host :
+				(scoped===1 ? addons.unshift(...c) : c.forEach(c=> c(el_host)), undefined);
+			scope.push({ scope: tag, host });
+			el= tag(attributes || undefined);
+			const is_fragment= isInstance(el, env.F);
+			if(el.nodeName==="#comment") break;
+			const el_mark= createElement.mark({
+				type: "component",
+				name: tag.name,
+				host: is_fragment ? "this" : "parentElement",
+			});
+			el.prepend(el_mark);
+			if(is_fragment) el_host= el_mark;
+			break;
+		}
+		case tag==="#text":      el= assign.call(this, env.D.createTextNode(""), attributes); break;
+		case tag==="<>" || !tag: el= assign.call(this, env.D.createDocumentFragment(), attributes); break;
+		case Boolean(namespace): el= assign.call(this, env.D.createElementNS(namespace, tag), attributes); break;
+		case !el:                el= assign.call(this, env.D.createElement(tag), attributes);
+	}
+	chainableAppend(el);
+	if(!el_host) el_host= el;
+	addons.forEach(c=> c(el_host));
+	if(scoped) scope.pop();
+	scoped= 2;
+	return el;
+}
+
+/**
+ * Creates a marker comment for elements
+ *
+ * @param {{ type: "component"|"reactive"|"later", name?: string, host?: "this"|"parentElement" }} attrs - Marker
+ * attributes
+ * @param {boolean} [is_open=false] - Whether the marker is open-ended
+ * @returns {Comment} Comment node marker
+ */
+createElement.mark= function(attrs, is_open= false){
+	attrs= Object.entries(attrs).map(([ n, v ])=> n+`="${v}"`).join(" ");
+	const end= is_open ? "" : "/";
+	const out= env.D.createComment(`<dde:mark ${attrs}${env.ssr}${end}>`);
+	if(is_open) out.end= env.D.createComment("</dde:mark>");
+	return out;
+};
+/** Alias for createElement */
+export { createElement as el };
+
+//TODO?: const namespaceHelper= ns=> ns==="svg" ? "http://www.w3.org/2000/svg" : ns;
+/**
+ * Creates a namespaced element creation function
+ *
+ * @param {string} ns - Namespace URI
+ * @returns {Function} Element creation function for the namespace
+ */
+export function createElementNS(ns){
+	const _this= this;
+	return function createElementNSCurried(...rest){
+		namespace= ns;
+		const el= createElement.call(_this, ...rest);
+		namespace= undefined;
+		return el;
+	};
+}
+
+/** Alias for createElementNS */
+export { createElementNS as elNS };
+
+/** Store for element assignment contexts */
+const assign_context= new WeakMap();
+const { setDeleteAttr }= env;
+
+/**
+ * Assigns attributes to an element
+ *
+ * @param {Element} element - Element to assign attributes to
+ * @param {...Object} attributes - Attribute objects to assign
+ * @returns {Element} The element with attributes assigned
+ */
+export function assign(element, ...attributes){
+	if(!attributes.length) return element;
+	assign_context.set(element, assignContext(element, this));
+
+	for(const [ key, value ] of Object.entries(oAssign({}, ...attributes)))
+		assignAttribute.call(this, element, key, value);
+	assign_context.delete(element);
+	return element;
+}
+import { setDelete } from "./helpers.js";
+/**
+ * Assigns a single attribute to an element
+ *
+ * @param {Element} element - Element to assign attribute to
+ * @param {string} key - Attribute name
+ * @param {any} value - Attribute value
+ * @returns {any} Result of the attribute assignment
+ */
+export function assignAttribute(element, key, value){
+	const { setRemoveAttr, s }= assignContext(element, this);
+	const _this= this;
+
+	value= s.processReactiveAttribute(element, key, value,
+		(key, value)=> assignAttribute.call(_this, element, key, value));
+	const [ k ]= key;
+	if("="===k) return setRemoveAttr(key.slice(1), value);
+	if("."===k) return setDelete(element, key.slice(1), value);
+	if(/(aria|data)([A-Z])/.test(key)){//TODO: temporal as aria* exists in Element for some browsers
+		key= key.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+		return setRemoveAttr(key, value);
+	}
+	if("className"===key) key= "class";//NOTE: just optimalization, this makes `isPropSetter` returns false immediately // editorconfig-checker-disable-line
+	switch(key){
+		case "xlink:href":
+			return setRemoveAttr(key, value, "http://www.w3.org/1999/xlink");
+		case "textContent": //NOTE: just optimalization, this makes `isPropSetter` returns false immediately (as its part of Node ⇒ deep for `isPropSetter`) // editorconfig-checker-disable-line
+			return setDeleteAttr(element, key, value);
+		case "style":
+			if(typeof value!=="object") break;
+			/* falls through */
+		case "dataset":
+			return forEachEntries(s, key, element, value, setDelete.bind(null, element[key]));
+		case "ariaset":
+			return forEachEntries(s, key, element, value, (key, val)=> setRemoveAttr("aria-"+key, val));
+		case "classList":
+			return classListDeclarative.call(_this, element, value);
+	}
+	return isPropSetter(element, key) ? setDeleteAttr(element, key, value) : setRemoveAttr(key, value);
+}
+import { setRemove, setRemoveNS } from "./helpers.js";
+/**
+ * Gets or creates assignment context for an element
+ *
+ * @param {Element} element - Element to get context for
+ * @param {Object} _this - Context object
+ * @returns {Object} Assignment context
+ * @private
+ */
+function assignContext(element, _this){
+	if(assign_context.has(element)) return assign_context.get(element);
+	const is_svg= isInstance(element, env.S);
+	const setRemoveAttr= (is_svg ? setRemoveNS : setRemove).bind(null, element, "Attribute");
+	const s= signals(_this);
+	return { setRemoveAttr, s };
+}
+/**
+ * Applies a declarative classList object to an element
+ *
+ * @param {Element} element - Element to apply classes to
+ * @param {Object} toggle - Object with class names as keys and boolean values
+ * @returns {Element} The element with classes applied
+ */
+export function classListDeclarative(element, toggle){
+	const s= signals(this);
+	forEachEntries(s, "classList", element, toggle,
+		(class_name, val)=>
+			element.classList.toggle(class_name, val===-1 ? undefined : Boolean(val)) );
+	return element;
+}
+
+//TODO: add cache? `(Map/Set)<el.tagName+key,isUndef>`
+/**
+ * Checks if a property can be set on an element
+ *
+ * @param {Element} el - Element to check
+ * @param {string} key - Property name
+ * @returns {boolean} Whether the property can be set
+ * @private
+ */
+function isPropSetter(el, key){
+	if(!(key in el)) return false;
+	const des= getPropDescriptor(el, key);
+	return !isUndef(des.set);
+}
+
+/**
+ * Gets a property descriptor from a prototype chain
+ *
+ * @param {Object} p - Prototype object
+ * @param {string} key - Property name
+ * @returns {PropertyDescriptor} Property descriptor
+ * @private
+ */
+function getPropDescriptor(p, key){
+	p= Object.getPrototypeOf(p);
+	if(!p) return {};
+	const des= Object.getOwnPropertyDescriptor(p, key);
+	if(!des) return getPropDescriptor(p, key);
+	return des;
+}
+
+/**
+ * @template {Record<any, any>} T
+ * @param {object} s
+ * @param {string} target
+ * @param {Element} element
+ * @param {T} obj
+ * @param {(param: [ keyof T, T[keyof T] ])=> void} cb
+ * */
+function forEachEntries(s, target, element, obj, cb){
+	const S = String;
+	if(typeof obj !== "object" || obj===null) return;
+	return Object.entries(obj).forEach(function process([ key, val ]){
+		if(!key) return;
+		key = new S(key);
+		key.target = target;
+		val= s.processReactiveAttribute(element, key, val, cb);
+		cb(key, val);
+	});
+}
--- a/src/dom-lib/events-observer.js
+++ b/src/dom-lib/events-observer.js
@ -0,0 +1,236 @@
+import { enviroment as env, evc, evd } from './common.js';
+import { isInstance } from "../helpers.js";
+
+/**
+ * Connection changes observer for tracking element connection/disconnection
+ * Falls back to a dummy implementation if MutationObserver is not available
+ */
+export const c_ch_o= env.M ? connectionsChangesObserverConstructor() : new Proxy({}, {
+	get(){ return ()=> {}; }
+});
+
+/**
+ * Creates an observer that tracks elements being connected to and disconnected from the DOM
+ * @returns {Object} Observer with methods to register element listeners
+ */
+function connectionsChangesObserverConstructor(){
+	const store= new Map();
+	let is_observing= false;
+
+	/**
+	 * Creates a mutation observer callback
+	 * @param {Function} stop - Function to stop observation when no longer needed
+	 * @returns {Function} MutationObserver callback
+	 */
+	const observerListener= stop=> function(mutations){
+		for(const mutation of mutations){
+			if(mutation.type!=="childList") continue;
+			if(observerAdded(mutation.addedNodes, true)){
+				stop();
+				continue;
+			}
+			if(observerRemoved(mutation.removedNodes, true))
+				stop();
+		}
+	};
+
+	const observer= new env.M(observerListener(stop));
+
+	return {
+		/**
+		 * Creates an observer for a specific element
+		 * @param {Element} element - Element to observe
+		 * @returns {Function} Cleanup function
+		 */
+		observe(element){
+			const o= new env.M(observerListener(()=> {}));
+			o.observe(element, { childList: true, subtree: true });
+			return ()=> o.disconnect();
+		},
+
+		/**
+		 * Register a connection listener for an element
+		 * @param {Element} element - Element to watch
+		 * @param {Function} listener - Callback for connection event
+		 */
+		onConnected(element, listener){
+			start();
+			const listeners= getElementStore(element);
+			if(listeners.connected.has(listener)) return;
+			listeners.connected.add(listener);
+			listeners.length_c+= 1;
+		},
+
+		/**
+		 * Unregister a connection listener
+		 * @param {Element} element - Element being watched
+		 * @param {Function} listener - Callback to remove
+		 */
+		offConnected(element, listener){
+			if(!store.has(element)) return;
+			const ls= store.get(element);
+			if(!ls.connected.has(listener)) return;
+			ls.connected.delete(listener);
+			ls.length_c-= 1;
+			cleanWhenOff(element, ls);
+		},
+
+		/**
+		 * Register a disconnection listener for an element
+		 * @param {Element} element - Element to watch
+		 * @param {Function} listener - Callback for disconnection event
+		 */
+		onDisconnected(element, listener){
+			start();
+			const listeners= getElementStore(element);
+			if(listeners.disconnected.has(listener)) return;
+			listeners.disconnected.add(listener);
+			listeners.length_d+= 1;
+		},
+
+		/**
+		 * Unregister a disconnection listener
+		 * @param {Element} element - Element being watched
+		 * @param {Function} listener - Callback to remove
+		 */
+		offDisconnected(element, listener){
+			if(!store.has(element)) return;
+			const ls= store.get(element);
+			ls.disconnected.delete(listener);
+			ls.length_d-= 1;
+			cleanWhenOff(element, ls);
+		}
+	};
+
+	/**
+	 * Cleanup element tracking when all listeners are removed
+	 * @param {Element} element - Element to potentially remove from tracking
+	 * @param {Object} ls - Element's listener store
+	 */
+	function cleanWhenOff(element, ls){
+		if(ls.length_c || ls.length_d)
+			return;
+		store.delete(element);
+		stop();
+	}
+
+	/**
+	 * Gets or creates a store for element listeners
+	 * @param {Element} element - Element to get store for
+	 * @returns {Object} Listener store for the element
+	 */
+	function getElementStore(element){
+		if(store.has(element)) return store.get(element);
+		const out= {
+			connected: new WeakSet(),
+			length_c: 0,
+			disconnected: new WeakSet(),
+			length_d: 0
+		};
+		store.set(element, out);
+		return out;
+	}
+
+	/**
+	 * Start observing DOM changes
+	 */
+	function start(){
+		if(is_observing) return;
+		is_observing= true;
+		observer.observe(env.D.body, { childList: true, subtree: true });
+	}
+
+	/**
+	 * Stop observing DOM changes when no longer needed
+	 */
+	function stop(){
+		if(!is_observing || store.size) return;
+		is_observing= false;
+		observer.disconnect();
+	}
+
+	//TODO: remount support?
+	/**
+	 * Schedule a task during browser idle time
+	 * @returns {Promise<void>} Promise that resolves when browser is idle
+	 */
+	function requestIdle(){ return new Promise(function(resolve){
+		(requestIdleCallback || requestAnimationFrame)(resolve);
+	}); }
+
+	/**
+	 * Collects child elements from the store that are contained by the given element
+	 * @param {Element} element - Parent element
+	 * @returns {Promise<Element[]>} Promise resolving to array of child elements
+	 */
+	async function collectChildren(element){
+		if(store.size > 30)//TODO?: limit
+			await requestIdle();
+		const out= [];
+		if(!isInstance(element, env.N)) return out;
+		for(const el of store.keys()){
+			if(el===element || !isInstance(el, env.N)) continue;
+			if(element.contains(el))
+				out.push(el);
+		}
+		return out;
+	}
+
+	/**
+	 * Process nodes added to the DOM
+	 * @param {NodeList} addedNodes - Nodes that were added
+	 * @param {boolean} is_root - Whether these are root-level additions
+	 * @returns {boolean} Whether any relevant elements were processed
+	 */
+	function observerAdded(addedNodes, is_root){
+		let out= false;
+		for(const element of addedNodes){
+			if(is_root) collectChildren(element).then(observerAdded);
+			if(!store.has(element)) continue;
+
+			const ls= store.get(element);
+			if(!ls.length_c) continue;
+
+			element.dispatchEvent(new Event(evc));
+			ls.connected= new WeakSet();
+			ls.length_c= 0;
+			if(!ls.length_d) store.delete(element);
+			out= true;
+		}
+		return out;
+	}
+
+	/**
+	 * Process nodes removed from the DOM
+	 * @param {NodeList} removedNodes - Nodes that were removed
+	 * @param {boolean} is_root - Whether these are root-level removals
+	 * @returns {boolean} Whether any relevant elements were processed
+	 */
+	function observerRemoved(removedNodes, is_root){
+		let out= false;
+		for(const element of removedNodes){
+			if(is_root) collectChildren(element).then(observerRemoved);
+			if(!store.has(element)) continue;
+
+			const ls= store.get(element);
+			if(!ls.length_d) continue;
+			// support for S.el, see https://vuejs.org/guide/extras/web-components.html#lifecycle
+			(globalThis.queueMicrotask || setTimeout)(dispatchRemove(element));
+			out= true;
+		}
+		return out;
+	}
+
+	/**
+	 * Creates a function to dispatch the disconnect event
+	 * @param {Element} element - Element that was removed
+	 * @returns {Function} Function to dispatch event after confirming disconnection
+	 */
+	function dispatchRemove(element){
+		return ()=> {
+			if(element.isConnected) return;
+			element.dispatchEvent(new Event(evd));
+			store.delete(element);
+		};
+	}
+}
--- a/src/dom-lib/events.js
+++ b/src/dom-lib/events.js
@ -0,0 +1,90 @@
+import { keyLTE, evc, evd } from './common.js';
+import { oAssign, onAbort } from '../helpers.js';
+
+/**
+ * Creates a function to dispatch events on elements
+ *
+ * @param {string} name - Event name
+ * @param {Object} [options] - Event options
+ * @param {Element|Function} [host] - Host element or function returning host element
+ * @returns {Function} Function that dispatches the event
+ */
+export function dispatchEvent(name, options, host){
+	if(typeof options==="function"){ host= options; options= null; }
+	if(!options) options= {};
+	return function dispatch(element, ...d){
+		if(host){
+			d.unshift(element);
+			element= typeof host==="function"? host() : host;
+		}
+		//TODO: what about re-emmitting?
+		const event= d.length ? new CustomEvent(name, oAssign({ detail: d[0] }, options)) : new Event(name, options);
+		return element.dispatchEvent(event);
+	};
+}
+
+/**
+ * Creates a function to register event listeners on elements
+ *
+ * @param {string} event - Event name
+ * @param {Function} listener - Event handler
+ * @param {Object} [options] - Event listener options
+ * @returns {Function} Function that registers the listener
+ */
+export function on(event, listener, options){
+	return function registerElement(element){
+		element.addEventListener(event, listener, options);
+		return element;
+	};
+}
+
+on.defer= fn=> setTimeout.bind(null, fn, 0);
+
+import { c_ch_o } from "./events-observer.js";
+
+/**
+ * Prepares lifecycle event options with once:true default
+ * @private
+ */
+const lifeOptions= obj=> oAssign({}, typeof obj==="object" ? obj : null, { once: true });
+
+//TODO: cleanUp when event before abort?
+
+/**
+ * Creates a function to register connected lifecycle event listeners
+ *
+ * @param {Function} listener - Event handler
+ * @param {Object} [options] - Event listener options
+ * @returns {Function} Function that registers the connected listener
+ */
+on.connected= function(listener, options){
+	options= lifeOptions(options);
+	return function registerElement(element){
+		element.addEventListener(evc, listener, options);
+		if(element[keyLTE]) return element;
+		if(element.isConnected) return ( element.dispatchEvent(new Event(evc)), element );
+
+		const c= onAbort(options.signal, ()=> c_ch_o.offConnected(element, listener));
+		if(c) c_ch_o.onConnected(element, listener);
+		return element;
+	};
+};
+
+/**
+ * Creates a function to register disconnected lifecycle event listeners
+ *
+ * @param {Function} listener - Event handler
+ * @param {Object} [options] - Event listener options
+ * @returns {Function} Function that registers the disconnected listener
+ */
+on.disconnected= function(listener, options){
+	options= lifeOptions(options);
+	return function registerElement(element){
+		element.addEventListener(evd, listener, options);
+		if(element[keyLTE]) return element;
+
+		const c= onAbort(options.signal, ()=> c_ch_o.offDisconnected(element, listener));
+		if(c) c_ch_o.onDisconnected(element, listener);
+		return element;
+	};
+};
--- a/src/dom-lib/helpers.js
+++ b/src/dom-lib/helpers.js
@ -0,0 +1,57 @@
+import { enviroment as env } from './common.js';
+import { isInstance, isUndef } from "../helpers.js";
+/**
+ * Sets or removes an attribute based on value
+ *
+ * @param {Element} obj - Element to modify
+ * @param {string} prop - Property suffix ("Attribute")
+ * @param {string} key - Attribute name
+ * @param {any} val - Attribute value
+ * @returns {void}
+ * @private
+ */
+export function setRemove(obj, prop, key, val){
+	return obj[ (isUndef(val) ? "remove" : "set") + prop ](key, val);
+}
+
+/**
+ * Sets or removes a namespaced attribute based on value
+ *
+ * @param {Element} obj - Element to modify
+ * @param {string} prop - Property suffix ("Attribute")
+ * @param {string} key - Attribute name
+ * @param {any} val - Attribute value
+ * @param {string|null} [ns=null] - Namespace URI
+ * @returns {void}
+ * @private
+ */
+export function setRemoveNS(obj, prop, key, val, ns= null){
+	return obj[ (isUndef(val) ? "remove" : "set") + prop + "NS" ](ns, key, val);
+}
+
+/**
+ * Sets or deletes a property based on value
+ *
+ * @param {Object} obj - Object to modify
+ * @param {string} key - Property name
+ * @param {any} val - Property value
+ * @returns {void}
+ * @private
+ */
+export function setDelete(obj, key, val){
+	Reflect.set(obj, key, val); if(!isUndef(val)) return; return Reflect.deleteProperty(obj, key);
+}
+/**
+ * Generic element attribute manipulation
+ *
+ * @param {Element} element - Element to manipulate
+ * @param {string} op - Operation ("set" or "remove")
+ * @param {string} key - Attribute name
+ * @param {any} [value] - Attribute value
+ * @returns {void}
+ */
+export function elementAttribute(element, op, key, value){
+	if(isInstance(element, env.H))
+		return element[op+"Attribute"](key, value);
+	return element[op+"AttributeNS"](null, key, value);
+}
--- a/src/dom-lib/index.js
+++ b/src/dom-lib/index.js
@ -0,0 +1,4 @@
+export * from "./scopes.js";
+export * from "./el.js";
+export * from "./events.js";
+export * from "./customElement.js";
--- a/src/dom-lib/scopes.js
+++ b/src/dom-lib/scopes.js
@ -0,0 +1,82 @@
+import { enviroment as env } from './common.js';
+import { oAssign } from "../helpers.js";
+import { on } from "./events.js";
+
+/**
+ * Array of scope contexts for tracking component hierarchies
+ * @type {{ scope: object, prevent: boolean, host: function }[]}
+ */
+const scopes= [ {
+	get scope(){ return  env.D.body; },
+	host: c=> c ? c(env.D.body) : env.D.body,
+	prevent: true,
+} ];
+/** Store for disconnect abort controllers */
+const store_abort= new WeakMap();
+/**
+ * Scope management utility for tracking component hierarchies
+ */
+export const scope= {
+	/**
+	 * Gets the current scope
+	 * @returns {Object} Current scope context
+	 */
+	get current(){ return scopes[scopes.length-1]; },
+
+	/**
+	 * Gets the host element of the current scope
+	 * @returns {Function} Host accessor function
+	 */
+	get host(){ return this.current.host; },
+
+	/**
+	 * Creates/gets an AbortController that triggers when the element disconnects
+	 * */
+	get signal(){
+		const { host }= this;
+		if(store_abort.has(host)) return store_abort.get(host);
+
+		const a= new AbortController();
+		store_abort.set(host, a);
+		host(on.disconnected(()=> a.abort()));
+		return a.signal;
+	},
+
+	/**
+	 * Prevents default behavior in the current scope
+	 * @returns {Object} Current scope context
+	 */
+	preventDefault(){
+		const { current }= this;
+		current.prevent= true;
+		return current;
+	},
+
+	/**
+	 * Gets a copy of the current scope stack
+	 * @returns {Array} Copy of scope stack
+	 */
+	get state(){ return [ ...scopes ]; },
+
+	/**
+	 * Pushes a new scope to the stack
+	 * @param {Object} [s={}] - Scope object to push
+	 * @returns {number} New length of the scope stack
+	 */
+	push(s= {}){ return scopes.push(oAssign({}, this.current, { prevent: false }, s)); },
+
+	/**
+	 * Pushes the root scope to the stack
+	 * @returns {number} New length of the scope stack
+	 */
+	pushRoot(){ return scopes.push(scopes[0]); },
+
+	/**
+	 * Pops the current scope from the stack
+	 * @returns {Object|undefined} Popped scope or undefined if only one scope remains
+	 */
+	pop(){
+		if(scopes.length===1) return;
+		return scopes.pop();
+	},
+};