Make scrollable code blocks and cell output keyboard-focusable in HTML output

[cwickham]

Closes #14378. Part of #8706.

What this does

A code block or cell output that overflows is scrollable, but keyboard users cannot reach or scroll it in Safari. Chrome and Firefox already make such regions focusable natively, so this is a Safari gap for users and a missing accessible name everywhere. axe reports scrollable-region-focusable (serious, WCAG 2.1.1/2.1.3) in all three, because it reads markup rather than browser behavior. Compatibility under Design notes has the detail.

This adds a runtime module to quarto.js, for bootstrap HTML formats only. While a region overflows it gets tabindex="0", role="group", a localized aria-label, and a data-quarto-scrollable marker so removal only touches attributes we added. The attributes come off when the region fits again. The sync runs on DOMContentLoaded and from the existing body ResizeObserver, so it adds no new observers. That observer's throttle now also makes a trailing call, so the last resize of a burst is synced. The margin layout and the reader-mode check share that callback, so they get the fix too. The TOC and sidebar scroll handlers keep the old leading-edge-only throttle.

The candidates are the three scroll containers in rendered HTML:

Candidate	Overflow source
div.sourceCode	Pandoc's div.sourceCode { overflow: auto } for highlighted code
pre	Bootstrap reboot's pre { overflow: auto }
.cell-output-display:not(.no-overflow-x)	_quarto-rules.scss

Which regions get marked

A region qualifies when its computed overflow is auto or scroll, which is axe's own condition, and it overflows by more than 1px. Three kinds of region are skipped:

• Author markup, meaning an existing tabindex or aria-label.
• No usable size: a closed <details>, an inactive tab pane, or a visually-hidden code alternative. The last is clipped to 1px, which makes its content height read as overflow. Marking it would add an invisible tab stop, and quarto-web's get-started pages carry about nine each.
• Real focusable content, such as a link in a wide table, which the browser already scrolls into view.

Pandoc's line anchors are the exception to that third rule. Without line numbers they carry tabindex="-1", so they are out of the tab order anyway. With line numbers they are real focusable links, kept that way on purpose by #14655. But each one sits at the start of its line, so focusing it leaves scrollLeft at 0 and the clipped content unreachable. A numbered block therefore satisfies axe while staying unscrollable, so it gets its own region tab stop alongside its per-line links.

When it re-syncs

One rule, not one per widget: the module re-syncs when the page's layout changes size. Collapsed callouts, folded <details>, and tab panes of differing heights all make the page taller, so a single ResizeObserver covers them with no mechanism-specific code.

The boundary is a reveal that changes no size, and two tab panes of equal height are the clean example. That case keeps today's behavior rather than regressing anything. A shown.bs.tab hook would fix tabsets while still missing equal-height accordions and overlay panels, trading one documented boundary for a special case plus a boundary.

Design notes

Runtime JS, not a static tabindex. A Lua filter would put a tab stop on every code block, whether or not it scrolls. It would also change the markup of every code block, which breaks scrapers and element-level snapshot tests. Here the element markup stays unchanged. Each page does gain one short script that carries the labels (see Labels), so a snapshot of the whole page still sees a diff.

Compatibility. Chrome (since 132, January 2025) and Firefox already make these regions focusable natively (Chrome blog). These tab stops have therefore been live on every Quarto site for over a year, with no reports. That bounds the risk: this polyfills shipped browser behavior rather than inventing a new interaction. What it adds on top is Safari coverage, an accessible name, and axe conformance. Every failure mode leaves an element exactly as it is today.

Labels. Two new language keys, scrollable-code-label and scrollable-output-label. quarto.js is static, so the after-body script passes the resolved strings through a window global. The module falls back to the English defaults.

role="group", not region. Pages carry many code blocks, and region landmarks would flood the screen-reader rotor.

Tests

