feat: add support for @TopicsVisualStyle

Author: Dobromir Hristov

src/components/DocumentationTopic.vue

@@ -71,10 +71,11 @@
         />
       </div>
       <Topics
-        v-if="topicSections"
+        v-if="shouldRenderTopicSection"
         :sections="topicSections"
         :isSymbolDeprecated="isSymbolDeprecated"
         :isSymbolBeta="isSymbolBeta"
+        :topicStyle="topicSectionsStyle"
       />
       <DefaultImplementations
         v-if="defaultImplementationsSections"
@@ -106,6 +107,7 @@ import BetaLegalText from 'theme/components/DocumentationTopic/BetaLegalText.vue
 import LanguageSwitcher from 'theme/components/DocumentationTopic/Summary/LanguageSwitcher.vue';
 import DocumentationHero from 'docc-render/components/DocumentationTopic/DocumentationHero.vue';
 import WordBreak from 'docc-render/components/WordBreak.vue';
+import { TopicStyles } from 'docc-render/constants/TopicStyles';
 import Abstract from './DocumentationTopic/Description/Abstract.vue';
 import ContentNode from './DocumentationTopic/ContentNode.vue';
 import CallToActionButton from './CallToActionButton.vue';
@@ -227,6 +229,10 @@ export default {
       type: Array,
       required: false,
     },
