Allow links & visits to specify their view transition direction, and apply it appropriately when navigating the history stack

A link may now set a  attribute with forward or backward to specify the direction of its view transition. When using Turbo.visit, this behavior is controller by the existing  option.

Author: jbarrieault

src/core/drive/history.js

@@ -87,8 +87,13 @@ export class History {
         this.location = new URL(window.location.href)
         const { restorationIdentifier, restorationIndex } = turbo
         this.restorationIdentifier = restorationIdentifier
-        const direction = restorationIndex > this.currentIndex ? "forward" : "back"
-        this.delegate.historyPoppedToLocationWithRestorationIdentifierAndDirection(this.location, restorationIdentifier, direction)
+        const direction = this.restorationVisitDirection(restorationIdentifier, restorationIndex)
+
+        this.delegate.historyPoppedToLocationWithRestorationIdentifierAndDirection(
+          this.location,
+          restorationIdentifier,
+          direction
+        )
         this.currentIndex = restorationIndex
       }
     }
@@ -109,4 +114,16 @@ export class History {
   pageIsLoaded() {
     return this.pageLoaded || document.readyState == "complete"
   }
+
+  restorationVisitDirection(restorationIdentifier, restorationIndex) {
+    const historyDirection = restorationIndex > this.currentIndex ? "forward" : "back"
+    const originalVisitDirection =
+      this.restorationData[restorationIdentifier]?.direction === "back" ? "back" : "forward"
+
+    return historyDirection === "forward" ? originalVisitDirection : this.oppositeDirection(originalVisitDirection)
+  }
+
+  oppositeDirection(direction) {
+    return direction === "forward" ? "back" : "forward"
+  }
 }

src/core/index.js

@@ -34,6 +34,8 @@ export function registerAdapter(adapter) {
  * @param options Options to apply
  * @param options.action Type of history navigation to apply ("restore",
  * "replace" or "advance")
+ * @param options.direction Logical direction of the navigation, applies to
+ * view transitions ("forward", "back")
  * @param options.historyChanged Specifies whether the browser history has
  * already been changed for this visit or not
  * @param options.referrer Specifies the referrer of this visit such that

src/core/session.js

@@ -95,6 +95,10 @@ export class Session {
   visit(location, options = {}) {
     const frameElement = options.frame ? document.getElementById(options.frame) : null
 
+    if (["forward", "back"].includes(options.direction)) {
+      this.history.updateRestorationData({ direction: options.direction })
+    }
+
     if (frameElement instanceof FrameElement) {
       const action = options.action || getVisitAction(frameElement)
 
@@ -250,8 +254,9 @@ export class Session {
   followedLinkToLocation(link, location) {
     const action = this.getActionForLink(link)
     const acceptsStreamResponse = link.hasAttribute("data-turbo-stream")
+    const direction = link.getAttribute("data-turbo-visit-direction")
 
-    this.visit(location.href, { action, acceptsStreamResponse })
+    this.visit(location.href, { action, acceptsStreamResponse, direction })
   }
 
   // Navigator delegate