Add accessibility note about dismissible alerts and focus (#31358)

diff --git a/site/content/docs/5.0/components/alerts.md b/site/content/docs/5.0/components/alerts.md
index a2fb75b917ee248874ef4eaf766b8a42e4c2e342..dace2f718128dd55e85e86b03939b34cbbfe7610 100644 (file)
--- a/site/content/docs/5.0/components/alerts.md
+++ b/site/content/docs/5.0/components/alerts.md
@@ -52,7 +52,6 @@ Alerts can also contain additional HTML elements like headings, paragraphs and d
 </div>
 {{< /example >}}
 
-
 ### Dismissing
 
 Using the alert JavaScript plugin, it's possible to dismiss any alert inline. Here's how:
@@ -73,6 +72,10 @@ You can see this in action with a live demo:
 </div>
 {{< /example >}}
 
+{{< callout warning >}}
+When an alert is dismissed, the element is completely removed from the page structure. If a keyboard user dismisses the alert using the close button, their focus will suddenly be lost and, depending on the browser, reset to the start of the page/document. For this reason, we recommend including additional JavaScript that listens for the `closed.bs.alert` event and programmatically sets `focus()` to the most appropriate location in the page. If you're planning to move focus to a non-interactive element that normally does not receive focus, make sure to add `tabindex="-1"` to the element.
+{{< /callout >}}
+
 ## JavaScript behavior
 
 ### Triggers
@@ -178,6 +181,8 @@ Bootstrap's alert plugin exposes a few events for hooking into alert functionali
 {{< highlight js >}}
 var myAlert = document.getElementById('myAlert')
 myAlert.addEventListener('closed.bs.alert', function () {
-  // do something…
+  // do something … for instance, explicitly move focus to the most appropriate element,
+  // so it doesn't get lost/reset to the start of the page
+  // document.getElementById('…').focus()
 })
 {{< /highlight >}}