From 4a13b6d993346df6aadf5b6b24ec3b506908a04f Mon Sep 17 00:00:00 2001
From: Sean Doyle <seanpdoyle@users.noreply.github.com>
Date: Thu, 11 Nov 2021 10:05:08 -0500
Subject: [PATCH] Toggle `[aria-busy="true"]` during requests (#199)

Toggle the `[aria-busy="true"]` attribute to be present on a
`<turbo-frame>` element when its navigating, a `<form>` element when
it's submitting, or on the `<html>` element during any request, then
remove the attribute after the submission or navigation completes.

This is a change from the `turbo-frame[busy]` attribute, but aims to
achieve the same purpose. For the sake of backwards compatibility, Turbo
will continue to toggle the `[busy]` attribute during Frame navigations.

By unifying a single, consistent attribute, consumer applications can
use a single attribute CSS selector at different depths within their
page to hide or show loading indicators.

For example, consider a loading indication spinner animation within a
submit button that animates while a submission is in progress:

```html
<style>
  .loading-spinner                      { display: none; }
  [aria-busy="true"] .loading-spinner   { display: block; }
</style>

<form action="/posts">
  <!-- ... -->
  <button type="submit">
    <span class="loading-spinner>...</span>
    <span>Create Post</span>
  </button>
</form>
```

Similarly, consider a `turbo-frame` scoped loading bar:

```html
<style>
  .loading-bar                          { display: none; }
  [aria-busy="true"] .loading-bar       { display: block; }
</style>
<a href="/content" data-turbo-frame="content">...</a>
<turbo-frame id="content">
  <progress id="content-loading-bar" class="loading-bar" value="0" data-turbo-permanent></progress>

  <!-- ... -->
</turbo-frame>
```

Finally, consider the same `.loading-bar` for page-wide navigation:

```html
<style>
  .loading-bar                          { display: none; }
  [aria-busy="true"] .loading-bar       { display: block; }
</style>

<nav>
  <progress id="loading-bar" class="loading-bar" value="0" data-turbo-permanent></progress>
</nav>

<!-- ... -->

<a href="/posts/1">...</a>
```
---
 src/core/frames/frame_controller.ts           | 16 +++++++---------
 src/core/session.ts                           |  4 +++-
 src/tests/fixtures/form.html                  |  2 +-
 src/tests/fixtures/frames.html                |  2 +-
 src/tests/fixtures/navigation.html            |  2 +-
 src/tests/functional/form_submission_tests.ts | 12 ++++++++++--
 src/tests/functional/frame_tests.ts           |  8 ++++++--
 src/tests/functional/navigation_tests.ts      |  2 ++
 src/util.ts                                   | 15 +++++++++++++++
 9 files changed, 46 insertions(+), 17 deletions(-)
diff --git a/src/core/frames/frame_controller.ts b/src/core/frames/frame_controller.ts
index 705e46640..e3c78ee95 100644
--- a/src/core/frames/frame_controller.ts
+++ b/src/core/frames/frame_controller.ts
@@ -2,7 +2,7 @@ import { FrameElement, FrameElementDelegate, FrameLoadingStyle } from "../../ele
 import { FetchMethod, FetchRequest, FetchRequestDelegate, FetchRequestHeaders } from "../../http/fetch_request"
 import { FetchResponse } from "../../http/fetch_response"
 import { AppearanceObserver, AppearanceObserverDelegate } from "../../observers/appearance_observer"
-import { getAttribute, parseHTMLDocument } from "../../util"
+import { clearBusyState, getAttribute, parseHTMLDocument, markAsBusy } from "../../util"
 import { FormSubmission, FormSubmissionDelegate } from "../drive/form_submission"
 import { Snapshot } from "../snapshot"
 import { ViewDelegate } from "../view"
@@ -165,7 +165,7 @@ export class FrameController implements AppearanceObserverDelegate, FetchRequest
   }
 
   requestStarted(request: FetchRequest) {
-    this.element.setAttribute("busy", "")
+    [ this.element, document.documentElement ].forEach(markAsBusy)
   }
 
   requestPreventedHandlingResponse(request: FetchRequest, response: FetchResponse) {
@@ -188,14 +188,13 @@ export class FrameController implements AppearanceObserverDelegate, FetchRequest
   }
 
   requestFinished(request: FetchRequest) {
-    this.element.removeAttribute("busy")
+    [ this.element, document.documentElement ].forEach(clearBusyState)
   }
 
   // Form submission delegate
 
