[GSoC] Quick navigation algorithm (#372)

* feat - Initial commit with quick navigation algorithm

* Fuzzy match algorithm made with regex only

* Tests for quick navigation component

* feat: Fuzzy search algorithm and basic functionality for Quick navigation

* Introduced a new component "QuickNavigationModal" that serves as UI for the new searching functionality.
* New regex pattern to match symbol titles by fuzzy and string match.
* Data store to control the Quick navigation modal from anywhere on the app without having to pass the data through multiple child compoents.

This change is under the quickNavigation feature flag.

* fix: Reversed changes of package-lock.json

* fix: `inputCoincidencesRegexPattern` now only matches the first appearance of a character

* fix: Remove hard coded items inside flatten Index state + fixed typo

* fix: Fuzzy match highlighting

* Refactor of match highlighter for Safari support using `QuickNavigationHighlighter` component
* Code quality improvements suggested on pr review

* fix: Code cleanup and readability improvements

Co-authored-by: Marina Aísa <[email protected]>

Author: sofiaromorales

app/public/theme-settings.json

@@ -54,6 +54,9 @@
   },
   "features": {
     "docs": {
+      "quickNavigation": {
+        "enable": false
+      }
     }
   }
 }

src/components/Icons/MagnifierIcon.vue

@@ -0,0 +1,24 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2022 Apple Inc. and the Swift project authors
+  Licensed under Apache License v2.0 with Runtime Library Exception
+
+  See https://swift.org/LICENSE.txt for license information
+  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+<template>
+  <SVGIcon viewBox="0 0 14 14" class="magnifier-icon">
+    <path d="M15.0013 14.0319L10.9437 9.97424C11.8165 8.88933 12.2925 7.53885 12.2929 6.14645C12.2929 2.75841 9.53449 0 6.14645 0C2.75841 0 0 2.75841 0 6.14645C0 9.53449 2.75841 12.2929 6.14645 12.2929C7.57562 12.2929 8.89486 11.7932 9.94425 10.9637L14.0019 15.0213L15.0013 14.0319ZM6.13645 11.0736C4.83315 11.071 3.58399 10.5521 2.66241 9.63048C1.74084 8.70891 1.22194 7.45974 1.2193 6.15644C1.2193 3.44801 3.41802 1.23928 6.13645 1.23928C8.85488 1.23928 11.0536 3.44801 11.0536 6.15644C11.0636 8.86488 8.85488 11.0736 6.13645 11.0736Z"/>
+  </SVGIcon>
+</template>
+
+<script>
+import SVGIcon from 'docc-render/components/SVGIcon.vue';
+
+export default {
+  name: 'MafnifierIcon',
+  components: { SVGIcon },
+};
+</script>

src/components/Navigator.vue

@@ -39,6 +39,7 @@
 </template>
 
 <script>
+import QuickNavigationStore from 'docc-render/stores/QuickNavigationStore';
 import NavigatorCard from 'theme/components/Navigator/NavigatorCard.vue';
 import SpinnerIcon from 'theme/components/Icons/SpinnerIcon.vue';
 import NavigatorCardInner from 'docc-render/components/Navigator/NavigatorCardInner.vue';
