feat: show toc on mobile screens (#1964)

_includes/toc-status.html

@@ -0,0 +1,10 @@
+{% comment %}
+  Determine TOC state and return it through variable "enable_toc"
+{% endcomment %}
+
+{% assign enable_toc = false %}
+{% if site.toc and page.toc %}
+  {% if page.content contains '<h2' or page.content contains '<h3' %}
+    {% assign enable_toc = true %}
+  {% endif %}
+{% endif %}

_includes/toc.html

@@ -1,12 +1,7 @@
-{% assign enable_toc = false %}
-{% if site.toc and page.toc %}
-  {% if page.content contains '<h2' or page.content contains '<h3' %}
-    {% assign enable_toc = true %}
-  {% endif %}
-{% endif %}
+{% include toc-status.html %}
 
 {% if enable_toc %}
-  <section id="toc-wrapper" class="d-none ps-0 pe-4">
+  <section id="toc-wrapper" class="ps-0 pe-4">
     <h2 class="panel-heading ps-3 mb-2">{{- site.data.locales[include.lang].panel.toc -}}</h2>
     <nav id="toc"></nav>
   </section>

_javascript/modules/components/toc.js

@@ -1,15 +1,30 @@
-export function toc() {
-  if (document.querySelector('main h2, main h3')) {
-    // see: https://github.com/tscanlin/tocbot#usage
-    tocbot.init({
-      tocSelector: '#toc',
-      contentSelector: '.content',
-      ignoreSelector: '[data-toc-skip]',
-      headingSelector: 'h2, h3, h4',
-      orderedList: false,
-      scrollSmooth: false
-    });
+import { TocMobile as mobile } from './toc/toc-mobile';
+import { TocDesktop as desktop } from './toc/toc-desktop';
 
-    document.getElementById('toc-wrapper').classList.remove('d-none');
+const desktopMode = matchMedia('(min-width: 1200px)');
+
+function refresh(e) {
+  if (e.matches) {
+    mobile.hidePopup();
+    desktop.refresh();
+  } else {
+    mobile.refresh();
   }
 }
+
+function init() {
+  if (document.querySelector('main>article[data-toc="true"]') === null) {
+    return;
+  }
+
+  // Avoid create multiple instances of Tocbot. Ref: <https://github.com/tscanlin/tocbot/issues/203>
+  if (desktopMode.matches) {
+    desktop.init();
+  } else {
+    mobile.init();
+  }
+
+  desktopMode.onchange = refresh;
+}
+
+export { init as initToc };

_javascript/modules/components/toc/toc-desktop.js

@@ -0,0 +1,22 @@
+export class TocDesktop {
+  /* Tocbot options Ref: https://github.com/tscanlin/tocbot#usage */
+  static options = {
+    tocSelector: '#toc',
+    contentSelector: '.content',
+    ignoreSelector: '[data-toc-skip]',
+    headingSelector: 'h2, h3, h4',
+    orderedList: false,
+    scrollSmooth: false,
+    headingsOffset: 16 * 2 // 2rem
+  };
+
+  static refresh() {
+    tocbot.refresh(this.options);
+  }
+
+  static init() {
+    if (document.getElementById('toc-wrapper')) {
+      tocbot.init(this.options);
+    }
+  }
+}

_javascript/modules/components/toc/toc-mobile.js

@@ -0,0 +1,117 @@
+/**
+ * TOC button, topbar and popup for mobile devices
+ */
+
+const $tocBar = document.getElementById('toc-bar');
+const $soloTrigger = document.getElementById('toc-solo-trigger');
+const $triggers = document.getElementsByClassName('toc-trigger');
+const $popup = document.getElementById('toc-popup');
+const $btnClose = document.getElementById('toc-popup-close');
+
+const SCROLL_LOCK = 'overflow-hidden';
+const CLOSING = 'closing';
+
+export class TocMobile {
+  static invisible = true;
+  static barHeight = 16 * 3; // 3rem
+
+  static options = {
+    tocSelector: '#toc-popup-content',
+    contentSelector: '.content',
+    ignoreSelector: '[data-toc-skip]',
+    headingSelector: 'h2, h3, h4',
+    orderedList: false,
+    scrollSmooth: false,
+    collapseDepth: 4,
+    headingsOffset: this.barHeight
+  };
+
+  static initBar() {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          $tocBar.classList.toggle('invisible', entry.isIntersecting);
+        });
+      },
+      { rootMargin: `-${this.barHeight}px 0px 0px 0px` }
+    );
+
+    observer.observe($soloTrigger);
+    this.invisible = false;
+  }
+
+  static listenAnchors() {
+    const $anchors = document.getElementsByClassName('toc-link');
+    [...$anchors].forEach((anchor) => {
+      anchor.onclick = this.hidePopup;
+    });
+  }
+
+  static refresh() {
+    if (this.invisible) {
+      this.initComponents();
+    }
+    tocbot.refresh(this.options);
+    this.listenAnchors();
+  }
+
+  static showPopup() {
+    TocMobile.lockScroll(true);
+    $popup.showModal();
+    const activeItem = $popup.querySelector('li.is-active-li');
+    activeItem.scrollIntoView({ block: 'center' });
+  }
+
+  static hidePopup() {
+    if (!$popup.open) {
+      return;
+    }
+
+    $popup.toggleAttribute(CLOSING);
+
+    $popup.addEventListener(
+      'animationend',
+      () => {
+        $popup.toggleAttribute(CLOSING);
+        $popup.close();
+      },
+      { once: true }
+    );
+
+    TocMobile.lockScroll(false);
+  }
+
+  static lockScroll(enable) {
+    document.documentElement.classList.toggle(SCROLL_LOCK, enable);
+    document.body.classList.toggle(SCROLL_LOCK, enable);
+  }
+
+  static clickBackdrop(event) {
+    const rect = event.target.getBoundingClientRect();
+    if (
+      event.clientX < rect.left ||
+      event.clientX > rect.right ||
+      event.clientY < rect.top ||
+      event.clientY > rect.bottom
+    ) {
+      TocMobile.hidePopup();
+    }
+  }
+
+  static initComponents() {
+    this.initBar();
+
+    [...$triggers].forEach((trigger) => {
+      trigger.onclick = this.showPopup;
+    });
+
+    $popup.onclick = this.clickBackdrop;
+    $btnClose.onclick = $popup.oncancel = this.hidePopup;
+  }
+
+  static init() {
+    tocbot.init(this.options);
+    this.listenAnchors();
+    this.initComponents();
+  }
+}

