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... This pull request has now been integrated. Changeset: eb7d972d Author: Hannes Wallnöfer <hann...@openjdk.org> URL: https://git.openjdk.org/jdk/commit/eb7d972d8a538a9840b5a17f52d7ca9f20bd6620 Stats: 289 lines in 37 files changed: 103 ins; 68 del; 118 mod 8308659: Use CSS scroll-margin instead of flexbox layout in API documentation Reviewed-by: jjg ------------- PR: https://git.openjdk.org/jdk/pull/15969
