Add generic pager component (swiftlang#782)

* Add `Pager`.

Introduces a new "pager" component, which can be used to group pages of
content with only one page being visible at any given time. Users can
toggle the page of content currently being shown.

As an experiment, this pager component is being used on the grid-style
`@Links` so that only a set number of links are shown at one time.

* Add basic unit tests and docs for pager components.

* Rewrite `Pager` using composition API.

* Move license comment to top of file.

* Fix license header comments.

* Exploring animation.

* Fix animation to slide in and out correctly.

* Remove unused code.

* Remove more unused code.

* Remove unecessary property.

* Only render indicators for multiple pages.

* Adjust page size depending on breakpoint.

* Update indicator styling.

* Add gutter controls to advance/retreat pager.

* Visually center page controls within links card grid.

* Adjust page size for links grid based on its style.

* Rewrite `Pager` using options API for now.

* Rewrite specs for `TopicsLinkCardGrid`.

* Re-implement pager using overflow and native scrolling.

* Update active page indicator when scrolling naturally.

* Hide native scrollbar UI.

* Wait for scroll to finish before re-observing page visibility.

* Use auto scroll behavior to match CSS.

* Improve strategy for awaiting scroll.

* Fix `Pager` specs.

* Prevent selection of inactive pages.

* Add basic transition for gutter controls.

* Make pager an opt-in experience for links grid.

* Optimize `Pager` with only a single page.

* Only show compact next/prev controls at small breakpoint.

* Fix vertical centering of gutter pager control.

* Adjust styling of pager controls.

* Fix `PagerControl` spec.

* Use compact controls at medium breakpoint instead of small.

* Add ARIA attributes where relevant.

* Add ARIA labels to pager controls.

* Add class for grid style.

* Add optional `pageSize` prop that can override default behavior.

Author: mportiz08

src/components/ContentNode/LinksBlock.vue

@@ -25,7 +25,7 @@
 </template>
 
 <script>
-import TopicsLinkCardGrid from 'docc-render/components/DocumentationTopic/TopicsLinkCardGrid.vue';
+import TopicsLinkCardGrid from 'theme/components/DocumentationTopic/TopicsLinkCardGrid.vue';
 import { TopicSectionsStyle } from 'docc-render/constants/TopicSectionsStyle';
 import referencesProvider from 'docc-render/mixins/referencesProvider';
 
@@ -63,6 +63,10 @@ export default {
   margin-top: var(--spacing-stacked-margin-xlarge);
 }
 
+* + .links-block {
+  margin-top: var(--spacing-stacked-margin-xlarge);
+}
+
 .topic-link-block {
   margin-top: 15px; // make sure its the same as in the TopicsTable
 }

src/components/DocumentationTopic/TopicsLinkCardGrid.vue

@@ -9,43 +9,100 @@
 -->
 
 <template>
-  <div class="TopicsLinkCardGrid">
-    <Row :columns="{
-      large: compactCards ? 3 : 2,
-      medium: 2,
-    }">
-      <Column
-        v-for="item in items"
-        :key="item.title"
-      >
-        <TopicsLinkCardGridItem :item="item" :compact="compactCards" />
-      </Column>
-    </Row>
-  </div>
+  <Pager
+    :aria-label="$t('links-grid.label')"
+    :class="['TopicsLinkCardGrid', topicStyle]"
+    :pages="pages"
+  >
+    <template #page="{ page }">
+      <Row :columns="{
+        large: compactCards ? 3 : 2,
+        medium: 2,
+      }">
+        <Column
+          v-for="item in page"
+          :key="item.title"
+        >
+          <TopicsLinkCardGridItem :item="item" :compact="compactCards" />
+        </Column>
+      </Row>
+    </template>
+    <BreakpointEmitter @change="handleBreakpointChange" />
+  </Pager>
 </template>
 
 <script>
-import Row from 'docc-render/components/ContentNode/Row.vue';
+import BreakpointEmitter from 'docc-render/components/BreakpointEmitter.vue';
 import Column from 'docc-render/components/ContentNode/Column.vue';
+import Pager from 'docc-render/components/Pager.vue';
+import Row from 'docc-render/components/ContentNode/Row.vue';
 import { TopicSectionsStyle } from 'docc-render/constants/TopicSectionsStyle';
+import { BreakpointName } from 'docc-render/utils/breakpoints';
+import { page } from 'docc-render/utils/arrays';
 import TopicsLinkCardGridItem from './TopicsLinkCardGridItem.vue';
 
 export default {
   name: 'TopicsLinkCardGrid',
-  components: { TopicsLinkCardGridItem, Column, Row },
+  components: {
+    BreakpointEmitter,
+    Column,
+    Pager,
+    Row,
+    TopicsLinkCardGridItem,
+  },
+  data: () => ({
+    breakpoint: BreakpointName.large,
+  }),
   props: {
     items: {
       type: Array,
       required: true,
     },
+    pageSize: {
+      type: Number,
+      required: false,
+    },
     topicStyle: {
       type: String,
       default: TopicSectionsStyle.compactGrid,
       validator: v => v === TopicSectionsStyle.compactGrid || v === TopicSectionsStyle.detailedGrid,
     },
+    usePager: {
+      type: Boolean,
+      default: false,
+    },
   },
   computed: {
     compactCards: ({ topicStyle }) => topicStyle === TopicSectionsStyle.compactGrid,
+    defaultPageSize: ({
+      breakpoint,
+      items,
+      topicStyle,
+      usePager,
+    }) => (usePager ? {
+      [TopicSectionsStyle.compactGrid]: {
+        [BreakpointName.large]: 6,
+        [BreakpointName.medium]: 4,
+        [BreakpointName.small]: 1,
+      },
+      [TopicSectionsStyle.detailedGrid]: {
+        [BreakpointName.large]: 4,
+        [BreakpointName.medium]: 2,
+        [BreakpointName.small]: 1,
+      },
+    }[topicStyle][breakpoint] : (
+      items.length
+    )),
+    pages: ({
+      items,
+      defaultPageSize,
+      pageSize,
+    }) => page(items, (pageSize || defaultPageSize)),
+  },
+  methods: {
+    handleBreakpointChange(breakpoint) {
+      this.breakpoint = breakpoint;
+    },
   },
 };
 </script>