fix(openapi): revise default version logic (#2180)

* feat: implement find-default-version

* fix: use findDefaultVersion

* chore: clean up unused imports

* fix: avoid potential undefined in static props

* chore: rm unused find-latest-stable-version

* style: clearer distinction in comment

src/views/open-api-docs-view/server.ts

@@ -12,7 +12,7 @@ import { getBreadcrumbLinks } from 'lib/get-breadcrumb-links'
 import { serialize } from 'next-mdx-remote/serialize'
 // Utilities
 import {
-	findLatestStableVersion,
+	findDefaultVersion,
 	getNavItems,
 	getOperationProps,
 	groupOperations,
@@ -25,13 +25,10 @@ import type {
 	GetStaticPropsResult,
 } from 'next'
 import type { OpenAPIV3 } from 'openapi-types'
-import type { ProductSlug } from 'types/products'
 import type {
 	OpenApiDocsParams,
 	OpenApiDocsViewProps,
 	OpenApiDocsVersionData,
-	StatusIndicatorConfig,
-	OpenApiNavItem,
 	OpenApiDocsPageConfig,
 } from './types'
 
@@ -71,7 +68,7 @@ export async function getStaticProps({
 	serviceProductSlug = productSlug,
 	versionData,
 	basePath,
-	statusIndicatorConfig,
+	statusIndicatorConfig = null, // must be JSON-serializable
 	topOfPageId = 'overview',
 	groupOperationsByPath = false,
 	massageSchemaForClient = (s: OpenAPIV3.Document) => s,
@@ -89,13 +86,12 @@ export async function getStaticProps({
 	const pathParts = context.params?.page
 	const versionId = pathParts?.length > 1 ? pathParts[0] : null
 	const isVersionedUrl = typeof versionId === 'string'
-	const latestStableVersion = findLatestStableVersion(versionData)
 	// Resolve the current version
 	let targetVersion: OpenApiDocsVersionData | undefined
 	if (isVersionedUrl) {
 		targetVersion = versionData.find((v) => v.versionId === versionId)
 	} else {
-		targetVersion = latestStableVersion
+		targetVersion = findDefaultVersion(versionData)
 	}
 	// If we can't resolve the current version, render a 404 page
 	if (!targetVersion) {

src/views/open-api-docs-view/utils/find-default-version.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import { OpenApiDocsVersionData } from '../types'
+import { sortDateVersionData } from './sort-date-version-data'
+
+/**
+ * Given an array of version data,
+ * Return the default version that should be shown.
+ *
+ * - If there is exactly one version, we treat it as the default version.
+ * - If there are multiple versions, but no `stable` version, we'll show
+ *   the very latest version as the default version (even if not `stable`).
+ * - If there are multiple versions, and at least one `stable` version,
+ *   we'll show the latest `stable` version as the default version.
+ *
+ * Note: only supports date-based version formats, for example "2023-01-15".
+ * We'd need to update the sort logic in order to support other formats.
+ */
+export function findDefaultVersion(
+	versionData: OpenApiDocsVersionData[]
+): OpenApiDocsVersionData {
+	// If we have exactly one version, we'll show that as the default.
+	if (versionData.length === 1) {
+		return versionData[0]
+	}
+	// Sort versions in descending order
+	const versionsDescending = sortDateVersionData(versionData)
+	// Ideally, we'll show the latest 'stable' release as the default.
+	const latestStableVersion = versionsDescending.find(
+		(v) => v.releaseStage === 'stable'
+	)
+	// Fall back to the latest version (any stage!) if there's no 'stable' version
+	const defaultVersion = latestStableVersion || versionsDescending[0]
+	// Return the default version
+	return defaultVersion
+}

src/views/open-api-docs-view/utils/index.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: MPL-2.0
  */
 
-export { findLatestStableVersion } from './find-latest-stable-version'
+export { findDefaultVersion } from './find-default-version'
 export { getNavItems } from './get-nav-items'
 export { getOperationProps } from './get-operation-props'
 export {