From ffa6de96c2800b8d688287c913eb86e95b28ae04 Mon Sep 17 00:00:00 2001
From: Ze Yu <angzeyu@gmail.com>
Date: Thu, 12 May 2022 16:42:49 +0800
Subject: [PATCH] Sticky using fixed

---
 docs/_markbind/layouts/default.md             |  2 +-
 docs/_markbind/layouts/devGuide.md            |  6 ++--
 docs/_markbind/layouts/headers/header.md      |  4 ++-
 docs/_markbind/layouts/userGuide.md           |  6 ++--
 docs/css/main.css                             |  4 +--
 docs/userGuide/tweakingThePageStructure.md    | 20 +++++------
 .../test_site/_markbind/layouts/default.md    |  6 ++--
 .../test_site/stylesheets/styles.css          |  4 +--
 .../non_markbind_site/stylesheets/main.css    |  4 +--
 .../non_markbind_site/stylesheets/main.css    |  4 +--
 packages/core-web/src/index.js                | 35 ++++++++++++++++---
 packages/core-web/src/styles/markbind.css     | 21 +++++++----
 packages/core/src/Site/siteConvertLayout.njk  |  8 ++---
 packages/core/src/html/NodeProcessor.js       |  2 +-
 .../default/_markbind/layouts/default.md      |  8 ++---
 .../template/default/stylesheets/main.css     |  4 +--
 .../vue-components/src/panels/PanelBase.js    |  2 +-
 17 files changed, 88 insertions(+), 52 deletions(-)

diff --git a/docs/_markbind/layouts/default.md b/docs/_markbind/layouts/default.md
index 6f96588826..66a782d496 100644
--- a/docs/_markbind/layouts/default.md
+++ b/docs/_markbind/layouts/default.md
@@ -1,7 +1,7 @@
 <include src="headers/header.md" />
 
 <div id="flex-body">
-  <div id="content-wrapper" class="fixed-header-padding">
+  <div id="content-wrapper" class="sticky-header-padding">
     {{ content }}
   </div>
 </div>
diff --git a/docs/_markbind/layouts/devGuide.md b/docs/_markbind/layouts/devGuide.md
index 75d0c17d69..43b6865080 100644
--- a/docs/_markbind/layouts/devGuide.md
+++ b/docs/_markbind/layouts/devGuide.md
@@ -1,7 +1,7 @@
 <include src="headers/header.md" />
 
 <div id="flex-body">
-  <nav id="site-nav" class="fixed-header-padding">
+  <nav id="site-nav" class="sticky-header-padding">
     <div class="site-nav-top">
       <div class="fw-bold mb-2" style="font-size: 1.25rem;">Developer Guide</div>
     </div>
@@ -27,10 +27,10 @@
       </site-nav>
     </div>
   </nav>
-  <div id="content-wrapper" class="fixed-header-padding">
+  <div id="content-wrapper" class="sticky-header-padding">
     {{ content }}
   </div>
-  <nav id="page-nav" class="fixed-header-padding">
+  <nav id="page-nav" class="sticky-header-padding">
     <div class="nav-component slim-scroll">
       <page-nav />
     </div>
diff --git a/docs/_markbind/layouts/headers/header.md b/docs/_markbind/layouts/headers/header.md
index 61eae0e562..c25f463ac0 100644
--- a/docs/_markbind/layouts/headers/header.md
+++ b/docs/_markbind/layouts/headers/header.md
@@ -2,7 +2,9 @@
   <link rel="stylesheet" href="{{baseUrl}}/css/main.css">
 </head-bottom>
 
-<header fixed>
+This is a breaking change
+
+<header sticky>
   <navbar type="dark">
     <a slot="brand" href="{{baseUrl}}/index.html" title="Home" class="navbar-brand"><img src="{{baseUrl}}/images/logo-darkbackground.svg" height="20"></a>
     <li><a highlight-on="exact" href="{{baseUrl}}/index.html" class="nav-link">HOME</a></li>
