Add anchor for section titles for quick sharing of sections (#408)

* [r96943502] chore: started adding anchor to titles

* [r96943502] feat: create SectionTitle component

* [r96943502] feat: add SectionTitle to more headings

* [r96943502] chore: make anchor optional for those that already have an anchor

* [r96943502] test: fix current tests

* [r96943502] test: add tests for SectionTitle component

* [r96943502] fix: TopicsTable component

* [r96943502] test: fix failing test

* [r96943502] fix: address feedback

* [r96943502] chore: it does not render anchor if target ide is true

* [r96943502] test: add new tests for scrollToElement

* [r96943502] fix: address feedback

* [r96943502] fix: prevent jumping issues

* [r96943502] fix: address feedback

* [r96943502] chore: delete extra anchors to avoid duplication of ids

* [r96943502] styles: [WIP] update UI

* [r96943502] styles: [WIP] update UI with link icon

* [r96943502] fix: address feedback

* [r96943502] fix: adding padding right to header anchor so icon does not dissapear when hovering on it

* [r96943502] chore: add aria label for AX

* [r94221573] chore: address design feedback + refactor vars

* [r94150776] fix: address feedback

Co-authored-by: Dobromir Hristov <[email protected]>

Author: marinaaisa

src/components/ContentNode.vue

@@ -11,6 +11,7 @@
 <script>
 import Aside from './ContentNode/Aside.vue';
 import CodeListing from './ContentNode/CodeListing.vue';
+import LinkableHeading from './ContentNode/LinkableHeading.vue';
 import CodeVoice from './ContentNode/CodeVoice.vue';
 import DictionaryExample from './ContentNode/DictionaryExample.vue';
 import EndpointExample from './ContentNode/EndpointExample.vue';
@@ -230,14 +231,13 @@ function renderNode(createElement, references) {
       };
       return createElement(EndpointExample, { props }, renderChildren(node.summary || []));
     }
