[ci skip] Improve accessibility (rails#51499)

* Add label and accessible content

Having a select element without a label outside a form isn't
directly problematic, but the text Version is the label of the
select and should act as such.

Because the select element is set up to browse to a different page
which loses the current focus position, users must be instructed
about this context change. It would be much better to display this
content to everyone, but having this for screenreaders only is
better than not having it at all.

* Fix accessible text for voice commands

Using the title attribute means some screenreaders will not be able
to show the expanded accessible text at all, but using aria-label
loses the hover text currently available.

If the title attribute is still used, the accessible label should
start with the same content as the visible label. This is necessary
for most voice operated tooling which only match starting text.

Having "Return" as the start of the accessible label and "Guides"
as the start of the visible label means in most cases users that
rely on voice commands will not be able to browse here.

* Add utilities for screen readers

This enables hiding content visually whilst still enabling it for
assisistive technologies.

* Feature detection for JavaScript functionalities

* Add landmarks to all guide pages

Landmarks such as header, section, footer, article, and the main
content landmark help navigating when using assistive tooling.

Since each guide is a self-contained article, a header section
with the guide introduction and navigation, a footer section which
is not part of the content but a call to action, and the rest can
be clearly separated, landmarks here are appropiate.

* Make back-to-top work without JavaScript

By doing feature detection on animation timeline CSS, the graceful
degradation can take care of the visiblity of the back-to-top
button. In case no JavaScript is available, it should always be
shown.

* Enable back-to-top without JavaScript

And add an accessible label to the button. It would be better to
just show the text back to top underneath the arrow, but this
change is again better than not having it at all.

* Consistent scrolling behaviour respecting pref

Use the preference to detect if a user wants reduced motion and if
not enable smooth scrolling. This takes care of the back-to-top
smooth scrolling, and also adds it to anchor links. If this is
unwanted, the change can be reverted and a matchmedia check should
be done in JavaScript instead before smooth scrolling

* Add skip links to quickly navigate past navs

Skip links are a common practice to allow keyboard and other users
to skip past large blocks of content that are present on every
page, which in this case are the secondary navigation at the top,
the version selector, and the chapter navigation.

The skip links only show when focused.

* Wrap tables to make them responsive

* Make back-to-top link to skip link

This allow screen readers to announce something, because linking
to an empty fragment or the body element doesn't announce anything
usefull.

* Fix false positive for broken (skip) link anchor

* Add branded selectable color

Fixes selecting text in dark mode and brands it for both modes.

* Make more info and guides index accessible

* Adds aria-controls, which binds the control to the content.

* Adds aria-expanded, which signals the current expansion state.

* Adds focus handling, which focuses the first link or the button
  depending on the expansion state.

* Adds keyboard closing for the more info button.

* Adds outside click tracking to close the expanded content.

* Fixes the more info button to not be focusable.

* Fix CSS for more info button

* Fix dark mode for guide selector

* Add accessible label for guide navigator

* Only use nav on sub-column if it's actually a nav

On the index page the sub-column is not a navigational element and
does not contain content that needs to be skipped over. Therefore
it should not be a <nav> and not contain a skiplink. Furthermore,
the definition list doesn't contain any definitions, thus its role
should be removed.

* Ignore turbo for in-page skiplinks

This ensures the JavaScript doesn't overridde any screenreader
behaviour and the resulting fragment is correctly focused as
expected.

* Use keydown for escape detection

When an action should be perceived as fast, or no pause is required
before the interaction, keydown should be used and not keyup, which
can add (the feeling of a) significant delay.

* Fix heading levels

It is important that the heading structure (all hx elements) are
properly closed, and make sense. They can only ever increment by
1 since the previous heading (and decrement by many).

* Presentational picture needs aria-hidden="true"

The picture here adds a visual gimmic, but doesn't provide
information to the user and thus should be removed from the
accessibility tree.

* JS-enabled link-as-button should have correct role

When JavaScript is enabled, this link turns into a button that
expands an element. The change ensures that screenreaders only
announce it as such if JavaScript is enabled and applied.

* Accessible regions, focusable anchors, cleanup

Applied requested changes from review. See PR for discussion about
explicitly adding a role="region"

rails#51499

* Apply requested changes from review and re-apply after rebase

* Adapt the highlight in the navigation side column

for the new page structure. Additionally, replace the active class
with aria-current="true", which is meant to keep track of what is
currently active in a set. Finally, update the implementation of
the intersection observer to:

* not rely on the viewport height (-95%)
* not rely on fixing the highlighted item after click
* support both scrolling up and scrolling down
* support fast scrolling

* Apply review commentary

* Fix issues with scrolling behaviour

To "restore" the current behaviour on main, a solution was needed
for browser-OS combinations that do not allow for two concurrent
scrolling elements. Current code on main breaks completely when
using scroll-behaviour: smooth (in CSS), and breaks when scrolling
back-to-top from the bottom of the page (highlight no longer
correct).

This commit works around the limitation whilst also enabling the
non-smooth scrolled solution for those who want reduced motion.
Additionally it has a workaround for a bug on Android, and some
defaults for those without JavaScript enabled.

* Ensure chapters list is always scrolled after scroll-end

Co-authored-by: Rafael Mendonça França <[email protected]>

Author: SleeplessByte

guides/assets/javascripts/guides.js

@@ -3,7 +3,7 @@
 // ----------------------------------------------------------------------------
 //
 // @include-media does not handle prefers-color-scheme so we are declaring this
-// as an independent file with the overrides for dark mode. 
+// as an independent file with the overrides for dark mode.
 
 @media (prefers-color-scheme: dark) {
   body.guide {
@@ -15,17 +15,17 @@
       width: 12px;
       background-color: transparent;
     }
-    
+
     &::-webkit-scrollbar-track {
-        -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.3); 
+        -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.3);
         border-radius: 10px;
         background-color: $gray-900;
       }
