Add support for @TopicsVisualStyle (#419)

closes rdar://97716047

Author: Dobromir Hristov

src/components/DocumentationTopic.vue

@@ -73,10 +73,11 @@
             />
           </div>
           <Topics
-            v-if="topicSections"
+            v-if="shouldRenderTopicSection"
             :sections="topicSections"
             :isSymbolDeprecated="isSymbolDeprecated"
             :isSymbolBeta="isSymbolBeta"
+            :topicStyle="topicSectionsStyle"
           />
           <DefaultImplementations
             v-if="defaultImplementationsSections"
@@ -113,6 +114,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 { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
 import OnThisPageNav from 'theme/components/OnThisPageNav.vue';
 import Abstract from './DocumentationTopic/Description/Abstract.vue';
 import ContentNode from './DocumentationTopic/ContentNode.vue';
@@ -238,6 +240,10 @@ export default {
       type: Array,
       required: false,
     },
+    topicSectionsStyle: {
+      type: String,
+      default: TopicSectionsStyle.list,
+    },
     sampleCodeDownload: {
       type: Object,
       required: false,
@@ -376,6 +382,10 @@ export default {
       const icon = pageImages.find(({ type }) => type === 'icon');
       return icon ? icon.identifier : null;
     },
+    shouldRenderTopicSection: ({
+      topicSectionsStyle,
+      topicSections,
+    }) => topicSections && topicSectionsStyle !== TopicSectionsStyle.hidden,
   },
   methods: {
     normalizePath(path) {

src/components/DocumentationTopic/ContentTableSection.vue

@@ -11,10 +11,10 @@
 <template>
   <div class="contenttable-section">
     <div class="section-title">
-      <slot name="title">
+      <slot name="title" :className="className">
         <LinkableHeading
           :level="3"
-          class="title"
+          :class="className"
           :anchor="anchorComputed"
           :register-on-this-page="false"
         >{{ title }}</LinkableHeading>
@@ -32,6 +32,8 @@
 import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 import { anchorize } from 'docc-render/utils/strings';
 
+export const TITLE_CLASS_NAME = 'contenttable-title';
+
 export default {
   name: 'ContentTableSection',
   components: { LinkableHeading },
@@ -47,6 +49,7 @@ export default {
   },
   computed: {
     anchorComputed: ({ title, anchor }) => anchor || anchorize(title),
+    className: () => TITLE_CLASS_NAME,
   },
 };
 </script>
@@ -67,7 +70,7 @@ export default {
   }
 }
 
-/deep/ .title {
+/deep/ .contenttable-title {
   @include font-styles(label);
 }
 
@@ -86,7 +89,7 @@ export default {
     }
   }
 
-  /deep/ .title {
+  /deep/ .contenttable-title {
     margin: 0 0 $contenttable-spacing-single-side 0;
     padding-bottom: 0.5rem;
   }

src/components/DocumentationTopic/Topics.vue

@@ -15,10 +15,12 @@
     :isSymbolDeprecated="isSymbolDeprecated"
     :isSymbolBeta="isSymbolBeta"
     :sections="sections"
+    :topicStyle="topicStyle"
   />
 </template>
 
 <script>
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
 import TopicsTable from './TopicsTable.vue';
 
 export default {
@@ -28,6 +30,11 @@ export default {
     isSymbolDeprecated: Boolean,
     isSymbolBeta: Boolean,
     sections: TopicsTable.props.sections,
+    topicStyle: {
+      type: String,
+      required: true,
+      validator: v => Object.hasOwnProperty.call(TopicSectionsStyle, v),
+    },
   },
 };
 </script>

src/components/DocumentationTopic/TopicsLinkCardGrid.vue

@@ -0,0 +1,48 @@
+<!--
+  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">
+    <Row :columns="compactCards ? 3 : 2">
+      <Column
+        v-for="item in items"
+        :key="item.title"
+      >
+        <TopicsLinkCardGridItem :item="item" :compact="compactCards" />
+      </Column>
+    </Row>
+  </div>
+</template>
+
+<script>
+import Row from 'docc-render/components/ContentNode/Row.vue';
+import Column from 'docc-render/components/ContentNode/Column.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
+import TopicsLinkCardGridItem from './TopicsLinkCardGridItem.vue';
+
+export default {
+  name: 'TopicsLinkCardGrid',
+  components: { TopicsLinkCardGridItem, Column, Row },
+  props: {
+    items: {
+      type: Array,
+      required: true,
+    },
+    topicStyle: {
+      type: String,
+      default: TopicSectionsStyle.compactGrid,
+      validator: v => v === TopicSectionsStyle.compactGrid || v === TopicSectionsStyle.detailedGrid,
+    },
+  },
+  computed: {
+    compactCards: ({ topicStyle }) => topicStyle === TopicSectionsStyle.compactGrid,
+  },
+};
+</script>

src/components/DocumentationTopic/TopicsLinkCardGridItem.vue

@@ -0,0 +1,95 @@
+<!--
+  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"
+    floating-style
+    :size="cardSize"
+    :link-text="linkText"
+  >
+    <template v-if="!imageReferences.card" #cover="{ classes }">
+      <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>
+    <ContentNode v-if="!compact" :content="item.abstract" />
+  </Card>
+</template>
+
+<script>
+import Card from 'docc-render/components/Card.vue';
+import TopicTypeIcon from 'docc-render/components/TopicTypeIcon.vue';
+import { TopicRole } from 'docc-render/constants/roles';
+import CardSize from 'docc-render/constants/CardSize';
+
+export const ROLE_LINK_TEXT = {
+  [TopicRole.article]: 'Read article',
+  [TopicRole.overview]: 'Start tutorial',
+  [TopicRole.collection]: 'View API collection',
+  [TopicRole.symbol]: 'View symbol',
+  [TopicRole.sampleCode]: 'View sample code',
+};
+
+export default {
+  name: 'TopicsLinkCardGridItem',
+  components: {
+    TopicTypeIcon,
+    Card,
+    ContentNode: () => import('docc-render/components/ContentNode.vue'),
+  },
+  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.identifier;
+      return all;
+    }, { icon: null, card: null }),
+    linkText: ({ compact, item }) => (compact ? '' : (ROLE_LINK_TEXT[item.role] || 'Learn more')),
+    cardSize: ({ compact }) => (compact ? undefined : CardSize.large),
+  },
+};
+</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/components/DocumentationTopic/TopicsTable.vue

@@ -16,11 +16,11 @@
       :title="section.title"
       :anchor="section.anchor"
     >
-      <template v-if="wrapTitle" slot="title">
+      <template v-if="wrapTitle" #title="{ className }">
         <LinkableHeading
           :level="3"
           :anchor="section.anchor"
-          class="title"
+          :class="className"
           :register-on-this-page="false"
         >
           <WordBreak>{{ section.title }}</WordBreak>
@@ -32,13 +32,21 @@
       <template v-if="section.discussion" slot="discussion">
         <ContentNode :content="section.discussion.content" />
       </template>
-      <TopicsLinkBlock
-        v-for="topic in section.topics"
+      <template v-if="shouldRenderList">
+        <TopicsLinkBlock
+          v-for="topic in section.topics"
+          class="topic"
+          :key="topic.identifier"
+          :topic="topic"
+          :isSymbolDeprecated="isSymbolDeprecated"
+          :isSymbolBeta="isSymbolBeta"
+        />
+      </template>
+      <TopicsLinkCardGrid
+        v-else
+        :items="section.topics"
+        :topicStyle="topicStyle"
         class="topic"
-        :key="topic.identifier"
-        :topic="topic"
-        :isSymbolDeprecated="isSymbolDeprecated"
-        :isSymbolBeta="isSymbolBeta"
       />
     </ContentTableSection>
   </ContentTable>
@@ -47,6 +55,8 @@
 <script>
 import ContentNode from 'docc-render/components/DocumentationTopic/ContentNode.vue';
 import WordBreak from 'docc-render/components/WordBreak.vue';
+import { TopicSectionsStyle } from '@/constants/TopicSectionsStyle';
+import TopicsLinkCardGrid from 'docc-render/components/DocumentationTopic/TopicsLinkCardGrid.vue';
 import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 import ContentTable from './ContentTable.vue';
 import ContentTableSection from './ContentTableSection.vue';
@@ -62,6 +72,7 @@ export default {
     },
   },
   components: {
+    TopicsLinkCardGrid,
     WordBreak,
     ContentTable,
     TopicsLinkBlock,
@@ -94,8 +105,13 @@ export default {
       type: Boolean,
       default: false,
     },
+    topicStyle: {
+      type: String,
+      default: TopicSectionsStyle.list,
+    },
   },
   computed: {
+    shouldRenderList: ({ topicStyle }) => topicStyle === TopicSectionsStyle.list,
     sectionsWithTopics() {
       return this.sections.map(section => ({
         ...section,

src/constants/TopicSectionsStyle.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 TopicSectionsStyle = {
+  list: 'list',
+  compactGrid: 'compactGrid',
+  detailedGrid: 'detailedGrid',
+  hidden: 'hidden',
+};

src/views/DocumentationTopic.vue

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