@@ -74,6 +75,7 @@ export default {
   data() {
     return {
       INDEX_ROOT_KEY,
+      store: QuickNavigationStore,
     };
   },
   props: {
@@ -110,6 +112,9 @@ export default {
       default: null,
     },
   },
+  provide() {
+    return { store: this.store };
+  },
   computed: {
     // gets the paths for each parent in the breadcrumbs
     parentTopicReferences({ references, parentTopicIdentifiers }) {
@@ -139,9 +144,11 @@ export default {
      * Recomputes the list of flat children.
      * @return NavigatorFlatItem[]
      */
-    flatChildren: ({ flattenNestedData, technology = {} }) => (
-      flattenNestedData(technology.children || [], null, 0, technology.beta)
-    ),
+    flatChildren: ({ flattenNestedData, technology = {}, store }) => {
+      const flatIndex = flattenNestedData(technology.children || [], null, 0, technology.beta);
+      store.setFlattenIndex(flatIndex);
+      return flatIndex;
+    },
     /**
      * The root item is always a module
      */

src/components/Navigator/NavigatorCard.vue

@@ -92,6 +92,13 @@
             @clear="clearFilters"
           />
         </div>
+        <div
+          class="magnifier-icon"
+          @click="store.toggleShowQuickNavigationModal()"
+          v-if="enableQuickNavigation"
+        >
+          <MagnifierIcon/>
+        </div>
       </div>
     </div>
   </div>
@@ -116,6 +123,9 @@ import keyboardNavigation from 'docc-render/mixins/keyboardNavigation';
 import { isEqual, last } from 'docc-render/utils/arrays';
 import { ChangeNames, ChangeNameToType } from 'docc-render/constants/Changes';
 import Badge from 'docc-render/components/Badge.vue';
+import MagnifierIcon from 'docc-render/components/Icons/MagnifierIcon.vue';
+import { getSetting } from 'docc-render/utils/theme-settings';
+import QuickNavigationStore from 'docc-render/stores/QuickNavigationStore';
 
 const STORAGE_KEY = 'navigator.state';
 
@@ -178,6 +188,7 @@ export default {
     Badge,
     FilterInput,
     SidenavIcon,
+    MagnifierIcon,
     NavigatorCardInner,
     NavigatorCardItem,
     RecycleScroller,
@@ -241,6 +252,7 @@ export default {
       nodesToRender: [],
       activeUID: null,
       resetScroll: false,
+      store: QuickNavigationStore,
       lastFocusTarget: null,
       NO_RESULTS,
       NO_CHILDREN,
@@ -452,6 +464,9 @@ export default {
     hasNodes: ({ nodesToRender }) => !!nodesToRender.length,
     totalItemsToNavigate: ({ nodesToRender }) => nodesToRender.length,
     lastActivePathItem: ({ activePath }) => last(activePath),
+    enableQuickNavigation: () => (
+      getSetting(['features', 'docs', 'quickNavigation', 'enable'], false)
+    ),
   },
   created() {
     this.restorePersistedState();
@@ -1053,6 +1068,9 @@ export default {
       this.focusIndex(parentIndex);
     },
   },
+  provide() {
+    return { store: this.store };
+  },
 };
 </script>
 
@@ -1066,6 +1084,13 @@ $filter-height: 71px;
 $navigator-head-background: var(--color-fill-secondary) !default;
 $navigator-head-background-active: var(--color-fill-tertiary) !default;
 
+.magnifier-icon {
+  height: 20px;
+  width: auto;
+  margin: auto;
+  padding-left: 5px;
+}
+
 .navigator-card {
   --card-vertical-spacing: #{$navigator-card-vertical-spacing};
   display: flex;

src/components/Navigator/QuickNavigationHighlighter.vue

@@ -0,0 +1,55 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2022 Apple Inc. and the Swift project authors
+  Licensed under Apache License v2.0 with Runtime Library Exception
+
+  See https://swift.org/LICENSE.txt for license information
+  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+<script>
+/**
+ * Component used to mark plain text.
+ */
+export default {
+  name: 'QuickNavigationHighlighter',
+  props: {
+    text: {
+      type: String,
+      required: true,
+    },
+    matcherText: {
+      type: String,
+      default: '',
+    },
+  },
+  render(createElement) {
+    const { matcherText, text } = this;
+    const children = [];
+    let lastIndex = 0;
+    [...matcherText].forEach((char) => {
+      const charIndex = text.indexOf(char, lastIndex);
+      if (lastIndex) {
+        children.push(createElement('span', text.slice(lastIndex, charIndex)));
+      }
+      const nextIndex = charIndex + 1;
+      children.push(createElement('span', { class: 'match' }, text.slice(charIndex, nextIndex)));
+      lastIndex = nextIndex;
+    });
+    return createElement('p', { class: 'highlight' }, children);
+  },
+};
+</script>
+<style lang="scss" scoped>
+@import 'docc-render/styles/_core.scss';
+
+.highlight {
+  display: inline;
+
+  /deep/ .match {
+    font-weight: $font-weight-semibold;
+    background: var(--color-fill-light-blue-secondary);
+  }
+}
+</style>

src/components/Navigator/QuickNavigationModal.vue

@@ -0,0 +1,188 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2022 Apple Inc. and the Swift project authors
+  Licensed under Apache License v2.0 with Runtime Library Exception
+
+  See https://swift.org/LICENSE.txt for license information
+  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+<template>
+  <div class="quick-navigation-modal">
+    <div class="container">
+      <div
+        class="close-icon"
+        @click="closeQuickNavigationModal()"
+      >
+        <p>
+          Close
+        </p>
+      </div>
+      <input
+        ref="input"
+        class="filter"
+        v-model="userInput"
+        type="text"
+      />
+      <div>
+        <div
+          v-for="(symbol, idx) in filteredSymbols"
+          class="symbol-match"
+          @click="closeQuickNavigationModal()"
+          :key="idx"
+        >
+          <Reference :url="symbol.path" :id="idx">
+            <span>
+              -
+              {{ symbol.title.slice(0, symbol.start) }}
+            </span>
+            <QuickNavigationHighlighter
+              :text="symbol.substring"
+              :matcherText="debouncedInput"
+            />
+            <span>
+              {{ symbol.title.slice(symbol.start + symbol.matchLength) }}
+            </span>
+          </Reference>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script>
+import debounce from 'docc-render/utils/debounce';
+import QuickNavigationHighlighter from 'docc-render/components/Navigator/QuickNavigationHighlighter.vue';
+import Reference from 'docc-render/components/ContentNode/Reference.vue';
+
+export default {
+  name: 'QuickNavigationModal',
+  components: {
+    QuickNavigationHighlighter,
+    Reference,
+  },
+  inject: ['quickNavigationStore'],
+  data() {
+    return {
+      debouncedInput: '',
+      quickNavigationStore: this.quickNavigationStore,
+      userInput: '',
+    };
+  },
+  computed: {
+    filteredSymbols: ({
+      flattenIndex,
+      constructFuzzyRegex,
+      fuzzyMatch,
+      debouncedInput,
+      orderSymbolsByPriority,
+    }) => {
+      const symbols = flattenIndex.filter(symbol => (
+        symbol.type !== 'groupMarker'
+        && symbol.title != null
+      ));
+      if (!debouncedInput) return [];
+      const matches = fuzzyMatch({
+        debouncedInput: debouncedInput.toLowerCase(),
+        symbols,
+        processedInputRegex: new RegExp(constructFuzzyRegex(debouncedInput)),
+      });
+      // Return the first 20 symbols out of sorted ones
+      return orderSymbolsByPriority(matches).slice(0, 20);
+    },
+    flattenIndex: ({ quickNavigationStore }) => quickNavigationStore.state.flattenIndex,
+  },
+  methods: {
+    closeQuickNavigationModal() {
+      this.quickNavigationStore.toggleShowQuickNavigationModal();
+    },
+    constructFuzzyRegex(userInput) {
+      // Construct regex for fuzzy match
+      // Ex:
+      // foobar -> f[^f]*?o[^o]*?o[^o]*?b[^b]*?a[^a]*?r
+      return [...userInput].reduce((prev, char, index) => (
+        prev
+          .concat(char.toLowerCase())
+          .concat(index < userInput.length - 1 ? `[^${char.toLowerCase()}]*?` : '')
+      ), '');
+    },
+    debounceInput: debounce(function debounceInput(value) {
+      this.debouncedInput = value;
+    }, 500),
+    fuzzyMatch: ({ debouncedInput, symbols, processedInputRegex }) => (
+      symbols.map((symbol) => {
+        const match = processedInputRegex.exec(symbol.title.toLowerCase());
+        // Dismiss if symbol isn't matched
+        if (!match) return false;
+
+        const matchLength = match[0].length;
+        const inputLength = debouncedInput.length;
+        // Dismiss if match length is greater than 3x the input's length
+        if (matchLength > inputLength * 3) return false;
+
+        return ({
+          title: symbol.title,
+          path: symbol.path,
+          inputLengthDifference: symbol.title.length - inputLength,
+          matchLength,
+          matchLengthDifference: matchLength - inputLength,
+          start: match.index,
+          substring: match[0],
+        });
+      }).filter(Boolean)
+    ),
+    orderSymbolsByPriority(matchingSymbols) {
+      return matchingSymbols.sort((a, b) => {
+        // Shortests symbol match title have preference over larger titles
+        if (a.matchLengthDifference > b.matchLengthDifference) return 1;
+        if (a.matchLengthDifference < b.matchLengthDifference) return -1;
+        // Shortests symbol title have preference over larger titles
+        if (a.inputLengthDifference > b.inputLengthDifference) return 1;
+        if (a.inputLengthDifference < b.inputLengthDifference) return -1;
+        // Matches at the beginning of string have relevance over matches at the end
+        if (a.start > b.start) return 1;
+        if (a.start < b.start) return -1;
+        return 0;
+      });
+    },
+  },
+  watch: {
+    userInput: 'debounceInput',
+  },
+};
+</script>
+
+<style scoped lang="scss">
+@import 'docc-render/styles/_core.scss';
+
+  .close-icon {
+    padding-bottom: 10px;
+  }
+  .container {
+      flex-direction: row;
+  }
+  .filter {
+    border-radius: $border-radius;
+    background-color: var(--color-fill);
+    border: solid var(--color-figure-gray) 1px;
+    padding: 20px;
+    width: 80%;
+    margin-bottom: 20px;
+  }
+  .quick-navigation-modal {
+    background-color: var(--color-fill);
+    position: fixed;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    z-index: 100;
+    padding: 100px;
+    overflow: scroll;
+  }
+  .symbol-match {
+    width: fit-content;
+  }
+
+</style>