-    
+
     &::-webkit-scrollbar-thumb {
       background-color: $gray-500;
         border-radius: 10px;
-        -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.5); 
+        -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.5);
     }
 
     h1, h2, h3 {
@@ -45,20 +45,24 @@
       } // &:visited
     } // a
 
+    a.skip-link {
+      background-color: $gray-900;
+    }
+
     h2 a, h3 a {
       &:link,
       &:visited {
         color: inherit;
-      } 
+      }
     } // h2 a
-    
+
     table {
       th {
         background-color: $gray-900;
         border-bottom: 2px solid $gray-700;
         color: $text-on-darker-bg;
       } // th
-  
+
       tr {
         &:nth-child(even) {
           background-color: $gray-900;
@@ -101,9 +105,10 @@
       color: #fff;
     }
 
-    nav#topNav {    background-color: $gray-900;
+    #mobile-navigation-bar {
+      background-color: $gray-900;
       color: $gray-400;
-  
+
 
       .more-info-links {
         background: $gray-1000;
@@ -112,22 +117,22 @@
       li {
         border-bottom: 1px solid $gray-800;
       } // li
-    } // nav#topNav
+    } // #mobile-navigation-bar
 
-    header#page_header {
-      nav#feature_nav {
+    header#page-header {
+      nav#feature-nav {
         .header-logo {
           a, a:link, a:visited {
             color: #fff;
           }
-          span#version_switcher {
+          span#version-switcher {
             color: $gray-400;
 
             select {
               background-color: $gray-900;
               color: $gray-400;
             } // select
-          } // span#version_switcher
+          } // span#version-switcher
         } // .header-logo
 
         ul.nav {
@@ -146,10 +151,19 @@
                 background-image: url("../images/icon_house-chimney-wht.svg");
               }
             } // @include media('>desktop')
+
+            &:last-child {
+              // the drop down
+
+              select {
+                background-color: $gray-900;
+                color: $gray-400;
+              } // select
+            }
           } // li
         } // ul.nav
-      } // nav#feature_nav
-    } // header#page_header
+      } // nav#feature-nav
+    } // header#page-header
 
     #guides {
       background: $gray-800;
@@ -179,43 +193,43 @@
         background-color: $gray-1000;
       }
 
-      #subCol {
-        background-color: $gray-900; 
+      #column-side {
+        background-color: $gray-900;
 
         ol.chapters {
           &::-webkit-scrollbar {
             background-color: $gray-800;
           }
-          
+
           &::-webkit-scrollbar-track {
             background-color: $gray-700;
             border-radius: 5px;
-            box-shadow: inset 0 0 6px rgba(0,0,0,0.3); 
+            box-shadow: inset 0 0 6px rgba(0,0,0,0.3);
           }
-          
+
           &::-webkit-scrollbar-thumb {
             background-image: -webkit-gradient(linear,
                             left bottom,
                             left top,
                             color-stop(0.44, $rf-brand-lightest),
                             color-stop(0.86, $rf-brand-lighter));
             border-radius: 5px;
-            box-shadow: inset 0 0 6px rgba(0,0,0,0.5); 
+            box-shadow: inset 0 0 6px rgba(0,0,0,0.5);
           }
           li {
             a,
             a:link,
             a:visited {
               color: inherit;
             }
-            
+
             a:hover,
             a:active {
               color: $rf-brand-lighter;
             } // a
           } // li
         } // ol
-      } // #subCol
+      } // #column-side
     } // #feature
 
     .interstitial {
@@ -247,4 +261,4 @@
       }
     }
   } // body.guide
-} // @media (prefers-color-scheme: dark
+} // @media (prefers-color-scheme: dark