Use a general approch to improve a11y for all checkboxes and dropdowns.

options/locale/locale_en-US.ini

@@ -84,6 +84,7 @@ add = Add
 add_all = Add All
 remove = Remove
 remove_all = Remove All
+remove_label_str = Remove item "%s"
 edit = Edit
 
 enabled = Enabled

templates/base/head_script.tmpl

@@ -41,6 +41,7 @@ If you introduce mistakes in it, Gitea JavaScript code wouldn't run correctly.
 			copy_error: '{{.locale.Tr "copy_error"}}',
 			error_occurred: '{{.locale.Tr "error.occurred"}}',
 			network_error: '{{.locale.Tr "error.network_error"}}',
+			remove_label_str: '{{.locale.Tr "remove_label_str"}}',
 		},
 	};
 	{{/* in case some pages don't render the pageData, we make sure it is an object to prevent null access */}}

web_src/js/features/aria-base.js

@@ -0,0 +1,7 @@
+export const ariaPatchKey = '_giteaAriaPatch';
+
+let ariaIdCounter = 0;
+
+export function generateAriaId() {
+  return `_aria_auto_id_${ariaIdCounter++}`;
+}

web_src/js/features/aria-checkbox.js

@@ -0,0 +1,37 @@
+import $ from 'jquery';
+import {ariaPatchKey, generateAriaId} from './aria-base.js';
+
+const fomanticCheckboxFn = $.fn.checkbox;
+
+// use our own `$.fn.checkbox` to patch Fomantic's checkbox module
+export function initAriaCheckboxPatch() {
+  if ($.fn.checkbox === ariaCheckboxFn) throw new Error('initAriaCheckboxPatch could only be called once');
+  $.fn.checkbox = ariaCheckboxFn;
+  ariaCheckboxFn.settings = fomanticCheckboxFn.settings;
+}
+
+// the patched `$.fn.checkbox` checkbox function
+// * it does the one-time attaching on the first call
+function ariaCheckboxFn(...args) {
+  const ret = fomanticCheckboxFn.apply(this, args);
+  for (const el of this) {
+    if (el[ariaPatchKey]) continue;
+    attachInit(el);
+  }
+  return ret;
+}
+
+function attachInit(el) {
+  // Fomantic UI checkbox needs to be something like: <div class="ui checkbox"><label /><input /></div>
+  // It doesn't work well with <label><input />...</label>
+  // 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.
+  el[ariaPatchKey] = {}; // record that this element has been patched
+  const label = el.querySelector('label');
+  const input = el.querySelector('input');
+  if (!label || !input || input.getAttribute('id')) return;
+
+  const id = generateAriaId();
+  input.setAttribute('id', id);
+  label.setAttribute('for', id);
+}

web_src/js/features/aria.js → web_src/js/features/aria-dropdown.js

@@ -1,14 +1,115 @@
 import $ from 'jquery';
+import {ariaPatchKey, generateAriaId} from './aria-base.js';
 
-let ariaIdCounter = 0;
+const fomanticDropdownFn = $.fn.dropdown;
 
