Update navbar design and improve search UI

[lhsazevedo]

Tip

You can view this proposal live at: https://php-navbar.lhsazevedo.dev/
This is now live at https://php.net

Intro

Over the years, the PHP webpage received various design proposals, some didn't gain traction due to their drastic nature or departure from PHP's established branding style. However, our community has shown that we can successfully implement design improvements when they're incremental – the PHP 8 release pages, homepage hero and thanks page are great examples of this approach.

Inspired by these successful updates and the the discussions they sparked, I'd like to propose some updates to the navbar design and introduce a new search dialog to enhance a bit the user experience on php.net. These changes are inspired by modern web design principles while respecting PHP's branding and build upon previous community discussions.

By focusing on small enhancements rather than a full redesign, we can improve the site's usability and aesthetics without disrupting its familiar layout and branding.

UI Scope

It's worth noting that while the current client-side search implementation could be considered outdated, replacing it would be beyond the scope of this design improvement. Such a change would require a separate, focused effort. This proposal aims to enhance the user interface while maintaining the existing search functionality, setting the stage for potential future improvements to the search implementation itself.

Enhancements

1. Modernized navbar design:

   • A responsive navbar with improved mobile navigation.
   • Ensures a consistent experience across devices, addressing the growing mobile user base while maintaining PHP's established visual identity.

2. New search dialog:

   • A user-friendly search modal with keyboard navigation.
   • Improves accessibility with proper ARIA attributes and keyboard navigation, making php.net more inclusive.

3. Retained search implementation:

   • Integration of the existing FuzzySearch with the new UI.
   • Maintains familiar search behavior while setting the stage for future improvements to the search implementation.

4. Code improvements

   • CSS refactoring and removal of outdated libraries (Hogan.js, typeahead.js).
   • Improves maintainability, making future enhancements easier to implement.

5. Enhanced reliability

   • Introduction of Playwright E2E tests for the new search modal.
   • Ensures the changes don't introduce regressions, maintaining the site's reliability.

Impact

These changes are designed to be minimally disruptive:

• Existing users will find a familiar but enhanced experience
• New users will benefit from improved navigation and search UI

Preview

Please note that the preview site uses an improved search index generated by a companion change I'm proposing to the PHP documentation generator (phd). While both PRs can be merged independently, I've captured the screenshots and recordings using the new index to showcase the full potential of these improvements.

You can find the companion PR for the phd changes here: php/phd#154

Desktop preview

desktop_preview-2024-10-03_22.08.18.mp4

Mobile preview

mobile_preview-2024-10-03_22.10.47.mp4

Comparison

View GIF comparisons (image heavy)

Desktop comparison

Navbar

Search modal dialog

Mobile comparison

Navbar

Navigation

Search

Final thoughts

I believe these improvements will benefit the PHP community while respecting the site's established design principles. I look forward to your feedback and collaboration in refining this proposal.

If you find this proposal valuable or have any concerns, I'd greatly appreciate your feedback. Please consider leaving a 👍 or 👎 to help measure the community opinion.

[github-actions]

🚀 Preview for commit fcc9565 can be found at https://web-php-pr-1084.preview.thephp.foundation

[github-actions]

🚀 Regression report for commit fcc9565 is at https://web-php-regression-report-pr-1084.preview.thephp.foundation

[lhsazevedo]

Suggested reviewers: @morrisonlevi @dragoonis @cmb69 @kamil-tekiela @ramsey @mvriel @pronskiy @Girgias @localheinz

Edit: Will check visual tests asap

[kamil-tekiela]

I like it. I like the changed color, I like that the text of the buttons is more readable, I like that the PHP logo is now white, and I like that the search results list is simpler. The mobile view looks really good. There are a couple of things I don't like though.

1. I am not of a fan of the search opening up to cover the page. Why is it that when I click on an input box a new input box pops up? The placeholder text also doesn't match suggesting that the popup does something different than the box I actually clicked on.
2. If the popup stays, I would not disable the page scroll. I never liked this as it creates a jarring visual experience. At least on Chrome the page shifts to the right and the scroll bar is now in the middle box which means that if I want to scroll I need to hover my mouse over the thin box.
3. If the popup stays, there should be no load animation. It's an unnecessary gimmick that only delays loading of the box.
4. Even though the text is more readable, I still think it's not contrast enough from the background color. Especially the "Search" placeholder is visually blending in with the surroundings. Make it stand out more, either by changing the text color or giving the search box lighter border. I wouldn't mind if all text in the navbar was pure white or whitesmoke.
5. IMHO there is no need to make the navbar taller. The previous height was ok. On most monitors the vertical space is more expensive than horizontal, so every padding you add makes the actual content push down to a place with less priority. You made it shorter in mobile view so why make it taller in desktop view.
6. Not sure if related but the code formatting on /releases/8.3/en.php is borked.
7. The navbar is now almost the same color as the main div of /releases/8.3/en.php. Everything is purple now. I don't hate the color, but it's just too much. Something needs to change.
8. The logograms in mobile view have too low contrast with the background. You made them #D2D9FF but even if they were #FFFFFF they would be still too dark. I would suggest making it #F5F5F5 with opacity 1, the same as all text in the navbar.

[cmb69]

Thank you! Overall, this looks like a nice improvement, but I don't like that the search now won't work if JavasScript is not available.

[simonrjones]

The popup search results looks very smart. A few thoughts:

Accessibility:

• Contrast of primary navigation items fails WCAG accessibility (so does the current site it seems), text colour #DBE2FF or lighter would fix this
• Contrast of search text fails WCAG accessibility, text colour #CBCCF1 or lighter would fix this
• ALT text of PHP logo is "PHP Logo" - there's no need for the text "logo" here for accessibility reasons. Ideally it would be "PHP home" to indicate it links to the homepage.

