').append(menuItems); - const $items = $wrapper.find('> .item'); - $items.each((_, item) => prepareMenuItem($(item))); - return $wrapper.html(); - }; - $dropdown.dropdown('setting', 'templates', dropdownTemplates); - - // use tooltip's content as aria-label if there is no aria-label - if ($dropdown.hasClass('tooltip') && $dropdown.attr('data-content') && !$dropdown.attr('aria-label')) { - $dropdown.attr('aria-label', $dropdown.attr('data-content')); - } - - // prepare dropdown menu list popup - const $menu = $dropdown.find('> .menu'); - if (!$menu.attr('id')) $menu.attr('id', generateAriaId()); - $menu.find('> .item').each((_, item) => { - prepareMenuItem($(item)); - }); - // this role could only be changed after its content is ready, otherwise some browsers+readers (like Chrome+AppleVoice) crash - $menu.attr('role', listPopupRole); - - // make the primary element (focusable) aria-friendly - $focusable.attr({ - 'role': $focusable.attr('role') ?? focusableRole, - 'aria-haspopup': listPopupRole, - 'aria-controls': $menu.attr('id'), - 'aria-expanded': 'false', - }); - - // when showing, it has class: ".animating.in" - // when hiding, it has class: ".visible.animating.out" - const isMenuVisible = () => ($menu.hasClass('visible') && !$menu.hasClass('out')) || $menu.hasClass('in'); - - // update aria attributes according to current active/selected item - const refreshAria = () => { - const menuVisible = isMenuVisible(); - $focusable.attr('aria-expanded', menuVisible ? 'true' : 'false'); - - // if there is an active item, use it (the user is navigating between items) - // otherwise use the "selected" for combobox (for the last selected item) - const $active = $menu.find('> .item.active, > .item.selected'); - // if the popup is visible and has an active/selected item, use its id as aria-activedescendant - if (menuVisible) { - $focusable.attr('aria-activedescendant', $active.attr('id')); - } else if (!isComboBox) { - // for menu, when the popup is hidden, no need to keep the aria-activedescendant, and clear the active/selected item - $focusable.removeAttr('aria-activedescendant'); - $active.removeClass('active').removeClass('selected'); - } - }; - - $dropdown.on('keydown', (e) => { - // here it must use keydown event before dropdown's keyup handler, otherwise there is no Enter event in our keyup handler - if (e.key === 'Enter') { - let $item = $dropdown.dropdown('get item', $dropdown.dropdown('get value')); - if (!$item) $item = $menu.find('> .item.selected'); // when dropdown filters items by input, there is no "value", so query the "selected" item - // if the selected item is clickable, then trigger the click event. - // we can not click any item without check, because Fomantic code might also handle the Enter event. that would result in double click. - if ($item && ($item.is('a') || $item.hasClass('js-aria-clickable'))) $item[0].click(); - } - }); - - // use setTimeout to run the refreshAria in next tick (to make sure the Fomantic UI code has finished its work) - // do not return any value, jQuery has return-value related behaviors. - // when the popup is hiding, it's better to have a small "delay", because there is a Fomantic UI animation - // without the delay for hiding, the UI will be somewhat laggy and sometimes may get stuck in the animation. - const deferredRefreshAria = (delay = 0) => { setTimeout(refreshAria, delay) }; - $dropdown.on('keyup', (e) => { if (e.key.startsWith('Arrow')) deferredRefreshAria(); }); - - // if the dropdown has been opened by focus, do not trigger the next click event again. - // otherwise the dropdown will be closed immediately, especially on Android with TalkBack - // * desktop event sequence: mousedown -> focus -> mouseup -> click - // * mobile event sequence: focus -> mousedown -> mouseup -> click - // Fomantic may stop propagation of blur event, use capture to make sure we can still get the event - let ignoreClickPreEvents = 0, ignoreClickPreVisible = 0; - $dropdown[0].addEventListener('mousedown', () => { - ignoreClickPreVisible += isMenuVisible() ? 1 : 0; - ignoreClickPreEvents++; - }, true); - $dropdown[0].addEventListener('focus', () => { - ignoreClickPreVisible += isMenuVisible() ? 1 : 0; - ignoreClickPreEvents++; - deferredRefreshAria(); - }, true); - $dropdown[0].addEventListener('blur', () => { - ignoreClickPreVisible = ignoreClickPreEvents = 0; - deferredRefreshAria(100); - }, true); - $dropdown[0].addEventListener('mouseup', () => { - setTimeout(() => { - ignoreClickPreVisible = ignoreClickPreEvents = 0; - deferredRefreshAria(100); - }, 0); - }, true); - $dropdown[0].addEventListener('click', (e) => { - if (isMenuVisible() && - ignoreClickPreVisible !== 2 && // dropdown is switch from invisible to visible - ignoreClickPreEvents === 2 // the click event is related to mousedown+focus - ) { - e.stopPropagation(); // if the dropdown menu has been opened by focus, do not trigger the next click event again - } - ignoreClickPreEvents = ignoreClickPreVisible = 0; - }, true); -} - -export function attachDropdownAria($dropdowns) { - $dropdowns.each((_, e) => attachOneDropdownAria($(e))); -} - -export function attachCheckboxAria($checkboxes) { - $checkboxes.checkbox(); - - // Fomantic UI checkbox needs to be something like:

