Add support for variantOverrides Render JSON key. (#10)

Adds renderer support for the newly introduced `variantOverrides` key in DocC Render JSON, which allows for using the same JSON file to represent documentation data for a symbol which is available in more than one variant—most commonly for a symbol available in both Swift and Objective-C languages.

For symbols available in both Swift/Objective-C, there will now be an affordance in the sidebar that can be used to toggle between the current language.

Author: mportiz08

src/components/DocumentationTopic.vue

@@ -98,6 +98,7 @@ import { getSetting } from 'docc-render/utils/theme-settings';
 import Aside from 'docc-render/components/ContentNode/Aside.vue';
 import DocumentationNav from 'theme/components/DocumentationTopic/DocumentationNav.vue';
 import BetaLegalText from 'theme/components/DocumentationTopic/BetaLegalText.vue';
+import LanguageSwitcher from 'theme/components/DocumentationTopic/Summary/LanguageSwitcher.vue';
 import Abstract from './DocumentationTopic/Description/Abstract.vue';
 import ContentNode from './DocumentationTopic/ContentNode.vue';
 import CallToActionButton from './CallToActionButton.vue';
@@ -113,7 +114,6 @@ import SeeAlso from './DocumentationTopic/SeeAlso.vue';
 import Summary from './DocumentationTopic/Summary.vue';
 import Title from './DocumentationTopic/Title.vue';
 import Topics from './DocumentationTopic/Topics.vue';
-import LanguageSwitcher from './DocumentationTopic/Summary/LanguageSwitcher.vue';
 
 export default {
   name: 'DocumentationTopic',
@@ -307,25 +307,33 @@ export default {
     // hierarchy/breadcrumb for a given topic. We choose to render only the
     // first one.
     parentTopicIdentifiers: ({ hierarchy: { paths: [ids = []] = [] } }) => ids,
-    shouldShowLanguageSwitcher: ({ isTargetIDE, objcPath, swiftPath }) => (
-      isTargetIDE && objcPath && swiftPath
-    ),
+    shouldShowLanguageSwitcher: ({ objcPath, swiftPath }) => objcPath && swiftPath,
     hideSummary: () => getSetting(['features', 'docs', 'summary', 'hide'], false),
   },
+  methods: {
+    normalizePath(path) {
+      // Sometimes `paths` data from `variants` are prefixed with a leading
+      // slash and sometimes they aren't
+      return path.startsWith('/') ? path : `/${path}`;
+    },
+  },
   created() {
     // Switch to the Objective-C variant of a page if the query parameter is not
     // present in the URL _but_ the user has previously selected Objective-C
     // using the navigation toggle (indicating a semi-global preference/mode)
     if (this.topicState.preferredLanguage === Language.objectiveC.key.url
       && this.interfaceLanguage !== Language.objectiveC.key.api
-      && this.objcPath) {
+      && this.objcPath && this.$route.query.language !== Language.objectiveC.key.url) {
       const { query } = this.$route;
-      this.$router.replace({
-        path: `/${this.objcPath}`,
-        query: {
-          ...query,
-          language: Language.objectiveC.key.url,
-        },
+
+      this.$nextTick().then(() => {
+        this.$router.replace({
+          path: this.normalizePath(this.objcPath),
+          query: {
+            ...query,
+            language: Language.objectiveC.key.url,
+          },
+        });
       });
     }
 

src/components/DocumentationTopic/Summary/LanguageSwitcher.vue

@@ -15,16 +15,19 @@
       class="language-option swift"
       :class="{ active: swift.active }"
       :url="swift.active ? null : swift.url"
+      @click="chooseLanguage(swift)"
     >{{swift.name}}</LanguageSwitcherLink>
     <LanguageSwitcherLink
       class="language-option objc"
       :class="{ active: objc.active }"
       :url="objc.active ? null : objc.url"
+      @click="chooseLanguage(objc)"
     >{{objc.name}}</LanguageSwitcherLink>
   </Section>
 </template>
 
 <script>
+import { buildUrl } from 'docc-render/utils/url-helper';
 import Language from 'docc-render/constants/Language';
 
 import LanguageSwitcherLink from './LanguageSwitcherLink.vue';
@@ -38,6 +41,18 @@ export default {
     Section,
     Title,
   },
+  inject: {
+    isTargetIDE: {
+      default: () => false,
+    },
+    store: {
+      default() {
+        return {
+          setPreferredLanguage() {},
+        };
+      },
+    },
+  },
   props: {
     interfaceLanguage: {
       type: String,
@@ -59,31 +74,44 @@ export default {
     // leading slash so that it doesn't try to link to a page relative to the
     // current URL.
     objc: ({
-      interfaceLanguage, isCurrentPath, objcPath, $route: { query },
+      interfaceLanguage,
+      normalizePath,
+      objcPath,
+      $route: { query },
     }) => ({
       ...Language.objectiveC,
       active: Language.objectiveC.key.api === interfaceLanguage,
-      url: {
-        path: isCurrentPath(objcPath) ? null : `/${objcPath}`,
-        query: { language: Language.objectiveC.key.url, context: query.context },
-      },
+      url: buildUrl(normalizePath(objcPath), {
+        ...query,
+        language: Language.objectiveC.key.url,
+      }),
     }),
     swift: ({
-      interfaceLanguage, isCurrentPath, swiftPath, $route: { query },
+      interfaceLanguage,
+      normalizePath,
+      swiftPath,
+      $route: { query },
     }) => ({
       ...Language.swift,
       active: Language.swift.key.api === interfaceLanguage,
-      url: {
-        path: isCurrentPath(swiftPath) ? null : `/${swiftPath}`,
-        query: { language: undefined, context: query.context },
-      },
+      url: buildUrl(normalizePath(swiftPath), {
+        ...query,
+        language: undefined,
+      }),
     }),
   },
   methods: {
-    isCurrentPath(path) {
-      // the `.replace` call is needed since paths vended by the backend do not
-      // include a leading slash, while the router provided path does
-      return this.$route.path.replace(/^\//, '') === path;
+    chooseLanguage(language) {
+      if (!this.isTargetIDE) {
+        this.store.setPreferredLanguage(language.key.url);
+      }
+
+      this.$router.push(language.url);
+    },
+    normalizePath(path) {
+      // Sometimes `paths` data from `variants` are prefixed with a leading
+      // slash and sometimes they aren't
+      return path.startsWith('/') ? path : `/${path}`;
     },
   },
 };

src/components/DocumentationTopic/Summary/LanguageSwitcherLink.vue

@@ -9,7 +9,7 @@
 -->
 
 <template>
-  <router-link v-if="url" :to="url"><slot /></router-link>
+  <a v-if="url" :href="url" @click.prevent="$emit('click')"><slot /></a>
   <span v-else><slot /></span>
 </template>
 

src/styles/core/colors/_dark.scss

@@ -15,6 +15,7 @@
   --color-fill-blue: #{dark-color(fill-blue)};
   --color-fill-gray: #{dark-color(fill-gray)};
   --color-fill-gray-secondary: #{dark-color(fill-gray-secondary)};
+  --color-fill-gray-tertiary: #{dark-color(fill-gray-tertiary)};
   --color-fill-green-secondary: #{dark-color(fill-green-secondary)};
   --color-fill-orange-secondary: #{dark-color(fill-orange-secondary)};
   --color-fill-red-secondary: #{dark-color(fill-red-secondary)};

src/styles/core/colors/_light.scss

@@ -16,6 +16,7 @@
   --color-fill-blue: #{light-color(fill-blue)};
   --color-fill-gray: #{light-color(fill-gray)};
   --color-fill-gray-secondary: #{light-color(fill-gray-secondary)};
+  --color-fill-gray-tertiary: #{light-color(fill-gray-tertiary)};
   --color-fill-green-secondary: #{light-color(fill-green-secondary)};
   --color-fill-orange-secondary: #{light-color(fill-orange-secondary)};
   --color-fill-red-secondary: #{light-color(fill-red-secondary)};

src/utils/data.js

@@ -102,3 +102,7 @@ export async function fetchAPIChangesForRoute(route, changes) {
 
   return data;
 }
+
+export function clone(jsonObject) {
+  return JSON.parse(JSON.stringify(jsonObject));
+}