Merge pull request #2119 from hypothesis/improve-document-outline

Improve document outline and stucture

src/sidebar/components/annotation-body.js

@@ -39,7 +39,7 @@ export default function AnnotationBody({
   const showTagList = !isEditing && tags.length > 0;
 
   return (
-    <section className="annotation-body">
+    <div className="annotation-body">
       {showExcerpt && (
         <Excerpt
           collapse={isCollapsed}
@@ -78,7 +78,7 @@ export default function AnnotationBody({
       )}
       {showTagList && <TagList annotation={annotation} tags={tags} />}
       {isEditing && <TagEditor onEditTags={onEditTags} tagList={tags} />}
-    </section>
+    </div>
   );
 }
 

src/sidebar/components/annotation-quote.js

@@ -23,7 +23,7 @@ function AnnotationQuote({ annotation, isFocused, settings = {} }) {
   const documentLanguage = '';
 
   return (
-    <section
+    <div
       className={classnames('annotation-quote', {
         'is-orphan': isOrphan(annotation),
         'is-focused': isFocused,
@@ -43,7 +43,7 @@ function AnnotationQuote({ annotation, isFocused, settings = {} }) {
           {quote(annotation)}
         </blockquote>
       </Excerpt>
-    </section>
+    </div>
   );
 }
 

src/sidebar/components/annotation-user.js

@@ -39,7 +39,7 @@ function AnnotationUser({ annotation, features, serviceUrl, settings }) {
           target="_blank"
           rel="noopener noreferrer"
         >
-          <span className="annotation-user__user-name">{displayName}</span>
+          <h3 className="annotation-user__user-name">{displayName}</h3>
         </a>
       </div>
     );
@@ -47,7 +47,7 @@ function AnnotationUser({ annotation, features, serviceUrl, settings }) {
 
   return (
     <div className="annotation-user">
-      <span className="annotation-user__user-name">{displayName}</span>
+      <h3 className="annotation-user__user-name">{displayName}</h3>
     </div>
   );
 }

src/sidebar/components/sidebar-content.js

@@ -127,6 +127,7 @@ function SidebarContent({
 
   return (
     <div>
+      <h2 className="u-screen-reader-only">Annotations</h2>
       {isFocusedMode && <FocusedModeHeader />}
       <LoginPromptPanel onLogin={onLogin} onSignUp={onSignUp} />
       {hasDirectLinkedAnnotationError && (

src/sidebar/components/sidebar-panel.js

@@ -55,7 +55,7 @@ export default function SidebarPanel({
               <SvgIcon name={icon} title={title} />
             </div>
           )}
-          <div className="sidebar-panel__title u-stretch">{title}</div>
+          <h2 className="sidebar-panel__title u-stretch">{title}</h2>
           <div>
             <Button
               icon="cancel"

src/sidebar/components/test/thread-list-test.js

@@ -214,13 +214,13 @@ describe('ThreadList', () => {
    * Get the blank spacer `<div>` that reserves space for non-rendered threads
    * above the viewport.
    */
-  const getUpperSpacer = wrapper => wrapper.find('div').first();
+  const getUpperSpacer = wrapper => wrapper.find('div > div').first();
 
   /**
    * Get the blank spacer `<div>` that reserves space for non-rendered threads
    * below the viewport.
    */
-  const getLowerSpacer = wrapper => wrapper.find('div').last();
+  const getLowerSpacer = wrapper => wrapper.find('div > div').last();
 
   it('renders dimensional elements above and below visible threads', () => {
     const wrapper = createComponent();

src/sidebar/components/thread-list.js

@@ -174,7 +174,7 @@ function ThreadList({ thread, $rootScope }) {
   }, [visibleThreads]);
 
   return (
-    <section>
+    <div>
       <div style={{ height: offscreenUpperHeight }} />
       {visibleThreads.map(child => (
         <div className="thread-list__card" id={child.id} key={child.id}>
@@ -182,7 +182,7 @@ function ThreadList({ thread, $rootScope }) {
         </div>
       ))}
       <div style={{ height: offscreenLowerHeight }} />
-    </section>
+    </div>
   );
 }
 

src/styles/annotator/highlights.scss

 @use '../variables' as var;
-
-// Hide content from sighted users but make it visible to screen readers.
-//
-// Resources:
-// - https://webaim.org/techniques/css/invisiblecontent/ (see "CSS clip")
-// - https://cloudfour.com/thinks/see-no-evil-hidden-content-and-accessibility/#showing-additional-content-for-screen-readers
-@mixin screen-reader-only {
-  // Take the content out of the normal layout flow.
-  position: absolute;
-
-  // Visually hide the content and prevent it from interfering with mouse/touch
-  // text selection by clipping it to an empty box. Compared to moving content with
-  // `top`/`left` this is less likely to cause the browser to scroll to a
-  // different part of the page when the hidden text has screen-reader focus.
-  clip: rect(0 0 0 0);
-  overflow: hidden;
-}
+@use "../mixins/a11y";
 
 // SVG highlights when the "Show Highlights" toggle is turned off.
 .hypothesis-svg-highlight {
@@ -47,14 +31,14 @@
     // Make highlights visible to screen readers.
     // See also - https://developer.paciellogroup.com/blog/2017/12/short-note-on-making-your-mark-more-accessible/.
     &::before {
-      @include screen-reader-only;
+      @include a11y.screen-reader-only;
 
       // nb. The leading/trailing spaces are intended to ensure the text is treated
       // as separate words by assisitve technologies from the content before/after it.
       content: ' annotation start ';
     }
     &::after {
-      @include screen-reader-only;
+      @include a11y.screen-reader-only;
       content: ' annotation end ';
     }
 

src/styles/mixins/a11y.scss

+// Hide content from sighted users but make it visible to screen readers.
+//
+// Resources:
+// - https://webaim.org/techniques/css/invisiblecontent/ (see "CSS clip")
+// - https://cloudfour.com/thinks/see-no-evil-hidden-content-and-accessibility/#showing-additional-content-for-screen-readers
+@mixin screen-reader-only {
+  // Take the content out of the normal layout flow.
+  position: absolute;
+
+  // Visually hide the content and prevent it from interfering with mouse/touch
+  // text selection by clipping it to an empty box. Compared to moving content with
+  // `top`/`left` this is less likely to cause the browser to scroll to a
+  // different part of the page when the hidden text has screen-reader focus.
+  clip: rect(0 0 0 0);
+  overflow: hidden;
+}

src/styles/reset.scss

@@ -94,6 +94,22 @@ blockquote {
   margin: 0;
 }
 
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  margin: 0;
+  padding: 0;
+  border: 0;
+  font: inherit;
+  font-size: 100%;
+  font-weight: normal;
+  font-style: normal;
+  vertical-align: baseline;
+}
+
 // Custom elements
 markdown {
   display: block;

src/styles/util.scss

+@use "./mixins/a11y";
+
 // Utility classes for layout
 .u-stretch {
   flex-grow: 1;
@@ -11,3 +13,7 @@
 .u-strong {
   font-weight: bold;
 }
+
+.u-screen-reader-only {
+  @include a11y.screen-reader-only;
+}