Implement Search as ARIA spec compliant* dialog and combobox pattern #2831

phoneticallySAARTHaK · 2025-01-20T08:05:06Z

Pretty much a complete rewrite of the UI and UI logic for search.

UI Changes:

fix height calculations in sectioning containers to remove extra scrollbars/overflows
Fixes tab order of toolbar links
Replaces search input with a button in toolbar, which in turn open a dialog, that has the search, which can be opened by clicking the button or pressing "/", or Ctrl+K
Implement search as combobox pattern (and all the changes that comes along with it)
Enabled virtualKeyboard API to adjust dialog height when keyboard opens in mobile (currently only chromium browsers support it)
Removes the ready class from search element.
Updat color variable to satisfy WCAG level AA

More details are in commit messages. I haven't updated the changelog, because I don't know what's relevant.

Visual Regression script probably won't detect the change?

*Mostly. There might be minor variations

- Add top margin to `.tsd-breadcrumb` in mobile screen - Remove top margin from `.tsd-navigation.settings` - Remove top padding from `.col-sidebar` on single sidebar - Remove margin for `.site-menu` on larger screens

- Move selectors (`#tsd-toolbar-links`, tag selectors) to a relevant place. - Remove classes (`.table-cell`, `.no-caption`, `.tsd-toolbar-icon`), and merge their styles to other common classes.

…cript - **theme_search_index_not_available** - **theme_search_no_results** - theme_search_placeholder - **theme_search_no_recent_searches**

- Use HTML dialog element as popup - Use ARIA-spec compliant "combobox with list autocomplete" pattern for search - Add entry animations - Comment out affected dead code for keyboard event listeners

- store recent searches (that were clicked) in localStorage, with `tsd-search-recent` key - Omit `matchData` property in `res`'s type to make it compatible with recent searches stored in localStorage. - This implementation prevents broken links, but refs might change, changing the suggestions

src/lib/output/themes/default/assets/bootstrap.ts

src/lib/output/themes/default/assets/typedoc/components/Search.ts

src/lib/output/themes/default/assets/typedoc/Application.ts

src/lib/output/themes/default/assets/typedoc/utils/modal.ts

static/style.css

src/lib/output/themes/default/assets/typedoc/components/Search.ts

Gerrit0

A couple general issues:

With no search history, typing something and then clearing the search field results in the claim "No Recent Searches"... which is rather confusing, I just searched for something! Didn't click on anything, but... maybe that's expected, but it greatly confused me for a bit.
This introduced some contrast issues in the new search dialog (run chromium's lighthouse checks)

This is looking really awesome! It seems to behave significantly better on mobile and I like the change on desktop as well

phoneticallySAARTHaK · 2025-01-25T03:43:12Z

Regarding the recent searches message, yup, totally agree, I think even left a comment about in the code that it's actually search results. I picked up it up from remix.run, and I'm confused what to show there, "no recent... What?"

Gerrit0 · 2025-01-25T03:49:22Z

Would it be better to just not show anything there? It's a different dialog size, but just showing a search bar the first time it is opened doesn't seem completely wrong to me.

I also just realized that storing IDs is not necessarily the way we should go about that. IDs are somewhat likely to change between rebuilds of the site as they are dependent on conversion order, so if the very first class TypeDoc converts gets a new property, all the IDs will end up shifted.

phoneticallySAARTHaK · 2025-01-25T04:12:23Z

Edit: Removing it.

...

Yup, I mainly added for cosmetic UX purposes. It's not important and I already had doubts about it (that's why it's the last commit).

Without anything it feels.. empty. I'll get some quick design advice on this, otherwise I'll just remove it.

And yes I tested the change of IDs, I still added it on the premises that atleast it won't crash.

From commit message:

This implementation prevents broken links, but refs might change, changing the suggestions

It was the simplest way to achieve it, and I don't wanna make it complicated, so I'll probably just remove it. But I don't think occasional changing suggestions is a big deal. But after all, it is a bug.

So here's my confusion:

last search is mainly for UX, to not have a tiny search dialog
The message "no recent search" is a bit confusing, it should probably be changed.
it could be a useful feature, but current implementation has a minor bug.
That shouldn't be a big issue, and a lot of people probably wouldn't even notice.

Tradeoffs everywhere.. What are your thoughts about it?

This reverts commit 1beacfa, and the new i18n strings added in 3548d14.

- fix typo (requierd -> required) - Remove unnecessary try-catch - Add falsy check for document.getElementById argument to avoid console warning in firefox

All children of a listbox must be options, showing error message in an li tag without role=option was invalid. An alternative approach is to use another element with aria-live=polite attribute, to announce the results to the user. However, consecutive queries with no results wouldn't be announced (because the message would be the same), so add search query as part of the message to make it dynamic - Add a new element with aria-live and aria-atomic attributes for a helpful message - Remove unnecessary attribute selector for search results. - Add styles height/margin styles for non-empty elements only. - Add maxLength to input

src/lib/output/themes/default/assets/typedoc/components/Search.ts

src/lib/internationalization/locales/en.cts

phoneticallySAARTHaK · 2025-01-26T22:50:53Z

src/lib/output/themes/default/assets/typedoc/components/Search.ts

        }

        const item = document.createElement("li");
+        item.id = `tsd-search:${optionsIdCounter}-${i}`;
+        item.role = "option";
+        item.ariaSelected = "false";
        item.classList.value = row.classes ?? "";


Figure out how to override filter styles to not affect search results