_javascript/modules/plugins.js

@@ -3,4 +3,4 @@ export { initClipboard } from './components/clipboard';
 export { loadImg } from './components/img-loading';
 export { imgPopup } from './components/img-popup';
 export { initLocaleDatetime } from './components/locale-datetime';
-export { toc } from './components/toc';
+export { initToc } from './components/toc';

_javascript/post.js

@@ -1,14 +1,15 @@
-import { basic, initSidebar, initTopbar } from './modules/layouts';
+import { basic, initTopbar, initSidebar } from './modules/layouts';
+
 import {
   loadImg,
   imgPopup,
   initLocaleDatetime,
   initClipboard,
-  toc
+  initToc
 } from './modules/plugins';
 
 loadImg();
-toc();
+initToc();
 imgPopup();
 initSidebar();
 initLocaleDatetime();

_layouts/post.html

@@ -11,7 +11,9 @@ tail_includes:
 
 {% include lang.html %}
 
-<article class="px-1">
+{% include toc-status.html %}
+
+<article class="px-1" data-toc="{{ enable_toc }}">
   <header>
     <h1 data-toc-skip>{{ page.title }}</h1>
     {% if page.description %}
@@ -95,6 +97,30 @@ tail_includes:
     </div>
   </header>
 
+  {% if enable_toc %}
+    <div id="toc-bar" class="d-flex align-items-center justify-content-between invisible">
+      <span class="label text-truncate">{{ page.title }}</span>
+      <button type="button" class="toc-trigger btn btn-link me-1">
+        <i class="fa-solid fa-list-ul fa-fw"></i>
+      </button>
+    </div>
+
+    <button id="toc-solo-trigger" type="button" class="toc-trigger btn btn-outline-secondary btn-sm">
+      <span class="label ps-2 pe-1">{{- site.data.locales[lang].panel.toc -}}</span>
+      <i class="fa-solid fa-angle-right fa-fw"></i>
+    </button>
+
+    <dialog id="toc-popup" class="p-0">
+      <div class="header d-flex flex-row align-items-center justify-content-between">
+        <div class="label text-truncate py-2 ms-4">{{- page.title -}}</div>
+        <button id="toc-popup-close" type="button" class="btn btn-link">
+          <i class="fas fa-close fa-fw"></i>
+        </button>
+      </div>
+      <div id="toc-popup-content" class="px-4 py-3 pb-4"></div>
+    </dialog>
+  {% endif %}
+
   <div class="content">
     {{ content }}
   </div>

