a11y - provide callout type in screen-reader-only class when needed.

news/changelog-1.8.md

@@ -10,7 +10,8 @@ All changes included in 1.8:
 
 ### `html`
 
-- ([#678](https://github.com/quarto-dev/quarto-cli/issues/678)): Provide appropriate `aria-label` to search button.
+- ([#678](https://github.com/quarto-dev/quarto-cli/issues/678)): a11y - Provide appropriate `aria-label` to search button.
+- ([#726](https://github.com/quarto-dev/quarto-cli/issues/726)): a11y - Provide `.screen-reader-only` callout type when callout text doesn't naturally include the type.
 - ([#10983](https://github.com/quarto-dev/quarto-cli/issues/10983)): Fix spacing inconsistency between paras and first section headings.
 - ([#12259](https://github.com/quarto-dev/quarto-cli/issues/12259)): Fix conflict between `html-math-method: katex` and crossref popups (author: @benkeks).
 - ([#12734](https://github.com/quarto-dev/quarto-cli/issues/12734)): `highlight-style` now correctly supports setting a different `light` and `dark`.

src/resources/filters/modules/callouts.lua

@@ -191,6 +191,11 @@ local calloutidx = 1
 local function calloutDiv(node)
   node = decorate_callout_title_with_crossref(node)
 
+  local needs_screen_reader_callout_type = true
+  if is_valid_ref_type(refType(node.attr.identifier)) then
+    needs_screen_reader_callout_type = false
+  end
+
   -- the first heading is the title
   local div = pandoc.Div({})
   local c = quarto.utils.as_blocks(node.content)
@@ -218,6 +223,7 @@ local function calloutDiv(node)
 
   if calloutAppearance == _quarto.modules.constants.kCalloutAppearanceDefault and pandoc.utils.stringify(title) == "" and not found then
     title = quarto.utils.as_inlines(pandoc.Plain(displayName(node.type)))
+    needs_screen_reader_callout_type = false
   end
 
   -- Make an outer card div and transfer classes and id
@@ -262,6 +268,12 @@ local function calloutDiv(node)
   -- show a titled callout
   if title ~= nil and (pandoc.utils.type(title) == "string" or next(title) ~= nil) then
 
+    if needs_screen_reader_callout_type then
+      -- add a screen reader callout type
+      local srCalloutType = pandoc.Span(pandoc.Str(displayName(callout_type)))
+      srCalloutType.attr.classes:insert("screen-reader-only")
+      title:insert(1, srCalloutType)
+    end
     -- mark the callout as being titleed
     calloutDiv.attr.classes:insert("callout-titled")
 

src/resources/formats/html/bootstrap/_bootstrap-rules.scss

@@ -2192,3 +2192,15 @@ a {
   font-weight: $link-weight;
   text-decoration: $link-decoration;
 }
+
+// screen-reader-only, cf https://github.com/quarto-dev/quarto-cli/issues/726#issuecomment-1112486100
+.screen-reader-only {
+    position: absolute;
+    clip: rect(0 0 0 0);
+    border: 0;
+    height: 1px;
+    margin: -1px;
+    overflow: hidden;
+    padding: 0;
+    width: 1px;
+}

tests/docs/smoke-all/2024/05/16/9701.qmd

@@ -5,7 +5,7 @@ _quarto:
     html:
       ensureFileRegexMatches:
         - []
-        - ["Note"]
+        - ["Note\\s+</div>"]
 ---
 
 ::: {.callout-note icon=false}

tests/docs/smoke-all/callouts/a11y/issue-726.qmd

@@ -0,0 +1,17 @@
+---
+format: html
+title: Hello
+_quarto:
+  tests:
+    html:
+      ensureHtmlElements:
+        - [div.callout.callout-note div.callout-title-container span.screen-reader-only]
+---
+
+::: callout-note
+
+## Title
+
+This is a callout.
+
+:::