Add support for @Video directive (#407)

closes rdar://97715316

Author: Dobromir Hristov

src/components/ContentNode.vue

@@ -22,6 +22,7 @@ import Reference from './ContentNode/Reference.vue';
 import Table from './ContentNode/Table.vue';
 import StrikeThrough from './ContentNode/StrikeThrough.vue';
 import Small from './ContentNode/Small.vue';
+import BlockVideo from './ContentNode/BlockVideo.vue';
 
 const BlockType = {
   aside: 'aside',
@@ -35,6 +36,7 @@ const BlockType = {
   unorderedList: 'unorderedList',
   dictionaryExample: 'dictionaryExample',
   small: 'small',
+  video: 'video',
 };
 
 const InlineType = {
@@ -198,7 +200,9 @@ function renderNode(createElement, references) {
     if ((title && abstract.length) || abstract.length) {
       // if there is a `title`, it should be above, otherwise below
       figureContent.splice(title ? 0 : 1, 0,
-        createElement(FigureCaption, { props: { title } }, renderChildren(abstract)));
+        createElement(FigureCaption, {
+          props: { title, centered: !title },
+        }, renderChildren(abstract)));
     }
     return createElement(Figure, { props: { anchor } }, figureContent);
   };
@@ -282,6 +286,19 @@ function renderNode(createElement, references) {
         createElement(Small, {}, renderChildren(node.inlineContent)),
       ]);
     }
+    case BlockType.video: {
+      if (node.metadata && node.metadata.abstract) {
+        return renderFigure(node);
+      }
+
+      return references[node.identifier] ? (
+        createElement(BlockVideo, {
+          props: {
+            identifier: node.identifier,
+          },
+        })
+      ) : null;
+    }
     case InlineType.codeVoice:
       return createElement(CodeVoice, {}, (
         node.code

src/components/ContentNode/BlockVideo.vue

@@ -0,0 +1,46 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2021 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>
+  <Asset
+    :identifier="identifier"
+    :video-autoplays="false"
+    :video-muted="false"
+    :showsReplayButton="!isClientMobile"
+    :showsVideoControls="isClientMobile"
+  />
+</template>
+
+<script>
+import Asset from 'docc-render/components/Asset.vue';
+import isClientMobile from 'docc-render/mixins/isClientMobile';
+
+export default {
+  name: 'BlockVideo',
+  mixins: [isClientMobile],
+  components: { Asset },
+  props: {
+    identifier: {
+      type: String,
+      required: true,
+    },
+  },
+};
+</script>
+
+<style lang="scss" scoped>
+/deep/ video {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+  object-fit: contain;
+  max-width: 100%;
+}
+</style>

src/components/ContentNode/FigureCaption.vue

@@ -9,7 +9,7 @@
 -->
 
 <template>
-  <figcaption class="caption">
+  <figcaption class="caption" :class="{ centered }">
     <strong v-if="title">{{ title }}</strong>&nbsp;<slot />
   </figcaption>
 </template>
@@ -22,6 +22,10 @@ export default {
       type: String,
       required: false,
     },
+    centered: {
+      type: Boolean,
+      default: false,
+    },
   },
 };
 </script>