-  formSubmissionStarted(formSubmission: FormSubmission) {
-    const frame = this.findFrameElement(formSubmission.formElement)
-    frame.setAttribute("busy", "")
+  formSubmissionStarted({ formElement }: FormSubmission) {
+    [ formElement, this.findFrameElement(formElement), document.documentElement ].forEach(markAsBusy)
   }
 
   formSubmissionSucceededWithResponse(formSubmission: FormSubmission, response: FetchResponse) {
@@ -214,9 +213,8 @@ export class FrameController implements AppearanceObserverDelegate, FetchRequest
     console.error(error)
   }
 
-  formSubmissionFinished(formSubmission: FormSubmission) {
-    const frame = this.findFrameElement(formSubmission.formElement)
-    frame.removeAttribute("busy")
+  formSubmissionFinished({ formElement }: FormSubmission) {
+    [ formElement, this.findFrameElement(formElement), document.documentElement ].forEach(clearBusyState)
   }
 
   // View delegate
diff --git a/src/core/session.ts b/src/core/session.ts
index 26ff0a2e2..064e809e6 100644
--- a/src/core/session.ts
+++ b/src/core/session.ts
@@ -12,7 +12,7 @@ import { ScrollObserver } from "../observers/scroll_observer"
 import { StreamMessage } from "./streams/stream_message"
 import { StreamObserver } from "../observers/stream_observer"
 import { Action, Position, StreamSource, isAction } from "./types"
-import { dispatch } from "../util"
+import { clearBusyState, dispatch, markAsBusy } from "../util"
 import { PageView, PageViewDelegate } from "./drive/page_view"
 import { Visit, VisitOptions } from "./drive/visit"
 import { PageSnapshot } from "./drive/page_snapshot"
@@ -285,6 +285,7 @@ export class Session implements FormSubmitObserverDelegate, HistoryDelegate, Lin
   }
 
   notifyApplicationAfterVisitingLocation(location: URL, action: Action) {
+    markAsBusy(document.documentElement)
     return dispatch("turbo:visit", { detail: { url: location.href, action } })
   }
 
@@ -301,6 +302,7 @@ export class Session implements FormSubmitObserverDelegate, HistoryDelegate, Lin
   }
 
   notifyApplicationAfterPageLoad(timing: TimingData = {}) {
+    clearBusyState(document.documentElement)
     return dispatch("turbo:load", { detail: { url: this.location.href, timing }})
   }
 
diff --git a/src/tests/fixtures/form.html b/src/tests/fixtures/form.html
index 9c871ca19..b40c2f310 100644
--- a/src/tests/fixtures/form.html
+++ b/src/tests/fixtures/form.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html>
+<html id="html">
   <head>
     <meta charset="utf-8">
     <title>Form</title>
diff --git a/src/tests/fixtures/frames.html b/src/tests/fixtures/frames.html
index 60d54f57e..acfc17257 100644
--- a/src/tests/fixtures/frames.html
+++ b/src/tests/fixtures/frames.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html>
+<html id="html">
   <head>
     <meta charset="utf-8">
     <title>Frame</title>
diff --git a/src/tests/fixtures/navigation.html b/src/tests/fixtures/navigation.html
index febd43614..2b97cb37c 100644
--- a/src/tests/fixtures/navigation.html
+++ b/src/tests/fixtures/navigation.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html>
+<html id="html">
   <head>
     <meta charset="utf-8">
     <title>Turbo</title>
