refactor: move some functions and module-level state into classes as private methods and properties to start to encapsulate Docsify

Also some small tweaks:

- move initGlobalAPI out of Docsify.js to start to encapsulate Docsify
- move ajax to utils folder
- fix some type definitions and improve content in some JSDoc comments
- use concise class field syntax
- consolidate duplicate docsify-ignore comment removal code

This handles a task in [Simplify and modernize Docsify](#2104), as well as works towards [Encapsulating Docsify](#2135).

Author: trusktr

src/core/Docsify.js

@@ -3,7 +3,6 @@ import { Render } from './render/index.js';
 import { Fetch } from './fetch/index.js';
 import { Events } from './event/index.js';
 import { VirtualRoutes } from './virtual-routes/index.js';
-import initGlobalAPI from './global-api.js';
 
 import config from './config.js';
 import { isFn } from './util/core.js';
@@ -16,11 +15,11 @@ export class Docsify extends Fetch(
   // eslint-disable-next-line new-cap
   Events(Render(VirtualRoutes(Router(Lifecycle(Object)))))
 ) {
+  config = config(this);
+
   constructor() {
     super();
 
-    this.config = config(this);
-
     this.initLifecycle(); // Init hooks
     this.initPlugin(); // Install plugins
     this.callHook('init');
@@ -46,8 +45,3 @@ export class Docsify extends Fetch(
     });
   }
 }
-
-/**
- * Global API
- */
-initGlobalAPI();

src/core/config.js

@@ -3,7 +3,7 @@ import { hyphenate, isPrimitive } from './util/core.js';
 
 const currentScript = document.currentScript;
 