Other:

• I'd strongly recommend using progressive enhancement so the search works without JS. JS can fail for many reasons and the search should be accessible to all. The search box is a button, if this switched back to input then the form would work without JS (since would submit to the search results page)
• When you do just press return it loads this full website search results page instead of the manual lookup page. It's probably more useful, but the styling is very basic on the full website search results page (I appreciate this is the same on the current site). Compare:
  • https://www.php.net/manual-lookup.php?pattern=function&scope=quickref
  • https://php-navbar.lhsazevedo.dev/search.php?lang=en&q=function

[Girgias]

The search bar not working any more with JS is a massive issue.

[lhsazevedo]

Thanks for the quick review and feedback! I've addressed many of your points and would like to discuss a few of them:

Progressive enhancement

@cmb69 @Girgias @simonrjones
The search was updated to work without JavaScript, using a form by default with the modal as a progressive enhancement.

Searching on mobile sized screens will still require JS. Given that it's common for mobile users to have JavaScript enabled, I think this is a reasonable trade-off. Some major language require JavaScript for searching (even on desktop): Kotlin, Rust, Swift, MDN, Dart. All Algolia-powered docs as well, and MkDocs.

Accessibility and contrast

@kamil-tekiela @simonrjones

All elements in the navbar and search modal have been updated to comply with WCAG AA contrast ratios. This includes the primary navigation items, search text, and icons in mobile view.

Layout

Page covered, no scroll

@kamil-tekiela The popup is inspired by Algolia that used in popular documentation sites (e.g. Composer, PHPStan, Laravel, Vue, React etc). It felt it a bit awkward the first time I saw it, but got used to it eventually.

The ideal UI for me would be something like Psalm docs (Material for MkDocs), but it is a bit more complicated to implement. Given the current search UI situation (5 different scrolling elements nested in a thin menu) maybe we could proceed with the Algolia-like modal as a first step and further improve it in the future. Would you consent to this approach?

Fade animation

@kamil-tekiela I believe this is a bit subjective and a matter of taste, but I can remove it if it's a common opinion. For now I halved the animation duration to 1/10th of a second, is this still a deal breaker? You can test it here (may need to disable cache).

Navbar height

@kamil-tekiela Forgot to mention but I followed @morrisonlevi's suggestion to avoid the sticky header, so now it doesn't take up any space after scrolling down. Note that the navbar is 64px tall on both desktop and mobile, which seems a common height for navbars, even sticky ones.

Other fixes

• Matched the placeholder text between the search button and the modal.
• Darkened the release page background a bit for better contrast with the navbar.
• Hid navbar logo from the accessibility tree, as the anchor aria-label is already "PHP home".
• Plus some minor adjustments, see commits.

Unrelated or out of scope

Release page formatting

@kamil-tekiela I think this is now fixed php/phd#156

Search page styling

@simonrjones Given that this is the current behavior and it relates to the page content, I think it would be out of scope for this PR. What do you think of discussing this in a separate issue?

[ddevsr]

I think keep header position fixed, but after scrolling resize to small is good

[Girgias]

@saundefined can you have another look at this?

[saundefined]

I like it, thank you!

We can wait a little longer (say, until the end of the week),
and if there are no objections, merge it

[lhsazevedo]

Sounds good, no rush.

It would be great to have this ready for the 8.4 release though.

[lhsazevedo]

Fixes #502

[theodorejb]

Can the mobile nav sidebar be made to close when tapping outside of it? I instinctively tried to do this when testing on my phone, and it feels annoying that I instead have to tap a small X in the corner.

[saundefined]

@lhsazevedo can you take a look?
lhsazevedo#1

Can the mobile nav sidebar be made to close when tapping outside of it?

Should solve it

[lhsazevedo]

Thanks @saundefined, merged.

I noticed some common code between the offcanvas menu and the search modal.

web-php/js/search.js

Lines 315 to 321 in eb7a39d

	// Close when the user clicks outside of it
	backdropElement.addEventListener("click", (event) => {
	if (event.target === backdropElement) {
	hide();
	}
	});
	};

In the future, we could consider refactoring this into a helper to keep things DRY. But hey, it's always good to go WET first!

[saundefined]

So, no more comments have come in,
I guess we can merge this PR 🎉

Thanks a lot for the work done!

[haszi]

@lhsazevedo Thanks for this! The UI and search in general look and feel much more natural and polished.

One question I have that I couldn't find an answer to here is whether the removal of the manual lookup page is deliberate or accidental? While in it's current form it is of limited use, I did like it taking me to a function's page when I typed the full function name into the search box and hit enter.

[lhsazevedo]

@haszi Great to hear that :)

The Google Search was a conscious decision (now the lookup it is only used when JavaScript is not available), but I also thought that this was the previous behavior. I just checked the previous implementation, and indeed, hitting enter would trigger the lookup.

While I think the Google search would benefit most of the users, I can see the value of the lookup use as well. Considering only those two implementations, I see two options:

• Restore the old behavior, were Enter triggers the lookup and the Google search option is the last entry in the result list.
• Keep it as is, with the lookup alternative being to navigate to the desired result with ↓, then Enter.

Both sound reasonable to me, so I don't have a strong preference. I can implement the first option if desired, plus some minor quality-of-life adjustments, by next week.

[haszi]

While I liked the search bar immediately taking me to a function's documentation, I don't have any strong preferences on this. And since I'm not active in web-php, neither do I think my opinion should carry too much weight. :-) That I leave up to those who do take care of the repo, like @saundefined . :-)