diff --git a/src/tests/functional/form_submission_tests.ts b/src/tests/functional/form_submission_tests.ts
index 6723816cb..bdd1ac286 100644
--- a/src/tests/functional/form_submission_tests.ts
+++ b/src/tests/functional/form_submission_tests.ts
@@ -63,6 +63,8 @@ export class FormSubmissionTests extends TurboDriveTestCase {
     this.assert.equal(await this.pathname, "/src/tests/fixtures/form.html")
     this.assert.equal(await this.visitAction, "advance")
     this.assert.equal(await this.getSearchParam("greeting"), "Hello from a redirect")
+    this.assert.equal(await this.nextAttributeMutationNamed("html", "aria-busy"), "true", "sets [aria-busy] on the document element")
+    this.assert.equal(await this.nextAttributeMutationNamed("html", "aria-busy"), null, "removes [aria-busy] from the document element")
   }
 
   async "test standard POST form submission events"() {
@@ -431,23 +433,29 @@ export class FormSubmissionTests extends TurboDriveTestCase {
     this.assert.equal(await this.attributeForSelector("#frame", "src"), url.href, "redirects the target frame")
   }
 
-  async "test frame form submission toggles the ancestor frame's [busy] attribute"() {
+  async "test frame form submission toggles the ancestor frame's [aria-busy] attribute"() {
     await this.clickSelector("#frame form.redirect input[type=submit]")
     await this.nextBeat
 
     this.assert.equal(await this.nextAttributeMutationNamed("frame", "busy"), "", "sets [busy] on the #frame")
+    this.assert.equal(await this.nextAttributeMutationNamed("frame", "aria-busy"), "true", "sets [aria-busy] on the #frame")
+    this.assert.equal(await this.nextAttributeMutationNamed("html", "aria-busy"), "true", "sets [aria-busy] on the document element")
     this.assert.equal(await this.nextAttributeMutationNamed("frame", "busy"), null, "removes [busy] from the #frame")
+    this.assert.equal(await this.nextAttributeMutationNamed("frame", "aria-busy"), null, "removes [aria-busy] from the #frame")
+    this.assert.equal(await this.nextAttributeMutationNamed("html", "aria-busy"), null, "removes [aria-busy] from the document element")
   }
 
-  async "test frame form submission toggles the target frame's [busy] attribute"() {
+  async "test frame form submission toggles the target frame's [aria-busy] attribute"() {
     await this.clickSelector('#targets-frame form.frame [type="submit"]')
     await this.nextBeat
 
     this.assert.equal(await this.nextAttributeMutationNamed("frame", "busy"), "", "sets [busy] on the #frame")
+    this.assert.equal(await this.nextAttributeMutationNamed("frame", "aria-busy"), "true", "sets [aria-busy] on the #frame")
 
     const title = await this.querySelector("#frame h2")
     this.assert.equal(await title.getVisibleText(), "Frame: Loaded")
     this.assert.equal(await this.nextAttributeMutationNamed("frame", "busy"), null, "removes [busy] from the #frame")
+    this.assert.equal(await this.nextAttributeMutationNamed("frame", "aria-busy"), null, "removes [aria-busy] from the #frame")
   }
 
   async "test frame form submission with empty created response"() {
diff --git a/src/tests/functional/frame_tests.ts b/src/tests/functional/frame_tests.ts
index a91ea3673..0c7653bb8 100644
--- a/src/tests/functional/frame_tests.ts
+++ b/src/tests/functional/frame_tests.ts
@@ -26,11 +26,15 @@ export class FrameTests extends TurboDriveTestCase {
     this.assert.equal(otherEvents.length, 0, "no more events")
   }
 
-  async "test following a link driving a frame toggles the [busy] attribute"() {
+  async "test following a link driving a frame toggles the [aria-busy=true] attribute"() {
     await this.clickSelector("#hello a")
 
     this.assert.equal(await this.nextAttributeMutationNamed("frame", "busy"), "", "sets [busy] on the #frame")
-    this.assert.equal(await this.nextAttributeMutationNamed("frame", "busy"), null, "removes [busy] from the #frame")
+    this.assert.equal(await this.nextAttributeMutationNamed("frame", "aria-busy"), "true", "sets [aria-busy=true] on the #frame")
+    this.assert.equal(await this.nextAttributeMutationNamed("html", "aria-busy"), "true", "sets [aria-busy=true] on the document element")
+    this.assert.equal(await this.nextAttributeMutationNamed("frame", "busy"), null, "removes [busy] on the #frame")
+    this.assert.equal(await this.nextAttributeMutationNamed("frame", "aria-busy"), null, "removes [aria-busy] from the #frame")
+    this.assert.equal(await this.nextAttributeMutationNamed("html", "aria-busy"), null, "removes [aria-busy] from the document element")
   }
 
   async "test following a link to a page without a matching frame results in an empty frame"() {
diff --git a/src/tests/functional/navigation_tests.ts b/src/tests/functional/navigation_tests.ts
index 70cbfb79f..a02f64500 100644
--- a/src/tests/functional/navigation_tests.ts
+++ b/src/tests/functional/navigation_tests.ts
@@ -35,6 +35,8 @@ export class NavigationTests extends TurboDriveTestCase {
     await this.nextBody
     this.assert.equal(await this.pathname, "/src/tests/fixtures/one.html")
     this.assert.equal(await this.visitAction, "advance")
+    this.assert.equal(await this.nextAttributeMutationNamed("html", "aria-busy"), "true", "sets [aria-busy] on the document element")
+    this.assert.equal(await this.nextAttributeMutationNamed("html", "aria-busy"), null, "removes [aria-busy] from the document element")
   }
 
   async "test following a same-origin unannotated custom element link"() {
diff --git a/src/util.ts b/src/util.ts
index 5cef3785b..d6d00a8fd 100644
--- a/src/util.ts
+++ b/src/util.ts
@@ -63,3 +63,18 @@ export function getAttribute(attributeName: string, ...elements: (Element | unde
 
   return null
 }
+
+export function markAsBusy(element: Element) {
+  if (element.localName == "turbo-frame") {
+    element.setAttribute("busy", "")
+  }
+  element.setAttribute("aria-busy", "true")
+}
+
+export function clearBusyState(element: Element) {
+  if (element.localName == "turbo-frame") {
+    element.removeAttribute("busy")
+  }
+
+  element.removeAttribute("aria-busy")
+}
