On Thu, 28 Sep 2023 19:50:21 GMT, Hannes Wallnöfer <hann...@openjdk.org> wrote:
> A few years ago we switched to [Flexbox > Layout](https://developer.mozilla.org/en-US/docs/Glossary/Flexbox) to > implement the sticky header in the API docs generated by `javadoc`. This > solved the problem of anchor link targets [not being positioned > correctly](https://bugs.openjdk.org/browse/JDK-8223378), but it also > introduced a few new ones: > > - It required a workaround to get browser history to work (JDK-8249133, > JDK-8250779, 8286832) > - It changed certain aspects of scrolling behavior in the browser > (JDK-8301080) > - It changed the way some CSS properties are interpreted (JDK-8315800) > > The reason for most of these problems is that the layout paradigm used by > Flexbox is very different from traditional layout of HTML pages. The > `scroll-margin-*` CSS properties introduced by the [CSS Scroll Snap > Module](https://www.w3.org/TR/css-scroll-snap-1/) provide a simpler and less > intrusive way to implement link target offsets in combination with sticky > elements implemented using [`position: > sticky`](https://developer.mozilla.org/en-US/docs/Web/CSS/position). However, > although it is implemented [in all supported > browsers](https://caniuse.com/?search=scroll-margin), it comes with its own > challanges and quirks, which are explained below. > > The first problem to overcome was that `position: sticky` is more fragile on > mobile browsers than Flexbox. If some part of the page content overflows the > allotted horizontal space, the whole page can be zoomed out to view the whole > content. This causes the header to become unsticky and the link target > offsets to become erroneous. It was therefore necessary to make sure page > content never overflows its allotted horizontal space, either by adding line > break opportunities, or by making all or part of the page horizontally > scrollable when its content overflows. Line break opportunities are difficult > to add especially in preformatted code, so I opted for making the parts of > the page most likely containing long lines of code scrollable. > > The next problem was that enabling horizontal scrolling on an element or one > of its containing elements breaks the `scroll-margin-top` property in Chrome > due to a browser quirk (both desktop and mobile versions). This means that > the scrolling must occur in a child element rather than the sections or other > elements serving as link targets. > > When enabling horizontal scrolling on the contents of sections containing > user-provided content, another problem is that it disables [Margin > Collapse](https://www.joshwc... src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/MethodWriter.java line 106: > 104: > 105: for (Element method : methods) { > 106: currentMethod = (ExecutableElement)method; As a separate RFE, _it would be nice_ if `getVisibleMembers` took an optional `Class<T>` argument that is used to cast the result of the method to `List<T extends Element>` instead of just `Element`. This would enable to eliminate downstream casts, like here on line 106, to get the subtype. See a similar technique in `Utils` for accessing sublists of a list of `DocTree` nodes, ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/15969#discussion_r1347805280
