feat: Stay on the same page when switching version

Closes gh-269

Author: rwinch

gulp.d/tasks/build-preview-pages.js

@@ -50,7 +50,7 @@ module.exports =
                 const siteRootPath = path.relative(ospath.dirname(file.path), ospath.resolve(previewSrc))
                 const uiModel = { ...baseUiModel }
                 const sharedPageModel = page.component ? baseUiModel.shared[page.component.name][page.version] : {}
-                uiModel.page = { ...uiModel.page, ...page, ...sharedPageModel }
+                uiModel.page = { ...uiModel.page, ...sharedPageModel, ...page }
                 uiModel.siteRootPath = siteRootPath
                 uiModel.siteRootUrl = path.join(siteRootPath, 'index.html')
                 uiModel.uiRootPath = path.join(siteRootPath, '_')

preview-src/samples/edge-cases/index.adoc.yml

@@ -25,3 +25,8 @@ breadcrumbs:
   - content: Edge cases
     url: '#'
     urlType: fragment
+versions:
+  - url: '/samples/edge-cases.html'
+    displayVersion: 2.0.0
+  - url: '/1.0.0/samples/edge-cases.html'
+    displayVersion: 1.0.0

src/helpers/versionTree.js

@@ -1,21 +1,42 @@
 'use strict'
 
-module.exports = (components) => versionTree(components)
+module.exports = (components, page) => versionTree(components, page)
 
-function versionTree (components) {
+function versionTree (components, page) {
+  const versionToUrl = {}
+  if (page && page.versions) {
+    page.versions.forEach((v) => {
+      versionToUrl[v.displayVersion] = v.url
+    })
+  }
   for (const [, component] of Object.entries(components)) {
-    component.versionTree = splitVersions(component.versions)
+    const componentVersionToUrl = component &&
+      page &&
+      page.component &&
+      component.name === page.component.name ? versionToUrl : {}
+    component.versionTree = splitVersions(component.versions, componentVersionToUrl)
   }
   return components
 }
 
-function splitVersions (versions) {
-  const snapshot = versions.filter((v) => v.displayVersion.includes('SNAPSHOT'))
-  const stable = versions.filter((v) => !v.displayVersion.includes('-'))
-  const preview = versions.filter((v) => !snapshot.includes(v) && !stable.includes(v))
+function splitVersions (versions, versionToUrl) {
+  const snapshot = versions.filter((v) => v.displayVersion.includes('SNAPSHOT')).map((v) => navVersion(v, versionToUrl))
+  const stable = versions.filter((v) => !v.displayVersion.includes('-')).map((v) => navVersion(v, versionToUrl))
+  const preview = versions.filter((v) => !v.displayVersion.includes('SNAPSHOT') &&
+    v.displayVersion.includes('-')).map((v) => navVersion(v, versionToUrl))
   return {
     snapshot: snapshot.length > 0 ? snapshot : null,
     stable: stable.length > 0 ? stable : null,
     preview: preview.length > 0 ? preview : null,
   }
 }
+
+function navVersion (v, versionToUrl) {
+  const navVersion =
+    v.latest ? { latest: v.latest, url: v.url, displayVersion: v.displayVersion }
+      : { url: v.url, displayVersion: v.displayVersion }
+  if (versionToUrl[v.displayVersion]) {
+    navVersion.url = versionToUrl[v.displayVersion]
+  }
+  return navVersion
+}

src/partials/version.hbs

@@ -9,7 +9,7 @@
                 <div class="col-left">
 
                   <ul class="nav-versions">
-                    {{#each (versionTree site.components)}}
+                    {{#each (versionTree site.components @root.page)}}
                       <li class="component">
                         <div>
                           <a class="title" href="{{{relativize ./url}}}">{{{./title}}}</a>

test/versionTree-test.js

@@ -5,7 +5,7 @@ const { expect } = require('./harness')
 const versionTree = require('../src/helpers/versionTree.js')
 
 describe('versionTree', () => {
-  it('should return stable, preview and snapshot  versions', () => {
+  it('should return stable, preview and snapshot versions', () => {
     const result = versionTree({
       test: {
         versions: [
@@ -45,6 +45,93 @@ describe('versionTree', () => {
     expect(tree.snapshot[1].displayVersion).is.eql('3.0.0-SNAPSHOT')
   })
 
+  it('page version overrides urls when component names are the same', () => {
+    const result = versionTree({
+      test: {
+        name: 'test',
+        versions: [
+          {
+            displayVersion: '2.0.0',
+            url: './version.html',
+          },
+        ],
+      },
+    }, {
+      component: {
+        name: 'test',
+      },
+      versions: [
+        {
+          displayVersion: '2.0.0',
+          url: './page.html',
+        },
+      ],
+    })
+
+    const tree = result.test.versionTree
+    expect(tree.stable.length).is.eql(1)
+    expect(tree.stable[0].displayVersion).is.eql('2.0.0')
+    expect(tree.stable[0].url).is.eql('./page.html')
+  })
+
+  it('does not override if page does not define same version', () => {
+    const result = versionTree({
+      test: {
+        name: 'test',
+        versions: [
+          {
+            displayVersion: '2.0.0',
+            url: './version.html',
+          },
+        ],
+      },
+    }, {
+      component: {
+        name: 'test',
+      },
+      versions: [
+        {
+          displayVersion: '1.0.0',
+          url: './page.html',
+        },
+      ],
+    })
+
+    const tree = result.test.versionTree
+    expect(tree.stable.length).is.eql(1)
+    expect(tree.stable[0].displayVersion).is.eql('2.0.0')
+    expect(tree.stable[0].url).is.eql('./version.html')
+  })
+
+  it('page versions do not override if different component name', () => {
+    const result = versionTree({
+      test: {
+        name: 'test',
+        versions: [
+          {
+            displayVersion: '2.0.0',
+            url: './version.html',
+          },
+        ],
+      },
+    }, {
+      component: {
+        name: 'baz',
+      },
+      versions: [
+        {
+          displayVersion: '2.0.0',
+          url: './page.html',
+        },
+      ],
+    })
+
+    const tree = result.test.versionTree
+    expect(tree.stable.length).is.eql(1)
+    expect(tree.stable[0].displayVersion).is.eql('2.0.0')
+    expect(tree.stable[0].url).is.eql('./version.html')
+  })
+
   it('should return an empty structure', () => {
     const result = versionTree({
       test: {