htmx.org 1.6.1 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.7.0] - 2022-02-2
+
+* The new [`hx-sync`](/attributes/hx-sync) attribute allows you to synchronize multiple element requests on a single
+  element using various strategies (e.g. replace)
+  * You can also now abort an element making a request by sending it the `htmx:abort` event
+* [Server Sent Events](/extensions/server-sent-events) and [Web Sockets](/extensions/web-sockets) are now available as 
+  extensions, in addition to the normal core support.  In htmx 2.0, the current `hx-sse` and `hx-ws` attributes will be
+  moved entirely out to these new extensions.  By moving these features to extensions we will be able to add functionality 
+  to both of them without compromising the core file size of htmx.  You are encouraged to move over to the new 
+  extensions, but `hx-sse` and `hx-ws` will continue to work indefinitely in htmx 1.x.
+* You can now mask out [attribute inheritance](/docs#inheritance) via the [`hx-disinherit`](/attributes/hx-disinherit) attribute.
+* The `HX-Push` header can now have the `false` value, which will prevent a history snapshot from occuring.
+* Many new extensions, with a big thanks to all the contributors!
+    * A new [`alpine-morph`](/extensions/alpine-morph) allows you to use Alpine's swapping engine, which preserves Alpine
+    * A [restored](/extensions/restored) extension was added that will trigger a `restore` event on all elements in the DOM
+      on history restoration.
+    * A [loading-states](/extensions/loading-states) extension was added that allows you to easily manage loading states
+      while a request is in flight, including disabling elements, and adding and removing CSS classes. 
+* The `this` symbol now resolves properly for the [`hx-include`](/attributes/hx-include) and [`hx-indicator`](/attributes/hx-indicator)
+  attributes
+* When an object is included via the [`hx-vals`](/attributes/hx-vals) attribute, it will be converted to JSON (rather 
+  than rendering as the string `[Object object]"`)
+* You can now pass a swap style in to the `htmx.ajax()` function call.
+* Poll events now contain a `target` attribute, allowing you to filter a poll on the element that is polling.
+* Two new Out Of Band-related events were added: `htmx:oobBeforeSwap` & `htmx:oobAfterSwap`
+
 ## [1.6.1] - 2021-11-22
 
 * A new `HX-Retarget` header allows you to change the default target of returned content

package/README.md

@@ -35,7 +35,7 @@ By removing these arbitrary constraints htmx completes HTML as a
 
 ```html
   <!-- Load from unpkg -->
-  <script src="https://unpkg.com/htmx.org@1.6.1" ></script>
+  <script src="https://unpkg.com/htmx.org@1.7.0" ></script>
   <!-- have a button POST a click via AJAX -->
   <button hx-post="/clicked" hx-swap="outerHTML">
     Click Me
@@ -74,30 +74,35 @@ keep the core htmx code tidy
 
 ### hacking guide
 
-to develop htmx locally, you will need to install the development dependencies:
+To develop htmx locally, you will need to install the development dependencies.
+Use node 15 and run:
 
-* `npm install`
+```
+npm install
+```
 
-and then run a web server in the root (easiest with python):
+Then, run a web server in the root.
+This is easiest with Python:
 
-* `python3 -m http.server
-`
+```
+python3 -m http.server
+```
 
-you can then run the test suite by navigating to:
+You can then run the test suite by navigating to:
 
 <http://0.0.0.0:8000/test/>
 
-at this point you can modify `/src/htmx.js` to add features, and then add tests in the appropriate area under `/test`
+At this point you can modify `/src/htmx.js` to add features, and then add tests in the appropriate area under `/test`.
 
 * `/test/index.html` - the root test page from which all other tests are included
-* `/test/attributres` - attribute specific tests
+* `/test/attributes` - attribute specific tests
 * `/test/core` - core functionality tests
-* `/test/core/regressions.js` - regresssion tests
+* `/test/core/regressions.js` - regression tests
 * `/test/ext` - extension tests
 * `/test/manual` - manual tests that cannot be automated
 
 htmx uses the [mocha](https://mochajs.org/) testing framework, the [chai](https://www.chaijs.com/) assertion framework 
-and [sinon](https://sinonjs.org/releases/v11.1.1/fake-xhr-and-server/) to mock out AJAX requests.  They are all OK.
+and [sinon](https://sinonjs.org/releases/v9/fake-xhr-and-server/) to mock out AJAX requests.  They are all OK.
 
 ## haiku
 

package/dist/ext/alpine-morph.js

@@ -0,0 +1,16 @@
+htmx.defineExtension('alpine-morph', {
+    isInlineSwap: function (swapStyle) {
+        return swapStyle === 'morph';
+    },
+    handleSwap: function (swapStyle, target, fragment) {
+        if (swapStyle === 'morph') {
+            if (fragment.nodeType === Node.DOCUMENT_FRAGMENT_NODE) {
+                Alpine.morph(target, fragment.firstElementChild);
+                return [target];
+            } else {
+                Alpine.morph(target, fragment.outerHTML);
+                return [target];
+            }
+        }
+    }
+});

package/dist/ext/loading-states.js

@@ -0,0 +1,165 @@
+;(function () {
+	let loadingStatesUndoQueue = []
+
+	function loadingStateContainer(target) {
+		return htmx.closest(target, '[data-loading-states]') || document.body
+	}
+
+	function mayProcessUndoCallback(target, callback) {
+		if (document.body.contains(target)) {
+			callback()
+		}
+	}
+
+	function mayProcessLoadingStateByPath(elt, requestPath) {
+		const pathElt = htmx.closest(elt, '[data-loading-path]')
+		if (!pathElt) {
+			return true
+		}
+
+		return pathElt.getAttribute('data-loading-path') === requestPath
+	}
+
+	function queueLoadingState(sourceElt, targetElt, doCallback, undoCallback) {
+		const delayElt = htmx.closest(sourceElt, '[data-loading-delay]')
+		if (delayElt) {
+			const delayInMilliseconds =
+				delayElt.getAttribute('data-loading-delay') || 200
+			const timeout = setTimeout(() => {
+				doCallback()
+
+				loadingStatesUndoQueue.push(() => {
+					mayProcessUndoCallback(targetElt, () => undoCallback())
+				})
+			}, delayInMilliseconds)
+
+			loadingStatesUndoQueue.push(() => {
+				mayProcessUndoCallback(targetElt, () => clearTimeout(timeout))
+			})
+		} else {
+			doCallback()
+			loadingStatesUndoQueue.push(() => {
+				mayProcessUndoCallback(targetElt, () => undoCallback())
+			})
+		}
+	}
+
+	function getLoadingStateElts(loadingScope, type, path) {
+		return Array.from(htmx.findAll(loadingScope, `[${type}]`)).filter(
+			(elt) => mayProcessLoadingStateByPath(elt, path)
+		)
+	}
+
+	function getLoadingTarget(elt) {
+		if (elt.getAttribute('data-loading-target')) {
+			return Array.from(
+				htmx.findAll(elt.getAttribute('data-loading-target'))
+			)
+		}
+		return [elt]
+	}
+
+	htmx.defineExtension('loading-states', {
+		onEvent: function (name, evt) {
+			if (name === 'htmx:beforeRequest') {
+				const container = loadingStateContainer(evt.target)
+
+				const loadingStateTypes = [
+					'data-loading',
+					'data-loading-class',
+					'data-loading-class-remove',
+					'data-loading-disable',
+				]
+
+				let loadingStateEltsByType = {}
+
+				loadingStateTypes.forEach((type) => {
+					loadingStateEltsByType[type] = getLoadingStateElts(
+						container,
+						type,
+						evt.detail.pathInfo.path
+					)
+				})
+
+				loadingStateEltsByType['data-loading'].forEach((sourceElt) => {
+					getLoadingTarget(sourceElt).forEach((targetElt) => {
+						queueLoadingState(
+							sourceElt,
+							targetElt,
+							() =>
+								(targetElt.style.display =
+									sourceElt.getAttribute('data-loading') ||
+									'inline-block'),
+							() => (targetElt.style.display = 'none')
+						)
+					})
+				})
+
+				loadingStateEltsByType['data-loading-class'].forEach(
+					(sourceElt) => {
+						const classNames = sourceElt
+							.getAttribute('data-loading-class')
+							.split(' ')
+
+						getLoadingTarget(sourceElt).forEach((targetElt) => {
+							queueLoadingState(
+								sourceElt,
+								targetElt,
+								() =>
+									classNames.forEach((className) =>
+										targetElt.classList.add(className)
+									),
+								() =>
+									classNames.forEach((className) =>
+										targetElt.classList.remove(className)
+									)
+							)
+						})
+					}
+				)
+
+				loadingStateEltsByType['data-loading-class-remove'].forEach(
+					(sourceElt) => {
+						const classNames = sourceElt
+							.getAttribute('data-loading-class-remove')
+							.split(' ')
+
+						getLoadingTarget(sourceElt).forEach((targetElt) => {
+							queueLoadingState(
+								sourceElt,
+								targetElt,
+								() =>
+									classNames.forEach((className) =>
+										targetElt.classList.remove(className)
+									),
+								() =>
+									classNames.forEach((className) =>
+										targetElt.classList.add(className)
+									)
+							)
+						})
+					}
+				)
+
+				loadingStateEltsByType['data-loading-disable'].forEach(
+					(sourceElt) => {
+						getLoadingTarget(sourceElt).forEach((targetElt) => {
+							queueLoadingState(
+								sourceElt,
+								targetElt,
+								() => (targetElt.disabled = true),
+								() => (targetElt.disabled = false)
+							)
+						})
+					}
+				)
+			}
+
+			if (name === 'htmx:afterOnLoad') {
+				while (loadingStatesUndoQueue.length > 0) {
+					loadingStatesUndoQueue.shift()()
+				}
+			}
+		},
+	})
+})()

package/dist/ext/restored.js

@@ -0,0 +1,15 @@
+htmx.defineExtension('restored', {
+    onEvent : function(name, evt) {
+        if (name === 'htmx:restored'){
+            var restoredElts = evt.detail.document.querySelectorAll(
+                "[hx-trigger='restored'],[data-hx-trigger='restored']"
+            );
+            // need a better way to do this, would prefer to just trigger from evt.detail.elt
+            var foundElt = Array.from(restoredElts).find(
+                (x) => (x.outerHTML === evt.detail.elt.outerHTML)
+            );
+            var restoredEvent = evt.detail.triggerEvent(foundElt, 'restored');
+        }
+        return;
+    }
+})

package/dist/ext/sse.js

@@ -0,0 +1,318 @@
+/*
+Server Sent Events Extension
+============================
+This extension adds support for Server Sent Events to htmx.  See /www/extensions/sse.md for usage instructions.
+
+*/
+
+(function(){
+
+	/** @type {import("../htmx").HtmxInternalApi} */
+	var api;
+
+	htmx.defineExtension("sse", {
+
+		/**
+		 * Init saves the provided reference to the internal HTMX API.
+		 * 
+		 * @param {import("../htmx").HtmxInternalApi} api 
+		 * @returns void
+		 */
+		init: function(apiRef) {
+			// store a reference to the internal API.
+			api = apiRef;
+
+			// set a function in the public API for creating new EventSource objects
+			if (htmx.createEventSource == undefined) {
+				htmx.createEventSource = createEventSource;
+			}
+		},
+
+		/**
+		 * onEvent handles all events passed to this extension.
+		 * 
+		 * @param {string} name 
+		 * @param {Event} evt 
+		 * @returns void
+		 */
+		onEvent: function(name, evt) {
+
+			switch (name) {
+
+			// Try to remove remove an EventSource when elements are removed
+			case "htmx:beforeCleanupElement":
+				var internalData = api.getInternalData(evt.target)
+				if (internalData.sseEventSource) {
+					internalData.sseEventSource.close();
+				}
+				return;
+
+			// Try to create EventSources when elements are processed
+			case "htmx:afterProcessNode":
+				createEventSourceOnElement(evt.target);
+			}
+		}
+	});
+
+	///////////////////////////////////////////////
+	// HELPER FUNCTIONS
+	///////////////////////////////////////////////
+
+
+	/**
+	 * createEventSource is the default method for creating new EventSource objects.
+	 * it is hoisted into htmx.config.createEventSource to be overridden by the user, if needed.
+	 * 
+	 * @param {string} url 
+	 * @returns EventSource
+	 */
+	 function createEventSource(url) {
+		return new EventSource(url, {withCredentials:true});
+	}
+
+	function splitOnWhitespace(trigger) {
+		return trigger.trim().split(/\s+/);
+	}
+
+	function getLegacySSEURL(elt) {
+		var legacySSEValue = api.getAttributeValue(elt, "hx-sse");
+		if (legacySSEValue) {
+			var values = splitOnWhitespace(legacySSEValue);
+			for (var i = 0; i < values.length; i++) {
+				var value = values[i].split(/:(.+)/);
+				if (value[0] === "connect") {
+					return value[1];
+				}
+			}
+		}
+	}
+
+	function getLegacySSESwaps(elt) {
+		var legacySSEValue = api.getAttributeValue(elt, "hx-sse");
+		var returnArr = [];
+		if (legacySSEValue) {
+			var values = splitOnWhitespace(legacySSEValue);
+			for (var i = 0; i < values.length; i++) {
+				var value = values[i].split(/:(.+)/);
+				if (value[0] === "swap") {
+					returnArr.push(value[1]);
+				}
+			}
+		}
+		return returnArr;
+	}
+
+	/**
+	 * createEventSourceOnElement creates a new EventSource connection on the provided element.
+	 * If a usable EventSource already exists, then it is returned.  If not, then a new EventSource
+	 * is created and stored in the element's internalData.
+	 * @param {HTMLElement} elt
+	 * @param {number} retryCount
+	 * @returns {EventSource | null}
+	 */
+	function createEventSourceOnElement(elt, retryCount) {
+
+		if (elt == null) {
+			return null;
+		}
+
+		var internalData = api.getInternalData(elt);
+
+		// get URL from element's attribute
+		var sseURL = api.getAttributeValue(elt, "sse-connect");
+
+
+		if (sseURL == undefined) {
+			var legacyURL = getLegacySSEURL(elt)
+			if (legacyURL) {
+				sseURL = legacyURL;
+			} else {
+				return null;
+			}
+		}
+
+		// Connect to the EventSource
+		var source = htmx.createEventSource(sseURL);
+		internalData.sseEventSource = source;
+
+		// Create event handlers
+		source.onerror = function (err) {
+
+			// Log an error event
+			api.triggerErrorEvent(elt, "htmx:sseError", {error:err, source:source});
+
+			// If parent no longer exists in the document, then clean up this EventSource
+			if (maybeCloseSSESource(elt)) {
+				return;
+			}
+
+			// Otherwise, try to reconnect the EventSource
+			if (source.readyState === EventSource.CLOSED) {
+				retryCount = retryCount || 0;
+				var timeout = Math.random() * (2 ^ retryCount) * 500;
+				window.setTimeout(function() {
+					createEventSourceOnElement(elt, Math.min(7, retryCount+1));
+				}, timeout);
+			}			
+		};
+		
+		// Add message handlers for every `sse-swap` attribute
+		queryAttributeOnThisOrChildren(elt, "sse-swap").forEach(function(child) {
+
+			var sseSwapAttr = api.getAttributeValue(child, "sse-swap");
+			if (sseSwapAttr) {
+				var sseEventNames = sseSwapAttr.split(",");
+			} else {
+				var sseEventNames = getLegacySSESwaps(child);
+			}
+
+			for (var i = 0 ; i < sseEventNames.length ; i++) {
+				var sseEventName = sseEventNames[i].trim();
+				var listener = function(event) {
+
+					// If the parent is missing then close SSE and remove listener
+					if (maybeCloseSSESource(elt)) {
+						source.removeEventListener(sseEventName, listener);
+						return;
+					}
+
+					// swap the response into the DOM and trigger a notification
+					swap(child, event.data);
+					api.triggerEvent(elt, "htmx:sseMessage", event);
+				};
+
+				// Register the new listener
+				api.getInternalData(elt).sseEventListener = listener;
+				source.addEventListener(sseEventName, listener);
+			}
+		});
+
+		// Add message handlers for every `hx-trigger="sse:*"` attribute
+		queryAttributeOnThisOrChildren(elt, "hx-trigger").forEach(function(child) {
+
+			var sseEventName = api.getAttributeValue(child, "hx-trigger");
+			if (sseEventName == null) {
+				return;
+			}
+
+			// Only process hx-triggers for events with the "sse:" prefix
+			if (sseEventName.slice(0, 4) != "sse:") {
+				return;
+			}
+
+			var listener = function(event) {
+
+				// If parent is missing, then close SSE and remove listener
+				if (maybeCloseSSESource(elt)) {
+					source.removeEventListener(sseEventName, listener);
+					return;
+				}
+
+				// Trigger events to be handled by the rest of htmx
+				htmx.trigger(child, sseEventName, event);
+				htmx.trigger(child, "htmx:sseMessage", event);
+			}
+
+			// Register the new listener
+			api.getInternalData(elt).sseEventListener = listener;
+			source.addEventListener(sseEventName.slice(4), listener);
+		});
+	}
+
+	/**
+	 * maybeCloseSSESource confirms that the parent element still exists.
+	 * If not, then any associated SSE source is closed and the function returns true.
+	 * 
+	 * @param {HTMLElement} elt 
+	 * @returns boolean
+	 */
+	function maybeCloseSSESource(elt) {
+		if (!api.bodyContains(elt)) {
+			var source = api.getInternalData(elt).sseEventSource;
+			if (source != undefined) {
+				source.close();
+				// source = null
+				return true;
+			}
+		}
+		return false;
+	}
+
+	/**
+	 * queryAttributeOnThisOrChildren returns all nodes that contain the requested attributeName, INCLUDING THE PROVIDED ROOT ELEMENT.
+	 * 
+	 * @param {HTMLElement} elt 
+	 * @param {string} attributeName 
+	 */
+	function queryAttributeOnThisOrChildren(elt, attributeName) {
+
+		var result = [];
+
+		// If the parent element also contains the requested attribute, then add it to the results too.
+		if (api.hasAttribute(elt, attributeName) || api.hasAttribute(elt, "hx-sse")) {
+			result.push(elt);
+		}
+
+		// Search all child nodes that match the requested attribute
+		elt.querySelectorAll("[" + attributeName + "], [data-" + attributeName + "], [hx-sse], [data-hx-sse]").forEach(function(node) {
+			result.push(node);
+		});
+
+		return result;
+	}
+
+	/**
+	 * @param {HTMLElement} elt
+	 * @param {string} content 
+	 */
+	function swap(elt, content) {
+
+		api.withExtensions(elt, function(extension) {
+			content = extension.transformResponse(content, null, elt);
+		});
+
+		var swapSpec = api.getSwapSpecification(elt);
+		var target = api.getTarget(elt);
+		var settleInfo = api.makeSettleInfo(elt);
+
+		api.selectAndSwap(swapSpec.swapStyle, target, elt, content, settleInfo);
+
+		settleInfo.elts.forEach(function (elt) {
+			if (elt.classList) {
+				elt.classList.add(htmx.config.settlingClass);
+			}
+			api.triggerEvent(elt, 'htmx:beforeSettle');
+		});
+
+		// Handle settle tasks (with delay if requested)
+		if (swapSpec.settleDelay > 0) {
+			setTimeout(doSettle(settleInfo), swapSpec.settleDelay);
+		} else {
+			doSettle(settleInfo)();
+		}
+	}
+
+	/**
+	 * doSettle mirrors much of the functionality in htmx that 
+	 * settles elements after their content has been swapped.
+	 * TODO: this should be published by htmx, and not duplicated here
+	 * @param {import("../htmx").HtmxSettleInfo} settleInfo 
+	 * @returns () => void
+	 */
+	function doSettle(settleInfo) {
+
+		return function() {
+			settleInfo.tasks.forEach(function (task) {
+				task.call();
+			});
+
+			settleInfo.elts.forEach(function (elt) {
+				if (elt.classList) {
+					elt.classList.remove(htmx.config.settlingClass);
+				}
+				api.triggerEvent(elt, 'htmx:afterSettle');
+			});
+		}
+	}
+
+})();