Add extra offset when scrolling to a section in Documentati… (#434)

closes rdar://100028167

Author: Dobromir Hristov

src/utils/router-utils.js

@@ -17,6 +17,7 @@ import { BreakpointAttributes } from 'docc-render/utils/breakpoints';
 import { waitFrames } from 'docc-render/utils/loading';
 import { cssEscapeTopicIdHash } from 'docc-render/utils/strings';
 import { areEquivalentLocations } from 'docc-render/utils/url-helper';
+import getExtraScrollOffset from 'theme/utils/scroll-offset.js';
 
 /**
  * Returns the current absolute location, eg: '/tutorials/swiftui/something'
@@ -54,8 +55,8 @@ export async function scrollBehavior(to, from, savedPosition) {
     const baseNavOffset = getBaseNavOffset();
     // if on docs and have API changes enabled
     const apiChangesNavHeight = (isDocumentation && hasNavBarOpen) ? baseNavOffset : 0;
-    // compensate for the nav sticky height.
-    const offset = baseNavOffset + apiChangesNavHeight;
+    // compensate for the nav sticky height and add any extra scroll offset we may need
+    const offset = baseNavOffset + apiChangesNavHeight + getExtraScrollOffset(to);
 
     const y = process.env.VUE_APP_TARGET === 'ide' ? 0 : offset;
     return { selector: cssEscapeTopicIdHash(hash), offset: { x: 0, y } };

src/utils/scroll-offset.js

@@ -0,0 +1,27 @@
+/**
+ * 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
+*/
+
+import { documentationTopicName } from 'docc-render/constants/router';
+
+/**
+ * Pixel based value for the extra scroll offset for doc pages.
+ * @type {number}
+ */
+export const EXTRA_DOCUMENTATION_OFFSET = 10;
+
+/**
+ * @param {import('vue-router').Route} to
+ * @returns {Number}
+ */
+export default function getExtraScrollOffset(to) {
+  const { name } = to;
+  const isDocumentation = name.includes(documentationTopicName);
+  return isDocumentation ? EXTRA_DOCUMENTATION_OFFSET : 0;
+}

tests/unit/utils/router-utils.spec.js

@@ -19,6 +19,7 @@ import {
   restoreScrollOnReload,
   saveScrollOnReload,
 } from 'docc-render/utils/router-utils';
+import { EXTRA_DOCUMENTATION_OFFSET } from '@/utils/scroll-offset';
 
 const appTarget = process.env.VUE_APP_TARGET;
 
@@ -77,7 +78,7 @@ describe('router-utils', () => {
       const resolved = await scrollBehavior(routeDocsNoChanges, routeBar);
       expect(resolved).toEqual({
         selector: routeDocsNoChanges.hash,
-        offset: { x: 0, y: baseNavHeight },
+        offset: { x: 0, y: baseNavHeight + EXTRA_DOCUMENTATION_OFFSET },
       });
     });
 
@@ -89,7 +90,7 @@ describe('router-utils', () => {
       const resolved = await scrollBehavior(routeDocsNoChanges, routeBar);
       expect(resolved).toEqual({
         selector: routeDocsNoChanges.hash,
-        offset: { x: 0, y: baseNavHeightSmallBreakpoint },
+        offset: { x: 0, y: baseNavHeightSmallBreakpoint + EXTRA_DOCUMENTATION_OFFSET },
       });
 
       window.innerWidth = innerWidth;
@@ -101,7 +102,7 @@ describe('router-utils', () => {
       const resolved = await scrollBehavior(routeDocsNoChanges, routeBar);
       expect(resolved).toEqual({
         selector: routeDocsNoChanges.hash,
-        offset: { x: 0, y: baseNavHeight * 2 },
+        offset: { x: 0, y: baseNavHeight * 2 + EXTRA_DOCUMENTATION_OFFSET },
       });
     });
 

tests/unit/utils/scroll-offset.spec.js

@@ -0,0 +1,24 @@
+/**
+ * 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 getExtraScrollOffset, { EXTRA_DOCUMENTATION_OFFSET } from 'docc-render/utils/scroll-offset';
+import { documentationTopicName } from 'docc-render/constants/router';
+
+describe('scroll-offset', () => {
+  it('returns extra offset for documentation pages', () => {
+    expect(getExtraScrollOffset({ name: documentationTopicName }))
+      .toEqual(EXTRA_DOCUMENTATION_OFFSET);
+  });
+
+  it('falls back to 0 for other pages', () => {
+    expect(getExtraScrollOffset({ name: 'foo' }))
+      .toEqual(0);
+  });
+});