Add support for DocC @tabNavigator (#403)

closes rdar://97714987

Author: Dobromir Hristov

src/components/ContentNode.vue

@@ -25,6 +25,7 @@ import Small from './ContentNode/Small.vue';
 import BlockVideo from './ContentNode/BlockVideo.vue';
 import Column from './ContentNode/Column.vue';
 import Row from './ContentNode/Row.vue';
+import TabNavigator from './ContentNode/TabNavigator.vue';
 
 const BlockType = {
   aside: 'aside',
@@ -40,6 +41,7 @@ const BlockType = {
   small: 'small',
   video: 'video',
   row: 'row',
+  tabNavigator: 'tabNavigator',
 };
 
 const InlineType = {
@@ -93,6 +95,9 @@ const TableHeaderStyle = {
   row: 'row',
 };
 
+// The point after which a TabNavigator turns to vertical mode.
+const TabNavigatorVerticalThreshold = 5;
+
 // Recursively call the passed `createElement` function for each content node
 // and any of its children by mapping each node `type` to a given Vue component
 //
@@ -311,6 +316,22 @@ function renderNode(createElement, references) {
         )),
       );
     }
+    case BlockType.tabNavigator: {
+      // If the tabs count is more than the threshold, use vertical tabs instead.
+      const vertical = node.tabs.length > TabNavigatorVerticalThreshold;
+      const titles = node.tabs.map(tab => tab.title);
+      const scopedSlots = node.tabs.reduce((slots, tab) => ({
+        ...slots,
+        [tab.title]: () => renderChildren(tab.content),
+      }), {});
+      return createElement(TabNavigator, {
+        props: {
+          titles,
+          vertical,
+        },
+        scopedSlots,
+      });
+    }
     case InlineType.codeVoice:
       return createElement(CodeVoice, {}, (
         node.code

src/components/ContentNode/TabNavigator.vue

@@ -0,0 +1,109 @@
+<!--
+  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="TabNavigator"
+    :class="[{ 'tabs--vertical': vertical }]"
+  >
+    <Tabnav v-model="currentTitle" v-bind="{ position, vertical }">
+      <TabnavItem v-for="title in titles" :key="title" :value="title">
+        {{ title }}
+      </TabnavItem>
+    </Tabnav>
+    <div class="tabs-content">
+      <template v-for="title in titles">
+        <slot v-if="title === currentTitle" :name="title" />
+      </template>
+    </div>
+  </div>
+</template>
+
+<script>
+import Tabnav from 'docc-render/components/Tabnav.vue';
+import TabnavItem from 'docc-render/components/TabnavItem.vue';
+
+/**
+ * Tab navigation component, that renders `ContentNode`,
+ * with ability to align the tabs horizontally and vertically to the start/center/end of the line.
+ * It can also flip the navigation, so it renders content first, navigation second,
+ * in both horizontal and vertical mode.
+ */
+export default {
+  name: 'TabNavigator',
+  components: {
+    TabnavItem,
+    Tabnav,
+  },
+  props: {
+    vertical: {
+      type: Boolean,
+      default: false,
+    },
+    position: {
+      type: String,
+      default: 'start',
+      validator: v => new Set(['start', 'center', 'end']).has(v),
+    },
+    titles: {
+      type: Array,
+      required: true,
+      default: () => [],
+    },
+  },
+  data() {
+    return {
+      currentTitle: this.titles[0],
+    };
+  },
+};
+</script>
+
+<style scoped lang='scss'>
+@import 'docc-render/styles/_core.scss';
+
+.TabNavigator {
+  margin-bottom: $stacked-margin-large;
+
+  .tabnav {
+    overflow: auto;
+    white-space: nowrap;
+  }
+}
+
+.tabs--vertical {
+  display: flex;
+  flex-flow: row-reverse;
+
+  @include breakpoint(small) {
+    flex-flow: column-reverse;
+  }
+
+  .tabnav {
+    width: 20%;
+    flex: 0 0 auto;
+    white-space: normal;
+    margin: 0;
+    @include breakpoint(small) {
+      width: 100%;
+    }
+  }
+
+  .tabs-content {
+    flex: 1 1 auto;
+    min-width: 0;
+    padding-right: $stacked-margin-large;
+    @include breakpoint(small) {
+      padding-right: 0;
+      padding-bottom: $stacked-margin-large;
+    }
+  }
+}
+</style>

src/components/Tabnav.vue

@@ -9,7 +9,10 @@
 -->
 
 <template>
-  <nav class="tabnav">
+  <nav
+    class="tabnav"
+    :class="{ [`tabnav--${position}`]: position, 'tabnav--vertical': vertical }"
+  >
     <ul class="tabnav-items">
       <slot />
     </ul>
@@ -35,8 +38,17 @@ export default {
     };
   },
   props: {
-    value: {
+    position: {
       type: String,
+      required: false,
+      validator: v => new Set(['start', 'center', 'end']).has(v),
+    },
+    vertical: {
+      type: Boolean,
+      default: false,
+    },
+    value: {
+      type: [String, Number],
       required: true,
     },
   },
@@ -56,10 +68,32 @@ $-tabnav-bottom-margin: rem(25px);
 
 .tabnav {
   margin: $-tabnav-top-margin 0 $-tabnav-bottom-margin 0;
+  display: flex;
+
+  &--center {
+    justify-content: center;
+  }
+
+  &--end {
+    justify-content: flex-end;
+  }
+
+  &--vertical {
+    flex-flow: column wrap;
+
+    .tabnav-items {
+      flex-flow: column;
+      overflow: hidden;
+    }
+
+    /deep/ .tabnav-item {
+      padding-left: 0;
+    }
+  }
 }
 
 .tabnav-items {
-  display: inline-block;
+  display: flex;
   margin: 0;
   text-align: center;
 }

src/components/TabnavItem.vue

@@ -14,6 +14,7 @@
       href="#"
       class="tabnav-link"
       :class="{ 'active': isActive }"
+      :aria-current="isActive ? 'true' : 'false'"
       @click.prevent="tabnavData.selectTab(value)"
     >
       <slot />
@@ -22,6 +23,7 @@
 </template>
 
 <script>
+
 export default {
   name: 'TabnavItem',
   inject: {
@@ -31,8 +33,8 @@ export default {
   },
   props: {
     value: {
-      type: String,
-      default: '',
+      type: [String, Number],
+      default: null,
     },
   },
   computed: {
@@ -46,15 +48,15 @@ export default {
 <style lang='scss' scoped>
 @import 'docc-render/styles/_core.scss';
 
-$tabnav-padding: 11px !default;
-$tabnav-bottom-border-margin: 4px !default;
+$tabnav-padding: 6px !default;
+$tabnav-margin: 4px !default;
 $tabnav-item-gutter: rem(30px);
 
 .tabnav-item {
   border-bottom: 1px solid;
   border-color: var(--colors-tabnav-item-border-color, var(--color-tabnav-item-border-color));
 
-  display: inline-block;
+  display: flex;
   list-style: none;
   padding-left: $tabnav-item-gutter;
   margin: 0;
@@ -71,19 +73,17 @@ $tabnav-item-gutter: rem(30px);
 }
 
 .tabnav-link {
-  $-tabnav-padding-focus-offset: 2px;
-  $-tabnav-padding-top: $tabnav-padding - $-tabnav-padding-focus-offset;
-
   color: var(--colors-secondary-label, var(--color-secondary-label));
   @include font-styles(tabnav-link);
-  padding: $-tabnav-padding-top 0 $tabnav-padding;
-  margin-top: $-tabnav-padding-focus-offset;
-  margin-bottom: $tabnav-bottom-border-margin;
+  padding: $tabnav-padding 0;
+  margin-top: $tabnav-margin;
+  margin-bottom: $tabnav-margin;
   text-align: left;
   text-decoration: none;
   display: block;
   position: relative;
   z-index: 0;
+  width: 100%;
 
   &:hover {
     text-decoration: none;
@@ -96,7 +96,7 @@ $tabnav-item-gutter: rem(30px);
   &:after {
     content: '';
     position: absolute;
-    bottom: -1 * ($tabnav-bottom-border-margin + 1);
+    bottom: -1 * ($tabnav-margin + 1);
     left: 0;
     width: 100%;
     border: 1px solid transparent;

src/styles/core/typography/_font-attributes.scss

@@ -71,8 +71,6 @@ $font-attributes: (
   // menu
   nav_12_12: (size: 12, line-height: 12),
   nav_14_14: (size: 14, line-height: 14),
-  // tabnav
-  tabnav_link_17_17: (size: 17, line-height: 17),
   // base dropdown
   form-default-text_17_21: (size: 17, line-height: 21),
   form-textbox-label-small_12_21: (size: 12, line-height: 21)

src/styles/core/typography/_font-styles.scss

@@ -172,7 +172,7 @@ $font-styles: (
     large: 17_25
   ),
   tabnav-link: (
-    large: tabnav_link_17_17
+    large: nav_14_14
   ),
   badge: (
     large: 12_16