• 15 unit tests (tests/unit/scrollable-regions.test.ts): overflow geometry, usable size, the focusable-content rule, label merging.
• 16 Playwright tests (tests/integration/playwright/tests/html-scrollable-regions.spec.ts) on chromium, firefox, and webkit: marking and removal across viewports, the last resize of a burst, the three skips, one tab stop per block, real-Tab reach with a visible focus ring, and arrow-key scrolling. A second fixture (scrollable-regions-labels.qmd) checks that a lang: fr label and a language: override holding </script> both reach aria-label intact. Arrow keys are asserted on chromium and firefox only, because Playwright's WebKit routes them to the page even when a scroller has focus.
• axe-accessibility still passes (116 tests), with its code-line-number fixtures re-rendered.
• On quarto-web pages rendered with this build, the violations on about.html (#cb1) and docs/troubleshooting/index.html (bare pre) are gone, and axe reports none for the rule at 390x844.
• A full sync costs 0.6ms median on a 200-block page (400 candidates), against the existing 50ms throttle.

Checklist

I have (if applicable):

• referenced the GitHub issue this PR closes
• updated the appropriate changelog in the PR
• ensured the present test suite passes (the suites listed above; not the full matrix)
• added new tests
• created a separate documentation PR in Quarto's website repo and linked it to this PR

AI-assisted PR

• AI tool used: Claude Code
• Codebase grounding: local clone
• Human review: I have reviewed, tested, and verified the AI-generated content before submitting.

[cwickham]

Filed #14817 for the revealjs side, which this PR does not cover. Same axe rule, different target: there the scroll container is .reveal pre code rather than div.sourceCode, and axe stays silent because revealjs enables code line numbers by default.

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[cderv]

Nice piece of work, thorough tests and design write-up. Left a few inline comments on things worth fixing before merge.

Two are real correctness issues in scrollable-regions.js: disabled controls are currently counted as focusable content, so a region whose only focusable descendant is a disabled button/input skips its tab stop entirely. And the guard meant to respect author markup checks tabindex/aria-label but not role, so an author-set role gets overwritten then stripped once the region stops overflowing.

There's also a stale-state case: cleanup correctly skips a focused region, but nothing reruns it once focus leaves, so tabindex/role/aria-label can stick around until the next unrelated resize.

Last one is smaller: the two new _language.yml keys are English-only. That's legal, we did the same for #14376, but #14684 already raised the bar by shipping major-locale translations in the same PR, and #14822 exists because we keep letting this drift. Could we add at least the major locales here rather than leaning on #14822 to backfill?

[cderv]

kFocusableSelector doesn't exclude disabled controls. button:disabled, input:disabled, etc. aren't in the tab order, so hasFocusableContent returns true for a region whose only "focusable" descendant is a disabled control, and syncScrollableRegions skips adding a tab stop there. The region ends up scrollable but unreachable by keyboard. Add :not(:disabled) to the button/input/select/textarea clauses.

[cderv]

The skip guard (lines 110–116) checks tabindex and aria-label but not role. An element with an author-set role (e.g. <pre role="log">) isn't skipped here: it gets role="group" overwritten at line 119, then role is stripped entirely at line 128 once the region stops overflowing. That contradicts the comment above kMarker at the top of the file ("removal never touches author markup") for this one attribute. Add role to the skip condition, or save/restore the original value instead of unconditionally removing it.

[cderv]

Cleanup is skipped while el === document.activeElement (line 125), which avoids pulling attributes out from under focused content mid-interaction — reasonable. But nothing reruns the check once focus leaves that element. Sequence: Tab into a scrollable region, resize so it no longer overflows, Tab away. tabindex, role, aria-label, and the marker all stay stale until the next unrelated resize or reload. Worth a focusout listener on marked regions that reruns syncScrollableRegions (or just the check for that one element) once focus leaves.

[cderv]

These two keys only exist in the English _language.yml — none of the 33 locale files got them. That's ok (precedent: #14376 added nav-landmark labels English-only) but it's the exact drift #14822 was filed to track, and the more recent #14684 (skip-to-content link) already raised the bar by shipping translations for the major locales (de/es/fr/it/ja/nl/pt/pt-BR/zh/zh-TW) in the same PR. Worth adding at least those before merge rather than leaning on #14822 to backfill later — it's aria-label-only text, so translation cost is two short strings per locale, not a big lift.

[cwickham]

@cderv Thanks — all four are in.

Disabled controls. :not(:disabled) now sits on the button, input, select and textarea clauses, and on the generic [tabindex] one, which also catches <button disabled tabindex="0">. It matches only form controls, so it is inert elsewhere.

Author role. I added role to the skip guard rather than save and restore it. That makes the guard uniform: any of tabindex, role or aria-label means the author has taken control, so the runtime leaves the element alone. A <pre role="log"> that overflows keeps its role and gets no tab stop, and Chrome and Firefox still focus it natively.

Stale state. Cleanup now attaches a one-shot focusout listener to a region it had to skip, and re-runs the sync when focus leaves. A WeakSet stops repeat syncs stacking listeners on one element.

Three new Playwright cases cover these, green on all three engines.

Language keys. All 34 locale files now carry both keys (fr-CA is a three-key overlay on fr, so it is skipped — the set #14376 covered). "Scrollable" comes from Firefox DevTools' tooltip for an element with scrollable overflow, code from each file's own code-summary, and output from LibreOffice Base's Direct SQL dialog, where it labels the results of the command you ran.

This is weaker than #14376, where 134 of 165 cells were attested strings used verbatim. Every value here is a phrase assembled from two attested parts, so all 68 name their sources and end needs review. Six locales have no attested word for "scrollable" at all — az, fi, is, nb, nn, sr-Latn — and each says so on its own line.

grep -rn 'needs review' src/resources/language/

Three extra commits you did not ask for.

The labels reach the page through JSON.stringify in the after-body template, which escapes quotes but not </script>, so a label holding one closed the script element early. < is now escaped to \u003c. A new lang: fr fixture has a language: override that holds </script>, and it checks that both labels reach aria-label intact.

The body ResizeObserver's throttle only ran on the leading edge, so a resize that ended inside the 50ms wait was never synced. It now also runs once at the end of a burst, for that observer only. layoutMarginEls() and the reader-mode check share the callback, so they get the fix too. The TOC and sidebar scroll handlers are unchanged.

I also merged main.