From f8ece3a26ab13dad120f2cf57b944d46a78bb96a Mon Sep 17 00:00:00 2001
From: Zach Shilton <4624598+zchsh@users.noreply.github.com>
Date: Wed, 30 Aug 2023 12:42:30 -0400
Subject: [PATCH] chore(openapi): update sidebar overview link to be anchor
 (#2146)

* chore(openapi): update sidebar overview link to be anchor

* chore: rename top of page slug to id for clarity
---
 .../components/open-api-overview/index.tsx            | 11 ++++++++---
 .../open-api-overview/open-api-overview.module.css    |  3 +++
 src/views/open-api-docs-view/index.tsx                |  4 ++--
 src/views/open-api-docs-view/server.ts                |  9 +++++++--
 src/views/open-api-docs-view/types.ts                 |  5 ++++-
 src/views/open-api-docs-view/utils/get-nav-items.ts   |  6 +++---
 6 files changed, 27 insertions(+), 11 deletions(-)

diff --git a/src/views/open-api-docs-view/components/open-api-overview/index.tsx b/src/views/open-api-docs-view/components/open-api-overview/index.tsx
index af0edc3ad8..2443cf0bdd 100644
--- a/src/views/open-api-docs-view/components/open-api-overview/index.tsx
+++ b/src/views/open-api-docs-view/components/open-api-overview/index.tsx
@@ -26,7 +26,10 @@ import s from './open-api-overview.module.css'
  */
 
 export interface OpenApiOverviewProps {
-	title: string
+	heading: {
+		text: string
+		id: string
+	}
 	badgeText: string
 	statusIndicatorConfig?: StatusIndicatorConfig
 	contentSlot?: ReactNode
@@ -34,7 +37,7 @@ export interface OpenApiOverviewProps {
 }
 
 export function OpenApiOverview({
-	title,
+	heading,
 	badgeText,
 	statusIndicatorConfig,
 	contentSlot,
@@ -46,7 +49,9 @@ export function OpenApiOverview({
 					<IconVaultColor16 />
 				</IconTile>
 				<span>
-					<h1 className={s.heading}>{title}</h1>
+					<h1 id={heading.id} className={s.heading}>
+						{heading.text}
+					</h1>
 					{statusIndicatorConfig ? (
 						<Status
 							endpointUrl={statusIndicatorConfig.endpointUrl}
diff --git a/src/views/open-api-docs-view/components/open-api-overview/open-api-overview.module.css b/src/views/open-api-docs-view/components/open-api-overview/open-api-overview.module.css
index bce5f8337f..d232d2ec44 100644
--- a/src/views/open-api-docs-view/components/open-api-overview/open-api-overview.module.css
+++ b/src/views/open-api-docs-view/components/open-api-overview/open-api-overview.module.css
@@ -23,6 +23,9 @@
 
 .heading {
 	composes: hds-typography-display-600 from global;
+
+	/* Ensure we jump to the very top of the page when linking to this item */
+	scroll-margin-top: calc(var(--total-scroll-offset) + 999vh);
 	font-weight: var(--token-typography-font-weight-bold);
 	color: var(--token-color-foreground-strong);
 	margin: 0 0 9px 0;
diff --git a/src/views/open-api-docs-view/index.tsx b/src/views/open-api-docs-view/index.tsx
index ea06bcf0bd..0e70d7793d 100644
--- a/src/views/open-api-docs-view/index.tsx
+++ b/src/views/open-api-docs-view/index.tsx
@@ -25,7 +25,7 @@ import { DescriptionMdx } from './components/open-api-overview/components/descri
  */
 function OpenApiDocsView({
 	productData,
-	title,
+	topOfPageHeading,
 	releaseStage,
 	descriptionMdx,
 	operationGroups,
@@ -57,7 +57,7 @@ function OpenApiDocsView({
 				<div className={s.spaceBreadcrumbsOverview}>
 					<BreadcrumbBar links={breadcrumbLinks} />
 					<OpenApiOverview
-						title={title}
+						heading={topOfPageHeading}
 						badgeText={releaseStage}
 						statusIndicatorConfig={statusIndicatorConfig}
 						contentSlot={
diff --git a/src/views/open-api-docs-view/server.ts b/src/views/open-api-docs-view/server.ts
index 5e50309935..d533ab82df 100644
--- a/src/views/open-api-docs-view/server.ts
+++ b/src/views/open-api-docs-view/server.ts
@@ -66,6 +66,7 @@ export async function getStaticProps({
 	versionData,
 	basePath,
 	statusIndicatorConfig,
+	topOfPageId = 'overview',
 	massageSchemaForClient = (s: OpenAPIV3.Document) => s,
 	navResourceItems = [],
 }: {
@@ -74,6 +75,7 @@ export async function getStaticProps({
 	versionData: OpenApiDocsVersionData[]
 	basePath: string
 	statusIndicatorConfig: StatusIndicatorConfig
+	topOfPageId?: string
 	massageSchemaForClient?: (
 		schemaData: OpenAPIV3.Document
 	) => OpenAPIV3.Document
@@ -115,7 +117,7 @@ export async function getStaticProps({
 	const operationGroups = groupOperations(operationProps)
 	const navItems = getNavItems({
 		operationGroups,
-		basePath,
+		topOfPageId,
 		title: schemaData.info.title,
 		productSlug: productData.slug,
 	})
@@ -140,7 +142,10 @@ export async function getStaticProps({
 	return {
 		props: {
 			productData,
-			title: schemaData.info.title,
+			topOfPageHeading: {
+				text: schemaData.info.title,
+				id: topOfPageId,
+			},
 			releaseStage: targetVersion.releaseStage,
 			descriptionMdx,
 			IS_REVISED_TEMPLATE: true,
diff --git a/src/views/open-api-docs-view/types.ts b/src/views/open-api-docs-view/types.ts
index 2590292c26..13e19b51ca 100644
--- a/src/views/open-api-docs-view/types.ts
+++ b/src/views/open-api-docs-view/types.ts
@@ -126,7 +126,10 @@ export interface StatusIndicatorConfig {
 export interface OpenApiDocsViewProps {
 	IS_REVISED_TEMPLATE: true
 	productData: ProductData
-	title: string
+	topOfPageHeading: {
+		text: string
+		id: string
+	}
 	descriptionMdx: MDXRemoteSerializeResult
 	releaseStage: string
 
diff --git a/src/views/open-api-docs-view/utils/get-nav-items.ts b/src/views/open-api-docs-view/utils/get-nav-items.ts
index ac056a4f65..7a0fe65365 100644
--- a/src/views/open-api-docs-view/utils/get-nav-items.ts
+++ b/src/views/open-api-docs-view/utils/get-nav-items.ts
@@ -10,12 +10,12 @@ import { OperationGroup, OpenApiNavItem } from '../types'
  * Build nav items for each operation, group-by-group.
  */
 export function getNavItems({
-	basePath,
+	topOfPageId,
 	operationGroups,
 	productSlug,
 	title,
 }: {
-	basePath: string
+	topOfPageId: string
 	operationGroups: OperationGroup[]
 	productSlug: ProductSlug
 	title: string
@@ -23,7 +23,7 @@ export function getNavItems({
 	// Build the top-level page nav item
 	const pageNavItem = {
 		title,
-		fullPath: basePath,
+		fullPath: `#${topOfPageId}`,
 		theme: productSlug,
 	}
 	// Include grouped operation items