Add aria-label and title attributes to links (#1266)

Remove use of sr-only class and elements
elixir-lang · Aug 30, 2020 · 848a501 · 848a501
1 parent 8232103
commit 848a501
Show file tree

Hide file tree

Showing 10 changed files with 46 additions and 43 deletions.
diff --git a/assets/test/tooltips/hints-extraction.spec.js b/assets/test/tooltips/hints-extraction.spec.js
@@ -7,12 +7,11 @@ describe('hints extraction', () => {
       <div id="content" class="content-inner">
         <div class="section-headeing">
           <h1>
-            Some module <small class="app-vsn">(ExDoc v0.0.1)</small>
+            SomeModule <small class="app-vsn">(ExDoc v0.0.1)</small>
           </h1>
 
-          <a href="https://github.com/" title="View Source" class="view-source" rel="help">
+          <a href="https://github.com/" title="View source" aria-label="View source of SomeModule" class="view-source" rel="help">
             <span class="icon-code" aria-hidden="true"></span>
-            <span class="sr-only">View Source</span>
           </a>
         </div>
 
@@ -29,7 +28,7 @@ describe('hints extraction', () => {
     `))
 
     it('extracts hint info', () => {
-      expect(extractModuleHint(modulePageObject).title).to.eql('Some module')
+      expect(extractModuleHint(modulePageObject).title).to.eql('SomeModule')
       expect(extractModuleHint(modulePageObject).description).to.eql('Module description here')
       expect(extractModuleHint(modulePageObject).kind).to.eql('module')
     })

diff --git a/lib/ex_doc/formatter/epub/templates/module_template.eex b/lib/ex_doc/formatter/epub/templates/module_template.eex
@@ -18,9 +18,8 @@
     <%= if Enum.any?(summary, fn {_, v} -> v != [] end) do %>
       <section id="summary" class="details-list">
         <div class="section-heading">
-          <a class="hover-link" href="#summary">
+          <a class="hover-link" href="#summary" title="Link to this section" aria-label="Link to Summary">
             <span class="icon-link" aria-hidden="true"></span>
-            <span class="sr-only">Anchor for this section</span>
           </a>
 
           <h1>Summary</h1>
@@ -32,9 +31,8 @@
     <%= for {name, nodes} <- summary, nodes != [], key = HTML.text_to_id(name) do %>
       <section id="<%= key %>" class="details-list">
         <div class="section-heading">
-          <a class="hover-link" href="#<%= key %>">
+          <a class="hover-link" href="#<%= key %>" title="Link to this section" aria-label="Link to <%= name %>">
             <span class="icon-link" aria-hidden="true"></span>
-            <span class="sr-only">Anchor for this section</span>
           </a>
 
           <h1><%= name %></h1>

diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex
@@ -248,7 +248,9 @@ defmodule ExDoc.Formatter.HTML.Templates do
   defp link_heading(_match, tag, title, id, prefix) do
     """
     <div class="section-heading">
-      <a href="##{prefix}#{id}" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+      <a href="##{prefix}#{id}" class="hover-link" title="Link to this section" aria-label="Link to #{
+      HTML.strip_tags(title)
+    }"><span class="icon-link" aria-hidden="true"></span></a>
       <#{tag} id="#{prefix}#{id}">
         #{title}
       </#{tag}>

diff --git a/lib/ex_doc/formatter/html/templates/detail_template.eex b/lib/ex_doc/formatter/html/templates/detail_template.eex
@@ -3,15 +3,13 @@
     <span id="<%=enc HTML.link_id("#{default_name}/#{default_arity}", node.type) %>"></span>
   <% end %>
   <div class="detail-header">
-    <a href="#<%=enc HTML.link_id(node) %>" class="detail-link" title="Link to this <%= pretty_type(node) %>">
+    <a href="#<%=enc HTML.link_id(node) %>" class="detail-link" title="Link to this <%= pretty_type(node) %>" aria-label="Link to <%= pretty_type(node) %> <%= node.id %>">
       <span class="icon-link" aria-hidden="true"></span>
-      <span class="sr-only">Link to this <%= pretty_type(node) %></span>
     </a>
     <h1 class="signature"><%=h node.signature %></h1>
     <%= if node.source_url do %>
-      <a href="<%= node.source_url %>" class="view-source" rel="help" title="View Source">
+      <a href="<%= node.source_url %>" class="view-source" rel="help" title="View source" aria-label="View source of <%= pretty_type(node) %> <%= node.id %>">
        <span class="icon-code" aria-hidden="true"></span>
-       <span class="sr-only">View Source</span>
      </a>
     <% end %>
     <%= for annotation <- node.annotations do %>

diff --git a/lib/ex_doc/formatter/html/templates/module_template.eex b/lib/ex_doc/formatter/html/templates/module_template.eex
@@ -6,9 +6,8 @@
           <%= module_title(module) %> <small class="app-vsn">(<%= config.project %> v<%= config.version %>)</small>
         </h1>
         <%= if module.source_url do %>
-          <a href="<%= module.source_url %>" title="View Source" class="view-source" rel="help">
+          <a href="<%= module.source_url %>" title="View source" aria-label="View source of <%= module_title(module) %>" class="view-source" rel="help">
             <span class="icon-code" aria-hidden="true"></span>
-            <span class="sr-only">View Source</span>
           </a>
         <% end %>
       </div>
@@ -28,9 +27,8 @@
       <%= if Enum.any?(summary, fn {_, v} -> v != [] end) do %>
         <section id="summary" class="details-list">
           <div class="section-heading">
-            <a class="hover-link" href="#summary">
+            <a class="hover-link" href="#summary" title="Link to this section" aria-label="Link to Summary">
               <span class="icon-link" aria-hidden="true"></span>
-              <span class="sr-only">Link to this section</span>
             </a>
             <h1>
               Summary
@@ -43,9 +41,8 @@
       <%= for {name, nodes} <- summary, nodes != [], key = HTML.text_to_id(name) do %>
         <section id="<%= key %>" class="details-list">
           <div class="section-heading">
-            <a class="hover-link" href="#<%= key %>">
+            <a class="hover-link" href="#<%= key %>" title="Link to this section" aria-label="Link to <%= name %>">
               <span class="icon-link" aria-hidden="true"></span>
-              <span class="sr-only">Link to this section</span>
             </a>
 
             <h1>

diff --git a/lib/ex_doc/formatter/html/templates/summary_entry_template.eex b/lib/ex_doc/formatter/html/templates/summary_entry_template.eex
@@ -1,6 +1,6 @@
 <div class="summary-row">
   <div class="summary-signature">
-    <a href="#<%=enc HTML.link_id(node) %>"><%=h node.signature %></a>
+    <a href="#<%=enc HTML.link_id(node) %>" data-title="Go to <%= h node.id %>" aria-label="Go to <%= pretty_type(node) %> <%= h node.id %>"><%=h node.signature %></a>
     <%= if deprecated = node.deprecated do %>
       <span class="deprecated" title="<%= h(deprecated) %>">deprecated</span>
     <% end %>

diff --git a/lib/ex_doc/formatter/html/templates/summary_template.eex b/lib/ex_doc/formatter/html/templates/summary_template.eex
@@ -1,7 +1,8 @@
 <%= unless Enum.empty?(nodes) do %>
+	<% name_string = String.downcase("#{name}") %>
   <div class="summary-<%= HTML.text_to_id(name) %> summary">
     <h2>
-      <a href="#<%= HTML.text_to_id(name) %>"><%= name %></a>
+      <a href="#<%= HTML.text_to_id(name) %>" title="Go to <%= name_string %> section" aria-label="Go to <%= name_string %> section"><%= name %></a>
     </h2>
     <%= for node <- nodes, do: summary_entry_template(node) %>
   </div>

diff --git a/test/ex_doc/formatter/epub/templates_test.exs b/test/ex_doc/formatter/epub/templates_test.exs
@@ -90,7 +90,9 @@ defmodule ExDoc.Formatter.EPUB.TemplatesTest do
 
     test "outputs summaries" do
       content = get_module_page([CompiledWithDocs])
-      assert content =~ ~r{<div class="summary-signature">\s*<a href="#example_1/0">}
+
+      assert content =~
+               ~r{<div class="summary-signature">\s*<a href="#example_1/0" data-title="Go to example_1/0" aria-label="Go to macro example_1/0">example_1\(\)</a>\s*</div>}
     end
 
     test "contains links to summary sections when those exist" do

diff --git a/test/ex_doc/formatter/html/templates_test.exs b/test/ex_doc/formatter/html/templates_test.exs
@@ -47,13 +47,13 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
     test "generates headers with hovers" do
       assert Templates.link_headings("<h2>Foo</h2><h2>Bar</h2>") == """
              <div class="section-heading">
-               <a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+               <a href="#foo" class="hover-link" title="Link to this section" aria-label="Link to Foo"><span class="icon-link" aria-hidden="true"></span></a>
                <h2 id="foo">
                  Foo
                </h2>
              </div>
              <div class="section-heading">
-               <a href="#bar" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+               <a href="#bar" class="hover-link" title="Link to this section" aria-label="Link to Bar"><span class="icon-link" aria-hidden="true"></span></a>
                <h2 id="bar">
                  Bar
                </h2>
@@ -62,14 +62,14 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
 
       assert Templates.link_headings("<h2>Foo</h2>\n<h2>Bar</h2>") == """
              <div class="section-heading">
-               <a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+               <a href="#foo" class="hover-link" title="Link to this section" aria-label="Link to Foo"><span class="icon-link" aria-hidden="true"></span></a>
                <h2 id="foo">
                  Foo
                </h2>
              </div>
 
              <div class="section-heading">
-               <a href="#bar" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+               <a href="#bar" class="hover-link" title="Link to this section" aria-label="Link to Bar"><span class="icon-link" aria-hidden="true"></span></a>
                <h2 id="bar">
                  Bar
                </h2>
@@ -78,7 +78,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
 
       assert Templates.link_headings("<h2></h2><h2>Bar</h2>") == """
              <h2></h2><div class="section-heading">
-               <a href="#bar" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+               <a href="#bar" class="hover-link" title="Link to this section" aria-label="Link to Bar"><span class="icon-link" aria-hidden="true"></span></a>
                <h2 id="bar">
                  Bar
                </h2>
@@ -88,7 +88,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
       assert Templates.link_headings("<h2></h2>\n<h2>Bar</h2>") == """
              <h2></h2>
              <div class="section-heading">
-               <a href="#bar" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+               <a href="#bar" class="hover-link" title="Link to this section" aria-label="Link to Bar"><span class="icon-link" aria-hidden="true"></span></a>
                <h2 id="bar">
                  Bar
                </h2>
@@ -98,7 +98,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
       assert Templates.link_headings("<h2>Foo</h2><h2></h2>") ==
                String.trim_trailing("""
                <div class="section-heading">
-                 <a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+                 <a href="#foo" class="hover-link" title="Link to this section" aria-label="Link to Foo"><span class="icon-link" aria-hidden="true"></span></a>
                  <h2 id="foo">
                    Foo
                  </h2>
@@ -109,7 +109,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
       assert Templates.link_headings("<h2>Foo</h2>\n<h2></h2>") ==
                String.trim_trailing("""
                <div class="section-heading">
-                 <a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+                 <a href="#foo" class="hover-link" title="Link to this section" aria-label="Link to Foo"><span class="icon-link" aria-hidden="true"></span></a>
                  <h2 id="foo">
                    Foo
                  </h2>
@@ -120,7 +120,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
 
       assert Templates.link_headings("<h3>Foo</h3>") == """
              <div class="section-heading">
-               <a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+               <a href="#foo" class="hover-link" title="Link to this section" aria-label="Link to Foo"><span class="icon-link" aria-hidden="true"></span></a>
                <h3 id="foo">
                  Foo
                </h3>
@@ -131,14 +131,14 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
     test "generates headers with unique id's" do
       assert Templates.link_headings("<h3>Foo</h3>\n<h3>Foo</h3>") == """
              <div class="section-heading">
-               <a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+               <a href="#foo" class="hover-link" title="Link to this section" aria-label="Link to Foo"><span class="icon-link" aria-hidden="true"></span></a>
                <h3 id="foo">
                  Foo
                </h3>
              </div>
 
              <div class="section-heading">
-               <a href="#foo-1" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
+               <a href="#foo-1" class="hover-link" title="Link to this section" aria-label="Link to Foo"><span class="icon-link" aria-hidden="true"></span></a>
                <h3 id="foo-1">
                  Foo
                </h3>
@@ -338,10 +338,10 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
                ~r{moduledoc.*Example.*<span class="nc">CompiledWithDocs</span><span class="o">\.</span><span class="n">example</span>.*}ms
 
       assert content =~
-               ~r{<div class="section-heading">\s*<a href="#module-example-unicode-escaping" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>\s*<h2 id="module-example-unicode-escaping">\s*Example[^<]+</h2>\s*</div>}ms
+               ~r{<div class="section-heading">\s*<a href="#module-example-unicode-escaping" class="hover-link" title="Link to this section" aria-label="Link to Example [^<]+ escaping"><span class="icon-link" aria-hidden="true"></span></a>\s*<h2 id="module-example-unicode-escaping">\s*Example [^<]+ escaping\s*</h2>\s*</div>}ms
 
       assert content =~
-               ~r{<div class="section-heading">\s*<a href="#module-example-h3-heading" class="hover-link">.*<span class="icon-link" aria-hidden="true"></span></a>\s*<h3 id="module-example-h3-heading">\s*Example H3 heading[^<]+</h3>\s*</div>}ms
+               ~r{<div class="section-heading">\s*<a href="#module-example-h3-heading" class="hover-link" title="Link to this section" aria-label="Link to Example H3 heading">.*<span class="icon-link" aria-hidden="true"></span></a>\s*<h3 id="module-example-h3-heading">\s*Example H3 heading\s*</h3>\s*</div>}ms
 
       # Summaries
       assert content =~ ~r{example/2.*Some example}ms
@@ -350,15 +350,15 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
 
       # Source
       assert content =~
-               ~r{<a href="#{source_url()}/blob/master/test/fixtures/compiled_with_docs.ex#L14"[^>]*>\s*<span class="icon-code" aria-hidden="true"></span>\s*<span class="sr-only">View Source</span>\s*</a>}ms
+               ~r{<a href="#{source_url()}/blob/master/test/fixtures/compiled_with_docs.ex#L14"[^>]*>\s*<span class="icon-code" aria-hidden="true"></span>\s*</a>}ms
 
       # Functions
       assert content =~ ~s{<section class="detail" id="example/2">}
       assert content =~ ~s{<span id="example/1"></span>}
       assert content =~ ~s{example(foo, bar \\\\ Baz)}
 
       assert content =~
-               ~r{<a href="#example/2" class="detail-link" title="Link to this function">\s*<span class="icon-link" aria-hidden="true"></span>\s*<span class="sr-only">Link to this function</span>\s*</a>}ms
+               ~r{<a href="#example/2" class="detail-link" title="Link to this function" aria-label="Link to function example/2">\s*<span class="icon-link" aria-hidden="true"></span>\s*</a>}ms
     end
 
     test "outputs function groups" do
@@ -398,8 +398,12 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
           ~S[<a href="TypesAndSpecs.Sub.html#t:t/0">TypesAndSpecs.Sub.t</a>(), ] <>
           ~S[<a href="#t:opaque/0">opaque</a>(), :ok | :error}]
 
-      assert content =~ ~s[<a href="#t:public/1">public(t)</a>]
-      refute content =~ ~s[<a href="#t:private/0">private</a>]
+      assert content =~
+               ~s[<a href="#t:public/1" data-title="Go to public/1" aria-label="Go to type public/1">public(t)</a>]
+
+      refute content =~
+               ~s[<a href="#t:private/0" data-title="Go to private/0" aria-label="Go to type private/0">private()</a>]
+
       assert content =~ public_html
       refute content =~ ~s[<strong>private\(t\)]
       assert content =~ ~s[A public type]
@@ -414,7 +418,9 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
 
     test "outputs summaries" do
       content = get_module_page([CompiledWithDocs])
-      assert content =~ ~r{<div class="summary-signature">\s*<a href="#example_1/0">}
+
+      assert content =~
+               ~r{<div class="summary-signature">\s*<a href="#example_1/0" data-title=\"Go to example_1/0\" aria-label=\"Go to macro example_1/0\">example_1\(\)</a>\s*</div>}
     end
 
     test "contains links to summary sections when those exist" do
@@ -426,7 +432,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
       content = get_module_page([CompiledWithDocs])
 
       assert content =~
-               ~r{<div class="section-heading">\s*<a href="#example_with_h3/0-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>\s*<h3 id="example_with_h3/0-examples">\s*Examples[^<]+</h3>\s*</div>}ms
+               ~r{<div class="section-heading">\s*<a href="#example_with_h3/0-examples" class="hover-link" title="Link to this section" aria-label="Link to Examples"><span class="icon-link" aria-hidden="true"></span></a>\s*<h3 id="example_with_h3/0-examples">\s*Examples[^<]+</h3>\s*</div>}ms
     end
 
     test "do not output overlapping functions, causing duplicate IDs" do

diff --git a/test/ex_doc/formatter/html_test.exs b/test/ex_doc/formatter/html_test.exs
@@ -307,10 +307,10 @@ defmodule ExDoc.Formatter.HTMLTest do
       assert content =~ ~r{<title>README [^<]*</title>}
 
       assert content =~
-               ~r{<div class="section-heading">\s*<a href="#header-sample" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>\s*<h2 id="header-sample">\s*<code(\sclass="inline")?>Header</code> sample\s*</h2>\s*</div>}ms
+               ~r{<div class="section-heading">\s*<a href="#header-sample" class="hover-link" title="Link to this section" aria-label="Link to Header sample"><span class="icon-link" aria-hidden="true"></span></a>\s*<h2 id="header-sample">\s*<code(\sclass="inline")?>Header</code> sample\s*</h2>\s*</div>}ms
 
       assert content =~
-               ~r{<div class="section-heading">\s*<a href="#more-than" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>\s*<h2 id="more-than">\s*more &gt; than\s*</h2>\s*</div>}ms
+               ~r{<div class="section-heading">\s*<a href="#more-than" class="hover-link" title="Link to this section" aria-label="Link to more &gt; than"><span class="icon-link" aria-hidden="true"></span></a>\s*<h2 id="more-than">\s*more &gt; than\s*</h2>\s*</div>}ms
 
       assert content =~ ~r{<a href="RandomError.html"><code(\sclass="inline")?>RandomError</code>}