Update from 2022-March-04
See #170 for the proposed change in direction. The rest of this issue summary is for the prior direction, so might be outdated, but I'm leaving it in place for now pending discussion on the new proposal.
Before going any further, know this:
Much of the work on this task took place here:
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
. It eventually became apparent that this needed its own issue
- Are you looking for the issue regarding a drop-in replacement for jQuery UI autocomplete, for stuff like entity reference fields? this is that issue
- Are you looking for the issue regarding UX improvments to
<select> elements, making it easier to deal with long lists of options? That is a different issue, and it is here:
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
Problem/Motivation
We are in the process of deprecating jQuery UI in core. jQuery UI's autocomplete is among the components that would need to be removed/replaced.
As mentioned in the parent issue:
🌱
[Plan] Remove jQuery UI components used by Drupal core and replace with a set of supported solutions
Fixed
jQuery UI, per an announcement in October 2021 jQuery UI's maintainers clarified it is not EOL, but "minimally maintained", and security and jQuery core compatibility will be supported. This was followed by a new 1.13 release that included security fixes. Although it's not clear how often or how comprehensive these maintenance releases will be, this reduces the urgency to remove jQuery UI from Drupal core altogether.
Proposed resolution
First, some context regarding the decisions made in this specific resolution
Because it was clear the new autocomplete would not be fully backwards compatible with jQuery Ui autocomplete, it was decided to introduce the new Autocomplete as an experimental module and leave jQuery UI autocomplete as the default until Drupal 10. This would provide sites with adequate time to make any changes required
The original plan for this was to replace jQuery UI with another library. Awesomplete was literally the only library without significant accessibility regressions compared to jQueryUI and one that could be added with the least disruption so that was the library we chose.
It was then observed that the amount of customization required for the Awesomplete implementation was significant enough that we were using very little of the library itself, and it may be simpler to make the solution entirely custom.
Then after that, it was observed that this new autocomplete may be a good candidate for being a standalone library that doesn't depend on Drupal, which would adhere to the policy here:
🌱
[policy, no patch] Publishing / Maintaining JS libraries produced by Drupal that do not have a dependency on Drupal
Needs review
With that context out of the way, this is the current proposed solution
- Create a new A11y_autocomplete standalone npm package that can work independent of Core.
- A11y_autocomplete will be added to /vendor. It will effectively replace the jQuery UI autocomplete library . There will be a backwards-compatible shim that translates jQuery UI autocomplete usages to work with A11y_autocomplete on any input initialized by
Drupal.Autocomplete.initialize. Drupal behaviors will continue to initialize autocomplete on any input with the .form-autocomplete class. This class is automatically added to any render array with autocomplete enabled.
- When shim features are used, deprecation warnings will be triggered so sites are aware that the A11y_Autocomplete equivalents must be used by Drupal 10.
- Stable and Stable 9 provide JS that refactors the autocomplete markup to match that provided by jQuery UI Autocomplete.
- Accessibility implementation will use Accessible Autocomplete from GOV.UK as reference, as it was informed by extensive testing and research. (the accessible autocomplete library was not an option as something Drupal could use as the feature set did not cover what core would need from an autocomplete.
Steps taken prior to the proposed resolution
Several other options were evaluated. Note that all links to evaluations go a separate issue:
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
, the issue that this originated from.
- https://github.com/jshjohnson/Choices
Evaluation (#189)
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
- https://harvesthq.github.io/chosen/
Evaluation (#194)
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
- https://github.com/Mobius1/Selectr
Evaluation (#195)
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
- https://github.com/alphagov/accessible-autocomplete (prototype at
#182
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
, great accessibility but not considered as it does not support select/multiselect It is strictly for providing suggestions to single-value text fields)
- https://github.com/HemantNegi/jquery.sumoselect
Evaluation (#201)
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
- http://ivaynberg.github.io/select2 (of which https://github.com/woocommerce/selectwoo is a fork of, created to improve accessibility)
Evalulation (#193)
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
- Custom library based on https://react-select.com
Evaluation (#200)
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
- https://selectize.github.io/selectize.js/
Evaluation (#199)
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
- https://leaverou.github.io/awesomplete/
Evaluation and prototype (#223)
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
- https://github.com/github/auto-complete-element
Evaluation (#222)
📌
Improve usability, accessibility, and scalability of long select lists
Needs work
Other than Awesomplete, nontrivial accessibility problems were identified in each candidate. These problems were discovered from general accessibility testing. In each case, enough issues were found that it wasn't worth devoting additional time to strictly checking against W3 specs.
Remaining tasks
- .
-
- check if comma separated lists work in multilingual settings, particularly where the English comma, ',' is not used. See #177.
- JS FM Signoff
- Product Manager review
- Release manager signoff (regarding the deprecations)
- Accessibility Signoff
- FEFM signoff
- A11y_Autocomplete added to core in separate issue so it's not part of this MR (potentially including PHP notices)
- Find some additional means of communicating this change + new npm package beyond just a boring change notice as this could benefit the community.
- A review that targets the Nightwatch tests and associated test modules - these are unlikely to change much so a comment signing off on those could remove them from the overall review-burden for other reviewers
- Deprecation warnings exist when overriding any default properties of the deprecated
Drupal.autocomplete API (note the lowercase "a" in "autocomplete". These specific warnings do not yet have test coverage. Determine if test coverage is necessary and if so add the tests.
User interface changes
Yes.
API changes
The entire Drupal.autocomplete API is deprecated.
There is a new Drupal.Autocomplete api with different properties. Details are in the
change record →
Release Notes Snippet
jQuery UI autocomplete has been deprecated and removed, replaced by Drupal's Accessible Autocomplete library. A backwards compatible shim has been added to provide an API surface that is fully compatible with the jQuery UI Autocomplete API, and largely compatible (but not 100%) with the jQuery UI's widget API, which autocomplete (and all other jQuery widgets) extend. When the shim is used by calling $('#an-input').autocomplete(/* anything */), a deprecation warning will be triggered. This shim will be removed in Drupal 10.0.
In themes that have Stable or Stable 9 as base themes, the Autocomplete widget markup is unchanged. Autocomplete markup will be different in themes not extending Stable/Stable 9. will and markup that is unchanged from jQuery UI Autocomplete.