Update hx-swap-oob documentation/examples

[Keeper-of-the-Keys]

Add around returned in example 2 (hx-swap-oob) since this is required by strict browser engines as described - https://stackoverflow.com/questions/76612680/htmx-hx-swap-oob-adding-a-new-table-row-only-adds-the-tds-and-not-the-wrappin

Description

This brings the example in the documentation in line with what works in Firefox (126) and Chrome (124), for my enabling/disabling htmx.config.useTemplateFragments = true; has no effect but enclosing the hx-swap-oob in the appropriate tags did work.

Corresponding issue:
#1900
#1198

Testing

This is documentation but I used the following PHP/HTML to test my theories and based on it there is I think even more that needs to be changed in the documentation but I am unsure of the way to formulate things:

<?php

if (isset($_GET['test'])) {
	switch($_GET['test']) {
	case 1:?>
<tr hx-swap-oob="beforeend:#table tbody">
	<td>1 tr</td>
	<td>2 tr</td>
	<td>3 tr</td>
</tr>
<tr hx-swap-oob="beforeend:#table2">
	<td>1 tr</td>
	<td>2 tr</td>
	<td>3 tr</td>
</tr>
<?php
	break;
	
	case 2:?>
<div hx-swap-oob="beforeend:#table tbody">
<tr>
	<td>1 div tr</td>
	<td>2 div tr</td>
	<td>3 div tr</td>
</tr>
</div>
<div hx-swap-oob="beforeend:#table2">
<tr>
	<td>1 div tr</td>
	<td>2 div tr</td>
	<td>3 div tr</td>
</tr>
</div>
<?php
	break;
	case 3:?>
<tbody hx-swap-oob="beforeend:#table tbody">
<tr>
	<td>1 tbody tr</td>
	<td>2 tbody tr</td>
	<td>3 tbody tr</td>
</tr>
</tbody>
<tbody hx-swap-oob="beforeend:#table2">
<tr>
	<td>1 tbody tr</td>
	<td>2 tbody tr</td>
	<td>3 tbody tr</td>
</tr>
</tbody>
<?php
	break;
	case 4:?>
<li hx-swap-oob="beforeend:#list1">new item li</li>
<?php
	break;
	case 5:?>
<ul hx-swap-oob="beforeend:#list1"><li>new item ul li</li></ul>
<?php
	break;
	case 6:?>
<div hx-swap-oob="beforeend:#list1"><li>new item div li</li></div>
<?php
	break;
	case 7:?>
<li hx-swap-oob="beforeend:#list1"><li>new item li li</li></li>
<?php
	break;
	case 8:?>
<p hx-swap-oob="beforeend:#text">new paragraph p</p>
<?php
	break;
	case 9:?>
<div hx-swap-oob="beforeend:#text"><p>new paragraph div p</p></div>
<?php
	break;
	case 10:?>
<p hx-swap-oob="beforeend:#text"><p>new paragraph p p</p></p>
<?php
	break;
	case 11:?>
<span hx-swap-oob="beforeend:#text"><p>new paragraph span p</p></span>
<?php
	break;
	}
} else {?>

<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
<script src="https://unpkg.com/[email protected]"></script>

<table id="table" class="table">
	<caption>With thead/tbody</caption>
	<thead>
		<tr>
			<td>Col 1</td>
			<td>Col 2</td>
			<td>Col 3</td>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>row 1-1</td>
			<td>row 1-2</td>
			<td>row 1-3</td>
		</tr>
	</tbody>
</table>
<table id="table2" class="table">
	<caption>No thead/tbody</caption>
	<tr>
		<th>Col 1</th>
		<th>Col 2</th>
		<th>Col 3</th>
	</tr>
	<tr>
		<td>row 1-1</td>
		<td>row 1-2</td>
		<td>row 1-3</td>
	</tr>
</table>
<button hx-get="?test=1" hx-swap="none">test1 tr</button>
<button hx-get="?test=2" hx-swap="none">test2 div</button>
<button hx-get="?test=3" hx-swap="none">test3 tbody</button>

<ul id="list1">
	<li>item 1</li>
	<li>item 2</li>
	<li>item 3</li>
</ul>
<button hx-get="?test=4" hx-swap="none">test4 li</button>
<button hx-get="?test=5" hx-swap="none">test5 ul li</button>
<button hx-get="?test=6" hx-swap="none">test6 div li</button>
<button hx-get="?test=7" hx-swap="none">test7 li li</button>

<div id="text">
	<p>paragraph1</p>
	<p>paragraph2</p>
</div>
<button hx-get="?test=8" hx-swap="none">test8 p</button>
<button hx-get="?test=9" hx-swap="none">test9 div p</button>
<button hx-get="?test=10" hx-swap="none">test10 p p</button>
<button hx-get="?test=11" hx-swap="none">test11 span p</button>


<?php
}
?>

Checklist

• I have read the contribution guidelines
• I have targeted this PR against the correct branch (master for website changes, dev for
  source changes)
• This is either a bugfix, a documentation update, or a new feature that has been explicitly
  approved via an issue
  * [ ] I ran the test suite locally (npm run test) and verified that it succeeded Not applicable for a documentation change

[Keeper-of-the-Keys]

From my basic tests what I saw was that the element with the hx-swap-oob property was stripped and not inserted in the target element, thus if like in the current example you would return

<tr hx-swap-oob="beforeend:#contacts-table">
    <td>Joe Smith</td>
    <td>[email protected]</td>
</tr>

Only the two <td> elements would be inserted, or if you return just an <li> only it's enclosed content would be inserted and thus you are required to enclose the element, for a <tr> it would seem a <tbody> is required whereas for other elements <div> or <span> seems to also work.

Based on all these observations IMHO this is not a bug in htmx as others suspected but just a bug in the documentation on how to use hx-swap-oob since it makes no mention or suggestion of the containing element not being inserted.

[Keeper-of-the-Keys]

I hope that my previous two messages weren't too rambling they were done very late at night/early in the morning for me, I actually thought out a more generalized way of saying what I was trying to say -

If I return the following

<elementX hx-swap-oob="beforeend:#someid">Content</elementX>

Then based on the documentation and all the given examples and other behavior of htmx I would expect the result of this action to be:

<elementA id="someid">
   <elementPreexistingChild></elementPreexistingChild>
   <elementX>Content</elementX>
</elementA>

Based on my tests what actually happens is

<elementA id="someid">
   <elementPreexistingChild></elementPreexistingChild>
   Content
</elementA>

Thus elementX needs to be enclosed in a container, in addition to this there seems to be a dependency on what elementX is as to what containing elements will be acceptable (specifically table elements need a valid table container like tbody).

Based on some further testing the only hx-swap option that would preserve elementX is outerHTML.

As stated previously I do not think this is a bug in htmx, rather it is an omission of a behavior in the documentation.