@aegisjsproject/callback-registry 1.0.0

package/callbackRegistry.mjs

@@ -0,0 +1,509 @@
+let _isRegistrationOpen = true;
+
+const $$ = (selector, base = document) => base.querySelectorAll(selector);
+
+const $ = (selector, base = document) => base.querySelector(selector);
+
+const FUNCS = {
+	debug: {
+		log: 'aegis:debug:log',
+		info: 'aegis:debug:info',
+		warn: 'aegis:debug:warn',
+		error: 'aegis:debug:error',
+	},
+	navigate: {
+		back: 'aegis:navigate:back',
+		forward: 'aegis:navigate:forward',
+		reload: 'aegis:navigate:reload',
+		link: 'aegis:navigate:go',
+		popup: 'aegis:navigate:popup',
+	},
+	ui: {
+		print: 'aegis:ui:print',
+		remove: 'aegis:ui:remove',
+		hide: 'aegis:ui:hide',
+		unhide: 'aegis:ui:unhide',
+		showModal: 'aegis:ui:showModal',
+		closeModal: 'aegis:ui:closeModal',
+		showPopover: 'aegis:ui:showPopover',
+		hidePopover: 'aegis:ui:hidePopover',
+		togglePopover: 'aegis:ui:togglePopover',
+		enable: 'aegis:ui:enable',
+		disable: 'aegis:ui:disable',
+		scrollTo: 'aegis:ui:scrollTo',
+		prevent: 'aegis:ui:prevent',
+	},
+};
+
+const registry = new Map([
+	[FUNCS.debug.log, console.log],
+	[FUNCS.debug.warn, console.warn],
+	[FUNCS.debug.error, console.error],
+	[FUNCS.debug.info, console.info],
+	[FUNCS.navigate.back, history.back],
+	[FUNCS.navigate.forward, history.forward],
+	[FUNCS.navigate.reload, () => history.go(0)],
+	[FUNCS.navigate.link, event => {
+		if (event.isTrusted) {
+			event.preventDefault();
+			location.href = event.currentTarget.dataset.url;
+		}
+	}],
+	[FUNCS.navigate.popup, event => {
+		if (event.isTrusted) {
+			event.preventDefault();
+			globalThis.open(event.currentTarget.dataset.url);
+		}
+	}],
+	[FUNCS.ui.hide, ({ currentTarget }) => {
+		$$(currentTarget.dataset.hideSelector).forEach(el => el.hidden = true);
+	}],
+	[FUNCS.ui.unhide, ({ currentTarget }) => {
+		$$(currentTarget.dataset.unhideSelector).forEach(el => el.hidden = false);
+	}],
+	[FUNCS.ui.disable, ({ currentTarget }) => {
+		$$(currentTarget.dataset.disableSelector).forEach(el => el.disabled = true);
+	}],
+	[FUNCS.ui.enable, ({ currentTarget }) => {
+		$$(currentTarget.dataset.enableSelector).forEach(el => el.disabled = false);
+	}],
+	[FUNCS.ui.remove, ({ currentTarget }) => {
+		$$(currentTarget.dataset.removeSelector).forEach(el => el.remove());
+	}],
+	[FUNCS.ui.scrollTo, ({ currentTarget }) => {
+		const target = $(currentTarget.dataset.scrollToSelector);
+
+		if (target instanceof Element) {
+			target.scrollIntoView({
+				behavior: matchMedia('(prefers-reduced-motion: reduce)').matches
+					? 'instant'
+					: 'smooth',
+			});
+		}
+	}],
+	[FUNCS.ui.showModal, ({ currentTarget }) => {
+		const target = $(currentTarget.dataset.showModalSelector);
+
+		if (target instanceof HTMLDialogElement) {
+			target.showModal();
+		}
+	}],
+	[FUNCS.ui.closeModal, ({ currentTarget }) => {
+		const target = $(currentTarget.dataset.closeModalSelector);
+
+		if (target instanceof HTMLDialogElement) {
+			target.close();
+		}
+	}],
+	[FUNCS.ui.showPopover, ({ currentTarget }) => {
+		const target = $(currentTarget.dataset.showPopoverSelector);
+
+		if (target instanceof HTMLElement) {
+			target.showPopover();
+		}
+	}],
+	[FUNCS.ui.hidePopover, ({ currentTarget }) => {
+		const target = $(currentTarget.dataset.hidePopoverSelector);
+
+		if (target instanceof HTMLElement) {
+			target.hidePopover();
+		}
+	}],
+	[FUNCS.ui.togglePopover, ({ currentTarget }) => {
+		const target = $(currentTarget.dataset.togglePopoverSelector);
+
+		if (target instanceof HTMLElement) {
+			target.togglePopover();
+		}
+	}],
+	[FUNCS.ui.print, () => globalThis.print()],
+	[FUNCS.ui.prevent, event => event.preventDefault()],
+]);
+
+/**
+ * Check if callback registry is open
+ *
+ * @returns {boolean} Whether or not callback registry is open
+ */
+const isRegistrationOpen = () => _isRegistrationOpen;
+
+/**
+ * Close callback registry
+ *
+ * @returns {boolean} Whether or not the callback was succesfully removed
+ */
+const closeRegistration = () => _isRegistrationOpen = false;
+
+/**
+ * Get an array of registered callbacks
+ *
+ * @returns {Array} A frozen array listing keys to all registered callbacks
+ */
+const listCallbacks = () => Object.freeze(Array.from(registry.keys()));
+
+/**
+ * Check if a callback is registered
+ *
+ * @param {string} name The name/key to check for in callback registry
+ * @returns {boolean} Whether or not a callback is registered
+ */
+const hasCallback = name => registry.has(name);
+
+/**
+ * Get a callback from the registry by name/key
+ *
+ * @param {string} name The name/key of the callback to get
+ * @returns {Function|undefined} The corresponding function registered under that name/key
+ */
+const getCallback = name => registry.get(name);
+
+/**
+ *	 Remove a callback from the registry
+ *
+ * @param {string} name The name/key of the callback to get
+ * @returns {boolean} Whether or not the callback was successfully unregisterd
+ */
+const unregisterCallback = name => _isRegistrationOpen && registry.delete(name);
+
+/**
+ * Remove all callbacks from the registry
+ *
+ * @returns {undefined}
+ */
+const clearRegistry = () => registry.clear();
+
+/**
+ * Create a registered callback with a randomly generated name
+ *
+ * @param {Function} callback Callback function to register
+ * @returns {string} The automatically generated key/name of the registered callback
+ */
+const createCallback = (callback) => registerCallback('aegis:callback:' + crypto.randomUUID(), callback);
+
+/**
+ * Call a callback fromt the registry by name/key
+ *
+ * @param {string} name The name/key of the registered function
+ * @param  {...any} args Any arguments to pass along to the function
+ * @returns {any} Whatever the return value of the function is
+ * @throws {Error} Throws if callback is not found or any error resulting from calling the function
+ */
+function callCallback(name, ...args) {
+	if (registry.has(name)) {
+		return registry.get(name).apply(this || globalThis, args);
+	} else {
+		throw new Error(`No ${name} function registered.`);
+	}
+}
+
+/**
+ * Register a named callback in registry
+ *
+ * @param {string} name The name/key to register the callback under
+ * @param {Function} callback The callback value to register
+ * @returns {string} The registered name/key
+ */
+function registerCallback(name, callback) {
+	if (typeof name !==  'string' || name.length === 0) {
+		throw new TypeError('Callback name must be a string.');
+	} if (! (callback instanceof Function)) {
+		throw new TypeError('Callback must be a function.');
+	} else if (! _isRegistrationOpen) {
+		throw new TypeError('Cannot register new callbacks because registry is closed.');
+	} else if (registry.has(name)) {
+		throw new Error(`Handler "${name}" is already registered.`);
+	} else {
+		registry.set(name, callback);
+		return name;
+	}
+}
+
+/**
+ * Get the host/root node of a given thing.
+ *
+ * @param {Event|Document|Element|ShadowRoot} target Source thing to search for host of
+ * @returns {Document|Element|null} The host/root node, or null
+ */
+function getHost(target) {
+	if (target instanceof Event) {
+		return getHost(target.currentTarget);
+	} else if (target instanceof Document) {
+		return target;
+	} else if (target instanceof Element) {
+		return getHost(target.getRootNode());
+	} else if (target instanceof ShadowRoot) {
+		return target.host;
+	} else {
+		return null;
+	}
+}
+
+const EVENT_PREFIX = 'data-aegis-event-on-';
+const EVENT_PREFIX_LENGTH = EVENT_PREFIX.length;
+const DATA_PREFIX = 'aegisEventOn';
+const DATA_PREFIX_LENGTH = DATA_PREFIX.length;
+
+const once = 'data-aegis-event-once',
+	passive = 'data-aegis-event-passive',
+	capture = 'data-aegis-event-capture';
+
+const eventAttrs = [
+	EVENT_PREFIX + 'abort',
+	EVENT_PREFIX + 'blur',
+	EVENT_PREFIX + 'focus',
+	EVENT_PREFIX + 'cancel',
+	EVENT_PREFIX + 'auxclick',
+	EVENT_PREFIX + 'beforeinput',
+	EVENT_PREFIX + 'beforetoggle',
+	EVENT_PREFIX + 'canplay',
+	EVENT_PREFIX + 'canplaythrough',
+	EVENT_PREFIX + 'change',
+	EVENT_PREFIX + 'click',
+	EVENT_PREFIX + 'close',
+	EVENT_PREFIX + 'contextmenu',
+	EVENT_PREFIX + 'copy',
+	EVENT_PREFIX + 'cuechange',
+	EVENT_PREFIX + 'cut',
+	EVENT_PREFIX + 'dblclick',
+	EVENT_PREFIX + 'drag',
+	EVENT_PREFIX + 'dragend',
+	EVENT_PREFIX + 'dragenter',
+	EVENT_PREFIX + 'dragexit',
+	EVENT_PREFIX + 'dragleave',
+	EVENT_PREFIX + 'dragover',
+	EVENT_PREFIX + 'dragstart',
+	EVENT_PREFIX + 'drop',
+	EVENT_PREFIX + 'durationchange',
+	EVENT_PREFIX + 'emptied',
+	EVENT_PREFIX + 'ended',
+	EVENT_PREFIX + 'formdata',
+	EVENT_PREFIX + 'input',
+	EVENT_PREFIX + 'invalid',
+	EVENT_PREFIX + 'keydown',
+	EVENT_PREFIX + 'keypress',
+	EVENT_PREFIX + 'keyup',
+	EVENT_PREFIX + 'load',
+	EVENT_PREFIX + 'loadeddata',
+	EVENT_PREFIX + 'loadedmetadata',
+	EVENT_PREFIX + 'loadstart',
+	EVENT_PREFIX + 'mousedown',
+	EVENT_PREFIX + 'mouseenter',
+	EVENT_PREFIX + 'mouseleave',
+	EVENT_PREFIX + 'mousemove',
+	EVENT_PREFIX + 'mouseout',
+	EVENT_PREFIX + 'mouseover',
+	EVENT_PREFIX + 'mouseup',
+	EVENT_PREFIX + 'wheel',
+	EVENT_PREFIX + 'paste',
+	EVENT_PREFIX + 'pause',
+	EVENT_PREFIX + 'play',
+	EVENT_PREFIX + 'playing',
+	EVENT_PREFIX + 'progress',
+	EVENT_PREFIX + 'ratechange',
+	EVENT_PREFIX + 'reset',
+	EVENT_PREFIX + 'resize',
+	EVENT_PREFIX + 'scroll',
+	EVENT_PREFIX + 'scrollend',
+	EVENT_PREFIX + 'securitypolicyviolation',
+	EVENT_PREFIX + 'seeked',
+	EVENT_PREFIX + 'seeking',
+	EVENT_PREFIX + 'select',
+	EVENT_PREFIX + 'slotchange',
+	EVENT_PREFIX + 'stalled',
+	EVENT_PREFIX + 'submit',
+	EVENT_PREFIX + 'suspend',
+	EVENT_PREFIX + 'timeupdate',
+	EVENT_PREFIX + 'volumechange',
+	EVENT_PREFIX + 'waiting',
+	EVENT_PREFIX + 'selectstart',
+	EVENT_PREFIX + 'selectionchange',
+	EVENT_PREFIX + 'toggle',
+	EVENT_PREFIX + 'pointercancel',
+	EVENT_PREFIX + 'pointerdown',
+	EVENT_PREFIX + 'pointerup',
+	EVENT_PREFIX + 'pointermove',
+	EVENT_PREFIX + 'pointerout',
+	EVENT_PREFIX + 'pointerover',
+	EVENT_PREFIX + 'pointerenter',
+	EVENT_PREFIX + 'pointerleave',
+	EVENT_PREFIX + 'gotpointercapture',
+	EVENT_PREFIX + 'lostpointercapture',
+	EVENT_PREFIX + 'mozfullscreenchange',
+	EVENT_PREFIX + 'mozfullscreenerror',
+	EVENT_PREFIX + 'animationcancel',
+	EVENT_PREFIX + 'animationend',
+	EVENT_PREFIX + 'animationiteration',
+	EVENT_PREFIX + 'animationstart',
+	EVENT_PREFIX + 'transitioncancel',
+	EVENT_PREFIX + 'transitionend',
+	EVENT_PREFIX + 'transitionrun',
+	EVENT_PREFIX + 'transitionstart',
+	EVENT_PREFIX + 'webkitanimationend',
+	EVENT_PREFIX + 'webkitanimationiteration',
+	EVENT_PREFIX + 'webkitanimationstart',
+	EVENT_PREFIX + 'webkittransitionend',
+	EVENT_PREFIX + 'error',
+];
+
+let selector = eventAttrs.map(attr => `[${CSS.escape(attr)}]`).join(', ');
+
+const attrToProp = attr => `on${attr[EVENT_PREFIX_LENGTH].toUpperCase()}${attr.substring(EVENT_PREFIX_LENGTH + 1)}`;
+
+const attrEntriesMap = attr => [attrToProp(attr), attr];
+
+const isEventDataAttr = ([name]) => name.startsWith(DATA_PREFIX);
+
+const DATA_EVENTS = Object.fromEntries([...eventAttrs].map(attrEntriesMap));
+
+function _addListeners(el, { signal, attrFilter = EVENTS } = {}) {
+	const dataset = el.dataset;
+
+	for (const [attr, val] of Object.entries(dataset).filter(isEventDataAttr)) {
+		try {
+			const event = 'on' + attr.substring(DATA_PREFIX_LENGTH);
+
+			if (attrFilter.hasOwnProperty(event) && hasCallback(val)) {
+				el.addEventListener(event.substring(2).toLowerCase(), getCallback(val), {
+					passive: dataset.hasOwnProperty('aegisEventPassive'),
+					capture: dataset.hasOwnProperty('aegisEventCapture'),
+					once: dataset.hasOwnProperty('aegisEventOnce'),
+					signal,
+				});
+			}
+		} catch(err) {
+			console.error(err);
+		}
+	}
+}
+
+const observer = new MutationObserver(records => {
+	records.forEach(record  => {
+		switch(record.type) {
+			case 'childList':
+				[...record.addedNodes]
+					.filter(node => node.nodeType === Node.ELEMENT_NODE)
+					.forEach(node => attachListeners(node));
+				break;
+
+			case 'attributes':
+				if (typeof record.oldValue === 'string' && hasCallback(record.oldValue)) {
+					record.target.removeEventListener(
+						record.attributeName.substring(EVENT_PREFIX_LENGTH),
+						getCallback(record.oldValue), {
+							once: record.target.hasAttribute(once),
+							capture: record.target.hasAttribute(capture),
+							passive: record.target.hasAttribute(passive),
+						}
+					);
+				}
+
+				if (
+					record.target.hasAttribute(record.attributeName)
+					&& hasCallback(record.target.getAttribute(record.attributeName))
+				) {
+					record.target.addEventListener(
+						record.attributeName.substring(EVENT_PREFIX_LENGTH),
+						getCallback(record.target.getAttribute(record.attributeName)), {
+							once: record.target.hasAttribute(once),
+							capture: record.target.hasAttribute(capture),
+							passive: record.target.hasAttribute(passive),
+						}
+					);
+				}
+				break;
+		}
+	});
+});
+
+const EVENTS = { ...DATA_EVENTS, once, passive, capture };
+
+/**
+ * Register an attribute to observe for adding/removing event listeners
+ *
+ * @param {string} attr Name of the attribute to observe
+ * @param {object} options
+ * @param {boolean} [options.addListeners=false] Whether or not to automatically add listeners
+ * @param {Document|Element} [options.base=document.body] Root node to observe
+ * @param {AbortSignal} [options.signal] An abort signal to remove any listeners when aborted
+ * @returns {string} The resulting `data-*` attribute name
+ */
+function registerEventAttribute(attr, {
+	addListeners = false,
+	base = document.body,
+	signal,
+} = {}) {
+	const fullAttr = EVENT_PREFIX + attr.toLowerCase();
+
+	if (! eventAttrs.includes(fullAttr)) {
+		const sel = `[${CSS.escape(fullAttr)}]`;
+		const prop = attrToProp(fullAttr);
+		eventAttrs.push(fullAttr);
+		EVENTS[prop] = fullAttr;
+		selector += `, ${sel}`;
+
+		if (addListeners) {
+			requestAnimationFrame(() => {
+				const config = { attrFilter: { [prop]: sel }, signal };
+				[base, ...base.querySelectorAll(sel)].forEach(el => _addListeners(el, config));
+			});
+		}
+	}
+
+	return fullAttr;
+}
+
+/**
+ * Add listeners to an element and its children, matching a generated query based on registered attributes
+ *
+ * @param {Element|Document} target Root node to add listeners from
+ * @param {object} options
+ * @param {AbortSignal} [options.signal] Optional signal to remove event listeners
+ * @returns {Element|Document} Returns the passed target node
+ */
+function attachListeners(target, { signal } = {}) {
+	const nodes = target instanceof Element && target.matches(selector)
+		? [target, ...target.querySelectorAll(selector)]
+		: target.querySelectorAll(selector);
+
+	nodes.forEach(el => _addListeners(el, { signal }));
+
+	return target;
+}
+/**
+ * Add a node to the `MutationObserver` to observe attributes and add/remove event listeners
+ *
+ * @param {Document|Element} root Element to observe attributes on
+ */
+function observeEvents(root = document) {
+	attachListeners(root);
+	observer.observe(root, {
+		subtree: true,
+		childList:true,
+		attributes: true,
+		attributeOldValue: true,
+		attributeFilter: eventAttrs,
+	});
+}
+
+/**
+ * Disconnects the `MutationObserver`, disabling observing of all attribute changes
+ *
+ * @returns {void}
+ */
+const disconnectEventsObserver = () => observer.disconnect();
+
+/**
+ * Register a global error handler callback
+ *
+ * @param {Function} callback Callback to register as a global error handler
+ * @param {EventInit} config Typical event listener config object
+ */
+function setGlobalErrorHandler(callback, { capture, once, passive, signal } = {}) {
+	if (callback instanceof Function) {
+		globalThis.addEventListener('error', callback, { capture, once, passive, signal });
+	} else {
+		throw new TypeError('Callback is not a function.');
+	}
+}
+
+export { EVENTS, FUNCS, attachListeners, callCallback, clearRegistry, closeRegistration, createCallback, disconnectEventsObserver, getCallback, getHost, hasCallback, isRegistrationOpen, listCallbacks, observeEvents, registerCallback, registerEventAttribute, setGlobalErrorHandler, unregisterCallback };