_sass/addon/commons.scss

@@ -908,9 +908,7 @@ $btn-mb: 0.5rem;
 }
 
 #topbar {
-  button i {
-    color: #999999;
-  }
+  @extend %btn-color;
 
   #breadcrumb {
     font-size: 1rem;

_sass/addon/module.scss

@@ -8,6 +8,7 @@
   color: var(--heading-color);
   font-weight: 400;
   font-family: $font-family-heading;
+  scroll-margin-top: 3.5rem;
 }
 
 %anchor {
@@ -134,6 +135,12 @@
   }
 }
 
+%btn-color {
+  button i {
+    color: #999999;
+  }
+}
+
 /* ---------- scss mixin --------- */
 
 @mixin mt-mb($value) {

_sass/colors/typography-dark.scss

@@ -22,7 +22,6 @@
   --btn-border-color: #2e2f31;
   --btn-backtotop-color: var(--text-color);
   --btn-backtotop-border-color: #212122;
-  --btn-box-shadow: var(--main-bg);
   --card-header-bg: #292929;
   --checkbox-color: rgb(118, 120, 121);
   --checkbox-checked-color: var(--link-color);
@@ -60,6 +59,7 @@
 
   /* Posts */
   --toc-highlight: rgb(116, 178, 243);
+  --toc-popup-border-color: #373737;
   --tag-hover: rgb(43, 56, 62);
   --tb-odd-bg: #252526; /* odd rows of the posts' table */
   --tb-even-bg: rgb(31, 31, 34); /* even rows of the posts' table */

_sass/colors/typography-light.scss

@@ -22,7 +22,6 @@
   --btn-border-color: #e9ecef;
   --btn-backtotop-color: #686868;
   --btn-backtotop-border-color: #f1f1f1;
-  --btn-box-shadow: #eaeaea;
   --checkbox-color: #c5c5c5;
   --checkbox-checked-color: #07a8f7;
   --img-bg: radial-gradient(
@@ -63,6 +62,7 @@
 
   /* Posts */
   --toc-highlight: #0550ae;
+  --toc-popup-border-color: lightgray;
   --btn-share-color: gray;
   --btn-share-hover-color: #0d6efd;
   --card-bg: white;

_sass/layout/post.scss

@@ -228,6 +228,7 @@ header {
   }
 }
 
+/* TOC panel */
 #toc-wrapper {
   border-left: 1px solid rgba(158, 158, 158, 0.17);
   position: -webkit-sticky;
@@ -290,6 +291,201 @@ header {
   }
 }
 
