Introduce turbo:before-permanent-element-render

While transposing a [permanent element][] from page to page, dispatch a
`turbo:before-permanent-element-render` event on the document with a
`(currentPermanentElement: Element, newPermanentElement: Element) =>
void` available as the event's `detail.render` property.

The `turbo:before-permanent-element-render` is named to follow the
pattern established by its predecessors (`turbo:before-render`,
`turbo:before-frame-render`, `turbo:before-stream-render`), and its
`CustomEvent.detail.render` property name mirrors the
`turbo:before-render` event's `CustomEvent.detail.render` property.

This opportunity to modify a permanent element might be useful if it's
possible for the preserved element to become partially stale. For
example, consider an invalid `<form>` submission with an `<input
type="file">`.

Since the server's response cannot fully encode the submitted file into
the response's element, it might be a useful to mark it with
`[data-turbo-permanent]` to preserve whatever client-side state precedes
the submission:

```html
<label for="profile_image">Profile image</label>
<input id="profile_image" type="file" data-turbo-permanent>
```

Suppose the uploaded file is too large, or doesn't match the server's
expectations for file type. The server's response might contain
a fragment like:

```html
<label for="profile_image">Profile image</label>
<input id="profile_image" type="file" data-turbo-permanent
       class="invalid" aria-describedby="profile_image_error">
<p id="profile_image_error">Profile image is too large (5GB). Try a smaller file (<5KB)</p>
```

Prior to this change, the fact that the `<input>` is marked with
`[data-turbo-permanent]` would ignore the `[class]` and
`[aria-describedby]` attributes from the response, and the `<input>`
would remain unchanged (with the attached file still in-memory).

With a new `turbo:before-permanent-element-render` available, there's an
opportunity to do application-specific merging:

```js
addEventListener("turbo:before-permanent-element-render", ({ target, { detail } }) => {
  detail.render = (currentElement, newElement) => {
    currentElement.setAttribute("class", newElement.getAttribute("class"))
    currentElement.setAttribute("aria-describedby", newElement.getAttribute("aria-describedby"))
  }
})
```

[permanent element]: https://turbo.hotwired.dev/handbook/building#persisting-elements-across-page-loads

src/core/bardo.ts

@@ -1,4 +1,6 @@
 import { PermanentElementMap } from "./snapshot"