-    case BlockType.heading:
-      return createElement(`h${node.level}`, {
-        attrs: {
-          id: node.anchor,
-        },
-      }, (
-        node.text
-      ));
+    case BlockType.heading: {
+      const props = {
+        anchor: node.anchor,
+        level: node.level,
+      };
+      return createElement(LinkableHeading, { props }, node.text);
+    }
     case BlockType.orderedList:
       return createElement('ol', {
         attrs: {

src/components/ContentNode/LinkableHeading.vue

@@ -0,0 +1,84 @@
+<!--
+  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>
+  <component
+   :id="anchor"
+   :is="`h${level}`"
+  >
+    <router-link
+      v-if="anchor && !isTargetIDE"
+      :to="{ hash: `#${anchor}` }"
+      class="header-anchor"
+      aria-label="Scroll to section"
+      @click="handleFocusAndScroll(anchor)"
+    >
+      <slot />
+      <LinkIcon class="icon" aria-hidden="true"/>
+    </router-link>
+    <template v-else>
+      <slot />
+    </template>
+  </component>
+</template>
+
+<script>
+import scrollToElement from 'docc-render/mixins/scrollToElement';
+import LinkIcon from 'theme/components/Icons/LinkIcon.vue';
+
+export default {
+  name: 'LinkableHeading',
+  mixins: [scrollToElement],
+  components: {
+    LinkIcon,
+  },
+  props: {
+    anchor: {
+      type: String,
+      required: false,
+    },
+    level: {
+      type: Number,
+      default: () => 2,
+      validator: v => v >= 1 && v <= 6,
+    },
+  },
+  inject: {
+    isTargetIDE: {
+      default: () => false,
+    },
+  },
+};
+</script>
+
+<style scoped lang="scss">
+@import 'docc-render/styles/_core.scss';
+$icon-margin: 7px;
+
+.header-anchor {
+  color: inherit;
+  text-decoration: none;
+  position: relative;
+  padding-right: $icon-size-default + $icon-margin;
+  display: inline-block;
+
+  .icon {
+    position: absolute;
+    bottom: .2em;
+    display: none;
+    height: $icon-size-default;
+    margin-left: $icon-margin;
+  }
+
+  &:hover .icon {
+    display: inline;
+  }
+}
+</style>

src/components/DocumentationTopic/ContentTable.vue

@@ -15,18 +15,19 @@
     :title="title"
   >
     <div class="container">
-      <h2 class="title">{{title}}</h2>
+      <LinkableHeading class="title" :anchor="anchor">{{ title }}</LinkableHeading>
       <slot />
     </div>
   </OnThisPageSection>
 </template>
 
 <script>
+import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 import OnThisPageSection from './OnThisPageSection.vue';
 
 export default {
   name: 'ContentTable',
-  components: { OnThisPageSection },
+  components: { OnThisPageSection, LinkableHeading },
   props: {
     anchor: {
       type: String,

src/components/DocumentationTopic/ContentTableSection.vue

@@ -12,7 +12,11 @@
   <div class="contenttable-section">
     <div class="section-title">
       <slot name="title">
-        <h3 class="title">{{ title }}</h3>
+        <LinkableHeading
+          :level="3"
+          class="title"
+          :anchor="anchorComputed"
+        >{{ title }}</LinkableHeading>
       </slot>
     </div>
     <div class="section-content">
@@ -24,13 +28,24 @@
 </template>
 
 <script>
+import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
+import { anchorize } from 'docc-render/utils/strings';
+
 export default {
   name: 'ContentTableSection',
+  components: { LinkableHeading },
   props: {
     title: {
       type: String,
       required: true,
     },
+    anchor: {
+      type: String,
+      default: null,
+    },
+  },
+  computed: {
+    anchorComputed: ({ title, anchor }) => anchor || anchorize(title),
   },
 };
 </script>

src/components/DocumentationTopic/OnThisPageSection.vue

@@ -9,7 +9,7 @@
 -->
 
 <template>
-  <section :id="anchor"><slot /></section>
+  <section><slot /></section>
 </template>
 
 <script>

src/components/DocumentationTopic/PrimaryContent/Declaration.vue

@@ -14,7 +14,7 @@
     class="declaration"
     title="Declaration"
   >
-    <h2>Declaration</h2>
+    <LinkableHeading anchor="declaration">Declaration</LinkableHeading>
     <template v-if="hasModifiedChanges">
       <DeclarationDiff
         :class="[changeClasses, multipleLinesClass]"
@@ -48,6 +48,7 @@
 <script>
 import ConditionalConstraints from 'docc-render/components/DocumentationTopic/ConditionalConstraints.vue';
 import OnThisPageSection from 'docc-render/components/DocumentationTopic/OnThisPageSection.vue';
+import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 
 import DeclarationGroup from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationGroup.vue';
 import DeclarationDiff
@@ -65,6 +66,7 @@ export default {
     DeclarationSourceLink,
     ConditionalConstraints,
     OnThisPageSection,
+    LinkableHeading,
   },
   constants: { ChangeTypes, multipleLinesClass },
   inject: ['identifier', 'store'],

src/components/DocumentationTopic/PrimaryContent/Parameters.vue

@@ -14,7 +14,7 @@
     class="parameters"
     title="Parameters"
   >
-    <h2>Parameters</h2>
+    <LinkableHeading anchor="parameters">Parameters</LinkableHeading>
     <dl>
       <template v-for="param in parameters">
         <dt class="param-name" :key="`${param.name}:name`">
@@ -31,12 +31,14 @@
 <script>
 import ContentNode from 'docc-render/components/DocumentationTopic/ContentNode.vue';
 import OnThisPageSection from 'docc-render/components/DocumentationTopic/OnThisPageSection.vue';
+import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 
 export default {
   name: 'Parameters',
   components: {
     ContentNode,
     OnThisPageSection,
+    LinkableHeading,
   },
   props: {
     parameters: {

src/components/DocumentationTopic/PrimaryContent/PossibleValues.vue

@@ -10,7 +10,7 @@
 
 <template>
   <OnThisPageSection anchor="possibleValues" title="PossibleValues">
-    <h2>Possible Values</h2>
+     <LinkableHeading anchor="possibleValues">Possible Values</LinkableHeading>
     <dl class="datalist">
       <template v-for="value in values">
         <dt class="param-name" :key="`${value.name}:name`">
@@ -28,10 +28,16 @@
 import OnThisPageSection from 'docc-render/components/DocumentationTopic/OnThisPageSection.vue';
 import ContentNode from 'docc-render/components/ContentNode.vue';
 import WordBreak from 'docc-render/components/WordBreak.vue';
+import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 
 export default {
   name: 'PossibleValues',
-  components: { ContentNode, OnThisPageSection, WordBreak },
+  components: {
+    ContentNode,
+    OnThisPageSection,
+    LinkableHeading,
+    WordBreak,
+  },
   props: {
     values: {
       type: Array,

src/components/DocumentationTopic/PrimaryContent/PropertyListKeyDetails.vue

@@ -14,7 +14,7 @@
     class="details"
     title="Details"
   >
-    <h2>Details</h2>
+    <LinkableHeading anchor="details">Details</LinkableHeading>
     <dl>
       <template v-if="isSymbol">
         <dt class="detail-type" :key="`${details.name}:name`">
@@ -45,12 +45,14 @@
 <script>
 import PropertyListKeyType from 'docc-render/components/DocumentationTopic/PrimaryContent/PropertyListKeyType.vue';
 import OnThisPageSection from 'docc-render/components/DocumentationTopic/OnThisPageSection.vue';
+import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 
 export default {
   name: 'PropertyListKeyDetails',
   components: {
     PropertyListKeyType,
     OnThisPageSection,
+    LinkableHeading,
   },
   props: {
     details: {

src/components/DocumentationTopic/PrimaryContent/PropertyTable.vue

@@ -10,7 +10,7 @@
 
 <template>
   <OnThisPageSection :anchor="anchor" :title="title">
-    <h2>{{ title }}</h2>
+    <LinkableHeading :anchor="anchor">{{ title }}</LinkableHeading>
     <ParametersTable :parameters="properties" :changes="propertyChanges" class="property-table">
       <template slot="symbol" slot-scope="{ name, type, content, changes, deprecated }">
         <div class="property-name" :class="{ deprecated: deprecated }">
@@ -60,6 +60,7 @@
 
 <script>
 import { anchorize } from 'docc-render/utils/strings';
+import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 import WordBreak from 'docc-render/components/WordBreak.vue';
 import ContentNode from 'docc-render/components/DocumentationTopic/ContentNode.vue';
 
@@ -83,6 +84,7 @@ export default {
     ContentNode,
     OnThisPageSection,
     ParametersTable,
+    LinkableHeading,
   },
   props: {
     title: {

src/components/DocumentationTopic/PrimaryContent/RestBody.vue

@@ -10,7 +10,7 @@
 
 <template>
   <OnThisPageSection :anchor="anchor" :title="title">
-    <h2>{{ title }}</h2>
+    <LinkableHeading :anchor="anchor">{{ title }}</LinkableHeading>
     <ParametersTable :parameters="[bodyParam]" :changes="bodyChanges" keyBy="key">
       <template slot="symbol" slot-scope="{ type, content, changes, name }">
         <PossiblyChangedType
@@ -84,6 +84,7 @@
 import { anchorize } from 'docc-render/utils/strings';
 import ContentNode from 'docc-render/components/DocumentationTopic/ContentNode.vue';
 import OnThisPageSection from 'docc-render/components/DocumentationTopic/OnThisPageSection.vue';
+import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 
 import WordBreak from 'docc-render/components/WordBreak.vue';
 import apiChangesProvider from 'docc-render/mixins/apiChangesProvider';
@@ -107,6 +108,7 @@ export default {
     ContentNode,
     OnThisPageSection,
     ParametersTable,
+    LinkableHeading,
   },
   constants: { ChangesKey },
   props: {

src/components/DocumentationTopic/PrimaryContent/RestEndpoint.vue

@@ -10,14 +10,15 @@
 
 <template>
   <OnThisPageSection :anchor="anchor" :title="title">
-    <h2>{{ title }}</h2>
+    <LinkableHeading :anchor="anchor">{{ title }}</LinkableHeading>
     <DeclarationSource :tokens="tokens" />
   </OnThisPageSection>
 </template>
 
 <script>
 import { anchorize } from 'docc-render/utils/strings';
 import OnThisPageSection from 'docc-render/components/DocumentationTopic/OnThisPageSection.vue';
+import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 import DeclarationSource
   from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationSource.vue';
 
@@ -29,6 +30,7 @@ export default {
   components: {
     DeclarationSource,
     OnThisPageSection,
+    LinkableHeading,
   },
   props: {
     title: {

src/components/DocumentationTopic/PrimaryContent/RestParameters.vue

@@ -10,7 +10,7 @@
 
 <template>
   <OnThisPageSection :anchor="anchor" :title="title">
-    <h2>{{ title }}</h2>
+    <LinkableHeading :anchor="anchor">{{ title }}</LinkableHeading>
     <ParametersTable :parameters="parameters" :changes="parameterChanges">
       <template slot="symbol" slot-scope="{ name, type, content, changes, deprecated }">
         <div class="param-name" :class="{ deprecated: deprecated }">
@@ -55,6 +55,7 @@
 import { anchorize } from 'docc-render/utils/strings';
 import ContentNode from 'docc-render/components/DocumentationTopic/ContentNode.vue';
 import OnThisPageSection from 'docc-render/components/DocumentationTopic/OnThisPageSection.vue';
+import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 
 import WordBreak from 'docc-render/components/WordBreak.vue';
 import apiChangesProvider from 'docc-render/mixins/apiChangesProvider';
@@ -76,6 +77,7 @@ export default {
     ContentNode,
     OnThisPageSection,
     ParametersTable,
+    LinkableHeading,
   },
   props: {
     title: {