diff --git a/docs/_markbind/layouts/userGuide.md b/docs/_markbind/layouts/userGuide.md
index 273503b8e3..eea7c1df66 100644
--- a/docs/_markbind/layouts/userGuide.md
+++ b/docs/_markbind/layouts/userGuide.md
@@ -1,7 +1,7 @@
 <include src="headers/header.md" />
 
 <div id="flex-body">
-  <nav id="site-nav" class="fixed-header-padding">
+  <nav id="site-nav" class="sticky-header-padding">
     <div class="site-nav-top">
       <div class="fw-bold mb-2" style="font-size: 1.25rem;">User Guide</div>
     </div>
@@ -44,10 +44,10 @@
       </site-nav>
     </div>
   </nav>
-  <div id="content-wrapper" class="fixed-header-padding">
+  <div id="content-wrapper" class="sticky-header-padding">
     {{ content }}
   </div>
-  <nav id="page-nav" class="fixed-header-padding">
+  <nav id="page-nav" class="sticky-header-padding">
     <div class="nav-component slim-scroll">
       <page-nav />
     </div>
diff --git a/docs/css/main.css b/docs/css/main.css
index 1963c65fd0..21356e46d0 100644
--- a/docs/css/main.css
+++ b/docs/css/main.css
@@ -56,7 +56,8 @@ mark {
     margin: 0 auto;
     min-width: 0;
     max-width: 1000px;
-    padding: 0.8rem 20px 0 20px;
+    padding: 0 20px;
+    margin-top: 0.8rem;
     transition: 0.4s;
     -webkit-transition: 0.4s;
 }
@@ -66,7 +67,6 @@ mark {
     position: sticky;
     top: 0;
     flex: 0 0 auto;
-    padding-top: 1rem;
     max-width: 300px;
     width: 300px;
 }