-function generateAriaId() {
-  return `_aria_auto_id_${ariaIdCounter++}`;
+// use our own `$().dropdown` function to patch Fomantic's dropdown module
+export function initAriaDropdownPatch() {
+  if ($.fn.dropdown === ariaDropdownFn) throw new Error('initAriaDropdownPatch could only be called once');
+  $.fn.dropdown = ariaDropdownFn;
+  ariaDropdownFn.settings = fomanticDropdownFn.settings;
 }
 
-function attachOneDropdownAria($dropdown) {
-  if ($dropdown.attr('data-aria-attached') || $dropdown.hasClass('custom')) return;
-  $dropdown.attr('data-aria-attached', 1);
+// the patched `$.fn.dropdown` function, it passes the arguments to Fomantic's `$.fn.dropdown` function, and:
+// * it does the one-time attaching on the first call
+// * it delegates the `onLabelCreate` to the patched `onLabelCreate` to add necessary aria attributes
+function ariaDropdownFn(...args) {
+  const ret = fomanticDropdownFn.apply(this, args);
+
+  // if the `$().dropdown()` call is without arguments, or it has non-string (object) argument,
+  // it means that this call will reset the dropdown internal settings, then we need to re-delegate the callbacks.
+  const needDelegate = (!args.length || typeof args[0] !== 'string');
+  for (const el of this) {
+    const $dropdown = $(el);
+    if (!el[ariaPatchKey]) {
+      attachInit($dropdown);
+    }
+    if (needDelegate) {
+      delegateOne($dropdown);
+    }
+  }
+  return ret;
+}
+
+// make the item has role=option/menuitem, add an id if there wasn't one yet, make items as non-focusable
+// the elements inside the dropdown menu item should not be focusable, the focus should always be on the dropdown primary element.
+function updateMenuItem(dropdown, item) {
+  if (!item.id) item.id = generateAriaId();
+  item.setAttribute('role', dropdown[ariaPatchKey].listItemRole);
+  item.setAttribute('tabindex', '-1');
+  for (const a of item.querySelectorAll('a')) a.setAttribute('tabindex', '-1');
+}
+
+// make the label item and its "delete icon" has correct aria attributes
+function updateSelectionLabel($label) {
+  // the "label" is like this: "<a|div class="ui label" data-value="1">the-label-name <i|svg class="delete icon"/></a>"
+  if (!$label.attr('id')) $label.attr('id', generateAriaId());
+  $label.attr('tabindex', '-1');
+  $label.find('.delete.icon').attr({
+    'aria-hidden': 'false',
+    'aria-label': window.config.i18n.remove_label_str.replace('%s', $label.attr('data-value')),
+    'role': 'button',
+  });
+}
+
+// delegate the dropdown's template functions and callback functions to add aria attributes.
+function delegateOne($dropdown) {
+  const dropdownCall = fomanticDropdownFn.bind($dropdown);
+
+  // the "template" functions are used for dynamic creation (eg: AJAX)
+  const dropdownTemplates = {...dropdownCall('setting', 'templates'), t: performance.now()};
+  const dropdownTemplatesMenuOld = dropdownTemplates.menu;
+  dropdownTemplates.menu = function(response, fields, preserveHTML, className) {
+    // when the dropdown menu items are loaded from AJAX requests, the items are created dynamically
+    const menuItems = dropdownTemplatesMenuOld(response, fields, preserveHTML, className);
+    const $wrapper = $('<div>').append(menuItems);
+    const $items = $wrapper.find('> .item');
+    $items.each((_, item) => updateMenuItem($dropdown[0], item));
+    $dropdown[0][ariaPatchKey].deferredRefreshAriaActiveItem();
+    return $wrapper.html();
+  };
+  dropdownCall('setting', 'templates', dropdownTemplates);
+
+  // the `onLabelCreate` is used to add necessary aria attributes for dynamically created selection labels
+  const dropdownOnLabelCreateOld = dropdownCall('setting', 'onLabelCreate');
+  dropdownCall('setting', 'onLabelCreate', function(value, text) {
+    const $label = dropdownOnLabelCreateOld.call(this, value, text);
+    updateSelectionLabel($label);
+    return $label;
+  });
+}
+
+// for static dropdown elements (generated by server-side template), prepare them with necessary aria attributes
+function attachStaticElements($dropdown, $focusable, $menu) {
+  const dropdown = $dropdown[0];
+
+  // prepare static dropdown menu list popup
+  if (!$menu.attr('id')) $menu.attr('id', generateAriaId());
+  $menu.find('> .item').each((_, item) => updateMenuItem(dropdown, item));
+  // this role could only be changed after its content is ready, otherwise some browsers+readers (like Chrome+AppleVoice) crash
+  $menu.attr('role', dropdown[ariaPatchKey].listPopupRole);
+
+  // prepare selection label items
+  $dropdown.find('.ui.label').each((_, label) => updateSelectionLabel($(label)));
+
+  // make the primary element (focusable) aria-friendly
+  $focusable.attr({
+    'role': $focusable.attr('role') ?? dropdown[ariaPatchKey].focusableRole,
+    'aria-haspopup': dropdown[ariaPatchKey].listPopupRole,
+    'aria-controls': $menu.attr('id'),
+    'aria-expanded': 'false',
+  });
+
+  // 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'));
+  }
+}
+
+function attachInit($dropdown) {
+  const dropdown = $dropdown[0];
+  dropdown[ariaPatchKey] = {};
+  if ($dropdown.hasClass('custom')) return;
 
   // Dropdown has 2 different focusing behaviors
   // * with search input: the input is focused, and it works with aria-activedescendant pointing another sibling element.
@@ -23,71 +124,39 @@ function attachOneDropdownAria($dropdown) {
   //    - if the menu item is clickable (eg: <a>), then trigger the click event
   //    - otherwise, the dropdown control (low-level code) handles the Enter event, hides the dropdown menu
 
-  // TODO: multiple selection is not supported yet.
+  // TODO: multiple selection is only partially supported. Check and test them one by one in the future.
 
   const $textSearch = $dropdown.find('input.search').eq(0);
   const $focusable = $textSearch.length ? $textSearch : $dropdown; // the primary element for focus, see comment above
   if (!$focusable.length) return;
 
+  let $menu = $dropdown.find('> .menu');
+  if (!$menu.length) {
+    // some "multiple selection" dropdowns don't have a static menu element in HTML, we need to pre-create it to make it have correct aria attributes
+    $menu = $('<div class="menu"></div>').appendTo($dropdown);
+  }
+
   // There are 2 possible solutions about the role: combobox or menu.
   // The idea is that if there is an input, then it's a combobox, otherwise it's a menu.
   // Since #19861 we have prepared the "combobox" solution, but didn't get enough time to put it into practice and test before.
   const isComboBox = $dropdown.find('input').length > 0;
 
-  const focusableRole = isComboBox ? 'combobox' : 'button';
-  const listPopupRole = isComboBox ? 'listbox' : 'menu';
-  const listItemRole = isComboBox ? 'option' : 'menuitem';
+  dropdown[ariaPatchKey].focusableRole = isComboBox ? 'combobox' : 'button';
+  dropdown[ariaPatchKey].listPopupRole = isComboBox ? 'listbox' : 'menu';
+  dropdown[ariaPatchKey].listItemRole = isComboBox ? 'option' : 'menuitem';
 
-  // make the item has role=option/menuitem, add an id if there wasn't one yet, make items as non-focusable
-  // the elements inside the dropdown menu item should not be focusable, the focus should always be on the dropdown primary element.
-  function prepareMenuItem($item) {
-    if (!$item.attr('id')) $item.attr('id', generateAriaId());
-    $item.attr({'role': listItemRole, 'tabindex': '-1'});
-    $item.find('a').attr('tabindex', '-1');
-  }
-
-  // delegate the dropdown's template function to add aria attributes.
-  // the "template" functions are used for dynamic creation (eg: AJAX)
-  const dropdownTemplates = {...$dropdown.dropdown('setting', 'templates')};
-  const dropdownTemplatesMenuOld = dropdownTemplates.menu;
-  dropdownTemplates.menu = function(response, fields, preserveHTML, className) {
-    // when the dropdown menu items are loaded from AJAX requests, the items are created dynamically
-    const menuItems = dropdownTemplatesMenuOld(response, fields, preserveHTML, className);
-    const $wrapper = $('<div>').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',
-  });
+  attachDomEvents($dropdown, $focusable, $menu);
+  attachStaticElements($dropdown, $focusable, $menu);
+}
 
+function attachDomEvents($dropdown, $focusable, $menu) {
+  const dropdown = $dropdown[0];
   // 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 refreshAriaActiveItem = () => {
     const menuVisible = isMenuVisible();
     $focusable.attr('aria-expanded', menuVisible ? 'true' : 'false');
 
@@ -97,7 +166,7 @@ function attachOneDropdownAria($dropdown) {
     // 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) {
+    } else if (dropdown[ariaPatchKey].listPopupRole === 'menu') {
       // 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');
@@ -107,7 +176,8 @@ function attachOneDropdownAria($dropdown) {
   $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'));
+      const dropdownCall = fomanticDropdownFn.bind($dropdown);
+      let $item = dropdownCall('get item', dropdownCall('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.
@@ -119,35 +189,36 @@ function attachOneDropdownAria($dropdown) {
   // 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(); });
+  const deferredRefreshAriaActiveItem = (delay = 0) => { setTimeout(refreshAriaActiveItem, delay) };
+  dropdown[ariaPatchKey].deferredRefreshAriaActiveItem = deferredRefreshAriaActiveItem;
+  $dropdown.on('keyup', (e) => { if (e.key.startsWith('Arrow')) deferredRefreshAriaActiveItem(); });
 
   // 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', () => {
+  dropdown.addEventListener('mousedown', () => {
     ignoreClickPreVisible += isMenuVisible() ? 1 : 0;
     ignoreClickPreEvents++;
   }, true);
-  $dropdown[0].addEventListener('focus', () => {
+  dropdown.addEventListener('focus', () => {
     ignoreClickPreVisible += isMenuVisible() ? 1 : 0;
     ignoreClickPreEvents++;
-    deferredRefreshAria();
+    deferredRefreshAriaActiveItem();
   }, true);
-  $dropdown[0].addEventListener('blur', () => {
+  dropdown.addEventListener('blur', () => {
     ignoreClickPreVisible = ignoreClickPreEvents = 0;
-    deferredRefreshAria(100);
+    deferredRefreshAriaActiveItem(100);
   }, true);
-  $dropdown[0].addEventListener('mouseup', () => {
+  dropdown.addEventListener('mouseup', () => {
     setTimeout(() => {
       ignoreClickPreVisible = ignoreClickPreEvents = 0;
-      deferredRefreshAria(100);
+      deferredRefreshAriaActiveItem(100);
     }, 0);
   }, true);
-  $dropdown[0].addEventListener('click', (e) => {
+  dropdown.addEventListener('click', (e) => {
     if (isMenuVisible() &&
       ignoreClickPreVisible !== 2 && // dropdown is switch from invisible to visible
       ignoreClickPreEvents === 2 // the click event is related to mousedown+focus
@@ -157,24 +228,3 @@ function attachOneDropdownAria($dropdown) {
     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: <div class="ui checkbox"><label /><input /></div>
-  // It doesn't work well with <label><input />...</label>
-  // 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);
-  }
-}

web_src/js/features/aria.md

@@ -23,6 +23,14 @@ To test the aria/accessibility with screen readers, developers can use the follo
   * Double-finger swipe means old single-finger swipe.
 * TODO: on Windows, on Linux, on iOS
 
+# Known Problems
+
+* Tested with Apple VoiceOver: If a dropdown menu/combobox is opened by mouse click, then arrow keys don't work.
+  But if the dropdown is opened by keyboard Tab, then arrow keys work, and from then on, the keys almost work with mouse click too.
+  The clue: when the dropdown is only opened by mouse click, VoiceOver doesn't send 'keydown' events of arrow keys to the DOM,
+  VoiceOver expects to use arrow keys to navigate between some elements, but it couldn't.
+  Users could use Option+ArrowKeys to navigate between menu/combobox items or selection labels if the menu/combobox is opened by mouse click.
+
 # Checkbox
 
 ## Accessibility-friendly Checkbox
@@ -52,9 +60,7 @@ 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
 
 Fomantic Dropdown is designed to be used for many purposes: