diff --git a/docs/architecture-decisions/0005-implement-an-accessible-navigation-system.md b/docs/architecture-decisions/0005-implement-an-accessible-navigation-system.md new file mode 100644 index 00000000..59d7f454 --- /dev/null +++ b/docs/architecture-decisions/0005-implement-an-accessible-navigation-system.md @@ -0,0 +1,223 @@ +# 5. Using SmartMenus 1 for navigation menus + +Date: 2024-03-22 + +## Status + +Accepted + +## Context + +Our initial releases of this theme use the [SmartMenus](https://www.smartmenus.org/) library to build its +navigation menus. While this library is easy to implement and pretty useful, its +output was flagged during usability and accessibility testing as needing some +improvements. + +The problem is that, for users relying on a keyboard or a screen reader to +navigate the platform, attempting to close a submenu in the navigation also +causes the user follow the link to the submenu's parent page. + +The markup which the user interacts with looks like this: + +```html + +``` + +The issue is that the element triggering the flyout menu (the +`` tag on line six above) is _inside_ the anchor +element, making it challenging for users relying on screen readers or keyboard +navigation to get around an exhibit. While it is possible to open all of the +submenus like this, attempting to close a submenu gets intercepted by the +containing anchor element, resulting in an unintentional navigation to that +page. + +Omeka provides other ways to get around an exhibit - for example the Next and +Previous buttons on all pages, and individual pages can also provide blocks of +links to their child pages. As a result, we believe that Omeka is still usable +by users who rely on these technologies - but this is a bug which should be +prioritized for resolution. + +The current release of SmartMenus (1.2.1) does not support placing this toggle +element outside of the link element, so it will be necessary to replace it with +a library which does support this behavior. We have evaluated several options +for resolving this issue: + + +### Option 1: SmartMenus 2 + +The maintainer for SmartMenus is aware of this problem in the library, as we and +others have reported it via GitHub (see [issue 204](https://github.com/vadikom/smartmenus/issues/204) and [issue 231](https://github.com/vadikom/smartmenus/issues/231)). He has +committed to including this as an improvement in the future release of +SmartMenus 2, and the documentation already available [includes this among its +available features](https://configurator.smartmenus.org/). + +However, at the time of writing [SmartMenus 2 is only available via one alpha +release](https://github.com/vadikom/smartmenus/releases) - and the maintainer has [cautioned us against using it in a production +system yet](https://github.com/vadikom/smartmenus/issues/245). + +* Pros: Just upgrading our existing menu library as it improves over time is a + good philosophy to follow. + +* Cons: The timeline for the release of SmartMenus 2 is not clear, and cannot + be guaranteed to happen. Additionally, the significant changes to the library + with version 2 will likely require a significant level of effort - so the + benefits of a simple upgrade may not accrue based on the materials published + so far. + + +### Option 2: Accessible Menu + +One alternative to SmartMenus is the [Accessible Menu](https://accessible-menu.dev/) library, which takes as its +starting point the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) for navigation menus. One of +the supported patterns is the [Disclosure Navigation Menu with Top-Level Links](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation-hybrid/), +which includes the needed separation between navigation links and submenu +toggles. + +While the provided example includes this separation only at the top level of the +menu, the pattern can be extended to all levels - [as demonstrated in this +CodePen](https://codepen.io/matt-bernhardt/pen/poBRKrY). + +#### Benefits of Accessible Menu + +This menu, when properly configured, appears to implement all the best practices +for an accessible navigation menu for web application. + +#### Drawbacks of Accessible Menu + +There are several significant drawbacks to using this menu library. + +* The most significant drawback is that it imposes some operating costs on users + of assistive technology that are not ideal. The library forces the screen + reader user to explicitly switch operating mode to interact with the menu, and + does not listen for the type of interaction events which users naturally + generate while navigating a page. + + > However, the library is not listening for click events; it seems they are + > only listening for explicit pointer events. This means you need to switch + > into forms mode, then press enter or space, to activate a menu ... It also + > seems they are handling keyboard events explicitly for keys that should + > normally be handled by the browser like tab and shift+tab. + + (The above comment comes from [our discussion of the navigation menu after + accessibility testing](https://github.mit.edu/Accessibility-FY2024/omeka/issues/4#issuecomment-182190).) + +* The markup requirements for this library do not immediately align with the + markup generated by Omeka. While this is manageable by either maintaining a + set of custom navigation templates (which other themes also do) or by writing + some javascript to manipulate the DOM prior to instantiating the menu, it does + mean that using this library increases the maintenance burden of the theme. + +* The library is javascript-only, and is not distributed with any CSS rules. + While we can develop and maintain these rules ourselves, it makes this library + less of a turnkey solution. + + +### Option 3: CSS-only menu libraries + +A third option would be to pursue a "pure CSS" navigation menu, which can be +found described in [several](https://purecss.io/menus/) [places](https://devsnap.me/css-menu) around the web. + +* Pros: A navigation menu which uses only CSS styles is technically much + simpler, lacking the javascript that would need to be maintained (either by + ourselves or by a dependency maintainer). + +* Cons: [These types of navigation systems are likely not going to be fully + accessible](https://moderncss.dev/css-only-accessible-dropdown-navigation-menu/). There are elements of the WCAG standards which cannot be satisfied + by stylesheets alone. An example is [WCAG 1.4.13](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html), which requires that revealed + content like a submenu must be dismissable without changing the focus on a + page. + + +### Option 4: A bespoke solution + +While attempting to implement the Accessible Menu library, we asked for feedback +about our progress from Rich Caloggero, who was involved in our earlier +accessibility testing. Rich helpfully assembled a [mockup](https://richcaloggero.github.io/tools/createNavigation.html) demonstrating a usable +navigation system with very little javascript (and no stylesheets). + +#### Benefits of a bespoke approach + +The amount of javascript which is needed is potentially very, very small. The +initial snippet which Rich provided was just this: + +```js +$submenus = document.querySelectorAll("nav ul ul"); +$submenus.forEach(x => x.setAttribute("hidden", "")); +$nav.removeEventListener("click", clickHandler); +$nav.addEventListener("click", clickHandler); + +function clickHandler (e) { +if (e.target instanceof HTMLButtonElement) { +e.preventDefault(); +const menu = e.target.parentElement instanceof HTMLLIElement? e.target.nextElementSibling : e.target.parentElement.nextElementSibling; +menu.hidden = not(menu.hidden); +e.target.setAttribute("aria-expanded", menu.hidden? "false" : "true"); +} // if +} // clickHandler +``` + +If we choose HTML elements which bring native functionality (`button`, `a`, and +header tags, for example) then we not only need less javascript but we are more +likely to match functionality which users are already familiar with using. The +only conceptual need we are solving is how to expand and collapse a submenu - +everything else is already present. + +The styling rules required for this approach should likewise be minimal. + +#### Drawbacks of a bespoke approach + +While conceptually simple, the bespoke approach proved to be beyond our +current bandwidth by the time all the use cases were resolved. + +We attempted to develop a bespoke navigation library for this theme, starting +from the code which Rich shared. The result of those efforts can be found on +the [post-107-bespoke](https://github.com/MITLibraries/mitlibraries-theme-omeka/tree/post-107-bespoke) branch of this repository. + +Follow-up testing showed that the solution was more suitable for users who rely +on assistive technologies, but the interaction needs for sighted and desktop +users were not adequately met in the available timeframe. + + +## Decision: Keep using SmartMenus 1, at least for now + +With the failure of option 4 to coalesce into a generally suitable solution in +the time available, we are choosing to continue using SmartMenus 1, at least in +the short term. + +We will continue to watch for future releases of SmartMenus which may resolve +this problem. This work has also identified the need for a general navigation +solution within [our style library](https://mitlibraries.github.io/mitlib-style/), which could provide an opportunity for us to +return to this problem space and devote additional time to finishing the bespoke +approach. + +The remaining items that need to be resolved have been noted in that branch, in +the form of a [punch list](https://github.com/MITLibraries/mitlibraries-theme-omeka/blob/post-107-bespoke/docs/navigation-notes.md) that was maintained during the initial development. + + +## Consequences + +The usability of our digital exhibits platform is less straightforward than we +want it to be. + +The theme applied to this platform remains somewhat simpler without a bespoke +navigation system that would need ongoing maintenance. + +Our organization as a whole continues to not have a navigation menu as part of +its style library. As a result, our various platforms with navigation menus all +implement their own approaches to a shared problem.