RFR: JDK-8273034: Make javadoc navigation collapsible on small displays

[Pavel Rappo]

On Fri, 3 Sep 2021 12:15:45 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> Please review a change to add a collapsible "hamburger" navigation bar to javadoc pages for small screens. The collapsible navbar is activated when the browser width is below 920px, which is the point where the normal navigation bar starts to wrap for some javadoc pages. 
> 
> The feature is implemented using CSS and JavaScript techniques employed by popular frameworks and has been successfully tested on several browsers and platforms, including various Android and iOS devices as well as IE and Edge browsers on Windows 10.
> 
> Sample documentation generated with this change is provided at the URL below. For testing, please review it on a mobile phone or tablet, or using the device emulation features provided with the developer tools of many desktop browsers.
> 
> http://cr.openjdk.java.net/~hannesw/8273034/api.00/index.html
> 
> One peculiarity of this change is that the sub-navigation links are rendered separately for the normal and the mobile navbar. The reason for this is that the links are structured differently (flat list vs nested lists) and reside in different containers. 
> 
> On the CSS side, apart from the collapsible navbar I overhauled the styles for the search input, especially the small reset "X" button. The positioning of the reset button is now simpler and more robust by using `absolute` instead of `relative` position, and doesn't require moving the search input and label to the right anymore.
> 
> The collapsible menu uses the `aria-controls`, `aria-expanded` attributes as described in the following wiki page:
> 
> https://www.w3.org/WAI/GL/wiki/Using_the_WAI-ARIA_aria-expanded_state_to_mark_expandable_and_collapsible_regions
> 
> Furthermore, the `aria-label` attribute is used to provide a human-readable lable for the button.
> 
> https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute

I haven't looked at the code yet. I've only seen the sample documentation on my laptop and my initial reaction was: Oh boy, does it look good! Both primary and secondary navigation is at your fingertips (no pun intended).

A few remarks.

  1. I don't expect this to be an issue on small devices and it's not a big deal, but might look better if fixed. When you try to resize the window in an expanded hamburger view, the view collapses. Compare this behavior with that of, for example, https://getbootstrap.com/.
  2. A problem which was highlighted by this change rather than brought by it, is that the primary navigation items (i.e. OVERVIEW, MODULE, PACKAGE, CLASS, USE, etc.) that are disabled (i.e. cannot be clicked) are indistinguishable from those that are enabled. Sure, if you have a pointing device such as a trackpad or mouse, you can hover over those items to see if they change their appearance. However, this does not seem achievable with your finger touching a phone screen.

-------------

PR: https://git.openjdk.java.net/jdk/pull/5360