+/* --- TOC button, bar and popup in mobile/tablet --- */
+
+#toc-bar {
+  position: -webkit-sticky;
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  margin: 0 -1rem;
+  height: $topbar-height;
+  background: var(--main-bg);
+  border-bottom: 1px solid var(--main-border-color);
+  transition: all 0.2s ease-in-out;
+
+  @extend %btn-color;
+
+  .label {
+    @extend %heading;
+
+    margin-left: 0.25rem;
+    padding: 0 0.75rem;
+    color: inherit;
+  }
+
+  &.invisible {
+    top: -$topbar-height;
+    transition: none;
+  }
+}
+
+#toc-solo-trigger {
+  color: var(--text-muted-color);
+  border-color: var(--btn-border-color);
+  border-radius: $radius-lg;
+
+  .label {
+    font-size: 1rem;
+    font-family: $font-family-heading;
+  }
+
+  &:hover {
+    box-shadow: none;
+    background: none;
+  }
+}
+
+@mixin slide-in {
+  from {
+    opacity: 0.7;
+    transform: translateY(-$topbar-height);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@mixin slide-out {
+  0% {
+    transform: translateY(0);
+    opacity: 1;
+  }
+
+  100% {
+    transform: translateY(-$topbar-height);
+    opacity: 0;
+  }
+}
+
+@-webkit-keyframes slide-in {
+  @include slide-in;
+}
+
+@keyframes slide-in {
+  @include slide-in;
+}
+
+@-webkit-keyframes slide-out {
+  @include slide-out;
+}
+
+@keyframes slide-out {
+  @include slide-out;
+}
+
+#toc-popup {
+  $slide-in: slide-in 0.3s ease-out;
+  $slide-out: slide-out 0.3s ease-out;
+  $curtain-height: 2rem;
+
+  border-color: var(--toc-popup-border-color);
+  border-width: 1px;
+  border-radius: $radius-lg;
+  color: var(--text-color);
+  background: var(--main-bg);
+  margin-top: $topbar-height;
+  min-width: 20rem;
+  font-size: 1.05rem;
+
+  @media all and (min-width: 576px) {
+    max-width: 32rem;
+  }
+
+  &[open] {
+    -webkit-animation: $slide-in;
+    animation: $slide-in;
+  }
+
+  &[closing] {
+    -webkit-animation: $slide-out;
+    animation: $slide-out;
+  }
+
+  @media all and (min-width: 850px) {
+    left: $sidebar-width;
+  }
+
+  .header {
+    @extend %btn-color;
+
+    position: -webkit-sticky;
+    position: sticky;
+    top: 0;
+    background-color: inherit;
+    border-bottom: 1px solid var(--main-border-color);
+
+    .label {
+      font-family: $font-family-heading;
+    }
+  }
+
+  button:focus-visible {
+    box-shadow: none;
+  }
+
+  ul {
+    list-style-type: none;
+    padding-left: 0;
+
+    li {
+      ul,
+      & + li {
+        margin-top: 0.25rem;
+      }
+
+      a {
+        display: flex;
+        line-height: 1.5;
+        padding: 0.375rem 0;
+        padding-right: 1.125rem;
+
+        &.toc-link::before {
+          display: none;
+        }
+      }
+    }
+  }
+
+  @for $i from 2 through 4 {
+    .node-name--H#{$i} {
+      padding-left: 1.125rem * ($i - 1);
+    }
+  }
+
+  .is-active-link {
+    color: var(--toc-highlight) !important;
+    font-weight: 600;
+  }
+
+  &::-webkit-backdrop {
+    -webkit-backdrop-filter: blur(5px);
+    backdrop-filter: blur(5px);
+  }
+
+  &::backdrop {
+    -webkit-backdrop-filter: blur(5px);
+    backdrop-filter: blur(5px);
+  }
+
+  &::after {
+    display: flex;
+    content: '';
+    position: relative;
+    background: linear-gradient(transparent, var(--main-bg) 70%);
+    height: $curtain-height;
+  }
+
+  #toc-popup-content {
+    overflow: auto;
+    max-height: calc(100vh - 4 * $topbar-height);
+    font-family: $font-family-heading;
+    margin-bottom: -$curtain-height;
+  }
+}
+
 /* --- Related Posts --- */
 
 #related-posts {
@@ -368,3 +564,16 @@ header {
     margin-right: -0.5rem;
   }
 }
+
+@media all and (min-width: 1200px) {
+  h2,
+  h3,
+  h4 {
+    scroll-margin-top: 2rem;
+  }
+
+  #toc-bar,
+  #toc-solo-trigger {
+    display: none !important;
+  }
+}