Restore focus when transposing Permanent Elements

[seanpdoyle]

Problem

When an interactive element like an <input>, <select>, <textarea>,
or <button> has an [id] attribute and is marked as
[data-turbo-permanent], the element and its internal state is
preserved except for its focus state.

Imagine a search form:

<form>
  <label for="search">Search</label>
  <input type="search" id="search" name="q" data-turbo-permanent>
</form>

When typing a query into the box and submitting the <form> by
enter, the request is submitted, the page transitions, the
element retains its [value] attribute, but focus is lost.

Solution

When transposing a permanent element during a Renderer descendant's
(e.g. PageRenderer, ErrorRenderer, or FrameRenderer) render cycle,
capture the document.activeElement.

Once the permanent element is inserted into the new page, use that
retained reference to re-focus the element.

[seanpdoyle]

As an alternative to handling this internally, Turbo could dispatch a new turbo:before-permanent-element-render event with target referencing the current element in the DOM, event.detail.newElement referencing the element in the response, and a render(currentPermanentElement: Element, newPermanentElement: Element) function that substitutes the two.

That way, if they want to do any attribute merging, they have an opportunity to do so based off target and event.detail.newElement alone:

addEventListener("turbo:before-permanent-element-render", ({ target, detail: { newElement } }) => {
  const validationMessageId = newElement.getAttribute("aria-describedby")

  if (validationMessageId) target.setAttribute("aria-describedby", validationMessageId)
})

If they want to preserve focus or anything else, they can assign their own render to event.detail.render:

addEventListener("turbo:before-permanent-element-render", (event) => {
  const { detail: { render } } = event
  
  event.render = (currentElement, newElement) => {
    const activeElement = currentElement.contains(document.activeElement) ? 
      document.activeElement :
      null
    
      render(currentElement, newElement)

      activeElement?.focus()
  }
})

[seanpdoyle]

@dhh this is ready for review.

[dhh]

Really clever, @seanpdoyle. I like it.

[seanpdoyle]

I've opened #622 as a follow-up to this change. It leverages the BardoDelegate.enteringBardo hook to dispatch a new Turbo Event to provide applications with a chance to merge new attributes into the permanent element.