Use <caption> for table captions instead of <figcaption> (#706)

Use <caption> for tables instead of <figcaption>.

Tables with captions will no longer be embedded in a <figure> with a
<figcaption>. Instead, the <table> will simply have a <caption> as its
first element when needed.

Co-authored-by: Marina Aísa <[email protected]>

Author: mportiz08

src/components/ContentNode.vue

@@ -17,7 +17,7 @@ import CodeVoice from './ContentNode/CodeVoice.vue';
 import DictionaryExample from './ContentNode/DictionaryExample.vue';
 import EndpointExample from './ContentNode/EndpointExample.vue';
 import Figure from './ContentNode/Figure.vue';
-import FigureCaption from './ContentNode/FigureCaption.vue';
+import Caption from './ContentNode/Caption.vue';
 import InlineImage from './ContentNode/InlineImage.vue';
 import Reference from './ContentNode/Reference.vue';
 import Table from './ContentNode/Table.vue';
@@ -31,6 +31,8 @@ import TaskList from './ContentNode/TaskList.vue';
 import LinksBlock from './ContentNode/LinksBlock.vue';
 import DeviceFrame from './ContentNode/DeviceFrame.vue';
 
+const { CaptionPosition, CaptionTag } = Caption.constants;
+
 export const BlockType = {
   aside: 'aside',
   codeListing: 'codeListing',
@@ -229,9 +231,16 @@ function renderNode(createElement, references) {
     const figureContent = [renderChildren([node])];
     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, centered: !title },
+      const position = title ? CaptionPosition.leading : CaptionPosition.trailing;
+      const index = position === CaptionPosition.trailing ? 1 : 0;
+      const tag = CaptionTag.figcaption;
+      figureContent.splice(index, 0,
+        createElement(Caption, {
+          props: {
+            title,
+            position,
+            tag,
+          },
         }, renderChildren(abstract)));
     }
     return createElement(Figure, { props: { anchor } }, figureContent);
@@ -297,18 +306,37 @@ function renderNode(createElement, references) {
         renderChildren(node.inlineContent)
       ));
     }
-    case BlockType.table:
-      if (node.metadata && node.metadata.anchor) {
-        return renderFigure(node);
+    case BlockType.table: {
+      const children = renderTableChildren(
+        node.rows, node.header, node.extendedData, node.alignments,
+      );
+
+      if (node.metadata && node.metadata.abstract) {
+        const { title } = node.metadata;
+        const position = title ? CaptionPosition.leading : CaptionPosition.trailing;
+        const tag = CaptionTag.caption;
+        children.unshift(createElement(Caption, {
+          props: {
+            title,
+            position,
+            tag,
+          },
+        }, (
+          renderChildren(node.metadata.abstract)
+        )));
       }
 
       return createElement(Table, {
+        attrs: {
+          id: node.metadata && node.metadata.anchor,
+        },
         props: {
           spanned: !!node.extendedData,
         },
       }, (
-        renderTableChildren(node.rows, node.header, node.extendedData, node.alignments)
+        children
       ));
+    }
     case BlockType.termList:
       return createElement('dl', {}, node.items.map(({ term, definition }) => [
         createElement('dt', {}, (

src/components/ContentNode/Caption.vue

@@ -0,0 +1,83 @@
+<!--
+  This source file is part of the Swift.org open source project
+
+  Copyright (c) 2021-2023 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 class="caption" :class="{ trailing }" :is="tag">
+    <template v-if="title">
+      <strong>{{ title }}</strong>&nbsp;<slot />
+    </template>
+    <template v-else>
+      <slot />
+    </template>
+  </component>
+</template>
+
+<script>
+const CaptionTag = {
+  caption: 'caption',
+  figcaption: 'figcaption',
+};
+
+const CaptionPosition = {
+  leading: 'leading', // before element and left aligned
+  trailing: 'trailing', // after element and center aligned
+};
+
+export default {
+  name: 'Caption',
+  constants: {
+    CaptionPosition,
+    CaptionTag,
+  },
+  props: {
+    title: {
+      type: String,
+      required: false,
+    },
+    tag: {
+      type: String,
+      required: true,
+      validator: v => Object.hasOwnProperty.call(CaptionTag, v),
+    },
+    position: {
+      type: String,
+      default: () => CaptionPosition.leading,
+      validator: v => Object.hasOwnProperty.call(CaptionPosition, v),
+    },
+  },
+  computed: {
+    trailing: ({ position }) => position === CaptionPosition.trailing,
+  },
+};
+</script>
+
+<style scoped lang="scss">
+@import 'docc-render/styles/_core.scss';
+
+.caption {
+  @include font-styles(documentation-caption);
+  margin: 0 0 var(--spacing-stacked-margin-large) 0;
+
+  &.trailing {
+    margin: var(--spacing-stacked-margin-large) 0 0 0;
+    text-align: center;
+  }
+}
+
+// for <caption> specifically since it must be the first element in a <table>
+// even when displayed at the bottom using this property
+caption.trailing {
+  caption-side: bottom;
+}
+
+/deep/ p {
+  display: inline-block;
+}
+</style>

src/components/ContentNode/Figure.vue

@@ -23,9 +23,3 @@ export default {
   },
 };
 </script>
-
-<style scoped lang="scss">
-/deep/ figcaption + * {
-  margin-top: 1rem;
-}
-</style>

src/components/ContentNode/FigureCaption.vue

@@ -153,7 +153,7 @@ $font-styles: (
   documentation-code-listing-number: (
     large: 12_18_normal_compact_mono,
   ),
-  documentation-figcaption: (
+  documentation-caption: (
     large: 14_21,
   ),
   documentation-declaration-link: (