Document <turbo-stream action="refresh">

Related to [hotwired/turbo#1193][]

Replace all mentions of "the seven" actions with "the eight". In
addition, include examples of `<turbo-stream action="refresh">`
elements.

[hotwired/turbo#1193]: hotwired/turbo#1193

_source/handbook/01_introduction.md

@@ -66,7 +66,7 @@ In addition to turning your segments into independent contexts, Turbo Frames aff
 
 Making partial page changes in response to asynchronous actions is how we make the application feel alive. While Turbo Frames give us such updates in response to direct interactions within a single frame, Turbo Streams let us change any part of the page in response to updates sent over a WebSocket connection, SSE or other transport. (Think an <a href="http://itsnotatypo.com">imbox</a> that automatically updates when a new email arrives.)
 
-Turbo Streams introduces a `<turbo-stream>` element with seven basic actions: `append`, `prepend`, `replace`, `update`, `remove`, `before`, and `after`. With these actions, along with the `target` attribute specifying the ID of the element you want to operate on, you can encode all the mutations needed to refresh the page. You can even combine several stream elements in a single stream message. Simply include the HTML you're interested in inserting or replacing in a <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template">template tag</a> and Turbo does the rest:
+Turbo Streams introduces a `<turbo-stream>` element with eight basic actions: `append`, `prepend`, `replace`, `update`, `remove`, `before`, `after`, and `refresh`. With these actions, along with the `target` attribute specifying the ID of the element you want to operate on, you can encode all the mutations needed to refresh the page. You can even combine several stream elements in a single stream message. Simply include the HTML you're interested in inserting or replacing in a <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template">template tag</a> and Turbo does the rest:
 
 ```html
 <turbo-stream action="append" target="messages">
@@ -111,4 +111,3 @@ See the <a href="https://github.com/hotwired/turbo-ios">Turbo Native: iOS</a> an
 ## Integrate with backend frameworks
 
 You don't need any backend framework to use Turbo. All the features are built to be used directly, without further abstractions. But if you have the opportunity to use a backend framework that's integrated with Turbo, you'll find life a lot simpler. [We've created a reference implementation for such an integration for Ruby on Rails](https://github.com/hotwired/turbo-rails).
-

_source/handbook/05_streams.md

@@ -9,7 +9,7 @@ Turbo Streams deliver page changes as fragments of HTML wrapped in self-executin
 
 ## Stream Messages and Actions
 
-A Turbo Streams message is a fragment of HTML consisting of `<turbo-stream>` elements. The stream message below demonstrates the seven possible stream actions:
+A Turbo Streams message is a fragment of HTML consisting of `<turbo-stream>` elements. The stream message below demonstrates the eight possible stream actions:
 
 ```html
 <turbo-stream action="append" target="messages">
@@ -70,6 +70,8 @@ A Turbo Streams message is a fragment of HTML consisting of `<turbo-stream>` ele
     <li>New item</li>
   </template>
 </turbo-stream>
+
+<turbo-stream action="refresh" request-id="abcd-1234"></turbo-stream>
 ```
 
 Note that every `<turbo-stream>` element must wrap its included HTML inside a `<template>` element.
@@ -186,15 +188,15 @@ The same is especially true for WebSocket updates. On poor connections, or if th
 
 ## But What About Running JavaScript?
 
-Turbo Streams consciously restricts you to seven actions: append, prepend, (insert) before, (insert) after, replace, update, and remove. If you want to trigger additional behavior when these actions are carried out, you should attach behavior using <a href="https://stimulus.hotwired.dev">Stimulus</a> controllers. This restriction allows Turbo Streams to focus on the essential task of delivering HTML over the wire, leaving additional logic to live in dedicated JavaScript files.
+Turbo Streams consciously restricts you to eight actions: append, prepend, (insert) before, (insert) after, replace, update, remove, and refresh. If you want to trigger additional behavior when these actions are carried out, you should attach behavior using <a href="https://stimulus.hotwired.dev">Stimulus</a> controllers. This restriction allows Turbo Streams to focus on the essential task of delivering HTML over the wire, leaving additional logic to live in dedicated JavaScript files.
 
 Embracing these constraints will keep you from turning individual responses into a jumble of behaviors that cannot be reused and which make the app hard to follow. The key benefit from Turbo Streams is the ability to reuse templates for initial rendering of a page through all subsequent updates.
 
 ## Custom Actions
 
-By default, Turbo Streams support [seven values for its `action` attribute](/reference/streams#the-seven-actions). If your application needs to support other behaviors, you can override the `event.detail.render` function.
+By default, Turbo Streams support [eight values for its `action` attribute](/reference/streams#the-seven-actions). If your application needs to support other behaviors, you can override the `event.detail.render` function.
 
-For example, if you'd like to expand upon the seven actions to support `<turbo-stream>` elements with `[action="alert"]` or `[action="log"]`, you could declare a `turbo:before-stream-render` listener to provide custom behavior:
+For example, if you'd like to expand upon the eight actions to support `<turbo-stream>` elements with `[action="alert"]` or `[action="log"]`, you could declare a `turbo:before-stream-render` listener to provide custom behavior:
 
 ```javascript
 addEventListener("turbo:before-stream-render", ((event) => {

_source/reference/streams.md

@@ -6,7 +6,7 @@ description: "A reference of everything you can do with Turbo Streams."
 
 # Streams
 
-## The seven actions
+## The eight actions
 
 ### Append
 
@@ -19,7 +19,7 @@ Appends the content within the template tag to the container designated by the t
   </template>
 </turbo-stream>
 ```
-If the template's first element has an id that is already used by a direct child inside the container targeted by dom_id, it is replaced instead of appended. 
+If the template's first element has an id that is already used by a direct child inside the container targeted by dom_id, it is replaced instead of appended.
 
 ### Prepend
 
@@ -32,7 +32,7 @@ Prepends the content within the template tag to the container designated by the
   </template>
 </turbo-stream>
 ```
-If the template's first element has an id that is already used by a direct child inside the container targeted by dom_id, it is replaced instead of prepended. 
+If the template's first element has an id that is already used by a direct child inside the container targeted by dom_id, it is replaced instead of prepended.
 
 ### Replace
 
@@ -91,6 +91,19 @@ Inserts the content within the template tag after the element designated by the
 </turbo-stream>
 ```
 
+### Refresh
+
+Initiates a [Page Refresh](/handbook/page_refreshes) to render new content with
+morphing.
+
+```html
+<!-- without `[request-id]` -->
+<turbo-stream action="refresh"></turbo-stream>
+
+<!-- debounced with `[request-id]` -->
+<turbo-stream action="refresh" request-id="abcd-1234"></turbo-stream>
+```
+
 ## Targeting Multiple Elements
 
 To target multiple elements with a single action, use the `targets` attribute with a CSS query selector instead of the `target` attribute.