Introduce refresh visit action and method to refresh the current page

[pfeiffer]

Related issues:

• Turbo visit with replace action flashes elements turbo-ios#136 (comment)
• Turbo 8 morphing refreshes not supported? turbo-ios#175
• Detecting if turbo:load event was caused by a refresh #1150

This PR adds a refresh visit action and changes Session#refresh to use the current URL if not provided explicitly.

Add refresh visit action

The motivation behind it is to support more granular behavior when doing refreshes. Today, a 'refresh' is essentially a replace action to the current URL. There's no easy way to know if this action was triggered by a user interaction or by a turbo stream refresh. By adding a granular refresh action, developers can handle refreshes (eg. broadcasted as streams) differently from replace actions (form submissions, drive navigations, ..).

An example of this would be in Turbo iOS, where there's no way to differentiate between a user-triggered replace action (ie. pull-to-refresh) or a programatically triggered refresh (ie. broadcasts) (see eg. Turbo iOS #136 and Turbo iOS #175).

With this change, developers (and library maintainers of eg. Turbo iOS) would able to differentiate between replace actions and refresh actions and handle eg. showing loading indicator behavior differently. As an example we'd like show a more subtle loading indicator on refresh actions than on replace actions.

Make Session#refresh refresh current page unless specified

Secondly, the Turbo.session.refresh(..) method is updated to use the current URL of the page. This allows developers to programatically refresh the current page simply by calling Turbo.session.refresh() without having to explicitly provide the current page's URL.

A common use-case could be refreshing (and morphing) a page when it becomes re-focused as a tab, to always ensure that the content is up to date:

addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible") {
    Turbo.session.refresh()
  }
})

I think this would also be usable for Turbo iOS and Turbo Android apps with multiple sessions, where other sessions could be refreshed instead of reloaded when a mutating request has been made in a single session. See: hotwired/turbo-ios#150

[pfeiffer]

Just noticed that there's a slightly similar PR approach-wise in #1145 although that PR deals with a different issue (navigating to another URL than the current page with morphing). I think the two are unrelated in that this PR explicitly not allows morphing between two different path names.

[pfeiffer]

I think the refresh action should be reserved for internal use, just as the restore action is.

[pfeiffer]

Closing as morphing has landed in Turbo Native without this 🎉

[tylerklose]

@pfeiffer any idea what the best upgrade path is?

For example, if I publish a new version of iOS with the updated Turbo Native, there will be some users with the change and others without the change.

I probably wouldn't want users on the older version of the app to see the previous behavior

[pfeiffer]

The Turbo Native adapters are compatible with both Turbolinks and Turbo 8.

Your users using an older version of the app would still be able to do that; they would not get the benefit of refreshes though. You could conditionally subscribe to broadcasts on your website, so that users of older app versions without morph support, would not receive any broadcasted refreshes.