From 6dcf1f422cab3a2cc811c36ddad1ac3307d099f3 Mon Sep 17 00:00:00 2001
From: Marcus Ortiz <marcus_ortiz@apple.com>
Date: Mon, 25 Oct 2021 14:28:57 -0700
Subject: [PATCH] Add support for `variantOverrides` Render JSON key.

---
 src/components/DocumentationTopic.vue         |  30 +-
 .../Summary/LanguageSwitcher.vue              |  56 ++-
 .../Summary/LanguageSwitcherLink.vue          |   2 +-
 src/styles/core/colors/_dark.scss             |   1 +
 src/styles/core/colors/_light.scss            |   1 +
 src/utils/data.js                             |   4 +
 src/utils/json-patch.js                       | 333 ++++++++++++++++++
 src/utils/json-pointer.js                     |  63 ++++
 src/views/DocumentationTopic.vue              |  36 +-
 .../components/DocumentationTopic.spec.js     |  23 +-
 .../Summary/LanguageSwitcher.spec.js          |  53 ++-
 .../Summary/LanguageSwitcherLink.spec.js      |  12 +-
 tests/unit/utils/json-patch.spec.js           | 225 ++++++++++++
 tests/unit/utils/json-pointer.spec.js         |  35 ++
 tests/unit/views/DocumentationTopic.spec.js   |  37 ++
 15 files changed, 849 insertions(+), 62 deletions(-)
 create mode 100644 src/utils/json-patch.js
 create mode 100644 src/utils/json-pointer.js
 create mode 100644 tests/unit/utils/json-patch.spec.js
 create mode 100644 tests/unit/utils/json-pointer.spec.js

diff --git a/src/components/DocumentationTopic.vue b/src/components/DocumentationTopic.vue
index 4b1a0eb4e..d52d7bdbb 100644
--- a/src/components/DocumentationTopic.vue
+++ b/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,
+          },
+        });
       });
     }
 
