Restructured project

src/assets/javascripts/components/Material/Source/Adapter/GitHub.js

@@ -1,95 +0,0 @@
-/*
- * Copyright (c) 2016-2019 Martin Donath <martin.donath@squidfunk.com>
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to
- * deal in the Software without restriction, including without limitation the
- * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
- * sell copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
- * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
- * IN THE SOFTWARE.
- */
-
-import Abstract from "./Abstract"
-
-/* ----------------------------------------------------------------------------
- * Class
- * ------------------------------------------------------------------------- */
-
-export default class GitHub extends Abstract {
-
-  /**
-   * Retrieve repository information from GitHub
-   *
-   * @constructor
-   *
-   * @property {string} name_ - Name of the repository
-   *
-   * @param {(string|HTMLAnchorElement)} el - Selector or HTML element
-   */
-  constructor(el) {
-    super(el)
-
-    /* Extract user (and repository name) from URL, as we have to query for all
-       repositories, to omit 404 errors for private repositories */
-    const matches = /^.+github\.com\/([^/]+)\/?([^/]+)?.*$/
-      .exec(this.base_)
-    if (matches && matches.length === 3) {
-      const [, user, name] = matches
-
-      /* Initialize base URL and repository name */
-      this.base_ = `https://api.github.com/users/${user}/repos`
-      this.name_ = name
-    }
-  }
-
-  /**
-   * Fetch relevant repository information from GitHub
-   *
-   * @return {Promise<Array<string>>} Promise returning an array of facts
-   */
-  fetch_() {
-    const paginate = (page = 0) => (
-      fetch(`${this.base_}?per_page=100&sort=updated&page=${page}`)
-        .then(response => response.json())
-        .then(data => {
-          if (!(data instanceof Array))
-            return []
-
-          /* Display number of stars and forks, if repository is given */
-          if (this.name_) {
-            const repo = data.find(item => item.name === this.name_)
-            if (!repo && data.length === 30)
-              return paginate(page + 1)
-
-            /* If we found a repo, extract the facts */
-            return repo
-              ? [
-                `${this.format_(repo.stargazers_count)} Stars`,
-                `${this.format_(repo.forks_count)} Forks`
-              ]
-              : []
-
-          /* Display number of repositories, otherwise */
-          } else {
-            return [
-              `${data.length} Repositories`
-            ]
-          }
-        })
-    )
-
-    /* Paginate through repos */
-    return paginate()
-  }
-}

src/assets/javascripts/components/_/index.ts

@@ -21,10 +21,10 @@
  */
 
 import { keys } from "ramda"
-import { NEVER, Observable, OperatorFunction, merge, of, pipe } from "rxjs"
+import { NEVER, Observable, OperatorFunction, of, pipe } from "rxjs"
 import { map, scan, shareReplay, switchMap } from "rxjs/operators"
 