diff --git a/docs/userGuide/tweakingThePageStructure.md b/docs/userGuide/tweakingThePageStructure.md
index 972c2a460d..ea09e242ac 100644
--- a/docs/userGuide/tweakingThePageStructure.md
+++ b/docs/userGuide/tweakingThePageStructure.md
@@ -46,8 +46,8 @@ Next, edit the layout file to your liking, and add the `{% raw %}{{ content }}{%
   <link rel="stylesheet" href="{{baseUrl}}/css/main.css">
 </head-bottom>
 
-<!-- Fix the header to the top while scrolling using the fixed attribute in a <header> tag -->
-<header fixed>
+<!-- Create a sticky header using the sticky attribute in a <header> tag -->
+<header sticky>
   <navbar type="dark">
     <a slot="brand" href="{{baseUrl}}/index.html" title="Home" class="navbar-brand">
       <img src="{{baseUrl}}/images/logo-darkbackground.svg" height="20">
@@ -70,8 +70,8 @@ Next, edit the layout file to your liking, and add the `{% raw %}{{ content }}{%
 </header>
 
 <div id="flex-body">
-  <!-- Push content downward when using a fixed header with the fixed-header-padding class -->
-  <nav id="site-nav" class="fixed-header-padding">
+  <!-- Push content downward when using a sticky header with the sticky-header-padding class -->
+  <nav id="site-nav" class="sticky-header-padding">
     <div class="site-nav-top">
       <div class="fw-bold mb-2" style="font-size: 1.25rem;">User Guide</div>
     </div>
@@ -87,11 +87,11 @@ Next, edit the layout file to your liking, and add the `{% raw %}{{ content }}{%
       </site-nav>
     </div>
   </nav>
-  <div id="content-wrapper" class="fixed-header-padding">
+  <div id="content-wrapper" class="sticky-header-padding">
     <!-- Insert the page's content into the layout using the {{ content }} variable -->
     {{ content }}
   </div>
-  <nav id="page-nav" class="fixed-header-padding">
+  <nav id="page-nav" class="sticky-header-padding">
     <div class="nav-component slim-scroll">
       <!-- Insert a page navigation menu using the <page-nav /> component -->
       <page-nav />
@@ -150,16 +150,16 @@ If you wish insert scripts at the bottom, before MarkBind's scripts, simply inse
 
 ### Fixing the header to the top
 
-Headers are commonly included inside the html `<header>` tag. In encouraging this, a convenient interface to implement <tooltip content="Headers that stick to the top of the page while scrolling the content">fixed headers</tooltip> surrounding the `<header>` tag is provided that ensures page anchors work correctly.
+Headers are commonly included inside the html `<header>` tag. In encouraging this, a convenient interface to implement sticky headers using the `<header>` tag is provided that ensures page anchors work correctly.
 
 ****To fix the `<header>`****
-1. Add the `fixed` attribute to your `<header>` element in the layout per the above example.
+1. Add the `sticky` attribute to your `<header>` element in the layout per the above example.
 
-2. Then, to add the necessary top padding for the main content, add the `fixed-header-padding` class to **elements that should be shifted down** in accordance with the fixed header.
+2. Then, to add the necessary top padding for the main content, add the `sticky-header-padding` class to **any other elements that should be shifted down** in accordance with the sticky header.
 
 <box type="tip" seamless>
 
-If you are not sure where to put the `fixed-header-padding` attribute, you may also refer to the default template for `markbind init`, which already has this setup.
+If you are not sure where to put the `sticky-header-padding` attribute, you may also refer to the default template for `markbind init`, which already has this setup.
 </box>
 
 ---
diff --git a/packages/cli/test/functional/test_site/_markbind/layouts/default.md b/packages/cli/test/functional/test_site/_markbind/layouts/default.md
index adbe2f24b6..66f24c417f 100644
--- a/packages/cli/test/functional/test_site/_markbind/layouts/default.md
+++ b/packages/cli/test/functional/test_site/_markbind/layouts/default.md
@@ -11,7 +11,7 @@
 <include src="headers/header.md" />
 
 <div id="flex-body">
-  <nav id="site-nav" class="fixed-header-padding">
+  <nav id="site-nav" class="sticky-header-padding">
     <div class="site-nav-top">
       <div class="fw-bold mb-2" style="font-size: 1.25rem;"><markdown>## {{ layoutName or "Default Layout" }}</markdown></div>
     </div>
@@ -19,10 +19,10 @@
       <include src="navigation/site-nav.md" />
     </div>
   </nav>
-  <div id="content-wrapper" class="fixed-header-padding">
+  <div id="content-wrapper" class="sticky-header-padding">
     {{ content }}
   </div>
-  <nav id="page-nav" class="fixed-header-padding">
+  <nav id="page-nav" class="sticky-header-padding">
     <div class="nav-component slim-scroll">
       <page-nav />
     </div>
diff --git a/packages/cli/test/functional/test_site/stylesheets/styles.css b/packages/cli/test/functional/test_site/stylesheets/styles.css
index c58b8a5120..5e0373a224 100644
--- a/packages/cli/test/functional/test_site/stylesheets/styles.css
+++ b/packages/cli/test/functional/test_site/stylesheets/styles.css
@@ -56,7 +56,8 @@ mark {
     margin: 0 auto;
     min-width: 0;
     max-width: 1000px;
-    padding: 0.8rem 20px 0 20px;
+    padding: 0 20px;
+    margin-top: 0.8rem;
     transition: 0.4s;
     -webkit-transition: 0.4s;
 }
@@ -66,7 +67,6 @@ mark {
     position: sticky;
     top: 0;
     flex: 0 0 auto;
-    padding-top: 1rem;
     max-width: 300px;
     width: 300px;
 }
diff --git a/packages/cli/test/functional/test_site_convert/test_basic_convert/non_markbind_site/stylesheets/main.css b/packages/cli/test/functional/test_site_convert/test_basic_convert/non_markbind_site/stylesheets/main.css
index c58b8a5120..5e0373a224 100644
--- a/packages/cli/test/functional/test_site_convert/test_basic_convert/non_markbind_site/stylesheets/main.css
+++ b/packages/cli/test/functional/test_site_convert/test_basic_convert/non_markbind_site/stylesheets/main.css
@@ -56,7 +56,8 @@ mark {
     margin: 0 auto;
     min-width: 0;
     max-width: 1000px;
-    padding: 0.8rem 20px 0 20px;
+    padding: 0 20px;
+    margin-top: 0.8rem;
     transition: 0.4s;
     -webkit-transition: 0.4s;
 }
@@ -66,7 +67,6 @@ mark {
     position: sticky;
     top: 0;
     flex: 0 0 auto;
-    padding-top: 1rem;
     max-width: 300px;
     width: 300px;
 }
diff --git a/packages/cli/test/functional/test_site_convert/test_navigation_convert/non_markbind_site/stylesheets/main.css b/packages/cli/test/functional/test_site_convert/test_navigation_convert/non_markbind_site/stylesheets/main.css
index 1963c65fd0..21356e46d0 100644
--- a/packages/cli/test/functional/test_site_convert/test_navigation_convert/non_markbind_site/stylesheets/main.css
+++ b/packages/cli/test/functional/test_site_convert/test_navigation_convert/non_markbind_site/stylesheets/main.css
@@ -56,7 +56,8 @@ mark {
     margin: 0 auto;
     min-width: 0;
     max-width: 1000px;
-    padding: 0.8rem 20px 0 20px;
+    padding: 0 20px;
+    margin-top: 0.8rem;
     transition: 0.4s;
     -webkit-transition: 0.4s;
 }
@@ -66,7 +67,6 @@ mark {
     position: sticky;
     top: 0;
     flex: 0 0 auto;
-    padding-top: 1rem;
     max-width: 300px;
     width: 300px;
 }
diff --git a/packages/core-web/src/index.js b/packages/core-web/src/index.js
index 45091b6722..39ba109120 100644
--- a/packages/core-web/src/index.js
+++ b/packages/core-web/src/index.js
@@ -21,16 +21,16 @@ function scrollToUrlAnchorHeading() {
   }
 }
 
-function detectAndApplyFixedHeaderStyles() {
+function detectAndApplyStickyHeaderStyles() {
   jQuery(':header').each((index, heading) => {
     if (heading.id) {
       jQuery(heading).removeAttr('id'); // to avoid duplicated id problem
     }
   });
 
-  const headerSelector = jQuery('header[fixed]');
-  const isFixed = headerSelector.length !== 0;
-  if (!isFixed) {
+  const headerSelector = jQuery('header[sticky]');
+  const isSticky = headerSelector.length !== 0;
+  if (!isSticky) {
     return;
   }
 
@@ -49,6 +49,31 @@ function detectAndApplyFixedHeaderStyles() {
     }
   };
 
+  /*
+   Handle dynamic sticky header listener to
+   prevent FOUC from sudden quick movement of padding-top application.
+   see https://www.w3schools.com/howto/howto_js_sticky_header.asp
+   */
+  let headerOffsetTop = headerSelector[0].offsetTop;
+  let isFixed = false;
+  const dynamicStickyHeaderListener = () => {
+    if (window.scrollY > headerSelector[0].offsetTop
+      && !isFixed
+    ) {
+      // Keep track of the offset "at the time it becomes sticky"
+      // still a wip
+      headerOffsetTop = headerSelector[0].offsetTop;
+      isFixed = true;
+      document.documentElement.style.setProperty('--header-padding', 'var(--header-height)');
+      document.documentElement.style.setProperty('--header-position', 'fixed');
+    } else if (window.scrollY <= headerOffsetTop) {
+      isFixed = false;
+      document.documentElement.style.setProperty('--header-padding', '0');
+      document.documentElement.style.setProperty('--header-position', 'static');
+    }
+  };
+  window.addEventListener('scroll', dynamicStickyHeaderListener);
+
   let lastOffset = 0;
   let lastHash = window.location.hash;
   const toggleHeaderOnScroll = () => {
@@ -125,7 +150,7 @@ function restoreStyleTags() {
 function executeAfterMountedRoutines() {
   restoreStyleTags();
   scrollToUrlAnchorHeading();
-  detectAndApplyFixedHeaderStyles();
+  detectAndApplyStickyHeaderStyles();
 }
 
 window.handleSiteNavClick = function (elem, useAnchor = true) {
diff --git a/packages/core-web/src/styles/markbind.css b/packages/core-web/src/styles/markbind.css
index ae59cbbda8..b4944eac9c 100644
--- a/packages/core-web/src/styles/markbind.css
+++ b/packages/core-web/src/styles/markbind.css
@@ -1,5 +1,7 @@
 :root {
     --header-height: 0;
+    --header-padding: 0;
+    --header-position: 'static';
 }
 
 a {
@@ -127,15 +129,16 @@ code.hljs.inline {
 
 /* Header */
 
-header[fixed] {
+header[sticky] {
+    position: var(--header-position);
+    top: 0;
     max-height: 100%;
-    position: fixed;
     transition: max-height 0.6s ease-in;
     width: 100%;
     z-index: 1001;
 }
 
-header[fixed].hide-header {
+header[sticky].hide-header {
     max-height: 0;
     transition: max-height 0.6s ease-out;
 }
@@ -145,12 +148,18 @@ span.anchor {
     top: calc(-1 * var(--header-height) - 1rem);
 }
 
-header[fixed] .nav-menu-open {
+header[sticky] .nav-menu-open {
     max-height: calc(-1 * var(--header-height) + 100% + 50px);
 }
 
-.fixed-header-padding {
-    padding-top: var(--header-height) !important;
+/*
+  Prevent sudden quick movement of page content with the dynamically sticky header.
+  The padding-top property is set dynamically according to the header height in index.js.
+  (see https://www.w3schools.com/howto/howto_js_sticky_header.asp)
+*/
+.sticky-header-padding {
+    padding-top: var(--header-padding) !important;
+    transition: padding-top 0s linear !important;
 }
 
 /* #app is treated as the main container */
diff --git a/packages/core/src/Site/siteConvertLayout.njk b/packages/core/src/Site/siteConvertLayout.njk
index e83ce73e2f..12fe9aeb51 100644
--- a/packages/core/src/Site/siteConvertLayout.njk
+++ b/packages/core/src/Site/siteConvertLayout.njk
@@ -2,7 +2,7 @@
   <link rel="stylesheet" href="{% raw %}{{baseUrl}}{% endraw %}/stylesheets/main.css">
 </head-bottom>
 
-<header fixed>
+<header sticky>
   <navbar placement="top" type="inverse">
     <a slot="brand" href="{% raw %}{{baseUrl}}{% endraw %}/index.html" title="Home" class="navbar-brand">
       <i class="far fa-file-image"></i>
@@ -18,7 +18,7 @@
 </header>
 
 <div id="flex-body">
-  <nav id="site-nav" class="fixed-header-padding">
+  <nav id="site-nav" class="sticky-header-padding">
     <div class="site-nav-top">
       <div class="fw-bold mb-2" style="font-size: 1.25rem;">Template</div>
     </div>
@@ -28,10 +28,10 @@
       </site-nav>
     </div>
   </nav>
-  <div id="content-wrapper" class="fixed-header-padding">
+  <div id="content-wrapper" class="sticky-header-padding">
     {% raw %}{{ content }}{% endraw %}
   </div>
-  <nav id="page-nav" class="fixed-header-padding">
+  <nav id="page-nav" class="sticky-header-padding">
     <div class="nav-component slim-scroll">
       <page-nav />
     </div>
diff --git a/packages/core/src/html/NodeProcessor.js b/packages/core/src/html/NodeProcessor.js
index 2bf5b64452..52a87418c2 100644
--- a/packages/core/src/html/NodeProcessor.js
+++ b/packages/core/src/html/NodeProcessor.js
@@ -305,7 +305,7 @@ class NodeProcessor {
       setHeadingId(node, this.config);
     }
 
-    // If a fixed header is applied to the page, generate dummy spans as anchor points
+    // If a sticky header is applied to the page, generate dummy spans as anchor points
     if (isHeadingTag && node.attribs.id) {
       cheerio(node).prepend(`<span id="${node.attribs.id}" class="anchor"></span>`);
     }
diff --git a/packages/core/template/default/_markbind/layouts/default.md b/packages/core/template/default/_markbind/layouts/default.md
index 72d2bb68b0..176c56f836 100644
--- a/packages/core/template/default/_markbind/layouts/default.md
+++ b/packages/core/template/default/_markbind/layouts/default.md
@@ -2,7 +2,7 @@
   <link rel="stylesheet" href="{{baseUrl}}/stylesheets/main.css">
 </head-bottom>
 
-<header fixed>
+<header sticky>
   <navbar type="dark">
     <a slot="brand" href="{{baseUrl}}/index.html" title="Home" class="navbar-brand">Your Logo</a>
     <li><a href="{{baseUrl}}/contents/topic1.html" class="nav-link">Topic 1</a></li>
@@ -20,7 +20,7 @@
 </header>
 
 <div id="flex-body">
-  <nav id="site-nav" class="fixed-header-padding">
+  <nav id="site-nav" class="sticky-header-padding">
     <div class="site-nav-top">
       <div class="fw-bold mb-2" style="font-size: 1.25rem;">Template</div>
     </div>
@@ -35,10 +35,10 @@
       </site-nav>
     </div>
   </nav>
-  <div id="content-wrapper" class="fixed-header-padding">
+  <div id="content-wrapper" class="sticky-header-padding">
     {{ content }}
   </div>
-  <nav id="page-nav" class="fixed-header-padding">
+  <nav id="page-nav" class="sticky-header-padding">
     <div class="nav-component slim-scroll">
       <page-nav />
     </div>
diff --git a/packages/core/template/default/stylesheets/main.css b/packages/core/template/default/stylesheets/main.css
index 1963c65fd0..21356e46d0 100644
--- a/packages/core/template/default/stylesheets/main.css
+++ b/packages/core/template/default/stylesheets/main.css
@@ -56,7 +56,8 @@ mark {
     margin: 0 auto;
     min-width: 0;
     max-width: 1000px;
-    padding: 0.8rem 20px 0 20px;
+    padding: 0 20px;
+    margin-top: 0.8rem;
     transition: 0.4s;
     -webkit-transition: 0.4s;
 }
@@ -66,7 +67,6 @@ mark {
     position: sticky;
     top: 0;
     flex: 0 0 auto;
-    padding-top: 1rem;
     max-width: 300px;
     width: 300px;
 }
diff --git a/packages/vue-components/src/panels/PanelBase.js b/packages/vue-components/src/panels/PanelBase.js
index 83825078f9..d9fd4e8ed9 100644
--- a/packages/vue-components/src/panels/PanelBase.js
+++ b/packages/vue-components/src/panels/PanelBase.js
@@ -145,7 +145,7 @@ export default {
         requestAnimationFrame(() => {
           // To enable behaviour of auto window scrolling during panel collapse
           if (this.$el.getBoundingClientRect().top < 0) {
-            const headerHeight = jQuery('header[fixed]').height() || 0;
+            const headerHeight = jQuery('header[sticky]').height() || 0;
             jQuery('html').animate({
               scrollTop: window.scrollY + this.$el.getBoundingClientRect().top - headerHeight - 3,
             }, 500, 'swing');