On Mon, 16 Oct 2023 12:11:03 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 Co... > > Hannes Wallnöfer has updated the pull request incrementally with one > additional commit since the last revision: > > A few more tweaks > > - Move scroll-margin update from search.js to script.js > - Use DOMContentLoaded event to update scroll-margin > - Avoid use of :has() CSS pseudo-class which is unsupported on Firefox I have updated this PR with a [few additional fixes](https://github.com/openjdk/jdk/pull/15969/commits/aad899048bdc5cd70424ab73bdcb1c2efa0eda4f): - The callback to update the scroll-margin to accomodate for the draft header has moved from `search.js` to `script.js` which is always available (`search.js` is dependent on the index). - The callback is implemented in pure JavaScript instead of relying on jQuery, and uses the `DOMContentLoaded` event instead of the `window` `load` event, which avoids flickering on Chrome and Safari (still a little bit of flickering in Firefox under some conditions). - I removed the change to make tab buttons scrollable instead of adding line breaks as the `:has()` CSS pseudo-class is not supported on Firefox. This change was unrelated to the issue at hand. Generated documentation can be viewed here: https://cr.openjdk.org/~hannesw/8308659/api.03/ ------------- PR Comment: https://git.openjdk.org/jdk/pull/15969#issuecomment-1764351923
