From f798de7e63a4a9fd1ee17031997b21eb185acd29 Mon Sep 17 00:00:00 2001
From: Rohan Kumar <seirdy@seirdy.one>
Date: Thu, 19 May 2022 17:18:14 -0700
Subject: [PATCH] A11y: drop draft ARIA, overhaul in-page links

- Stop using draft WAI-ARIA 1.3 that isn't supported yet
- Make in-page links focusable across shortcodes/partials
- Replace existing in-page heading anchor links with a more accessible
  option.
- Make backlinks aria-labelledby instead of giving them an aria-label,
  so they can be translated.
---
 assets/css/main.css                          |  8 ++-
 layouts/_default/_markup/render-heading.html |  9 +--
 layouts/partials/full-article.html           |  2 +-
 layouts/partials/processed-content.html      | 27 ++++---
 layouts/partials/webmentions.html            | 76 +++++++++++---------
 layouts/shortcodes/codecaption.html          |  2 +-
 layouts/shortcodes/image-figure.html         |  2 +-
 layouts/shortcodes/quotation.html            |  2 +-
 layouts/shortcodes/transcribed-image.html    |  3 +-
 linter-configs/vnu_filter.jq                 |  5 --
 10 files changed, 75 insertions(+), 61 deletions(-)

diff --git a/assets/css/main.css b/assets/css/main.css
index a879ac3..5b69347 100644
--- a/assets/css/main.css
+++ b/assets/css/main.css
@@ -62,7 +62,7 @@ html {
 		 * between tappables" by creating margins/paddings between nav links;
 		 * re-use that same amount of space here. 24px is what it takes to
 		 * create atl 48px of non-interactive space on <ul> and <ol> elements
-		 * containing lists of interactives.
+		 * containing lists of interactives, with 8px in between.
 		 * Don't use relative units here; this margin shouldn't scale with
 		 * zoom, or else text will get narrower with zoom. */
 		padding: 0 24px;
@@ -234,6 +234,11 @@ samp {
 	font-family: monospace, monospace;
 }
 
+/* Some browsers don't support the hidden attr */
+span[hidden] {
+	display: none;
+}
+
 /* Narrow screens: long words can cause content to flow out of the
  * viewport, triggering horizontal scrolling. Allow breaking words in
  * content I don't control (comments, names). For content I do control,
@@ -292,6 +297,7 @@ picture > img {
  * reducing the number of DOM nodes rendered at once. */
 aside,
 footer,
+section[role="doc-endnotes"],
 section[aria-labelledby="webmentions"] {
 	border-top: 1px solid;
 	content-visibility: auto;
diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html
index 8919bb9..0163550 100644
--- a/layouts/_default/_markup/render-heading.html
+++ b/layouts/_default/_markup/render-heading.html
@@ -1,11 +1,8 @@
+<h{{ .Level }} id="{{ .Anchor | safeURL }}" tabindex="-1">{{ .Text | safeHTML -}}</h{{ .Level }}>
 {{- if and (eq .Level 2) (eq .Page.Section "posts") }}
-<h{{ .Level }} id="{{ .Anchor | safeURL }}-hd">{{ .Text | safeHTML -}}</h{{ .Level }}>
 <a
-	id="{{ .Anchor | safeURL }}" href="#{{ .Anchor | safeURL }}"
-	aria-labelledby="{{ .Anchor | safeURL }}-prefix {{ .Anchor | safeURL }}-hd">
+	id="{{ .Anchor | safeURL }}-anchor" href="#{{ .Anchor | safeURL }}"
+	aria-labelledby="{{ .Anchor | safeURL }}-prefix {{ .Anchor | safeURL }}">
 	<span id="{{ .Anchor | safeURL }}-prefix">Permalink to section</span>
 </a>
-{{- else }}
-{{- with . -}}
-<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML -}}</h{{ .Level }}>{{ end -}}
 {{- end }}
diff --git a/layouts/partials/full-article.html b/layouts/partials/full-article.html
index d37b4ac..15deaa0 100644
--- a/layouts/partials/full-article.html
+++ b/layouts/partials/full-article.html
@@ -1,4 +1,4 @@
-<article aria-details="webmentions" class="h-entry hentry">
+<article class="h-entry hentry"><!--Once WAI-ARIA 1.3 gains traction, I'll add aria-details for webmentions.-->
 <header>
 	<h1 itemprop="name headline" class="p-name entry-title">{{ .Title }}</h1>
 	{{- if not .Params.disableMeta }}