-/** @param {import('./Docsify').Docsify} vm */
+/** @param {import('./Docsify.js').Docsify} vm */
 export default function (vm) {
   const config = Object.assign(
     {

src/core/event/index.js

@@ -1,9 +1,11 @@
+import Tweezer from 'tweezer.js';
 import { isMobile } from '../util/env.js';
 import { body, on } from '../util/dom.js';
-import * as sidebar from './sidebar.js';
-import { scrollIntoView, scroll2Top } from './scroll.js';
+import * as dom from '../util/dom.js';
+import { removeParams } from '../router/util.js';
+import config from '../config.js';
 
-/** @typedef {import('../Docsify').Constructor} Constructor */
+/** @typedef {import('../Docsify.js').Constructor} Constructor */
 
 /**
  * @template {!Constructor} T
@@ -18,29 +20,300 @@ export function Events(Base) {
       if (source !== 'history') {
         // Scroll to ID if specified
         if (this.route.query.id) {
-          scrollIntoView(this.route.path, this.route.query.id);
+          this.#scrollIntoView(this.route.path, this.route.query.id);
         }
         // Scroll to top if a link was clicked and auto2top is enabled
         if (source === 'navigate') {
-          auto2top && scroll2Top(auto2top);
+          auto2top && this.#scroll2Top(auto2top);
         }
       }
 
       if (this.config.loadNavbar) {
-        sidebar.getAndActive(this.router, 'nav');
+        this.__getAndActive(this.router, 'nav');
       }
     }
 
     initEvent() {
       // Bind toggle button
-      sidebar.btn('button.sidebar-toggle', this.router);
-      sidebar.collapse('.sidebar', this.router);
+      this.#btn('button.sidebar-toggle', this.router);
+      this.#collapse('.sidebar', this.router);
       // Bind sticky effect
       if (this.config.coverpage) {
-        !isMobile && on('scroll', sidebar.sticky);
+        !isMobile && on('scroll', this.__sticky);
       } else {
         body.classList.add('sticky');
       }
     }
+
+    /** @readonly */
+    #nav = {};
+
+    #hoverOver = false;
+    #scroller = null;
+    #enableScrollEvent = true;
+    #coverHeight = 0;
+
+    #scrollTo(el, offset = 0) {
+      if (this.#scroller) {
+        this.#scroller.stop();
+      }
+
+      this.#enableScrollEvent = false;
+      this.#scroller = new Tweezer({
+        start: window.pageYOffset,
+        end:
+          Math.round(el.getBoundingClientRect().top) +
+          window.pageYOffset -
+          offset,
+        duration: 500,
+      })
+        .on('tick', v => window.scrollTo(0, v))
+        .on('done', () => {
+          this.#enableScrollEvent = true;
+          this.#scroller = null;
+        })
+        .begin();
+    }
+
+    #highlight(path) {
+      if (!this.#enableScrollEvent) {
+        return;
+      }
+
+      const sidebar = dom.getNode('.sidebar');
+      const anchors = dom.findAll('.anchor');
+      const wrap = dom.find(sidebar, '.sidebar-nav');
+      let active = dom.find(sidebar, 'li.active');
+      const doc = document.documentElement;
+      const top =
+        ((doc && doc.scrollTop) || document.body.scrollTop) - this.#coverHeight;
+      let last;
+
+      for (const node of anchors) {
+        if (node.offsetTop > top) {
+          if (!last) {
+            last = node;
+          }
+
+          break;
+        } else {
+          last = node;
+        }
+      }
+
+      if (!last) {
+        return;
+      }
+
+      const li = this.#nav[this.#getNavKey(path, last.getAttribute('data-id'))];
+
+      if (!li || li === active) {
+        return;
+      }
+
+      active && active.classList.remove('active');
+      li.classList.add('active');
+      active = li;
+
+      // Scroll into view
+      // https://github.com/vuejs/vuejs.org/blob/master/themes/vue/source/js/common.js#L282-L297
+      if (!this.#hoverOver && dom.body.classList.contains('sticky')) {
+        const height = sidebar.clientHeight;
+        const curOffset = 0;
+        const cur = active.offsetTop + active.clientHeight + 40;
+        const isInView =
+          active.offsetTop >= wrap.scrollTop && cur <= wrap.scrollTop + height;
+        const notThan = cur - curOffset < height;
+
+        sidebar.scrollTop = isInView
+          ? wrap.scrollTop
+          : notThan
+          ? curOffset
+          : cur - height;
+      }
+    }
+
+    #getNavKey(path, id) {
+      return `${decodeURIComponent(path)}?id=${decodeURIComponent(id)}`;
+    }
+
+    __scrollActiveSidebar(router) {
+      const cover = dom.find('.cover.show');
+      this.#coverHeight = cover ? cover.offsetHeight : 0;
+
+      const sidebar = dom.getNode('.sidebar');
+      let lis = [];
+      if (sidebar !== null && sidebar !== undefined) {
+        lis = dom.findAll(sidebar, 'li');
+      }
+
+      for (const li of lis) {
+        const a = li.querySelector('a');
+        if (!a) {
+          continue;
+        }
+
+        let href = a.getAttribute('href');
+
+        if (href !== '/') {
+          const {
+            query: { id },
+            path,
+          } = router.parse(href);
+          if (id) {
+            href = this.#getNavKey(path, id);
+          }
+        }
+
+        if (href) {
+          this.#nav[decodeURIComponent(href)] = li;
+        }
+      }
+
+      if (isMobile) {
+        return;
+      }
+
+      const path = removeParams(router.getCurrentPath());
+      dom.off('scroll', () => this.#highlight(path));
+      dom.on('scroll', () => this.#highlight(path));
+      dom.on(sidebar, 'mouseover', () => {
+        this.#hoverOver = true;
+      });
+      dom.on(sidebar, 'mouseleave', () => {
+        this.#hoverOver = false;
+      });
+    }
+
+    #scrollIntoView(path, id) {
+      if (!id) {
+        return;
+      }
+      const topMargin = config().topMargin;
+      // Use [id='1234'] instead of #id to handle special cases such as reserved characters and pure number id
+      // https://stackoverflow.com/questions/37270787/uncaught-syntaxerror-failed-to-execute-queryselector-on-document
+      const section = dom.find("[id='" + id + "']");
+      section && this.#scrollTo(section, topMargin);
+
+      const li = this.#nav[this.#getNavKey(path, id)];
+      const sidebar = dom.getNode('.sidebar');
+      const active = dom.find(sidebar, 'li.active');
+      active && active.classList.remove('active');
+      li && li.classList.add('active');
+    }
+
+    #scrollEl = dom.$.scrollingElement || dom.$.documentElement;
+
+    #scroll2Top(offset = 0) {
+      this.#scrollEl.scrollTop = offset === true ? 0 : Number(offset);
+    }
+
+    /** @readonly */
+    #title = dom.$.title;
+
+    /**
+     * Toggle button
+     * @param {Element} el Button to be toggled
+     * @void
+     */
+    #btn(el) {
+      const toggle = _ => dom.body.classList.toggle('close');
+
+      el = dom.getNode(el);
+      if (el === null || el === undefined) {
+        return;
+      }
+
+      dom.on(el, 'click', e => {
+        e.stopPropagation();
+        toggle();
+      });
+
+      isMobile &&
+        dom.on(
+          dom.body,
+          'click',
+          _ => dom.body.classList.contains('close') && toggle()
+        );
+    }
+
+    #collapse(el) {
+      el = dom.getNode(el);
+      if (el === null || el === undefined) {
+        return;
+      }
+
+      dom.on(el, 'click', ({ target }) => {
+        if (
+          target.nodeName === 'A' &&
+          target.nextSibling &&
+          target.nextSibling.classList &&
+          target.nextSibling.classList.contains('app-sub-sidebar')
+        ) {
+          dom.toggleClass(target.parentNode, 'collapse');
+        }
+      });
+    }
+
+    __sticky = () => {
+      const cover = dom.getNode('section.cover');
+      if (!cover) {
+        return;
+      }
+
+      const coverHeight = cover.getBoundingClientRect().height;
+
+      if (
+        window.pageYOffset >= coverHeight ||
+        cover.classList.contains('hidden')
+      ) {
+        dom.toggleClass(dom.body, 'add', 'sticky');
+      } else {
+        dom.toggleClass(dom.body, 'remove', 'sticky');
+      }
+    };
+
+    /**
+     * Get and active link
+     * @param  {Object} router Router
+     * @param  {String|Element} el Target element
+     * @param  {Boolean} isParent Active parent
+     * @param  {Boolean} autoTitle Automatically set title
+     * @return {Element} Active element
+     */
+    __getAndActive(router, el, isParent, autoTitle) {
+      el = dom.getNode(el);
+      let links = [];
+      if (el !== null && el !== undefined) {
+        links = dom.findAll(el, 'a');
+      }
+
+      const hash = decodeURI(router.toURL(router.getCurrentPath()));
+      let target;
+
+      links
+        .sort((a, b) => b.href.length - a.href.length)
+        .forEach(a => {
+          const href = decodeURI(a.getAttribute('href'));
+          const node = isParent ? a.parentNode : a;
+
+          a.title = a.title || a.innerText;
+
+          if (hash.indexOf(href) === 0 && !target) {
+            target = a;
+            dom.toggleClass(node, 'add', 'active');
+          } else {
+            dom.toggleClass(node, 'remove', 'active');
+          }
+        });
+
+      if (autoTitle) {
+        dom.$.title = target
+          ? target.title || `${target.innerText} - ${this.#title}`
+          : this.#title;
+      }
+
+      return target;
+    }
   };
 }