-import { getElement } from "../../../utilities"
+import { getElement } from "../../utilities"
 
 /* ----------------------------------------------------------------------------
  * Types
@@ -62,7 +62,7 @@ export type ComponentMap = {
  * Options
  */
 interface Options {
-  load$: Observable<Document>          /* Document observable */
+  document$: Observable<Document>      /* Document observable */
 }
 
 /* ----------------------------------------------------------------------------
@@ -81,9 +81,9 @@ interface Options {
  * @return Component map observable
  */
 export function watchComponentMap(
-  names: Component[], { load$ }: Options
+  names: Component[], { document$ }: Options
 ): Observable<ComponentMap> {
-  const components$ = load$
+  const components$ = document$
     .pipe(
 
       /* Build component map */

src/assets/javascripts/components/header/offset/index.ts

@@ -28,7 +28,7 @@ import {
   switchMapTo
 } from "rxjs/operators"
 
-import { ViewportOffset, ViewportSize } from "../../../../ui"
+import { ViewportOffset, ViewportSize } from "../../../utilities"
 import { Header } from "../_"
 
 /* ----------------------------------------------------------------------------

src/assets/javascripts/components/header/shadow/index.ts

@@ -32,10 +32,7 @@ import {
   tap
 } from "rxjs/operators"
 
-import {
+import { resetHeaderShadow, setHeaderShadow } from "../../../actions"
-  resetHeaderShadow,
-  setHeaderShadow
-} from "../../../action"
 import { Main } from "../../main"
 
 /* ----------------------------------------------------------------------------

src/assets/javascripts/components/hidden/index.ts

@@ -29,8 +29,8 @@ import {
   tap
 } from "rxjs/operators"
 
-import { ViewportOffset } from "../../../ui"
+import { resetHidden, setHidden } from "../../actions"
-import { resetHidden, setHidden } from "../../action"
+import { ViewportOffset } from "../../utilities"
 
 /* ----------------------------------------------------------------------------
  * Functions

src/assets/javascripts/components/main/index.ts

@@ -28,7 +28,7 @@ import {
   shareReplay
 } from "rxjs/operators"
 
-import { ViewportOffset, ViewportSize } from "../../../ui"
+import { ViewportOffset, ViewportSize } from "../../utilities"
 import { Header } from "../header"
 
 /* ----------------------------------------------------------------------------

src/assets/javascripts/components/sidebar/index.ts

@@ -37,13 +37,13 @@ import {
   tap
 } from "rxjs/operators"
 
-import { ViewportOffset } from "../../../ui"
 import {
   resetSidebarHeight,
   resetSidebarLock,
   setSidebarHeight,
   setSidebarLock
-} from "../../action"
+} from "../../actions"
+import { ViewportOffset } from "../../utilities"
 import { Main } from "../main"
 
 /* ----------------------------------------------------------------------------

src/assets/javascripts/extensions/index.ts

@@ -20,7 +20,4 @@
  * IN THE SOFTWARE.
  */
 
-export * from "./action"
+export * from "./rxjs"
-export * from "./component"
-export * from "./toggle"
-// export * from "./worker"

src/assets/javascripts/extensions/rxjs/_/index.ts

@@ -20,30 +20,25 @@
  * IN THE SOFTWARE.
  */
 
-/* ----------------------------------------------------------------------------
+import { Observable } from "rxjs"
- * Types
+import { map } from "rxjs/operators"
- * ------------------------------------------------------------------------- */
-
-/**
- * Configuration
- */
-export interface Config {
-  base: string                         /* Base URL */
-  search: string                       /* Web worker URL */
-}
 
 /* ----------------------------------------------------------------------------
  * Functions
  * ------------------------------------------------------------------------- */
 
 /**
- * Ensure that the given value is a valid configuration
+ * Invert boolean value of source observable
  *
- * @param config - Configuration
+ * @param toggle$ - Toggle observable
  *
- * @return Test result
+ * @return Inverted toggle observable
  */
-export function isConfig(config: any): config is Config {
+export function not(
-  return typeof config === "object"
+  toggle$: Observable<boolean>
-      && typeof config.base === "string"
+): Observable<boolean> {
+  return toggle$
+    .pipe(
+      map(active => !active)
+    )
 }

src/assets/javascripts/extensions/rxjs/index.ts

@@ -20,38 +20,5 @@
  * IN THE SOFTWARE.
  */
 
-/* ----------------------------------------------------------------------------
+export * from "./_"
- * Functions
+export * from "./operators"
- * ------------------------------------------------------------------------- */
-
-/**
- * Retrieve an element matching the query selector
- *
- * @template T - Element type
- *
- * @param selector - Query selector
- * @param node - Node of reference
- *
- * @return Element
- */
-export function getElement<T extends HTMLElement>(
-  selector: string, node: ParentNode = document
-): T | undefined {
-  return node.querySelector<T>(selector) || undefined
-}
-
-/**
- * Retrieve all elements matching the query selector
- *
- * @template T - Element type
- *
- * @param selector - Query selector
- * @param node - Node of reference
- *
- * @return Elements
- */
-export function getElements<T extends HTMLElement>(
-  selector: string, node: ParentNode = document
-): T[] {
-  return Array.from(node.querySelectorAll<T>(selector))
-}

src/assets/javascripts/extensions/rxjs/operators/index.ts

@@ -30,7 +30,6 @@ import {
 } from "rxjs"
 import {
   filter,
-  map,
   switchMap,
   takeUntil
 } from "rxjs/operators"
@@ -39,24 +38,6 @@ import {
  * Functions
  * ------------------------------------------------------------------------- */
 
-/**
- * Invert boolean value of source observable
- *
- * @param toggle$ - Toggle observable
- *
- * @return Inverted toggle observable
- */
-export function not(
-  toggle$: Observable<boolean>
-): Observable<boolean> {
-  return toggle$
-    .pipe(
-      map(active => !active)
-    )
-}
-
-/* ------------------------------------------------------------------------- */
-
 /**
  * Toggle switch map with another observable
  *

src/assets/javascripts/modules/index.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2016-2019 Martin Donath <martin.donath@squidfunk.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+export * from "./search"

src/assets/javascripts/modules/search/_/index.ts

@@ -0,0 +1,202 @@
+/*
+ * Copyright (c) 2016-2019 Martin Donath <martin.donath@squidfunk.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import * as lunr from "lunr"
+import { compress, decompress } from "lz-string"
+
+import {
+  SearchArticle,
+  SearchDocumentMap,
+  SearchSection,
+  setupSearchDocumentMap
+} from "../document"
+
+/* ----------------------------------------------------------------------------
+ * Types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Search index configuration
+ */
+export interface SearchIndexConfig {
+  lang: string[]                       /* Search languages */
+  separator: string                    /* Search separator */
+}
+
+/**
+ * Search index document
+ */
+export interface SearchIndexDocument {
+  location: string                     /* Document location */
+  title: string                        /* Document title */
+  text: string                         /* Document text */
+}
+
+/**
+ * Search index
+ *
+ * This interfaces describes the format of the `search_index.json` file which
+ * is automatically built by the MkDocs search plugin.
+ */
+export interface SearchIndex {
+  config: SearchIndexConfig            /* Search index configuration */
+  docs: SearchIndexDocument[]          /* Search index documents */
+  index?: object | string              /* Pre-built or serialized index */
+}
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Search result
+ */
+export interface SearchResult {
+  article: SearchArticle               /* Relevant article */
+  sections: SearchSection[]            /* Relevant sections */
+}
+
+/* ----------------------------------------------------------------------------
+ * Function types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Options
+ */
+interface Options {
+  pipeline: {
+    trimmer: boolean                   /* Add trimmer to pipeline */
+    stopwords: boolean                 /* Add stopword filter to pipeline */
+  }
+}
+
+/* ----------------------------------------------------------------------------
+ * Class
+ * ------------------------------------------------------------------------- */
+
+export class Search {
+
+  /**
+   * Search document mapping
+   *
+   * A mapping of URLs (including hash fragments) to the actual articles and
+   * sections of the documentation. The search document mapping must be created
+   * regardless of whether the index was prebuilt or not, as lunr itself will
+   * only store the actual index.
+   */
+  protected documents: SearchDocumentMap
+
+  /**
+   * The lunr search index
+   */
+  protected index: lunr.Index
+
+  /**
+   * Create a search index
+   *
+   * @param index - Search index
+   * @param options - Options
+   */
+  public constructor({ docs, index }: SearchIndex, options: Options) {
+    this.documents = setupSearchDocumentMap(docs)
+
+    /* If no index was given, create it */
+    if (typeof index === "undefined") {
+      this.index = lunr(function() {
+
+        /* Remove stemmer, as it cripples search experience */
+        this.pipeline.reset()
+        if (options.pipeline.trimmer)
+          this.pipeline.add(lunr.trimmer)
+        if (options.pipeline.stopwords)
+          this.pipeline.add(lunr.stopWordFilter)
+
+        /* Setup fields and reference */
+        this.field("title", { boost: 10 })
+        this.field("text")
+        this.ref("location")
+
+        /* Index documents */
+        for (const doc of docs)
+          this.add(doc)
+      })
+
+    /* Serialized and compressed index */
+    } else if (typeof index === "string") {
+      this.index = lunr.Index.load(JSON.parse(decompress(index)))
+
+    /* Prebuilt index */
+    } else {
+      this.index = lunr.Index.load(index)
+    }
+  }
+
+  /**
+   * Search for matching documents
+   *
+   * The search index which MkDocs provides is divided up into articles, which
+   * contain the whole content of the individual pages, and sections, which only
+   * contain the contents of the subsections obtained by breaking the individual
+   * pages up at `h1` ... `h6`. As there may be many sections on different pages
+   * with indentical titles (for example within this very project, e.g. "Usage"
+   * or "Installation"), they need to be put into the context of the containing
+   * page. For this reason, section results are grouped within their respective
+   * articles which are the top-level results that are returned.
+   *
+   * @param query - Query string
+   *
+   * @return Search results
+   */
+  public search(query: string): SearchResult[] {
+    const groups = this.index.search(query)
+
+      /* Group sections results by article */
+      .reduce((results, result) => {
+        const document = this.documents.get(result.ref)
+        if (typeof document !== "undefined") {
+          if ("article" in document) {
+            const ref = document.article.location
+            results.set(ref, [...results.get(ref) || [], result])
+          } else {
+            const ref = document.location
+            results.set(ref, results.get(ref) || [])
+          }
+        }
+        return results
+      }, new Map<string, lunr.Index.Result[]>())
+
+    /* Map groups to search documents */
+    return [...groups].map(([ref, sections]) => ({
+      article: this.documents.get(ref) as SearchArticle,
+      sections: sections.map(section => {
+        return this.documents.get(section.ref) as SearchSection
+      })
+    }))
+  }
+
+  /**
+   * Serialize and compress the index
+   *
+   * @return Serialized and compressed index
+   */
+  public toString(): string {
+    return compress(JSON.stringify(this.index))
+  }
+}

src/assets/javascripts/modules/search/document/index.ts

@@ -0,0 +1,107 @@
+/*
+ * Copyright (c) 2016-2019 Martin Donath <martin.donath@squidfunk.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+import * as escapeHTML from "escape-html"
+
+import { SearchIndexDocument } from "../_"
+
+/* ----------------------------------------------------------------------------
+ * Types
+ * ------------------------------------------------------------------------- */
+
+/**
+ * A top-level article
+ */
+export interface SearchArticle extends SearchIndexDocument {
+  section: boolean                     /* Whether the section was linked */
+}
+
+/**
+ * A section of an article
+ */
+export interface SearchSection extends SearchIndexDocument {
+  article: SearchArticle               /* Parent article */
+}
+
+/* ------------------------------------------------------------------------- */
+
+/**
+ * Search document
+ */
+export type SearchDocument =
+  | SearchArticle
+  | SearchSection
+
+/**
+ * Search document mapping
+ */
+export type SearchDocumentMap = Map<string, SearchDocument>
+
+/* ----------------------------------------------------------------------------
+ * Functions
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Build a search document mapping
+ *
+ * @param docs - Search index documents
+ *
+ * @return Search document map
+ */
+export function setupSearchDocumentMap(
+  docs: SearchIndexDocument[]
+): SearchDocumentMap {
+  const documents = new Map<string, SearchDocument>()
+  for (const doc of docs) {
+    const [path, hash] = doc.location.split("#")
+
+    /* Extract location and title */
+    const location = doc.location
+    const title    = doc.title
+
+    /* Escape and cleanup text */
+    const text = escapeHTML(doc.text)
+      .replace(/\s+(?=[,.:;!?])/g, "")
+      .replace(/\s+/g, " ")
+
+    /* Handle section */
+    if (hash) {
+      const article = documents.get(path) as SearchArticle
+
+      /* Ignore first section, override article */
+      if (!article.section) {
+        article.title   = doc.title
+        article.text    = text
+        article.section = true
+
+      /* Add subsequent section */
+      } else {
+        documents.set(location, { location, title, text, article })
+      }
+
+    /* Add article */
+    } else {
+      documents.set(location, { location, title, text, section: false })
+    }
+  }
+  return documents
+}

src/assets/javascripts/modules/search/index.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2016-2019 Martin Donath <martin.donath@squidfunk.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+export * from "./_"
+export * from "./document"

src/assets/javascripts/utilities/index.ts

@@ -20,5 +20,5 @@
  * IN THE SOFTWARE.
  */
 
-export * from "./element"
+export * from "./agent"
-export * from "./operator"
+export * from "./toggle"