move hx-trigger response header timing to after swap (#3900)

Author: MichaelWest22

src/htmx.js

@@ -644,6 +644,9 @@ var htmx = (() => {
                 this.__trigger(elt, "htmx:error", {ctx, error})
             } finally {
                 clearTimeout(ctx.requestTimeout);
+                if (ctx.hx?.trigger) { // HX-Trigger
+                    this.__handleTriggerHeader(ctx.hx.trigger, ctx.sourceElement);
+                }
                 this.__trigger(elt, "htmx:finally:request", {ctx})
                 if (!ctx.keepIndicators) {
                     this.__hideIndicators(indicators);
@@ -672,9 +675,6 @@ var htmx = (() => {
         // Handle response headers that abort normal swap processing.
         // Returns true if the response was fully handled by a header.
         __handleHeadersAndMaybeReturnEarly(ctx) {
-            if (ctx.hx.trigger) { // HX-Trigger
-                this.__handleTriggerHeader(ctx.hx.trigger, ctx.sourceElement);
-            }
             if (ctx.hx.refresh === 'true') { // HX-Refresh
                 location.reload();
                 return true

test/tests/unit/__handleHxHeadersAndMaybeReturnEarly.js

@@ -8,26 +8,6 @@ describe('__handleHxHeadersAndMaybeReturnEarly unit tests', function() {
         cleanupTest();
     });
 
-    it('handles hx-trigger header', function () {
-        let triggerFired = false
-        let listener = () => { triggerFired = true }
-
-        let container = createProcessedHTML('<div></div>')
-        container.addEventListener('myEvent', listener)
-
-        let ctx = {
-            hx: {
-                trigger: 'myEvent'
-            },
-            sourceElement: container
-        }
-
-        let result = htmx.__handleHeadersAndMaybeReturnEarly(ctx)
-
-        assert.isNotOk(result)
-        assert.isTrue(triggerFired)
-    })
-
     it('returns false when no headers to handle', function () {
         let ctx = {
             hx: {},

test/tests/unit/__issueRequest.js

@@ -177,6 +177,23 @@ describe('__issueRequest unit tests', function() {
         assert.equal(capturedError, testError)
     })
 
+    it('fires HX-Trigger event after swap completes', async function () {
+        let div = createProcessedHTML('<div hx-get="/test" hx-swap="none"></div>')
+        let ctx = htmx.__createRequestContext(div, new Event('click'))
+
+        let triggerFired = false
+        div.addEventListener('myEvent', () => triggerFired = true)
+
+        ctx.fetch = async () => ({
+            status: 200,
+            headers: new Headers({ 'HX-Trigger': 'myEvent' }),
+            text: async () => ''
+        })
+
+        await htmx.__issueRequest(ctx)
+        assert.isTrue(triggerFired)
+    })
+
     it('always triggers htmx:finally:request', async function () {
         let div = createProcessedHTML('<div hx-get="/test" hx-swap="none"></div>')
         let ctx = htmx.__createRequestContext(div, new Event('click'))

www/src/content/reference/02-headers/10-HX-Trigger.md

@@ -3,7 +3,7 @@ title: "HX-Trigger"
 description: "Triggers client-side events with `htmx.trigger()`"
 ---
 
-The `HX-Trigger` response header triggers client-side events when a response is received.
+The `HX-Trigger` response header triggers client-side events after the swap has completed.
 
 ## Basic Usage
 
@@ -104,6 +104,8 @@ _This example uses the [`hx-live`](/extensions/hx-live) extension._
 
 Response headers are not processed on 3xx response codes. Return a 2xx status when using this header.
 
+In htmx 2, there were three variants: `HX-Trigger`, `HX-Trigger-After-Swap`, and `HX-Trigger-After-Settle`. In htmx 4, these were consolidated into a single `HX-Trigger` header that fires after the swap completes.
+
 ## See Also
 
 - [`htmx.trigger()`](/reference/methods/htmx-trigger)