@@ -31,6 +35,14 @@ export default {
 
 .caption {
   @include font-styles(documentation-figcaption);
+
+  &:last-child {
+    margin-top: $stacked-margin-xlarge;
+  }
+
+  &.centered {
+    text-align: center;
+  }
 }
 
 /deep/ p {

src/components/ReplayableVideoAsset.vue

@@ -28,18 +28,21 @@
       @click.prevent="replay"
     >
       {{ text }}
-      <InlineReplayIcon class="replay-icon icon-inline" />
+      <InlineReplayIcon v-if="played" class="replay-icon icon-inline" />
+      <PlayIcon v-else class="replay-icon icon-inline" />
     </a>
   </div>
 </template>
 
 <script>
 import VideoAsset from 'docc-render/components/VideoAsset.vue';
 import InlineReplayIcon from 'theme/components/Icons/InlineReplayIcon.vue';
+import PlayIcon from 'theme/components/Icons/PlayIcon.vue';
 
 export default {
   name: 'ReplayableVideoAsset',
   components: {
+    PlayIcon,
     InlineReplayIcon,
     VideoAsset,
   },

tests/unit/components/ContentNode.spec.js

@@ -23,6 +23,7 @@ import Table from 'docc-render/components/ContentNode/Table.vue';
 import LinkableHeading from 'docc-render/components/ContentNode/LinkableHeading.vue';
 import StrikeThrough from 'docc-render/components/ContentNode/StrikeThrough.vue';
 import Small from '@/components/ContentNode/Small.vue';
+import BlockVideo from '@/components/ContentNode/BlockVideo.vue';
 
 const { TableHeaderStyle } = ContentNode.constants;
 
@@ -475,12 +476,13 @@ describe('ContentNode', () => {
       expect(caption.exists()).toBe(true);
       expect(caption.contains('p')).toBe(true);
       expect(caption.props('title')).toBeFalsy();
+      expect(caption.props('centered')).toBe(true);
       expect(caption.text()).toContain('blah');
       // assert figurerecaption is below the image
       expect(figure.html()).toMatchInlineSnapshot(`
         <figure-stub>
           <inlineimage-stub alt="" variants="[object Object],[object Object]"></inlineimage-stub>
-          <figurecaption-stub>
+          <figurecaption-stub centered="true">
             <p>blah</p>
           </figurecaption-stub>
         </figure-stub>
@@ -531,6 +533,102 @@ describe('ContentNode', () => {
     });
   });
 
+  describe('with type="video"', () => {
+    const identifier = 'video.mp4';
+    const references = {
+      [identifier]: {
+        identifier,
+        variants: [
+          {
+            traits: ['2x', 'light'],
+            url: '',
+            size: { width: 1202, height: 630 },
+          },
+        ],
+      },
+    };
+
+    it('renders an `BlockVideo`', () => {
+      const wrapper = mountWithItem({
+        type: 'video',
+        identifier,
+      }, references);
+
+      const inlineVideo = wrapper.find('.content').find(BlockVideo);
+      expect(inlineVideo.exists()).toBe(true);
+      expect(inlineVideo.props('identifier')).toEqual(identifier);
+    });
+
+    it('does not crash with missing video reference data', () => {
+      expect(() => mountWithItem({
+        type: 'video',
+        identifier,
+      }, {})).not.toThrow();
+    });
+
+    it('renders a `Figure`/`FigureCaption` with metadata', () => {
+      const metadata = {
+        anchor: 'foo',
+        abstract: [{
+          type: 'paragraph',
+          inlineContent: [{ type: 'text', text: 'blah' }],
+        }],
+      };
+      const wrapper = mountWithItem({
+        type: 'video',
+        identifier,
+        metadata,
+      }, references);
+
+      const figure = wrapper.find(Figure);
+      expect(figure.exists()).toBe(true);
+      expect(figure.props('anchor')).toBe('foo');
+      expect(figure.contains(BlockVideo)).toBe(true);
+
+      const caption = wrapper.find(FigureCaption);
+      expect(caption.exists()).toBe(true);
+      expect(caption.contains('p')).toBe(true);
+      expect(caption.props('title')).toBe(metadata.title);
+      expect(caption.props('centered')).toBe(true);
+      expect(caption.text()).toContain('blah');
+    });
+
+    it('renders a `Figure`/`FigureCaption` without an anchor, with text under the video', () => {
+      const metadata = {
+        abstract: [{
+          type: 'paragraph',
+          inlineContent: [{ type: 'text', text: 'blah' }],
+        }],
+      };
+      const wrapper = mountWithItem({
+        type: 'video',
+        identifier,
+        metadata,
+      }, references);
+
+      const figure = wrapper.find(Figure);
+      expect(figure.exists()).toBe(true);
+      expect(figure.props('anchor')).toBeFalsy();
+      expect(figure.contains(BlockVideo)).toBe(true);
+
+      const caption = wrapper.find(FigureCaption);
+      expect(caption.exists()).toBe(true);
+      expect(caption.contains('p')).toBe(true);
+      expect(caption.props('title')).toBeFalsy();
+      expect(caption.props('centered')).toBe(true);
+      expect(caption.text()).toContain('blah');
+      // assert figurerecaption is below the image
+      expect(figure.html()).toMatchInlineSnapshot(`
+        <figure-stub>
+          <blockvideo-stub identifier="video.mp4"></blockvideo-stub>
+          <figurecaption-stub centered="true">
+            <p>blah</p>
+          </figurecaption-stub>
+        </figure-stub>
+      `);
+    });
+  });
+
   describe('with type="link"', () => {
     it('renders a <a>', () => {
       const wrapper = mountWithItem({
@@ -969,6 +1067,7 @@ describe('ContentNode', () => {
       const caption = figure.find(FigureCaption);
       expect(caption.exists()).toBe(true);
       expect(caption.props('title')).toBe(metadata.title);
+      expect(caption.props('centered')).toBe(false);
       expect(caption.contains('p')).toBe(true);
       expect(caption.text()).toContain('blah');
     });

tests/unit/components/ContentNode/BlockVideo.spec.js

@@ -0,0 +1,51 @@
+/**
+ * This source file is part of the Swift.org open source project
+ *
+ * Copyright (c) 2021 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 BlockVideo from '@/components/ContentNode/BlockVideo.vue';
+import { shallowMount } from '@vue/test-utils';
+import Asset from '@/components/Asset.vue';
+import isClientMobile from 'docc-render/mixins/isClientMobile';
+
+jest.mock('docc-render/mixins/isClientMobile');
+
+isClientMobile.computed.isClientMobile.mockReturnValue(false);
+
+const defaultProps = {
+  identifier: 'foo',
+};
+
+const createWrapper = () => shallowMount(BlockVideo, {
+  propsData: defaultProps,
+});
+
+describe('BlockVideo', () => {
+  it('renders an Asset on desktop', () => {
+    const wrapper = createWrapper();
+    expect(wrapper.find(Asset).props()).toEqual({
+      identifier: defaultProps.identifier,
+      videoAutoplays: false,
+      videoMuted: false,
+      showsReplayButton: true,
+      showsVideoControls: false,
+    });
+  });
+
+  it('renders an Asset, on a mobile device', () => {
+    isClientMobile.computed.isClientMobile.mockReturnValue(true);
+    const wrapper = createWrapper();
+    expect(wrapper.find(Asset).props()).toEqual({
+      identifier: defaultProps.identifier,
+      videoAutoplays: false,
+      videoMuted: false,
+      showsReplayButton: false,
+      showsVideoControls: true,
+    });
+  });
+});

tests/unit/components/ContentNode/FigureCaption.spec.js

@@ -27,4 +27,10 @@ describe('FigureCaption', () => {
     expect(wrapper.is('figcaption')).toBe(true);
     expect(wrapper.text()).toBe('Blah');
   });
+
+  it('renders a <figcaption> centered', () => {
+    const slots = { default: '<p>Blah</p>' };
+    const wrapper = shallowMount(FigureCaption, { slots, propsData: { centered: true } });
+    expect(wrapper.classes()).toContain('centered');
+  });
 });

tests/unit/components/ReplayableVideoAsset.spec.js

@@ -12,6 +12,7 @@ import { shallowMount } from '@vue/test-utils';
 import ReplayableVideoAsset from 'docc-render/components/ReplayableVideoAsset.vue';
 import VideoAsset from 'docc-render/components/VideoAsset.vue';
 import InlineReplayIcon from 'theme/components/Icons/InlineReplayIcon.vue';
+import PlayIcon from '@/components/Icons/PlayIcon.vue';
 import { flushPromises } from '../../../test-utils';
 
 const variants = [{ traits: ['dark', '1x'], url: 'https://www.example.com/myvideo.mp4' }];
@@ -62,11 +63,12 @@ describe('ReplayableVideoAsset', () => {
     expect(replayButton.exists()).toBe(true);
     expect(replayButton.classes('visible')).toBe(false);
 
-    expect(replayButton.find('.replay-icon').is(InlineReplayIcon)).toBe(true);
+    expect(replayButton.find('.replay-icon').is(PlayIcon)).toBe(true);
     const video = wrapper.find(VideoAsset);
     video.vm.$emit('ended');
 
     expect(replayButton.classes('visible')).toBe(true);
+    expect(wrapper.find('.replay-icon').is(InlineReplayIcon)).toBe(true);
 
     // When the video is playing, the replay button should be hidden.
     replayButton.trigger('click');