docs: clarify HX-Retarget interaction with hx-swap="none" (#3446)

HX-Retarget only changes *where* the swap happens — the swap style is still
determined by the source element's hx-swap (or by HX-Reswap). When the source
uses hx-swap="none", retargeting alone produces a no-op because the "none"
swap style applies at the new target too.

Updates the HX-Retarget entries in both docs.md and reference.md to spell
this out and point users at HX-Reswap. The behavior itself is intentional
and consistent — only the docs were silent on this combination.

The original issue reporter noticed the surprise and explicitly suggested
"I would update the docs to include that setting hx-swap='none' will
prevent the use of a swap via HX-Retarget."

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: manwithacat

www/content/docs.md

@@ -1038,7 +1038,7 @@ htmx supports some htmx-specific response headers:
 * `HX-Refresh` - if set to "true" the client-side will do a full refresh of the page
 * [`HX-Replace-Url`](@/headers/hx-replace-url.md) - replaces the current URL in the location bar
 * `HX-Reswap` - allows you to specify how the response will be swapped. See [hx-swap](@/attributes/hx-swap.md) for possible values
-* `HX-Retarget` - a CSS selector that updates the target of the content update to a different element on the page
+* `HX-Retarget` - a CSS selector that updates the target of the content update to a different element on the page. Note that this only changes *where* the swap happens; the swap style is still determined by the source element's [`hx-swap`](@/attributes/hx-swap.md) (or `HX-Reswap`). If the source uses `hx-swap="none"`, you also need to send `HX-Reswap` to make the swap actually occur at the new target.
 * `HX-Reselect` - a CSS selector that allows you to choose which part of the response is used to be swapped in. Overrides an existing [`hx-select`](@/attributes/hx-select.md) on the triggering element
 * [`HX-Trigger`](@/headers/hx-trigger.md) - allows you to trigger client-side events
 * [`HX-Trigger-After-Settle`](@/headers/hx-trigger.md) - allows you to trigger client-side events after the settle step

www/content/reference.md

@@ -116,7 +116,7 @@ All other attributes available in htmx.
 | `HX-Refresh`                                         | if set to "true" the client-side will do a full refresh of the page
 | [`HX-Replace-Url`](@/headers/hx-replace-url.md)      | replaces the current URL in the location bar
 | `HX-Reswap`                                          | allows you to specify how the response will be swapped. See [hx-swap](@/attributes/hx-swap.md) for possible values
-| `HX-Retarget`                                        | a CSS selector that updates the target of the content update to a different element on the page
+| `HX-Retarget`                                        | a CSS selector that updates the target of the content update to a different element on the page (only changes *where* the swap happens; combine with `HX-Reswap` if the source has `hx-swap="none"`)
 | `HX-Reselect`                                        | a CSS selector that allows you to choose which part of the response is used to be swapped in. Overrides an existing [`hx-select`](@/attributes/hx-select.md) on the triggering element
 | [`HX-Trigger`](@/headers/hx-trigger.md)              | allows you to trigger client-side events
 | [`HX-Trigger-After-Settle`](@/headers/hx-trigger.md) | allows you to trigger client-side events after the settle step