feat: add a hero to the DocumentationTopic.vue

src/components/DocumentationTopic.vue

@@ -11,11 +11,13 @@
 <template>
   <div class="doc-topic">
     <main class="main" id="main" role="main" tabindex="0">
-      <slot name="above-title" />
-      <Title :eyebrow="roleHeading">{{ title }}</Title>
+      <DocumentationHero :type="symbolKind || role" :enhanceBackground="enhanceBackground">
+        <slot name="above-title" />
+        <Title :eyebrow="roleHeading">{{ title }}</Title>
+        <Abstract v-if="abstract" :content="abstract" />
+      </DocumentationHero>
       <div class="container content-grid" :class="{ 'full-width': hideSummary }">
         <Description :hasOverview="hasOverview">
-          <Abstract v-if="abstract" :content="abstract" />
           <RequirementMetadata
             v-if="isRequirement"
             :defaultImplementationsCount="defaultImplementationsCount"
@@ -50,6 +52,7 @@
         </Summary>
         <PrimaryContent
           v-if="primaryContentSections && primaryContentSections.length"
+          :class="{ 'with-border': !enhanceBackground }"
           :conformance="conformance"
           :sections="primaryContentSections"
         />
@@ -86,6 +89,7 @@ import { getSetting } from 'docc-render/utils/theme-settings';
 import Aside from 'docc-render/components/ContentNode/Aside.vue';
 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 Abstract from './DocumentationTopic/Description/Abstract.vue';
 import ContentNode from './DocumentationTopic/ContentNode.vue';
 import CallToActionButton from './CallToActionButton.vue';
