From 2dd4b780f8e39d24066a0163c563d710527772ec Mon Sep 17 00:00:00 2001
From: Sean Doyle <sean.p.doyle24@gmail.com>
Date: Thu, 4 Apr 2024 15:31:22 -0400
Subject: [PATCH] Re-structure turbo-stream[action=morph] support

Related to [hotwired/turbo#1240][]

Since the `<turbo-stream action="morph">` hasn't yet been part of a
release, there's an opportunity to rename it without being considerate
of backwards compatibility.

As an alternative to introduce a new Stream Action, this commit changes
existing actions to be more flexible.

For example, the `<turbo-stream method="morph">` element behaves like a
specialized version of a `<turbo-stream method="replace">`, since it
operates on the target element's `outerHTML` property.

Similarly, the `<turbo-stream method="morph" children-only>` element
behaves like a specialized version of a `<turbo-stream
method="update">`, since it operates on the target element's `innerHTML`
property.

```diff
-<turbo-stream action="morph">
+<turbo-stream action="replace" method="morph">
   <template>Replace me with morphing</template>
 </turbo-stream>

-<turbo-stream action="morph" children-only>
+<turbo-stream action="update" method="morph">
   <template>Update me with morphing</template>
 </turbo-stream>
```

[hotwired/turbo#1240]: https://github.com/hotwired/turbo/pull/1240
---
 _source/handbook/05_streams.md | 30 ++++++++++++------------
 _source/reference/streams.md   | 42 ++++++++++++++++------------------
 2 files changed, 34 insertions(+), 38 deletions(-)

diff --git a/_source/handbook/05_streams.md b/_source/handbook/05_streams.md
index 0cfc74e..c426272 100644
--- a/_source/handbook/05_streams.md
+++ b/_source/handbook/05_streams.md
@@ -38,6 +38,13 @@ A Turbo Streams message is a fragment of HTML consisting of `<turbo-stream>` ele
   </template>
 </turbo-stream>
 
+<turbo-stream action="replace" method="morph" target="current_step">
+  <template>
+    <!-- The contents of this template will replace the element with ID "current_step" via morph. -->
+    <li>New item</li>
+  </template>
+</turbo-stream>
+
 <turbo-stream action="update" target="unread_count">
   <template>
     <!-- The contents of this template will replace the
@@ -52,6 +59,13 @@ A Turbo Streams message is a fragment of HTML consisting of `<turbo-stream>` ele
   </template>
 </turbo-stream>
 
+<turbo-stream action="update" method="morph" target="current_step">
+  <template>
+    <!-- The contents of this template will replace the children of the element with ID "current_step" via morph. -->
+    <li>New item</li>
+  </template>
+</turbo-stream>
+
 <turbo-stream action="remove" target="message_1">
   <!-- The element with DOM ID "message_1" will be removed.
   The contents of this stream element are ignored. -->
@@ -73,22 +87,6 @@ A Turbo Streams message is a fragment of HTML consisting of `<turbo-stream>` ele
   </template>
 </turbo-stream>
 
-<turbo-stream action="morph" target="current_step">
-  <template>
-    <!-- The contents of this template will replace the 
-    element with ID "current_step" via morph. -->
-    <li>New item</li>
-  </template>
-</turbo-stream>
-
-<turbo-stream action="morph" target="current_step" children-only>
-  <template>
-    <!-- The contents of this template will replace the 
-    children of the element with ID "current_step" via morph. -->
-    <li>New item</li>
-  </template>
-</turbo-stream>
-
 <turbo-stream action="refresh" request-id="abcd-1234"></turbo-stream>
 ```
 
diff --git a/_source/reference/streams.md b/_source/reference/streams.md
index b065a2b..f8aabda 100644
--- a/_source/reference/streams.md
+++ b/_source/reference/streams.md
@@ -46,6 +46,16 @@ Replaces the element designated by the target dom id.
 </turbo-stream>
 ```
 
+The `[method="morph"]` attribute can be added to the `turbo-stream` element to replace the element designated by the target dom id via morph.
+
+```html
+<turbo-stream action="replace" method="morph" target="dom_id">
+  <template>
+    Content to replace the element.
+  </template>
+</turbo-stream>
+```
+
 ### Update
 
 Updates the content within the template tag to the container designated by the target dom id.
@@ -58,6 +68,16 @@ Updates the content within the template tag to the container designated by the t
 </turbo-stream>
 ```
 
+The `[method="morph"]` attribute can be added to the `turbo-stream` element to morph only the children of the element designated by the target dom id.
+
+```html
+<turbo-stream action="update" method="morph" target="dom_id">
+  <template>
+    Content to replace the element.
+  </template>
+</turbo-stream>
+```
+
 ### Remove
 
 Removes the element designated by the target dom id.
@@ -91,28 +111,6 @@ Inserts the content within the template tag after the element designated by the
 </turbo-stream>
 ```
 
-### Morph
-
-Replaces the element designated by the target dom id via morph.
-
-```html
-<turbo-stream action="morph" target="dom_id">
-  <template>
-    Content to replace the element.
-  </template>
-</turbo-stream>
-```
-
-The `children-only` attribute can be added to the `turbo-stream` element to morph only the children of the element designated by the target dom id.
-
-```html
-<turbo-stream action="morph" target="dom_id" children-only>
-  <template>
-    Content to replace the element.
-  </template>
-</turbo-stream>
-```
-
 ### Refresh
 
 Initiates a [Page Refresh](/handbook/page_refreshes) to render new content with