support extended css selectors in hx-partial (#3924)

* support extended css selectors in hx-partial

* fix empty hx-partial targeting cuasing empty swaps

Author: MichaelWest22

src/htmx.js

@@ -1176,7 +1176,8 @@ var htmx = (() => {
                     if (targetSelector) {
                         this.__processScripts(templateElt.content);
                         let swapSpec = this.__parseSwapSpec(this.__attr(templateElt, 'hx-swap') || this.config.defaultSwap);
-                        for (let target of document.querySelectorAll(targetSelector)) {
+                        let targets = this.__findAllExt(ctx.sourceElement, targetSelector);
+                        for (let target of targets.length ? targets : [null]) {
                             tasks.push({
                                 type: 'partial',
                                 fragment: templateElt.content.cloneNode(true),
@@ -1894,7 +1895,7 @@ var htmx = (() => {
 
         __findAllExt(eltOrSelector, maybeSelector, thisAttr, global) {
             let selector = maybeSelector ?? eltOrSelector;
-            let elt = maybeSelector ? this.__normalizeElement(eltOrSelector) : document;
+            let elt = maybeSelector ? (this.__normalizeElement(eltOrSelector) || document.body) : document;
             if (selector.startsWith('global ')) {
                 return this.__findAllExt(elt, selector.slice(7), thisAttr, true);
             }

test/tests/unit/swap.js

@@ -468,6 +468,15 @@ describe('swap() unit tests', function() {
         find('#target_oob').textContent.should.equal("OOB Updated");
     })
 
+    it('does not swap main target when partial target is not found', async function () {
+        createProcessedHTML("<div id='target'>Original</div>")
+        await htmx.swap({
+            "target":"#target",
+            "text":"<hx-partial hx-target='#nonexistent' hx-swap='innerHTML'><div>Should Not Appear</div></hx-partial>"
+        })
+        find('#target').textContent.should.equal("Original");
+    })
+
     it('does not swap main target when only whitespace and partial present', async function () {
         createProcessedHTML("<div id='target'>Original</div><div id='target_oob'>OOB</div>")
         await htmx.swap({
@@ -683,6 +692,16 @@ describe('swap() unit tests', function() {
         target.textContent.should.equal('response')
     })
 
+    it('hx-partial hx-target resolves closest relative to sourceElement', async function () {
+        createProcessedHTML("<ul><li id='item-1'>Item 1 <button id='btn'>Edit</button></li></ul>")
+        await htmx.swap({
+            target: find('#btn'),
+            sourceElement: find('#btn'),
+            text: "<hx-partial hx-target='closest li' hx-swap='innerHTML'>Updated</hx-partial>"
+        })
+        find('#item-1').innerText.should.equal('Updated')
+    })
+
     it('swaps partial to all elements matching a class selector', async function () {
         createProcessedHTML("<div class='target'>A</div><div class='target'>B</div>")
         await htmx.swap({"target":"#test-playground", "text":"<hx-partial hx-target='.target' hx-swap='innerHTML'>Updated</hx-partial>"})

www/src/content/reference/06-tags/01-hx-partial.md

@@ -20,12 +20,30 @@ The `<hx-partial>` tag lets you update multiple elements from a single response,
 
 ## Attributes
 
-- [`hx-target`](/reference/attributes/hx-target) - CSS selector for where to place content
+- [`hx-target`](/reference/attributes/hx-target) - Where to place content. Accepts any CSS selector or htmx extended selector, resolved relative to the element that triggered the request
 - `id` - Shorthand alternative to `hx-target`. Targets the element with that ID (e.g. `<hx-partial id="messages">` targets `#messages`)
 - [`hx-swap`](/reference/attributes/hx-swap) - Swap style (defaults to `innerHTML`)
 
 Either `hx-target` or `id` is required. If both are present, `hx-target` takes precedence.
 
+## Relative Targeting
+
+`hx-target` supports the full htmx extended selector vocabulary — `closest`, `next`, `previous`, `find`, `findAll` — resolved relative to the element that triggered the request. This lets the server express structural intent without requiring stable IDs:
+
+```html
+<!-- replace the list row containing the button that was clicked -->
+<hx-partial hx-target="closest li" hx-swap="outerHTML">
+    <li>Updated item <button hx-post="/edit/2">Edit</button></li>
+</hx-partial>
+
+<!-- update the error element after the input that triggered validation -->
+<hx-partial hx-target="next .error">
+    <span class="error">Required</span>
+</hx-partial>
+```
+
+Avoid targeting an ancestor that the main swap is also replacing — the partial would be swapping into a detached node.
+
 ## Responses Without Main Content
 
 When a response contains only `<hx-partial>` tags (no main content), the main target is left untouched. See [Multi-Target Updates](/docs#choosing-between-them) for details.