diff --git a/layouts/partials/processed-content.html b/layouts/partials/processed-content.html
index 6ade99f..cff3f9e 100644
--- a/layouts/partials/processed-content.html
+++ b/layouts/partials/processed-content.html
@@ -24,23 +24,32 @@
 </ol>
 </section>` -}}
 
-<!--Descriptive footnote link names, remove unused class-->
-{{- $badNoteRef := `class="footnote-ref" role="doc-noteref">([0-9]*)</a>` -}}
-{{- $goodNoteRef := `role="doc-noteref">note&nbsp;${1}</a>` -}}
+<!--
+	Descriptive footnote link names, remove unused class, put
+	backlink id in <a> since <a> is focusable, remove unused class.
+-->
+{{- $badNoteRef := `<sup id="fnref([0-9\:]*)"><a( [^>]*)class="footnote-ref" role="doc-noteref">([0-9]*)</a>` -}}
+{{- $goodNoteRef := `<sup><a${2}id="fnref${1}" role="doc-noteref">note&nbsp;${3}</a>` -}}
 
 <!--Move the Table of Contents heading *inside* the <nav> element-->
 {{- $tocHeadingOutside := `<h2>Table of Contents</h2><nav(?:.*)>` -}}
-{{- $tocHeadingInside := `<nav id=TableOfContents role="doc-toc" aria-labelledby="toc-hd"><h2 id="toc-hd">Table of Contents</h2>` -}}
+{{- $tocHeadingInside := `<nav id=TableOfContents role="doc-toc" aria-labelledby="toc-hd" tabindex="-1">
+	<h2 id="toc-hd">Table of Contents</h2>` -}}
 
 <!--Give footnote backlinks accessible names-->
-{{- $footnoteBacklinksBad  :=  `<a href="#fnref:([0-9]*)" class="footnote-backref"(.*role="doc-backlink"(?:.*)?)>` -}}
-{{- $footnoteBacklinksGood :=  `<a href="#fnref:${1}" aria-label="back to reference ${1}"${2}>` -}}
+{{- $footnoteBacklinksBad  :=  `<a href="#fnref:([0-9]*)" class="footnote-backref"(.*role="doc-backlink"(?:[^>]*)?)>([^<]*)` -}}
+{{- $footnoteBacklinksGood :=  `<a href="#fnref:${1}" aria-labelledby="bl-${1}"${2}>${3} <span id="bl-${1}" hidden>back to reference ${1}</span>` -}}
 
 <!--
 	If two backlinks exist, give them different names.
 	I currently don't have any triple backlinks; if I ever do, I'll implement this properly with a loop.
 -->
-{{- $repeatedFootnoteBacklinksBad  :=  `"back to reference ([0-9]*)"(.*)<a href="#fnref([0-9]):([0-9]*)"(.*role="doc-backlink"(?:.*)?)>` -}}
-{{- $repeatedFootnoteBacklinksGood :=  `"back to reference ${1}, instance 1"${2}<a href="#fnref${3}:${4}" aria-label="back to reference ${4}, instance 2"${5}>` -}}
+{{- $repeatedFootnoteBacklinksBad  :=  `<a href="#fnref([0-9]):([0-9]*)"(.*role="doc-backlink"(?:[^>]*)?)>([^<]*)` -}}
+{{- $repeatedFootnoteBacklinksGood :=  `<a href="#fnref${1}:${2}" aria-labelledby="bl-${2}-2"${3}>${4} <span id="bl-${2}-2" hidden>back to reference ${2}, instance 2</span>` -}}
 
-{{- .Content | replaceRE $referencesWithoutHeading $referencesWithHeading | replaceRE $badNoteRef $goodNoteRef | replaceRE $endnotesClosingDiv $endnotesClosingSection | replaceRE $tocHeadingOutside $tocHeadingInside | replaceRE $footnoteBacklinksBad $footnoteBacklinksGood | replaceRE $repeatedFootnoteBacklinksBad $repeatedFootnoteBacklinksGood | safeHTML -}}
+<!--Make endnotes focusable by ATs. Necessary for VoiceOver compatibility.-->
+{{- $endNotesNotFocusable := `<li id="fn:([0-9]*)">` -}}
+{{- $endNotesFocusable := `<li id="fn:${1}" tabindex="-1">` -}}
+
+
+{{- .Content | replaceRE $referencesWithoutHeading $referencesWithHeading | replaceRE $badNoteRef $goodNoteRef | replaceRE $endnotesClosingDiv $endnotesClosingSection | replaceRE $tocHeadingOutside $tocHeadingInside | replaceRE $footnoteBacklinksBad $footnoteBacklinksGood | replaceRE $repeatedFootnoteBacklinksBad $repeatedFootnoteBacklinksGood | replaceRE $endNotesNotFocusable $endNotesFocusable | safeHTML -}}
diff --git a/layouts/partials/webmentions.html b/layouts/partials/webmentions.html
index 932cf57..dbf9c27 100644
--- a/layouts/partials/webmentions.html
+++ b/layouts/partials/webmentions.html
@@ -1,48 +1,56 @@
 <section aria-labelledby="webmentions">
-		<h2 id="webmentions">Webmen&shy;tions</h2>
+		<h2 id="webmentions" tabindex="-1">Webmen&shy;tions</h2>
 		<p>This site supports <a href="https://indieweb.org/webmention">Webmentions</a>. Webmentions received for this post will appear below after I approve them. I sometimes send Webmentions to myself on behalf of linking sites that don't support them. Check the <a href="https://web.archive.org/">Wayback Machine</a> if any links are broken.</p>
-		<ul>
+		<dl>
 			{{- $target := .RelPermalink | replaceRE "^/~seirdy/" "/" }}
 			{{ $url := printf "https://seirdy.one/webmentions/get?status=approved&target=https://seirdy.one%s" $target -}}
 			{{ $webmentions := getJSON $url -}}
 			{{ range $webmentions -}}
 			{{ $webmention := . -}}
 				{{ if (eq $webmention.type "like") -}}
-				<li itemprop="potentialAction" itemscope itemtype="https://schema.org/LikeAction" class="u-like h-cite">
+				<div itemprop="potentialAction" itemscope itemtype="https://schema.org/LikeAction" class="u-like h-cite">
 				{{- else -}}
-				<li itemprop="comment" itemscope itemtype="https://schema.org/Comment">
-				{{- end }}
-				<p role="comment" class="u-comment h-cite">
-					<time class="dt-published" itemprop="{{ if (eq $webmention.type "like") -}}startTime{{ else }}datePublished{{ end }}" datetime="{{ dateFormat "2006-01-02 15:04:05Z07:00" $webmention.created_at }}">{{ dateFormat "2006-01-02" $webmention.created_at }}</time>
-					<br>
-					{{ if (eq $webmention.type "like") -}}
-						{{ if $webmention.author_name -}}
-							<span itemprop="agent" itemscope itemtype="https://schema.org/Person" class="h-card p-author vcard"><span itemprop="name" class="p-name fn n">{{ $webmention.author_name }}</span></span>
-						{{ else if $webmention.title -}}
-							<span itemprop="name" class="p-name">{{ $webmention.title -}}</span>
-						{{ else -}}
-							{{ $webmention.source -}}
-						{{ end -}}
-						<a class="u-url" href="{{ $webmention.source }}" rel="nofollow ugc">liked</a> this
-					{{ else -}}
-						<a class="u-url" href="{{ $webmention.source }}" rel="nofollow ugc">
-						<span itemprop="name" class="p-content p-name">
-							{{ if $webmention.title -}}
-								{{ $webmention.title | truncate 200 -}}
+				<div itemprop="comment" itemscope itemtype="https://schema.org/Comment" class="u-comment h-cite">
+				{{- end -}}
+				<!--Will eventually add role="comment" once WAI-ARIA 1.3 starts seeing some adoption.-->
+					<dt>
+						<time
+							class="dt-published"
+							itemprop="{{ if (eq $webmention.type "like") -}}startTime{{ else }}datePublished{{ end }}"
+							datetime="{{ dateFormat "2006-01-02 15:04:05Z07:00" $webmention.created_at }}">
+							{{ dateFormat "2006-01-02" $webmention.created_at }}
+						</time>
+					</dt>
+					<dd><p>
+						{{ if (eq $webmention.type "like") -}}
+							{{ if $webmention.author_name -}}
+								<span itemprop="agent" itemscope itemtype="https://schema.org/Person" class="h-card p-author vcard"><span itemprop="name" class="p-name fn n">{{ $webmention.author_name }}</span></span>
+							{{ else if $webmention.title -}}
+								<span itemprop="name" class="p-name">{{ $webmention.title -}}</span>
 							{{ else -}}
-								{{- $webmention.source | strings.TrimPrefix "https://" | strings.TrimPrefix "www." | strings.TrimRight "/" | truncate 35 -}}
-							{{ end }}
-						</span>
-					</a>
-						{{- if $webmention.author_name }}
-						by <span itemprop="author" itemscope itemtype="https://schema.org/Person" class="h-card p-author vcard"><span itemprop="name" class="p-name fn n">{{ $webmention.author_name }}</span></span>
-							{{- end -}}
-					{{- end }}
-				</p>
-			</li>
+								{{ $webmention.source -}}
+							{{ end -}}
+								<a class="u-url" itemprop="url" href="{{ $webmention.source }}" rel="nofollow ugc">liked</a> this
+						{{ else -}}
+							<a class="u-url" itemprop="url" href="{{ $webmention.source }}" rel="nofollow ugc">
+								<span itemprop="name" class="p-content p-name">
+									{{ if $webmention.title -}}
+										{{ $webmention.title | truncate 200 -}}
+									{{ else -}}
+										{{- $webmention.source | strings.TrimPrefix "https://" | strings.TrimPrefix "www." | strings.TrimRight "/" | truncate 35 -}}
+									{{ end }}
+								</span>
+							</a>
+							{{- if $webmention.author_name }}
+							by <span itemprop="author" itemscope itemtype="https://schema.org/Person" class="h-card p-author vcard"><span itemprop="name" class="p-name fn n">{{ $webmention.author_name }}</span></span>
+								{{- end -}}
+						{{- end }}
+					</p></dd>
+			</div>
 			{{ else -}}
-			<li><p>This post doesn't have any approved Webmentions yet.</p></li>
+			<dt>Nothing here</dt>
+			<dd>This post does not have any approved Webmentions yet.</dd>
 			{{- end }}
-		</ul>
+		</dl>
 		<p></p>
 	</section>
diff --git a/layouts/shortcodes/codecaption.html b/layouts/shortcodes/codecaption.html
index 0d88e35..aa655c0 100644
--- a/layouts/shortcodes/codecaption.html
+++ b/layouts/shortcodes/codecaption.html
@@ -9,7 +9,7 @@
 	{{- end -}}
 {{- end -}}
 <figcaption id="{{ $id }}-caption">
-	<span id="{{ $id }}">
+	<span id="{{ $id }}" tabindex="-1">
 	<strong itemprop="name"> <span itemprop="codeSampleType">Code snippet</span> {{ $codeIndex }}</strong>{{with .Get "lang"}} (<span itemprop="programmingLanguage">{{ . }}</span>){{ end -}}
 	</span>:
 {{ .Inner | markdownify | safeHTML }}
diff --git a/layouts/shortcodes/image-figure.html b/layouts/shortcodes/image-figure.html
index 2ad4316..7254986 100644
--- a/layouts/shortcodes/image-figure.html
+++ b/layouts/shortcodes/image-figure.html
@@ -1,5 +1,5 @@
 <figure itemscope itemtype="https://schema.org/ImageObject"
-	{{- with .Get "id" }} id="{{ . }}"{{ end -}}
+	{{- with .Get "id" }} id="{{ . }}" tabindex="-1"{{ end -}}
 	{{- if .Get "representative" }} itemprop="image">
 <meta itemprop="representativeOfPage" content="true">
 	{{- else }} itemprop="hasPart">
diff --git a/layouts/shortcodes/quotation.html b/layouts/shortcodes/quotation.html
index 236a1d7..cfb8f3f 100644
--- a/layouts/shortcodes/quotation.html
+++ b/layouts/shortcodes/quotation.html
@@ -2,6 +2,6 @@
 {{- with .Get "itemprop" -}}
 	{{- $itemprop = . -}}
 {{- end -}}
-<figure itemprop="{{ $itemprop }}"{{ with .Get "id" }} id="{{ . }}"{{ end }} itemscope itemtype="https://schema.org/Quotation">
+<figure itemprop="{{ $itemprop }}"{{ with .Get "id" }} id="{{ . }}" tabindex="-1"{{ end }} itemscope itemtype="https://schema.org/Quotation">
 {{ .Inner | markdownify }}
 </figure>
diff --git a/layouts/shortcodes/transcribed-image.html b/layouts/shortcodes/transcribed-image.html
index 3dc162f..88a7cc9 100644
--- a/layouts/shortcodes/transcribed-image.html
+++ b/layouts/shortcodes/transcribed-image.html
@@ -2,7 +2,6 @@
 {{- with .Get "type" -}}
 {{- $type = . -}}
 {{- end -}}
-
-<section aria-label="{{ $type }}, caption, and transcript" itemprop="mentions" itemscope itemtype="https://schema.org/ImageObject" id="{{ .Get "id" }}">
+<section aria-label="{{ $type }}, caption, and transcript" itemprop="mentions" itemscope itemtype="https://schema.org/ImageObject" id="{{ .Get "id" }}" tabindex="-1">
 {{ .Inner | markdownify | safeHTML }}
 </section>
diff --git a/linter-configs/vnu_filter.jq b/linter-configs/vnu_filter.jq
index 4da36dc..10154b1 100644
--- a/linter-configs/vnu_filter.jq
+++ b/linter-configs/vnu_filter.jq
@@ -14,11 +14,6 @@
 				and .firstColumn == 1
 				and (.extract | test(" name=\"theme-color\""))
 			)
-			or
-			( # See https://w3c.github.io/aria/#comment
-				.message == "Bad value “comment” for attribute “role” on element “p”."
-				and (.extract | test("u-comment"))
-			)
 		) | not
 	)
 )