Add view in source link to Documentation pages (#366)

closes rdar://95613947

Author: Dobromir Hristov

src/components/DocumentationTopic.vue

@@ -65,6 +65,7 @@
           v-if="primaryContentSections && primaryContentSections.length"
           :class="{ 'with-border': !enhanceBackground }"
           :conformance="conformance"
+          :source="remoteSource"
           :sections="primaryContentSections"
         />
       </div>
@@ -265,6 +266,10 @@ export default {
       type: String,
       default: '',
     },
+    remoteSource: {
+      type: Object,
+      required: false,
+    },
   },
   provide() {
     // NOTE: this is not reactive: if this.references change, the provided value

src/components/DocumentationTopic/PrimaryContent.vue

@@ -66,6 +66,10 @@ export default {
       type: Object,
       required: false,
     },
+    source: {
+      type: Object,
+      required: false,
+    },
     sections: {
       type: Array,
       required: true,
@@ -101,7 +105,10 @@ export default {
       }[section.kind];
     },
     propsFor(section) {
-      const { conformance } = this;
+      const {
+        conformance,
+        source,
+      } = this;
       const {
         bodyContentType,
         content,
@@ -117,7 +124,7 @@ export default {
       } = section;
       return {
         [SectionKind.content]: { content },
-        [SectionKind.declarations]: { conformance, declarations },
+        [SectionKind.declarations]: { conformance, source, declarations },
         [SectionKind.details]: { details },
         [SectionKind.parameters]: { parameters },
         [SectionKind.possibleValues]: { values },

src/components/DocumentationTopic/PrimaryContent/Declaration.vue

@@ -32,6 +32,11 @@
         :changeType="changeType"
       />
     </template>
+    <DeclarationSourceLink
+      v-if="source"
+      :url="source.url"
+      :fileName="source.fileName"
+    />
     <ConditionalConstraints
       v-if="conformance"
       :constraints="conformance.constraints"
@@ -47,6 +52,7 @@ import OnThisPageSection from 'docc-render/components/DocumentationTopic/OnThisP
 import DeclarationGroup from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationGroup.vue';
 import DeclarationDiff
   from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationDiff.vue';
+import DeclarationSourceLink from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationSourceLink.vue';
 
 import { ChangeTypes } from 'docc-render/constants/Changes';
 import { multipleLinesClass } from 'docc-render/constants/multipleLines';
@@ -56,6 +62,7 @@ export default {
   components: {
     DeclarationDiff,
     DeclarationGroup,
+    DeclarationSourceLink,
     ConditionalConstraints,
     OnThisPageSection,
   },
@@ -70,6 +77,10 @@ export default {
       type: Object,
       required: false,
     },
+    source: {
+      type: Object,
+      required: false,
+    },
     declarations: {
       type: Array,
       required: true,

src/components/DocumentationTopic/PrimaryContent/DeclarationSourceLink.vue

@@ -0,0 +1,61 @@
+<!--
+  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>
+  <a
+    :href="url"
+    :title="`Open source file for ${fileName}`"
+    target="_blank"
+    class="declaration-source-link"
+  >
+    <SwiftFileIcon v-if="isSwiftFile" class="declaration-icon" />
+    <WordBreak>{{ fileName }}</WordBreak>
+  </a>
+</template>
+
+<script>
+import SwiftFileIcon from 'docc-render/components/Icons/SwiftFileIcon.vue';
+import WordBreak from 'docc-render/components/WordBreak.vue';
+
+export default {
+  name: 'DeclarationSourceLink',
+  components: { WordBreak, SwiftFileIcon },
+  props: {
+    url: {
+      type: String,
+      required: true,
+    },
+    fileName: {
+      type: String,
+      required: true,
+    },
+  },
+  computed: {
+    isSwiftFile: ({ fileName }) => fileName.endsWith('.swift'),
+  },
+};
+</script>
+
+<style scoped lang="scss">
+@import 'docc-render/styles/_core.scss';
+
+.declaration-source-link {
+  @include font-styles(body-reduced-tight);
+  display: flex;
+  align-items: center;
+  // nudge up, so its closer to the declaration source
+  margin-top: -4px;
+}
+
+.declaration-icon {
+  width: 1em;
+  margin-right: 5px;
+}
+</style>

src/components/Icons/SwiftFileIcon.vue

@@ -11,11 +11,10 @@
 <template>
   <SVGIcon
     class="swift-file-icon"
-    viewBox="0 0 14 14"
+    viewBox="0 0 15 14"
   >
-    <path d="M8.033 1l3.967 4.015v7.985h-10v-12zM7.615 2h-4.615v10h8v-6.574z"></path>
-    <path d="M7 1h1v4h-1z"></path>
-    <path d="M7 5h5v1h-5z"></path>
+    <path
+      d="M14.93,13.56A2.15,2.15,0,0,0,15,13a5.37,5.37,0,0,0-1.27-3.24A6.08,6.08,0,0,0,14,7.91,9.32,9.32,0,0,0,9.21.31a8.51,8.51,0,0,1,1.78,5,6.4,6.4,0,0,1-.41,2.18A45.06,45.06,0,0,1,3.25,1.54,44.57,44.57,0,0,0,7.54,6.9,45.32,45.32,0,0,1,1.47,2.32,35.69,35.69,0,0,0,8.56,9.94a6.06,6.06,0,0,1-3.26.85A9.48,9.48,0,0,1,0,8.91a10,10,0,0,0,8.1,4.72c2.55,0,3.25-1.2,4.72-1.2a2.09,2.09,0,0,1,1.91,1.15C14.79,13.69,14.88,13.75,14.93,13.56Z" />
   </SVGIcon>
 </template>
 
@@ -27,3 +26,12 @@ export default {
   components: { SVGIcon },
 };
 </script>
+<style scoped lang="scss">
+@import 'docc-render/styles/_core.scss';
+
+.swift-file-icon {
+  &.file-icon {
+    height: 1rem;
+  }
+}
+</style>

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

@@ -153,6 +153,9 @@ $font-styles: (
   documentation-figcaption: (
     large: 14_21,
   ),
+  documentation-declaration-link: (
+    large: 17_25,
+  ),
   // custom typography for /navigation
   nav-toggles: (
     large: (14_18, nav),

src/views/DocumentationTopic.vue

@@ -178,6 +178,7 @@ export default {
           tags = [],
           role,
           symbolKind = '',
+          remoteSource,
         } = {},
         primaryContentSections,
         relationshipsSections,
@@ -212,6 +213,7 @@ export default {
         variantOverrides,
         symbolKind,
         tags: tags.slice(0, 1), // make sure we only show the first tag
+        remoteSource,
       };
     },
     // The `hierarchy.paths` array will contain zero or more subarrays, each

tests/unit/components/DocumentationTopic.spec.js

@@ -145,6 +145,7 @@ const propsData = {
       type: 'foo',
     },
   ],
+  remoteSource: { url: 'foo' },
 };
 
 describe('DocumentationTopic', () => {
@@ -355,6 +356,7 @@ describe('DocumentationTopic', () => {
     expect(primary.exists()).toBe(true);
     expect(primary.props('conformance')).toEqual(propsData.conformance);
     expect(primary.props('sections')).toEqual(propsData.primaryContentSections);
+    expect(primary.props('source')).toEqual(propsData.remoteSource);
   });
 
   it('does not render a `PrimaryContent` column when passed undefined as PrimaryContent', () => {

tests/unit/components/DocumentationTopic/PrimaryContent.spec.js

@@ -147,6 +147,7 @@ const restEndpointSection = {
 
 const propsData = {
   conformance: { availbilityPrefix: [], constraints: [] },
+  source: { url: 'foo.com' },
   sections: [
     declarationsSection,
     detailsSection,
@@ -186,6 +187,7 @@ describe('PrimaryContent', () => {
   checkProps(Declaration, {
     conformance: propsData.conformance,
     declarations: declarationsSection.declarations,
+    source: propsData.source,
   });
   checkProps(PropertyListKeyDetails, { details: detailsSection.details });
   checkProps(GenericContent, { content: genericContentSection.content, tag: 'div' });

tests/unit/components/DocumentationTopic/PrimaryContent/Declaration.spec.js

@@ -10,8 +10,12 @@
 
 import { shallowMount } from '@vue/test-utils';
 import Declaration from 'docc-render/components/DocumentationTopic/PrimaryContent/Declaration.vue';
-import DeclarationToken from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationToken.vue';
-import DeclarationDiff from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationDiff.vue';
+import DeclarationToken
+  from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationToken.vue';
+import DeclarationDiff
+  from 'docc-render/components/DocumentationTopic/PrimaryContent/DeclarationDiff.vue';
+import DeclarationSourceLink
+  from '@/components/DocumentationTopic/PrimaryContent/DeclarationSourceLink.vue';
 
 const {
   ConditionalConstraints,
@@ -95,6 +99,20 @@ describe('Declaration', () => {
     expect(group.props('declaration')).toEqual(propsData.declarations[0]);
   });
 
+  it('renders a DeclarationSourceLink if `source` is available', () => {
+    expect(wrapper.find(DeclarationSourceLink).exists()).toBe(false);
+    wrapper.setProps({
+      source: {
+        url: 'foo.com',
+        fileName: 'Foo.swift',
+      },
+    });
+    expect(wrapper.find(DeclarationSourceLink).props()).toEqual({
+      url: 'foo.com',
+      fileName: 'Foo.swift',
+    });
+  });
+
   it('renders a `ConditionalConstraints` for availability with `conformance` data', () => {
     const conformance = {
       availabilityPrefix: [{ type: 'text', text: 'Available when' }],

tests/unit/components/DocumentationTopic/PrimaryContent/DeclarationSourceLink.spec.js

@@ -0,0 +1,47 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021-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 DeclarationSourceLink
+  from '@/components/DocumentationTopic/PrimaryContent/DeclarationSourceLink.vue';
+import { shallowMount } from '@vue/test-utils';
+import SwiftFileIcon from '@/components/Icons/SwiftFileIcon.vue';
+import WordBreak from '@/components/WordBreak.vue';
+
+const defaultProps = {
+  url: 'foo.com',
+  fileName: 'Foo.swift',
+};
+
+const createWrapper = ({ propsData, ...others } = {}) => shallowMount(DeclarationSourceLink, {
+  propsData: {
+    ...defaultProps,
+    ...propsData,
+  },
+  ...others,
+});
+
+describe('DeclarationSourceLink', () => {
+  it('renders the DeclarationSourceLink with a swift icon', () => {
+    const wrapper = createWrapper();
+    expect(wrapper.find(SwiftFileIcon).exists()).toBe(true);
+    expect(wrapper.find(WordBreak).text()).toContain(defaultProps.fileName);
+    expect(wrapper.find('a').attributes('href')).toBe(defaultProps.url);
+  });
+
+  it('does not render the Swift icon for none-swift files', () => {
+    const wrapper = createWrapper({
+      propsData: {
+        fileName: 'foo.js',
+      },
+    });
+    expect(wrapper.find(SwiftFileIcon).exists()).toBe(false);
+    expect(wrapper.text()).toContain('foo.js');
+  });
+});

tests/unit/views/DocumentationTopic.spec.js

@@ -104,6 +104,9 @@ const topicData = {
       paths: ['documentation/swift'],
     },
   ],
+  remoteSource: {
+    url: 'foo.com',
+  },
   schemaVersion: {
     major: 0,
     minor: 2,