htmx.org 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,21 +1,111 @@
 # Changelog
 
-
-## [1.6.0] - 2021-?-??
+## [1.8.0] - 2022-12-7
+
+* **NOTE**: This release involved some changes to toughy code (e.g. history support) so please test thoroughly and let
+  us know if you see any issues
+* Boosted forms now will automatically push URLs into history as with links.  The [response URL](https://caniuse.com/mdn-api_xmlhttprequest_responseurl) 
+  detection API support is good enough that we feel comfortable making this the default now. 
+  * If you do not want this behavior you can add `hx-push-url='false'` to your boosted forms
+* The [`hx-replace-url`](https://htmx.org/attributes/hx-replace-url) attribute was introduced, allowing you to replace
+  the current URL in history (to complement `hx-push-url`)
+* Bug fix - if htmx is included in a page more than once, we do not process elements multiple times
+* Bug fix - When localStorage is not available we do not attempt to save history in it
+* [Bug fix](https://github.com/bigskysoftware/htmx/issues/908) - `hx-boost` respects the `enctype` attribute
+* `m` is now a valid timing modifier (e.g. `hx-trigger="every 2m"`)
+* `next` and `previous` are now valid extended query selector modifiers, e.g. `hx-target="next div"` will target the
+  next div from the current element
+* Bug fix - `hx-boost` will boost anchor tags with a `_self` target
+* The `load` event now properly supports event filters
+* The websocket extension has had many improvements: (A huge thank you to Denis Palashevskii, our newest committer on the project!)
+  * Implement proper `hx-trigger` support
+  * Expose trigger handling API to extensions
+  * Implement safe message sending with sending queue
+  * Fix `ws-send` attributes connecting in new elements
+  * Fix OOB swapping of multiple elements in response
+* The `HX-Location` response header now implements client-side redirects entirely within htmx
+* The `HX-Reswap` response header allows you to change the swap behavior of htmx
+* The new [`hx-select-oob`](/attributes/hx-select-oob) attribute selects one or more elements from a server response to swap in via an out of band swap
+* The new [`hx-replace-url`](/attributes/hx-replace-url) attribute can be used to replace the current URL in the location 
+  bar (very similar to `hx-push-url` but no new history entry is created).  The corresponding `HX-Replace-Url` response header can be used as well.
+* htmx now properly handles anchors in both boosted links, as well as in `hx-get`, etc. attributes
+
+## [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
+* The `htmx:beforeSwap` event now includes another configurable property: `detail.isError` which can
+  be used to indicate if a given response should be treated as an error or not
+* The `htmx:afterRequest` event has two new detail properties: `success` and `failed`, allowing you to write 
+  trigger filters in htmx or hyperscript:
+  ```applescript
+    on htmx:afterRequest[failed]
+      set #myCheckbox's checked to true
+  ```
+* Fixed the `from:` option in [`hx-trigger`](/attributes/hx-trigger) to support `closest <CSS selector>` 
+  and `find <CSS selector>` forms
+* Don't boost anchor tags with an explicit `target` set
+* Don't cancel all events on boosted elements, only the events that naturally trigger them (click for anchors, submit
+  for forms)
+* Persist revealed state in the DOM so that on history navigation, revealed elements are not re-requested
+* Process all [`hx-ext`](/attributes/hx-ext) attributes, even if no other htmx attribute is on the element
+* Snapshot the current URL on load so that history support works properly after a page refresh occurs
+* Many, many documentation updates (thank you to all the contributors!)
+
+
+## [1.6.0] - 2021-10-01
+
+* Completely reworked `<script>` tag support that now supports the `<script src="...'/>` form
+* You can now use the value `unset` to clear a property that would normally be inherited (e.g. hx-confirm)
+* The `htmx-added` class is added to new content before a swap and removed after the settle phase, which allows you
+  more flexibility in writing CSS transitions for added content (rather than relying on the target, as with `htmx-settling`)
+* The `htmx:beforeSwap` event has been updated to allow you to [configure swapping](https://htmx.org/docs/#modifying_swapping_behavior_with_events)
+  behavior
+* Improved `<title>` extraction support
+* You can listen to events on the `window` object using the `from:` modifier in `hx-trigger`
+* The `root` option of the `intersect` event was fixed
+* Boosted forms respect the `enctype` declaration
+* The `HX-Boosted` header will be sent on requests from boosted elements
+* Promises are not returned from the main ajax function unless it is an api call (i.e. `htmx.ajax`)
 
 ## [1.5.0] - 2021-7-12
 
 * Support tracking of button clicked during a form submission
-* Conditional polling via the [hx-trigger](/attributes/hx-trigger) attribute
-* `document` is now a valid pseudo-selector on the [hx-trigger](/attributes/hx-trigger) `from:` argument, allowing you
+* Conditional polling via the [hx-trigger](https://htmx.org/attributes/hx-trigger) attribute
+* `document` is now a valid pseudo-selector on the [hx-trigger](https://htmx.org/attributes/hx-trigger) `from:` argument, allowing you
   to listen for events on the document.
-* Added the [hx-request](/attributes/hx-request) attribute, allowing you to configure the following aspects of the request
+* Added the [hx-request](https://htmx.org/attributes/hx-request) attribute, allowing you to configure the following aspects of the request
     * `timeout` - the timeout of the request
     * `credentials` - if the request will send credentials
     * `noHeaders` - strips all headers from the request
 * Along with the above attribute, you can configure the default values for each of these via the corresponding `htmx.config`
   properties (e.g. `htmx.config.timeout`)
-* Both the `scroll` and `show` options on [hx-swap](/attributes/hx-swap) now support extended syntax for selecting the
+* Both the `scroll` and `show` options on [hx-swap](https://htmx.org/attributes/hx-swap) now support extended syntax for selecting the
   element to scroll or to show, including the pseudo-selectors `window:top` and `window:bottom`.
 
 ## [1.4.1] - 2021-6-1
@@ -24,13 +114,13 @@
 
 ## [1.4.0] - 2021-5-25
 
-* Added the `queue` option to the [hx-trigger](/attributes/hx-trigger) attribute, allowing you to specify how events
+* Added the `queue` option to the [hx-trigger](https://htmx.org/attributes/hx-trigger) attribute, allowing you to specify how events
   should be queued when they are received with a request in flight
 * The `htmx.config.useTemplateFragments` option was added, allowing you to use HTML template tags for parsing content
   from the server.  This allows you to use Out of Band content when returning things like table rows, but it is not
   IE11 compatible.
 * The `defaultSettleDelay` was dropped to 20ms from 100ms
-* Introduced a new synthetic event, [intersect](/docs#pecial-events) that allows you to trigger when an item is scrolled into view
+* Introduced a new synthetic event, [intersect](https://htmx.org/docs#pecial-events) that allows you to trigger when an item is scrolled into view
   as specified by the `IntersectionObserver` API
 * Fixed timing issue that caused exceptions in the `reveal` logic when scrolling at incredible speeds - <https://github.com/bigskysoftware/htmx/issues/463>
 * Fixed bug causing SVG titles to be incorrectly used as page title - <https://github.com/bigskysoftware/htmx/issues/459>
@@ -46,7 +136,7 @@
   
 ## [1.3.3] - 2021-4-5
 
-* Added the [`hx-disabled`](/docs#security) attribute to allow htmx to be turned off for parts of the DOM
+* Added the [`hx-disabled`](https://htmx.org/docs#security) attribute to allow htmx to be turned off for parts of the DOM
 * SSE now uses a full-jitter exponential backoff algorithm on reconnection, using the `htmx.config.wsReconnectDelay`
   setting
 

package/README.md

@@ -34,8 +34,7 @@ By removing these arbitrary constraints htmx completes HTML as a
 ## quick start
 
 ```html
-  <!-- Load from unpkg -->
-  <script src="https://unpkg.com/htmx.org@1.6.0" ></script>
+  <script src="https://unpkg.com/htmx.org@1.8.0"></script>
   <!-- have a button POST a click via AJAX -->
   <button hx-post="/clicked" hx-swap="outerHTML">
     Click Me
@@ -74,30 +73,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/disable-element.js

@@ -0,0 +1,16 @@
+"use strict";
+
+// Disable Submit Button
+htmx.defineExtension('disable-element', {
+    onEvent: function (name, evt) {
+        let elt = evt.detail.elt;
+        let target = elt.getAttribute("hx-disable-element");
+        let targetElement = (target == "self") ? elt : document.querySelector(target);
+
+        if (name === "htmx:beforeRequest" && targetElement) {
+            targetElement.disabled = true;
+        } else if (name == "htmx:afterRequest" && targetElement) {
+            targetElement.disabled = false;
+        }
+    }
+});

package/dist/ext/loading-states.js

@@ -0,0 +1,179 @@
+;(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',
+					'data-loading-aria-busy',
+				]
+
+				let loadingStateEltsByType = {}
+
+				loadingStateTypes.forEach((type) => {
+					loadingStateEltsByType[type] = getLoadingStateElts(
+						container,
+						type,
+						evt.detail.pathInfo.requestPath
+					)
+				})
+
+				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)
+							)
+						})
+					}
+				)
+
+				loadingStateEltsByType['data-loading-aria-busy'].forEach(
+					(sourceElt) => {
+						getLoadingTarget(sourceElt).forEach((targetElt) => {
+							queueLoadingState(
+								sourceElt,
+								targetElt,
+								() => (targetElt.setAttribute("aria-busy", "true")),
+								() => (targetElt.removeAttribute("aria-busy"))
+							)
+						})
+					}
+				)
+			}
+
+			if (name === 'htmx:afterOnLoad') {
+				while (loadingStatesUndoQueue.length > 0) {
+					loadingStatesUndoQueue.shift()()
+				}
+			}
+		},
+	})
+})()

package/dist/ext/path-deps.js

@@ -5,6 +5,9 @@
     var _root = this;
   
     function dependsOn(pathSpec, url) {
+        if (pathSpec === "ignore") {
+            return false;
+        }
         var dependencyPath = pathSpec.split("/");
         var urlPath = url.split("/");
         for (var i = 0; i < urlPath.length; i++) {
@@ -35,7 +38,7 @@
             if (name === "htmx:beforeOnLoad") {
                 var config = evt.detail.requestConfig;
                 // mutating call
-                if (config.verb !== "get") {
+                if (config.verb !== "get" && evt.target.getAttribute('path-deps') !== 'ignore') {
                     refreshPath(config.path);
                 }
             } 

package/dist/ext/preload.js

@@ -1,7 +1,7 @@
 // This adds the "preload" extension to htmx.  By default, this will 
 // preload the targets of any tags with `href` or `hx-get` attributes 
 // if they also have a `preload` attribute as well.  See documentation
-// for more detauls
+// for more details
 htmx.defineExtension("preload", {
 
 	onEvent: function(name, event) {

package/dist/ext/remove-me.js

@@ -15,7 +15,7 @@
                 if (elt.getAttribute) {
                     maybeRemoveMe(elt);
                     if (elt.querySelectorAll) {
-                        var children = elt.querySelectorAll("[remove-me], [data-remove-me");
+                        var children = elt.querySelectorAll("[remove-me], [data-remove-me]");
                         for (var i = 0; i < children.length; i++) {
                             maybeRemoveMe(children[i]);
                         }

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;
+    }
+})