update doco

Author: MichaelWest22

src/htmx.js

@@ -1908,8 +1908,8 @@ var htmx = (function() {
         // @ts-ignore
         end: activeElt ? activeElt.selectionEnd : null
       }
-      if (swapSpec.settleDelay !== undefined) {
-        oobSettleInfo = undefined // for oobSwaps with settle modifier make and perform own settleInfo
+      if (swapSpec.settleDelay !== undefined || swapSpec.swapDelay != undefined) {
+        oobSettleInfo = undefined // for oobSwaps with swap or settle modifier make and perform own settleInfo
       }
       const settleInfo = oobSettleInfo || makeSettleInfo(target)
 

www/content/attributes/hx-swap-oob.md

@@ -7,7 +7,7 @@ description = """\
 +++
 
 The `hx-swap-oob` attribute allows you to specify that some content in a response should be
-swapped into the DOM somewhere other than the target, that is "Out of Band".  This allows you to piggyback updates to other element updates on a response.
+swapped into the DOM somewhere other than the target, that is "Out of Band". This allows you to update multiple elements on a page with a single request.
 
 Consider the following response HTML:
 
@@ -23,44 +23,71 @@ Consider the following response HTML:
 
 The first div will be swapped into the target the usual manner.  The second div, however, will be swapped in as a replacement for the element with the id `alerts`, and will not end up in the target.
 
-The value of the `hx-swap-oob` can be:
+### Syntax Options
 
-* `true`
-* any valid basic [`hx-swap`](@/attributes/hx-swap.md) strategy (innerHTML, outerHTML, beforebegin, etc)
-* any valid basic [`hx-swap`](@/attributes/hx-swap.md) strategy, followed by a colon, followed by a CSS selector
-* any valid complex [`hx-swap`](@/attributes/hx-swap.md) value including modifiers like `target:` to set the target of the swap
+The value of the `hx-swap-oob` attribute can be:
+
+* `true` - Uses the default `outerHTML` swap strategy with ID-based targeting
+* Any valid basic [`hx-swap`](@/attributes/hx-swap.md) strategy (innerHTML, outerHTML, beforebegin, etc)
+* Any valid basic [`hx-swap`](@/attributes/hx-swap.md) strategy, followed by a colon, followed by a target CSS selector
+* Any valid complex [`hx-swap`](@/attributes/hx-swap.md) value including modifiers like `target:` to set the target of the swap
+
+### Behavior Details
 
 If the value is `true` or `outerHTML` (which are equivalent) the element will be swapped inline.
 
-If a swap strategy is given, that swap strategy will be used and the encapsulating tag pair will be stripped for all strategies other than `outerHTML`. You can now use `strip:true` modifier to enable tag stripping for `outerHTML` or `strip:false` to disable it for the other strategies.
+If a different swap strategy than `true`/`outerHTML` is supplied the encapsulating tag pair will be stripped so only the inner contents of the element will be used. You can now use `strip:true` modifier to enable tag stripping for `outerHTML` or `strip:false` to disable it for the other strategies when required.
 
 If a selector is given, all elements matched by that selector will be swapped.  If not, the element on the page with an ID matching that of the oob element will be swapped instead.
 
-If you include any [`hx-swap`](@/attributes/hx-swap.md) modifers (e.g. `innerHTML swap:1s` to delay the swap) then you need to also use `target:<Selector>` if you want to target something other than the oob elements ID instead of using the basic colon followed by a selector. So `innerHTML:#foo` with a delay becomes `innerHTML swap:1s target:#foo`.
+### Modifers
+
+The following modifers from [`hx-swap`](@/attributes/hx-swap.md) can now be included after the swap strategy sperated by spaces:
 
-You can include `strip:true` as a modifer to allow you to override the `outerHTML` swap strategy to remove the encapsulating tag pair and allow you to swap in just the inner nodes of the oob element instead
+* `transition:` - Wrap the oob swap in its own [View Transition](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) 
+* `swap:`/`settle:` - Delay the swap or settle time for the oob swap and make its settle independant from the main swap
+* `scroll:`/`show:`/`focus-scroll:` - Control the scrolling behaviour of the oob swap
+* `strip:` - Override the stripping or not of the oob elements encapsulating tag pair
+* `target:` - Set a custom CSS selector to use as the target
 
-You can include `strip:false` as a modifer to allow you to override an inner swap strategy like `innerHTML` or `beforeend` to keep the encapsulating tag pair and swap in the whole oob element instead of just its inner contents.
+Before modifers were supported the swap strategy value could not contain spaces and the target selector was placed after a colon like `innerHTML:#status`. Now when the swap value contains a space it is parsed as swap modifers and you have to be explicit and use the `target:<selector>` modifier like `innerHTML swap:1s target:#status`.
 
 ### Using alternate swap strategies
 
-As mentioned previously when using swap strategies other than `true` or `outerHTML` the encapsulating tags are stripped by default, as such you need to excapsulate the returned data with the correct tags for the context.
+Here are some examples of the various swap strategies:
+
+```html
+<!-- Basic usage with ID targeting -->
+<div id="notifications" hx-swap-oob="true">New notification!</div>
+
+<!-- Using innerHTML with explicit selector -->
+<div hx-swap-oob="innerHTML:#status">Processing complete</div>
+
+<!-- With timing modifier -->
+<div hx-swap-oob="innerHTML swap:1s target:#status">Processing complete</div>
+
+<!-- With scrolling -->
+<div hx-swap-oob="beforeend scroll:bottom target:#log">New log entry</div>
+
+<!-- With transition effect -->
+<div id="animated-element" hx-swap-oob="outerHTML transition:true">Updated content</div>
+```
+
+### Proper Element Encapsulation
+
+As mentioned previously when using swap strategies other than `true` or `outerHTML` the encapsulating tags are stripped by default, however you still need to excapsulate the returned data with the correct tags for the content so it can be parsed as valid html.
 
 When trying to insert a `<tr>` in a table that uses `<tbody>`:
 ```html
-<tbody hx-swap-oob="beforeend target:#table tbody">
-	<tr>
-		...
-	</tr>
+<tbody hx-swap-oob="beforeend:#table tbody">
+	<tr>...</tr>
 </tbody>
 ```
 
 A "plain" table:
 ```html
 <table hx-swap-oob="beforeend target:#table2">
-	<tr>
-		...
-	</tr>
+	<tr>...</tr>
 </table>
 ```
 
@@ -78,31 +105,34 @@ A `<p>` can be encapsulated in `<div>` or `<span>`:
 </span>
 ```
 
-You can also now use `template` tag as this should work for nearly any tag type:
+You can also now use `template` tag as a universal tag that can encapsulate all tag types:
 ```html
 <template hx-swap-oob="beforeend target:#table tbody">
-	<tr>
-		...
-	</tr>
+	<tr>...</tr>
 </template>
 ```
 
+### Overriding Element Encapsulation 
+
 Another new option is the `strip:true` swap modifier that allows you to replace an element with multiple nodes:
 ```html
 <div id="foo" hx-swap-oob="outerHTML strip:true">
-	<div id="foo2">
-		Replace original
-	</div>
-    <div>
-        And add something more
-    </div>
+	<div id="foo2">Replace original</div>
+    <div>And add something more</div>
+</div>
+```
+
+You can also use `strip:false` to allow you to place the oob element itself in various locations
+```html
+<!-- insert after #username -->
+<div hx-swap-oob="afterend strip:false target:#username">
+	User Name is already taken!
 </div>
 ```
 
 ### Troublesome Tables and lists
 
-Note that you can use a `template` tag to encapsulate types of elements that, by the HTML spec, can't stand on their own in the
-DOM (`<tr>`, `<td>`, `<th>`, `<thead>`, `<tbody>`, `<tfoot>`, `<colgroup>`, `<caption>`, `<col>` & `<li>`).
+Note that you can use a `template` tag to encapsulate types of elements that, by the HTML spec, can not be placed adjacent to other normal tags in the DOM (`<tr>`, `<td>`, `<th>`, `<thead>`, `<tbody>`, `<tfoot>`, `<colgroup>`, `<caption>`, `<col>` & `<li>`).
 
 Here is an example with an out-of-band swap of a table row being encapsulated in this way:
 
@@ -118,6 +148,7 @@ Here is an example with an out-of-band swap of a table row being encapsulated in
 ```
 
 Note that these template tags will be removed from the final content of the page.
+When the main content node tag is one of the restricted ones you may also need to wrap the oob nodes.
 
 ### Slippery SVGs