- Add background-active and contrast-text css properties - update text-aside, menu-item-active color in light theme - break light and dark colors in separate selectors to make them easier to work with "contrast-text" slightly improves contrast. though, not enough to pass WCAG level AAA

phoneticallySAARTHaK added 15 commits January 19, 2025 00:23

Add css variables for dimensions, and use svh units

c53e480

Fix excess/absent margins and padding.

79a9b56

- Add top margin to `.tsd-breadcrumb` in mobile screen - Remove top margin from `.tsd-navigation.settings` - Remove top padding from `.col-sidebar` on single sidebar - Remove margin for `.site-menu` on larger screens

Fix tab order of toolbar and remove unused selectors. **Breaks search**

1df9967

- Move selectors (`#tsd-toolbar-links`, tag selectors) to a relevant place. - Remove classes (`.table-cell`, `.no-caption`, `.tsd-toolbar-icon`), and merge their styles to other common classes.

Add more search related 118n strings, and inject more strings in js s…

3548d14

…cript - **theme_search_index_not_available** - **theme_search_no_results** - theme_search_placeholder - **theme_search_no_recent_searches**

Implement search component as combobox, with minimal functionality

55c0576

- Use HTML dialog element as popup - Use ARIA-spec compliant "combobox with list autocomplete" pattern for search - Add entry animations - Comment out affected dead code for keyboard event listeners

Add global keyboard listeners for opening modal

28320e1

rename setCurrentResult to setNextResult

b0f75ef

Use semantic element mark for highlighting search matches

f4d4fbd

Add exit animation for modals, using custom overlay

0b58bf5

Remove unused keyframes. Merge body selectors

b2f79de

Adjust max-height with virtual keyboard, in mobiles

d687ef6

fix placeholder text color on focus search input

548df5c

Remove min-height from search dialog and set it to .state

a606615

fix single element edge case in setNextResult

ec6b774

phoneticallySAARTHaK commented Jan 20, 2025

View reviewed changes

src/lib/output/themes/default/assets/bootstrap.ts Show resolved Hide resolved

phoneticallySAARTHaK commented Jan 20, 2025

View reviewed changes

src/lib/output/themes/default/assets/bootstrap.ts Show resolved Hide resolved

phoneticallySAARTHaK commented Jan 20, 2025

View reviewed changes

src/lib/output/themes/default/assets/typedoc/components/Search.ts Outdated Show resolved Hide resolved

phoneticallySAARTHaK commented Jan 20, 2025

View reviewed changes

src/lib/output/themes/default/assets/typedoc/Application.ts Outdated Show resolved Hide resolved

Gerrit0 mentioned this pull request Jan 25, 2025

support regions in @includeCode #2816

Open

15 tasks

Gerrit0 reviewed Jan 25, 2025

View reviewed changes

src/lib/output/themes/default/assets/typedoc/utils/modal.ts Outdated Show resolved Hide resolved

Gerrit0 reviewed Jan 25, 2025

View reviewed changes

static/style.css Outdated Show resolved Hide resolved

Gerrit0 reviewed Jan 25, 2025

View reviewed changes

src/lib/output/themes/default/assets/typedoc/components/Search.ts Outdated Show resolved Hide resolved

Gerrit0 requested changes Jan 25, 2025

View reviewed changes

Gerrit0 added this to the v0.28.0 milestone Jan 25, 2025

phoneticallySAARTHaK added 2 commits January 25, 2025 12:57

Completely revert "recent searches" feature.

4fd690e

This reverts commit 1beacfa, and the new i18n strings added in 3548d14.

Fix typo and refactor search.ts code

b49240a

- fix typo (requierd -> required) - Remove unnecessary try-catch - Add falsy check for document.getElementById argument to avoid console warning in firefox

Gerrit0 reviewed Jan 26, 2025

View reviewed changes

src/lib/output/themes/default/assets/typedoc/components/Search.ts Outdated Show resolved Hide resolved

Gerrit0 reviewed Jan 26, 2025

View reviewed changes

src/lib/internationalization/locales/en.cts Outdated Show resolved Hide resolved

Add placeholder for no_results i18n string

8a4b5e3

phoneticallySAARTHaK commented Jan 26, 2025

View reviewed changes

phoneticallySAARTHaK added 2 commits January 27, 2025 05:17

remove global button styles and add it to tsd-widget

cccf2d4

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement Search as ARIA spec compliant* dialog and combobox pattern #2831

Implement Search as ARIA spec compliant* dialog and combobox pattern #2831

phoneticallySAARTHaK commented Jan 20, 2025 •

edited

Loading

Gerrit0 left a comment

phoneticallySAARTHaK commented Jan 25, 2025

Gerrit0 commented Jan 25, 2025

phoneticallySAARTHaK commented Jan 25, 2025 •

edited

Loading

phoneticallySAARTHaK Jan 26, 2025

Implement Search as ARIA spec compliant* dialog and combobox pattern #2831

Are you sure you want to change the base?

Implement Search as ARIA spec compliant* dialog and combobox pattern #2831

Conversation

phoneticallySAARTHaK commented Jan 20, 2025 • edited Loading

Gerrit0 left a comment

Choose a reason for hiding this comment

phoneticallySAARTHaK commented Jan 25, 2025

Gerrit0 commented Jan 25, 2025

phoneticallySAARTHaK commented Jan 25, 2025 • edited Loading

phoneticallySAARTHaK Jan 26, 2025

Choose a reason for hiding this comment

phoneticallySAARTHaK commented Jan 20, 2025 •

edited

Loading

phoneticallySAARTHaK commented Jan 25, 2025 •

edited

Loading