From 6cd9f6aed175da3247334f6441d2ff12ba92d8fa Mon Sep 17 00:00:00 2001
From: Dobromir Hristov <dhristov@apple.com>
Date: Thu, 11 Aug 2022 11:31:40 +0300
Subject: [PATCH 1/8] refactor: rename NavigatorLeafIcon to TopicTypeIcon. Move
 location to `/components`

---
 .../DocumentationTopic/DocumentationHero.vue           |  6 +++---
 src/components/Navigator/NavigatorCardItem.vue         |  6 +++---
 .../NavigatorLeafIcon.vue => TopicTypeIcon.vue}        |  6 +++---
 .../DocumentationTopic/DocumentationHero.spec.js       | 10 +++++-----
 .../components/Navigator/NavigatorCardItem.spec.js     |  6 +++---
 ...NavigatorLeafIcon.spec.js => TopicTypeIcon.spec.js} |  8 ++++----
 6 files changed, 21 insertions(+), 21 deletions(-)
 rename src/components/{Navigator/NavigatorLeafIcon.vue => TopicTypeIcon.vue} (98%)
 rename tests/unit/components/{Navigator/NavigatorLeafIcon.spec.js => TopicTypeIcon.spec.js} (88%)

diff --git a/src/components/DocumentationTopic/DocumentationHero.vue b/src/components/DocumentationTopic/DocumentationHero.vue
index 30f7ca1ed..dc91b5c97 100644
--- a/src/components/DocumentationTopic/DocumentationHero.vue
+++ b/src/components/DocumentationTopic/DocumentationHero.vue
@@ -17,7 +17,7 @@
     :style="styles"
   >
     <div class="icon">
-      <NavigatorLeafIcon
+      <TopicTypeIcon
         v-if="enhanceBackground" :type="type"
         key="first" class="background-icon first-icon" with-colors
       />
@@ -36,14 +36,14 @@
 
 <script>
 
