Creating an IndexStore for Quick Navigation (#889) rdar://134272215

Creating an `IndexStore` for Quick Navigation (#889) rdar://134272215

Author: hqhhuang

src/components/DocumentationLayout.vue

@@ -40,7 +40,7 @@
             <div class="documentation-layout-aside">
               <QuickNavigationModal
                 v-if="enableQuickNavigation"
-                :children="slotProps.flatChildren"
+                :children="quickNavNodes"
                 :showQuickNavigationModal.sync="showQuickNavigationModal"
                 :technology="technology ? technology.title : ''"
               />
@@ -83,10 +83,12 @@ import QuickNavigationModal from 'docc-render/components/Navigator/QuickNavigati
 import AdjustableSidebarWidth from 'docc-render/components/AdjustableSidebarWidth.vue';
 import Navigator from 'docc-render/components/Navigator.vue';
 import onPageLoadScrollToFragment from 'docc-render/mixins/onPageLoadScrollToFragment';
+import Language from 'docc-render/constants/Language';
 import { BreakpointName } from 'docc-render/utils/breakpoints';
 import { storage } from 'docc-render/utils/storage';
 import { getSetting } from 'docc-render/utils/theme-settings';
 
+import IndexStore from 'docc-render/stores/IndexStore';
 import NavigatorDataProvider from 'theme/components/Navigator/NavigatorDataProvider.vue';
 import DocumentationNav from 'theme/components/DocumentationTopic/DocumentationNav.vue';
 
@@ -150,12 +152,16 @@ export default {
       sidenavHiddenOnLarge: storage.get(NAVIGATOR_HIDDEN_ON_LARGE_KEY, false),
       showQuickNavigationModal: false,
       BreakpointName,
+      indexState: IndexStore.state,
     };
   },
   computed: {
     enableQuickNavigation: ({ isTargetIDE }) => (
       !isTargetIDE && getSetting(['features', 'docs', 'quickNavigation', 'enable'], true)
     ),
+    quickNavNodes({ indexState: { flatChildren = {} }, interfaceLanguage }) {
+      return flatChildren[interfaceLanguage] ?? (flatChildren[Language.swift.key.url] || []);
+    },
     sidebarProps: ({
       sidenavVisibleOnMobile, enableNavigator, sidenavHiddenOnLarge, navigatorFixedWidth,
     }) => (

src/components/Navigator/NavigatorDataProvider.vue

@@ -11,7 +11,6 @@
 <script>
 import { fetchIndexPathsData } from 'docc-render/utils/data';
 import { flattenNestedData } from 'docc-render/utils/navigatorData';
-import AppStore from 'docc-render/stores/AppStore';
 import Language from 'docc-render/constants/Language';
 
 /**
@@ -91,15 +90,13 @@ export default {
       try {
         this.isFetching = true;
         const {
-          includedArchiveIdentifiers = [],
           interfaceLanguages,
           references,
         } = await fetchIndexPathsData(
           { slug: this.$route.params.locale || '' },
         );
         this.navigationIndex = Object.freeze(interfaceLanguages);
         this.navigationReferences = Object.freeze(references);
-        AppStore.setIncludedArchiveIdentifiers(includedArchiveIdentifiers);
       } catch (e) {
         this.errorFetching = true;
       } finally {

src/mixins/indexProvider.js

@@ -0,0 +1,49 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2024 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
+*/
+import { fetchData } from 'docc-render/utils/data';
+import { pathJoin } from 'docc-render/utils/assets';
+import { flattenNavigationIndex, extractTechnologyProps } from 'docc-render/utils/navigatorData';
+import IndexStore from 'docc-render/stores/IndexStore';
+
+export default {
+  computed: {
+    indexDataPath() {
+      const slug = this.$route?.params?.locale || '';
+      return pathJoin(['/index/', slug, 'index.json']);
+    },
+  },
+  methods: {
+    async fetchIndexPathsData() {
+      return fetchData(this.indexDataPath);
+    },
+    async fetchIndexData() {
+      try {
+        IndexStore.reset();
+        const {
+          includedArchiveIdentifiers = [],
+          interfaceLanguages,
+          references = {},
+        } = await this.fetchIndexPathsData();
+        IndexStore.setFlatChildren(flattenNavigationIndex(interfaceLanguages));
+        IndexStore.setTechnologyProps(extractTechnologyProps(interfaceLanguages));
+        IndexStore.setReferences(references);
+        IndexStore.setIncludedArchiveIdentifiers(includedArchiveIdentifiers);
+      } catch (e) {
+        IndexStore.setErrorFetching(true);
+      }
+    },
+  },
+  watch: {
+    indexDataPath: {
+      handler: 'fetchIndexData',
+      immediate: true,
+    },
+  },
+};

src/stores/AppStore.js

@@ -30,15 +30,13 @@ export default {
     supportsAutoColorScheme,
     systemColorScheme: ColorScheme.light,
     availableLocales: [],
-    includedArchiveIdentifiers: [],
   },
   reset() {
     this.state.imageLoadingStrategy = process.env.VUE_APP_TARGET === 'ide'
       ? ImageLoadingStrategy.eager : ImageLoadingStrategy.lazy;
     this.state.preferredColorScheme = Settings.preferredColorScheme || defaultColorScheme;
     this.state.supportsAutoColorScheme = supportsAutoColorScheme;
     this.state.systemColorScheme = ColorScheme.light;
-    this.state.includedArchiveIdentifiers = [];
   },
   setImageLoadingStrategy(strategy) {
     this.state.imageLoadingStrategy = strategy;
@@ -61,9 +59,6 @@ export default {
   setSystemColorScheme(value) {
     this.state.systemColorScheme = value;
   },
-  setIncludedArchiveIdentifiers(value) {
-    this.state.includedArchiveIdentifiers = value;
-  },
   syncPreferredColorScheme() {
     if (!!Settings.preferredColorScheme
       && Settings.preferredColorScheme !== this.state.preferredColorScheme) {

src/stores/IndexStore.js

@@ -0,0 +1,46 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2024 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
+*/
+
+export default {
+  state: {
+    flatChildren: {},
+    references: {},
+    apiChanges: null,
+    includedArchiveIdentifiers: [],
+    errorFetching: false,
+    technologyProps: {},
+  },
+  reset() {
+    this.state.flatChildren = {};
+    this.state.references = {};
+    this.state.apiChanges = null;
+    this.state.includedArchiveIdentifiers = [];
+    this.state.errorFetching = false;
+    this.state.technologyProps = {};
+  },
+  setFlatChildren(children) {
+    this.state.flatChildren = children;
+  },
+  setReferences(references) {
+    this.state.references = references;
+  },
+  setApiChanges(diff) {
+    this.state.apiChanges = diff;
+  },
+  setIncludedArchiveIdentifiers(includedArchiveIdentifiers) {
+    this.state.includedArchiveIdentifiers = includedArchiveIdentifiers;
+  },
+  setErrorFetching(state) {
+    this.state.errorFetching = state;
+  },
+  setTechnologyProps(technology) {
+    this.state.technologyProps = technology;
+  },
+};

src/utils/navigatorData.js

@@ -177,3 +177,30 @@ export function getSiblings(uid, childrenMap, children) {
   if (!item) return [];
   return getChildren(item.parent, childrenMap, children);
 }
+
+/**
+ * Flatten data for each language variant
+ * @return { languageVariant: NavigatorFlatItem[] }
+ */
+export function flattenNavigationIndex(indexData) {
+  return Object.entries(indexData).reduce((acc, [language, data]) => {
+    acc[language] = flattenNestedData(
+      data[0].children || [], null, 0, data[0].beta,
+    );
+    return acc;
+  }, {});
+}
+
+/**
+ * Extract technology data for each language variant
+ */
+export function extractTechnologyProps(indexData) {
+  return Object.entries(indexData).reduce((acc, [language, data]) => {
+    acc[language] = {
+      technology: data[0].title,
+      technologyPath: data[0].path || data[0].url,
+      isTechnologyBeta: data[0].beta,
+    };
+    return acc;
+  }, {});
+}

src/views/DocumentationTopic.vue

@@ -54,6 +54,7 @@ import {
 import DocumentationTopic from 'theme/components/DocumentationTopic.vue';
 import DocumentationLayout from 'docc-render/components/DocumentationLayout.vue';
 import DocumentationTopicStore from 'docc-render/stores/DocumentationTopicStore';
+import indexProvider from 'theme/mixins/indexProvider';
 import Language from 'docc-render/constants/Language';
 import OnThisPageRegistrator from 'docc-render/mixins/onThisPageRegistrator';
 import { updateLocale } from 'theme/utils/i18n-utils';
@@ -74,7 +75,7 @@ export default {
     Topic: DocumentationTopic,
     DocumentationLayout,
   },
-  mixins: [OnThisPageRegistrator, communicationBridgeUtils],
+  mixins: [OnThisPageRegistrator, communicationBridgeUtils, indexProvider],
   props: {
     enableMinimized: {
       type: Boolean,

tests/unit/components/DocumentationLayout.spec.js

@@ -30,6 +30,20 @@ jest.mock('docc-render/utils/scroll-lock');
 jest.mock('docc-render/utils/storage');
 jest.mock('docc-render/utils/theme-settings');
 
+const swiftChildren = [
+  'swiftChildrenMock',
+];
+const objcChildren = [
+  'objcChildrenMock',
+];
+jest.mock('docc-render/stores/IndexStore', () => ({
+  state: {
+    flatChildren: {
+      swift: swiftChildren,
+    },
+  },
+}));
+
 storage.get.mockImplementation((key, value) => value);
 
 const TechnologyWithChildren = {
@@ -273,6 +287,64 @@ describe('DocumentationLayout', () => {
     expect(quickNavigationModalComponent.exists()).toBe(false);
   });
 
+  it('QuickNavigation renders Swift items', async () => {
+    getSetting.mockReturnValueOnce(true);
+    wrapper = createWrapper({
+      stubs: {
+        ...stubs,
+        Nav: DocumentationNav,
+        NavBase,
+      },
+    });
+    wrapper.setProps({
+      enableNavigator: true,
+    });
+    await wrapper.vm.$nextTick();
+    expect(wrapper.find(QuickNavigationModal).props('children')).toEqual(swiftChildren);
+  });
+
+  it('QuickNavigation falls back to swift items, if no objc items', async () => {
+    getSetting.mockReturnValueOnce(true);
+    wrapper = createWrapper({
+      stubs: {
+        ...stubs,
+        Nav: DocumentationNav,
+        NavBase,
+      },
+    });
+    wrapper.setProps({
+      enableNavigator: true,
+      interfaceLanguage: Language.objectiveC.key.url,
+    });
+    await wrapper.vm.$nextTick();
+    expect(wrapper.find(QuickNavigationModal).props('children')).toEqual(swiftChildren);
+  });
+
+  it('QuickNavigation renders objc items', async () => {
+    getSetting.mockReturnValueOnce(true);
+    wrapper = createWrapper({
+      stubs: {
+        ...stubs,
+        Nav: DocumentationNav,
+        NavBase,
+      },
+    });
+    wrapper.setProps({
+      enableNavigator: true,
+      interfaceLanguage: Language.objectiveC.key.url,
+    });
+    wrapper.setData({
+      indexState: {
+        flatChildren: {
+          [Language.swift.key.url]: swiftChildren,
+          [Language.objectiveC.key.url]: objcChildren,
+        },
+      },
+    });
+    await wrapper.vm.$nextTick();
+    expect(wrapper.find(QuickNavigationModal).props('children')).toEqual(objcChildren);
+  });
+
   describe('if breakpoint is small', () => {
     beforeEach(() => {
       wrapper = createWrapper({

tests/unit/components/Navigator/NavigatorDataProvider.spec.js

@@ -10,7 +10,6 @@
 
 import NavigatorDataProvider from '@/components/Navigator/NavigatorDataProvider.vue';
 import { shallowMount } from '@vue/test-utils';
-import AppStore from 'docc-render/stores/AppStore';
 import Language from 'docc-render/constants/Language';
 import { TopicTypes } from '@/constants/TopicTypes';
 import { fetchIndexPathsData } from '@/utils/data';
@@ -175,10 +174,6 @@ describe('NavigatorDataProvider', () => {
     jest.clearAllMocks();
   });
 
-  afterEach(() => {
-    AppStore.reset();
-  });
-
   it('fetches data when mounting NavigatorDataProvider', async () => {
     expect(fetchIndexPathsData).toHaveBeenCalledTimes(0);
     createWrapper();
@@ -559,12 +554,4 @@ describe('NavigatorDataProvider', () => {
       },
     ]);
   });
-
-  it('sets `includedArchiveIdentifiers` state in the app store', async () => {
-    expect(AppStore.state.includedArchiveIdentifiers).toEqual([]);
-    fetchIndexPathsData.mockResolvedValue(response);
-    createWrapper();
-    await flushPromises();
-    expect(AppStore.state.includedArchiveIdentifiers).toEqual(includedArchiveIdentifiers);
-  });
 });