+import { TurboBeforePermanentElementRenderEvent } from "./session"
+import { dispatch } from "../util"
 
 export interface BardoDelegate {
   enteringBardo(currentPermanentElement: Element, newPermanentElement: Element): void
@@ -20,6 +22,11 @@ export class Bardo {
     bardo.leave()
   }
 
+  static renderElement(permanentElement: Element, _newElement: Element) {
+    const clone = permanentElement.cloneNode(true)
+    permanentElement.replaceWith(clone)
+  }
+
   constructor(delegate: BardoDelegate, permanentElementMap: PermanentElementMap) {
     this.delegate = delegate
     this.permanentElementMap = permanentElementMap
@@ -35,8 +42,14 @@ export class Bardo {
 
   leave() {
     for (const id in this.permanentElementMap) {
-      const [currentPermanentElement] = this.permanentElementMap[id]
-      this.replaceCurrentPermanentElementWithClone(currentPermanentElement)
+      const [currentPermanentElement, newPermanentElement] = this.permanentElementMap[id]
+      const {
+        detail: { render },
+      } = dispatch<TurboBeforePermanentElementRenderEvent>("turbo:before-permanent-element-render", {
+        detail: { render: Bardo.renderElement },
+      })
+
+      render(currentPermanentElement, newPermanentElement)
       this.replacePlaceholderWithPermanentElement(currentPermanentElement)
       this.delegate.leavingBardo(currentPermanentElement)
     }
@@ -47,11 +60,6 @@ export class Bardo {
     permanentElement.replaceWith(placeholder)
   }
 
-  replaceCurrentPermanentElementWithClone(permanentElement: Element) {
-    const clone = permanentElement.cloneNode(true)
-    permanentElement.replaceWith(clone)
-  }
-
   replacePlaceholderWithPermanentElement(permanentElement: Element) {
     const placeholder = this.getPlaceholderById(permanentElement.id)
     placeholder?.replaceWith(permanentElement)

src/core/renderer.ts

@@ -59,9 +59,7 @@ export abstract class Renderer<E extends Element, S extends Snapshot<E> = Snapsh
   // Bardo delegate
 
   enteringBardo(currentPermanentElement: Element) {
-    if (this.activeElement) return
-
-    if (currentPermanentElement.contains(this.currentSnapshot.activeElement)) {
+    if (this.activeElement == null && currentPermanentElement.contains(this.currentSnapshot.activeElement)) {
       this.activeElement = this.currentSnapshot.activeElement
     }
   }

src/core/session.ts

@@ -22,11 +22,13 @@ import { FrameElement } from "../elements/frame_element"
 import { FrameViewRenderOptions } from "./frames/frame_view"
 import { FetchResponse } from "../http/fetch_response"
 import { Preloader, PreloaderDelegate } from "./drive/preloader"
+import { Render } from "./renderer"
 
 export type FormMode = "on" | "off" | "optin"
 export type TimingData = unknown
 export type TurboBeforeCacheEvent = CustomEvent
 export type TurboBeforeRenderEvent = CustomEvent<{ newBody: HTMLBodyElement } & PageViewRenderOptions>
+export type TurboBeforePermanentElementRenderEvent = CustomEvent<{ render: Render<Element> }>
 export type TurboBeforeVisitEvent = CustomEvent<{ url: string }>
 export type TurboClickEvent = CustomEvent<{ url: string; originalEvent: MouseEvent }>
 export type TurboFrameLoadEvent = CustomEvent

src/tests/fixtures/permanent_element.html

@@ -10,7 +10,7 @@
     <section>
       <h1>Permanent element</h1>
     </section>
-    <div id="permanent" data-turbo-permanent>Permanent element</div>
+    <div id="permanent" class="loaded" data-turbo-permanent>Permanent element</div>
 
     <turbo-frame id="frame">
       <div id="permanent-in-frame" data-turbo-permanent>Permanent element</div>

src/tests/fixtures/rendering.html

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html>
+<html data-skip-event-details="turbo:before-permanent-element-render">
   <head>
     <meta charset="utf-8">
     <title>Turbo</title>

src/tests/fixtures/test.js

@@ -50,6 +50,7 @@
   "turbo:before-stream-render",
   "turbo:before-cache",
   "turbo:before-render",
+  "turbo:before-permanent-element-render",
   "turbo:before-visit",
   "turbo:load",
   "turbo:render",

src/tests/functional/rendering_tests.ts

@@ -299,15 +299,43 @@ test("test does not evaluate data-turbo-eval=false scripts", async ({ page }) =>
 test("test preserves permanent elements", async ({ page }) => {
   const permanentElement = await page.locator("#permanent")
   assert.equal(await permanentElement.textContent(), "Rendering")
+  assert.equal(await permanentElement.getAttribute("class"), null)
 
   await page.click("#permanent-element-link")
   await nextEventNamed(page, "turbo:render")
   assert.ok(await strictElementEquals(permanentElement, await page.locator("#permanent")))
   assert.equal(await permanentElement!.textContent(), "Rendering")
+  assert.equal(await permanentElement.getAttribute("class"), null)
 
   await page.goBack()
   await nextEventNamed(page, "turbo:render")
   assert.ok(await strictElementEquals(permanentElement, await page.locator("#permanent")))
+  assert.equal(await permanentElement.getAttribute("class"), null)
+})
+
+test("test dispatches a turbo:before-permanent-element-render event while preserving permanent elements", async ({
+  page,
+}) => {
+  const permanentElement = await page.locator("#permanent")
+  await page.evaluate(() => {
+    addEventListener("turbo:before-permanent-element-render", (event) => {
+      const { detail } = event as CustomEvent<{ render: (c: Element, n: Element) => void }>
+      detail.render = (currentElement, newElement) => {
+        const newClassList = newElement.getAttribute("class") || ""
+
+        currentElement.setAttribute("class", newClassList)
+      }
+    })
+  })
+
+  assert.equal(await page.textContent("#permanent"), "Rendering")
+  assert.equal(await permanentElement.getAttribute("class"), null)
+
+  await page.click("#permanent-element-link")
+  await nextEventNamed(page, "turbo:before-permanent-element-render")
+
+  assert.equal(await page.textContent("#permanent"), "Rendering")
+  assert.equal(await permanentElement.getAttribute("class"), "loaded")
 })
 
 test("test restores focus during page rendering when transposing the activeElement", async ({ page }) => {