- // It doesn't work well with ... - // To make it work with aria, the "id"/"for" attributes are necessary, so add them automatically if missing. - // In the future, refactor to use native checkbox directly, then this patch could be removed. - for (const el of $checkboxes) { - const label = el.querySelector('label'); - const input = el.querySelector('input'); - if (!label || !input || input.getAttribute('id')) continue; - const id = generateAriaId(); - input.setAttribute('id', id); - label.setAttribute('for', id); - } -} diff --git a/web_src/js/features/aria.md b/web_src/js/features/aria.md deleted file mode 100644 index 679cec774c..0000000000 --- a/web_src/js/features/aria.md +++ /dev/null @@ -1,116 +0,0 @@ -# Background - -This document is used as aria/accessibility(a11y) reference for future developers. - -There are a lot of a11y problems in the Fomantic UI library. This `aria.js` is used -as a workaround to make the UI more accessible. - -The `aria.js` is designed to avoid touching the official Fomantic UI library, -and to be as independent as possible, so it can be easily modified/removed in the future. - -To test the aria/accessibility with screen readers, developers can use the following steps: - -* On macOS, you can use VoiceOver. - * Press `Command + F5` to turn on VoiceOver. - * Try to operate the UI with keyboard-only. - * Use Tab/Shift+Tab to switch focus between elements. - * Arrow keys to navigate between menu/combobox items (only aria-active, not really focused). - * Press Enter to trigger the aria-active element. -* On Android, you can use TalkBack. - * Go to Settings -> Accessibility -> TalkBack, turn it on. - * Long-press or press+swipe to switch the aria-active element (not really focused). - * Double-tap means old single-tap on the aria-active element. - * Double-finger swipe means old single-finger swipe. -* TODO: on Windows, on Linux, on iOS - -# Checkbox - -## Accessibility-friendly Checkbox - -The ideal checkboxes should be: - -```html - ... -``` - -However, related CSS styles aren't supported (not implemented) yet, so at the moment, -almost all the checkboxes are still using Fomantic UI checkbox. - -## Fomantic UI Checkbox - -```html -

- - ... -

-``` - -Then the JS `$.checkbox()` should be called to make it work with keyboard and label-clicking, -then it works like the ideal checkboxes. - -There is still a problem: Fomantic UI checkbox is not friendly to screen readers, -so we add IDs to all the Fomantic UI checkboxes automatically by JS. -If the `label` part is empty, then the checkbox needs to get the `aria-label` attribute manually. - -# Dropdown - -## Fomantic UI Dropdown - -Fomantic Dropdown is designed to be used for many purposes: - -* Menu (the profile menu in navbar, the language menu in footer) -* Popup (the branch/tag panel, the review box) -* Simple ` -

Default

- -