diff --git a/src/components/DocumentationTopic/Summary/LanguageSwitcher.vue b/src/components/DocumentationTopic/Summary/LanguageSwitcher.vue
index b92508ed0..bc65a1ed8 100644
--- a/src/components/DocumentationTopic/Summary/LanguageSwitcher.vue
+++ b/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}`;
     },
   },
 };
diff --git a/src/components/DocumentationTopic/Summary/LanguageSwitcherLink.vue b/src/components/DocumentationTopic/Summary/LanguageSwitcherLink.vue
index b04f5174c..0053c5005 100644
--- a/src/components/DocumentationTopic/Summary/LanguageSwitcherLink.vue
+++ b/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>
 
diff --git a/src/styles/core/colors/_dark.scss b/src/styles/core/colors/_dark.scss
index 4d4b38300..ca4c8593b 100644
--- a/src/styles/core/colors/_dark.scss
+++ b/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)};
diff --git a/src/styles/core/colors/_light.scss b/src/styles/core/colors/_light.scss
index 568d6e690..f41584093 100644
--- a/src/styles/core/colors/_light.scss
+++ b/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)};
diff --git a/src/utils/data.js b/src/utils/data.js
index 442296181..3b95b4652 100644
--- a/src/utils/data.js
+++ b/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));
+}
diff --git a/src/utils/json-patch.js b/src/utils/json-patch.js
new file mode 100644
index 000000000..00804f1eb
--- /dev/null
+++ b/src/utils/json-patch.js
@@ -0,0 +1,333 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021 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
+*/
+
+/* eslint-disable no-restricted-syntax */
+
+import { tokenize } from 'docc-render/utils/json-pointer';
+
+const DECIMAL_RADIX = 10;
+const END_INDEX = '-';
+const OBJECT = 'object';
+
+// A generic error used to indicate that a given JSON pointer is considered
+// invalid in the context of some JSON Patch operation.
+class InvalidPointerError extends Error {
+  constructor(pointer) {
+    super(`invalid pointer ${pointer}`);
+    this.pointer = pointer;
+  }
+}
+
+// Parses a string representing a JSON pointer array index, which will either be
+// an integer or the character "-", which is used to indicate that an operation
+// will add to the end of an array.
+//
+// Examples:
+//
+// parseArrayIndex('42')           // 42
+// parseArrayIndex('-')            // 0
+// parseArrayIndex('-', [0, 1, 2]) // 3
+// parseArrayIndex('two')          // Error: invalid array two
+// parseArrayIndex('4', [0, 1, 2]) // Error: invalid array 4
+function parseArrayIndex(token, { length }) {
+  if (token === END_INDEX) {
+    return length || 0;
+  }
+
+  const index = parseInt(token, DECIMAL_RADIX);
+  if (!Number.isInteger(index) || index > length) {
+    throw new Error(`invalid array index ${token}`);
+  }
+
+  return index;
+}
+
+// Given a document, this generates a sequence of object values corresponding to
+// each reference token in a given JSON pointer. An object representing each
+// individual token and its associated value is yielded.
+//
+// Examples:
+//
+// [...walk({ a: b: { c: 42 } }, '/a/b/c')]
+// // [
+// //   { token: 'a', node: { b: { c: { 42 } } } },
+// //   { token: 'b', node: { c: 42 } },
+// //   { token: 'c', node: 42 },
+// // ]
+//
+// [...walk({ a: 42 }, '/z', { strict: true })]
+// // Error: invalid pointer /z
+function* walk(document, pointer, options = { strict: false }) {
+  let node = document;
+
+  for (const token of tokenize(pointer)) {
+    // if the `strict` flag is used, first check that each token references an
+    // existing property and throw an error if not
+    if (options.strict && !Object.prototype.hasOwnProperty.call(node, token)) {
+      throw new InvalidPointerError(pointer);
+    }
+    node = node[token];
+    yield { node, token };
+  }
+}
+
+// Retrieves the document value associated with a given JSON pointer.
+//
+// Examples:
+//
+// get({ a: { b: { c: 42 } } }, '/a/b/c') // 42
+// get({ a: 42 }, '/z')                   // Error: invalid pointer /z
+function get(document, pointer) {
+  let value = document;
+
+  for (const { node } of walk(document, pointer, { strict: true })) {
+    value = node;
+  }
+
+  return value;
+}
+
+// JSON Patch operation "add" can be used to add a new property to an existing
+// object in a document or overwrite an existing one. It can also be used to
+// insert new items into an existing array value.
+//
+// See [RFC6902, Section 4.1](https://datatracker.ietf.org/doc/html/rfc6902#section-4.1)
+//
+// Examples:
+//
+// add({ foo: 'bar' }, '/foo', 'baz')
+// // { foo: 'baz' }
+//
+// add({ foo: 'bar' }, '/baz', 'qux')
+// // { foo: 'bar', baz: 'qux' }
+//
+// add({ foo: ['bar', qux'] }, '/foo/1', 'baz')
+// // { foo: ['bar', 'baz', 'qux'] }
+//
+// add({ foo: ['bar'] }, '/foo/-', 'baz')
+// // { foo: ['bar', 'baz'] }
+//
+// add({ q: { bar: 2 } }, '/a/b', 'c')
+// // Error: invalid pointer /a/b
+function add(document, path, value) {
+  let parent = null;
+  let node = document;
+  let lastToken = null;
+
+  // walk through the pointer, keeping track of the parent token/node
+  for (const { node: next, token } of walk(document, path)) {
+    parent = node;
+    node = next;
+    lastToken = token;
+  }
+
+  // if there is no parent, the pointer is invalid since we cannot add anything
+  // in that scenario
+  if (!parent) {
+    throw new InvalidPointerError(path);
+  }
+
+  if (Array.isArray(parent)) {
+    // if the pointer references an index to an array, try to add the new value
+    // into the array
+    try {
+      const index = parseArrayIndex(lastToken, parent);
+      parent.splice(index, 0, value);
+    } catch (e) {
+      throw new InvalidPointerError(path);
+    }
+  } else {
+    // otherwise, either overwrite the existing item or add a new one if it did
+    // not already exist
+    Object.assign(parent, { [lastToken]: value });
+  }
+
+  return document;
+}
+
+// JSON Patch operation "remove" can be used to remove the document value
+// associated with a given JSON pointer. It can also be used to remove an item
+// from an existing array value.
+//
+// See [RFC6902, Section 4.2](https://datatracker.ietf.org/doc/html/rfc6902#section-4.2)
+//
+// Examples:
+//
+// remove({ foo: 'bar' }, '/foo')
+// // {}
+//
+// remove({ foo: ['bar', 'qux', 'baz'] }, '/foo/1')
+// // { foo: ['bar', 'baz'] }
+//
+// remove({ foo: 'bar' }, '/qux')
+// // Error: invalid pointer /qux
+function remove(document, path) {
+  let parent = null;
+  let node = document;
+  let lastToken = null;
+
+  for (const { node: next, token } of walk(document, path)) {
+    parent = node;
+    node = next;
+    lastToken = token;
+  }
+
+  if (!parent) {
+    throw new InvalidPointerError(path);
+  }
+
+  if (Array.isArray(parent)) {
+    try {
+      const index = parseArrayIndex(lastToken, parent);
+      parent.splice(index, 1);
+    } catch (e) {
+      throw new InvalidPointerError(path);
+    }
+  } else if (node) {
+    delete parent[lastToken];
+  } else {
+    throw new InvalidPointerError(path);
+  }
+
+  return document;
+}
+
+// JSON Patch operation "replace" can be used to change the value of an existing
+// JSON pointer within a document. It can be expressed in terms of a remove and
+// an add operation for the same pointer.
+//
+// See [RFC6902, Section 4.3](https://datatracker.ietf.org/doc/html/rfc6902#section-4.3)
+//
+// Examples:
+//
+// replace({ foo: 'bar' }, '/foo', 'baz')
+// // { foo: 'baz' }
+//
+// replace({ foo: 'bar' }, '/baz', 'qux')
+// // Error: invalid pointer /baz
+function replace(document, path, value) {
+  remove(document, path);
+  add(document, path, value);
+  return document;
+}
+
+// JSON Patch operation "move" can be used to swap the location of an existing
+// document pointer value. It can be expressed in terms of a removal of one
+// pointer and an add of another pointer with the same value.
+//
+// See [RFC6902, Section 4.4](https://datatracker.ietf.org/doc/html/rfc6902#section-4.4)
+//
+// Examples:
+//
+// move({ foo: 42 }, '/foo', '/bar')
+// // { bar: 42 }
+//
+// move({ foo: 42 }, '/bar', 'baz')
+// // Error: invalid pointer /bar
+function move(document, from, to) {
+  const value = get(document, from);
+  remove(document, from);
+  add(document, to, value);
+  return document;
+}
+
+// JSON Patch operation "copy" can be used to duplicate an existing document
+// pointer value to a new pointer. It can be expressed in terms of an add
+// operation using the value from an existing pointer.
+//
+// See [RFC6902, Section 4.5](https://datatracker.ietf.org/doc/html/rfc6902#section-4.5)
+//
+// Examples:
+//
+// copy({ foo: 42 }, '/foo', '/bar')
+// // { foo: 42, bar: 42 }
+//
+// copy({ foo: 42 }, '/bar', '/baz')
+// // Error: invalid pointer /bar
+function copy(document, from, to) {
+  add(document, to, get(document, from));
+  return document;
+}
+
+// JSON Patch operation "test" can be used to check if an existing document
+// pointer matches a specified value. It will throw an error if the test fails.
+// The unchanged document will be returned if the test passes.
+//
+// See [RFC6902, Section 4.6](https://datatracker.ietf.org/doc/html/rfc6902#section-4.6)
+//
+// Examples:
+//
+// test({ foo: { bar: 'baz' } }, '/foo/bar', { bar: 'baz' })
+// // { foo: { bar: 'baz' } }
+//
+// test({ foo: { bar: 'baz' } }, '/foo/bar', { bar: 'baz', qux: 42 })
+// // Error: test failed
+function test(document, path, value) {
+  function isEqual(a, b) {
+    const typeA = typeof a;
+    const typeB = typeof b;
+    if (typeA !== typeB) {
+      return false;
+    }
+
+    switch (typeA) {
+    case OBJECT: {
+      // recursively compare children of objects and arrays to deeply check that
+      // all values are equal
+      const aKeys = Object.keys(a);
+      const bKeys = Object.keys(b);
+      return aKeys.length === bKeys.length && aKeys.every((key, i) => (
+        key === bKeys[i] && isEqual(a[key], b[key])
+      ));
+    }
+    default:
+      return a === b;
+    }
+  }
+
+  const actual = get(document, path);
+  if (!isEqual(value, actual)) {
+    throw new Error('test failed');
+  }
+
+  return document;
+}
+
+const Operation = {
+  add: (document, { path, value }) => add(document, path, value),
+  copy: (document, { from, path }) => copy(document, from, path),
+  move: (document, { from, path }) => move(document, from, path),
+  remove: (document, { path }) => remove(document, path),
+  replace: (document, { path, value }) => replace(document, path, value),
+  test: (document, { path, value }) => test(document, path, value),
+};
+
+// Applies an individual JSON patch operation to an existing document and
+// returns the result.
+function applyOperation(document, { op, ...args }) {
+  const operation = Operation[op];
+  if (!operation) {
+    throw new Error('unknown operation');
+  }
+
+  return operation(document, args);
+}
+
+// Applies a JSON patch to an existing document and returns the result.
+//
+// The patch is an array of operation objects as specified by RFC6902.
+//
+// See [RFC6902](https://datatracker.ietf.org/doc/html/rfc6902)
+function applyPatch(document, patch) {
+  return patch.reduce(applyOperation, document);
+}
+
+// eslint-disable-next-line import/prefer-default-export
+export { applyPatch as apply };
diff --git a/src/utils/json-pointer.js b/src/utils/json-pointer.js
new file mode 100644
index 000000000..81adf3982
--- /dev/null
+++ b/src/utils/json-pointer.js
@@ -0,0 +1,63 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021 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
+*/
+
+const SEPARATOR = '/';
+
+function decode(token) {
+  // Decode escaped character sequences:
+  //   * replace "~0" with "~"
+  //   * replace "~1" with "/"
+  return token.replace(/~[0,1]/g, match => (({
+    '~0': '~',
+    '~1': '/',
+  })[match] || match));
+}
+
+// This can be used to lazily generate a sequence of the individual decoded
+// reference tokens contained within a given JSON pointer, which are separated
+// by the "/" character. Within each token, the string "~0" is decoded to "~"
+// and the string "~1" is decoded to "/".
+//
+// Examples:
+//
+// [...tokenize('')]       // []
+// [...tokenize('!')]      // []
+// [...tokenize('/')]      // ['']
+// [...tokenize('/a/b/c')] // ['a', 'b', 'c']
+// [...tokenize('/~0/~1']) // ['~', '/']
+//
+// for (const token of tokenize('/a/b/c')) {
+//   // ...
+// }
+function* tokenize(pointer) {
+  const start = 1;
+  if (pointer.length < start || pointer.charAt(0) !== SEPARATOR) {
+    return;
+  }
+
+  let encodedToken = '';
+  let i = start;
+  while (i < pointer.length) {
+    const char = pointer.charAt(i);
+
+    if (char === SEPARATOR) {
+      yield decode(encodedToken);
+      encodedToken = '';
+    } else {
+      encodedToken += char;
+    }
+    i += 1;
+  }
+
+  yield decode(encodedToken);
+}
+
+// eslint-disable-next-line import/prefer-default-export
+export { tokenize };
diff --git a/src/views/DocumentationTopic.vue b/src/views/DocumentationTopic.vue
index 569e2d391..60800bddd 100644
--- a/src/views/DocumentationTopic.vue
+++ b/src/views/DocumentationTopic.vue
@@ -19,7 +19,9 @@
 </template>
 
 <script>
+import { apply } from 'docc-render/utils/json-patch';
 import {
+  clone,
   fetchDataForRouteEnter,
   shouldFetchDataForRouteUpdate,
 } from 'docc-render/utils/data';
@@ -27,6 +29,7 @@ import DocumentationTopic from 'theme/components/DocumentationTopic.vue';
 import DocumentationTopicStore from 'docc-render/stores/DocumentationTopicStore';
 import CodeTheme from 'docc-render/components/Tutorial/CodeTheme.vue';
 import CodeThemeStore from 'docc-render/stores/CodeThemeStore';
+import Language from 'docc-render/constants/Language';
 import performanceMetrics from 'docc-render/mixins/performanceMetrics';
 import onPageLoadScrollToFragment from 'docc-render/mixins/onPageLoadScrollToFragment';
 
@@ -38,12 +41,31 @@ export default {
   },
   mixins: [performanceMetrics, onPageLoadScrollToFragment],
   data() {
-    return { topicData: null };
+    return { topicDataDefault: null, topicDataObjc: null };
   },
   computed: {
     store() {
       return DocumentationTopicStore;
     },
+    objcOverrides: ({ topicData }) => {
+      const { variantOverrides = [] } = topicData || {};
+
+      const isObjcTrait = ({ interfaceLanguage }) => (
+        interfaceLanguage === Language.objectiveC.key.api
+      );
+      const hasObjcTrait = ({ traits }) => traits.some(isObjcTrait);
+
+      const objcVariant = variantOverrides.find(hasObjcTrait);
+      return objcVariant ? objcVariant.patch : null;
+    },
+    topicData: {
+      get() {
+        return this.topicDataObjc ? this.topicDataObjc : this.topicDataDefault;
+      },
+      set(data) {
+        this.topicDataDefault = data;
+      },
+    },
     topicProps() {
       const {
         abstract,
@@ -72,6 +94,7 @@ export default {
         sampleCodeDownload,
         topicSections,
         seeAlsoSections,
+        variantOverrides,
         variants,
       } = this.topicData;
       return {
@@ -95,6 +118,7 @@ export default {
         title,
         topicSections,
         seeAlsoSections,
+        variantOverrides,
         variants,
         extendsFramework,
         tags: tags.slice(0, 1), // make sure we only show the first tag
@@ -123,11 +147,19 @@ export default {
   beforeRouteEnter(to, from, next) {
     fetchDataForRouteEnter(to, from, next).then(data => next((vm) => {
       vm.topicData = data; // eslint-disable-line no-param-reassign
+      if (to.query.language === Language.objectiveC.key.url && vm.objcOverrides) {
+        // eslint-disable-next-line no-param-reassign
+        vm.topicDataObjc = apply(clone(vm.topicData), vm.objcOverrides);
+      }
     })).catch(next);
   },
   beforeRouteUpdate(to, from, next) {
-    if (shouldFetchDataForRouteUpdate(to, from)) {
+    if (to.query.language === Language.objectiveC.key.url && this.objcOverrides) {
+      this.topicDataObjc = apply(clone(this.topicData), this.objcOverrides);
+      next();
+    } else if (shouldFetchDataForRouteUpdate(to, from)) {
       fetchDataForRouteEnter(to, from, next).then((data) => {
+        this.topicDataObjc = null;
         this.topicData = data;
         next();
       }).catch(next);
diff --git a/tests/unit/components/DocumentationTopic.spec.js b/tests/unit/components/DocumentationTopic.spec.js
index aa3cca88a..ac06a32d5 100644
--- a/tests/unit/components/DocumentationTopic.spec.js
+++ b/tests/unit/components/DocumentationTopic.spec.js
@@ -382,8 +382,14 @@ describe('DocumentationTopic', () => {
       expect(summary.contains(OnThisPageNav)).toBe(false);
     });
 
-    it('does not render a `LanguageSwitcher` for non-IDE targets', () => {
-      expect(wrapper.contains(LanguageSwitcher)).toBe(false);
+    it('renders a `LanguageSwitcher`', () => {
+      const switcher = summary.find(LanguageSwitcher);
+      expect(switcher.exists()).toBe(true);
+      expect(switcher.props()).toEqual({
+        interfaceLanguage: propsData.interfaceLanguage,
+        objcPath: propsData.variants[0].paths[0],
+        swiftPath: propsData.variants[1].paths[0],
+      });
     });
 
     it('renders an `FrameworkList` component in the sidebar', () => {
@@ -645,7 +651,7 @@ describe('DocumentationTopic', () => {
       expect(store.reset).toBeCalled();
     });
 
-    it('routes to the objc variant of a page if that is the preferred language', () => {
+    it('routes to the objc variant of a page if that is the preferred language', async () => {
       const $route = { query: {} };
       const $router = { replace: jest.fn() };
       const store = {
@@ -664,6 +670,7 @@ describe('DocumentationTopic', () => {
         propsData,
         provide: { store },
       });
+      await wrapper.vm.$nextTick();
       expect($router.replace).toBeCalledWith({
         path: `/${propsData.variants[0].paths[0]}`,
         query: { language: Language.objectiveC.key.url },
@@ -684,14 +691,4 @@ describe('isTargetIDE', () => {
   it('does not render a `Nav`', () => {
     expect(wrapper.contains(Nav)).toBe(false);
   });
-
-  it('renders a `LanguageSwitcher`', () => {
-    const switcher = wrapper.find(Summary).find(LanguageSwitcher);
-    expect(switcher.exists()).toBe(true);
-    expect(switcher.props()).toEqual({
-      interfaceLanguage: propsData.interfaceLanguage,
-      objcPath: propsData.variants[0].paths[0],
-      swiftPath: propsData.variants[1].paths[0],
-    });
-  });
 });
diff --git a/tests/unit/components/DocumentationTopic/Summary/LanguageSwitcher.spec.js b/tests/unit/components/DocumentationTopic/Summary/LanguageSwitcher.spec.js
index 2081a4e5d..0e1366a41 100644
--- a/tests/unit/components/DocumentationTopic/Summary/LanguageSwitcher.spec.js
+++ b/tests/unit/components/DocumentationTopic/Summary/LanguageSwitcher.spec.js
@@ -35,6 +35,9 @@ describe('LanguageSwitcher', () => {
         context: 'foo',
       },
     },
+    $router: {
+      push: jest.fn(),
+    },
   };
 
   beforeEach(() => {
@@ -73,10 +76,9 @@ describe('LanguageSwitcher', () => {
     expect(links.at(1).classes('language-option')).toBe(true);
     expect(links.at(1).classes('objc')).toBe(true);
     expect(links.at(1).classes('active')).toBe(false);
-    expect(links.at(1).props('url')).toEqual({
-      path: null,
-      query: { language: Language.objectiveC.key.url, context: 'foo' },
-    });
+    expect(links.at(1).props('url').startsWith('/documentation/foo?')).toBe(true);
+    expect(links.at(1).props('url')).toContain('language=objc');
+    expect(links.at(1).props('url')).toContain('context=foo');
     expect(links.at(1).text()).toBe(Language.objectiveC.name);
   });
 
@@ -93,10 +95,7 @@ describe('LanguageSwitcher', () => {
     expect(links.at(0).classes('language-option')).toBe(true);
     expect(links.at(0).classes('swift')).toBe(true);
     expect(links.at(0).classes('active')).toBe(false);
-    // make sure the `language` parameter is `undefined`,
-    // otherwise Vue-Router has issues with navigating to Swift pages
-    expect(links.at(0).props('url'))
-      .toStrictEqual({ path: null, query: { context: 'foo', language: undefined } });
+    expect(links.at(0).props('url')).toBe('/documentation/foo?context=foo');
     expect(links.at(0).text()).toBe(Language.swift.name);
 
     expect(links.at(1).classes('language-option')).toBe(true);
@@ -120,10 +119,38 @@ describe('LanguageSwitcher', () => {
     expect(links.length).toBe(2);
 
     expect(links.at(0).props('url')).toEqual(null);
-    expect(links.at(1).props('url'))
-      .toStrictEqual({
-        path: null,
-        query: { context: undefined, language: Language.objectiveC.key.url },
-      });
+    expect(links.at(1).props('url')).toBe('/documentation/foo?language=objc');
+  });
+
+  it('stores the preferred language when a link is clicked', () => {
+    const store = { setPreferredLanguage: jest.fn() };
+    wrapper = shallowMount(LanguageSwitcher, {
+      mocks,
+      propsData,
+      provide: { store },
+    });
+
+    let link = wrapper.findAll(LanguageSwitcherLink).at(1);
+    link.vm.$emit('click');
+    expect(store.setPreferredLanguage).toBeCalledWith(Language.objectiveC.key.url);
+
+    link = wrapper.findAll(LanguageSwitcherLink).at(0);
+    link.vm.$emit('click');
+    expect(store.setPreferredLanguage).toBeCalledWith(Language.swift.key.url);
+  });
+
+  it('does not store the preferred language when links are clicked for IDE targets', () => {
+    const store = { setPreferredLanguage: jest.fn() };
+    wrapper = shallowMount(LanguageSwitcher, {
+      mocks,
+      propsData,
+      provide: {
+        isTargetIDE: true,
+        store,
+      },
+    });
+
+    wrapper.findAll(LanguageSwitcherLink).at(1).vm.$emit('click');
+    expect(store.setPreferredLanguage).not.toBeCalled();
   });
 });
diff --git a/tests/unit/components/DocumentationTopic/Summary/LanguageSwitcherLink.spec.js b/tests/unit/components/DocumentationTopic/Summary/LanguageSwitcherLink.spec.js
index 2f915a957..af0f8c84f 100644
--- a/tests/unit/components/DocumentationTopic/Summary/LanguageSwitcherLink.spec.js
+++ b/tests/unit/components/DocumentationTopic/Summary/LanguageSwitcherLink.spec.js
@@ -8,25 +8,21 @@
  * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-import {
-  shallowMount,
-  RouterLinkStub,
-} from '@vue/test-utils';
+import { shallowMount } from '@vue/test-utils';
 import LanguageSwitcherLink from 'docc-render/components/DocumentationTopic/Summary/LanguageSwitcherLink.vue';
 
 describe('LanguageSwitcherLink', () => {
   const slots = { default: 'Foo' };
 
-  it('renders a router-link if provided a url', () => {
+  it('renders a anchor if provided a url', () => {
     const url = '/foo';
     const wrapper = shallowMount(LanguageSwitcherLink, {
       propsData: { url },
       slots,
-      stubs: { 'router-link': RouterLinkStub },
     });
-    const link = wrapper.find(RouterLinkStub);
+    const link = wrapper.find('a');
     expect(link.exists()).toBe(true);
-    expect(link.props('to')).toEqual(url);
+    expect(link.attributes('href')).toBe(url);
     expect(link.text()).toBe(slots.default);
   });
 
diff --git a/tests/unit/utils/json-patch.spec.js b/tests/unit/utils/json-patch.spec.js
new file mode 100644
index 000000000..c7fde12c9
--- /dev/null
+++ b/tests/unit/utils/json-patch.spec.js
@@ -0,0 +1,225 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021 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 { apply } from 'docc-render/utils/json-patch';
+
+describe('apply', () => {
+  it('returns an unchanged document with an empty patch', () => {
+    expect(apply({}, [])).toEqual({});
+    expect(apply([], [])).toEqual([]);
+    expect(apply({
+      foo: 'foo',
+      bar: 'bar',
+    }, [])).toEqual({
+      bar: 'bar',
+      foo: 'foo',
+    });
+  });
+
+  it('throws an error for an operation with an unknown "op" value', () => {
+    expect(() => apply({}, [{ op: 'fake' }])).toThrowError('unknown operation');
+  });
+
+  it('adds an object member', () => {
+    expect(apply({
+      foo: 'bar',
+    }, [
+      { op: 'add', path: '/baz', value: 'qux' },
+    ])).toEqual({
+      foo: 'bar',
+      baz: 'qux',
+    });
+  });
+
+  it('adds an array element', () => {
+    expect(apply({
+      foo: ['bar', 'baz'],
+    }, [
+      { op: 'add', path: '/foo/1', value: 'qux' },
+    ])).toEqual({
+      foo: ['bar', 'qux', 'baz'],
+    });
+  });
+
+  it('removes an object member', () => {
+    expect(apply({
+      baz: 'qux',
+      foo: 'bar',
+    }, [
+      { op: 'remove', path: '/baz' },
+    ])).toEqual({
+      foo: 'bar',
+    });
+  });
+
+  it('removes an array element', () => {
+    expect(apply({
+      foo: ['bar', 'qux', 'baz'],
+    }, [
+      { op: 'remove', path: '/foo/1' },
+    ])).toEqual({
+      foo: ['bar', 'baz'],
+    });
+  });
+
+  it('replaces a value', () => {
+    expect(apply({
+      baz: 'qux',
+      foo: 'bar',
+    }, [
+      { op: 'replace', path: '/baz', value: 'boo' },
+    ])).toEqual({
+      baz: 'boo',
+      foo: 'bar',
+    });
+  });
+
+  it('moves a value', () => {
+    expect(apply({
+      foo: {
+        bar: 'baz',
+        waldo: 'fred',
+      },
+      qux: {
+        corge: 'grault',
+      },
+    }, [
+      { op: 'move', from: '/foo/waldo', path: '/qux/thud' },
+    ])).toEqual({
+      foo: {
+        bar: 'baz',
+      },
+      qux: {
+        corge: 'grault',
+        thud: 'fred',
+      },
+    });
+  });
+
+  it('moves an array element', () => {
+    expect(apply({
+      foo: ['all', 'grass', 'cows', 'eat'],
+    }, [
+      { op: 'move', from: '/foo/1', path: '/foo/3' },
+    ])).toEqual({
+      foo: ['all', 'cows', 'eat', 'grass'],
+    });
+  });
+
+  it('successfully tests a value', () => {
+    expect(() => {
+      apply({
+        baz: 'qux',
+        foo: ['a', 2, 'c'],
+      }, [
+        { op: 'test', path: '/baz', value: 'qux' },
+        { op: 'test', path: '/foo/1', value: 2 },
+      ]);
+    }).not.toThrow();
+  });
+
+  it('unsuccessfully tests a value', () => {
+    expect(() => {
+      apply({
+        baz: 'qux',
+      }, [
+        { op: 'test', path: '/baz', value: 'bar' },
+      ]);
+    }).toThrow();
+  });
+
+  it('adds a nested member object', () => {
+    expect(apply({
+      foo: 'bar',
+    }, [
+      { op: 'add', path: '/child', value: { grandchild: {} } },
+    ])).toEqual({
+      foo: 'bar',
+      child: {
+        grandchild: {},
+      },
+    });
+  });
+
+  it('ignores unrecognized elements', () => {
+    expect(apply({
+      foo: 'bar',
+    }, [
+      {
+        op: 'add',
+        path: '/baz',
+        value: 'qux',
+        xyz: 123,
+      },
+    ])).toEqual({
+      foo: 'bar',
+      baz: 'qux',
+    });
+  });
+
+  it('fails when attempting to add to a nonexistent target', () => {
+    expect(() => {
+      apply({
+        foo: 'bar',
+      }, [
+        { op: 'add', path: '/baz/bat', value: 'qux' },
+      ]);
+    }).toThrow();
+  });
+
+  it('handles escape ordering for ~ properly', () => {
+    const document = JSON.parse(`
+    {
+      "/": 9,
+      "~1": 10
+    }`);
+    const patch = [{ op: 'test', path: '/~01', value: 10 }];
+    expect(() => apply(document, patch)).not.toThrow();
+    expect(apply(document, patch)).toEqual({ ...document });
+  });
+
+  it('fails when attempting to compare strings and numbers', () => {
+    const document = JSON.parse(`
+    {
+      "/": 9,
+      "~1": 10
+    }`);
+    const patch = [{ op: 'test', path: '/~01', value: '10' }];
+    expect(() => apply(document, patch)).toThrow();
+  });
+
+  it('adds an array value', () => {
+    expect(apply({
+      foo: ['bar'],
+    }, [
+      { op: 'add', path: '/foo/-', value: ['abc', 'def'] },
+    ])).toEqual({
+      foo: ['bar', ['abc', 'def']],
+    });
+  });
+
+  it('returns an unchanged document when the patch results in no changes', () => {
+    expect(apply({}, [
+      { op: 'add', path: '/foo', value: 'bar' },
+      { op: 'remove', path: '/foo' },
+    ])).toEqual({});
+  });
+
+  it('handles `null` values properly', () => {
+    expect(apply({
+      foo: { bar: null },
+    }, [
+      { op: 'copy', from: '/foo/bar', path: '/baz' },
+    ])).toEqual({
+      foo: { bar: null },
+      baz: null,
+    });
+  });
+});
diff --git a/tests/unit/utils/json-pointer.spec.js b/tests/unit/utils/json-pointer.spec.js
new file mode 100644
index 000000000..2e34d4531
--- /dev/null
+++ b/tests/unit/utils/json-pointer.spec.js
@@ -0,0 +1,35 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021 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 { tokenize } from 'docc-render/utils/json-pointer';
+
+describe('tokenize', () => {
+  it('returns an empty token array for an empty string pointer', () => {
+    expect([...tokenize('')]).toEqual([]);
+  });
+
+  it('returns an array of one token for top level JSON pointers', () => {
+    expect([...tokenize('/foo')]).toEqual(['foo']);
+    expect([...tokenize('/')]).toEqual(['']);
+    expect([...tokenize('/a~1b')]).toEqual(['a/b']);
+    expect([...tokenize('/c%d')]).toEqual(['c%d']);
+    expect([...tokenize('/e^f')]).toEqual(['e^f']);
+    expect([...tokenize('/g|h')]).toEqual(['g|h']);
+    expect([...tokenize('/i\\j')]).toEqual(['i\\j']);
+    expect([...tokenize('/k"l')]).toEqual(['k"l']);
+    expect([...tokenize('/ ')]).toEqual([' ']);
+    expect([...tokenize('/m~0n')]).toEqual(['m~n']);
+  });
+
+  it('returns an array of tokens when the pointer contains an index', () => {
+    expect([...tokenize('/foo/0')]).toEqual(['foo', '0']);
+    expect([...tokenize('/foo/1')]).toEqual(['foo', '1']);
+  });
+});
diff --git a/tests/unit/views/DocumentationTopic.spec.js b/tests/unit/views/DocumentationTopic.spec.js
index b3755b89b..79fe90814 100644
--- a/tests/unit/views/DocumentationTopic.spec.js
+++ b/tests/unit/views/DocumentationTopic.spec.js
@@ -8,6 +8,7 @@
  * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
+import * as dataUtils from 'docc-render/utils/data';
 import { shallowMount } from '@vue/test-utils';
 import DocumentationTopic from 'docc-render/views/DocumentationTopic.vue';
 import DocumentationTopicStore from 'docc-render/stores/DocumentationTopicStore';
@@ -146,4 +147,40 @@ describe('DocumentationTopic', () => {
 
     expect(wrapper.vm.topicData).toEqual(data);
   });
+
+  it('applies ObjC data when provided as overrides', () => {
+    dataUtils.fetchDataForRouteEnter = jest.fn();
+
+    const oldInterfaceLang = topicData.identifier.interfaceLanguage; // swift
+    const newInterfaceLang = 'occ';
+
+    const variantOverrides = [
+      {
+        traits: [{ interfaceLanguage: newInterfaceLang }],
+        patch: [
+          { op: 'replace', path: '/identifier/interfaceLanguage', value: newInterfaceLang },
+        ],
+      },
+    ];
+    wrapper.setData({
+      topicData: { ...topicData, variantOverrides },
+    });
+    expect(wrapper.vm.topicData.identifier.interfaceLanguage).toBe(oldInterfaceLang);
+
+    const to = {
+      query: { language: 'objc' },
+    };
+    const from = mocks.$route;
+    const next = jest.fn();
+    // there is probably a more realistic way to simulate this
+    DocumentationTopic.beforeRouteUpdate.call(wrapper.vm, to, from, next);
+
+    // check that the provided override data has been applied after updating the
+    // route with the "language=objc" query param and also ensure that new data
+    // is not fetched
+    expect(wrapper.vm.topicData.identifier.interfaceLanguage).not.toBe(oldInterfaceLang);
+    expect(wrapper.vm.topicData.identifier.interfaceLanguage).toBe(newInterfaceLang);
+    expect(dataUtils.fetchDataForRouteEnter).not.toBeCalled();
+    expect(next).toBeCalled();
+  });
 });