Improve the fixed header approach to remove "header padding fouc"

[ang-zeyu]

Is your request related to a problem?

Browser refresh:

Describe the solution you'd like

Experiment with a dynamic positioning approach, e.g. https://www.w3schools.com/howto/howto_js_sticky_header.asp.

Describe alternatives you've considered

• Add a "best estimate" of the initial header height -- issue: some pages have headers, some don't. Also only an estimate, some fouc would still remain.

Additional context

#1534 eliminates fouc from vue rendering but fouc from the style detection of headers at runtime remains.

[ang-zeyu]

Some existing solutions / compromises:

• position: fixed + we know the height of the header beforehand (e.g. see https://vuepress.vuejs.org/guide/): unfortunately not an option in our case (by far the most common one around)
• position: sticky + accept the con of shorter elements being hidden behind the header as you scroll down (see https://webpack.js.org/concepts/output/'s left sidebar just for illustration)
• position: sticky + dynamically hide the header like what we're doing for mobile (e.g. https://docusaurus.io/docs)

In general it seems like there is no "easy / ideal way out". The core of the problem is that style detection of the header height is required, something that isn't too common.

[ang-zeyu]

I ended up sidetracking here and there and drafted 3 solutions below on top of the OP's, all of which achieve the aim of "no more fouc" but each has pros and cons.

1. (OP's) Fix header padding fouc (1st version w/ dynamically fixed header) #1929
   • simplest option (implementation wise) that activates position: fixed only when the reader scrolls past the header. our fixed-header-padding class's height is also only "populated" once this is done.
   • pros: simple implementation
   • cons: not sticky (no element can be above the header) (e.g. announcement at the top of the page but should not follow the header as you scroll downward)
2. (~70% complete, edge cases with window resizing remain) Fix header padding fouc (2nd version w/ sticky header, implemented w/ position:fixed) #1930
   • this is the most complex option. It implements a sticky header using position: fixed + scrolling detection.
   • pros: position: sticky positioning rules / nuances do not have to be followed (e.g. sticky element must be placed as a direct child of "scroll container"), increasing author convenience. Vs opt 3, parts of the sidebars will not be hidden too.
   • cons: very complex implementation wise (the pr is not quite done yet), not sure if its quite worth it. Not quite a canonical sticky positioning (per css spec) as well.
3. Fix header padding fouc (3rd version w/ sticky header, implemented w/ position:sticky) #1931
   • uses position: sticky to implement the sticky header. the fixed/sticky-header-padding class is removed in this case
   • pros: simple implementation, author-friendly (no fixed/sticky-header-padding class)
   • cons: ❗ part of the sidebars will be hidden as you scroll down
4. (not implemented) option 3 with dynamically hidden header. Will "resolve" option 3's con.

Honestly not too sure which we should go with.

• Option 1 can be viable as a minimal addition on top of our existing implementation. Personally slightly tending toward this for now (then see how things turn out again later). But still worth discussing the rest.
• Option 2 seems complex implementation wise, although it is the most "robust" (but dosen't quite conform to css "sticky" concepts / nuances which might need some elaborate explaining to authors).
• Ideally option 3's con didn't exist, then it could work since we assume authors have some html knowledge (of position: sticky's nuances). Option 4 resolves it but dosen't look the best (the header is hidden).
  • the con seems ok for the site nav but particularly damaging to the page nav (e.g. here)

Wdyt? @jonahtanjz

ps: the tests in the PRs will be updated once this is resolved

[jonahtanjz]

Option 1 can be viable as a minimal addition on top of our existing implementation. Personally slightly tending toward this for now (then see how things turn out again later). But still worth discussing the rest.

I am also leaning towards option 1 as it is the simplest implementation-wise compared to the other options.

cons: not sticky (no element can be above the header) (e.g. announcement at the top of the page but should not follow the header as you scroll downward)

Perhaps we can introduce a new component to MarkBind to support announcement bar? This seems like a good addition as currently announcements have to be implemented manually by the user. Having a native announcement bar in MarkBind should make it easier for users to add elements before/after the header and also toggle between fixed/non-fixed bar accordingly (#1631). This will also help to resolve most of the concerns if we go with Option 1.

[ang-zeyu]

I am also leaning towards option 1 as it is the simplest implementation-wise compared to the other options.

👍, I'll cleanup the PR sometime soon and ping when its ready. (sorry, backtracking a little with the item you raised)

*Missed mentioning: while simple incrementally, option 3/4 should be the simplest when considered in whole.

Perhaps we can introduce a new component to MarkBind to support announcement bar? This seems like a good addition as currently announcements have to be implemented manually by the user. Having a native announcement bar in MarkBind should make it easier for users to add elements before/after the header and also toggle between fixed/non-fixed bar accordingly (#1631). This will also help to resolve most of the concerns if we go with Option 1.

Thanks for raising this.. hmm...

I think we should we leave the announcement bar design to the author, since its one of the reasons of having expressive layouts. Also quite a few announcement bar designs to account for in a single component. More importantly it shouldn't be too much trouble to design this one-off thing from the author side (maybe @damithc can chip in here w.r.t to that discussion). But I'm ok if this can add enough value otherwise. (e.g. navbars are also one off but feature rich enough to warrant them)

But more importantly (not sure if this was accounted for) supporting this would ultimately still require implementing sticky positioning (via option 2 or 3) as well.

---

I think that discussion thread also brings up again whether supporting something like a fixed-header-padding is a flexible enough (in addition to not being user friendly) in the first place. (ref #1631 (reply in thread))

Previously I imagined you could place the banner below the header as a workaround (but didn't recall that discussion).

Wonder if we should go with 3/4 after all as such, it seems to be more generalisable although not optimal-looking. (at best the header is hidden when you scroll down)

---

Likely problematic food for thought:

To implement a fixed-positioned header, maybe instead we provide some instructions in the documentation on how to do so, following the most common solution around:

position: fixed + we know the height of the header beforehand (e.g. see https://vuepress.vuejs.org/guide/): unfortunately not an option in our case (by far the most common one around)

i.e. author manually measures the header size on some screen sizes and sets the padding-top manually. Although, even this is sometimes tricky (differing user agent stylesheets for one can change font styles/sizes/paddings and thus the height of headers).

---

or we can support both options 1 & 4, and advise when to use each in the documentation.

maybe one thing we can agree on first is that option 2 is definitely not the way to go (interesting experiment but difficult to explain and too complex (not even done yet) in implementation 😅)