-import NavigatorLeafIcon from 'docc-render/components/Navigator/NavigatorLeafIcon.vue';
+import TopicTypeIcon from 'docc-render/components/TopicTypeIcon.vue';
 import { TopicTypes, TopicTypeAliases } from 'docc-render/constants/TopicTypes';
 import { HeroColorsMap, HeroColors } from 'docc-render/constants/HeroColors';
 import { TopicRole } from 'docc-render/constants/roles';
 
 export default {
   name: 'DocumentationHero',
-  components: { NavigatorLeafIcon },
+  components: { TopicTypeIcon },
   props: {
     role: {
       type: String,
diff --git a/src/components/Navigator/NavigatorCardItem.vue b/src/components/Navigator/NavigatorCardItem.vue
index 5bfa3281d..28c1bafc5 100644
--- a/src/components/Navigator/NavigatorCardItem.vue
+++ b/src/components/Navigator/NavigatorCardItem.vue
@@ -45,7 +45,7 @@
           />
         </button>
       </div>
-      <NavigatorLeafIcon
+      <TopicTypeIcon
         v-if="!isGroupMarker && !apiChange"
         :type="item.type"
         class="navigator-icon"
@@ -93,7 +93,7 @@
 
 <script>
 import InlineChevronRightIcon from 'theme/components/Icons/InlineChevronRightIcon.vue';
-import NavigatorLeafIcon from 'docc-render/components/Navigator/NavigatorLeafIcon.vue';
+import TopicTypeIcon from 'docc-render/components/TopicTypeIcon.vue';
 import HighlightMatches from 'docc-render/components/Navigator/HighlightMatches.vue';
 import Reference from 'docc-render/components/ContentNode/Reference.vue';
 import Badge from 'docc-render/components/Badge.vue';
@@ -111,7 +111,7 @@ export default {
   ],
   components: {
     HighlightMatches,
-    NavigatorLeafIcon,
+    TopicTypeIcon,
     InlineChevronRightIcon,
     Reference,
     Badge,
diff --git a/src/components/Navigator/NavigatorLeafIcon.vue b/src/components/TopicTypeIcon.vue
similarity index 98%
rename from src/components/Navigator/NavigatorLeafIcon.vue
rename to src/components/TopicTypeIcon.vue
index 0a4c1d61a..3a125bf68 100644
--- a/src/components/Navigator/NavigatorLeafIcon.vue
+++ b/src/components/TopicTypeIcon.vue
@@ -9,7 +9,7 @@
 -->
 
 <template>
-  <div class="NavigatorLeafIcon">
+  <div class="TopicTypeIcon">
     <component :is="icon" v-bind="iconProps" class="icon-inline" :style="styles" />
   </div>
 </template>
@@ -80,7 +80,7 @@ const TopicTypeProps = {
 };
 
 export default {
-  name: 'NavigatorLeafIcon',
+  name: 'TopicTypeIcon',
   components: { SingleLetterSymbolIcon },
   constants: { TopicTypeIcons, TopicTypeProps },
   props: {
@@ -106,7 +106,7 @@ export default {
 <style scoped lang='scss'>
 @import 'docc-render/styles/_core.scss';
 
-.NavigatorLeafIcon {
+.TopicTypeIcon {
   width: 1em;
   height: 1em;
   margin-right: 7px;
diff --git a/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js b/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js
index 11215a727..651e3d26d 100644
--- a/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js
+++ b/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js
@@ -11,7 +11,7 @@
 import DocumentationHero from '@/components/DocumentationTopic/DocumentationHero.vue';
 import { shallowMount } from '@vue/test-utils';
 import { TopicTypes, TopicTypeAliases } from '@/constants/TopicTypes';
-import NavigatorLeafIcon from '@/components/Navigator/NavigatorLeafIcon.vue';
+import TopicTypeIcon from 'docc-render/components/TopicTypeIcon.vue';
 import { HeroColors, HeroColorsMap } from '@/constants/HeroColors';
 import { TopicRole } from '@/constants/roles';
 
@@ -53,7 +53,7 @@ describe('DocumentationHero', () => {
 
   it('renders the DocumentationHero, enabled', () => {
     const wrapper = createWrapper();
-    const allIcons = wrapper.findAll(NavigatorLeafIcon);
+    const allIcons = wrapper.findAll(TopicTypeIcon);
     expect(allIcons).toHaveLength(1);
     expect(allIcons.at(0).props()).toEqual({
       withColors: true,
@@ -127,7 +127,7 @@ describe('DocumentationHero', () => {
       enhanceBackground: false,
     });
     // assert no icon
-    const allIcons = wrapper.findAll(NavigatorLeafIcon);
+    const allIcons = wrapper.findAll(TopicTypeIcon);
     expect(allIcons).toHaveLength(0);
     // assert slot
     expect(wrapper.find('.default-slot').text()).toBe('Default Slot');
@@ -143,7 +143,7 @@ describe('DocumentationHero', () => {
         role: TopicRole.collection,
       },
     });
-    expect(wrapper.find(NavigatorLeafIcon).props('type')).toBe(TopicTypes.module);
+    expect(wrapper.find(TopicTypeIcon).props('type')).toBe(TopicTypes.module);
   });
 
   it('maps the "collectionGroup" role to the "collection" type', () => {
@@ -153,6 +153,6 @@ describe('DocumentationHero', () => {
         role: TopicRole.collectionGroup,
       },
     });
-    expect(wrapper.find(NavigatorLeafIcon).props('type')).toBe(TopicTypes.collection);
+    expect(wrapper.find(TopicTypeIcon).props('type')).toBe(TopicTypes.collection);
   });
 });
diff --git a/tests/unit/components/Navigator/NavigatorCardItem.spec.js b/tests/unit/components/Navigator/NavigatorCardItem.spec.js
index 84fd26a0f..f2c69b6a1 100644
--- a/tests/unit/components/Navigator/NavigatorCardItem.spec.js
+++ b/tests/unit/components/Navigator/NavigatorCardItem.spec.js
@@ -11,7 +11,7 @@
 import NavigatorCardItem from '@/components/Navigator/NavigatorCardItem.vue';
 import { RouterLinkStub, shallowMount } from '@vue/test-utils';
 import { TopicTypes } from '@/constants/TopicTypes';
-import NavigatorLeafIcon from '@/components/Navigator/NavigatorLeafIcon.vue';
+import TopicTypeIcon from 'docc-render/components/TopicTypeIcon.vue';
 import HighlightMatches from '@/components/Navigator/HighlightMatches.vue';
 import Reference from '@/components/ContentNode/Reference.vue';
 import { waitFrames } from 'docc-render/utils/loading';
@@ -62,7 +62,7 @@ describe('NavigatorCardItem', () => {
     const wrapper = createWrapper();
     expect(wrapper.find('.navigator-card-item').exists()).toBe(true);
     expect(wrapper.find('button.tree-toggle').exists()).toBe(true);
-    expect(wrapper.find(NavigatorLeafIcon).props('type')).toBe(defaultProps.item.type);
+    expect(wrapper.find(TopicTypeIcon).props('type')).toBe(defaultProps.item.type);
     const leafLink = wrapper.find('.leaf-link');
     expect(leafLink.is(Reference)).toBe(true);
     expect(leafLink.props('url')).toEqual(defaultProps.item.path);
@@ -287,7 +287,7 @@ describe('NavigatorCardItem', () => {
       },
     });
 
-    expect(wrapper.find(NavigatorLeafIcon).exists()).toBe(false);
+    expect(wrapper.find(TopicTypeIcon).exists()).toBe(false);
     expect(wrapper.find('.navigator-icon').classes())
       .toEqual(expect.arrayContaining(['changed', 'changed-modified']));
   });
diff --git a/tests/unit/components/Navigator/NavigatorLeafIcon.spec.js b/tests/unit/components/TopicTypeIcon.spec.js
similarity index 88%
rename from tests/unit/components/Navigator/NavigatorLeafIcon.spec.js
rename to tests/unit/components/TopicTypeIcon.spec.js
index bfc8a57ea..beb97d09d 100644
--- a/tests/unit/components/Navigator/NavigatorLeafIcon.spec.js
+++ b/tests/unit/components/TopicTypeIcon.spec.js
@@ -8,17 +8,17 @@
  * See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-import NavigatorLeafIcon from '@/components/Navigator/NavigatorLeafIcon.vue';
+import TopicTypeIcon from 'docc-render/components/TopicTypeIcon.vue';
 import { shallowMount } from '@vue/test-utils';
 import { TopicTypes, TopicTypeAliases } from '@/constants/TopicTypes';
 import { HeroColorsMap } from 'docc-render/constants/HeroColors';
 import CollectionIcon from '@/components/Icons/CollectionIcon.vue';
 
-const createWrapper = opts => shallowMount(NavigatorLeafIcon, opts);
+const createWrapper = opts => shallowMount(TopicTypeIcon, opts);
 const {
   TopicTypeIcons,
   TopicTypeProps,
-} = NavigatorLeafIcon.constants;
+} = TopicTypeIcon.constants;
 
 const cases = Object.keys(TopicTypes).map((type) => {
   const k = TopicTypeAliases[type] || type;
@@ -27,7 +27,7 @@ const cases = Object.keys(TopicTypes).map((type) => {
   return [type, icon.name, TopicTypeProps[type] || {}, color, icon];
 });
 
-describe('NavigatorLeafIcon', () => {
+describe('TopicTypeIcon', () => {
   it.each(cases)('Should render %s as %s, with %O bindings, and a %s color', (type, iconName, bindings, color, icon) => {
     const wrapper = createWrapper({
       propsData: {

From 93ed3a25666ebd4b59c3bd78cf36880d808f939b Mon Sep 17 00:00:00 2001
From: Dobromir Hristov <dhristov@apple.com>
Date: Thu, 11 Aug 2022 19:15:26 +0300
Subject: [PATCH 2/8] feat: support icon overriding

---
 src/components/DocumentationTopic.vue         |  5 +++
 .../DocumentationTopic/DocumentationHero.vue  |  8 ++++-
 src/components/Navigator.vue                  |  6 ++++
 src/components/Navigator/NavigatorCard.vue    |  5 +++
 .../Navigator/NavigatorCardItem.vue           |  5 +++
 .../Navigator/NavigatorDataProvider.vue       |  5 ++-
 src/components/SVGIcon.vue                    | 21 +++++++++++--
 src/components/TopicTypeIcon.vue              | 31 +++++++++++++++++--
 src/views/DocumentationTopic.vue              |  3 ++
 9 files changed, 82 insertions(+), 7 deletions(-)

diff --git a/src/components/DocumentationTopic.vue b/src/components/DocumentationTopic.vue
index d86a3c430..89cde109b 100644
--- a/src/components/DocumentationTopic.vue
+++ b/src/components/DocumentationTopic.vue
@@ -16,6 +16,7 @@
         :enhanceBackground="enhanceBackground"
         :shortHero="shortHero"
         :shouldShowLanguageSwitcher="shouldShowLanguageSwitcher"
+        :iconOverride="references[pageIcon]"
       >
         <template #above-content>
           <slot name="above-hero-content" />
@@ -270,6 +271,10 @@ export default {
       type: Object,
       required: false,
     },
+    pageIcon: {
+      type: String,
+      required: false,
+    },
   },
   provide() {
     // NOTE: this is not reactive: if this.references change, the provided value
diff --git a/src/components/DocumentationTopic/DocumentationHero.vue b/src/components/DocumentationTopic/DocumentationHero.vue
index dc91b5c97..b22c4809d 100644
--- a/src/components/DocumentationTopic/DocumentationHero.vue
+++ b/src/components/DocumentationTopic/DocumentationHero.vue
@@ -18,7 +18,9 @@
   >
     <div class="icon">
       <TopicTypeIcon
-        v-if="enhanceBackground" :type="type"
+        v-if="enhanceBackground"
+        :type="type"
+        :image-override="iconOverride"
         key="first" class="background-icon first-icon" with-colors
       />
     </div>
@@ -61,6 +63,10 @@ export default {
       type: Boolean,
       required: true,
     },
+    iconOverride: {
+      type: Object,
+      required: false,
+    },
   },
   computed: {
     // get the alias, if any, and fallback to the `teal` color
diff --git a/src/components/Navigator.vue b/src/components/Navigator.vue
index 895019116..39291a72e 100644
--- a/src/components/Navigator.vue
+++ b/src/components/Navigator.vue
@@ -27,6 +27,7 @@
       :api-changes="apiChanges"
       :allow-hiding="allowHiding"
       :enableQuickNavigation="enableQuickNavigation"
+      :navigator-references="navigatorReferences"
       @close="$emit('close')"
     />
     <NavigatorCardInner v-else class="loading-placeholder">
@@ -55,6 +56,7 @@ import { getSetting } from 'docc-render/utils/theme-settings';
  * @property {number} uid - generated UID
  * @property {string} title - title of symbol
  * @property {string} type - symbol type, used for the icon
+ * @property {string} icon - an image reference to override the type icon
  * @property {array} abstract - symbol abstract
  * @property {string} path - path to page, used in navigation
  * @property {number} parent - parent UID
@@ -101,6 +103,10 @@ export default {
       type: Object,
       default: () => {},
     },
+    navigatorReferences: {
+      type: Object,
+      default: () => {},
+    },
     scrollLockID: {
       type: String,
       default: '',
diff --git a/src/components/Navigator/NavigatorCard.vue b/src/components/Navigator/NavigatorCard.vue
index 3dbe4787f..f9bcf163a 100644
--- a/src/components/Navigator/NavigatorCard.vue
+++ b/src/components/Navigator/NavigatorCard.vue
@@ -65,6 +65,7 @@
               :api-change="apiChangesObject[item.path]"
               :isFocused="focusedIndex === index"
               :enableFocus="!externalFocusChange"
+              :navigator-references="navigatorReferences"
               @toggle="toggle"
               @toggle-full="toggleFullTree"
               @toggle-siblings="toggleSiblings"
@@ -253,6 +254,10 @@ export default {
       type: Boolean,
       default: true,
     },
+    navigatorReferences: {
+      type: Object,
+      default: () => {},
+    },
   },
   mixins: [
     keyboardNavigation,
diff --git a/src/components/Navigator/NavigatorCardItem.vue b/src/components/Navigator/NavigatorCardItem.vue
index 28c1bafc5..f7f74d881 100644
--- a/src/components/Navigator/NavigatorCardItem.vue
+++ b/src/components/Navigator/NavigatorCardItem.vue
@@ -48,6 +48,7 @@
       <TopicTypeIcon
         v-if="!isGroupMarker && !apiChange"
         :type="item.type"
+        :image-override="item.icon ? navigatorReferences[item.icon] : null"
         class="navigator-icon"
       />
       <span
@@ -154,6 +155,10 @@ export default {
       type: Boolean,
       default: true,
     },
+    navigatorReferences: {
+      type: Object,
+      default: () => ({}),
+    },
   },
   idState() {
     return {
diff --git a/src/components/Navigator/NavigatorDataProvider.vue b/src/components/Navigator/NavigatorDataProvider.vue
index 719268d3c..e0c3d1a99 100644
--- a/src/components/Navigator/NavigatorDataProvider.vue
+++ b/src/components/Navigator/NavigatorDataProvider.vue
@@ -40,6 +40,7 @@ export default {
       navigationIndex: {
         [Language.swift.key.url]: [],
       },
+      navigationReferences: {},
       diffs: null,
     };
   },
@@ -73,8 +74,9 @@ export default {
     async fetchIndexData() {
       try {
         this.isFetching = true;
-        const { interfaceLanguages } = await fetchIndexPathsData();
+        const { interfaceLanguages, references } = await fetchIndexPathsData();
         this.navigationIndex = Object.freeze(interfaceLanguages);
+        this.navigationReferences = Object.freeze(references);
       } catch (e) {
         this.errorFetching = true;
       } finally {
@@ -89,6 +91,7 @@ export default {
       errorFetching: this.errorFetching,
       isFetchingAPIChanges: this.isFetchingAPIChanges,
       apiChanges: this.diffs,
+      references: this.navigationReferences,
     });
   },
 };
diff --git a/src/components/SVGIcon.vue b/src/components/SVGIcon.vue
index 1dfaa87c1..1ec359f99 100644
--- a/src/components/SVGIcon.vue
+++ b/src/components/SVGIcon.vue
@@ -13,13 +13,30 @@
     aria-hidden="true"
     class="svg-icon"
     xmlns="http://www.w3.org/2000/svg"
+    xmlns:xlink="http://www.w3.org/1999/xlink"
   >
-    <slot />
+    <use v-if="themeOverrideURL" :href="`${themeOverrideURL}#${themeId}`" />
+    <slot v-else />
   </svg>
 </template>
 
 <script>
-export default { name: 'SVGIcon' };
+export default {
+  name: 'SVGIcon',
+  props: {
+    themeId: {
+      type: String,
+      required: false,
+    },
+    iconUrl: {
+      type: String,
+      default: null,
+    },
+  },
+  computed: {
+    themeOverrideURL: ({ iconUrl }) => iconUrl,
+  },
+};
 </script>
 
 <style scoped lang="scss">
diff --git a/src/components/TopicTypeIcon.vue b/src/components/TopicTypeIcon.vue
index 3a125bf68..4ecfe1dd2 100644
--- a/src/components/TopicTypeIcon.vue
+++ b/src/components/TopicTypeIcon.vue
@@ -10,7 +10,20 @@
 
 <template>
   <div class="TopicTypeIcon">
-    <component :is="icon" v-bind="iconProps" class="icon-inline" :style="styles" />
+    <component
+      v-if="!imagePath"
+      :is="icon"
+      v-bind="iconProps"
+      :style="styles"
+      class="icon-inline"
+    />
+    <SVGIcon
+      v-else
+      :icon-url="imagePath"
+      theme-id="topic"
+      :style="styles"
+      class="icon-inline"
+    />
   </div>
 </template>
 
@@ -28,6 +41,7 @@ import TwoLetterSymbolIcon from 'theme/components/Icons/TwoLetterSymbolIcon.vue'
 import SingleLetterSymbolIcon from 'theme/components/Icons/SingleLetterSymbolIcon.vue';
 import { TopicTypes, TopicTypeAliases } from 'docc-render/constants/TopicTypes';
 import { HeroColorsMap } from 'docc-render/constants/HeroColors';
+import SVGIcon from 'docc-render/components/SVGIcon.vue';
 
 const TopicTypeIcons = {
   [TopicTypes.article]: ArticleIcon,
@@ -81,7 +95,7 @@ const TopicTypeProps = {
 
 export default {
   name: 'TopicTypeIcon',
-  components: { SingleLetterSymbolIcon },
+  components: { SVGIcon, SingleLetterSymbolIcon },
   constants: { TopicTypeIcons, TopicTypeProps },
   props: {
     type: {
@@ -92,13 +106,24 @@ export default {
       type: Boolean,
       default: false,
     },
+    imageOverride: {
+      type: Object,
+      default: null,
+    },
   },
   computed: {
     normalisedType: ({ type }) => TopicTypeAliases[type] || type,
     icon: ({ normalisedType }) => TopicTypeIcons[normalisedType] || CollectionIcon,
     iconProps: ({ normalisedType }) => TopicTypeProps[normalisedType] || {},
     color: ({ normalisedType }) => HeroColorsMap[normalisedType],
-    styles: ({ color, withColors }) => (withColors && color ? { color: `var(--color-type-icon-${color})` } : {}),
+    imagePath: ({ imageOverride }) => {
+      if (!imageOverride) return null;
+      return imageOverride.variants[0].url;
+    },
+    styles: ({
+      color,
+      withColors,
+    }) => (withColors && color ? { color: `var(--color-type-icon-${color})` } : {}),
   },
 };
 </script>
diff --git a/src/views/DocumentationTopic.vue b/src/views/DocumentationTopic.vue
index 385f182db..97ab51d6b 100644
--- a/src/views/DocumentationTopic.vue
+++ b/src/views/DocumentationTopic.vue
@@ -37,6 +37,7 @@
                       :error-fetching="slotProps.errorFetching"
                       :api-changes="slotProps.apiChanges"
                       :references="topicProps.references"
+                      :navigator-references="slotProps.references"
                       :scrollLockID="scrollLockID"
                       :breakpoint="breakpoint"
                       @close="handleToggleSidenav(breakpoint)"
@@ -179,6 +180,7 @@ export default {
           role,
           symbolKind = '',
           remoteSource,
+          pageIcon = '',
         } = {},
         primaryContentSections,
         relationshipsSections,
@@ -214,6 +216,7 @@ export default {
         symbolKind,
         tags: tags.slice(0, 1), // make sure we only show the first tag
         remoteSource,
+        pageIcon,
       };
     },
     // The `hierarchy.paths` array will contain zero or more subarrays, each

From ce1f219ca8caa9f37f28e303e903800aaa03cffb Mon Sep 17 00:00:00 2001
From: Dobromir Hristov <dhristov@apple.com>
Date: Fri, 12 Aug 2022 12:49:38 +0300
Subject: [PATCH 3/8] chore: add tests

---
 .../components/DocumentationTopic.spec.js     |  8 ++++++
 .../DocumentationHero.spec.js                 |  2 ++
 tests/unit/components/Navigator.spec.js       |  7 ++++++
 .../Navigator/NavigatorCard.spec.js           |  9 ++++++-
 .../Navigator/NavigatorCardItem.spec.js       | 25 ++++++++++++++++++-
 .../Navigator/NavigatorDataProvider.spec.js   | 13 ++++++++++
 tests/unit/components/TopicTypeIcon.spec.js   | 23 +++++++++++++++++
 tests/unit/views/DocumentationTopic.spec.js   |  5 ++++
 8 files changed, 90 insertions(+), 2 deletions(-)

diff --git a/tests/unit/components/DocumentationTopic.spec.js b/tests/unit/components/DocumentationTopic.spec.js
index 0c1f4e6a9..3b5fccc3b 100644
--- a/tests/unit/components/DocumentationTopic.spec.js
+++ b/tests/unit/components/DocumentationTopic.spec.js
@@ -146,6 +146,7 @@ const propsData = {
     },
   ],
   remoteSource: { url: 'foo' },
+  pageIcon: 'foo',
 };
 
 describe('DocumentationTopic', () => {
@@ -217,6 +218,12 @@ describe('DocumentationTopic', () => {
   });
 
   it('renders a `DocumentationHero`, enabled', () => {
+    const iconOverride = { variants: [] };
+    wrapper.setProps({
+      references: {
+        [propsData.pageIcon]: iconOverride,
+      },
+    });
     const hero = wrapper.find(DocumentationHero);
     expect(hero.exists()).toBe(true);
     expect(hero.props()).toEqual({
@@ -224,6 +231,7 @@ describe('DocumentationTopic', () => {
       enhanceBackground: true,
       shortHero: false,
       shouldShowLanguageSwitcher: false,
+      iconOverride,
     });
   });
 
diff --git a/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js b/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js
index 651e3d26d..1e55642c0 100644
--- a/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js
+++ b/tests/unit/components/DocumentationTopic/DocumentationHero.spec.js
@@ -20,6 +20,7 @@ const defaultProps = {
   enhanceBackground: true,
   shortHero: true,
   shouldShowLanguageSwitcher: true,
+  iconOverride: { variants: ['foo'] },
 };
 
 const createWrapper = ({ propsData, ...others } = {}) => shallowMount(DocumentationHero, {
@@ -58,6 +59,7 @@ describe('DocumentationHero', () => {
     expect(allIcons.at(0).props()).toEqual({
       withColors: true,
       type: defaultProps.role,
+      imageOverride: defaultProps.iconOverride,
     });
     expect(allIcons.at(0).classes()).toEqual(['background-icon', 'first-icon']);
     // assert slot
diff --git a/tests/unit/components/Navigator.spec.js b/tests/unit/components/Navigator.spec.js
index ad68dd768..a3d89a8b0 100644
--- a/tests/unit/components/Navigator.spec.js
+++ b/tests/unit/components/Navigator.spec.js
@@ -94,12 +94,17 @@ const mocks = {
   },
 };
 
+const navigatorReferences = {
+  foo: {},
+};
+
 const defaultProps = {
   parentTopicIdentifiers,
   technology,
   references,
   scrollLockID: 'foo',
   breakpoint: 'large',
+  navigatorReferences,
 };
 
 const fauxAnchor = document.createElement('DIV');
@@ -144,6 +149,7 @@ describe('Navigator', () => {
       errorFetching: false,
       apiChanges: null,
       allowHiding: true,
+      navigatorReferences,
     });
     expect(wrapper.find('.loading-placeholder').exists()).toBe(false);
   });
@@ -198,6 +204,7 @@ describe('Navigator', () => {
       errorFetching: false,
       apiChanges: null,
       allowHiding: true,
+      navigatorReferences,
     });
   });
 
diff --git a/tests/unit/components/Navigator/NavigatorCard.spec.js b/tests/unit/components/Navigator/NavigatorCard.spec.js
index cd6a1e7e7..45879cad8 100644
--- a/tests/unit/components/Navigator/NavigatorCard.spec.js
+++ b/tests/unit/components/Navigator/NavigatorCard.spec.js
@@ -122,7 +122,9 @@ const children = [
 ];
 
 const activePath = [root0.path, root0Child0.path];
-
+const navigatorReferences = {
+  foo: {},
+};
 const defaultProps = {
   technology: 'TestKit',
   technologyPath: '/documentation/testkit',
@@ -131,6 +133,7 @@ const defaultProps = {
   type: TopicTypes.module,
   scrollLockID: 'foo',
   breakpoint: 'large',
+  navigatorReferences,
 };
 
 const createWrapper = ({ propsData, ...others } = {}) => shallowMount(NavigatorCard, {
@@ -215,6 +218,7 @@ describe('NavigatorCard', () => {
       item: root0,
       apiChange: null,
       enableFocus: false,
+      navigatorReferences,
     });
     // assert no-items-wrapper
     expect(wrapper.find('.no-items-wrapper').exists()).toBe(true);
@@ -426,6 +430,7 @@ describe('NavigatorCard', () => {
         isRendered: false,
         apiChange: null,
         enableFocus: false,
+        navigatorReferences,
       });
       unopenedItem.vm.$emit('toggle', item);
       await wrapper.vm.$nextTick();
@@ -1860,6 +1865,7 @@ describe('NavigatorCard', () => {
         isRendered: false, // this is not passed in the mock
         item: root0Child1,
         enableFocus: false,
+        navigatorReferences,
       });
       // assert item is scrolled to once
       expect(getChildPositionInScroller).toHaveBeenCalledTimes(2);
@@ -1884,6 +1890,7 @@ describe('NavigatorCard', () => {
         isRendered: false, // this is not passed in the mock
         item: root0Child1,
         enableFocus: false,
+        navigatorReferences,
       });
     });
 
diff --git a/tests/unit/components/Navigator/NavigatorCardItem.spec.js b/tests/unit/components/Navigator/NavigatorCardItem.spec.js
index f2c69b6a1..ee228d33d 100644
--- a/tests/unit/components/Navigator/NavigatorCardItem.spec.js
+++ b/tests/unit/components/Navigator/NavigatorCardItem.spec.js
@@ -62,7 +62,11 @@ describe('NavigatorCardItem', () => {
     const wrapper = createWrapper();
     expect(wrapper.find('.navigator-card-item').exists()).toBe(true);
     expect(wrapper.find('button.tree-toggle').exists()).toBe(true);
-    expect(wrapper.find(TopicTypeIcon).props('type')).toBe(defaultProps.item.type);
+    expect(wrapper.find(TopicTypeIcon).props()).toEqual({
+      type: defaultProps.item.type,
+      imageOverride: null,
+      withColors: false,
+    });
     const leafLink = wrapper.find('.leaf-link');
     expect(leafLink.is(Reference)).toBe(true);
     expect(leafLink.props('url')).toEqual(defaultProps.item.path);
@@ -75,6 +79,25 @@ describe('NavigatorCardItem', () => {
       .toBe(`container-${defaultProps.item.uid}`);
   });
 
+  it('renders the NavigationCardItem with an icon override', () => {
+    const navigatorReferences = {
+      iconRef: {
+        identifier: 'iconRef',
+        variants: [],
+      },
+    };
+    const wrapper = createWrapper({
+      propsData: {
+        navigatorReferences,
+        item: {
+          ...defaultProps.item,
+          icon: navigatorReferences.iconRef.identifier,
+        },
+      },
+    });
+    expect(wrapper.find(TopicTypeIcon).props('imageOverride')).toEqual(navigatorReferences.iconRef);
+  });
+
   it('renders a deprecated badge when item is deprecated', () => {
     let wrapper;
     wrapper = createWrapper();
diff --git a/tests/unit/components/Navigator/NavigatorDataProvider.spec.js b/tests/unit/components/Navigator/NavigatorDataProvider.spec.js
index 793913ab8..937c852ff 100644
--- a/tests/unit/components/Navigator/NavigatorDataProvider.spec.js
+++ b/tests/unit/components/Navigator/NavigatorDataProvider.spec.js
@@ -37,6 +37,10 @@ const objectiveCIndexOne = {
   children: [1],
 };
 
+const references = {
+  foo: { bar: 'bar' },
+};
+
 const response = {
   interfaceLanguages: {
     [Language.swift.key.url]: [
@@ -47,6 +51,7 @@ const response = {
       objectiveCIndexOne,
     ],
   },
+  references,
 };
 
 fetchIndexPathsData.mockResolvedValue(response);
@@ -88,6 +93,7 @@ describe('NavigatorDataProvider', () => {
       isFetching: false,
       technology: swiftIndexOne,
       errorFetching: false,
+      references,
     });
   });
 
@@ -110,6 +116,7 @@ describe('NavigatorDataProvider', () => {
       isFetching: false,
       technology: swiftIndexOne,
       errorFetching: false,
+      references,
     });
   });
 
@@ -126,6 +133,7 @@ describe('NavigatorDataProvider', () => {
       isFetching: false,
       technology: undefined,
       errorFetching: true,
+      references: {},
     });
   });
 
@@ -145,6 +153,7 @@ describe('NavigatorDataProvider', () => {
       errorFetching: false,
       isFetching: false,
       technology: objectiveCIndexOne,
+      references,
     });
   });
 
@@ -154,6 +163,7 @@ describe('NavigatorDataProvider', () => {
       interfaceLanguages: {
         [Language.swift.key.url]: response.interfaceLanguages[Language.swift.key.url],
       },
+      references,
     });
     createWrapper({
       propsData: {
@@ -169,6 +179,7 @@ describe('NavigatorDataProvider', () => {
       errorFetching: false,
       isFetching: false,
       technology: swiftIndexOne,
+      references,
     });
   });
 
@@ -187,6 +198,7 @@ describe('NavigatorDataProvider', () => {
       errorFetching: false,
       isFetching: false,
       technology: undefined,
+      references,
     });
   });
 
@@ -201,6 +213,7 @@ describe('NavigatorDataProvider', () => {
       isFetching: false,
       technology: undefined,
       errorFetching: false,
+      references: undefined,
     });
   });
 });
diff --git a/tests/unit/components/TopicTypeIcon.spec.js b/tests/unit/components/TopicTypeIcon.spec.js
index beb97d09d..6809ad9f2 100644
--- a/tests/unit/components/TopicTypeIcon.spec.js
+++ b/tests/unit/components/TopicTypeIcon.spec.js
@@ -13,6 +13,7 @@ import { shallowMount } from '@vue/test-utils';
 import { TopicTypes, TopicTypeAliases } from '@/constants/TopicTypes';
 import { HeroColorsMap } from 'docc-render/constants/HeroColors';
 import CollectionIcon from '@/components/Icons/CollectionIcon.vue';
+import SVGIcon from '@/components/SVGIcon.vue';
 
 const createWrapper = opts => shallowMount(TopicTypeIcon, opts);
 const {
@@ -52,4 +53,26 @@ describe('TopicTypeIcon', () => {
     });
     expect(wrapper.vm.styles).not.toHaveProperty('color');
   });
+
+  it('renders an icon override', () => {
+    const imageOverride = {
+      variants: [{
+        url: 'baz.svg',
+      }, {
+        url: 'bar.svg',
+      }],
+    };
+    const wrapper = createWrapper({
+      propsData: {
+        imageOverride,
+        type: TopicTypes.class,
+      },
+    });
+    const icon = wrapper.find('.icon-inline');
+    expect(icon.is(SVGIcon)).toBe(true);
+    expect(icon.props()).toMatchObject({
+      iconUrl: imageOverride.variants[0].url,
+      themeId: 'topic', // TODO: figure out if we should make this authorable
+    });
+  });
 });
diff --git a/tests/unit/views/DocumentationTopic.spec.js b/tests/unit/views/DocumentationTopic.spec.js
index 7fb20d756..1770e3546 100644
--- a/tests/unit/views/DocumentationTopic.spec.js
+++ b/tests/unit/views/DocumentationTopic.spec.js
@@ -33,10 +33,13 @@ const TechnologyWithChildren = {
   children: [],
 };
 
+const navigatorReferences = { foo: {} };
+
 jest.spyOn(dataUtils, 'fetchIndexPathsData').mockResolvedValue({
   interfaceLanguages: {
     [Language.swift.key.url]: [TechnologyWithChildren, { path: 'another/technology' }],
   },
+  references: navigatorReferences,
 });
 
 const { CodeTheme, Nav, Topic } = DocumentationTopic.components;
@@ -200,6 +203,7 @@ describe('DocumentationTopic', () => {
       technology,
       apiChanges: null,
       allowHiding: true,
+      navigatorReferences: {},
     });
     expect(dataUtils.fetchIndexPathsData).toHaveBeenCalledTimes(1);
     await flushPromises();
@@ -213,6 +217,7 @@ describe('DocumentationTopic', () => {
       technology: TechnologyWithChildren,
       apiChanges: null,
       allowHiding: true,
+      navigatorReferences,
     });
     // assert the nav is in wide format
     const nav = wrapper.find(Nav);

From 9bbcf9674c6a39d2615d1c1ec7464bdf84288a20 Mon Sep 17 00:00:00 2001
From: Dobromir Hristov <dhristov@apple.com>
Date: Tue, 6 Sep 2022 12:13:14 +0300
Subject: [PATCH 4/8] refactor: use provided in RenderJSOn svgID, for image
 overrides.

---
 src/components/TopicTypeIcon.vue            | 20 +++++++++++---------
 tests/unit/components/TopicTypeIcon.spec.js | 19 ++++++++++++++++++-
 2 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/src/components/TopicTypeIcon.vue b/src/components/TopicTypeIcon.vue
index 4ecfe1dd2..a27e2d1c1 100644
--- a/src/components/TopicTypeIcon.vue
+++ b/src/components/TopicTypeIcon.vue
@@ -10,17 +10,17 @@
 
 <template>
   <div class="TopicTypeIcon">
-    <component
-      v-if="!imagePath"
-      :is="icon"
-      v-bind="iconProps"
+    <SVGIcon
+      v-if="imageOverridePath && imageOverrideId"
+      :icon-url="imageOverridePath"
+      :theme-id="imageOverrideId"
       :style="styles"
       class="icon-inline"
     />
-    <SVGIcon
+    <component
       v-else
-      :icon-url="imagePath"
-      theme-id="topic"
+      :is="icon"
+      v-bind="iconProps"
       :style="styles"
       class="icon-inline"
     />
@@ -116,10 +116,12 @@ export default {
     icon: ({ normalisedType }) => TopicTypeIcons[normalisedType] || CollectionIcon,
     iconProps: ({ normalisedType }) => TopicTypeProps[normalisedType] || {},
     color: ({ normalisedType }) => HeroColorsMap[normalisedType],
-    imagePath: ({ imageOverride }) => {
+    imageOverrideVariant: ({ imageOverride }) => {
       if (!imageOverride) return null;
-      return imageOverride.variants[0].url;
+      return imageOverride.variants[0];
     },
+    imageOverridePath: ({ imageOverrideVariant }) => imageOverrideVariant && imageOverrideVariant.url,
+    imageOverrideId: ({ imageOverrideVariant }) => imageOverrideVariant && imageOverrideVariant.svgID,
     styles: ({
       color,
       withColors,
diff --git a/tests/unit/components/TopicTypeIcon.spec.js b/tests/unit/components/TopicTypeIcon.spec.js
index 6809ad9f2..f6615369f 100644
--- a/tests/unit/components/TopicTypeIcon.spec.js
+++ b/tests/unit/components/TopicTypeIcon.spec.js
@@ -58,6 +58,7 @@ describe('TopicTypeIcon', () => {
     const imageOverride = {
       variants: [{
         url: 'baz.svg',
+        svgID: 'foo',
       }, {
         url: 'bar.svg',
       }],
@@ -72,7 +73,23 @@ describe('TopicTypeIcon', () => {
     expect(icon.is(SVGIcon)).toBe(true);
     expect(icon.props()).toMatchObject({
       iconUrl: imageOverride.variants[0].url,
-      themeId: 'topic', // TODO: figure out if we should make this authorable
+      themeId: imageOverride.variants[0].svgID,
     });
   });
+
+  it('does not render icon overrides, if it does not have an `svgID`', () => {
+    const imageOverride = {
+      variants: [{
+        url: 'baz.svg',
+      }],
+    };
+    const wrapper = createWrapper({
+      propsData: {
+        imageOverride,
+        type: TopicTypes.class,
+      },
+    });
+    const icon = wrapper.find('.icon-inline');
+    expect(icon.is(SVGIcon)).toBe(false);
+  });
 });

From 45297f7da70e8174dc302ab1cb8c935153c8a090 Mon Sep 17 00:00:00 2001
From: Dobromir Hristov <dhristov@apple.com>
Date: Fri, 9 Sep 2022 14:28:27 +0300
Subject: [PATCH 5/8] refactor: use `images` metadata property to override the
 page image

---
 src/components/DocumentationTopic.vue         | 13 +++++++++++--
 src/views/DocumentationTopic.vue              |  4 ++--
 .../components/DocumentationTopic.spec.js     | 19 +++++++++++++++++--
 3 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/src/components/DocumentationTopic.vue b/src/components/DocumentationTopic.vue
index 89cde109b..a0b75aa47 100644
--- a/src/components/DocumentationTopic.vue
+++ b/src/components/DocumentationTopic.vue
@@ -271,8 +271,8 @@ export default {
       type: Object,
       required: false,
     },
-    pageIcon: {
-      type: String,
+    pageImages: {
+      type: Array,
       required: false,
     },
   },
@@ -355,6 +355,15 @@ export default {
       || (primaryContentSections && primaryContentSections.length)
     ),
     tagName: ({ isSymbolDeprecated }) => (isSymbolDeprecated ? 'Deprecated' : 'Beta'),
+    /**
+     * Finds the page icon in the `pageImages` array
+     * @param {Array} pageImages
+     * @returns {String|null}
+     */
+    pageIcon: ({ pageImages = [] }) => {
+      const icon = pageImages.find(({ type }) => type === 'icon');
+      return icon ? icon.reference : null;
+    },
   },
   methods: {
     normalizePath(path) {
diff --git a/src/views/DocumentationTopic.vue b/src/views/DocumentationTopic.vue
index 97ab51d6b..29725eab3 100644
--- a/src/views/DocumentationTopic.vue
+++ b/src/views/DocumentationTopic.vue
@@ -180,7 +180,7 @@ export default {
           role,
           symbolKind = '',
           remoteSource,
-          pageIcon = '',
+          images: pageImages = [],
         } = {},
         primaryContentSections,
         relationshipsSections,
@@ -216,7 +216,7 @@ export default {
         symbolKind,
         tags: tags.slice(0, 1), // make sure we only show the first tag
         remoteSource,
-        pageIcon,
+        pageImages,
       };
     },
     // The `hierarchy.paths` array will contain zero or more subarrays, each
diff --git a/tests/unit/components/DocumentationTopic.spec.js b/tests/unit/components/DocumentationTopic.spec.js
index 3b5fccc3b..79e25d969 100644
--- a/tests/unit/components/DocumentationTopic.spec.js
+++ b/tests/unit/components/DocumentationTopic.spec.js
@@ -146,7 +146,7 @@ const propsData = {
     },
   ],
   remoteSource: { url: 'foo' },
-  pageIcon: 'foo',
+  pageImages: [{ reference: 'foo', type: 'icon' }],
 };
 
 describe('DocumentationTopic', () => {
@@ -221,7 +221,7 @@ describe('DocumentationTopic', () => {
     const iconOverride = { variants: [] };
     wrapper.setProps({
       references: {
-        [propsData.pageIcon]: iconOverride,
+        [propsData.pageImages[0].reference]: iconOverride,
       },
     });
     const hero = wrapper.find(DocumentationHero);
@@ -235,6 +235,21 @@ describe('DocumentationTopic', () => {
     });
   });
 
+  it('renders a `DocumentationHero` without an image override ', () => {
+    wrapper.setProps({
+      pageImages: [],
+    });
+    const hero = wrapper.find(DocumentationHero);
+    expect(hero.exists()).toBe(true);
+    expect(hero.props()).toEqual({
+      role: propsData.role,
+      enhanceBackground: true,
+      shortHero: false,
+      shouldShowLanguageSwitcher: false,
+      iconOverride: undefined,
+    });
+  });
+
   it('render a `DocumentationHero`, enabled, if top-level technology page', () => {
     const hero = wrapper.find(DocumentationHero);
     expect(hero.props()).toEqual({

From 048e70ae78fa2ee4072c5bc1b009c78b55d2ab4a Mon Sep 17 00:00:00 2001
From: Dobromir Hristov <dhristov@apple.com>
Date: Mon, 12 Sep 2022 12:37:25 +0300
Subject: [PATCH 6/8] fix: use `identifier` instead of `reference`

---
 src/components/DocumentationTopic.vue            | 2 +-
 tests/unit/components/DocumentationTopic.spec.js | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/components/DocumentationTopic.vue b/src/components/DocumentationTopic.vue
index a0b75aa47..644778253 100644
--- a/src/components/DocumentationTopic.vue
+++ b/src/components/DocumentationTopic.vue
@@ -362,7 +362,7 @@ export default {
      */
     pageIcon: ({ pageImages = [] }) => {
       const icon = pageImages.find(({ type }) => type === 'icon');
-      return icon ? icon.reference : null;
+      return icon ? icon.identifier : null;
     },
   },
   methods: {
diff --git a/tests/unit/components/DocumentationTopic.spec.js b/tests/unit/components/DocumentationTopic.spec.js
index 79e25d969..03e1b7bd8 100644
--- a/tests/unit/components/DocumentationTopic.spec.js
+++ b/tests/unit/components/DocumentationTopic.spec.js
@@ -146,7 +146,7 @@ const propsData = {
     },
   ],
   remoteSource: { url: 'foo' },
-  pageImages: [{ reference: 'foo', type: 'icon' }],
+  pageImages: [{ identifier: 'foo', type: 'icon' }],
 };
 
 describe('DocumentationTopic', () => {
@@ -221,7 +221,7 @@ describe('DocumentationTopic', () => {
     const iconOverride = { variants: [] };
     wrapper.setProps({
       references: {
-        [propsData.pageImages[0].reference]: iconOverride,
+        [propsData.pageImages[0].identifier]: iconOverride,
       },
     });
     const hero = wrapper.find(DocumentationHero);

From 0b9f5b3cdcbfb162fd7b20c40ca3a4cb06f8c798 Mon Sep 17 00:00:00 2001
From: Dobromir Hristov <dhristov@apple.com>
Date: Mon, 12 Sep 2022 14:31:26 +0300
Subject: [PATCH 7/8] refactor: allow overriding the icon for TopicsLinkBlock

---
 .../DocumentationTopic/TopicLinkBlockIcon.vue | 26 +++++++-
 .../DocumentationTopic/TopicsLinkBlock.vue    | 15 ++++-
 .../TopicLinkBlockIcon.spec.js                | 64 +++++++++++++++++++
 .../TopicsLinkBlock.spec.js                   | 22 +++++++
 4 files changed, 122 insertions(+), 5 deletions(-)
 create mode 100644 tests/unit/components/DocumentationTopic/TopicLinkBlockIcon.spec.js

diff --git a/src/components/DocumentationTopic/TopicLinkBlockIcon.vue b/src/components/DocumentationTopic/TopicLinkBlockIcon.vue
index 60326e074..21050df4f 100644
--- a/src/components/DocumentationTopic/TopicLinkBlockIcon.vue
+++ b/src/components/DocumentationTopic/TopicLinkBlockIcon.vue
@@ -9,8 +9,14 @@
 -->
 
 <template>
-  <div class="topic-icon-wrapper" v-if="icon">
-    <component :is="icon" class="topic-icon" />
+  <div class="topic-icon-wrapper" v-if="icon || shouldShowImageOverride">
+    <SVGIcon
+      v-if="shouldShowImageOverride"
+      :icon-url="imageOverridePath"
+      :theme-id="imageOverrideId"
+      class="topic-icon"
+    />
+    <component v-else :is="icon" class="topic-icon" />
   </div>
 </template>
 
@@ -21,6 +27,7 @@ import ApiCollectionIcon from 'theme/components/Icons/APIReferenceIcon.vue';
 import EndpointIcon from 'theme/components/Icons/EndpointIcon.vue';
 import PathIcon from 'theme/components/Icons/PathIcon.vue';
 import TutorialIcon from 'theme/components/Icons/TutorialIcon.vue';
+import SVGIcon from 'docc-render/components/SVGIcon.vue';
 import { TopicRole } from 'docc-render/constants/roles';
 
 const TopicRoleIcons = {
@@ -36,15 +43,30 @@ const TopicRoleIcons = {
 };
 
 export default {
+  components: { SVGIcon },
   props: {
     role: {
       type: String,
       required: true,
     },
+    imageOverride: {
+      type: Object,
+      default: null,
+    },
   },
 
   computed: {
     icon: ({ role }) => TopicRoleIcons[role],
+    imageOverrideVariant: ({ imageOverride }) => {
+      if (!imageOverride) return null;
+      return imageOverride.variants[0];
+    },
+    imageOverridePath: ({ imageOverrideVariant }) => imageOverrideVariant && imageOverrideVariant.url,
+    imageOverrideId: ({ imageOverrideVariant }) => imageOverrideVariant && imageOverrideVariant.svgID,
+    shouldShowImageOverride: ({
+      imageOverridePath,
+      imageOverrideId,
+    }) => imageOverridePath && imageOverrideId,
   },
 };
 </script>
diff --git a/src/components/DocumentationTopic/TopicsLinkBlock.vue b/src/components/DocumentationTopic/TopicsLinkBlock.vue
index 377b1546d..6e25b7ab9 100644
--- a/src/components/DocumentationTopic/TopicsLinkBlock.vue
+++ b/src/components/DocumentationTopic/TopicsLinkBlock.vue
@@ -17,7 +17,11 @@
       class="link"
       ref="apiChangesDiff"
     >
-      <TopicLinkBlockIcon v-if="topic.role && !change" :role="topic.role" />
+      <TopicLinkBlockIcon
+        v-if="topic.role && !change"
+        :role="topic.role"
+        :imageOverride="references[iconOverride]"
+      />
       <DecoratedTopicTitle v-if="topic.fragments" :tokens="topic.fragments" />
       <WordBreak v-else :tag="titleTag">{{ topic.title }}</WordBreak>
       <span v-if="change" class="visuallyhidden">- {{ changeName }}</span>
@@ -66,7 +70,8 @@ import WordBreak from 'docc-render/components/WordBreak.vue';
 import ContentNode from 'docc-render/components/DocumentationTopic/ContentNode.vue';
 import TopicLinkBlockIcon from 'docc-render/components/DocumentationTopic/TopicLinkBlockIcon.vue';
 import DecoratedTopicTitle from 'docc-render/components/DocumentationTopic/DecoratedTopicTitle.vue';
-import ConditionalConstraints from 'docc-render/components/DocumentationTopic/ConditionalConstraints.vue';
+import ConditionalConstraints
+  from 'docc-render/components/DocumentationTopic/ConditionalConstraints.vue';
 import RequirementMetadata
 
   from 'docc-render/components/DocumentationTopic/Description/RequirementMetadata.vue';
@@ -98,7 +103,7 @@ export default {
     RequirementMetadata,
     ConditionalConstraints,
   },
-  inject: ['store'],
+  inject: ['store', 'references'],
   mixins: [getAPIChanges, APIChangesMultipleLines],
   constants: {
     ReferenceType,
@@ -208,6 +213,10 @@ export default {
     ),
     // pick only the first available tag
     tags: ({ topic }) => (topic.tags || []).slice(0, 1),
+    iconOverride: ({ topic: { images = [] } }) => {
+      const icon = images.find(({ type }) => type === 'icon');
+      return icon ? icon.identifier : null;
+    },
   },
 };
 </script>
diff --git a/tests/unit/components/DocumentationTopic/TopicLinkBlockIcon.spec.js b/tests/unit/components/DocumentationTopic/TopicLinkBlockIcon.spec.js
new file mode 100644
index 000000000..746192be4
--- /dev/null
+++ b/tests/unit/components/DocumentationTopic/TopicLinkBlockIcon.spec.js
@@ -0,0 +1,64 @@
+/**
+ * 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
+*/
+
+import TopicLinkBlockIcon from '@/components/DocumentationTopic/TopicLinkBlockIcon.vue';
+import { shallowMount } from '@vue/test-utils';
+import { TopicRole } from '@/constants/roles';
+import ArticleIcon from '@/components/Icons/ArticleIcon.vue';
+import SVGIcon from '@/components/SVGIcon.vue';
+
+const defaultProps = {
+  role: TopicRole.article,
+};
+
+const createWrapper = ({ propsData, ...others } = {}) => shallowMount(TopicLinkBlockIcon, {
+  propsData: {
+    ...defaultProps,
+    ...propsData,
+  },
+  ...others,
+});
+
+describe('TopicLinkBlockIcon', () => {
+  it('renders an icon from a `role`', () => {
+    const wrapper = createWrapper();
+    expect(wrapper.find('.topic-icon').is(ArticleIcon)).toBe(true);
+  });
+
+  it('renders an override icon from an image override', () => {
+    const wrapper = createWrapper({
+      propsData: {
+        imageOverride: {
+          variants: [{
+            url: '/foo/bar',
+            svgID: 'foo',
+          }],
+        },
+      },
+    });
+    const icon = wrapper.find('.topic-icon');
+    expect(icon.is(ArticleIcon)).toBe(false);
+    expect(icon.is(SVGIcon)).toBe(true);
+    expect(icon.props()).toMatchObject({
+      iconUrl: '/foo/bar',
+      themeId: 'foo',
+    });
+  });
+
+  it('renders nothing if no role or image override', () => {
+    const wrapper = createWrapper({
+      propsData: {
+        imageOverride: null,
+        role: TopicRole.devLink, // no icon for this
+      },
+    });
+    expect(wrapper.html()).toBeFalsy();
+  });
+});
diff --git a/tests/unit/components/DocumentationTopic/TopicsLinkBlock.spec.js b/tests/unit/components/DocumentationTopic/TopicsLinkBlock.spec.js
index f3047f36d..c4f9c355e 100644
--- a/tests/unit/components/DocumentationTopic/TopicsLinkBlock.spec.js
+++ b/tests/unit/components/DocumentationTopic/TopicsLinkBlock.spec.js
@@ -42,8 +42,18 @@ describe('TopicsLinkBlock', () => {
     },
   };
 
+  const iconOverride = {
+    type: 'icon',
+    identifier: 'icon-override',
+  };
+
+  const references = {
+    [iconOverride.identifier]: { foo: 'bar' },
+  };
+
   const provide = {
     store,
+    references,
   };
 
   const propsData = {
@@ -126,6 +136,18 @@ describe('TopicsLinkBlock', () => {
     expect(link.props('role')).toBe(propsData.topic.role);
   });
 
+  it('renders a TopicLinkBlockIcon with an override', () => {
+    const icon = wrapper.find(TopicLinkBlockIcon);
+    expect(icon.props('imageOverride')).toBe(null);
+    wrapper.setProps({
+      topic: {
+        ...propsData.topic,
+        images: [iconOverride, { type: 'card', identifier: 'foo' }],
+      },
+    });
+    expect(icon.props('imageOverride')).toBe(references[iconOverride.identifier]);
+  });
+
   it('renders a normal `WordBreak` for the link text', () => {
     const wordBreak = wrapper.find('.link').find(WordBreak);
     expect(wordBreak.exists()).toBe(true);

From aebfb1f71d196151fa3e425e90e45dff205f4c5a Mon Sep 17 00:00:00 2001
From: Dobromir Hristov <dhristov@apple.com>
Date: Tue, 13 Sep 2022 13:32:37 +0300
Subject: [PATCH 8/8] refactor: extract away repeated logic

---
 .../DocumentationTopic/TopicLinkBlockIcon.vue | 35 ++++----
 src/components/IconOverrideProvider.vue       | 35 ++++++++
 src/components/TopicTypeIcon.vue              | 45 +++++------
 .../TopicLinkBlockIcon.spec.js                |  4 +-
 .../components/IconOverrideProvider.spec.js   | 81 +++++++++++++++++++
 tests/unit/components/TopicTypeIcon.spec.js   |  5 +-
 6 files changed, 158 insertions(+), 47 deletions(-)
 create mode 100644 src/components/IconOverrideProvider.vue
 create mode 100644 tests/unit/components/IconOverrideProvider.spec.js

diff --git a/src/components/DocumentationTopic/TopicLinkBlockIcon.vue b/src/components/DocumentationTopic/TopicLinkBlockIcon.vue
index 21050df4f..65277e4c1 100644
--- a/src/components/DocumentationTopic/TopicLinkBlockIcon.vue
+++ b/src/components/DocumentationTopic/TopicLinkBlockIcon.vue
@@ -9,15 +9,19 @@
 -->
 
 <template>
-  <div class="topic-icon-wrapper" v-if="icon || shouldShowImageOverride">
-    <SVGIcon
-      v-if="shouldShowImageOverride"
-      :icon-url="imageOverridePath"
-      :theme-id="imageOverrideId"
-      class="topic-icon"
-    />
-    <component v-else :is="icon" class="topic-icon" />
-  </div>
+  <IconOverrideProvider
+    :imageOverride="imageOverride"
+    #default="{ shouldUseOverride, themeId, iconUrl }"
+  >
+    <div class="topic-icon-wrapper" v-if="icon || shouldUseOverride">
+      <SVGIcon
+        v-if="shouldUseOverride"
+        v-bind="{ themeId, iconUrl }"
+        class="topic-icon"
+      />
+      <component v-else :is="icon" class="topic-icon" />
+    </div>
+  </IconOverrideProvider>
 </template>
 
 <script>
@@ -29,6 +33,7 @@ import PathIcon from 'theme/components/Icons/PathIcon.vue';
 import TutorialIcon from 'theme/components/Icons/TutorialIcon.vue';
 import SVGIcon from 'docc-render/components/SVGIcon.vue';
 import { TopicRole } from 'docc-render/constants/roles';
+import IconOverrideProvider from 'docc-render/components/IconOverrideProvider.vue';
 
 const TopicRoleIcons = {
   [TopicRole.article]: ArticleIcon,
@@ -43,7 +48,7 @@ const TopicRoleIcons = {
 };
 
 export default {
-  components: { SVGIcon },
+  components: { IconOverrideProvider, SVGIcon },
   props: {
     role: {
       type: String,
@@ -57,16 +62,6 @@ export default {
 
   computed: {
     icon: ({ role }) => TopicRoleIcons[role],
-    imageOverrideVariant: ({ imageOverride }) => {
-      if (!imageOverride) return null;
-      return imageOverride.variants[0];
-    },
-    imageOverridePath: ({ imageOverrideVariant }) => imageOverrideVariant && imageOverrideVariant.url,
-    imageOverrideId: ({ imageOverrideVariant }) => imageOverrideVariant && imageOverrideVariant.svgID,
-    shouldShowImageOverride: ({
-      imageOverridePath,
-      imageOverrideId,
-    }) => imageOverridePath && imageOverrideId,
   },
 };
 </script>
diff --git a/src/components/IconOverrideProvider.vue b/src/components/IconOverrideProvider.vue
new file mode 100644
index 000000000..0d23bf57d
--- /dev/null
+++ b/src/components/IconOverrideProvider.vue
@@ -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
+-->
+
+<script>
+export default {
+  name: 'IconOverrideProvider',
+  props: {
+    imageOverride: {
+      type: Object,
+      default: null,
+    },
+  },
+  computed: {
+    imageOverrideVariant: ({ imageOverride }) => (imageOverride ? imageOverride.variants[0] : null),
+    iconUrl: ({ imageOverrideVariant }) => imageOverrideVariant && imageOverrideVariant.url,
+    themeId: ({ imageOverrideVariant }) => imageOverrideVariant && imageOverrideVariant.svgID,
+    shouldUseOverride: ({ iconUrl, themeId }) => !!(iconUrl && themeId),
+  },
+  render() {
+    const { shouldUseOverride, iconUrl, themeId } = this;
+    return this.$scopedSlots.default({
+      shouldUseOverride,
+      iconUrl,
+      themeId,
+    });
+  },
+};
+</script>
diff --git a/src/components/TopicTypeIcon.vue b/src/components/TopicTypeIcon.vue
index a27e2d1c1..686c013a6 100644
--- a/src/components/TopicTypeIcon.vue
+++ b/src/components/TopicTypeIcon.vue
@@ -9,22 +9,26 @@
 -->
 
 <template>
-  <div class="TopicTypeIcon">
-    <SVGIcon
-      v-if="imageOverridePath && imageOverrideId"
-      :icon-url="imageOverridePath"
-      :theme-id="imageOverrideId"
-      :style="styles"
-      class="icon-inline"
-    />
-    <component
-      v-else
-      :is="icon"
-      v-bind="iconProps"
-      :style="styles"
-      class="icon-inline"
-    />
-  </div>
+  <IconOverrideProvider
+    :imageOverride="imageOverride"
+    #default="{ shouldUseOverride, themeId, iconUrl }"
+  >
+    <div class="TopicTypeIcon">
+      <SVGIcon
+        v-if="shouldUseOverride"
+        v-bind="{ themeId, iconUrl }"
+        :style="styles"
+        class="icon-inline"
+      />
+      <component
+        v-else
+        :is="icon"
+        v-bind="iconProps"
+        :style="styles"
+        class="icon-inline"
+      />
+    </div>
+  </IconOverrideProvider>
 </template>
 
 <script>
@@ -42,6 +46,7 @@ import SingleLetterSymbolIcon from 'theme/components/Icons/SingleLetterSymbolIco
 import { TopicTypes, TopicTypeAliases } from 'docc-render/constants/TopicTypes';
 import { HeroColorsMap } from 'docc-render/constants/HeroColors';
 import SVGIcon from 'docc-render/components/SVGIcon.vue';
+import IconOverrideProvider from 'docc-render/components/IconOverrideProvider.vue';
 
 const TopicTypeIcons = {
   [TopicTypes.article]: ArticleIcon,
@@ -95,7 +100,7 @@ const TopicTypeProps = {
 
 export default {
   name: 'TopicTypeIcon',
-  components: { SVGIcon, SingleLetterSymbolIcon },
+  components: { IconOverrideProvider, SVGIcon, SingleLetterSymbolIcon },
   constants: { TopicTypeIcons, TopicTypeProps },
   props: {
     type: {
@@ -116,12 +121,6 @@ export default {
     icon: ({ normalisedType }) => TopicTypeIcons[normalisedType] || CollectionIcon,
     iconProps: ({ normalisedType }) => TopicTypeProps[normalisedType] || {},
     color: ({ normalisedType }) => HeroColorsMap[normalisedType],
-    imageOverrideVariant: ({ imageOverride }) => {
-      if (!imageOverride) return null;
-      return imageOverride.variants[0];
-    },
-    imageOverridePath: ({ imageOverrideVariant }) => imageOverrideVariant && imageOverrideVariant.url,
-    imageOverrideId: ({ imageOverrideVariant }) => imageOverrideVariant && imageOverrideVariant.svgID,
     styles: ({
       color,
       withColors,
diff --git a/tests/unit/components/DocumentationTopic/TopicLinkBlockIcon.spec.js b/tests/unit/components/DocumentationTopic/TopicLinkBlockIcon.spec.js
index 746192be4..57f6b7e8f 100644
--- a/tests/unit/components/DocumentationTopic/TopicLinkBlockIcon.spec.js
+++ b/tests/unit/components/DocumentationTopic/TopicLinkBlockIcon.spec.js
@@ -9,7 +9,7 @@
 */
 
 import TopicLinkBlockIcon from '@/components/DocumentationTopic/TopicLinkBlockIcon.vue';
-import { shallowMount } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
 import { TopicRole } from '@/constants/roles';
 import ArticleIcon from '@/components/Icons/ArticleIcon.vue';
 import SVGIcon from '@/components/SVGIcon.vue';
@@ -18,7 +18,7 @@ const defaultProps = {
   role: TopicRole.article,
 };
 
-const createWrapper = ({ propsData, ...others } = {}) => shallowMount(TopicLinkBlockIcon, {
+const createWrapper = ({ propsData, ...others } = {}) => mount(TopicLinkBlockIcon, {
   propsData: {
     ...defaultProps,
     ...propsData,
diff --git a/tests/unit/components/IconOverrideProvider.spec.js b/tests/unit/components/IconOverrideProvider.spec.js
new file mode 100644
index 000000000..9b36593fd
--- /dev/null
+++ b/tests/unit/components/IconOverrideProvider.spec.js
@@ -0,0 +1,81 @@
+/**
+ * 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 IconOverrideProvider from '@/components/IconOverrideProvider.vue';
+import { shallowMount } from '@vue/test-utils';
+
+const variant = {
+  url: '/foo/bar',
+  svgID: 'baz',
+};
+
+const variantWithoutId = {
+  url: '/baz/bar',
+};
+
+const defaultProps = {
+  imageOverride: {
+    variants: [variant, variantWithoutId],
+  },
+};
+let slotProps = null;
+const createWrapper = ({ propsData, ...others } = {}) => shallowMount(IconOverrideProvider, {
+  propsData: {
+    ...defaultProps,
+    ...propsData,
+  },
+  scopedSlots: {
+    default(props) {
+      slotProps = props;
+      return this.$createElement('div', 'Default Slot');
+    },
+  },
+  ...others,
+});
+
+describe('IconOverrideProvider', () => {
+  it('provides data to the default scoped slot', () => {
+    const wrapper = createWrapper();
+    expect(wrapper.text()).toContain('Default Slot');
+    expect(slotProps).toEqual({
+      shouldUseOverride: true,
+      iconUrl: variant.url,
+      themeId: variant.svgID,
+    });
+  });
+
+  it('sets shouldUseOverride to `false`, if variant has no id', () => {
+    createWrapper({
+      propsData: {
+        imageOverride: {
+          variants: [variantWithoutId],
+        },
+      },
+    });
+    expect(slotProps).toEqual({
+      shouldUseOverride: false,
+      iconUrl: variantWithoutId.url,
+      themeId: undefined,
+    });
+  });
+
+  it('sets shouldUseOverride to `false`, if no override passed', () => {
+    createWrapper({
+      propsData: {
+        imageOverride: null,
+      },
+    });
+    expect(slotProps).toEqual({
+      shouldUseOverride: false,
+      iconUrl: null,
+      themeId: null,
+    });
+  });
+});
diff --git a/tests/unit/components/TopicTypeIcon.spec.js b/tests/unit/components/TopicTypeIcon.spec.js
index f6615369f..8ae4eb3af 100644
--- a/tests/unit/components/TopicTypeIcon.spec.js
+++ b/tests/unit/components/TopicTypeIcon.spec.js
@@ -9,13 +9,14 @@
 */
 
 import TopicTypeIcon from 'docc-render/components/TopicTypeIcon.vue';
-import { shallowMount } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
 import { TopicTypes, TopicTypeAliases } from '@/constants/TopicTypes';
 import { HeroColorsMap } from 'docc-render/constants/HeroColors';
 import CollectionIcon from '@/components/Icons/CollectionIcon.vue';
 import SVGIcon from '@/components/SVGIcon.vue';
 
-const createWrapper = opts => shallowMount(TopicTypeIcon, opts);
+const createWrapper = opts => mount(TopicTypeIcon, opts);
+
 const {
   TopicTypeIcons,
   TopicTypeProps,