Proposal: WCAG 2.2 AA–compliant glossary with accessible click popovers (Bootstrap/Quarto)

[maehr]

Summary
I propose upstreaming an accessibility-focused refactor that replaces custom hover popups with keyboard- and screen-reader friendly click popovers, implemented via Quarto’s built-in Bootstrap 5 Popover API. This aligns with WCAG 2.2 AA, and simplifies maintenance. See reference implementation.

Motivation

• WCAG 2.2 adds new AA criteria that affect interactive glossary triggers, notably Focus Not Obscured and Target Size (Minimum). Click activation with clear focus management reduces failure modes common to hover-only UIs (WCAG 2.2).
• Using Quarto’s bundled Bootstrap avoids re-implementing ARIA state and behavior (Quarto docs).

Proposed change

• Replace custom ARIA/JS hover popups with Bootstrap popovers initialized on demand.
• Minimal Lua changes emit data-bs-toggle="popover" and data-bs-content for terms; small CSS keeps focus visibility and placement sane.
• Default interaction: click to open, Escape or outside click to close, tab order preserved, screen readers announce title/content via Bootstrap semantics.

User-facing behavior

• Glossary terms remain inline. Activation shifts from hover to click/tap by default, which is more robust on touch and meets WCAG 2.2 target-size expectations. Spacing or padding can satisfy small inline targets when needed.
• Optional config could expose placement and trigger for projects that need hover on wide screens while keeping click on touch.

Implementation notes

• Quarto/Bootstrap are already present in HTML output; no new dependencies.

Testing

• Keyboard: Tab/Shift-Tab navigation to term, Enter/Space toggles popover, Escape closes, focus returns to trigger.
• Screen readers: NVDA/JAWS/VoiceOver announce trigger and popover content.
• Automated: axe-core/Lighthouse checks pass for popover states.
• Pointer targets: verify 24×24 CSS px minimum or spacing exception for dense inline text (WCAG 2.2 target-size).

Compatibility

• No breaking changes to authoring flow. Existing glossaries render; interaction improves.
• Where hover is desired, maintainers can expose an opt-in trigger="hover focus" variant while keeping click as the accessible default (Bootstrap popovers).

Request
If maintainers agree with the direction, I will open a PR against debruine/quarto-glossary with the minimal patch, tests, and documentation.

[maehr]

I've also implemented a fallback solution for docx and pdf documents. This ensures that glossary terms render appropriately even in non-HTML outputs. For details, please see the most recent commit in maehr/quarto-glossary (4ccfe41).