Skip to content

Commit 848a501

Browse files
eksperimentaleksperimental
authored
Add aria-label and title attributes to links (#1266)
Remove use of sr-only class and elements
1 parent 8232103 commit 848a501

File tree

10 files changed

+46
-43
lines changed

10 files changed

+46
-43
lines changed

‎assets/test/tooltips/hints-extraction.spec.js

+3-4
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,11 @@ describe('hints extraction', () => {
77
<div id="content" class="content-inner">
88
<div class="section-headeing">
99
<h1>
10-
Some module <small class="app-vsn">(ExDoc v0.0.1)</small>
10+
SomeModule <small class="app-vsn">(ExDoc v0.0.1)</small>
1111
</h1>
1212
13-
<a href="https://github.com/" title="View Source" class="view-source" rel="help">
13+
<a href="https://github.com/" title="View source" aria-label="View source of SomeModule" class="view-source" rel="help">
1414
<span class="icon-code" aria-hidden="true"></span>
15-
<span class="sr-only">View Source</span>
1615
</a>
1716
</div>
1817
@@ -29,7 +28,7 @@ describe('hints extraction', () => {
2928
`))
3029

3130
it('extracts hint info', () => {
32-
expect(extractModuleHint(modulePageObject).title).to.eql('Some module')
31+
expect(extractModuleHint(modulePageObject).title).to.eql('SomeModule')
3332
expect(extractModuleHint(modulePageObject).description).to.eql('Module description here')
3433
expect(extractModuleHint(modulePageObject).kind).to.eql('module')
3534
})

‎lib/ex_doc/formatter/epub/templates/module_template.eex

+2-4
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,8 @@
1818
<%= if Enum.any?(summary, fn {_, v} -> v != [] end) do %>
1919
<section id="summary" class="details-list">
2020
<div class="section-heading">
21-
<a class="hover-link" href="#summary">
21+
<a class="hover-link" href="#summary" title="Link to this section" aria-label="Link to Summary">
2222
<span class="icon-link" aria-hidden="true"></span>
23-
<span class="sr-only">Anchor for this section</span>
2423
</a>
2524

2625
<h1>Summary</h1>
@@ -32,9 +31,8 @@
3231
<%= for {name, nodes} <- summary, nodes != [], key = HTML.text_to_id(name) do %>
3332
<section id="<%= key %>" class="details-list">
3433
<div class="section-heading">
35-
<a class="hover-link" href="#<%= key %>">
34+
<a class="hover-link" href="#<%= key %>" title="Link to this section" aria-label="Link to <%= name %>">
3635
<span class="icon-link" aria-hidden="true"></span>
37-
<span class="sr-only">Anchor for this section</span>
3836
</a>
3937

4038
<h1><%= name %></h1>

‎lib/ex_doc/formatter/html/templates.ex

+3-1
Original file line numberDiff line numberDiff line change
@@ -248,7 +248,9 @@ defmodule ExDoc.Formatter.HTML.Templates do
248248
defp link_heading(_match, tag, title, id, prefix) do
249249
"""
250250
<div class="section-heading">
251-
<a href="##{prefix}#{id}" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
251+
<a href="##{prefix}#{id}" class="hover-link" title="Link to this section" aria-label="Link to #{
252+
HTML.strip_tags(title)
253+
}"><span class="icon-link" aria-hidden="true"></span></a>
252254
<#{tag} id="#{prefix}#{id}">
253255
#{title}
254256
</#{tag}>

‎lib/ex_doc/formatter/html/templates/detail_template.eex

+2-4
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,13 @@
33
<span id="<%=enc HTML.link_id("#{default_name}/#{default_arity}", node.type) %>"></span>
44
<% end %>
55
<div class="detail-header">
6-
<a href="#<%=enc HTML.link_id(node) %>" class="detail-link" title="Link to this <%= pretty_type(node) %>">
6+
<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 %>">
77
<span class="icon-link" aria-hidden="true"></span>
8-
<span class="sr-only">Link to this <%= pretty_type(node) %></span>
98
</a>
109
<h1 class="signature"><%=h node.signature %></h1>
1110
<%= if node.source_url do %>
12-
<a href="<%= node.source_url %>" class="view-source" rel="help" title="View Source">
11+
<a href="<%= node.source_url %>" class="view-source" rel="help" title="View source" aria-label="View source of <%= pretty_type(node) %> <%= node.id %>">
1312
<span class="icon-code" aria-hidden="true"></span>
14-
<span class="sr-only">View Source</span>
1513
</a>
1614
<% end %>
1715
<%= for annotation <- node.annotations do %>

‎lib/ex_doc/formatter/html/templates/module_template.eex

+3-6
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,8 @@
66
<%= module_title(module) %> <small class="app-vsn">(<%= config.project %> v<%= config.version %>)</small>
77
</h1>
88
<%= if module.source_url do %>
9-
<a href="<%= module.source_url %>" title="View Source" class="view-source" rel="help">
9+
<a href="<%= module.source_url %>" title="View source" aria-label="View source of <%= module_title(module) %>" class="view-source" rel="help">
1010
<span class="icon-code" aria-hidden="true"></span>
11-
<span class="sr-only">View Source</span>
1211
</a>
1312
<% end %>
1413
</div>
@@ -28,9 +27,8 @@
2827
<%= if Enum.any?(summary, fn {_, v} -> v != [] end) do %>
2928
<section id="summary" class="details-list">
3029
<div class="section-heading">
31-
<a class="hover-link" href="#summary">
30+
<a class="hover-link" href="#summary" title="Link to this section" aria-label="Link to Summary">
3231
<span class="icon-link" aria-hidden="true"></span>
33-
<span class="sr-only">Link to this section</span>
3432
</a>
3533
<h1>
3634
Summary
@@ -43,9 +41,8 @@
4341
<%= for {name, nodes} <- summary, nodes != [], key = HTML.text_to_id(name) do %>
4442
<section id="<%= key %>" class="details-list">
4543
<div class="section-heading">
46-
<a class="hover-link" href="#<%= key %>">
44+
<a class="hover-link" href="#<%= key %>" title="Link to this section" aria-label="Link to <%= name %>">
4745
<span class="icon-link" aria-hidden="true"></span>
48-
<span class="sr-only">Link to this section</span>
4946
</a>
5047

5148
<h1>

‎lib/ex_doc/formatter/html/templates/summary_entry_template.eex

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<div class="summary-row">
22
<div class="summary-signature">
3-
<a href="#<%=enc HTML.link_id(node) %>"><%=h node.signature %></a>
3+
<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>
44
<%= if deprecated = node.deprecated do %>
55
<span class="deprecated" title="<%= h(deprecated) %>">deprecated</span>
66
<% end %>

‎lib/ex_doc/formatter/html/templates/summary_template.eex

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
<%= unless Enum.empty?(nodes) do %>
2+
<% name_string = String.downcase("#{name}") %>
23
<div class="summary-<%= HTML.text_to_id(name) %> summary">
34
<h2>
4-
<a href="#<%= HTML.text_to_id(name) %>"><%= name %></a>
5+
<a href="#<%= HTML.text_to_id(name) %>" title="Go to <%= name_string %> section" aria-label="Go to <%= name_string %> section"><%= name %></a>
56
</h2>
67
<%= for node <- nodes, do: summary_entry_template(node) %>
78
</div>

‎test/ex_doc/formatter/epub/templates_test.exs

+3-1
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,9 @@ defmodule ExDoc.Formatter.EPUB.TemplatesTest do
9090

9191
test "outputs summaries" do
9292
content = get_module_page([CompiledWithDocs])
93-
assert content =~ ~r{<div class="summary-signature">\s*<a href="#example_1/0">}
93+
94+
assert content =~
95+
~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>}
9496
end
9597

9698
test "contains links to summary sections when those exist" do

‎test/ex_doc/formatter/html/templates_test.exs

+25-19
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,13 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
4747
test "generates headers with hovers" do
4848
assert Templates.link_headings("<h2>Foo</h2><h2>Bar</h2>") == """
4949
<div class="section-heading">
50-
<a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
50+
<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>
5151
<h2 id="foo">
5252
Foo
5353
</h2>
5454
</div>
5555
<div class="section-heading">
56-
<a href="#bar" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
56+
<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>
5757
<h2 id="bar">
5858
Bar
5959
</h2>
@@ -62,14 +62,14 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
6262

6363
assert Templates.link_headings("<h2>Foo</h2>\n<h2>Bar</h2>") == """
6464
<div class="section-heading">
65-
<a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
65+
<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>
6666
<h2 id="foo">
6767
Foo
6868
</h2>
6969
</div>
7070
7171
<div class="section-heading">
72-
<a href="#bar" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
72+
<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>
7373
<h2 id="bar">
7474
Bar
7575
</h2>
@@ -78,7 +78,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
7878

7979
assert Templates.link_headings("<h2></h2><h2>Bar</h2>") == """
8080
<h2></h2><div class="section-heading">
81-
<a href="#bar" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
81+
<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>
8282
<h2 id="bar">
8383
Bar
8484
</h2>
@@ -88,7 +88,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
8888
assert Templates.link_headings("<h2></h2>\n<h2>Bar</h2>") == """
8989
<h2></h2>
9090
<div class="section-heading">
91-
<a href="#bar" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
91+
<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>
9292
<h2 id="bar">
9393
Bar
9494
</h2>
@@ -98,7 +98,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
9898
assert Templates.link_headings("<h2>Foo</h2><h2></h2>") ==
9999
String.trim_trailing("""
100100
<div class="section-heading">
101-
<a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
101+
<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>
102102
<h2 id="foo">
103103
Foo
104104
</h2>
@@ -109,7 +109,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
109109
assert Templates.link_headings("<h2>Foo</h2>\n<h2></h2>") ==
110110
String.trim_trailing("""
111111
<div class="section-heading">
112-
<a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
112+
<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>
113113
<h2 id="foo">
114114
Foo
115115
</h2>
@@ -120,7 +120,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
120120

121121
assert Templates.link_headings("<h3>Foo</h3>") == """
122122
<div class="section-heading">
123-
<a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
123+
<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>
124124
<h3 id="foo">
125125
Foo
126126
</h3>
@@ -131,14 +131,14 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
131131
test "generates headers with unique id's" do
132132
assert Templates.link_headings("<h3>Foo</h3>\n<h3>Foo</h3>") == """
133133
<div class="section-heading">
134-
<a href="#foo" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
134+
<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>
135135
<h3 id="foo">
136136
Foo
137137
</h3>
138138
</div>
139139
140140
<div class="section-heading">
141-
<a href="#foo-1" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
141+
<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>
142142
<h3 id="foo-1">
143143
Foo
144144
</h3>
@@ -338,10 +338,10 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
338338
~r{moduledoc.*Example.*<span class="nc">CompiledWithDocs</span><span class="o">\.</span><span class="n">example</span>.*}ms
339339

340340
assert content =~
341-
~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
341+
~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
342342

343343
assert content =~
344-
~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
344+
~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
345345

346346
# Summaries
347347
assert content =~ ~r{example/2.*Some example}ms
@@ -350,15 +350,15 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
350350

351351
# Source
352352
assert content =~
353-
~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
353+
~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
354354

355355
# Functions
356356
assert content =~ ~s{<section class="detail" id="example/2">}
357357
assert content =~ ~s{<span id="example/1"></span>}
358358
assert content =~ ~s{example(foo, bar \\\\ Baz)}
359359

360360
assert content =~
361-
~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
361+
~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
362362
end
363363

364364
test "outputs function groups" do
@@ -398,8 +398,12 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
398398
~S[<a href="TypesAndSpecs.Sub.html#t:t/0">TypesAndSpecs.Sub.t</a>(), ] <>
399399
~S[<a href="#t:opaque/0">opaque</a>(), :ok | :error}]
400400

401-
assert content =~ ~s[<a href="#t:public/1">public(t)</a>]
402-
refute content =~ ~s[<a href="#t:private/0">private</a>]
401+
assert content =~
402+
~s[<a href="#t:public/1" data-title="Go to public/1" aria-label="Go to type public/1">public(t)</a>]
403+
404+
refute content =~
405+
~s[<a href="#t:private/0" data-title="Go to private/0" aria-label="Go to type private/0">private()</a>]
406+
403407
assert content =~ public_html
404408
refute content =~ ~s[<strong>private\(t\)]
405409
assert content =~ ~s[A public type]
@@ -414,7 +418,9 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
414418

415419
test "outputs summaries" do
416420
content = get_module_page([CompiledWithDocs])
417-
assert content =~ ~r{<div class="summary-signature">\s*<a href="#example_1/0">}
421+
422+
assert content =~
423+
~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>}
418424
end
419425

420426
test "contains links to summary sections when those exist" do
@@ -426,7 +432,7 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
426432
content = get_module_page([CompiledWithDocs])
427433

428434
assert content =~
429-
~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
435+
~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
430436
end
431437

432438
test "do not output overlapping functions, causing duplicate IDs" do

‎test/ex_doc/formatter/html_test.exs

+2-2
Original file line numberDiff line numberDiff line change
@@ -307,10 +307,10 @@ defmodule ExDoc.Formatter.HTMLTest do
307307
assert content =~ ~r{<title>README [^<]*</title>}
308308

309309
assert content =~
310-
~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
310+
~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
311311

312312
assert content =~
313-
~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
313+
~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
314314

315315
assert content =~ ~r{<a href="RandomError.html"><code(\sclass="inline")?>RandomError</code>}
316316

0 commit comments

Comments
 (0)