typedoc
typedoc copied to clipboard
TypeStrong
Search results are not announced in type doc search edit field.
Search terms
Expected Behavior
while entering text in the search field narrator should announce the displaying results.
Actual Behavior
while entering text in the search field narrator not announcing the displaying results.
Steps to reproduce the bug
- Open https://typedoc.org/api/ in edge browser.
- Navigate to type doc search edit field present in the top right of the page and invoke it.
- In search edit field enter some text and observe narrator announcement whether the search results are announced or not!
search results not announcing.webm
Environment
- Typedoc version: v0.26.3
- TypeScript version:
- Node.js version:
- OS: 23H2 ((OS Build 26052.1000)
I'm unlikely to get to this anytime soon, last time narrator and I crossed paths I emerged victorious, but very frustrated. PR welcome!
Doing a little bit of research on this... I'm not convinced announcing results is a good idea. Interrupting people's flow is (almost) never a good thing.
- https://www.scottohara.me/blog/2022/02/05/dynamic-results.html
I did a bit of investigation of other sites with dynamic search results as well, and they also do not announce results:
- https://www.google.com/
- https://duckduckgo.com/
- https://doc.rust-lang.org/std/index.html
- https://docs.readthedocs.io/en/stable/
- https://www.wikipedia.org/
- https://www.startpage.com/
- https://www.merriam-webster.com/
- https://www.dictionary.com/
I found only two sites which did announce results:
- https://www.bing.com/
- https://www.typescriptlang.org/
Perhaps this is that I have not spent a lot of time with narrator, but it seemed to behave very poorly, resulting in a significantly worse experience than the sites which did not announce results. With Bing, half the time it was announcing results which I had never even seen on the screen because I'd started typing other characters, so the results were out of date. With TypeScript's site, the results were even worse. It refused to stop announcing search results and neither tab nor down arrow appears to let me select the resulting links to actually select them.
If there's one thing that this has taught me, it's that apparently doing this right is next to impossible... Wikipedia's search results seemed to be the best behaved to me. Dictionary.com wasn't bad, but from there it degraded rapidly, with none of the other sites seeming to behave nicely.
Are you aware of any sites where this is actually done in a way it isn't more annoying than helpful?
@Gerrit0, Thanks for the response. We are currently in discussion with our internal dependent team and SME. Once we get the response, we will update you soon.
@Gerrit0 - We have checked on https://www.microsoft.com/en-us/ Narrator is announcing proper information of search result. Same expected on https://typedoc.org/api/
I just tried it, and... no, it doesn't. It says "Suggestions available" when entering the search box, and they are displayed for non-narrator users, but they do not appear to be usable with narrator, or I just don't understand how it works. If that's the case, please provide the necessary keystrokes to reproduce it working.
https://support.microsoft.com/en-us/windows/chapter-5-navigation-68941680-3245-6ef5-5012-0674b8b6fc59 claims that I should be able to use up/down keys to select results, which is non-functional. Furthermore, hitting tab closes the search box and suggestions, so there's not even a way to tab through those results.
Please refer attached Video with Narrator behavior for (https://www.microsoft.com/en-us/)
https://github.com/user-attachments/assets/b45a40cf-392e-4472-aa46-39fa1bc5649f
Observation: Narrator is announcing proper information as “11 results are available, use up and down arrow keys to navigate search expanded M edit” and on invoking down arrow key focus goes to Suggestion list results.
This information will be helpful for Narrator users as it will be easy for them to understand how many search results are available.
That is very strange, that's not at all the behavior which I receive. Maybe narrator doesn't work properly within a VM?
Going to leave this as help wanted. I'd be happy to look at someone's attempt at fixing this, but I'd rather spend time on something which isn't horribly painful to work on.
@Gerrit0 - thanks, let me know if anything else is required from our side.
The ARIA specification for combobox does not mention announcing the number of results, and thus, narrator does not announce the number of results even on their own example page: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/
The combobox role is also not fully supported by screen readers: https://a11ysupport.io/tests/apg__aria-1-2-combobox-with-list-autocomplete-example
Microsoft achieves the announcement by using aria-live="assertive" (which is also broken :laughing: ; it does not update if the number of results are the same for consecutive key input).
aria-live="assertive" should only be used for time-sensitive/critical notifications that absolutely require the user's immediate attention.
source: MDN
That said, typedoc does not use proper ARIA guidelines for the search combobox, let me know if you need help with that, @Gerrit0
Help would be greatly appreciated here! I'd love to spend the time I have for typedoc on the backend changes to enable new features rather than in the frontend where my skills are weaker than many.
The ARIA specification for combobox does not mention announcing the number of results, and thus, narrator does not announce the number of results even on their own example page: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/
Per this, I'm going to close this as won't implement. I'm happy to review and merge PRs which improve the accessibility of typedoc, but don't have plans to work on it myself at the moment.