@@ -121,6 +125,7 @@ export default {
     },
   },
   components: {
+    DocumentationHero,
     Abstract,
     Aside,
     BetaLegalText,
@@ -296,6 +301,7 @@ export default {
     ),
     shouldShowLanguageSwitcher: ({ objcPath, swiftPath }) => objcPath && swiftPath,
     hideSummary: () => getSetting(['features', 'docs', 'summary', 'hide'], false),
+    enhanceBackground: ({ symbolKind }) => (symbolKind ? (symbolKind === 'module') : true),
   },
   methods: {
     normalizePath(path) {

src/components/DocumentationTopic/DocumentationHero.vue

@@ -0,0 +1,156 @@
+<!--
+  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="['documentation-hero', { 'documentation-hero--disabled': !enhanceBackground }]"
+    :style="styles"
+  >
+    <NavigatorLeafIcon
+      v-if="enhanceBackground" :type="type"
+      key="first" class="background-icon first-icon" with-colors
+    />
+    <NavigatorLeafIcon
+      v-if="enhanceBackground" :type="type"
+      key="second" class="background-icon second-icon" with-colors
+    />
+    <div class="documentation-hero__content">
+      <slot />
+    </div>
+  </div>
+</template>
+
+<script>
+
+import NavigatorLeafIcon from 'docc-render/components/Navigator/NavigatorLeafIcon.vue';
+import { TopicTypeColorsMap, TopicTypeAliases, TopicTypeColors } from 'docc-render/constants/TopicTypes';
+
+export default {
+  name: 'DocumentationHero',
+  components: { NavigatorLeafIcon },
+  props: {
+    type: {
+      type: String,
+      required: true,
+    },
+    enhanceBackground: {
+      type: Boolean,
+      required: true,
+    },
+  },
+  computed: {
+    // get the alias, if any, and fallback to the `teal` color
+    color: ({ type }) => TopicTypeColorsMap[TopicTypeAliases[type] || type] || TopicTypeColors.teal,
+    styles: ({ color }) => ({
+      // use the color or fallback to the gray secondary, if not defined.
+      '--accent-color': `var(--color-type-icon-${color}, var(--color-figure-gray-secondary))`,
+    }),
+  },
+};
+</script>
+
+<style scoped lang='scss'>
+@import 'docc-render/styles/_core.scss';
+
+$doc-hero-gradient-background: dark-color(fill-tertiary) !default;
+$doc-hero-overlay-background: transparent !default;
+$doc-hero-icon-opacity: 1 !default;
+$doc-hero-icon-color: dark-color(fill-secondary) !default;
+
+.documentation-hero {
+  background: dark-color(fill);
+  color: dark-color(figure-gray);
+  overflow: hidden;
+  text-align: left;
+  padding-top: rem(40px);
+  padding-bottom: 40px;
+  position: relative;
+
+  @include breakpoint(small) {
+    text-align: center;
+  }
+
+  // gradient
+  &:before {
+    content: '';
+    background: $doc-hero-gradient-background;
+    position: absolute;
+    width: 100%;
+    left: 0;
+    top: -50%;
+    height: 150%;
+    right: 0;
+  }
+
+  // black overlay
+  &:after {
+    background: $doc-hero-overlay-background;
+    opacity: 0.4;
+    width: 100%;
+    position: absolute;
+    content: '';
+    height: 100%;
+    left: 0;
+    top: 0;
+  }
+
+  .background-icon {
+    color: $doc-hero-icon-color;
+    position: absolute;
+    display: block;
+    width: 250px;
+    height: 250px;
+    opacity: $doc-hero-icon-opacity;
+
+    /deep/ svg {
+      width: 100%;
+      height: 100%;
+    }
+
+    &.first-icon {
+      left: 0;
+      top: 100%;
+      transform: translateY(-50%);
+      @include breakpoint(small) {
+        left: -15%;
+        top: 80%;
+      }
+    }
+
+    &.second-icon {
+      right: 0;
+      top: -10%;
+      transform: translateY(-50%);
+      @include breakpoint(small) {
+        display: none;
+      }
+    }
+  }
+
+  &__content {
+    position: relative;
+    z-index: 1;
+    @include dynamic-content-container;
+  }
+}
+
+.documentation-hero--disabled {
+  background: none;
+  color: var(--colors-text, var(--color-text));
+
+  &:before {
+    content: none;
+  }
+
+  &:after {
+    content: none;
+  }
+}
+</style>

src/components/DocumentationTopic/PrimaryContent.vue

@@ -150,7 +150,7 @@ export default {
 }
 
 .primary-content {
-  &::before {
+  &.with-border::before {
     border-top-color: var(--colors-grid, var(--color-grid));
     border-top-style: solid;
     border-top-width: 1px;

src/components/DocumentationTopic/Title.vue

@@ -33,19 +33,24 @@ export default {
 <style scoped lang="scss">
 @import 'docc-render/styles/_core.scss';
 
-.topictitle {
-  @include dynamic-content-container;
-  margin-top: 2rem;
-}
-
 .eyebrow {
   @include font-styles(eyebrow-reduced);
-  color: var(--colors-secondary-label, var(--color-secondary-label));
+  color: dark-color(figure-gray-secondary);
   display: block;
   margin-bottom: rem(20px);
+
+  .documentation-hero--disabled & {
+    color: var(--colors-secondary-label, var(--color-secondary-label));
+  }
 }
 
 .title {
   @include font-styles(headline-reduced);
+  color: dark-color(figure-gray);
+  margin-bottom: rem(12px);
+
+  .documentation-hero--disabled & {
+    color: var(--colors-header-text, var(--color-header-text));
+  }
 }
 </style>

src/styles/core/_breakpoints.scss

@@ -329,16 +329,24 @@ $breakpoint-attributes: (
     min-width: map-deep-get($breakpoint-attributes, (default, small, min-width));
     margin-left: auto;
     margin-right: auto;
-    padding: 0 20px;
+    padding-left: 80px;
+    padding-right: 80px;
     box-sizing: border-box;
 
-    // make sure there is 120px space around the content on xlarge
-    @include breakpoints-from(xlarge) {
+    // make sure there is 120px space between the content and nav bar on xl and l
+    @include breakpoints-from(large) {
       box-sizing: unset;
-      padding-right: 120px;
       padding-left: 120px;
+      padding-right: 120px;
+      margin-left: 0px;
+    }
+
+    @include breakpoint(small) {
+      padding-left: 20px;
+      padding-right: 20px;
     }
   }
+
   @include inTargetIde {
     @include breakpoint-content()
   }

tests/unit/components/DocumentationTopic.spec.js

@@ -13,6 +13,7 @@ import { getSetting } from 'docc-render/utils/theme-settings';
 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';
 
 jest.mock('docc-render/utils/theme-settings', () => ({
   getSetting: jest.fn((_, fallback) => fallback),
@@ -204,16 +205,49 @@ describe('DocumentationTopic', () => {
     expect(main.attributes('tabindex')).toBe('0');
   });
 
+  it('renders a `DocumentationHero`, enabled', () => {
+    const hero = wrapper.find(DocumentationHero);
+    expect(hero.exists()).toBe(true);
+    expect(hero.props()).toEqual({ type: propsData.symbolKind, enhanceBackground: true });
+  });
+
+  it('renders a `DocumentationHero`, enabled, with a the `role`, if no symbolKind', () => {
+    wrapper.setProps({
+      role: TopicTypes.article,
+      symbolKind: '',
+    });
+    const hero = wrapper.find(DocumentationHero);
+    expect(hero.props()).toEqual({ type: TopicTypes.article, enhanceBackground: true });
+  });
+
+  it('render a `DocumentationHero`, enabled, if top-level technology page', () => {
+    wrapper.setProps({
+      role: TopicTypes.collection,
+      symbolKind: 'module',
+    });
+    const hero = wrapper.find(DocumentationHero);
+    expect(hero.props()).toEqual({ type: TopicTypes.module, enhanceBackground: true });
+  });
+
+  it('render a `DocumentationHero`, disabled, if symbol page', () => {
+    wrapper.setProps({
+      symbolKind: 'protocol',
+    });
+    const hero = wrapper.find(DocumentationHero);
+    expect(hero.props()).toEqual({ type: TopicTypes.protocol, enhanceBackground: false });
+  });
+
   it('renders a `Title`', () => {
-    const title = wrapper.find(Title);
+    const hero = wrapper.find(DocumentationHero);
+    const title = hero.find(Title);
     expect(title.exists()).toBe(true);
     expect(title.props('eyebrow')).toBe(propsData.roleHeading);
     expect(title.text()).toBe(propsData.title);
   });
 
   it('renders an abstract', () => {
-    const descr = wrapper.find(Description);
-    const abstractComponent = descr.find(Abstract);
+    const hero = wrapper.find(DocumentationHero);
+    const abstractComponent = hero.find(Abstract);
     expect(abstractComponent.exists()).toBe(true);
     expect(abstractComponent.props('content')).toEqual(propsData.abstract);
   });
@@ -231,8 +265,8 @@ describe('DocumentationTopic', () => {
     wrapper.setProps({
       abstract: emptyParagraph,
     });
-    const descr = wrapper.find(Description);
-    const abstractComponent = descr.find(Abstract);
+    const hero = wrapper.find(DocumentationHero);
+    const abstractComponent = hero.find(Abstract);
     expect(abstractComponent.exists()).toBe(true);
     expect(abstractComponent.props('content')).toEqual(emptyParagraph);
   });
@@ -565,10 +599,10 @@ describe('DocumentationTopic', () => {
     wrapper = shallowMount(DocumentationTopic, {
       propsData,
       slots: {
-        'above-title': 'Above Title Content',
+        'above-title': '<div class="above-title">Above Title Content</div>',
       },
     });
-    expect(wrapper.text()).toContain('Above Title Content');
+    expect(wrapper.find(DocumentationHero).contains('.above-title')).toBe(true);
   });
 
   describe('lifecycle hooks', () => {