From 8f01b48fa20322cb77c1db2ecd786be2c1026fce Mon Sep 17 00:00:00 2001
From: Sean Doyle <sean.p.doyle24@gmail.com>
Date: Tue, 9 Nov 2021 10:23:17 -0500
Subject: [PATCH] Document Frame Visit Actions

Document the changes proposed in [hotwired/turbo#398][].

[hotwired/turbo#398]: https://github.com/hotwired/turbo/pull/398
---
 _source/handbook/03_frames.md | 37 +++++++++++++++++++++++++++++++++++
 _source/reference/frames.md   |  9 +++++++++
 2 files changed, 46 insertions(+)

diff --git a/_source/handbook/03_frames.md b/_source/handbook/03_frames.md
index 6b237c1..5aa7c5c 100644
--- a/_source/handbook/03_frames.md
+++ b/_source/handbook/03_frames.md
@@ -165,3 +165,40 @@ Sometimes you want most links to operate within the frame context, but not other
   </form>
 </body>
 ```
+
+## Promoting a Frame Navigation to a Page Visit
+
+Navigating Frames provides applications with an opportunity to change part of
+the page's contents while preserving the rest of the document's state (for
+example, its current scroll position or focused element). There are times when
+we want changes to a Frame to also affect the browser's [history][].
+
+To promote a Frame navigation to a Visit, render the element with the
+`[data-turbo-action]` attribute. The attribute supports all [Visit][] values,
+and can be declared on:
+
+* the `<turbo-frame>` element
+* any `<a>` elements that navigate the `<turbo-frame>`
+* any `<form>` elements that navigate the `<turbo-frame>`
+* any `<input type="submit">` or `<button>` elements contained within `<form>`
+  elements that navigate the `<turbo-frame>`
+
+For example, consider a Frame that renders a paginated list of articles and
+transforms navigations into ["advance" Actions][advance]:
+
+```html
+<turbo-frame data-turbo-action="advance">
+  <a href="/articles?page=2" rel="next">Next page</a>
+</turbo-frame>
+```
+
+Clicking the `<a rel="next">` element will set _both_ the `<turbo-frame>`
+element's `[src]` attribute _and_ the browser's path to `/articles?page=2`.
+
+**Note:** when render the page after refreshing the browser, it is _the
+application's_ responsibility to render the _second_ page of articles along with
+any other state derived from the URL path and search parameters.
+
+[history]: https://developer.mozilla.org/en-US/docs/Web/API/History
+[Visit]: /handbook/drive#page-navigation-basics
+[advance]: /handbook/drive#application-visits
diff --git a/_source/reference/frames.md b/_source/reference/frames.md
index 31305f9..8de22d0 100644
--- a/_source/reference/frames.md
+++ b/_source/reference/frames.md
@@ -78,6 +78,15 @@ Like an eager-loaded frame, but the content is not loaded from `src` until the f
 </turbo-frame>
 ```
 
+## Frame that promotes navigations to Visits
+
+```html
+<turbo-frame id="messages" data-turbo-action="advance">
+  <a href="/messages?page=2">Advance history to next page</a>
+  <a href="/messages?page=2" data-turbo-action="replace">Replace history with next page</a>
+</turbo-frame>
+```
+
 # Attributes, properties, and functions
 
 The `<turbo-frame>` element is a [custom element][] with its own set of HTML