+    topicSectionsStyle: {
+      type: String,
+      default: TopicStyles.list,
+    },
     sampleCodeDownload: {
       type: Object,
       required: false,
@@ -355,6 +361,10 @@ export default {
       || (primaryContentSections && primaryContentSections.length)
     ),
     tagName: ({ isSymbolDeprecated }) => (isSymbolDeprecated ? 'Deprecated' : 'Beta'),
+    shouldRenderTopicSection: ({
+      topicSectionsStyle,
+      topicSections,
+    }) => topicSections && topicSectionsStyle !== TopicStyles.hidden,
   },
   methods: {
     normalizePath(path) {

src/components/DocumentationTopic/Topics.vue

@@ -10,24 +10,39 @@
 
 <template>
   <TopicsTable
+    v-if="shouldRenderList"
     anchor="topics"
     title="Topics"
     :isSymbolDeprecated="isSymbolDeprecated"
     :isSymbolBeta="isSymbolBeta"
     :sections="sections"
   />
+  <TopicsGrid
+    v-else
+    :sections="sections"
+    :topicStyle="topicStyle"
+  />
 </template>
 
 <script>
+import { TopicStyles } from 'docc-render/constants/TopicStyles';
+import TopicsGrid from './TopicsGrid.vue';
 import TopicsTable from './TopicsTable.vue';
 
 export default {
   name: 'Topics',
-  components: { TopicsTable },
+  components: { TopicsGrid, TopicsTable },
   props: {
     isSymbolDeprecated: Boolean,
     isSymbolBeta: Boolean,
     sections: TopicsTable.props.sections,
+    topicStyle: {
+      type: String,
+      required: true,
+    },
+  },
+  computed: {
+    shouldRenderList: ({ topicStyle }) => topicStyle === TopicStyles.list,
   },
 };
 </script>

src/components/DocumentationTopic/TopicsGrid.vue

@@ -0,0 +1,70 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2022 Apple Inc. and the Swift project authors
+  Licensed under Apache License v2.0 with Runtime Library Exception
+
+  See https://swift.org/LICENSE.txt for license information
+  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+<template>
+  <div class="TopicsGrid">
+    <OnThisPageSection
+      v-for="(section, i) in sections"
+      :key="i"
+      :title="section.title || ''"
+      :anchor="anchorize(section.title || '')"
+      :level="3"
+      class="topic-grid"
+    >
+      <div class="container">
+        <h3 class="title" v-if="section.title">
+          {{ section.title }}
+        </h3>
+        <TopicsLinkCardGrid :identifiers="section.identifiers" :topicStyle="topicStyle" />
+      </div>
+    </OnThisPageSection>
+  </div>
+</template>
+
+<script>
+import { anchorize } from 'docc-render/utils/strings';
+
+import TopicsLinkCardGrid from 'docc-render/components/DocumentationTopic/TopicsLinkCardGrid.vue';
+import OnThisPageSection from 'docc-render/components/DocumentationTopic/OnThisPageSection.vue';
+
+export default {
+  name: 'TopicsGrid',
+  components: { OnThisPageSection, TopicsLinkCardGrid },
+  props: {
+    sections: {
+      type: Array,
+      required: true,
+    },
+    topicStyle: {
+      type: String,
+      required: true,
+    },
+  },
+  methods: {
+    anchorize,
+  },
+};
+</script>
+
+<style scoped lang='scss'>
+@import 'docc-render/styles/_core.scss';
+
+.container {
+  @include dynamic-content-container
+}
+
+.title {
+  @include font-styles(label);
+}
+
+.topic-grid + .topic-grid {
+  margin-top: $stacked-margin-large;
+}
+</style>

src/components/DocumentationTopic/TopicsLinkCardGrid.vue

@@ -0,0 +1,59 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2022 Apple Inc. and the Swift project authors
+  Licensed under Apache License v2.0 with Runtime Library Exception
+
+  See https://swift.org/LICENSE.txt for license information
+  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+<template>
+  <div class="TopicsLinkCardGrid">
+    <Grid :columns="compactCards ? 3 : 2">
+      <Column
+        v-for="(item, index) in items"
+        :key="index"
+      >
+        <TopicsLinkCardGridItem :item="item" :compact="compactCards" />
+      </Column>
+    </Grid>
+  </div>
+</template>
+
+<script>
+import Grid from 'docc-render/components/ContentNode/Grid.vue';
+import Column from 'docc-render/components/ContentNode/Column.vue';
+import { TopicStyles } from 'docc-render/constants/TopicStyles';
+import TopicsLinkCardGridItem from './TopicsLinkCardGridItem.vue';
+
+export default {
+  name: 'TopicsLinkCardGrid',
+  components: { TopicsLinkCardGridItem, Column, Grid },
+  inject: ['references'],
+  props: {
+    identifiers: {
+      type: Array,
+      required: true,
+    },
+    topicStyle: {
+      type: String,
+      default: TopicStyles.compactGrid,
+    },
+  },
+  computed: {
+    items() {
+      return this.identifiers.map(i => this.references[i]);
+    },
+    compactCards: ({ topicStyle }) => topicStyle === TopicStyles.compactGrid,
+  },
+};
+</script>
+
+<style scoped lang='scss'>
+@import '@/styles/_core.scss';
+
+.grid {
+  grid-gap: 20px;
+}
+</style>

src/components/DocumentationTopic/TopicsLinkCardGridItem.vue

@@ -0,0 +1,79 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2022 Apple Inc. and the Swift project authors
+  Licensed under Apache License v2.0 with Runtime Library Exception
+
+  See https://swift.org/LICENSE.txt for license information
+  See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+-->
+
+<template>
+  <Card
+    class="reference-card-grid-item"
+    :url="item.url"
+    :image="imageReferences.card"
+    :title="item.title"
+    :content="compact ? []: item.abstract"
+    floating-style
+    :size="compact ? undefined: 'large'"
+    :link-text="compact? '': 'Visit page'"
+  >
+    <template #cover="{ classes }" v-if="!imageReferences.card">
+      <div :class="classes" class="reference-card-grid-item__image">
+        <TopicTypeIcon
+          :type="item.role"
+          :image-override="references[imageReferences.icon]"
+          class="reference-card-grid-item__icon"
+        />
+      </div>
+    </template>
+  </Card>
+</template>
+
+<script>
+import Card from 'docc-render/components/Card.vue';
+import TopicTypeIcon from 'docc-render/components/TopicTypeIcon.vue';
+
+export default {
+  name: 'TopicsLinkCardGridItem',
+  components: { TopicTypeIcon, Card },
+  inject: ['references'],
+  props: {
+    item: {
+      type: Object,
+      required: true,
+    },
+    compact: {
+      type: Boolean,
+      default: true,
+    },
+  },
+  computed: {
+    imageReferences: ({ item }) => (item.images || []).reduce((all, current) => {
+      // eslint-disable-next-line no-param-reassign
+      all[current.type] = current.reference;
+      return all;
+    }, { icon: null, card: null }),
+  },
+};
+</script>
+
+<style scoped lang='scss'>
+@import 'docc-render/styles/_core.scss';
+
+.reference-card-grid-item {
+  &__image {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 80px;
+    background-color: var(--color-fill-gray-quaternary);
+  }
+
+  &__icon {
+    display: flex;
+    margin: 0;
+  }
+}
+</style>

src/constants/TopicStyles.js

@@ -0,0 +1,17 @@
+/**
+ * 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
+*/
+
+/* eslint-disable import/prefer-default-export */
+export const TopicStyles = {
+  list: 'list',
+  compactGrid: 'compactGrid',
+  detailedGrid: 'detailedGrid',
+  hidden: 'hidden',
+};

src/views/DocumentationTopic.vue

@@ -186,6 +186,7 @@ export default {
         relationshipsSections,
         references = {},
         sampleCodeDownload,
+        topicSectionsStyle,
         topicSections,
         seeAlsoSections,
         variantOverrides,
@@ -211,6 +212,7 @@ export default {
         sampleCodeDownload,
         title,
         topicSections,
+        topicSectionsStyle,
         seeAlsoSections,
         variantOverrides,
         symbolKind,

tests/unit/components/DocumentationTopic.spec.js

@@ -13,6 +13,7 @@ import DocumentationTopic from 'docc-render/components/DocumentationTopic.vue';
 import Language from 'docc-render/constants/Language';
 import { TopicTypes } from '@/constants/TopicTypes';
 import DocumentationHero from '@/components/DocumentationTopic/DocumentationHero.vue';
+import { TopicStyles } from '@/constants/TopicStyles';
 
 const {
   Abstract,
@@ -445,7 +446,7 @@ describe('DocumentationTopic', () => {
     });
   });
 
-  it('renders `Topics` if there are topic sections', () => {
+  it('renders `Topics` if there are topic sections, passing the `topicSectionStyles` over', () => {
     expect(wrapper.contains(Topics)).toBe(false);
 
     const topicSections = [
@@ -461,11 +462,23 @@ describe('DocumentationTopic', () => {
         identifiers: ['baz'],
       },
     ];
-    wrapper.setProps({ topicSections });
+    wrapper.setProps({ topicSections, topicSectionsStyle: TopicStyles.detailedGrid });
 
     const topics = wrapper.find(Topics);
     expect(topics.exists()).toBe(true);
     expect(topics.props('sections')).toBe(topicSections);
+    expect(topics.props('topicStyle')).toBe(TopicStyles.detailedGrid);
+  });
+
+  it('does not render the `Topics` if the `topicSectionsStyle` is `hidden`', () => {
+    const topicSections = [
+      {
+        title: 'Baz',
+        identifiers: ['baz'],
+      },
+    ];
+    wrapper.setProps({ topicSections, topicSectionsStyle: 'hidden' });
+    expect(wrapper.find(Topics).exists()).toBe(false);
   });
 
   it('renders `SeeAlso` if there are see also sections', () => {